@sublang/playbook 1.3.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, and DISCUSS workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -126,7 +126,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.154",
     "@openai/codex-sdk": "^0.139.0",
-    "@sublang/cligent": "^0.15.0",
+    "@sublang/cligent": "^0.16.0",
     "@sublang/spex": "^0.3.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/slc/link.md

@@ -257,15 +257,21 @@ array requests a tool-free call, while omission preserves the host Captain's
 configured tools.
 `CaptainResult` carries no resume token or player-continuation selection.
 A non-`ok`
-result, or an `ok` result without `finalText`, shall reject the actor through
-the FSM's error path.
-Outside a signal-driven abort, those invalid direct-Captain results are
-latched control-plane failures. The runtime shall let the actor take `onError`,
-drive it to quiescence, and drain ordered emissions before the public method
-rejects with the original failure. It shall never translate either case into
-a recoverable workflow `{ outcome: 'failed' }` result. If the combined signal
-has aborted, an aborted host result follows the ordinary abort settlement
-instead of being promoted to a control-plane failure.
+result, or an `ok` result without non-empty `finalText`, shall record that
+failure on the call's single finish trace and reject the actor through the
+FSM's error path. These structured host-result failures are recoverable
+workflow failures, not control-plane failures: the runtime shall let the actor
+take `onError`, drive it to quiescence, drain ordered emissions, and resolve
+the public method with `{ outcome: 'failed' }` carrying the failure state's
+error. This matches the delegated-player result boundary.
+A non-abort thrown `callCaptain` port, a malformed host result, and a rejecting
+trace sink remain control-plane failures that reject the public method. If the
+required finish sink rejects after a structured host-result failure, the
+actor's error and failure-state evidence shall remain the host-result failure,
+while the public method rejects with the sink failure surfaced by the turn's
+emission drain. Absent such a control-plane failure, if the combined signal
+has aborted, ordinary abort settlement remains authoritative after the actor
+reaches its error path.
 
 Every linked runtime owns a map from resolved player id to its latest non-empty `resumeToken`.
 Before reading a resolved direct-Captain or delegated-player result, the
@@ -753,8 +759,11 @@ Adjudicator failures are control-plane errors.
 The runtime shall propagate them by throwing out of `handleBossInput` after attempting cleanup.
 The host adapter surfaces the throw on its control-plane channel (cligent surfaces such throws as `runtime_error` per [TMUX-025](https://github.com/sublang-ai/cligent/blob/main/specs/user/tmux-play.md#tmux-025)).
 The host's player-result channels (`player_finished` and equivalents) are reserved for failures the player itself produced; the host emits them when `callPlayer` resolves with `status !== 'ok'`.
-Captain call failures stay on the Captain/control boundary and shall not be
-reported as player failures.
+Direct-Captain host-result failures stay on the Captain actor boundary and
+shall not be reported as player failures; they follow the recoverable FSM
+failure path specified above. Captain transport, result-shape, trace-sink, and
+adjudication failures remain control-plane errors unless the transport failure
+is causally identical to the active abort signal.
 Because XState still needs the invoked promise to settle, the linked runtime
 shall latch an adjudicator, actor-output JSON-validation, or nested-boundary
 control error outside machine context, allow the invocation's `onError` path to
@@ -1316,6 +1325,13 @@ The emitted module:
   weaken, runtime-derived entry text ownership or closed interrupt targets.
   A conflicting duplicate field contract is a linker/runtime construction
   error.
+  `NO_ACTION` and `BOSS_REPLY` are runtime-owned event types the factory
+  supplies itself — `NO_ACTION` as exactly `{ type: 'NO_ACTION' }`, and
+  `BOSS_REPLY` as an optional judge-selected `questionId` plus the exact-text
+  `answer` the runtime attaches. `bossEvents` shall carry no entry for either
+  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.
 - Default-exports the factory call as `createPlaybookRuntime`, typed
   `PlaybookRuntimeFactory<PlaybookRuntimeOptions>`.
 - Exposes, under an `_internal` export, the pure helpers verification

package/src/xstate-playbook-runtime.js

@@ -23,6 +23,25 @@ export const BOSS_REPLY_ERRORS = {
     unregisteredState: (stateId) => `state ${stateId} declared needsBossReply but is not registered as resumable`,
 };
 // ---------------------------------------------------------------------------
+// A host agent result that is not `ok` (or is `ok` with no final text) is a
+// recoverable FSM failure, not a control-plane error: it travels the invoked
+// actor's XState error path to the failure state and the public boundary
+// resolves `failed` (PBRT-47, matching the player boundary's PBRT-9). The
+// direct-Captain boundary has to emit its paired finish trace before
+// rethrowing, so it needs to tell that failure apart from the control-plane
+// errors it does latch — a thrown port, a malformed result, a rejecting sink.
+// ---------------------------------------------------------------------------
+const fsmResultFailures = new WeakSet();
+function markFsmResultFailure(error) {
+    fsmResultFailures.add(error);
+    return error;
+}
+function isFsmResultFailure(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        fsmResultFailures.has(error));
+}
+// ---------------------------------------------------------------------------
 // Tolerant judge-JSON recovery (slc/link.md §Boss-event mapping).
 // ---------------------------------------------------------------------------
 function isPlainObject(value) {
@@ -587,10 +606,20 @@ function configuredEventTypesForState(machine, stateId) {
     }
     return configured;
 }
+// Derived contracts merge into whatever the machine already yielded for the
+// same type, so a deterministic entry event that shares a type with another
+// derived contract keeps its exact-text ownership instead of being replaced.
+function mergeDerivedContract(contracts, contract) {
+    const existing = contracts.get(contract.type);
+    contracts.set(contract.type, {
+        type: contract.type,
+        fields: { ...(existing?.fields ?? {}), ...(contract.fields ?? {}) },
+    });
+}
 function defaultBossEventSpecs(machine, entryEvent, supplied) {
     const contracts = new Map();
     if (entryEvent !== undefined) {
-        contracts.set(entryEvent.type, {
+        mergeDerivedContract(contracts, {
             type: entryEvent.type,
             fields: { [entryEvent.textField]: { source: 'text', required: true } },
         });
@@ -601,7 +630,7 @@ function defaultBossEventSpecs(machine, entryEvent, supplied) {
         : undefined;
     const interruptTargets = rootInterrupt === undefined ? [] : transitionTargets(rootInterrupt);
     if (interruptTargets.length > 0) {
-        contracts.set('BOSS_INTERRUPT', {
+        mergeDerivedContract(contracts, {
             type: 'BOSS_INTERRUPT',
             fields: {
                 targetId: {
@@ -609,6 +638,10 @@ function defaultBossEventSpecs(machine, entryEvent, supplied) {
                     required: true,
                     values: [...new Set(interruptTargets)],
                 },
+                // slc/link.md §Boss-event mapping: for BOSS_INTENT and
+                // BOSS_INTERRUPT the runtime, never the judge, attaches the exact
+                // original Boss text as `bossIntent`.
+                bossIntent: { source: 'text', required: true },
             },
         });
     }
@@ -839,8 +872,12 @@ export function createXStatePlaybookRuntime(machine, spec) {
             : {}),
     };
     const extractFields = spec.extractRequiredFields ?? defaultExtractRequiredFields;
-    const classifyBossText = spec.classifyBossText ??
-        makeDefaultClassifyBossText(machine, spec.entryEvent, spec.bossEvents ?? []);
+    // Build the derived classifier unconditionally: it is the sole validator of
+    // supplied `bossEvents`, and DR-019 §2 requires a conflicting duplicate to
+    // fail factory construction whether or not this spec overrides the
+    // classifier that would have consumed the contracts.
+    const derivedClassifyBossText = makeDefaultClassifyBossText(machine, spec.entryEvent, spec.bossEvents ?? []);
+    const classifyBossText = spec.classifyBossText ?? derivedClassifyBossText;
     const normalizeTransitionEvent = spec.normalizeTransitionEvent ??
         makeDefaultNormalizeTransitionEvent(spec.transitionEventFields ?? []);
     const statusesForState = spec.statusesForState ?? defaultStatusesForState;
@@ -1221,18 +1258,17 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         await emitTrace('captain.call.finished', { ...identity, status: 'error', error: normalizeError(error) }, position);
                         throw error;
                     }
+                    // A non-`ok` host result is a recoverable FSM failure (PBRT-47), so
+                    // it is never latched as a control-plane error; it is still
+                    // authoritative for the actor's error path even when the required
+                    // finish emission fails or a coincident boundary abort lands.
                     let resultFailure;
                     if (result.status !== 'ok') {
-                        resultFailure = new Error(result.error ??
-                            `captainActor: callCaptain status "${result.status}"`);
+                        resultFailure = markFsmResultFailure(new Error(result.error ??
+                            `captainActor: callCaptain status "${result.status}"`));
                     }
                     else if (result.finalText === undefined || result.finalText === '') {
-                        resultFailure = new Error('captainActor: callCaptain returned status=ok with no finalText');
-                    }
-                    if (resultFailure !== undefined) {
-                        // The host result is authoritative even when the required finish
-                        // emission fails or triggers a coincident boundary abort.
-                        controlPlaneError ??= resultFailure;
+                        resultFailure = markFsmResultFailure(new Error('captainActor: callCaptain returned status=ok with no finalText'));
                     }
                     try {
                         await emitTrace('captain.call.finished', {
@@ -1290,12 +1326,12 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     await drainEmissions();
                     const prompt = composeCaptainPrompt(input);
                     const result = await boundary.callCaptain(input, prompt, active);
-                    if (result.status !== 'ok') {
-                        throw new Error(result.error ??
-                            `captainActor: callCaptain status "${result.status}"`);
-                    }
-                    if (result.finalText === undefined || result.finalText === '') {
-                        throw new Error('captainActor: callCaptain returned status=ok with no finalText');
+                    // The boundary owns result validation (PBRT-47) and throws the
+                    // authoritative failure itself, so a returned result is always
+                    // `ok` with visible text. Assert that invariant rather than
+                    // restating the failure semantics, which would drift.
+                    if (result.status !== 'ok' || !result.finalText) {
+                        throw new Error('captainActor: boundary returned an unvalidated Captain result');
                     }
                     const judgePrompt = buildCaptainJudgePrompt(input, result.finalText);
                     const raw = await boundary.callJudge('captain-output-adjudication', input.stateId, judgePrompt, active);
@@ -1304,8 +1340,13 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     return output;
                 }
                 catch (error) {
-                    if (!active.aborted)
+                    // A host-reported Captain result failure routes to the FSM's
+                    // failure state (PBRT-47); everything else here — a drained
+                    // emission failure, prompt composition, the port itself,
+                    // adjudication — is control plane.
+                    if (!active.aborted && !isFsmResultFailure(error)) {
                         controlPlaneError ??= error;
+                    }
                     throw error;
                 }
             });

package/src/xstate-playbook-runtime.ts

@@ -152,6 +152,31 @@ export const BOSS_REPLY_ERRORS = {
     `state ${stateId} declared needsBossReply but is not registered as resumable`,
 } as const;
 
+// ---------------------------------------------------------------------------
+// A host agent result that is not `ok` (or is `ok` with no final text) is a
+// recoverable FSM failure, not a control-plane error: it travels the invoked
+// actor's XState error path to the failure state and the public boundary
+// resolves `failed` (PBRT-47, matching the player boundary's PBRT-9). The
+// direct-Captain boundary has to emit its paired finish trace before
+// rethrowing, so it needs to tell that failure apart from the control-plane
+// errors it does latch — a thrown port, a malformed result, a rejecting sink.
+// ---------------------------------------------------------------------------
+
+const fsmResultFailures = new WeakSet<object>();
+
+function markFsmResultFailure(error: Error): Error {
+  fsmResultFailures.add(error);
+  return error;
+}
+
+function isFsmResultFailure(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    fsmResultFailures.has(error as object)
+  );
+}
+
 // ---------------------------------------------------------------------------
 // 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
@@ -940,6 +965,20 @@ function configuredEventTypesForState(
   return configured;
 }
 
+// Derived contracts merge into whatever the machine already yielded for the
+// same type, so a deterministic entry event that shares a type with another
+// derived contract keeps its exact-text ownership instead of being replaced.
+function mergeDerivedContract(
+  contracts: Map<string, XStateBossEventSpec>,
+  contract: XStateBossEventSpec,
+): void {
+  const existing = contracts.get(contract.type);
+  contracts.set(contract.type, {
+    type: contract.type,
+    fields: { ...(existing?.fields ?? {}), ...(contract.fields ?? {}) },
+  });
+}
+
 function defaultBossEventSpecs(
   machine: AnyStateMachine,
   entryEvent: { type: string; textField: string } | undefined,
@@ -947,7 +986,7 @@ function defaultBossEventSpecs(
 ): ReadonlyMap<string, XStateBossEventSpec> {
   const contracts = new Map<string, XStateBossEventSpec>();
   if (entryEvent !== undefined) {
-    contracts.set(entryEvent.type, {
+    mergeDerivedContract(contracts, {
       type: entryEvent.type,
       fields: { [entryEvent.textField]: { source: 'text', required: true } },
     });
@@ -961,7 +1000,7 @@ function defaultBossEventSpecs(
   const interruptTargets =
     rootInterrupt === undefined ? [] : transitionTargets(rootInterrupt);
   if (interruptTargets.length > 0) {
-    contracts.set('BOSS_INTERRUPT', {
+    mergeDerivedContract(contracts, {
       type: 'BOSS_INTERRUPT',
       fields: {
         targetId: {
@@ -969,6 +1008,10 @@ function defaultBossEventSpecs(
           required: true,
           values: [...new Set(interruptTargets)],
         },
+        // slc/link.md §Boss-event mapping: for BOSS_INTENT and
+        // BOSS_INTERRUPT the runtime, never the judge, attaches the exact
+        // original Boss text as `bossIntent`.
+        bossIntent: { source: 'text', required: true },
       },
     });
   }
@@ -1313,9 +1356,16 @@ export function createXStatePlaybookRuntime<TOptions>(
   };
   const extractFields =
     spec.extractRequiredFields ?? defaultExtractRequiredFields;
-  const classifyBossText =
-    spec.classifyBossText ??
-    makeDefaultClassifyBossText(machine, spec.entryEvent, spec.bossEvents ?? []);
+  // Build the derived classifier unconditionally: it is the sole validator of
+  // supplied `bossEvents`, and DR-019 §2 requires a conflicting duplicate to
+  // fail factory construction whether or not this spec overrides the
+  // classifier that would have consumed the contracts.
+  const derivedClassifyBossText = makeDefaultClassifyBossText(
+    machine,
+    spec.entryEvent,
+    spec.bossEvents ?? [],
+  );
+  const classifyBossText = spec.classifyBossText ?? derivedClassifyBossText;
   const normalizeTransitionEvent =
     spec.normalizeTransitionEvent ??
     makeDefaultNormalizeTransitionEvent(spec.transitionEventFields ?? []);
@@ -1815,22 +1865,25 @@ export function createXStatePlaybookRuntime<TOptions>(
             );
             throw error;
           }
+          // A non-`ok` host result is a recoverable FSM failure (PBRT-47), so
+          // it is never latched as a control-plane error; it is still
+          // authoritative for the actor's error path even when the required
+          // finish emission fails or a coincident boundary abort lands.
           let resultFailure: Error | undefined;
           if (result.status !== 'ok') {
-            resultFailure = new Error(
-              result.error ??
-                `captainActor: callCaptain status "${result.status}"`,
+            resultFailure = markFsmResultFailure(
+              new Error(
+                result.error ??
+                  `captainActor: callCaptain status "${result.status}"`,
+              ),
             );
           } else if (result.finalText === undefined || result.finalText === '') {
-            resultFailure = new Error(
-              'captainActor: callCaptain returned status=ok with no finalText',
+            resultFailure = markFsmResultFailure(
+              new Error(
+                'captainActor: callCaptain returned status=ok with no finalText',
+              ),
             );
           }
-          if (resultFailure !== undefined) {
-            // The host result is authoritative even when the required finish
-            // emission fails or triggers a coincident boundary abort.
-            controlPlaneError ??= resultFailure;
-          }
           try {
             await emitTrace(
               'captain.call.finished',
@@ -1903,15 +1956,13 @@ export function createXStatePlaybookRuntime<TOptions>(
             await drainEmissions();
             const prompt = composeCaptainPrompt(input);
             const result = await boundary.callCaptain!(input, prompt, active);
-            if (result.status !== 'ok') {
-              throw new Error(
-                result.error ??
-                  `captainActor: callCaptain status "${result.status}"`,
-              );
-            }
-            if (result.finalText === undefined || result.finalText === '') {
+            // The boundary owns result validation (PBRT-47) and throws the
+            // authoritative failure itself, so a returned result is always
+            // `ok` with visible text. Assert that invariant rather than
+            // restating the failure semantics, which would drift.
+            if (result.status !== 'ok' || !result.finalText) {
               throw new Error(
-                'captainActor: callCaptain returned status=ok with no finalText',
+                'captainActor: boundary returned an unvalidated Captain result',
               );
             }
             const judgePrompt = buildCaptainJudgePrompt(
@@ -1933,7 +1984,13 @@ export function createXStatePlaybookRuntime<TOptions>(
             validateBossReplyOutput(input, output, resumableStateIds);
             return output;
           } catch (error) {
-            if (!active.aborted) controlPlaneError ??= error;
+            // A host-reported Captain result failure routes to the FSM's
+            // failure state (PBRT-47); everything else here — a drained
+            // emission failure, prompt composition, the port itself,
+            // adjudication — is control plane.
+            if (!active.aborted && !isFsmResultFailure(error)) {
+              controlPlaneError ??= error;
+            }
             throw error;
           }
         },