@sublang/playbook 3.0.0 → 4.0.0

package/reference/sdlc/code.playbook/bin/provision.js

@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// PBCLI-36/37 (DR-024): probe-first engine provisioning for filesystem
+// registry modules. A compiled thin artifact imports `xstate` and
+// `@sublang/playbook/xstate-runtime`, which Node resolves by walking up
+// from the artifact's own directory; a globally installed host therefore
+// fails at artifact load in a bare directory. Before importing such a
+// module, `playbook run` probes both specifiers with the module's path as
+// resolution parent and, only when a probe fails, symlinks the running
+// host's own installed package roots beside the module. It never shells
+// out to `npm link` and never installs from the registry.
+
+import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs';
+import { mkdir, symlink, unlink } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// PBCLI-37: probe specifier → the package name provisioning may link.
+const ENGINE_LINKS = new Map([
+  ['xstate', 'xstate'],
+  ['@sublang/playbook/xstate-runtime', '@sublang/playbook'],
+]);
+
+const DEPENDENCY_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'peerDependencies',
+  'optionalDependencies',
+];
+
+// PBCLI-37: package names whose probes fail with the module as resolution
+// parent. `createRequire` follows the same walk-up Node uses for the
+// module's own imports, so an empty result means a project-local (or
+// already provisioned) engine wins and provisioning must touch nothing.
+function missingEngineLinks(modulePath) {
+  const req = createRequire(modulePath);
+  const missing = [];
+  for (const [specifier, name] of ENGINE_LINKS) {
+    try {
+      req.resolve(specifier);
+    } catch {
+      missing.push(name);
+    }
+  }
+  return missing;
+}
+
+// PBCLI-36: a manifest at or above the module declaring @sublang/playbook
+// means a project chose a dependency and its install is broken or absent;
+// shadow-provisioning would mask the real fix.
+function declaringManifest(startDir) {
+  for (let dir = startDir; ; ) {
+    const manifestPath = join(dir, 'package.json');
+    if (existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        for (const field of DEPENDENCY_FIELDS) {
+          const block = manifest?.[field];
+          if (
+            block !== null &&
+            typeof block === 'object' &&
+            Object.prototype.hasOwnProperty.call(block, '@sublang/playbook')
+          ) {
+            return manifestPath;
+          }
+        }
+      } catch {
+        // An unreadable manifest cannot declare the dependency.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+function packageRootUpward(startDir, name) {
+  for (let dir = startDir; ; ) {
+    const manifestPath = join(dir, 'package.json');
+    if (existsSync(manifestPath)) {
+      try {
+        if (JSON.parse(readFileSync(manifestPath, 'utf8')).name === name) {
+          return dir;
+        }
+      } catch {
+        // Keep walking past an unreadable manifest.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+// PBCLI-37: the running host's own installed package roots, resolved from
+// the host's module scope — this file lives inside @sublang/playbook, and
+// xstate resolves from that root's own dependency tree.
+function defaultHostRoots() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const playbookRoot = packageRootUpward(here, '@sublang/playbook');
+  if (playbookRoot === undefined) {
+    throw new Error(
+      'cannot locate the running @sublang/playbook package root for provisioning',
+    );
+  }
+  const req = createRequire(join(playbookRoot, 'package.json'));
+  let xstateRoot;
+  try {
+    xstateRoot = packageRootUpward(dirname(req.resolve('xstate')), 'xstate');
+  } catch {
+    xstateRoot = undefined;
+  }
+  if (xstateRoot === undefined) {
+    throw new Error(
+      "cannot locate the running host's own xstate package for provisioning",
+    );
+  }
+  return { xstate: xstateRoot, '@sublang/playbook': playbookRoot };
+}
+
+// 'absent' | 'dangling' | 'live' (a symlink with an existing target) |
+// 'occupied' (a real file or directory, never removed).
+function linkState(linkPath) {
+  let stat;
+  try {
+    stat = lstatSync(linkPath);
+  } catch {
+    return 'absent';
+  }
+  if (!stat.isSymbolicLink()) return 'occupied';
+  return existsSync(linkPath) ? 'live' : 'dangling';
+}
+
+// PBCLI-36/37: probe, then provision the missing engine links beside a
+// filesystem registry module. Returns {} when the run may proceed (either
+// nothing was needed or links were created and logged) or { code: 1 }
+// after writing one `playbook run: <message>` diagnostic to stderr.
+export async function provisionEngine({
+  modulePath,
+  stderr,
+  enabled = true,
+  hostRoots,
+}) {
+  const missing = missingEngineLinks(modulePath);
+  if (missing.length === 0) return {};
+
+  const moduleDir = dirname(modulePath);
+  if (!enabled) {
+    // PBCLI-36: --no-provision still owes the dangling-link diagnostic —
+    // a stale link we (or a prior host) created must not surface as a raw
+    // module-not-found error.
+    for (const name of missing) {
+      const linkPath = join(moduleDir, 'node_modules', name);
+      if (linkState(linkPath) === 'dangling') {
+        stderr.write(
+          `playbook run: ${linkPath} is a stale engine link to missing ` +
+            `${readlinkSync(linkPath)}; rerun without --no-provision to relink\n`,
+        );
+        return { code: 1 };
+      }
+    }
+    return {};
+  }
+
+  const manifestPath = declaringManifest(moduleDir);
+  if (manifestPath !== undefined) {
+    stderr.write(
+      `playbook run: ${manifestPath} declares @sublang/playbook; ` +
+        'provisioning would shadow the project install — run the ' +
+        "project's dependency install (e.g. npm install) instead\n",
+    );
+    return { code: 1 };
+  }
+
+  let roots;
+  try {
+    roots = hostRoots ?? defaultHostRoots();
+  } catch (error) {
+    stderr.write(
+      `playbook run: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    return { code: 1 };
+  }
+
+  // PBCLI-37: validate every destination before mutating any, so an
+  // occupied-path refusal leaves the module directory unchanged rather
+  // than half-provisioned.
+  const plans = [];
+  for (const name of missing) {
+    const linkPath = join(moduleDir, 'node_modules', name);
+    const state = linkState(linkPath);
+    if (state === 'occupied' || state === 'live') {
+      // A live-but-unresolvable link is as foreign as a real directory:
+      // neither is a link this host may replace.
+      stderr.write(
+        `playbook run: cannot provision ${linkPath}: the path is already ` +
+          `occupied${state === 'live' ? ' by a foreign symbolic link' : ''}\n`,
+      );
+      return { code: 1 };
+    }
+    plans.push({
+      linkPath,
+      target: roots[name],
+      dangling: state === 'dangling',
+    });
+  }
+
+  const created = [];
+  try {
+    for (const { linkPath, target, dangling } of plans) {
+      if (dangling) await unlink(linkPath);
+      await mkdir(dirname(linkPath), { recursive: true });
+      await symlink(target, linkPath, 'dir');
+      created.push(`${linkPath} -> ${target}`);
+    }
+  } catch (error) {
+    // PBCLI-37: a filesystem failure is a load fault, not a raw crash.
+    stderr.write(
+      'playbook run: cannot provision engine links: ' +
+        `${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    return { code: 1 };
+  }
+  stderr.write(`playbook run: provisioned ${created.join(', ')}\n`);
+  return {};
+}

package/reference/sdlc/code.playbook/bin/run.js

@@ -21,7 +21,7 @@ import {
 } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
   Cligent,
   isEffortSupported,
@@ -29,6 +29,13 @@ import {
 } from '@sublang/cligent';
 import { parse as parseYaml } from 'yaml';
 import { hiddenControlEnvelope } from '../../../../src/xstate-runtime.js';
+import {
+  adapterSdkFailureLines,
+  checkAdapterSdks,
+  mappedSdksFor,
+  probeAdapterSdk,
+} from './adapter-sdk.js';
+import { provisionEngine } from './provision.js';
 
 // PBCLI-19: adapter shorthands the run host can construct.
 const ADAPTER_LOADERS = {
@@ -76,6 +83,18 @@ export async function runPlaybookRun(options = {}) {
     readStdin,
     sessionsDir,
     userConfigPath,
+    // PBCLI-39: the adapter SDK probe and the runtime classifier, injectable
+    // like createAgent so tests can drive an unavailable or below-floor
+    // runtime without uninstalling or downgrading one.
+    probeAdapterSdk: options.probeAdapterSdk ?? probeAdapterSdk,
+    classifyRuntime: options.classifyRuntime,
+    // PBCLI-40: the original invocation, preserved on the ephemeral re-run;
+    // this module receives argv with the leading `run` already consumed.
+    rawArgv: ['run', ...argv],
+    ephemeralNpx: options.ephemeralNpx,
+    // PBCLI-37: injected host package roots let tests provision against
+    // synthetic trees, like the injected session store.
+    hostRoots: options.hostRoots,
   };
 
   let args;
@@ -101,6 +120,11 @@ async function runFirst(args, ctx) {
     return { code: EXIT.arg };
   }
 
+  // PBCLI-36/37 (DR-024): provision engine links for a filesystem module
+  // before importing it; a resolvable engine is never touched.
+  const provisioned = await maybeProvision(args.from, args, ctx);
+  if (provisioned.code !== undefined) return provisioned;
+
   const loaded = await loadRegistryEntry(args.from, ctx);
   if (loaded.code !== undefined) return loaded;
   const { entry } = loaded;
@@ -150,6 +174,18 @@ async function runFirst(args, ctx) {
     return { code: EXIT.arg };
   }
 
+  // PBCLI-39/40: an optional-peer SDK that is not installed fails here,
+  // before the runtime exists and before any agent call — never mid-turn.
+  const sdkError = await adapterSdksDiagnostic(
+    [...roleSpecs.values(), captainSpec],
+    ctx,
+    stdinReplayArgs(args, task),
+  );
+  if (sdkError !== undefined) {
+    stderr.write(sdkError);
+    return { code: EXIT.arg };
+  }
+
   let runtime;
   try {
     runtime = entry.createRuntime({
@@ -246,6 +282,11 @@ async function runResume(args, ctx) {
     return { code: EXIT.arg };
   }
 
+  // PBCLI-37: a stored filesystem `from` (a file: URL) is probed and
+  // provisioned on resume exactly as on a first run.
+  const provisioned = await maybeProvision(record.from, args, ctx);
+  if (provisioned.code !== undefined) return provisioned;
+
   const loaded = await loadRegistryEntry(record.from, ctx);
   if (loaded.code !== undefined) return loaded;
   const { entry } = loaded;
@@ -276,6 +317,18 @@ async function runResume(args, ctx) {
     return { code: EXIT.arg };
   }
 
+  // PBCLI-39: a resume rebuilds the stored lineup, so it needs the same
+  // SDKs — an install that lost one must not resume into a mid-turn error.
+  const sdkError = await adapterSdksDiagnostic(
+    [...roleSpecs.values(), record.captain],
+    ctx,
+    stdinReplayArgs(args, reply),
+  );
+  if (sdkError !== undefined) {
+    stderr.write(sdkError);
+    return { code: EXIT.arg };
+  }
+
   let runtime;
   try {
     runtime = entry.createRuntime({
@@ -625,6 +678,50 @@ function specsDiagnostic(specs) {
   return undefined;
 }
 
+// PBCLI-40: the replay tail for input the command consumed from stdin —
+// the pipe that carried it will not exist when the printed command runs.
+// The value rides behind a `--` end-of-options terminator, because quoting
+// alone cannot keep a flag-shaped value (`--json`, `--last`, a `-`-leading
+// bullet) from being read as an option; where the original invocation
+// already activated a terminator of its own, that one is reused — a second
+// `--` after the first would itself be positional data on the replay,
+// turning a `--json` task into `-- --json`.
+function stdinReplayArgs(args, resolved) {
+  if (args.task !== undefined) return [];
+  return args.terminated ? [resolved] : ['--', resolved];
+}
+
+// PBCLI-39/40: returns the ready-to-write stderr block naming every bound
+// adapter whose optional-peer SDK is not installed, or undefined when every
+// one of them loads. Runs only after specsDiagnostic has accepted the
+// adapter names, so every spec here carries a known adapter.
+async function adapterSdksDiagnostic(specs, ctx, stdinArgs = []) {
+  const adapters = specs.map((spec) => spec.adapter);
+  const { unusableAdapters } = await checkAdapterSdks(
+    adapters,
+    ctx.probeAdapterSdk,
+    ...(ctx.classifyRuntime ? [ctx.classifyRuntime] : []),
+  );
+  if (unusableAdapters.length === 0) return undefined;
+  const [header, ...commands] = adapterSdkFailureLines(unusableAdapters, {
+    // PBCLI-40: the ephemeral re-run carries the lineup's full mapped SDK
+    // set and the original arguments, so it completes in one hop and runs
+    // exactly as printed. stdinArgs arrive terminator-ready from
+    // stdinReplayArgs — appended verbatim here, because whether a `--` is
+    // needed depends on the original invocation's own parse state.
+    requiredSdks: mappedSdksFor(adapters),
+    invocation: [...ctx.rawArgv, ...stdinArgs],
+    ...(ctx.ephemeralNpx !== undefined
+      ? { ephemeralNpx: ctx.ephemeralNpx }
+      : {}),
+  }).filter((line) => line !== '');
+  // Only the header takes the command prefix; the install lines stay
+  // copy-pasteable.
+  return [`playbook run: ${header}`, ...commands]
+    .map((line) => `${line}\n`)
+    .join('');
+}
+
 function isAgentSpec(spec) {
   return (
     typeof spec === 'object' &&
@@ -876,14 +973,29 @@ export function parseRunArgs(argv) {
     cwd: undefined,
     json: false,
     verbose: false,
+    noProvision: false,
     help: false,
+    terminated: false,
   };
   const positionals = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
+    // PBCLI-40: end-of-options — everything after `--` is positional, so a
+    // flag-shaped task or reply (a stdin-derived `--json`, a `- bullet`
+    // line) survives the ephemeral re-run round trip instead of being
+    // reinterpreted as an option. `terminated` records that this branch
+    // fired — only a `--` the walk itself treats as the terminator counts,
+    // never one consumed as an option's value (`--cwd --`) — so the re-run
+    // builder can reuse an active terminator instead of doubling it.
+    if (arg === '--') {
+      args.terminated = true;
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
     if (arg === '--help' || arg === '-h') args.help = true;
     else if (arg === '--json') args.json = true;
     else if (arg === '--verbose') args.verbose = true;
+    else if (arg === '--no-provision') args.noProvision = true;
     else if (arg === '--last') args.last = true;
     else if (arg === '--cwd') args.cwd = takeValue(argv, (i += 1), '--cwd');
     else if (arg === '--captain')
@@ -961,6 +1073,36 @@ function registryImportSpecifier(specifier, cwd) {
   return specifier;
 }
 
+// PBCLI-37: the absolute file path of a filesystem `<from>` (path or
+// file: URL), or undefined for a bare package specifier — those resolve
+// from the host's own module tree and are neither probed nor provisioned.
+function moduleFilePath(specifier, cwd) {
+  if (specifier.startsWith('file:')) return fileURLToPath(specifier);
+  if (
+    isAbsolute(specifier) ||
+    specifier.startsWith('./') ||
+    specifier.startsWith('../') ||
+    specifier.startsWith('.\\') ||
+    specifier.startsWith('..\\')
+  ) {
+    return resolve(cwd, specifier);
+  }
+  return undefined;
+}
+
+// PBCLI-36/37: probe-and-provision for a filesystem registry module.
+// Returns {} to proceed or { code } after a reported provisioning fault.
+async function maybeProvision(specifier, args, ctx) {
+  const modulePath = moduleFilePath(specifier, ctx.cwdDefault);
+  if (modulePath === undefined) return {};
+  return provisionEngine({
+    modulePath,
+    stderr: ctx.stderr,
+    enabled: !args.noProvision,
+    hostRoots: ctx.hostRoots,
+  });
+}
+
 function isValidRegistryEntry(value) {
   return (
     typeof value === 'object' &&
@@ -990,6 +1132,7 @@ function runHelpText() {
     '  <from>   registry module specifier (package subpath, path, or file: URL)',
     '  [task]   Boss intent; read from stdin when omitted',
     '  [reply]  Boss reply to a parked session; read from stdin when omitted',
+    '  --       end of options; use before a task or reply that starts with -',
     '',
     'Options:',
     '  --player <role>=<agent>   bind a required role (repeatable)',
@@ -1000,6 +1143,8 @@ function runHelpText() {
     '                            output or questions) instead of plain text',
     '  --last                    resume the most recently parked session',
     '  --verbose                 forward telemetry topics to stderr',
+    '  --no-provision            never create engine links beside a',
+    '                            filesystem <from> module',
     '  -h, --help                print this help',
     '',
     '  <agent> is <adapter>[:<model>][@<effort>] over the shorthands',

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -919,9 +919,30 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         if (visibilityControlError !== undefined)
             throw visibilityControlError;
     }
+    // CAPTAIN-34/35: a parentless internal Captain frame holds no recoverable
+    // work, so any rejected boundary call disposes the stack instead of
+    // stranding a frame that would refuse every later registered command. A
+    // parentless external root keeps its frame for Boss recovery.
+    async function failParentlessBoundary(frame, error) {
+        if (!frame.internal || !frames.includes(frame))
+            throw error;
+        if (!disposing) {
+            try {
+                await disposeStack('failure');
+            }
+            catch {
+                // The boundary failure wins; disposal detail stays on telemetry.
+            }
+        }
+        const commands = [...enablementById.values()]
+            .map((enablement) => `/${enablement.command} <task>`)
+            .join(' or ');
+        throw new Error('Captain could not finish that turn and the engagement was reset. ' +
+            `Send the request again${commands ? `, or start a playbook directly with ${commands}` : ''}.`, { cause: error });
+    }
     async function returnBoundaryFailure(frame, error, context) {
         if (!frame.parent)
-            throw error;
+            await failParentlessBoundary(frame, error);
         await resumeParent(frame, {
             status: context.signal.aborted ? 'aborted' : 'error',
             playbookId: frame.entry.id,
@@ -1126,7 +1147,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 completed = true;
             }
             else {
-                throw error;
+                await failParentlessBoundary(frame, error);
             }
         }
         finally {

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -103,7 +103,7 @@ class VisibilityControlError extends Error {
   }
 }
 
-type DisposalReason = 'dismiss' | 'final' | 'dispose';
+type DisposalReason = 'dismiss' | 'final' | 'dispose' | 'failure';
 
 interface ControlLedger {
   activePlaybookId?: string;
@@ -1275,12 +1275,38 @@ export function createPlaybookCaptainShell(
     if (visibilityControlError !== undefined) throw visibilityControlError;
   }
 
+  // CAPTAIN-34/35: a parentless internal Captain frame holds no recoverable
+  // work, so any rejected boundary call disposes the stack instead of
+  // stranding a frame that would refuse every later registered command. A
+  // parentless external root keeps its frame for Boss recovery.
+  async function failParentlessBoundary(
+    frame: EngagementFrame,
+    error: unknown,
+  ): Promise<never> {
+    if (!frame.internal || !frames.includes(frame)) throw error;
+    if (!disposing) {
+      try {
+        await disposeStack('failure');
+      } catch {
+        // The boundary failure wins; disposal detail stays on telemetry.
+      }
+    }
+    const commands = [...enablementById.values()]
+      .map((enablement) => `/${enablement.command} <task>`)
+      .join(' or ');
+    throw new Error(
+      'Captain could not finish that turn and the engagement was reset. ' +
+        `Send the request again${commands ? `, or start a playbook directly with ${commands}` : ''}.`,
+      { cause: error },
+    );
+  }
+
   async function returnBoundaryFailure(
     frame: EngagementFrame,
     error: unknown,
     context: CaptainContext,
   ): Promise<void> {
-    if (!frame.parent) throw error;
+    if (!frame.parent) await failParentlessBoundary(frame, error);
     await resumeParent(
       frame,
       {
@@ -1524,7 +1550,7 @@ export function createPlaybookCaptainShell(
         await returnBoundaryFailure(frame, error, context);
         completed = true;
       } else {
-        throw error;
+        await failParentlessBoundary(frame, error);
       }
     } finally {
       activeTurnSummary = undefined;

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -10,6 +10,13 @@
 # settings inline: an adapter shorthand (claude, codex) or a block with
 # adapter/model/effort/permissions. Retuning one agent never changes
 # another.
+
+# Each adapter needs its vendor SDK installed as its own top-level
+# install root — they are optional peer dependencies, so you pay only
+# for the vendors named below:
+#   claude -> npm install -g @anthropic-ai/claude-agent-sdk
+#   codex  -> npm install -g @openai/codex-sdk
+# Drop an adapter from this file and you can skip its SDK entirely.
 # Every seeded agent runs in cligent's protected auto mode
 # (permissions.mode: auto): claude maps it to permissionMode auto, codex to
 # on-request + auto_review. Codex roles also grant writablePaths: ['.git']

package/slc/link.md

@@ -1335,6 +1335,20 @@ The emitted module:
   type; supplying one is a construction error, so a linker that judges a
   runtime-owned arm to have lost payload detail under erasure shall report
   that gap rather than emit the entry.
+- Supplies `spec.compat` with the compatibility values current at link time:
+  `{ artifactSchema, runtimeAbi }`, where `artifactSchema` is `1` — the
+  schema number of the thin-module format this §Output defines — and
+  `runtimeAbi` is the installed shared engine's `RUNTIME_ABI` self-report.
+  The linker shall verify that the installed engine lists the emitted
+  schema in `SUPPORTED_ARTIFACT_SCHEMAS` and treat its absence as a
+  link-time error; it shall not stamp a different member (such as the
+  highest) merely because that engine also supports a newer artifact
+  format — the declaration names the format of the emitted module, not
+  the capability of the emitting engine. The factory checks the
+  declaration against the engine instance that actually loads the emitted
+  module and fails construction on a mismatch, so an artifact linked under
+  one engine cannot run silently skewed under another. Modules emitted
+  before this contract carry no `compat` member and remain loadable.
 - Default-exports the factory call as `createPlaybookRuntime`, typed
   `PlaybookRuntimeFactory<PlaybookRuntimeOptions>`.
 - Exposes, under an `_internal` export, the pure helpers verification

package/src/xstate-playbook-runtime.d.ts

@@ -70,9 +70,26 @@ export declare const BOSS_REPLY_ERRORS: {
     readonly missingQuestion: "needsBossReply outcome missing 'question' field";
     readonly unregisteredState: (stateId: string) => string;
 };
+/** The runtime ABI this engine implements (DR-022). */
+export declare const RUNTIME_ABI = 1;
+/** The linked-artifact schema versions this engine accepts (DR-022). */
+export declare const SUPPORTED_ARTIFACT_SCHEMAS: readonly number[];
+/** A linked artifact's declared link-time compatibility values (DR-022). */
+export interface XStatePlaybookRuntimeCompat {
+    /** The artifact schema version the linker emitted. */
+    artifactSchema: number;
+    /** The engine ABI the artifact was linked against. */
+    runtimeAbi: number;
+}
 export interface XStatePlaybookRuntimeSpec<TOptions> {
     /** Diagnostic label used in internal invariant errors. Default 'playbook'. */
     label?: string;
+    /**
+     * Link-time compatibility declaration checked at construction against the
+     * loaded engine's self-report (DR-022). Absent: a legacy artifact emitted
+     * before the contract — constructed with no compatibility check.
+     */
+    compat?: XStatePlaybookRuntimeCompat;
     /** Validate and JSON-snapshot the caller's per-run options. */
     snapshotOptions: (value: unknown) => TOptions;
     /** Derive the FSM machine input from validated options. Default: identity. */
@@ -186,6 +203,16 @@ export interface PlayerBridgeSpec {
     resumableStateIds: ReadonlySet<string>;
 }
 export declare function createPlayerBridge(spec: PlayerBridgeSpec, ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined, boundary?: RuntimeBoundaryCalls, onControlPlaneError?: (error: unknown) => void): PromiseActorLogic<PlaybookActorOutput, PlaybookPlayerInput>;
+/**
+ * Default direct-Captain adjudicator prompt (DR-025). The single statement of
+ * the `{ guard, …structuralPayloadFields }` reply contract, shared with the
+ * compiled default Captain artifact so the wording cannot drift.
+ */
+export declare function defaultBuildCaptainJudgePrompt(input: {
+    readonly stateId: string;
+    readonly sourceItem: string;
+    readonly result: Readonly<Record<string, string>>;
+}, finalText: string): string;
 /** Targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
 export declare function resumableStateIdsFromMachine(machine: AnyStateMachine): ReadonlySet<string>;
 /**