@quolu/lattice 0.34.2 → 0.36.0

package/src/todo-revision.mjs

@@ -185,7 +185,7 @@ function validTaskMigration(value) {
     ]) && isTodoIdentifier(entry.from_task_id)
       && (entry.to_task_id === 'removed' || isTodoIdentifier(entry.to_task_id))
       && ((entry.state_policy === 'removed' && entry.to_task_id === 'removed')
-        || (['carry', 'carry_reconciled_metadata', 'reset_pending'].includes(entry.state_policy)
+        || (['carry', 'carry_reconciled_metadata', 'reset_pending', 'acquire_phase'].includes(entry.state_policy)
           && entry.to_task_id !== 'removed')))
     && new Set(value.map(({ from_task_id }) => from_task_id)).size === value.length
     && new Set(activeTargets).size === activeTargets.length
@@ -277,8 +277,11 @@ function validRuntimeTodoProjection(runtimeMigration, taskMigration) {
   return projected.length === taskMigration.length && projected.every((expected, index) => {
     const actual = taskMigration[index];
     return expected.from_task_id === actual.from_task_id && expected.to_task_id === actual.to_task_id
+      // runtime disposition carry/stayは実行状態の持ち越しだけを申告する。task_migration側は
+      // carry_reconciled_metadataに加え、Phase獲得だけを許すacquire_phase(ADR 0147裁定4)も
+      // 「状態を持ち越すcarry系」の投影として受理する。
       && (expected.state_policy === 'carry'
-        ? ['carry', 'carry_reconciled_metadata'].includes(actual.state_policy)
+        ? ['carry', 'carry_reconciled_metadata', 'acquire_phase'].includes(actual.state_policy)
         : expected.state_policy === actual.state_policy);
   });
 }
@@ -396,6 +399,569 @@ export function validateTodoRevision(value) {
   } catch { return false; }
 }
 
+const reject = (reason, path = '') => ({ valid: false, reason, path });
+
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * 期待keyとの過不足を1件ずつ言い当てる。missing/unexpectedのどちらが先に見つかっても
+ * そこで止め、複数の欠落を一度に説明しない——`exactRecord`のbooleanと違い、
+ * 最初に見つかった違反fieldをpathへ刻む（ADR 0130の案内規律をrevision入口へ拡張）。
+ */
+function explainKeys(value, requiredKeys, at) {
+  if (!plainObject(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+    return reject('not_an_object', at);
+  }
+  const actualKeys = new Set(Object.keys(value));
+  for (const key of requiredKeys) {
+    if (!actualKeys.has(key)) return reject('missing_required_key', `${at}/${key}`);
+  }
+  const requiredSet = new Set(requiredKeys);
+  for (const key of actualKeys) {
+    if (!requiredSet.has(key)) return reject('unexpected_key', `${at}/${key}`);
+  }
+  return { valid: true };
+}
+
+function explainPredecessor(value, at = '/predecessor') {
+  const keyCheck = explainKeys(value, ['plan_digest', 'journal_head_digest', 'plan_version'], at);
+  if (!keyCheck.valid) return keyCheck;
+  if (!isTodoDigest(value.plan_digest)) return reject('invalid_digest', `${at}/plan_digest`);
+  if (!isTodoDigest(value.journal_head_digest)) return reject('invalid_digest', `${at}/journal_head_digest`);
+  if (!isTodoIdentifier(value.plan_version)) return reject('invalid_identifier', `${at}/plan_version`);
+  return { valid: true };
+}
+
+/**
+ * 実運用で最も時間を溶かした違反——配列のソート漏れ——を、壊れているindexを名指しして返す。
+ * `validTaskMigration`と同じ規則（from_task_idの厳密昇順、from/toの重複禁止）を、
+ * 可否を変えずに1件ずつ言い当てる。
+ */
+function explainTaskMigration(value, at = '/task_migration') {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 512) {
+    return reject('bounded_collection_violation', at);
+  }
+  for (const [index, entry] of value.entries()) {
+    const entryAt = `${at}/${index}`;
+    const keyCheck = explainKeys(entry, ['from_task_id', 'to_task_id', 'state_policy'], entryAt);
+    if (!keyCheck.valid) return keyCheck;
+    if (!isTodoIdentifier(entry.from_task_id)) return reject('invalid_identifier', `${entryAt}/from_task_id`);
+    if (entry.to_task_id !== 'removed' && !isTodoIdentifier(entry.to_task_id)) {
+      return reject('invalid_identifier', `${entryAt}/to_task_id`);
+    }
+    const validPolicy = (entry.state_policy === 'removed' && entry.to_task_id === 'removed')
+      || (['carry', 'carry_reconciled_metadata', 'reset_pending', 'acquire_phase'].includes(entry.state_policy)
+        && entry.to_task_id !== 'removed');
+    if (!validPolicy) return reject('state_policy_disposition_mismatch', `${entryAt}/state_policy`);
+  }
+  if (new Set(value.map(({ from_task_id: fromTaskId }) => fromTaskId)).size !== value.length) {
+    return reject('duplicate_from_task_id', at);
+  }
+  const activeTargets = value.filter(({ to_task_id: toTaskId }) => toTaskId !== 'removed')
+    .map(({ to_task_id: toTaskId }) => toTaskId);
+  if (new Set(activeTargets).size !== activeTargets.length) {
+    return reject('duplicate_to_task_id', at);
+  }
+  for (let index = 1; index < value.length; index += 1) {
+    if (compareText(value[index - 1].from_task_id, value[index].from_task_id) >= 0) {
+      return reject('unsorted_or_duplicate_collection', `${at}/${index}/from_task_id`);
+    }
+  }
+  return { valid: true };
+}
+
+function explainPhaseMigration(value, desiredPlan, at = '/phase_migration') {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 512) {
+    return reject('bounded_collection_violation', at);
+  }
+  for (const [index, entry] of value.entries()) {
+    const entryAt = `${at}/${index}`;
+    const keyCheck = explainKeys(entry, ['from_phase_id', 'to_phase_id', 'state_policy'], entryAt);
+    if (!keyCheck.valid) return keyCheck;
+    if (entry.from_phase_id !== null && !isTodoIdentifier(entry.from_phase_id)) {
+      return reject('invalid_identifier', `${entryAt}/from_phase_id`);
+    }
+    if (entry.to_phase_id !== 'removed' && !isTodoIdentifier(entry.to_phase_id)) {
+      return reject('invalid_identifier', `${entryAt}/to_phase_id`);
+    }
+    if (!['carry', 'reset', 'removed'].includes(entry.state_policy)) {
+      return reject('invalid_state_policy', `${entryAt}/state_policy`);
+    }
+    if (entry.state_policy === 'carry'
+      && (entry.from_phase_id === null || entry.to_phase_id === 'removed')) {
+      return reject('state_policy_disposition_mismatch', entryAt);
+    }
+    if (entry.state_policy === 'removed'
+      && (entry.from_phase_id === null || entry.to_phase_id !== 'removed')) {
+      return reject('state_policy_disposition_mismatch', entryAt);
+    }
+    if (entry.state_policy === 'reset' && entry.to_phase_id === 'removed') {
+      return reject('state_policy_disposition_mismatch', entryAt);
+    }
+  }
+  const sources = value.filter(({ from_phase_id: fromPhaseId }) => fromPhaseId !== null)
+    .map(({ from_phase_id: fromPhaseId }) => fromPhaseId);
+  if (new Set(sources).size !== sources.length) return reject('duplicate_from_phase_id', at);
+  const targets = value.filter(({ to_phase_id: toPhaseId }) => toPhaseId !== 'removed')
+    .map(({ to_phase_id: toPhaseId }) => toPhaseId);
+  if (new Set(targets).size !== targets.length) return reject('duplicate_to_phase_id', at);
+  if (canonicalizeForCompare(targets)
+    !== canonicalizeForCompare(desiredPlan.phases.map(({ phase_id: phaseId }) => phaseId))) {
+    return reject('phase_migration_target_set_mismatch', at);
+  }
+  return { valid: true };
+}
+
+function explainRuntimeTaskMigration(value, taskMigration, desiredPlan, at = '/runtime_task_migration') {
+  const keyCheck = explainKeys(value, ['schema', 'entries', 'migration_digest'], at);
+  if (!keyCheck.valid) return keyCheck;
+  if (value.schema !== 'lattice.runtime_task_migration.v1') return reject('schema_mismatch', `${at}/schema`);
+  if (!Array.isArray(value.entries) || value.entries.length === 0 || value.entries.length > 512) {
+    return reject('bounded_collection_violation', `${at}/entries`);
+  }
+  const targets = [];
+  for (const [index, entry] of value.entries.entries()) {
+    const entryAt = `${at}/entries/${index}`;
+    const keys = ['predecessor_task_id', 'disposition', 'successor_task_ids', 'reason', 'evidence_digests'];
+    const entryKeyCheck = explainKeys(entry, keys, entryAt);
+    if (!entryKeyCheck.valid) return entryKeyCheck;
+    if (!isTodoIdentifier(entry.predecessor_task_id)) {
+      return reject('invalid_identifier', `${entryAt}/predecessor_task_id`);
+    }
+    if (!['carry', 'stay', 'replace', 'split', 'retire'].includes(entry.disposition)) {
+      return reject('invalid_disposition', `${entryAt}/disposition`);
+    }
+    if (!Array.isArray(entry.successor_task_ids) || entry.successor_task_ids.length > 512
+      || !entry.successor_task_ids.every(isTodoIdentifier)) {
+      return reject('invalid_successor_task_ids', `${entryAt}/successor_task_ids`);
+    }
+    if (new Set(entry.successor_task_ids).size !== entry.successor_task_ids.length) {
+      return reject('duplicate_successor_task_id', `${entryAt}/successor_task_ids`);
+    }
+    const successorTail = entry.successor_task_ids.slice(1);
+    for (let tailIndex = 1; tailIndex < successorTail.length; tailIndex += 1) {
+      if (compareText(successorTail[tailIndex - 1], successorTail[tailIndex]) >= 0) {
+        return reject('unsorted_or_duplicate_collection', `${entryAt}/successor_task_ids/${tailIndex + 1}`);
+      }
+    }
+    if (!boundedText(entry.reason)) return reject('invalid_text', `${entryAt}/reason`);
+    if (!Array.isArray(entry.evidence_digests) || entry.evidence_digests.length === 0
+      || entry.evidence_digests.length > 512 || !entry.evidence_digests.every(isTodoDigest)) {
+      return reject('invalid_evidence_digests', `${entryAt}/evidence_digests`);
+    }
+    if (new Set(entry.evidence_digests).size !== entry.evidence_digests.length) {
+      return reject('duplicate_evidence_digest', `${entryAt}/evidence_digests`);
+    }
+    for (let digestIndex = 1; digestIndex < entry.evidence_digests.length; digestIndex += 1) {
+      if (compareText(entry.evidence_digests[digestIndex - 1], entry.evidence_digests[digestIndex]) >= 0) {
+        return reject('unsorted_or_duplicate_collection', `${entryAt}/evidence_digests/${digestIndex}`);
+      }
+    }
+    if (['carry', 'stay'].includes(entry.disposition)
+      && (entry.successor_task_ids.length !== 1
+        || entry.successor_task_ids[0] !== entry.predecessor_task_id)) {
+      return reject('disposition_successor_mismatch', entryAt);
+    }
+    if (entry.disposition === 'retire' && entry.successor_task_ids.length !== 0) {
+      return reject('disposition_successor_mismatch', entryAt);
+    }
+    if (['replace', 'split'].includes(entry.disposition) && entry.successor_task_ids.length === 0) {
+      return reject('disposition_successor_mismatch', entryAt);
+    }
+    if (index > 0 && compareText(value.entries[index - 1].predecessor_task_id,
+      entry.predecessor_task_id) >= 0) {
+      return reject('unsorted_or_duplicate_collection', `${at}/entries/${index}/predecessor_task_id`);
+    }
+    targets.push(...entry.successor_task_ids);
+  }
+  if (new Set(targets).size !== targets.length) return reject('duplicate_successor_task_id_across_entries', `${at}/entries`);
+  if (!isTodoDigest(value.migration_digest)) return reject('invalid_digest', `${at}/migration_digest`);
+  const expectedMigrationDigest = todoSelfDigest(value, 'migration_digest');
+  if (value.migration_digest !== expectedMigrationDigest) {
+    return reject('migration_digest_mismatch', `${at}/migration_digest`);
+  }
+  if (!validRuntimeTodoProjection(value, taskMigration)) {
+    return reject('runtime_task_migration_projection_mismatch', at);
+  }
+  if (canonicalizeForCompare(value.entries.flatMap(({ successor_task_ids: ids }) => ids))
+    !== canonicalizeForCompare(desiredPlan.tasks.map(({ task_id: taskId }) => taskId))) {
+    return reject('runtime_task_migration_target_set_mismatch', at);
+  }
+  return { valid: true };
+}
+
+function explainSourceInventory(value, desiredPlan, { requireNarrativeRef = false } = {}, at = '/source_inventory') {
+  const keyCheck = explainKeys(value, ['active', 'excluded_tombstones'], at);
+  if (!keyCheck.valid) return keyCheck;
+  if (!Array.isArray(value.active) || value.active.length > 512) {
+    return reject('bounded_collection_violation', `${at}/active`);
+  }
+  if (!Array.isArray(value.excluded_tombstones) || value.excluded_tombstones.length > 2_048) {
+    return reject('bounded_collection_violation', `${at}/excluded_tombstones`);
+  }
+  for (const [index, entry] of value.active.entries()) {
+    const entryAt = `${at}/active/${index}`;
+    const entryKeyCheck = explainKeys(entry, ['task_id', 'source_ref', 'source_digest'], entryAt);
+    if (!entryKeyCheck.valid) return entryKeyCheck;
+    if (!isTodoIdentifier(entry.task_id)) return reject('invalid_identifier', `${entryAt}/task_id`);
+    if (parseTodoSourceRef(entry.source_ref) === null) return reject('invalid_source_ref', `${entryAt}/source_ref`);
+    if (!isTodoDigest(entry.source_digest)) return reject('invalid_digest', `${entryAt}/source_digest`);
+  }
+  for (const [index, entry] of value.excluded_tombstones.entries()) {
+    const entryAt = `${at}/excluded_tombstones/${index}`;
+    const entryKeyCheck = explainKeys(entry, ['source_ref', 'source_digest', 'exclusion_reason'], entryAt);
+    if (!entryKeyCheck.valid) return entryKeyCheck;
+    if (parseTodoSourceRef(entry.source_ref) === null) return reject('invalid_source_ref', `${entryAt}/source_ref`);
+    if (!isTodoDigest(entry.source_digest)) return reject('invalid_digest', `${entryAt}/source_digest`);
+    if (!boundedText(entry.exclusion_reason)) return reject('invalid_text', `${entryAt}/exclusion_reason`);
+  }
+  const taskIds = desiredPlan.tasks.map(({ task_id: taskId }) => taskId);
+  const activeIds = value.active.map(({ task_id: taskId }) => taskId);
+  if (taskIds.length !== activeIds.length || !taskIds.every((id, index) => id === activeIds[index])) {
+    return reject('source_inventory_task_set_mismatch', `${at}/active`);
+  }
+  if (requireNarrativeRef) {
+    for (const [index, entry] of value.active.entries()) {
+      const task = desiredPlan.tasks.find(({ task_id: taskId }) => taskId === entry.task_id);
+      if (task?.narrative_ref !== entry.source_ref) {
+        return reject('source_inventory_narrative_ref_mismatch', `${at}/active/${index}/source_ref`);
+      }
+    }
+  }
+  const activeRefs = value.active.map(({ source_ref: sourceRef }) => sourceRef);
+  if (new Set(activeRefs).size !== activeRefs.length) return reject('duplicate_source_ref', `${at}/active`);
+  const tombstoneRefs = value.excluded_tombstones.map(({ source_ref: sourceRef }) => sourceRef);
+  if (new Set(tombstoneRefs).size !== tombstoneRefs.length) {
+    return reject('duplicate_source_ref', `${at}/excluded_tombstones`);
+  }
+  const activeRefSet = new Set(activeRefs);
+  if (tombstoneRefs.some((ref) => activeRefSet.has(ref))) {
+    return reject('tombstone_ref_still_active', `${at}/excluded_tombstones`);
+  }
+  for (let index = 1; index < value.excluded_tombstones.length; index += 1) {
+    if (compareText(value.excluded_tombstones[index - 1].source_ref,
+      value.excluded_tombstones[index].source_ref) >= 0) {
+      return reject('unsorted_or_duplicate_collection', `${at}/excluded_tombstones/${index}/source_ref`);
+    }
+  }
+  return { valid: true };
+}
+
+function explainSourceCutoverBatch(value, revision, at = '/source_cutover_batch') {
+  const keyCheck = explainKeys(value, ['batch_id', 'archive_ref', 'operations', 'batch_digest'], at);
+  if (!keyCheck.valid) return keyCheck;
+  if (!isTodoIdentifier(value.batch_id)) return reject('invalid_identifier', `${at}/batch_id`);
+  if (!isTodoRef(value.archive_ref) || !value.archive_ref.endsWith('.md')
+    || parseTodoSourceRef(value.archive_ref) !== null) {
+    return reject('invalid_archive_ref', `${at}/archive_ref`);
+  }
+  if (!Array.isArray(value.operations) || value.operations.length === 0 || value.operations.length > 512) {
+    return reject('bounded_collection_violation', `${at}/operations`);
+  }
+  const sourceRefs = new Set();
+  const activeTaskIds = new Set();
+  for (const [index, operation] of value.operations.entries()) {
+    const opAt = `${at}/operations/${index}`;
+    const keys = ['task_id', 'disposition', 'source_ref', 'source_digest', 'live_replacement'];
+    const opKeyCheck = explainKeys(operation, keys, opAt);
+    if (!opKeyCheck.valid) return opKeyCheck;
+    if (!['active', 'excluded'].includes(operation.disposition)) {
+      return reject('invalid_disposition', `${opAt}/disposition`);
+    }
+    if (operation.disposition === 'active' ? !isTodoIdentifier(operation.task_id)
+      : operation.task_id !== null) {
+      return reject('task_id_disposition_mismatch', `${opAt}/task_id`);
+    }
+    if (parseTodoSourceRef(operation.source_ref) === null) return reject('invalid_source_ref', `${opAt}/source_ref`);
+    if (!isTodoDigest(operation.source_digest)) return reject('invalid_digest', `${opAt}/source_digest`);
+    if (!validLiveReplacement(operation.live_replacement)) {
+      return reject('invalid_live_replacement', `${opAt}/live_replacement`);
+    }
+    if (sourceRefs.has(operation.source_ref)) return reject('duplicate_source_ref', `${opAt}/source_ref`);
+    sourceRefs.add(operation.source_ref);
+    if (index > 0 && compareText(value.operations[index - 1].source_ref, operation.source_ref) >= 0) {
+      return reject('unsorted_or_duplicate_collection', `${opAt}/source_ref`);
+    }
+    const archivedSourceRef = todoCutoverArchiveSourceRef(value, index);
+    if (operation.disposition === 'active') {
+      if (activeTaskIds.has(operation.task_id)) return reject('duplicate_task_id', `${opAt}/task_id`);
+      activeTaskIds.add(operation.task_id);
+      const inventory = revision.source_inventory.active
+        .find(({ task_id: taskId }) => taskId === operation.task_id);
+      const task = revision.desired_plan.tasks.find(({ task_id: taskId }) => taskId === operation.task_id);
+      if (inventory?.source_ref !== archivedSourceRef || inventory.source_digest !== operation.source_digest
+        || task?.narrative_ref !== archivedSourceRef) {
+        return reject('cutover_operation_not_bound_to_inventory', opAt);
+      }
+    } else {
+      const tombstone = revision.source_inventory.excluded_tombstones.find((entry) => (
+        entry.source_ref === archivedSourceRef && entry.source_digest === operation.source_digest
+      ));
+      if (tombstone === undefined) return reject('cutover_operation_not_bound_to_tombstone', opAt);
+    }
+  }
+  if (!isTodoDigest(value.batch_digest)) return reject('invalid_digest', `${at}/batch_digest`);
+  const expectedBatchDigest = todoSelfDigest(value, 'batch_digest');
+  if (value.batch_digest !== expectedBatchDigest) return reject('batch_digest_mismatch', `${at}/batch_digest`);
+  return { valid: true };
+}
+
+/**
+ * `lattice todo revise`が受理する`lattice.todo_revision.v1/v2`を診断する。
+ *
+ * `validateTodoRevision`の可否は変えない。desired_plan自体のgraph整合
+ * （task/phase閉包・topology digest）は`validateTodoPlan`任せの単一reasonへ丸め、
+ * ここでは実運用で詰まった箇所——必須key・task_migrationのソート・各digestの不一致——
+ * を優先して名指しする。
+ */
+export function explainTodoRevision(value) {
+  try {
+    if (!plainObject(value)) return reject('not_an_object', '');
+    const revisionV1 = value.schema === 'lattice.todo_revision.v1';
+    const revisionV2 = value.schema === 'lattice.todo_revision.v2';
+    if (!revisionV1 && !revisionV2) return reject('schema_mismatch', '/schema');
+    const keyCheck = explainKeys(value, revisionV1 ? REVISION_V1_KEYS : REVISION_V2_KEYS, '');
+    if (!keyCheck.valid) return keyCheck;
+    if (!isTodoIdentifier(value.project_id)) return reject('invalid_identifier', '/project_id');
+    if (!isTodoIdentifier(value.plan_key)) return reject('invalid_identifier', '/plan_key');
+    const predecessorCheck = explainPredecessor(value.predecessor);
+    if (!predecessorCheck.valid) return predecessorCheck;
+    if (!validateTodoPlan(value.desired_plan)) return reject('desired_plan_invalid', '/desired_plan');
+    if (value.desired_plan.schema !== 'lattice.todo_plan.v3') {
+      return reject('desired_plan_schema_mismatch', '/desired_plan/schema');
+    }
+    if (value.desired_plan.project_id !== value.project_id) {
+      return reject('desired_plan_project_id_mismatch', '/desired_plan/project_id');
+    }
+    if (value.desired_plan.plan_key !== value.plan_key) {
+      return reject('desired_plan_plan_key_mismatch', '/desired_plan/plan_key');
+    }
+    if (value.desired_plan.predecessor_plan_digest !== value.predecessor.plan_digest) {
+      return reject('desired_plan_predecessor_mismatch', '/desired_plan/predecessor_plan_digest');
+    }
+    const taskMigrationCheck = explainTaskMigration(value.task_migration);
+    if (!taskMigrationCheck.valid) return taskMigrationCheck;
+    const sourceCutoverBatch = revisionV2 ? value.source_cutover_batch : undefined;
+    const sourceInventoryCheck = explainSourceInventory(value.source_inventory, value.desired_plan);
+    if (!sourceInventoryCheck.valid) return sourceInventoryCheck;
+    const expectedPlanVersion = todoRevisionPlanVersion({
+      projectId: value.project_id, planKey: value.plan_key, predecessor: value.predecessor,
+      desiredPlan: value.desired_plan, taskMigration: value.task_migration,
+      sourceInventory: value.source_inventory, sourceCutoverBatch,
+    });
+    if (value.desired_plan.plan_version !== expectedPlanVersion) {
+      return reject('plan_version_mismatch', '/desired_plan/plan_version');
+    }
+    const reconciliationCheck = explainKeys(value.reconciliation, [
+      'predecessor_reconciliation_digest', 'source_inventory_digest', 'reconciliation_digest',
+    ], '/reconciliation');
+    if (!reconciliationCheck.valid) return reconciliationCheck;
+    if (!isTodoDigest(value.reconciliation.predecessor_reconciliation_digest)) {
+      return reject('invalid_digest', '/reconciliation/predecessor_reconciliation_digest');
+    }
+    const expectedSourceInventoryDigest = todoSourceInventoryDigest(value.source_inventory);
+    if (value.reconciliation.source_inventory_digest !== expectedSourceInventoryDigest) {
+      return reject('source_inventory_digest_mismatch', '/reconciliation/source_inventory_digest');
+    }
+    const expectedReconciliationDigest = todoReconciliationDigest({
+      predecessorReconciliationDigest: value.reconciliation.predecessor_reconciliation_digest,
+      sourceInventoryDigest: value.reconciliation.source_inventory_digest,
+      predecessor: value.predecessor, desiredPlanDigest: value.desired_plan.plan_digest,
+      taskMigration: value.task_migration, sourceCutoverBatch,
+    });
+    if (value.reconciliation.reconciliation_digest !== expectedReconciliationDigest) {
+      return reject('reconciliation_digest_mismatch', '/reconciliation/reconciliation_digest');
+    }
+    if (revisionV2) {
+      const cutoverCheck = explainSourceCutoverBatch(value.source_cutover_batch, value);
+      if (!cutoverCheck.valid) return cutoverCheck;
+    }
+    const targets = new Set(value.desired_plan.tasks.map(({ task_id: taskId }) => taskId));
+    const badTargetIndex = value.task_migration
+      .findIndex(({ to_task_id: toTaskId }) => toTaskId !== 'removed' && !targets.has(toTaskId));
+    if (badTargetIndex !== -1) {
+      return reject('task_migration_target_unresolved', `/task_migration/${badTargetIndex}/to_task_id`);
+    }
+    if (!isTodoDigest(value.revision_digest)) return reject('invalid_digest', '/revision_digest');
+    const expectedRevisionDigest = todoSelfDigest(value, 'revision_digest');
+    if (value.revision_digest !== expectedRevisionDigest) {
+      return reject('revision_digest_mismatch', '/revision_digest');
+    }
+    // ここまでの個別検査を全て通過したのに`validateTodoRevision`がfalseを返す状況は、
+    // このexplainがまだ言い当てられない違反があるということ。捏造せず未特定と申告する。
+    return { valid: true };
+  } catch {
+    return reject('diagnosis_failed', '');
+  }
+}
+
+/**
+ * `lattice todo revise-phase`が受理する`lattice.phase_todo_revision.v1/v2/v3`を診断する。
+ * 方針は`explainTodoRevision`と同じ——desired_planのgraph整合は単一reasonへ丸め、
+ * v3で増える`runtime_task_migration`・`source_cutover_batch`・8-key reconciliationの
+ * 各digestを個別に名指しする。
+ */
+export function explainPhaseTodoRevision(value) {
+  try {
+    if (!plainObject(value)) return reject('not_an_object', '');
+    const revisionV1 = value.schema === 'lattice.phase_todo_revision.v1';
+    const revisionV2 = value.schema === 'lattice.phase_todo_revision.v2';
+    const revisionV3 = value.schema === 'lattice.phase_todo_revision.v3';
+    if (!revisionV1 && !revisionV2 && !revisionV3) return reject('schema_mismatch', '/schema');
+    const keyCheck = explainKeys(value, revisionV3 ? PHASE_REVISION_V3_KEYS : PHASE_REVISION_KEYS, '');
+    if (!keyCheck.valid) return keyCheck;
+    if (!isTodoIdentifier(value.project_id)) return reject('invalid_identifier', '/project_id');
+    if (!isTodoIdentifier(value.plan_key)) return reject('invalid_identifier', '/plan_key');
+    const predecessorCheck = explainPredecessor(value.predecessor);
+    if (!predecessorCheck.valid) return predecessorCheck;
+    if (!validateTodoPlan(value.desired_plan)) return reject('desired_plan_invalid', '/desired_plan');
+    const expectedPlanSchema = (revisionV2 || revisionV3) ? 'lattice.todo_plan.v5' : 'lattice.todo_plan.v4';
+    if (value.desired_plan.schema !== expectedPlanSchema) {
+      return reject('desired_plan_schema_mismatch', '/desired_plan/schema');
+    }
+    if (value.desired_plan.project_id !== value.project_id) {
+      return reject('desired_plan_project_id_mismatch', '/desired_plan/project_id');
+    }
+    if (value.desired_plan.plan_key !== value.plan_key) {
+      return reject('desired_plan_plan_key_mismatch', '/desired_plan/plan_key');
+    }
+    if (value.desired_plan.predecessor_plan_digest !== value.predecessor.plan_digest) {
+      return reject('desired_plan_predecessor_mismatch', '/desired_plan/predecessor_plan_digest');
+    }
+    const taskMigrationCheck = explainTaskMigration(value.task_migration);
+    if (!taskMigrationCheck.valid) return taskMigrationCheck;
+    const phaseMigrationCheck = explainPhaseMigration(value.phase_migration, value.desired_plan);
+    if (!phaseMigrationCheck.valid) return phaseMigrationCheck;
+    const expectedPlanVersion = phaseTodoRevisionPlanVersion({
+      projectId: value.project_id, planKey: value.plan_key, predecessor: value.predecessor,
+      desiredPlan: value.desired_plan, taskMigration: value.task_migration,
+      phaseMigration: value.phase_migration,
+    });
+    if (value.desired_plan.plan_version !== expectedPlanVersion) {
+      return reject('plan_version_mismatch', '/desired_plan/plan_version');
+    }
+    if (revisionV3) {
+      const runtimeCheck = explainRuntimeTaskMigration(
+        value.runtime_task_migration, value.task_migration, value.desired_plan,
+      );
+      if (!runtimeCheck.valid) return runtimeCheck;
+      const sourceInventoryCheck = explainSourceInventory(value.source_inventory, value.desired_plan, {
+        requireNarrativeRef: true,
+      });
+      if (!sourceInventoryCheck.valid) return sourceInventoryCheck;
+      const cutoverCheck = explainSourceCutoverBatch(value.source_cutover_batch, value);
+      if (!cutoverCheck.valid) return cutoverCheck;
+      const reconciliationKeys = [
+        'predecessor_reconciliation_digest', 'source_inventory_digest', 'desired_plan_digest',
+        'runtime_task_migration_digest', 'task_migration_digest', 'phase_migration_digest',
+        'source_cutover_batch_digest', 'reconciliation_digest',
+      ];
+      const reconciliationCheck = explainKeys(value.reconciliation, reconciliationKeys, '/reconciliation');
+      if (!reconciliationCheck.valid) return reconciliationCheck;
+      if (!isTodoDigest(value.reconciliation.predecessor_reconciliation_digest)) {
+        return reject('invalid_digest', '/reconciliation/predecessor_reconciliation_digest');
+      }
+      if (value.reconciliation.source_inventory_digest
+        !== todoSourceInventoryDigest(value.source_inventory)) {
+        return reject('source_inventory_digest_mismatch', '/reconciliation/source_inventory_digest');
+      }
+      if (value.reconciliation.desired_plan_digest !== value.desired_plan.plan_digest) {
+        return reject('desired_plan_digest_mismatch', '/reconciliation/desired_plan_digest');
+      }
+      if (value.reconciliation.runtime_task_migration_digest !== value.runtime_task_migration.migration_digest) {
+        return reject('runtime_task_migration_digest_mismatch', '/reconciliation/runtime_task_migration_digest');
+      }
+      if (value.reconciliation.task_migration_digest !== todoTaskMigrationDigest(value.task_migration)) {
+        return reject('task_migration_digest_mismatch', '/reconciliation/task_migration_digest');
+      }
+      if (value.reconciliation.phase_migration_digest !== digestTodoArtifact(value.phase_migration)) {
+        return reject('phase_migration_digest_mismatch', '/reconciliation/phase_migration_digest');
+      }
+      if (value.reconciliation.source_cutover_batch_digest !== value.source_cutover_batch.batch_digest) {
+        return reject('source_cutover_batch_digest_mismatch', '/reconciliation/source_cutover_batch_digest');
+      }
+      const expectedReconciliationDigest = todoSelfDigest(value.reconciliation, 'reconciliation_digest');
+      if (value.reconciliation.reconciliation_digest !== expectedReconciliationDigest) {
+        return reject('reconciliation_digest_mismatch', '/reconciliation/reconciliation_digest');
+      }
+    }
+    if (!isTodoDigest(value.revision_digest)) return reject('invalid_digest', '/revision_digest');
+    const expectedRevisionDigest = todoSelfDigest(value, 'revision_digest');
+    if (value.revision_digest !== expectedRevisionDigest) {
+      return reject('revision_digest_mismatch', '/revision_digest');
+    }
+    return { valid: true };
+  } catch {
+    return reject('diagnosis_failed', '');
+  }
+}
+
+/**
+ * `lattice todo revise-set`が受理する`lattice.todo_revision_set.v1/v2/v3`を診断する。
+ * 個々のrevision memberの中身は`explainTodoRevision`／`explainPhaseTodoRevision`へ委譲し、
+ * setとして必要な件数・plan_key順序・自己digestだけをここで見る。
+ */
+export function explainTodoRevisionSet(value) {
+  try {
+    if (!plainObject(value)) return reject('not_an_object', '');
+    const setV1 = value.schema === 'lattice.todo_revision_set.v1';
+    const setV2 = value.schema === 'lattice.todo_revision_set.v2';
+    const setV3 = value.schema === 'lattice.todo_revision_set.v3';
+    if (!setV1 && !setV2 && !setV3) return reject('schema_mismatch', '/schema');
+    const keyCheck = explainKeys(value, ['schema', 'project_id', 'revisions', 'revision_set_digest'], '');
+    if (!keyCheck.valid) return keyCheck;
+    if (!isTodoIdentifier(value.project_id)) return reject('invalid_identifier', '/project_id');
+    if (!Array.isArray(value.revisions) || value.revisions.length < 2 || value.revisions.length > 64) {
+      return reject('bounded_collection_violation', '/revisions');
+    }
+    for (const [index, revision] of value.revisions.entries()) {
+      const entryAt = `/revisions/${index}`;
+      const isPhaseMember = setV3 && ['lattice.phase_todo_revision.v1', 'lattice.phase_todo_revision.v2']
+        .includes(revision?.schema);
+      if (isPhaseMember) {
+        const memberCheck = explainPhaseTodoRevision(revision);
+        if (!memberCheck.valid) {
+          return reject(memberCheck.reason, `${entryAt}${memberCheck.path}`);
+        }
+      } else {
+        if (!setV2 && !setV3 && revision?.schema !== 'lattice.todo_revision.v1') {
+          return reject('revision_set_v1_requires_todo_revision_v1', `${entryAt}/schema`);
+        }
+        const memberCheck = explainTodoRevision(revision);
+        if (!memberCheck.valid) {
+          return reject(memberCheck.reason, `${entryAt}${memberCheck.path}`);
+        }
+      }
+      if (revision.project_id !== value.project_id) {
+        return reject('revision_project_id_mismatch', `${entryAt}/project_id`);
+      }
+    }
+    if (setV2 && !value.revisions.some((revision) => revision.schema === 'lattice.todo_revision.v2')) {
+      return reject('revision_set_v2_requires_todo_revision_v2_member', '/revisions');
+    }
+    if (setV3 && !value.revisions.some((revision) => [
+      'lattice.phase_todo_revision.v1', 'lattice.phase_todo_revision.v2',
+    ].includes(revision.schema))) {
+      return reject('revision_set_v3_requires_phase_todo_revision_member', '/revisions');
+    }
+    for (let index = 1; index < value.revisions.length; index += 1) {
+      if (compareText(value.revisions[index - 1].plan_key, value.revisions[index].plan_key) >= 0) {
+        return reject('unsorted_or_duplicate_collection', `/revisions/${index}/plan_key`);
+      }
+    }
+    if (!isTodoDigest(value.revision_set_digest)) return reject('invalid_digest', '/revision_set_digest');
+    const expectedDigest = todoSelfDigest(value, 'revision_set_digest');
+    if (value.revision_set_digest !== expectedDigest) {
+      return reject('revision_set_digest_mismatch', '/revision_set_digest');
+    }
+    return { valid: true };
+  } catch {
+    return reject('diagnosis_failed', '');
+  }
+}
+
 export function validateTodoRevisionSet(value) {
   try {
     const setV1 = value?.schema === 'lattice.todo_revision_set.v1';

package/src/todo-status.mjs

@@ -182,8 +182,10 @@ function buildTodoGraph(readModel) {
   const nodes = new Map();
   const incoming = new Map();
   const memberHeads = [];
+  // snapshot artifactの形式(v1にはphasesキーが無い)には縛られない導出ビューを読む
+  // (readTodoStoreが常にmember.phasesとして埋める。ADR 0147)。
   const phaseStatuses = new Map(readModel.members.flatMap((member) => (
-    (member.snapshot?.phases ?? []).map((phase) => [
+    (member.phases ?? []).map((phase) => [
       `${member.plan.project_id}\0${member.plan.plan_key}\0${phase.phase_id}`, phase.status,
     ])
   )));
@@ -224,7 +226,8 @@ function buildTodoGraph(readModel) {
         }),
     });
     const states = new Map(member.tasks.map((state) => [state.task_id, state]));
-    const phases = new Map((member.snapshot?.phases ?? []).map((state) => [state.phase_id, state]));
+    // snapshot artifactの形式には縛られない導出ビュー(member.phases)を読む(ADR 0147)。
+    const phases = new Map((member.phases ?? []).map((state) => [state.phase_id, state]));
     for (const task of member.plan.tasks) {
       const state = states.get(task.task_id);
       if (!plain(state) || !['pending', 'in-progress', 'blocked', 'done'].includes(state.status)) {