@quolu/lattice 0.12.34 → 0.14.0

package/src/todo-store.mjs

@@ -20,6 +20,10 @@ import {
   validateTodoPlan,
   validateTodoSnapshot,
 } from './todo-contracts.mjs';
+import {
+  validateTodoIndependence,
+  validateTodoWitnessSet,
+} from './todo-independence-contracts.mjs';
 import { sha256Bytes, verifyLinearHashChain } from './hash-chain.mjs';
 import {
   parseTodoSourceRef,
@@ -3533,3 +3537,131 @@ export async function createSuccessorTodoPlan(options = {}) {
     return { plan, genesis, snapshot };
   });
 }
+
+const INDEPENDENCE_ARTIFACT_NAME = 'independence.json';
+const INDEPENDENCE_ARTIFACT_BYTES = 1_048_576;
+
+/**
+ * planと同じversionディレクトリに置く並置artifactのref（ADR 0127 Decision 1）。
+ * manifestへは登録しない。plan versionが変われば旧artifactは自然に非アクティブになる。
+ */
+export function todoIndependenceRef(planKey, planVersion) {
+  return `${STORE_ROOT_REF}/plans/${planKey}/${planVersion}/${INDEPENDENCE_ARTIFACT_NAME}`;
+}
+
+function activeMember(store, planKey) {
+  const member = store.members.find(({ descriptor }) => descriptor.plan_key === planKey);
+  if (!member) fail('STORE_INCONSISTENT', 'plan_not_active', { plan_key: planKey });
+  return member;
+}
+
+/**
+ * independence artifactを、active planへbindしてから書く。
+ *
+ * plan versionとtopology digestが現在のactive planと一致しない記録は、書いた瞬間から
+ * 別topologyについての主張になるため受理しない。planの正本（journal・snapshot・manifest）
+ * には触れない。
+ */
+export async function writeTodoIndependenceArtifact(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const { artifact } = options;
+  if (!validateTodoIndependence(artifact)) {
+    fail('INDEPENDENCE_ARTIFACT_INVALID', 'independence_artifact_invalid');
+  }
+  return withLock(repoRoot, async () => {
+    const store = await readTodoStore({ repoRoot, forWrite: true, now: options.now });
+    if (store.project_id !== artifact.project_id) {
+      fail('INDEPENDENCE_BINDING_MISMATCH', 'project_id_mismatch', {
+        expected: store.project_id, actual: artifact.project_id,
+      });
+    }
+    const member = activeMember(store, artifact.plan_key);
+    if (member.plan.plan_version !== artifact.plan_version) {
+      fail('INDEPENDENCE_BINDING_MISMATCH', 'plan_version_mismatch', {
+        expected: member.plan.plan_version, actual: artifact.plan_version,
+      });
+    }
+    if (member.plan.topology_digest !== artifact.topology_digest) {
+      fail('INDEPENDENCE_BINDING_MISMATCH', 'topology_digest_mismatch', {
+        expected: member.plan.topology_digest, actual: artifact.topology_digest,
+      });
+    }
+    const planTaskIds = new Set(member.plan.tasks.map(({ task_id: taskId }) => taskId));
+    const absent = artifact.task_ids.filter((taskId) => !planTaskIds.has(taskId));
+    if (absent.length > 0) {
+      fail('INDEPENDENCE_BINDING_MISMATCH', 'task_absent_from_plan', { task_ids: absent });
+    }
+    const ref = todoIndependenceRef(artifact.plan_key, artifact.plan_version);
+    await atomicWrite(path.resolve(repoRoot, ref), canonicalLine(artifact));
+    return { ref, artifact };
+  });
+}
+
+/**
+ * active planに紐づくindependence artifactを読む。
+ *
+ * 記録が無ければnull（「まだ判定していない」）を返す。壊れている・非canonical・
+ * 契約違反はnullへ丸めずtyped failにする。無い状態と読めない状態を同じ顔にしない。
+ */
+export async function readTodoIndependenceArtifact(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 = todoIndependenceRef(member.plan.plan_key, member.plan.plan_version);
+  try {
+    return await readArtifact(repoRoot, ref, {
+      code: 'INDEPENDENCE_ARTIFACT_INVALID',
+      maxBytes: INDEPENDENCE_ARTIFACT_BYTES,
+      validate: validateTodoIndependence,
+      missing: true,
+    });
+  } catch (error) {
+    // 読めない記録は握りつぶさない。ただしどのplanをどう直すかまで言わないと、
+    // 消費者は「壊れている」以上のことができない。
+    if (error instanceof TodoStoreError && error.code === 'INDEPENDENCE_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_independence_or_remove_stale_record',
+      });
+    }
+    throw error;
+  }
+}
+
+const WITNESS_SET_BYTES = 4_194_304;
+
+/**
+ * witness set宣言の置き場（ADR 0128 Decision 6）。
+ *
+ * 運用規約だった規則をコードの所有へ移す。`todoIndependenceRef`が判定結果のpathを持つのに対し、
+ * こちらは入力のpathを持つ。plan versionで分けないのは、宣言はtopologyでなくtaskについての
+ * 記述であり、revisionを跨いで移行して使い続けるためである。
+ */
+export function todoWitnessRef(planKey) {
+  return `${STORE_ROOT_REF}/witness/${planKey}.json`;
+}
+
+/** witness setを読む。無ければnull、壊れていればtyped fail（両者を同じ顔にしない）。 */
+export async function readTodoWitnessSet(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  return readArtifact(repoRoot, todoWitnessRef(options.planKey), {
+    code: 'INVALID_TODO_WITNESS_SET',
+    maxBytes: WITNESS_SET_BYTES,
+    validate: validateTodoWitnessSet,
+    missing: true,
+  });
+}
+
+/** witness setを書く。canonical JSON+LFで、契約を満たさないものは書かせない。 */
+export async function writeTodoWitnessSet(options = {}) {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const { witnessSet } = options;
+  if (!validateTodoWitnessSet(witnessSet)) {
+    fail('INVALID_TODO_WITNESS_SET', 'witness_set_invalid');
+  }
+  const ref = todoWitnessRef(witnessSet.plan_key);
+  await atomicWrite(path.resolve(repoRoot, ref), canonicalLine(witnessSet));
+  return { ref, witnessSet };
+}