@quolu/lattice 0.20.1 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",

package/src/bounded-seam.mjs

@@ -14,8 +14,94 @@ function sortedUniqueRefs(value, { nonempty = false } = {}) {
     && value.every((entry, index) => index === 0 || value[index - 1] < entry);
 }
 
+/**
+ * v2の三面surface（ADR 0137 Decision 1）。所有だけがtaskへ紐づく。
+ *
+ * 残余はsymbolを列挙しない。移らなかったものすべてという補集合であり、列挙を要求すると
+ * 原fileの全symbol目録が契約の一部になる。
+ */
+function seamSurface(value, taskIds) {
+  if (!exactRecord(value, ['role', 'path', 'owner_task_ids', 'symbols'])
+    || !['task_owned', 'shared', 'residual'].includes(value.role)
+    || !isTodoRef(value.path)
+    || !Array.isArray(value.owner_task_ids)
+    || !sortedUniqueSymbols(value.symbols)) return false;
+  if (value.role === 'task_owned') {
+    return value.owner_task_ids.length === 1 && taskIds.has(value.owner_task_ids[0])
+      && value.symbols.length > 0;
+  }
+  if (value.owner_task_ids.length !== 0) return false;
+  return value.role === 'shared' ? value.symbols.length > 0 : value.symbols.length === 0;
+}
+
+function sortedUniqueSymbols(value) {
+  return Array.isArray(value) && value.every(isTodoIdentifier)
+    && value.every((entry, index) => index === 0 || value[index - 1] < entry);
+}
+
+function validateBoundedSeamCandidateV2(value) {
+  if (!exactRecord(value, [
+    'schema', 'candidate_id', 'base_sha', 'manifest_digest', 'finding_digest',
+    'source_path', 'todo_refs', 'surfaces', 'allowed_paths', 'required_paths',
+    'verification_policy', 'candidate_digest',
+  ])
+    || !isTodoIdentifier(value.candidate_id) || !GIT_OID.test(value.base_sha)
+    || !isTodoDigest(value.manifest_digest) || !isTodoDigest(value.finding_digest)
+    || !isTodoRef(value.source_path)
+    || !Array.isArray(value.todo_refs) || value.todo_refs.length < 2
+    || !value.todo_refs.every((entry) => exactRecord(entry, ['plan_key', 'task_id'])
+      && isTodoIdentifier(entry.plan_key) && isTodoIdentifier(entry.task_id))
+    || !value.todo_refs.every((entry, index) => index === 0
+      || `${value.todo_refs[index - 1].plan_key}\0${value.todo_refs[index - 1].task_id}`
+        < `${entry.plan_key}\0${entry.task_id}`)) return false;
+
+  const taskIds = new Set(value.todo_refs.map(({ task_id: taskId }) => taskId));
+  if (!Array.isArray(value.surfaces)
+    || !value.surfaces.every((surface) => seamSurface(surface, taskIds))
+    || !value.surfaces.every((surface, index) => index === 0
+      || value.surfaces[index - 1].path < surface.path)) return false;
+
+  // 所有面は全taskへ1つずつ。残余は原path上に必ず1つ。共有面は0または1（粒度は未裁定）。
+  const owned = value.surfaces.filter(({ role }) => role === 'task_owned');
+  const shared = value.surfaces.filter(({ role }) => role === 'shared');
+  const residual = value.surfaces.filter(({ role }) => role === 'residual');
+  const ownerIds = new Set(owned.flatMap(({ owner_task_ids: ids }) => ids));
+  if (owned.length !== taskIds.size || ownerIds.size !== taskIds.size
+    || shared.length > 1 || residual.length !== 1
+    || residual[0].path !== value.source_path) return false;
+
+  // symbolは1面にしか属せない。二重所有は移動先が決まらない。
+  const symbols = value.surfaces.flatMap(({ symbols: list }) => list);
+  if (new Set(symbols).size !== symbols.length) return false;
+
+  if (!sortedUniqueRefs(value.allowed_paths, { nonempty: true })
+    || !sortedUniqueRefs(value.required_paths, { nonempty: true })
+    || !value.required_paths.every((entry) => value.allowed_paths.includes(entry))
+    || !value.surfaces.every(({ path }) => value.allowed_paths.includes(path))
+    || !value.required_paths.includes(value.source_path)
+    || !owned.every(({ path }) => value.required_paths.includes(path))) return false;
+
+  // ADR 0138の五条件。1つでもfalseなら、その候補は採用条件を緩めた別物である。
+  return exactRecord(value.verification_policy, [
+    'focused_test_refs', 'require_behavior_equivalence', 'require_fresh_sensor',
+    'require_overlap_reduction', 'require_no_new_conflict_pairs',
+    'require_parallelism_improvement',
+  ])
+    && sortedUniqueRefs(value.verification_policy.focused_test_refs, { nonempty: true })
+    && value.verification_policy.require_behavior_equivalence === true
+    && value.verification_policy.require_fresh_sensor === true
+    && value.verification_policy.require_overlap_reduction === true
+    && value.verification_policy.require_no_new_conflict_pairs === true
+    && value.verification_policy.require_parallelism_improvement === true
+    && isTodoDigest(value.candidate_digest)
+    && value.candidate_digest === todoSelfDigest(value, 'candidate_digest');
+}
+
 export function validateBoundedSeamCandidate(value) {
   try {
+    if (value?.schema === 'lattice.bounded_seam_candidate.v2') {
+      return validateBoundedSeamCandidateV2(value);
+    }
     return exactRecord(value, [
       'schema', 'candidate_id', 'base_sha', 'manifest_digest', 'finding_digest',
       'todo_refs', 'anchor', 'allowed_paths', 'required_paths', 'verification_policy',

package/src/cli-help.mjs

@@ -71,6 +71,8 @@ Write commands:
   independence compile --plan <key> --input <file>  # witness setとsensorから並列可否を記録する
   independence witness migrate --plan <key>  # revision後の宣言をtask migrationで写す
   seam-proposal compile --plan <key>  # 並列可否記録と実sensorからseam提案を記録する
+  seam-proposal apply --plan <key>  # 記録済み提案を隔離worktreeで適用し五条件で採否を決める
+  seam-proposal land --plan <key> --names <file>  # 採用された変換を本ツリーへ着地させる
   revise --plan <key> --input <file>
   revise-phase --plan <key> --input <file>
   revise-set --input <file>

package/src/isolation-runner.mjs

@@ -3,8 +3,10 @@ import {
   mkdtemp,
   readdir,
   readFile,
+  mkdir,
   readlink,
   rm,
+  symlink,
 } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -51,13 +53,18 @@ function verificationReceipt(verifier, result, outcome) {
   };
 }
 
-function verifierEnvironment() {
-  const env = { ...process.env, NO_COLOR: '1' };
+function verifierEnvironment(extra = {}) {
+  const env = { ...process.env, NO_COLOR: '1', ...extra };
   delete env.NODE_TEST_CONTEXT;
   delete env.FORCE_COLOR;
   return env;
 }
 
+function isPlainStringRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.values(value).every((entry) => typeof entry === 'string');
+}
+
 function safeRelativePath(value) {
   return typeof value === 'string'
     && value.length > 0
@@ -123,10 +130,17 @@ async function buildPatch(worktreePath, changedPaths) {
   return Buffer.concat(parts);
 }
 
-async function captureSnapshot(worktreePath, baseSha, allowedPaths) {
+async function captureSnapshot(worktreePath, baseSha, allowedPaths, mountedEntries = []) {
+  const mounted = new Set(mountedEntries);
   const changedPaths = statusPaths((await run('git', [
     'status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignored=matching',
-  ], { cwd: worktreePath })).stdout);
+  ], { cwd: worktreePath })).stdout)
+    // runnerが張ったmountだけを外す。それ以外は無視しない——gitignore対象であっても、
+    // allowed pathの外に現れたものは変更である。
+    .filter((changedPath) => {
+      const normalized = changedPath.replace(/\/$/u, '');
+      return ![...mounted].some((entry) => normalized === entry || normalized.startsWith(`${entry}/`));
+    });
   for (const changedPath of changedPaths) {
     if (!safeRelativePath(changedPath) || !isAllowed(changedPath, allowedPaths)) {
       throw new Error(`change outside allowed paths: ${changedPath}`);
@@ -136,8 +150,8 @@ async function captureSnapshot(worktreePath, baseSha, allowedPaths) {
   return { changedPaths, patch: await buildPatch(worktreePath, changedPaths) };
 }
 
-async function assertSnapshotUnchanged(worktreePath, baseSha, allowedPaths, expected, actor) {
-  const actual = await captureSnapshot(worktreePath, baseSha, allowedPaths);
+async function assertSnapshotUnchanged(worktreePath, baseSha, allowedPaths, expected, actor, mountedEntries = []) {
+  const actual = await captureSnapshot(worktreePath, baseSha, allowedPaths, mountedEntries);
   if (actual.changedPaths.length !== expected.changedPaths.length
     || actual.changedPaths.some((changedPath, index) => changedPath !== expected.changedPaths[index])
     || !actual.patch.equals(expected.patch)) {
@@ -257,13 +271,20 @@ async function assertSourceUnchanged(repoRoot, sourceState) {
   return receipt;
 }
 
-export async function runIsolatedTransform({ repoRoot, baseRef, allowedPaths, transform, verifyCommands, observe } = {}) {
+export async function runIsolatedTransform({ repoRoot, baseRef, allowedPaths, transform, verifyCommands, observe, mounts = [], verifierEnv = {} } = {}) {
   if (!safeRelativePath('.') || typeof repoRoot !== 'string' || typeof baseRef !== 'string'
     || !Array.isArray(allowedPaths) || allowedPaths.some((entry) => !safeRelativePath(entry))
     || typeof transform !== 'function' || !Array.isArray(verifyCommands)
-    || (observe !== undefined && typeof observe !== 'function')) {
+    || (observe !== undefined && typeof observe !== 'function')
+    || !isPlainStringRecord(verifierEnv)
+    || !Array.isArray(mounts)
+    || mounts.some(({ entry, target } = {}) => typeof entry !== 'string'
+      || !safeRelativePath(entry) || typeof target !== 'string' || !path.isAbsolute(target))) {
     throw new TypeError('invalid isolated transform arguments');
   }
+  // mountはrunnerが自分で張り、自分が張ったentryだけをsnapshotから外す。呼び出し側が
+  // transformの中で作ると、任意の変更をsnapshotから隠す口になる。
+  const mountedEntries = mounts.map(({ entry }) => entry);
 
   const sourceState = await captureSourceState(repoRoot);
   if (sourceState.visibleStatus.length > 0) throw new Error('source repository must be clean');
@@ -278,8 +299,20 @@ export async function runIsolatedTransform({ repoRoot, baseRef, allowedPaths, tr
   try {
     await run('git', ['worktree', 'add', '--detach', worktreePath, baseSha], { cwd: repoRoot });
     added = true;
+    for (const { entry, target } of mounts) {
+      // 保護pathへはmountさせない。そこを許すと、変更をsnapshotから隠す口になる。
+      if (PROTECTED_PATHS.includes(entry.split('/')[0])) {
+        throw new Error(`mount over protected path is not allowed: ${entry}`);
+      }
+      const mountPath = path.join(worktreePath, entry);
+      await mkdir(path.dirname(mountPath), { recursive: true });
+      // base checkoutが同名を持つ場合がある（trackedな.gitignore等）。mount配下は
+      // まるごとsnapshotの対象外になるので、置き換えても判定の抜けは生まれない。
+      await rm(mountPath, { recursive: true, force: true });
+      await symlink(target, mountPath);
+    }
     await transform({ worktreePath });
-    snapshot = await captureSnapshot(worktreePath, baseSha, allowedPaths);
+    snapshot = await captureSnapshot(worktreePath, baseSha, allowedPaths, mountedEntries);
     for (const verifier of verifyCommands) {
       if (!verifier || typeof verifier.command !== 'string' || !Array.isArray(verifier.args) || verifier.args.some((arg) => typeof arg !== 'string')) {
         throw new TypeError('verifyCommands must contain command and string args');
@@ -287,18 +320,18 @@ export async function runIsolatedTransform({ repoRoot, baseRef, allowedPaths, tr
       try {
         const verification = await run(verifier.command, verifier.args, {
           cwd: worktreePath,
-          env: verifierEnvironment(),
+          env: verifierEnvironment(verifierEnv),
         });
         verifications.push(verificationReceipt(verifier, verification, 'passed'));
       } catch (error) {
         verifications.push(verificationReceipt(verifier, error, 'failed'));
         throw new Error(`verifier failed (${error.signal ?? error.code}): ${verifier.command}`);
       }
-      await assertSnapshotUnchanged(worktreePath, baseSha, allowedPaths, snapshot, 'verifier');
+      await assertSnapshotUnchanged(worktreePath, baseSha, allowedPaths, snapshot, 'verifier', mountedEntries);
     }
     if (observe) {
       await observe({ worktreePath, changedPaths: snapshot.changedPaths, patch: snapshot.patch, baseSha });
-      await assertSnapshotUnchanged(worktreePath, baseSha, allowedPaths, snapshot, 'observe');
+      await assertSnapshotUnchanged(worktreePath, baseSha, allowedPaths, snapshot, 'observe', mountedEntries);
     }
     result = { baseSha, ...snapshot, verifications };
   } catch (error) {

package/src/seam-derivation.mjs

@@ -0,0 +1,188 @@
+/**
+ * seam提案から実行可能な変換候補を導出する（ADR 0137・0138）。
+ *
+ * 提案が持つのは所有surfaceだけである。宣言symbolを新fileへ移すには、それが依存していて
+ * 誰も宣言していないsymbol（共有surface）と、原pathに残るもの（残余surface）まで決まっていなければ
+ * 適用後の姿が一意にならない。ここはその三面を、sensorが返した同一file内の依存から導く。
+ *
+ * 導出は宣言とsensor観測だけを入力にする。ここで新しい所有を発明しない——宣言していないsymbolは
+ * 誰のものにもせず、共有面へ送る。
+ */
+
+import { isTodoIdentifier, isTodoRef, todoSelfDigest } from './todo-contracts.mjs';
+
+export const BOUNDED_SEAM_CANDIDATE_SCHEMA = 'lattice.bounded_seam_candidate.v2';
+
+/** 三面の役割。所有だけがtaskへ紐づき、共有と残余は誰のものでもない。 */
+export const SEAM_SURFACE_ROLES = Object.freeze(['task_owned', 'shared', 'residual']);
+
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const sortedUnique = (values) => [...new Set(values)].sort(compareText);
+
+function reject(reasons) {
+  return { candidate: null, reasons: sortedUnique(reasons) };
+}
+
+/**
+ * 宣言symbolが同一file内で依存する先を、宣言されていない分だけ集める。
+ *
+ * 推移的に辿るのは、共有面が所有面へ依存しない一方向を作るためである。1段だけ見て止めると、
+ * helperのhelperが原pathに残り、共有面から原pathへの辺が生き残る。
+ */
+function collectSharedClosure({ sourcePath, ownedSymbols, calleesBySymbol }) {
+  const owned = new Set(ownedSymbols);
+  const shared = new Set();
+  const missing = new Set();
+  const pending = [...ownedSymbols];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    const callees = calleesBySymbol[current];
+    // 未照会と「calleeが無い」を同一視しない。同一視すると閉包が黙って浅くなり、
+    // 移動先で参照だけが宙に浮く——構文は通るので、実行するまで壊れたと分からない。
+    if (callees === undefined) { missing.add(current); continue; }
+    for (const callee of callees) {
+      // 同一file内だけを見る。sensorのsymbol解決は同名の別fileへ寄ることがあるので、
+      // pathのexact一致で絞らないと無関係なsymbolを共有面へ引き込む。
+      if (callee.path !== sourcePath) continue;
+      if (owned.has(callee.name) || shared.has(callee.name)) continue;
+      shared.add(callee.name);
+      pending.push(callee.name);
+    }
+  }
+  return { shared: [...shared].sort(compareText), missing: [...missing].sort(compareText) };
+}
+
+/** 共有面から所有面への辺。1本でもあれば循環を作るので候補にしない（ADR 0137 Decision 2）。 */
+function sharedDependsOnOwned({ sourcePath, ownedSymbols, sharedSymbols, calleesBySymbol }) {
+  const owned = new Set(ownedSymbols);
+  const violations = [];
+  for (const symbol of sharedSymbols) {
+    for (const callee of calleesBySymbol[symbol] ?? []) {
+      if (callee.path !== sourcePath || !owned.has(callee.name)) continue;
+      violations.push(`${symbol}->${callee.name}`);
+    }
+  }
+  return violations.sort(compareText);
+}
+
+function surfaceEntry(role, path, ownerTaskIds, symbols) {
+  return {
+    role,
+    path,
+    owner_task_ids: [...ownerTaskIds].sort(compareText),
+    symbols: [...symbols].sort(compareText),
+  };
+}
+
+/**
+ * 実行可能な変換候補を導出する。
+ *
+ * 入力はすべて記録済みの事実である——宣言（concern anchors）、提案が決めた所有surfaceのpath、
+ * sensorが返した同一file内のcallee、候補のaffected test。ここで再びsensorを引かない。
+ */
+export function deriveBoundedSeamCandidate(options = {}) {
+  const {
+    sourcePath, taskRefs, ownedSymbolsByTask, proposedPathByTask, sharedPath,
+    calleesBySymbol = {}, affectedTests = [], baseSha, manifestDigest, findingDigest,
+    candidateId,
+  } = options;
+
+  if (!isTodoRef(sourcePath)) return reject(['invalid_source_path']);
+  if (!Array.isArray(taskRefs) || taskRefs.length < 2) return reject(['task_refs_below_minimum']);
+  const taskIds = taskRefs.map(({ task_id: taskId }) => taskId);
+  if (new Set(taskIds).size !== taskIds.length) return reject(['duplicate_task_id']);
+
+  const ownedByTask = new Map();
+  for (const taskId of taskIds) {
+    const symbols = sortedUnique(ownedSymbolsByTask?.[taskId] ?? []);
+    // 宣言の無いtaskがある構成は、その所有面を作れない。片側の宣言から他方を補完しない。
+    if (symbols.length === 0) return reject([`owned_symbols_missing:${taskId}`]);
+    ownedByTask.set(taskId, symbols);
+  }
+  const ownedSymbols = sortedUnique([...ownedByTask.values()].flat());
+  const declaredCount = [...ownedByTask.values()].reduce((total, list) => total + list.length, 0);
+  if (ownedSymbols.length !== declaredCount) return reject(['owned_symbol_claimed_twice']);
+
+  const closure = collectSharedClosure({ sourcePath, ownedSymbols, calleesBySymbol });
+  // 閉包が閉じていない。呼び出し側は不足分のcalleeを引いてから導出をやり直す。
+  if (closure.missing.length > 0) {
+    return reject(closure.missing.map((symbol) => `callee_data_missing:${symbol}`));
+  }
+  const sharedSymbols = closure.shared;
+  if (sharedSymbols.length > 0 && !isTodoRef(sharedPath)) return reject(['invalid_shared_path']);
+  const violations = sharedDependsOnOwned({
+    sourcePath, ownedSymbols, sharedSymbols, calleesBySymbol,
+  });
+  if (violations.length > 0) {
+    return reject(violations.map((edge) => `shared_depends_on_owned:${edge}`));
+  }
+
+  const surfaces = [];
+  for (const taskId of [...taskIds].sort(compareText)) {
+    const path = proposedPathByTask?.[taskId];
+    if (!isTodoRef(path)) return reject([`invalid_owned_path:${taskId}`]);
+    surfaces.push(surfaceEntry('task_owned', path, [taskId], ownedByTask.get(taskId)));
+  }
+  if (sharedSymbols.length > 0) {
+    surfaces.push(surfaceEntry('shared', sharedPath, [], sharedSymbols));
+  }
+  // 残余はsymbolを列挙しない。移らなかったものすべてという補集合であり、
+  // 列挙すると原fileの全symbol目録を導出の入力に持ち込むことになる。
+  surfaces.push(surfaceEntry('residual', sourcePath, [], []));
+
+  const paths = surfaces.map(({ path }) => path);
+  if (new Set(paths).size !== paths.length) return reject(['surface_path_collision']);
+
+  const candidate = {
+    schema: BOUNDED_SEAM_CANDIDATE_SCHEMA,
+    candidate_id: candidateId,
+    base_sha: baseSha,
+    manifest_digest: manifestDigest,
+    finding_digest: findingDigest,
+    source_path: sourcePath,
+    todo_refs: [...taskRefs]
+      .map(({ plan_key: planKey, task_id: taskId }) => ({ plan_key: planKey, task_id: taskId }))
+      .sort((left, right) => compareText(
+        `${left.plan_key}\0${left.task_id}`, `${right.plan_key}\0${right.task_id}`,
+      )),
+    surfaces: surfaces.sort((left, right) => compareText(left.path, right.path)),
+    allowed_paths: sortedUnique(paths),
+    // 原pathと所有面は必ず変わる。変わっていなければ変換が起きていない。
+    required_paths: sortedUnique([sourcePath, ...surfaces
+      .filter(({ role }) => role === 'task_owned').map(({ path }) => path)]),
+    verification_policy: {
+      focused_test_refs: sortedUnique(affectedTests),
+      require_behavior_equivalence: true,
+      require_fresh_sensor: true,
+      require_overlap_reduction: true,
+      // ADR 0138。局所の競合を消して全体の競合を増やす変換と、
+      // 競合は消えるが波数が変わらない変換を採用しない。
+      require_no_new_conflict_pairs: true,
+      require_parallelism_improvement: true,
+    },
+    candidate_digest: '',
+  };
+  if (!isTodoIdentifier(candidate.candidate_id)) return reject(['invalid_candidate_id']);
+  candidate.candidate_digest = todoSelfDigest(candidate, 'candidate_digest');
+  return { candidate, reasons: [] };
+}
+
+/**
+ * 導出に要るsensor query set。宣言symbolのcalleeだけを引く。
+ *
+ * pathのconflictはaffected testしか観測していないので、同一file内の依存は別途引く必要がある
+ * （ADR 0133が「pathの競合には分割すべきcall graphが無い」と述べた面）。
+ */
+export function buildSeamDerivationQuerySet(concernSymbols = []) {
+  const symbols = sortedUnique(concernSymbols);
+  return {
+    queries: [
+      { id: 'seam-derive-status', operation: 'status' },
+      ...symbols.map((symbol, index) => ({
+        id: `seam-derive-callees-${String(index).padStart(3, '0')}`,
+        operation: 'callees',
+        target: symbol,
+      })),
+    ],
+  };
+}

package/src/seam-rewrite.mjs

@@ -0,0 +1,182 @@
+/**
+ * 三面の変換候補を実際のソースへ適用する書き換え（ADR 0137）。
+ *
+ * 決まった移動を機械的に実行するだけである。どこへ何を移すかはseam導出が決めており、
+ * 「どう書くのが綺麗か」の裁量は持ち込まない。整形の判断を入れると、変換の前後で挙動以外の差が
+ * 増え、外部挙動同等性の検証が何を見ているのか分からなくなる。
+ *
+ * 純関数として組む。worktreeへ書くのは呼び出し側の仕事で、ここはtextからtextを作る。
+ */
+
+const IMPORT_START = /^import[\s{*]/u;
+const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*|\*\/)/u;
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+
+function fail(reasons) {
+  return { files: null, reasons: [...new Set(reasons)].sort(compareText) };
+}
+
+/**
+ * 先頭のimport文を、行範囲と束縛名つきで取り出す。
+ *
+ * 複数行importがあるので`from '...'`で終わる行までを1文とする。束縛名は、移した先で
+ * どのimportが要るかを語単位で判定するために使う。
+ */
+export function scanImportStatements(lines) {
+  const statements = [];
+  let index = 0;
+  while (index < lines.length) {
+    const line = lines[index];
+    if (line.trim() === '' || COMMENT_LINE.test(line)) { index += 1; continue; }
+    if (!IMPORT_START.test(line)) break;
+    const start = index;
+    while (index < lines.length
+      && !/from\s+['"][^'"]+['"];?\s*$/u.test(lines[index])
+      && !/^import\s+['"][^'"]+['"];?\s*$/u.test(lines[index])) index += 1;
+    const end = Math.min(index, lines.length - 1);
+    const text = lines.slice(start, end + 1).join('\n');
+    statements.push({ text, bindings: importBindings(text), start, end });
+    index = end + 1;
+  }
+  return { statements, endIndex: statements.length === 0 ? -1 : statements.at(-1).end };
+}
+
+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]);
+  const defaultBinding = /^import\s+([A-Za-z_$][\w$]*)\s*(?:,|\sfrom)/u.exec(text);
+  if (defaultBinding) bindings.push(defaultBinding[1]);
+  const named = /\{([\s\S]*?)\}/u.exec(text);
+  if (named) {
+    for (const entry of named[1].split(',')) {
+      const parts = entry.split(/\s+as\s+/u).map((part) => part.trim());
+      const name = parts.length > 1 ? parts[1] : parts[0];
+      if (/^[A-Za-z_$][\w$]*$/u.test(name)) bindings.push(name);
+    }
+  }
+  return [...new Set(bindings)];
+}
+
+/** 語として現れるか。string中やcomment中の一致も拾うが、余分なimportは害にならない。 */
+function mentions(text, name) {
+  return new RegExp(`(?<![\\w$])${name.replace(/[$]/gu, '\\$$')}(?![\\w$])`, 'u').test(text);
+}
+
+/**
+ * 宣言の範囲を直前の連続コメント行まで広げる。
+ *
+ * JSDocを置き去りにすると、残余に持ち主のいない説明が残り、移した先が無説明になる。
+ * 空行で切るのは、離れた位置のコメントを巻き込まないため。
+ */
+function extendUpward(lines, startLine) {
+  let start = startLine;
+  while (start - 1 >= 1 && COMMENT_LINE.test(lines[start - 2])) start -= 1;
+  return start;
+}
+
+function exportedBlock(raw) {
+  const parts = raw.split('\n');
+  const declarationIndex = parts
+    .findIndex((line) => !COMMENT_LINE.test(line) && line.trim() !== '');
+  if (declarationIndex >= 0 && !/^\s*export\s/u.test(parts[declarationIndex])) {
+    parts[declarationIndex] = `export ${parts[declarationIndex]}`;
+  }
+  return parts.join('\n');
+}
+
+function relativeSpecifier(fromPath, toPath) {
+  const fromDir = fromPath.slice(0, fromPath.lastIndexOf('/') + 1);
+  return toPath.startsWith(fromDir) ? `./${toPath.slice(fromDir.length)}` : `./${toPath}`;
+}
+
+/**
+ * 三面の変換後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始まり・両端含む）
+ * @returns {{files: object|null, reasons: string[]}} pathごとの変換後text
+ */
+export function planSeamRewrite({ sourceText, candidate, symbolExtents } = {}) {
+  if (typeof sourceText !== 'string' || sourceText.length === 0) return fail(['empty_source']);
+  const lines = sourceText.split('\n');
+  const surfaces = candidate?.surfaces ?? [];
+  const residual = surfaces.find(({ role }) => role === 'residual');
+  const moving = surfaces.filter(({ role }) => role !== 'residual');
+  if (residual === undefined || moving.length === 0) return fail(['surfaces_incomplete']);
+
+  const blocks = [];
+  for (const surface of moving) {
+    for (const symbol of surface.symbols) {
+      const extent = symbolExtents?.[symbol];
+      if (extent === undefined
+        || !Number.isSafeInteger(extent.startLine) || !Number.isSafeInteger(extent.endLine)
+        || extent.startLine < 1 || extent.endLine > lines.length
+        || extent.endLine < extent.startLine) {
+        return fail([`symbol_extent_missing:${symbol}`]);
+      }
+      blocks.push({
+        symbol, path: surface.path, end: extent.endLine,
+        start: extendUpward(lines, extent.startLine),
+      });
+    }
+  }
+  blocks.sort((left, right) => left.start - right.start);
+  for (let index = 1; index < blocks.length; index += 1) {
+    // 範囲が重なる宣言は、片方を切ると他方が壊れる。整形で解こうとせず止める。
+    if (blocks[index].start <= blocks[index - 1].end) {
+      return fail([`symbol_extent_overlap:${blocks[index - 1].symbol}:${blocks[index].symbol}`]);
+    }
+  }
+
+  const { statements, endIndex } = scanImportStatements(lines);
+  if (blocks.some((block) => block.start <= endIndex + 1)) {
+    return fail(['symbol_inside_import_block']);
+  }
+
+  const bodyByPath = new Map();
+  const removal = new Set();
+  for (const block of blocks) {
+    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));
+    for (let line = block.start; line <= block.end; line += 1) removal.add(line);
+  }
+
+  const symbolPath = new Map(blocks.map((block) => [block.symbol, block.path]));
+  const importsFor = (ownerPath, body) => {
+    const carried = statements
+      .filter((statement) => statement.bindings.some((name) => mentions(body, name)))
+      .map((statement) => statement.text);
+    const byTarget = new Map();
+    for (const [symbol, targetPath] of symbolPath) {
+      if (targetPath === ownerPath || !mentions(body, symbol)) continue;
+      if (!byTarget.has(targetPath)) byTarget.set(targetPath, []);
+      byTarget.get(targetPath).push(symbol);
+    }
+    const cross = [...byTarget.entries()]
+      .sort(([left], [right]) => compareText(left, right))
+      .map(([targetPath, names]) => `import { ${[...names].sort(compareText).join(', ')} } from '${relativeSpecifier(ownerPath, targetPath)}';`);
+    return [...carried, ...cross];
+  };
+
+  const files = {};
+  for (const [path, bodies] of bodyByPath) {
+    const body = bodies.join('\n\n');
+    const header = importsFor(path, body);
+    files[path] = `${header.length === 0 ? '' : `${header.join('\n')}\n\n`}${body}\n`;
+  }
+
+  const keptHeader = lines.slice(0, endIndex + 1);
+  const keptBody = lines.slice(endIndex + 1)
+    .filter((_, index) => !removal.has(endIndex + 2 + index));
+  const residualBody = keptBody.join('\n').replace(/\n{3,}/gu, '\n\n').replace(/\n+$/u, '');
+  const residualCross = importsFor(residual.path, residualBody)
+    .filter((statement) => !keptHeader.join('\n').includes(statement));
+  files[residual.path] = `${[...keptHeader, ...residualCross].join('\n')}\n${residualBody}\n`
+    .replace(/^\n+/u, '');
+
+  return { files, reasons: [] };
+}