@sublang/playbook 3.0.0 → 4.0.0

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) {
@@ -412,7 +454,12 @@ export function createPlayerBridge(spec, ports, getActiveSignal, boundary, onCon
 // `response` and rejects a judge reply that supplies either presentation
 // field as an undeclared extra key.
 // ---------------------------------------------------------------------------
-function buildCaptainJudgePrompt(input, finalText) {
+/**
+ * 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 function defaultBuildCaptainJudgePrompt(input, finalText) {
     const lines = [];
     lines.push('Adjudicate the direct Captain output for this FSM state.');
     lines.push(`State id: ${input.stateId}`);
@@ -857,6 +904,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;
@@ -1337,7 +1387,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     if (result.status !== 'ok' || !result.finalText) {
                         throw new Error('captainActor: boundary returned an unvalidated Captain result');
                     }
-                    const judgePrompt = buildCaptainJudgePrompt(input, result.finalText);
+                    const judgePrompt = defaultBuildCaptainJudgePrompt(input, result.finalText);
                     const raw = await boundary.callJudge('captain-output-adjudication', input.stateId, judgePrompt, active);
                     const output = adjudicateCaptainOutput(extractFields, input, result.finalText, raw);
                     validateBossReplyOutput(input, output, resumableStateIds);

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. */
@@ -731,8 +799,17 @@ export function createPlayerBridge(
 // field as an undeclared extra key.
 // ---------------------------------------------------------------------------
 
-function buildCaptainJudgePrompt(
-  input: PlaybookCaptainInput,
+/**
+ * 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 function defaultBuildCaptainJudgePrompt(
+  input: {
+    readonly stateId: string;
+    readonly sourceItem: string;
+    readonly result: Readonly<Record<string, string>>;
+  },
   finalText: string,
 ): string {
   const lines: string[] = [];
@@ -1337,6 +1414,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);
@@ -1971,7 +2051,7 @@ export function createXStatePlaybookRuntime<TOptions>(
                 'captainActor: boundary returned an unvalidated Captain result',
               );
             }
-            const judgePrompt = buildCaptainJudgePrompt(
+            const judgePrompt = defaultBuildCaptainJudgePrompt(
               input,
               result.finalText,
             );