create-agdf 0.20.1 → 0.30.0

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

@@ -1,3 +1,4 @@
+import { resolutionRecordVersion } from './input-resolution.js';
 import { readFileSync, statSync } from '../control-read/fs.js';
 import { canonicalJson, digest } from './approval-command-contract.js';
 import { canonicalRunText } from './run-text.js';
@@ -5,7 +6,7 @@ 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 { STRUCTURED_REQUIRED_REVIEWS, CORRECTABLE_REVIEWS, readEvidenceBindings } 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;
@@ -48,7 +49,7 @@ export function projectPresentationDecision(state, gate, material) {
   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
+    ...approvals.receipts.filter(r => resolutionRecordVersion(r) === '4' && 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 })),
   ];
@@ -64,7 +65,7 @@ export function presentationDecisionState(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;
+  return operations.receipts.find(r => resolutionRecordVersion(r) === '4' && 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
@@ -89,9 +90,13 @@ function reviewRecordingChains(state) {
   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) });
+    const byId = new Map(readEvidenceBindings(state.content).bindings.map(row => [row.operation_id, row]));
+    const steps = operations.receipts.filter(r => r.kind === 'step.record').map(r => {
+      const binding = byId.get(r.effect.record.evidence_binding_id);
+      return { ...r, record: binding ? { ...r.effect.record, step: binding.step, source: binding.report, source_set_digest: binding.source_set_digest } : null };
+    }).filter(r => r.record && (r.record.step === type || type === 'CR' && r.record.step === 'review'));
+    const seen = steps.filter(r => r.effect.revision < uat.effect.revision).at(-1)?.record;
+    if (seen) chains.set(type, { seen, later: steps.filter(r => r.effect.revision > uat.effect.revision).map(r => r.record) });
   }
   return chains;
 }
@@ -118,7 +123,7 @@ export function approvedMaterialFindings(state, decisions) {
   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);
+    const receipt = receipts.find(r => resolutionRecordVersion(r) === '4' && 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 [];

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

@@ -0,0 +1,90 @@
+import { runCommandRequestDigest } from './run-command-contract.js';
+import { resolveControlCommandTarget } from './approval-command-contract.js';
+import { readRun } from './run-state-edits.js';
+import { runSealState } from './run-seal.js';
+import { currentInputResolution } from './input-resolution.js';
+import { assertInputConfigurationCurrent } from '../resources/configuration.js';
+
+export const presentationDeliveryKey = input => [input.target_id, input.run_id, input.expected_revision_id,
+  input.command?.payload?.presentation_id ?? input.presentation_id ?? input.operation_id].join(':');
+
+// Connection-local delivery bookkeeping, shared by every MCP host. A private UI
+// view may offer a live confirmation/retirement hook; it never grants a gate.
+export function createPresentationDelivery({ now = Date.now } = {}) {
+  const rows = new Map(), pendingRuns = new Set(); let closed = false;
+  const sameRun = (a, b) => a.target_id === b.target_id && a.run_id === b.run_id;
+  function expire() {
+    for (const [key, row] of rows) if (!row.pending && now() - row.created >= 30 * 60_000) {
+      void row.view?.retire().catch(() => {}); rows.delete(key);
+    }
+  }
+  const failure = reason => ({ schema_version: '1', outcome: 'rejected', reason, authorizes: false });
+  return Object.freeze({
+    remember(input, result) {
+      expire();
+      if (closed || !['accepted', 'already_applied'].includes(result.outcome) || !result.family_result?.text) return;
+      const prepared = result.family_result, key = presentationDeliveryKey({ ...input, operation_id: prepared.presentation_id });
+      if (rows.has(key)) return;
+      if (rows.size >= 64 || [...rows.values()].reduce((n, d) => n + Buffer.byteLength(d.result.family_result.text) + d.resolutionBytes, 0)
+        + Buffer.byteLength(prepared.text) > 8 * 1024 ** 2) return;
+      rows.set(key, { input, result, created: now(), selected: null, view: null, pending: false, resolutions: new Map(), resolutionBytes: 0 });
+    },
+    prepared(input) { return rows.get(presentationDeliveryKey(input)) ?? null; },
+    originalInput(input) {
+      expire();
+      const resolution = rows.get(presentationDeliveryKey(input))?.resolutions.get(input.operation_id);
+      return resolution ? { known: true, resolution } : null;
+    },
+    async deliver(input, host = {}) {
+      const payload = input.command.payload, row = rows.get(presentationDeliveryKey(input));
+      const runKey = `${input.target_id}:${input.run_id}`;
+      const base = { ...(row?.result ?? {}), family_result: {}, receipt: null, effect: null, historical_effect: false, recovery: null,
+        schema_version: '1', outcome: 'accepted', reason: null, operation_id: input.operation_id, request_digest: runCommandRequestDigest(input),
+        binding: { target_id: input.target_id, run_id: input.run_id, expected_revision_id: input.expected_revision_id, kind: 'presentation.deliver' }, authorizes: false };
+      if (closed || !row || now() - row.created >= 30 * 60_000) return { ...base, ...failure('delivery_state_unavailable') };
+      if (row.pending || pendingRuns.has(runKey)) return { ...base, ...failure('busy') };
+      const selected = row.selected;
+      if (selected?.operation_id === input.operation_id && selected.digest !== base.request_digest) return { ...base, ...failure('operation_payload_conflict') };
+      const emit = (mode, text, historical = false) => ({ ...base, historical_effect: historical, presentation_delivery: {
+        delivery_id: selected?.operation_id ?? input.operation_id, mode, text, historical_delivery: historical,
+        presentation_id: payload.presentation_id, revision_id: input.expected_revision_id, document_digest: row.result.family_result.document_digest,
+        cleanup_state: row.cleanup ?? 'not_required',
+        instruction: historical ? 'Already delivered. Do not repeat the summary or decision question.' : 'Forward this exact text once; append no second summary or decision request.', authorizes: false } });
+      if (selected && !(payload.route === 'fallback' && selected.mode === 'ui_primary')) return emit(selected.mode, '', true);
+      const resolution = currentInputResolution();
+      if (resolution && !row.resolutions.has(input.operation_id)) {
+        const bytes = Buffer.byteLength(JSON.stringify(resolution));
+        if (row.resolutions.size >= 4 || [...rows.values()].reduce((n, d) => n + Buffer.byteLength(d.result.family_result.text) + d.resolutionBytes, bytes) > 8 * 1024 ** 2)
+          return { ...base, ...failure('resource_limit') };
+        row.resolutions.set(input.operation_id, resolution);
+        row.resolutionBytes += bytes;
+      }
+      row.pending = true; pendingRuns.add(runKey);
+      try {
+        const root = resolveControlCommandTarget(input.primary_target).root;
+        if (resolveControlCommandTarget(root).target_id !== input.target_id || row.input.command.payload.gate !== payload.gate) return { ...base, ...failure('presentation_binding_changed') };
+        assertInputConfigurationCurrent(root);
+        const run = readRun(root, input.run_id);
+        if (run.rejection || run.meta.revision_id !== input.expected_revision_id || runSealState(root, run.content).status !== 'valid') {
+          await row.view?.retire().catch(() => {}); return { ...base, ...failure('presentation_binding_changed') };
+        }
+        const priorViews = [...rows.values()].filter(peer => peer !== row && sameRun(peer.input, input) && peer.view);
+        const retired = await Promise.all(priorViews.map(peer => peer.view.retire().then(() => 'confirmed', () => 'unconfirmed')));
+        if (retired.length) row.cleanup = retired.includes('unconfirmed') ? 'unconfirmed' : 'confirmed';
+        const displayed = !selected && payload.route === 'automatic' && row.view?.confirm(host) === true;
+        // The session owner revokes primary/actions synchronously, before its
+        // asynchronous read-worker cleanup. Failed cleanup retains capacity but
+        // cannot retain decision authority or prevent a safe Markdown fallback.
+        if (displayed) row.view.select();
+        else if (row.view) {
+          const cleanup = await row.view.retire().then(() => 'confirmed', () => 'unconfirmed');
+          row.cleanup = row.cleanup === 'unconfirmed' ? row.cleanup : cleanup;
+        }
+        const mode = displayed ? 'ui_primary' : 'full_markdown';
+        row.selected = { mode, operation_id: input.operation_id, digest: base.request_digest };
+        return emit(mode, displayed ? row.result.family_result.companion_text : row.result.family_result.text);
+      } finally { row.pending = false; pendingRuns.delete(runKey); }
+    },
+    close() { closed = true; for (const row of rows.values()) void row.view?.retire().catch(() => {}); rows.clear(); },
+  });
+}

package/runtime/core/lib/control-state/preview-render.js

@@ -1,5 +1,5 @@
-import { parse, serialize } from 'parse5';
-import postcss from 'postcss';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
 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'";
@@ -19,6 +19,9 @@ const replace = (node, tag, content) => {
 // 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) {
+  // Both pinned packages ship CommonJS entries. Load the actual parsers only
+  // when rendering, keeping this synchronous API and all resource guards intact.
+  const { parse, serialize } = require('parse5'), postcss = require('postcss');
   const resources = new Map(files.map(file => [file.path, file]));
   const styles = new Map();
   let embeddedBytes = 0;

package/runtime/core/lib/control-state/preview-review.js

@@ -1,3 +1,4 @@
+import { runEvidencePath } from './run-identity.js';
 import { readFileSync, statSync } from '../control-read/fs.js';
 import { containedRegularFile, hasSymlinkComponent, isSafeControlRelativePath } from './contained-file.js';
 import { canonicalJson, digest, exactObject, DIGEST_PATTERN } from './approval-command-contract.js';
@@ -9,7 +10,7 @@ export const PREVIEW_LIMITS = Object.freeze({ descriptor: 16384, files: 32, file
 export const PREVIEW_REVIEW_FORMAT = Object.freeze({ section: 'Preview Review', fence: 'json', schema_version: '1',
   fields: Object.freeze(['schema_version', 'version', 'source_ur_digest', 'entry', 'files', 'review_task', 'scenarios', 'criterion_ids', 'open_questions']),
   file_fields: Object.freeze(['path', 'digest', 'bytes', 'media_type']), limits: PREVIEW_LIMITS,
-  entry: '.agdf/control/artefacts/<run_id>/previews/<short-name-vN>/index.html', digest_rule: 'raw bytes for files; canonical approved UR text for source_ur_digest',
+  entry: '.agdf/control/runs/<run_id>/evidence/previews/<short-name-vN>/index.html', digest_rule: 'raw bytes for files; canonical approved UR text for source_ur_digest',
 });
 export const previewError = code => { throw Error(`preview_${code}`); };
 const text = (value, max = 1200) => typeof value === 'string' && !!value.trim() && value.length <= max && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/u.test(value);
@@ -90,7 +91,7 @@ export function validatePreviewDescriptor(row, runId, criteria, urDigest) {
     || !Array.isArray(row.criterion_ids) || !row.criterion_ids.length || row.criterion_ids.length > 64
     || new Set(row.criterion_ids).size !== row.criterion_ids.length || !row.criterion_ids.every(id => /^[A-Z][A-Z0-9-]*$/u.test(id) && (!criteria || criteria.includes(id)))
     || !Array.isArray(row.files) || !row.files.length || row.files.length > PREVIEW_LIMITS.files) previewError('descriptor_invalid');
-  const prefix = `.agdf/control/artefacts/${runId}/previews/${row.version}/`;
+  const prefix = `${runEvidencePath(runId, '')}/previews/${row.version}/`;
   if (row.entry !== prefix + 'index.html') previewError('entry_invalid');
   let previous = '', total = 0;
   for (const file of row.files) {

package/runtime/core/lib/control-state/preview-snapshot.js

@@ -1,3 +1,6 @@
+import { runControlPath } from './run-identity.js';
+import { runDocumentPath } from './run-identity.js';
+import { resolutionRecordVersion } from './input-resolution.js';
 import { closeSync, constants, fsyncSync, openSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { canonicalJson, digest, exactObject, DIGEST_PATTERN } from './approval-command-contract.js';
@@ -6,7 +9,7 @@ import { canonicalRunText } from './run-text.js';
 import { readFileSync, statSync } from '../control-read/fs.js';
 import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
 
-const prefix = (runId, id) => `.agdf/control/runs/${runId}/presentations/${id}`;
+const prefix = (runId, id) => `${runControlPath(runId, 'presentations')}/${id}`;
 export function previewSnapshotBinding(preview, runId, id) {
   const start = prefix(runId, id), bytes = Buffer.from(preview.html);
   const chunks = [];
@@ -63,7 +66,7 @@ export function publishPreviewSnapshot(root, record, preview, { resume = false,
 
 export function readPreviewSnapshot(root, record, { readBytes = path => readPreviewBytes(root, path), current = false } = {}) {
   const row = record.preview_review;
-  if (record.schema_version !== 5 || !validPreviewSnapshot(row, record.run_id, record.presentation_id)) previewError('snapshot_invalid');
+  if (!(resolutionRecordVersion(record) === 7 && record.preview_review) || !validPreviewSnapshot(row, record.run_id, record.presentation_id)) previewError('snapshot_invalid');
   for (const file of row.files) {
     const bytes = readBytes(file.snapshot);
     if (!bytes || bytes.length !== file.bytes || digest(bytes) !== file.digest) previewError('snapshot_changed');
@@ -80,11 +83,11 @@ export function readPreviewSnapshot(root, record, { readBytes = path => readPrev
 }
 
 export function validateCurrentPreviewRecord(root, record) {
-  if (record.schema_version !== 5) return;
+  if (!(resolutionRecordVersion(record) === 7 && record.preview_review)) return;
   readPreviewSnapshot(root, record, { current: true });
   readStandalone(root, record);
-  const base = `.agdf/control/artefacts/${record.run_id}/`;
-  if (digest(readPreviewBytes(root, base + 'PRD.md')) !== record.document_digest
+  const base = `${runDocumentPath(record.run_id, '')}/`;
+  if (digest(readPreviewBytes(root, base + 'PRD.md')) !== (record.artefact_digest)
     || digest(canonicalRunText(readPreviewBytes(root, base + 'UR.md').toString('utf8'))) !== record.preview_review.descriptor.source_ur_digest) previewError('source_changed');
 }
 
@@ -104,5 +107,5 @@ export function previewProof(record, { rawFileDigest, fileDigest }) {
   if (!validPreviewSnapshot(row, record.run_id, record.presentation_id)) return false;
   if (row.files.some(file => rawFileDigest(file.snapshot) !== file.digest || rawFileDigest(file.path) !== file.digest)
     || row.chunks.some(chunk => rawFileDigest(chunk.snapshot) !== chunk.digest)) return false;
-  return fileDigest(`.agdf/control/artefacts/${record.run_id}/UR.md`) === row.descriptor.source_ur_digest;
+  return fileDigest(`${runDocumentPath(record.run_id, '')}/UR.md`) === row.descriptor.source_ur_digest;
 }

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

@@ -1,27 +1,23 @@
+export const SOURCE_REVISION_PROPOSAL_VERSION = '3';
 // Field contracts shared by the existing recording/revision owners and selected Inspect
 // descriptors. These describe review input; they do not manufacture review findings.
-export const REVIEWED_REQUEST_FIELDS = Object.freeze(['schema_version', 'target_id', 'run_id', 'expected_revision_id', 'destination', 'source', 'relationship', 'review', 'update_draft']);
-export const REVIEW_PROOF_FIELDS = Object.freeze(['schema_version', 'target_id', 'run_id', 'relationship', 'destination', 'source', 'reviewer', 'reviewed']);
-export const REVISION_PROPOSAL_FIELDS = Object.freeze(['schema_version', 'target_id', 'run_id', 'expected_revision_id', 'operation_id', 'source_gate', 'reason', 'intended_change', 'sources', 'impact_assessment']);
+export const REVISION_PROPOSAL_FIELDS = Object.freeze(['schema_version', 'target_id', 'run_id', 'expected_revision_id', 'operation_id', 'source_gate', 'reason', 'intended_change', 'sources', 'impact_assessment', 'policy_version', 'initiating_phase', 'changed_statements', 'quality_assessment']);
 export const REVISION_IMPACT_FIELDS = Object.freeze(['reviewer', 'earliest_source', 'upstream', 'analyses', 'implementation_evidence', 'unresolved']);
 export const REVISION_UPSTREAM_FIELDS = Object.freeze(['type', 'path', 'digest', 'rationale']);
 export const REVISION_ANALYSIS_FIELDS = Object.freeze(['type', 'disposition', 'path', 'digest', 'reason']);
-export const REVISION_PROPOSAL_V2_FIELDS = Object.freeze([...REVISION_PROPOSAL_FIELDS, 'policy_version', 'initiating_phase', 'changed_statements', 'quality_assessment']);
 export const REVISION_STATEMENT_FIELDS = Object.freeze(['type', 'path', 'digest', 'statement', 'intended_change', 'reason']);
 export const REVISION_QUALITY_FIELDS = Object.freeze(['record', 'record_digest', 'operation_id', 'source_set_digest', 'sources', 'association', 'disposition', 'reason']);
 
-export const REVIEWED_REQUEST_FORMAT = Object.freeze({ schema_version: '1', fields: REVIEWED_REQUEST_FIELDS,
-  references: { destination: ['type', 'path', 'digest', 'status'], source: ['type', 'path', 'digest'], review: ['reviewer', 'path', 'digest'] },
-  relationship: 'Use the current gate relationship returned by this descriptor; source must be the current approved exact artefact.',
-  review_proof: { fields: REVIEW_PROOF_FIELDS, reviewed: true, equality: 'target/run/relationship/destination/source/reviewer must equal the reviewed request; hash the contained proof after canonical BOM removal and CRLF normalization' },
-  update_draft: 'false for first recording; true only for updating the same unapproved recorded draft with fresh reviewed mapping. Never update approved material.',
-  scope: 'All request, report and review proof paths belong to .agdf/control/artefacts/<run_id>/; each source is bounded to 131072 bytes.',
-  evidence: 'A real reviewed mapping is required. Authoring completeness alone does not prove derivation.' });
-export const REVISION_PROPOSAL_FORMAT = Object.freeze({ schema_version: '1', fields: REVISION_PROPOSAL_FIELDS,
-  supported_versions: ['1', '2'], expanded: { schema_version: '2', policy_version: 2, fields: REVISION_PROPOSAL_V2_FIELDS,
-    changed_statements: REVISION_STATEMENT_FIELDS, quality_assessment: REVISION_QUALITY_FIELDS,
-    initiating_phase: 'Actual current PRD/SD/TP/CD+Tests/QA/pending UAT; choose the earliest approved changed source, never by phase alone.',
-    quality: 'Cover every current registered analysis/result and evidence row exactly; bind report, source set, original operation and record digest. Unknown associations require reassess. Use the inspected current facts; no invented dependency proof.' },
+export const REVIEWED_BINDING_FORMAT = Object.freeze({ schema_version: '3',
+  command_fields: ['gate', 'material', 'reviewer', 'reviewed', 'update_draft'],
+  material: 'Bound private material or an exact contained Run source path/digest; at most 131072 bytes. The owner publishes the canonical document atomically.',
+  relationship: 'The current gate relationship and exact approved source come from the canonical Run; callers do not duplicate their mapping in proof files.',
+  review: { fields: ['reviewer', 'reviewed'], reviewed: true, storage: 'Embedded attestation in the canonical Artefact Binding; no RECORD/REVIEW JSON files.' },
+  update_draft: 'false for first recording; true only for a reviewed replacement of the same unapproved recorded draft. Never edit an approved document.' });
+export const REVISION_PROPOSAL_FORMAT = Object.freeze({ schema_version: SOURCE_REVISION_PROPOSAL_VERSION, policy_version: 2, fields: REVISION_PROPOSAL_FIELDS,
+  changed_statements: REVISION_STATEMENT_FIELDS, quality_assessment: REVISION_QUALITY_FIELDS,
+  initiating_phase: 'Actual current PRD/SD/TP/Brownfield Analysis/CD+Tests/QA/pending UAT; choose the earliest approved changed source, never by phase alone.',
+  quality: 'Cover every current registered analysis/result and evidence row exactly; bind report, source set, original operation and record digest. Unknown associations require reassess. Use the inspected current facts; no invented dependency proof.',
   impact_assessment: { fields: REVISION_IMPACT_FIELDS, upstream: REVISION_UPSTREAM_FIELDS, analyses: REVISION_ANALYSIS_FIELDS,
     dispositions: ['retain', 'reassess'], unresolved: [], earliest_source: 'Must match source_gate; unchanged upstream needs actual rationale. UR requires reassess for both applicable analyses.' },
   sources: 'Use the exact current sources returned by the existing preview boundary, in UR/PRD/SD/TP order; the eligible boundary determines the subset.',

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

@@ -1,81 +1,69 @@
-import { readOperationSource } from "./run-operation-proof.js";
+import { ARTEFACT_BINDING_VERSION } from './artefact-bindings.js';
+import { exactApprovedArtefacts, validateBindingProof } from './artefact-binding-proof.js';
+import { runDocumentPath } from './run-identity.js';
+import { bindInputResolution } from './input-resolution.js';
 import { randomUUID } from "node:crypto";
-import { canonicalJson, exactObject, resolveControlCommandTarget } from "./approval-command-contract.js";
+import { canonicalJson, digest, exactObject, resolveControlCommandTarget } from "./approval-command-contract.js";
 import { appendArtefactBinding, artefactBindingKey, readArtefactBindings, validArtefactBinding } from "./artefact-bindings.js";
-import { exactApprovedArtefacts, readContainedJson, validateBindingProof } from "./artefact-binding-proof.js";
-import { artefactFileDigest, computeRunSeals, runSealState } from "./run-seal.js";
-import { appendTableRow, upsertTableRow } from "./run-state-edits.js";
+import { artefactFileDigest, computeRunSeals, runSealState, canonicalRunText } from "./run-seal.js";
+import { prepareOwnedOutput } from './run-owned-outputs.js';
 import { relationshipForGate, sameRelationship } from "../control-evaluation/delivery-relationships.js";
-import { readFileSync } from "node:fs";
-import { containedRegularFile } from "./contained-file.js";
 import { readSourceRevisions } from "./run-source-revisions.js";
-import { REVIEWED_REQUEST_FIELDS } from './recording-formats.js';
 import { readReportDecision } from '../control-evaluation/report-decision.js';
 
-// Called by run-step with Run and Backlog locks already held. No approval or QA decision owner.
+// Read the same binding history that the writer enforces; never infer editing intent.
+export function inspectArtefactRecordingMode(state, gate) {
+  const bindings = readArtefactBindings(state.content);
+  if (!bindings.valid || state.approvals.get(gate)?.status === 'approved')
+    return { available: false, mode: 'blocked', reason: 'recording_binding_invalid_or_approved' };
+  const prior = bindings.latest.filter(b => b.relationship.from === (relationshipForGate(gate)?.from ?? gate));
+  if (prior.length > 1) return { available: false, mode: 'blocked', reason: 'recording_binding_ambiguous' };
+  const active = prior.length && bindings.active.some(b => b.binding_id === prior[0].binding_id);
+  return { available: true, mode: !prior.length ? 'initial' : active ? 'replace_unapproved' : 'renew_invalidated_binding',
+    update_draft: prior.length > 0, supersedes: prior[0]?.binding_id ?? null,
+    instruction: prior.length ? 'Explicit reviewed renewal/replacement requires update_draft true and current exact approved sources. Previous approvals remain historical.'
+      : 'Initial reviewed recording uses update_draft false; this observation grants no editing intent.' };
+}
+
+// The command supplies reviewed material; its canonical binding contains the
+// attestation. No request/proof JSON is published beside the actual document.
 export function prepareArtefactRecording(root, run, input, control, before) {
-  const fail = reason => { throw new Error(reason); };
+  const fail = reason => { throw Error(reason); };
   const expected = relationshipForGate(input.gate);
   const qaRecording = input.gate === 'QA' && before.current_gate === 'QA'
     && (before.status === 'open' || before.status === 'blocked' && control.artefacts.get('QA')?.status === 'block');
-  if (readSourceRevisions(run.content).present && !qaRecording && before.missing_approval !== `Approval: ${input.gate}` && before.next_operation?.type !== "revise_gate_material") fail("AGDF_ARTEFACT_RECORDING_GATE_INVALID");
-  if (!expected || input.gate === "UR" || before.current_gate !== input.gate || before.status !== "open" && !qaRecording
-      || control.approvals.get(input.gate)?.status === "approved") fail("AGDF_ARTEFACT_RECORDING_GATE_INVALID");
-  const sourceRequest = input.requestBinding ? readOperationSource(root, input.runId, input.requestBinding) : null;
-  const command = readContainedJson(root, input.evidence);
-  if (!exactObject(command, REVIEWED_REQUEST_FIELDS)
-      || command.schema_version !== "1" || command.target_id !== resolveControlCommandTarget(root).target_id
-      || command.run_id !== input.runId || command.expected_revision_id !== input.revisionId
-      || typeof command.update_draft !== "boolean" || !exactObject(command.relationship, ["from", "relationship", "to"])
-      || !sameRelationship(command.relationship, expected)) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
+  if (!expected || input.gate === 'UR' || before.current_gate !== input.gate || before.status !== 'open' && !qaRecording
+    || control.approvals.get(input.gate)?.status === 'approved') fail('AGDF_ARTEFACT_RECORDING_GATE_INVALID');
+  if (readSourceRevisions(run.content).present && !qaRecording && before.missing_approval !== `Approval: ${input.gate}`
+    && before.next_operation?.type !== 'revise_gate_material') fail('AGDF_ARTEFACT_RECORDING_GATE_INVALID');
+  if (!input.stagedMaterial || input.reviewed !== true || !input.reviewer?.trim() || !input.operationId || !input.requestDigest)
+    fail('AGDF_ARTEFACT_RECORDING_INPUT_INVALID');
   const bindings = readArtefactBindings(run.content);
-  if (!bindings.valid) fail("AGDF_ARTEFACT_BINDINGS_INVALID");
-  const candidate = {
-    schema_version: input.operationId ? "2" : "1", binding_id: randomUUID(), target_id: command.target_id, run_id: input.runId,
-    relationship: command.relationship, destination: command.destination, source: command.source, review: command.review,
-    origin: "reviewed_mapping", operation: { id: input.operationId ?? randomUUID(), previous_revision_id: input.revisionId, resulting_revision_id: randomUUID(), revision: Number(run.meta.revision) + 1, ...(input.operationId ? { request_digest: input.requestDigest } : {}) }, supersedes: null,
-  };
-  const prior = bindings.latest.filter(item => artefactBindingKey(item) === artefactBindingKey(candidate));
-  if (prior.length > 1) fail("AGDF_ARTEFACT_BINDINGS_INVALID");
-  candidate.supersedes = prior[0]?.binding_id ?? null;
+  if (!bindings.valid) fail('AGDF_ARTEFACT_BINDINGS_INVALID');
   const source = control.artefacts.get(expected.to);
-  if (!validArtefactBinding(candidate) || !source || source.path !== command.source.path || source.status !== "approved"
-      || control.approvals.get(expected.to)?.status !== "approved" || !validateBindingProof(root, candidate)
-      || !exactApprovedArtefacts(root, control)) fail("AGDF_ARTEFACT_BINDING_PROOF_INVALID");
-  if (input.gate === "QA") {
-    const report = readFileSync(containedRegularFile(root, candidate.destination.path).path, "utf8");
-    if (readReportDecision(report) !== candidate.destination.status) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
-  }
-  const old = control.artefacts.get(input.gate);
-  if (old?.path && old.path !== candidate.destination.path) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
-  const seal = runSealState(root, run.content);
-  let draftChange = false;
-  if (seal.status === "content_changed" && command.update_draft && (old?.status === "draft"
-      || qaRecording && ['pass', 'revise', 'block'].includes(old?.status))
-      && prior.length === 1 && old.path === prior[0].destination.path && prior[0].destination.digest !== candidate.destination.digest) {
-    // Reconstruct the old aggregate seal using only the previously sealed draft digest.
-    // Every other bound file and the complete recorded body must still match that seal.
-    const restored = computeRunSeals(root, run.content, { artefactDigests: new Map([[old.path, prior[0].destination.digest]]) });
-    draftChange = restored.content_seal === seal.recorded.content_seal && restored.approval_seal === seal.recorded.approval_seal;
-  }
-  if (seal.status !== "valid" && !draftChange) fail("AGDF_RUN_SEAL_INVALID");
-  const rows = control.artefact_chain.filter(row => row.from === expected.from);
-  if (rows.length > 1 || rows.some(row => !sameRelationship(row, expected))) fail("AGDF_ARTEFACT_BINDING_PROOF_INVALID");
-  const evidence = `binding ${candidate.binding_id}; reviewed by ${candidate.review.reviewer}; ${candidate.review.path}`;
-  let text = upsertTableRow(run.content, "Artefacts", 0, input.gate, [input.gate, candidate.destination.path, candidate.destination.status, "Reviewed source binding recorded atomically"]);
-  text = text && upsertTableRow(text, "Artefact Chain", 0, expected.from, [expected.from, expected.relationship, expected.to, evidence]);
-  if (!text) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
-  text = appendArtefactBinding(text, candidate);
-  // Proof files are seal-bound too; historical proofs may not be silently rewritten on update.
-  text = upsertTableRow(text, "Artefacts", 0, `Binding proof ${candidate.binding_id}`, [`Binding proof ${candidate.binding_id}`, candidate.review.path, "done", "Subordinate reviewed mapping evidence"]);
-  text = text && appendTableRow(text, "Evidence", ["Artefact source binding", candidate.review.path, `${expected.from} ${expected.relationship} ${expected.to}; binding ${candidate.binding_id}; operation ${candidate.operation.id}; ${input.revisionId} -> ${candidate.operation.resulting_revision_id}`, "reviewed cooperative mapping"]);
-  if (!text) fail("AGDF_ARTEFACT_RECORDING_INPUT_INVALID");
-  const snapshot = canonicalJson([candidate, command]);
-  return { text, receipt: candidate, nextRevisionId: candidate.operation.resulting_revision_id, allowContentChange: draftChange,
+  const relationship = { from: expected.from, relationship: expected.relationship, to: expected.to };
+  const prior = bindings.latest.filter(item => canonicalJson(item.relationship) === canonicalJson(relationship));
+  if (prior.length > 1 || prior.length && !input.updateDraft) fail('AGDF_ARTEFACT_RECORDING_INPUT_INVALID');
+  const destination = { type: expected.from, path: runDocumentPath(input.runId, `${expected.from}.md`),
+    digest: input.stagedMaterial.digest, status: input.gate === 'QA' ? readReportDecision(input.stagedMaterial.content) : 'draft' };
+  const candidate = bindInputResolution({ schema_version: ARTEFACT_BINDING_VERSION, binding_id: randomUUID(),
+    target_id: resolveControlCommandTarget(root).target_id, run_id: input.runId, relationship, destination,
+    source: { type: expected.to, path: source?.path, digest: artefactFileDigest(root, source?.path) },
+    review: { reviewer: input.reviewer, reviewed: true }, origin: 'reviewed_mapping',
+    operation: { id: input.operationId, previous_revision_id: input.revisionId, resulting_revision_id: randomUUID(),
+      revision: Number(run.meta.revision) + 1, request_digest: input.requestDigest }, supersedes: prior[0]?.binding_id ?? null });
+  const stagedDigest = path => path === destination.path ? destination.digest : artefactFileDigest(root, path);
+  if (!validArtefactBinding(candidate) || !source || source.status !== 'approved'
+    || control.approvals.get(expected.to)?.status !== 'approved' || !validateBindingProof(root, candidate, { fileDigest: stagedDigest })
+    || !exactApprovedArtefacts(root, control)) fail('AGDF_ARTEFACT_BINDING_PROOF_INVALID');
+  const old = control.artefacts.get(input.gate), seal = runSealState(root, run.content);
+  if (old?.path && old.path !== destination.path) fail('AGDF_ARTEFACT_RECORDING_INPUT_INVALID');
+  if (seal.status !== 'valid') fail('AGDF_RUN_SEAL_INVALID');
+  const output = prepareOwnedOutput(root, input.runId, destination.path, input.stagedMaterial.content);
+  return { text: appendArtefactBinding(run.content, candidate), receipt: candidate, nextRevisionId: candidate.operation.resulting_revision_id,
+    outputs: [output], allowContentChange: false,
     validateBeforeWrite: () => {
-      sourceRequest?.validate();
-      if (!validateBindingProof(root, candidate) || !exactApprovedArtefacts(root, control)
-          || canonicalJson([candidate, readContainedJson(root, input.evidence)]) !== snapshot
-          || artefactFileDigest(root, candidate.destination.path) !== candidate.destination.digest) fail("AGDF_ARTEFACT_BINDING_PROOF_INVALID");
+      input.stagedMaterial.validate?.();
+      if (!validateBindingProof(root, candidate) || !exactApprovedArtefacts(root, control)) fail('AGDF_ARTEFACT_BINDING_PROOF_INVALID');
     } };
 }