@sublang/playbook 1.0.0 → 2.0.0

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -66,3 +66,14 @@ playbooks:
 #      host: claude-opus
 #      participant: codex-gpt
 #    committer: host
+
+# Non-interactive `playbook run` defaults (optional). Each value is an
+# agent string <adapter>[:<model>][@<effort>]; `player` is the catch-all
+# for any required role without its own `players.<role>` entry, across
+# every playbook. Flags override per role (--player / --captain), and
+# `playbook run resume` keeps the lineup stored with the parked session.
+#run:
+#  captain: claude:claude-opus-4-8@high
+#  player: claude:claude-opus-4-8@high
+#  players:
+#    coder: claude:claude-opus-4-8[1m]@xhigh

package/reference/sdlc/discuss.playbook/discuss.fsm.d.ts

@@ -266,7 +266,7 @@ export declare const discussMachine: import("xstate").StateMachine<DiscussContex
 } | {
     type: "mixedReview";
     params: unknown;
-}, never, "done" | "failed" | "ready" | "awaitBossReply" | "hostWritesAgreement" | "commitInitialChanges" | "reviewSpecInitialCommit" | "reviewSpecHostChanges" | "reviewDrInitialCommit" | "reviewDrHostChanges" | "reviewMixedInitialCommit" | "reviewMixedHostChanges" | "hostAddressesFindings" | "participantAddressesRebuttals" | "commitReviewedChanges" | {
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "hostWritesAgreement" | "commitInitialChanges" | "reviewSpecInitialCommit" | "reviewSpecHostChanges" | "reviewDrInitialCommit" | "reviewDrHostChanges" | "reviewMixedInitialCommit" | "reviewMixedHostChanges" | "hostAddressesFindings" | "participantAddressesRebuttals" | "commitReviewedChanges" | {
     initialProposalRound: {
         host: "working" | "waiting" | "complete";
         participant: "working" | "waiting" | "complete";

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
@@ -779,8 +788,9 @@ independent cleanup evidence.
 ## Script execution
 
 Where the FSM declares the typed `script` actor from
-[gears2fsm "Setup"](gears2fsm.md#setup), the linker shall provide its
-implementation inside the emitted module.
+[gears2fsm "Setup"](gears2fsm.md#setup), the linked runtime shall provide
+its implementation through the shared factory (§Output); the linker shall
+not regenerate a script executor inside each emitted module.
 A script invocation is the one actor kind that runs without any agent:
 it makes no `callPlayer`, `callCaptain`, or `callJudge` call and needs no
 adjudication.
@@ -791,7 +801,8 @@ The provided actor shall:
   (`sh -c`), with the working directory taken from the emitted
   `PlaybookRuntimeOptions.cwd` when the caller supplies it, else the process
   working directory. The linker shall declare the optional `cwd` option on the
-  emitted options interface whenever the FSM contains a script state.
+  emitted options interface whenever the FSM contains a script state; the
+  validated option reaches the shared script actor through the spec.
 - Resolve deterministically from the child's exit status: status zero resolves
   `{ guard: <first declared guard>, exitStatus: 0 }`; any nonzero status
   resolves the second declared guard with that status. Guard selection is
@@ -816,9 +827,9 @@ them in machine context, prompts, or trace payloads.
 
 Where the FSM declares the typed `playbook` actor from
 [gears2fsm](gears2fsm.md#nested-playbook-calls), the linked runtime shall provide
-it with the shared `createNestedPlaybookBridge(...).actorLogic`; it shall not
-regenerate a second pending-call, identity-validation, or abort-cleanup
-substrate inside each linked artifact.
+it with the shared `createNestedPlaybookBridge(...).actorLogic` — wired by the
+shared factory per §Output — and shall not regenerate a second pending-call,
+identity-validation, or abort-cleanup substrate inside each linked artifact.
 Instantiate the generic bridge with the FSM-exported `PlaybookInput` type so
 XState `.provide(...)` receives the exact declared actor input rather than a
 structurally similar local type.
@@ -1122,7 +1133,9 @@ At a safe capture point it shall return a JSON-safe
 - `playerResumeTokens`: the resume-token map as a plain object
   (§PlaybookPorts contract).
 - `sequences`: the live `trace`, `turn`, `judgeCall`, `playerCall`, and
-  `playbookCall` counters.
+  `playbookCall` counters, plus `captainCall` when the runtime supports direct
+  Captain calls. `captainCall` remains optional under schema version `1` for
+  backward compatibility; a direct-Captain-capable runtime shall persist it.
 - `state`: the current normalized state descriptor.
 - `pendingBossQuestions`: the pending Boss question(s) from FSM context as
   a list of `{ questionId, player, question, sourceItem? }`, empty when the
@@ -1141,7 +1154,9 @@ module identity — that the factory constructing this runtime still
 belongs to the snapshot's playbook — is likewise the host's check to
 make before calling `restore`.
 `restore` shall bind the session, restore the resume-token map, the
-sequence counters, and the prior-state descriptor from the snapshot,
+sequence counters (using the persisted global `trace` counter as a
+collision-safe floor for an absent legacy `captainCall`), and the
+prior-state descriptor from the snapshot,
 construct the actor with the persisted `machine` snapshot, and start it
 with root inspection emissions suppressed so rehydration emits no
 `session.started` trace, no transition trace, and no human status — the
@@ -1227,7 +1242,19 @@ The `playbook.trace` copies are the host-agnostic runtime-boundary record requir
 
 ## Output
 
-The link compiler emits **one** TypeScript module that:
+The link compiler emits **one thin** TypeScript module per playbook.
+The FSM-interpreter machinery — actor wiring, boundary tracing, Boss-event
+mapping, adjudication, script execution, nested-playbook bridging, session
+lifecycle, abort handling, and the optional parked-session snapshot
+capability — is not regenerated per artifact: it ships once as the shared
+`createXStatePlaybookRuntime(machine, spec)` factory exported by
+`@sublang/playbook/xstate-runtime`, and the emitted module hands its FSM and
+a small per-playbook `spec` to that factory. Every behavioral section of
+this definition still binds the emitted module's runtime; the shared factory
+is how the emitted module satisfies them, so a runtime fix ships as a
+package release instead of a re-link of every artifact.
+
+The emitted module:
 
 - Imports the FSM artifact by relative path with an extension-bearing
   runtime specifier. When the linked TypeScript is part of a package that
@@ -1240,34 +1267,82 @@ The link compiler emits **one** TypeScript module that:
   that strip cleanly, no constructor parameter properties, `enum`s, or
   namespaces — so a host running under type stripping loads it
   directly.
-- Imports XState's actor primitives (`createActor`, `fromPromise`,
-  `setup`'s `.provide`).
-- Imports `PQueue` from `p-queue` for its single serialized emission channel.
-- Imports the FSM's exported machine/actor input and output types and uses
-  those exact types in `.provide(...)`; it shall not redeclare look-alike
-  Captain, player, playbook, question, or output contracts beside the linked
-  runtime.
-- Imports the applicable shared helpers from the extension-bearing
-  `xstate-runtime.js` sibling of the resolved shared `--link` contract module,
-  with that sibling path relativized from the emitted artifact exactly as the
-  contract import is. Every runtime uses `assertJsonSafe`, `snapshotJsonValue`,
-  `snapshotPlaybookSession`, `normalizeError`,
-  `normalizePlaybookSnapshot`, and `waitForPlaybookQuiescence`; it additionally
-  imports `combineAbortSignals`, result validators, and
-  `createNestedPlaybookBridge` only when its actor and composition paths need
-  them. It shall use those helpers instead of emitting weaker local JSON,
-  error, snapshot, nested-call, or imperative-wait implementations.
-- Exports `createPlaybookRuntime` and the typed `PlaybookRuntimeOptions`
-  interface for that playbook.
+- Imports `createXStatePlaybookRuntime` (plus any shared strategy defaults
+  its `_internal` surface re-exports) from the shared engine module through
+  its bare package specifier `@sublang/playbook/xstate-runtime`, and the
+  contract types through `@sublang/playbook/runtime`. It shall not copy,
+  inline, or re-derive interpreter machinery — actor bridges, trace
+  emission, judge-JSON recovery, lifecycle guards — beside the factory
+  call, and shall not import `xstate`, `p-queue`, or `node:child_process`
+  itself; those are the shared engine's dependencies.
+- Declares and exports the typed `PlaybookRuntimeOptions` interface for that
+  playbook, derived from every required FSM input field that is not supplied
+  by `PlaybookSession` or another linker-owned source (§PlaybookRuntime
+  contract), plus the optional `cwd` option whenever the FSM contains a
+  `script` state (§Script execution).
+- Supplies the spec's `snapshotOptions` with the same options-validation
+  semantics previously generated inline: validate and JSON-snapshot the
+  caller's options, rejecting undeclared keys and non-conforming values, so
+  the factory binds an immutable options record before constructing any
+  actor.
+- Supplies in `spec` only what the factory cannot read from the FSM
+  artifact's own data: the deterministic textual entry event where
+  §Boss-event mapping prescribes deterministic entry; compact `bossEvents`
+  metadata for each additional Boss-union arm whose exact required/optional
+  judge fields, runtime-owned text fields, or closed string values disappear
+  under TypeScript erasure; `placeholderFields` only for authored token/field
+  exceptions not covered by the canonical kebab-token-to-camel-field mapping
+  and the canonical `<#>` → `irNumber` special case; the
+  transition-event payload fields the FSM's Boss union declares; a
+  non-default player binding where the linker inputs supplied one; and any
+  per-playbook strategy override (classifier, prompt composers,
+  required-field extraction, status formatting) an earlier section of this
+  definition requires for that playbook. The metadata shall keep the shared
+  classifier's reply contract exactly flat `{ type, ...declaredFields }` and
+  distinguish judge-authored routing fields from exact-text fields the
+  runtime attaches itself. Everything else — player/script/captain/nested actor
+  provisioning, prompt composition, classification, adjudication, statuses,
+  resumable-state derivation — comes from the factory's generic defaults,
+  which implement the behavioral sections of this definition.
+
+  ```ts
+  interface XStateBossEventFieldSpec {
+    source: 'judge' | 'text';
+    required?: boolean;
+    values?: readonly string[];
+  }
+
+  interface XStateBossEventSpec {
+    type: string;
+    fields?: Readonly<Record<string, XStateBossEventFieldSpec>>;
+  }
+
+  bossEvents?: readonly XStateBossEventSpec[];
+  placeholderFields?: Readonly<Record<string, string>>;
+  ```
+
+  Supplied `bossEvents` metadata shall merge with, and shall not replace or
+  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
   needs — at least the player-prompt and Captain-prompt composers
-  (`composePlayerPrompt` and `composeCaptainPrompt`) — so
+  (`composePlayerPrompt` and `composeCaptainPrompt`), which may re-export
+  the shared defaults when the spec does not override composition — so
   compilation-correctness tests can exercise composition without a host.
 - Holds no host-specific types and no host primitive calls. The runtime
-  speaks only `PlaybookPorts` for every agent and host concern; the sole
-  exception is `node:child_process`, imported only when the FSM declares a
-  `script` actor, so §Script execution can run its deterministic commands
-  locally.
+  speaks only `PlaybookPorts` for every agent and host concern; the
+  `node:child_process` dependency of §Script execution lives in the shared
+  factory, not in the emitted module.
 - Records the linker inputs (FSM path, player binding, strategies) in a
   top-of-file header comment so the file is reproducible from the same
   inputs.
@@ -1276,12 +1351,12 @@ The link compiler emits **one** TypeScript module that:
   `PlaybookTraceEvent`,
   `PlaybookCallRequest`, `PlaybookCallResult`, `PlaybookCallStart`,
   `PlaybookStateValue`, `PlaybookState`, `PlaybookRunResult`,
-  `PlaybookRuntime`, `PlaybookRuntimeFactory`) from a single shared
+  `PlaybookRuntime`, `PlaybookRuntimeFactory`) from the single shared
   type-only module instead of redefining them, and re-exports the names
   its consumers import, so every linked playbook shares one contract
-  definition. The shared module imports no FSM or host types, so the
+  definition. The shared modules import no FSM or host types, so the
   dependency runs one way — from each linked module to the shared
-  contract, never the reverse.
+  engine and contract, never the reverse.
 
 When a co-located integration test for the linked runtime already exists, the
 link compiler shall run it before reporting success and treat any failure as a

package/slc/optimize.md

@@ -56,9 +56,9 @@ For each eligible item, the pass shall:
 
 - Keep the item's ID, heading form, and condition text unchanged.
 - Replace the acting clause with the literal script form `Captain shall run:`.
-  Like guard names, the script clause is fixed machine syntax and stays in
-  this exact English form even when the surrounding item text is in another
-  language.
+  Like guard names, the script clause is fixed machine syntax [[1]] and
+  stays in this exact English form even when the surrounding item text is
+  in another language.
 - Replace the blockquoted prompt with the exact POSIX shell script that
   performs the behavior, static text only.
 - Emit exactly two `Results:` bullets per
@@ -86,3 +86,7 @@ with no `## Optimizations` section.
 - Reordering, merging, splitting, or deleting items.
 - Any change to prompts, conditions, or result contracts of items the pass
   does not rewrite.
+
+## References
+
+[1]: GEARS definition shipped by the installed `@sublang/spex` package: `@sublang/spex/scaffold/specs/meta.md` (English) and `@sublang/spex/scaffold/i18n/zh/specs/meta.md` (Chinese); canonical renditions [GEARS: AI-Ready Spec Syntax](https://sublang.ai/ref/gears-ai-ready-spec-syntax) (en) and [GEARS：面向 AI 的规约语法](https://sublang.ai/zh/ref/gears-ai-ready-spec-syntax) (zh)

package/slc/text2gears.md

@@ -287,7 +287,13 @@ Results:
 - `failed`: The command exited with a nonzero status.
 ```
 
-Target should be written in the same language as Source.
+Target shall be written in the same language as Source: an item's condition
+prose, acting prompts, and result descriptions follow the Source language,
+read per the matching localization of the GEARS definition [[1]].
+The four `Captain shall` acting-clause forms defined above (direct,
+delegated, nested playbook call, and script), guard names, and the
+`Players:` and `Results:` labels are fixed machine syntax and stay in this
+exact English form regardless of Source language.
 
 ## Transformation-spec sources
 
@@ -324,4 +330,4 @@ Dead branches mislead readers and downstream phases.
 
 ## References
 
-[1]: [GEARS syntax](/specs/meta.md#item-syntax)
+[1]: GEARS definition shipped by the installed `@sublang/spex` package: `@sublang/spex/scaffold/specs/meta.md` (English) and `@sublang/spex/scaffold/i18n/zh/specs/meta.md` (Chinese); canonical renditions [GEARS: AI-Ready Spec Syntax](https://sublang.ai/ref/gears-ai-ready-spec-syntax) (en) and [GEARS：面向 AI 的规约语法](https://sublang.ai/zh/ref/gears-ai-ready-spec-syntax) (zh)

package/src/runtime.d.ts

@@ -143,6 +143,7 @@ export interface PlaybookRuntimeSnapshot {
         judgeCall: number;
         playerCall: number;
         playbookCall: number;
+        captainCall?: number;
     };
     state: PlaybookState;
     pendingBossQuestions: readonly PlaybookPendingBossQuestion[];

package/src/runtime.ts

@@ -200,6 +200,7 @@ export interface PlaybookRuntimeSnapshot {
     judgeCall: number;
     playerCall: number;
     playbookCall: number;
+    captainCall?: number;
   };
   state: PlaybookState;
   pendingBossQuestions: readonly PlaybookPendingBossQuestion[];

package/src/xstate-playbook-runtime.d.ts

@@ -0,0 +1,201 @@
+import type { AnyStateMachine, EventObject, PromiseActorLogic } from 'xstate';
+import type { CaptainResult, JsonValue, PlaybookPorts, PlaybookRuntimeFactory, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
+export interface PlaybookPendingBossQuestionContext {
+    questionId: string;
+    resumeStateId: string;
+    sourceItem: string;
+    player: string;
+    question: string;
+}
+export interface PlaybookPlayerInput {
+    stateId: string;
+    player: string;
+    sourceItem: string;
+    prompt: string;
+    result: Readonly<Record<string, string>>;
+    pendingBossQuestion?: {
+        readonly question: string;
+    };
+    bossReply?: string;
+}
+export interface PlaybookCaptainInput {
+    stateId: string;
+    sourceItem: string;
+    prompt: string;
+    result: Readonly<Record<string, string>>;
+    allowedTools?: readonly string[];
+    pendingBossQuestion?: {
+        readonly question: string;
+    };
+    bossReply?: string;
+}
+export interface PlaybookScriptInput {
+    stateId: string;
+    sourceItem: string;
+    command: string;
+    result: Readonly<Record<string, string>>;
+}
+/** Adjudicated actor output: the selected guard plus payload fields. */
+export type PlaybookActorOutput = Record<string, unknown> & {
+    guard: string;
+};
+export type JudgePurpose = 'boss-input-classification' | 'player-output-adjudication' | 'captain-output-adjudication';
+/**
+ * Traced runtime boundary used by the provided actors. The factory's runtime
+ * implements it; standalone helpers accept it optionally so verification can
+ * exercise composition/adjudication without a live runtime.
+ */
+export interface RuntimeBoundaryCalls {
+    callPlayer(input: PlaybookPlayerInput, playerId: string, prompt: string, signal: AbortSignal): Promise<PlayerResult>;
+    callJudge(purpose: JudgePurpose, stateId: string | undefined, prompt: string, signal: AbortSignal): Promise<string>;
+    callCaptain?(input: PlaybookCaptainInput, prompt: string, signal: AbortSignal): Promise<CaptainResult>;
+}
+export interface ScheduledStatus {
+    message: string;
+    data?: JsonValue;
+}
+export interface XStateBossEventFieldSpec {
+    /** The judge supplies routing data; the runtime supplies exact Boss text. */
+    source: 'judge' | 'text';
+    /** Judge-authored fields are optional unless explicitly required. */
+    required?: boolean;
+    /** Optional closed set for a string-valued judge field. */
+    values?: readonly string[];
+}
+export interface XStateBossEventSpec {
+    type: string;
+    fields?: Readonly<Record<string, XStateBossEventFieldSpec>>;
+}
+export declare const BOSS_REPLY_ERRORS: {
+    readonly missingQuestion: "needsBossReply outcome missing 'question' field";
+    readonly unregisteredState: (stateId: string) => string;
+};
+export interface XStatePlaybookRuntimeSpec<TOptions> {
+    /** Diagnostic label used in internal invariant errors. Default 'playbook'. */
+    label?: string;
+    /** Validate and JSON-snapshot the caller's per-run options. */
+    snapshotOptions: (value: unknown) => TOptions;
+    /** Derive the FSM machine input from validated options. Default: identity. */
+    machineInput?: (options: TOptions, session: PlaybookSession) => unknown;
+    /**
+     * Deterministic textual entry event (slc/link.md §Boss-event mapping):
+     * where the ready or reconstructed terminal machine accepts exactly one
+     * ordinary textual entry event, send it without a judge call, carrying the
+     * exact Boss text in `textField`. Absent: every non-empty turn classifies.
+     */
+    entryEvent?: {
+        type: string;
+        textField: string;
+    };
+    /**
+     * Exact flat Boss-event contracts whose non-text fields the judge may
+     * select. `entryEvent` and scalar `BOSS_REPLY` contracts are supplied by
+     * the factory; linkers emit entries here for additional typed events such
+     * as `BOSS_INTERRUPT` when their erased payload cannot be recovered from
+     * the XState machine alone.
+     */
+    bossEvents?: readonly XStateBossEventSpec[];
+    /** Boss-input classifier override; default: generic parked-state classifier. */
+    classifyBossText?: (text: string, ports: PlaybookPorts, signal: AbortSignal, snapshotOrState: unknown, boundary?: RuntimeBoundaryCalls) => Promise<EventObject | undefined>;
+    /** Status line emitted after classification names an event. Default: none. */
+    classificationStatus?: (event: EventObject) => string | undefined;
+    /** Map a player-invoking state's input to the host player id. Default: lowercased player name. */
+    resolvePlayerId?: (input: PlaybookPlayerInput, options: TOptions) => string;
+    /** Compose the player prompt. Default: continuation blocks + `<field>` placeholder substitution. */
+    composePlayerPrompt?: (input: PlaybookPlayerInput) => string;
+    /** Compose the direct-Captain prompt. Default: continuation blocks + placeholder substitution with deterministic JSON rendering. */
+    composeCaptainPrompt?: (input: PlaybookCaptainInput) => string;
+    /** Linker-known exceptions to the default kebab-token → camel-field mapping. */
+    placeholderFields?: Readonly<Record<string, string>>;
+    /** Adjudicator prompt for delegated players. Default: generic guard menu. */
+    buildJudgePrompt?: (input: PlaybookPlayerInput, finalText: string) => string;
+    /** Required-payload-field extraction from a `result` description. Default: bilingual `Output shall include` clause scan. */
+    extractRequiredFields?: (description: string) => string[];
+    /** Required fields carried verbatim from the player's finalText instead of judge JSON. Default: none. */
+    verbatimPayloadFields?: ReadonlySet<string>;
+    /** States that may suspend for a Boss reply. Default: targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
+    resumableStateIds?: ReadonlySet<string>;
+    /** Human status lines for a root transition. Default: entry lines with question/failure surfacing. */
+    statusesForState?: (state: PlaybookState, context: Record<string, unknown>, event: unknown) => readonly ScheduledStatus[];
+    /** Detached JSON-safe transition-event descriptor. Default: `type` + `transitionEventFields` strings + validated output + normalized error. */
+    normalizeTransitionEvent?: (event: unknown) => JsonValue | undefined;
+    /** String payload fields the default transition-event descriptor copies. */
+    transitionEventFields?: readonly string[];
+    /** Working directory for `script` actors. Default: the validated options' string `cwd`, else the process working directory. */
+    scriptCwd?: (options: TOptions) => string | undefined;
+}
+/** Strip a single Markdown code fence that wraps the whole string. */
+export declare function stripCodeFence(text: string): string;
+export declare function extractJsonValue(text: string, start: number, repair: boolean): string | undefined;
+export declare function parseJudgeJson(raw: string): unknown;
+export declare function normalizeErrorCompact(err: unknown): {
+    name: string;
+    message: string;
+} | undefined;
+export declare function normalizeErrorFull(err: unknown): {
+    name: string;
+    message: string;
+    stack?: string;
+} | undefined;
+/** Read the FSM context's single pending Boss question, when well-formed. */
+export declare function pendingBossQuestionFromContext(context: Record<string, unknown>): PlaybookPendingBossQuestionContext | undefined;
+/**
+ * Default player-prompt composer (slc/link.md §Player prompt composition).
+ * One callback-based pass substitutes each `<fieldName>` placeholder whose
+ * typed input field is a string; replacement text is literal, and
+ * placeholder-looking text inside a value is never re-substituted. The
+ * continuation preamble and Q/A blocks precede the domain body on resume.
+ */
+export declare function defaultComposePlayerPrompt(input: PlaybookPlayerInput, placeholderFields?: Readonly<Record<string, string>>): string;
+/**
+ * Default direct-Captain prompt composer (slc/link.md §Captain prompt
+ * composition). Placeholder substitution is presence-based: string fields
+ * substitute verbatim; JSON-safe arrays/objects render as deterministic JSON
+ * with lexicographically sorted keys at every depth.
+ */
+export declare function defaultComposeCaptainPrompt(input: PlaybookCaptainInput, placeholderFields?: Readonly<Record<string, string>>): string;
+/** Default player binding: each player to its lowercased name. */
+export declare function defaultResolvePlayerId(input: PlaybookPlayerInput): string;
+/**
+ * Default required-field extraction (slc/link.md §Captain adjudication).
+ * Limited to the description's `Output shall include` / `输出应包含` clause;
+ * recognizes both the bare backticked name and the annotated `name: <...>`
+ * form.
+ */
+export declare function defaultExtractRequiredFields(description: string): string[];
+/** Default delegated-player adjudicator prompt. */
+export declare function defaultBuildJudgePrompt(input: PlaybookPlayerInput, finalText: string): string;
+export interface PlayerAdjudicationSpec {
+    buildJudgePrompt?: (input: PlaybookPlayerInput, finalText: string) => string;
+    extractRequiredFields?: (description: string) => string[];
+    verbatimPayloadFields?: ReadonlySet<string>;
+}
+/**
+ * LLM-judge adjudicator for delegated players. Coerces the player's
+ * finalText into one of the state's declared guards, extracts every required
+ * payload field from the judge reply, and fails loudly (throws) on a missing
+ * JSON object, an undeclared guard, or a missing required field. Fields in
+ * `verbatimPayloadFields` carry `finalText.trim()` rather than round-tripping
+ * long-form prose through judge JSON.
+ */
+export declare function adjudicatePlayerOutput(spec: PlayerAdjudicationSpec, input: PlaybookPlayerInput, finalText: string, ports: PlaybookPorts, signal: AbortSignal, boundary?: RuntimeBoundaryCalls): Promise<PlaybookActorOutput>;
+export interface PlayerBridgeSpec {
+    resolvePlayerId: (input: PlaybookPlayerInput) => string;
+    composePlayerPrompt: (input: PlaybookPlayerInput) => string;
+    adjudication: PlayerAdjudicationSpec;
+    resumableStateIds: ReadonlySet<string>;
+}
+export declare function createPlayerBridge(spec: PlayerBridgeSpec, ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined, boundary?: RuntimeBoundaryCalls, onControlPlaneError?: (error: unknown) => void): PromiseActorLogic<PlaybookActorOutput, PlaybookPlayerInput>;
+/** Targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
+export declare function resumableStateIdsFromMachine(machine: AnyStateMachine): ReadonlySet<string>;
+/**
+ * Build a `PlaybookRuntimeFactory` that interprets the given FSM artifact
+ * under the slc/link.md contract. The factory provides every actor kind the
+ * machine declares — `player`, `script`, `captain`, and nested `playbook`
+ * (literal and dynamic) — and implements the full runtime lifecycle including
+ * the optional parked-session snapshot capability (DR-014).
+ *
+ * Scope: single-region root machines (each snapshot exposes exactly one
+ * playbook state id). Parallel-region FSMs keep their own linked runtimes.
+ */
+export declare function createXStatePlaybookRuntime<TOptions>(machine: AnyStateMachine, spec: XStatePlaybookRuntimeSpec<TOptions>): PlaybookRuntimeFactory<TOptions>;