@quolu/lattice 0.57.3 → 0.58.0

package/src/todo-store.mjs

@@ -28,6 +28,18 @@ import {
   validateTodoWitnessSet,
 } from './todo-independence-contracts.mjs';
 import { validateSeamProposal } from './seam-proposal-contracts.mjs';
+import {
+  digestTodoStructureRealizationHeads,
+  explainTodoStructureSet,
+  explainTodoStructureRealization,
+  validateTodoStructureBinding,
+  validateTodoStructureCompileArtifact,
+  validateTodoStructureSet,
+} from './todo-structure-contracts.mjs';
+import {
+  bindTodoStructureRealizationCommits,
+  collectTodoStructureGitProvenance,
+} from './todo-structure-git-adapter.mjs';
 import { sha256Bytes, verifyLinearHashChain } from './hash-chain.mjs';
 import { gitCatFileBatch, gitSync } from './git-process.mjs';
 import {
@@ -1392,17 +1404,11 @@ export async function readTodoStoreStable(options = {}) {
   if (!Number.isSafeInteger(maximumAttempts) || maximumAttempts < 1 || maximumAttempts > 16) {
     throw new TypeError('maximumAttempts must be 1..16');
   }
-  // `manifest_journal_head_mismatch`/`manifest_plan_binding_mismatch` are treated as a
-  // transient in-flight write and retried. That is correct while a concurrent writer is
-  // mid-commit, but a crashed writer can leave the SAME mismatch permanently — retrying
-  // forever against a manifest that never changes just burns attempts and then reports
-  // a content-free STORE_BUSY, hiding the real STORE_INCONSISTENT reason the caller needs
-  // to actually recover (2026-08-10 P0: a crashed `todo start` left exactly this behind).
-  // Track the manifest digest seen at the START of the previous attempt: if it is
-  // unchanged going into this attempt too, no writer completed anything in between, so
-  // the "transient" classification no longer has evidence behind it — surface the real
-  // error instead of exhausting the budget on a window that was never closing.
-  let previousAttemptManifestDigest = null;
+  // `manifest_journal_head_mismatch`/`manifest_plan_binding_mismatch`は、manifestを最後に
+  // publishする並行writerの一時窓でも、crash後に残った恒久的な千切れでも同じ形に見える。
+  // 同じdigestを2回観測しただけでは両者を判別できないため、この2 reasonだけはattempt
+  // 上限まで待つ。上限内に閉じれば正常storeを返し、閉じなければ最後のtyped errorを返す。
+  // これにより一時窓を早計に破損扱いせず、恒久破損もSTORE_BUSYへ丸めない。
   let lastError = null;
   for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
     const before = await readArtifact(repoRoot, MANIFEST_REF, {
@@ -1423,12 +1429,10 @@ export async function readTodoStoreStable(options = {}) {
       const transientWriteWindow = error.code === 'STORE_INCONSISTENT'
         && ['manifest_journal_head_mismatch', 'manifest_plan_binding_mismatch']
           .includes(error.detail.reason);
-      const stableAcrossAttempts = previousAttemptManifestDigest === before.manifest_digest;
       if (before.manifest_digest === after.manifest_digest
-        && (!transientWriteWindow || stableAcrossAttempts)) throw error;
+        && !transientWriteWindow) throw error;
       lastError = error;
     }
-    previousAttemptManifestDigest = before.manifest_digest;
     if (attempt < maximumAttempts) {
       await new Promise((resolve) => setTimeout(resolve, Math.min(16, 2 ** attempt)));
     }
@@ -1617,6 +1621,98 @@ function resolveCanonicalTaskId(plan, requestedTaskId) {
   return matches[0].task_id;
 }
 
+async function enforceTodoStructureLifecycleGate(repoRoot, member, eventInput) {
+  const binding = await readTodoStructureBinding({
+    repoRoot, planKey: member.plan.plan_key, planVersion: member.plan.plan_version,
+  });
+  if (binding === null) return;
+  const source = await readTodoStructureSource({ repoRoot, planKey: member.plan.plan_key });
+  if (source === null || source.structure_set_digest !== binding.structure_set_digest) {
+    fail('STRUCTURE_LIFECYCLE_GATE_FAILED', 'enabled_structure_source_unreadable');
+  }
+  if (eventInput.kind === 'done') {
+    const task = source.tasks.find(({ task_id: id }) => id === eventInput.task_id);
+    if (task?.applicability !== 'graph') return;
+    const chain = await readTodoStructureRealizationChain({
+      repoRoot, structureSet: source, taskId: eventInput.task_id,
+    });
+    const latest = chain.at(-1);
+    if (latest === undefined) {
+      fail('STRUCTURE_REALIZATION_REQUIRED', 'fresh_realization_missing', {
+        plan_key: member.plan.plan_key, task_id: eventInput.task_id,
+        next_action: `lattice todo structure realize --plan ${member.plan.plan_key} --task ${eventInput.task_id} --input <realization.json>`,
+      });
+    }
+    let currentHead;
+    try {
+      currentHead = gitSync(['rev-parse', '--verify', 'HEAD^{commit}'], {
+        cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      fail('STRUCTURE_GIT_HEAD_UNAVAILABLE', 'current_head_unavailable');
+    }
+    if (latest.head_sha !== currentHead) {
+      fail('STRUCTURE_REALIZATION_REQUIRED', 'realization_head_stale', {
+        plan_key: member.plan.plan_key, task_id: eventInput.task_id,
+        realization_head_sha: latest.head_sha, current_head_sha: currentHead,
+        next_action: `lattice todo structure realize --plan ${member.plan.plan_key} --task ${eventInput.task_id} --input <realization.json>`,
+      });
+    }
+  }
+  if (!['phase_accept', 'phase_close_unaudited'].includes(eventInput.kind)
+    || member.tasks.some(({ status }) => status !== 'done')) return;
+  const finalization = await readTodoStructureFinalization({
+    repoRoot, planKey: member.plan.plan_key, planVersion: member.plan.plan_version,
+  });
+  if (finalization === null) {
+    fail('STRUCTURE_FINALIZATION_REQUIRED', 'fresh_consistent_finalization_missing', {
+      plan_key: member.plan.plan_key,
+      next_action: `lattice todo structure finalize --plan ${member.plan.plan_key} --json`,
+    });
+  }
+  let currentHead;
+  try {
+    currentHead = gitSync(['rev-parse', '--verify', 'HEAD^{commit}'], {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    fail('STRUCTURE_GIT_HEAD_UNAVAILABLE', 'current_head_unavailable');
+  }
+  const realizationHeads = [];
+  for (const task of source.tasks.filter(({ applicability }) => applicability === 'graph')) {
+    const chain = await readTodoStructureRealizationChain({
+      repoRoot, structureSet: source, taskId: task.task_id,
+    });
+    const head = chain.at(-1);
+    if (head !== undefined) realizationHeads.push({
+      task_id: task.task_id, sequence: head.sequence,
+      realization_digest: head.realization_digest,
+    });
+  }
+  const staleReasons = [];
+  if (finalization.project_id !== member.plan.project_id) staleReasons.push('project_id');
+  if (finalization.plan_key !== member.plan.plan_key) staleReasons.push('plan_key');
+  if (finalization.plan_version !== member.plan.plan_version) staleReasons.push('plan_version');
+  if (finalization.topology_digest !== member.plan.topology_digest) {
+    staleReasons.push('topology_digest');
+  }
+  if (finalization.structure_set_digest !== source.structure_set_digest) {
+    staleReasons.push('structure_set_digest');
+  }
+  if (finalization.current_head_sha !== currentHead) staleReasons.push('current_head_sha');
+  if (finalization.realization_head_digest
+    !== digestTodoStructureRealizationHeads(realizationHeads)) {
+    staleReasons.push('realization_head_digest');
+  }
+  if (finalization.overlay.verdict !== 'consistent') staleReasons.push('verdict');
+  if (staleReasons.length > 0) {
+    fail('STRUCTURE_FINALIZATION_REQUIRED', 'finalization_stale', {
+      plan_key: member.plan.plan_key, stale_reasons: staleReasons.sort(),
+      next_action: `lattice todo structure finalize --plan ${member.plan.plan_key} --json`,
+    });
+  }
+}
+
 export async function appendTodoEvent(options = {}) {
   requireWriter(options.writer, 'g5-authoring');
   const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
@@ -1641,6 +1737,7 @@ export async function appendTodoEvent(options = {}) {
       task_id: resolveCanonicalTaskId(member.plan, options.event.task_id),
       recorded_at: options.event.recorded_at ?? new Date().toISOString(),
     }, member);
+    await enforceTodoStructureLifecycleGate(repoRoot, member, input);
     const event = nextEvent(input, member);
     if ((event.kind === 'start' && event.payload.start_mode === 'historical_import')
       || (event.kind === 'done' && event.payload.done_mode === 'historical_import')) {
@@ -4403,3 +4500,500 @@ export async function writeTodoWitnessSet(options = {}) {
   await atomicWrite(path.resolve(repoRoot, ref), canonicalLine(witnessSet));
   return { ref, witnessSet };
 }
+
+const STRUCTURE_SOURCE_BYTES = 8_388_608;
+const STRUCTURE_COMPILE_ARTIFACT_BYTES = 67_108_864;
+const STRUCTURE_REALIZATION_CHAIN_BYTES = 8_388_608;
+
+/** AI-authored planned sourceの正規ref。derived artifact／bindingとは所有を分ける。 */
+export function todoStructureSourceRef(planKey) {
+  if (!isTodoIdentifier(planKey)) throw new TypeError('planKey must be a todo identifier');
+  return `${STORE_ROOT_REF}/structure/${planKey}.json`;
+}
+
+/** plan versionごとのimmutable activation binding ref。sourceだけでは有効化しない。 */
+export function todoStructureBindingRef(planKey, planVersion) {
+  if (!isTodoIdentifier(planKey) || !isTodoIdentifier(planVersion)) {
+    throw new TypeError('planKey and planVersion must be todo identifiers');
+  }
+  return `${STORE_ROOT_REF}/plans/${planKey}/${planVersion}/structure/binding.json`;
+}
+
+/** plan versionへ並置するderived compile artifactの正規ref。 */
+export function todoStructureCompileArtifactRef(planKey, planVersion) {
+  if (!isTodoIdentifier(planKey) || !isTodoIdentifier(planVersion)) {
+    throw new TypeError('planKey and planVersion must be todo identifiers');
+  }
+  return `${STORE_ROOT_REF}/plans/${planKey}/${planVersion}/structure/compile.json`;
+}
+
+/** plan終端で再compileした最終構造artifactの正規ref。 */
+export function todoStructureFinalizationRef(planKey, planVersion) {
+  if (!isTodoIdentifier(planKey) || !isTodoIdentifier(planVersion)) {
+    throw new TypeError('planKey and planVersion must be todo identifiers');
+  }
+  return `${STORE_ROOT_REF}/plans/${planKey}/${planVersion}/structure/finalization.json`;
+}
+
+/** task単位append-only realization chainの正規ref。 */
+export function todoStructureRealizationRef(planKey, planVersion, taskId) {
+  if (![planKey, planVersion, taskId].every(isTodoIdentifier)) {
+    throw new TypeError('planKey, planVersion and taskId must be todo identifiers');
+  }
+  return `${STORE_ROOT_REF}/plans/${planKey}/${planVersion}/structure/realizations/${taskId}.jsonl`;
+}
+
+/** sourceが無ければnull、壊れていればtyped failure。missingをinvalidへ丸めない。 */
+export async function readTodoStructureSource(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  return readArtifact(repoRoot, todoStructureSourceRef(options.planKey), {
+    code: 'INVALID_TODO_STRUCTURE_SET', maxBytes: STRUCTURE_SOURCE_BYTES,
+    validate: validateTodoStructureSet, missing: true,
+  });
+}
+
+/**
+ * dry-run済みplanned sourceをcanonical JSON+LFで保存する唯一のwriter。
+ * bindingは発行しない——authoritative compileが成功するまではdraftであり、完了gateを有効化しない。
+ */
+export async function writeTodoStructureSource(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const { structureSet } = options;
+  const explained = explainTodoStructureSet(structureSet);
+  if (!explained.valid) {
+    fail('INVALID_TODO_STRUCTURE_SET', explained.reason, { path: explained.path });
+  }
+  return withLock(repoRoot, async () => {
+    const store = await readTodoStore({ repoRoot, forWrite: true, now: options.now });
+    if (store.project_id !== structureSet.project_id) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'project_id_mismatch', {
+        expected: store.project_id, actual: structureSet.project_id,
+      });
+    }
+    const member = activeMember(store, structureSet.plan_key);
+    if (member.plan.plan_version !== structureSet.plan_version) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'plan_version_mismatch', {
+        expected: member.plan.plan_version, actual: structureSet.plan_version,
+      });
+    }
+    if (member.plan.topology_digest !== structureSet.topology_digest) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'topology_digest_mismatch', {
+        expected: member.plan.topology_digest, actual: structureSet.topology_digest,
+      });
+    }
+    const expectedTaskIds = member.tasks.filter(({ status }) => status !== 'done')
+      .map(({ task_id: taskId }) => taskId);
+    const coverage = explainTodoStructureSet(structureSet, { expectedTaskIds });
+    if (!coverage.valid) {
+      fail('STRUCTURE_BINDING_MISMATCH', coverage.reason, {
+        path: coverage.path, ...(coverage.detail ?? {}),
+      });
+    }
+    const bindingRef = todoStructureBindingRef(structureSet.plan_key, structureSet.plan_version);
+    if (await exactFileOrNull(path.resolve(repoRoot, bindingRef)) !== null) {
+      fail('STRUCTURE_ALREADY_ENABLED', 'immutable_binding_exists', {
+        binding_ref: bindingRef,
+        next_action: 'revise_the_plan_or_run_authoritative_compile_with_the_existing_source',
+      });
+    }
+    const ref = todoStructureSourceRef(structureSet.plan_key);
+    try {
+      await ensureSafeStoreDirectory(repoRoot, path.dirname(path.resolve(repoRoot, ref)));
+    } catch (error) {
+      if (error instanceof TodoStoreError && error.code === 'REVISION_CONFLICT') {
+        fail('INVALID_TODO_STRUCTURE_SET', 'structure_source_directory_unsafe', { source_ref: ref });
+      }
+      throw error;
+    }
+    await atomicWrite(path.resolve(repoRoot, ref), canonicalLine(structureSet));
+    return { ref, structureSet };
+  });
+}
+
+/** bindingが無ければnull、壊れていればtyped failure。 */
+export async function readTodoStructureBinding(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  return readArtifact(repoRoot, todoStructureBindingRef(options.planKey, options.planVersion), {
+    code: 'INVALID_TODO_STRUCTURE_BINDING', maxBytes: TODO_LIMITS.snapshotBytes,
+    validate: validateTodoStructureBinding, missing: true,
+  });
+}
+
+/** derived artifactが無ければnull、壊れていればtyped failure。 */
+export async function readTodoStructureCompileArtifact(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  return readArtifact(repoRoot,
+    todoStructureCompileArtifactRef(options.planKey, options.planVersion), {
+      code: 'INVALID_TODO_STRUCTURE_COMPILE_ARTIFACT',
+      maxBytes: STRUCTURE_COMPILE_ARTIFACT_BYTES,
+      validate: validateTodoStructureCompileArtifact,
+      missing: true,
+    });
+}
+
+/** finalizationが無ければnull、壊れていればtyped failure。 */
+export async function readTodoStructureFinalization(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  return readArtifact(repoRoot, todoStructureFinalizationRef(options.planKey, options.planVersion), {
+    code: 'INVALID_TODO_STRUCTURE_FINALIZATION',
+    maxBytes: STRUCTURE_COMPILE_ARTIFACT_BYTES,
+    validate: validateTodoStructureCompileArtifact,
+    missing: true,
+  });
+}
+
+/**
+ * active planとplanned sourceへ束縛したderived artifactを書く。
+ * activation前は再生成可能artifactとして置換できるが、binding発行後は固定する。
+ */
+export async function writeTodoStructureCompileArtifact(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const { artifact } = options;
+  if (!validateTodoStructureCompileArtifact(artifact)) {
+    fail('INVALID_TODO_STRUCTURE_COMPILE_ARTIFACT', 'compile_artifact_invalid');
+  }
+  return withLock(repoRoot, async () => {
+    const store = await readTodoStore({ repoRoot, forWrite: true, now: options.now });
+    if (store.project_id !== artifact.project_id) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'project_id_mismatch');
+    }
+    const member = activeMember(store, artifact.plan_key);
+    if (member.plan.plan_version !== artifact.plan_version) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'plan_version_mismatch');
+    }
+    if (member.plan.topology_digest !== artifact.topology_digest) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'topology_digest_mismatch');
+    }
+    const source = await readTodoStructureSource({ repoRoot, planKey: artifact.plan_key });
+    if (source === null) fail('STRUCTURE_SOURCE_MISSING', 'planned_source_missing');
+    if (source.structure_set_digest !== artifact.structure_set_digest
+      || source.baseline_sha !== artifact.baseline_sha
+      || source.plan_version !== artifact.plan_version
+      || source.topology_digest !== artifact.topology_digest) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'planned_source_mismatch');
+    }
+    let currentHead;
+    try {
+      currentHead = gitSync(['rev-parse', '--verify', 'HEAD^{commit}'], {
+        cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      fail('STRUCTURE_GIT_HEAD_UNAVAILABLE', 'current_head_unavailable');
+    }
+    if (currentHead !== artifact.current_head_sha) {
+      fail('STRUCTURE_COMPILE_STALE', 'current_head_changed_before_store');
+    }
+    const realizationHeads = [];
+    for (const task of source.tasks.filter(({ applicability }) => applicability === 'graph')) {
+      const chain = await readTodoStructureRealizationChain({
+        repoRoot, structureSet: source, taskId: task.task_id,
+      });
+      const head = chain.at(-1);
+      if (head !== undefined) realizationHeads.push({
+        task_id: task.task_id, sequence: head.sequence,
+        realization_digest: head.realization_digest,
+      });
+    }
+    if (artifact.realization_head_digest
+      !== digestTodoStructureRealizationHeads(realizationHeads)) {
+      fail('STRUCTURE_COMPILE_STALE', 'realization_changed_before_store');
+    }
+    const ref = todoStructureCompileArtifactRef(artifact.plan_key, artifact.plan_version);
+    const bindingRef = todoStructureBindingRef(artifact.plan_key, artifact.plan_version);
+    if (await exactFileOrNull(path.resolve(repoRoot, bindingRef)) !== null) {
+      fail('STRUCTURE_ALREADY_ENABLED', 'immutable_binding_exists', {
+        binding_ref: bindingRef,
+      });
+    }
+    await ensureSafeStoreDirectory(repoRoot, path.dirname(path.resolve(repoRoot, ref)));
+    await atomicWrite(path.resolve(repoRoot, ref), canonicalLine(artifact));
+    return { ref, artifact };
+  });
+}
+
+/** compile artifactをexactに指すimmutable activation bindingを書く。 */
+export async function writeTodoStructureBinding(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const { binding } = options;
+  if (!validateTodoStructureBinding(binding)) {
+    fail('INVALID_TODO_STRUCTURE_BINDING', 'structure_binding_invalid');
+  }
+  return withLock(repoRoot, async () => {
+    const store = await readTodoStore({ repoRoot, forWrite: true, now: options.now });
+    if (store.project_id !== binding.project_id) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'project_id_mismatch');
+    }
+    const member = activeMember(store, binding.plan_key);
+    if (member.plan.plan_version !== binding.plan_version
+      || member.plan.topology_digest !== binding.topology_digest) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'active_plan_mismatch');
+    }
+    const source = await readTodoStructureSource({ repoRoot, planKey: binding.plan_key });
+    const artifact = await readTodoStructureCompileArtifact({
+      repoRoot, planKey: binding.plan_key, planVersion: binding.plan_version,
+    });
+    if (source === null || artifact === null
+      || source.structure_set_digest !== binding.structure_set_digest
+      || source.baseline_sha !== binding.baseline_sha
+      || artifact.artifact_digest !== binding.compile_artifact_digest
+      || artifact.current_head_sha !== binding.compiled_head_sha) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'source_or_compile_artifact_mismatch');
+    }
+    let currentHead;
+    try {
+      currentHead = gitSync(['rev-parse', '--verify', 'HEAD^{commit}'], {
+        cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      fail('STRUCTURE_GIT_HEAD_UNAVAILABLE', 'current_head_unavailable');
+    }
+    if (currentHead !== artifact.current_head_sha) {
+      fail('STRUCTURE_COMPILE_STALE', 'current_head_changed_before_activation');
+    }
+    const realizationHeads = [];
+    for (const task of source.tasks.filter(({ applicability }) => applicability === 'graph')) {
+      const chain = await readTodoStructureRealizationChain({
+        repoRoot, structureSet: source, taskId: task.task_id,
+      });
+      const head = chain.at(-1);
+      if (head !== undefined) realizationHeads.push({
+        task_id: task.task_id, sequence: head.sequence,
+        realization_digest: head.realization_digest,
+      });
+    }
+    if (artifact.realization_head_digest
+      !== digestTodoStructureRealizationHeads(realizationHeads)) {
+      fail('STRUCTURE_COMPILE_STALE', 'realization_changed_before_activation');
+    }
+    const ref = todoStructureBindingRef(binding.plan_key, binding.plan_version);
+    if (await exactFileOrNull(path.resolve(repoRoot, ref)) !== null) {
+      fail('STRUCTURE_ALREADY_ENABLED', 'immutable_binding_exists', { binding_ref: ref });
+    }
+    await ensureSafeStoreDirectory(repoRoot, path.dirname(path.resolve(repoRoot, ref)));
+    await atomicWrite(path.resolve(repoRoot, ref), canonicalLine(binding));
+    return { ref, binding };
+  });
+}
+
+/** 全task done後のfresh consistent artifactだけをfinalization refへ固定する。 */
+export async function writeTodoStructureFinalization(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const { artifact } = options;
+  if (!validateTodoStructureCompileArtifact(artifact) || artifact.overlay.verdict !== 'consistent') {
+    fail('INVALID_TODO_STRUCTURE_FINALIZATION', 'finalization_not_consistent');
+  }
+  return withLock(repoRoot, async () => {
+    const store = await readTodoStore({ repoRoot, forWrite: true, now: options.now });
+    const member = activeMember(store, artifact.plan_key);
+    if (store.project_id !== artifact.project_id || member.plan.project_id !== artifact.project_id) {
+      fail('STRUCTURE_BINDING_MISMATCH', 'project_id_mismatch');
+    }
+    if (member.plan.plan_version !== artifact.plan_version
+      || member.plan.topology_digest !== artifact.topology_digest
+      || member.tasks.some(({ status }) => status !== 'done')) {
+      fail('STRUCTURE_FINALIZATION_UNAVAILABLE', 'plan_not_fully_done');
+    }
+    const source = await readTodoStructureSource({ repoRoot, planKey: artifact.plan_key });
+    const binding = await readTodoStructureBinding({
+      repoRoot, planKey: artifact.plan_key, planVersion: artifact.plan_version,
+    });
+    if (source === null || binding === null
+      || source.structure_set_digest !== artifact.structure_set_digest
+      || binding.structure_set_digest !== artifact.structure_set_digest) {
+      fail('STRUCTURE_FINALIZATION_UNAVAILABLE', 'structure_not_enabled_or_stale');
+    }
+    const heads = [];
+    for (const task of source.tasks.filter(({ applicability }) => applicability === 'graph')) {
+      const chain = await readTodoStructureRealizationChain({
+        repoRoot, structureSet: source, taskId: task.task_id,
+      });
+      const head = chain.at(-1);
+      if (head === undefined) {
+        fail('STRUCTURE_FINALIZATION_UNAVAILABLE', 'realization_missing', { task_id: task.task_id });
+      }
+      heads.push({
+        task_id: task.task_id, sequence: head.sequence,
+        realization_digest: head.realization_digest,
+      });
+    }
+    if (artifact.realization_head_digest !== digestTodoStructureRealizationHeads(heads)) {
+      fail('STRUCTURE_FINALIZATION_STALE', 'realization_head_changed');
+    }
+    let currentHead;
+    try {
+      currentHead = gitSync(['rev-parse', '--verify', 'HEAD^{commit}'], {
+        cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      fail('STRUCTURE_GIT_HEAD_UNAVAILABLE', 'current_head_unavailable');
+    }
+    if (artifact.current_head_sha !== currentHead) {
+      fail('STRUCTURE_FINALIZATION_STALE', 'current_head_changed');
+    }
+    const ref = todoStructureFinalizationRef(artifact.plan_key, artifact.plan_version);
+    await ensureSafeStoreDirectory(repoRoot, path.dirname(path.resolve(repoRoot, ref)));
+    await atomicWrite(path.resolve(repoRoot, ref), canonicalLine(artifact));
+    return { ref, artifact };
+  });
+}
+
+function parseTodoStructureRealizationChain(bytes, { structureSet, taskId }) {
+  if (bytes.length === 0 || bytes.length > STRUCTURE_REALIZATION_CHAIN_BYTES) {
+    fail('INVALID_TODO_STRUCTURE_REALIZATION_CHAIN',
+      bytes.length > STRUCTURE_REALIZATION_CHAIN_BYTES ? 'size_limit_exceeded' : 'chain_empty');
+  }
+  const text = decodeUtf8(bytes, 'INVALID_TODO_STRUCTURE_REALIZATION_CHAIN', 'invalid_utf8');
+  if (!text.endsWith('\n') || text.includes('\r') || text.startsWith('\uFEFF')) {
+    fail('INVALID_TODO_STRUCTURE_REALIZATION_CHAIN', 'chain_byte_contract');
+  }
+  const records = []; let previous = null; const priorDigests = new Set();
+  for (const [index, line] of text.slice(0, -1).split('\n').entries()) {
+    if (line.length === 0) fail('INVALID_TODO_STRUCTURE_REALIZATION_CHAIN', 'empty_record');
+    let value;
+    try { value = JSON.parse(line); } catch {
+      fail('INVALID_TODO_STRUCTURE_REALIZATION_CHAIN', 'record_json_invalid', { index });
+    }
+    if (line !== canonicalizeTodoArtifact(value)) {
+      fail('INVALID_TODO_STRUCTURE_REALIZATION_CHAIN', 'record_non_canonical', { index });
+    }
+    const explained = explainTodoStructureRealization(value, {
+      structureSet, previous, priorDigests,
+    });
+    if (!explained.valid || value.task_id !== taskId) {
+      fail('INVALID_TODO_STRUCTURE_REALIZATION_CHAIN',
+        explained.valid ? 'task_id_mismatch' : explained.reason,
+        { index, path: explained.path ?? '/task_id' });
+    }
+    records.push(value); previous = value; priorDigests.add(value.realization_digest);
+  }
+  return records;
+}
+
+/** chain未作成は[]、存在するchainの破損はtyped failure。 */
+export async function readTodoStructureRealizationChain(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  if (!validateTodoStructureSet(options.structureSet)) {
+    throw new TypeError('structureSet must be valid');
+  }
+  const ref = todoStructureRealizationRef(
+    options.structureSet.plan_key, options.structureSet.plan_version, options.taskId,
+  );
+  const state = await pathState(repoRoot, ref, 'INVALID_TODO_STRUCTURE_REALIZATION_CHAIN', {
+    missing: true,
+  });
+  if (state === null) return [];
+  return parseTodoStructureRealizationChain(await readFile(state.absolute), {
+    structureSet: options.structureSet, taskId: options.taskId,
+  });
+}
+
+/**
+ * active binding配下のtask realizationをappend-onlyで追記する。
+ * Git objectと他task chainを追記前に照合し、拒否時はchain bytesを変えない。
+ */
+export async function appendTodoStructureRealization(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const { realization } = options;
+  const initial = explainTodoStructureRealization(realization);
+  if (!initial.valid) {
+    fail('INVALID_TODO_STRUCTURE_REALIZATION', initial.reason, { path: initial.path });
+  }
+  return withLock(repoRoot, async () => {
+    const store = await readTodoStore({ repoRoot, forWrite: true, now: options.now });
+    const member = activeMember(store, realization.plan_key);
+    if (store.project_id !== realization.project_id
+      || member.plan.plan_version !== realization.plan_version) {
+      fail('STRUCTURE_REALIZATION_BINDING_MISMATCH', 'active_plan_identity_mismatch');
+    }
+    const structureSet = await readTodoStructureSource({
+      repoRoot, planKey: realization.plan_key,
+    });
+    const binding = await readTodoStructureBinding({
+      repoRoot, planKey: realization.plan_key, planVersion: realization.plan_version,
+    });
+    if (structureSet === null || binding === null
+      || structureSet.structure_set_digest !== binding.structure_set_digest
+      || realization.structure_set_digest !== binding.structure_set_digest) {
+      fail('STRUCTURE_REALIZATION_BINDING_MISMATCH', 'structure_not_enabled_or_stale');
+    }
+    const task = structureSet.tasks.find(({ task_id: id }) => id === realization.task_id);
+    if (task?.applicability !== 'graph') {
+      fail('STRUCTURE_REALIZATION_BINDING_MISMATCH', 'task_not_graph_applicable');
+    }
+    let currentHead;
+    try {
+      currentHead = gitSync(['rev-parse', '--verify', 'HEAD^{commit}'], {
+        cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      fail('STRUCTURE_GIT_HEAD_UNAVAILABLE', 'current_head_unavailable');
+    }
+    if (realization.head_sha !== currentHead) {
+      fail('STRUCTURE_REALIZATION_STALE', 'realization_head_mismatch', {
+        expected: currentHead, actual: realization.head_sha,
+      });
+    }
+    const chain = await readTodoStructureRealizationChain({
+      repoRoot, structureSet, taskId: realization.task_id,
+    });
+    const priorDigests = new Set(chain.map(({ realization_digest: digest }) => digest));
+    const explained = explainTodoStructureRealization(realization, {
+      structureSet, previous: chain.at(-1) ?? null, priorDigests,
+    });
+    if (!explained.valid) {
+      fail('INVALID_TODO_STRUCTURE_REALIZATION_CHAIN', explained.reason, {
+        path: explained.path, task_id: realization.task_id,
+      });
+    }
+
+    for (const otherTask of structureSet.tasks.filter(({ applicability, task_id: taskId }) => (
+      applicability === 'graph' && taskId !== realization.task_id
+    ))) {
+      const otherChain = await readTodoStructureRealizationChain({
+        repoRoot, structureSet, taskId: otherTask.task_id,
+      });
+      const claimed = new Set(otherChain.flatMap(({ commit_oids: commitOids }) => commitOids));
+      const reused = realization.commit_oids.filter((commitOid) => claimed.has(commitOid));
+      if (reused.length > 0) {
+        fail('STRUCTURE_REALIZATION_COMMIT_CLAIMED', 'commit_claimed_by_other_task', {
+          task_id: realization.task_id, other_task_id: otherTask.task_id,
+          commit_oids: reused,
+        });
+      }
+    }
+
+    const provenance = collectTodoStructureGitProvenance({
+      repoRoot, structureSet, requireClean: false,
+    });
+    bindTodoStructureRealizationCommits({ provenance, realizations: [realization] });
+    const declared = new Set(realization.commit_oids);
+    const changedPaths = new Set(provenance.changesets
+      .filter(({ commit_oid: commitOid }) => declared.has(commitOid))
+      .flatMap(({ changes }) => changes.flatMap(({ path: changedPath, previous_path: previousPath }) => (
+        previousPath === null ? [changedPath] : [changedPath, previousPath]
+      ))));
+    const mutatingAnchors = realization.realized.code_anchors
+      .filter(({ effect }) => ['create', 'modify', 'delete'].includes(effect));
+    const unboundAnchors = mutatingAnchors.filter(({ path: anchorPath }) => !changedPaths.has(anchorPath));
+    if (mutatingAnchors.length === 0 || unboundAnchors.length > 0) {
+      fail('STRUCTURE_REALIZATION_ANCHOR_UNBOUND',
+        mutatingAnchors.length === 0 ? 'mutating_code_anchor_missing' : 'commit_does_not_touch_anchor', {
+          task_id: realization.task_id,
+          anchor_ids: unboundAnchors.map(({ anchor_id: anchorId }) => anchorId).sort(),
+          changed_paths: [...changedPaths].sort(),
+        });
+    }
+
+    const ref = todoStructureRealizationRef(
+      structureSet.plan_key, structureSet.plan_version, realization.task_id,
+    );
+    const absolute = path.resolve(repoRoot, ref);
+    await ensureSafeStoreDirectory(repoRoot, path.dirname(absolute));
+    const before = await exactFileOrNull(absolute);
+    await atomicWrite(absolute, Buffer.concat([before ?? Buffer.alloc(0), canonicalLine(realization)]));
+    return {
+      ref, realization, history_length: chain.length + 1,
+      previous_realization_digest: chain.at(-1)?.realization_digest ?? null,
+    };
+  });
+}