@quolu/lattice 0.32.0 → 0.34.0

package/src/seam-apply.mjs

@@ -14,7 +14,7 @@ import { runIsolatedTransform } from './isolation-runner.mjs';
 import { collectSensorEvidence } from './sensor-adapter.mjs';
 import { invokeSensorCli } from './sensor-runtime.mjs';
 import { buildSeamDerivationQuerySet, deriveBoundedSeamCandidate } from './seam-derivation.mjs';
-import { planSeamRewrite } from './seam-rewrite.mjs';
+import { joinImportSurface, mentions, planSeamRewrite } from './seam-rewrite.mjs';
 import {
   buildPostTransformWitnessSet, compareExportSurface, evaluateSeamVerification, measureWaveCount,
 } from './seam-verification.mjs';
@@ -112,13 +112,38 @@ export async function readSymbolExtents({ cwd, sourcePath, symbols }) {
       const node = nodeOf(entry);
       if (node === null || node.name !== symbol || node.filePath !== sourcePath) continue;
       if (!Number.isSafeInteger(node.startLine) || !Number.isSafeInteger(node.endLine)) continue;
-      extents[symbol] = { startLine: node.startLine, endLine: node.endLine };
+      // 装飾込みの開始行（sensor v11）を優先する。Pythonの@decoratorやRustの#[derive]は
+      // 宣言の外の行にあり、宣言行だけで切ると装飾が残余面へ取り残される。
+      const start = Number.isSafeInteger(node.extentStartLine) && node.extentStartLine < node.startLine
+        ? node.extentStartLine : node.startLine;
+      // export状態もAST事実として持ち帰る（sc-013）。書き換え側のtext走査を置き換える。
+      extents[symbol] = { startLine: start, endLine: node.endLine, isExported: node.isExported === true };
     }
     if (extents[symbol] === undefined && entries.length >= SYMBOL_LOOKUP_LIMIT) truncated.push(symbol);
   }
   return { extents, truncated: [...new Set(truncated)].sort(compareText) };
 }
 
+/**
+ * 対象fileのimport面をsensorの観測から読む（sc-013）。
+ *
+ * `file-nodes`の`imports`（文の行範囲）と`import_bindings`（AST由来の束縛）を
+ * `joinImportSurface`で文単位へ束ねる。観測が取れなければnullを返し、書き換え側が
+ * `import_surface_missing`のtyped理由で止める——正規表現の再解析へfallbackしない。
+ */
+export function readImportSurface({ cwd, sourcePath }) {
+  const result = invokeSensorCli(
+    (command, args, options) => spawnSync(command, args, options),
+    ['file-nodes', sourcePath, '--path', '.'],
+    { cwd, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 },
+  );
+  if (result.status !== 0) return null;
+  let parsed;
+  try { parsed = JSON.parse(result.stdout); } catch { return null; }
+  if (!Array.isArray(parsed?.imports) || !Array.isArray(parsed?.import_bindings)) return null;
+  return joinImportSurface(parsed.imports, parsed.import_bindings);
+}
+
 async function runIn(worktreePath, command, args) {
   try {
     const { stdout } = await execFileAsync(command, args, {
@@ -130,6 +155,66 @@ async function runIn(worktreePath, command, args) {
   }
 }
 
+/**
+ * 変換で切断された参照を数える（検証網、ADR 0145）。
+ *
+ * 移した先のcodeが、残余面に留まったsymbol（module変数・非公開関数）へ束縛なしで言及して
+ * いれば、その参照は切断されている——moduleの読み込みは通り、実行して初めてReferenceErrorに
+ * なるので、focused testが当該経路を通らなければ黙って壊れたまま採用される。これを受入の
+ * 一点で数える。
+ *
+ * 残余面のsymbol一覧は、変換後worktreeのfresh indexから抽出精度で取る（`file-nodes`）。
+ * value-ref辺の名前フィルタはノード生成に効かないので、全小文字のmodule変数もここには載る。
+ * `unresolved_refs`は使わない——bare参照の切断はそこに記録されないことを実測で確認した
+ * （builtin呼び出しは載るが、未束縛のidentifier読みは載らない）。
+ *
+ * 検査は保守的である。`mentions`はtext一致なので、文字列やcomment内の同名語も
+ * 「切断の疑い」として数える——見逃す方向ではなく誤検出の方向へ倒す（fail closed）。
+ * 網は受入の一点だけで、過程には触れない。不認定は拒否ではなく、理由を見て直せば
+ * 何度でも再提出できる。
+ */
+async function detectSeveredReferences({ worktreePath, files, residualPath }) {
+  const readFileNodes = (target) => {
+    const result = invokeSensorCli(
+      (command, args, options) => spawnSync(command, args, options),
+      ['file-nodes', target, '--path', '.'],
+      { cwd: worktreePath, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 },
+    );
+    if (result.status !== 0) return null;
+    let parsed;
+    try { parsed = JSON.parse(result.stdout); } catch { return null; }
+    if (!Array.isArray(parsed?.nodes)) return null;
+    return parsed;
+  };
+
+  const residual = readFileNodes(residualPath);
+  if (residual === null) return { observed: false, entries: [] };
+  const residualNames = residual.nodes.map(({ name }) => name);
+
+  const entries = [];
+  for (const [target, body] of Object.entries(files)) {
+    if (target === residualPath) continue;
+    const own = readFileNodes(target);
+    if (own === null) return { observed: false, entries: [] };
+    const defined = new Set(own.nodes.map(({ name }) => name));
+    // import束縛はworktreeのfresh indexのAST観測から取る（sc-013）。text再解析をしない。
+    // 束縛が観測できないindexでは網の判定材料が欠けるので、unobservedへ倒す（fail closed）。
+    if (!Array.isArray(own.import_bindings)) return { observed: false, entries: [] };
+    const imported = new Set(own.import_bindings
+      .map(({ local }) => local).filter((name) => typeof name === 'string'));
+    for (const name of residualNames) {
+      if (defined.has(name) || imported.has(name)) continue;
+      if (mentions(body, name)) entries.push({ file: target, name });
+    }
+  }
+  return {
+    observed: true,
+    entries: entries.sort((left, right) => compareText(
+      `${left.file}\0${left.name}`, `${right.file}\0${right.name}`,
+    )),
+  };
+}
+
 /**
  * 変換後worktreeを再indexし、新pathが索引に載ったかを見る。
  *
@@ -230,6 +315,7 @@ export function seamConflictFromProposal({ proposal, witnessSet, pathNames = {}
  */
 export function seamConflictFromFinding({
   finding, witnessSet, pathNames = {}, affectedTests = [], baseSha, manifestDigest,
+  recordedFindingDigest = null,
 } = {}) {
   if (finding?.kind !== 'observed_write_conflict' || typeof finding.path !== 'string') {
     return { conflict: null, reasons: ['finding_not_write_conflict'] };
@@ -250,7 +336,11 @@ export function seamConflictFromFinding({
       baseSha,
       manifestDigest,
       // 実行時は提案artifactが無い。観測したfindingそのものを出所として縛る。
-      findingDigest: digestArtifact({
+      //
+      // **記録済みfindingのdigestがあるなら、それを使う。** 内容から再導出したdigestで縛ると、
+      // 「この変換はあのfindingへの答えだ」という記録が、storeに実在しないidを指す。実際、
+      // 再計画側は`findings/<digest>.json`を読むので、再導出値では必ず読めない。
+      findingDigest: recordedFindingDigest ?? digestArtifact({
         kind: finding.kind, path: finding.path, todo_ids: taskIds,
       }),
       candidateId: `seam-runtime-${sha16(`${finding.path}\0${taskIds.join(',')}`)}`,
@@ -314,6 +404,7 @@ export async function applySeamConflict({
   }
   const rewritten = planSeamRewrite({
     sourceText: beforeText, candidate, symbolExtents: lookup.extents,
+    importSurface: readImportSurface({ cwd: repoRoot, sourcePath }),
   });
   if (rewritten.files === null) {
     return { outcome: outcome({ planKey, decision: 'rejected', reasons: rewritten.reasons, candidate }), files: null };
@@ -361,9 +452,14 @@ export async function applySeamConflict({
         const owned = candidate.surfaces
           .filter(({ role }) => role === 'task_owned').map(({ path: target }) => target);
         const sensor = await observeFreshSensor({ worktreePath, latticeBin, paths: owned });
-        observation = { sensor, afterText: null, afterArtifact: null };
+        observation = { sensor, afterText: null, afterArtifact: null, severed: null };
         observation.afterText = await readFile(path.join(worktreePath, sourcePath), 'utf8');
         if (!sensor.fresh) return;
+        // 網は受入の一点だけ（ADR 0145）。fresh indexの上でしか意味を持たないので、
+        // sensorが新pathを見ていない時は数えず、observation欠落として別理由で落とす。
+        observation.severed = await detectSeveredReferences({
+          worktreePath, files: rewritten.files, residualPath: sourcePath,
+        });
         const post = buildPostTransformWitnessSet({
           witnessSet, candidate, affectedTestsByPath: sensor.affectedByPath,
         });
@@ -389,6 +485,7 @@ export async function applySeamConflict({
     exportSurface: observation?.afterText === null || observation?.afterText === undefined
       ? { preserved: false, missing: [] }
       : compareExportSurface({ before: beforeText, after: observation.afterText }),
+    severed: observation?.severed ?? null,
     focusedTestsPassed: verifierFailure === null,
     sensorFresh: observation?.sensor?.fresh === true,
     conflictPairs: afterPairs === null ? { targetResolved: false }

package/src/seam-cost.mjs

@@ -0,0 +1,322 @@
+/**
+ * seam 切断コストの内訳（`lattice.seam_cost_profile.v1`、docs/plan_seam-cost.md）。
+ *
+ * 係争 file を task ごとに分割する時、**何を共有しているから単純に切れないのか**を
+ * 数えられる事実として返す。装置は分類して見せるだけで、可否を決めない——「切るのを
+ * やめろ」とは言わないし、閾値も持たない。「深さ2まで」「件数20超はやめる」を決めるのは
+ * 方針と操作する AI である（seam-proposal の Pareto 支配と同じ規律）。
+ *
+ * これは**投影であって記録ではない**。sensor が進めば変わる値なので、digest 済み artifact へ
+ * 焼き込まない（ADR 0127 の independence 記録と同じ線）。記録に残らないものは採点にも
+ * 使えない——「このファイルは N 回競合した」という会計を装置が持たないための構造的裏付け
+ * でもある（ADR 0145）。
+ *
+ * 共有物は複製可能性で重さが分かれる:
+ *
+ * | 分類 | 分割後 | 由来 |
+ * |---|---|---|
+ * | `shared_imports` | 両面から import すればよい（複製可・安い） | import 文の束縛言及 |
+ * | `shared_functions` | 共有面へ出せる（装置が機械的に処理できる） | 同一 file 内の calls 辺 |
+ * | `shared_state` | **複製できない**。所有者を決める設計判断が要る | valueRef 辺 |
+ * | `cross_edges` | 書き換える参照そのもの | task 間の直接辺 |
+ * | `same_cycle` | 循環を壊さない限り**切れない** | 同一 file 内 SCC |
+ */
+
+import { spawnSync } from 'node:child_process';
+
+import { invokeSensorCli } from './sensor-runtime.mjs';
+import { mentions, scanImportStatements } from './seam-rewrite.mjs';
+
+const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+
+export const SEAM_COST_PROFILE_SCHEMA = 'lattice.seam_cost_profile.v1';
+
+/** module 状態として数えるノード種別。関数・クラスは複製や共有面行きで解けるので含めない。 */
+const STATE_KINDS = new Set(['constant', 'variable']);
+const FUNCTION_KINDS = new Set(['function', 'method']);
+
+function sortedEntries(entries, key) {
+  return [...entries].sort((left, right) => compareText(key(left), key(right)));
+}
+
+/**
+ * 同一 file 内の隣接から強連結成分を求める（Tarjan・反復形）。
+ *
+ * seam-proposal の実装は正規化 graph の shape に結合しているので、ここでは file 内
+ * adjacency（symbol 名 → symbol 名）の小さな入力に対して独立に持つ。
+ */
+export function fileCycles(adjacency) {
+  const names = [...adjacency.keys()].sort(compareText);
+  const index = new Map();
+  const low = new Map();
+  const onStack = new Set();
+  const stack = [];
+  const cycles = [];
+  let next = 0;
+
+  for (const root of names) {
+    if (index.has(root)) continue;
+    const work = [{ name: root, childIndex: 0 }];
+    while (work.length > 0) {
+      const frame = work.at(-1);
+      const { name } = frame;
+      if (frame.childIndex === 0) {
+        index.set(name, next);
+        low.set(name, next);
+        next += 1;
+        stack.push(name);
+        onStack.add(name);
+      }
+      const targets = (adjacency.get(name) ?? []).filter((target) => adjacency.has(target));
+      if (frame.childIndex < targets.length) {
+        const target = targets[frame.childIndex];
+        frame.childIndex += 1;
+        if (!index.has(target)) {
+          work.push({ name: target, childIndex: 0 });
+        } else if (onStack.has(target)) {
+          low.set(name, Math.min(low.get(name), index.get(target)));
+        }
+        continue;
+      }
+      work.pop();
+      const parent = work.at(-1);
+      if (parent !== undefined) {
+        low.set(parent.name, Math.min(low.get(parent.name), low.get(name)));
+      }
+      if (low.get(name) === index.get(name)) {
+        const component = [];
+        let member;
+        do {
+          member = stack.pop();
+          onStack.delete(member);
+          component.push(member);
+        } while (member !== name);
+        // 自己再帰だけの1要素成分は「循環で切れない」とは別の話なので、2要素以上だけを返す。
+        if (component.length > 1) cycles.push(component.sort(compareText));
+      }
+    }
+  }
+  return cycles.sort((left, right) => compareText(left.join(','), right.join(',')));
+}
+
+/**
+ * 内訳の計算本体（純関数）。観測の取得と分類を分けるので、分類はここで単体検証できる。
+ *
+ * @param {object} options
+ * @param {string} options.sourcePath 係争 file
+ * @param {string} options.sourceText 係争 file の現在の内容
+ * @param {Array<{name: string, kind: string, startLine: number, endLine: number, isExported: boolean}>} options.nodes
+ *   係争 file の symbol 一覧（`file-nodes`）
+ * @param {Record<string, Array<{name: string, path: string, edgeKind: string, valueRef: boolean, truncated?: boolean}>>} options.calleesBySymbol
+ *   symbol ごとの隣接（callees、辺種別つき）。**係争 file 内の相手だけ**が渡される前提
+ * @param {Record<string, string[]>} options.ownedSymbolsByTask task ごとの宣言 symbol
+ * @param {string[]} [options.truncatedSymbols] callees が limit に達した symbol（観測の打ち切り申告）
+ */
+export function classifySeamCost({
+  sourcePath, sourceText, nodes, calleesBySymbol, ownedSymbolsByTask, truncatedSymbols = [],
+} = {}) {
+  const taskIds = Object.keys(ownedSymbolsByTask).sort(compareText);
+  const ownerOf = new Map();
+  for (const taskId of taskIds) {
+    for (const symbol of ownedSymbolsByTask[taskId]) ownerOf.set(symbol, taskId);
+  }
+  const nodeByName = new Map(nodes.map((node) => [node.name, node]));
+  const lines = sourceText.split('\n');
+
+  // task ごとの本文。extent の行範囲で切る。宣言に extent が無い symbol は本文不明として
+  // 言及判定から外れる——「無い」へ丸めず observed で申告する。
+  const bodyOf = new Map();
+  const bodyMissing = [];
+  for (const taskId of taskIds) {
+    const parts = [];
+    for (const symbol of ownedSymbolsByTask[taskId]) {
+      const node = nodeByName.get(symbol);
+      if (node === undefined) { bodyMissing.push(symbol); continue; }
+      parts.push(lines.slice(node.startLine - 1, node.endLine).join('\n'));
+    }
+    bodyOf.set(taskId, parts.join('\n'));
+  }
+
+  // 1) task 間の直接辺。書き換える参照そのものであり、切断コストのほぼ定義。
+  const crossEdges = [];
+  for (const [symbol, callees] of Object.entries(calleesBySymbol)) {
+    const fromTask = ownerOf.get(symbol);
+    if (fromTask === undefined) continue;
+    for (const callee of callees) {
+      const toTask = ownerOf.get(callee.name);
+      if (toTask === undefined || toTask === fromTask) continue;
+      crossEdges.push({
+        from_task: fromTask, from: symbol, to_task: toTask, to: callee.name,
+        edge_kind: callee.edgeKind, value_ref: callee.valueRef === true,
+        value_write: callee.valueWrite === true,
+      });
+    }
+  }
+
+  // 2) 同一 file 内の循環。両 task を跨ぐ成分は、循環を壊さない限り切れない。
+  const adjacency = new Map();
+  for (const node of nodes) adjacency.set(node.name, []);
+  for (const [symbol, callees] of Object.entries(calleesBySymbol)) {
+    if (!adjacency.has(symbol)) adjacency.set(symbol, []);
+    for (const callee of callees) {
+      if (adjacency.has(callee.name)) adjacency.get(symbol).push(callee.name);
+    }
+  }
+  const sameCycle = fileCycles(adjacency)
+    .map((component) => ({
+      symbols: component,
+      task_ids: [...new Set(component.map((name) => ownerOf.get(name)).filter(Boolean))].sort(compareText),
+    }))
+    .filter(({ task_ids: ids }) => ids.length >= 2);
+
+  // 3) 共有の分類。誰の宣言でもない同一 file 内の隣接を、複製可能性で分ける。
+  const reachedBy = new Map();
+  for (const [symbol, callees] of Object.entries(calleesBySymbol)) {
+    const fromTask = ownerOf.get(symbol);
+    if (fromTask === undefined) continue;
+    for (const callee of callees) {
+      if (ownerOf.has(callee.name)) continue;
+      if (!reachedBy.has(callee.name)) {
+        reachedBy.set(callee.name, { tasks: new Set(), writers: new Set() });
+      }
+      const reach = reachedBy.get(callee.name);
+      reach.tasks.add(fromTask);
+      if (callee.valueWrite === true) reach.writers.add(fromTask);
+    }
+  }
+  const sharedState = [];
+  const sharedFunctions = [];
+  for (const [name, reach] of reachedBy) {
+    const kind = nodeByName.get(name)?.kind ?? 'unknown';
+    const referencedBy = [...reach.tasks].sort(compareText);
+    if (STATE_KINDS.has(kind)) {
+      // 共有の重さは読むだけ/片方が書く/両方書くでほぼ決まる。誰が書くかまで数える。
+      sharedState.push({
+        name, kind, referenced_by: referencedBy,
+        written_by: [...reach.writers].sort(compareText),
+      });
+    } else if (FUNCTION_KINDS.has(kind)) {
+      sharedFunctions.push({ name, kind, referenced_by: referencedBy });
+    } else {
+      // それ以外（class等）は cross/cycle が拾う。分類できない共有を黙って捨てないため、
+      // state でも function でもない到達は shared_functions 側へ kind つきで載せる。
+      sharedFunctions.push({ name, kind, referenced_by: referencedBy });
+    }
+  }
+
+  // 4) import の共有。複製できるので安い——ESM の import 文束縛への言及で数える。
+  //    正規表現による ESM 限定の解析であり、他言語では観測不能（confidence で申告）。
+  const statements = scanImportStatements(lines).statements;
+  const sharedImports = [];
+  for (const statement of statements) {
+    const usedBy = taskIds.filter((taskId) => statement.bindings
+      .some((binding) => mentions(bodyOf.get(taskId) ?? '', binding)));
+    if (usedBy.length >= 2) sharedImports.push({ statement: statement.text, used_by: usedBy });
+  }
+
+  // 5) symbol ごとの数えられる事実。行数と公開面。判断はしない。
+  const tasks = {};
+  for (const taskId of taskIds) {
+    tasks[taskId] = {
+      symbols: ownedSymbolsByTask[taskId].map((symbol) => {
+        const node = nodeByName.get(symbol);
+        return node === undefined
+          ? { name: symbol, kind: null, lines: null, exported: null }
+          : {
+            name: symbol, kind: node.kind,
+            lines: node.endLine - node.startLine + 1,
+            exported: node.isExported === true,
+          };
+      }),
+    };
+  }
+
+  return {
+    schema: SEAM_COST_PROFILE_SCHEMA,
+    source_path: sourcePath,
+    tasks,
+    cross_edges: sortedEntries(crossEdges, (edge) => `${edge.from}\0${edge.to}`),
+    same_cycle: sameCycle,
+    shared_state: sortedEntries(sharedState, ({ name }) => name),
+    shared_functions: sortedEntries(sharedFunctions, ({ name }) => name),
+    shared_imports: sharedImports,
+    confidence: {
+      // 盲点の申告（計画の不変条件4）。見えていないものを「共有なし」と言わない。
+      // 3文字未満の名前（i, db等）はloop/parameterのnoiseが支配的なので辺にしない。
+      value_ref_name_filter: 'names-under-3-chars-invisible-in-edges',
+      // 書き込み判定はTS/JS族のwasm経路だけが持つ。kernel経路（Rust）は未配線で、
+      // その索引では書き込みが読みに見える——盲点として申告する（sc-007で解消）。
+      write_distinction: 'ts-js-wasm-pipeline-only',
+      imports_analysis: 'esm-only',
+      callees_truncated: [...new Set(truncatedSymbols)].sort(compareText),
+      body_missing: [...new Set(bodyMissing)].sort(compareText),
+    },
+  };
+}
+
+const CALLEES_LIMIT = 200;
+
+/**
+ * 実 sensor から材料を集めて内訳を返す（投影・read-only）。
+ *
+ * `blast_by_depth` は impact を深さ別に引いて差分で数える。深さだけの方針は粗い——
+ * 深さ2に3件と300件は別の作業なので、件数まで出す。「深さ2まで、件数 N 超はやめる」を
+ * 書けるようにするのが目的で、書くのは方針と AI である。
+ */
+export async function computeSeamCostProfile({
+  repoRoot, sourcePath, sourceText, ownedSymbolsByTask, impactDepths = [1, 2, 3],
+} = {}) {
+  const invoke = (args) => invokeSensorCli(
+    (command, cliArgs, options) => spawnSync(command, cliArgs, options),
+    args,
+    { cwd: repoRoot, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
+  );
+
+  const fileNodes = invoke(['file-nodes', sourcePath, '--path', '.']);
+  if (fileNodes.status !== 0) {
+    return { profile: null, reasons: ['file_nodes_unavailable'] };
+  }
+  let nodes;
+  try { nodes = JSON.parse(fileNodes.stdout)?.nodes ?? null; } catch { nodes = null; }
+  if (nodes === null) return { profile: null, reasons: ['file_nodes_unreadable'] };
+
+  const allOwned = [...new Set(Object.values(ownedSymbolsByTask).flat())].sort(compareText);
+  const calleesBySymbol = {};
+  const truncatedSymbols = [];
+  for (const symbol of allOwned) {
+    const result = invoke(['callees', symbol, '--path', '.', '--limit', String(CALLEES_LIMIT), '--json']);
+    if (result.status !== 0) { calleesBySymbol[symbol] = []; continue; }
+    let callees;
+    try { callees = JSON.parse(result.stdout)?.callees ?? []; } catch { callees = []; }
+    if (callees.length >= CALLEES_LIMIT) truncatedSymbols.push(symbol);
+    calleesBySymbol[symbol] = callees
+      .filter((callee) => callee.filePath === sourcePath)
+      .map((callee) => ({
+        name: callee.name, path: callee.filePath,
+        edgeKind: callee.edgeKind ?? 'calls', valueRef: callee.valueRef === true,
+        valueWrite: callee.valueWrite === true,
+      }));
+  }
+
+  const profile = classifySeamCost({
+    sourcePath, sourceText, nodes, calleesBySymbol, ownedSymbolsByTask, truncatedSymbols,
+  });
+
+  // 深さごとの影響件数。累積値の差分が「その深さで初めて届く数」になる。
+  const blast = {};
+  for (const symbol of allOwned) {
+    const perDepth = {};
+    let previous = 0;
+    for (const depth of [...impactDepths].sort((a, b) => a - b)) {
+      const result = invoke(['impact', symbol, '--path', '.', '--depth', String(depth), '--json']);
+      if (result.status !== 0) { perDepth[depth] = null; continue; }
+      let count = null;
+      try { count = JSON.parse(result.stdout)?.nodeCount ?? null; } catch { count = null; }
+      perDepth[depth] = count === null ? null : Math.max(0, count - previous);
+      if (count !== null) previous = count;
+    }
+    blast[symbol] = perDepth;
+  }
+  profile.blast_by_depth = blast;
+  return { profile, reasons: [] };
+}

package/src/seam-gate.mjs

@@ -0,0 +1,146 @@
+/**
+ * 確実の門（docs/plan_seam-cost.md sc-012、オーナー裁定）。
+ *
+ * スクリプト変換は**確実にできる内容だけ**行う。チャレンジは駄目、怪しければ AI へ。
+ * ESM 変換器は元から fail closed で、導出・照会・書き換え・五条件の各段が typed 理由で
+ * 拒否する——だが条件はコードに散在し、「機械が何を前提にしているか」「拒否されたら誰の
+ * 仕事か」を読める一覧が無かった。ここが正典。
+ *
+ * 門は2つのことだけを言う:
+ *
+ * - **前提の一覧**: 機械変換が立つ条件。1つでも欠ければ変換は実行されない（既存挙動）。
+ * - **手渡しの分類**: 拒否理由を「宣言を直せば機械で通る」(fix_declaration) と
+ *   「機械の変換能力の外＝AI が変換すべき」(hand_to_ai) へ分ける。装置は可否を決めず、
+ *   次に誰が動くべきかの事実だけ返す。
+ *
+ * **未知の理由は certain 側へ丸めない。** 分類できない拒否は unrecognized として返し、
+ * 門は閉じたままにする——理由の語彙が増えた時、黙って「確実」へ倒れる方向の壊れ方を防ぐ。
+ */
+
+const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+
+/**
+ * 機械変換の事前条件の正典。id は安定識別子、reason_prefixes は各段が返す typed 理由
+ * との対応（`:` 以降に対象名が付く動的形を含む）。
+ */
+export const SEAM_GATE_PRECONDITIONS = Object.freeze([
+  {
+    id: 'inputs_well_formed',
+    holds: '入力（path・task・candidate id）が契約の形である',
+    handoff: 'fix_declaration',
+    reason_prefixes: [
+      'invalid_source_path', 'invalid_shared_path', 'invalid_owned_path',
+      'invalid_candidate_id', 'task_refs_below_minimum', 'duplicate_task_id',
+      'surface_path_collision', 'empty_source', 'surfaces_incomplete',
+    ],
+  },
+  {
+    id: 'ownership_declared_and_exclusive',
+    holds: '移す symbol が宣言され、2 task が同じ symbol を主張していない',
+    handoff: 'fix_declaration',
+    reason_prefixes: ['owned_symbols_missing', 'owned_symbol_claimed_twice'],
+  },
+  {
+    id: 'closure_observed_and_closed',
+    holds: '所有 symbol の同一 file 内閉包が観測で閉じている',
+    handoff: 'hand_to_ai',
+    reason_prefixes: ['callee_data_missing', 'closure_rounds_exhausted'],
+  },
+  {
+    id: 'shared_surface_acyclic',
+    holds: '共有面が所有面へ逆依存しない（切った先が元を向かない）',
+    handoff: 'hand_to_ai',
+    reason_prefixes: ['shared_depends_on_owned'],
+  },
+  {
+    id: 'extents_resolved_and_disjoint',
+    holds: '全対象 symbol の行範囲と export 状態が確定し、互いに重ならず、import block の外にある',
+    handoff: 'hand_to_ai',
+    reason_prefixes: [
+      'symbol_extent_missing', 'symbol_extent_overlap', 'symbol_inside_import_block',
+      'symbol_lookup_truncated', 'symbol_export_status_missing',
+    ],
+  },
+  {
+    id: 'import_surface_observed',
+    holds: 'import 文の範囲と束縛が sensor 観測で確定している（先頭 block に収まり、帰属が一意）',
+    handoff: 'hand_to_ai',
+    reason_prefixes: [
+      'import_surface_missing', 'import_statement_ambiguous',
+      'import_binding_unassigned', 'import_below_header',
+    ],
+  },
+  {
+    id: 'behavior_preserved',
+    holds: '公開面が保たれ、切断参照が無い（ADR 0145 の網）',
+    handoff: 'hand_to_ai',
+    reason_prefixes: ['behavior_equivalent'],
+  },
+  {
+    id: 'tests_and_index_pass',
+    holds: 'focused test が通り、変換後 index が新面を収載している',
+    handoff: 'hand_to_ai',
+    reason_prefixes: ['focused_tests_passed', 'sensor_fresh', 'verifier', 'witness'],
+  },
+  {
+    id: 'parallelism_gained',
+    holds: '対象競合が消え、競合対が増えず、波数が減る（ADR 0138）',
+    handoff: 'hand_to_ai',
+    reason_prefixes: ['overlap_reduced', 'parallelism_improved'],
+  },
+]);
+
+const PREFIX_TO_CONDITION = new Map();
+for (const condition of SEAM_GATE_PRECONDITIONS) {
+  for (const prefix of condition.reason_prefixes) {
+    PREFIX_TO_CONDITION.set(prefix, condition);
+  }
+}
+
+function conditionOf(reason) {
+  const head = reason.split(':')[0];
+  return PREFIX_TO_CONDITION.get(head) ?? null;
+}
+
+/**
+ * 拒否理由の集合を門で分類する。
+ *
+ * @param {string[]} reasons 変換が返した typed 理由（空なら門は開いている＝機械で確実に通った）
+ * @returns {{
+ *   certain: boolean,
+ *   handoff: 'none'|'fix_declaration'|'hand_to_ai',
+ *   failed: Array<{id: string, holds: string, handoff: string, reasons: string[]}>,
+ *   unrecognized: string[],
+ * }}
+ */
+export function explainSeamGate(reasons = []) {
+  const byCondition = new Map();
+  const unrecognized = [];
+  for (const reason of reasons) {
+    const condition = conditionOf(reason);
+    if (condition === null) {
+      unrecognized.push(reason);
+      continue;
+    }
+    if (!byCondition.has(condition.id)) {
+      byCondition.set(condition.id, { id: condition.id, holds: condition.holds,
+        handoff: condition.handoff, reasons: [] });
+    }
+    byCondition.get(condition.id).reasons.push(reason);
+  }
+  const failed = [...byCondition.values()]
+    .map((entry) => ({ ...entry, reasons: [...entry.reasons].sort(compareText) }))
+    .sort((left, right) => compareText(left.id, right.id));
+  const certain = reasons.length === 0;
+  // hand_to_ai が1つでもあれば機械の再試行では越えられない。fix_declaration だけなら
+  // 宣言を直して再提出すれば機械で通りうる。未知の理由は安全側＝hand_to_ai として扱う。
+  const handoff = certain ? 'none'
+    : (failed.some(({ handoff: kind }) => kind === 'hand_to_ai') || unrecognized.length > 0)
+      ? 'hand_to_ai' : 'fix_declaration';
+  return {
+    certain,
+    handoff,
+    failed,
+    unrecognized: [...unrecognized].sort(compareText),
+  };
+}