referenceupdated v2evergreen

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 を生成するのは、配備されるツールにデータを渡すためだけ。生成に失敗しても警告を出してサイトのビルドは続行する(失敗で困るのはツール側だけ)
  • エージェントからの書き戻し
  • 組織向け機能(決定者別分析、バス係数)

入力契約

対象ディレクトリ

  • 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) に底上げ
expensiveP50 反転コストを ×2.5
cheapP50 反転コストを ×0.4
volatileBeta 事前分布の分散を拡大

規則:

  • 予約タグは通常タグと区別しない。サイドバーのタグフィルタに表示する
  • 複数指定可
  • 予約タグ様の未知名(oneway 等のタイポ)は診断に出す
  • 数値の精密な上書きはサポートしない。既定モデルは常に EST 扱い

本文セクション規約

ツールは以下の本文セクションを解釈する。frontmatter には何も書かない。

Outcome セクション

見出し形式は ## Outcome (YYYY-MM-DD) — <result>。<result> は worked | failed | mixed のいずれか。

記法フィールド必須
見出しの (YYYY-MM-DD)observed✅
見出しの — <result>actual✅
Confidence at decision time: 0.85predicted任意
インシデントN件 / N incidentsincidents任意
復旧にN日 / N days to recoverrework-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):

種別重みパターン
supersedes1.00supersede, replaces?, 置き換え, 置換, 廃止して
depends-on0.80depends? on, requires?, 前提, 依存, based on, builds? on
refines0.60refine, extend, 詳細, 具体化, 補足, narrows?
conflicts-with0.50conflict, contradict, 矛盾, 衝突, 対立
informs0.25see also, cf\., 参照, 参考, informs?, context
relates-to0.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 で、診断に記録

読み込み順

  1. URL の ?src=<path> があればそれを使用
  2. #<hash> があれば状態を復元(データは ?src から)
  3. 既定で graph.json → index.json の順に fetch
  4. フォルダドロップ / PNG ドロップはローカル検証用に残す

状態のシリアライズ

serialize() / restore() は以下を保持:

  • sel: 選択ノードの集合
  • origins: ブラスト起点
  • t: タイムマシン位置
  • filters: type / status / tag / 可視性フラグ
  • cf: 反事実の削除集合
  • seed, trials
  • cam: カメラ位置

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 の読み取りとバス係数 UI
  • parseXBlast / parseXOutcome
  • S.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 パーサが誤検出する。回避策は以下:

  1. 記事本文で見出し記法を示すときは、コードフェンス内で4スペースインデントする(splitSections の regex は行頭3スペースまでしか拾わない)
  2. または `## 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 スコアが算出される
  • ライトテーマで文字が読める