create-agdf 0.14.5 → 0.20.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/evidence-bindings.js

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson, digest, exactObject, DIGEST_PATTERN, COOPERATIVE_ASSURANCE } from './approval-command-contract.js';
+import { RUN_ID_PATTERN, REVISION_ID_PATTERN } from './run-identity.js';
+import { isSafeControlRelativePath } from './contained-file.js';
+
+export const EVIDENCE_PREREQUISITES = Object.freeze({
+  ur: [], route: ['UR'], 'Brownfield Review': ['UR'], 'UX Intent Definition': ['UR', 'Brownfield Review'],
+  'Brownfield Analysis': ['UR', 'PRD', 'SD', 'TP', 'Brownfield Review', 'UX Intent Definition'],
+  'CD+Tests': ['UR', 'PRD', 'SD', 'TP', 'Brownfield Analysis'],
+  'TP Review': ['UR', 'PRD', 'SD', 'TP', 'CD+Tests'], 'Clean Implementation Review': ['UR', 'PRD', 'SD', 'TP', 'CD+Tests'],
+  CR: ['UR', 'PRD', 'SD', 'TP', 'CD+Tests'], review: ['UR', 'PRD', 'SD', 'TP', 'CD+Tests'], evidence: ['UR', 'PRD', 'SD', 'TP'],
+  QA: ['UR', 'PRD', 'SD', 'TP', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR'], UAT: ['QA'],
+});
+// Reviews a structured closeout requires (closeout-readiness.js). Gate order and late
+// recording use the same list, so no route can be approved into an unclosable state.
+export const STRUCTURED_REQUIRED_REVIEWS = Object.freeze(['TP Review', 'Clean Implementation Review']);
+// `Clean Review` is the supported legacy name of the Clean Implementation Review row.
+export const reviewArtefactType = (state, step) => step === 'Clean Implementation Review' && !state.artefacts.get(step)?.path
+  && state.artefacts.get('Clean Review')?.path ? 'Clean Review' : step;
+// Reviews whose normalized findings closeout inspects; at OR they may be recorded again only
+// to correct invalid rows (run-operation-proof.js, presentation-decision.js).
+export const CORRECTABLE_REVIEWS = Object.freeze([...STRUCTURED_REQUIRED_REVIEWS, 'CR']);
+export const evidenceSourceSetDigest = sources => digest(`agdf-operation-sources/1\0${canonicalJson(sources)}`);
+export const canonicalEvidenceDigest = text => 'sha256:' + createHash('sha256').update(String(text).replace(/\r\n?/gu, '\n').replace(/^\uFEFF/u, '')).digest('hex');
+const hash = value => typeof value === 'string' && DIGEST_PATTERN.test(value);
+const ownPath = (value, runId) => isSafeControlRelativePath(value) && value.startsWith(`.agdf/control/artefacts/${runId}/`);
+export function validEvidenceBinding(row) {
+  return exactObject(row, ['schema_version', 'run_id', 'operation_id', 'action', 'step', 'report', 'sources', 'source_set_digest', 'producer', 'assurance'])
+    && row.schema_version === '1' && RUN_ID_PATTERN.test(row.run_id ?? '') && REVISION_ID_PATTERN.test(row.operation_id ?? '')
+    && ['step.record', 'artefact.record'].includes(row.action) && Object.hasOwn(EVIDENCE_PREREQUISITES, row.step)
+    && exactObject(row.report, ['path', 'digest']) && ownPath(row.report.path, row.run_id) && hash(row.report.digest)
+    && Array.isArray(row.sources) && row.sources.length === EVIDENCE_PREREQUISITES[row.step].length
+    && row.sources.every((s, i) => exactObject(s, ['type', 'path', 'digest', 'status']) && s.type === EVIDENCE_PREREQUISITES[row.step][i]
+      && (s.path === '' && s.digest === null || ownPath(s.path, row.run_id) && (hash(s.digest) || s.digest === null))
+      && typeof s.status === 'string' && s.status.length <= 128)
+    && hash(row.source_set_digest) && row.source_set_digest === evidenceSourceSetDigest(row.sources)
+    && exactObject(row.producer, ['contract', 'package_version']) && row.producer.contract === 'run-command/1'
+    && typeof row.producer.package_version === 'string' && row.producer.package_version.length > 0 && row.producer.package_version.length <= 128
+    && canonicalJson(row.assurance) === canonicalJson(COOPERATIVE_ASSURANCE);
+}
+export function readEvidenceBindings(content) {
+  const lines = String(content).replace(/\r\n?/gu, '\n').split('\n');
+  const starts = lines.flatMap((line, i) => /^## Evidence Bindings\s*$/u.test(line) ? [i] : []);
+  const invalid = () => ({ present: true, valid: false, bindings: [] });
+  if (!starts.length) return { present: false, valid: true, bindings: [] };
+  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 | binding |' || !/^\|[-:|\s]+\|$/u.test(body[2] ?? '')) return invalid();
+  const bindings = [], ids = new Set();
+  for (const line of body.slice(3)) {
+    const cells = line.match(/^\| ([^|]+) \| ([A-Za-z0-9_-]+) \|$/u);
+    if (!cells || cells[2].length > 32768) return invalid();
+    try {
+      const bytes = Buffer.from(cells[2], 'base64url'), json = new TextDecoder('utf-8', { fatal: true }).decode(bytes), row = JSON.parse(json);
+      if (bytes.toString('base64url') !== cells[2] || canonicalJson(row) !== json || !validEvidenceBinding(row) || row.operation_id !== cells[1] || ids.has(row.operation_id)) return invalid();
+      bindings.push(row); ids.add(row.operation_id);
+    } catch { return invalid(); }
+  }
+  return bindings.length ? { present: true, valid: true, bindings, start, end } : invalid();
+}
+export function appendEvidenceBinding(content, binding) {
+  const before = readEvidenceBindings(content);
+  if (!before.valid || !validEvidenceBinding(binding) || before.bindings.some(row => row.operation_id === binding.operation_id)) throw Error('AGDF_EVIDENCE_BINDINGS_INVALID');
+  const block = ['## Evidence Bindings', '', '- schema_version: 1', '', '| operation_id | binding |', '|---|---|',
+    ...[...before.bindings, binding].map(row => `| ${row.operation_id} | ${Buffer.from(canonicalJson(row)).toString('base64url')} |`), ''];
+  const lines = String(content).split('\n');
+  return before.present ? [...lines.slice(0, before.start), ...block, ...lines.slice(before.end)].join('\n') : `${String(content).trimEnd()}\n\n${block.join('\n')}`;
+}
+export function assertEvidenceBindingsChange(current, candidate, appended) {
+  const before = readEvidenceBindings(current), after = readEvidenceBindings(candidate);
+  if (!before.valid || !after.valid || after.present !== (before.present || Boolean(appended))
+    || canonicalJson(after.bindings) !== canonicalJson(appended ? [...before.bindings, appended] : before.bindings)) throw Error('AGDF_EVIDENCE_BINDINGS_CHANGED');
+}
+
+// Compares the recorded sources of one binding with the current Run. `lateTypes` names
+// dependencies that were recorded as explicitly missing and may since have been recorded
+// (the late required reviews of closeout-readiness.js); every other source must match.
+export function bindingSourceAssociation(row, state, readArtefact, { lateTypes = [], corrections = new Map() } = {}) {
+  for (const source of row.sources) {
+    const now = state.artefacts.get(source.type);
+    // An explicit empty dependency is retained as empty, never presented as a report.
+    if (!source.path && !now?.path && source.status === (now?.status ?? 'missing')) continue;
+    if (lateTypes.includes(source.type) && !source.path && source.digest === null && source.status === 'missing') continue;
+    const text = source.path ? readArtefact(source.path) : undefined;
+    if (source.digest === null || typeof text !== 'string') return { group: 'applicability_unknown', reason: 'source_association_unavailable' };
+    // A proven correction (presentation-decision.js reviewCorrections) of the version this binding saw.
+    const correction = corrections.get(source.type);
+    if (correction && source.digest === correction.seen_digest && now?.path === source.path && now?.status === source.status
+      && canonicalEvidenceDigest(text) === correction.current_digest) continue;
+    if (now?.path !== source.path || now?.status !== source.status || canonicalEvidenceDigest(text) !== source.digest) return { group: 'superseded', reason: 'source_version_superseded' };
+  }
+  return { group: 'current', reason: 'current_exact_association' };
+}
+
+// The read callback is selected by the common Run-state owner (live, immutable archive,
+// or a transaction overlay). Presence and free claims never establish applicability.
+// `lateReviewTypes` names required reviews that the current QA approval provably never saw and
+// `reviewCorrections` the reviews corrected at OR (run-state.js); a QA association stale only
+// through them stays current.
+export function evidenceApplicability(state, readArtefact, { lateReviewTypes = [], reviewCorrections = new Map() } = {}) {
+  const parsed = readEvidenceBindings(state.content), groups = { current: [], superseded: [], applicability_unknown: [] }, byStep = new Map();
+  const latest = new Map(parsed.bindings.map(row => [row.step, row.operation_id]));
+  if (parsed.valid) for (const row of parsed.bindings) {
+    let reason = 'current_exact_association', group = 'current';
+    try {
+      const current = state.artefacts.get(row.step), bytes = readArtefact(row.report.path);
+      if (typeof bytes !== 'string' || canonicalEvidenceDigest(bytes) !== row.report.digest) { group = 'applicability_unknown'; reason = 'recorded_report_unavailable_or_changed'; }
+      else if (current && (current.path !== row.report.path || !['done', 'approved', 'not_applicable', 'pass', 'revise', 'block'].includes(current.status))) { group = 'superseded'; reason = 'report_registration_superseded'; }
+      else {
+        ({ group, reason } = bindingSourceAssociation(row, state, readArtefact));
+        if (row.step === 'QA' && reason === 'source_association_unavailable' && lateReviewTypes.length
+            && bindingSourceAssociation(row, state, readArtefact, { lateTypes: lateReviewTypes }).group === 'current') {
+          group = 'current'; reason = 'current_with_late_unseen_reviews';
+        } else if (row.step === 'QA' && group !== 'current' && reviewCorrections.size
+            && bindingSourceAssociation(row, state, readArtefact, { lateTypes: lateReviewTypes, corrections: reviewCorrections }).group === 'current') {
+          group = 'current'; reason = 'current_with_corrected_reviews';
+        }
+      }
+    } catch { group = 'applicability_unknown'; reason = 'source_observation_unavailable'; }
+    const available = group !== 'applicability_unknown';
+    if (latest.get(row.step) !== row.operation_id) { group = 'superseded'; reason = 'writer_owned_result_superseded'; }
+    const item = { ...row, applicability: group, reason, available };
+    groups[group].push(item); byStep.set(row.step, item);
+  }
+  for (const row of state.evidence_refs ?? []) {
+    const source = String(row.source ?? '').replace(/^`|`$/gu, '');
+    if (!parsed.bindings.some(binding => binding.report.path === source)) groups.applicability_unknown.push({ ...row, applicability: 'applicability_unknown', reason: 'no_writer_owned_association', available: null });
+  }
+  return { valid: parsed.valid, ...groups, by_step: byStep };
+}

package/generated/plugins/agdf/runtime/create-agdf/{lib → runtime/core/lib}/control-state/index.js

@@ -5,3 +5,5 @@ export * from "./run-state-writer.js";
 export * from "./legacy-migration.js";
 export * from "./aggregate.js";
 export * from "./gate-approval-validator.js";
+export * from "./run-seal.js";
+export * from "./run-recording.js";

package/generated/plugins/{copilot/agdf/runtime/create-agdf → agdf/runtime/create-agdf/runtime/core}/lib/control-state/legacy-migration.js

@@ -1,12 +1,10 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, rmdirSync, unlinkSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
+import { renderRunState } from "./run-state-repository.js";
+import { runPath } from "./run-state-reader.js";
 import {
-  discoverRuns,
-  renderRunState,
-  runPath,
-} from "./run-state-repository.js";
-import {
+  normalizeLineEndings,
   parseRunState,
   RUN_ID_PATTERN,
   scalarFields,
@@ -58,7 +56,7 @@ export function migrateLegacy(root, requested, io = {}) {
   return { status: "migrated", path: dest };
 }
 export function renderLegacyProjection(path, root = process.cwd()) {
-  const content = readFileSync(path, "utf8"),
+  const content = normalizeLineEndings(readFileSync(path, "utf8")),
     parsed = parseRunState(content),
     digest = createHash("sha256").update(content).digest("hex");
   if (!parsed.valid) throw Error("AGDF_RUN_NOT_SELECTABLE");
@@ -68,28 +66,4 @@ export function renderLegacyProjection(path, root = process.cwd()) {
 export function writeLegacyProjection(path, canonical) {
   atomicWrite(path, renderLegacyProjection(canonical, resolve(dirname(path), "../..")));
 }
-export function verifyLegacyProjection(root) {
-  const path = join(root, ".agdf", "control", "AGDF_RUN.md");
-  if (!existsSync(path)) return { status: "absent" };
-  const p = readFileSync(path, "utf8"),
-    source = p.match(/canonical_source:\s*(.*?)\s*-->/)?.[1],
-    runId = p.match(/<!-- run_id:\s*(.*?)\s*-->/)?.[1],
-    digest = p.match(/sha256:\s*([0-9a-f]{64})/)?.[1],
-    projectedStart = p.indexOf("# AGDF Run State"),
-    projected = projectedStart >= 0 ? p.slice(projectedStart) : undefined;
-  if (!source || !runId || !digest || projected === undefined)
-    return { status: discoverRuns(root).length ? "mixed_authority" : "legacy" };
-  const target = resolve(root, source.replaceAll("\\", "/")),
-    rel = relative(resolve(root), target),
-    expected = relative(resolve(root), resolve(runPath(root, runId)));
-  if (rel.startsWith("..") || !rel || rel !== expected || !existsSync(target))
-    return { status: "projection_source_invalid" };
-  const canonical = readFileSync(target, "utf8"),
-    canonicalDigest = createHash("sha256").update(canonical).digest("hex");
-  return {
-    status:
-      canonicalDigest === digest && projected === canonical
-        ? "valid"
-        : "legacy_projection_drift",
-  };
-}
+export { verifyLegacyProjection } from "./legacy-projection-reader.js";

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/legacy-projection-reader.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "../control-read/fs.js";
+import { join, relative, resolve } from "node:path";
+import { normalizeLineEndings } from "./run-state-parser.js";
+import { discoverRuns, runPath } from "./run-state-reader.js";
+
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export function verifyLegacyProjection(root) {
+  const path = join(root, ".agdf", "control", "AGDF_RUN.md");
+  if (!existsSync(path)) return { status: "absent" };
+  const projection = normalizeLineEndings(readFileSync(path, "utf8"));
+  const source = projection.match(/canonical_source:\s*(.*?)\s*-->/)?.[1];
+  const runId = projection.match(/<!-- run_id:\s*(.*?)\s*-->/)?.[1];
+  const digest = projection.match(/sha256:\s*([0-9a-f]{64})/)?.[1];
+  const projectedStart = projection.indexOf("# AGDF Run State");
+  const projected = projectedStart >= 0 ? projection.slice(projectedStart) : undefined;
+  if (!source || !runId || !digest || projected === undefined) {
+    return { status: discoverRuns(root).length ? "mixed_authority" : "legacy" };
+  }
+  const target = resolve(root, source.replaceAll("\\", "/"));
+  const targetRelative = relative(resolve(root), target);
+  const expected = relative(resolve(root), resolve(runPath(root, runId)));
+  if (targetRelative.startsWith("..") || !targetRelative || targetRelative !== expected || !existsSync(target)) {
+    return { status: "projection_source_invalid" };
+  }
+  const canonical = normalizeLineEndings(readFileSync(target, "utf8"));
+  // Git checkouts may convert line endings (core.autocrlf), and projections rendered from a CRLF
+  // checkout carry a CRLF digest, so the digest identifies the content independent of line endings.
+  const digestMatches = [canonical, canonical.replaceAll("\n", "\r\n")].some((text) => sha256(text) === digest);
+  return {
+    status: digestMatches && projected === canonical
+      ? "valid"
+      : "legacy_projection_drift",
+  };
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/presentation-decision.js

@@ -0,0 +1,138 @@
+import { readFileSync, statSync } from '../control-read/fs.js';
+import { canonicalJson, digest } from './approval-command-contract.js';
+import { canonicalRunText } from './run-text.js';
+import { containedRegularFile } from './contained-file.js';
+import { readRunOperations } from './run-operations.js';
+import { readApprovalOperations } from './approval-operations.js';
+import { READ_LIMITS } from '../control-read/snapshot.js';
+import { STRUCTURED_REQUIRED_REVIEWS, CORRECTABLE_REVIEWS } from './evidence-bindings.js';
+import { decisionMaterialVersion } from './decision-material-contract.js';
+
+export const decisionRemediationOwner = gate => ({ UR: 'ur-definition', PRD: 'prd-definition', SD: 'sd-definition', TP: 'tp-definition', QA: 'qa-gate', UAT: 'delivery-closeout' })[gate] ?? null;
+const prerequisiteTypes = {
+  UR: ['UR'], PRD: ['UR', 'PRD'],
+  SD: ['UR', 'PRD', 'SD'],
+  TP: ['UR', 'PRD', 'SD', 'TP'],
+  QA: ['UR', 'PRD', 'SD', 'TP', 'Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR', 'QA'],
+  UAT: ['UR', 'PRD', 'SD', 'TP', 'Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR', 'QA'],
+};
+
+// Version is actual material, not a new envelope, recording UUID, Run revision or comment.
+// Archived/proposed state supplies its own byte reader; it cannot adopt current bytes.
+export function decisionMaterial(root, state, gate, { readArtefact } = {}) {
+  const types = prerequisiteTypes[gate];
+  if (!types || !state.run_id) return { available: false, reason: 'decision_material_unavailable' };
+  const sources = [];
+  try {
+    for (const type of types) {
+      const row = state.artefacts.get(type) ?? state.artefacts.get({ CR: 'Code Review', 'Clean Implementation Review': 'Clean Review' }[type]);
+      if (!row?.path) { if (type === gate || gate === 'UAT' && type === 'QA') throw Error(); continue; }
+      let content;
+      if (readArtefact) content = readArtefact(row.path);
+      else { const file = containedRegularFile(root, row.path); if (file.status !== 'valid' || statSync(file.path).size > READ_LIMITS.file) throw Error(); content = readFileSync(file.path, 'utf8'); }
+      if (typeof content !== 'string' || !content.trim() || Buffer.byteLength(content) > READ_LIMITS.file) throw Error();
+      sources.push({ type, path: row.path, digest: digest(canonicalRunText(content)) });
+    }
+    const material = { run_id: state.run_id, gate, sources };
+    return { available: true, ...material, material_version: digest(`agdf-decision-material/1\0${canonicalJson(material)}`) };
+  } catch { return { available: false, reason: 'decision_material_unavailable' }; }
+}
+
+export { validDecisionMaterial, decisionMaterialVersion } from './decision-material-contract.js';
+
+export function projectPresentationDecision(state, gate, material) {
+  if (!material.available) return { available: false, decided: false, reason: material.reason };
+  const internal = readRunOperations(state.content), approvals = readApprovalOperations(state.content);
+  if (!internal.valid || !approvals.valid) return { available: false, decided: false, reason: 'decision_receipts_invalid' };
+  const approval = state.approvals.get(gate), currentPresentation = approval?.evidence?.match(/presentation ([0-9a-f-]{36}) /u)?.[1];
+  const decisions = [
+    ...internal.receipts.filter(r => r.kind === 'presentation_decision.record' && r.effect.record.gate === gate && r.effect.record.material_version === material.material_version)
+      .map(receipt => ({ action: receipt.effect.record.action, receipt, owner: receipt.effect.record.owner })),
+    ...approvals.receipts.filter(r => ['2', '3'].includes(r.schema_version) && r.binding.gate === gate && r.effect.material_version === material.material_version
+      && approval?.status === 'approved' && r.binding.presentation_id === currentPresentation)
+      .map(receipt => ({ action: 'approve', receipt, owner: null })),
+  ];
+  if (decisions.length > 1) return { available: false, decided: true, reason: 'decision_version_ambiguous', material_version: material.material_version };
+  return { available: true, decided: decisions.length === 1, material_version: material.material_version, sources: material.sources,
+    ...(decisions[0] ?? {}), authorizes: false };
+}
+
+export function presentationDecisionState(root, state, gate, options = {}) {
+  return projectPresentationDecision(state, gate, decisionMaterial(root, state, gate, options));
+}
+
+// The material receipt of the current approval of a gate, located by its presentation id.
+function currentApprovalReceipt(state, gate, operations = readApprovalOperations(state.content ?? '')) {
+  const id = state.approvals?.get(gate)?.evidence?.match(/presentation ([0-9a-f-]{36}) /u)?.[1];
+  return operations.receipts.find(r => ['2', '3'].includes(r.schema_version) && r.binding.gate === gate && r.binding.presentation_id === id) ?? null;
+}
+
+// Material types of the current approval of a gate: 'recorded' with its receipt's source
+// types, 'unrecorded' for an approval without a material receipt (legacy), or 'invalid'
+// when the receipts cannot be read. Callers fail closed on 'invalid'.
+export function approvalMaterialTypes(state, gate) {
+  const approval = state.approvals?.get(gate);
+  if (approval?.status !== 'approved') return { status: 'unapproved', types: new Set() };
+  const operations = readApprovalOperations(state.content ?? '');
+  if (!operations.valid) return { status: 'invalid', types: new Set() };
+  const receipt = currentApprovalReceipt(state, gate, operations);
+  return receipt ? { status: 'recorded', types: new Set(receipt.effect.material_sources.map(source => source.type)) } : { status: 'unrecorded', types: new Set() };
+}
+
+// For each review: the version the approvals saw (its last step receipt before the current
+// UAT approval; CR includes the quick-task review step) and every later recording. Missing
+// or invalid ledgers, or a UAT approval without a material receipt, prove nothing.
+function reviewRecordingChains(state) {
+  const chains = new Map();
+  if (state.approvals?.get('UAT')?.status !== 'approved') return chains;
+  const approvals = readApprovalOperations(state.content ?? ''), operations = readRunOperations(state.content ?? '');
+  const uat = approvals.valid ? currentApprovalReceipt(state, 'UAT', approvals) : null;
+  if (!uat || !operations.valid) return chains;
+  for (const type of CORRECTABLE_REVIEWS) {
+    const steps = operations.receipts.filter(r => r.kind === 'step.record' && (r.effect.record.step === type || type === 'CR' && r.effect.record.step === 'review'));
+    const seen = steps.filter(r => r.effect.revision < uat.effect.revision).at(-1)?.effect.record;
+    if (seen) chains.set(type, { seen, later: steps.filter(r => r.effect.revision > uat.effect.revision).map(r => r.effect.record) });
+  }
+  return chains;
+}
+export const reviewRecordingChain = (state, type) => reviewRecordingChains(state).get(type) ?? null;
+
+// After Approval: UAT a review can be recorded only through the OR correction path or the
+// D4 late path, so later receipts at the same path with the status of the version the
+// approvals saw prove a correction. Maps type -> { seen_digest, current_digest }.
+export function reviewCorrections(state) {
+  const corrections = new Map();
+  for (const [type, { seen, later }] of reviewRecordingChains(state)) {
+    const current = later.at(-1), row = state.artefacts?.get(type);
+    if (!current || later.some(record => record.status !== seen.status || record.source.path !== seen.source.path)
+      || row?.path !== current.source.path || row.status !== current.status) continue;
+    corrections.set(type, { seen_digest: seen.source.digest, current_digest: current.source.digest });
+  }
+  return corrections;
+}
+
+// Only a positively matched current row/receipt is tested. Legacy approvals are
+// not retrospectively assigned a material/source association they never recorded.
+export function approvedMaterialFindings(state, decisions) {
+  const receipts = readApprovalOperations(state.content).receipts, corrections = reviewCorrections(state);
+  return [...state.approvals].flatMap(([gate, approval]) => {
+    if (approval.status !== 'approved') return [];
+    const id = approval.evidence?.match(/presentation ([0-9a-f-]{36}) /u)?.[1];
+    const receipt = receipts.find(r => ['2', '3'].includes(r.schema_version) && r.binding.gate === gate && r.binding.presentation_id === id);
+    if (!receipt) return [];
+    const material = decisions.get(gate);
+    if (material?.available && material.material_version === receipt.effect.material_version) return [];
+    // A required review the approval never saw (absent from its recorded material) may be
+    // recorded later for closeout, and a proven correction of a review it saw is compared as
+    // the version it saw; everything else the approval saw must still match exactly.
+    const seen = new Set(receipt.effect.material_sources.map(source => source.type));
+    const unseenReviews = source => STRUCTURED_REQUIRED_REVIEWS.includes(source.type) && !seen.has(source.type);
+    const corrected = source => {
+      const correction = corrections.get(source.type);
+      return correction && source.digest === correction.current_digest ? { ...source, digest: correction.seen_digest } : source;
+    };
+    const exempt = material?.available
+      && decisionMaterialVersion(state.run_id, gate, material.sources.filter(source => !unseenReviews(source)).map(corrected)) === receipt.effect.material_version;
+    return exempt ? [] : [{ gate, reason: 'approved_material_sources_changed', operation_id: receipt.operation_id }];
+  });
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/preview-render.js

@@ -0,0 +1,130 @@
+import { parse, serialize } from 'parse5';
+import postcss from 'postcss';
+import { posix } from 'node:path';
+
+export const PREVIEW_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; connect-src 'none'; worker-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
+export const PREVIEW_RENDER_LIMIT = 2 * 1024 ** 2;
+const fail = reason => { throw Error(`preview_${reason}`); };
+const decode = bytes => { try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { fail('encoding_invalid'); } };
+const dataUrl = file => `data:${file.media_type};base64,${file.data.toString('base64')}`;
+const attr = (node, name) => node.attrs?.find(a => a.name === name)?.value;
+const set = (node, name, value) => { const a = node.attrs?.find(a => a.name === name); if (a) a.value = value; else (node.attrs ??= []).push({ name, value }); };
+const children = node => node.childNodes ?? [];
+const walk = (node, fn) => { fn(node); for (const child of children(node)) walk(child, fn); if (node.content) walk(node.content, fn); };
+const replace = (node, tag, content) => {
+  node.tagName = node.nodeName = tag; node.attrs = (node.attrs ?? []).filter(a => ['id', 'media'].includes(a.name));
+  node.childNodes = [{ nodeName: '#text', value: content, parentNode: node }];
+};
+
+// One deliberately bounded resource grammar. Ambiguous/unsupported syntax fails,
+// rather than silently omitting a resource needed for the user's review.
+export function renderPreview(descriptor, files) {
+  const resources = new Map(files.map(file => [file.path, file]));
+  const styles = new Map();
+  let embeddedBytes = 0;
+  const embed = value => {
+    embeddedBytes += Buffer.byteLength(value);
+    if (embeddedBytes > PREVIEW_RENDER_LIMIT) fail('render_limit');
+    return value;
+  };
+  const local = (url, from, types) => {
+    if (typeof url !== 'string' || !url || /[%\\\s?#<>"']/u.test(url) || url.startsWith('/') || /^[a-z][a-z0-9+.-]*:/iu.test(url)) fail('resource_unsupported');
+    const path = posix.join(posix.dirname(from), url), prefix = posix.dirname(descriptor.entry) + '/';
+    const file = resources.get(path);
+    if (!path.startsWith(prefix) || !file || !types.includes(file.media_type)) fail('resource_undeclared');
+    return file;
+  };
+  const css = (source, from, stack = []) => {
+    if (stack.includes(from) || stack.length > 32) fail('resource_cycle');
+    const cached = styles.get(from);
+    if (cached?.source === source) return cached.code;
+    let resolvedBytes = 0;
+    const reserve = value => {
+      resolvedBytes += Buffer.byteLength(value);
+      if (resolvedBytes > PREVIEW_RENDER_LIMIT) fail('render_limit');
+      return value;
+    };
+    let tree;
+    try { tree = postcss.parse(source, { from: undefined }); } catch { fail('css_invalid'); }
+    // Resolve this file's declarations before inserting already-resolved imports.
+    // Imported image URLs must neither be re-resolved as local paths nor counted twice.
+    tree.walkDecls(decl => {
+      if (/\\|\/\*/u.test(decl.value)) fail('resource_unsupported');
+      decl.value = decl.value.replace(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^\s()"']+))\s*\)/giu, (all, a, b, c) => {
+        const url = a ?? b ?? c;
+        if (/^#[A-Za-z][\w.-]*$/u.test(url)) return `url("${url}")`;
+        return reserve(`url("${dataUrl(local(url, from, ['image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/svg+xml']))}")`);
+      });
+      // Every surviving url must be one of the generated data URLs or local SVG fragments.
+      if (/url\s*\(/iu.test(decl.value.replace(/url\("(?:data:image\/[\w+.-]+;base64,[A-Za-z0-9+/=]+|#[\w.-]+)"\)/gu, ''))) fail('resource_unsupported');
+    });
+    tree.walkAtRules(rule => {
+      if (rule.name.toLowerCase() === 'import') {
+        const match = rule.params.match(/^(?:["']([^"']+)["']|url\(\s*["']?([^"'()\s]+)["']?\s*\))$/iu);
+        if (!match) fail('resource_unsupported');
+        const file = local(match[1] ?? match[2], from, ['text/css']);
+        const code = reserve(css(decode(file.data), file.path, [...stack, from]));
+        rule.replaceWith(postcss.parse(code).nodes);
+      } else if (/url\s*\(|\\/iu.test(rule.params)) fail('resource_unsupported');
+    });
+    const code = tree.toString();
+    if (Buffer.byteLength(code) > PREVIEW_RENDER_LIMIT) fail('render_limit');
+    styles.set(from, { source, code });
+    return code;
+  };
+  const doc = parse(decode(resources.get(descriptor.entry).data));
+  walk(doc, node => {
+    if (!node.tagName) return;
+    const tag = node.tagName.toLowerCase();
+    if (['base', 'iframe', 'frame', 'frameset', 'object', 'embed', 'form', 'portal', 'foreignobject', 'template'].includes(tag)) fail('markup_unsupported');
+    for (const a of node.attrs ?? []) {
+      if (['srcset', 'srcdoc', 'action', 'formaction', 'ping', 'target', 'download', 'manifest', 'poster', 'background'].includes(a.name)
+        || a.name.startsWith('on') || a.name.includes(':') || a.name === 'xmlns') fail('markup_unsupported');
+    }
+    if (tag === 'meta' && attr(node, 'http-equiv') !== undefined) fail('markup_unsupported');
+    if (tag === 'script') {
+      if (attr(node, 'type') && !['text/javascript', 'application/javascript'].includes(attr(node, 'type').toLowerCase())
+        || ['async', 'defer', 'nomodule', 'integrity', 'crossorigin'].some(name=>attr(node,name)!==undefined)) fail('script_unsupported');
+      const src = attr(node, 'src');
+      const code = src ? decode(local(src, descriptor.entry, ['text/javascript']).data) : children(node).map(c => c.value ?? '').join('');
+      // Raw script closing tags cannot be safely embedded from separate files.
+      if (/<\/script/iu.test(code)) fail('script_unsupported');
+      replace(node, 'script', embed(code));
+    } else if (tag === 'link') {
+      if (attr(node, 'rel')?.toLowerCase() !== 'stylesheet' || !attr(node, 'href')) fail('resource_unsupported');
+      const file = local(attr(node, 'href'), descriptor.entry, ['text/css']);
+      const code = css(decode(file.data), file.path);
+      if (/<\/style/iu.test(code)) fail('markup_unsupported');
+      replace(node, 'style', embed(code));
+    } else if (tag === 'style') {
+      const code = css(children(node).map(c => c.value ?? '').join(''), descriptor.entry);
+      if (/<\/style/iu.test(code)) fail('markup_unsupported');
+      replace(node, 'style', embed(code));
+    } else {
+      if (attr(node, 'src') !== undefined) {
+        if (tag !== 'img') fail('resource_unsupported');
+        set(node, 'src', embed(dataUrl(local(attr(node, 'src'), descriptor.entry, ['image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/svg+xml']))));
+      }
+      if (attr(node, 'href') !== undefined && !/^#[A-Za-z][\w.-]*$/u.test(attr(node, 'href'))) fail('navigation_unsupported');
+    }
+    if (attr(node, 'style') !== undefined) set(node, 'style', embed(css(attr(node, 'style'), descriptor.entry)));
+  });
+  // Extra declared source files still bind exact bytes. They cannot be resolved by
+  // authored dynamic paths; the CSP grants no file/network access.
+  const head = children(children(doc).find(n => n.tagName === 'html')).find(n => n.tagName === 'head');
+  const meta = { nodeName: 'meta', tagName: 'meta', namespaceURI: 'http://www.w3.org/1999/xhtml', attrs: [
+    { name: 'http-equiv', value: 'Content-Security-Policy' }, { name: 'content', value: PREVIEW_CSP },
+  ], childNodes: [], parentNode: head };
+  head.childNodes.unshift(meta);
+  const body = children(children(doc).find(n => n.tagName === 'html')).find(n => n.tagName === 'body');
+  const ready = { nodeName: 'script', tagName: 'script', namespaceURI: 'http://www.w3.org/1999/xhtml', attrs: [], parentNode: body,
+    childNodes: [{ nodeName: '#text', value: 'addEventListener("message",e=>{if(e.source===parent&&e.data?.type==="agdf-preview-ping")parent.postMessage({type:"agdf-preview-content-ready"},"*")});parent.postMessage({type:"agdf-preview-content-ready"},"*")' }] };
+  ready.childNodes[0].parentNode = ready;
+  body.childNodes.push(ready);
+  const source = serialize(doc).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+  // The standalone snapshot carries its own opaque-origin frame too. Opening the
+  // retained view in a browser never gives authored scripts file-page authority.
+  const html = '<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="default-src \'none\'; frame-src about:; img-src data:; script-src \'unsafe-inline\'; style-src \'unsafe-inline\'; object-src \'none\'; base-uri \'none\'; form-action \'none\'"><meta name="viewport" content="width=device-width,initial-scale=1"><style>html,body{margin:0}iframe{display:block;width:100%;height:96vh;border:0}</style></head><body><iframe title="Illustrative preview" sandbox="allow-scripts" referrerpolicy="no-referrer" srcdoc="' + source + '"></iframe><script>const f=document.querySelector("iframe");let timer;f.addEventListener("load",()=>{clearTimeout(timer);timer=setTimeout(()=>parent.postMessage({type:"agdf-preview-unavailable"},"*"),300);f.contentWindow.postMessage({type:"agdf-preview-ping"},"*")});addEventListener("message",e=>{if(e.source===f.contentWindow&&e.data?.type==="agdf-preview-content-ready"){clearTimeout(timer);parent.postMessage({type:"agdf-preview-ready"},"*")}})</script></body></html>';
+  if (Buffer.byteLength(html) > PREVIEW_RENDER_LIMIT) fail('render_limit');
+  return html;
+}