@sublang/playbook 3.0.0 → 3.1.0

package/README.md

@@ -70,14 +70,15 @@ playbook run @sublang/playbook/code/registry "add a test for parseArgs" --json
 - **[docs/embedding.md](docs/embedding.md)** — the six-port runtime
   contract for hosts other than `tmux-play`.
 
-> **Current release:** 3.0.0. The composed system — the compiled default
+> **Current release:** 3.1.0. The composed system — the compiled default
 > Captain, CODE and DISCUSS, nested playbook calls, script actors and the
 > GEARS optimize pass, the semver-stable six-port runtime contract, and
 > non-interactive `playbook run` with parked-session resume — landed in
 > 1.0.0. Since then, `playbook run` gained defaults in the user config,
-> and 3.0.0 replaces the top-level `profiles` map with
-> inline agent settings (existing configs migrate themselves on the next
-> launch). See the [CHANGELOG](CHANGELOG.md).
+> 3.0.0 replaced the top-level `profiles` map with inline agent settings
+> (existing configs migrate themselves on the next launch), and 3.1.0
+> added the linked-artifact/engine compatibility check. See the
+> [CHANGELOG](CHANGELOG.md).
 
 ## How it compiles
 

package/docs/cli.md

@@ -67,6 +67,7 @@ intents the same way you would to `claude -p` or `codex exec`.
 | `--option <key>=<value>` | a playbook option (CODE's `committer`) |
 | `--cwd <dir>` | the agents' working directory |
 | `--json` | one envelope: `outcome`, `sessionId`, output or questions |
+| `--no-provision` | never create engine links beside a filesystem `<from>` |
 
 `<agent>` is `<adapter>[:<model>][@<effort>]` — `codex:gpt-5.5@xhigh`,
 or `claude@high` for the default model at high reasoning effort. The
@@ -79,6 +80,26 @@ Exit codes: `0` terminal, `1` bad argument or module, `2` failure, `3`
 the playbook needs a Boss reply
 ([PBCLI-18](../specs/user/playbook-cli.md#pbcli-18)).
 
+### Engine provisioning
+
+A compiled playbook module imports `xstate` and
+`@sublang/playbook/xstate-runtime` from its own directory. When a
+filesystem `<from>` cannot resolve them — typically under a global
+`npm install -g @sublang/playbook` with no project-local packages —
+`playbook run` provisions them automatically before loading: it creates
+`node_modules/xstate` and `node_modules/@sublang/playbook` beside the
+module as symlinks to the running host's own packages and prints one
+line naming what it linked
+([PBCLI-36](../specs/user/playbook-cli.md#pbcli-36),
+[DR-024](../specs/decisions/024-runtime-engine-provisioning.md)).
+A directory where the imports already resolve is never touched — a
+project-local install always wins — and `--no-provision` disables the
+mechanism entirely.
+
+If the module's directory is a git repository, add `node_modules/` to
+its `.gitignore` so the provisioned links never land in commits made by
+player agents working there.
+
 ### Resuming a parked run
 
 When the playbook stops to ask something, the run is parked, not lost:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, and DISCUSS workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -67,6 +67,7 @@
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
     "reference/sdlc/code.playbook/bin/playbook.js",
     "reference/sdlc/code.playbook/bin/run.js",
+    "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/discuss.playbook/discuss.gears.md",
     "reference/sdlc/discuss.playbook/discuss.fsm.ts",
     "reference/sdlc/discuss.playbook/discuss.fsm.js",

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

@@ -67,6 +67,7 @@ export async function runPlaybookCli(options = {}) {
       ...(options.createAgent ? { createAgent: options.createAgent } : {}),
       ...(options.readStdin ? { readStdin: options.readStdin } : {}),
       ...(options.sessionsDir ? { sessionsDir: options.sessionsDir } : {}),
+      ...(options.hostRoots ? { hostRoots: options.hostRoots } : {}),
     });
   }
 

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,7 @@ import {
 } from '@sublang/cligent';
 import { parse as parseYaml } from 'yaml';
 import { hiddenControlEnvelope } from '../../../../src/xstate-runtime.js';
+import { provisionEngine } from './provision.js';
 
 // PBCLI-19: adapter shorthands the run host can construct.
 const ADAPTER_LOADERS = {
@@ -76,6 +77,9 @@ export async function runPlaybookRun(options = {}) {
     readStdin,
     sessionsDir,
     userConfigPath,
+    // PBCLI-37: injected host package roots let tests provision against
+    // synthetic trees, like the injected session store.
+    hostRoots: options.hostRoots,
   };
 
   let args;
@@ -101,6 +105,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;
@@ -246,6 +255,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;
@@ -876,6 +890,7 @@ export function parseRunArgs(argv) {
     cwd: undefined,
     json: false,
     verbose: false,
+    noProvision: false,
     help: false,
   };
   const positionals = [];
@@ -884,6 +899,7 @@ export function parseRunArgs(argv) {
     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 +977,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' &&
@@ -1000,6 +1046,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/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. */

package/src/xstate-playbook-runtime.js

@@ -42,6 +42,48 @@ function isFsmResultFailure(error) {
         fsmResultFailures.has(error));
 }
 // ---------------------------------------------------------------------------
+// DR-022: the engine's compatibility self-report. A linked thin module
+// records the values current at link time in `spec.compat`; the factory
+// checks that declaration against this very module — the engine instance
+// that will interpret the FSM, so the check can never consult a different
+// engine copy than the one executing — and fails construction on a mismatch
+// instead of misbehaving deep in a session. Raising RUNTIME_ABI or removing
+// a member of SUPPORTED_ARTIFACT_SCHEMAS is a breaking change (RELEASE-15).
+// ---------------------------------------------------------------------------
+/** The runtime ABI this engine implements (DR-022). */
+export const RUNTIME_ABI = 1;
+/** The linked-artifact schema versions this engine accepts (DR-022). */
+export const SUPPORTED_ARTIFACT_SCHEMAS = Object.freeze([
+    1,
+]);
+// PBRT-50: validate a declaration against the loaded engine, schema first,
+// so one clear diagnostic covers a fully skewed artifact. Absent means a
+// legacy artifact emitted before the DR-022 contract; those must keep
+// loading unchanged (DR-019 §4), so there is nothing to check.
+function assertRuntimeCompat(compat, label) {
+    if (compat === undefined)
+        return;
+    if (compat === null || typeof compat !== 'object') {
+        throw new TypeError(`${label} spec.compat must be an object`);
+    }
+    const { artifactSchema, runtimeAbi } = compat;
+    if (!Number.isSafeInteger(artifactSchema)) {
+        throw new TypeError(`${label} spec.compat.artifactSchema must be an integer`);
+    }
+    if (!Number.isSafeInteger(runtimeAbi)) {
+        throw new TypeError(`${label} spec.compat.runtimeAbi must be an integer`);
+    }
+    if (!SUPPORTED_ARTIFACT_SCHEMAS.includes(artifactSchema)) {
+        throw new TypeError(`${label} artifact declares schema ${artifactSchema}, but this ` +
+            `@sublang/playbook/xstate-runtime engine supports ` +
+            `[${SUPPORTED_ARTIFACT_SCHEMAS.join(', ')}]`);
+    }
+    if (runtimeAbi !== RUNTIME_ABI) {
+        throw new TypeError(`${label} artifact declares runtime ABI ${runtimeAbi}, but this ` +
+            `@sublang/playbook/xstate-runtime engine implements ${RUNTIME_ABI}`);
+    }
+}
+// ---------------------------------------------------------------------------
 // Tolerant judge-JSON recovery (slc/link.md §Boss-event mapping).
 // ---------------------------------------------------------------------------
 function isPlainObject(value) {
@@ -857,6 +899,9 @@ function makeDefaultClassifyBossText(machine, entryEvent, bossEvents) {
  */
 export function createXStatePlaybookRuntime(machine, spec) {
     const label = spec.label ?? 'playbook';
+    // DR-022 / PBRT-50: reject an incompatible artifact declaration before any
+    // machine interpretation, against this loaded engine's own self-report.
+    assertRuntimeCompat(spec.compat, label);
     const declaredActors = collectInvokeSources(machine);
     const resumableStateIds = spec.resumableStateIds ?? resumableStateIdsFromMachine(machine);
     const resolvePlayerIdSpec = spec.resolvePlayerId;

package/src/xstate-playbook-runtime.ts

@@ -177,18 +177,86 @@ function isFsmResultFailure(error: unknown): boolean {
   );
 }
 
+// ---------------------------------------------------------------------------
+// DR-022: the engine's compatibility self-report. A linked thin module
+// records the values current at link time in `spec.compat`; the factory
+// checks that declaration against this very module — the engine instance
+// that will interpret the FSM, so the check can never consult a different
+// engine copy than the one executing — and fails construction on a mismatch
+// instead of misbehaving deep in a session. Raising RUNTIME_ABI or removing
+// a member of SUPPORTED_ARTIFACT_SCHEMAS is a breaking change (RELEASE-15).
+// ---------------------------------------------------------------------------
+
+/** The runtime ABI this engine implements (DR-022). */
+export const RUNTIME_ABI = 1;
+
+/** The linked-artifact schema versions this engine accepts (DR-022). */
+export const SUPPORTED_ARTIFACT_SCHEMAS: readonly number[] = Object.freeze([
+  1,
+]);
+
+/** 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;
+}
+
+// PBRT-50: validate a declaration against the loaded engine, schema first,
+// so one clear diagnostic covers a fully skewed artifact. Absent means a
+// legacy artifact emitted before the DR-022 contract; those must keep
+// loading unchanged (DR-019 §4), so there is nothing to check.
+function assertRuntimeCompat(
+  compat: XStatePlaybookRuntimeCompat | undefined,
+  label: string,
+): void {
+  if (compat === undefined) return;
+  if (compat === null || typeof compat !== 'object') {
+    throw new TypeError(`${label} spec.compat must be an object`);
+  }
+  const { artifactSchema, runtimeAbi } = compat;
+  if (!Number.isSafeInteger(artifactSchema)) {
+    throw new TypeError(
+      `${label} spec.compat.artifactSchema must be an integer`,
+    );
+  }
+  if (!Number.isSafeInteger(runtimeAbi)) {
+    throw new TypeError(`${label} spec.compat.runtimeAbi must be an integer`);
+  }
+  if (!SUPPORTED_ARTIFACT_SCHEMAS.includes(artifactSchema)) {
+    throw new TypeError(
+      `${label} artifact declares schema ${artifactSchema}, but this ` +
+        `@sublang/playbook/xstate-runtime engine supports ` +
+        `[${SUPPORTED_ARTIFACT_SCHEMAS.join(', ')}]`,
+    );
+  }
+  if (runtimeAbi !== RUNTIME_ABI) {
+    throw new TypeError(
+      `${label} artifact declares runtime ABI ${runtimeAbi}, but this ` +
+        `@sublang/playbook/xstate-runtime engine implements ${RUNTIME_ABI}`,
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // The per-workflow spec. Every strategy member has a generic default derived
 // from the FSM artifact's own data, so a linker-emitted thin module normally
-// supplies only `snapshotOptions` and, where applicable, `entryEvent`, erased
-// Boss-event field metadata, placeholder exceptions, and transition-event
-// fields. Hand-maintained artifacts may override any member to preserve their
-// existing observable behavior exactly.
+// supplies only `snapshotOptions` and, where applicable, `compat`,
+// `entryEvent`, erased Boss-event field metadata, placeholder exceptions, and
+// transition-event fields. Hand-maintained artifacts may override any member
+// to preserve their existing observable behavior exactly.
 // ---------------------------------------------------------------------------
 
 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. */
@@ -1337,6 +1405,9 @@ export function createXStatePlaybookRuntime<TOptions>(
   spec: XStatePlaybookRuntimeSpec<TOptions>,
 ): PlaybookRuntimeFactory<TOptions> {
   const label = spec.label ?? 'playbook';
+  // DR-022 / PBRT-50: reject an incompatible artifact declaration before any
+  // machine interpretation, against this loaded engine's own self-report.
+  assertRuntimeCompat(spec.compat, label);
   const declaredActors = collectInvokeSources(machine);
   const resumableStateIds =
     spec.resumableStateIds ?? resumableStateIdsFromMachine(machine);