Blast Radius 実装仕様
Parlourite Notes の決定依存関係を可視化する静的ツール Blast Radius の入力契約・出力契約・アルゴリズム仕様。frontmatter 拡張なしで動作し、予約タグと本文 Outcome セクションでリスクと実績を表現する。
目的
Parlourite Notes の src/content/{ja,en}/**/*.md を読み込み、決定の依存関係・影響範囲・リスクを可視化する単一HTMLツールの実装仕様。ビルド時に静的な graph.json を生成し、public/tools/blast-radius/index.html から読み込む。
frontmatter 拡張は行わない。リスクの粗いヒントは予約タグで、決定の実績は本文 Outcome セクションで表現する。この設計判断の詳細は Blast Radius のスキーマ拡張を却下する を参照。
非目標
- リアルタイムでのファイル監視・自動リロード
- サーバサイドレンダリング
- サイト本体(Astro)のビルドパイプラインへの統合(別工程)
- 依存の向きは一方向に保つ: サイト本体は Blast Radius に依存しない。ツールはサイトのコンテンツ(
src/content/**)を読むだけで、サイトの記事ページ・コンポーネント・ビルド結果にツールの計算結果を埋め込まない(2026-10-10 決定、Blast Radius 点検ログ — 再生が速すぎる・半透明で触れない問題の調査と、恒久ツール化のアイデア 追記2) npm run buildのprebuildでgraph.jsonを生成するのは、配備されるツールにデータを渡すためだけ。生成に失敗しても警告を出してサイトのビルドは続行する(失敗で困るのはツール側だけ)
- 依存の向きは一方向に保つ: サイト本体は Blast Radius に依存しない。ツールはサイトのコンテンツ(
- エージェントからの書き戻し
- 組織向け機能(決定者別分析、バス係数)
入力契約
対象ディレクトリ
src/content/ja/**/*.md→lang: "ja"src/content/en/**/*.md→lang: "en"- サブフォルダ(
decision/,references/等)は無視。ID は basename。
ID
id= ファイル名 basename(拡張子なし)idの正規表現:/^[a-z0-9][a-z0-9._-]*$/about.mdのような日付なし ID も許可(meta/SCHEMA.md準拠)- 言語をまたいで同一 basename を許可(collection 単位で一意)
frontmatter フィールド
meta/SCHEMA.md を SSOT とする。本ツールは新しいフィールドを追加しない。
読み取り対象:
- 必須:
date,title - 任意:
type,tags,related,status,nobuild,nolist,unlisted,noindex,time,updates,description
リスクヒント(予約タグ)
tags に予約値を書くとリスクモデルに反映する。meta/SCHEMA.md § 予約タグを参照。
| 予約タグ | 効果 |
|---|---|
one-way | 不可逆性を max(現在値, 0.85) に底上げ |
expensive | P50 反転コストを ×2.5 |
cheap | P50 反転コストを ×0.4 |
volatile | Beta 事前分布の分散を拡大 |
規則:
- 予約タグは通常タグと区別しない。サイドバーのタグフィルタに表示する
- 複数指定可
- 予約タグ様の未知名(
oneway等のタイポ)は診断に出す - 数値の精密な上書きはサポートしない。既定モデルは常に
EST扱い
本文セクション規約
ツールは以下の本文セクションを解釈する。frontmatter には何も書かない。
Outcome セクション
見出し形式は ## Outcome (YYYY-MM-DD) — <result>。<result> は worked | failed | mixed のいずれか。
| 記法 | フィールド | 必須 |
|---|---|---|
見出しの (YYYY-MM-DD) | observed | ✅ |
見出しの — <result> | actual | ✅ |
Confidence at decision time: 0.85 | predicted | 任意 |
インシデントN件 / N incidents | incidents | 任意 |
復旧にN日 / N days to recover | rework-days | 任意 |
規則:
- パース失敗時は診断に出す(黙って無視しない)
- このセクションが無い記事はキャリブレーション対象外
- Update セクションとの併存は許可
記述例(このコードフェンス内の見出しは4スペースインデントし、パーサに拾わせない):
## Outcome (2026-11-15) — failed
Confidence at decision time: 0.85
フラグは8台中1台で再利用され、旧い意味が残っていた。 インシデント1件、復旧に2日。リンク記法
| 記法 | 抽出 | 意味 |
|---|---|---|
[[id]] | ✅ | 正典 |
[[TBD: 説明]] | ✅(placeholder扱い) | 未解決。診断に出す |
[label](path.md) | ⚠️ フォールバック | 非推奨。basename を id として扱う |
裸 ADR-XXXX | ❌ 抽出しない | 本リポジトリの ID 体系に存在しない |
リンクの方向と種類
meta/RULES.md § decision の supersede 慣習に従う:
- 旧記事側に「本記事は
[[新ID]]に置き換えられた」と書く - 新記事側には書かない(方向逆転の防止)
- ツールは「参照先 → 参照元」を影響方向とする
- 旧記事が
[[新ID]]を参照 → エッジは新ID → 旧ID(supersedes)
- 旧記事が
リンク種別の推論(コンテキスト文字列に対する regex):
| 種別 | 重み | パターン |
|---|---|---|
supersedes | 1.00 | supersede, replaces?, 置き換え, 置換, 廃止して |
depends-on | 0.80 | depends? on, requires?, 前提, 依存, based on, builds? on |
refines | 0.60 | refine, extend, 詳細, 具体化, 補足, narrows? |
conflicts-with | 0.50 | conflict, contradict, 矛盾, 衝突, 対立 |
informs | 0.25 | see also, cf\., 参照, 参考, informs?, context |
relates-to | 0.10 | 既定 |
方向の規則:
supersedes以外 →参照先 → 参照元conflicts-with→ 無向(両方向に伝播)related[]frontmatter → 日付順で古→新のrelates-to
コンテキスト文字列は、リンク出現位置の前後90文字を空白正規化したもの。
可視性フラグ
meta/SCHEMA.md の可視性マトリクスをそのまま採用。ツール内の扱い:
| フラグ | ツール内 |
|---|---|
nobuild: true | ノードとして存在しない(build 時に除外) |
nolist: true | 既定で非表示。トグルONで表示。[[id]] 解決は未解決扱い |
unlisted: true | 既定で非表示。トグルONで表示。[[id]] 解決は解決する |
noindex: true | 既定で表示。破線リングでマーク |
サイドバーに “show hidden” トグルを設け、nolist / unlisted を一括表示切替。
出力契約
graph.json
scripts/build-blast-graph.mjs が src/content/**/*.md を走査し、public/tools/blast-radius/graph.json を生成する。
スキーマ:
{ "generated": "2026-10-02T12:00:00.000Z", "source": "src/content", "schemaVersion": 1, "entries": [ { "id": "2026-10-01-git-submodule-workflow", "lang": "ja", "title": "Git submodule ワークフロー", "date": "2026-10-01", "type": "reference", "status": "evergreen", "tags": ["git", "workflow"], "related": [], "updates": ["2026-10-15"], "time": "", "description": "…", "nolist": false, "unlisted": false, "noindex": false, "words": 842, "links": [ { "target": "2026-09-20-old-decision", "context": "…置き換えられた…", "placeholder": false, "source": "wikilink" } ], "supersedesFromText": [], "supersededByFromText": ["2026-09-20-old-decision"], "sections": ["context", "decision", "consequences"], "outcome": { "observed": "2026-11-15", "actual": "failed", "predicted": 0.85, "incidents": 1, "reworkDays": 2 }, "body": "…(最大4000字)" } ]}nobuild: trueのエントリは entries に含めないlinks[]は本文から抽出済みであること(ツールは再パースしない)bodyは 4000 文字で切る(ペイロード上限)outcomeはnullまたは上記オブジェクト。パース失敗時はnullで、診断に記録
読み込み順
- URL の
?src=<path>があればそれを使用 #<hash>があれば状態を復元(データは?srcから)- 既定で
graph.json→index.jsonの順に fetch - フォルダドロップ / PNG ドロップはローカル検証用に残す
状態のシリアライズ
serialize() / restore() は以下を保持:
sel: 選択ノードの集合origins: ブラスト起点t: タイムマシン位置filters: type / status / tag / 可視性フラグcf: 反事実の削除集合seed,trialscam: カメラ位置
undo / redo: 選択・ブラスト・反事実・フィルタ変更が対象。カメラ移動は対象外。restore() 内で fit() を呼ばない。
アルゴリズム仕様
レイアウト
- 日付を列とする時間層 DAG
- Tarjan の SCC 検出、back-edge 除去
- 中央値法+転置による交差最小化
- ダミーノードによる長エッジの折れ線化
N > 400では sweep 回数を削減(簡略化モード)
ブラスト半径
- 単一起点:
-log(w)上の Dijkstra - 複数起点: 各起点の raw influence に対する Noisy-OR
- 不可逆性増幅:
I' = I × (1 + 0.5 × irreversibility) - カットオフ:
tau = 0.05(既定、:blast --threshold=で変更可)
経路ハイライト
blastRadius() は prev を返す。選択ノードから起点への最短影響経路をゴールドで描画。ツールチップに “via [[…]]” を表示。
:why <id> コマンドで起点からの経路を全列挙(分岐は最大 K=5 本まで)。
Monte Carlo
修正1: コスト二重計上の解消
現行実装は、ルート i のブラストで touch 済みのノード j が、自身のループでも独立に失敗判定され、コストが二重計上される。
修正方針:
- 各トライアルでグローバルな
failedMaskを管理 - ノード
iの失敗で既に失敗済みのjはスキップ - コスト寄与は最初に失敗させたノードに帰属
修正2: contribBuf のメモリ上限
N × trials × 8B は --trials=200000 で OOM する。
- 上限を
trials_effective = min(trials, floor(2e7 / N)) - Spearman 用のトルネードは上位 K ノード(既定 K=64)のみバッファ確保
修正3: 早期終了ソートのフレーム外化
現行は 9ms フレーム予算の内側で毎チャンク全ソートする。修正:
- ソートは別フレームまたは
requestIdleCallbackで実行 - 判定は 1000 トライアルごと
- P90 標準誤差 < 1% が2回連続で早期終了
リスクモデル
既定モデル:
P50 = f(語数, fan-in, fan-out, 改訂回数) → clamp(0.5, 400)μ = log(P50)σ = clamp(0.38 + 0.22 × staleY + (status なし ? 0.15 : 0), 0.3, 1.4)不可逆性 = clamp(0.12 + type補正 + status補正 + 0.24 × (1 - exp(-fanIn/2.2)) + 0.1 × min(1, ageY/4), 0, 1)α = 1 + churn + (deprecated ? 2 : 0)β = 3 + ageY × 1.2 + (settled ? 1 : 0)予約タグによる補正(上記「リスクヒント」節)を適用後、S.diag に「EST」フラグを立てる。
バリデーション
x-blast は存在しないため、以下を検証:
- 予約タグの既知/未知判定(
oneway等のタイポ検出) - Outcome 見出しのフォーマット
predicted∈ [0, 1]actual∈ {worked, failed, mixed}date/updatesのパース成功updatesの昇順
違反時は S.diag に積み、:doctor に表示。
削除するもの
- 裸
ADR-XXXXの抽出 regex(extractLinks内) decidersの読み取りとバス係数 UIparseXBlast/parseXOutcomeS.mode(未使用)physicsStep()/S.physics(実装予定なし)window.showDoctor = ...等の露出(?debug=1でガード)
テスト
フィクスチャ:
fixtures/schema-ok/— 正常系fixtures/schema-bad/— 日付不正、予約タグタイポ、Outcome フォーマット崩れfixtures/visibility/— 4フラグの組み合わせfixtures/links/— wikilink, placeholder, mdlink, 日本語コンテキストfixtures/outcome/— Outcome セクションの正常系・異常系
npm run test:blast-graph で graph.json のスナップショット比較。
回帰テスト: knight デモで P50 が修正前の約半分になることを確認(二重計上分の消滅)。
実装上の注意
Outcome パーサの誤検出
本記事のように、reference 記事の本文中で Outcome 見出しの記法を説明する場合、そのまま書くと Blast Radius の Outcome パーサが誤検出する。回避策は以下:
- 記事本文で見出し記法を示すときは、コードフェンス内で4スペースインデントする(
splitSectionsの regex は行頭3スペースまでしか拾わない) - または
`## Outcome`のようにインラインコードで囲む
フォルダ名の統一
現状 ja/references/ と ja/reference/ が混在している可能性がある。meta/SCHEMA.md の例に揃えるなら単数形(decision/, reference/)が正典だが、既存記事の慣習を尊重するなら複数形。統一は別途 meta/RULES.md の TODO として扱う。本記事は既存慣習に合わせて references/ に配置している。
完了条件
npm run buildが通り、graph.jsonが生成されるpublic/tools/blast-radius/index.htmlを開くと、全記事がノードとして表示される:doctorが空または既知の警告のみ- knight デモで Brier スコアが算出される
- ライトテーマで文字が読める