@quolu/lattice 0.32.0 → 0.33.0

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),
+  };
+}

package/src/seam-rewrite.mjs

@@ -21,6 +21,10 @@ function fail(reasons) {
  *
  * 複数行importがあるので`from '...'`で終わる行までを1文とする。束縛名は、移した先で
  * どのimportが要るかを語単位で判定するために使う。
+ *
+ * **書き換え本体はこれを使わない（sc-013）。** planSeamRewriteのimport面はsensorの
+ * AST観測（`joinImportSurface`）から受け取る。この正規表現走査が残っているのは
+ * seam-costのprofile投影（ESM限定とconfidenceで申告済み）のためだけである。
  */
 export function scanImportStatements(lines) {
   const statements = [];
@@ -41,7 +45,7 @@ export function scanImportStatements(lines) {
   return { statements, endIndex: statements.length === 0 ? -1 : statements.at(-1).end };
 }
 
-function importBindings(text) {
+export function importBindings(text) {
   const bindings = [];
   const namespace = /import\s+\*\s+as\s+([A-Za-z_$][\w$]*)/u.exec(text);
   if (namespace) bindings.push(namespace[1]);
@@ -59,10 +63,39 @@ function importBindings(text) {
 }
 
 /** 語として現れるか。string中やcomment中の一致も拾うが、余分なimportは害にならない。 */
-function mentions(text, name) {
+export function mentions(text, name) {
   return new RegExp(`(?<![\\w$])${name.replace(/[$]/gu, '\\$$')}(?![\\w$])`, 'u').test(text);
 }
 
+/**
+ * sensorの観測（`file-nodes`の`imports`と`import_bindings`）をimport文単位へ束ねる（sc-013）。
+ *
+ * importsは文の行範囲、import_bindingsは束縛ごとの`{local, form, imported, line}`で、
+ * 両者は行番号で結合できる（解決済み束縛はedge metadata、builtin等の未解決束縛は
+ * unresolved_refs由来——どちらもAST抽出であり、正規表現の再実装ではない）。
+ * どの文にも入らない束縛は`unassigned`として返し、黙って捨てない。
+ *
+ * @returns {{statements: Array<{startLine:number,endLine:number,bindings:string[]}>, unassigned: string[]}}
+ */
+export function joinImportSurface(importNodes = [], importBindings = []) {
+  const statements = importNodes
+    .filter((node) => Number.isSafeInteger(node?.startLine) && Number.isSafeInteger(node?.endLine)
+      && node.startLine >= 1 && node.endLine >= node.startLine)
+    .map((node) => ({ startLine: node.startLine, endLine: node.endLine, bindings: [] }))
+    .sort((left, right) => left.startLine - right.startLine);
+  const unassigned = [];
+  for (const binding of importBindings) {
+    if (typeof binding?.local !== 'string' || binding.local === '') continue;
+    const owner = Number.isSafeInteger(binding.line)
+      ? statements.find(({ startLine, endLine }) => binding.line >= startLine && binding.line <= endLine)
+      : undefined;
+    if (owner === undefined) { unassigned.push(binding.local); continue; }
+    if (!owner.bindings.includes(binding.local)) owner.bindings.push(binding.local);
+  }
+  for (const statement of statements) statement.bindings.sort(compareText);
+  return { statements, unassigned: [...new Set(unassigned)].sort(compareText) };
+}
+
 /**
  * 宣言の範囲を直前の連続コメント行まで広げる。
  *
@@ -85,28 +118,44 @@ function exportedBlock(raw) {
   return parts.join('\n');
 }
 
-/** 原pathでexport宣言だったか。移動先でexportを足したかではなく、元の姿を見る。 */
-function wasExported(raw) {
-  const declaration = raw.split('\n')
-    .find((line) => !COMMENT_LINE.test(line) && line.trim() !== '');
-  return declaration !== undefined && /^\s*export\s/u.test(declaration);
-}
+// 原pathでexport宣言だったかは、text走査でなくsensorのisExported（AST事実）で判定する
+// （sc-013）。extentと同じくfile-nodes由来で、symbolExtentsの各entryが持って来る。
 
-function relativeSpecifier(fromPath, toPath) {
-  const fromDir = fromPath.slice(0, fromPath.lastIndexOf('/') + 1);
-  return toPath.startsWith(fromDir) ? `./${toPath.slice(fromDir.length)}` : `./${toPath}`;
+/**
+ * repo相対path同士から、ESMが解決できる相対specifierを作る。
+ *
+ * 以前は行き先がfromの配下でない時に`./<repo相対>`を返しており、親ディレクトリや兄弟
+ * ディレクトリへの移動で**解決不能なspecifier**を生成していた（`src/a/x.mjs`→`src/b/y.mjs`で
+ * `./src/b/y.mjs`）。segment単位で共通prefixを外し、残りを`../`で遡って組み立てる。
+ */
+export function relativeSpecifier(fromPath, toPath) {
+  const fromSegments = fromPath.split('/').slice(0, -1);
+  const toSegments = toPath.split('/');
+  let shared = 0;
+  while (shared < fromSegments.length && shared < toSegments.length - 1
+    && fromSegments[shared] === toSegments[shared]) shared += 1;
+  const ascent = '../'.repeat(fromSegments.length - shared);
+  const descent = toSegments.slice(shared).join('/');
+  return ascent === '' ? `./${descent}` : `${ascent}${descent}`;
 }
 
 /**
  * 三面の変換後textを作る。
  *
+ * import面と各symbolのexport状態はsensorの観測を入力として受け取る（sc-013）。
+ * ここで正規表現によるimport再解析を行わない——言語理解はsensorが所有し、
+ * ここは決まった移動のtext組み立てだけを持つ。観測が無ければtyped理由で止める。
+ * 唯一残るtext走査は直前コメント行の巻き込み（extendUpward）で、sensorはcomment行の
+ * 範囲を記録しないため、これはtext組み立ての一部として保持する。
+ *
  * @param {object} options
  * @param {string} options.sourceText 原pathの現在の内容
  * @param {object} options.candidate `lattice.bounded_seam_candidate.v2`
- * @param {object} options.symbolExtents symbol名 -> `{startLine, endLine}`（1始まり・両端含む）
+ * @param {object} options.symbolExtents symbol名 -> `{startLine, endLine, isExported}`（1始まり・両端含む）
+ * @param {object} options.importSurface `joinImportSurface`の結果（`{statements, unassigned}`）
  * @returns {{files: object|null, reasons: string[]}} pathごとの変換後text
  */
-export function planSeamRewrite({ sourceText, candidate, symbolExtents } = {}) {
+export function planSeamRewrite({ sourceText, candidate, symbolExtents, importSurface } = {}) {
   if (typeof sourceText !== 'string' || sourceText.length === 0) return fail(['empty_source']);
   const lines = sourceText.split('\n');
   const surfaces = candidate?.surfaces ?? [];
@@ -124,8 +173,12 @@ export function planSeamRewrite({ sourceText, candidate, symbolExtents } = {}) {
         || extent.endLine < extent.startLine) {
         return fail([`symbol_extent_missing:${symbol}`]);
       }
+      // export状態はAST事実として要求する。無ければ推測せず止める（確実の門）。
+      if (typeof extent.isExported !== 'boolean') {
+        return fail([`symbol_export_status_missing:${symbol}`]);
+      }
       blocks.push({
-        symbol, path: surface.path, end: extent.endLine,
+        symbol, path: surface.path, end: extent.endLine, exported: extent.isExported,
         start: extendUpward(lines, extent.startLine),
       });
     }
@@ -138,7 +191,40 @@ export function planSeamRewrite({ sourceText, candidate, symbolExtents } = {}) {
     }
   }
 
-  const { statements, endIndex } = scanImportStatements(lines);
+  // import面はsensorの観測から。観測が無い・束縛の帰属が決まらない・importが先頭block
+  // の外にある——いずれも「たぶん大丈夫」で進まず、typed理由でAIへ渡す。
+  if (importSurface === null || typeof importSurface !== 'object'
+    || !Array.isArray(importSurface.statements)) {
+    return fail(['import_surface_missing']);
+  }
+  if (Array.isArray(importSurface.unassigned) && importSurface.unassigned.length > 0) {
+    return fail(importSurface.unassigned.map((name) => `import_binding_unassigned:${name}`));
+  }
+  const statements = [];
+  let cursor = 1;
+  for (const entry of [...importSurface.statements]
+    .sort((left, right) => left.startLine - right.startLine)) {
+    if (!Number.isSafeInteger(entry.startLine) || !Number.isSafeInteger(entry.endLine)
+      || entry.startLine < 1 || entry.endLine > lines.length || entry.endLine < entry.startLine
+      || !Array.isArray(entry.bindings)) {
+      return fail(['import_surface_missing']);
+    }
+    if (entry.startLine < cursor) return fail([`import_statement_ambiguous:${entry.startLine}`]);
+    for (let line = cursor; line < entry.startLine; line += 1) {
+      const text = lines[line - 1];
+      if (text.trim() !== '' && !COMMENT_LINE.test(text)) {
+        // 先頭block外のimport（ESMでは合法）は、残余headerの組み立てが機械では確実に
+        // できない。整形で解こうとせず止める。
+        return fail([`import_below_header:${entry.startLine}`]);
+      }
+    }
+    statements.push({
+      text: lines.slice(entry.startLine - 1, entry.endLine).join('\n'),
+      bindings: entry.bindings.filter((name) => typeof name === 'string' && name !== ''),
+    });
+    cursor = entry.endLine + 1;
+  }
+  const endIndex = cursor - 2;
   if (blocks.some((block) => block.start <= endIndex + 1)) {
     return fail(['symbol_inside_import_block']);
   }
@@ -152,7 +238,7 @@ export function planSeamRewrite({ sourceText, candidate, symbolExtents } = {}) {
     const raw = lines.slice(block.start - 1, block.end).join('\n');
     if (!bodyByPath.has(block.path)) bodyByPath.set(block.path, []);
     bodyByPath.get(block.path).push(exportedBlock(raw));
-    if (wasExported(raw)) {
+    if (block.exported) {
       if (!reExportByPath.has(block.path)) reExportByPath.set(block.path, []);
       reExportByPath.get(block.path).push(block.symbol);
     }