create-agdf 0.20.1 → 0.30.0

package/runtime/core/lib/control-state/run-seal.js

@@ -1,15 +1,19 @@
+import { CURRENT_RUN_VERSION } from './run-identity.js';
 // Validation composes seal computation with historical and receipt proofs.
 export * from "./run-seal-compute.js";
 import { canonicalRunText, computeRunSeals } from "./run-seal-compute.js";
-import { scalarFields } from "./run-state-document.js";
+import { scalarFields, hasPersistedDerivedState } from "./run-state-document.js";
 import { readApprovalOperations } from "./approval-operations.js";
 import { readArtefactBindings } from "./artefact-bindings.js";
 import { validSourceRevisionHistories } from "./run-revision-history.js";
+import { validPlannedOriginHistory } from './planned-origin.js';
 const SEAL_PATTERN = /^sha256:[0-9a-f]{64}$/u;
 
 export function runSealState(root, content) {
   const text = canonicalRunText(content);
   const { values } = scalarFields(text);
+  if (values.get('control_state_version') !== String(CURRENT_RUN_VERSION)) return Object.freeze({ status: 'unsupported', classification: 'unsupported_version' });
+  if (hasPersistedDerivedState(text)) return Object.freeze({ status: 'invalid' });
   const recorded = Object.freeze({ content_seal: values.get("content_seal"), approval_seal: values.get("approval_seal") });
   if (recorded.content_seal === undefined && recorded.approval_seal === undefined) return Object.freeze({ status: "unsealed" });
   if (!SEAL_PATTERN.test(recorded.content_seal ?? "") || !SEAL_PATTERN.test(recorded.approval_seal ?? "")) {
@@ -18,6 +22,7 @@ export function runSealState(root, content) {
   if (!readApprovalOperations(text).valid) return Object.freeze({ status: "invalid", recorded });
   if (!readArtefactBindings(text).valid) return Object.freeze({ status: "invalid", recorded });
   if (!validSourceRevisionHistories(root, text)) return Object.freeze({ status: "invalid", recorded });
+  if (!validPlannedOriginHistory(root, text)) return Object.freeze({ status: 'invalid', recorded });
   const actual = computeRunSeals(root, text);
   const status = actual.approval_seal !== recorded.approval_seal
     ? "approvals_changed"

package/runtime/core/lib/control-state/run-source-revisions.js

@@ -1,3 +1,6 @@
+import { runEvidencePath } from './run-identity.js';
+import { runDocumentPath, runHistoryPath } from './run-identity.js';
+import { resolutionRecord, resolutionRecordVersion } from './input-resolution.js';
 import { TextDecoder } from "node:util";
 import { canonicalJson, digest, DIGEST_PATTERN, exactObject, COOPERATIVE_ASSURANCE } from "./approval-command-contract.js";
 import { REVISION_ID_PATTERN, RUN_ID_PATTERN } from "./run-identity.js";
@@ -7,6 +10,7 @@ import { APPROVAL_GATES } from "./run-identity.js";
 import { evidenceApplicability } from './evidence-bindings.js';
 import { REVISION_STATEMENT_FIELDS, REVISION_QUALITY_FIELDS, REVISION_IMPACT_FIELDS, REVISION_UPSTREAM_FIELDS, REVISION_ANALYSIS_FIELDS } from './recording-formats.js';
 
+export const SOURCE_REVISION_VERSION = '4';
 export const SOURCE_GATES = Object.freeze(["UR", "PRD", "SD", "TP"]);
 export const sourceRevisionConfirmation = ({ runId, revisionId, operationId, sourceGate, previewDigest }) =>
   `Apply source revision: ${runId} ${revisionId} ${operationId} ${sourceGate} ${previewDigest}`;
@@ -14,7 +18,7 @@ const uuid = value => typeof value === "string" && REVISION_ID_PATTERN.test(valu
 const hashes = value => typeof value === "string" && DIGEST_PATTERN.test(value);
 const fields = ["schema_version", "operation_id", "target_id", "run_id", "source_gate", "request_digest", "preview_digest", "previous_revision_id", "resulting_revision_id", "revision", "invalidated_bindings", "analyses", "retained_sources", "archive", "reason"];
 export const sourceRevisionDigest = value => digest(`agdf-source-revision/1\0${canonicalJson(value)}`);
-export const revisionHistoryPrefix = (runId, operationId) => `.agdf/control/runs/${runId}/revisions/${operationId}/`;
+export const revisionHistoryPrefix = (runId, operationId) => `${runHistoryPath(runId, `revisions/${operationId}`)}/`;
 
 // One inventory for live preview and immutable archive validation. No inferred
 // association can preserve fulfillment; the original writer owns consumed sources.
@@ -83,26 +87,25 @@ export function validExpandedRevisionProof(proposal, state, readArtefact, phase)
 
 export function sourceRevisionImpact(proposal, activeBindings) {
   const index = SOURCE_GATES.indexOf(proposal.source_gate), affected = SOURCE_GATES.slice(index);
-  const expanded = proposal.schema_version === '2';
   return { source_gate: proposal.source_gate, retained: SOURCE_GATES.slice(0, index), superseded: affected,
     invalidated_bindings: activeBindings.filter(row => affected.includes(row.destination.type)
-      || expanded && ['QA', 'QA_REPORT'].includes(row.destination.type)).map(row => row.binding_id),
-    analyses: proposal.impact_assessment.analyses, invalidated_steps: expanded
-      ? [...new Set(['Brownfield Analysis', 'CD+Tests', 'CR', ...proposal.quality_assessment.filter(row => row.disposition === 'reassess' && row.record.type !== 'evidence').map(row => row.record.type)])]
-      : ["Brownfield Analysis", "CD+Tests", "CR"],
+      || ['QA', 'QA_REPORT'].includes(row.destination.type)).map(row => row.binding_id),
+    analyses: proposal.impact_assessment.analyses, invalidated_steps: [...new Set(['Brownfield Analysis', 'CD+Tests', 'CR', ...proposal.quality_assessment.filter(row => row.disposition === 'reassess' && row.record.type !== 'evidence').map(row => row.record.type)])],
     retained_work: "Code and test files are retained; fulfillment and evidence require the renewed TP.",
     next_gate: proposal.source_gate !== "UR" && proposal.impact_assessment.analyses.some(row => row.type === "Brownfield Review" && row.disposition === "reassess") ? "Brownfield Review" : proposal.source_gate,
     implementation_authority: false,
-    ...(expanded ? { policy_version: 2, initiating_phase: proposal.initiating_phase,
+    policy_version: 2, initiating_phase: proposal.initiating_phase,
       changed_statements: proposal.changed_statements, quality_assessment: proposal.quality_assessment,
       invalidated_quality: proposal.quality_assessment.filter(row => row.disposition === 'reassess'),
-      renewed_approvals: [...affected, 'QA', 'UAT'], pending_presentations: 'superseded by exact material-version guard' } : {}) };
+      renewed_approvals: [...affected, 'QA', 'UAT'], pending_presentations: 'superseded by exact material-version guard' };
 }
 
 export function validSourceRevision(row) {
+  row = resolutionRecord(row);
+  if (!row) return false;
   const commandFields = ['command_digest', 'confirmation_digest', 'proposal_reference', 'producer', 'assurance'];
   const expandedFields = ['policy_version', 'initiating_phase', 'impact_digest', 'quality_digest'];
-  if (!exactObject(row, row.schema_version === '3' ? [...fields, ...commandFields, ...expandedFields] : row.schema_version === '2' ? [...fields, ...commandFields] : fields) || !['1', '2', '3'].includes(row.schema_version) || !uuid(row.operation_id)
+  if (!exactObject(row, [...fields, ...commandFields, ...expandedFields]) || row.schema_version !== SOURCE_REVISION_VERSION || !uuid(row.operation_id)
       || !RUN_ID_PATTERN.test(row.run_id ?? "") || !SOURCE_GATES.includes(row.source_gate)
       || ![row.target_id, row.request_digest, row.preview_digest].every(hashes)
       || ![row.previous_revision_id, row.resulting_revision_id].every(uuid)
@@ -114,22 +117,22 @@ export function validSourceRevision(row) {
       || !Array.isArray(row.analyses) || !row.analyses.every(item => exactObject(item, ["type", "disposition", "path", "digest", "reason"])
         && ["Brownfield Review", "UX Intent Definition"].includes(item.type)
         && ["retain", "reassess"].includes(item.disposition) && hashes(item.digest)
-        && isSafeControlRelativePath(item.path) && item.path.startsWith(`.agdf/control/artefacts/${row.run_id}/`)
+        && isSafeControlRelativePath(item.path) && item.path.startsWith(`${runDocumentPath(row.run_id, '')}/`)
         && typeof item.reason === "string" && item.reason.trim() && item.reason.length <= 4096)
       || new Set(row.analyses.map(item => item.type)).size !== row.analyses.length
       || !Array.isArray(row.retained_sources) || row.retained_sources.length !== SOURCE_GATES.indexOf(row.source_gate)
       || !row.retained_sources.every((item, i) => exactObject(item, ["type", "path", "digest", "rationale"])
-        && item.type === SOURCE_GATES[i] && item.path === `.agdf/control/artefacts/${row.run_id}/${item.type}.md`
+        && item.type === SOURCE_GATES[i] && item.path === `${runDocumentPath(row.run_id, '')}/${item.type}.md`
         && hashes(item.digest) && typeof item.rationale === "string" && item.rationale.trim() && item.rationale.length <= 4096)
       || !exactObject(row.archive, ["path", "digest"]) || !hashes(row.archive.digest)
       || row.archive.path !== `${revisionHistoryPrefix(row.run_id, row.operation_id)}manifest.json`) return false;
-  if (['2', '3'].includes(row.schema_version) && (![row.command_digest, row.confirmation_digest].every(hashes)
+  if ((![row.command_digest, row.confirmation_digest].every(hashes)
     || !exactObject(row.proposal_reference, ['path', 'digest']) || !hashes(row.proposal_reference.digest)
-    || !isSafeControlRelativePath(row.proposal_reference.path) || !row.proposal_reference.path.startsWith(`.agdf/control/artefacts/${row.run_id}/`)
+    || !isSafeControlRelativePath(row.proposal_reference.path) || !row.proposal_reference.path.startsWith(`${runHistoryPath(row.run_id, '')}/`) && !row.proposal_reference.path.startsWith(`${runEvidencePath(row.run_id, '')}/`)
     || !exactObject(row.producer, ['contract', 'package_version']) || row.producer.contract !== 'run-command/1' || typeof row.producer.package_version !== 'string'
     || canonicalJson(row.assurance) !== canonicalJson(COOPERATIVE_ASSURANCE)
     || row.confirmation_digest !== digest(sourceRevisionConfirmation({ runId: row.run_id, revisionId: row.previous_revision_id, operationId: row.operation_id, sourceGate: row.source_gate, previewDigest: row.preview_digest })))) return false;
-  if (row.schema_version === '3' && (row.policy_version !== 2 || !['PRD', 'SD', 'TP', 'CD+Tests', 'QA', 'UAT'].includes(row.initiating_phase)
+  if ((row.policy_version !== 2 || !['PRD', 'SD', 'TP', 'Brownfield Analysis', 'CD+Tests', 'QA', 'UAT'].includes(row.initiating_phase)
     || ![row.impact_digest, row.quality_digest].every(hashes))) return false;
   return row.source_gate !== "UR" || row.analyses.every(item => item.disposition === "reassess");
 }
@@ -207,10 +210,8 @@ export function validSourceRevisionEffect(before, after, receipt) {
     : next.approvals.get(gate)?.status === "missing" && !next.approvals.get(gate)?.evidence
       && next.artefacts.get(gate)?.status === "missing" && !next.artefacts.get(gate)?.path
       && !next.artefact_chain.some(row => row.from === gate))
-    && ["QA", "UAT"].every(gate => receipt.schema_version === '3'
-      ? next.approvals.get(gate)?.status === 'missing' && !next.approvals.get(gate)?.evidence
-        && (!old.artefacts.has(gate) || next.artefacts.get(gate)?.status === 'missing' && !next.artefacts.get(gate)?.path)
-      : canonicalJson(next.approvals.get(gate)) === canonicalJson(old.approvals.get(gate)))
+    && ["QA", "UAT"].every(gate => next.approvals.get(gate)?.status === 'missing' && !next.approvals.get(gate)?.evidence
+        && (!old.artefacts.has(gate) || next.artefacts.get(gate)?.status === 'missing' && !next.artefacts.get(gate)?.path))
     && steps.filter(type => ["Brownfield Analysis", "CD+Tests", "CR"].includes(type) || old.artefacts.has(type) && !["Brownfield Review", "UX Intent Definition"].includes(type))
       .every(type => next.artefacts.get(type)?.status === "missing" && !next.artefacts.get(type)?.path)
     && receipt.analyses.every(row => row.disposition === "retain"

package/runtime/core/lib/control-state/run-state-document.js

@@ -1,4 +1,104 @@
 // Structural Run document parsing; receipt validation belongs to run-state-parser.
+import { APPROVAL_GATES, runDocumentPath } from './run-identity.js';
+
+// These tables used to repeat current facts. They are now rendered from the
+// typed records in this document. They have no persistence or editing authority.
+export const DERIVED_RUN_SECTIONS = Object.freeze([
+  'Current Control State', 'Approvals', 'Gate Checklist', 'Artefacts', 'Artefact Chain', 'Evidence',
+]);
+export function hasPersistedDerivedState(content) {
+  return String(content).split(/\r?\n/u).some(line => DERIVED_RUN_SECTIONS.includes(line.match(/^## (.+?)\s*$/u)?.[1])
+    ) || /(?:^|\n)## Run Meta\s*\n(?:(?!\n## )[\s\S])*?^- (?:current_gate|next_allowed_action):/mu.test(String(content));
+}
+export function canonicalRunDocument(content) {
+  const lines = String(content).replace(/\r\n?/gu, '\n').split('\n');
+  let omitted = false, meta = false;
+  return lines.filter(line => {
+    const heading = line.match(/^## (.+?)\s*$/u);
+    if (heading) { omitted = DERIVED_RUN_SECTIONS.includes(heading[1]); meta = heading[1] === 'Run Meta'; }
+    return !omitted && !(meta && /^- (?:current_gate|next_allowed_action):/u.test(line));
+  }).join('\n').trimEnd() + '\n';
+}
+
+// Decode display facts only. Family codecs validate exact shapes, digests,
+// ordering and cross-record associations before a saved Run is accepted.
+// Browser consumers share this pure projection; it never reads a file or clock.
+export function recordRows(content, heading) {
+  return sectionTableRows(content, heading).slice(1).map(row => {
+    const encoded = row.at(-1);
+    if (!/^[A-Za-z0-9_-]+$/u.test(encoded ?? '') || encoded.length > 131072) throw Error('AGDF_RUN_RECORDS_INVALID');
+    try {
+      const base64 = encoded.replace(/-/gu, '+').replace(/_/gu, '/').padEnd(Math.ceil(encoded.length / 4) * 4, '=');
+      const bytes = Uint8Array.from(atob(base64), c => c.charCodeAt(0));
+      return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    } catch { throw Error('AGDF_RUN_RECORDS_INVALID'); }
+  });
+}
+export function projectRunFacts(content) {
+  const approvals = new Map(APPROVAL_GATES.map(gate => [gate, { status: 'missing', evidence: '' }]));
+  const artefacts = new Map(), chain = new Map(), immutableFiles = [];
+  const currentEvidence = new Map();
+  const evidence = recordRows(content, 'Evidence Bindings');
+  const byId = new Map(evidence.map(row => [row.operation_id, row]));
+  const events = [
+    ...recordRows(content, 'Run Operations').map(record => ({ type: 'operation', revision: record.effect?.revision, record })),
+    ...recordRows(content, 'Artefact Bindings').map(record => ({ type: 'binding', revision: record.operation?.revision, record })),
+    ...recordRows(content, 'Approval Operations').map(record => ({ type: 'approval', revision: record.effect?.revision, record })),
+    ...recordRows(content, 'Source Revisions').map(record => ({ type: 'revision', revision: record.revision, record })),
+  ].sort((a, b) => a.revision - b.revision);
+  const put = (type, path, status) => artefacts.set(type, {
+    path, status, notes: '', raw_path: path, path_format: 'plain', path_reason: path ? 'none' : 'empty',
+  });
+  const invalidate = gate => {
+    const affected = ['UR', 'PRD', 'SD', 'TP'].slice(['UR', 'PRD', 'SD', 'TP'].indexOf(gate));
+    for (const name of [...affected, 'QA', 'UAT']) approvals.set(name, { status: 'missing', evidence: '' });
+    for (const name of [...affected, 'QA']) { put(name, '', 'missing'); chain.delete(name); }
+  };
+  for (const { type, record } of events) {
+    if (type === 'revision') {
+      invalidate(record.source_gate);
+      currentEvidence.clear();
+      const retained = new Set(record.analyses.filter(row => row.disposition === 'retain').map(row => row.type));
+      for (const name of new Set([...artefacts.keys(), 'Brownfield Analysis', 'CD+Tests', 'CR'])) if (!['UR', 'PRD', 'SD', 'TP'].includes(name) && !retained.has(name)) {
+        put(name, '', 'missing'); chain.delete(name);
+      }
+    } else if (type === 'binding') {
+      const destination = record.destination;
+      const name = destination.type === 'QA_REPORT' ? 'QA' : destination.type;
+      put(name, destination.path, destination.status);
+      if (name === 'QA' && byId.has(record.operation.id)) currentEvidence.set('QA', byId.get(record.operation.id));
+      chain.set(name, { ...record.relationship, evidence: `binding ${record.binding_id}; reviewed by ${record.review.reviewer}` });
+    } else if (type === 'approval') {
+      const gate = record.binding.gate;
+      const attestation = `${record.effect.approval} · ${record.created_at.slice(0, 10)} · presentation ${record.binding.presentation_id} ${record.effect.presentation_digest}`;
+      approvals.set(gate, { status: 'approved', evidence: attestation });
+      if (['UR', 'PRD', 'SD', 'TP'].includes(gate) && artefacts.get(gate)?.path) put(gate, artefacts.get(gate).path, 'approved');
+      if (gate === 'UR') chain.set('UR', { from: 'UR', relationship: 'approved_by', to: 'Approval: UR', evidence: attestation });
+    } else {
+      const r = record.effect.record;
+      if (record.kind === 'run.create_from_planned') {
+        put('UR', runDocumentPath(record.run_id, 'UR.md'), 'draft'); immutableFiles.push(r.snapshot.path);
+      }
+      else if (['step.record', 'ur_draft.replace'].includes(record.kind)) {
+        const binding = byId.get(r.evidence_binding_id);
+        if (!binding) throw Error('AGDF_EVIDENCE_BINDINGS_INVALID');
+        const name = ({ ur: 'UR', route: 'Brownfield Review', review: 'CR' })[binding.step] ?? binding.step;
+        currentEvidence.set(binding.step, binding);
+        if (binding.step !== 'evidence') put(name, binding.report.path, binding.step === 'ur' ? 'draft' : r.status);
+      } else if (record.kind === 'prd_revision.reopen') {
+        approvals.set('PRD', { status: 'missing', evidence: '' });
+        const previous = artefacts.get('PRD'); if (previous?.path) put('PRD', previous.path, 'draft');
+      }
+      else if (record.kind === 'closeout.record') {
+        put('OR', (r.verified_change ?? r.or).path, 'done');
+        if (r.mode === 'verified_change') put('Verified Change', r.verified_change.path, 'executed');
+      }
+    }
+  }
+  return { approvals, artefacts, immutable_files: immutableFiles, artefact_chain: [...chain.values()], evidence_refs: [...currentEvidence.values()].map(row => ({
+    evidence: row.step, source: row.report.path, covers: `operation ${row.operation_id}`, strength: 'bound cooperative result',
+  })) };
+}
 export function scalarFields(content) {
   const values = new Map(),
     duplicates = [];
@@ -96,35 +196,11 @@ export function parseControlState(
   { userGates = [], internalSteps = [], closeoutArtefacts = [] } = {},
 ) {
   const metaValues = scalarFields(content).values;
-  const approvals = new Map();
-  for (const h of ["Approvals", "Gate Checklist"])
-    for (const [g, s, e] of rows(section(content, h))) {
-      if (userGates.includes(g)) {
-        const status = clean(s);
-        approvals.set(g, {
-          status: g === "QA" && (status === "pass" || status === "passed") ? "approved" : status,
-          evidence: e ?? "",
-        });
-      }
-    }
-  const artefacts = new Map();
-  for (const [t, p, s, n] of rows(section(content, "Artefacts"))) {
-    if (userGates.includes(t) || internalSteps.includes(t) || closeoutArtefacts.includes(t)) {
-      const parsedPath = parseArtefactPathCell(p ?? "");
-      artefacts.set(t, {
-        path: parsedPath.path,
-        status: clean(s),
-        notes: n ?? "",
-        raw_path: parsedPath.raw,
-        path_format: parsedPath.format,
-        path_reason: parsedPath.reason,
-      });
-    }
-  }
+  const facts = projectRunFacts(content);
+  const approvals = facts.approvals;
+  const artefacts = facts.artefacts;
   const mapRows = (h, header, fn) => dataRows(content, h, header).map(fn);
-  const mode = section(content, "Mode/Slice Decision").trim()
-      ? "Mode/Slice Decision"
-      : "Mode / Slice Decision",
+  const mode = "Mode/Slice Decision",
     source = "Source And Scope State",
     memory = "Knowledge Persistence Decision",
     handoff = "Parent Reconciliation Handoff",
@@ -136,23 +212,18 @@ export function parseControlState(
   const aggregationMissingEvidence = sectionScalar(content, aggregation, "programme_aggregation_missing_evidence");
   return {
     run_id: clean(metaValues.get("run_id") ?? ""),
-    current_gate: field(content, "current_gate"),
-    next_allowed_action: field(content, "next_allowed_action"),
+    current_gate: '',
+    next_allowed_action: '',
     approvals,
     artefacts,
     artefact_row_duplicates: duplicateArtefactRowTypes(content),
-    evidence_refs: mapRows("Evidence", "Evidence", (r) => ({
-      evidence: r[0] ?? "",
-      source: r[1] ?? "",
-      covers: r[2] ?? "",
-      strength: clean(r[3]),
-    })),
-    artefact_chain: mapRows("Artefact Chain", "From", (r) => ({
+    evidence_refs: facts.evidence_refs,
+    artefact_chain: [...facts.artefact_chain, ...mapRows("Relationships", "From", (r) => ({
       from: r[0] ?? "",
       relationship: clean(r[1]),
       to: clean(r[2]),
       evidence: r[3] ?? "",
-    })),
+    }))],
     missing_evidence: mapRows("Missing Evidence", "Missing evidence", (r) => ({
       missing_evidence: r[0] ?? "",
       impact: clean(r[1]),
@@ -173,10 +244,7 @@ export function parseControlState(
     },
     quality_outlook: field(content, "quality_outlook"),
     mode_slice_decision: {
-      decision: clean(sectionField(content, mode, "decision")),
-      required_next_gate: clean(
-        sectionField(content, mode, "required_next_gate"),
-      ),
+      decision: clean(metaValues.get("mode") ?? ""),
       scope_reason: sectionField(content, mode, "scope_reason"),
       evidence: sectionField(content, mode, "evidence"),
     },

package/runtime/core/lib/control-state/run-state-edits.js

@@ -4,23 +4,22 @@ import { runPath } from "./run-state-reader.js";
 import { pendingRunStepPath } from "./run-step-pending.js";
 import { existsSync } from "node:fs";
 import { authoredGoal, isDecisionContentPlaceholder } from '../control-evaluation/decision-content-readiness.js';
+import { runClosure, endedRunMessage, RUN_ENDED_NEXT_ACTION } from './run-operations.js';
 
 // Shared line-based edits for the recording commands (run-approve, run-step). They change only the
 // addressed section or table row and keep every other byte of the run state.
 const WRITE_REJECTIONS = new Map([
+  ['AGDF_CONTROL_MAINTENANCE_REQUIRED', 'control_maintenance_required'],
+  ['AGDF_CONTROL_LAYOUT_UNSUPPORTED', 'control_layout_unsupported'],
   ['AGDF_OPERATION_PAYLOAD_CONFLICT', 'operation_payload_conflict'],
   ['AGDF_OPERATION_BINDING_INVALID', 'operation_binding_invalid'],
   ['AGDF_OPERATION_IDENTITY_UNCONFIRMED', 'operation_identity_unconfirmed'],
   ['AGDF_RUN_OPERATION_SOURCE_INVALID', 'operation_source_invalid'],
   ['AGDF_RUN_OPERATION_SOURCE_CHANGED', 'operation_source_changed'],
   ["AGDF_RUN_PATH_INVALID", "run_path_invalid"],
-  ["AGDF_BACKLOG_PATH_INVALID", "backlog_path_invalid"],
-  ["AGDF_BACKLOG_LAYOUT_UNSUPPORTED", "backlog_layout_unsupported"],
-  ["AGDF_BACKLOG_IDENTITY_AMBIGUOUS", "backlog_identity_ambiguous"],
   ["AGDF_SOURCE_REVISIONS_INVALID", "source_revisions_invalid"],
   ["AGDF_SOURCE_REVISIONS_CHANGED", "source_revisions_changed"],
   ["AGDF_REVISION_HISTORY_INVALID", "revision_history_invalid"],
-  ["AGDF_CORRECTION_COMMIT_UNCONFIRMED", "correction_commit_unconfirmed"],
   ["AGDF_ARTEFACT_RECORDING_GATE_INVALID", "artefact_recording_gate_invalid"],
   ["AGDF_ARTEFACT_RECORDING_INPUT_INVALID", "artefact_recording_input_invalid"],
   ["AGDF_ARTEFACT_BINDING_PROOF_INVALID", "artefact_binding_proof_invalid"],
@@ -33,12 +32,20 @@ const WRITE_REJECTIONS = new Map([
   ["AGDF_RUN_STATE_INVALID", "run_state_invalid"],
   ["AGDF_ARTEFACT_ROW_DUPLICATE", "artefact_row_duplicate"],
   ["AGDF_RUN_STEP_RECOVERY_REQUIRED", "run_step_recovery_required"],
+  ["AGDF_RUN_LIFECYCLE_ENDED", "lifecycle_ended"],
 ]);
 
 export function rejected(runId, reason, details = {}) {
   return Object.freeze({ schema_version: "1", outcome: "rejected", run_id: runId ?? null, reason, ...details });
 }
 
+// Readable refusal for every operation on a superseded or abandoned Run; nothing is written.
+const endedDetails = (runId, closure) => ({ closure, message: endedRunMessage(runId, closure), next_action: RUN_ENDED_NEXT_ACTION });
+export function endedRunRejection(runId, content) {
+  const closure = runClosure(content);
+  return closure ? rejected(runId, "lifecycle_ended", endedDetails(runId, closure)) : null;
+}
+
 export function readRun(root, runId) {
   let path;
   try {
@@ -57,7 +64,7 @@ export function readRun(root, runId) {
   }
   const parsed = parseRunState(content, runId);
   if (!parsed.valid) {
-    return { rejection: rejected(runId, "run_state_invalid", { findings: parsed.findings.map((finding) => finding.code) }) };
+    return { rejection: rejected(runId, parsed.findings.some(row => row.classification === "unsupported_version") ? "run_version_unsupported" : "run_state_invalid", { findings: parsed.findings.map((finding) => finding.code) }) };
   }
   return { path, content, meta: parsed.meta };
 }
@@ -72,6 +79,7 @@ export function guardedWrite(runId, write) {
       ...(error.lock_path ? { lock_path: error.lock_path } : {}),
       ...(error.pending_run_id ? { pending_run_id: error.pending_run_id } : {}),
       ...(error.committed_revision_id ? { committed: true, revision_id: error.committed_revision_id } : {}),
+      ...(error.closure ? endedDetails(runId, error.closure) : {}),
     }) };
   }
 }

package/runtime/core/lib/control-state/run-state-parser.js

@@ -1,4 +1,5 @@
-import { scalarFields } from "./run-state-document.js";
+import { CURRENT_RUN_VERSION, RUN_MODES } from './run-identity.js';
+import { scalarFields, hasPersistedDerivedState } from "./run-state-document.js";
 export { scalarFields, sectionTableRows, duplicateArtefactRowTypes, parseArtefactPathCell, parseControlState } from "./run-state-document.js";
 import { normalizeLineEndings } from "./run-text.js";
 export { normalizeLineEndings } from "./run-text.js";
@@ -30,8 +31,16 @@ export function parseRunState(content, expected) {
   if (!RUN_ID_PATTERN.test(id)) findings.push({ code: "AGDF_RUN_ID_INVALID" });
   if (expected && id !== expected)
     findings.push({ code: "AGDF_RUN_PATH_MISMATCH" });
-  if (values.get("control_state_version") !== "2")
-    findings.push({ code: "AGDF_RUN_VERSION_UNSUPPORTED" });
+  const version = values.get('control_state_version');
+  if (version !== String(CURRENT_RUN_VERSION)) {
+    const unsupported = /^[1-9]\d*$/u.test(version ?? '') && !duplicates.includes('control_state_version');
+    findings.push({ code: unsupported ? 'AGDF_RUN_VERSION_UNSUPPORTED' : 'AGDF_RUN_VERSION_INVALID',
+      actual_version: version ?? null, classification: unsupported ? 'unsupported_version' : 'unclassified' });
+    return { content, meta: Object.fromEntries(values), findings, valid: false };
+  }
+  if (!RUN_MODES.includes(values.get('mode'))) findings.push({ code: 'AGDF_RUN_MODE_INVALID' });
+  if (values.has('decision')) findings.push({ code: 'AGDF_RUN_DERIVED_STATE_FORBIDDEN' });
+  if (hasPersistedDerivedState(content)) findings.push({ code: 'AGDF_RUN_DERIVED_STATE_FORBIDDEN' });
   if (!LIFECYCLES.has(values.get("lifecycle")))
     findings.push({ code: "AGDF_RUN_LIFECYCLE_INVALID" });
   if (!/^[1-9]\d*$/.test(values.get("revision") ?? ""))
@@ -72,9 +81,8 @@ export function parseRunState(content, expected) {
   const runOperations = readRunOperations(content);
   const evidenceBindings = readEvidenceBindings(content);
   if (!evidenceBindings.valid || evidenceBindings.bindings.some(row => row.run_id !== id
-    || (row.action === 'step.record'
-      ? !runOperations.receipts.some(r => r.operation_id === row.operation_id && r.kind === row.action && r.effect.record.step === row.step
-          && r.effect.record.source.path === row.report.path && r.effect.record.source.digest === row.report.digest && r.effect.record.source_set_digest === row.source_set_digest)
+    || (['step.record', 'ur_draft.replace'].includes(row.action)
+      ? !runOperations.receipts.some(r => r.operation_id === row.operation_id && r.kind === row.action && r.effect.record.evidence_binding_id === row.operation_id)
       : !bindings.receipts.some(r => r.operation.id === row.operation_id && r.relationship.from === (row.step === 'QA' ? 'QA_REPORT' : row.step)
           && r.destination.path === row.report.path && r.destination.digest === row.report.digest)))) findings.push({ code: 'AGDF_EVIDENCE_BINDINGS_INVALID' });
   const existingEffects = [

package/runtime/core/lib/control-state/run-state-reader.js

@@ -1,7 +1,12 @@
+import { readControlLayout } from './control-layout.js';
 import { existsSync, lstatSync, lstatKindSync, readFileSync, readdirSync, memoizeControlRead } from "../control-read/fs.js";
 import { join } from "node:path";
 import { parseRunState, RUN_ID_PATTERN } from "./run-state-parser.js";
 import { pendingRunStepPath } from "./run-step-pending.js";
+import { hasSymlinkComponent } from './contained-file.js';
+import { runRelativePath } from './run-identity.js';
+export { runRelativePath, runDocumentPath, runEvidencePath, runControlPath, runHistoryPath } from './run-identity.js';
+export const runPath = (root, runId) => join(root, runRelativePath(runId, '', 'RUN_STATE.md'));
 
 function invalidRun(runId, path) {
   return {
@@ -12,18 +17,34 @@ function invalidRun(runId, path) {
   };
 }
 
-export function runPath(root, id) {
-  if (!RUN_ID_PATTERN.test(id)) throw Error(`invalid run_id: ${id}`);
-  return join(root, ".agdf", "control", "runs", id, "RUN_STATE.md");
-}
-
 export function discoverRuns(root) {
   return memoizeControlRead(`discoverRuns:${root}`, () => discoverCapturedRuns(root));
 }
 
+// Exact selection is a dependency of the selected Run, not an inventory assignment.
+// Share the same entry validator with discovery, without reading foreign histories.
+export function readSelectedRun(root, id) {
+  let path;
+  try { path = runPath(root, id); } catch { return invalidRun(id, ''); }
+  try { readControlLayout(root); } catch (error) { return { ...invalidRun(id, path), findings: [{ code: error.code ?? error.message, classification: error.message === 'AGDF_CONTROL_LAYOUT_UNSUPPORTED' ? 'unsupported_layout' : 'invalid_current' }] }; }
+  const relative = runRelativePath(id, '', 'RUN_STATE.md');
+  if (hasSymlinkComponent(root, relative) || !existsSync(path)) return invalidRun(id, path);
+  const directory = join(root, '.agdf/control/runs', id);
+  if (lstatKindSync(directory) !== 'directory') return invalidRun(id, path);
+  if (existsSync(pendingRunStepPath(root, id))) {
+    return { ...invalidRun(id, path), findings: [{ code: 'AGDF_RUN_STEP_RECOVERY_REQUIRED', path: pendingRunStepPath(root, id) }] };
+  }
+  const stateStats = lstatSync(path);
+  if (stateStats.isSymbolicLink() || !stateStats.isFile()) return invalidRun(id, path);
+  const parsed = parseRunState(readFileSync(path, 'utf8'), id);
+  return { run_id: id, path, ...parsed, findings: parsed.findings.map(finding => ({ ...finding, path: finding.path ?? path })),
+    last_updated_at: parsed.meta.updated_at || stateStats.mtime.toISOString() };
+}
+
 function discoverCapturedRuns(root) {
   const dir = join(root, ".agdf", "control", "runs");
   if (!existsSync(dir)) return [];
+  readControlLayout(root);
   if (lstatKindSync(dir) !== 'directory') {
     return [invalidRun("<repository>", dir)];
   }
@@ -40,18 +61,6 @@ function discoverCapturedRuns(root) {
         return invalidRun(id, path);
       }
 
-      if (existsSync(pendingRunStepPath(root, id))) {
-        return { ...invalidRun(id, path), findings: [{ code: "AGDF_RUN_STEP_RECOVERY_REQUIRED", path: pendingRunStepPath(root, id) }] };
-      }
-
-      const stateStats = lstatSync(path);
-      if (stateStats.isSymbolicLink() || !stateStats.isFile()) return invalidRun(id, path);
-      const parsed = parseRunState(readFileSync(path, "utf8"), id);
-      return {
-        run_id: id,
-        path,
-        ...parsed,
-        last_updated_at: parsed.meta.updated_at || stateStats.mtime.toISOString(),
-      };
+      return readSelectedRun(root, id);
     });
 }