create-agdf 0.14.4 → 0.20.0

package/runtime/core/lib/control-state/approval-operations.js

@@ -0,0 +1,95 @@
+import { validDecisionMaterial, decisionMaterialVersion } from './decision-material-contract.js';
+import { TextDecoder } from "node:util";
+import { APPROVAL_GATES, REVISION_ID_PATTERN, RUN_ID_PATTERN } from "./run-identity.js";
+import { canonicalJson, COOPERATIVE_ASSURANCE, DIGEST_PATTERN, exactObject } from "./approval-command-contract.js";
+
+const RECEIPT_FIELDS = ["schema_version", "action", "operation_id", "request_digest", "binding", "assurance", "created_at", "producer", "effect"];
+const BINDING_FIELDS = ["target_id", "run_id", "gate", "expected_revision_id", "presentation_id"];
+const EFFECT_FIELDS = ["previous_revision_id", "resulting_revision_id", "revision", "gate", "approval", "artefact_digest", "presentation_digest", "next_gate_after_approval", "allowed_after_approval"];
+
+export function validApprovalReceipt(receipt) {
+  const modern = ['2', '3'].includes(receipt.schema_version);
+  if (!exactObject(receipt, modern ? [...RECEIPT_FIELDS, "command_digest"] : RECEIPT_FIELDS) || !["1", "2", "3"].includes(receipt.schema_version) || receipt.action !== "record_gate_approval"
+      || !REVISION_ID_PATTERN.test(receipt.operation_id ?? "") || !DIGEST_PATTERN.test(receipt.request_digest ?? "")
+      || !exactObject(receipt.binding, BINDING_FIELDS) || !exactObject(receipt.effect, modern ? [...EFFECT_FIELDS, "material_version", "material_sources", ...(receipt.schema_version === '3' ? ['qa_acceptance'] : [])] : EFFECT_FIELDS)
+      || !exactObject(receipt.producer, ["contract", "package_version"])) return false;
+  const binding = receipt.binding, effect = receipt.effect;
+  if (modern && (!DIGEST_PATTERN.test(effect.material_version ?? "") || !validDecisionMaterial(effect.material_sources, binding.run_id) || effect.material_version !== decisionMaterialVersion(binding.run_id, binding.gate, effect.material_sources) || receipt.command_digest !== null && !DIGEST_PATTERN.test(receipt.command_digest ?? ""))) return false;
+  if (receipt.schema_version === '3') {
+    const acceptance = effect.qa_acceptance;
+    if (binding.gate !== 'QA' || !exactObject(acceptance, ['kind', 'digest', 'deviation_ids', 'qa_outcome'])
+      || acceptance.kind !== 'accepted_with_deviations' || acceptance.qa_outcome !== 'revise' || !DIGEST_PATTERN.test(acceptance.digest ?? '')
+      || !Array.isArray(acceptance.deviation_ids) || !acceptance.deviation_ids.length || acceptance.deviation_ids.length > 16
+      || new Set(acceptance.deviation_ids).size !== acceptance.deviation_ids.length
+      || !acceptance.deviation_ids.every(id => /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(id ?? ''))) return false;
+  }
+  return DIGEST_PATTERN.test(binding.target_id ?? "") && RUN_ID_PATTERN.test(binding.run_id ?? "")
+    && APPROVAL_GATES.includes(binding.gate)
+    && [binding.expected_revision_id, binding.presentation_id, effect.resulting_revision_id].every((id) => typeof id === "string" && REVISION_ID_PATTERN.test(id))
+    && effect.previous_revision_id === binding.expected_revision_id && effect.resulting_revision_id !== effect.previous_revision_id
+    && Number.isSafeInteger(effect.revision) && effect.revision >= 2 && effect.gate === binding.gate
+    && effect.approval === `Approval: ${binding.gate}`
+    && (binding.gate === "UAT" ? effect.artefact_digest === null : DIGEST_PATTERN.test(effect.artefact_digest ?? ""))
+    && DIGEST_PATTERN.test(effect.presentation_digest ?? "")
+    && typeof effect.next_gate_after_approval === "string" && effect.next_gate_after_approval.length > 0
+    && typeof effect.allowed_after_approval === "string" && effect.allowed_after_approval.length > 0
+    && canonicalJson(receipt.assurance) === canonicalJson(COOPERATIVE_ASSURANCE)
+    && typeof receipt.created_at === "string" && /^\d{4}-\d{2}-\d{2}T.*Z$/u.test(receipt.created_at) && !Number.isNaN(Date.parse(receipt.created_at))
+    && receipt.producer.contract === "approval-service/1" && typeof receipt.producer.package_version === "string" && receipt.producer.package_version.length > 0;
+}
+
+export function readApprovalOperations(content) {
+  const lines = String(content).replace(/\r\n?/gu, "\n").split("\n");
+  const headings = lines.map((line, index) => /^## Approval Operations\s*$/u.test(line) ? index : -1).filter((index) => index >= 0);
+  if (!headings.length) return { present: false, valid: true, receipts: [] };
+  const invalid = () => ({ present: true, valid: false, receipts: [], reason: "approval_operations_invalid" });
+  if (headings.length !== 1) return invalid();
+  const start = headings[0];
+  let end = start + 1;
+  while (end < lines.length && !/^#{1,2} /u.test(lines[end])) end += 1;
+  const body = lines.slice(start + 1, end).map((line) => line.trim()).filter(Boolean);
+  if (body[0] !== "- schema_version: 1" || body[1] !== "| operation_id | request_digest | receipt |"
+      || !/^\|[-:|\s]+\|$/u.test(body[2] ?? "")) return invalid();
+  const receipts = [], seen = new Set();
+  for (const line of body.slice(3)) {
+    const cells = line.match(/^\| ([^|]+) \| ([^|]+) \| ([A-Za-z0-9_-]+) \|$/u);
+    if (!cells || seen.has(cells[1])) return invalid();
+    try {
+      const bytes = Buffer.from(cells[3], "base64url");
+      const json = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      const receipt = JSON.parse(json);
+      if (bytes.toString("base64url") !== cells[3] || canonicalJson(receipt) !== json || !validApprovalReceipt(receipt)
+          || receipt.operation_id !== cells[1] || receipt.request_digest !== cells[2]) return invalid();
+      seen.add(receipt.operation_id);
+      receipts.push(receipt);
+    } catch { return invalid(); }
+  }
+  return { present: true, valid: true, receipts, start, end };
+}
+
+export function approvalOperationsRecord(content) {
+  const operations = readApprovalOperations(content);
+  if (!operations.valid) throw new Error("AGDF_APPROVAL_OPERATIONS_INVALID");
+  return operations.present ? canonicalJson(operations.receipts) : null;
+}
+
+export function appendApprovalOperation(content, receipt) {
+  const operations = readApprovalOperations(content);
+  if (!operations.valid || !validApprovalReceipt(receipt) || operations.receipts.some((item) => item.operation_id === receipt.operation_id)) {
+    throw new Error("AGDF_APPROVAL_OPERATIONS_INVALID");
+  }
+  const block = ["## Approval Operations", "", "- schema_version: 1", "", "| operation_id | request_digest | receipt |", "|---|---|---|",
+    ...[...operations.receipts, receipt].map((item) => `| ${item.operation_id} | ${item.request_digest} | ${Buffer.from(canonicalJson(item), "utf8").toString("base64url")} |`), ""];
+  if (!operations.present) return `${String(content).trimEnd()}\n\n${block.join("\n")}`;
+  const lines = String(content).replace(/\r\n?/gu, "\n").split("\n");
+  return [...lines.slice(0, operations.start), ...block, ...lines.slice(operations.end)].join("\n");
+}
+
+// Only the approval service can append its one matching receipt. Every other writer preserves it.
+export function assertApprovalOperationsChange(current, candidate, appendedReceipt) {
+  const before = readApprovalOperations(current), after = readApprovalOperations(candidate);
+  if (!before.valid || !after.valid) throw new Error("AGDF_APPROVAL_OPERATIONS_INVALID");
+  const expected = appendedReceipt ? [...before.receipts, appendedReceipt] : before.receipts;
+  if (canonicalJson(after.receipts) !== canonicalJson(expected)
+      || after.present !== (before.present || Boolean(appendedReceipt))) throw new Error("AGDF_APPROVAL_OPERATIONS_CHANGED");
+}

package/runtime/core/lib/control-state/artefact-binding-proof.js

@@ -0,0 +1,90 @@
+import { readFileSync, statSync } from "../control-read/fs.js";
+import { canonicalJson, digest, exactObject } from "./approval-command-contract.js";
+import { readApprovalOperations } from "./approval-operations.js";
+import { artefactFileDigest, APPROVAL_GATES } from "./run-seal-compute.js";
+import { containedRegularFile, hasSymlinkComponent } from "./contained-file.js";
+import { readArtefactBindings } from "./artefact-bindings.js";
+import { readSourceRevisions } from "./run-source-revisions.js";
+import { validateRunPresentationEnvelope } from './run-presentation-envelope.js';
+import { REVIEW_PROOF_FIELDS } from './recording-formats.js';
+import { previewProof } from './preview-snapshot.js';
+import { reviewCorrections } from './presentation-decision.js';
+
+export function readContainedJson(root, path) {
+  const file = containedRegularFile(root, path);
+  if (file.status !== "valid" || hasSymlinkComponent(root, path) || statSync(file.path).size > 131072) throw new Error("AGDF_ARTEFACT_BINDING_PROOF_INVALID");
+  try { return JSON.parse(readFileSync(file.path, "utf8")); }
+  catch { throw new Error("AGDF_ARTEFACT_BINDING_PROOF_INVALID"); }
+}
+
+// Keep the existing aggregate semantics, including legacy receipts and UAT omission.
+export function exactApprovedArtefacts(root, control, options = {}) {
+  if (!readApprovalOperations(control.content).valid || !readSourceRevisions(control.content).valid
+      || !readArtefactBindings(control.content).valid) return false;
+  return APPROVAL_GATES.filter(gate => gate !== 'UAT' && control.approvals.get(gate)?.status === 'approved')
+    .every(gate => inspectApprovedArtefact(root, control, gate, options).confirmed);
+}
+
+export function inspectApprovedArtefact(root, control, gate, { fileDigest = path => artefactFileDigest(root, path), readJson = path => readContainedJson(root, path), historical = false,
+  rawFileDigest = path => {
+    const file = containedRegularFile(root, path);
+    return file.status === "valid" && !hasSymlinkComponent(root, path) && statSync(file.path).size <= 131072 ? digest(readFileSync(file.path)) : "missing";
+  } } = {}) {
+  const unconfirmed = () => ({ confirmed: false, reason: 'approval_proof_unconfirmed' });
+  if (!APPROVAL_GATES.includes(gate) || gate === 'UAT' || control.approvals.get(gate)?.status !== 'approved') return unconfirmed();
+  const operations = readApprovalOperations(control.content);
+  if (!operations.valid) return unconfirmed();
+  const revisions = readSourceRevisions(control.content), bindings = readArtefactBindings(control.content);
+  if (!revisions.valid || !bindings.valid) return unconfirmed();
+  // Receipts keep their recording checkout's target_id; writers bind new commands locally.
+    const row = control.artefacts.get(gate), actual = fileDigest(row?.path);
+    if (!actual.startsWith("sha256:")) return unconfirmed();
+    if (revisions.present && ["PRD", "SD", "TP", "QA"].includes(gate)
+        && !bindings.active.some(binding => binding.destination.type === (gate === "QA" ? "QA_REPORT" : gate) && binding.destination.path === row?.path
+          && binding.destination.digest === actual && validateBindingProof(root, binding, { fileDigest, readJson, historical }))) return unconfirmed();
+    const evidence = control.approvals.get(gate).evidence ?? "";
+    const presentation = evidence.match(/presentation ([0-9a-f-]{36}) (sha256:[0-9a-f]{64})(?:\s|$)/u);
+    if (!presentation) return unconfirmed();
+    const receipt = operations.receipts.filter(item => item.binding.gate === gate && item.binding.presentation_id === presentation[1]);
+    if (receipt.length > 1) return unconfirmed();
+    if (receipt.length === 1) {
+      if (receipt[0].binding.run_id !== control.meta.run_id
+          || receipt[0].effect.artefact_digest !== actual || receipt[0].effect.presentation_digest !== presentation[2]) return unconfirmed();
+      // A review corrected at OR (receipt-proven, presentation-decision.js) counts as the version the approval saw.
+      const corrections = reviewCorrections(control), seen = source => fileDigest(source.path) === source.digest
+        || corrections.get(source.type)?.seen_digest === source.digest && fileDigest(source.path) === corrections.get(source.type).current_digest;
+      if (['2', '3'].includes(receipt[0].schema_version) && !receipt[0].effect.material_sources.every(seen)) return unconfirmed();
+      // The row identifies the exact prepared record, not a historical superseded approval.
+    }
+    let observedRaw;
+    try {
+      const envelope = readJson(`.agdf/control/runs/${control.meta.run_id}/presentations/${presentation[1]}.json`);
+      const record = envelope.record;
+      // Preserve the existing aggregate's v1 proof checks. New v2/v3/v4 envelopes have the
+      // complete command grammar; older minimal proofs are not retroactively v2.
+      if (!record || ![1, 2, 3, 4, 5].includes(record.schema_version)
+          || record.schema_version >= 2 && validateRunPresentationEnvelope(envelope, { runId: control.meta.run_id, gate, revisionId: record.revision_id, presentationId: presentation[1] }).reason
+          || record.presentation_id !== presentation[1] || record.run_id !== control.meta.run_id
+          || record.gate !== gate || record.artefact_digest !== (observedRaw = rawFileDigest(row.path)) || envelope.digest !== presentation[2]
+          || receipt.length === 1 && record.revision_id !== receipt[0].binding.expected_revision_id
+          || digest(JSON.stringify(record)) !== envelope.digest) return unconfirmed();
+      if ([3, 4, 5].includes(record.schema_version) && rawFileDigest(`.agdf/control/runs/${control.meta.run_id}/presentations/${presentation[1]}.document`) !== record.document_digest) return unconfirmed();
+      if (record.schema_version === 5 && !previewProof(record, { rawFileDigest, fileDigest })) return unconfirmed();
+    } catch { return unconfirmed(); }
+  return { confirmed: true, reason: null, path: row.path, artefact_digest: actual, raw_digest: observedRaw };
+}
+
+// Local reviewed attestation: explicit exact mapping, never prose or inferred gate order.
+export function validateBindingProof(root, receipt, { fileDigest = path => artefactFileDigest(root, path), readJson = path => readContainedJson(root, path), historical = false } = {}) {
+  if ([receipt.destination, receipt.source, receipt.review].some(file => !historical && hasSymlinkComponent(root, file.path)
+        || fileDigest(file.path) !== file.digest)) return false;
+  try {
+    const proof = readJson(receipt.review.path);
+    return exactObject(proof, REVIEW_PROOF_FIELDS)
+      && proof.schema_version === "1" && proof.reviewed === true && proof.target_id === receipt.target_id && proof.run_id === receipt.run_id
+      && proof.reviewer === receipt.review.reviewer
+      && canonicalJson(proof.relationship) === canonicalJson(receipt.relationship)
+      && canonicalJson(proof.destination) === canonicalJson(receipt.destination)
+      && canonicalJson(proof.source) === canonicalJson(receipt.source);
+  } catch { return false; }
+}

package/runtime/core/lib/control-state/artefact-bindings.js

@@ -0,0 +1,94 @@
+import { TextDecoder } from "node:util";
+import { canonicalJson, digest, DIGEST_PATTERN, exactObject } from "./approval-command-contract.js";
+import { REVISION_ID_PATTERN, RUN_ID_PATTERN } from "./run-identity.js";
+import { isSafeControlRelativePath } from "./contained-file.js";
+import { deliveryRelationships, sameRelationship } from "../control-evaluation/delivery-relationships.js";
+import { bindingIsEffective } from "./run-source-revisions.js";
+
+const fields = ["schema_version", "binding_id", "target_id", "run_id", "relationship", "destination", "source", "review", "origin", "operation", "supersedes"];
+const text = value => typeof value === "string" && value.trim().length > 0 && value.length <= 4096 && !/[\r\n\0|]/u.test(value);
+const uuid = value => typeof value === "string" && REVISION_ID_PATTERN.test(value);
+const file = (value, keys) => exactObject(value, keys) && text(value.type)
+  && isSafeControlRelativePath(value.path) && DIGEST_PATTERN.test(value.digest ?? "");
+export const artefactBindingDigest = receipt => digest(`agdf-artefact-binding/1\0${canonicalJson(receipt)}`);
+// One current binding per run relationship, whichever checkout recorded it.
+export const artefactBindingKey = receipt => canonicalJson([receipt.run_id, receipt.relationship]);
+
+export function validArtefactBinding(receipt) {
+  if (!exactObject(receipt, fields) || !["1", "2"].includes(receipt.schema_version) || !uuid(receipt.binding_id)
+      || !DIGEST_PATTERN.test(receipt.target_id ?? "") || !RUN_ID_PATTERN.test(receipt.run_id ?? "")
+      || !exactObject(receipt.relationship, ["from", "relationship", "to"])
+      || !file(receipt.destination, ["type", "path", "digest", "status"])
+      || !file(receipt.source, ["type", "path", "digest"])
+      || !exactObject(receipt.review, ["reviewer", "path", "digest"]) || !text(receipt.review.reviewer)
+      || !isSafeControlRelativePath(receipt.review.path) || !DIGEST_PATTERN.test(receipt.review.digest ?? "")
+      || receipt.origin !== "reviewed_mapping" || !exactObject(receipt.operation, ["id", "previous_revision_id", "resulting_revision_id", "revision", ...(receipt.schema_version === "2" ? ["request_digest"] : [])])
+      || receipt.schema_version === "2" && !DIGEST_PATTERN.test(receipt.operation.request_digest ?? "")
+      || ![receipt.operation.id, receipt.operation.previous_revision_id, receipt.operation.resulting_revision_id].every(uuid)
+      || receipt.operation.previous_revision_id === receipt.operation.resulting_revision_id
+      || !Number.isSafeInteger(receipt.operation.revision) || receipt.operation.revision < 2
+      || !(receipt.supersedes === null || uuid(receipt.supersedes))) return false;
+  const expected = deliveryRelationships.find(row => row.requiredBy !== "UR" && sameRelationship(receipt.relationship, row));
+  if (!expected || receipt.destination.type !== expected.from || receipt.source.type !== expected.to) return false;
+  const prefix = `.agdf/control/artefacts/${receipt.run_id}/`;
+  return receipt.destination.path === `${prefix}${expected.from}.md` && receipt.source.path === `${prefix}${expected.to}.md`
+    && receipt.review.path.startsWith(prefix) && receipt.review.path !== receipt.destination.path && receipt.review.path !== receipt.source.path
+    && (expected.requiredBy === "QA" ? ["pass", "revise", "block"].includes(receipt.destination.status) : receipt.destination.status === "draft");
+}
+
+export function readArtefactBindings(content) {
+  const lines = String(content).replace(/\r\n?/gu, "\n").split("\n");
+  const starts = lines.flatMap((line, i) => /^## Artefact Bindings\s*$/u.test(line) ? [i] : []);
+  if (!starts.length) return { present: false, valid: true, receipts: [], active: [], latest: [] };
+  const invalid = () => ({ present: true, valid: false, receipts: [], active: [], reason: "artefact_bindings_invalid" });
+  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] !== "| binding_id | receipt_digest | receipt |"
+      || !/^\|[-:|\s]+\|$/u.test(body[2] ?? "")) return invalid();
+  const receipts = [], active = new Map(), ids = new Set(), operations = new Set();
+  let lastRevision = 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);
+      const receipt = JSON.parse(json);
+      if (bytes.toString("base64url") !== cells[3] || canonicalJson(receipt) !== json || !validArtefactBinding(receipt)
+          || receipt.binding_id !== cells[1] || artefactBindingDigest(receipt) !== cells[2]
+          || ids.has(receipt.binding_id) || operations.has(receipt.operation.id)
+          || receipt.operation.revision <= lastRevision) return invalid();
+      const key = artefactBindingKey(receipt), prior = active.get(key);
+      if (receipt.supersedes !== (prior?.binding_id ?? null)) return invalid();
+      active.set(key, receipt);
+      receipts.push(receipt); ids.add(receipt.binding_id); operations.add(receipt.operation.id);
+      lastRevision = receipt.operation.revision;
+    } catch { return invalid(); }
+  }
+  const latest = [...active.values()];
+  return { present: true, valid: true, receipts, latest, active: latest.filter(receipt => bindingIsEffective(content, receipt)), start, end };
+}
+
+export function appendArtefactBinding(content, receipt) {
+  const prior = readArtefactBindings(content);
+  if (!prior.valid || !validArtefactBinding(receipt)) throw new Error("AGDF_ARTEFACT_BINDINGS_INVALID");
+  const block = ["## Artefact Bindings", "", "- schema_version: 1", "", "| binding_id | receipt_digest | receipt |", "|---|---|---|",
+    ...[...prior.receipts, receipt].map(item => `| ${item.binding_id} | ${artefactBindingDigest(item)} | ${Buffer.from(canonicalJson(item)).toString("base64url")} |`), ""];
+  const lines = String(content).replace(/\r\n?/gu, "\n").split("\n");
+  const candidate = prior.present ? [...lines.slice(0, prior.start), ...block, ...lines.slice(prior.end)].join("\n")
+    : `${String(content).trimEnd()}\n\n${block.join("\n")}`;
+  if (!readArtefactBindings(candidate).valid) throw new Error("AGDF_ARTEFACT_BINDINGS_INVALID");
+  return candidate;
+}
+
+// Only explicit artefact recording can append proof. All other writes preserve the history.
+export function assertArtefactBindingsChange(current, candidate, appendedBinding) {
+  const before = readArtefactBindings(current), after = readArtefactBindings(candidate);
+  if (!before.valid || !after.valid) throw new Error("AGDF_ARTEFACT_BINDINGS_INVALID");
+  const expected = appendedBinding ? [...before.receipts, appendedBinding] : before.receipts;
+  if (canonicalJson(after.receipts) !== canonicalJson(expected)
+      || after.present !== (before.present || Boolean(appendedBinding))) throw new Error("AGDF_ARTEFACT_BINDINGS_CHANGED");
+}

package/runtime/core/lib/control-state/backlog-summary-shape.d.ts

@@ -0,0 +1,4 @@
+export const BACKLOG_SUMMARY_FIELDS: readonly string[];
+export function validBacklogSummary(value: unknown): boolean;
+
+export function validWorkSummary(value: unknown, runId: string): boolean;

package/runtime/core/lib/control-state/backlog-summary-shape.js

@@ -0,0 +1,40 @@
+import { SUMMARY_KINDS } from '../control-evaluation/backlog-vocabulary.js';
+const exactObject = (v, keys) => !!v && typeof v === 'object' && !Array.isArray(v)
+  && Object.keys(v).length === keys.length && keys.every(k => Object.hasOwn(v, k));
+export const BACKLOG_SUMMARY_FIELDS = ['schema_version', 'target_id', 'run_id', 'section', 'row_digest', 'revision_id', 'observed_at',
+  'kind', 'phase', 'qa_outcome', 'lifecycle', 'recorded_approvals', 'decisive_obligation', 'open_obligation_count',
+  'display_action', 'sources', 'limitations', 'authorizes'];
+const id = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/u.test(value);
+const hash = value => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/u.test(value);
+const text = value => typeof value === 'string' && !value.includes('\0');
+const list = value => Array.isArray(value) && value.every(text);
+const sourcePath = value => typeof value === 'string' && value.startsWith('.agdf/control/artefacts/')
+  && !/[\\:%?#\0]/u.test(value) && value.split('/').every(part => part && part !== '.' && part !== '..');
+const sections = ['Active Backlog', 'Planned / Parking Lot', 'Completed / Superseded Pointers'];
+
+export function validBacklogSummary(row) {
+  return exactObject(row, BACKLOG_SUMMARY_FIELDS) && row.schema_version === 1 && hash(row.target_id) && id(row.run_id)
+    && sections.includes(row.section) && hash(row.row_digest)
+    && typeof row.revision_id === 'string' && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u.test(row.revision_id)
+    && text(row.observed_at) && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{3})?Z$/u.test(row.observed_at) && Number.isFinite(Date.parse(row.observed_at))
+    && validWorkSummary(row, row.run_id);
+}
+
+export function validWorkSummary(row, runId) {
+  if (!row || !id(runId)) return false;
+  return SUMMARY_KINDS.includes(row.kind) && text(row.phase)
+    && ['not_applicable', 'missing', 'unconfirmed', 'pass', 'revise', 'block'].includes(row.qa_outcome)
+    && ['active', 'completed', 'superseded', 'abandoned'].includes(row.lifecycle)
+    && list(row.recorded_approvals) && row.recorded_approvals.length <= 6
+    && row.recorded_approvals.every(g => ['UR', 'PRD', 'SD', 'TP', 'QA', 'UAT'].includes(g))
+    && (row.decisive_obligation === null || exactObject(row.decisive_obligation, ['id', 'routing_target', 'action', 'source_path'])
+      && text(row.decisive_obligation.id) && row.decisive_obligation.id.length <= 128
+      && ['UR', 'PRD', 'SD', 'TP', 'CD+Tests', 'evidence_obligation'].includes(row.decisive_obligation.routing_target)
+      && text(row.decisive_obligation.action) && sourcePath(row.decisive_obligation.source_path)
+      && row.decisive_obligation.source_path.startsWith(`.agdf/control/artefacts/${runId}/`))
+    && Number.isSafeInteger(row.open_obligation_count) && row.open_obligation_count >= 0 && row.open_obligation_count <= 64
+    && text(row.display_action) && Array.isArray(row.sources) && row.sources.length <= 64
+    && row.sources.every(s => exactObject(s, ['path', 'digest', 'state']) && sourcePath(s.path)
+      && s.path.startsWith(`.agdf/control/artefacts/${runId}/`) && hash(s.digest) && s.state === 'available')
+    && list(row.limitations) && row.authorizes === false;
+}

package/runtime/core/lib/control-state/backlog-summary.js

@@ -0,0 +1,67 @@
+import { BACKLOG_SUMMARY_FIELDS, validBacklogSummary } from './backlog-summary-shape.js';
+import { createHash } from 'node:crypto';
+import { canonicalJson, resolveControlCommandTarget } from './approval-command-contract.js';
+import { firstSection, tableCells, tableLineIndexes } from './run-state-edits.js';
+import { summaryLabel } from '../control-evaluation/backlog-vocabulary.js';
+
+export const BACKLOG_SUMMARY_LIMIT = 65536;
+const prefix = '<!-- agdf-backlog-summary-v1 ';
+const fields = BACKLOG_SUMMARY_FIELDS;
+const digest = bytes => 'sha256:' + createHash('sha256').update(bytes).digest('hex');
+const sections = ['Active Backlog', 'Planned / Parking Lot', 'Completed / Superseded Pointers'];
+export const backlogRowDigest = (section, cells) => digest(canonicalJson({ section, cells }));
+export { validBacklogSummary } from './backlog-summary-shape.js';
+
+export function decodeBacklogMarker(line) {
+  if (!line.startsWith('<!-- agdf-backlog-summary-')) return null;
+  const match = line.match(/^<!-- agdf-backlog-summary-v1 ([A-Za-z0-9+/]+={0,2}) -->$/u);
+  if (!match || match[1].length > Math.ceil(BACKLOG_SUMMARY_LIMIT / 3) * 4) return { code: 'backlog_summary_invalid', record: null };
+  try {
+    const bytes = Buffer.from(match[1], 'base64');
+    if (bytes.length > BACKLOG_SUMMARY_LIMIT || bytes.toString('base64') !== match[1]) throw Error();
+    const value = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    const record = JSON.parse(value);
+    if (!validBacklogSummary(record) || canonicalJson(record) !== value) throw Error();
+    return { code: null, record };
+  } catch { return { code: 'backlog_summary_invalid', record: null }; }
+}
+export function savedBacklogSummary(root, section, cells, markers) {
+  const key = cells[section === sections[2] ? 0 : 1]?.replaceAll('`', '').trim();
+  const candidates = markers.filter(m => m.record?.run_id === key);
+  const fallback = code => ({ provenance_state: code ? 'invalid' : 'unverified', code, record: null,
+    label_de: null, limitation_de: code ? 'Gespeicherter Quellenbezug ungültig; aktueller Stand nicht geprüft.' : 'Gespeicherter Stand; Quellenbezug und aktueller Run nicht geprüft.', authorizes: false });
+  if (!candidates.length) return fallback(markers.some(m => m.code) ? 'backlog_summary_invalid' : null);
+  const row = candidates[0].record;
+  if (markers.some(m => m.code) || candidates.length !== 1 || row.target_id !== resolveControlCommandTarget(root).target_id
+      || row.section !== section || row.row_digest !== backlogRowDigest(section, cells)) return fallback('backlog_summary_mismatch');
+  return { provenance_state: 'recorded', code: null, record: row, label_de: summaryLabel(row.kind, 'de'),
+    limitation_de: row.limitations.length ? 'Quellenbezug eingeschränkt; aktueller Stand nicht bestätigt.'
+      : 'Gespeicherte Beobachtung; aktueller Run noch nicht verglichen.', authorizes: false };
+}
+
+// Called by existing writers under their locks. Only the addressed marker is replaced.
+export function recordBacklogSummary(root, content, runId, section, summary, revisionId) {
+  if (Buffer.byteLength(content) > 2097152) throw Error('AGDF_BACKLOG_LAYOUT_UNSUPPORTED');
+  const bounded = next => { if (Buffer.byteLength(next) > 2097152) throw Error('AGDF_BACKLOG_LAYOUT_UNSUPPORTED'); return next; };
+  const lines = content.split('\n'), scope = firstSection(lines, section);
+  if (!scope) throw Error('AGDF_BACKLOG_LAYOUT_UNSUPPORTED');
+  const indexes = tableLineIndexes(lines, scope), column = section === sections[2] ? 0 : 1;
+  const matches = indexes.slice(2).filter(i => tableCells(lines[i])[column]?.replaceAll('`', '').trim() === runId);
+  if (matches.length !== 1) throw Error('AGDF_BACKLOG_IDENTITY_AMBIGUOUS');
+  const row = { schema_version: 1, target_id: resolveControlCommandTarget(root).target_id, run_id: runId,
+    section, row_digest: backlogRowDigest(section, tableCells(lines[matches[0]])), revision_id: revisionId,
+    observed_at: new Date().toISOString(), ...Object.fromEntries(fields.slice(7).map(k => [k, summary[k]])) };
+  const previous = lines.map(decodeBacklogMarker).filter(m => m?.record?.run_id === runId);
+  if (previous.length === 1 && canonicalJson({ ...previous[0].record, observed_at: row.observed_at }) === canonicalJson(row)) row.observed_at = previous[0].record.observed_at;
+  const encoded = canonicalJson(row);
+  if (!validBacklogSummary(row) || Buffer.byteLength(encoded) > BACKLOG_SUMMARY_LIMIT) throw Error('AGDF_BACKLOG_SUMMARY_INVALID');
+  // An identical explicit synchronization preserves all bytes, including whitespace and time.
+  if (previous.length === 1 && canonicalJson(previous[0].record) === encoded) return content;
+  if (previous.length === 1 && previous[0].record.section === section) return bounded(lines.map(line =>
+    decodeBacklogMarker(line)?.record?.run_id === runId ? prefix + Buffer.from(encoded).toString('base64') + ' -->' : line).join('\n'));
+  const filtered = lines.filter(line => decodeBacklogMarker(line)?.record?.run_id !== runId);
+  const target = firstSection(filtered, section), table = tableLineIndexes(filtered, target);
+  const afterTable = table.at(-1) + 1;
+  filtered.splice(afterTable, 0, '', prefix + Buffer.from(encoded).toString('base64') + ' -->');
+  return bounded(filtered.join('\n'));
+}

package/runtime/core/lib/control-state/contained-file.js

@@ -0,0 +1,56 @@
+import { lstatKindSync, realpathSync, statSync } from "../control-read/fs.js";
+import { isAbsolute, join, posix, relative, resolve, sep, win32 } from "node:path";
+
+// A control artefact path is stored independently of the current host. Check Windows forms even
+// on POSIX, where `D:foo` would otherwise name an ordinary file inside the checkout.
+export function isSafeControlRelativePath(value) {
+  if (typeof value !== "string" || !value || value === "none" || value.includes("\0")
+      || value.includes("\\") || value.includes(":")) return false;
+  if (isAbsolute(value) || win32.isAbsolute(value) || posix.isAbsolute(value)) return false;
+  const normalized = posix.normalize(value);
+  return normalized !== "." && normalized !== ".." && !normalized.startsWith("../")
+    && normalized === value;
+}
+
+export function hasSymlinkComponent(root, relativePath) {
+  if (!isSafeControlRelativePath(relativePath)) return true;
+  let cursor = root;
+  for (const component of relativePath.split("/")) {
+    cursor = join(cursor, component);
+    try {
+      if (lstatKindSync(cursor) === 'symlink') return true;
+    } catch (error) {
+      // A genuinely absent planned output is safe; unreadable or non-directory ancestors are not.
+      return error.code !== "ENOENT";
+    }
+  }
+  return false;
+}
+
+export function containedRegularFile(root, value) {
+  if (!isSafeControlRelativePath(value)) return { status: "invalid", path: "" };
+  const target = resolve(root, value);
+  const lexical = relative(resolve(root), target);
+  if (!lexical || lexical === ".." || lexical.startsWith(`..${sep}`) || isAbsolute(lexical)) {
+    return { status: "invalid", path: "" };
+  }
+  let realRoot;
+  let realTarget;
+  try {
+    realRoot = realpathSync(root);
+    realTarget = realpathSync(target);
+  } catch {
+    return { status: "missing", path: "" };
+  }
+  const within = relative(realRoot, realTarget);
+  if (!within || within === ".." || within.startsWith(`..${sep}`) || isAbsolute(within)) {
+    return { status: "invalid", path: "" };
+  }
+  try {
+    return statSync(realTarget).isFile()
+      ? { status: "valid", path: realTarget }
+      : { status: "invalid", path: "" };
+  } catch {
+    return { status: "missing", path: "" };
+  }
+}

package/runtime/core/lib/control-state/control-configuration.js

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function inspectControlConfiguration(targetDir) {
+  const control_dir = join(targetDir, ".agdf", "control");
+  const config_path = join(control_dir, "config.json");
+  const base = { control_dir, config_path };
+  if (!existsSync(config_path)) return { ...base, state: "inactive", active: false, diagnostic: "missing_control_config" };
+  try {
+    const config = JSON.parse(readFileSync(config_path, "utf8"));
+    if (!config || typeof config !== "object" || Array.isArray(config)
+        || !["artifact_language", "chat_language", "runtime_language"].every((field) => typeof config[field] === "string" && config[field].trim())) {
+      return { ...base, state: "invalid_control", active: false, diagnostic: "invalid_control_config" };
+    }
+  } catch (error) {
+    return { ...base, state: "invalid_control", active: false, diagnostic: "invalid_control_json", error: error.message };
+  }
+  return { ...base, state: "active", active: true, diagnostic: "valid_control_config" };
+}

package/runtime/core/lib/control-state/decision-action-contract.js

@@ -0,0 +1,32 @@
+import { strictObject, schemaDiagnostics, RUN_COMMAND_LIMITS, RUN_COMMAND_GROUPS } from './run-command-contract.js';
+import { REVISION_ID_PATTERN } from './run-identity.js';
+import { canonicalJson, digest } from './approval-command-contract.js';
+
+import { DECISION_UI_URI } from '../mcp-resource-contract.js';
+export { DECISION_UI_URI };
+export const DECISION_ACTION_GROUPS = Object.freeze({ approve: 'agdf_approve', request_change: 'agdf_record', reject: 'agdf_record' });
+const uuid = { type: 'string', pattern: REVISION_ID_PATTERN.source };
+export function enabledDecisionActions(groups) {
+  if (!Array.isArray(groups) || new Set(groups).size !== groups.length || groups.some(group => !Object.hasOwn(RUN_COMMAND_GROUPS, group))) throw Error('command_group_unsupported');
+  return Object.keys(DECISION_ACTION_GROUPS).filter(action => groups.includes(DECISION_ACTION_GROUPS[action]));
+}
+export function decisionActionSchema(actions = Object.keys(DECISION_ACTION_GROUPS)) {
+  return strictObject({ session_id: uuid, operation_id: uuid, presentation_id: uuid, expected_revision_id: uuid,
+    action: { enum: actions }, comment: { type: 'string', maxLength: 8192 } }, ['session_id', 'operation_id', 'presentation_id', 'expected_revision_id', 'action']);
+}
+export function validateDecisionAction(input, actions = Object.keys(DECISION_ACTION_GROUPS)) {
+  const errors = schemaDiagnostics(input, decisionActionSchema(actions));
+  if (errors.length) return errors;
+  if (input.action === 'request_change' && !input.comment?.trim()) errors.push({ path: '$.comment', code: 'change_comment_required' });
+  if (/\0/u.test(input.comment ?? '')) errors.push({ path: '$.comment', code: 'comment_invalid' });
+  if (Buffer.byteLength(input.comment ?? '') > 8192 || Buffer.byteLength(canonicalJson(input)) > RUN_COMMAND_LIMITS.input_bytes) errors.push({ path: '$.comment', code: 'comment_budget_exceeded' });
+  return errors;
+}
+export function decisionActionDefinition(groups) {
+  const actions = enabledDecisionActions(groups);
+  if (!actions.length) return null;
+  return Object.freeze({ name: 'agdf_decision_action', description: 'App-only deliberate decision of one immutable presentation. Enabled actions: ' + actions.join(', ') + '. Cooperative UI route; technical tool permission is not a gate decision. Preserve original UUID after uncertainty.',
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    inputSchema: decisionActionSchema(actions), _meta: { ui: { resourceUri: DECISION_UI_URI, visibility: ['app'] } } });
+}
+export const decisionActionRequestDigest = (binding, input) => digest(`agdf-app-decision/1\0${canonicalJson({ binding, input })}`);

package/runtime/core/lib/control-state/decision-action-service.js

@@ -0,0 +1,55 @@
+import { withLiveControlReads } from '../control-read/fs.js';
+import { evaluateGateCheck } from '../control-evaluation/gate-check.js';
+import { executeApprovalCommand } from './approval-command.js';
+import { recordRunPresentationDecision } from './run-steps.js';
+import { inspectRunOperation } from './run-operation-status.js';
+import { resolveControlCommandTarget, COOPERATIVE_ASSURANCE } from './approval-command-contract.js';
+import { validateDecisionAction, enabledDecisionActions, decisionActionRequestDigest } from './decision-action-contract.js';
+import { RUN_COMMAND_GROUPS, RUN_COMMAND_LIMITS } from './run-command-contract.js';
+import { observeCurrentRunCommand } from './run-command-service.js';
+
+// Private serving composition. Binding is held by the decision-session owner, never
+// accepted as model/App input. Qualification is package/host evidence, not a gesture credential.
+export function createDecisionActionService({ enabledGroups = Object.keys(RUN_COMMAND_GROUPS), appOnlyMediationQualified = false,
+  packageVersion = '0.14.5', checkpoint = () => {} } = {}) {
+  const actions = enabledDecisionActions(enabledGroups);
+  return (root, binding, input) => withLiveControlReads(() => {
+    const diagnostics = validateDecisionAction(input);
+    const result = (outcome, reason, family = {}) => {
+      let observed;
+      try { observed = inspectRunOperation(root, { runId: binding.run_id, operationId: input.operation_id, targetId: binding.target_id }); } catch {}
+      const receipt = family.receipt ?? observed?.receipt ?? null;
+      const response = { schema_version: '1', outcome, reason: reason ?? null, operation_id: input.operation_id ?? null,
+        receipt, historical_effect: Boolean(family.historical_effect || outcome === 'already_applied'),
+        current: observeCurrentRunCommand(root, { ...binding, presentation_language: binding.presentation_language }),
+        assurance: COOPERATIVE_ASSURANCE, input_route: 'app_only_cooperative', authorizes: false,
+        recovery: outcome === 'effect_unknown' ? 'Inspect operation-status using the original UUID. Preserve the exact original submission; do not create another decision.' : null };
+      return Buffer.byteLength(JSON.stringify(response)) <= RUN_COMMAND_LIMITS.result_bytes ? response
+        : { schema_version: '1', outcome: 'effect_unknown', reason: 'command_result_budget_exceeded', operation_id: input.operation_id, authorizes: false };
+    };
+    // Invalid input never reaches a filesystem owner or an observation based on that input.
+    if (diagnostics.length) return { schema_version: '1', outcome: 'rejected', reason: 'decision_schema_invalid', diagnostics, authorizes: false };
+    if (!actions.includes(input.action)) return result('rejected', 'command_group_disabled');
+    if (!appOnlyMediationQualified) return result('rejected', 'app_only_mediation_not_qualified');
+    if (input.presentation_id !== binding.presentation_id || input.expected_revision_id !== binding.expected_revision_id
+      || resolveControlCommandTarget(root).target_id !== binding.target_id) return result('rejected', 'decision_binding_invalid');
+    const requestDigest = decisionActionRequestDigest(binding, input);
+    let dispatched = false;
+    try {
+      checkpoint('before_dispatch'); dispatched = true;
+      const family = input.action === 'approve'
+        ? executeApprovalCommand(root, { schema_version: '1', action: 'record_gate_approval', target_id: binding.target_id, run_id: binding.run_id,
+          expected_revision_id: binding.expected_revision_id, operation_id: input.operation_id, assurance: 'cooperative_local', gate: binding.gate,
+          presentation_id: binding.presentation_id, response: `Approval: ${binding.gate}` }, { evaluateGateCheck, packageVersion, checkpoint,
+          commandContext: { kind: 'approval.record', operation_id: input.operation_id, target_id: binding.target_id, request_digest: requestDigest } })
+        : recordRunPresentationDecision(root, { runId: binding.run_id, gate: binding.gate, revisionId: binding.expected_revision_id,
+          operationId: input.operation_id, presentationId: binding.presentation_id, action: input.action, comment: input.comment ?? '', requestDigest },
+        { evaluateGateCheck, packageVersion, afterWrite: checkpoint });
+      checkpoint('before_result');
+      return result(['accepted', 'recorded'].includes(family.outcome) ? 'accepted' : family.outcome === 'already_applied' ? 'already_applied'
+        : ['retryable_failure', 'recovery_required'].includes(family.outcome) ? 'effect_unknown' : 'rejected', family.reason, family);
+    } catch (error) {
+      return result(dispatched ? 'effect_unknown' : 'rejected', error.message);
+    }
+  });
+}

package/runtime/core/lib/control-state/decision-material-contract.js

@@ -0,0 +1,12 @@
+import { canonicalJson, digest, DIGEST_PATTERN } from './approval-command-contract.js';
+
+export function validDecisionMaterial(sources, runId) {
+  return Array.isArray(sources) && sources.length > 0 && sources.length <= 12
+    && new Set(sources.map(s => s?.type)).size === sources.length
+    && sources.every(s => s && Object.keys(s).sort().join(',') === 'digest,path,type' && typeof s.type === 'string'
+      && typeof s.path === 'string' && s.path.startsWith(`.agdf/control/artefacts/${runId}/`)
+      && !s.path.includes('..') && DIGEST_PATTERN.test(s.digest ?? ''));
+}
+
+export const decisionMaterialVersion = (runId, gate, sources) => digest(`agdf-decision-material/1\0${canonicalJson({ run_id: runId, gate, sources })}`);
+