create-agdf 0.20.2 → 0.30.0

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

@@ -1,3 +1,5 @@
+import { runDocumentPath, runHistoryPath } from './run-identity.js';
+import { resolutionRecord } from './input-resolution.js';
 import { validDecisionMaterial, decisionMaterialVersion } from './decision-material-contract.js';
 import { TextDecoder } from 'node:util';
 import { canonicalJson, digest, COOPERATIVE_ASSURANCE, DIGEST_PATTERN, exactObject } from './approval-command-contract.js';
@@ -5,39 +7,68 @@ import { REVISION_ID_PATTERN, RUN_ID_PATTERN, APPROVAL_GATES } from './run-ident
 import { isSafeControlRelativePath } from './contained-file.js';
 
 const fields = ['schema_version', 'kind', 'operation_id', 'request_digest', 'target_id', 'run_id', 'expected_revision_id', 'created_at', 'producer', 'assurance', 'effect'];
-export const RUN_OPERATION_KINDS = Object.freeze(['step.record', 'presentation_decision.record', 'prd_revision.reopen', 'closeout.record']);
+export const RUN_OPERATION_VERSION = '4';
+export const RUN_OPERATION_KINDS = Object.freeze(['run.create', 'run.create_from_planned', 'ur_draft.replace', 'step.record', 'presentation_decision.record', 'prd_revision.reopen', 'closeout.record', 'lifecycle_close.record']);
+export const ENDED_LIFECYCLES = Object.freeze(['superseded', 'abandoned']);
 const uuid = value => typeof value === 'string' && REVISION_ID_PATTERN.test(value);
 const hash = value => typeof value === 'string' && DIGEST_PATTERN.test(value);
 const text = (value, max = 8192) => typeof value === 'string' && value.length <= max && !/\0/u.test(value);
 const source = (value, runId) => exactObject(value, ['path', 'digest']) && isSafeControlRelativePath(value.path)
-  && value.path.startsWith(`.agdf/control/artefacts/${runId}/`) && hash(value.digest);
+  && value.path.startsWith(`${runDocumentPath(runId, '')}/`) && hash(value.digest);
+// One bounded table-safe line for typed closure facts.
+export const closureLine = (value, max) => text(value, max) && value.trim() === value && Boolean(value) && !/[|\u0000-\u001f\u007f]/u.test(value);
+const validSuccessor = (value, runId) => exactObject(value, ['kind', 'value', 'verified']) && (value.kind === 'run'
+  ? value.verified === true && RUN_ID_PATTERN.test(value.value) && value.value !== runId : value.kind === 'reference' && value.verified === false && closureLine(value.value, 512));
+// The confirming person is a cooperative local Git statement, never proof of a human identity.
+const validConfirmer = value => exactObject(value, ['statement']) ? value.statement === 'unknown'
+  : exactObject(value, ['name', 'email', 'statement']) && value.statement === 'cooperative' && (value.name !== null || value.email !== null)
+    && [value.name, value.email].every(item => item === null || closureLine(item, 256));
 function validRecord(receipt) {
   const r = receipt.effect.record;
-  if (receipt.kind === 'step.record') return exactObject(r, ['step', 'source', 'status', 'covers', 'source_set_digest'])
-    && ['ur', 'route', 'review', 'evidence', 'Brownfield Review', 'UX Intent Definition', 'Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR'].includes(r.step)
-    && source(r.source, receipt.run_id) && ['done', 'revise', 'block', 'not_applicable'].includes(r.status)
-    && text(r.covers, 1024) && hash(r.source_set_digest);
+  if (receipt.kind === 'run.create') return exactObject(r, ['title']) && text(r.title, 1024) && r.title.trim()
+    && !/[\r\n|]/u.test(r.title) && receipt.run_id === `run-${receipt.operation_id}`;
+  if (receipt.kind === 'run.create_from_planned') return exactObject(r, ['title', 'planned', 'snapshot'])
+    && text(r.title, 1024) && Boolean(r.title.trim()) && !/[\r\n\u2028\u2029]/u.test(r.title)
+    && receipt.run_id === `run-${receipt.operation_id}` && exactObject(r.planned, ['plan_id', 'path', 'digest'])
+    && RUN_ID_PATTERN.test(r.planned.plan_id ?? '') && r.planned.path === `.agdf/control/planned/${r.planned.plan_id}/UR.md` && hash(r.planned.digest)
+    && exactObject(r.snapshot, ['path', 'digest', 'raw_digest']) && r.snapshot.path === runHistoryPath(receipt.run_id, 'planning/UR.md')
+    && r.snapshot.digest === r.planned.digest && hash(r.snapshot.raw_digest);
+  if (['step.record', 'ur_draft.replace'].includes(receipt.kind)) return exactObject(r, ['evidence_binding_id', 'status', 'covers'])
+    && r.evidence_binding_id === receipt.operation_id && uuid(r.evidence_binding_id)
+    && ['done', 'revise', 'block', 'not_applicable', 'eligible', 'executed', 'escalated'].includes(r.status) && text(r.covers, 1024);
   if (receipt.kind === 'presentation_decision.record') return exactObject(r, ['gate', 'presentation_id', 'presentation_digest', 'material_version', 'material_sources', 'action', 'comment', 'owner', 'artefact_digest'])
     && APPROVAL_GATES.includes(r.gate) && uuid(r.presentation_id) && hash(r.presentation_digest) && hash(r.material_version)
     && validDecisionMaterial(r.material_sources, receipt.run_id) && r.material_version === decisionMaterialVersion(receipt.run_id, r.gate, r.material_sources) && ['request_change', 'reject'].includes(r.action) && text(r.comment) && Buffer.byteLength(r.comment) <= 8192 && (r.action !== 'request_change' || r.comment.trim())
     && text(r.owner, 128) && r.owner.trim() && (r.gate === 'UAT' ? r.artefact_digest === null : hash(r.artefact_digest));
+  if (receipt.kind === 'closeout.record' && r.mode === 'verified_change') return exactObject(r, ['mode', 'verified_change', 'lifecycle', 'context_evidence_digest', 'confirmation_digest'])
+    && source(r.verified_change, receipt.run_id) && r.verified_change.path === `${runDocumentPath(receipt.run_id, '')}/VERIFIED_CHANGE.md`
+    && r.lifecycle === 'completed' && hash(r.context_evidence_digest) && hash(r.confirmation_digest);
   if (receipt.kind === 'closeout.record') return exactObject(r, ['or', 'lifecycle', 'context_evidence_digest', 'confirmation_digest'])
-    && source(r.or, receipt.run_id) && r.or.path === `.agdf/control/artefacts/${receipt.run_id}/OR.md`
+    && source(r.or, receipt.run_id) && r.or.path === `${runDocumentPath(receipt.run_id, '')}/OR.md`
     && r.lifecycle === 'completed' && hash(r.context_evidence_digest) && hash(r.confirmation_digest);
+  if (receipt.kind === 'lifecycle_close.record') return exactObject(r, ['lifecycle', 'reason', 'successor', 'confirmed_by', 'preview'])
+    && ENDED_LIFECYCLES.includes(r.lifecycle) && closureLine(r.reason, 1024)
+    && (r.lifecycle === 'abandoned' ? r.successor === null : validSuccessor(r.successor, receipt.run_id)) && validConfirmer(r.confirmed_by)
+    && exactObject(r.preview, ['id', 'digest']) && /^[0-9a-f]{8}$/u.test(r.preview.id) && hash(r.preview.digest);
   if (receipt.kind === 'prd_revision.reopen') return exactObject(r, ['prd', 'archive', 'confirmation_digest']) && source(r.prd, receipt.run_id)
-    && r.prd.path === `.agdf/control/artefacts/${receipt.run_id}/PRD.md`
-    && exactObject(r.archive, ['path', 'digest']) && r.archive.path === `.agdf/control/runs/${receipt.run_id}/revisions/${receipt.operation_id}/manifest.json`
+    && r.prd.path === `${runDocumentPath(receipt.run_id, '')}/PRD.md`
+    && exactObject(r.archive, ['path', 'digest']) && r.archive.path === runHistoryPath(receipt.run_id, `revisions/${receipt.operation_id}/manifest.json`)
     && hash(r.archive.digest) && hash(r.confirmation_digest)
     && r.confirmation_digest === digest(earlyPrdConfirmation(receipt.run_id, receipt.expected_revision_id, receipt.operation_id, r.prd.digest));
   return false;
 }
 export const earlyPrdConfirmation = (runId, revisionId, operationId, prdDigest) => `Reopen PRD: ${runId} ${revisionId} ${operationId} ${prdDigest}`;
 export function validRunOperation(receipt) {
-  return exactObject(receipt, fields) && receipt.schema_version === '1' && RUN_OPERATION_KINDS.includes(receipt.kind)
+  receipt = resolutionRecord(receipt);
+  if (!receipt) return false;
+  const plannedCreation = receipt?.kind === 'run.create_from_planned';
+  const creation = receipt?.kind === 'run.create' || plannedCreation;
+  return exactObject(receipt, fields) && receipt.schema_version === RUN_OPERATION_VERSION && RUN_OPERATION_KINDS.includes(receipt.kind)
     && uuid(receipt.operation_id) && hash(receipt.request_digest) && hash(receipt.target_id) && RUN_ID_PATTERN.test(receipt.run_id ?? '')
-    && uuid(receipt.expected_revision_id) && exactObject(receipt.effect, ['previous_revision_id', 'resulting_revision_id', 'revision', 'record'])
+    && (creation ? receipt.expected_revision_id === null : uuid(receipt.expected_revision_id)) && exactObject(receipt.effect, ['previous_revision_id', 'resulting_revision_id', 'revision', 'record'])
     && receipt.effect.previous_revision_id === receipt.expected_revision_id && uuid(receipt.effect.resulting_revision_id)
-    && receipt.effect.resulting_revision_id !== receipt.expected_revision_id && Number.isSafeInteger(receipt.effect.revision) && receipt.effect.revision >= 2
+    && receipt.effect.resulting_revision_id !== receipt.expected_revision_id && Number.isSafeInteger(receipt.effect.revision)
+    && (creation ? receipt.effect.revision === 1 : receipt.effect.revision >= 2)
     && exactObject(receipt.producer, ['contract', 'package_version']) && receipt.producer.contract === 'run-command/1' && text(receipt.producer.package_version, 128) && receipt.producer.package_version
     && 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.isFinite(Date.parse(receipt.created_at)) && Boolean(validRecord(receipt));
@@ -52,7 +83,7 @@ export function readRunOperations(content) {
   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 | request_digest | receipt |' || !/^\|[-:|\s]+\|$/u.test(body[2] ?? '')) return invalid();
-  const receipts = [], ids = new Set(), revisions = new Set(); let revision = 1;
+  const receipts = [], ids = new Set(), revisions = new Set(); let revision = 0;
   for (const line of body.slice(3)) {
     const cells = line.match(/^\| ([^|]+) \| ([^|]+) \| ([A-Za-z0-9_-]+) \|$/u);
     if (!cells || cells[3].length > 131072) return invalid();
@@ -78,3 +109,29 @@ export function assertRunOperationsChange(current, candidate, appended) {
   if (!before.valid || !after.valid || after.present !== (before.present || Boolean(appended))
     || canonicalJson(after.receipts) !== canonicalJson(appended ? [...before.receipts, appended] : before.receipts)) throw Error('AGDF_RUN_OPERATIONS_CHANGED');
 }
+
+// Lifecycle and closure facts of an ended Run. The sealed receipt is the record; a missing or
+// unreadable receipt still leaves the Run ended and is reported as unavailable.
+const lifecycleOf = content => String(content).match(/^- lifecycle:[ \t]*(\S+)[ \t]*\r?$/mu)?.[1] ?? null;
+export function runClosure(content) {
+  const lifecycle = lifecycleOf(content);
+  if (!ENDED_LIFECYCLES.includes(lifecycle)) return null;
+  const operations = readRunOperations(content), receipt = operations.valid ? operations.receipts.filter(row => row.kind === 'lifecycle_close.record').at(-1) : undefined;
+  const r = receipt?.effect.record;
+  return { outcome: lifecycle, closed_at: receipt?.created_at ?? null, reason: r?.reason ?? null, successor: r?.successor ?? null,
+    confirmed_by: r?.confirmed_by ?? null, operation_id: receipt?.operation_id ?? null, preview: r?.preview ?? null, receipt: receipt ? 'recorded' : 'unavailable' };
+}
+export const RUN_ENDED_NEXT_ACTION = 'Start a new run; it may reference the ended run.';
+export const closureSuccessorText = successor => successor ? ` by ${successor.value}${successor.verified ? '' : ' (unverified reference)'}` : '';
+// The archived closure outcome of an ended Run: successor and reason, or the reason alone.
+export const closureOutcomeText = (outcome, successor, reason) => outcome === 'superseded'
+  ? `Superseded${closureSuccessorText(successor)}: ${reason ?? 'reason unavailable'}` : `Abandoned: ${reason ?? 'reason unavailable'}`;
+export const closureBacklogRecord = runId => `[RUN_STATE](runs/${runId}/RUN_STATE.md)`;
+export function endedRunMessage(runId, closure) {
+  const successor = closure.successor ? ` by ${closure.successor.value}${closure.successor.verified ? '' : ' (unverified reference)'}` : '';
+  return `Run ${runId} was closed as ${closure.outcome}${successor}${closure.closed_at ? ` on ${closure.closed_at.slice(0, 10)}` : ''}; it accepts no further delivery operation. ${RUN_ENDED_NEXT_ACTION}`;
+}
+export function assertRunNotEnded(content) {
+  const closure = runClosure(content);
+  if (closure) throw Object.assign(Error('AGDF_RUN_LIFECYCLE_ENDED'), { closure });
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-owned-outputs.js

@@ -1,5 +1,6 @@
-import { join } from 'node:path';
-import { existsSync, lstatSync, readFileSync, unlinkSync } from 'node:fs';
+import { runDocumentPath, runEvidencePath } from './run-identity.js';
+import { join, dirname } from 'node:path';
+import { existsSync, lstatSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { exactObject } from './approval-command-contract.js';
 import { hasSymlinkComponent } from './contained-file.js';
@@ -10,11 +11,15 @@ export const INTERNAL_STEP_FILES = Object.freeze({
   'Brownfield Analysis': 'BROWNFIELD_ANALYSIS.md', 'CD+Tests': 'CD_TESTS.md', 'TP Review': 'TP_REVIEW.md',
   'Clean Implementation Review': 'CLEAN_IMPLEMENTATION_REVIEW.md', CR: 'CODE_REVIEW.md',
 });
-const permitted = new Set(['UR.md', 'OR.md', ...Object.values(INTERNAL_STEP_FILES)]);
+const documentNames = new Set(['UR.md', 'OR.md', 'PRD.md', 'SD.md', 'TP.md', 'QA_REPORT.md', 'VERIFIED_CHANGE.md', ...Object.values(INTERNAL_STEP_FILES)]);
+function allowedPath(runId, path) {
+  const documents = `${runDocumentPath(runId, '')}/`, evidence = `${runEvidencePath(runId, '')}/`;
+  return typeof path === 'string' && (path.startsWith(documents) && documentNames.has(path.slice(documents.length))
+    || path.startsWith(evidence) && /^EVIDENCE-[0-9a-f]{64}\.(?:md|json)$/u.test(path.slice(evidence.length)));
+}
 export const outputBytesDigest = text => text === null ? null : 'sha256:' + createHash('sha256').update(text, 'utf8').digest('hex');
 export function ownedOutputPath(root, runId, path) {
-  const prefix = `.agdf/control/artefacts/${runId}/`;
-  if (typeof path !== 'string' || !path.startsWith(prefix) || !permitted.has(path.slice(prefix.length)) || hasSymlinkComponent(root, path)) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
+  if (!allowedPath(runId, path) || hasSymlinkComponent(root, path)) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
   return join(root, path);
 }
 export function ownedOutputText(root, runId, path) {
@@ -24,10 +29,9 @@ export function ownedOutputText(root, runId, path) {
   return new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(file));
 }
 export function validOwnedOutputs(runId, outputs) {
-  const prefix = `.agdf/control/artefacts/${runId}/`;
-  return Array.isArray(outputs) && outputs.length <= 2 && new Set(outputs.map(row => row?.path)).size === outputs.length
+  return Array.isArray(outputs) && outputs.length <= 1 && new Set(outputs.map(row => row?.path)).size === outputs.length
     && outputs.every(row => exactObject(row, ['path', 'old', 'next', 'old_digest', 'next_digest'])
-      && typeof row.path === 'string' && row.path.startsWith(prefix) && permitted.has(row.path.slice(prefix.length))
+      && allowedPath(runId, row.path)
       && (row.old === null || typeof row.old === 'string') && typeof row.next === 'string'
       && Buffer.byteLength(row.next) <= 131072 && (row.old === null || Buffer.byteLength(row.old) <= 131072)
       && row.old_digest === outputBytesDigest(row.old) && row.next_digest === outputBytesDigest(row.next));
@@ -37,6 +41,14 @@ export function prepareOwnedOutput(root, runId, path, next) {
   if (!validOwnedOutputs(runId, [row])) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED'); return row;
 }
 export function publishOwnedOutputs(root, journal, checkpoint) {
+  if (journal.outputs.length) {
+    for (const relative of [...new Set(journal.outputs.map(row => row.path.slice(0, row.path.lastIndexOf('/'))))]) {
+      const directory = join(root, relative);
+      if (hasSymlinkComponent(root, relative)) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
+      if (!existsSync(directory)) { mkdirSync(directory, { mode: 0o700 }); fsyncDirectory(dirname(directory)); }
+      if (!lstatSync(directory).isDirectory() || lstatSync(directory).isSymbolicLink()) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
+    }
+  }
   for (const row of journal.outputs) {
     if (ownedOutputText(root, journal.run_id, row.path) !== row.old) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
     atomicWrite(ownedOutputPath(root, journal.run_id, row.path), row.next, { checkpoint: stage => checkpoint(`output_${stage}`) });
@@ -51,7 +63,7 @@ export function recoverOwnedOutputs(root, journal, committed) {
       if (text !== row.old && text !== row.next) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
       if (text !== row.old) {
         const file = ownedOutputPath(root, journal.run_id, row.path);
-        if (row.old === null) { unlinkSync(file); fsyncDirectory(join(root, `.agdf/control/artefacts/${journal.run_id}`)); }
+        if (row.old === null) { unlinkSync(file); fsyncDirectory(dirname(file)); }
         else atomicWrite(file, row.old);
       }
     }

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

@@ -1,36 +1,28 @@
-// Immutable envelope validation is shared by live and archived proofs.
-import { digest as hash, exactObject, DIGEST_PATTERN } from "./approval-command-contract.js";
-import { validPreviewSnapshot } from "./preview-snapshot.js";
-
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
-const recovery = "Run run-present for the current run/gate/revision, show its exact presentation, then wait for a NEW deliberate user response. Never bind an earlier reply retroactively.";
-
-export { UUID as PRESENTATION_ID_PATTERN, recovery as PRESENTATION_RECOVERY };
-
-// Rechecks the immutable presentation envelope without evaluating a Run hidden by its
-// own pending journal. Full policy/binding validation must precede transaction intent.
-// Pure record check is also consumed inside captured read-only observations.
+import { resolutionRecord } from './input-resolution.js';
+import { digest as hash, exactObject, DIGEST_PATTERN } from './approval-command-contract.js';
+import { validPreviewSnapshot } from './preview-snapshot.js';
+import { REVISION_ID_PATTERN } from './run-identity.js';
+export const PRESENTATION_RECORD_VERSION = 7;
+export { REVISION_ID_PATTERN as PRESENTATION_ID_PATTERN } from './run-identity.js';
+export const PRESENTATION_RECOVERY = 'Run run-present for the current run/gate/revision, show its exact presentation, then wait for a NEW deliberate user response. Never bind an earlier reply retroactively.';
 export function validateRunPresentationEnvelope(envelope, { runId, gate, revisionId, presentationId }) {
-  const { record, digest } = envelope ?? {};
-  if (!record || ![1, 2, 3, 4, 5].includes(record.schema_version) || record.presentation_id !== presentationId
-      || record.run_id !== runId || record.gate !== gate || record.revision_id !== revisionId
-      || digest !== hash(JSON.stringify(record)) || !Number.isFinite(Date.parse(record.created_at))) {
-    return { reason: "presentation_binding_invalid", recovery };
-  }
-  if (record.schema_version === 2 && (!exactObject(envelope, ['record', 'digest'])
-    || !exactObject(record, ['schema_version', 'presentation_id', 'operation_id', 'request_digest', 'created_at', 'run_id', 'gate', 'revision_id', 'content_digest', 'artefact_digest', 'summary_digest', 'presentation_language', 'presentation_digest'])
-    || record.operation_id !== presentationId || !UUID.test(record.operation_id) || !DIGEST_PATTERN.test(record.request_digest ?? ''))) return { reason: 'presentation_binding_invalid', recovery };
-  if ([3, 4, 5].includes(record.schema_version) && (!exactObject(envelope, ['record', 'digest'])
-    || !exactObject(record, ['schema_version', 'presentation_id', ...(record.operation_id ? ['operation_id', 'request_digest'] : []),
-      'created_at', 'run_id', 'gate', 'revision_id', 'content_digest', 'artefact_digest', 'summary_digest', 'presentation_language',
-      'presentation_digest', 'document_digest', 'document_bytes', 'document_language', ...(record.schema_version === 4 ? ['qa_acceptance'] : []), ...(record.schema_version === 5 ? ['preview_review'] : [])])
-    || record.operation_id && (record.operation_id !== presentationId || !UUID.test(record.operation_id) || !DIGEST_PATTERN.test(record.request_digest ?? ''))
+  const invalid = () => ({ reason: 'presentation_binding_invalid', recovery: PRESENTATION_RECOVERY });
+  const record = resolutionRecord(envelope?.record);
+  if (!record || !exactObject(envelope, ['record', 'digest']) || record.schema_version !== PRESENTATION_RECORD_VERSION
+    || !exactObject(record, ['schema_version', 'presentation_id', 'operation_id', 'request_digest', 'created_at', 'run_id', 'gate', 'revision_id',
+      'content_digest', 'artefact_digest', 'summary_digest', 'presentation_language', 'presentation_digest',
+      'document_digest', 'document_bytes', 'document_language', ...(record.qa_acceptance ? ['qa_acceptance'] : []), ...(record.preview_review ? ['preview_review'] : [])])
+    || record.presentation_id !== presentationId || record.operation_id !== presentationId || !REVISION_ID_PATTERN.test(presentationId ?? '')
+    || record.run_id !== runId || record.gate !== gate || record.revision_id !== revisionId
+    || ![record.request_digest, record.content_digest, record.summary_digest, record.presentation_digest, record.document_digest].every(value => DIGEST_PATTERN.test(value ?? ''))
+    || !DIGEST_PATTERN.test(record.artefact_digest ?? '')
+    || envelope.digest !== hash(JSON.stringify(envelope.record)) || !Number.isFinite(Date.parse(record.created_at))
     || !/^[a-z]{2}(?:-[A-Za-z0-9]{2,8})*$/u.test(record.document_language ?? '')
-    || !DIGEST_PATTERN.test(record.document_digest ?? '') || !Number.isInteger(record.document_bytes)
-    || record.document_bytes < 1 || record.document_bytes > 131072)) return { reason: 'presentation_binding_invalid', recovery };
-  if (record.schema_version === 4 && (gate !== 'QA' || !exactObject(record.qa_acceptance, ['kind', 'digest'])
-    || record.qa_acceptance.kind !== 'accepted_with_deviations' || !DIGEST_PATTERN.test(record.qa_acceptance.digest ?? ''))) return { reason: 'presentation_binding_invalid', recovery };
-  if (record.schema_version === 5 && (gate !== 'PRD' || !validPreviewSnapshot(record.preview_review, runId, presentationId))) return { reason: 'presentation_binding_invalid', recovery };
-  return { presentationId, digest, record };
+    || typeof record.presentation_language !== 'string' || !record.presentation_language
+    || !Number.isInteger(record.document_bytes) || record.document_bytes < 1 || record.document_bytes > 131072
+    || record.presentation_digest !== record.document_digest) return invalid();
+  if (record.qa_acceptance && (gate !== 'QA' || !exactObject(record.qa_acceptance, ['kind', 'digest'])
+    || record.qa_acceptance.kind !== 'accepted_with_deviations' || !DIGEST_PATTERN.test(record.qa_acceptance.digest ?? ''))) return invalid();
+  if (record.preview_review && (gate !== 'PRD' || !validPreviewSnapshot(record.preview_review, runId, presentationId))) return invalid();
+  return { presentationId, digest: envelope.digest, record: envelope.record };
 }
-

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

@@ -426,18 +426,19 @@ export function renderReviewableApproval(root, report, { runId, gate, revisionId
   // One source-authored summary and one decision moment. Provenance remains
   // available without duplicating the status, transition and approval prompts.
   if (qaAcceptance) { summaryMarkdown = qaAcceptance.summary; summaryDigest = hash(summaryMarkdown); }
-  const parts = [`## ${qaAcceptance ? pack.decisionCard.deviationAcceptanceIntro : pack.gateActionTitles[gate]}`, resolveHumanRunTitle({ currentArtefactHeading: documentHeading, runContent: runState?.content, runId }),
-    qaAcceptance?.summary || decisionMarkdown || decisionBriefFromSummary(summaryMarkdown, p.presentation_language) || summaryMarkdown, qaAcceptance?.effect || pack.primary.afterApproval[gate],
+  const title = resolveHumanRunTitle({ currentArtefactHeading: documentHeading, runContent: runState?.content, runId });
+  const parts = [`## ${pack.gateActionTitles[gate]}`, title,
+    summaryMarkdown, qaAcceptance?.effect || pack.primary.afterApproval[gate],
     german ? 'Antworte „Dokument lesen“, um diese Fassung vollständig im Chat zu lesen. Fragen und Änderungswünsche kannst du hier besprechen. Ohne deine Freigabe bleibt dieser Schritt offen.'
       : 'Reply “Read document” to read this complete version in Chat. Discuss questions and requested changes here. This step remains open until you approve.',
     pack.decisionCard.chatApprovalHint.replace('{gate}', gate),
-    `### ${german ? 'Details und Nachweise' : 'Details and evidence'}\n\n${summaryMarkdown}`,
     `### ${german ? 'Fassung und Quellen' : 'Version and sources'}\n\nRun: \`${runId}\` · ${pack.gateTitles[gate]} · Revision: \`${revisionId}\`\n\nSHA-256: \`${artefactDigest}\``];
+  const markdown = parts.join('\n\n');
   return parts.every((part) => typeof part === "string" && part.trim())
-    ? { markdown: parts.join("\n\n"), companion_markdown: [german
-          ? `Die AGDF-Karte ist geöffnet. Du kannst dort „${qaAcceptance?.approve_label || 'Freigeben'}“ klicken oder hier \`Approval: ${gate}\` eingeben. Beide Wege entscheiden dieselbe vorgelegte Fassung einmal.`
-          : `The AGDF card is open. Click “${qaAcceptance?.approve_label || 'Approve'}” there or enter \`Approval: ${gate}\` here. Both paths decide the same presented version once.`, ...parts].join("\n\n"), preview_markdown: artifactSection,
+    ? { markdown, companion_markdown: german
+          ? `Die Entscheidungsfassung „${title.slice(0, 240)}“ (${gate}, Revision ${revisionId}) wird in der bestätigten AGDF-Ansicht angezeigt.`
+          : `The decision “${title.slice(0, 240)}” (${gate}, revision ${revisionId}) is displayed in the confirmed AGDF view.`, preview_markdown: artifactSection,
         artefact_digest: artefactDigest, summary_digest: summaryDigest, summary_markdown: summaryMarkdown,
-        document_content: documentContent, document_language: documentLanguage,
+        document_content: markdown, document_language: p.presentation_language,
         ...(qaAcceptance ? { qa_acceptance: { kind: qaAcceptance.kind, digest: qaAcceptance.digest } } : {}) } : null;
 }

package/generated/plugins/agdf/runtime/create-agdf/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));