@quolu/lattice 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",
@@ -60,7 +60,8 @@
     "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 verify:todo-store",
+    "verify:todo-store": "node bin/lattice.mjs todo verify --json",
+    "check:cli-surface": "node scripts/verify-cli-surface.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/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 };
+}