@sublang/playbook 17.11.0 → 18.0.0

package/reference/sdlc/code.playbook/bin/storage-manifest.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import { MAX_SESSION_CHUNK_BYTES } from './session-chunks.js';
+
+export const SESSION_STORAGE_VERSION = 8;
+const FIELDS = ['schemaVersion', 'kind', 'sessionId', 'cwd', 'state', 'createdAt', 'updatedAt', 'root'];
+const SUMMARY = ['sessionId', 'cwd', 'state', 'createdAt', 'updatedAt'];
+
+// Logical schema validation remains owned by portable-codec. This boundary
+// validates the physical representation before giving that codec its input.
+export async function decodeStoredManifest(bytes, chunks, sessionId) {
+  const value = JSON.parse(bytes);
+  if (value?.schemaVersion !== SESSION_STORAGE_VERSION) return value;
+  if (Buffer.byteLength(bytes) > MAX_SESSION_CHUNK_BYTES ||
+      !value || Array.isArray(value) || Object.keys(value).length !== FIELDS.length ||
+      FIELDS.some((key) => !Object.hasOwn(value, key)) ||
+      value.kind !== 'captain-session-storage' || value.sessionId !== sessionId) {
+    throw new Error('invalid bounded session manifest');
+  }
+  const manifest = await chunks.readJson(value.root);
+  if (manifest?.schemaVersion !== 7 || SUMMARY.some((key) => manifest[key] !== value[key])) {
+    throw new Error('bounded session summary differs from recovery');
+  }
+  return manifest;
+}
+
+export async function encodeStoredManifest(manifest, chunks) {
+  const root = await chunks.writeJson(manifest);
+  const value = { schemaVersion: SESSION_STORAGE_VERSION, kind: 'captain-session-storage' };
+  for (const key of SUMMARY) value[key] = manifest[key];
+  value.root = root;
+  const bytes = Buffer.from(`${JSON.stringify(value)}\n`);
+  if (bytes.length > MAX_SESSION_CHUNK_BYTES) throw new Error('session manifest summary exceeds file bound');
+  return bytes;
+}

package/reference/sdlc/code.playbook/session-store.d.ts

@@ -9,6 +9,8 @@ export interface SessionBundle {
   readonly manifest: Uint8Array;
   readonly replay: Uint8Array;
   readonly assets: readonly AssetFile[];
+  /** Verified physical bundle files relative to sessionsDir; replay is a logical prefix. */
+  readonly files: readonly { readonly path: string; readonly byteLength: number }[];
 }
 
 export declare const RECORDS_STREAM_VERSION: 1;

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();
             }