@quolu/lattice 0.26.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",
@@ -60,7 +60,10 @@
     "test": "node scripts/run-product-tests.mjs",
     "test:sensor": "npm --prefix sensor test",
     "check": "node scripts/check-syntax.mjs",
-    "ci": "npm run test && npm run test:sensor && npm run check && npm run verify:todo-store",
-    "verify:todo-store": "node bin/lattice.mjs todo verify --json"
+    "ci": "npm run test && npm run test:sensor && npm run check && npm run check:cli-surface && npm run check:open-questions && npm run check:reachability && npm run verify:todo-store",
+    "verify:todo-store": "node bin/lattice.mjs todo verify --json",
+    "check:cli-surface": "node scripts/verify-cli-surface.mjs",
+    "check:open-questions": "node scripts/verify-open-questions.mjs",
+    "check:reachability": "node scripts/verify-product-reachability.mjs"
   }
 }

package/src/cli-help.mjs

@@ -44,6 +44,10 @@ Commands:
   close --run .lattice/runs/<id>
   abandon --run .lattice/runs/<id> --reason <reason>
   list --json
+  seam resolve --run .lattice/runs/<id> --finding <digest> --input <request.json>
+      # 記録済み競合を隔離worktreeで実際に変換し、五条件を通ればseam splitと後継baseを返す。
+      # 入力(lattice.runtime_seam_request.v1)へ書くのは、係争fileの中で各TODOが触るsymbolと
+      # 新しい面の名前だけ。branchは動かさないので、後継baseへ進めるかは呼び出し側が決める。
 `,
   event: `Usage: lattice event verify --run .lattice/runs/<id>
 `,
@@ -119,6 +123,8 @@ registerはLATTICE_BRIDGE_REGISTRAR_SSH_HOSTとLATTICE_BRIDGE_REGISTRAR_SCRIPT
 });
 
 const SUBCOMMAND_USAGE = Object.freeze({
+  status: 'status --json',
+  'session-context': 'session-context --json',
   'plan create': 'plan create --input <file> | --schema --json | --schema-version <2|3> --json',
   'plan compile': 'plan compile --request <request.json> | --schema --json',
   'plan verify': 'plan verify --request <request.json> --plan <plan.json>',
@@ -131,6 +137,13 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'run close': 'run close --run .lattice/runs/<id>',
   'run abandon': 'run abandon --run .lattice/runs/<id> --reason <reason>',
   'run list': 'run list --json',
+  'run activate': 'run activate --run .lattice/runs/<id>',
+  'run conflict': 'run conflict --run .lattice/runs/<id> --finding <digest>',
+  'run hold': 'run hold --run .lattice/runs/<id> --finding <digest>',
+  'run recompile': 'run recompile --run .lattice/runs/<id> --input <recompile-request.json>',
+  'run reprocess': 'run reprocess --run .lattice/runs/<id>',
+  'run finding record': 'run finding record --run .lattice/runs/<id> --checkpoint <digest> --input <candidate.json>',
+  'run seam resolve': 'run seam resolve --run .lattice/runs/<id> --finding <digest> --input <seam-request.json>',
   'event verify': 'event verify --run .lattice/runs/<id>',
   'todo status': 'todo status [--json]',
   'todo bindings': 'todo bindings [--plan <key>] [--json]',
@@ -155,6 +168,7 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'todo revise': 'todo revise --plan <key> --input <file>',
   'todo revise-phase': 'todo revise-phase --plan <key> --input <file>',
   'todo revise-set': 'todo revise-set --input <file>',
+  'todo migrate': 'todo migrate --input <extraction.json>',
   'sensor init': 'sensor init [path] --json',
   'sensor sync': 'sensor sync [path] --json',
   'runtime-errors snapshot': 'runtime-errors snapshot [--after-cursor <n>] [--limit <n>] --json',
@@ -192,5 +206,10 @@ export function renderCliHelp(argv) {
     return usage === undefined ? null : `Usage: lattice ${usage}\n`;
   }
   const namespace = requestedNamespace(argv);
-  return namespace === null ? null : NAMESPACE_HELP[namespace] ?? null;
+  if (namespace === null) return null;
+  // namespaceを持たない1語コマンド（status等）は、SUBCOMMAND_USAGEへ落ちる。
+  // 落とさないと「存在するのに使い方を知る手段が無い」コマンドになる。
+  if (NAMESPACE_HELP[namespace] !== undefined) return NAMESPACE_HELP[namespace];
+  const usage = SUBCOMMAND_USAGE[namespace];
+  return usage === undefined ? null : `Usage: lattice ${usage}\n`;
 }

package/src/isolation-runner.mjs

@@ -311,7 +311,15 @@ export async function runIsolatedTransform({ repoRoot, baseRef, allowedPaths, tr
   const mountedEntries = mounts.map(({ entry }) => entry);
 
   const sourceState = await captureSourceState(repoRoot);
-  if (sourceState.visibleStatus.length > 0) throw new Error('source repository must be clean');
+  if (sourceState.visibleStatus.length > 0) {
+    // どのpathが汚しているかを言わないと、呼び出したAIは何を片付ければよいか分からない。
+    // 実運用で、このコマンドへ渡す入力fileそのものが木を汚して詰まった。
+    // visibleStatusはNUL区切りのBufferである。行として扱うと空文字が並ぶ。
+    const entries = statusPaths(sourceState.visibleStatus).slice(0, 20);
+    throw new Error('source repository must be clean :: '
+      + `${entries.join(' | ')} :: 変換は既知のbaseに対して測る。commitするか、`
+      + 'gitが無視するpathへ退避してから再実行する');
+  }
   const baseSha = (await run('git', ['rev-parse', '--verify', `${baseRef}^{commit}`], { cwd: repoRoot })).stdout.toString('utf8').trim();
   const worktreePath = await mkdtemp(path.join(os.tmpdir(), 'lattice-isolated-transform-'));
   let added = false;
@@ -349,7 +357,18 @@ export async function runIsolatedTransform({ repoRoot, baseRef, allowedPaths, tr
         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}`);
+        // どのverifierがなぜ落ちたかを載せる。commandだけ返すと、五条件の棄却理由が
+        // 「focused testが落ちた」で止まり、原因を追う手段が無くなる。
+        // stdout/stderrはBufferで、空でもtruthyになる。`||`で繋ぐとstdoutへ落ちない。
+        // node --testは失敗をstdoutへ書くので、それを取り落とすと理由が消える。
+        const streams = [error?.stderr, error?.stdout]
+          .map((value) => (value === undefined ? '' : String(value)))
+          .filter((value) => value.trim().length > 0);
+        const detail = (streams[0] ?? '')
+          .split('\n').filter((line) => line.trim().length > 0).slice(-6).join(' | ').slice(0, 600);
+        throw new Error(`verifier failed (${error.signal ?? error.code}):`
+          + ` ${[verifier.command, ...verifier.args].join(' ')}`
+          + (detail.length > 0 ? ` :: ${detail}` : ''));
       }
       await assertSnapshotUnchanged(worktreePath, baseSha, allowedPaths, snapshot, 'verifier', mountedEntries);
     }

package/src/runtime-cli.mjs

@@ -15,10 +15,15 @@ import {
   writeFile,
 } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { canonicalizeArtifact, digestArtifact } from './artifact-contracts.mjs';
 import { collectSensorEvidence } from './sensor-adapter.mjs';
 import { detectCheckpointFindings } from './runtime-diff-observer.mjs';
+import {
+  buildRuntimeSeamResolution, readRuntimeFindingRecord, resolveRuntimeSeam,
+  validateRuntimeSeamRequest, verifySeamSplitSuccessor,
+} from './runtime-seam-resolve.mjs';
 import {
   compileRuntimePlanV1,
   evidenceFromCollectedOutcomes,
@@ -995,6 +1000,51 @@ async function runStart({ requestPath, executorAdapter, cwd, stdout }) {
   return 0;
 }
 
+/**
+ * 記録済み競合findingを、実際の変換で解消する（請求項8・ADR 0137〜0141）。
+ *
+ * 事前宣言されたtreatmentが無い競合は、これが無い間ずっと意図的直列へ退化していた。
+ * 隔離worktreeで変換し、五条件（ADR 0138）を通り、確定できた時だけseam splitを返す。
+ *
+ * branchは動かさない。返す`successor_base_sha`へ進めるかどうかは操作するAIが決める——
+ * 静的側の`land`と同じ責務分担であり、Latticeは変換・検証・記録と、後継baseの検査を持つ。
+ */
+async function runSeamResolve({ runDir, repoRoot, findingDigest, requestPath, stdout }) {
+  const committed = await readCommittedEpochStore(runDir);
+  if (committed === null) {
+    throw new CliContractError('RUN_NOT_MANAGED', 'runがmanaged storeへactivateされていない');
+  }
+  const declaration = await readBoundedJson(requestPath, 'runtime seam request');
+  if (!validateRuntimeSeamRequest(declaration)) {
+    throw new CliContractError('INVALID_SEAM_REQUEST', 'lattice.runtime_seam_request.v1として不正');
+  }
+  if (declaration.run_id !== committed.meta.run_id) {
+    throw new CliContractError('INVALID_SEAM_REQUEST', '宣言のrun_idがrun storeと一致しない');
+  }
+  if (declaration.finding_digest !== findingDigest) {
+    throw new CliContractError('INVALID_SEAM_REQUEST', '宣言のfinding_digestが--findingと一致しない');
+  }
+  const found = await readRuntimeFindingRecord({
+    runDir, findingDigest, planEpoch: committed.pointer.plan_epoch,
+  });
+  if (found.record === null) throw new CliContractError('STALE_FINDING', found.reason);
+
+  const resolved = await resolveRuntimeSeam({
+    repoRoot,
+    runDir,
+    findingRecord: found.record,
+    bundle: committed.bundle,
+    declaration,
+    latticeBin: fileURLToPath(new URL('../bin/lattice.mjs', import.meta.url)),
+    compiledAt: canonicalNow(),
+  });
+  const resolution = buildRuntimeSeamResolution({
+    runId: committed.meta.run_id, findingDigest, resolved,
+  });
+  stdout.write(`${JSON.stringify(resolution)}\n`);
+  return resolution.lane === 'seam_transform' ? 0 : 1;
+}
+
 async function runObserve({ runDir, stdout }) {
   const { events } = await readRunStore(runDir);
   const chain = verifyRunEventChain({ events });
@@ -2068,6 +2118,27 @@ export async function runManagedSupervisorDaemon({
           newPlan.conflicts.sort((left, right) => `${left.todo_ids.join('\0')}\0${left.resource_id}`
             .localeCompare(`${right.todo_ids.join('\0')}\0${right.resource_id}`));
         }
+        if (recompileRequest.mode === 'seam_split') {
+          // 変換を含まないbaseを指したseam_splitを通さない（ADR 0141）。splitが新しい面の
+          // 所有を宣言するのに後継treeにそのfileが無い、という状態を作らせない。
+          const predecessorBaseSha = active.bundle.request.repo.base_sha;
+          const successorBaseSha = recompileRequest.successor_request.repo.base_sha;
+          const ancestry = await runGit(
+            ['merge-base', '--is-ancestor', predecessorBaseSha, successorBaseSha], repoRoot,
+          );
+          const verdict = verifySeamSplitSuccessor({
+            split: recompileRequest.seam_split,
+            predecessorBaseSha,
+            successorBaseSha,
+            successorIsDescendant: ancestry.code === 0,
+            successorConflicts: newPlan.conflicts,
+            successorWitness: recompileRequest.successor_request.manual_witness,
+          });
+          if (!verdict.ok) {
+            throw new ManagedRuntimeError('SEAM_SPLIT_UNPROVEN',
+              `後継baseがseam splitの主張を満たさない: ${verdict.reasons.join(', ')}`);
+          }
+        }
         newPlan.plan_digest = selfDigest(newPlan, 'plan_digest');
         const executorPackets = buildExecutorPackets({ plan: newPlan, manifests: compiled.manifests });
 
@@ -3189,6 +3260,16 @@ export async function runRuntimeCli({ argv, cwd, stdout, stderr }) {
         requestId: requestIdOverride,
       });
     };
+  } else if (argv.length === 9
+    && argv[0] === 'run' && argv[1] === 'seam' && argv[2] === 'resolve'
+    && argv[3] === '--run' && typeof argv[4] === 'string' && argv[4].length > 0
+    && argv[5] === '--finding' && /^[0-9a-f]{64}$/u.test(argv[6])
+    && argv[7] === '--input' && typeof argv[8] === 'string' && argv[8].length > 0) {
+    action = async () => {
+      const { repoRoot, runDir } = await resolveRunStore(cwd, argv[4]);
+      return runSeamResolve({ runDir, repoRoot, findingDigest: argv[6],
+        requestPath: path.resolve(cwd, argv[8]), stdout });
+    };
   } else if (argv.length === 8
     && argv[0] === 'run' && argv[1] === 'finding' && argv[2] === 'record'
     && argv[3] === '--run' && typeof argv[4] === 'string' && argv[4].length > 0

package/src/runtime-hold-recompile.mjs

@@ -65,7 +65,6 @@ function sha16(value) {
 
 const WITNESS_KINDS = Object.freeze(['state', 'schema', 'invariant', 'effect', 'external_effect']);
 const HEX_DIGEST = /^[0-9a-f]{64}$/u;
-const HEX_SHA1 = /^[0-9a-f]{40}$/u;
 const IDENTIFIER = /^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$/u;
 const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 
@@ -616,24 +615,20 @@ export function routeConflictTreatment(options = {}) {
  * （content不変・epoch/plan refのみ更新）、hold TODOへは新plan_ref由来の
  * 新context packetを発行し、旧contextを失効する。rebind／prepare ack、epoch pointer、
  * controller ready/release ack、中央gate commit前にはepoch_rebound/intake_resumedを発行しない。
+ *
+ * baseはここでは動かさない。変換で構造が変わった時に後継baseを決めるのは後継run requestで
+ * あり、それが本当に変換を含むかは`verifySeamSplitSuccessor`が見る（ADR 0141）。
  */
 export function recompileNextEpochPlan(options = {}) {
   if (!exactRecord(options, [
     'runId', 'request', 'plan', 'manifests', 'packets', 'events', 'holdDecision',
     'additionalConflicts', 'recordedAt',
-  ]) && !exactRecord(options, [
-    'runId', 'request', 'plan', 'manifests', 'packets', 'events', 'holdDecision',
-    'additionalConflicts', 'recordedAt', 'successorBaseSha',
   ])) {
     fail('recompileNextEpochPlan optionsがexact shapeでない');
   }
   const {
     runId, request, plan, manifests, packets, events, holdDecision, additionalConflicts, recordedAt,
-    successorBaseSha = null,
   } = options;
-  if (successorBaseSha !== null && !HEX_SHA1.test(successorBaseSha)) {
-    fail('successorBaseShaがgit shaでない');
-  }
   if (!validateRuntimePlan(plan)) fail('planがruntime_plan.v1 contractを満たさない');
   if (!validateHoldDecision(holdDecision)) fail('holdDecisionがcontractを満たさない');
   if (!Array.isArray(additionalConflicts)) fail('additionalConflictsがarrayではない');
@@ -681,11 +676,7 @@ export function recompileNextEpochPlan(options = {}) {
     plan_ref: newPlanRef,
     plan_epoch: newEpoch,
     request_digest: request.request_digest,
-    // 変換でsourceの構造が変わったなら、再開先は変換を含むbaseでなければならない。
-    // 旧baseのまま再開させると、splitが所有を宣言した新pathがworktreeに存在しない（ADR 0141）。
-    // carry-over側のrebind packetはcontent不変が要件なので、そちらは触らない——
-    // 継続する作業は自分のworktreeで走り続けており、baseを付け替える対象ではない。
-    base_sha: successorBaseSha ?? plan.base_sha,
+    base_sha: plan.base_sha,
     nodes: structuredClone(plan.nodes),
     precedence: structuredClone(plan.precedence),
     conflicts: mergedConflicts,

package/src/runtime-seam-resolve.mjs

@@ -0,0 +1,283 @@
+/**
+ * 実行時に観測した競合を、実際の変換で解消するproduct入口（請求項8）。
+ *
+ * これが無い間、変換の中身は動くのに実運転からそこへ行く道が無かった。実運転側が使う
+ * `routeConflictTreatment`は「事前宣言済みtreatmentがpathを覆う時だけseam_transform」なので、
+ * **予期しなかった競合は変換にかからず直列へ退化していた**。
+ *
+ * 装置の境界にAIを含める（AGENTS.md）。したがってここでLatticeが供給するのは、AIが自分では
+ * 作れないもの——構造観測、隔離実行、五条件の検証、変換の確定と記録——だけである。
+ * 「どのTODOが係争fileの中のどのsymbolを触るか」「新しい面をどう名付けるか」はAIが既に
+ * 知っているので、宣言として受け取る。推定しない。
+ */
+
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import { digestArtifact } from './artifact-contracts.mjs';
+import { commitSeamTransform } from './seam-commit.mjs';
+import { applySeamConflict } from './seam-apply.mjs';
+import { resolveRuntimeSeamTreatment } from './runtime-seam-treatment.mjs';
+import { collectWitnessSensorEvidence, compileTodoIndependence } from './todo-independence.mjs';
+import { todoSelfDigest } from './todo-contracts.mjs';
+
+export const RUNTIME_SEAM_REQUEST_SCHEMA = 'lattice.runtime_seam_request.v1';
+export const RUNTIME_SEAM_RESOLUTION_SCHEMA = 'lattice.runtime_seam_resolution.v1';
+
+/** 合成するtodo planのkey。実行時planとは別空間なので固定でよい。 */
+const SYNTHETIC_PLAN_KEY = 'runtime';
+const HEX_DIGEST = /^[0-9a-f]{64}$/u;
+const REPO_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[\w./-]+$/u;
+const IDENTIFIER = /^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$/u;
+
+const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+
+/** 資源idはruntime front-endと同じ合成形にする（`own-<kind>-<sha16>`）。 */
+const sha16 = (value) => createHash('sha256').update(value, 'utf8').digest('hex').slice(0, 16);
+
+function plainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function exactRecord(value, keys) {
+  if (!plainObject(value)) return false;
+  const own = Object.keys(value);
+  return own.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+/**
+ * AIが出す宣言。ここに書くのは「係争fileの中で各TODOが触るsymbol」「新しい面の名前」
+ * 「後継planへ渡すtask migrationのdigest」だけで、どれもAIが既に持っている情報である。
+ */
+export function validateRuntimeSeamRequest(value) {
+  if (!exactRecord(value, [
+    'schema', 'run_id', 'finding_digest', 'concern_symbols', 'path_names',
+    'task_migration_digest', 'request_digest',
+  ])) return false;
+  if (value.schema !== RUNTIME_SEAM_REQUEST_SCHEMA) return false;
+  if (!IDENTIFIER.test(value.run_id ?? '')) return false;
+  if (!HEX_DIGEST.test(value.finding_digest ?? '')) return false;
+  if (!HEX_DIGEST.test(value.task_migration_digest ?? '')) return false;
+  if (!plainObject(value.concern_symbols) || !plainObject(value.path_names)) return false;
+
+  const todoIds = Object.keys(value.concern_symbols);
+  if (todoIds.length < 2 || todoIds.length > 64) return false;
+  for (const todoId of todoIds) {
+    if (!IDENTIFIER.test(todoId)) return false;
+    const symbols = value.concern_symbols[todoId];
+    if (!Array.isArray(symbols) || symbols.length === 0 || symbols.length > 256) return false;
+    if (!symbols.every((symbol) => IDENTIFIER.test(symbol))) return false;
+    if (!REPO_PATH.test(value.path_names[todoId] ?? '')) return false;
+  }
+  // sharedはresidualから切り出す共有面。TODOに属さないので別枠で必ず要る。
+  if (!REPO_PATH.test(value.path_names.shared ?? '')) return false;
+  if (!exactRecord(value.path_names, [...todoIds, 'shared'])) return false;
+  if (!HEX_DIGEST.test(value.request_digest ?? '')) return false;
+  return value.request_digest === todoSelfDigest(value, 'request_digest');
+}
+
+/**
+ * 実行時witnessへconcern anchorを足してtodo witness setにする。
+ *
+ * 実行時のmanual_witnessはconcern_anchorsを持たない（`lattice.run_request.v3`）。持たせるのでなく、
+ * 宣言から足す——係争資源の中のどのsymbolを触るかは実行時に確定する情報であり、run開始時点の
+ * 契約に書けるものではないからである。
+ */
+export function buildRuntimeSeamWitnessSet({ request, declaration, contestedPath, executors }) {
+  const todoIds = Object.keys(declaration.concern_symbols).sort(compareText);
+  const manual = {};
+  for (const todoId of todoIds) {
+    const witness = request.manual_witness?.[todoId];
+    if (!plainObject(witness)) return { witnessSet: null, reasons: [`witness_absent:${todoId}`] };
+    manual[todoId] = {
+      ...structuredClone(witness),
+      concern_anchors: [{
+        within: { kind: 'path', target: contestedPath },
+        symbols: [...declaration.concern_symbols[todoId]].sort(compareText),
+      }],
+    };
+  }
+  const witnessSet = {
+    schema: 'lattice.todo_witness_set.v3',
+    project_id: SYNTHETIC_PLAN_KEY,
+    plan_key: SYNTHETIC_PLAN_KEY,
+    capacity: { executors },
+    sensor_query_set: structuredClone(request.sensor_query_set),
+    manual_witness: manual,
+    witness_set_digest: '',
+  };
+  witnessSet.witness_set_digest = todoSelfDigest(witnessSet, 'witness_set_digest');
+  return { witnessSet, reasons: [] };
+}
+
+function syntheticTodoPlan(todoIds) {
+  return {
+    schema: 'lattice.todo_plan.v2',
+    project_id: SYNTHETIC_PLAN_KEY,
+    plan_key: SYNTHETIC_PLAN_KEY,
+    plan_version: 'v1',
+    topology_digest: digestArtifact({ tasks: [...todoIds].sort(compareText) }),
+    tasks: [...todoIds].sort(compareText).map((taskId) => ({ task_id: taskId })),
+  };
+}
+
+/**
+ * 記録済みfindingと宣言から、変換を導出・適用・検証・確定して処置を返す。
+ *
+ * 五条件（ADR 0138）を1つでも欠いたら意図的直列を返す。確定できなければ採用しない（ADR 0141）。
+ * 「変換した」と言いながら再開できない状態を作らない。
+ */
+export async function resolveRuntimeSeam({
+  repoRoot, runDir, findingRecord, bundle, declaration, latticeBin, compiledAt,
+} = {}) {
+  const finding = findingRecord.finding;
+  const request = bundle.request;
+  const baseSha = request.repo.base_sha;
+  const todoIds = Object.keys(declaration.concern_symbols).sort(compareText);
+
+  if (finding.kind !== 'observed_write_conflict' || typeof finding.path !== 'string') {
+    return { lane: 'intentional_serial', reasons: ['finding_not_write_conflict'], split: null };
+  }
+  const findingTodoIds = [...finding.todo_ids].sort(compareText);
+  if (findingTodoIds.join('\0') !== todoIds.join('\0')) {
+    return {
+      lane: 'intentional_serial',
+      reasons: ['declared_todos_differ_from_finding'],
+      split: null,
+    };
+  }
+
+  const built = buildRuntimeSeamWitnessSet({
+    request, declaration, contestedPath: finding.path,
+    executors: request.capacity.executors,
+  });
+  if (built.witnessSet === null) {
+    return { lane: 'intentional_serial', reasons: built.reasons, split: null };
+  }
+  const witnessSet = built.witnessSet;
+  const plan = syntheticTodoPlan(todoIds);
+
+  // 観測したaffected testsだけを検証に使う。宣言から発明しない。
+  const affectedTests = [...new Set(todoIds
+    .flatMap((todoId) => request.manual_witness[todoId].affected_tests))].sort(compareText);
+
+  const baseArtifact = compileTodoIndependence({
+    witnessSet, plan, baseSha, compiledAt,
+    sensorEvidence: await collectWitnessSensorEvidence({ cwd: repoRoot, witnessSet }),
+  });
+
+  const pathNames = { ...declaration.path_names };
+  return resolveRuntimeSeamTreatment({
+    finding,
+    witnessSet,
+    pathNames,
+    baseSha,
+    manifestDigest: baseArtifact.result_digest,
+    affectedTests,
+    taskMigrationDigest: declaration.task_migration_digest,
+    commitTransform: async ({ files, candidateId }) => commitSeamTransform({
+      repoRoot, baseSha, files, candidateId,
+    }),
+    applyConflict: async ({ conflict }) => {
+      const applied = await applySeamConflict({
+        repoRoot,
+        planKey: SYNTHETIC_PLAN_KEY,
+        conflict,
+        witnessSet,
+        latticeBin,
+        sharedPathFor: () => declaration.path_names.shared,
+        executors: request.capacity.executors,
+        pathNames,
+        compileIndependence: {
+          baseArtifact,
+          inWorktree: async ({ worktreePath, witnessSet: postWitness }) => compileTodoIndependence({
+            witnessSet: postWitness,
+            plan,
+            baseSha,
+            compiledAt,
+            sensorEvidence: await collectWitnessSensorEvidence({
+              cwd: worktreePath, witnessSet: postWitness,
+            }),
+          }),
+        },
+      });
+      return { ...applied, candidate: applied.candidate ?? null };
+    },
+  });
+}
+
+/** 決着をartifactにする。branchを動かすのは操作するAIなので、行き先を明示して返す。 */
+export function buildRuntimeSeamResolution({ runId, findingDigest, resolved }) {
+  const resolution = {
+    schema: RUNTIME_SEAM_RESOLUTION_SCHEMA,
+    run_id: runId,
+    finding_digest: findingDigest,
+    lane: resolved.lane,
+    reasons: [...resolved.reasons].sort(compareText),
+    split: resolved.split ?? null,
+    successor_base_sha: resolved.successor_base_sha ?? null,
+    successor_base_ref: resolved.successor_base_ref ?? null,
+    resolution_digest: '',
+  };
+  resolution.resolution_digest = todoSelfDigest(resolution, 'resolution_digest');
+  return resolution;
+}
+
+/**
+ * seam_split再計画で、後継baseが本当に変換を含むかを検査する（ADR 0141）。
+ *
+ * これが無い間、`mode: 'seam_split'`の再計画requestは**変換を含まないbaseを指していても通った**。
+ * splitは新しい面の所有を宣言するのに、compileされる後継treeにそのfileが無い——rb工程で
+ * 直したのと同じ欠陥が、管理runtimeの層に残っていた。
+ *
+ * 検査するのは3つ。どれもLatticeが既に持っているartifactだけで判定でき、推定を含まない。
+ *
+ * 1. baseが前進し、かつ旧baseの子孫であること。変換が着地していなければ前進しない。
+ * 2. splitが「消える」と述べた競合辺が、後継planに実際に無いこと。後継treeに変換が
+ *    載っていなければ両TODOは同じfileを書き続けるので、この辺は消えない。
+ * 3. splitが新たに所有すると述べた資源が、後継requestで**creationとして宣言されていない**こと。
+ *    seam splitは既存codeを新しい面へ移す操作であり、変換が既に作っている。これから作る、
+ *    と宣言されているなら、指しているbaseは変換前である。
+ */
+export function verifySeamSplitSuccessor({
+  split, predecessorBaseSha, successorBaseSha, successorIsDescendant,
+  successorConflicts = [], successorWitness = {},
+} = {}) {
+  const reasons = [];
+  if (successorBaseSha === predecessorBaseSha) reasons.push('successor_base_not_advanced');
+  else if (successorIsDescendant !== true) reasons.push('successor_base_not_descendant');
+
+  const removedEdges = split?.edge_diff?.removed ?? [];
+  const remaining = new Set(successorConflicts
+    .map(({ todo_ids: ids }) => [...ids].sort(compareText).join('\0')));
+  for (const edge of removedEdges) {
+    const key = [edge.from_todo_id, edge.to_todo_id].sort(compareText).join('\0');
+    if (remaining.has(key)) reasons.push(`declared_removed_conflict_persists:${key.replace('\0', ',')}`);
+  }
+
+  for (const added of split?.ownership_diff?.added ?? []) {
+    const owns = successorWitness[added.owner_todo_id]?.owns ?? [];
+    for (const own of owns) {
+      const resourceId = `own-${own.kind}-${sha16(own.target)}`;
+      if (resourceId === added.resource_id && own.creates === true) {
+        reasons.push(`declared_owned_surface_is_creation:${added.owner_todo_id}`);
+      }
+    }
+  }
+  return { ok: reasons.length === 0, reasons: [...new Set(reasons)].sort(compareText) };
+}
+
+/** `<runDir>/findings/<digest>.json`を読む。存在しない／別epochのfindingは受けない。 */
+export async function readRuntimeFindingRecord({ runDir, findingDigest, planEpoch }) {
+  const filePath = path.join(runDir, 'findings', `${findingDigest}.json`);
+  let record;
+  try {
+    record = JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return { record: null, reason: 'finding_not_recorded' };
+  }
+  if (record?.finding_digest !== findingDigest) return { record: null, reason: 'finding_digest_mismatch' };
+  if (record.plan_epoch !== planEpoch) return { record: null, reason: 'finding_from_other_epoch' };
+  return { record, reason: null };
+}

package/src/seam-commit-shared.mjs

@@ -0,0 +1,22 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+export const execFileAsync = promisify(execFile);
+
+export const GIT_SHA1 = /^[0-9a-f]{40}$/u;
+
+export const SEAM_REF_PREFIX = 'refs/lattice/seam';
+
+export async function git(args, cwd) {
+  const { stdout } = await execFileAsync('git', args, {
+    cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+  });
+  return stdout;
+}
+
+export function safeRelative(target) {
+  return typeof target === 'string' && target.length > 0 && !target.includes('\0')
+    && !path.posix.isAbsolute(target) && target === path.posix.normalize(target)
+    && !target.split('/').includes('..');
+}

package/src/seam-commit-transform.mjs

@@ -0,0 +1,81 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { GIT_SHA1, execFileAsync, git, safeRelative } from './seam-commit-shared.mjs';
+import { seamRefFor } from './seam-ref.mjs';
+
+/**
+ * 採用された変換をcommitへ確定し、そのshaを返す。
+ *
+ * 本repositoryの作業ツリーは触らない。使い捨てworktreeをbaseへ張り、変換後のfileを書き、
+ * detached HEADでcommitし、refへ繋いでからworktreeを畳む。commit objectはobject DBを共有する
+ * ので、worktreeを消してもshaは生き残る——refはそれをGCから守るためである。
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot 本repository
+ * @param {string} options.baseSha 変換前のbase
+ * @param {object} options.files pathごとの変換後text
+ * @param {string} options.candidateId ref名に使う識別子
+ * @param {string} options.message commit message
+ * @returns {Promise<{commitSha: string, ref: string}>}
+ */
+export async function commitSeamTransform({
+  repoRoot, baseSha, files, candidateId, message,
+} = {}) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) throw new TypeError('repoRootが不正');
+  if (!GIT_SHA1.test(baseSha ?? '')) throw new TypeError('baseShaが不正');
+  if (files === null || typeof files !== 'object' || Array.isArray(files)
+    || Object.keys(files).length === 0) throw new TypeError('filesが不正');
+  const targets = Object.keys(files);
+  if (!targets.every(safeRelative)) throw new TypeError('変換後pathがrepo相対規律を満たさない');
+  if (typeof candidateId !== 'string' || !/^[0-9A-Za-z][\w.-]{0,127}$/u.test(candidateId)) {
+    throw new TypeError('candidateIdが不正');
+  }
+
+  const worktreeRoot = await mkdtemp(path.join(tmpdir(), 'lattice-seam-commit-'));
+  const worktreePath = path.join(worktreeRoot, 'tree');
+  let commitSha;
+  try {
+    await git(['worktree', 'add', '--detach', '--quiet', worktreePath, baseSha], repoRoot);
+    for (const [target, text] of Object.entries(files)) {
+      const absolute = path.join(worktreePath, target);
+      await mkdir(path.dirname(absolute), { recursive: true });
+      await writeFile(absolute, text);
+    }
+    await git(['add', '--', ...targets], worktreePath);
+    // 変換で1 byteも変わらなかったなら、確定すべき成果が無い。空commitで
+    // 「進んだ」ように見せない。
+    const staged = await git(['diff', '--cached', '--name-only'], worktreePath);
+    if (staged.trim() === '') throw new TypeError('変換後の差分が無い');
+    await git([
+      '-c', 'user.email=lattice@localhost', '-c', 'user.name=lattice',
+      'commit', '--quiet', '-m', message ?? `seam transform ${candidateId}`,
+    ], worktreePath);
+    commitSha = (await git(['rev-parse', 'HEAD'], worktreePath)).trim();
+    if (!GIT_SHA1.test(commitSha)) throw new TypeError('commit shaが不正');
+  } finally {
+    await git(['worktree', 'remove', '--force', worktreePath], repoRoot).catch(() => {});
+    await rm(worktreeRoot, { recursive: true, force: true });
+  }
+
+  // worktreeを畳んだ後にrefを張る。object DBは共有なのでshaは生きているが、
+  // refが無いとGCの対象になる。
+  const ref = seamRefFor(candidateId);
+  // 同じcandidateへ2回目の変換が来た時、黙って上書きすると1回目の証跡が消える。
+  // 連鎖は「前の変換を含むbaseの上で次を確定する」形でしか正しくならないので、
+  // 既存refが今回のbaseの祖先を指していなければ拒む（ADR 0142 / ADR 0141 OQ2）。
+  const existing = await git(['for-each-ref', '--format=%(objectname)', ref], repoRoot)
+    .then((stdout) => stdout.trim())
+    .catch(() => '');
+  if (GIT_SHA1.test(existing) && existing !== commitSha) {
+    const chained = await execFileAsync('git', ['merge-base', '--is-ancestor', existing, baseSha], {
+      cwd: repoRoot, encoding: 'utf8',
+    }).then(() => true).catch(() => false);
+    if (!chained) {
+      throw new Error(`seam ref ${ref} は既に ${existing} を指しており、今回のbaseはその子孫でない`
+        + '。前の変換を含むbaseの上で確定するか、別のcandidate idを使う');
+    }
+  }
+  await git(['update-ref', ref, commitSha], repoRoot);
+  return { commitSha, ref };
+}

package/src/seam-ref.mjs

@@ -0,0 +1,33 @@
+import { SEAM_REF_PREFIX, git } from './seam-commit-shared.mjs';
+
+/** 変換の成果を指すref。branch名前空間へ置かないので、通常のbranch一覧には現れない。 */
+export function seamRefFor(candidateId) {
+  return `${SEAM_REF_PREFIX}/${candidateId}`;
+}
+
+/**
+ * 確定済みseam refを列挙する（ADR 0142 / ADR 0141 OQ1）。
+ *
+ * **自動では消さない。** このrefが指すのは「五条件を通って受理された変換の実体」であり、
+ * どの版がどの競合をどう解いたかを後から辿れる唯一の資源である。runが閉じたら消す設計も
+ * 検討したが、それは証跡を寿命付きにするということで、記録を所有するという製品の役目と
+ * 衝突する。消すかどうかは所有者の裁定に委ね、道具は「何が在るか」を見せる側だけを持つ。
+ *
+ * @returns {Promise<Array<{ref: string, candidate_id: string, commit_sha: string}>>}
+ */
+export async function listSeamRefs({ repoRoot } = {}) {
+  let stdout;
+  try {
+    stdout = await git(['for-each-ref', '--format=%(refname) %(objectname)', SEAM_REF_PREFIX], repoRoot);
+  } catch {
+    return [];
+  }
+  return stdout.split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      const [ref, commitSha] = line.split(' ');
+      return { ref, candidate_id: ref.slice(`${SEAM_REF_PREFIX}/`.length), commit_sha: commitSha };
+    })
+    .sort((left, right) => (left.ref < right.ref ? -1 : left.ref > right.ref ? 1 : 0));
+}

package/src/seam-rewrite.mjs

@@ -85,6 +85,13 @@ 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);
+}
+
 function relativeSpecifier(fromPath, toPath) {
   const fromDir = fromPath.slice(0, fromPath.lastIndexOf('/') + 1);
   return toPath.startsWith(fromDir) ? `./${toPath.slice(fromDir.length)}` : `./${toPath}`;
@@ -138,10 +145,17 @@ export function planSeamRewrite({ sourceText, candidate, symbolExtents } = {}) {
 
   const bodyByPath = new Map();
   const removal = new Set();
+  // 原pathでexportされていたsymbolは、移した先から残余面が再exportする。
+  // しないと原pathをimportしている全fileが壊れ、外部挙動同等性が原理的に満たせない。
+  const reExportByPath = new Map();
   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));
+    if (wasExported(raw)) {
+      if (!reExportByPath.has(block.path)) reExportByPath.set(block.path, []);
+      reExportByPath.get(block.path).push(block.symbol);
+    }
     for (let line = block.start; line <= block.end; line += 1) removal.add(line);
   }
 
@@ -175,7 +189,11 @@ export function planSeamRewrite({ sourceText, candidate, symbolExtents } = {}) {
   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`
+  const reExports = [...reExportByPath.entries()]
+    .sort(([left], [right]) => compareText(left, right))
+    .map(([targetPath, names]) => `export { ${[...names].sort(compareText).join(', ')} }`
+      + ` from '${relativeSpecifier(residual.path, targetPath)}';`);
+  files[residual.path] = `${[...keptHeader, ...residualCross, ...reExports].join('\n')}\n${residualBody}\n`
     .replace(/^\n+/u, '');
 
   return { files, reasons: [] };

package/src/todo-cli.mjs

@@ -276,7 +276,7 @@ async function readEvidenceInput(repoRoot, inputRef) {
   });
 }
 
-async function readJsonInput(repoRoot, inputRef, { validate, invalidCode }) {
+async function readJsonInput(repoRoot, inputRef, { validate, invalidCode, expected = null }) {
   if (!isTodoRef(inputRef)) {
     throw new TodoStoreError('INPUT_UNREADABLE', 'input_path_outside_repo', undefined, { input_ref: inputRef });
   }
@@ -321,7 +321,10 @@ async function readJsonInput(repoRoot, inputRef, { validate, invalidCode }) {
     throw new TodoStoreError('INVALID_JSON', 'json_parse_failed');
   }
   if (!validate(descriptor)) {
-    throw new TodoStoreError(invalidCode, 'schema_invalid');
+    // 「schema_invalid」だけを返すと、呼び出したAIは何をどう直せばよいか分からない。
+    // 期待する形を渡されている入口は、それをそのまま返す（ADR 0130の案内規律）。
+    throw new TodoStoreError(invalidCode, 'schema_invalid', undefined,
+      expected === null ? undefined : { expected });
   }
   return descriptor;
 }
@@ -1006,6 +1009,11 @@ async function readSeamPathNames(repoRoot, inputRef) {
       && Object.entries(candidate.names)
         .every(([key, target]) => isTodoIdentifier(key) && isTodoRef(target)),
     invalidCode: 'SEAM_PATH_NAMES_INVALID',
+    expected: {
+      schema: 'lattice.seam_path_names.v1',
+      shape: '{ "schema": "lattice.seam_path_names.v1", "names": { "<task_id>": "<repo相対path>" } }',
+      note: '所有面はtask_idごとに、共有面は"shared"というkeyで名前を与える',
+    },
   });
   return value.names;
 }