create-agdf 0.20.2 → 0.31.0

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

@@ -0,0 +1,179 @@
+// Shared run inventory derived from stored run state texts only. Pure: no `node:` import, no file,
+// clock, network or process access, so a bundled copy can serve hosts without the Core runtime.
+// Callers pass validity findings from the full parser; this module never validates receipts.
+import { scalarFields, sectionTableRows, projectRunFacts } from "./run-state-document.js";
+import { RUN_ID_PATTERN } from "./run-identity.js";
+import { isDecisionContentPlaceholder } from "../control-evaluation/decision-content-placeholder.js";
+
+export const RUN_INVENTORY_SCHEMA_VERSION = "1";
+export const RUN_INVENTORY_LIFECYCLES = Object.freeze(["active", "completed", "superseded", "abandoned"]);
+export const RUN_INVENTORY_ATTENTION = Object.freeze(["decision_required", "clarification_required", "blocked", "in_progress", "unclear", "none"]);
+
+// English first, German second.
+const LABELS = Object.freeze({
+  decision_required: ["Decision required", "Entscheidung erforderlich"],
+  clarification_required: ["Clarification required", "Klärung erforderlich"],
+  blocked: ["Blocked", "blockiert"],
+  in_progress: ["In progress", "in Arbeit"],
+  unclear: ["Unclear", "unklar"],
+  none: ["History", "Historie"],
+});
+const TEXT = Object.freeze({
+  basis: [revision => `Derived observation at revision ${revision}; no delivery authority.`,
+    revision => `Abgeleitete Beobachtung der Revision ${revision}; keine Lieferfreigabe.`],
+  basisUnknown: [() => "Derived observation at an unknown revision; no delivery authority.",
+    () => "Abgeleitete Beobachtung unbekannter Revision; keine Lieferfreigabe."],
+  history: [c => `History: ${c.completed} completed, ${c.superseded} superseded, ${c.abandoned} abandoned.`,
+    c => `Historie: ${c.completed} abgeschlossen, ${c.superseded} abgelöst, ${c.abandoned} abgebrochen.`],
+  inspect: [id => `Inspect the run with doctor --run ${id}.`, id => `Den Run mit doctor --run ${id} prüfen.`],
+});
+const languageIndex = language => /^de(?:-|$)/iu.test(String(language ?? "")) ? 1 : 0;
+export const runInventoryLabel = (code, language) => (LABELS[code] ?? LABELS.unclear)[languageIndex(language)];
+export const runInventoryHistoryLine = (counts, language) => TEXT.history[languageIndex(language)](counts);
+
+const BLOCKED = new Set(["block", "blocked"]);
+const CLARIFICATION = new Set(["revise", "decline"]);
+const AWAITING = new Set(["pending", "awaiting_uat"]);
+const WORKING = new Set(["open", "in_progress", "pass", "qa_approved", "completed"]);
+const ATTENTION_ORDER = RUN_INVENTORY_ATTENTION.slice(0, 5);
+const TITLE_LIMIT = 240;
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u;
+
+const plain = value => String(value ?? "").replace(/`/gu, "").trim();
+const clip = text => (text.length > TITLE_LIMIT ? `${text.slice(0, TITLE_LIMIT - 1)}…` : text);
+
+// The run-ID title every reader shows when no authored title exists.
+export function normalizedRunTitle(runId) {
+  const words = String(runId ?? "").replace(/[._-]+/g, " ").replace(/\s+/g, " ").trim();
+  return words ? words.replace(/\b\p{L}/gu, (letter) => letter.toUpperCase()) : "AGDF run";
+}
+
+// Lines of one level-two section up to the next heading; an empty section stays empty.
+function sectionLines(text, heading) {
+  const lines = text.split("\n"), start = lines.findIndex(line => line.trimEnd() === `## ${heading}`);
+  if (start < 0) return [];
+  const rest = lines.slice(start + 1), end = rest.findIndex(line => /^#{1,2} /u.test(line));
+  return end < 0 ? rest : rest.slice(0, end);
+}
+
+function objectiveTitle(text, runId) {
+  // The first paragraph, so hard-wrapped objectives stay whole.
+  const lines = sectionLines(text, "Objective").map(value => value.trim()), first = lines.findIndex(Boolean);
+  const paragraph = first < 0 ? [] : lines.slice(first), end = paragraph.indexOf("");
+  const line = (end < 0 ? paragraph : paragraph.slice(0, end)).join(" ");
+  const stripped = line.replace(/^(?:[-*>]|#+|\d+\.)\s+/u, "").replace(/\*\*|__|`/gu, "").replace(/\s+/gu, " ").trim();
+  return isDecisionContentPlaceholder(stripped)
+    ? { title: normalizedRunTitle(runId), title_source: "run_id" }
+    : { title: clip(stripped), title_source: "objective" };
+}
+
+// Base64url receipt cells decoded for display facts only; undecodable cells are skipped.
+function decodeReceipt(cell) {
+  if (!/^[A-Za-z0-9_-]+$/u.test(cell)) return null;
+  try {
+    const base64 = cell.replace(/-/gu, "+").replace(/_/gu, "/").padEnd(Math.ceil(cell.length / 4) * 4, "=");
+    const bytes = Uint8Array.from(atob(base64), char => char.charCodeAt(0));
+    const receipt = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    return receipt && typeof receipt === "object" ? receipt : null;
+  } catch { return null; }
+}
+const receipts = text => ["Run Operations", "Approval Operations", "Artefact Bindings", "Source Revisions"]
+  .flatMap(heading => sectionTableRows(text, heading).filter(row => row.length === 3).map(row => decodeReceipt(row[2])))
+  .filter(Boolean);
+const timeOf = value => (typeof value === "string" && ISO_TIME.test(value) && !Number.isNaN(Date.parse(value)) ? Date.parse(value) : null);
+
+function lastActivity(decoded) {
+  const times = decoded.map(receipt => timeOf(receipt.created_at)).filter(value => value !== null);
+  if (times.length) return { at: new Date(Math.max(...times)).toISOString(), source: "receipt", precision: "time" };
+  return { at: null, source: "none", precision: null };
+}
+
+function closureFacts(lifecycle, decoded) {
+  if (!["superseded", "abandoned"].includes(lifecycle)) return null;
+  const receipt = decoded.filter(row => row.kind === "lifecycle_close.record")
+    .sort((left, right) => (timeOf(left.created_at) ?? 0) - (timeOf(right.created_at) ?? 0)).at(-1);
+  const record = receipt?.effect?.record ?? {};
+  const successor = record.successor && typeof record.successor.value === "string"
+    ? { value: record.successor.value, verified: record.successor.verified === true } : null;
+  return { outcome: lifecycle, reason: typeof record.reason === "string" ? record.reason : null, successor,
+    closed_at: timeOf(receipt?.created_at) === null ? null : receipt.created_at };
+}
+
+// Attention from stored control state only; the first matching rule wins (PRD AC-003).
+export function runAttention({ lifecycle, valid, decision, gateResult, presentationDecision, missing }) {
+  if (valid && lifecycle !== "active") return "none";
+  if (!valid) return "blocked";
+  if (BLOCKED.has(decision) || BLOCKED.has(gateResult)) return "blocked";
+  if (CLARIFICATION.has(decision) || gateResult === "revise" || presentationDecision) return "clarification_required";
+  if (/(?<!\b(?:[Nn]o|[Nn]ot|[Ww]ithout) )\bApproval: (?:UR|PRD|SD|TP|QA|UAT|OR)\b/u.test(missing) || AWAITING.has(decision)) return "decision_required";
+  if (WORKING.has(decision)) return "in_progress";
+  return "unclear";
+}
+
+function entryOf(source, language) {
+  const runId = String(source?.run_id ?? "");
+  const text = typeof source?.text === "string" ? source.text.replace(/^/u, "").replace(/\r\n?/gu, "\n") : null;
+  const findings = [...(Array.isArray(source?.findings) ? source.findings : [])].map(finding => ({ ...finding }));
+  const meta = text ? scalarFields(text).values : new Map();
+  const lifecycle = meta.get("lifecycle") ?? null;
+  if (!text) { if (!findings.length) findings.push({ code: "AGDF_RUN_STATE_UNAVAILABLE" }); }
+  else if (meta.get("run_id") !== runId || !RUN_INVENTORY_LIFECYCLES.includes(lifecycle)) findings.push({ code: "AGDF_RUN_META_INVALID" });
+  const valid = RUN_ID_PATTERN.test(runId) && findings.length === 0;
+  const gate = source.observation?.current_gate ?? null;
+  const decision = source.observation?.decision ?? null;
+  const decoded = text ? receipts(text) : [];
+  const facts = text && valid ? projectRunFacts(text) : null;
+  const gateResult = facts?.artefacts.get(gate === 'Quick Task Execution' ? 'CR' : gate)?.status ?? null;
+  const presentationDecision = source.observation?.presentation_decision === true;
+  const missing = source.observation?.missing === 'none' ? '' : source.observation?.missing ?? '';
+  const attention = runAttention({ lifecycle, valid, decision, gateResult, presentationDecision, missing });
+  const revision = /^[1-9]\d*$/u.test(meta.get("revision") ?? "") ? Number(meta.get("revision")) : null;
+  const index = languageIndex(language);
+  return {
+    run_id: runId,
+    ...(text ? objectiveTitle(text, runId) : { title: normalizedRunTitle(runId), title_source: "run_id" }),
+    valid,
+    lifecycle: valid ? lifecycle : null,
+    current_gate: gate,
+    decision,
+    attention: { code: attention, label: LABELS[attention][index] },
+    basis: revision === null ? TEXT.basisUnknown[index]() : TEXT.basis[index](revision),
+    last_activity: text ? lastActivity(decoded) : { at: null, source: "none", precision: null },
+    revision,
+    revision_id: meta.get("revision_id") ?? null,
+    missing: missing || null,
+    next_action: source.observation?.next_action ?? null,
+    path: `.agdf/control/runs/${runId}/RUN_STATE.md`,
+    closure: valid ? closureFacts(lifecycle, decoded) : null,
+    findings: valid ? [] : findings.map(finding => ({ ...finding, next_step: TEXT.inspect[index](runId) })),
+  };
+}
+
+const groupOf = entry => (entry.lifecycle === null || entry.lifecycle === "active" ? 0 : 1 + RUN_INVENTORY_LIFECYCLES.indexOf(entry.lifecycle));
+const activityOf = entry => (entry.last_activity.at === null ? -Infinity : Date.parse(entry.last_activity.at));
+function compareEntries(left, right) {
+  return groupOf(left) - groupOf(right)
+    || (groupOf(left) === 0 ? ATTENTION_ORDER.indexOf(left.attention.code) - ATTENTION_ORDER.indexOf(right.attention.code) : 0)
+    || activityOf(right) - activityOf(left)
+    || (left.run_id < right.run_id ? -1 : left.run_id > right.run_id ? 1 : 0);
+}
+
+// `sources` is null when the repository has no run store; otherwise one item per run folder.
+// Store-level findings, such as a runs path that is no directory, make the inventory incomplete.
+export function buildRunInventory(sources, { language = "en", findings = [] } = {}) {
+  const runs = Array.isArray(sources) ? sources.map(source => entryOf(source, language)).sort(compareEntries) : [];
+  const lifecycle = Object.fromEntries([...RUN_INVENTORY_LIFECYCLES, "invalid"].map(key => [key, 0]));
+  const attention = Object.fromEntries(RUN_INVENTORY_ATTENTION.map(key => [key, 0]));
+  for (const run of runs) {
+    lifecycle[run.valid ? run.lifecycle : "invalid"] += 1;
+    attention[run.attention.code] += 1;
+  }
+  return {
+    schema_version: RUN_INVENTORY_SCHEMA_VERSION,
+    state: !Array.isArray(sources) ? "absent" : findings.length || runs.some(run => !run.valid) ? "incomplete" : "complete",
+    counts: { total: runs.length, lifecycle, attention },
+    runs,
+    findings: findings.map(finding => ({ ...finding })),
+    authorizes: false,
+  };
+}

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

@@ -0,0 +1,229 @@
+import { resolutionRecordVersion } from './input-resolution.js';
+import { currentInputResolution } from './input-resolution.js';
+import { assertInputConfigurationCurrent } from '../resources/configuration.js';
+import { randomUUID } from 'node:crypto';
+import { resolveTaskTarget } from '../task-target-resolution.js';
+import { canonicalJson, digest, resolveControlCommandTarget, COOPERATIVE_ASSURANCE } from './approval-command-contract.js';
+import { readRun } from './run-state-edits.js';
+import { runSealState } from './run-seal.js';
+import { canonicalRunText } from './run-seal-compute.js';
+import { validateRunCommand, runCommandRequestDigest } from './run-command-contract.js';
+import { inspectRunOperation } from './run-operation-status.js';
+import { readFileSync, statSync } from 'node:fs';
+import { parseRunState } from './run-state-parser.js';
+import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
+import { readPendingSourceRevisionJournal } from './run-step-transaction.js';
+import { inspectPlannedOperation, inspectPlannedSelection } from './planned-entry.js';
+
+import { MATERIAL_LIMITS } from './material-limits.js';
+export { MATERIAL_LIMITS } from './material-limits.js';
+
+// A rejected transfer step names its concrete cause; the reason code stays stable for clients.
+const MATERIAL_RECOVERY = Object.freeze({
+  file_index_unknown: 'file is not an index of this transfer; use the 0-based position from begin.files.',
+  offset_invalid: 'offset must be a non-negative integer byte offset.',
+  data_not_base64: 'data must be canonical standard base64 (A-Z a-z 0-9 + /, = padding, no whitespace or line breaks) of the raw UTF-8 bytes.',
+  data_empty: 'data must encode at least one byte.',
+  part_too_large: 'one append decodes to at most 16384 bytes; split the file into more parts.',
+  part_exceeds_file: 'offset plus decoded length exceeds the bytes declared at begin; check the byte count (UTF-8 bytes, not characters).',
+  offset_not_next: 'append the next part at offset received; read status for the current received count.',
+  file_incomplete: 'seal requires every file to have received exactly its declared bytes; read status and append the missing parts.',
+  transfer_expired: 'the transfer expired (idle or lifetime bound) or the serving generation changed; begin a new transfer and restage the bytes.',
+});
+const materialError = (reason, detail, facts = {}) => Object.assign(Error(reason), { detail, facts });
+
+// One serving generation/connection owns these bounded private buffers. They are
+// not files, Run State, evidence, receipts or an approval authority.
+export function createRunMaterialStore({ now = Date.now } = {}) {
+  const sets = new Map();
+  let closed = false;
+  function expire() {
+    for (const [id, row] of sets) if (now() - row.created >= MATERIAL_LIMITS.lifetime || now() - row.touched >= MATERIAL_LIMITS.idle) sets.delete(id);
+  }
+  const planning = input => Object.hasOwn(input, 'planning');
+  function binding(input) { return planning(input) ? canonicalJson(['planned', input.target_id, input.planning.plan_id, input.planning.expected_digest])
+    : canonicalJson([input.target_id, input.run_id, input.expected_revision_id]); }
+  function current(input) {
+    const target = resolveTaskTarget({ workingDirectory: input.working_directory, targetSource: input.target_source, primaryTarget: input.primary_target });
+    if (target.resolution_state !== 'resolved') throw Error('target_unresolved');
+    const root = target.governance_target;
+    if (resolveControlCommandTarget(root).target_id !== input.target_id) throw Error('target_binding_mismatch');
+    assertInputConfigurationCurrent(root);
+    if (planning(input)) return inspectPlannedSelection(root, input.planning, { presentationLanguage: input.presentation_language });
+    const runPath = `.agdf/control/runs/${input.run_id}/RUN_STATE.md`;
+    if (hasSymlinkComponent(root, runPath)) throw Error('run_path_invalid');
+    const source = containedRegularFile(root, runPath);
+    if (source.status !== 'valid') throw Error(source.status === 'missing' ? 'run_missing' : 'run_path_invalid');
+    let run = readRun(root, input.run_id);
+    if (run.rejection?.reason === 'run_step_recovery_required') {
+      const pending = readPendingSourceRevisionJournal(root, input.run_id), path = `.agdf/control/runs/${input.run_id}/RUN_STATE.md`;
+      const file = containedRegularFile(root, path);
+      if (resolutionRecordVersion(pending) === 7 && [pending.old_revision_id, pending.next_revision_id].includes(input.expected_revision_id)
+        && !hasSymlinkComponent(root, path) && file.status === 'valid' && statSync(file.path).size <= 1048576) {
+        const content = readFileSync(file.path, 'utf8'), parsed = parseRunState(content, input.run_id);
+        if (parsed.valid) run = { ...parsed, content };
+      }
+    }
+    if (run.rejection) throw Error(run.rejection.reason);
+    if (run.meta.revision_id !== input.expected_revision_id) throw Error('stale_revision');
+    if (run.meta.lifecycle !== 'active' || runSealState(root, run.content).status !== 'valid') throw Error('material_binding_invalid');
+    return { available: true, revision: Number(run.meta.revision), revision_id: run.meta.revision_id, lifecycle: run.meta.lifecycle };
+  }
+  function rowFor(input, id) {
+    expire(); const row = sets.get(id);
+    if (closed || !row) throw materialError('material_transfer_expired', 'transfer_expired', { idle_ms: MATERIAL_LIMITS.idle, lifetime_ms: MATERIAL_LIMITS.lifetime });
+    if (row.binding !== binding(input)) throw Error('material_binding_mismatch');
+    row.touched = now(); return row;
+  }
+  function rememberResolution(row, input) {
+    const resolution = currentInputResolution();
+    if (!resolution || row.resolutions.has(input.operation_id)) return;
+    const bytes = Buffer.byteLength(canonicalJson(resolution));
+    if (row.resolutions.size >= 64 || row.size + row.resolutionBytes + bytes > MATERIAL_LIMITS.set
+      || [...sets.values()].reduce((total, entry) => total + entry.size + entry.resolutionBytes, bytes) > MATERIAL_LIMITS.total) throw Error('material_resource_limit');
+    row.resolutions.set(input.operation_id, resolution);
+    row.resolutionBytes += bytes;
+  }
+  return Object.freeze({
+    originalInput(input) {
+      expire();
+      for (const row of sets.values()) {
+        const resolution = row.resolutions.get(input.operation_id);
+        if (resolution && row.binding === binding(input)) return { known: true, resolution };
+      }
+      return null;
+    },
+    stage(input) {
+      const envelope = (outcome, reason, family = {}, state = null) => ({ schema_version: '1', outcome, reason,
+        operation_id: input?.operation_id ?? null, request_digest: digest(canonicalJson(input)),
+        binding: planning(input) ? { target_id: input.target_id, planning: input.planning, kind: 'planned_material.stage' }
+          : { target_id: input.target_id, run_id: input.run_id, expected_revision_id: input.expected_revision_id, kind: 'material.stage' },
+        effect: null, receipt: null, current: state ?? { available: false }, assurance: COOPERATIVE_ASSURANCE,
+        historical_effect: Boolean(family.replayed), recovery: null, authorizes: false, family_result: family });
+      const explained = (reason, detail, facts) => ({ ...envelope('rejected', reason), recovery: MATERIAL_RECOVERY[detail],
+        diagnostics: [{ code: detail, ...facts }] });
+      if (validateRunCommand('agdf_record', input).length || !['material.stage', 'planned_material.stage'].includes(input.command.kind)) return envelope('rejected', 'command_schema_invalid');
+      try {
+        if (closed) throw materialError('material_transfer_expired', 'transfer_expired', { idle_ms: MATERIAL_LIMITS.idle, lifetime_ms: MATERIAL_LIMITS.lifetime });
+        const state = current(input), p = input.command.payload;
+        expire();
+        let row;
+        if (p.action === 'begin' || p.action === 'put') {
+          // The small-text path bundles only private transfer work. Validate the
+          // whole set before allocating; canonical recording still uses its owner.
+          const files = p.action === 'put' ? p.files.map(({ slot, content }) => {
+            const bytes = Buffer.from(content, 'utf8');
+            if (bytes.length > MATERIAL_LIMITS.inline || new TextDecoder('utf-8', { fatal: true }).decode(bytes) !== content)
+              throw Error('material_text_invalid');
+            return { slot, bytes: bytes.length, content, data: bytes };
+          }) : p.files;
+          const request = digest(canonicalJson(input));
+          row = sets.get(input.operation_id);
+          if (row) {
+            if (row.request !== request || row.binding !== binding(input)) throw Error('operation_payload_conflict');
+          } else {
+            const size = files.reduce((n, f) => n + f.bytes, 0);
+            const resolutionBytes = currentInputResolution() ? Buffer.byteLength(canonicalJson(currentInputResolution())) : 0;
+            if (!files.length || files.length > 4 || files.some(f => !Number.isSafeInteger(f.bytes) || f.bytes < 0 || f.bytes > MATERIAL_LIMITS.file)
+              || size + resolutionBytes > MATERIAL_LIMITS.set || sets.size >= MATERIAL_LIMITS.sets
+              || [...sets.values()].reduce((n, r) => n + r.size + r.resolutionBytes, size + resolutionBytes) > MATERIAL_LIMITS.total) throw Error('material_resource_limit');
+            row = { request, binding: binding(input), size, created: now(), touched: now(), resolutions: new Map(), resolutionBytes: 0,
+              files: files.map(f => ({ slot: f.slot, bytes: f.bytes, parts: f.data ? [f.data] : [],
+                received: f.data ? f.bytes : 0, material_id: randomUUID(), content: f.content ?? null,
+                digest: f.data ? digest(canonicalRunText(f.content)) : null })) };
+            sets.set(input.operation_id, row);
+          }
+          rememberResolution(row, input);
+          return envelope('accepted', null, { transfer_id: input.operation_id, files: row.files.map(({ slot, bytes, received, content, material_id, digest }) => ({ slot, bytes, received,
+            ...(content !== null ? { sealed: true, reference: { material_id, digest } } : {}) })), limits: MATERIAL_LIMITS }, state);
+        }
+        row = rowFor(input, p.transfer_id);
+        rememberResolution(row, input);
+        if (p.action === 'discard') { sets.delete(p.transfer_id); return envelope('accepted', null, { discarded: true }, state); }
+        if (p.action === 'append') {
+          const file = row.files[p.file], bytes = Buffer.from(p.data, 'base64');
+          if (!file) throw materialError('material_part_invalid', 'file_index_unknown', { file: p.file, files: row.files.length });
+          if (!Number.isSafeInteger(p.offset) || p.offset < 0) throw materialError('material_part_invalid', 'offset_invalid');
+          if (bytes.toString('base64') !== p.data) throw materialError('material_part_invalid', 'data_not_base64');
+          if (!bytes.length) throw materialError('material_part_invalid', 'data_empty');
+          if (bytes.length > MATERIAL_LIMITS.part) throw materialError('material_part_invalid', 'part_too_large', { decoded_bytes: bytes.length, part_bytes: MATERIAL_LIMITS.part });
+          if (p.offset + bytes.length > file.bytes) throw materialError('material_part_invalid', 'part_exceeds_file',
+            { offset: p.offset, decoded_bytes: bytes.length, declared_bytes: file.bytes });
+          if (p.offset < file.received) {
+            const original = Buffer.concat(file.parts).subarray(p.offset, p.offset + bytes.length);
+            if (!original.equals(bytes)) throw Error('material_part_conflict');
+            return envelope('accepted', null, { transfer_id: p.transfer_id, file: p.file, received: file.received, replayed: true }, state);
+          }
+          if (file.content !== null || p.offset !== file.received) throw materialError('material_part_offset_invalid', 'offset_not_next', { offset: p.offset, received: file.received, sealed: file.content !== null });
+          file.parts.push(bytes); file.received += bytes.length;
+        }
+        if (p.action === 'seal') {
+          if (row.files.some(f => f.received !== f.bytes)) throw materialError('material_incomplete', 'file_incomplete',
+            { files: row.files.map(({ received, bytes }) => ({ received, bytes })) });
+          // Validate every file before publishing any sealed reference.
+          const decoded = row.files.map(f => new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(f.parts)));
+          row.files.forEach((f, i) => { f.content = decoded[i]; f.digest = digest(canonicalRunText(f.content)); });
+        }
+        return envelope('accepted', null, { transfer_id: p.transfer_id, files: row.files.map(({ slot, bytes, received, content, material_id, digest: hash }) => ({
+          slot, bytes, received, sealed: content !== null, ...(content !== null ? { reference: { material_id, digest: hash } } : {}) })) }, state);
+      } catch (e) { return e.detail ? explained(e.message, e.detail, e.facts) : envelope('rejected', e.message); }
+    },
+    grants(input) {
+      const refs = [input.command?.payload?.source, input.command?.payload?.material, input.command?.payload?.or, input.command?.payload?.proposal].filter(r => r?.material_id);
+      if (!refs.length) return [];
+      const target = resolveTaskTarget({ workingDirectory: input.working_directory, targetSource: input.target_source, primaryTarget: input.primary_target });
+      if (target.resolution_state === 'resolved' && resolveControlCommandTarget(target.governance_target).target_id === input.target_id) {
+        if (planning(input)) {
+          const previous = inspectPlannedOperation(target.governance_target, input.planning.plan_id, input.operation_id);
+          if (previous.receipt?.request_digest === runCommandRequestDigest(input)) return [];
+        } else {
+        const previous = inspectRunOperation(target.governance_target, { runId: input.run_id, operationId: input.operation_id, targetId: input.target_id });
+        if (previous.status === 'recorded' && previous.request_digest === runCommandRequestDigest(input)) return [];
+        if (input.command.kind === 'source_revision.recover' && ['recorded', 'committed_recovery_required'].includes(previous.status)
+          && previous.family === 'source_revision.apply' && previous.receipt?.proposal_reference?.digest === input.command.payload.proposal.digest) return [];
+        }
+      }
+      current(input); expire();
+      return refs.map(ref => {
+        for (const row of sets.values()) {
+          const file = row.files.find(f => f.material_id === ref.material_id);
+          if (!file) continue;
+          if (row.binding !== binding(input) || file.content === null || file.digest !== ref.digest) throw Error('material_binding_mismatch');
+          row.touched = now();
+          return { material_id: file.material_id, digest: file.digest, slot: file.slot, content: file.content,
+            target_id: input.target_id, ...(planning(input) ? { planning: input.planning }
+              : { run_id: input.run_id, expected_revision_id: input.expected_revision_id }) };
+        }
+        throw Error('material_transfer_expired');
+      });
+    },
+    settle(input, result) {
+      if (!['accepted', 'already_applied'].includes(result.outcome) || !result.receipt
+        || result.request_digest !== runCommandRequestDigest(input)) return;
+      const ids = new Set([input.command.payload.source?.material_id, input.command.payload.material?.material_id,
+        input.command.payload.or?.material_id, input.command.payload.proposal?.material_id].filter(Boolean));
+      // A confirmed mutating commit advances the bound revision, so remaining
+      // parts in that same set cannot be used for another current write.
+      for (const [id, row] of sets) if (row.files.some(file => ids.has(file.material_id))) sets.delete(id);
+    },
+    // Review facts (companion core SDD-008): the sealed text of one transfer for the runtime's bounded
+    // preview, or null when it is unknown or not sealed. It reads only; it is never a material grant.
+    sealedFiles(transferId) {
+      const row = sets.get(transferId);
+      if (closed || !row || row.files.some(file => file.content === null)) return null;
+      return row.files.map(({ slot, content, digest: hash }) => Object.freeze({ slot, content, digest: hash }));
+    },
+    close() { closed = true; sets.clear(); },
+    inspectOwnership() { expire(); return { sets: sets.size, bytes: [...sets.values()].reduce((n, r) => n + r.size, 0) }; },
+  });
+}
+
+export function grantedMaterial(input, reference, grants = []) {
+  const row = grants.find(g => g.material_id === reference?.material_id);
+  const sameScope = row && (Object.hasOwn(input, 'planning') ? row.planning && !Object.hasOwn(row, 'run_id')
+    && canonicalJson(row.planning) === canonicalJson(input.planning) : !Object.hasOwn(row, 'planning') && row.run_id === input.run_id && row.expected_revision_id === input.expected_revision_id);
+  if (!row || row.target_id !== input.target_id || !sameScope
+    || row.digest !== reference.digest || typeof row.content !== 'string' || Buffer.byteLength(row.content) > MATERIAL_LIMITS.file
+    || digest(canonicalRunText(row.content)) !== row.digest) throw Error('material_binding_invalid');
+  return row;
+}

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

@@ -0,0 +1,51 @@
+import { resolutionRecordVersion } from './input-resolution.js';
+import { readFileSync, existsSync } from 'node:fs';
+import { relative, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parseRunState } from './run-state-parser.js';
+
+import { withOwnedFileLock } from './run-state-writer.js';
+import { commitRunStepLocked, recoverPendingRunStepLocked, readPendingRunStepJournal, pendingRunStepConflictIds } from './run-step-transaction.js';
+import { pendingRunStepPath } from './run-step-pending.js';
+import { containedRegularFile, hasSymlinkComponent } from './contained-file.js';
+import { runWorkSummary, assertSummarySources } from '../control-evaluation/run-work-summary.js';
+import { withControlMutation, assertLayoutRunWrite } from './control-layout.js';
+
+export function withRunMutationLock(root, path, work, options = {}) {
+  const relativePath = relative(root, path).split(sep).join('/');
+  if (hasSymlinkComponent(root, relativePath) || containedRegularFile(root, relativePath).status !== 'valid') throw Error('AGDF_RUN_PATH_INVALID');
+  return withOwnedFileLock(path, () => {
+    const run = parseRunState(readFileSync(path, 'utf8'));
+    if (!run.valid) throw Error('AGDF_RUN_STATE_INVALID');
+    return withControlMutation(root, { resource: `run:${run.meta.run_id}`, operation_id: options.operationContext?.operation_id ?? randomUUID(),
+      resume: true, proveOutcome: result => ['accepted', 'already_applied', 'recorded', 'recovered'].includes(result?.outcome) || Boolean(result?.meta?.revision_id) }, () => {
+      assertLayoutRunWrite(root, run);
+      const other = pendingRunStepConflictIds(root, run.meta.run_id).find(id => id !== run.meta.run_id);
+      if (other) { const error = Error('AGDF_RUN_STEP_RECOVERY_REQUIRED'); error.pending_run_id = other; throw error; }
+      if (existsSync(pendingRunStepPath(root, run.meta.run_id))) {
+        const pending = readPendingRunStepJournal(root, run.meta.run_id), expected = options.operationContext;
+        if (expected && (resolutionRecordVersion(pending) !== 7 || pending.operation_id !== expected.operation_id || pending.kind !== expected.kind
+          || pending.target_id !== expected.target_id || pending.request_digest !== expected.request_digest)) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
+      }
+      recoverPendingRunStepLocked(root, run.meta.run_id);
+      return work();
+    });
+  }, options);
+}
+
+// A mutation publishes only the selected Run and its captured owned outputs.
+export function writeRunMutationLocked(root, path, content, revisionId, options = {}) {
+  const old = readFileSync(path, 'utf8'), run = parseRunState(old);
+  if (!run.valid) throw Error('AGDF_RUN_STATE_INVALID');
+  if (run.meta.revision_id !== revisionId || options.expectedContent !== undefined && old !== options.expectedContent) throw Error('AGDF_STALE_RUN_REVISION');
+  const nextRevisionId = options.nextRevisionId ?? randomUUID();
+  const summary = runWorkSummary(root, content, path);
+  const guard = () => assertSummarySources(root, summary);
+  options.validateBeforeWrite?.(); guard();
+  return { ...commitRunStepLocked(root, { runId: run.meta.run_id, runPath: path, content,
+    revisionId, expectedContent: old, operationContext: options.operationContext, nextRevisionId,
+    writeOptions: { ...options, validateBeforeWrite: () => { options.validateDuringTransaction?.(); guard(); } }, afterWrite: options.afterWrite }) };
+}
+export function writeRunMutation(root, path, content, revisionId, options = {}) {
+  return withRunMutationLock(root, path, () => writeRunMutationLocked(root, path, content, revisionId, options));
+}

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

@@ -1,3 +1,4 @@
+import { runControlPath } from './run-identity.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { readRunOperations } from './run-operations.js';
@@ -19,7 +20,7 @@ export function assertRunOperationIdentity(root, run, operationId, family) {
     ...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`;
+  const path = `${runControlPath(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');

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

@@ -1,3 +1,6 @@
+import { RUN_OPERATION_VERSION } from './run-operations.js';
+import { runDocumentPath, runEvidencePath } from './run-identity.js';
+import { bindInputResolution } from './input-resolution.js';
 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';
@@ -12,7 +15,7 @@ import { approvalMaterialTypes, reviewRecordingChain } from './presentation-deci
 
 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}/`)
+    || typeof source.path !== 'string' || ![runDocumentPath(runId, ''), runEvidencePath(runId, '')].some(prefix => source.path.startsWith(`${prefix}/`))
     || 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');
@@ -32,10 +35,10 @@ export function operationSources(root, state, step) {
 }
 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,
+  return bindInputResolution({ schema_version: RUN_OPERATION_VERSION, 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 } };
+    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
@@ -60,7 +63,7 @@ function reviewCorrectionCandidate(state, before, input) {
     || !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]}`;
+  const chain = reviewRecordingChain(state, type), canonical = `${runDocumentPath(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;
 }
 

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

@@ -1,3 +1,4 @@
+import { runControlPath } from './run-identity.js';
 import { readFileSync, existsSync } from '../control-read/fs.js';
 import { join } from 'node:path';
 import { readApprovalOperations } from './approval-operations.js';
@@ -6,6 +7,7 @@ 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 { projectRunFacts } from './run-state-document.js';
 import { runSealState } from './run-seal.js';
 import { readPendingRunStepJournal } from './run-step-transaction.js';
 import { validateRunPresentationEnvelope } from './run-presentation.js';
@@ -17,7 +19,12 @@ 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 unavailable = (reason, source_path) => result({ available: false, status: 'unavailable', reason,
+    ...(source_path ? { source_path } : {}), historical_effect: null,
+    recovery_instruction: 'Inspect the named source and original operation. The current read changes nothing; the prior effect is unconfirmed. Preserve existing bytes and identity; do not recreate deleted state or retry with a new UUID.' });
+  if (hasSymlinkComponent(root, relative)) return unavailable('run_path_invalid', relative);
+  if (!existsSync(join(root, relative))) return unavailable('run_missing', relative);
+  if (containedRegularFile(root, relative).status !== 'valid') return unavailable('run_path_invalid', relative);
   const content = readFileSync(join(root, relative), 'utf8'), parsed = parseRunState(content, runId);
   if (!parsed.valid) return result({ status: 'unavailable', reason: 'run_state_invalid' });
   const records = [
@@ -26,7 +33,7 @@ export function inspectRunOperation(root, { runId, operationId, targetId }) {
     ...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`;
+  const pendingPath = runControlPath(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',
@@ -37,13 +44,22 @@ export function inspectRunOperation(root, { runId, operationId, targetId }) {
   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 });
+    if (seal.status !== 'valid') {
+      // Only emit canonical contained paths from the parsed registry; no raw
+      // exception or arbitrary path is exposed, and no missing file is repaired.
+      for (const artefact of projectRunFacts(content).artefacts.values()) {
+        if (artefact.path?.startsWith(`.agdf/control/runs/${runId}/documents/`)
+          && !hasSymlinkComponent(root, artefact.path) && !existsSync(join(root, artefact.path)))
+          return unavailable('document_missing', artefact.path);
+      }
+      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`;
+  const path = `${runControlPath(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 {