create-agdf 0.14.5 → 0.20.0

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-source-revisions.js

@@ -0,0 +1,221 @@
+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";
+import { isSafeControlRelativePath } from "./contained-file.js";
+import { parseControlState } from "./run-state-document.js";
+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_GATES = Object.freeze(["UR", "PRD", "SD", "TP"]);
+export const sourceRevisionConfirmation = ({ runId, revisionId, operationId, sourceGate, previewDigest }) =>
+  `Apply source revision: ${runId} ${revisionId} ${operationId} ${sourceGate} ${previewDigest}`;
+const uuid = value => typeof value === "string" && REVISION_ID_PATTERN.test(value);
+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}/`;
+
+// One inventory for live preview and immutable archive validation. No inferred
+// association can preserve fulfillment; the original writer owns consumed sources.
+export function sourceRevisionQualityFacts(state, readArtefact) {
+  const applicability = evidenceApplicability(state, readArtefact);
+  if (!applicability.valid) throw Error('AGDF_EVIDENCE_BINDINGS_INVALID');
+  const facts = [];
+  for (const [type, record] of state.artefacts) {
+    if (SOURCE_GATES.includes(type) || !record.path) continue;
+    const text = readArtefact(record.path);
+    if (typeof text !== 'string') throw Error('AGDF_REVISION_QUALITY_UNAVAILABLE');
+    const binding = applicability.by_step.get(type === 'QA_REPORT' ? 'QA' : type)
+      ?? applicability.current.find(row => row.report.path === record.path);
+    const matched = binding?.report.path === record.path && binding.report.digest === digest(text.replace(/\r\n?/gu, '\n').replace(/^\uFEFF/u, ''));
+    facts.push({ record: { type, path: record.path, digest: digest(text.replace(/\r\n?/gu, '\n').replace(/^\uFEFF/u, '')), status: record.status },
+      record_digest: digest(canonicalJson(record)), operation_id: matched ? binding.operation_id : null,
+      source_set_digest: matched ? binding.source_set_digest : null, sources: matched ? binding.sources : [],
+      association: matched ? binding.applicability : 'applicability_unknown' });
+  }
+  for (const record of state.evidence_refs ?? []) {
+    const path = String(record.source).replace(/^`|`$/gu, '');
+    const binding = applicability.current.find(row => row.report.path === path);
+    const text = isSafeControlRelativePath(path) ? readArtefact(path) : undefined;
+    facts.push({ record: { type: 'evidence', path: typeof text === 'string' ? path : '', digest: typeof text === 'string' ? digest(text.replace(/\r\n?/gu, '\n').replace(/^\uFEFF/u, '')) : null, status: 'documented' },
+      record_digest: digest(canonicalJson(record)), operation_id: binding?.operation_id ?? null,
+      source_set_digest: binding?.source_set_digest ?? null, sources: binding?.sources ?? [],
+      association: binding ? 'current' : 'applicability_unknown' });
+  }
+  return facts;
+}
+
+export function validExpandedRevisionProof(proposal, state, readArtefact, phase) {
+  const changed = proposal.changed_statements, affected = SOURCE_GATES.slice(SOURCE_GATES.indexOf(proposal.source_gate));
+  const nonempty = value => typeof value === 'string' && value.trim() && value.length <= 4096;
+  const assessmentProof = proposal.impact_assessment, index = SOURCE_GATES.indexOf(proposal.source_gate);
+  const analyticalTypes = ['Brownfield Review', 'UX Intent Definition'].filter(type => state.artefacts.get(type)?.path);
+  if (!exactObject(assessmentProof, REVISION_IMPACT_FIELDS) || !nonempty(assessmentProof.reviewer)
+    || assessmentProof.earliest_source !== proposal.source_gate || !nonempty(assessmentProof.implementation_evidence)
+    || !Array.isArray(assessmentProof.unresolved) || assessmentProof.unresolved.length
+    || !Array.isArray(assessmentProof.upstream) || assessmentProof.upstream.length !== index
+    || !assessmentProof.upstream.every((row, i) => exactObject(row, REVISION_UPSTREAM_FIELDS) && nonempty(row.rationale)
+      && canonicalJson({type:row.type,path:row.path,digest:row.digest}) === canonicalJson(proposal.sources[i]))
+    || !Array.isArray(assessmentProof.analyses) || assessmentProof.analyses.length !== analyticalTypes.length
+    || !assessmentProof.analyses.every((row, i) => exactObject(row, REVISION_ANALYSIS_FIELDS) && row.type === analyticalTypes[i]
+      && row.path === state.artefacts.get(row.type).path && hashes(row.digest) && nonempty(row.reason)
+      && ['retain', 'reassess'].includes(row.disposition) && (proposal.source_gate !== 'UR' || row.disposition === 'reassess'))) return false;
+  if (proposal.policy_version !== 2 || proposal.initiating_phase !== phase || !Array.isArray(changed) || !changed.length
+      || !changed.every(row => exactObject(row, REVISION_STATEMENT_FIELDS) && affected.includes(row.type)
+        && proposal.sources.some(source => source.type === row.type && source.path === row.path && source.digest === row.digest)
+        && [row.statement, row.intended_change, row.reason].every(nonempty)
+        && String(readArtefact(row.path)).replace(/\r\n?/gu, '\n').includes(row.statement))
+      || !changed.some(row => row.type === proposal.source_gate)) return false;
+  const facts = sourceRevisionQualityFacts(state, readArtefact), assessment = proposal.quality_assessment;
+  if (!Array.isArray(assessment) || !assessment.length || assessment.length !== facts.length) return false;
+  return assessment.every((row, i) => {
+    if (!exactObject(row, REVISION_QUALITY_FIELDS) || !['retain', 'reassess'].includes(row.disposition) || !nonempty(row.reason)) return false;
+    const { disposition, reason, ...proof } = row;
+    if (canonicalJson(proof) !== canonicalJson(facts[i])) return false;
+    const analysis = proposal.impact_assessment.analyses.find(item => item.type === row.record.type);
+    if (analysis && (analysis.disposition !== disposition || analysis.path !== row.record.path || analysis.digest !== row.record.digest)) return false;
+    return disposition !== 'retain' || row.association === 'current'
+      && !row.sources.some(source => affected.includes(source.type))
+      && !(proposal.source_gate === 'UR' && analysis);
+  });
+}
+
+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"],
+    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,
+      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' } : {}) };
+}
+
+export function validSourceRevision(row) {
+  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)
+      || !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)
+      || row.previous_revision_id === row.resulting_revision_id
+      || !Number.isSafeInteger(row.revision) || row.revision < 2
+      || typeof row.reason !== "string" || !row.reason.trim() || row.reason.length > 4096
+      || !Array.isArray(row.invalidated_bindings) || !row.invalidated_bindings.every(uuid)
+      || new Set(row.invalidated_bindings).size !== row.invalidated_bindings.length
+      || !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}/`)
+        && 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`
+        && 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)
+    || !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}/`)
+    || !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)
+    || ![row.impact_digest, row.quality_digest].every(hashes))) return false;
+  return row.source_gate !== "UR" || row.analyses.every(item => item.disposition === "reassess");
+}
+
+// This history is authority only as part of the sealed Run, never a second workflow store.
+export function readSourceRevisions(content) {
+  const lines = String(content).replace(/\r\n?/gu, "\n").split("\n");
+  const starts = lines.flatMap((line, i) => /^## Source Revisions\s*$/u.test(line) ? [i] : []);
+  if (!starts.length) return { present: false, valid: true, receipts: [] };
+  const invalid = () => ({ present: true, valid: false, receipts: [] });
+  if (starts.length !== 1) return invalid();
+  const start = starts[0]; let end = start + 1;
+  while (end < lines.length && !/^#{1,2} /u.test(lines[end])) end++;
+  const body = lines.slice(start + 1, end).map(line => line.trim()).filter(Boolean);
+  if (body[0] !== "- schema_version: 1" || body[1] !== "| operation_id | receipt_digest | receipt |"
+      || !/^\|[-:|\s]+\|$/u.test(body[2] ?? "")) return invalid();
+  const receipts = [], ids = new Set(), effects = new Set(); let revision = 1;
+  for (const line of body.slice(3)) {
+    const cells = line.match(/^\| ([^|]+) \| ([^|]+) \| ([A-Za-z0-9_-]+) \|$/u);
+    if (!cells || cells[3].length > 131072) return invalid();
+    try {
+      const bytes = Buffer.from(cells[3], "base64url");
+      const json = new TextDecoder("utf-8", { fatal: true }).decode(bytes), row = JSON.parse(json);
+      if (bytes.toString("base64url") !== cells[3] || canonicalJson(row) !== json || !validSourceRevision(row)
+          || row.operation_id !== cells[1] || sourceRevisionDigest(row) !== cells[2] || ids.has(row.operation_id)
+          || effects.has(row.resulting_revision_id) || row.revision <= revision) return invalid();
+      receipts.push(row); ids.add(row.operation_id); effects.add(row.resulting_revision_id); revision = row.revision;
+    } catch { return invalid(); }
+  }
+  return receipts.length ? { present: true, valid: true, receipts, start, end } : invalid();
+}
+
+export function appendSourceRevision(content, receipt) {
+  const history = readSourceRevisions(content);
+  if (!history.valid || !validSourceRevision(receipt)) throw Error("AGDF_SOURCE_REVISIONS_INVALID");
+  const block = ["## Source Revisions", "", "- schema_version: 1", "", "| operation_id | receipt_digest | receipt |", "|---|---|---|",
+    ...[...history.receipts, receipt].map(row => `| ${row.operation_id} | ${sourceRevisionDigest(row)} | ${Buffer.from(canonicalJson(row)).toString("base64url")} |`), ""];
+  const lines = String(content).split("\n");
+  const next = history.present ? [...lines.slice(0, history.start), ...block, ...lines.slice(history.end)].join("\n")
+    : `${String(content).trimEnd()}\n\n${block.join("\n")}`;
+  if (!readSourceRevisions(next).valid) throw Error("AGDF_SOURCE_REVISIONS_INVALID");
+  return next;
+}
+
+export function assertSourceRevisionsChange(before, after, appended) {
+  const old = readSourceRevisions(before), next = readSourceRevisions(after);
+  if (!old.valid || !next.valid || next.present !== (old.present || Boolean(appended))
+      || canonicalJson(next.receipts) !== canonicalJson(appended ? [...old.receipts, appended] : old.receipts)) {
+    throw Error("AGDF_SOURCE_REVISIONS_CHANGED");
+  }
+}
+
+export function bindingIsEffective(content, receipt) {
+  const history = readSourceRevisions(content);
+  return history.valid && !history.receipts.some(row => row.invalidated_bindings.includes(receipt.binding_id));
+}
+
+export function sourceRevisionObservation(content, unavailable = false) {
+  const history = readSourceRevisions(content);
+  if (!history.present) return null;
+  return { status: unavailable || !history.valid ? "unavailable" : "verified",
+    archive_authority: "historical_evidence_only", entries: history.receipts.map(row => ({
+      operation_id: row.operation_id, source_gate: row.source_gate, previous_revision_id: row.previous_revision_id,
+      resulting_revision_id: row.resulting_revision_id, archive: row.archive, superseded_sources: SOURCE_GATES.slice(SOURCE_GATES.indexOf(row.source_gate)),
+    })) };
+}
+
+export function validSourceRevisionEffect(before, after, receipt) {
+  const steps = ["Brownfield Review", "UX Intent Definition", "Brownfield Analysis", "CD+Tests", "CR", "Code Review", "TP Review", "Clean Review", "Clean Implementation Review"];
+  const state = text => parseControlState(text, { userGates: APPROVAL_GATES, internalSteps: steps });
+  const old = state(before), next = state(after), index = SOURCE_GATES.indexOf(receipt.source_gate);
+  return SOURCE_GATES.every((gate, i) => i < index
+    ? canonicalJson(next.approvals.get(gate)) === canonicalJson(old.approvals.get(gate))
+      && next.artefacts.get(gate)?.path === old.artefacts.get(gate)?.path && next.artefacts.get(gate)?.status === "approved"
+    : 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)))
+    && 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"
+      ? canonicalJson(old.artefacts.get(row.type)) === canonicalJson(next.artefacts.get(row.type))
+      : next.artefacts.get(row.type)?.status === "missing" && !next.artefacts.get(row.type)?.path)
+    && (receipt.source_gate !== "UR" && !receipt.analyses.some(row => row.type === "Brownfield Review" && row.disposition === "reassess")
+      || next.artefacts.get("Brownfield Review")?.status === "missing" && next.mode_slice_decision.decision === "undecided");
+}

package/{lib/control-state/run-state-parser.js → generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-state-document.js}

@@ -1,59 +1,14 @@
-import { REVISION_ID_PATTERN, RUN_ID_PATTERN } from "./run-identity.js";
-
-export { RUN_ID_PATTERN } from "./run-identity.js";
-export const LIFECYCLES = new Set([
-  "active",
-  "completed",
-  "superseded",
-  "abandoned",
-]);
+// Structural Run document parsing; receipt validation belongs to run-state-parser.
 export function scalarFields(content) {
   const values = new Map(),
     duplicates = [];
   const runMeta = content.match(/(?:^|\n)## Run Meta\s*\n([\s\S]*?)(?=\n## |$)/)?.[1] ?? "";
-  for (const [, k, v] of runMeta.matchAll(/^- ([a-z_]+):\s*(.*?)\s*$/gm)) {
+  for (const [, k, v] of runMeta.matchAll(/^- ([a-z_]+):[ \t]*(.*?)[ \t]*$/gm)) {
     if (values.has(k)) duplicates.push(k);
     else values.set(k, v.replace(/^`|`$/g, ""));
   }
   return { values, duplicates };
 }
-export function parseRunState(content, expected) {
-  const { values, duplicates } = scalarFields(content),
-    findings = duplicates.map((field) => ({
-      code: "AGDF_RUN_FIELD_DUPLICATE",
-      field,
-    })),
-    id = values.get("run_id") ?? "";
-  if (content.split(/\r?\n/).some((line) => line.trimStart().startsWith("|") && !line.trimEnd().endsWith("|"))) {
-    findings.push({ code: "AGDF_RUN_TABLE_INVALID" });
-  }
-  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" });
-  if (!LIFECYCLES.has(values.get("lifecycle")))
-    findings.push({ code: "AGDF_RUN_LIFECYCLE_INVALID" });
-  if (!/^[1-9]\d*$/.test(values.get("revision") ?? ""))
-    findings.push({ code: "AGDF_RUN_REVISION_INVALID" });
-  if (!REVISION_ID_PATTERN.test(values.get("revision_id") ?? ""))
-    findings.push({ code: "AGDF_RUN_REVISION_ID_INVALID" });
-  return {
-    content,
-    meta: Object.fromEntries(values),
-    findings,
-    valid: !findings.length,
-  };
-}
-export function semanticBody(content) {
-  return content
-    .replace(/^# AGDF Run State\s*/m, "")
-    .replace(/## Run Meta[\s\S]*?(?=\n## )/, "")
-    .trim();
-}
-export function semanticFingerprint(content) {
-  return semanticBody(content).replace(/\s+/g, " ");
-}
 
 function section(c, h) {
   const e = h.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -75,6 +30,19 @@ function rows(s) {
     )
     .filter((r) => !r.every((x) => /^[-:]+$/.test(x)));
 }
+export function sectionTableRows(content, heading) {
+  return rows(section(content, heading));
+}
+export function duplicateArtefactRowTypes(content) {
+  const seen = new Set();
+  const duplicates = new Set();
+  for (const [type = ""] of sectionTableRows(content, "Artefacts")) {
+    if (!type || type === "Type") continue;
+    if (seen.has(type)) duplicates.add(type);
+    else seen.add(type);
+  }
+  return [...duplicates];
+}
 function clean(v = "") {
   return v.replace(/^`|`$/g, "").trim();
 }
@@ -172,6 +140,7 @@ export function parseControlState(
     next_allowed_action: field(content, "next_allowed_action"),
     approvals,
     artefacts,
+    artefact_row_duplicates: duplicateArtefactRowTypes(content),
     evidence_refs: mapRows("Evidence", "Evidence", (r) => ({
       evidence: r[0] ?? "",
       source: r[1] ?? "",
@@ -196,6 +165,7 @@ export function parseControlState(
     })),
     context_graph: {
       impact: clean(field(content, "context_graph_impact")),
+      reconciliation: clean(field(content, 'context_graph_reconciliation')),
       refs: field(content, "context_graph_refs"),
       required_action: clean(field(content, "context_graph_required_action")),
       gate_effect: clean(field(content, "context_graph_gate_effect")),

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-state-edits.js

@@ -0,0 +1,170 @@
+import { readFileSync } from "node:fs";
+import { parseRunState } from "./run-state-parser.js";
+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';
+
+// 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_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"],
+  ["AGDF_ARTEFACT_BINDINGS_INVALID", "artefact_bindings_invalid"],
+  ["AGDF_ARTEFACT_BINDINGS_CHANGED", "artefact_bindings_changed"],
+  ["AGDF_STALE_RUN_REVISION", "stale_revision"],
+  ["AGDF_RUN_WRITE_LOCKED", "run_write_locked"],
+  ["AGDF_RUN_APPROVALS_UNRECORDED", "approvals_unrecorded"],
+  ["AGDF_RUN_SEAL_INVALID", "seal_invalid"],
+  ["AGDF_RUN_STATE_INVALID", "run_state_invalid"],
+  ["AGDF_ARTEFACT_ROW_DUPLICATE", "artefact_row_duplicate"],
+  ["AGDF_RUN_STEP_RECOVERY_REQUIRED", "run_step_recovery_required"],
+]);
+
+export function rejected(runId, reason, details = {}) {
+  return Object.freeze({ schema_version: "1", outcome: "rejected", run_id: runId ?? null, reason, ...details });
+}
+
+export function readRun(root, runId) {
+  let path;
+  try {
+    path = runPath(root, runId);
+  } catch {
+    return { rejection: rejected(runId, "run_id_invalid") };
+  }
+  if (existsSync(pendingRunStepPath(root, runId))) {
+    return { rejection: rejected(runId, "run_step_recovery_required", { pending_path: pendingRunStepPath(root, runId) }) };
+  }
+  let content;
+  try {
+    content = readFileSync(path, "utf8");
+  } catch {
+    return { rejection: rejected(runId, "run_missing") };
+  }
+  const parsed = parseRunState(content, runId);
+  if (!parsed.valid) {
+    return { rejection: rejected(runId, "run_state_invalid", { findings: parsed.findings.map((finding) => finding.code) }) };
+  }
+  return { path, content, meta: parsed.meta };
+}
+
+export function guardedWrite(runId, write) {
+  try {
+    return { state: write() };
+  } catch (error) {
+    const reason = WRITE_REJECTIONS.get(error?.message);
+    if (!reason) throw error;
+    return { rejection: rejected(runId, reason, {
+      ...(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 } : {}),
+    }) };
+  }
+}
+
+export function tableCells(line) {
+  return line.split("|").slice(1, -1).map((cell) => cell.trim());
+}
+
+// The table parser splits on every pipe, so cell text must not contain one.
+export function tableLine(cells) {
+  return `| ${cells.map((cell) => String(cell).replaceAll("|", "/").replace(/\r\n?|\n/gu, " ")).join(" | ")} |`;
+}
+
+function padded(cells, width) {
+  return cells.length >= width ? cells : [...cells, ...Array(width - cells.length).fill("")];
+}
+
+export function firstSection(lines, heading) {
+  const pattern = new RegExp(`^## ${heading.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}\\s*$`, "u");
+  const start = lines.findIndex((line) => pattern.test(line));
+  if (start < 0) return null;
+  let end = start + 1;
+  while (end < lines.length && !/^#{1,2} /u.test(lines[end])) end += 1;
+  return { start, end };
+}
+
+// Pure text projection used only by permitted unapproved UR mutation owners.
+export function projectUrObjective(text, urText) {
+  const lines = text.split('\n'), range = firstSection(lines, 'Objective');
+  if (!range || lines.filter(line => /^## Objective\s*$/u.test(line)).length !== 1
+      || !isDecisionContentPlaceholder(lines.slice(range.start + 1, range.end).join('\n').trim())) return text;
+  const goal = authoredGoal(urText);
+  if (!goal) return text;
+  lines.splice(range.start + 1, range.end - range.start - 1, '', goal, '');
+  return lines.join('\n');
+}
+
+export function tableLineIndexes(lines, range) {
+  const indexes = [];
+  for (let index = range.start + 1; index < range.end; index += 1) {
+    if (lines[index].trimStart().startsWith("|")) indexes.push(index);
+  }
+  return indexes;
+}
+
+// Replaces the first `- key:` line anywhere, matching how the parser reads unsectioned fields.
+export function replaceFirstScalar(text, key, value) {
+  const pattern = new RegExp(`^- ${key}:.*$`, "mu");
+  return pattern.test(text) ? text.replace(pattern, () => `- ${key}: ${value}`) : null;
+}
+
+export function replaceSectionScalar(text, heading, key, value) {
+  const lines = text.split("\n");
+  const range = firstSection(lines, heading);
+  if (!range) return null;
+  const prefix = `- ${key}:`;
+  const index = lines.findIndex((line, position) => position > range.start && position < range.end && line.startsWith(prefix));
+  if (index < 0) return null;
+  lines[index] = `${prefix} ${value}`;
+  return lines.join("\n");
+}
+
+// Replaces the rows whose `column` cell equals `key` (keeping extra columns) or appends one row.
+export function upsertTableRow(text, heading, column, key, cells) {
+  const lines = text.split("\n");
+  const range = firstSection(lines, heading);
+  if (!range) return null;
+  const indexes = tableLineIndexes(lines, range);
+  if (indexes.length < 2) return null;
+  const width = tableCells(lines[indexes[0]]).length;
+  const matches = indexes.slice(2).filter((index) => tableCells(lines[index])[column] === key);
+  if (matches.length) {
+    for (const index of matches) lines[index] = tableLine(padded([...cells, ...tableCells(lines[index]).slice(cells.length)], width));
+  } else {
+    lines.splice(indexes.at(-1) + 1, 0, tableLine(padded(cells, width)));
+  }
+  return lines.join("\n");
+}
+
+export function appendTableRow(text, heading, cells) {
+  const lines = text.split("\n");
+  const range = firstSection(lines, heading);
+  if (!range) return null;
+  const indexes = tableLineIndexes(lines, range);
+  if (indexes.length < 2) return null;
+  lines.splice(indexes.at(-1) + 1, 0, tableLine(padded(cells, tableCells(lines[indexes[0]]).length)));
+  return lines.join("\n");
+}
+
+export function removeTableRows(text, heading, column, key) {
+  const lines = text.split("\n");
+  const range = firstSection(lines, heading);
+  if (!range) return null;
+  const doomed = new Set(tableLineIndexes(lines, range).slice(2).filter((index) => tableCells(lines[index])[column] === key));
+  return lines.filter((_, index) => !doomed.has(index)).join("\n");
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-state-parser.js

@@ -0,0 +1,106 @@
+import { scalarFields } 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";
+import { readRunOperations } from "./run-operations.js";
+import { readEvidenceBindings } from './evidence-bindings.js';
+import { readApprovalOperations } from "./approval-operations.js";
+import { REVISION_ID_PATTERN, RUN_ID_PATTERN } from "./run-identity.js";
+import { readSourceRevisions } from "./run-source-revisions.js";
+import { readArtefactBindings } from "./artefact-bindings.js";
+
+export { RUN_ID_PATTERN } from "./run-identity.js";
+export const LIFECYCLES = new Set([
+  "active",
+  "completed",
+  "superseded",
+  "abandoned",
+]);
+
+export function parseRunState(content, expected) {
+  const { values, duplicates } = scalarFields(content),
+    findings = duplicates.map((field) => ({
+      code: "AGDF_RUN_FIELD_DUPLICATE",
+      field,
+    })),
+    id = values.get("run_id") ?? "";
+  if (content.split(/\r?\n/).some((line) => line.trimStart().startsWith("|") && !line.trimEnd().endsWith("|"))) {
+    findings.push({ code: "AGDF_RUN_TABLE_INVALID" });
+  }
+  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" });
+  if (!LIFECYCLES.has(values.get("lifecycle")))
+    findings.push({ code: "AGDF_RUN_LIFECYCLE_INVALID" });
+  if (!/^[1-9]\d*$/.test(values.get("revision") ?? ""))
+    findings.push({ code: "AGDF_RUN_REVISION_INVALID" });
+  const updatedAt = values.get("updated_at");
+  if (updatedAt && (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/u.test(updatedAt)
+      || Number.isNaN(Date.parse(updatedAt)))) {
+    findings.push({ code: "AGDF_RUN_UPDATED_AT_INVALID" });
+  }
+  if (!REVISION_ID_PATTERN.test(values.get("revision_id") ?? ""))
+    findings.push({ code: "AGDF_RUN_REVISION_ID_INVALID" });
+  const operations = readApprovalOperations(content);
+  const effectIds = new Set(), effectRevisions = new Set();
+  let lastEffectRevision = 0;
+  const invalidHistory = operations.receipts.some((receipt) => {
+    const invalid = effectIds.has(receipt.effect.resulting_revision_id) || effectRevisions.has(receipt.effect.revision)
+      || receipt.effect.revision <= lastEffectRevision;
+    effectIds.add(receipt.effect.resulting_revision_id); effectRevisions.add(receipt.effect.revision);
+    lastEffectRevision = receipt.effect.revision;
+    return invalid;
+  });
+  if (!operations.valid || invalidHistory || operations.receipts.some((receipt) => receipt.binding.run_id !== id
+      || receipt.effect.revision > Number(values.get("revision"))
+      || (receipt.effect.revision === Number(values.get("revision")) && receipt.effect.resulting_revision_id !== values.get("revision_id")))) {
+    findings.push({ code: "AGDF_APPROVAL_OPERATIONS_INVALID" });
+  }
+  const revisions = readSourceRevisions(content);
+  const bindings = readArtefactBindings(content);
+  if (!revisions.valid || revisions.receipts.some(row => row.run_id !== id || row.revision > Number(values.get("revision"))
+      || operations.receipts.some(item => item.operation_id === row.operation_id
+        || item.effect.resulting_revision_id === row.resulting_revision_id || item.effect.revision === row.revision)
+      || bindings.receipts.some(item => item.operation.id === row.operation_id
+        || item.operation.resulting_revision_id === row.resulting_revision_id || item.operation.revision === row.revision)
+      || row.invalidated_bindings.some(bindingId => !bindings.receipts.some(item => item.binding_id === bindingId && item.operation.revision < row.revision))
+      || row.revision === Number(values.get("revision")) && row.resulting_revision_id !== values.get("revision_id"))) {
+    findings.push({ code: "AGDF_SOURCE_REVISIONS_INVALID" });
+  }
+  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)
+      : !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 = [
+    ...operations.receipts.map(r => ({ id: r.operation_id, revision: r.effect.revision, next: r.effect.resulting_revision_id })),
+    ...bindings.receipts.map(r => ({ id: r.operation.id, revision: r.operation.revision, next: r.operation.resulting_revision_id })),
+    ...revisions.receipts.map(r => ({ id: r.operation_id, revision: r.revision, next: r.resulting_revision_id })),
+  ];
+  if (!runOperations.valid || runOperations.receipts.some(r => r.run_id !== id
+      || r.effect.revision > Number(values.get("revision"))
+      || r.effect.revision === Number(values.get("revision")) && r.effect.resulting_revision_id !== values.get("revision_id")
+      || existingEffects.some(e => e.id === r.operation_id || e.revision === r.effect.revision || e.next === r.effect.resulting_revision_id))) {
+    findings.push({ code: "AGDF_RUN_OPERATIONS_INVALID" });
+  }
+  return {
+    content,
+    meta: Object.fromEntries(values),
+    findings,
+    valid: !findings.length,
+  };
+}
+export function semanticBody(content) {
+  return content
+    .replace(/^# AGDF Run State\s*/m, "")
+    .replace(/## Run Meta[\s\S]*?(?=\n## )/, "")
+    .trim();
+}
+export function semanticFingerprint(content) {
+  return semanticBody(content).replace(/\s+/g, " ");
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-state-reader.js

@@ -0,0 +1,57 @@
+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";
+
+function invalidRun(runId, path) {
+  return {
+    run_id: runId,
+    path,
+    valid: false,
+    findings: [{ code: "AGDF_RUN_PATH_INVALID", 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));
+}
+
+function discoverCapturedRuns(root) {
+  const dir = join(root, ".agdf", "control", "runs");
+  if (!existsSync(dir)) return [];
+  if (lstatKindSync(dir) !== 'directory') {
+    return [invalidRun("<repository>", dir)];
+  }
+  return readdirSync(dir)
+    .filter((entry) => !entry.startsWith("."))
+    .sort()
+    .map((id) => {
+      const directory = join(dir, id);
+      const path = join(directory, "RUN_STATE.md");
+      const directoryKind = lstatKindSync(directory);
+      if (!RUN_ID_PATTERN.test(id)
+          || directoryKind !== 'directory'
+          || !existsSync(path)) {
+        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(),
+      };
+    });
+}