@agdf/mcp-server 0.20.2 → 0.31.0

package/src/generation.js

@@ -8,7 +8,7 @@ import { DispatchExecutionError } from './worker.js';
 // One live facade, three directly owned children, no process registry or PID
 // discovery. Capacity includes startup and unconfirmed cleanup, not just current.
 export async function createOwnedGenerationFacade({ runtime, publisher, createControlRuntime, surface, cockpitDir, cockpitMode,
-  Fork = fork, qualifyMs = L.qualify, closeMs = L.close, invokeMs = L.qualify, onEvent = () => {} } = {}) {
+  generationTransport, Fork = fork, qualifyMs = L.qualify, closeMs = L.close, invokeMs = L.qualify, onEvent = () => {} } = {}) {
   if (![qualifyMs, closeMs, invokeMs].every(value => Number.isSafeInteger(value) && value > 0)
     || qualifyMs > L.qualify || closeMs > L.close || invokeMs > L.qualify) throw Error('generation_deadline_invalid');
   const epoch = randomUUID(), slots = new Map(), routes = new Map(), presentations = new Map(), operations = new Map(), receipts = new Map();
@@ -64,10 +64,16 @@ export async function createOwnedGenerationFacade({ runtime, publisher, createCo
       unknown: new Set(), inflight: 0, exited: false, closeAck: false, observed: null };
     slots.set(row.id, row); event(row, 'reserved'); // Reservation precedes acquisition/load/spawn.
     try {
-      const claim = publisher.acquire(packageInfo, { ownerEpoch: epoch, generation: row.id });
-      row.child = Fork(join(packageInfo.packageRoot, 'src/generation-entry.js'), [epoch, String(row.id)],
-        { stdio: ['ignore', 'ignore', 'ignore', 'ipc'], serialization: 'json', execArgv: [] });
-      claim.bindOwnedChild(row.child, { confirmedEnd: () => row.closeAck && !row.inflight && !row.unknown.size });
+      if (generationTransport) {
+        // This is a logical private connection. Actual Worker and claim ownership
+        // stay in the detached owner; no ChildProcess/Worker impersonation.
+        row.child = await generationTransport.open({ packageInfo, epoch, generation: row.id });
+      } else {
+        const claim = publisher.acquire(packageInfo, { ownerEpoch: epoch, generation: row.id });
+        row.child = Fork(join(packageInfo.packageRoot, 'src/generation-entry.js'), [epoch, String(row.id)],
+          { stdio: ['ignore', 'ignore', 'ignore', 'ipc'], serialization: 'json', execArgv: [] });
+        claim.bindOwnedChild(row.child, { confirmedEnd: () => row.closeAck && !row.inflight && !row.unknown.size });
+      }
       row.child.on('message', reply => {
         if (!validGenerationMessage(reply, { epoch, generation: row.id, reply: true })) { event(row, 'invalid_reply'); return; }
         const pending = row.pending.get(reply.request_id);
@@ -81,13 +87,18 @@ export async function createOwnedGenerationFacade({ runtime, publisher, createCo
           pending.resolve(reply);
         }
       });
-      row.child.once('exit', () => {
+      row.child.once('exit', (code, signal) => {
         row.exited = true;
         for (const pending of row.pending.values()) { clearTimeout(pending.timer); pending.reject(new DispatchExecutionError('generation_connection_lost')); }
         row.pending.clear();
-        if (row.closeAck && !row.inflight && !row.unknown.size) { slots.delete(row.id); row.state = 'closed'; event(row, 'confirmed_exit'); row.end?.(true); }
+        if (code === 0 && !signal && row.closeAck && !row.inflight && !row.unknown.size) { slots.delete(row.id); row.state = 'closed'; event(row, 'confirmed_exit'); row.end?.(true); }
         else { row.state = 'close_unconfirmed'; event(row, 'unexpected_exit'); row.end?.(false); }
       });
+      row.child.once('disconnect', () => {
+        row.state = 'close_unconfirmed'; event(row, 'connection_lost');
+        for (const pending of row.pending.values()) { clearTimeout(pending.timer); pending.reject(new DispatchExecutionError('generation_connection_lost')); }
+        row.pending.clear();
+      });
       row.child.once('error', () => { row.state = 'close_unconfirmed'; event(row, 'spawn_failed'); });
       row.state = 'qualifying'; event(row, 'qualifying');
       const qualified = (await request(row, 'qualify', { surface, commandGroups: [...(runtime.trustedContext.commandGroups ?? [])],
@@ -105,6 +116,11 @@ export async function createOwnedGenerationFacade({ runtime, publisher, createCo
   }
   const control = {
     status,
+    originalInput(input) {
+      const prior = receipts.get(input.operation_id);
+      if (!prior) return null;
+      return { known: true, resolution: prior.resolution ?? null };
+    },
     async refresh() { await Promise.all([...slots.values()].filter(row => !row.exited).map(observe)); return status(); },
     inspect(id, input) { const record = receipts.get(id);
       if (record && (record.input.run_id !== input.run_id || record.input.primary_target !== input.primary_target
@@ -112,18 +128,23 @@ export async function createOwnedGenerationFacade({ runtime, publisher, createCo
       return record ? { status: record.result ? 'recorded' : 'pending',
       request_digest: record.digest, result: record.result, current: status(), authorizes: false }
       : { status: 'unknown', reason: 'connection_control_record_unavailable', current: status(), authorizes: false }; },
-    async replace({ input, candidate, requestDigest, revalidate }) {
+    async replace({ input, candidate, requestDigest, resolution, revalidate }) {
       const prior = receipts.get(input.operation_id);
       if (prior) return prior.digest !== requestDigest ? failure('operation_payload_conflict')
         : prior.result ? { ...prior.result, outcome: prior.result.outcome === 'accepted' ? 'already_applied' : prior.result.outcome, historical_effect: true, current: status() }
         : { outcome: 'effect_unknown', reason: 'generation_replacement_pending', current: status(), authorizes: false };
       if (receipts.size >= L.receipts) return failure('connection_control_capacity');
       if (closed || replacing) return failure(closed ? 'connection_closed' : 'generation_replacement_busy');
-      const record = { digest: requestDigest, input, result: null }; receipts.set(input.operation_id, record); replacing = true;
+      const record = { digest: requestDigest, input, resolution, result: null }; receipts.set(input.operation_id, record); replacing = true;
       let candidateRow;
       try {
-        revalidate(); const packageInfo = publisher.resolve(candidate);
-        candidateRow = await reserve(packageInfo, actualContext); revalidate();
+        const recheck = () => {
+          if (closed) throw new DispatchExecutionError('connection_closed', 'not_dispatched');
+          controlRuntimeInstance?.verifyProducer();
+          revalidate();
+        };
+        recheck(); const packageInfo = publisher.resolve(candidate);
+        candidateRow = await reserve(packageInfo, actualContext); recheck();
         const previous = current; current = candidateRow; current.state = 'current';
         if (previous) previous.state = previous.exited ? 'close_unconfirmed' : 'draining';
         event(current, 'admitted'); record.result = { outcome: 'accepted', reason: null, operation_id: input.operation_id,
@@ -135,44 +156,66 @@ export async function createOwnedGenerationFacade({ runtime, publisher, createCo
       record.result.current = status(); return record.result;
     },
   };
-  const controlRuntime = createControlRuntime(control);
+  // Ordinary requests belong to the fully qualified generation. Only the rare
+  // facade control branches need another Core instance; share one initialization.
+  let controlRuntimePromise, controlRuntimeInstance;
+  const getControlRuntime = () => controlRuntimePromise ??= Promise.resolve().then(() => createControlRuntime(control)).then(async created => {
+    const producer = created?.producerIdentity;
+    const code = created?.trustedContext?.expectedVersion !== runtime.trustedContext.expectedVersion ? 'runtime_version_mismatch'
+      : created?.trustedContext?.provenanceStatus !== 'matched'
+      || !producer || producer.server_digest !== publisher.initial.digest || producer.dispatcher_digest !== publisher.initial.dispatcherDigest
+      || producer.sdk_digest !== publisher.initial.sdkDigest || typeof created.verifyProducer !== 'function'
+      ? 'runtime_provenance_invalid' : null;
+    if (code) {
+      await created?.close?.(); throw new DispatchExecutionError(code, 'not_dispatched');
+    }
+    controlRuntimeInstance = created;
+    return created;
+  }).catch(error => { throw new DispatchExecutionError(generationFailureReason(error), 'not_dispatched'); });
   function operationKey(input, id = input.operation_id) { return JSON.stringify([input.primary_target, input.run_id, id]); }
   async function invoke(name, args, host = {}, signal) {
     if (signal?.aborted) throw new DispatchExecutionError('dispatch_cancelled', 'not_dispatched');
     if (closed) throw new DispatchExecutionError('connection_closed', 'not_dispatched');
     actualContext = { client: host.client, uiSupported: host.uiSupported === true };
+    const canonical = Boolean(args.operation_id) && !runtime.isEphemeralControlCommand?.(name,args);
     if (args.operation_id && name === 'agdf_record' && args.command?.kind === 'runtime_generation.replace'
       && operations.has(operationKey(args))) throw new DispatchExecutionError('operation_payload_conflict', 'not_dispatched');
     if (args.operation_id && args.command?.kind !== 'runtime_generation.replace' && receipts.has(args.operation_id))
       throw new DispatchExecutionError('operation_payload_conflict', 'not_dispatched');
     if (name === 'agdf_record' && args.command?.kind === 'runtime_generation.replace'
       || name === 'agdf_inspect' && args.operation === 'runtime-generations') {
+      const controlRuntime = await getControlRuntime();
+      if (closed || signal?.aborted) throw new DispatchExecutionError(closed ? 'connection_closed' : 'dispatch_cancelled', 'not_dispatched');
+      try { controlRuntime.verifyProducer(); } catch (error) { throw new DispatchExecutionError(generationFailureReason(error), 'not_dispatched'); }
       const result = await controlRuntime.tool(name).execute(controlRuntime.tool(name).parse(args));
       return controlRuntime.projectToolResult(name, args, name === 'agdf_inspect' && result.report?.available ? { ...result, report: await control.refresh() } : result);
     }
     if (name === 'agdf_inspect' && args.operation === 'operation-status' && receipts.has(args.module)) {
+      const controlRuntime = await getControlRuntime();
+      if (closed || signal?.aborted) throw new DispatchExecutionError(closed ? 'connection_closed' : 'dispatch_cancelled', 'not_dispatched');
+      try { controlRuntime.verifyProducer(); } catch (error) { throw new DispatchExecutionError(generationFailureReason(error), 'not_dispatched'); }
       const validated = await controlRuntime.tool(name).execute(controlRuntime.tool(name).parse(args));
       return controlRuntime.projectToolResult(name, args, validated.report?.status === 'unknown' || validated.report?.status === 'absent'
         ? { ...validated, report: control.inspect(args.module, args) } : validated);
     }
     const knownSession = args.session_id && routes.get(args.session_id);
     if (args.session_id && !knownSession) throw new DispatchExecutionError('session_expired', 'not_dispatched');
-    const id = name === 'agdf_inspect' && args.operation === 'operation-status' ? args.module : args.operation_id;
+    const id = name === 'agdf_inspect' && args.operation === 'operation-status' ? args.module.split('/').at(-1) : canonical ? args.operation_id : null;
     const key = id && operationKey(args, id), original = key && operations.get(key);
     const presentationId = args.command?.payload?.presentation_id ?? args.presentation_id;
     const presentationOwner = presentationId && presentations.get(operationKey(args, presentationId));
     const row = knownSession ?? original ?? presentationOwner ?? current;
     if (!row || row.exited) throw new DispatchExecutionError('generation_unavailable', 'not_dispatched');
-    if (args.operation_id && !original) {
+    if (canonical && !original) {
       if (operations.size >= L.routes) throw new DispatchExecutionError('generation_route_capacity', 'not_dispatched');
       operations.set(key, row);
     }
     ++row.inflight; event(row, 'invoke', name);
     try {
-      const result = (await request(row, 'invoke', { name, arguments: args }, actualContext, args.operation_id ?? null, invokeMs)).payload;
-      if (args.operation_id && result.outcome === 'effect_unknown') row.unknown.add(key);
+      const result = (await request(row, 'invoke', { name, arguments: args }, actualContext, canonical ? args.operation_id : null, invokeMs)).payload;
+      if (canonical && result.outcome === 'effect_unknown') row.unknown.add(key);
       if (name === 'agdf_inspect' && args.operation === 'operation-status' && result.report?.status === 'recorded'
-        && result.report.receipt?.operation_id === args.module) row.unknown.delete(key);
+        && (result.report.receipt?.operation_id ?? result.report.receipt?.operation?.operation_id) === id) row.unknown.delete(key);
       if (result.app_capability === 'available') nativeRequired = true;
       if (result.family_result?.presentation_id && ['accepted', 'already_applied'].includes(result.outcome)) {
         const presentationKey = operationKey(args, result.family_result.presentation_id);
@@ -185,7 +228,7 @@ export async function createOwnedGenerationFacade({ runtime, publisher, createCo
         }
       }
       return result;
-    } catch (error) { if (args.operation_id && error.dispatch !== 'not_dispatched') row.unknown.add(key); throw error; }
+    } catch (error) { if (canonical && error.dispatch !== 'not_dispatched') row.unknown.add(key); throw error; }
     finally { --row.inflight; if (closed && !row.inflight && !row.unknown.size) void retire(row, true); }
   }
   current = await reserve(publisher.initial, {}); current.state = 'current'; event(current, 'admitted');
@@ -194,16 +237,17 @@ export async function createOwnedGenerationFacade({ runtime, publisher, createCo
   // not wire requests; parsing them again in a child both breaks the contract
   // and copies the entire locale registry into a bounded private message.
   const tools = runtime.tools.map(tool => ({ ...tool, parentOwned: true,
-    parse: input => { tool.parse(input); return input; }, execute: input => invoke(tool.name, input) }));
+    parse: input => { if (runtime.validatePublicInput?.(tool.name, input) !== true) tool.parse(input); return input; }, execute: input => invoke(tool.name, input) }));
   // The server supplies actual initialize/request context only at this seam.
   for (const tool of tools) tool.execute = (input, signal, host) => invoke(tool.name, input, host, signal);
   return Object.freeze({ ...runtime, tools, tool: name => tools.find(tool => tool.name === name),
-    requiresProjectedResult: true, postprocessToolResult: undefined, inspectOwnership: status, runtimeControl: control,
+    requiresProjectedResult: true, prepareInput: undefined, postprocessToolResult: undefined, inspectOwnership: status, runtimeControl: control,
     close() {
       return closing ??= (async () => {
         closed = true;
         const previous = current; current = null; if (previous && !previous.exited) previous.state = 'draining';
         await Promise.allSettled([...slots.values()].map(row => retire(row, true)));
+        if (controlRuntimePromise) await controlRuntimePromise.then(controlRuntime => controlRuntime.close?.(), () => {});
         return status();
       })();
     },

package/src/main.js

@@ -1,15 +1,16 @@
 import { readFileSync } from "node:fs";
 import process from "node:process";
-import { createAgdfWorkerExecutor, serveAgdfStdio } from "./server.js";
 import { loadCockpitResource } from './cockpit-resource.js';
 
-export async function runMcpServer({ surface, cockpitDir, cockpitMode, runtime, executor, ownedPublication, ownedPublisher, onClosed } = {}) {
+export async function runMcpServer({ surface, cockpitDir, cockpitMode, runtime, executor, ownedPublication, ownedPublisher, generationTransport, onClosed } = {}) {
   if (cockpitMode !== undefined && (cockpitMode !== 'plugin' || surface !== 'codex' || cockpitDir !== undefined)) throw Error('AGDF_COCKPIT_TARGET_INVALID');
   const defaultRuntime = runtime === undefined && cockpitDir === undefined && cockpitMode === undefined;
   // A supplied, bound runtime owns its resources. Do not load a second package
   // composition merely to run an explicit adapter/protocol fixture.
-  const dispatcherRuntime = runtime === undefined ? await import('create-agdf/mcp-dispatch-runtime') : null;
-  runtime ??= cockpitDir !== undefined || cockpitMode !== undefined ? await dispatcherRuntime.createMcpCockpitRuntime({ surface, cockpitDir, cockpitMode }) : dispatcherRuntime.createMcpDispatchRuntime({ surface });
+  const thin = defaultRuntime && !!ownedPublication;
+  const dispatcherRuntime = runtime === undefined ? await import(thin ? 'create-agdf/mcp-protocol-runtime' : 'create-agdf/mcp-dispatch-runtime') : null;
+  runtime ??= cockpitDir !== undefined || cockpitMode !== undefined ? await dispatcherRuntime.createMcpCockpitRuntime({ surface, cockpitDir, cockpitMode })
+    : thin ? dispatcherRuntime.createMcpTransportRuntime({ surface }) : dispatcherRuntime.createMcpDispatchRuntime({ surface });
   const serverVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
   if (runtime.trustedContext.expectedVersion !== serverVersion) {
     process.stderr.write("AGDF_MCP_VERSION_MISMATCH\n");
@@ -21,26 +22,58 @@ export async function runMcpServer({ surface, cockpitDir, cockpitMode, runtime,
     process.exitCode = 1;
     return null;
   }
-  if (defaultRuntime && surface === 'codex' && dispatcherRuntime?.createMcpDecisionRuntime) {
+  if (ownedPublication) {
+    // The serving protocol factory freshly inspects all selected source and SDK
+    // bytes. Bind that actual producer to the parent's claimed expectation;
+    // never treat a cross-thread/async observation as fresh inspection evidence.
+    const producer = runtime.producerIdentity;
+    if (!producer || producer.server_digest !== ownedPublication.digest
+      || producer.dispatcher_digest !== ownedPublication.dispatcherDigest || producer.sdk_digest !== ownedPublication.sdkDigest)
+      throw Error('AGDF_MCP_FACADE_IDENTITY_INVALID');
+  }
+  if (defaultRuntime && surface === 'codex') {
     const ui = { uri: dispatcherRuntime.DECISION_UI_URI, mimeType: 'text/html;profile=mcp-app', limit: 4 * 1024 ** 2, kind: 'decision' };
-    ui.digest = loadCockpitResource(ui).digest;
+    // The thin front has no session/qualification consumer. Its facade loads
+    // the resource for the real generation manifest; full runtimes need it here.
+    if (!thin) ui.digest = loadCockpitResource(ui).digest;
     // A shipped resource does not qualify native App-only mediation. Production
     // actions remain disabled until exact package/host evidence is provided.
-    runtime = await dispatcherRuntime.createMcpDecisionRuntime({ runtime, ui });
+    runtime = thin ? await dispatcherRuntime.createMcpDecisionTransportRuntime({ runtime, ui })
+      : await dispatcherRuntime.createMcpDecisionRuntime({ runtime, ui });
   }
   if (runtime.mode === 'cockpit') loadCockpitResource(runtime.ui);
+  let transport;
   if (ownedPublication) {
     const { createOwnedGenerationFacade } = await import('./generation.js');
     if (!ownedPublisher) throw Error('runtime_publication_unowned');
     const publisher = ownedPublisher;
-    runtime = await createOwnedGenerationFacade({ runtime, publisher, surface, cockpitDir, cockpitMode,
-      createControlRuntime: runtimeControl => dispatcherRuntime.createMcpDispatchRuntime({ surface, runtimeControl }) });
-  }
+    let beginTransport;
+    const claimed = new Promise(resolve => { beginTransport = resolve; });
+    const starting = createOwnedGenerationFacade({ runtime, publisher, generationTransport, surface, cockpitDir, cockpitMode,
+      onEvent: event => { if (event.kind === 'qualifying') beginTransport(); },
+      createControlRuntime: async runtimeControl => {
+        const full = thin ? await import('create-agdf/mcp-dispatch-runtime') : dispatcherRuntime;
+        return full.createMcpDispatchRuntime({ surface, runtimeControl });
+      } });
+    // Only a claimed private-generation start releases the SDK import. A
+    // pre-claim failure rejects starting without loading transport code. Its full
+    // qualification and the facade SDK must both finish before public service.
+    // Observe both promises so a transport failure cannot abandon a live child.
+    const transportStarting = Promise.race([claimed, starting]).then(() => import('./server.js'));
+    const [generation, loaded] = await Promise.allSettled([starting, transportStarting]);
+    if (generation.status === 'rejected' || loaded.status === 'rejected') {
+      if (generation.status === 'fulfilled') await generation.value.close();
+      throw generation.status === 'rejected' ? generation.reason : loaded.reason;
+    }
+    runtime = generation.value; transport = loaded.value;
+  } else transport = await import('./server.js');
+  const { createAgdfWorkerExecutor, serveAgdfStdio } = transport;
   const dispatchExecutor = executor ?? (runtime.mode === 'cockpit' ? undefined
     : createAgdfWorkerExecutor(runtime, { releaseOwnedLock: dispatcherRuntime?.releaseAbandonedOwnedLock ?? null }));
   const handle = serveAgdfStdio({
     runtime,
     executor: dispatchExecutor,
+    preparedCallStore: ownedPublication ? ownedPublisher?.preparedCallStore?.({ surface }) : undefined,
     onerror(code) {
       process.stderr.write(`${code}\n`);
     },

package/src/next-action.js

@@ -0,0 +1,227 @@
+const writeTools = new Set(['agdf_project', 'agdf_run', 'agdf_prepare', 'agdf_record', 'agdf_approve', 'agdf_revise', 'agdf_closeout']);
+const knownTools = new Set([...writeTools, 'agdf_inspect', 'agdf_dispatch']);
+const clone = value => structuredClone(value);
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const canonical = value => JSON.stringify(stable(value));
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  return object(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])])) : value;
+}
+function callValue(value) {
+  return object(value) && knownTools.has(value.tool) && object(value.arguments)
+    ? { tool: value.tool, arguments: clone(value.arguments) } : null;
+}
+function formValue(value) {
+  if (!object(value)) return null;
+  const call = callValue(value.call ?? value);
+  if (!call) return null;
+  // A normal mutating action must already be the transport's bound form. Never
+  // promote its Raw recovery branch or reconstruct one from operation metadata.
+  if (writeTools.has(call.tool) && (!Object.hasOwn(call.arguments, 'prepared_call_id')
+    || typeof call.arguments.prepared_call_id !== 'string' || !call.arguments.prepared_call_id
+    || !object(call.arguments.inputs) || Object.keys(call.arguments).some(key => !['prepared_call_id', 'inputs'].includes(key)))) return null;
+  if (value.required_inputs !== undefined && (!Array.isArray(value.required_inputs)
+    || value.required_inputs.some(field => typeof field !== 'string' || !field))) return null;
+  const source = clone(value);
+  delete source.tool; delete source.arguments;
+  return { ...source, call, required_inputs: Array.isArray(value.required_inputs) ? clone(value.required_inputs) : [] };
+}
+function uniqueForms(values) {
+  const forms = new Map();
+  for (const value of values.filter(Boolean)) {
+    const form = formValue(value);
+    if (!form) return null;
+    const key = canonical({ call: form.call, required_inputs: form.required_inputs });
+    if (!forms.has(key)) forms.set(key, form);
+  }
+  return [...forms.values()];
+}
+function base(state, instruction, source, extra = {}) {
+  return { state, call: null, required_inputs: [], instruction, source, ...extra, authorizes: false };
+}
+function terminal(result, source) {
+  return base('terminal', 'Respect this result\'s terminal host_action and stop; no next tool call is selected.', source,
+    result.host_action ? { host_action: clone(result.host_action) } : {});
+}
+function selectForms(values, source, { forceReply = false, readOnly = false } = {}) {
+  const forms = uniqueForms(values);
+  if (!forms?.length) return base('requires_source', 'No complete normal action was supplied. Read the canonical source or use its explicit recovery instructions; do not construct a replacement call.', source);
+  if (forms.length !== 1) return base('requires_selection', 'Several distinct actions were supplied. Preserve the current binding and obtain the authoritative selection; do not pick the first action.', source);
+  const form = forms[0];
+  if (readOnly && form.call.tool !== 'agdf_inspect') return base('requires_source', 'The supplied continuation is not a read-only page call; no action is selected.', source);
+  const reply = forceReply || form.call.tool === 'agdf_approve' || form.operation?.kind === 'approval.record';
+  if (reply) {
+    // The contract's approval_value is syntax, never a response. A producer that
+    // filled a reply in an offered form cannot establish new human intent here.
+    if (Object.values(form.call.arguments.inputs ?? {}).some(value => value !== '' && value !== undefined))
+      return base('requires_new_reply', 'Obtain a fresh blank approval form and a NEW deliberate reply for its exact presentation. No reply or approval is inferred.', source);
+    return { ...form, state: 'requires_new_reply', source, authorizes: false,
+      instruction: 'Deliver the current presentation before waiting for a NEW deliberate reply. Fill only the supplied reply field from that response; never copy approval_value as a decision. ' + (form.instruction ?? '') };
+  }
+  return { ...form, state: form.required_inputs.length ? 'form' : 'ready', source, authorizes: false,
+    instruction: 'Use this one exact call. Supply only its named required inputs from actual authored content or review; do not rebuild IDs, bindings or a Raw envelope. ' + (form.instruction ?? '') };
+}
+function authoringKey(result, report) {
+  if (report.format !== 'document_bundle_v2' || !/^sha256:[0-9a-f]{64}$/u.test(report.manifest_digest ?? '')) return null;
+  return canonical({ manifest: report.manifest_digest,
+    target_id: result.target?.target_id ?? result.binding?.target_id ?? report.target_id ?? null,
+    target: result.target?.governance_target ?? result.target?.display_path ?? null,
+    run_id: report.run_id ?? null, revision_id: report.revision_id ?? null, planning: report.planning ?? null,
+    owner: report.authoring_owner ?? null, artifact_language: report.artifact_language ?? null,
+    presentation_language: report.presentation_language ?? null });
+}
+function authoringRevision(key) {
+  const { manifest, ...binding } = JSON.parse(key);
+  return canonical(binding);
+}
+function authoringScope(key) {
+  const { manifest, revision_id, ...scope } = JSON.parse(key);
+  return canonical(scope);
+}
+
+// A connection-local projection of supplied actions, not an executor, permission
+// decision or proof that the model has read/reviewed all source pages.
+export function createNextActionProjection({ maxEntries = 32, isAvailable = () => true } = {}) {
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1 || maxEntries > 32) throw Error('next_action_cache_limit_invalid');
+  if (typeof isAvailable !== 'function') throw Error('next_action_availability_invalid');
+  const forms = new Map(), superseded = new Set();
+  function available(form) {
+    const normal = formValue(form);
+    if (!normal) return false;
+    try { return isAvailable(clone(normal.call)) === true; } catch { return false; }
+  }
+  function remember(key, form) {
+    if (!key) return;
+    const revision = authoringRevision(key);
+    if (superseded.has(revision)) return;
+    if (!available(form)) { forms.delete(key); return; }
+    // A newly supplied first-page form for this exact authoring scope replaces
+    // cached forms from its earlier revision. Never refresh their bindings, or
+    // let a later old page revive them. Other targets/Runs/owners stay intact.
+    const scope = authoringScope(key);
+    for (const prior of forms.keys()) if (authoringScope(prior) === scope && authoringRevision(prior) !== revision) {
+      forms.delete(prior); superseded.add(authoringRevision(prior));
+    }
+    while (superseded.size > maxEntries) superseded.delete(superseded.values().next().value);
+    forms.delete(key); forms.set(key, clone(form));
+    while (forms.size > maxEntries) forms.delete(forms.keys().next().value);
+  }
+  function rememberAuthoring(result) {
+    if (result?.terminal === true || result?.outcome !== 'inspect_result' || result.operation !== 'authoring-inputs') return;
+    const report = result.report;
+    if (!object(report) || report.available === false || !report.material_call
+      || report.page_index !== undefined && report.page_index !== 0) return;
+    for (const owner of [result, result.continuation, result.navigation, report, result.family_result].filter(object))
+      if (owner.next_calls !== undefined && owner.next_calls !== null && !Array.isArray(owner.next_calls)
+        || owner.recording_calls !== undefined && owner.recording_calls !== null && !Array.isArray(owner.recording_calls)) return;
+    remember(authoringKey(result, report), report.material_call);
+  }
+  function fromContext(result, source) {
+    if (result.terminal === true) return terminal(result, source);
+    if (['rejected', 'recovery_required', 'effect_unknown', 'invalid_input', 'evaluator_error', 'target_unresolved'].includes(result.outcome))
+      return base('requires_source', 'This operation did not establish a successful normal continuation. Preserve its original receipt and recovery instructions; no write form is selected.', source);
+    const report = object(result.report) ? result.report : null;
+    for (const owner of [result, result.continuation, result.navigation, report, result.family_result].filter(object))
+      if (owner.next_calls !== undefined && owner.next_calls !== null && !Array.isArray(owner.next_calls)
+        || owner.recording_calls !== undefined && owner.recording_calls !== null && !Array.isArray(owner.recording_calls))
+        return base('requires_source', 'The supplied action list is malformed. Preserve the existing outcome and obtain the canonical action source.', source);
+    if (Object.hasOwn(result, 'material_call')) {
+      const material = formValue(result.material_call);
+      // This is an explicit correction after accepted private staging, not a
+      // ready write or permission to bypass the source's recording decision.
+      if (result.outcome !== 'accepted' || result.historical_effect === true || result.source_validation?.recordable !== false
+          || report?.available === false || report?.complete === false
+          || !material || material.call.tool !== 'agdf_record' || material.operation?.kind !== 'material.stage'
+          || material.state === 'transport_unavailable' || material.transport_reason
+          || !material.required_inputs.length || new Set(material.required_inputs).size !== material.required_inputs.length
+          || Object.keys(material.call.arguments.inputs).length || !available(material))
+        return base('requires_source', 'No complete authored correction form was supplied. Preserve the source validation and receipt; obtain the canonical correction source without constructing a new call.', source + '.material_call');
+      const competing = [...(result.recording_calls ?? []), ...(result.next_calls ?? []),
+        ...(result.continuation?.next_calls ?? []), ...(report?.next_calls ?? []),
+        ...(result.navigation?.next_calls ?? []), ...(result.family_result?.next_calls ?? []),
+        ...(result.approval_call ? [result.approval_call] : []), ...(report?.prepared_call ? [report.prepared_call] : []),
+        ...(report?.material_call ? [report.material_call] : [])];
+      if (competing.some(value => !value))
+        return base('requires_source', 'The correction action list is malformed. Preserve the source validation and obtain the canonical correction source.', source + '.material_call');
+      return selectForms([result.material_call, ...competing], source + '.material_call');
+    }
+    if (result.approval_call && result.presentation_delivery && !result.historical_effect && !result.presentation_delivery.historical_delivery
+      && ['accepted', 'already_applied'].includes(result.outcome)) return selectForms([result.approval_call], source + '.approval_call', { forceReply: true });
+    if (Array.isArray(result.recording_calls) && result.recording_calls.length)
+      return selectForms(result.recording_calls, source + '.recording_calls');
+    if (result.operation === 'operation-contract' && report?.prepared_call && report.available === false)
+      return base('requires_source', 'The operation-contract report is unavailable. Preserve its original binding and recovery instructions; no write form is selected.', source + '.report');
+    if (result.operation === 'operation-contract' && report?.prepared_call)
+      return selectForms([report.prepared_call], source + '.report.prepared_call');
+    if (result.operation === 'authoring-inputs' && report) {
+      if (report.available === false)
+        return base('requires_source', 'The authoring source is unavailable. Preserve its original binding and recovery instructions; no staging form is selected.', source + '.report');
+      const key = authoringKey(result, report);
+      if (report.material_call && (report.page_index === 0 || report.page_index === undefined)) remember(key, report.material_call);
+      if (key && superseded.has(authoringRevision(key)))
+        return base('requires_source', 'A newly supplied first-page form superseded this authoring revision. Preserve the selected source and obtain its canonical current form; no older binding or cached form is revived.', source + '.report');
+      if (report.complete !== true) {
+        if (report.next_calls?.length) {
+          const next = selectForms(report.next_calls, source + '.report.next_calls', { readOnly: true });
+          return next.state === 'ready' ? { ...next, state: 'read_required',
+            instruction: 'Read this exact next page before authoring. Retain earlier bytes and respect fragment identities; page transport does not prove review. ' + next.instruction } : next;
+        }
+        return base('requires_source', 'The authoring source is incomplete and no exact next-page call was supplied. Do not stage or edit incomplete content.', source + '.report');
+      }
+      if (report.authoring_scope === 'delivery-closeout')
+        return base('idle', 'The bound closeout evidence is complete. Use the current control and evidence for the requested handoff.', source + '.report');
+      let material = report.material_call ?? (key && forms.get(key));
+      if (material && !available(material)) {
+        if (key) forms.delete(key);
+        material = null;
+      }
+      if (material) return selectForms([material], source + (report.material_call ? '.report.material_call' : '.cached_material_call'));
+      if (report.first_page_call) {
+        const next = selectForms([report.first_page_call], source + '.report.first_page_call', { readOnly: true });
+        return next.state === 'ready' ? { ...next, state: 'read_required',
+          instruction: 'No first-page form is retained for this exact manifest. Read the supplied first page; never derive a cursor, reference or new binding. ' + next.instruction } : next;
+      }
+      return base('requires_source', 'No authoring form is available for this exact manifest. Obtain its canonical first page; do not reuse another target, revision or manifest.', source + '.report');
+    }
+    const supplied = [...(result.next_calls ?? []), ...(result.continuation?.next_calls ?? []),
+      ...(report?.next_calls ?? []), ...(result.navigation?.next_calls ?? []), ...(result.family_result?.next_calls ?? [])];
+    if (supplied.length) return selectForms(supplied, source + '.next_calls');
+    const resume = [...(result.resume_call ? [result.resume_call] : []),
+      ...(result.continuation?.resume_call ? [result.continuation.resume_call] : [])];
+    if (resume.length) return selectForms(resume, source + '.resume_call');
+    if ([result, result.continuation, report].filter(object).some(owner => owner.recovery_only?.unavailable_calls?.length))
+      return base('requires_source', 'No normal call could be registered. The exact original requests are retained only in recovery_only; follow original-operation recovery without creating new identities.', source);
+    return base('idle', 'No unique next action was supplied. Follow the canonical current-state instruction; no tool call is inferred.', source);
+  }
+  return Object.freeze({
+    project(domain) {
+      const result = clone(domain);
+      // An adapter may already have loaded one safe page after this result.
+      // Retain the exact outer first-page form before selecting that nested
+      // context; incomplete nested pages still select only their supplied read.
+      rememberAuthoring(result);
+      if (result.terminal === true) result.next_action = terminal(result, 'outer');
+      else if (result.next_read) {
+        const read = result.next_read, nested = read.result;
+        // An explicit null means the exact read could not be retained. Its Raw
+        // execution record remains evidence/recovery, never a normal fallback.
+        const retry = Object.hasOwn(read, 'call') ? read.call : read;
+        if (read.failure?.phase === 'validation') result.next_action = base('requires_source',
+          'The supplied read could not be validated. Preserve the original outcome and receipt; obtain the canonical read source without repeating the write.', 'next_read');
+        else if (nested?.terminal === true) result.next_action = terminal(nested, 'next_read.result');
+        else if (!read.error && read.failed !== true && nested?.outcome === 'inspect_result' && nested.report?.available !== false)
+          result.next_action = fromContext(nested, 'next_read.result');
+        else if (callValue(retry)?.tool === 'agdf_inspect') {
+          const next = selectForms([retry], 'next_read', { readOnly: true });
+          result.next_action = next.state === 'ready' ? { ...next, state: 'read_required',
+            instruction: 'The follow-up read did not produce an available nonterminal result. Retry only this exact read when appropriate; never repeat the outer write. ' + next.instruction } : next;
+        } else result.next_action = base('requires_source', 'The follow-up read failed without an exact supplied read call. Preserve the outer outcome/receipt; do not retry the outer write.', 'next_read');
+      } else result.next_action = fromContext(result, 'outer');
+      result.next_action.context_path = result.next_read?.result ? 'next_read.result' : 'outer';
+      if (result.next_read?.result?.report) result.next_action.instruction +=
+        ' The already loaded source report is response.structuredContent.next_read.result.report. Consume that report without another inspect call.';
+      return result;
+    },
+    close() { forms.clear(); superseded.clear(); },
+  });
+}