@quolu/lattice 0.14.0 → 0.15.0

package/src/todo-independence-contracts.mjs

@@ -14,8 +14,13 @@ import {
 import { TODO_INDEPENDENCE_GUIDANCE_CODES } from './todo-independence-guidance.mjs';
 
 export const TODO_WITNESS_SET_SCHEMA = 'lattice.todo_witness_set.v1';
-export const TODO_INDEPENDENCE_SCHEMA = 'lattice.todo_independence.v2';
+export const TODO_INDEPENDENCE_SCHEMA = 'lattice.todo_independence.v3';
 export const TODO_INDEPENDENCE_PROJECTION_SCHEMA = 'lattice.todo_independence_projection.v2';
+export const TODO_INDEPENDENCE_LEGACY_MARKER_SCHEMA = 'lattice.todo_independence_legacy_marker.v1';
+export const TODO_INDEPENDENCE_LEGACY_SCHEMAS = Object.freeze([
+  'lattice.todo_independence.v1',
+  'lattice.todo_independence.v2',
+]);
 
 /** boundary compileが一度に扱えるToDo数（runtime front-endのMAX_COLLECTIONと同じ閉じ方）。 */
 export const TODO_INDEPENDENCE_TASK_LIMIT = 256;
@@ -53,6 +58,19 @@ function plain(value) {
     && Object.getPrototypeOf(value) === Object.prototype;
 }
 
+/**
+ * 既知の旧independence artifactを、単なるschema文字列だけでなく版をまたいで不変な
+ * identity fieldの型までで識別する。本体構造や自己digestは旧契約validatorの再実装に
+ * なるため、ここでは検査しない。
+ */
+export function isTodoIndependenceLegacyArtifactIdentity(value) {
+  return plain(value) && TODO_INDEPENDENCE_LEGACY_SCHEMAS.includes(value.schema)
+    && isTodoIdentifier(value.project_id) && isTodoIdentifier(value.plan_key)
+    && isTodoIdentifier(value.plan_version) && isTodoDigest(value.topology_digest)
+    && isTodoDigest(value.witness_set_digest) && isTodoDigest(value.result_digest)
+    && isGitSha(value.base_sha);
+}
+
 function boundedList(value, validator, limit = TODO_INDEPENDENCE_LIST_LIMIT) {
   return Array.isArray(value) && value.length <= limit && value.every(validator);
 }
@@ -139,12 +157,39 @@ export function validateTodoWitnessSet(value) {
 }
 
 function conflictEntry(value) {
-  return exactRecord(value, ['task_ids', 'resource_id', 'kind'])
+  return exactRecord(value, ['task_ids', 'resource_id'])
     && Array.isArray(value.task_ids) && value.task_ids.length === 2
     && value.task_ids.every(isTodoIdentifier)
     && compareText(value.task_ids[0], value.task_ids[1]) < 0
-    && boundedText(value.resource_id)
-    && TODO_INDEPENDENCE_CONFLICT_KINDS.includes(value.kind);
+    && boundedText(value.resource_id);
+}
+
+function repoRelativeResourceTarget(value) {
+  if (!boundedText(value) || value.startsWith('/') || value.includes('\\')
+    || /^[A-Za-z]:/u.test(value)) return false;
+  const body = value.endsWith('/') ? value.slice(0, -1) : value;
+  return body.length > 0 && body.split('/')
+    .every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+
+function conflictResourceEntry(value) {
+  if (!exactRecord(value, ['resource_id', 'kind', 'target'])
+    || !boundedText(value.resource_id)
+    || !TODO_INDEPENDENCE_CONFLICT_KINDS.includes(value.kind)) return false;
+  return value.kind === 'path'
+    ? repoRelativeResourceTarget(value.target)
+    : boundedText(value.target);
+}
+
+export function isTodoIndependenceLegacyMarker(value) {
+  return exactRecord(value, [
+    'schema', 'legacy_schema', 'project_id', 'plan_key', 'plan_version',
+    'topology_digest', 'base_sha',
+  ])
+    && value.schema === TODO_INDEPENDENCE_LEGACY_MARKER_SCHEMA
+    && TODO_INDEPENDENCE_LEGACY_SCHEMAS.includes(value.legacy_schema)
+    && isTodoIdentifier(value.project_id) && isTodoIdentifier(value.plan_key)
+    && value.plan_version === null && value.topology_digest === null && value.base_sha === null;
 }
 
 /**
@@ -188,10 +233,10 @@ function wavePlan(value, taskIds) {
 }
 
 /**
- * `lattice.todo_independence.v2`。
+ * `lattice.todo_independence.v3`。
  *
  * conflict／precedence／unknownはnormalized boundary graphから採る（ADR 0127 Decision 4）。
- * conflictはresource kindを併せて持ち、切断可能性の導出を投影側に許す（ADR 0128 Decision 1）。
+ * conflictは`conflict_resources`のresource idを参照し、kindとnormalized targetを一度だけ保持する。
  * `task_boundaries`はtask別の宣言境界で、鮮度のdiff交差判定をartifactだけで閉じるために持つ。
  * `wave_plan`はschedulability compileが`compiled`を返した時だけ持ち、unknownが残る間はnullになる。
  * verdictに現れないペアをverified独立と読めるのは、両taskにunknownが無いときだけである。
@@ -200,7 +245,7 @@ export function validateTodoIndependence(value) {
   try {
     if (!exactRecord(value, [
       'schema', 'project_id', 'plan_key', 'plan_version', 'topology_digest', 'base_sha',
-      'witness_set_digest', 'compiled_at', 'task_ids', 'task_boundaries', 'conflicts',
+      'witness_set_digest', 'compiled_at', 'task_ids', 'task_boundaries', 'conflict_resources', 'conflicts',
       'precedences', 'unknowns', 'wave_plan', 'outcome', 'result_digest',
     ])) return false;
     if (value.schema !== TODO_INDEPENDENCE_SCHEMA) return false;
@@ -221,10 +266,16 @@ export function validateTodoIndependence(value) {
       || !value.task_boundaries.every((entry, index) => entry.task_id === value.task_ids[index])) {
       return false;
     }
+    if (!boundedList(value.conflict_resources, conflictResourceEntry)
+      || !strictlySorted(value.conflict_resources, (entry) => entry.resource_id)) return false;
+    const conflictResourceIds = new Set(value.conflict_resources.map(({ resource_id: id }) => id));
     if (!boundedList(value.conflicts, conflictEntry)
       || !value.conflicts.every((entry) => entry.task_ids.every((taskId) => known.has(taskId)))
+      || !value.conflicts.every((entry) => conflictResourceIds.has(entry.resource_id))
       || !strictlySorted(value.conflicts, (entry) => (
         `${entry.task_ids[0]}\0${entry.task_ids[1]}\0${entry.resource_id}`))) return false;
+    const referencedResourceIds = new Set(value.conflicts.map(({ resource_id: id }) => id));
+    if (referencedResourceIds.size !== value.conflict_resources.length) return false;
     if (!boundedList(value.precedences, precedenceEntry)
       || !value.precedences.every((entry) => known.has(entry.from_task_id) && known.has(entry.to_task_id))
       || !strictlySorted(value.precedences, (entry) => (
@@ -345,7 +396,9 @@ export function validateTodoIndependenceProjection(value) {
     // 記録が無い状態でcompile済みidentityを名乗らない。
     if (value.coverage === 'missing'
       && (value.compiled_base_sha !== null || value.topology_digest !== null)) return false;
-    if (value.coverage !== 'missing' && value.compiled_base_sha === null) return false;
+    if (['verified', 'stale'].includes(value.coverage) && value.compiled_base_sha === null) return false;
+    if (value.coverage === 'superseded' && value.compiled_base_sha === null
+      && (value.plan_version !== null || value.topology_digest !== null)) return false;
     for (const key of ['active_task_ids', 'uncovered_active_task_ids']) {
       if (!Array.isArray(value[key]) || value[key].length > TODO_INDEPENDENCE_TASK_LIMIT
         || !value[key].every(isTodoIdentifier) || !strictlySorted(value[key])) return false;

package/src/todo-independence-guidance.mjs

@@ -12,6 +12,7 @@ export const TODO_INDEPENDENCE_GUIDANCE_CODES = Object.freeze([
   'independence_no_ready_frontier',
   'independence_unrecorded',
   'independence_task_undeclared',
+  'independence_contract_superseded',
   'independence_superseded',
   'independence_stale_for_task',
   'independence_conflict_with_active',
@@ -19,6 +20,13 @@ export const TODO_INDEPENDENCE_GUIDANCE_CODES = Object.freeze([
   'independence_verified',
 ]);
 
+export const SEAM_PROPOSAL_GUIDANCE_CODES = Object.freeze([
+  'seam_proposal_unrecorded',
+  'seam_proposal_superseded',
+  'seam_proposal_stale',
+  'seam_proposal_verified',
+]);
+
 const CATALOG = Object.freeze({
   independence_no_ready_frontier: Object.freeze({
     message: '着手候補が無いため、並列可否を述べる対象が無い。',
@@ -32,6 +40,10 @@ const CATALOG = Object.freeze({
     message: 'この工程はwitness setで宣言されていないため、記録には含まれていない。',
     next_action: 'add_task_to_witness_set_then_compile',
   }),
+  independence_contract_superseded: Object.freeze({
+    message: '記録は旧契約versionで書かれており、現在の並列可否の判定としては読めない。現在の契約での再compileが次の一歩になる。',
+    next_action: 'recompile_independence',
+  }),
   independence_superseded: Object.freeze({
     message: 'planが改訂され、記録は別のtopologyについての判定になっている。',
     next_action: 'migrate_witness_set_then_compile',
@@ -52,6 +64,22 @@ const CATALOG = Object.freeze({
     message: '記録時点の宣言境界では、他のready工程と干渉しない。',
     next_action: 'none',
   }),
+  seam_proposal_unrecorded: Object.freeze({
+    message: 'このplanのseam提案はまだ生成していない。提案対象が無いのではなく、記録が存在しない。',
+    next_action: 'compile_seam_proposal',
+  }),
+  seam_proposal_superseded: Object.freeze({
+    message: '参照元のplanまたは並列可否記録が更新され、このseam提案は現在の競合についての記録ではない。',
+    next_action: 'compile_seam_proposal',
+  }),
+  seam_proposal_stale: Object.freeze({
+    message: 'seam提案の生成後にHEADが進み、記録時点の構造証拠は現在のcodeを指していない。',
+    next_action: 'compile_seam_proposal',
+  }),
+  seam_proposal_verified: Object.freeze({
+    message: 'seam提案の記録は現在のplan、並列可否記録、HEADと一致している。',
+    next_action: 'none',
+  }),
 });
 
 /** 切断可能性の言い換え。conflictの案内へ添える。 */
@@ -82,7 +110,7 @@ export function todoIndependenceGuidance(code, { severability = null } = {}) {
  */
 export function selectIndependenceGuidance({
   coverage, taskDeclared, taskStale, conflictWithActive = null, conflictBetweenReady = null,
-  readyCount = null,
+  contractSuperseded = false, readyCount = null,
 }) {
   // 着手候補が無いなら述べる対象が無い。ここを通さないと、readyが空のとき
   // 「未検査taskが1件も無い」が空虚に真になり、記録が古くても検証済みへ倒れる。
@@ -97,6 +125,9 @@ export function selectIndependenceGuidance({
       severability: conflictBetweenReady,
     });
   }
+  if (contractSuperseded) {
+    return todoIndependenceGuidance('independence_contract_superseded');
+  }
   if (coverage === 'missing') return todoIndependenceGuidance('independence_unrecorded');
   if (coverage === 'superseded') return todoIndependenceGuidance('independence_superseded');
   if (!taskDeclared) return todoIndependenceGuidance('independence_task_undeclared');
@@ -104,6 +135,15 @@ export function selectIndependenceGuidance({
   return todoIndependenceGuidance('independence_verified');
 }
 
+export function selectSeamProposalGuidance({ coverage }) {
+  const code = coverage === 'missing' ? 'seam_proposal_unrecorded'
+    : coverage === 'superseded' ? 'seam_proposal_superseded'
+      : coverage === 'stale' ? 'seam_proposal_stale'
+        : coverage === 'verified' ? 'seam_proposal_verified' : null;
+  if (code === null) throw new TypeError(`unknown seam proposal coverage: ${coverage}`);
+  return todoIndependenceGuidance(code);
+}
+
 /**
  * 宣言からcompileを経て読むまでの順序。helpとMCP instructionsが同じ手順を語るための正本。
  * 面ごとに手順を書き直すと、片方だけが古くなる。

package/src/todo-independence.mjs

@@ -2,6 +2,7 @@ import { digestTodoArtifact, isTodoIdentifier, todoSelfDigest } from './todo-con
 import {
   TODO_INDEPENDENCE_SCHEMA,
   isGitSha,
+  isTodoIndependenceLegacyMarker,
   severabilityOfConflictKind,
   synthesizeWitnessRunRequest,
   validateTodoIndependence,
@@ -50,34 +51,65 @@ export async function collectWitnessSensorEvidence({ cwd, witnessSet, execute =
 }
 
 /**
- * conflictへresource kindを載せる（ADR 0128 Decision 1）。
+ * conflictから参照されるnormalized resourceを正規化してartifactへ載せる。
  *
  * `graph.conflicts`はresource_idしか持たず、宣言由来のstate resource idは任意文字列なので
  * prefixからkindを復元できない。normalized resourceを引けない場合は、切断可能性を
  * 不明のまま記録するのでなくtyped failで止める。
  */
 function conflictsFrom(verdicts, resources) {
-  const kindByResourceId = new Map((Array.isArray(resources) ? resources : [])
-    .map((resource) => [resource?.resource_id, resource?.kind]));
-  return verdicts
+  const resourceById = new Map();
+  for (const resource of Array.isArray(resources) ? resources : []) {
+    const resourceId = resource?.resource_id;
+    if (resourceById.has(resourceId)) {
+      const previous = resourceById.get(resourceId);
+      if (previous.kind !== resource?.kind) {
+        fail('INDEPENDENCE_RESOURCE_KIND_MISMATCH', 'conflict_resource_kind_mismatch', {
+          resource_id: resourceId ?? null,
+          observed_kinds: [previous.kind ?? null, resource?.kind ?? null],
+        });
+      }
+      if (previous.target !== resource?.target) {
+        fail('INDEPENDENCE_RESOURCE_TARGET_MISMATCH', 'conflict_resource_target_mismatch', {
+          resource_id: resourceId ?? null,
+          observed_targets: [previous.target ?? null, resource?.target ?? null],
+        });
+      }
+      fail('INDEPENDENCE_RESOURCE_DUPLICATE', 'conflict_resource_duplicate', {
+        resource_id: resourceId ?? null,
+      });
+    }
+    resourceById.set(resourceId, { kind: resource?.kind, target: resource?.target });
+  }
+  const conflicts = verdicts
     .filter((verdict) => verdict.type === 'conflict')
     .map((verdict) => {
-      const kind = kindByResourceId.get(verdict.resource_id);
+      const resource = resourceById.get(verdict.resource_id);
+      const kind = resource?.kind;
       if (!['symbol', 'path', 'state', 'effect'].includes(kind)) {
         fail('INDEPENDENCE_RESOURCE_KIND_UNRESOLVED', 'conflict_resource_kind_unresolved', {
           resource_id: verdict.resource_id, observed_kind: kind ?? null,
         });
       }
+      if (typeof resource.target !== 'string' || resource.target.length === 0) {
+        fail('INDEPENDENCE_RESOURCE_TARGET_UNRESOLVED', 'conflict_resource_target_unresolved', {
+          resource_id: verdict.resource_id, observed_target: resource.target ?? null,
+        });
+      }
       return {
         task_ids: [...verdict.todo_ids].sort(compareText),
         resource_id: verdict.resource_id,
-        kind,
       };
     })
     .sort((left, right) => compareText(
       `${left.task_ids[0]}\0${left.task_ids[1]}\0${left.resource_id}`,
       `${right.task_ids[0]}\0${right.task_ids[1]}\0${right.resource_id}`,
     ));
+  const used = new Set(conflicts.map(({ resource_id: resourceId }) => resourceId));
+  const conflictResources = [...used]
+    .map((resourceId) => ({ resource_id: resourceId, ...resourceById.get(resourceId) }))
+    .sort((left, right) => compareText(left.resource_id, right.resource_id));
+  return { conflicts, conflictResources };
 }
 
 /**
@@ -141,7 +173,7 @@ function unknownsFrom(detail) {
 }
 
 /**
- * witness setとsensor evidenceから`lattice.todo_independence.v1`を作る。
+ * witness setとsensor evidenceから`lattice.todo_independence.v3`を作る。
  *
  * compileは宣言済みtaskの部分集合へ閉じる（ADR 0127 Decision 4）。未宣言taskを混ぜると、
  * unknownが1件でも出た時点で宣言済みtask同士の判定まで失われるためである。
@@ -187,6 +219,9 @@ export function compileTodoIndependence(options = {}) {
   }
 
   const dispatchable = compiled.outcome === 'dispatchable';
+  const conflictProjection = dispatchable
+    ? conflictsFrom(compiled.pairwise_verdicts, compiled.resources)
+    : { conflicts: [], conflictResources: [] };
   const artifact = {
     schema: TODO_INDEPENDENCE_SCHEMA,
     project_id: plan.project_id,
@@ -201,8 +236,8 @@ export function compileTodoIndependence(options = {}) {
       task_id: taskId,
       paths: boundaryPathsOf(witnessSet.manual_witness[taskId]),
     })),
-    conflicts: dispatchable
-      ? conflictsFrom(compiled.pairwise_verdicts, compiled.resources) : [],
+    conflict_resources: conflictProjection.conflictResources,
+    conflicts: conflictProjection.conflicts,
     precedences: dispatchable ? precedencesFrom(compiled.pairwise_verdicts) : [],
     unknowns: dispatchable ? [] : unknownsFrom(compiled.detail),
     wave_plan: dispatchable
@@ -290,6 +325,24 @@ export function projectIndependenceFrontier({
     };
   }
 
+  if (isTodoIndependenceLegacyMarker(artifact)) {
+    return {
+      coverage: 'superseded',
+      drift: null,
+      active_task_ids: active,
+      uncovered_active_task_ids: active,
+      frontier: {
+        parallel_groups: [],
+        serialize_pairs: [],
+        conflicts_with_active: [],
+        unknown: ready.map((taskId) => ({
+          task_id: taskId,
+          unknowns: [{ kind: 'record_superseded', ref: artifact.legacy_schema }],
+        })),
+      },
+    };
+  }
+
   const superseded = artifact.plan_version !== plan.plan_version
     || artifact.topology_digest !== plan.topology_digest;
   const coverage = superseded ? 'superseded'
@@ -382,9 +435,17 @@ export function projectIndependenceFrontier({
     });
   };
 
+  const conflictResourceById = new Map(artifact.conflict_resources
+    .map((resource) => [resource.resource_id, resource]));
   for (const conflict of artifact.conflicts) {
+    const resource = conflictResourceById.get(conflict.resource_id);
+    if (resource === undefined) {
+      fail('INDEPENDENCE_RESOURCE_KIND_UNRESOLVED', 'conflict_resource_kind_unresolved', {
+        resource_id: conflict.resource_id, observed_kind: null,
+      });
+    }
     notePair(conflict.task_ids[0], conflict.task_ids[1], 'conflict', conflict.resource_id,
-      conflict.kind);
+      resource.kind);
   }
   for (const precedence of artifact.precedences) {
     notePair(precedence.from_task_id, precedence.to_task_id, 'precedence', precedence.reason, null);

package/src/todo-store.mjs

@@ -21,9 +21,12 @@ import {
   validateTodoSnapshot,
 } from './todo-contracts.mjs';
 import {
+  TODO_INDEPENDENCE_LEGACY_MARKER_SCHEMA,
+  isTodoIndependenceLegacyArtifactIdentity,
   validateTodoIndependence,
   validateTodoWitnessSet,
 } from './todo-independence-contracts.mjs';
+import { validateSeamProposal } from './seam-proposal-contracts.mjs';
 import { sha256Bytes, verifyLinearHashChain } from './hash-chain.mjs';
 import {
   parseTodoSourceRef,
@@ -3609,12 +3612,25 @@ export async function readTodoIndependenceArtifact(options = {}) {
   const member = activeMember(store, options.planKey);
   const ref = todoIndependenceRef(member.plan.plan_key, member.plan.plan_version);
   try {
-    return await readArtifact(repoRoot, ref, {
+    const artifact = await readArtifact(repoRoot, ref, {
       code: 'INDEPENDENCE_ARTIFACT_INVALID',
       maxBytes: INDEPENDENCE_ARTIFACT_BYTES,
-      validate: validateTodoIndependence,
+      // 旧契約は本体を信用せず、canonical JSONと版をまたいで不変なidentityの型だけを見る。
+      // schema名だけの壊れた記録や現行v3をこの分岐へ逃がさず、旧版集合も明示したものだけに閉じる。
+      validate: (value) => validateTodoIndependence(value)
+        || isTodoIndependenceLegacyArtifactIdentity(value),
       missing: true,
     });
+    if (artifact === null || validateTodoIndependence(artifact)) return artifact;
+    return {
+      schema: TODO_INDEPENDENCE_LEGACY_MARKER_SCHEMA,
+      legacy_schema: artifact.schema,
+      project_id: member.plan.project_id,
+      plan_key: member.plan.plan_key,
+      plan_version: null,
+      topology_digest: null,
+      base_sha: null,
+    };
   } catch (error) {
     // 読めない記録は握りつぶさない。ただしどのplanをどう直すかまで言わないと、
     // 消費者は「壊れている」以上のことができない。
@@ -3630,6 +3646,91 @@ export async function readTodoIndependenceArtifact(options = {}) {
   }
 }
 
+const SEAM_PROPOSAL_ARTIFACT_NAME = 'seam-proposal.json';
+const SEAM_PROPOSAL_ARTIFACT_BYTES = 4_194_304;
+
+/** independence.jsonと同じplan versionディレクトリへ並置し、manifestへ登録しない。 */
+export function todoSeamProposalRef(planKey, planVersion) {
+  return `${STORE_ROOT_REF}/plans/${planKey}/${planVersion}/${SEAM_PROPOSAL_ARTIFACT_NAME}`;
+}
+
+/**
+ * seam proposal artifactをactive planと現在のindependence artifactへbindして書く。
+ * planの正本とmanifestには触れない。
+ */
+export async function writeTodoSeamProposalArtifact(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const { artifact } = options;
+  if (!validateSeamProposal(artifact)) {
+    fail('SEAM_PROPOSAL_ARTIFACT_INVALID', 'seam_proposal_artifact_invalid');
+  }
+  return withLock(repoRoot, async () => {
+    const store = await readTodoStore({ repoRoot, forWrite: true, now: options.now });
+    if (store.project_id !== artifact.project_id) {
+      fail('SEAM_PROPOSAL_BINDING_MISMATCH', 'project_id_mismatch', {
+        expected: store.project_id, actual: artifact.project_id,
+      });
+    }
+    const member = activeMember(store, artifact.plan_key);
+    const binding = artifact.source_binding;
+    if (member.plan.plan_version !== binding.plan_version) {
+      fail('SEAM_PROPOSAL_BINDING_MISMATCH', 'plan_version_mismatch', {
+        expected: member.plan.plan_version, actual: binding.plan_version,
+      });
+    }
+    if (member.plan.topology_digest !== binding.topology_digest) {
+      fail('SEAM_PROPOSAL_BINDING_MISMATCH', 'topology_digest_mismatch', {
+        expected: member.plan.topology_digest, actual: binding.topology_digest,
+      });
+    }
+    const independenceArtifact = await readTodoIndependenceArtifact({
+      repoRoot, store, planKey: artifact.plan_key,
+    });
+    if (independenceArtifact === null
+      || !validateTodoIndependence(independenceArtifact)
+      || independenceArtifact.schema !== binding.independence_schema
+      || independenceArtifact.result_digest !== binding.independence_result_digest
+      || independenceArtifact.witness_set_digest !== binding.witness_set_digest
+      || independenceArtifact.plan_version !== binding.plan_version
+      || independenceArtifact.topology_digest !== binding.topology_digest
+      || independenceArtifact.base_sha !== binding.base_sha) {
+      fail('SEAM_PROPOSAL_BINDING_MISMATCH', 'independence_binding_mismatch');
+    }
+    const ref = todoSeamProposalRef(artifact.plan_key, binding.plan_version);
+    await atomicWrite(path.resolve(repoRoot, ref), canonicalLine(artifact));
+    return { ref, artifact };
+  });
+}
+
+/**
+ * active planに並置されたseam proposal artifactを読む。
+ * 無ければnull、壊れた記録はtyped failureとし、missingへ丸めない。
+ */
+export async function readTodoSeamProposalArtifact(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const store = options.store ?? await readTodoStore({ repoRoot, now: options.now });
+  const member = activeMember(store, options.planKey);
+  const ref = todoSeamProposalRef(member.plan.plan_key, member.plan.plan_version);
+  try {
+    return await readArtifact(repoRoot, ref, {
+      code: 'SEAM_PROPOSAL_ARTIFACT_INVALID',
+      maxBytes: SEAM_PROPOSAL_ARTIFACT_BYTES,
+      validate: validateSeamProposal,
+      missing: true,
+    });
+  } catch (error) {
+    if (error instanceof TodoStoreError && error.code === 'SEAM_PROPOSAL_ARTIFACT_INVALID') {
+      throw new TodoStoreError(error.code, error.detail.reason, undefined, {
+        ...error.detail,
+        plan_key: member.plan.plan_key,
+        artifact_ref: ref,
+        next_action: 'recompile_seam_proposal_or_remove_stale_record',
+      });
+    }
+    throw error;
+  }
+}
+
 const WITNESS_SET_BYTES = 4_194_304;
 
 /**