@sublang/playbook 5.0.0 → 7.0.0

package/slc/gears2fsm.md

@@ -167,6 +167,7 @@ The default never applies to an item carrying a `Results:` label, and it does
 not license inferring any richer contract from prose.
 The item's blockquote alone becomes `invoke.input.prompt`; the `Results:`
 label and bullets shall never enter that prompt.
+A `>` that remains at the start of a prompt line after removing the outer GEARS blockquote marker is literal quoted-context content and shall remain in `invoke.input.prompt` unchanged.
 Each result description shall name every additional output field its accepting
 guard requires, using the exact case-sensitive property names. For example, a
 delegation or continuing-call description whose guard reads the planned child
@@ -243,13 +244,15 @@ Each state shall declare:
 - a stable `id` (for `#id` targeting and Boss interrupts);
 - an intuitive state key (the property name under `states: { ... }`);
 - a one-line `description` (for inspector tools and documentation);
-- JSON-safe `meta: { playbook: { stateId, description } }` repeating its
-  stable id and description so linked runtimes can discover active public
-  identities through `snapshot.getMeta()` without private XState nodes;
+- JSON-safe `meta: { playbook: { stateId, description, player? } }` repeating
+  its stable id and description so linked runtimes can discover active public
+  identities through `snapshot.getMeta()` without private XState nodes. A
+  delegated-player state shall also carry the exact source player in
+  `meta.playbook.player`; every other state shall omit `player`;
 - if it invokes the direct `captain` actor: `invoke.input` carrying
   `sourceItem`, `prompt`, and `result` (per [Setup](#setup));
 - if it invokes the delegated `player` actor: `invoke.input` additionally
-  carrying `player`;
+  carrying the same source-derived `player` as `meta.playbook.player`;
 - if it invokes the `script` actor: `invoke.input` carrying `stateId`,
   `sourceItem`, `command`, and `result` (per [Setup](#setup)) — no `prompt`
   and no `player`.
@@ -598,6 +601,11 @@ context precondition required to enter that target safely. It shall not jump
 into a working or reassessment state with missing intent, prior result, plan,
 or other required context and shall not invent defaults merely to make an
 interrupt target executable.
+Control-action discovery probes these guards with optional textual fields
+omitted. Before applying a string operation such as `trim()`, a generated
+guard shall narrow the field to a string; a missing required textual field
+shall make the guard return false, never throw, so the control view remains
+total and omits an action whose payload the runtime cannot source.
 XState automatically stops the current state's invoked actor on transition [[2]].
 Where the default Captain's routing state accepts a fresh intent while another
 state or Boss-reply wait is active, its `BOSS_INTERRUPT` event shall carry a
@@ -642,6 +650,7 @@ decision state would add a seventh outcome to a closed six-action contract
 whose guard discriminants [Setup](#setup) fixes, and is nonconformant.
 There is no source-level opt-in annotation and no `needsBossReply` result metadata in GEARS output.
 The FSM compiler shall preserve the GEARS blockquote as the state's domain `prompt` body and shall not inject any Boss-question instruction into `invoke.input.prompt`.
+This preservation includes every literal leading `>` carried inside the outer GEARS blockquote for quoted runtime context.
 
 For every captain- and player-invoking state outside a controller machine,
 the compiler shall add

package/slc/link.md

@@ -59,9 +59,17 @@ interface PlaybookSession {
   parentSessionId?: string;
   parentCallId?: string;
   depth: number;
+  playerSessions?: PlayerSessionStore;
   ports: PlaybookPorts;
 }
 
+interface PlayerSessionStore {
+  select(playerId: string): string | false;
+  update(playerId: string, resumeToken?: string): void;
+  snapshot(): Readonly<Record<string, string>>;
+  restore(tokens: Readonly<Record<string, string>>): void;
+}
+
 type JsonValue =
   | null
   | boolean
@@ -379,6 +387,11 @@ interface PlaybookTraceEvent {
 }
 ```
 
+A composing host may supply `playerSessions` as a frame-local view of player continuation owned by the root engagement tree.
+The runtime shall select through that view before allocating or tracing a player call and shall update or clear it from a validated player result before emitting the matching finish trace.
+Snapshot export and restore shall use the same view, failed restore shall leave its prior contents unchanged, and child disposal shall not clear host-owned continuation.
+A host that omits the view retains the runtime's private per-session continuation behavior.
+
 The trace types are `session.started`, `boss.input.received`,
 `judge.call.started`, `judge.call.finished`, `player.call.started`,
 `player.call.finished`, `captain.call.started`, `captain.call.finished`,
@@ -531,6 +544,7 @@ decides only the `callPlayer` invocation.
 The runtime shall compose the actual player prompt from the state's
 `PlayerInput`.
 `input.prompt` is the GEARS-derived domain prompt body and shall not be mutated, re-flowed, or treated as a place to store framework control instructions.
+A leading `>` inside that body is authored quoted-context content and shall reach the player unchanged.
 
 The composer may prepend structured labelled blocks from typed `PlayerInput`
 fields the FSM exposes (for example `Boss intent:`, `Review items:`,
@@ -731,6 +745,9 @@ clause (or equivalent typed output metadata). Backticked prose before that
 clause can name statuses, guards, or concepts such as `ok`, `aborted`, and
 `error`; those names are not output properties and shall never become required
 judge fields.
+For a delegated-player field annotated exactly `` `<field>: <verbatim final text>` ``, the judge shall select the guard but the runtime shall replace any judge-supplied value with the player's canonical non-empty final text before returning the actor output.
+The linker shall derive the complete `verbatimPayloadFields` set from those annotations across the FSM result maps.
+A field name that is annotated in one result map and unannotated in another is a link error because the shared adjudication strategy cannot give one property both ownership policies.
 For a direct Captain result, `question` and `response` are human-presentation
 fields owned by the visible call rather than fields authored by the hidden
 judge.
@@ -784,8 +801,8 @@ structured adjudication merely to present the same response.
 That visible-call presentation — visible Captain prose as the Boss
 presentation, a separate hidden adjudicator that never authors the
 `question`/`response` fields, and runtime injection of the visible
-`finalText` — stays scoped to visible-presentation playbooks such as CODE
-and DISCUSS. For a controller playbook, whose FSM declares the controller
+`finalText` — stays scoped to a working playbook whose FSM declares a visible
+direct-Captain state. For a controller playbook, whose FSM declares the controller
 decision-state class of [gears2fsm "Setup"](gears2fsm.md#setup), the
 Captain-call presentation admits the hidden controller form instead
 (DR-029): the decision and closing-reply Captain calls run
@@ -1174,6 +1191,23 @@ The `PlaybookRuntime` shall:
   failure cannot skip the parent disposal boundary or leave the runtime bound.
 
 The actor's `lastError` field shall be surfaced via `emitStatus` when the machine enters its `failed` state.
+Presence of linker-emitted `playerStates` selects the canonical
+factory-backed status profile. That profile shall emit the selected Boss event type
+before sending that event, exactly `→ <guard>` (with no payload-count or tally
+rider) when a settling actor output carries a guard, and
+`⤷ <Player>: <label>` only when the entered state appears in the
+linked module's `playerStates` metadata. It shall emit no raw state-id fallback
+for any other state. `playerStates` shall be a complete map of the FSM states
+that invoke the typed `player` actor; each value carries the exact player from
+that state's source-derived `meta.playbook.player` and the state's exact FSM
+description as `{ player, label }`. The factory shall reject an incomplete
+entry, a non-player state, or a player or label that differs from the FSM
+metadata. A schema-1 legacy module that predates this metadata
+shall preserve the prior factory status defaults, including no classification
+line, `Entered <stateId>.` for ordinary state entry, the single question line,
+and the unglyphed failure line. The new profile is opt-in so adding the seam
+does not silently reinterpret an already-linked artifact without an ABI or
+artifact-schema bump.
 For the default Captain runtime, an initial `ready` state and a terminal `done`
 state shall not emit human status. The terminal response is already visible
 Captain prose; a synthetic “entered done” message would present it twice.
@@ -1206,12 +1240,12 @@ durability, the pair shall behave as follows.
 
 `exportSnapshot()` shall return `undefined` unless the runtime is at a safe
 capture point: initialized, not disposing or disposed, no active
-`handleBossInput`/`resumePlaybookCall` boundary, no pending nested playbook
-call, and the root actor at a quiescent state with actor status `active`.
+`handleBossInput`/`resumePlaybookCall` boundary, and the root actor at a
+quiescent state with actor status `active`.
 At a safe capture point it shall return a JSON-safe
 `PlaybookRuntimeSnapshot` carrying:
 
-- `schemaVersion`: literal `1`.
+- `schemaVersion`: literal `2`.
 - `playbookId`: the bound session's playbook id.
 - `machine`: the root actor's `getPersistedSnapshot()` result, passed
   through the shared JSON detachment with any raw `Error` context value
@@ -1221,19 +1255,33 @@ At a safe capture point it shall return a JSON-safe
   (§PlaybookPorts contract).
 - `sequences`: the live `trace`, `turn`, `judgeCall`, `playerCall`, and
   `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.
+  Captain calls. A direct-Captain-capable runtime shall persist it in current
+  schema-version-2 exports; it remains optional in legacy schema-version-1
+  input, where restore uses `trace` as its collision-safe floor.
 - `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
   parked state awaits no reply. This list exists so hosts can surface the
   question without parsing status lines or telemetry.
+- `suspendedCall`: omitted when no nested call is pending; otherwise the
+  shared nested bridge's complete `callId`, source `stateId`, target
+  `playbookId`, exact handed-off `text`, and `childSessionId`, enriched with
+  the call-to-turn map's optional `turnId`.
+
+A pending nested call is exportable only when the bridge's pending identity
+and complete descriptor agree and the call-to-turn map owns that exact call
+id, including ownership whose value is absent. A bridge descriptor that
+already carries a turn id shall equal that map value. Any missing or
+inconsistent bridge, descriptor, or turn-ownership record makes the capture
+unsafe and returns `undefined`.
 
 `restore(session, snapshot)` is an alternative to `init` under the same
 lifecycle guards (§Session lifecycle): it shall reject when already
 initialized, disposing, or disposed, and shall validate
-`snapshot.schemaVersion` and that `snapshot.playbookId` equals
-`session.playbookId` before touching state.
+schema version `1` or `2` and that `snapshot.playbookId` equals
+`session.playbookId` before touching state. Schema version `1` remains a
+descriptor-free legacy input; schema version `2` may carry the suspended-call
+descriptor above.
 The host supplies the same immutable `PlaybookSession` identity the
 snapshot was exported under and recreates the runtime through the same
 factory with equivalent options; the runtime does not diff options, and
@@ -1244,13 +1292,22 @@ make before calling `restore`.
 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
+prepare the shared nested bridge with the suspended-call descriptor or its
+explicit absence, restore a descriptor's call-to-turn map entry, 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
 session already started, and the next public boundary continues the
-contiguous trace sequence. After start, a restored actor whose status is
-not `active` or whose state descriptor cannot be normalized shall fail
-`restore` through the same failed-start cleanup path as `init`.
+contiguous trace sequence. After start, the runtime shall normalize the
+actual actor state with the prepared suspended call as its pending identity
+and require it to equal the detached persisted state exactly, including
+active status. It shall drain suppressed startup work and invoke the bridge's
+`confirmRestore` as the final fallible restore step, publishing the pending
+identity only after every other validation succeeds. A missing, extra, or
+mismatched reconstructed invocation, an actual/persisted state mismatch, or
+any other failed validation shall fail `restore` through the same
+failed-start cleanup path as `init`, rolling back provisional bridge and turn
+ownership without a child-host call or duplicate start/finish boundary.
 A restore failure shall leave the runtime unbound so `dispose` remains
 callable and terminal.
 
@@ -1406,7 +1463,7 @@ runtime's emission-failure channel to surface from the next public boundary
 that drains.
 
 The recorded receipts and the recorded last classified event are
-process-local: the schema-1 parked-session snapshot persists neither, and a
+process-local: the durable runtime snapshot persists neither, and a
 restored runtime advertises a retry again only after its next classified
 event.
 
@@ -1544,6 +1601,11 @@ The thin emitted module:
   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; the
+  complete `playerStates` status map derived from every FSM state that invokes
+  the typed `player` actor, with each `player` copied from that state's
+  source-derived `meta.playbook.player` (an empty map when there is no such
+  state); the
+  `verbatimPayloadFields` set derived from annotated result fields above; the
   `controlContextFields` projection of §Control surface; and any
   per-playbook strategy override (classifier, prompt composers,
   required-field extraction, status formatting) an earlier section of this
@@ -1579,7 +1641,13 @@ The thin emitted module:
     fields?: Readonly<Record<string, XStateBossEventFieldSpec>>;
   }
 
+  interface XStatePlayerStateStatus {
+    player: string;
+    label: string;
+  }
+
   bossEvents?: readonly XStateBossEventSpec[];
+  playerStates?: Readonly<Record<string, XStatePlayerStateStatus>>;
   placeholderFields?: Readonly<Record<string, string>>;
   ```
 
@@ -1629,6 +1697,7 @@ The thin emitted module:
   top-of-file header comment so the file is reproducible from the same
   inputs.
 - Sources the contract types (`PlayerResult`, `PlayerCallOptions`,
+  `PlayerSessionStore`,
   `CaptainResult`, `CaptainCallOptions`, `PlaybookPorts`, `PlaybookSession`,
   `PlaybookTraceEvent`,
   `PlaybookCallRequest`, `PlaybookCallResult`, `PlaybookCallStart`,

package/slc/text2gears.md

@@ -65,6 +65,20 @@ Those requirements remain in the item's condition or `Results:` metadata.
 Adding control-oriented prompt lines merely to restate them changes the
 Boss-visible contract and is nonconformant.
 
+### Authored prompt fragments
+
+Source may compose one acting prompt from authored Markdown instruction blocks and runtime context that it explicitly says to relay in quotes (`>`).
+A fenced `markdown` block introduced as an instruction or prompt is an authored static prompt fragment: its fence delimiters are Source syntax, while every interior line and blank line is prompt content preserved after documented Markdown unescaping.
+
+An instruction fence and a relayed-context fragment that apply to one behavior shall appear in the target blockquote in their Source order.
+Distinct non-empty fragments shall be separated by one blank prompt line unless Source explicitly supplies a different boundary.
+text2gears shall not move a shared instruction ahead of behavior-specific context, move quoted evidence after an instruction that Source says follows the evidence, or otherwise regroup fragments for convenience.
+
+Where Source says that a runtime value is relayed in quotes, the leading `>` is prompt content rather than Source-only blockquote syntax.
+If Source supplies a blockquoted template for that relay, text2gears shall keep one literal leading `>` on every quoted line; the target GEARS line therefore uses its outer blockquote marker followed by the literal marker, such as `> > Coder output: <coder-output>`.
+If Source names the relayed value but supplies no template, text2gears shall emit its canonical typed placeholder on a line beginning with literal `> ` and shall not summarize, paraphrase, or invent a value in its place.
+An ordinary Source blockquote that specifies a complete acting prompt without requiring quoted relay retains the existing rule above: its one leading marker is Source syntax and is not prompt content.
+
 Source statements that assign active-leaf routing, call identity, suspension,
 or return matching to the host describe execution preconditions rather than
 behaviors for Captain to perform. text2gears shall use such a statement only as
@@ -139,6 +153,11 @@ A single-outcome producer then declares exactly one bullet naming the
 property; this consumed-output case is the sole one in which a
 single-outcome behavior carries a `Results:` label.
 
+Where a later prompt relays a delegated player's whole final response as quoted context, the producer shall declare that property in the exact annotated form `` `<field>: <verbatim final text>` ``.
+The annotation makes the field runtime-owned: the adjudicator selects the result guard, while the linked runtime carries the player's canonical final text into that field instead of asking a judge to reproduce it.
+A distinct typed field extracted from that response remains judge-authored even when a later prompt quotes its exact value; quoting a field does not turn it into the player's whole final response.
+One property name shall not be annotated as verbatim in one result contract and judge-authored in another; text2gears shall choose distinct properties or report that the Source cannot be represented by the current contract.
+
 Result metadata is compiler control data, not part of the acting agent's
 prompt.
 text2gears shall not put guard names, result-property schema, JSON control
@@ -202,11 +221,11 @@ next phase cannot compile.
 Example:
 
 ```markdown
-### DISCUSS-1
+### DECIDE-1
 
 Parallel group: initial-proposals
 
-When Boss gives a topic, Captain shall prompt Host:
+When Boss gives a topic, Captain shall prompt Coder:
 
 > Propose your design independently.
 ```
@@ -306,6 +325,7 @@ Prompts shall carry the specification's normative requirements as instructions t
 
 Source snippets may overlap or duplicate.
 When composing them into a spec item, text2gears shall deduplicate identical prompt lines.
+It shall not deduplicate across distinct authored fragments when doing so would erase a fragment boundary or change the Source-ordered prompt.
 
 Each spec item addresses one state behavior and carries its full final prompt (the static part).
 Cross-item duplication is acceptable: spec items are compiled artifacts; Source is what users maintain.

package/src/runtime.d.ts

@@ -7,6 +7,12 @@ export interface PlayerResult {
 export interface PlayerCallOptions {
     resume: string | false;
 }
+export interface PlayerSessionStore {
+    select(playerId: string): string | false;
+    update(playerId: string, resumeToken?: string): void;
+    snapshot(): Readonly<Record<string, string>>;
+    restore(tokens: Readonly<Record<string, string>>): void;
+}
 export interface CaptainCallOptions {
     visibility: 'visible' | 'hidden';
     resume: string | false;
@@ -41,6 +47,11 @@ export interface PlaybookPendingCall {
     playbookId: string;
     childSessionId: string;
 }
+export interface PlaybookSuspendedCall extends PlaybookPendingCall {
+    stateId: string;
+    text: string;
+    turnId?: number;
+}
 export interface PlaybookCallRequest {
     callId: string;
     playbookId: string;
@@ -106,6 +117,7 @@ export interface PlaybookSession {
     parentSessionId?: string;
     parentCallId?: string;
     depth: number;
+    playerSessions?: PlayerSessionStore;
     ports: PlaybookPorts;
 }
 export type PlaybookTraceType = 'session.started' | 'boss.input.received' | 'judge.call.started' | 'judge.call.finished' | 'player.call.started' | 'player.call.finished' | 'captain.call.started' | 'captain.call.finished' | 'playbook.call.started' | 'playbook.call.finished' | 'apply.started' | 'apply.finished' | 'fsm.transition' | 'status.emitted' | 'boss.input.settled' | 'session.disposed';
@@ -130,8 +142,7 @@ export interface PlaybookPendingBossQuestion {
     question: string;
     sourceItem?: string;
 }
-export interface PlaybookRuntimeSnapshot {
-    schemaVersion: 1;
+interface PlaybookRuntimeSnapshotFields {
     playbookId: string;
     machine: JsonValue;
     playerResumeTokens: {
@@ -148,6 +159,13 @@ export interface PlaybookRuntimeSnapshot {
     state: PlaybookState;
     pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
 }
+export type PlaybookRuntimeSnapshot = PlaybookRuntimeSnapshotFields & ({
+    schemaVersion: 1;
+    suspendedCall?: never;
+} | {
+    schemaVersion: 2;
+    suspendedCall?: PlaybookSuspendedCall;
+});
 export interface PlaybookControlAction {
     id: string;
     label: string;
@@ -192,3 +210,4 @@ export interface PlaybookRuntime {
     dispose(): Promise<void>;
 }
 export type PlaybookRuntimeFactory<Options = unknown> = (options: Options) => PlaybookRuntime;
+export {};

package/src/runtime.ts

@@ -19,6 +19,17 @@ export interface PlayerCallOptions {
   resume: string | false;
 }
 
+// DR-030: a composing host may supply one frame-local view of the root
+// engagement's player continuation. The runtime selects through this store
+// before tracing/calling and updates it from the validated result. Hosts that
+// omit it retain the runtime's private per-session store.
+export interface PlayerSessionStore {
+  select(playerId: string): string | false;
+  update(playerId: string, resumeToken?: string): void;
+  snapshot(): Readonly<Record<string, string>>;
+  restore(tokens: Readonly<Record<string, string>>): void;
+}
+
 export interface CaptainCallOptions {
   visibility: 'visible' | 'hidden';
   resume: string | false;
@@ -64,6 +75,15 @@ export interface PlaybookPendingCall {
   childSessionId: string;
 }
 
+// DR-031 §5: complete durable identity for one nested call whose start
+// boundary has already been published and whose child remains suspended.
+// `turnId` is absent when the call was opened outside a Boss-turn boundary.
+export interface PlaybookSuspendedCall extends PlaybookPendingCall {
+  stateId: string;
+  text: string;
+  turnId?: number;
+}
+
 export interface PlaybookCallRequest {
   callId: string;
   playbookId: string;
@@ -143,6 +163,7 @@ export interface PlaybookSession {
   parentSessionId?: string;
   parentCallId?: string;
   depth: number;
+  playerSessions?: PlayerSessionStore;
   ports: PlaybookPorts;
 }
 
@@ -187,12 +208,11 @@ export interface PlaybookPendingBossQuestion {
   sourceItem?: string;
 }
 
-// DR-014 §1: JSON-safe capture of a parked session. `machine` is the
-// XState persisted snapshot and is opaque to hosts; the pending Boss
-// questions are first-class so a host can surface what was asked
-// without parsing status lines or telemetry.
-export interface PlaybookRuntimeSnapshot {
-  schemaVersion: 1;
+// DR-014 §1 / DR-031 §5: JSON-safe capture of a parked or nested-call
+// suspended session. `machine` is the opaque XState persisted snapshot;
+// pending Boss questions and a schema-2 suspended call are first-class so a
+// host never has to reconstruct durable ownership from presentation records.
+interface PlaybookRuntimeSnapshotFields {
   playbookId: string;
   machine: JsonValue;
   playerResumeTokens: { readonly [playerId: string]: string };
@@ -208,6 +228,18 @@ export interface PlaybookRuntimeSnapshot {
   pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
 }
 
+export type PlaybookRuntimeSnapshot = PlaybookRuntimeSnapshotFields &
+  (
+    | {
+        schemaVersion: 1;
+        suspendedCall?: never;
+      }
+    | {
+        schemaVersion: 2;
+        suspendedCall?: PlaybookSuspendedCall;
+      }
+  );
+
 // DR-029: one currently valid, runtime-advertised control action. The id
 // is stable within the returned view; the label is runtime-written,
 // Boss-appropriate text derived from source state descriptions.

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

@@ -67,6 +67,11 @@ export interface ScheduledStatus {
     message: string;
     data?: JsonValue;
 }
+/** Boss-facing identity for one FSM state whose invoked actor is `player`. */
+export interface XStatePlayerStateStatus {
+    player: string;
+    label: string;
+}
 export interface XStateBossEventFieldSpec {
     /** The judge supplies routing data; the runtime supplies exact Boss text. */
     source: 'judge' | 'text';
@@ -177,8 +182,10 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
      * recoverable FSM-result failures instead.
      */
     captainStrategy?: XStateCaptainStrategy<TOptions>;
-    /** Status line emitted after classification names an event. Default: none. */
+    /** Status line emitted after classification; canonical metadata defaults to the event type, legacy artifacts to none. */
     classificationStatus?: (event: EventObject) => string | undefined;
+    /** Complete FSM-derived Boss-facing metadata for every `player` state; its presence selects the canonical status profile. */
+    playerStates?: Readonly<Record<string, XStatePlayerStateStatus>>;
     /** 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. */
@@ -207,7 +214,7 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
     controlContextFields?: readonly 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. */
+    /** Human status lines for a root transition. Default: guard, declared-player, question, and failure lines. */
     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;