@sublang/playbook 17.11.0 → 17.11.1

package/docs/releases/17.11.1-preparation.md

@@ -0,0 +1,37 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Playbook 17.11.1 preparation
+
+This record captures the initial preparation checkpoint on 2026-10-21,
+before tagging or release. Subsequent gate outcomes are recorded separately.
+
+This patch release carries the classified-entry lifecycle fix from
+`f31250de548d78f2576f753e5f564e1988604b6f` ([IR-116](https://github.com/sublang-ai/playbook/blob/main/specs/intents/116-classified-entry-lifecycle.md)).
+It preserves required classification fields and exact Boss text on terminal
+restart, and clears earlier run exchanges only for a valid new entry.
+Refused entries, replies and global interrupts retain the current run.
+Dependencies and the locked Cligent 0.36.0 binding are unchanged.
+
+The fix candidate passed the canonical model-free integration checks: build,
+spec lint, 2,842 main tests with 24 skips, the separate 146 capability tests,
+link checks and SPDX checks. The shared-runtime segment includes 261 tests.
+Those results precede this version/changelog/record-only preparation; they do
+not establish packed or real-agent acceptance for 17.11.1.
+The historical failed broad run remains qualified in IR-116.
+
+At that checkpoint, the remaining pre-tag release gates were the full canonical
+`pnpm smoke:release` followed by `pnpm test:acceptance`, compiled-sibling and CI
+verification, and review/commit/push to main under
+[release-10](https://github.com/sublang-ai/playbook/blob/main/specs/packages/release.md#release-10).
+Neither smoke nor real-agent acceptance had run at that checkpoint.
+The real-agent gate must request `gpt-6.1-sol` and `claude-opus-5-5` through
+`PLAYBOOK_ACCEPTANCE_CODEX_MODEL` and `PLAYBOOK_ACCEPTANCE_CLAUDE_MODEL`.
+Requested model names alone do not independently identify the serving backend.
+
+This change does not alter interactive presentation/layout or the declared or
+locked Cligent version, so it does not itself trigger the conditional manual
+presentation check in [release-26](https://github.com/sublang-ai/playbook/blob/main/specs/packages/release.md#release-26).
+Reassess that condition if the release inputs change.
+Raw live logs and retained scratch evidence remain private outside the repository.
+No publication, installation or adoption is claimed by this record.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.11.0",
+  "version": "17.11.1",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",

package/slc/link.md

@@ -1099,7 +1099,7 @@ Before the composer's result it places, in order:
 - once the run has heard a Boss reply, the run's Boss exchanges so far, each a `? ⟶` line and the verbatim question, then a `Boss ⟶` line and the verbatim reply, whatever the role and whether or not the Source retains them, leaving out the one exchange the call's own continuation carries;
 - for a call after a Boss reply, the marked verbatim question, only for a fresh conversation, and the marked verbatim reply.
 
-A run begins at the entry event or a finished machine's restart, and its exchanges travel in the runtime snapshot as `bossExchanges`.
+A run begins at a deterministic entry or an event declared on the initial parked state itself, including a classified entry from recoverable failure, or at a finished machine's restart; a reply, global interrupt alone, or refused event starts no run. Its exchanges travel in the runtime snapshot as `bossExchanges`.
 
 The runtime chooses the compact prompt only after selecting a conversation token and carries the complete prompt as optional `PlayerCallOptions.freshPrompt`.
 A host starting fresh after a definite pre-execution token rejection uses `freshPrompt`, when supplied, instead of the compact prompt.
@@ -1181,6 +1181,15 @@ host's teardown resolution — and invokes no classifier judge call; the exact
 original text still rides only the runtime-owned textual payload field.
 All other non-empty turns shall use `callJudge` only to choose one of the FSM's
 event kinds and non-text routing fields, or no FSM action.
+An entry requiring a judge-selected routing field therefore omits deterministic
+`entryEvent` metadata and declares its exact fields through `bossEvents`.
+The shared engine derives that entry from the initial parked state's own
+transitions and resets the run's exchanges when it dispatches the entry.
+At a terminal state, the classifier uses those initial entry transitions and
+their guards under detached bound machine input. This evaluates pure context
+and assignment initialization under the supported FSM contract; it does not
+run returned executable actions or start actors. Global interrupts and reply
+events are not terminal entries.
 The classifier prompt shall include the exact, unmodified `turn.text` in a
 clearly labelled Boss-message block so the judge can make that choice. Omitting
 the message makes a parked-state classifier unable to distinguish an answer,
@@ -1849,9 +1858,9 @@ The `PlaybookRuntime` shall:
      cannot be recovered or validated, emit the one recovery status required
      by §Boss-event mapping, send no event, leave the actor unchanged, and
      return `no-action` after the ordinary settled boundary drains.
-  3. Only after classification produces a real event, if the actor is in a
+  3. Only after classification produces a valid initial entry event, if the actor is in a
      `final` state, dispose and reconstruct it — `final` is terminal and cannot
-     accept new events. `NO_ACTION`, classifier rejection, and malformed
+     accept new events. `NO_ACTION`, classifier rejection, invalid initial guards, and malformed
      classification shall leave a terminal actor untouched.
   4. Bind the active public-boundary signal and send the classified event to
      the actor.

package/src/xstate-playbook-runtime.js

@@ -19,7 +19,7 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import PQueue from 'p-queue';
-import { createActor, fromPromise } from 'xstate';
+import { createActor, fromPromise, initialTransition } from 'xstate';
 import { ACCEPTED_OUTCOME_ACTION_TYPE, createAcceptedOutcomeConsumer, } from './accepted-outcome.js';
 import { assertPlaybookFailureCause } from './runtime.js';
 import { assertPlaybookRuntimeSnapshot, assertPlaybookEffectLedger, attachPlaybookFailureCause, combineAbortSignals, createNestedPlaybookBridge, describePlaybookSemanticValueShape, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, snapshotJsonValue, snapshotPlaybookSession, isPlaybookEffectLedgerMonotonicExtension, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, validateCaptainResult, validatePlayerResult, waitForPlaybookQuiescence, } from './xstate-runtime.js';
@@ -2490,7 +2490,7 @@ function activeStateIdsOf(snapshotOrState) {
 }
 function makeDefaultClassifyBossText(machine, entryEvent, bossEvents, parallelProfile) {
     const contracts = defaultBossEventSpecs(machine, entryEvent, bossEvents);
-    return async (text, ports, signal, snapshotOrState, boundary) => {
+    return async (text, ports, signal, snapshotOrState, boundary, allowedEventTypes) => {
         const trimmed = text.trim();
         if (trimmed === '')
             return undefined;
@@ -2523,6 +2523,7 @@ function makeDefaultClassifyBossText(machine, entryEvent, bossEvents, parallelPr
         const severalPending = pendingQuestions.length > 1;
         const applicable = [...contracts.values()]
             .filter((contract) => configuredTypes.has(contract.type) &&
+            (allowedEventTypes === undefined || allowedEventTypes.has(contract.type)) &&
             (contract.type !== 'BOSS_REPLY' || pendingQuestions.length > 0))
             .map((contract) => contract.type === 'BOSS_REPLY' && severalPending
             ? {
@@ -2807,7 +2808,9 @@ export function createXStatePlaybookRuntime(machine, spec) {
     // 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 ?? [], parallelProfile);
-    const classifyBossText = spec.classifyBossText ?? derivedClassifyBossText;
+    // Initial-state-owned events describe new runs independently of whether
+    // their payload is deterministic. Root interrupts are deliberately absent.
+    const initialEntryEventTypes = new Set((machine.root.initial.target ?? []).flatMap((node) => Object.keys(node.config.on ?? {}).filter((type) => type !== 'BOSS_REPLY' && type !== 'NO_ACTION')));
     const normalizeTransitionEvent = spec.normalizeTransitionEvent ??
         makeDefaultNormalizeTransitionEvent(spec.transitionEventFields ?? []);
     const statusesForState = spec.statusesForState ??
@@ -3619,7 +3622,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
         }
         /** DR-090 §1: an entry event begins a new run, with no exchanges yet. */
         function beginRunIfEntry(event) {
-            if (spec.entryEvent !== undefined && event.type === spec.entryEvent.type) {
+            if ((event.type === spec.entryEvent?.type || initialEntryEventTypes.has(event.type)) &&
+                snapshotCan(actor?.getSnapshot(), event)) {
                 bossExchanges = [];
             }
         }
@@ -7780,7 +7784,31 @@ export function createXStatePlaybookRuntime(machine, spec) {
                                 };
                             }
                             else {
-                                event = await classifyBossText(text, runtimePorts, signal, snapshot, boundary, boundOptions);
+                                // Classify a finished run against its fresh entry context,
+                                // without starting/replacing an actor or running the returned
+                                // executable actions. Pure context/assign initialization is
+                                // evaluated under the supported FSM contract.
+                                // Detach the input so pure initialization cannot mutate the
+                                // current actor or the host's bound input through an alias.
+                                const input = terminal
+                                    ? machineInput(boundOptions, requireSession())
+                                    : undefined;
+                                const classificationSnapshot = terminal
+                                    ? initialTransition(machine, input === undefined
+                                        ? undefined
+                                        : snapshotJsonValue(input, 'initial classification input'))[0]
+                                    : snapshot;
+                                event = spec.classifyBossText !== undefined
+                                    ? await spec.classifyBossText(text, runtimePorts, signal, classificationSnapshot, boundary, boundOptions)
+                                    : await derivedClassifyBossText(text, runtimePorts, signal, classificationSnapshot, boundary, terminal ? initialEntryEventTypes : undefined);
+                                if (terminal &&
+                                    event !== undefined &&
+                                    (!initialEntryEventTypes.has(event.type) ||
+                                        (spec.classifyBossText !== undefined &&
+                                            !snapshotCan(classificationSnapshot, event)))) {
+                                    await runtimePorts.emitStatus('Classifier selected an invalid initial entry event');
+                                    event = undefined;
+                                }
                             }
                             signal.throwIfAborted();
                         }

package/src/xstate-playbook-runtime.ts

@@ -20,7 +20,7 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import PQueue from 'p-queue';
-import { createActor, fromPromise } from 'xstate';
+import { createActor, fromPromise, initialTransition } from 'xstate';
 import type {
   AnyStateMachine,
   EventObject,
@@ -3915,9 +3915,10 @@ function makeDefaultClassifyBossText(
   signal: AbortSignal,
   snapshotOrState: unknown,
   boundary?: RuntimeBoundaryCalls,
+  allowedEventTypes?: ReadonlySet<string>,
 ) => Promise<EventObject | undefined> {
   const contracts = defaultBossEventSpecs(machine, entryEvent, bossEvents);
-  return async (text, ports, signal, snapshotOrState, boundary) => {
+  return async (text, ports, signal, snapshotOrState, boundary, allowedEventTypes) => {
     const trimmed = text.trim();
     if (trimmed === '') return undefined;
     const state = classifierState(snapshotOrState);
@@ -3959,6 +3960,7 @@ function makeDefaultClassifyBossText(
       .filter(
         (contract) =>
           configuredTypes.has(contract.type) &&
+          (allowedEventTypes === undefined || allowedEventTypes.has(contract.type)) &&
           (contract.type !== 'BOSS_REPLY' || pendingQuestions.length > 0),
       )
       .map((contract): XStateBossEventSpec =>
@@ -4407,9 +4409,15 @@ export function createXStatePlaybookRuntime<
     spec.bossEvents ?? [],
     parallelProfile,
   );
-  const classifyBossText: NonNullable<
-    XStatePlaybookRuntimeSpec<TOptions>['classifyBossText']
-  > = spec.classifyBossText ?? derivedClassifyBossText;
+  // Initial-state-owned events describe new runs independently of whether
+  // their payload is deterministic. Root interrupts are deliberately absent.
+  const initialEntryEventTypes = new Set(
+    (machine.root.initial.target ?? []).flatMap((node) =>
+      Object.keys(node.config.on ?? {}).filter(
+        (type) => type !== 'BOSS_REPLY' && type !== 'NO_ACTION',
+      ),
+    ),
+  );
   const normalizeTransitionEvent =
     spec.normalizeTransitionEvent ??
     makeDefaultNormalizeTransitionEvent(spec.transitionEventFields ?? []);
@@ -5558,7 +5566,10 @@ export function createXStatePlaybookRuntime<
 
     /** DR-090 §1: an entry event begins a new run, with no exchanges yet. */
     function beginRunIfEntry(event: EventObject): void {
-      if (spec.entryEvent !== undefined && event.type === spec.entryEvent.type) {
+      if (
+        (event.type === spec.entryEvent?.type || initialEntryEventTypes.has(event.type)) &&
+        snapshotCan(actor?.getSnapshot(), event)
+      ) {
         bossExchanges = [];
       }
     }
@@ -10991,14 +11002,52 @@ export function createXStatePlaybookRuntime<
                   [spec.entryEvent.textField]: text,
                 };
               } else {
-                event = await classifyBossText(
-                  text,
-                  runtimePorts!,
-                  signal,
-                  snapshot,
-                  boundary,
-                  boundOptions,
-                );
+                // Classify a finished run against its fresh entry context,
+                // without starting/replacing an actor or running the returned
+                // executable actions. Pure context/assign initialization is
+                // evaluated under the supported FSM contract.
+                // Detach the input so pure initialization cannot mutate the
+                // current actor or the host's bound input through an alias.
+                const input = terminal
+                  ? machineInput(boundOptions, requireSession())
+                  : undefined;
+                const classificationSnapshot = terminal
+                  ? initialTransition(
+                      machine,
+                      input === undefined
+                        ? undefined
+                        : snapshotJsonValue(input, 'initial classification input'),
+                    )[0]
+                  : snapshot;
+                event = spec.classifyBossText !== undefined
+                  ? await spec.classifyBossText(
+                      text,
+                      runtimePorts!,
+                      signal,
+                      classificationSnapshot,
+                      boundary,
+                      boundOptions,
+                    )
+                  : await derivedClassifyBossText(
+                      text,
+                      runtimePorts!,
+                      signal,
+                      classificationSnapshot,
+                      boundary,
+                      terminal ? initialEntryEventTypes : undefined,
+                    );
+                if (
+                  terminal &&
+                  event !== undefined &&
+                  (!initialEntryEventTypes.has(event.type) ||
+                    (spec.classifyBossText !== undefined &&
+                      !snapshotCan(classificationSnapshot, event)))
+                ) {
+                  await runtimePorts!.emitStatus(
+                    'Classifier selected an invalid initial entry event',
+                  );
+                  event = undefined;
+                }
               }
               signal.throwIfAborted();
             }