create-agdf 0.20.2 → 0.31.0

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

@@ -1,16 +1,21 @@
+import { PRESENTATION_RECORD_VERSION } from './run-presentation-envelope.js';
+import { assertInputConfigurationCurrent } from '../resources/configuration.js';
+import { bindInputResolution } from './input-resolution.js';
+import { resolutionRecordVersion } from './input-resolution.js';
 import { validateRunPresentationEnvelope, PRESENTATION_ID_PATTERN as UUID, PRESENTATION_RECOVERY as recovery } from "./run-presentation-envelope.js";
 export { validateRunPresentationEnvelope } from "./run-presentation-envelope.js";
 import { randomUUID } from "node:crypto";
 import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, existsSync, openSync, opendirSync, readSync, writeFileSync } from "node:fs";
-import { fsyncDirectory } from "./run-state-writer.js";
+import { fsyncDirectory, withOwnedFileLock } from "./run-state-writer.js";
+import { withControlMutation, markControlMutationEffect } from './control-layout.js';
 import { dirname, join } from "node:path";
 import { TextDecoder } from 'node:util';
 import { runPath } from "./run-state-reader.js";
-import { readRun, rejected } from "./run-state-edits.js";
+import { readRun, rejected, endedRunRejection } from "./run-state-edits.js";
 import { APPROVAL_GATES, runSealState } from "./run-seal.js";
 import { hash } from "./run-presentation-render.js";
 import { resolveControlCommandTarget } from './approval-command-contract.js';
-import { REVISION_ID_PATTERN } from './run-identity.js';
+import { REVISION_ID_PATTERN, RUN_ID_PATTERN } from './run-identity.js';
 import { prepareRunContentState } from '../control-evaluation/run-state.js';
 import { previewForState } from './preview-review.js';
 import { previewSnapshotBinding, publishPreviewSnapshot, readPreviewSnapshot, validateCurrentPreviewRecord } from './preview-snapshot.js';
@@ -62,7 +67,7 @@ function binding(root, { runId, gate, revisionId, language, presentationId }, ev
       || report.approval_presentation?.revision_id !== revisionId || !text) throw new Error("approval_presentation_unavailable");
   const preview = gate === 'PRD' ? previewForState(root, prepareRunContentState(root, run.content, run.path)) : null;
   if (preview) {
-    const path = join(root, '.agdf', 'control', 'runs', runId, 'presentations', `${presentationId}.preview.html`);
+    const path = join(root, '.agdf', 'control', 'runs', runId, 'control', 'presentations', `${presentationId}.preview.html`);
     if (/[<>\r\n]/u.test(path)) throw Error('preview_path_unsafe');
     const german = language?.startsWith('de');
     text += `\n\n[${german ? 'Geprüfte Vorschau öffnen' : 'Open checked preview'} · ${preview.descriptor.version}](<${path}>)`;
@@ -71,18 +76,26 @@ function binding(root, { runId, gate, revisionId, language, presentationId }, ev
     artefact_digest: artefactPresentation.artefact_digest,
     summary_digest: artefactPresentation.summary_digest,
     presentation_language: report.approval_presentation.presentation_language, presentation_digest: hash(text), text,
-    document_content: artefactPresentation.document_content,
+    document_content: text,
     summary: artefactPresentation.summary_markdown,
     companion_text: artefactPresentation.companion_markdown,
     document_language: artefactPresentation.document_language,
-    document_digest: hash(artefactPresentation.document_content),
-    document_bytes: Buffer.byteLength(artefactPresentation.document_content, 'utf8'),
+    document_digest: hash(text),
+    document_bytes: Buffer.byteLength(text, 'utf8'),
     ...(preview ? { preview_review: previewSnapshotBinding(preview, runId, presentationId), preview_content: preview } : {}),
     ...(artefactPresentation.qa_acceptance ? { qa_acceptance: artefactPresentation.qa_acceptance } : {}) };
 }
 
 // Evidence of a prepared presentation, NOT a signature or proof of human visibility.
 export function prepareRunPresentation(root, input, { evaluateGateCheck, checkpoint = () => {} }) {
+  if (!RUN_ID_PATTERN.test(input.runId ?? '')) return rejected(input.runId, 'run_id_invalid');
+  return withOwnedFileLock(join(dirname(runPath(root, input.runId)), '.presentation'), () => withControlMutation(root, {
+    resource: `presentation:${input.runId}`, operation_id: input.operationId ?? null, resume: true,
+    proveOutcome: result => ['prepared', 'already_prepared'].includes(result?.outcome),
+  }, () => prepareRunPresentationAdmitted(root, input, { evaluateGateCheck, checkpoint })));
+}
+function prepareRunPresentationAdmitted(root, input, { evaluateGateCheck, checkpoint }) {
+  let effectStarted = false;
   const { runId, gate, operationId, requestDigest } = input;
   if (!APPROVAL_GATES.includes(gate)) return rejected(runId, "gate_invalid");
   if (operationId !== undefined && (!UUID.test(operationId) || !/^sha256:[0-9a-f]{64}$/u.test(requestDigest ?? ""))) return rejected(runId, "operation_binding_invalid");
@@ -90,7 +103,7 @@ export function prepareRunPresentation(root, input, { evaluateGateCheck, checkpo
     const presentationId = operationId ?? randomUUID();
     input = { ...input, presentationId };
     if (operationId) {
-      const dir = join(checkedRunDirectory(root, runId), "presentations");
+      const dir = join(checkedRunDirectory(root, runId), 'control', 'presentations');
       const path = join(dir, `${operationId}.json`);
       if (existsSync(path)) {
         const previous = validateRunPresentationRecord(root, { runId, gate, revisionId: input.revisionId, presentationId: operationId });
@@ -101,12 +114,18 @@ export function prepareRunPresentation(root, input, { evaluateGateCheck, checkpo
           text, summary, companion_text: companion, historical_effect: true, next_action: text ? "Show the exact current text before waiting for a new deliberate reply." : "Observe current control; this historical preparation cannot authorize a current decision." });
       }
     }
+    const current = readRun(root, runId), ended = current.rejection ? null : endedRunRejection(runId, current.content);
+    if (ended) return ended;
     const prepared = binding(root, input, evaluateGateCheck);
-    const dir = join(checkedRunDirectory(root, runId), "presentations");
+    const dir = join(checkedRunDirectory(root, runId), 'control', 'presentations');
+    assertInputConfigurationCurrent(root);
+    const control = dirname(dir);
+    if (!existsSync(control)) { mkdirSync(control); fsyncDirectory(dirname(control)); }
+    directory(control);
     try { mkdirSync(dir); } catch (error) { if (error.code !== "EEXIST") throw error; }
     const identity = directory(dir);
     const { text, summary, companion_text: companion, document_content: documentContent, preview_content: previewContent, ...bindingRecord } = prepared;
-    const record = { schema_version: prepared.preview_review ? 5 : prepared.qa_acceptance ? 4 : 3, presentation_id: presentationId, ...(operationId ? { operation_id: operationId, request_digest: requestDigest } : {}), created_at: new Date().toISOString(), ...bindingRecord };
+    const record = bindInputResolution({ schema_version: PRESENTATION_RECORD_VERSION, presentation_id: presentationId, ...(operationId ? { operation_id: operationId, request_digest: requestDigest } : {}), created_at: new Date().toISOString(), ...bindingRecord });
     if (typeof documentContent !== 'string' || record.document_bytes > 131072) throw Error('presentation_document_invalid');
     // A contained snapshot belongs to the existing presentation owner. It never
     // substitutes a later mutable artefact or exposes a caller-selected path.
@@ -120,10 +139,12 @@ export function prepareRunPresentation(root, input, { evaluateGateCheck, checkpo
       readDocumentSnapshot(root, record);
     }
     if (documentFd !== undefined) {
+      effectStarted = true; markControlMutationEffect();
       try { writeFileSync(documentFd, documentContent); fsyncSync(documentFd); } finally { closeSync(documentFd); }
     }
     fsyncDirectory(dir);
     checkpoint('presentation_document_published');
+    effectStarted = true; markControlMutationEffect();
     publishPreviewSnapshot(root, record, previewContent, { resume: Boolean(operationId), checkpoint });
     fsyncDirectory(dir);
     const body = JSON.stringify(record);
@@ -138,12 +159,13 @@ export function prepareRunPresentation(root, input, { evaluateGateCheck, checkpo
     return Object.freeze({ ...record, schema_version: "1", outcome: "prepared", text, summary, companion_text: companion, record_digest: hash(body),
       next_action: "Show text verbatim before waiting for a deliberate response. Pass this presentation_id to run-approve only for that response." });
   } catch (error) {
-    return rejected(runId, error.code ?? error.message, { recovery: error.recovery ?? recovery });
+    return rejected(runId, effectStarted ? 'presentation_recovery_required' : error.code ?? error.message,
+      { recovery: error.recovery ?? recovery, ...(effectStarted ? { detail: error.code ?? error.message } : {}) });
   }
 }
 
 function readPresentationEnvelope(root, runId, presentationId) {
-    const dir = join(checkedRunDirectory(root, runId), "presentations");
+    const dir = join(checkedRunDirectory(root, runId), 'control', 'presentations');
     directory(dir);
     const path = join(dir, `${presentationId}.json`);
     const stat = lstatSync(path);
@@ -182,7 +204,7 @@ export function readPresentationCatalog(root, { runId, revisionId, targetId, gat
     if (resolveControlCommandTarget(root).target_id !== targetId) return fail('target_binding_mismatch');
     const runDir = checkedRunDirectory(root, runId), run = readRun(root, runId);
     if (run.rejection || run.meta.revision_id !== revisionId || runSealState(root, run.content).status !== 'valid') return fail('operation_binding_stale_or_invalid');
-    const path = join(runDir, 'presentations');
+    const path = join(runDir, 'control', 'presentations');
     const identity = stat => [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(':');
     const parents = [root, join(root, '.agdf'), join(root, '.agdf/control'), join(root, '.agdf/control/runs'), runDir];
     const beforeParents = parents.map(p => identity(directory(p)));
@@ -216,7 +238,7 @@ export function readPresentationCatalog(root, { runId, revisionId, targetId, gat
       const checked = validateRunPresentationEnvelope(envelope, { runId, gate: record.gate, revisionId: record.revision_id, presentationId: id });
       if (checked.reason) return fail(checked.reason);
       // Old records without snapshots cannot establish a complete readable catalog.
-      if (![3, 4, 5].includes(record.schema_version)) return fail('presentation_document_snapshot_unavailable');
+      if (resolutionRecordVersion(record) !== 7) return fail('presentation_document_snapshot_unavailable');
       const documentPath = join(path, `${id}.document`), documentStat = lstatSync(documentPath);
       new TextDecoder('utf-8', { fatal: true }).decode(readDocumentSnapshot(root, record));
       observedFiles.push([join(path, `${id}.json`), identity(stat)], [documentPath, identity(documentStat)]);
@@ -251,11 +273,10 @@ export function validateRunPresentation(root, input, { evaluateGateCheck }) {
   const envelope = validateRunPresentationRecord(root, input);
   if (envelope.reason) return envelope;
   try {
-    if ([3, 4, 5].includes(envelope.record.schema_version)) readDocumentSnapshot(root, envelope.record);
-    if (envelope.record.schema_version === 5) validateCurrentPreviewRecord(root, envelope.record);
+    if (resolutionRecordVersion(envelope.record) === 7) readDocumentSnapshot(root, envelope.record);
+    if (resolutionRecordVersion(envelope.record) === 7 && envelope.record.preview_review) validateCurrentPreviewRecord(root, envelope.record);
     const fresh = binding(root, { ...input, language: envelope.record.presentation_language }, evaluateGateCheck);
     if (Object.entries(fresh).some(([key, value]) => !['text', 'summary', 'companion_text', 'document_content', 'preview_content'].includes(key)
-      && ([3, 4, 5].includes(envelope.record.schema_version) || !['document_digest', 'document_bytes', 'document_language'].includes(key))
       && (['qa_acceptance', 'preview_review'].includes(key) ? JSON.stringify(envelope.record[key]) !== JSON.stringify(value) : envelope.record[key] !== value))) throw new Error("presentation_state_changed");
     return { presentationId: envelope.presentationId, digest: envelope.digest };
   } catch (error) {
@@ -264,7 +285,7 @@ export function validateRunPresentation(root, input, { evaluateGateCheck }) {
 }
 
 function readDocumentSnapshot(root, record) {
-  const dir = join(checkedRunDirectory(root, record.run_id), 'presentations'); directory(dir);
+  const dir = join(checkedRunDirectory(root, record.run_id), 'control', 'presentations'); directory(dir);
   const path = join(dir, `${record.presentation_id}.document`), stat = lstatSync(path);
   if (stat.isSymbolicLink() || !stat.isFile() || stat.size !== record.document_bytes) throw Error('presentation_document_invalid');
   const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
@@ -295,7 +316,7 @@ export function readPresentationDocument(root, { runId, gate, revisionId, presen
     const checked = validateRunPresentationRecord(root, { runId, gate, revisionId, presentationId });
     if (checked.reason) return fail(checked.reason);
     const record = checked.record;
-    if (![3, 4, 5].includes(record.schema_version)) return fail('presentation_document_snapshot_unavailable');
+    if (resolutionRecordVersion(record) !== 7) return fail('presentation_document_snapshot_unavailable');
     const bytes = readDocumentSnapshot(root, record);
     // Cursor is bound to this immutable record; offsets always end on UTF-8 boundaries.
     const prefix = `${checked.digest.slice(7)}:`;
@@ -303,7 +324,10 @@ export function readPresentationDocument(root, { runId, gate, revisionId, presen
       || !/^(0|[1-9][0-9]*)$/u.test(cursor.slice(prefix.length)))) return fail('presentation_document_cursor_invalid');
     const start = cursor === undefined ? 0 : Number(cursor.slice(prefix.length));
     if (!Number.isSafeInteger(start) || start < 0 || start >= bytes.length || (bytes[start] & 0xc0) === 0x80) return fail('presentation_document_cursor_invalid');
-    let end = Math.min(start + 32768, bytes.length);
+    // Keep a full text page small enough for a model to transmit before reading
+    // the next one. The existing digest/offset cursor and UTF-8 checks still own
+    // continuity; previously issued larger-page cursors remain readable.
+    let end = Math.min(start + 8192, bytes.length);
     while (end < bytes.length && (bytes[end] & 0xc0) === 0x80) --end;
     const content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes.subarray(start, end));
     const currentRun = readRun(root, runId);
@@ -326,7 +350,7 @@ export function readPresentationPreview(root, { runId, gate, revisionId, present
     if (resolveControlCommandTarget(root).target_id !== targetId) return fail('target_binding_mismatch');
     const checked = validateRunPresentationRecord(root, { runId, gate, revisionId, presentationId });
     if (checked.reason) return fail(checked.reason);
-    if (checked.record.schema_version !== 5) return fail('preview_unavailable');
+    if (!(resolutionRecordVersion(checked.record) === 7 && checked.record.preview_review)) return fail('preview_unavailable');
     const bytes = readPreviewSnapshot(root, checked.record), token = `${checked.digest.slice(7)}:`;
     if (cursor !== undefined && (typeof cursor !== 'string' || !cursor.startsWith(token) || !/^(0|[1-9][0-9]*)$/u.test(cursor.slice(token.length)))) return fail('preview_cursor_invalid');
     const start = cursor === undefined ? 0 : Number(cursor.slice(token.length));

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

@@ -8,151 +8,22 @@ import { firstSection, guardedWrite, readRun, rejected, replaceFirstScalar, tabl
 import { APPROVAL_GATES, artefactFileDigest, canonicalRunText, runSealState } from "./run-seal.js";
 import { transitionDecisionForRunState } from "../control-evaluation/gate-policy.js";
 import { storedNextActionStale } from "../control-evaluation/next-action.js";
-import { writeRunWithBacklog, synchronizeRunBacklog, withRunBacklogLock, writeRunWithBacklogLocked } from "./run-backlog-writer.js";
-import { backlogSkip } from "./run-backlog.js";
+import { writeRunMutation, withRunMutationLock, writeRunMutationLocked } from "./run-mutation.js";
 import { runPath } from "./run-state-reader.js";
-import { projectUrObjective } from './run-state-edits.js';
+import { projectUrObjective, endedRunRejection } from './run-state-edits.js';
 import { readFileSync } from 'node:fs';
 import { containedRegularFile } from './contained-file.js';
 
 const DURABLE_STATUS_GATES = new Set(["UR", "PRD", "SD", "TP"]);
 
-function recordGateApproval(text, gate, evidence) {
-  const lines = text.split("\n");
-  const sections = ["Approvals", "Gate Checklist"].map((heading) => firstSection(lines, heading));
-  let updated = false;
-  for (const range of sections.filter(Boolean)) {
-    for (const index of tableLineIndexes(lines, range)) {
-      const cells = tableCells(lines[index]);
-      if (cells[0] !== gate) continue;
-      lines[index] = tableLine([gate, "approved", evidence, ...cells.slice(3)]);
-      updated = true;
-    }
-  }
-  if (updated) return lines.join("\n");
-  const row = tableLine([gate, "approved", evidence]);
-  const target = sections.find(Boolean);
-  if (target) {
-    const rowsInTarget = tableLineIndexes(lines, target);
-    if (rowsInTarget.length) lines.splice(rowsInTarget.at(-1) + 1, 0, row);
-    else lines.splice(target.start + 1, 0, "", "| Gate | Status | Evidence |", "|---|---|---|", row);
-    return lines.join("\n");
-  }
-  const block = ["## Approvals", "", "| Gate | Status | Evidence |", "|---|---|---|", row, ""];
-  const anchor = ["Artefacts", "Evidence", "Closeout"].map((heading) => firstSection(lines, heading)).find(Boolean);
-  if (anchor) lines.splice(anchor.start, 0, ...block);
-  else lines.push("", ...block);
-  return lines.join("\n");
-}
-
-function markGateArtefactApproved(text, gate) {
-  const lines = text.split("\n");
-  const range = firstSection(lines, "Artefacts");
-  if (!range) return text;
-  for (const index of tableLineIndexes(lines, range)) {
-    const cells = tableCells(lines[index]);
-    if (cells[0] === gate && cells[1] && cells.length >= 3) lines[index] = tableLine([...cells.slice(0, 2), "approved", ...cells.slice(3)]);
-  }
-  return lines.join("\n");
-}
-
-// The delivery map requires UR to be traceable via "UR | approved_by | Approval: UR".
-function recordUrApprovalChain(text, evidence) {
-  const lines = text.split("\n");
-  const row = tableLine(["UR", "approved_by", "Approval: UR", evidence]);
-  const range = firstSection(lines, "Artefact Chain");
-  if (!range) {
-    const block = ["## Artefact Chain", "", "| From | Relationship | To | Evidence |", "|---|---|---|---|", row, ""];
-    const anchor = ["Evidence", "Closeout"].map((heading) => firstSection(lines, heading)).find(Boolean);
-    if (anchor) lines.splice(anchor.start, 0, ...block);
-    else lines.push("", ...block);
-    return lines.join("\n");
-  }
-  const indexes = tableLineIndexes(lines, range);
-  const existing = indexes.filter((index) => {
-    const cells = tableCells(lines[index]);
-    return cells[0] === "UR" && (cells[1] ?? "").replace(/^`|`$/gu, "") === "approved_by";
-  });
-  if (existing.length) {
-    for (const index of existing) {
-      const cells = tableCells(lines[index]);
-      lines[index] = tableLine(["UR", "approved_by", "Approval: UR", ...cells.slice(3, -1), evidence]);
-    }
-  } else if (indexes.length) {
-    lines.splice(indexes.at(-1) + 1, 0, row);
-  } else {
-    lines.splice(range.start + 1, 0, "", "| From | Relationship | To | Evidence |", "|---|---|---|---|", row);
-  }
-  return lines.join("\n");
-}
-
-// run-update: record the current run state and listed artefacts as a new sealed revision. Approval
-// rows must match the recorded approvals; only run-approve may change them.
-// run-update reseals hand-edited content. When the edit moved an active run's evaluated gate (for
-// example a recorded internal step), refresh the derived control fields as the other canonical
-// writers do; run-specific text on an unchanged gate and "What is known?" stay as authored.
-function refreshMovedGateFields(root, content, path) {
-  const state = prepareRunContentState(root, content, path);
-  const after = transitionDecisionForRunState(state);
-  if (!storedNextActionStale({ content, current_gate: state.current_gate, next_allowed_action: state.next_allowed_action }, after)) return content;
-  const approvedGates = APPROVAL_GATES.filter((gate) => state.approvals.get(gate)?.status === "approved");
-  let next = replaceFirstScalar(content, "current_gate", after.current_gate) ?? content;
-  next = replaceFirstScalar(next, "next_allowed_action", after.next_allowed_action) ?? next;
-  for (const [key, value] of [
-    ["What is approved?", approvedGates.length ? approvedGates.map((gate) => `Approval: ${gate}`).join(", ") : "Nothing yet."],
-    ["What is missing?", after.missing_approval !== "none" ? `Exact ${after.missing_approval}.` : "No approval is pending."],
-    ["What is the next allowed action?", after.next_allowed_action],
-    ["What is explicitly forbidden right now?", after.forbidden.join("; ") || "none"],
-  ]) next = upsertTableRow(next, "Current Control State", 0, key, [key, value]) ?? next;
-  return next;
-}
-
-export function recordRunRevision(root, { runId, revisionId }) {
-  const run = readRun(root, runId);
-  if (run.rejection) return run.rejection;
-  if (run.meta.revision_id !== revisionId) return rejected(runId, "stale_revision");
-  const duplicates = duplicateArtefactRowTypes(run.content);
-  if (duplicates.length) return rejected(runId, "artefact_row_duplicate", {
-    artefact_types: duplicates,
-    recovery: "Keep one Artefacts row per type, then retry run-update with the current revision_id.",
-  });
-  const seal = runSealState(root, run.content);
-  if (seal.status === "valid") {
-    const synced = guardedWrite(runId, () => synchronizeRunBacklog(root, run.path, revisionId));
-    if (synced.rejection) return synced.rejection;
-    return Object.freeze({ schema_version: "1", outcome: synced.state.backlog === "updated" ? "updated" : "unchanged", run_id: runId,
-      revision: run.meta.revision, revision_id: run.meta.revision_id, run_state: "unchanged", backlog: synced.state.backlog,
-      ...backlogSkip({ status: synced.state.backlog, reason: synced.state.backlog_reason }) });
-  }
-  if (seal.status === "approvals_changed") return rejected(runId, "approvals_unrecorded");
-  if (seal.status === "invalid" || seal.status === "unsealed") return rejected(runId, "seal_invalid");
-  let content = refreshMovedGateFields(root, run.content, run.path);
-  const current = parseControlState(content, { userGates: APPROVAL_GATES });
-  if (run.meta.lifecycle === 'active' && current.approvals.get('UR')?.status !== 'approved'
-      && current.artefacts.get('UR')?.status === 'draft') {
-    const file = containedRegularFile(root, current.artefacts.get('UR').path);
-    if (file.status === 'valid') content = projectUrObjective(content, readFileSync(file.path, 'utf8'));
-  }
-  const written = guardedWrite(runId, () => writeRunWithBacklog(root, run.path, content, revisionId, { expectedContent: run.content, allowContentChange: true }));
-  if (written.rejection) return written.rejection;
-  return Object.freeze({
-    schema_version: "1",
-    outcome: "updated",
-    run_id: runId,
-    previous_revision_id: revisionId,
-    revision: written.state.meta.revision,
-    revision_id: written.state.meta.revision_id,
-    backlog: written.state.backlog,
-    ...backlogSkip({ status: written.state.backlog, reason: written.state.backlog_reason }),
-  });
-}
-
 // run-approve: persist one exact gate reply for the revision the user was shown. The CLI cannot
 // observe the conversation; callers pass only the user's verbatim reply to the presented gate.
 export function prepareGateApproval(root, { runId, gate, revisionId, response, presentationId, date = new Date().toISOString().slice(0, 10) }, { evaluateGateCheck }) {
   if (!APPROVAL_GATES.includes(gate)) return rejected(runId, "gate_invalid");
   const run = readRun(root, runId);
   if (run.rejection) return run.rejection;
+  const ended = endedRunRejection(runId, run.content);
+  if (ended) return ended;
   const state = prepareRunContentState(root, run.content, run.path);
   const material = decisionMaterial(root, state, gate);
   const decided = presentationDecisionState(root, state, gate);
@@ -210,29 +81,15 @@ export function prepareGateApproval(root, { runId, gate, revisionId, response, p
     kind: 'accepted_with_deviations', digest: state.qa_acceptance.digest,
     deviation_ids: state.qa_acceptance.proposal.deviations.map(row => row.finding_id), qa_outcome: 'revise',
   } : null;
-  let next = recordGateApproval(canonicalRunText(run.content), gate,
-    evidence + (qaAcceptance ? ` · accepted with deviations ${qaAcceptance.digest}` : ''));
-  if (DURABLE_STATUS_GATES.has(gate)) next = markGateArtefactApproved(next, gate);
-  if (gate === "UR") next = recordUrApprovalChain(next, evidence);
-  // The receipt is appended by the approval owner under the same transaction.
-  // This proposed-state projection is local only; saved readers require that receipt.
-  const proposedState = prepareRunContentState(root, next, run.path);
+  const next = canonicalRunText(run.content);
+  const approvals = new Map(state.approvals);
+  approvals.set(gate, { status: 'approved', evidence });
+  const artefacts = new Map(state.artefacts);
+  if (DURABLE_STATUS_GATES.has(gate)) artefacts.set(gate, { ...artefact, status: 'approved' });
+  const proposedState = { ...state, approvals, artefacts };
   const postApprovalState = qaAcceptance ? { ...proposedState,
     qa_acceptance: { ...state.qa_acceptance, accepted: true } } : proposedState;
   const after = transitionDecisionForRunState(postApprovalState);
-  const approvedGates = APPROVAL_GATES.filter((candidate) => postApprovalState.approvals.get(candidate)?.status === "approved");
-  const controlRows = [
-    ["What is known?", `Approval recorded for ${gate}; current gate is ${after.current_gate}.`],
-    ["What is approved?", approvedGates.length ? approvedGates.map((candidate) => `Approval: ${candidate}`).join(", ") : "Nothing yet."],
-    ["What is missing?", after.missing_approval !== "none" ? `Exact ${after.missing_approval}.` : "No approval is pending."],
-    ["What is the next allowed action?", after.next_allowed_action],
-    ["What is explicitly forbidden right now?", after.forbidden.join("; ") || "none"],
-  ];
-  next = replaceFirstScalar(next, "current_gate", after.current_gate) ?? next;
-  next = replaceFirstScalar(next, "next_allowed_action", after.next_allowed_action) ?? next;
-  for (const [key, value] of controlRows) {
-    next = upsertTableRow(next, "Current Control State", 0, key, [key, value]) ?? next;
-  }
   return { run, next, after, digest, presentation, material, qaAcceptance,
     validateBeforeWrite: () => {
       const current = validateRunPresentation(root, { runId, gate, revisionId, presentationId }, { evaluateGateCheck });
@@ -245,29 +102,3 @@ export function prepareGateApproval(root, { runId, gate, revisionId, response, p
     },
   };
 }
-
-export function approveRunGate(root, input, dependencies) {
-  const { runId, gate, revisionId } = input;
-  if (!APPROVAL_GATES.includes(gate)) return rejected(runId, "gate_invalid");
-  const initial = readRun(root, runId);
-  if (initial.rejection && initial.rejection.reason !== "run_step_recovery_required") return initial.rejection;
-  const written = guardedWrite(runId, () => withRunBacklogLock(root, runPath(root, runId), () => {
-    // Recovery precedes preparation: an interrupted legacy approval may have committed
-    // already, in which case the old reply is rejected rather than applied a second time.
-    const prepared = prepareGateApproval(root, input, dependencies);
-    if (prepared.outcome === "rejected") return prepared;
-    if (prepared.qaAcceptance) return rejected(runId, 'qa_deviation_requires_typed_approval', {
-      recovery: 'Use the existing typed approval.record command with this exact presentation and original operation UUID.',
-    });
-    const { run, next, after, validateBeforeWrite, validateDuringTransaction } = prepared;
-    const state = writeRunWithBacklogLocked(root, run.path, next, revisionId, {
-      allowApprovalChange: true, validateBeforeWrite, validateDuringTransaction, expectedContent: run.content,
-    });
-    return Object.freeze({ schema_version: "1", outcome: "approved", run_id: runId,
-      gate, approval: `Approval: ${gate}`, previous_revision_id: revisionId,
-      revision: state.meta.revision, revision_id: state.meta.revision_id,
-      next_gate_after_approval: after.current_gate, allowed_after_approval: after.next_allowed_action,
-      ...backlogSkip({ status: state.backlog, reason: state.backlog_reason }) });
-  }));
-  return written.rejection ?? written.state;
-}

package/runtime/core/lib/control-state/run-revision-boundary.js

@@ -3,12 +3,14 @@ import { SOURCE_GATES } from "./run-source-revisions.js";
 
 // Shared by current revision preparation and historical proof validation. A history
 // cannot acquire authority from a boundary that the original Run did not satisfy.
-export function sourceRevisionBoundary(state, sourceGate, policyVersion = 1) {
+export function sourceRevisionBoundary(state, sourceGate, policyVersion = 2) {
   const current = transitionDecisionForRunState(state);
   if (policyVersion === 2) {
     // Version selection comes from the exact proposal/receipt, never current defaults.
-    const phases = { UR: ["PRD", "SD", "TP", "CD+Tests", "QA", "UAT"],
-      PRD: ["SD", "TP", "CD+Tests", "QA", "UAT"], SD: ["TP", "CD+Tests", "QA", "UAT"], TP: ["CD+Tests", "QA", "UAT"] };
+    // Brownfield Analysis follows the approved TP; a design or plan gap it finds must reach its source.
+    const phases = { UR: ["PRD", "SD", "TP", "Brownfield Analysis", "CD+Tests", "QA", "UAT"],
+      PRD: ["SD", "TP", "Brownfield Analysis", "CD+Tests", "QA", "UAT"], SD: ["TP", "Brownfield Analysis", "CD+Tests", "QA", "UAT"],
+      TP: ["Brownfield Analysis", "CD+Tests", "QA", "UAT"] };
     if (state.meta.lifecycle !== "active" || current.status !== "open"
         || !["structured_delivery", "structured_slice"].includes(state.mode_slice_decision.decision)
         || state.approvals.get("UAT")?.status === "approved" || state.artefacts.get("OR")?.status === "done"
@@ -18,27 +20,11 @@ export function sourceRevisionBoundary(state, sourceGate, policyVersion = 1) {
     if (!SOURCE_GATES.slice(0, SOURCE_GATES.indexOf(sourceGate) + 1).every(type => approved.includes(type))) return null;
     return { sources, approved, bindings: sources.filter(type => type !== "UR"), initiating_phase: current.current_gate };
   }
-  if (policyVersion !== 1) return null;
-  if (state.meta.lifecycle !== "active"
-      || !["structured_delivery", "structured_slice"].includes(state.mode_slice_decision.decision)
-      || current.status !== "open"
-      || ["QA", "UAT"].some(gate => state.approvals.get(gate)?.status === "approved")
-      || state.artefacts.get("OR")?.status === "done") return null;
-  if (current.current_gate === "CD+Tests") {
-    return { sources: SOURCE_GATES, approved: SOURCE_GATES, bindings: ["PRD", "SD", "TP"] };
-  }
-  if (sourceGate !== "UR" || current.current_gate !== "SD"
-      || !["UR", "PRD"].every(gate => state.approvals.get(gate)?.status === "approved")
-      || ["SD", "TP"].some(gate => state.approvals.get(gate)?.status === "approved")
-      || state.artefacts.get("SD")?.status !== "draft" || !state.artefacts.get("SD")?.path
-      || ["TP", "Brownfield Analysis", "CD+Tests", "CR", "Code Review", "TP Review", "Clean Review",
-        "Clean Implementation Review", "QA", "QA_REPORT", "UAT", "OR"]
-        .some(type => state.artefacts.get(type)?.path || state.artefacts.get(type)?.status === "done")) return null;
-  return { sources: ["UR", "PRD", "SD"], approved: ["UR", "PRD"], bindings: ["PRD", "SD"] };
+  return null;
 }
 
 // Existing early PRD-to-SD boundary, shared with its immutable history validator.
 export function earlyPrdRevisionBoundary(state) {
   return state.meta?.lifecycle === 'active' && state.approvals.get('PRD')?.status === 'approved'
-    && state.meta.current_gate === 'SD' && !['SD', 'TP', 'QA', 'UAT'].some(gate => state.approvals.get(gate)?.status === 'approved' || state.artefacts.get(gate)?.path);
+    && transitionDecisionForRunState(state).current_gate === 'SD' && !['SD', 'TP', 'QA', 'UAT'].some(gate => state.approvals.get(gate)?.status === 'approved' || state.artefacts.get(gate)?.path);
 }

package/runtime/core/lib/control-state/run-revision-history.js

@@ -1,3 +1,8 @@
+import { transitionDecisionForRunState } from '../control-evaluation/gate-policy.js';
+export const REVISION_ARCHIVE_VERSION = '2';
+import { runEvidencePath } from './run-identity.js';
+import { runDocumentPath } from './run-identity.js';
+import { resolutionRecordVersion } from './input-resolution.js';
 import { prepareRunContentState } from "../control-evaluation/run-state.js";
 import { createHash } from "node:crypto";
 import { readFileSync, statSync } from "../control-read/fs.js";
@@ -7,9 +12,9 @@ import { APPROVAL_GATES, canonicalRunText, computeRunSeals, listedArtefactPaths,
 import { parseControlState, parseRunState } from "./run-state-parser.js";
 import { readArtefactBindings } from "./artefact-bindings.js";
 import { exactApprovedArtefacts, validateBindingProof } from "./artefact-binding-proof.js";
-import { internalStepArtefacts } from "../control-evaluation/run-state.js";
+
 import { readSourceRevisions, revisionHistoryPrefix, SOURCE_GATES, sourceRevisionImpact, validExpandedRevisionProof } from "./run-source-revisions.js";
-import { REVISION_PROPOSAL_FIELDS, REVISION_PROPOSAL_V2_FIELDS } from './recording-formats.js';
+import { REVISION_PROPOSAL_FIELDS, SOURCE_REVISION_PROPOSAL_VERSION } from './recording-formats.js';
 import { sourceRevisionBoundary, earlyPrdRevisionBoundary } from "./run-revision-boundary.js";
 import { readRunOperations } from './run-operations.js';
 
@@ -29,20 +34,22 @@ export function readHistoryBytes(root, path) {
   return readBoundedHistoryBytes(root, path, historyLimit(path));
 }
 
-export function collectRevisionHistory(root, runId, operationId, paths) {
+export function collectRevisionHistory(root, runId, operationId, paths, { proposalMaterial } = {}) {
   const prefix = revisionHistoryPrefix(runId, operationId);
   const files = [...new Set(paths)].sort().map((path, i) => {
     if (!isSafeControlRelativePath(path) || !path.startsWith(".agdf/control/")) throw Error("AGDF_REVISION_HISTORY_INVALID");
-    const bytes = readBoundedHistoryBytes(root, path,
+    const bytes = proposalMaterial?.path === path ? Buffer.from(proposalMaterial.content) : readBoundedHistoryBytes(root, path,
       path === `.agdf/control/runs/${runId}/RUN_STATE.md` ? CONTROL_STATE_LIMIT : DOCUMENT_LIMIT);
+    if (proposalMaterial?.path === path && (bytes.length > DOCUMENT_LIMIT || byteDigest(Buffer.from(canonicalRunText(bytes.toString('utf8')))) !== proposalMaterial.digest
+      || path !== runEvidencePath(runId, `EVIDENCE-${proposalMaterial.digest.slice(7)}.json`))) throw Error('AGDF_REVISION_HISTORY_INVALID');
     return { path, snapshot: `${prefix}files/${i}.bin`, bytes, digest: byteDigest(bytes),
       canonical_digest: byteDigest(Buffer.from(canonicalRunText(bytes.toString("utf8")), "utf8")) };
   });
-  const manifest = { schema_version: "1", run_id: runId, operation_id: operationId,
+  const manifest = { schema_version: REVISION_ARCHIVE_VERSION, run_id: runId, operation_id: operationId,
     files: files.map(({ path, snapshot, bytes, digest, canonical_digest }) => ({ path, snapshot, length: bytes.length, digest, canonical_digest })) };
   const text = canonicalJson(manifest) + "\n";
   if (Buffer.byteLength(text) > 131072) throw Error("AGDF_REVISION_HISTORY_INVALID");
-  return { manifest, text, digest: byteDigest(Buffer.from(text)), files };
+  return { manifest, text, digest: byteDigest(Buffer.from(text)), files, ...(proposalMaterial ? { proposalMaterial } : {}) };
 }
 
 export function readValidatedRevisionArchive(root, receipt) {
@@ -51,7 +58,7 @@ export function readValidatedRevisionArchive(root, receipt) {
     if (byteDigest(bytes) !== receipt.archive.digest) return false;
     const manifest = JSON.parse(bytes.toString("utf8")), prefix = revisionHistoryPrefix(receipt.run_id, receipt.operation_id);
     // target_id names the recording checkout; clones verify it via the archived proposal, not their path.
-    if (!exactObject(manifest, ["schema_version", "run_id", "operation_id", "files"]) || manifest.schema_version !== "1"
+    if (!exactObject(manifest, ["schema_version", "run_id", "operation_id", "files"]) || manifest.schema_version !== REVISION_ARCHIVE_VERSION
         || manifest.run_id !== receipt.run_id || manifest.operation_id !== receipt.operation_id
         || !Array.isArray(manifest.files) || !manifest.files.length) return false;
     const names = new Set(), snapshots = new Set(), archived = new Map(), digests = new Map();
@@ -99,9 +106,9 @@ export function validateRevisionHistory(root, receipt) {
     const closure = readValidatedRevisionArchive(root, receipt);
     if (!closure) return false;
     const { original, parsed, archived, digests, names, readers, control } = closure;
-    const expanded = receipt.schema_version === '3';
-    const boundary = sourceRevisionBoundary(control, receipt.source_gate, expanded ? 2 : 1);
-    if (!boundary || !boundary.sources.every(type => names.has(`.agdf/control/artefacts/${receipt.run_id}/${type}.md`))) return false;
+    if (resolutionRecordVersion(receipt) !== '4') return false;
+    const boundary = sourceRevisionBoundary(control, receipt.source_gate, 2);
+    if (!boundary || !boundary.sources.every(type => names.has(`${runDocumentPath(receipt.run_id, '')}/${type}.md`))) return false;
     const bindings = readArtefactBindings(original);
     // The receipt pins an actually archived reviewed request and its computed preview,
     // not just unrelated valid old approvals beside caller-supplied request hashes.
@@ -109,22 +116,22 @@ export function validateRevisionHistory(root, receipt) {
       try { const row = JSON.parse(bytes.toString("utf8")); return digest(canonicalJson(row)) === receipt.request_digest ? [row] : []; } catch { return []; }
     });
     const proposal = proposals[0];
-    if (['2', '3'].includes(receipt.schema_version)) {
+    {
       const bytes = archived.get(receipt.proposal_reference.path);
       if (!bytes || digest(canonicalRunText(bytes.toString('utf8'))) !== receipt.proposal_reference.digest) return false;
     }
     const sources = boundary.sources.map(type => ({ type, path: control.artefacts.get(type)?.path, digest: digests.get(control.artefacts.get(type)?.path) }));
-    if (proposals.length !== 1 || !exactObject(proposal, expanded ? REVISION_PROPOSAL_V2_FIELDS : REVISION_PROPOSAL_FIELDS)
-        || proposal.schema_version !== (expanded ? '2' : '1') || proposal.target_id !== receipt.target_id || proposal.run_id !== receipt.run_id
+    if (proposals.length !== 1 || !exactObject(proposal, REVISION_PROPOSAL_FIELDS)
+        || proposal.schema_version !== SOURCE_REVISION_PROPOSAL_VERSION || proposal.target_id !== receipt.target_id || proposal.run_id !== receipt.run_id
         || proposal.expected_revision_id !== receipt.previous_revision_id || proposal.operation_id !== receipt.operation_id
         || proposal.source_gate !== receipt.source_gate || proposal.reason !== receipt.reason || canonicalJson(proposal.sources) !== canonicalJson(sources)
         || canonicalJson(proposal.impact_assessment?.upstream) !== canonicalJson(receipt.retained_sources)
         || canonicalJson(proposal.impact_assessment?.analyses) !== canonicalJson(receipt.analyses)) return false;
     const impact = sourceRevisionImpact(proposal, bindings.active);
-    if (expanded && (receipt.policy_version !== 2 || receipt.initiating_phase !== boundary.initiating_phase
+    if ((receipt.policy_version !== 2 || receipt.initiating_phase !== boundary.initiating_phase
       || receipt.impact_digest !== digest(canonicalJson(impact)) || receipt.quality_digest !== digest(canonicalJson(proposal.quality_assessment))
       || !validExpandedRevisionProof(proposal, control, path => archived.get(path)?.toString('utf8'), boundary.initiating_phase))) return false;
-    const preview = { schema_version: expanded ? '2' : "1", target_id: receipt.target_id, run_id: receipt.run_id, expected_revision_id: receipt.previous_revision_id,
+    const preview = { schema_version: '2', target_id: receipt.target_id, run_id: receipt.run_id, expected_revision_id: receipt.previous_revision_id,
       operation_id: receipt.operation_id, request_digest: receipt.request_digest, reason: proposal.reason, intended_change: proposal.intended_change,
       sources, impact, archive_digest: receipt.archive.digest,
       current_run_digest: byteDigest(archived.get(`.agdf/control/runs/${receipt.run_id}/RUN_STATE.md`)) };
@@ -167,7 +174,7 @@ export function validEarlyPrdEffect(before, after) {
       : canonicalJson(old.approvals.get(gate)) === canonicalJson(next.approvals.get(gate)))
     && [...old.artefacts].every(([type, row]) => type === 'PRD' ? next.artefacts.get(type)?.path === row.path && next.artefacts.get(type)?.status === 'draft'
       : canonicalJson(next.artefacts.get(type)) === canonicalJson(row))
-    && parseRunState(after).meta.current_gate === 'PRD' && parseRunState(after).meta.lifecycle === 'active';
+    && transitionDecisionForRunState({ ...next, content: after, meta: parseRunState(after).meta }).current_gate === 'PRD' && parseRunState(after).meta.lifecycle === 'active';
 }
 
 export function inspectRevisionHistory(root, receipt) {