create-agdf 0.20.2 → 0.30.0

package/runtime/core/lib/control-state/planned-entry.js

@@ -0,0 +1,273 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { atomicWrite, fsyncDirectory, withOwnedFileLock } from '../owned-file-lock.js';
+import { renameSyncWithRetry } from '../fs-swap.js';
+import { canonicalRunText } from './run-seal-compute.js';
+import { exactObject, canonicalJson } from './approval-command-contract.js';
+import { RUN_ID_PATTERN, REVISION_ID_PATTERN } from './run-identity.js';
+import { hasSymlinkComponent, containedRegularFile } from './contained-file.js';
+import { CURRENT_LAYOUT, readControlLayout, withControlMutation, withControlRecovery, inspectMutationClaims, markControlMutationEffect } from './control-layout.js';
+import { evaluateUrContentReadiness } from '../control-evaluation/ur-readiness.js';
+import { resolveArtifactPresentationLanguages } from '../resources/context.js';
+import { readContainedControlText, controlPathPresent } from '../control-read/snapshot.js';
+import { assertPlannedNotTransferred } from './planned-origin-reader.js';
+import { bindInputResolution, resolutionRecord } from './input-resolution.js';
+import { existsSync as observedExists } from '../control-read/fs.js';
+
+export const PLANNED_SCHEMA = 'planned-ur-v1';
+export const PLANNED_ROOT = '.agdf/control/planned';
+export const PLANNED_INTENT_BYTES = 1048576;
+export const plannedTextDigest = text => 'sha256:' + createHash('sha256').update(canonicalRunText(text)).digest('hex');
+export const plannedRawDigest = text => 'sha256:' + createHash('sha256').update(text).digest('hex');
+const digestPattern = /^sha256:[a-f0-9]{64}$/u;
+const fail = code => { throw Error(code); };
+const priorities = ['high', 'normal', 'low'];
+const json = value => JSON.stringify(value) + '\n';
+export const planningId = operationId => {
+  if (!REVISION_ID_PATTERN.test(operationId)) fail('AGDF_PLANNED_OPERATION_INVALID');
+  return `plan-${operationId}`;
+};
+export function plannedEntryPath(id) {
+  if (typeof id !== 'string' || !RUN_ID_PATTERN.test(id)) fail('AGDF_PLANNED_ID_INVALID');
+  return `${PLANNED_ROOT}/${id}`;
+}
+
+function safeRead(root, path, limit = 131072) {
+  try { return readContainedControlText(root, path, limit); }
+  catch (error) { if (error.code === 'resource_denied') fail('AGDF_PLANNED_PATH_INVALID'); throw error; }
+}
+function ensureDirectory(root, relative) {
+  if (hasSymlinkComponent(root, relative)) fail('AGDF_PLANNED_PATH_INVALID');
+  const path = join(root, relative);
+  if (!existsSync(path)) {
+    try { mkdirSync(path, { mode: 0o700 }); fsyncDirectory(dirname(path)); }
+    catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('AGDF_PLANNED_PATH_INVALID');
+}
+function validateContent(content) {
+  if (typeof content !== 'string' || !content.isWellFormed() || Buffer.byteLength(content) > 131072
+    || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(content)) fail('AGDF_PLANNED_CONTENT_INVALID');
+  return canonicalRunText(content);
+}
+export function parsePlannedUr(content, expectedId) {
+  const text = validateContent(content), metadata = text.split(/^##[ \t]+/mu)[0];
+  const field = key => {
+    const rows = [...metadata.matchAll(new RegExp(`^${key}:[ \\t]*([^\\n]*)$`, 'gmu'))];
+    if (rows.length !== 1) fail('AGDF_PLANNED_METADATA_INVALID');
+    return rows[0][1].trim();
+  };
+  const schema = field('Planning schema'), id = field('Planning id'), priority = field('Planning priority');
+  if (schema !== PLANNED_SCHEMA || !RUN_ID_PATTERN.test(id) || expectedId && id !== expectedId || !priorities.includes(priority)) fail('AGDF_PLANNED_METADATA_INVALID');
+  const titles = [...text.matchAll(/^# ([^\n]+)$/gmu)];
+  if (titles.length !== 1 || !text.startsWith('# ') || !titles[0][1].trim() || titles[0][1].length > 1024) fail('AGDF_PLANNED_TITLE_INVALID');
+  const title = titles[0][1].replace(/^UR:[ \t]*/u, '').trim();
+  if (!title) fail('AGDF_PLANNED_TITLE_INVALID');
+  return { schema, plan_id: id, priority, title, content: text, digest: plannedTextDigest(text) };
+}
+
+export function preparePlannedUr(content, id, priority = 'normal') {
+  plannedEntryPath(id);
+  const text = validateContent(content);
+  if (!priorities.includes(priority) || /^Planning (schema|id|priority):/mu.test(text)) fail('AGDF_PLANNED_METADATA_INVALID');
+  const end = text.indexOf('\n');
+  if (end < 0) fail('AGDF_PLANNED_TITLE_INVALID');
+  const candidate = text.slice(0, end + 1) + `\nPlanning schema: ${PLANNED_SCHEMA}\nPlanning id: ${id}\nPlanning priority: ${priority}\n` + text.slice(end + 1);
+  return parsePlannedUr(candidate, id).content;
+}
+
+export function inspectPlannedEntry(root, id, { presentationLanguage } = {}) {
+  const path = `${plannedEntryPath(id)}/UR.md`;
+  const raw = safeRead(root, path), entry = parsePlannedUr(raw, id);
+  const readiness = evaluateUrContentReadiness(entry.content, { languages: resolveArtifactPresentationLanguages(root, presentationLanguage), path, requireClarification: true });
+  return { ...entry, raw_digest: plannedRawDigest(raw), path, readiness, pending: controlPathPresent(root, `${plannedEntryPath(id)}/MUTATION_PENDING.json`), authorizes: false };
+}
+
+export function withPlannedEntryLock(root, id, work, { operation_id, recovery = false, resume = false, proveOutcome, checkpoint } = {}) {
+  const path = plannedEntryPath(id);
+  readControlLayout(root);
+  ensureDirectory(root, PLANNED_ROOT);
+  if (hasSymlinkComponent(root, path)) fail('AGDF_PLANNED_PATH_INVALID');
+  return withOwnedFileLock(join(root, PLANNED_ROOT, `.entry-${id}`), () => {
+    const resource = `planned:${id}`;
+    const recovering = recovery || resume && inspectMutationClaims(root, { strict: false }).some(row => row.resource === resource && row.operation_id === operation_id);
+    return recovering ? withControlRecovery(root, { resource, operation_id, proveOutcome }, work)
+      : withControlMutation(root, { resource, operation_id, checkpoint }, work);
+  });
+}
+
+function validReceipt(receipt, id) {
+  receipt = resolutionRecord(receipt);
+  if (!receipt) return false;
+  return exactObject(receipt, ['schema_version', 'kind', 'operation_id', 'plan_id', 'request_digest', 'previous_digest', 'resulting_digest'])
+    && receipt.schema_version === 1 && ['planned_ur.create', 'planned_ur.replace'].includes(receipt.kind)
+    && REVISION_ID_PATTERN.test(receipt.operation_id) && receipt.plan_id === id && digestPattern.test(receipt.request_digest)
+    && (receipt.previous_digest === null || digestPattern.test(receipt.previous_digest)) && digestPattern.test(receipt.resulting_digest)
+    && (receipt.kind === 'planned_ur.create' ? receipt.previous_digest === null : receipt.previous_digest !== null);
+}
+function receiptPath(id, operationId) { return `${plannedEntryPath(id)}/operations/${operationId}.json`; }
+function receiptAt(root, id, operationId) {
+  const path = receiptPath(id, operationId);
+  if (!existsSync(join(root, path))) return null;
+  let receipt; try { receipt = JSON.parse(safeRead(root, path, 16384)); } catch { fail('AGDF_PLANNED_RECOVERY_REQUIRED'); }
+  if (!validReceipt(receipt, id) || receipt.operation_id !== operationId) fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+  return receipt;
+}
+function publishReceipt(root, receipt) {
+  const path = receiptPath(receipt.plan_id, receipt.operation_id);
+  ensureDirectory(root, `${plannedEntryPath(receipt.plan_id)}/operations`);
+  if (existsSync(join(root, path))) {
+    if (safeRead(root, path, 16384) !== json(receipt)) fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+  } else atomicWrite(join(root, path), json(receipt));
+}
+function readIntent(root, id) {
+  const path = `${plannedEntryPath(id)}/MUTATION_PENDING.json`;
+  let intent; try { intent = JSON.parse(safeRead(root, path, PLANNED_INTENT_BYTES)); } catch { fail('AGDF_PLANNED_RECOVERY_REQUIRED'); }
+  if (!exactObject(intent, ['schema_version', 'receipt', 'old', 'next']) || intent.schema_version !== 1
+    || !validReceipt(intent.receipt, id) || intent.receipt.kind !== 'planned_ur.replace'
+    || typeof intent.old !== 'string' || typeof intent.next !== 'string'
+    || parsePlannedUr(intent.old, id).digest !== intent.receipt.previous_digest
+    || parsePlannedUr(intent.next, id).digest !== intent.receipt.resulting_digest) fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+  return { path, intent };
+}
+export function recoverPlannedMutationLocked(root, id, operationId) {
+  const path = `${plannedEntryPath(id)}/MUTATION_PENDING.json`;
+  if (!existsSync(join(root, path))) return { status: 'none' };
+  const { intent } = readIntent(root, id);
+  if (intent.receipt.operation_id !== operationId) fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+  const current = safeRead(root, `${plannedEntryPath(id)}/UR.md`);
+  let status;
+  if (current === intent.old) status = 'rolled_back';
+  else if (current === intent.next) { publishReceipt(root, intent.receipt); status = 'completed'; }
+  else fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+  unlinkSync(join(root, path)); fsyncDirectory(join(root, plannedEntryPath(id)));
+  return { status, receipt: status === 'completed' ? intent.receipt : null };
+}
+
+export function recoverPlannedMutation(root, id, operationId) {
+  return withPlannedEntryLock(root, id, () => recoverPlannedMutationLocked(root, id, operationId), {
+    recovery: true, operation_id: operationId, proveOutcome: result => ['none', 'completed', 'rolled_back'].includes(result.status),
+  });
+}
+
+export function inspectPlannedOperation(root, id, operationId) {
+  plannedEntryPath(id);
+  if (!REVISION_ID_PATTERN.test(operationId ?? '')) fail('AGDF_PLANNED_OPERATION_INVALID');
+  const receipt = receiptAt(root, id, operationId);
+  const pendingPath = `${plannedEntryPath(id)}/MUTATION_PENDING.json`;
+  const pending = observedExists(join(root, pendingPath)) ? readIntent(root, id).intent.receipt : null;
+  const stagePath = `${PLANNED_ROOT}/.stage-${id}-${operationId}/OWNER.json`;
+  let creation = null;
+  if (observedExists(join(root, stagePath))) {
+    creation = JSON.parse(safeRead(root, stagePath, 16384));
+    if (!validReceipt(creation, id) || creation.operation_id !== operationId) fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+  }
+  return { status: receipt ? pending?.operation_id === operationId ? 'committed_recovery_required' : 'recorded'
+    : pending?.operation_id === operationId || creation ? 'pending' : 'absent', receipt,
+    pending: pending?.operation_id === operationId ? pending : creation, authorizes: false };
+}
+
+export function inspectPlannedSelection(root, scope, options) {
+  plannedEntryPath(scope.plan_id);
+  if (readControlLayout(root).layout !== CURRENT_LAYOUT) fail('AGDF_CONTROL_LAYOUT_MIGRATION_REQUIRED');
+  if (scope.expected_digest === null) return { available: true, planning: scope, authorizes: false };
+  const entry = inspectPlannedEntry(root, scope.plan_id, options);
+  if (entry.digest !== scope.expected_digest) {
+    if (!entry.pending || readIntent(root, scope.plan_id).intent.receipt.previous_digest !== scope.expected_digest) fail('AGDF_PLANNED_SOURCE_STALE');
+  }
+  return { available: true, planning: scope, source_digest: entry.digest, authorizes: false };
+}
+
+export function replayPlannedUr(root, { plan_id, operation_id, request_digest }) {
+  return withPlannedEntryLock(root, plan_id, () => {
+    const previous = receiptAt(root, plan_id, operation_id);
+    if (!previous || previous.request_digest !== request_digest) fail('AGDF_OPERATION_PAYLOAD_CONFLICT');
+    if (existsSync(join(root, plannedEntryPath(plan_id), 'MUTATION_PENDING.json')) && readIntent(root, plan_id).intent.receipt.operation_id === operation_id)
+      recoverPlannedMutationLocked(root, plan_id, operation_id);
+    return { outcome: 'already_applied', receipt: previous, entry: inspectPlannedEntry(root, plan_id) };
+  }, { operation_id, resume: true, proveOutcome: result => result.outcome === 'already_applied' });
+}
+
+// Source content is the only editable authority. Receipts retain operation/source
+// history but are never used as a saved title, priority, status or approval.
+export function mutatePlannedUr(root, { kind, operation_id, plan_id = planningId(operation_id), expected_digest, content, priority, request_digest: commandDigest }, { checkpoint = () => {} } = {}) {
+  if (!['planned_ur.create', 'planned_ur.replace'].includes(kind) || !REVISION_ID_PATTERN.test(operation_id)
+    || kind === 'planned_ur.create' && (expected_digest !== null || plan_id !== planningId(operation_id))
+    || kind === 'planned_ur.replace' && (!digestPattern.test(expected_digest) || priority !== undefined)) fail('AGDF_PLANNED_OPERATION_INVALID');
+  const text = kind === 'planned_ur.create' ? preparePlannedUr(content, plan_id, priority) : parsePlannedUr(content, plan_id).content;
+  if (commandDigest !== undefined && !digestPattern.test(commandDigest)) fail('AGDF_PLANNED_OPERATION_INVALID');
+  const request_digest = commandDigest ?? plannedTextDigest(canonicalJson({ kind, plan_id, expected_digest, content: text }));
+  let effectStarted = false;
+  const execute = () => {
+    const base = plannedEntryPath(plan_id), destination = join(root, base);
+    const existing = receiptAt(root, plan_id, operation_id);
+    if (existing) {
+      if (existing.kind !== kind || existing.request_digest !== request_digest) fail('AGDF_OPERATION_PAYLOAD_CONFLICT');
+      if (existsSync(join(destination, 'MUTATION_PENDING.json')) && readIntent(root, plan_id).intent.receipt.operation_id === operation_id)
+        recoverPlannedMutationLocked(root, plan_id, operation_id);
+      return { outcome: 'already_applied', receipt: existing, entry: inspectPlannedEntry(root, plan_id) };
+    }
+    if (existsSync(join(destination, 'MUTATION_PENDING.json'))) {
+      if (readIntent(root, plan_id).intent.receipt.request_digest !== request_digest) fail('AGDF_OPERATION_PAYLOAD_CONFLICT');
+      recoverPlannedMutationLocked(root, plan_id, operation_id);
+      const recovered = receiptAt(root, plan_id, operation_id);
+      if (recovered) {
+        if (recovered.request_digest !== request_digest) fail('AGDF_OPERATION_PAYLOAD_CONFLICT');
+        return { outcome: 'already_applied', receipt: recovered, entry: inspectPlannedEntry(root, plan_id) };
+      }
+    }
+    for (const name of ['HANDOFF_PENDING.json', 'TRANSFER.json'])
+      if (existsSync(join(destination, name))) fail('AGDF_PLANNED_ALREADY_TRANSFERRED');
+    assertPlannedNotTransferred(root, plan_id);
+    const receipt = bindInputResolution({ schema_version: 1, kind, operation_id, plan_id, request_digest,
+      previous_digest: expected_digest, resulting_digest: plannedTextDigest(text) });
+    if (kind === 'planned_ur.create') {
+      if (existsSync(destination)) fail('AGDF_PLANNED_COLLISION');
+      const stage = `${PLANNED_ROOT}/.stage-${plan_id}-${operation_id}`, stagePath = join(root, stage);
+      if (hasSymlinkComponent(root, stage)) fail('AGDF_PLANNED_PATH_INVALID');
+      if (existsSync(stagePath)) {
+        if (!lstatSync(stagePath).isDirectory() || readdirSync(stagePath).some(name => !['OWNER.json', 'UR.md', 'operations'].includes(name))
+          || safeRead(root, `${stage}/OWNER.json`, 16384) !== json(receipt)) fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+        if (existsSync(join(stagePath, 'UR.md')) && safeRead(root, `${stage}/UR.md`) !== text) fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+        if (existsSync(join(stagePath, 'operations'))) {
+          ensureDirectory(root, `${stage}/operations`);
+          if (readdirSync(join(stagePath, 'operations')).some(name => name !== `${operation_id}.json`)
+            || existsSync(join(stagePath, 'operations', `${operation_id}.json`)) && safeRead(root, `${stage}/operations/${operation_id}.json`, 16384) !== json(receipt)) fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+        }
+      } else {
+        effectStarted = true;
+        markControlMutationEffect();
+        ensureDirectory(root, stage);
+        atomicWrite(join(stagePath, 'OWNER.json'), json(receipt)); checkpoint('create_intent');
+      }
+      effectStarted = true;
+      markControlMutationEffect();
+      if (!existsSync(join(stagePath, 'UR.md'))) atomicWrite(join(stagePath, 'UR.md'), text);
+      checkpoint('create_source');
+      ensureDirectory(root, `${stage}/operations`);
+      if (!existsSync(join(stagePath, 'operations', `${operation_id}.json`))) atomicWrite(join(stagePath, 'operations', `${operation_id}.json`), json(receipt));
+      fsyncDirectory(join(stagePath, 'operations')); fsyncDirectory(stagePath); checkpoint('create_staged');
+      renameSyncWithRetry(stagePath, destination); fsyncDirectory(join(root, PLANNED_ROOT)); checkpoint('create_committed');
+    } else {
+      const old = safeRead(root, `${base}/UR.md`);
+      if (parsePlannedUr(old, plan_id).digest !== expected_digest) fail('AGDF_PLANNED_SOURCE_STALE');
+      if (old === text) fail('AGDF_PLANNED_SOURCE_UNCHANGED');
+      effectStarted = true;
+      markControlMutationEffect();
+      atomicWrite(join(destination, 'MUTATION_PENDING.json'), json({ schema_version: 1, receipt, old, next: text })); checkpoint('replace_intent');
+      atomicWrite(join(destination, 'UR.md'), text); checkpoint('replace_committed');
+      publishReceipt(root, receipt); checkpoint('replace_receipt');
+      unlinkSync(join(destination, 'MUTATION_PENDING.json')); fsyncDirectory(destination); checkpoint('replace_retired');
+    }
+    return { outcome: 'accepted', receipt, entry: inspectPlannedEntry(root, plan_id) };
+  };
+  return withPlannedEntryLock(root, plan_id, () => {
+    try { return execute(); }
+    catch (error) {
+      if (!effectStarted || /RECOVERY_REQUIRED/u.test(error.message)) throw error;
+      throw Object.assign(Error('AGDF_PLANNED_RECOVERY_REQUIRED'), { cause: error, operation_id, plan_id });
+    }
+  }, { operation_id, resume: true, proveOutcome: result => ['accepted', 'already_applied'].includes(result.outcome) });
+}

package/runtime/core/lib/control-state/planned-handoff.js

@@ -0,0 +1,174 @@
+import { RUN_OPERATION_VERSION } from './run-operations.js';
+import { runDocumentPath, runHistoryPath } from './run-identity.js';
+import { existsSync, lstatSync, mkdirSync, unlinkSync, readdirSync, rmdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { atomicWrite, fsyncDirectory, withOwnedFileLock } from '../owned-file-lock.js';
+import { readContainedControlText, controlPathPresent } from '../control-read/snapshot.js';
+import { inspectPlannedEntry, withPlannedEntryLock, plannedEntryPath, plannedTextDigest, plannedRawDigest, PLANNED_INTENT_BYTES } from './planned-entry.js';
+import { inspectPlannedOrigins } from './planned-origin-reader.js';
+import { validPlannedOrigin } from './planned-origin.js';
+import { exactObject, canonicalJson, digest, COOPERATIVE_ASSURANCE, resolveControlCommandTarget } from './approval-command-contract.js';
+import { REVISION_ID_PATTERN, creationRunId } from './run-identity.js';
+import { hasSymlinkComponent } from './contained-file.js';
+import { markControlMutationEffect, withControlRecovery } from './control-layout.js';
+import { createRun, recoverRunCreationStage } from './run-state-repository.js';
+import { parseRunState } from './run-state-parser.js';
+import { readRunOperations, appendRunOperation } from './run-operations.js';
+import { projectUrObjective, upsertTableRow, appendTableRow, replaceFirstScalar } from './run-state-edits.js';
+import { runSealState, computeRunSeals } from './run-seal.js';
+import { bindInputResolution, resolutionRecord, recordedInputResolution } from './input-resolution.js';
+
+const json = value => JSON.stringify(value) + '\n';
+const fail = code => { throw Error(code); };
+function ensureDirectory(root, path) {
+  if (hasSymlinkComponent(root, path)) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+  const full = join(root, path);
+  if (!existsSync(full)) { mkdirSync(full, { mode: 0o700 }); fsyncDirectory(dirname(full)); }
+  if (!lstatSync(full).isDirectory() || lstatSync(full).isSymbolicLink()) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+}
+function validateIntent(stored, id) {
+  const intent = resolutionRecord(stored);
+  if (!intent) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+  if (!exactObject(intent, ['schema_version', 'origin', 'outputs']) || intent.schema_version !== 1 || !validPlannedOrigin(intent.origin)
+    || intent.origin.plan_id !== id || !Array.isArray(intent.outputs) || intent.outputs.length !== 2) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+  const { origin, outputs } = intent, base = `${runDocumentPath(origin.run_id, '')}/`;
+  const expected = [origin.initial_ur.path, origin.snapshot.path];
+  if (outputs.some((row, i) => !exactObject(row, ['path', 'content', 'digest']) || row.path !== expected[i]
+      || typeof row.content !== 'string' || Buffer.byteLength(row.content) > 131072 || plannedTextDigest(row.content) !== row.digest)
+    || outputs[0].content !== outputs[1].content || outputs[0].digest !== origin.planned.digest
+    || plannedRawDigest(outputs[1].content) !== origin.raw_digest) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+  const resolution = recordedInputResolution(stored);
+  if (resolution && (resolution.operation_id !== intent.origin.operation_id || resolution.kind !== 'run.create_from_planned'
+    || resolution.effective_digest !== intent.origin.request_digest)) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+  return stored;
+}
+function transferRecord(origin, originDigest) {
+  return { schema_version: 1, plan_id: origin.plan_id, run_id: origin.run_id, operation_id: origin.operation_id,
+    request_digest: origin.request_digest, source_digest: origin.planned.digest, origin_digest: originDigest };
+}
+function finishEntry(root, origin, originDigest, checkpoint) {
+  const base = plannedEntryPath(origin.plan_id), transfer = `${base}/TRANSFER.json`, pending = `${base}/HANDOFF_PENDING.json`;
+  const receipt = transferRecord(origin, originDigest), text = json(receipt);
+  if (existsSync(join(root, transfer))) {
+    if (readContainedControlText(root, transfer, 4096) !== text) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+  } else { markControlMutationEffect(); atomicWrite(join(root, transfer), text); checkpoint('handoff_entry_receipt'); }
+  if (existsSync(join(root, pending))) {
+    const intent = validateIntent(JSON.parse(readContainedControlText(root, pending, PLANNED_INTENT_BYTES)), origin.plan_id);
+    if (canonicalJson(intent.origin) !== canonicalJson(origin)) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+    unlinkSync(join(root, pending)); fsyncDirectory(join(root, base)); checkpoint('handoff_retired');
+  }
+  return receipt;
+}
+
+export function inspectPlannedHandoffOperation(root, planId, operationId) {
+  plannedEntryPath(planId);
+  if (!REVISION_ID_PATTERN.test(operationId ?? '')) fail('AGDF_PLANNED_HANDOFF_INPUT_INVALID');
+  const observed = inspectPlannedOrigins(root, planId);
+  if (!observed.complete) return { status: 'unknown', reason: 'planned_origin_unconfirmed', findings: observed.findings, authorizes: false };
+  const known = observed.matches[0], path = `${plannedEntryPath(planId)}/HANDOFF_PENDING.json`;
+  if (known) {
+    if (known.origin.operation_id !== operationId) return { status: 'already_transferred', run_id: known.run_id, authorizes: false };
+    return { status: existsSync(join(root, path)) ? 'committed_recovery_required' : 'recorded', receipt: known.receipt,
+      request_digest: known.origin.request_digest, run_id: known.run_id, historical_effect: true, authorizes: false };
+  }
+  if (controlPathPresent(root, `${plannedEntryPath(planId)}/TRANSFER.json`)) return { status: 'unknown', reason: 'planned_transfer_unconfirmed', authorizes: false };
+  if (!existsSync(join(root, path))) return { status: 'absent', reason: 'absence_is_not_proof_of_non_execution', authorizes: false };
+  const pending = validateIntent(JSON.parse(readContainedControlText(root, path, PLANNED_INTENT_BYTES)), planId);
+  if (pending.origin.operation_id !== operationId) return { status: 'unknown', reason: 'another_pending_handoff', authorizes: false };
+  return { status: 'pending', request_digest: pending.origin.request_digest, pending, run_id: pending.origin.run_id, authorizes: false };
+}
+
+// Explicit selected-source handoff, never approval. Entry -> deterministic
+// creation -> staged Run publication. No active UR synchronization afterwards.
+export function createRunFromPlanned(root, { plan_id, expected_digest, operation_id, target_id, request_digest, presentation_language = 'en', title },
+  { packageVersion = '0.20.2', checkpoint = () => {} } = {}) {
+  plannedEntryPath(plan_id);
+  if (!REVISION_ID_PATTERN.test(operation_id ?? '') || !/^sha256:[a-f0-9]{64}$/u.test(expected_digest ?? '')
+    || !/^sha256:[a-f0-9]{64}$/u.test(request_digest ?? '') || target_id !== resolveControlCommandTarget(root).target_id) fail('AGDF_PLANNED_HANDOFF_INPUT_INVALID');
+  let effectStarted = false;
+  return withPlannedEntryLock(root, plan_id, () => {
+    const execute = () => {
+      const origins = inspectPlannedOrigins(root, plan_id);
+      if (!origins.complete) fail('AGDF_PLANNED_ORIGIN_UNCONFIRMED');
+      if (origins.matches.length) {
+        const known = origins.matches[0], originDigest = digest(canonicalJson(known.receipt.effect.record));
+        if (known.origin.operation_id === operation_id && (known.origin.request_digest !== request_digest || known.origin.target_id !== target_id)) fail('AGDF_OPERATION_PAYLOAD_CONFLICT');
+        effectStarted = true;
+        const finish = () => withOwnedFileLock(join(root, '.agdf/control/runs', `.create-${known.origin.operation_id}`),
+          () => finishEntry(root, known.origin, originDigest, checkpoint));
+        if (known.origin.operation_id === operation_id) finish();
+        else withControlRecovery(root, { resource: `planned:${plan_id}`, operation_id: known.origin.operation_id,
+          proveOutcome: () => inspectPlannedOrigins(root, plan_id).matches.length === 1 }, finish);
+        return { outcome: known.origin.operation_id === operation_id ? 'already_applied' : 'already_transferred', run_id: known.run_id, receipt: known.receipt, historical_effect: true, authorizes: false };
+      }
+      if (controlPathPresent(root, `${plannedEntryPath(plan_id)}/TRANSFER.json`)) fail('AGDF_PLANNED_ORIGIN_UNCONFIRMED');
+      const entry = inspectPlannedEntry(root, plan_id, { presentationLanguage: presentation_language });
+      if (entry.pending) fail('AGDF_PLANNED_RECOVERY_REQUIRED');
+      if (entry.digest !== expected_digest) fail('AGDF_PLANNED_SOURCE_STALE');
+      if (!entry.readiness.ready) throw Object.assign(Error('AGDF_PLANNED_UR_NOT_READY'), { readiness: entry.readiness });
+      if (title !== undefined && title !== entry.title) fail('AGDF_PLANNED_TITLE_INVALID');
+      const rawSource = readContainedControlText(root, entry.path);
+      if (plannedRawDigest(rawSource) !== entry.raw_digest) fail('AGDF_PLANNED_SOURCE_STALE');
+      const runId = creationRunId(operation_id), base = plannedEntryPath(plan_id), runBase = `${runDocumentPath(runId, '')}/`;
+      const origin = { schema_version: 1, plan_id, operation_id, run_id: runId, target_id, request_digest, raw_digest: entry.raw_digest,
+        planned: { path: entry.path, digest: entry.digest }, snapshot: { path: runHistoryPath(runId, 'planning/UR.md'), digest: entry.digest },
+        initial_ur: { path: `${runBase}UR.md`, digest: entry.digest } };
+      const outputs = [{ path: origin.initial_ur.path, content: rawSource, digest: entry.digest },
+        { path: origin.snapshot.path, content: rawSource, digest: entry.digest }];
+      const intent = validateIntent(bindInputResolution({ schema_version: 1, origin, outputs }), plan_id), pendingPath = `${base}/HANDOFF_PENDING.json`;
+      function matching(content, staged) {
+        const parsed = parseRunState(content, runId), receipt = readRunOperations(content).receipts.find(row => row.operation_id === operation_id);
+        const seals = staged ? computeRunSeals(root, content, { artefactDigests: staged.artefactDigests }) : null;
+        const sealed = staged ? seals.content_seal === parsed.meta.content_seal && seals.approval_seal === parsed.meta.approval_seal : runSealState(root, content).status === 'valid';
+        if (!parsed.valid || !sealed || receipt?.kind !== 'run.create_from_planned'
+          || receipt.target_id !== target_id || receipt.request_digest !== request_digest
+          || canonicalJson(receipt.effect.record.planned) !== canonicalJson({ plan_id, path: entry.path, digest: entry.digest })) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+        return receipt;
+      }
+      return withOwnedFileLock(join(root, '.agdf/control/runs', `.create-${operation_id}`), () => {
+        if (existsSync(join(root, pendingPath))) {
+          const previous = validateIntent(JSON.parse(readContainedControlText(root, pendingPath, PLANNED_INTENT_BYTES)), plan_id);
+          if (canonicalJson(previous) !== canonicalJson(intent)) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+          // Roll back only the original sealed stage and exact owned bytes.
+          // Foreign or partially unprovable state remains recovery-required.
+          effectStarted = true; markControlMutationEffect();
+          recoverRunCreationStage(root, runId, matching, { discard: true, outputs });
+          checkpoint('handoff_rolled_back');
+        } else {
+          // No pre-existing publication or sibling output may be adopted just
+          // because its bytes happen to match the requested content.
+          if (existsSync(join(root, `.agdf/control/runs/${runId}`)) || outputs.some(row => existsSync(join(root, row.path)))) fail('AGDF_PLANNED_HANDOFF_COLLISION');
+        }
+        effectStarted = true; markControlMutationEffect();
+        if (existsSync(join(root, pendingPath))) {
+          if (readContainedControlText(root, pendingPath, PLANNED_INTENT_BYTES) !== json(intent)) fail('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED');
+        } else atomicWrite(join(root, pendingPath), json(intent));
+        checkpoint('handoff_intent');
+        let receipt = recoverRunCreationStage(root, runId, matching, { outputs });
+        if (!receipt) {
+          createRun(root, runId, undefined, { outputs, checkpoint, prepare(content) {
+            const next = projectUrObjective(content, entry.content);
+            const parsed = parseRunState(next, runId);
+            receipt = bindInputResolution({ schema_version: RUN_OPERATION_VERSION, kind: 'run.create_from_planned', operation_id, request_digest, target_id,
+              run_id: runId, expected_revision_id: null, created_at: new Date().toISOString(), producer: { contract: 'run-command/1', package_version: packageVersion },
+              assurance: COOPERATIVE_ASSURANCE, effect: { previous_revision_id: null, resulting_revision_id: parsed.meta.revision_id, revision: 1,
+                record: { title: entry.title, planned: { plan_id, path: entry.path, digest: entry.digest },
+                  snapshot: { ...origin.snapshot, raw_digest: origin.raw_digest } } } });
+            return appendRunOperation(next, receipt);
+          }, beforePublish: () => {
+            checkpoint('handoff_before_run_publish');
+            if (readContainedControlText(root, entry.path) !== rawSource) fail('AGDF_PLANNED_SOURCE_STALE');
+          } });
+        }
+        checkpoint('handoff_run_committed');
+        finishEntry(root, origin, digest(canonicalJson(receipt.effect.record)), checkpoint);
+        return { outcome: 'accepted', run_id: runId, receipt, historical_effect: false, authorizes: false };
+      });
+    };
+    try { return execute(); }
+    catch (error) {
+      if (!effectStarted || /RECOVERY_REQUIRED/u.test(error.message)) throw error;
+      throw Object.assign(Error('AGDF_PLANNED_HANDOFF_RECOVERY_REQUIRED'), { cause: error, operation_id, plan_id });
+    }
+  }, { operation_id, resume: true, proveOutcome: result => ['accepted', 'already_applied', 'already_transferred'].includes(result.outcome) });
+}

package/runtime/core/lib/control-state/planned-inventory.js

@@ -0,0 +1,90 @@
+import { readControlLayout } from './control-layout.js';
+import { existsSync, readdirSync, lstatSync, currentControlReadView } from '../control-read/fs.js';
+import { captureControlScope, controlPathPresent } from '../control-read/snapshot.js';
+import { join } from 'node:path';
+import { inspectPlannedEntry, inspectPlannedOperation, PLANNED_ROOT } from './planned-entry.js';
+import { inspectPlannedOrigins } from './planned-origin-reader.js';
+import { readRunInventory } from './run-inventory-reader.js';
+import { artefactFileDigest } from './run-seal.js';
+import { RUN_ID_PATTERN } from './run-identity.js';
+import { hasSymlinkComponent } from './contained-file.js';
+
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const titleKey = title => title.normalize('NFKC').replace(/\s+/gu, ' ').trim().toLowerCase();
+const rank = { high: 0, normal: 1, low: 2 };
+
+export function projectPlannedInventory(root, { language = 'en' } = {}) {
+  readControlLayout(root);
+  const entries = [], findings = [];
+  if (!existsSync(join(root, PLANNED_ROOT))) throw Error('AGDF_PLANNED_STORE_MISSING');
+  if (hasSymlinkComponent(root, PLANNED_ROOT) || !lstatSync(join(root, PLANNED_ROOT)).isDirectory()) throw Error('AGDF_PLANNED_PATH_INVALID');
+  const names = readdirSync(join(root, PLANNED_ROOT));
+  if (names.length > 20000) throw Error('AGDF_PLANNED_INVENTORY_LIMIT');
+  for (const name of names.filter(name => !RUN_ID_PATTERN.test(name))) {
+    if (name === '.gitkeep') {
+      const marker = lstatSync(join(root, PLANNED_ROOT, name));
+      if (marker.isFile() && !marker.isSymbolicLink() && marker.size === 0) continue;
+    }
+    if (/^\.entry-[a-z0-9][a-z0-9._-]{0,127}\.lock(?:\.reclaim)?$/u.test(name)) continue;
+    const staged = name.match(/^\.stage-(plan-[a-f0-9-]{36})-([a-f0-9-]{36})$/u);
+    if (staged) {
+      try {
+        const operation = inspectPlannedOperation(root, staged[1], staged[2]);
+        if (operation.status !== 'pending' || !operation.pending) throw Error('planned_stage_unknown');
+        findings.push({ plan_id: staged[1], code: 'planned_creation_pending', operation_id: staged[2] });
+        entries.push({ kind: 'planned', identity: `planned/${staged[1]}`, plan_id: staged[1], title: staged[1], priority: null,
+          source: { path: `${PLANNED_ROOT}/${staged[1]}/UR.md`, digest: null, raw_digest: null }, coverage: 'recovery_required',
+          run_id: null, handoff_ready: false, diagnostics: [{ code: 'planned_creation_pending', operation_id: staged[2] }],
+          actions: ['inspect_original_operation'], authorizes: false });
+      } catch (error) { findings.push({ code: 'planned_stage_unknown', path: `${PLANNED_ROOT}/${name}`, reason: error.code ?? error.message }); }
+    } else findings.push({ code: 'planned_name_unsupported', path: `${PLANNED_ROOT}/${name}` });
+  }
+  for (const id of names.filter(name => RUN_ID_PATTERN.test(name)).sort()) {
+    try {
+      const entry = inspectPlannedEntry(root, id, { presentationLanguage: language }), origins = inspectPlannedOrigins(root, id);
+      const handedOff = origins.matches.length === 1 && origins.complete;
+      const handoffPending = controlPathPresent(root, `${PLANNED_ROOT}/${id}/HANDOFF_PENDING.json`);
+      const orphanTransfer = !handedOff && controlPathPresent(root, `${PLANNED_ROOT}/${id}/TRANSFER.json`);
+      if (orphanTransfer) origins.findings.push({ code: 'planned_transfer_unconfirmed', plan_id: id });
+      const coverage = !origins.complete || orphanTransfer ? 'unconfirmed' : handedOff ? 'transferred' : entry.pending || handoffPending ? 'recovery_required'
+        : entry.readiness.ready ? 'ready' : 'draft';
+      entries.push({ kind: 'planned', identity: `planned/${id}`, plan_id: id, title: entry.title, priority: entry.priority,
+        source: { path: entry.path, digest: entry.digest, raw_digest: entry.raw_digest }, coverage,
+        run_id: handedOff ? origins.matches[0].run_id : null, handoff_ready: coverage === 'ready',
+        diagnostics: origins.findings, actions: handedOff ? ['inspect_source', 'open_run'] : coverage === 'unconfirmed' || coverage === 'recovery_required'
+          ? ['inspect_source', 'inspect_original_operation'] : ['inspect_source', 'continue_planning'], authorizes: false });
+      findings.push(...origins.findings.map(row => ({ ...row, plan_id: id })));
+    } catch (error) {
+      findings.push({ plan_id: id, code: error.code ?? error.message });
+      entries.push({ kind: 'planned', identity: `planned/${id}`, plan_id: id, title: id, priority: null,
+        source: { path: `${PLANNED_ROOT}/${id}/UR.md`, digest: null, raw_digest: null }, coverage: 'unavailable', run_id: null,
+        handoff_ready: false, diagnostics: [{ code: error.code ?? error.message }], actions: ['retry_inspection'], authorizes: false });
+    }
+  }
+  entries.sort((a, b) => (rank[a.priority] ?? 3) - (rank[b.priority] ?? 3) || compare(titleKey(a.title), titleKey(b.title)) || compare(a.plan_id, b.plan_id));
+  return { schema_version: 'planned-inventory/1', state: findings.length ? 'partial' : 'complete', entries, findings, authorizes: false };
+}
+
+export function readPlannedInventory(root, options) {
+  try { return currentControlReadView()?.readOptionalFileSync ? projectPlannedInventory(root, options) : captureControlScope(root, () => projectPlannedInventory(root, options)).data; }
+  catch (error) { return { schema_version: 'planned-inventory/1', state: 'unavailable', entries: [], findings: [{ code: error.code ?? error.message }], authorizes: false }; }
+}
+
+export function readWorkInventory(root, options = {}) {
+  try {
+    readControlLayout(root);
+    const project = () => {
+      const planned = projectPlannedInventory(root, options), runs = readRunInventory(root, options);
+      const references = planned.entries.filter(row => row.coverage === 'transferred');
+      const entries = [...planned.entries.filter(row => row.coverage !== 'transferred'), ...runs.runs.map(row => ({ ...row,
+        kind: 'run', identity: `run/${row.run_id}`, source: { path: row.path, digest: row.valid ? artefactFileDigest(root, row.path) : null },
+        planning_origins: references.filter(ref => ref.run_id === row.run_id).map(ref => ({ plan_id: ref.plan_id, source: ref.source })),
+        coverage: row.valid ? 'available' : 'unavailable', actions: ['open_run'], authorizes: false }))];
+      return { schema_version: 'work-inventory/1', state: planned.state === 'partial' || runs.state !== 'complete' ? 'partial' : 'complete',
+        entries, planning_references: references, findings: [...planned.findings, ...runs.findings, ...runs.runs.flatMap(row => row.findings)],
+        counts: { planned: planned.entries.length - references.length, runs: runs.runs.length, planning_references: references.length }, authorizes: false };
+    };
+    return currentControlReadView()?.readOptionalFileSync ? project() : captureControlScope(root, project).data;
+  } catch (error) { return { schema_version: 'work-inventory/1', state: 'unavailable', entries: [], planning_references: [],
+    findings: [{ code: error.code ?? error.message }], counts: null, authorizes: false }; }
+}

package/runtime/core/lib/control-state/planned-origin-reader.js

@@ -0,0 +1,48 @@
+// Live origin discovery composes current proof and seal validation. The seal's
+// immutable-origin proof stays below this reader to keep the dependency acyclic.
+import { RUN_ID_PATTERN } from './run-identity.js';
+import { existsSync, readdirSync, memoizeControlRead } from '../control-read/fs.js';
+import { join } from 'node:path';
+import { readContainedControlText, controlPathPresent, READ_LIMITS } from '../control-read/snapshot.js';
+import { parseRunState } from './run-state-parser.js';
+import { readRunOperations } from './run-operations.js';
+import { runSealState } from './run-seal.js';
+import { hasSymlinkComponent } from './contained-file.js';
+import { plannedOriginFromReceipt, validPlannedOrigin } from './planned-origin.js';
+
+function collectPlannedOrigins(root) {
+  const directory = '.agdf/control/runs', matches = [], findings = [];
+  if (hasSymlinkComponent(root, directory)) throw Error('AGDF_PLANNED_ORIGIN_UNCONFIRMED');
+  if (!existsSync(join(root, directory))) return { matches, findings };
+  const names = readdirSync(join(root, directory));
+  if (names.length > 20000) throw Error('AGDF_PLANNED_ORIGIN_LIMIT');
+  for (const id of names.filter(name => RUN_ID_PATTERN.test(name))) {
+    let receipt, origin;
+    try {
+      const path = `${directory}/${id}/RUN_STATE.md`;
+      if (!controlPathPresent(root, path)) continue;
+      const content = readContainedControlText(root, path, READ_LIMITS.file), parsed = parseRunState(content, id);
+      if (!parsed.valid) throw Error();
+      const creations = readRunOperations(content).receipts.filter(row => row.kind === 'run.create_from_planned');
+      if (creations.length > 1) throw Error();
+      receipt = creations[0]; if (!receipt) continue;
+      origin = plannedOriginFromReceipt(receipt);
+      if (!validPlannedOrigin(origin) || runSealState(root, content).status !== 'valid') throw Error();
+      matches.push({ origin, receipt, run_id: id, current_revision_id: parsed.meta.revision_id });
+    } catch { findings.push({ run_id: id, ...(origin ? { plan_id: origin.plan_id } : {}), code: 'planned_origin_unconfirmed' }); }
+  }
+  return { matches, findings };
+}
+export function inspectPlannedOrigins(root, planId) {
+  if (!RUN_ID_PATTERN.test(planId ?? '')) throw Error('AGDF_PLANNED_ID_INVALID');
+  const inventory = memoizeControlRead(`plannedOrigins:${root}`, () => collectPlannedOrigins(root));
+  const matches = inventory.matches.filter(row => row.origin.plan_id === planId);
+  const findings = inventory.findings.filter(row => !row.plan_id || row.plan_id === planId);
+  if (matches.length > 1) findings.push({ code: 'planned_origin_ambiguous', plan_id: planId });
+  return { matches, findings, complete: findings.length === 0 };
+}
+export function assertPlannedNotTransferred(root, id) {
+  const origins = inspectPlannedOrigins(root, id);
+  if (!origins.complete) throw Error('AGDF_PLANNED_ORIGIN_UNCONFIRMED');
+  if (origins.matches.length) throw Object.assign(Error('AGDF_PLANNED_ALREADY_TRANSFERRED'), { run_id: origins.matches[0].run_id });
+}

package/runtime/core/lib/control-state/planned-origin.js

@@ -0,0 +1,40 @@
+import { runDocumentPath, runHistoryPath, RUN_ID_PATTERN, REVISION_ID_PATTERN } from './run-identity.js';
+import { readContainedControlText } from '../control-read/snapshot.js';
+import { exactObject, digest, canonicalJson } from './approval-command-contract.js';
+import { readRunOperations } from './run-operations.js';
+import { artefactFileDigest } from './run-seal-compute.js';
+
+const hash = value => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/u.test(value);
+const reference = (value, path) => exactObject(value, ['path', 'digest']) && value.path === path && hash(value.digest);
+// The pending handoff retains its exact original effect for recovery. After
+// publication, the creation receipt and immutable snapshot are the authority.
+export function validPlannedOrigin(origin) {
+  if (!exactObject(origin, ['schema_version', 'plan_id', 'operation_id', 'run_id', 'target_id', 'request_digest', 'raw_digest', 'planned', 'snapshot', 'initial_ur'])
+    || origin.schema_version !== 1 || !RUN_ID_PATTERN.test(origin.plan_id ?? '') || !REVISION_ID_PATTERN.test(origin.operation_id ?? '')
+    || origin.run_id !== `run-${origin.operation_id}` || !hash(origin.target_id) || !hash(origin.request_digest) || !hash(origin.raw_digest)) return false;
+  return reference(origin.planned, `.agdf/control/planned/${origin.plan_id}/UR.md`)
+    && reference(origin.snapshot, runHistoryPath(origin.run_id, 'planning/UR.md'))
+    && reference(origin.initial_ur, runDocumentPath(origin.run_id, 'UR.md'))
+    && origin.snapshot.digest === origin.planned.digest && origin.initial_ur.digest === origin.planned.digest;
+}
+export function plannedOriginFromReceipt(receipt) {
+  const r = receipt.effect.record;
+  return { schema_version: 1, plan_id: r.planned.plan_id, operation_id: receipt.operation_id, run_id: receipt.run_id,
+    target_id: receipt.target_id, request_digest: receipt.request_digest, raw_digest: r.snapshot.raw_digest,
+    planned: { path: r.planned.path, digest: r.planned.digest }, snapshot: { path: r.snapshot.path, digest: r.snapshot.digest },
+    initial_ur: { path: runDocumentPath(receipt.run_id, 'UR.md'), digest: r.planned.digest } };
+}
+export function assertPlannedOriginImmutable(root, before, after) {
+  const creation = readRunOperations(before).receipts.find(row => row.kind === 'run.create_from_planned');
+  if (!creation) return;
+  try {
+    const next = readRunOperations(after).receipts.find(row => row.operation_id === creation.operation_id);
+    const origin = plannedOriginFromReceipt(creation);
+    if (canonicalJson(next) !== canonicalJson(creation) || !validPlannedOrigin(origin)
+      || artefactFileDigest(root, origin.snapshot.path) !== origin.snapshot.digest
+      || digest(readContainedControlText(root, origin.snapshot.path)) !== origin.raw_digest) throw Error();
+  } catch { throw Error('AGDF_PLANNED_ORIGIN_IMMUTABLE'); }
+}
+export function validPlannedOriginHistory(root, content) {
+  try { assertPlannedOriginImmutable(root, content, content); return true; } catch { return false; }
+}