create-agdf 0.20.2 → 0.31.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/prepared-control-calls.js

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import { canonicalJson, digest } from './approval-command-contract.js';
+import { RUN_COMMAND_DESCRIPTORS, validateRunCommand } from './run-command-schema.js';
+import { closeoutConfirmation } from '../control-evaluation/closeout-readiness.js';
+import { REPORT_DECISION_FORMAT } from '../control-evaluation/report-decision.js';
+import { MATERIAL_LIMITS } from './material-limits.js';
+
+// Call construction only. The existing command/dispatch owners still validate
+// intent, current bindings, review, presentation and every actual mutation.
+export function continueDeliveryCall(input, runId = input.run_id) {
+  return { tool: 'agdf_dispatch', arguments: { presentation_language: input.presentation_language,
+    working_directory: input.working_directory, primary_target: input.primary_target, target_source: input.target_source,
+    skill_id: 'gate-check', run_id: runId, continue_delivery: true } };
+}
+
+// Observation of the original UUID, never a new write or refreshed revision.
+export function originalOperationCall(input) {
+  const kind = input.command?.kind;
+  if (!input.run_id && !input.planning && !['project.initialize', 'run.create'].includes(kind)) return undefined;
+  if (['material.stage', 'planned_material.stage', 'presentation.deliver'].includes(kind)) return undefined;
+  return { tool: 'agdf_inspect', arguments: {
+    presentation_language: input.presentation_language, working_directory: input.working_directory,
+    primary_target: input.primary_target, target_source: input.target_source,
+    operation: 'operation-status', module: input.planning || kind === 'project.initialize' ? `${kind}/${input.operation_id}` : input.operation_id,
+    ...(input.planning ? { planning: input.planning } : input.run_id ? { run_id: input.run_id, expected_revision_id: input.expected_revision_id } : {}),
+  } };
+}
+
+function compatible(schema, value) {
+  if (schema.oneOf || schema.anyOf) return (schema.oneOf ?? schema.anyOf).some(row => compatible(row, value));
+  if (schema.allOf) return schema.allOf.every(row => compatible(row, value));
+  if (schema.additionalProperties === false && value && typeof value === 'object'
+      && Object.keys(value).some(key => !Object.hasOwn(schema.properties ?? {}, key))) return false;
+  return Object.entries(schema.properties ?? {}).every(([key, rule]) => value?.[key] === undefined
+    || (!Object.hasOwn(rule, 'const') || value[key] === rule.const) && (!rule.enum || rule.enum.includes(value[key])));
+}
+
+function missing(schema, value, path) {
+  if (schema.oneOf || schema.anyOf) {
+    const variants = (schema.oneOf ?? schema.anyOf).filter(row => compatible(row, value));
+    return variants.length === 1 ? missing(variants[0], value, path) : [path];
+  }
+  if (schema.allOf) return [...new Set(schema.allOf.flatMap(row => missing(row, value, path)))];
+  if (schema.type === 'array' && Array.isArray(value)) return value.flatMap((row, i) => missing(schema.items, row, `${path}/${i}`));
+  if (schema.type !== 'object') return [];
+  return Object.entries(schema.properties ?? {}).flatMap(([key, rule]) => value?.[key] === undefined
+    ? (schema.required ?? []).includes(key) ? [`${path}/${key}`] : [] : missing(rule, value[key], `${path}/${key}`));
+}
+
+// Authoring gates whose staged source uses another material slot. A Quick Task
+// closes with its mandatory Code Review, so that report is the material it stages.
+const MATERIAL_SLOT_BY_GATE = Object.freeze({ 'Mode/Slice Decision': 'Brownfield Review',
+  'Verified Change Execution': 'Verified Change', 'Quick Task Execution': 'CR' });
+const INTERNAL_STEPS = Object.freeze(['UX Intent Definition', 'Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR']);
+// Reports whose recorded result Core reads with readReportDecision.
+const DECISION_REPORT_SLOTS = new Set(['Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR']);
+
+// Selects the one step.record variant an authoring gate records, so the form's
+// required inputs name concrete fields instead of the ambiguous whole payload.
+function recordingStep(gate) {
+  if (gate === 'UR') return { step: 'ur' };
+  if (['Brownfield Review', 'Mode/Slice Decision'].includes(gate)) return { step: 'route' };
+  if (gate === 'Quick Task Execution') return { step: 'review' };
+  if (INTERNAL_STEPS.includes(gate)) return { step: 'internal', internal_step: gate };
+  return {};
+}
+
+// A restaged OR may have a different material handle but the same command identity.
+function stagedCloseoutOperationId(binding, reportDigest) {
+  const hash = digest(`agdf-staged-closeout/1\0${canonicalJson([binding, reportDigest])}`).slice(7, 39);
+  const variant = (8 | (Number.parseInt(hash[16], 16) & 3)).toString(16);
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-8${hash.slice(13, 16)}-${variant}${hash.slice(17, 20)}-${hash.slice(20)}`;
+}
+
+// `revision` continues an accepted source revision preview: apply keeps the
+// preview's operation UUID, which the proposal binds, and its preview digest.
+export function preparedCommandCall(group, kind, input, { gate, material, recording, presentationId, revision } = {}) {
+  if (!RUN_COMMAND_DESCRIPTORS[kind] || RUN_COMMAND_DESCRIPTORS[kind].group !== group) return undefined;
+  let payload = {}, slot;
+  if (kind === 'material.stage') {
+    slot = MATERIAL_SLOT_BY_GATE[gate] ?? gate ?? 'EVIDENCE';
+    const roles = RUN_COMMAND_DESCRIPTORS[kind].payload_schema.oneOf.find(row => row.properties.action.const === 'put').properties.files.items.properties.slot.enum;
+    if (!roles.includes(slot)) return undefined;
+    payload = { action: 'put', files: [{ slot }] };
+  }
+  if (kind === 'artefact.record') payload = { ...(gate ? { gate } : {}), ...(material ? { material } : {}),
+    ...(recording?.available ? { update_draft: recording.update_draft } : {}) };
+  if (['presentation.prepare', 'presentation.deliver', 'approval.record'].includes(kind)) payload = {
+    ...(gate ? { gate } : {}), ...(presentationId ? { presentation_id: presentationId } : {}),
+    ...(kind === 'presentation.deliver' ? { route: 'automatic' } : {}) };
+  if (kind === 'ur_draft.replace' && material) payload = { source: material };
+  if (kind === 'step.record') payload = { ...(material ? { source: material } : {}), ...recordingStep(gate) };
+  // The proposal reference stays an input: staged material rarely outlives the
+  // person's confirmation, and restaging identical bytes keeps the same digest.
+  if (kind === 'source_revision.apply' && revision) payload = { source_gate: revision.source_gate, preview_digest: revision.preview_digest };
+  const unbound = ['run.create', 'project.initialize'].includes(kind);
+  const binding = { schema_version: '1', presentation_language: input.presentation_language,
+    working_directory: input.working_directory, primary_target: input.primary_target, target_source: input.target_source,
+    target_id: input.target_id, ...(!unbound ? { run_id: input.run_id, expected_revision_id: input.expected_revision_id } : {}),
+    assurance: 'cooperative_local' };
+  const stagedCloseout = kind === 'closeout.record' && material;
+  const operation_id = stagedCloseout ? stagedCloseoutOperationId(binding, material.digest) : revision?.operation_id ?? randomUUID();
+  if (stagedCloseout) payload = { or: material,
+    confirmation: closeoutConfirmation(binding.run_id, binding.expected_revision_id, operation_id, material.digest) };
+  const argumentsValue = { ...binding, operation_id, command: { kind, payload } };
+  const required = missing(RUN_COMMAND_DESCRIPTORS[kind].payload_schema, payload, '/command/payload');
+  const valid = validateRunCommand(group, argumentsValue).length === 0;
+  return { state: valid ? 'ready' : 'requires_author_input', call: { tool: group, arguments: argumentsValue },
+    required_inputs: valid ? [] : required.length ? required : ['/command/payload'], authorizes: false,
+    ...(kind === 'material.stage' ? { content_contract: {
+      encoding: 'UTF-8', max_utf8_bytes_per_file: RUN_COMMAND_DESCRIPTORS[kind].payload_schema.oneOf[0].properties.files.items.properties.content.maxLength,
+      instruction: 'put accepts text up to this UTF-8 limit within the 64 KiB whole JSON request bound; no client hashes or byte counts are needed. If either bound would be exceeded, retain the complete text and use the supplied larger_source_call for multipart; never truncate or shorten approved source to fit.',
+      larger_source_call: { tool: 'agdf_inspect', arguments: { operation: 'operation-contract', module: `${group}/${kind}`,
+        presentation_language: input.presentation_language, working_directory: input.working_directory,
+        primary_target: input.primary_target, target_source: input.target_source,
+        run_id: input.run_id, expected_revision_id: input.expected_revision_id } },
+      // Staged material is private to the serving MCP process and short-lived,
+      // so a recording that waits for a person must not stage first.
+      retention: { idle_ms: MATERIAL_LIMITS.idle, lifetime_ms: MATERIAL_LIMITS.lifetime, scope: 'serving MCP server process',
+        instruction: 'Stage only when every input of the following recording (for example reviewer and review confirmation) is already available. Staged material does not survive a reconnect or a pause beyond idle_ms. After expiry stage the identical bytes again: a form that takes the material reference as an input (closeout, source revision apply) is reused with the new reference, which keeps its UUID and any confirmation valid; otherwise use the recording form returned by the new staging.' },
+      ...(DECISION_REPORT_SLOTS.has(slot) ? { report_decision: REPORT_DECISION_FORMAT } : {}),
+    } } : {}),
+    ...(kind === 'approval.record' && gate ? { contract_call: { tool: 'agdf_inspect', arguments: {
+      operation: 'operation-contract', module: 'agdf_approve/approval.record',
+      presentation_language: input.presentation_language, working_directory: input.working_directory,
+      primary_target: input.primary_target, target_source: input.target_source,
+      run_id: input.run_id, expected_revision_id: input.expected_revision_id, gate,
+    } }, response_contract: {
+      approval_value: `Approval: ${gate}`, exact: true,
+      instruction: 'Only a NEW deliberate reply for this presentation. Put the exact reply alone in response; simulation/reviewer explanation belongs outside response. Never prefix or suffix the approval formula. This value is a format, not a decision or permission. The complete approval form already binds the revision and presentation; fill response without another contract read. If explanatory schema help is needed, copy contract_call exactly; never omit or guess expected_revision_id.' } } : {}),
+    ...(kind === 'source_revision.apply' && revision ? { confirmation_contract: { confirmation_value: revision.confirmation_selector, exact: true,
+      instruction: 'confirmation is only the person\'s NEW deliberate reply with exactly this text. proposal is the reference of the previewed proposal; if its staged material expired, stage the identical bytes again and use the new reference. This form keeps the previewed UUID and digest.' } } : {}),
+    ...(stagedCloseout && valid ? { operation_status_call: originalOperationCall(argumentsValue) } : {}),
+    instruction: stagedCloseout
+      ? 'Invoke the supplied closeout separately. If its effect is uncertain, inspect the original operation first. If material expired and restaging is appropriate, stage the identical OR with the original binding and use the returned form for the same operation and digest.'
+      : 'Fill required_inputs from actual authored content, review or a NEW deliberate reply. Preserve the supplied binding and UUID. Retry an uncertain dispatch with the identical call; each new logical command already has its own supplied UUID; do not regenerate it or put IDs in inputs. This form is not permission or an approval.' };
+}

package/generated/plugins/agdf/runtime/create-agdf/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/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/presentation-delivery.js

@@ -0,0 +1,93 @@
+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';
+import { preparedCommandCall } from './prepared-control-calls.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, next_calls: [],
+        ...(!historical ? { approval_call: preparedCommandCall('agdf_approve', 'approval.record', input,
+          { gate: payload.gate, presentationId: payload.presentation_id }) } : {}), 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/generated/plugins/agdf/runtime/create-agdf/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/generated/plugins/agdf/runtime/create-agdf/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/generated/plugins/agdf/runtime/create-agdf/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/generated/plugins/agdf/runtime/create-agdf/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/generated/plugins/agdf/runtime/create-agdf/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');
     } };
 }