create-agdf 0.14.5 → 0.20.1

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

@@ -0,0 +1,143 @@
+import { UR_AUTHORING_FORMAT } from '../control-evaluation/ur-readiness.js';
+import { PRD_DECISION_FORMAT } from '../control-evaluation/prd-readiness.js';
+import { SD_DECISION_FORMAT } from '../control-evaluation/sd-readiness.js';
+import { DIGEST_PATTERN, canonicalJson, digest } from './approval-command-contract.js';
+import { RUN_ID_PATTERN, REVISION_ID_PATTERN, APPROVAL_GATES } from './run-identity.js';
+import { TASK_TARGET_SOURCES } from '../task-target-resolution.js';
+import { PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE } from '../interaction-presentation.js';
+import { ACCEPTANCE_CRITERIA_FORMAT, TP_AUTHORING_FORMAT } from '../control-evaluation/traceability-readiness.js';
+import { UX_DECISION_FORMAT } from '../control-evaluation/definition-sources.js';
+import { REVIEWED_REQUEST_FORMAT, REVISION_PROPOSAL_FORMAT } from './recording-formats.js';
+import { relationshipForGate } from '../control-evaluation/delivery-relationships.js';
+import { PREVIEW_REVIEW_FORMAT } from './preview-review.js';
+
+export const RUN_COMMAND_VERSION = '1';
+export const RUN_COMMAND_LIMITS = Object.freeze({ input_bytes: 65536, result_bytes: 1048576, definition_bytes: 8192, aggregate_definition_bytes: 24576 });
+const string = (maxLength = 4096) => ({ type: 'string', minLength: 1, maxLength });
+const identity = { type: 'string', pattern: REVISION_ID_PATTERN.source };
+const hash = { type: 'string', pattern: DIGEST_PATTERN.source };
+const enumeration = values => ({ enum: [...values] });
+export const strictObject = (properties, required = Object.keys(properties)) => ({ type: 'object', additionalProperties: false, properties, required });
+const source = strictObject({ path: string(), digest: hash });
+const recoveryGroups = Object.freeze({ 'step.record': 'agdf_record', 'artefact.record': 'agdf_record',
+  'presentation_decision.record': 'agdf_record', 'prd_revision.reopen': 'agdf_revise', 'closeout.record': 'agdf_closeout' });
+const recovery = strictObject({ original_kind: enumeration(Object.keys(recoveryGroups)), pending_digest: hash, recovery_revision_id: identity });
+const recordStep = { oneOf: [
+  strictObject({ step: { const: 'ur' }, source, title: string(1024) }),
+  strictObject({ step: { const: 'route' }, source, reason: string(8192), route: enumeration(['quick_task', 'structured_slice', 'structured_delivery']) }),
+  strictObject({ step: { const: 'review' }, source, decision: enumeration(['pass', 'revise', 'block']) }),
+  strictObject({ step: { const: 'evidence' }, source, reason: string(8192), covers: string(1024) }),
+  { oneOf: [strictObject({ step: { const: 'internal' }, source,
+    internal_step: { const: 'UX Intent Definition' }, decision: enumeration(['ready', 'blocked', 'not_applicable']), reason: string(8192), covers: string(1024),
+  }, ['step', 'source', 'internal_step', 'decision']), strictObject({ step: { const: 'internal' }, source,
+    internal_step: enumeration(['Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR']),
+    decision: enumeration(['pass', 'revise', 'block', 'not_applicable']), reason: string(8192), covers: string(1024),
+  }, ['step', 'source', 'internal_step', 'decision'])] },
+] };
+
+const spec = (group, payload, owner, effects, confirmation = 'authorized_recording') => ({ group, payload_schema: payload, owner, effects, confirmation });
+const proposal = strictObject({ source_gate: enumeration(['UR', 'PRD', 'SD', 'TP']), proposal: source });
+const apply = strictObject({ ...proposal.properties, preview_digest: hash, confirmation: string(8192) });
+const closeout = strictObject({ or: source, confirmation: string(8192) });
+const descriptors = {
+  'runtime_generation.replace': spec('agdf_record', strictObject({ candidate: source, confirmation: string(256) }), 'owned-runtime-generation.replace', ['replace only the serving facade own runtime; no Run or gate write'], 'concrete_candidate_digest'),
+  'presentation.prepare': spec('agdf_prepare', strictObject({ gate: enumeration(APPROVAL_GATES) }), 'run-presentation.prepareRunPresentation', ['create immutable exact presentation'], 'no_gate_approval'),
+  'step.record': spec('agdf_record', recordStep, 'run-steps.recordRunStep', ['register bounded actual internal/evidence result; update Run/backlog']),
+  'artefact.record': spec('agdf_record', strictObject({ gate: enumeration(['PRD', 'SD', 'TP', 'QA']), reviewed_request: source }), 'run-artefact-recording.prepareArtefactRecording', ['register reviewed source mapping; replace only unapproved draft']),
+  'approval.record': spec('agdf_approve', strictObject({ gate: enumeration(APPROVAL_GATES), presentation_id: identity, response: string(8192) }), 'approval-command.executeApprovalCommand', ['record one exact deliberate gate reply'], 'new_deliberate_exact_reply'),
+  'presentation_decision.record': spec('agdf_record', strictObject({ gate: enumeration(APPROVAL_GATES), presentation_id: identity,
+    action: enumeration(['request_change', 'reject']), comment: { type: 'string', maxLength: 8192 } }),
+    'run-steps.recordRunPresentationDecision', ['record one exact deliberate change request or rejection; no gate approval'], 'new_deliberate_bound_human_reply'),
+  'source_revision.preview': spec('agdf_revise', proposal, 'run-revision.previewSourceRevision', ['read exact revision impact'], 'no_mutation'),
+  'source_revision.apply': spec('agdf_revise', apply, 'run-revision.applySourceRevision', ['archive selected material; invalidate affected decisions; reopen earliest source'], 'exact_material_confirmation'),
+  'source_revision.recover': spec('agdf_revise', strictObject({ proposal: source, source_gate: enumeration(['UR', 'PRD', 'SD', 'TP']), recovery_revision_id: identity, pending_digest: hash }), 'run-revision.recoverSourceRevision', ['recover original bounded source revision'], 'original_confirmed_effect'),
+  'prd_revision.reopen': spec('agdf_revise', strictObject({ prd: source, confirmation: string(8192) }), 'run-revision.reopenPrdRevision', ['reopen existing early PRD boundary preserving history'], 'exact_material_confirmation'),
+  'closeout.record': spec('agdf_closeout', closeout, 'run-steps.recordRunStep', ['publish exact OR; complete selected Run; synchronize selected backlog'], 'exact_material_confirmation'),
+  'operation.recover': { ...spec(null, recovery, 'run-step-transaction.recoverPendingRunStep', ['recover original bounded owned outputs and selected backlog'], 'original_confirmed_effect'), groups: ['agdf_record', 'agdf_revise', 'agdf_closeout'] },
+};
+function freeze(value) { if (value && typeof value === 'object' && !Object.isFrozen(value)) { Object.values(value).forEach(freeze); Object.freeze(value); } return value; }
+export const RUN_COMMAND_DESCRIPTORS = freeze(descriptors);
+export const RUN_COMMAND_GROUPS = freeze({
+  agdf_prepare: ['presentation.prepare'], agdf_record: ['step.record', 'artefact.record', 'presentation_decision.record', 'runtime_generation.replace', 'operation.recover'],
+  agdf_approve: ['approval.record'], agdf_revise: ['source_revision.preview', 'source_revision.apply', 'source_revision.recover', 'prd_revision.reopen', 'operation.recover'],
+  agdf_closeout: ['closeout.record', 'operation.recover'],
+});
+const envelope = {
+  schema_version: { const: RUN_COMMAND_VERSION }, presentation_language: { type: 'string', maxLength: 64, pattern: PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE },
+  working_directory: string(), target_source: enumeration(TASK_TARGET_SOURCES), primary_target: string(), target_id: hash,
+  run_id: { type: 'string', pattern: RUN_ID_PATTERN.source }, expected_revision_id: identity, operation_id: identity,
+  assurance: { const: 'cooperative_local' },
+};
+function payloadSchema(group, kind) {
+  return kind === 'operation.recover' ? strictObject({ ...recovery.properties,
+    original_kind: enumeration(Object.keys(recoveryGroups).filter(original => recoveryGroups[original] === group)) })
+    : RUN_COMMAND_DESCRIPTORS[kind].payload_schema;
+}
+export function commandGroupSchema(group) {
+  const kinds = RUN_COMMAND_GROUPS[group]; if (!kinds) throw Error('command_group_unsupported');
+  return strictObject({ ...envelope, command: { oneOf: kinds.map(kind => strictObject({ kind: { const: kind }, payload: payloadSchema(group, kind) })) } });
+}
+export function commandGroupDefinition(group) {
+  const definition = { name: group,
+    description: `${group}: ${RUN_COMMAND_GROUPS[group]?.join(', ')}. Exact target/Run/revision/UUID required. Cooperative caller intent only; tool permission never approves a gate. Inspect operation-contract before use; retry original UUID via operation-status after uncertainty. No VCS.`,
+    annotations: { readOnlyHint: false, destructiveHint: group !== 'agdf_prepare', idempotentHint: false, openWorldHint: false }, inputSchema: commandGroupSchema(group) };
+  if (Buffer.byteLength(JSON.stringify(definition)) > RUN_COMMAND_LIMITS.definition_bytes) throw Error('command_definition_budget_exceeded');
+  return freeze(definition);
+}
+// A deliberately small schema interpreter over the same generated JSON Schema subset.
+// No caller validator, accessor execution, coercion or default-expanded effect is allowed.
+export function schemaDiagnostics(value, schema, path = '$') {
+  const errors = [];
+  if (schema.oneOf) return schema.oneOf.filter(choice => schemaDiagnostics(value, choice, path).length === 0).length === 1 ? [] : [{ path, code: 'one_of_invalid' }];
+  if (Object.hasOwn(schema, 'const') && value !== schema.const) errors.push({ path, code: 'constant_invalid' });
+  if (schema.enum && !schema.enum.includes(value)) errors.push({ path, code: 'enum_invalid' });
+  if (schema.type === 'object') {
+    if (value === null || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return [{ path, code: 'object_required' }];
+    const keys = Reflect.ownKeys(value);
+    for (const key of keys) {
+      if (typeof key !== 'string' || !Object.hasOwn(schema.properties, key)) { errors.push({ path, code: 'unknown_field' }); continue; }
+      const property = Object.getOwnPropertyDescriptor(value, key);
+      if (!Object.hasOwn(property, 'value')) { errors.push({ path: `${path}.${key}`, code: 'accessor_forbidden' }); continue; }
+      errors.push(...schemaDiagnostics(property.value, schema.properties[key], `${path}.${key}`));
+    }
+    for (const key of schema.required ?? []) if (!Object.hasOwn(value, key)) errors.push({ path: `${path}.${key}`, code: 'field_required' });
+  }
+  if (schema.type === 'string') {
+    if (typeof value !== 'string') return [...errors, { path, code: 'string_required' }];
+    if (schema.minLength !== undefined && value.length < schema.minLength || schema.maxLength !== undefined && value.length > schema.maxLength
+      || schema.pattern && !(new RegExp(schema.pattern, 'u')).test(value)) errors.push({ path, code: 'string_invalid' });
+  }
+  return errors;
+}
+export function validateRunCommand(group, input) {
+  if (!RUN_COMMAND_GROUPS[group]) return [{ path: '$', code: 'command_group_unsupported' }];
+  const errors = schemaDiagnostics(input, commandGroupSchema(group));
+  if (errors.length) return errors;
+  if (Buffer.byteLength(canonicalJson(input)) > RUN_COMMAND_LIMITS.input_bytes) return [{ path: '$', code: 'command_input_budget_exceeded' }];
+  const kind = input.command.kind;
+  if (kind === 'operation.recover' && group !== recoveryGroups[input.command.payload.original_kind]) return [{ path: '$.command.payload.original_kind', code: 'command_group_effect_mismatch' }];
+  return [];
+}
+export const runCommandRequestDigest = input => digest(`agdf-run-command/1\0${canonicalJson(input)}`);
+export function operationContract(group, kind, { gate } = {}) {
+  if (!RUN_COMMAND_GROUPS[group]?.includes(kind)) return { available: false, reason: 'command_group_unsupported' };
+  return { schema_version: RUN_COMMAND_VERSION, available: true, group, kind, ...RUN_COMMAND_DESCRIPTORS[kind], payload_schema: payloadSchema(group, kind),
+    schema: strictObject({ ...envelope, command: strictObject({ kind: { const: kind }, payload: payloadSchema(group, kind) }) }), retry_class: 'inspect_original_operation_after_dispatch', assurance: 'cooperative_local',
+    reference_limits: { input_bytes: RUN_COMMAND_LIMITS.input_bytes, source_file_bytes: 131072, result_bytes: RUN_COMMAND_LIMITS.result_bytes },
+    internal_result_formats: kind === 'step.record' ? { 'UX Intent Definition': UX_DECISION_FORMAT,
+      reviews: { declaration: '- decision: pass | revise | block | not_applicable', result_scope: 'actual current owner report; no generated judgement or approval' } } : undefined,
+    reviewed_request_format: kind === 'artefact.record' ? { ...REVIEWED_REQUEST_FORMAT, current_relationship: relationshipForGate(gate) ?? null,
+      destination_status: gate === 'QA' ? 'pass | revise | block matching the actual QA report' : 'draft' } : undefined,
+    proposal_format: kind.startsWith('source_revision.') ? REVISION_PROPOSAL_FORMAT : undefined,
+    authorizes: false, authoring_format: kind === 'artefact.record' || kind === 'presentation.prepare' || kind === 'step.record'
+      ? ({ UR: UR_AUTHORING_FORMAT, PRD: { decisions: PRD_DECISION_FORMAT, criteria: ACCEPTANCE_CRITERIA_FORMAT, preview_review: PREVIEW_REVIEW_FORMAT }, SD: SD_DECISION_FORMAT, TP: TP_AUTHORING_FORMAT }[gate] ?? null) : undefined,
+    presentation_format: kind === 'presentation.prepare' || kind === 'artefact.record' ? {
+      owner: 'run-presentation-render', compact_brief_fields: ['Goal/Ziel', 'Proposal/Vorschlag or Scope/Umfang', 'Changes/Änderungen', 'Risks/Risiken'],
+      source: 'source-authored canonical artefact or validated localized AGDF Approval Summary; no adapter paraphrase',
+      missing_fields: 'retain absence and the complete validated summary; do not fabricate a legacy brief',
+      delivery: 'native_plus_chat only with qualified native approval and confirmed display on the current user surface; otherwise full_chat; forward one exact decision request. Mac display never proves iPad visibility.',
+      remote_document: 'presentation-document; exact binding and every cursor; local file links do not prove iPad access',
+      remote_preview: 'presentation-preview; exact binding and every cursor; render only through isolated supported access; unavailable access leaves the review open',
+    } : undefined,
+    confirmation_boundary: 'host permission, concrete human intent and Core eligibility are separate' };
+}

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

@@ -0,0 +1,174 @@
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { resolveTaskTarget } from '../task-target-resolution.js';
+import { withLiveControlReads } from '../control-read/fs.js';
+import { evaluateGateCheck } from '../control-evaluation/gate-check.js';
+import { policyForRunContent } from '../control-evaluation/run-step-policy.js';
+import { RUN_COMMAND_GROUPS, RUN_COMMAND_LIMITS, runCommandRequestDigest, validateRunCommand } from './run-command-contract.js';
+import { COOPERATIVE_ASSURANCE, canonicalJson, digest, resolveControlCommandTarget } from './approval-command-contract.js';
+import { readRun } from './run-state-edits.js';
+import { runSealState } from './run-seal.js';
+import { runPath } from './run-state-reader.js';
+import { withOwnedFileLock } from './run-state-writer.js';
+import { assertRunOperationIdentity } from './run-operation-identity.js';
+import { prepareRunPresentation } from './run-presentation.js';
+import { executeApprovalCommand } from './approval-command.js';
+import { recordRunStep, recordRunPresentationDecision } from './run-steps.js';
+import { inspectRunOperation } from './run-operation-status.js';
+import { readOperationSource } from './run-operation-proof.js';
+import { pendingRunStepIds, pendingRunStepPath } from './run-step-pending.js';
+import { readPendingRunStepJournal, recoverPendingRunStepLocked } from './run-step-transaction.js';
+import { previewSourceRevision, applySourceRevision, recoverSourceRevision, reopenPrdRevision } from './run-revision.js';
+import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
+import { parseRunState } from './run-state-parser.js';
+import { existsSync } from 'node:fs';
+
+function safeOperationStatus(root, input) {
+  try { return inspectRunOperation(root, { runId: input.run_id, operationId: input.operation_id, targetId: input.target_id }); }
+  catch { return { status: 'unknown', reason: 'operation_observation_unavailable' }; }
+}
+
+function assertCommandRunPath(root, input) {
+  const relative = `.agdf/control/runs/${input.run_id}/RUN_STATE.md`;
+  if (hasSymlinkComponent(root, relative) || containedRegularFile(root, relative).status !== 'valid') throw Error('run_path_invalid');
+}
+
+export function observeCurrentRunCommand(root, input) {
+  try {
+    const run = readRun(root, input.run_id);
+    if (run.rejection) return { available: false, reason: run.rejection.reason };
+    if (runSealState(root, run.content).status !== 'valid') return { available: false, reason: 'seal_invalid' };
+    const report = evaluateGateCheck(root, { runId: input.run_id, presentationLanguage: input.presentation_language });
+    return { available: true, revision: Number(run.meta.revision), revision_id: run.meta.revision_id, lifecycle: run.meta.lifecycle,
+      gate: report.current_gate, status: report.status, missing_approval: report.missing_approval,
+      blocking_reason: report.blocking_reason ?? null, next_operation: report.next_operation, completion: report.completion };
+  } catch { return { available: false, reason: 'current_observation_unavailable' }; }
+}
+
+function boundedRecover(root, input) {
+  const payload = input.command.payload, path = runPath(root, input.run_id);
+  assertCommandRunPath(root, input);
+  return withOwnedFileLock(path, () => withOwnedFileLock(join(root, '.agdf/control/MASTER_BACKLOG.md'), () => {
+    const other = pendingRunStepIds(root).find(id => id !== input.run_id);
+    if (other) return { outcome: 'recovery_required', reason: 'another_pending_operation', pending_run_id: other };
+    if (!existsSync(pendingRunStepPath(root, input.run_id))) {
+      const observed = safeOperationStatus(root, input);
+      return observed.status === 'recorded' && observed.family === payload.original_kind
+        ? { outcome: 'recovered', status: 'already_completed', historical_effect: true, receipt: observed.receipt }
+        : { outcome: 'recovery_required', reason: 'original_operation_unconfirmed' };
+    }
+    const pending = readPendingRunStepJournal(root, input.run_id);
+    if (pending.schema_version !== 3 || pending.kind !== payload.original_kind || pending.operation_id !== input.operation_id
+      || pending.target_id !== input.target_id || digest(canonicalJson(pending)) !== payload.pending_digest
+      || ![pending.old_revision_id, pending.next_revision_id].includes(input.expected_revision_id)
+      || payload.recovery_revision_id !== input.expected_revision_id) return { outcome: 'rejected', reason: 'recovery_binding_invalid' };
+    const statePath = `.agdf/control/runs/${input.run_id}/RUN_STATE.md`;
+    if (hasSymlinkComponent(root, statePath) || containedRegularFile(root, statePath).status !== 'valid') return { outcome: 'rejected', reason: 'run_path_invalid' };
+    const raw = readFileSync(path, 'utf8');
+    const parsed = parseRunState(raw, input.run_id);
+    if (!parsed.valid || parsed.meta.revision_id !== input.expected_revision_id) return { outcome: 'rejected', reason: 'stale_revision' };
+    return { outcome: 'recovered', ...recoverPendingRunStepLocked(root, input.run_id) };
+  }));
+}
+
+// The public selector is a fixed permission group, never an arbitrary function name.
+// Adapters receive this same service; private dependencies are package-owned test seams.
+export function createRunCommandService({ packageVersion = '0.14.5', enabledGroups = Object.keys(RUN_COMMAND_GROUPS), checkpoint = () => {}, runtimeControl } = {}) {
+  if (!Array.isArray(enabledGroups) || new Set(enabledGroups).size !== enabledGroups.length) throw Error('command_group_unsupported');
+  const enabled = new Set(enabledGroups);
+  if ([...enabled].some(group => !Object.hasOwn(RUN_COMMAND_GROUPS, group))) throw Error('command_group_unsupported');
+  return function executeRunCommand(group, input) {
+    return withLiveControlReads(() => {
+      const diagnostics = validateRunCommand(group, input);
+      if (diagnostics.length) return { schema_version: '1', outcome: 'rejected', reason: 'command_schema_invalid', diagnostics, authorizes: false };
+      const requestDigest = runCommandRequestDigest(input);
+      let root, dispatched = false;
+      const result = (outcome, reason, family = {}, extra = {}) => {
+        const status = root ? safeOperationStatus(root, input) : null;
+        const receipt = family.receipt ?? status?.receipt ?? null;
+        const response = { schema_version: '1', outcome, reason: reason ?? null, operation_id: input.operation_id,
+          request_digest: requestDigest, binding: { target_id: input.target_id, run_id: input.run_id, expected_revision_id: input.expected_revision_id, kind: input.command.kind },
+          effect: receipt?.effect ?? null, receipt, historical_effect: Boolean(family.historical_effect || outcome === 'already_applied'),
+          current: root ? observeCurrentRunCommand(root, input) : { available: false, reason: 'target_unavailable' },
+          assurance: COOPERATIVE_ASSURANCE, authorizes: false,
+          recovery: ['effect_unknown', 'recovery_required'].includes(outcome) ? 'Inspect operation-status with the original UUID and preserve the exact original payload. Do not infer absence or create another decision.' : null,
+          family_result: family, ...extra };
+        if (Buffer.byteLength(JSON.stringify(response)) > RUN_COMMAND_LIMITS.result_bytes) return { schema_version: '1', outcome: dispatched ? 'effect_unknown' : 'rejected',
+          reason: 'command_result_budget_exceeded', operation_id: input.operation_id, binding: response.binding, authorizes: false,
+          recovery: 'Inspect operation-status with the original UUID. A lost response does not prove non-execution.' };
+        return response;
+      };
+      if (!enabled.has(group)) return result('rejected', 'command_group_disabled', {}, { dispatch: 'not_dispatched' });
+      try {
+        const target = resolveTaskTarget({ workingDirectory: input.working_directory, targetSource: input.target_source, primaryTarget: input.primary_target });
+        if (target.resolution_state !== 'resolved') return result('rejected', target.reason_code, {}, { dispatch: 'not_dispatched' });
+        root = target.governance_target;
+        if (resolveControlCommandTarget(root).target_id !== input.target_id) return result('rejected', 'target_binding_mismatch', {}, { dispatch: 'not_dispatched' });
+        const payload = input.command.payload, kind = input.command.kind;
+        const context = { kind, operation_id: input.operation_id, target_id: input.target_id, request_digest: requestDigest };
+        const bound = { runId: input.run_id, revisionId: input.expected_revision_id, operationId: input.operation_id };
+        assertCommandRunPath(root, input);
+        let family;
+        if (kind === 'runtime_generation.replace') {
+          const current = observeCurrentRunCommand(root, input);
+          if (!current.available || current.revision_id !== input.expected_revision_id) return result('rejected', 'stale_revision');
+          if (current.lifecycle !== 'active') return result('rejected', 'lifecycle_ineligible');
+          if (payload.confirmation !== `Replace owned runtime: ${payload.candidate.digest}`) return result('rejected', 'confirmation_required');
+          if (!runtimeControl) return result('rejected', 'connection_control_unavailable', {}, { dispatch: 'not_dispatched' });
+          const source = readOperationSource(root, input.run_id, payload.candidate);
+          const candidate = JSON.parse(source.content);
+          // The shared Core validates the current binding and contained manifest;
+          // only the serving facade owns an actual process handle. No Run write.
+          return Promise.resolve(runtimeControl.replace({ input, candidate, requestDigest,
+            revalidate: () => {
+              source.validate(); const fresh = observeCurrentRunCommand(root, input);
+              if (!fresh.available || fresh.revision_id !== input.expected_revision_id) throw Error('stale_revision');
+            } })).then(family => result(family.outcome, family.reason, family, { runtime_control: true }),
+              error => result('effect_unknown', error.message, {}, { runtime_control: true }));
+        }
+        checkpoint('before_dispatch'); dispatched = true;
+        if (kind === 'presentation.prepare') {
+          family = withOwnedFileLock(runPath(root, input.run_id), () => {
+            const run = readRun(root, input.run_id); if (run.rejection) return run.rejection;
+            assertRunOperationIdentity(root, run, input.operation_id, kind);
+            return prepareRunPresentation(root, { ...bound, gate: payload.gate, language: input.presentation_language, requestDigest }, { evaluateGateCheck, checkpoint });
+          });
+        } else if (kind === 'approval.record') {
+          family = executeApprovalCommand(root, { schema_version: '1', action: 'record_gate_approval', target_id: input.target_id,
+            run_id: input.run_id, expected_revision_id: input.expected_revision_id, operation_id: input.operation_id,
+            assurance: input.assurance, gate: payload.gate, presentation_id: payload.presentation_id, response: payload.response }, { evaluateGateCheck, packageVersion, checkpoint, commandContext: context });
+        } else if (kind === 'presentation_decision.record') {
+          family = recordRunPresentationDecision(root, { ...bound, gate: payload.gate, presentationId: payload.presentation_id,
+            action: payload.action, comment: payload.comment, requestDigest }, { evaluateGateCheck, packageVersion, afterWrite: checkpoint });
+        } else if (kind === 'step.record' || kind === 'artefact.record') {
+          const record = kind === 'artefact.record' ? { step: 'artefact', gate: payload.gate, evidence: payload.reviewed_request.path, sourceBinding: payload.reviewed_request }
+            : { step: payload.step, sourceBinding: payload.source, evidence: payload.source.path, title: payload.title,
+              route: payload.route, reason: payload.reason, decision: payload.decision, covers: payload.covers, internalStep: payload.internal_step };
+          family = recordRunStep(root, { ...bound, ...record }, { policy: policyForRunContent, packageVersion, operationContext: context, afterWrite: checkpoint });
+        } else if (kind === 'operation.recover') family = boundedRecover(root, input);
+        else if (kind === 'source_revision.preview' || kind === 'source_revision.apply') {
+          const revised = { ...bound, sourceGate: payload.source_gate, evidence: payload.proposal.path, previewDigest: payload.preview_digest,
+            proposalBinding: payload.proposal, confirmation: payload.confirmation, commandContext: context, packageVersion };
+          family = kind.endsWith('.apply') ? applySourceRevision(root, revised, { afterWrite: checkpoint }) : previewSourceRevision(root, revised);
+        } else if (kind === 'source_revision.recover') {
+          family = recoverSourceRevision(root, { ...bound, proposalBinding: payload.proposal, evidence: payload.proposal.path, sourceGate: payload.source_gate,
+            recoveryRevisionId: payload.recovery_revision_id, pendingDigest: payload.pending_digest });
+        } else if (kind === 'prd_revision.reopen') {
+          family = reopenPrdRevision(root, { ...bound, prdBinding: payload.prd, confirmation: payload.confirmation, commandContext: context, packageVersion }, { afterWrite: checkpoint });
+        } else if (kind === 'closeout.record') {
+          family = recordRunStep(root, { ...bound, step: 'closeout', sourceBinding: payload.or, confirmation: payload.confirmation },
+            { policy: policyForRunContent, packageVersion, operationContext: context, afterWrite: checkpoint });
+        }
+        checkpoint('before_result');
+        const accepted = ['prepared', 'recorded', 'accepted', 'preview', 'recovered', 'reopened'].includes(family?.outcome);
+        const repeated = ['already_applied', 'already_prepared', 'replayed'].includes(family?.outcome);
+        const status = safeOperationStatus(root, input);
+        if (family?.outcome === 'rejected' && ['pending', 'unknown', 'committed_recovery_required'].includes(status.status)) return result('effect_unknown', family.reason, family);
+        return result(repeated ? 'already_applied' : accepted ? 'accepted' : family?.outcome === 'recovery_required' ? 'recovery_required' : 'rejected', family?.reason, family ?? {});
+      } catch (error) {
+        if (error.message === 'AGDF_OPERATION_PAYLOAD_CONFLICT') return result('rejected', 'operation_payload_conflict');
+        return result(dispatched ? 'effect_unknown' : 'rejected', error.message, {}, { dispatch: dispatched ? 'dispatched' : 'not_dispatched' });
+      }
+    });
+  };
+}

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

@@ -1,5 +1,6 @@
 export const RUN_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
 export const REVISION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const APPROVAL_GATES = Object.freeze(["UR", "PRD", "SD", "TP", "QA", "UAT"]);
 
 export function validateRunIdentity({ runId, revisionId } = {}) {
   const findings = [];

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

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readRunOperations } from './run-operations.js';
+import { readApprovalOperations } from './approval-operations.js';
+import { readArtefactBindings } from './artefact-bindings.js';
+import { readSourceRevisions } from './run-source-revisions.js';
+import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
+import { REVISION_ID_PATTERN } from './run-identity.js';
+import { validateRunPresentationEnvelope } from './run-presentation.js';
+
+// Called under the existing selected Run lock. This is identity reservation only;
+// the original family alone validates payload, eligibility, receipt and replay.
+export function assertRunOperationIdentity(root, run, operationId, family) {
+  if (!REVISION_ID_PATTERN.test(operationId ?? '')) throw Error('AGDF_OPERATION_BINDING_INVALID');
+  const receipts = [
+    ...readRunOperations(run.content).receipts.map(r => [r.operation_id, r.kind]),
+    ...readApprovalOperations(run.content).receipts.map(r => [r.operation_id, 'approval.record']),
+    ...readArtefactBindings(run.content).receipts.map(r => [r.operation.id, 'artefact.record']),
+    ...readSourceRevisions(run.content).receipts.map(r => [r.operation_id, 'source_revision.apply']),
+  ].filter(([id]) => id === operationId);
+  if (receipts.length > 1 || receipts.some(([, kind]) => kind !== family)) throw Error('AGDF_OPERATION_PAYLOAD_CONFLICT');
+  const path = `.agdf/control/runs/${run.meta.run_id}/presentations/${operationId}.json`;
+  if (!existsSync(join(root, path))) return;
+  if (hasSymlinkComponent(root, path) || containedRegularFile(root, path).status !== 'valid') throw Error('AGDF_OPERATION_IDENTITY_UNCONFIRMED');
+  const bytes = readFileSync(join(root, path)); if (bytes.length > 262144) throw Error('AGDF_OPERATION_IDENTITY_UNCONFIRMED');
+  let envelope; try { envelope = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); } catch { throw Error('AGDF_OPERATION_IDENTITY_UNCONFIRMED'); }
+  const r = envelope.record;
+  const check = validateRunPresentationEnvelope(envelope, { runId: run.meta.run_id, gate: r?.gate, revisionId: r?.revision_id, presentationId: operationId });
+  if (check.reason) throw Error('AGDF_OPERATION_IDENTITY_UNCONFIRMED');
+  if (r.operation_id === operationId && (family !== 'presentation.prepare' || receipts.length)) throw Error('AGDF_OPERATION_PAYLOAD_CONFLICT');
+}

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

@@ -0,0 +1,103 @@
+import { readFileSync, statSync } from 'node:fs';
+import { canonicalJson, digest, DIGEST_PATTERN, exactObject, COOPERATIVE_ASSURANCE, resolveControlCommandTarget } from './approval-command-contract.js';
+import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
+import { artefactFileDigest, canonicalRunText } from './run-seal-compute.js';
+import { INTERNAL_STEP_FILES } from './run-owned-outputs.js';
+import { EVIDENCE_PREREQUISITES, evidenceSourceSetDigest } from './evidence-bindings.js';
+import { evaluateQaFollowUp } from '../control-evaluation/qa-follow-up.js';
+import { STRUCTURED_REQUIRED_REVIEWS, CORRECTABLE_REVIEWS } from './evidence-bindings.js';
+import { maskFindingCells, readNormalizedFindings, reviewFindingDiagnostics } from '../control-evaluation/normalized-gaps.js';
+import { readReportDecision } from '../control-evaluation/report-decision.js';
+import { approvalMaterialTypes, reviewRecordingChain } from './presentation-decision.js';
+
+export function readOperationSource(root, runId, source) {
+  if (!exactObject(source, ['path', 'digest']) || !DIGEST_PATTERN.test(source.digest ?? '')
+    || typeof source.path !== 'string' || !source.path.startsWith(`.agdf/control/artefacts/${runId}/`)
+    || source.path.endsWith('/RUN_STATE.md') || hasSymlinkComponent(root, source.path)) throw Error('AGDF_RUN_OPERATION_SOURCE_INVALID');
+  const file = containedRegularFile(root, source.path);
+  if (file.status !== 'valid' || statSync(file.path).size > 131072) throw Error('AGDF_RUN_OPERATION_SOURCE_INVALID');
+  const bytes = readFileSync(file.path);
+  if (bytes.length > 131072) throw Error('AGDF_RUN_OPERATION_SOURCE_INVALID');
+  const content = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  if (artefactFileDigest(root, source.path) !== source.digest || !canonicalRunText(content).trim()) throw Error('AGDF_RUN_OPERATION_SOURCE_INVALID');
+  return { content, validate: () => { if (hasSymlinkComponent(root, source.path) || containedRegularFile(root, source.path).status !== 'valid' || artefactFileDigest(root, source.path) !== source.digest) throw Error('AGDF_RUN_OPERATION_SOURCE_CHANGED'); } };
+}
+export function operationSources(root, state, step) {
+  const types = EVIDENCE_PREREQUISITES[step]; if (!types) throw Error('AGDF_RUN_OPERATION_STEP_INVALID');
+  return types.map(type => {
+    const row = state.artefacts.get(type);
+    const value = row?.path ? artefactFileDigest(root, row.path) : null;
+    return { type, path: row?.path ?? '', digest: DIGEST_PATTERN.test(value ?? '') ? value : null, status: row?.status ?? 'missing' };
+  });
+}
+export const operationSourceSetDigest = (root, state, step) => evidenceSourceSetDigest(operationSources(root, state, step));
+export function operationReceipt(root, run, context, nextRevisionId, record, packageVersion) {
+  return { schema_version: '1', kind: context.kind, operation_id: context.operation_id, request_digest: context.request_digest,
+    target_id: resolveControlCommandTarget(root).target_id, run_id: run.meta.run_id, expected_revision_id: run.meta.revision_id,
+    created_at: new Date().toISOString(), producer: { contract: 'run-command/1', package_version: packageVersion }, assurance: COOPERATIVE_ASSURANCE,
+    effect: { previous_revision_id: run.meta.revision_id, resulting_revision_id: nextRevisionId, revision: Number(run.meta.revision) + 1, record } };
+}
+// A run approved past QA without a review that closeout requires may record it once, at
+// UAT or OR, when the QA approval never saw that review. A recorded review is never
+// replaced here, and no other internal step becomes recordable after QA approval.
+function lateRequiredReviewEligible(state, before, input) {
+  const type = input.internalStep, rows = [state.artefacts.get(type), type === 'Clean Implementation Review' ? state.artefacts.get('Clean Review') : null];
+  if (!STRUCTURED_REQUIRED_REVIEWS.includes(type) || state.approvals.get('QA')?.status !== 'approved'
+    || state.approvals.get('TP')?.status !== 'approved' || !['UAT', 'OR'].includes(before.current_gate)
+    || rows.some(row => row && (row.path || row.status !== 'missing')) || state.artefacts.get('CD+Tests')?.status !== 'done') return false;
+  // Only a material receipt proves the approval never saw this review; the same proof lets the
+  // QA association stay current afterwards (run-state.js). Legacy or unreadable receipts refuse.
+  const material = approvalMaterialTypes(state, 'QA');
+  return material.status === 'recorded' && !material.types.has(type);
+}
+
+// At OR after Approval: UAT a recorded review may be recorded again only to correct invalid
+// normalized finding rows. This is the structural part; run-steps.js applies
+// reviewCorrectionRefusal to the recorded and the new content before writing.
+function reviewCorrectionCandidate(state, before, input) {
+  const type = input.internalStep, row = state.artefacts.get(type);
+  if (!CORRECTABLE_REVIEWS.includes(type) || before.current_gate !== 'OR' || !['QA', 'UAT'].every(gate => state.approvals.get(gate)?.status === 'approved')
+    || !row?.path || !['done', 'revise', 'block'].includes(row.status)) return false;
+  // Only a correction that the approval-material proof recognises afterwards is eligible:
+  // the approvals saw a receipt-recorded version at the canonical path with this status.
+  const chain = reviewRecordingChain(state, type), canonical = `.agdf/control/artefacts/${state.run_id ?? state.meta?.run_id}/${INTERNAL_STEP_FILES[type]}`;
+  return Boolean(chain) && chain.seen.source.path === canonical && String(row.path).replace(/^`|`$/gu, '') === canonical && row.status === chain.seen.status;
+}
+
+// Closeout names the OR correction path only where it can be taken (run-steps.js).
+export function reviewCorrectionAvailable(state, type, problems = []) {
+  return problems.length > 0 && problems.every(problem => problem.rule === 'required_next_step')
+    && reviewCorrectionCandidate(state, { current_gate: 'OR' }, { internalStep: type });
+}
+
+const findingClasses = content => readNormalizedFindings(content).entries.filter(entry => entry.kind === 'row')
+  .map(entry => entry.row.slice(0, 4).join('|')).sort().join('\n');
+// The approvals saw the recorded version. Only the stuck-run defect is correctable: an empty,
+// placeholder or overlong required_next_step of a readable finding row. A correction changes
+// exactly those cells; decision, status, classification, evidence and all other text stay equal.
+export function reviewCorrectionRefusal(type, recorded, decision, content) {
+  if (typeof recorded?.content !== 'string') return 'recorded_review_unavailable';
+  const recordedDecision = readReportDecision(recorded.content);
+  const problems = reviewFindingDiagnostics(type, recorded.content, { decision: recordedDecision });
+  if (!problems.length) return 'recorded_review_valid';
+  if (problems.some(problem => !problem.finding_id || problem.rule !== 'required_next_step')) return 'recorded_review_uncorrectable';
+  if (recordedDecision !== decision || (decision === 'pass' ? 'done' : decision) !== recorded.status) return 'decision_changed';
+  if (findingClasses(recorded.content) !== findingClasses(content)) return 'classification_changed';
+  const ids = new Set(problems.map(problem => problem.finding_id));
+  return maskFindingCells(recorded.content, ids) === maskFindingCells(content, ids) ? null : 'content_changed';
+}
+
+export function internalStepEligibility(state, before, input, root) {
+  if (state.meta?.lifecycle !== 'active' || !['structured_slice', 'structured_delivery'].includes(state.mode_slice_decision.decision)) return false;
+  if (lateRequiredReviewEligible(state, before, input) || reviewCorrectionCandidate(state, before, input)) return true;
+  if (['QA', 'UAT'].some(gate => state.approvals.get(gate)?.status === 'approved')) return false;
+  const type = input.internalStep;
+  if (!Object.hasOwn(INTERNAL_STEP_FILES, type) || type === 'Brownfield Review') return false;
+  if (type === 'UX Intent Definition') return state.approvals.get('UR')?.status === 'approved'
+    && (before.next_operation?.analysis === type || before.current_gate === 'PRD' && state.approvals.get('PRD')?.status !== 'approved');
+  if (state.approvals.get('TP')?.status !== 'approved') return false;
+  if (type === 'Brownfield Analysis') return before.current_gate === 'Brownfield Analysis';
+  if (type === 'CD+Tests') return before.current_gate === 'CD+Tests'
+    || before.current_gate === 'QA' && evaluateQaFollowUp(root, state, state.run_id, 64, true).kind === 'implementation';
+  return state.artefacts.get('CD+Tests')?.status === 'done' && ['CR', 'QA'].includes(before.current_gate);
+}

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

@@ -0,0 +1,59 @@
+import { readFileSync, existsSync } from '../control-read/fs.js';
+import { join } from 'node:path';
+import { readApprovalOperations } from './approval-operations.js';
+import { readArtefactBindings } from './artefact-bindings.js';
+import { readSourceRevisions } from './run-source-revisions.js';
+import { readRunOperations } from './run-operations.js';
+import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
+import { parseRunState } from './run-state-parser.js';
+import { runSealState } from './run-seal.js';
+import { readPendingRunStepJournal } from './run-step-transaction.js';
+import { validateRunPresentationEnvelope } from './run-presentation.js';
+import { digest, canonicalJson, resolveControlCommandTarget } from './approval-command-contract.js';
+import { RUN_ID_PATTERN, REVISION_ID_PATTERN } from './run-identity.js';
+
+// Lookup only. Receipts stay in their original family; no shadow ledger or recovery here.
+export function inspectRunOperation(root, { runId, operationId, targetId }) {
+  const result = extra => ({ schema_version: '1', run_id: runId, operation_id: operationId, authorizes: false, ...extra });
+  if (!RUN_ID_PATTERN.test(runId ?? '') || !REVISION_ID_PATTERN.test(operationId ?? '') || targetId !== resolveControlCommandTarget(root).target_id) return result({ status: 'unavailable', reason: 'operation_binding_invalid' });
+  const relative = `.agdf/control/runs/${runId}/RUN_STATE.md`;
+  if (hasSymlinkComponent(root, relative) || containedRegularFile(root, relative).status !== 'valid') return result({ status: 'unavailable', reason: 'run_path_invalid' });
+  const content = readFileSync(join(root, relative), 'utf8'), parsed = parseRunState(content, runId);
+  if (!parsed.valid) return result({ status: 'unavailable', reason: 'run_state_invalid' });
+  const records = [
+    ...readApprovalOperations(content).receipts.map(receipt => ({ kind: 'approval.record', receipt, id: receipt.operation_id, request_digest: receipt.command_digest ?? receipt.request_digest })),
+    ...readArtefactBindings(content).receipts.map(receipt => ({ kind: 'artefact.record', receipt, id: receipt.operation.id, request_digest: receipt.operation.request_digest ?? null })),
+    ...readSourceRevisions(content).receipts.map(receipt => ({ kind: 'source_revision.apply', receipt, id: receipt.operation_id, request_digest: receipt.command_digest ?? receipt.request_digest })),
+    ...readRunOperations(content).receipts.map(receipt => ({ kind: receipt.kind, receipt, id: receipt.operation_id, request_digest: receipt.request_digest })),
+  ].filter(row => row.id === operationId);
+  const pendingPath = `.agdf/control/runs/${runId}/RUN_STEP_PENDING.json`;
+  let pending = null;
+  if (existsSync(join(root, pendingPath))) {
+    try { const journal = readPendingRunStepJournal(root, runId, { readJournal: path => readFileSync(path, "utf8") }); pending = { kind: journal.kind ?? 'legacy',
+      operation_id: journal.operation_id, pending_digest: digest(canonicalJson(journal)), original_revision_id: journal.old_revision_id,
+      next_revision_id: journal.next_revision_id, schema_version: journal.schema_version, matches_operation: journal.operation_id === operationId }; }
+    catch { return result({ status: 'unknown', reason: 'pending_intent_unconfirmed', receipt: records[0]?.receipt ?? null }); }
+  }
+  if (records.length > 1) return result({ status: 'unknown', reason: 'operation_identity_ambiguous' });
+  if (records.length === 1) {
+    const record = records[0], seal = runSealState(root, content);
+    if (seal.status !== 'valid') return result({ status: 'unknown', reason: 'current_seal_unconfirmed', receipt: record.receipt, pending });
+    return result({ status: pending?.matches_operation ? 'committed_recovery_required' : 'recorded', family: record.kind,
+      request_digest: record.request_digest, receipt: record.receipt, historical_effect: true, current_revision_id: parsed.meta.revision_id, pending });
+  }
+  if (pending) return result({ status: pending.matches_operation ? 'pending' : 'unknown', reason: pending.matches_operation ? null : 'another_pending_operation', pending, current_revision_id: parsed.meta.revision_id });
+  // New immutable presentations use the original UUID as their presentation ID.
+  const path = `.agdf/control/runs/${runId}/presentations/${operationId}.json`;
+  if (existsSync(join(root, path))) {
+    if (hasSymlinkComponent(root, path) || containedRegularFile(root, path).status !== 'valid') return result({ status: 'unknown', reason: 'presentation_path_invalid' });
+    try {
+      const bytes = readFileSync(join(root, path), 'utf8'); if (Buffer.byteLength(bytes) > 262144) throw Error();
+      const envelope = JSON.parse(bytes), record = envelope.record;
+      const checked = validateRunPresentationEnvelope(envelope, { runId, gate: record.gate, revisionId: record.revision_id, presentationId: operationId });
+      if (checked.reason || record.operation_id !== operationId || !record.request_digest) throw Error();
+      return result({ status: 'recorded', family: 'presentation.prepare', receipt: record, request_digest: record.request_digest,
+        historical_effect: true, current_revision_id: parsed.meta.revision_id });
+    } catch { return result({ status: 'unknown', reason: 'presentation_operation_unconfirmed' }); }
+  }
+  return result({ status: 'absent', reason: 'absence_is_not_proof_of_non_execution', current_revision_id: parsed.meta.revision_id });
+}