create-agdf 0.30.0 → 0.31.0

package/lib/mcp-dispatch-runtime.js

@@ -7,11 +7,30 @@ import { createPresentationDelivery } from '#agdf-core/control-state/presentatio
 import { mcpControlContinuation } from '#agdf-core/skill-dispatch/mcp-continuation.js';
 import { inspectRunInputResolution } from '#agdf-core/control-state/run-input-resolution.js';
 import { assertMcpControlReadBoundary } from "#agdf-core/control-read-boundary.js";
+import { knownExecutionCode, validExecutionFacts } from '#agdf-core/mcp-tool-errors.js';
+import { createCompanionJournal } from '#agdf-core/companion/journal.js';
 import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
 import { composeMcpProtocolRuntime, errorSupport, inspectMcpDispatcherRuntime, configuredMcpCommandGroups } from './mcp-protocol-runtime.js';
 export { inspectMcpDispatcherRuntime, configuredMcpCommandGroups, CONTROL_INSPECT_FUNCTION_DEFINITION, SKILL_DISPATCH_FUNCTION_DEFINITION,
   parseControlInspectFunctionArguments, parseSkillDispatchFunctionArguments, serializeSkillDispatchResult, DECISION_UI_URI, OWNED_LOCK_CHANNEL, releaseAbandonedOwnedLock } from './mcp-protocol-runtime.js';
+// Core reasons that the tool-error contract names differently. Core's command service maps
+// RECOVERY_REQUIRED the same way and rejects the others under these existing codes.
+const PREPARATION_REASONS = Object.freeze([
+  [/RECOVERY_REQUIRED/iu, 'recovery_required'],
+  [/^AGDF_PLANNED_SOURCE_STALE$/u, 'planning_source_stale'],
+  [/^(?:run_state_invalid|run_id_invalid)$/u, 'invalid_run'],
+  [/^AGDF_CONTROL_LAYOUT_MIGRATION_REQUIRED$/u, 'control_layout_unsupported'],
+]);
+// Dispatch preparation only reads the input context and grants staged material; no command has
+// been dispatched yet. Its failures therefore carry typed not_dispatched facts, so the facade and
+// generation call sites report a rejected command with its classified reason, never an unknown effect.
+export function preDispatchFailure(error) {
+  if (validExecutionFacts(error?.facts)) return Object.assign(error, { facts: { ...error.facts, dispatch: 'not_dispatched' } });
+  const reason = String(error?.message ?? '');
+  const code = knownExecutionCode(PREPARATION_REASONS.find(([pattern]) => pattern.test(reason))?.[1] ?? reason);
+  return Object.assign(new Error(code), { facts: { code, dispatch: 'not_dispatched' } });
+}
 export async function createMcpCockpitRuntime({ surface, cockpitDir, cockpitMode, inspected = inspectMcpDispatcherRuntime() } = {}) {
   const pluginMode = cockpitMode === 'plugin';
   if (cockpitMode !== undefined && !pluginMode || pluginMode && (surface !== 'codex' || cockpitDir !== undefined)
@@ -66,6 +85,9 @@ export function createMcpDispatchRuntime({ surface, inspected = inspectMcpDispat
     commandGroups, runtimeControl, materialGrants, gitObservation: cliGitObservation,
     observeDoctor: (root, input, signal) => diagnostic.observe(root, input, signal),
   } });
+  // Companion events (companion core SDD-006): the executing process journals each final command result
+  // once, below the data root the launcher hands over; review facts read the sealed material here.
+  const journal = createCompanionJournal({ sealedFiles: transferId => services.material.sealedFiles(transferId) });
   const execute = input => mcpControlContinuation(input, services.dispatch(input), commandGroups);
   const executeInspect = services.inspect;
   const protocol = composeMcpProtocolRuntime({ surface, inspected, commandGroups, execute, executeInspect, inputContext, executionContext,
@@ -76,25 +98,28 @@ export function createMcpDispatchRuntime({ surface, inspected = inspectMcpDispat
       : input.command.kind === 'presentation.deliver' ? delivery.deliver(input, host) : services.command(group, input) });
   return Object.freeze({ ...protocol,
     verifyProducer,
-    prepareDispatch(name, input) { return { inputContext: protocol.inputContextFor(input), materialGrants: ['agdf_record', 'agdf_revise', 'agdf_closeout'].includes(name) ? services.material.grants(input) : [] }; },
+    prepareDispatch(name, input) {
+      try {
+        return { inputContext: protocol.inputContextFor(input), materialGrants: ['agdf_record', 'agdf_revise', 'agdf_closeout'].includes(name) ? services.material.grants(input) : [] };
+      } catch (error) { throw preDispatchFailure(error); }
+    },
     readBudget,
     delivery,
+    observeOutcome: (name, input, result) => journal.observe(name, input, result),
     async postprocessToolResult(name, input, result) {
       const configuration = protocol.configurationProjection(input);
       if (configuration && name === 'agdf_inspect' && result.report) result = { ...result, report: { ...result.report, effective_configuration: configuration } };
       if (['agdf_record', 'agdf_revise', 'agdf_closeout'].includes(name)) services.material.settle(input, result);
       if (name !== 'agdf_prepare' || input.command?.kind !== 'presentation.prepare' || !result.family_result?.text) return result;
       delivery.remember(input, result);
-      const prepared = result.family_result, { operation_id, ...binding } = input;
+      const prepared = result.family_result;
       return { ...result, presentation_delivery: { mode: 'prepared', text: '', presentation_id: prepared.presentation_id,
         document_digest: prepared.document_digest, authorizes: false,
         ...(prepared.preview_review ? { preview_review: { operation: 'presentation-preview', version: prepared.preview_review.descriptor.version,
           content_digest: prepared.preview_review.rendered_digest, access_state: 'not_observed', target_id: input.target_id,
           run_id: input.run_id, gate: 'PRD', expected_revision_id: input.expected_revision_id, presentation_id: prepared.presentation_id } } : {}),
-        instruction: 'Prepared, not delivered. Optionally open agdf_decision_view as a non-primary preview. Then presentation.deliver selects once. Default route markdown; no second summary.',
-        next_calls: [{ tool: 'agdf_prepare', arguments: { ...binding, command: { kind: 'presentation.deliver',
-          payload: { gate: input.command.payload.gate, presentation_id: prepared.presentation_id, route: 'markdown' } } },
-          required_input: { operation_id: 'Generate a new UUID for delivery; no gate approval is required.' } }] } };
+        instruction: 'Prepared, not delivered. Optionally open agdf_decision_view as a non-primary preview. Follow the authoritative top-level next action for presentation.deliver; its original UUID and binding are already supplied. No second summary and no generated delivery UUID.',
+        next_action_source: 'next_calls' } };
     },
     async close() { services.material.close(); delivery.close(); await diagnostic.close(); },
     inspectOwnership() { const d = diagnostic.inspectOwnership(); return { diagnostic: d, read_workers: readBudget.inspect(),
@@ -116,6 +141,7 @@ export async function createMcpDecisionRuntime({ runtime, ui, appOnlyMediationQu
     open: (input, result, host) => session.open(input, result, host), read: (input, signal, host) => session.read(input, signal, host),
     action: (input, host) => session.action(input, host), close: () => session.close() });
   return Object.freeze({ ...protocol,
+    observeOutcome: (name, input, result) => runtime.observeOutcome?.(name, input, result) ?? false,
     async postprocessToolResult(name, input, result, { uiSupported, client } = {}) {
       if (name === 'agdf_inspect' && input.operation === 'native-qualification' && result.report?.available) {
         return { ...result, report: { ...result.report, ui_rendering_support: uiSupported ? 'supported' : 'unsupported',

package/lib/mcp-lifecycle/package.js

@@ -27,6 +27,7 @@ import {
 import { defaultNpmInstallRoot, npmInvocation } from "../npm-invocation.js";
 import { renameSyncWithRetry } from "#agdf-core/fs-swap.js";
 import { fsyncDirectory, withOwnedFileLock } from '#agdf-core/owned-file-lock.js';
+import { createPreparedCallJournal } from './prepared-call-journal.js';
 
 const CLAIMS = '.agdf-executable-claims';
 
@@ -440,6 +441,12 @@ export function createMcpGenerationPublisher(base, { publicationDeadline = Infin
   if (canonical !== base.publisher_root || !base.immutable) throw Error('runtime_publication_unowned');
   return Object.freeze({
     initial: base,
+    // Only a freshly owned publisher supplies persistent transport storage.
+    // This is lazy: constructing/discovering the SDK creates no journal files.
+    preparedCallStore({ surface }) {
+      return createPreparedCallJournal({ publisherRoot: canonical, identity: { surface, version: base.version,
+        server_digest: base.digest, dispatcher_digest: base.dispatcherDigest, sdk_digest: base.sdkDigest } });
+    },
     resolve(candidate) {
       const keys = ['schema_version', 'publication_id', 'version', 'server_digest', 'dispatcher_digest', 'sdk_digest'];
       if (!candidate || Object.keys(candidate).sort().join() !== keys.sort().join()

package/lib/mcp-lifecycle/plugin-runtime.js

@@ -1,10 +1,11 @@
 import { execFileSync, spawn, fork } from "node:child_process";
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync, rmdirSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync, rmdirSync, unlinkSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import process from "node:process";
 import { createHash, randomUUID } from 'node:crypto';
 import { digestDirectory, digestPluginMcpDispatcherSource, mcpDispatcherRuntimeEntries, mcpDispatcherPackageExports } from "#agdf-core/runtime/plugin-provenance.js";
 import { acquireMcpExecutableClaim, inspectMcpServerPackage, mcpPackageConstants, mcpRuntimeRetirementState, prepareMcpServerPackage, createMcpRuntimeRetirementTransaction } from "./package.js";
+import { inspectPreparedCallJournals, retirePreparedCallJournals } from './prepared-call-journal.js';
 
 // Plugin-local AGDF MCP runtime shared by the hosts whose runtime plugin declares the server itself:
 // Claude Code passes ${CLAUDE_PLUGIN_DATA}, which it deletes on uninstall; Codex receives an absolute
@@ -15,6 +16,12 @@ const SDK_PACKAGE_SPEC = "@modelcontextprotocol/server@2.0.0";
 // the shipped digest; the override deliberately restores the unverified install and is recorded.
 export const SDK_BUNDLE = Object.freeze({ manifest: "package.json", lock: "package-lock.json", expected: "expected-sdk.json" });
 export const SDK_OVERRIDE_ENV = "AGDF_MCP_ALLOW_UNVERIFIED_SDK";
+// The journal's data-root variable (COMPANION_DATA_ROOT_ENV of core companion/journal.js), kept as a
+// literal so the launcher stays free of the journal module; the journal test asserts both agree.
+export const COMPANION_DATA_ROOT_ENV = "AGDF_COMPANION_DATA_ROOT";
+// The journal's directory and its two files below the data root (JOURNAL_DIRECTORY, JOURNAL_FILE and
+// JOURNAL_ROTATED_FILE of core companion/journal.js), owned and removed with the runtime (SD SDD-006).
+export const COMPANION_JOURNAL = Object.freeze({ directory: "companion", files: Object.freeze(["events.jsonl", "events.1.jsonl"]) });
 export const SDK_VERIFICATION = Object.freeze({ verified: "verified", override: "unverified_override" });
 
 function readJson(path) {
@@ -249,6 +256,10 @@ export async function launchPluginMcpServer({
     return null;
   }
   const { surface, dataRoot, cockpitDir, cockpitMode, prepareOnly } = invocation;
+  // Companion events (companion core SDD-006): the facade and its generations journal final tool
+  // results below the data root this launcher received; the variable reaches them with the facade's
+  // environment only. Preparation keeps the launcher's own environment.
+  const facadeEnv = typeof dataRoot === 'string' && dataRoot ? { ...env, [COMPANION_DATA_ROOT_ENV]: resolve(dataRoot) } : env;
   const publicationDeadline = performance.now() + CONCURRENT_PUBLICATION_WAIT_MS;
   let runtime, waitingOwner;
   try {
@@ -256,7 +267,7 @@ export async function launchPluginMcpServer({
     // preparation. It cannot claim or start a facade until the private message
     // carries the successfully verified publication.
     if (!prepareOnly && !startFacade && acquireClaim === acquireMcpExecutableClaim && ensure === ensurePluginMcpRuntime)
-      waitingOwner = startFacadeOwner({ surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline });
+      waitingOwner = startFacadeOwner({ surface, cockpitDir, cockpitMode, pluginRoot, env: facadeEnv, publicationDeadline });
     // Reject a damaged installed dispatcher before publication, claim acquisition
     // or SDK execution. Its downstream resource context cannot qualify a facade;
     // starting one first would correctly retain its unconfirmed executable use.
@@ -285,7 +296,7 @@ export async function launchPluginMcpServer({
   // executable before fork and releases only after orderly teardown AND exit.
   if (!startFacade && acquireClaim === acquireMcpExecutableClaim) {
     try {
-      const owner = waitingOwner ?? startFacadeOwner({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline });
+      const owner = waitingOwner ?? startFacadeOwner({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env: facadeEnv, publicationDeadline });
       waitingOwner?.activate(runtime);
       return await owner.settled;
     }
@@ -299,7 +310,7 @@ export async function launchPluginMcpServer({
       ? error.message : 'AGDF_MCP_EXECUTABLE_CLAIM_INVALID';
     stderr.write(`${launcherFailureLine(code)}\n`); process.exitCode = 1; return null;
   }
-  try { return await (startFacade ?? supervisePluginMcpFacade)({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline, claim }); }
+  try { return await (startFacade ?? supervisePluginMcpFacade)({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env: facadeEnv, publicationDeadline, claim }); }
   catch (error) {
     const code = Object.hasOwn(LAUNCHER_FAILURES, error?.message) ? error.message : 'AGDF_MCP_PLUGIN_RUNTIME_FAILED';
     stderr.write(`${launcherFailureLine(code, 'facade')}\n`); process.exitCode = 1; return null;
@@ -376,12 +387,18 @@ export const claudePluginMcpConstants = Object.freeze({ sdkPackageSpec: SDK_PACK
 
 // Codex keeps the plugin-local MCP runtime in an AGDF-owned data root because it passes no plugin data
 // directory; `codex plugin remove` cannot delete it. `dataRoot` is the launcher data root (--data);
-// uninstall removes it only when it holds nothing but owned runtimes and abandoned stages under mcp/.
+// uninstall removes it only when it holds nothing but owned runtimes and abandoned stages under mcp/
+// and the companion journal (a plain directory holding only its own regular files).
+function ownedCompanionJournal(dataRoot) {
+  const directory = join(dataRoot, COMPANION_JOURNAL.directory), stats = lstatSync(directory);
+  if (!stats.isDirectory() || stats.isSymbolicLink()) return false;
+  return readdirSync(directory).every(name => COMPANION_JOURNAL.files.includes(name) && lstatSync(join(directory, name)).isFile());
+}
 export function inspectPluginMcpDataRoot(dataRoot) {
   if (!existsSync(dataRoot)) return "absent";
   try {
     if (!lstatSync(dataRoot).isDirectory() || lstatSync(dataRoot).isSymbolicLink()) return "foreign";
-    if (readdirSync(dataRoot).some((name) => name !== "mcp")) return "foreign";
+    if (readdirSync(dataRoot).some((name) => name !== "mcp" && !(name === COMPANION_JOURNAL.directory && ownedCompanionJournal(dataRoot)))) return "foreign";
     const mcpDataRoot = join(realpathSync(dataRoot), "mcp");
     if (!existsSync(mcpDataRoot)) return "owned";
     if (!lstatSync(mcpDataRoot).isDirectory() || lstatSync(mcpDataRoot).isSymbolicLink()) return "foreign";
@@ -390,6 +407,10 @@ export function inspectPluginMcpDataRoot(dataRoot) {
       const path = join(mcpDataRoot, name);
       const stats = lstatSync(path);
       if (!stats.isDirectory() || stats.isSymbolicLink()) return "foreign";
+      if (name === 'prepared-calls') {
+        if (inspectPreparedCallJournals(mcpDataRoot) !== 'owned') return 'foreign';
+        continue;
+      }
       if (name !== 'generations') {
         if (!ownedRoot(path) && !name.startsWith('.stage-')) return 'foreign';
         protectedFiles = true; continue;
@@ -430,7 +451,14 @@ export function retirePluginMcpDataRoot(dataRoot, revalidate = () => {}) {
       rmdirSync(publication);
     }
     if (existsSync(generations)) rmdirSync(generations);
+    retirePreparedCallJournals(mcp);
     if (existsSync(mcp)) rmdirSync(mcp);
+    const journal = join(dataRoot, COMPANION_JOURNAL.directory);
+    if (existsSync(journal)) {
+      revalidate();
+      for (const name of COMPANION_JOURNAL.files) if (existsSync(join(journal, name))) unlinkSync(join(journal, name));
+      rmdirSync(journal);
+    }
     revalidate(); rmdirSync(dataRoot);
     return true;
   } catch (error) {

package/lib/mcp-lifecycle/prepared-call-journal.js

@@ -0,0 +1,269 @@
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmdirSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { atomicWrite, fsyncDirectory, withOwnedFileLock } from '#agdf-core/owned-file-lock.js';
+import { renameSyncWithRetry } from '#agdf-core/fs-swap.js';
+
+const OWNER = 'agdf-prepared-calls-v1', DIRECTORY = 'prepared-calls';
+const MARKER = 'owner.json', KEY = 'key', RECORD = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\.json$/u;
+// Each live connection still has its original 256-entry Map. The shared
+// journal accommodates four such producers without silently evicting live IDs.
+const DIGEST = /^[0-9a-f]{64}$/u, LIMIT = 65_536, LIFETIME = 30 * 60_000, CAPACITY = 1024;
+const MAX_NAMESPACES = 16, MAX_BYTES = 64 * 1024 * 1024;
+const bad = () => { throw Error('runtime_provenance_invalid'); };
+const sha = text => createHash('sha256').update(text).digest('hex');
+const json = value => JSON.stringify(value);
+function privatePath(path, directory = false) {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1)
+      || realpathSync(path) !== resolve(path)
+      || process.getuid && stat.uid !== process.getuid()
+      || process.platform !== 'win32' && (stat.mode & 0o077)) bad();
+  return stat;
+}
+function boundedRead(path, limit) {
+  if (privatePath(path).size > limit) bad();
+  return readFileSync(path);
+}
+function identityOf(identity) {
+  if (!identity || Object.keys(identity).sort().join() !== 'dispatcher_digest,sdk_digest,server_digest,surface,version'
+      || !['codex', 'claude', 'copilot', 'opencode'].includes(identity.surface)
+      || typeof identity.version !== 'string' || !identity.version || identity.version.length > 128
+      || !['server_digest', 'dispatcher_digest', 'sdk_digest'].every(key => DIGEST.test(identity[key] ?? ''))) bad();
+  return { surface: identity.surface, version: identity.version, server_digest: identity.server_digest,
+    dispatcher_digest: identity.dispatcher_digest, sdk_digest: identity.sdk_digest };
+}
+function assertOwner(root) {
+  privatePath(root, true);
+  if (boundedRead(join(root, MARKER), 256).toString() !== json({ schema_version: 1, owner: OWNER })) bad();
+}
+function readNamespace(root, namespace) {
+  const dir = join(root, namespace); privatePath(dir, true);
+  const identity = JSON.parse(boundedRead(join(dir, MARKER), 2048));
+  if (identity.schema_version !== 1 || identity.owner !== OWNER || Object.keys(identity).sort().join() !== 'created,identity,owner,schema_version'
+      || !Number.isSafeInteger(identity.created) || identity.created < 0
+      || sha(json(identityOf(identity.identity))) !== namespace) bad();
+  const key = boundedRead(join(dir, KEY), 32); if (key.length !== 32) bad();
+  return { dir, key, created: identity.created };
+}
+const signature = (key, row) => createHmac('sha256', key).update(json(row)).digest('hex');
+function readEntry(dir, name, key, namespace) {
+  if (!RECORD.test(name)) bad();
+  const record = JSON.parse(boundedRead(join(dir, name), 2 * LIMIT + 4096));
+  const { mac, ...row } = record;
+  if (!DIGEST.test(mac ?? '') || !timingSafeEqual(Buffer.from(mac, 'hex'), Buffer.from(signature(key, row), 'hex'))
+      || row.schema_version !== 1 || row.namespace !== namespace || name !== row.id + '.json'
+      || !Number.isSafeInteger(row.created) || row.created < 0 || !['available', 'expired'].includes(row.state)) bad();
+  const fields = row.state === 'available' ? 'created,id,namespace,schema_version,signature,state,value'
+    : 'created,id,namespace,schema_version,state';
+  if (Object.keys(row).sort().join() !== fields) bad();
+  if (row.state === 'available' && (typeof row.value !== 'string' || Buffer.byteLength(row.value) > LIMIT
+      || !DIGEST.test(row.signature ?? '') || sha(row.value) !== row.signature)) bad();
+  return row;
+}
+function inspectRoot(publisherRoot) {
+  assertPublisherRoot(publisherRoot);
+  const root = join(publisherRoot, DIRECTORY);
+  if (!existsSync(root)) return 'absent';
+  assertOwner(root);
+  const namespaces = readdirSync(root).filter(name => name !== MARKER);
+  if (namespaces.length > MAX_NAMESPACES) bad();
+  let bytes = privatePath(join(root, MARKER)).size;
+  for (const namespace of namespaces) {
+    if (namespace === MARKER) continue;
+    if (!DIGEST.test(namespace)) bad();
+    const { dir, key } = readNamespace(root, namespace);
+    const names = readdirSync(dir);
+    if (names.length > 2 * CAPACITY + 2) bad();
+    let active = 0, expired = 0;
+    for (const name of names) {
+      bytes += privatePath(join(dir, name)).size;
+      if ([MARKER, KEY].includes(name)) continue;
+      const row = readEntry(dir, name, key, namespace);
+      row.state === 'available' ? active++ : expired++;
+    }
+    if (active > CAPACITY || expired > CAPACITY) bad();
+  }
+  if (bytes > MAX_BYTES) bad();
+  return 'owned';
+}
+export function inspectPreparedCallJournals(publisherRoot) {
+  try { return inspectRoot(publisherRoot); } catch { return 'foreign'; }
+}
+
+function locked(publisherRoot, operation) {
+  assertPublisherRoot(publisherRoot);
+  const deadline = performance.now() + 5550;
+  for (;;) {
+    try { return withOwnedFileLock(join(publisherRoot, '.agdf-prepared-calls'), () => { assertPublisherRoot(publisherRoot); return operation(); }); }
+    catch (error) {
+      if (error?.message !== 'AGDF_RUN_WRITE_LOCKED') throw error;
+      if (error.lock_owner_status !== 'live') bad();
+      if (performance.now() >= deadline) throw Error('dispatch_busy');
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+}
+function assertPublisherRoot(root) {
+  const stat = lstatSync(root);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || realpathSync(root) !== root
+      || process.getuid && stat.uid !== process.getuid()) bad();
+}
+function normalizedError(error) {
+  if (['runtime_provenance_invalid', 'dispatch_busy'].includes(error?.message)) return error;
+  return Error('prepared_call_store_unavailable');
+}
+
+// The publisher supplies the root and immutable producer identity. No tool
+// argument can select this storage; constructing/discovering a server writes nothing.
+export function createPreparedCallJournal({ publisherRoot, identity, now = Date.now,
+  lifetimeMs = LIFETIME, maxEntries = CAPACITY, maxBytes = MAX_BYTES, checkpoint = () => {} } = {}) {
+  const canonical = realpathSync(publisherRoot);
+  if (canonical !== publisherRoot || lstatSync(canonical).isSymbolicLink()
+      || !Number.isSafeInteger(lifetimeMs) || lifetimeMs <= 0 || lifetimeMs > LIFETIME
+      || !Number.isSafeInteger(maxEntries) || maxEntries <= 0 || maxEntries > CAPACITY
+      || !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > MAX_BYTES) bad();
+  assertPublisherRoot(canonical);
+  identity = identityOf(identity);
+  const namespace = sha(json(identity)), root = join(canonical, DIRECTORY), dir = join(root, namespace);
+  const publish = (row, key) => atomicWrite(join(dir, row.id + '.json'), json({ ...row, mac: signature(key, row) }));
+  function publishDirectory(target, contents, point) {
+    const stage = join(canonical, '.agdf-prepared-stage-' + randomUUID());
+    mkdirSync(stage, { mode: 0o700 }); const owned = lstatSync(stage);
+    try {
+      for (const [name, value] of Object.entries(contents)) atomicWrite(join(stage, name), value);
+      checkpoint(point);
+      if (existsSync(target)) bad();
+      renameSyncWithRetry(stage, target); fsyncDirectory(dirname(target));
+    } finally {
+      if (existsSync(stage)) {
+        const current = lstatSync(stage);
+        // A hard-killed unconfirmed sibling stage is retained by lifecycle
+        // inspection. Ordinary rollback removes only our same, unchanged inode
+        // and the exact initialization bytes authored by this invocation.
+        if (!current.isSymbolicLink() && current.dev === owned.dev && current.ino === owned.ino) {
+          for (const [name, value] of Object.entries(contents)) {
+            const file = join(stage, name);
+            if (existsSync(file) && boundedRead(file, 4096).equals(Buffer.from(value))) unlinkSync(file);
+          }
+          if (!readdirSync(stage).length) rmdirSync(stage);
+        }
+      }
+    }
+  }
+  function removeNamespace(target) {
+    for (const name of readdirSync(target)) unlinkSync(join(target, name));
+    rmdirSync(target);
+  }
+  function pruneNamespaces(time) {
+    if (inspectRoot(canonical) !== 'owned') bad();
+    for (const name of readdirSync(root).filter(name => name !== MARKER)) {
+      const scope = readNamespace(root, name), rows = readdirSync(scope.dir).filter(file => ![MARKER, KEY].includes(file))
+        .map(file => readEntry(scope.dir, file, scope.key, name));
+      // Keep one further lifetime of signed tombstones. Never delete a live
+      // call from another candidate merely to make room for the current one.
+      const latest = Math.max(scope.created, ...rows.map(row => row.created));
+      if (name !== namespace && time - latest >= 2 * LIFETIME) removeNamespace(scope.dir);
+    }
+  }
+  function size() {
+    return privatePath(join(root, MARKER)).size + readdirSync(root).filter(name => name !== MARKER).reduce((total, name) => {
+      const target = join(root, name);
+      return total + readdirSync(target).reduce((bytes, file) => bytes + privatePath(join(target, file)).size, 0);
+    }, 0);
+  }
+  function open(create = false, reserveBytes = 0) {
+    if (!existsSync(root)) {
+      if (!create) return null;
+      publishDirectory(root, { [MARKER]: json({ schema_version: 1, owner: OWNER }) }, 'root_staged');
+    }
+    assertOwner(root);
+    if (!existsSync(dir)) {
+      if (!create) return null;
+      // Verifying and pruning every namespace is costly; it runs only when a new
+      // namespace competes for the shared budget, not on every registration.
+      pruneNamespaces(now());
+      const marker = json({ schema_version: 1, owner: OWNER, identity, created: now() });
+      if (readdirSync(root).length - 1 >= MAX_NAMESPACES || size() + Buffer.byteLength(marker) + 32 + reserveBytes > maxBytes) return null;
+      publishDirectory(dir, { [MARKER]: marker, [KEY]: randomBytes(32) }, 'namespace_staged');
+    }
+    return readNamespace(root, namespace);
+  }
+  function entries(key) {
+    const names = readdirSync(dir).filter(name => ![MARKER, KEY].includes(name));
+    if (names.length > 2 * CAPACITY) bad();
+    return names.map(name => readEntry(dir, name, key, namespace));
+  }
+  function expire(rows, key, time) {
+    for (let index = 0; index < rows.length; index++) if (rows[index].state === 'available' && time - rows[index].created >= lifetimeMs) {
+      const old = rows[index], row = { schema_version: 1, namespace, id: old.id, created: old.created, state: 'expired' };
+      publish(row, key); rows[index] = row;
+    }
+    const expired = rows.filter(row => row.state === 'expired').sort((a, b) => b.created - a.created || a.id.localeCompare(b.id));
+    for (const row of expired.slice(maxEntries)) { unlinkSync(join(dir, row.id + '.json')); rows.splice(rows.indexOf(row), 1); }
+  }
+  function run(create, operation, reserveBytes = 0) {
+    try {
+      // Absent reads do not create lock/marker directories during discovery.
+      if (!create && !existsSync(root)) return { state: 'reference_unknown' };
+      return locked(canonical, () => { const opened = open(create, reserveBytes); return opened ? operation(opened.key) : create ? null : { state: 'reference_unknown' }; });
+    } catch (error) { throw normalizedError(error); }
+  }
+  return Object.freeze({
+    register({ value, signature: digest, created }) {
+      if (typeof value !== 'string' || Buffer.byteLength(value) > LIMIT || digest !== sha(value)
+          || !Number.isSafeInteger(created) || created < 0) bad();
+      const estimate = Buffer.byteLength(json({ schema_version: 1, namespace, id: '00000000-0000-4000-8000-000000000000', created,
+        state: 'available', signature: digest, value, mac: '0'.repeat(64) }));
+      return run(true, key => {
+        const rows = entries(key), time = now(); expire(rows, key, time);
+        const previous = rows.find(row => row.state === 'available' && row.signature === digest && row.value === value);
+        if (previous) return { id: previous.id, created: previous.created };
+        if (rows.filter(row => row.state === 'available').length >= maxEntries) return null;
+        // Stale candidate namespaces are reclaimed only when the shared byte budget is reached.
+        if (size() + estimate > maxBytes) pruneNamespaces(time);
+        if (size() + estimate > maxBytes) return null;
+        const row = { schema_version: 1, namespace, id: randomUUID(), created, state: 'available', signature: digest, value };
+        publish(row, key); return { id: row.id, created: row.created };
+      }, estimate);
+    },
+    load(id) {
+      if (!RECORD.test(id + '.json')) return { state: 'reference_unknown' };
+      return run(false, key => {
+        const file = join(dir, id + '.json');
+        if (!existsSync(file)) return { state: 'reference_unknown' };
+        let row = readEntry(dir, id + '.json', key, namespace);
+        if (row.state === 'available' && now() - row.created >= lifetimeMs) {
+          const rows = entries(key); expire(rows, key, now()); row = rows.find(value => value.id === id);
+        }
+        return row?.state === 'available' ? { state: 'available', value: row.value, signature: row.signature, created: row.created }
+          : { state: 'reference_expired' };
+      });
+    },
+  });
+}
+
+// Called only after the plugin owner has retired its executable generations.
+// Never adopts unknown records or follows a foreign/symlink entry for cleanup.
+export function retirePreparedCallJournals(publisherRoot) {
+  const root = join(publisherRoot, DIRECTORY);
+  if (!existsSync(root)) return;
+  locked(publisherRoot, () => {
+    // The lifecycle owner removed generations before acquiring this lock. A
+    // concurrent preparer can recreate it in that gap; retain every reference
+    // if any new generation node is present, even before it is fully published.
+    let generations;
+    try { generations = lstatSync(join(publisherRoot, 'generations')); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (generations) throw Error('AGDF_MCP_RUNTIME_RETAINED');
+    if (inspectRoot(publisherRoot) !== 'owned') bad();
+    for (const namespace of readdirSync(root).filter(name => name !== MARKER)) {
+      const dir = join(root, namespace);
+      for (const name of readdirSync(dir)) unlinkSync(join(dir, name));
+      rmdirSync(dir);
+    }
+    // The owner marker goes last: an interrupted cleanup still leaves a
+    // verifiable owned root instead of unmarked namespaces.
+    unlinkSync(join(root, MARKER)); rmdirSync(root);
+  });
+}