@sublang/playbook 8.0.0 → 9.0.0

package/reference/sdlc/review.playbook/review.playbook.js

@@ -9,7 +9,7 @@
 // Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
 //                carried verbatim
 // Compat:        artifact schema 2 / runtime ABI 1
-import { RUNTIME_ABI, createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
+import { createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { reviewMachine, } from './review.fsm.js';
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
 const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
@@ -71,9 +71,20 @@ export const _internal = {
 };
 const runtimeSpec = {
     label: 'REVIEW',
-    compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
+    // DR-022 / slc/link.md: the declaration carries the value current at link
+    // time — a literal, never the loading engine's RUNTIME_ABI self-report,
+    // which would follow whatever engine loads the module and make the
+    // factory's skew check compare that engine with itself.
+    compat: { artifactSchema: 2, runtimeAbi: 1 },
     snapshotOptions: snapshotReviewOptions,
-    entryEvent: { type: 'START_REVIEW', textField: 'callerInput' },
+    entryEvent: {
+        type: 'START_REVIEW',
+        textField: 'callerInput',
+        // `copyStartInput` copies the entry text here, so the failure-state
+        // retry reads it back from the persisted machine snapshot and survives
+        // a continued session (DR-034).
+        contextField: 'callerInput',
+    },
     roleStates: {
         reviewInitial: {
             role: 'reviewer',

package/reference/sdlc/review.playbook/review.playbook.ts

@@ -11,7 +11,6 @@
 // Compat:        artifact schema 2 / runtime ABI 1
 
 import {
-  RUNTIME_ABI,
   createXStatePlaybookRuntime,
   snapshotJsonValue,
   type PlaybookPlayerInput,
@@ -156,9 +155,20 @@ export const _internal = {
 
 const runtimeSpec = {
   label: 'REVIEW',
-  compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
+  // DR-022 / slc/link.md: the declaration carries the value current at link
+  // time — a literal, never the loading engine's RUNTIME_ABI self-report,
+  // which would follow whatever engine loads the module and make the
+  // factory's skew check compare that engine with itself.
+  compat: { artifactSchema: 2, runtimeAbi: 1 },
   snapshotOptions: snapshotReviewOptions,
-  entryEvent: { type: 'START_REVIEW', textField: 'callerInput' },
+  entryEvent: {
+    type: 'START_REVIEW',
+    textField: 'callerInput',
+    // `copyStartInput` copies the entry text here, so the failure-state
+    // retry reads it back from the persisted machine snapshot and survives
+    // a continued session (DR-034).
+    contextField: 'callerInput',
+  },
   roleStates: {
     reviewInitial: {
       role: 'reviewer',

package/slc/gears2fsm.md

@@ -244,8 +244,9 @@ 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, role? } }` repeating
-  its stable id and description so linked runtimes can discover active public
+- JSON-safe `meta: { playbook: { stateId, description, role? } }` naming the
+  state's public playbook identity per the identity rule below and repeating
+  its description so linked runtimes can discover active public
   identities through `snapshot.getMeta()` without private XState nodes. A
   delegated-role state shall also carry the canonical lowercase source role id in
   `meta.playbook.role`; every other state shall omit `role`;
@@ -258,6 +259,8 @@ Each state shall declare:
   and no `role`.
 
 The source item ID shall live in `invoke.input.sourceItem`, not in a comment — this keeps the GEARS-to-state mapping machine-readable.
+
+Outside a parallel group's regions, a state's `meta.playbook.stateId` shall equal its state key — the one identity a factory-backed linked runtime indexes by.
 A delegated state's `invoke.input.role` shall match the canonical lowercase id of its source item's named role.
 A direct Captain state shall not invent a `Captain` role binding.
 
@@ -748,6 +751,20 @@ an unhandled runtime error.
 Every machine shall declare at least one `type: 'final'` state (typically `done`) reachable on completion.
 A never-terminating machine is a defect: the runner has no completion signal.
 
+At least one is a floor, not a ceiling. A final state's `description` is the
+machine's published terminal meaning: a host that cannot read the machine's
+output quotes that description to report what the run did. It shall therefore
+be true of every arm that enters the state and of no other terminal outcome.
+Where Source declares more than one terminal outcome — an approval that
+completes the workflow and a failure the workflow reports to its caller
+instead of parking — each outcome shall get its own `type: 'final'` state
+whose description names it. Routing an approval arm and a failure, abort, or
+invalid-result arm into one final state is a defect of the same kind as a
+wrong result field, because the quoting host cannot detect the difference.
+This constrains only published meaning: the declared machine `output` still
+derives its status and fields from typed context, so a caller that does read
+the output is unaffected.
+
 Where Source declares a JSON-safe terminal result, the setup types shall
 declare that output and the root machine shall derive it from typed context
 through XState's machine `output` function. A final-state transition alone does

package/slc/link.md

@@ -151,6 +151,7 @@ type PlaybookRunResult =
   | {
       outcome: 'terminal';
       state: PlaybookState;
+      stateDescription?: string;
       output?: JsonValue;
     }
   | {
@@ -184,8 +185,10 @@ differ from both its `rootSessionId` and `parentSessionId`.
 Run outcomes are exact: `no-action` means no FSM event was sent;
 `quiescent` means a non-failure parked/idle state; `failed` means the FSM is in
 a recoverable failure state; `terminal` means top-level final with optional
-JSON output; `aborted` means the turn signal ended work; and `suspended` means
+JSON output and the exact authored `stateDescription` of the reached final
+state when one is declared; `aborted` means the turn signal ended work; and `suspended` means
 exactly one `pendingCall` is active.
+Only the terminal variant may carry `stateDescription`; the runtime shall omit it when the final state declares none and shall never substitute a state id or derive it from opaque output ([DR-037](../specs/decisions/037-terminal-result-meaning.md)).
 Control-plane exceptions reject the runtime method rather than masquerade as a
 recoverable workflow `failed` result.
 
@@ -494,6 +497,15 @@ If a started-boundary sink records the event and then rejects, the runtime
 shall make one best-effort normalized error-finish attempt with the same call
 id and then reject the original start error. It shall not retry either event or
 let a failure of that finish attempt replace the start error.
+A start-sink rejection causally identical to the applicable signal reason is
+the cancellation itself, not a control error: no host call begins, the
+best-effort paired finish carries the boundary's canonical aborted evidence —
+`status: 'aborted'` for a host call, or the rejected-before-effect disposition
+and reason for apply — and nothing is latched. An ordinary run boundary settles
+as §Abort prescribes. At the apply boundary the same event remains
+pre-acceptance: `apply` rejects with that exact reason, records no receipt, and
+leaves the key reusable
+([DR-036](../specs/decisions/036-coherent-abort-settlement.md)).
 When a call boundary carries `callId`, that id shall be unique within the
 runtime session. A stable FSM `stateId` is identity metadata in the payload,
 not a call id and shall not be reused as one across repeated invocations.
@@ -658,10 +670,14 @@ nonconformant.
 The FSM's `events` union enumerates every Boss-originated event.
 The runtime receives Boss input as a free-form string
 (`handleBossInput.text`).
-Where the current ready or reconstructed terminal machine accepts exactly one
+Where the current ready, recoverable-failure (`failed`), or reconstructed
+terminal machine accepts exactly one
 ordinary textual entry event and no Boss question is pending, the runtime
 shall send that event deterministically and attach the exact original text to
-its declared textual payload field without invoking `callJudge`.
+its declared textual payload field without invoking `callJudge`: each of the
+three is an entry awaiting a fresh intent, so delivered text has exactly one
+meaning there and a judge call could only spend budget or settle the restart
+as no action.
 The default Captain — the controller playbook of
 [gears2fsm "Setup"](gears2fsm.md#setup) — is deterministic at every parked
 entry: the runtime maps each Boss turn from the exact text and the host's
@@ -937,10 +953,34 @@ The provided actor shall:
   `{ guard: <first declared guard>, exitStatus: 0 }`; any nonzero status
   resolves the second declared guard with that status. Guard selection is
   mechanical; the runtime shall not route script output through the judge.
-- Reject only when the command cannot be spawned at all, routing through the
-  state's ordinary `onError` path.
-- Honor the active turn's abort signal by terminating the child process and
-  rejecting per §Abort.
+- Reject when the command cannot be spawned at all, routing through the
+  state's ordinary `onError` path. Beyond spawn failure, the invocation
+  rejects only per the abort bullet below or when one of its own script
+  emissions rejects; a completed command's exit status itself never rejects.
+- Honor the active turn's abort signal per §Abort: the actor shall reject
+  without spawning when the combined signal is already aborted; shall run the
+  shell detached as its own process-group leader; and on abort — whenever it
+  lands before the invocation settles, including only after the shell's own
+  exit — shall deliver
+  `SIGTERM` to the entire group, escalate to `SIGKILL` after a bounded grace,
+  and settle only after the shell process itself has exited and the group has
+  stopped being signalable, confirmed by an `ESRCH` liveness probe, rejecting
+  with the signal's reason. The same
+  bounded grace caps the post-`SIGKILL` wait for kernel teardown, so an
+  unreaped member outside the runtime's control cannot stall settlement. If
+  the group remains signalable through that bound, or confirmation fails
+  without `ESRCH`, the boundary rejects with a distinct teardown control error
+  rather than reporting a clean abort over unconfirmed cleanup. The kill is
+  always posted before the actor settles. Abort ownership — the
+  listener and its escalation — spans the whole invocation, not the
+  spawn-to-exit window
+  ([DR-036](../specs/decisions/036-coherent-abort-settlement.md)). An abort
+  observed only after the shell's exit shall additionally reject before guard
+  resolution and before starting any script emission not already in flight; an
+  emission already started when the abort lands completes through the
+  ordinary serialized channel and the rejection follows it. A
+  descendant that leaves the process group is beyond the runtime's kill
+  scope.
 - Emit, after the child settles and before the invocation resolves, one status
   line `Executed script for <stateId> (exit <status>).` and one telemetry
   event under topic `playbook.script` with payload
@@ -965,14 +1005,18 @@ XState `.provide(...)` receives the exact declared actor input rather than a
 structurally similar local type.
 Construct one bridge per runtime and wire every integration hook: allocate ids
 with `nextCallId`; return the currently active public-boundary signal from
-`getBoundarySignal`; bind `resumePlaybookCall.signal` before settling the
-deferred actor through `bindResumeSignal`; enqueue the exact start/finish trace
-through `emitStarted` / `emitFinished`; drain the global emission queue through
-`drain`; latch the original control error through `onControlPlaneError`; and
-retain any cleanup/observer failure through `onBackgroundError` for the next
-public boundary or disposal rejection. The runtime shall not leave these
-optional API hooks unwired merely because their TypeScript properties are
-optional for simpler bridge consumers.
+`getBoundarySignal`; capture an immutable cancellation classifier for the
+invocation's signal identities; compose `resumePlaybookCall.signal` into that
+classifier through `bindResumeSignal`; pass the applicable classifier through
+`emitStarted`, `emitFinished`, and `drain`; bind it to the root transition
+caused by child settlement through `bindActorSettlement`; and pass it through
+`onControlPlaneError` and `onBackgroundError`. Each receiving latch shall drop
+only a failure the supplied classifier identifies as exact cancellation and
+shall retain every distinct cleanup or observer failure for the owning public
+boundary, the next drain, or disposal rejection as applicable. A stored
+distinct failure shall never be reclassified against a later boundary. The
+runtime shall not leave these optional API hooks unwired merely because their
+TypeScript properties are optional for simpler bridge consumers.
 On invocation the bridge allocates a runtime-local call id, traces the start,
 and calls `PlaybookPorts.callPlaybook` with the composed target/text and the
 bridge signal combined from the XState invocation lifetime, the active public
@@ -1057,12 +1101,15 @@ registry; linker-time metadata is not authorization to call a target.
 
 Disposal shall settle an outstanding call as aborted and drain its finish
 trace before `session.disposed`.
-If registered child abort cleanup rejects, the bridge shall emit the paired
-finish with an error result and reject `abortPending` or disposal with that
-original cleanup error; it shall not swallow the failure merely because the
-promise actor also observes a `NestedPlaybookCallError`. Parent disposal shall
-still drain, emit its one `session.disposed` boundary, and clear the bound
-session before rejecting with that preserved cleanup error.
+If registered child abort cleanup rejects with a failure distinct from every
+applicable abort reason, the bridge shall emit the paired finish with an error
+result and reject `abortPending` or disposal with that original cleanup error,
+or with an aggregate containing every distinct failure when more than one
+remains;
+an exact abort-reason rejection is cancellation evidence and shall not be
+retained as a control failure. Parent disposal shall still drain, emit its one
+`session.disposed` boundary, and clear the bound session before rejecting with
+any preserved distinct cleanup error.
 Child output and errors must be JSON-safe; a non-JSON-safe result is a
 control-plane error.
 
@@ -1140,6 +1187,12 @@ The `PlaybookRuntime` shall:
   transition-trace or telemetry sink failure is part of `init`: initialization
   shall reject, stop the actor, and perform the failed-start cleanup below
   rather than swallowing it as a later background error.
+  A root-actor error observed during startup — an initial entry action or a
+  synchronously failing initial invocation — is equally part of `init` and
+  `restore`: the boundary shall reject with that original error after the
+  failed-start cleanup, and shall never resolve leaving the errored actor as
+  later background state
+  ([DR-036](../specs/decisions/036-coherent-abort-settlement.md)).
   Where the FSM input declares `selfPlaybookId`, seed it from the immutable
   `session.playbookId`; do not expose a caller option or reuse a working leaf's
   `stateId` as the self-call identity.
@@ -1193,7 +1246,14 @@ The `PlaybookRuntime` shall:
   transition/status/telemetry queue before returning, just as
   `handleBossInput` does. A resume shall not allocate a new Boss-input
   `turnId`; retain the original call-start turn id for its matching finish and
-  for the parent continuation caused by that return. Every success and
+  for the parent continuation caused by that return.
+  A resume whose signal is already aborted after identity and result
+  validation shall deliver nothing: bind no resume signal, settle no deferred,
+  emit no call finish, and preserve the pending call — the boundary settles
+  `{ outcome: 'aborted' }` with the signal's reason while the suspended state
+  and pending identity survive, so a later resume with the same call id and a
+  fresh signal still delivers
+  ([DR-036](../specs/decisions/036-coherent-abort-settlement.md)). Every success and
   exceptional path shall drain ordered emissions, select the first latched
   non-abort control error before considering abort, and clear its boundary
   latches in `finally`, so a failed resume cannot leak an emission error into a
@@ -1246,9 +1306,14 @@ transition first.
 
 If a `*.call.started` trace records and then its sink rejects, no host call may
 begin. The runtime shall still enqueue exactly one synthetic paired
-`*.call.finished` trace with `status: 'error'`, preserving the original call
+`*.call.finished` trace — with `status: 'error'`, or `status: 'aborted'` when
+the sink rejection is causally identical to the applicable signal reason, in
+which case nothing is latched and the turn follows abort settlement
+([DR-036](../specs/decisions/036-coherent-abort-settlement.md)) — preserving
+the original call
 id, turn id, actor visibility, state/source identity, and prompt or request
-metadata from the start boundary. It shall then follow the same latched
+metadata from the start boundary. A distinct rejection shall then follow the
+same latched
 control-error, FSM settlement, and ordered-drain path as any other call-start
 failure; the synthetic finish must not replace the original sink error.
 
@@ -1421,11 +1486,18 @@ still describes the state. Two families exist, labeled from source state
 descriptions:
 
 - **Failure-state retry** — while the singular state id is the recoverable
-  failure state and the runtime holds a recorded last classified event (the
-  event a public Boss boundary sent that drove the run into `failed`, kept
-  with its recorded payload), and the live snapshot accepts that event, the
-  runtime shall advertise `retry:<EVENT_TYPE>` replaying exactly that
-  recorded event.
+  failure state and the live snapshot accepts the retry event sourced below,
+  the runtime shall advertise `retry:<EVENT_TYPE>` replaying exactly that
+  event. Where the emitted module's entry-event declaration names the FSM
+  context member the machine's entry action copies the exact Boss text into
+  (DR-034), the retry event is that deterministic entry event built from the
+  live snapshot's member — excluded when the member is absent, not a string,
+  or blank, and never falling back to the record. Where it names no member,
+  the retry event is the recorded last classified event (the event a public
+  Boss boundary sent that drove the run into `failed`, kept with its recorded
+  payload), and there is none while the runtime holds none. The member is
+  declared, never inferred from a context member that happens to match the
+  entry event's text field.
 - **Jump entries** — for each registered resumable state id whose
   explicit-state-jump event (`BOSS_INTERRUPT` with that `targetId`, optional
   textual fields omitted) the live snapshot accepts, guards included, the
@@ -1480,12 +1552,17 @@ trace and the return agree, and a receipt states what happened to the effect
 rather than what happened to its telemetry. The published receipt stands, is
 returned and replayed verbatim, and the delivery failure travels on the
 runtime's emission-failure channel to surface from the next public boundary
-that drains.
+that drains — unless the delivery failure is causally identical to the apply
+signal's own abort reason, in which case it evidences the cancellation and is
+dropped, not latched
+([DR-036](../specs/decisions/036-coherent-abort-settlement.md)).
 
 The recorded receipts and the recorded last classified event are
-process-local: the durable runtime snapshot persists neither, and a
-restored runtime advertises a retry again only after its next classified
-event.
+process-local: the durable runtime snapshot persists neither. A restored
+runtime therefore advertises the retry of a declared entry-event source
+immediately — that payload rides the persisted machine snapshot — while a
+module declaring no source advertises a retry again only after its next
+classified event.
 
 ## Abort
 
@@ -1499,7 +1576,61 @@ the shared `combineAbortSignals`). Classify a rejection as cancellation by its
 causal identity with the applicable signal reason, not by an `AbortError` name
 or by observing only that the signal is also aborted. Signals may carry an
 ordinary `Error`, while a distinct transport or sink failure that occurs after
-abort remains a non-abort control error and takes precedence. On abort, the
+abort remains a non-abort control error and takes precedence. Classification
+lives at each latch or report site, against the boundary signal applicable
+there — the invocation-lifetime combined signal, and during a resume that
+boundary's own signal — so a failure causally identical to the applicable
+reason is the cancellation's own evidence: it is handled there under the phase
+rules below, never mislabeled as a distinct failure and never carried to an
+unrelated later boundary
+([DR-036](../specs/decisions/036-coherent-abort-settlement.md)).
+A failure already latched as distinct retains that ownership; a later drain
+shall not reinterpret it against another boundary whose abort signal happens
+to use the same object as its reason.
+A public boundary settles on the machine's state at its quiescence point,
+in this precedence: a suspended pending call, then a distinct actor error,
+then terminal completion, then a coincident abort, then the recoverable
+failure state — a completed machine settles `terminal` even when the signal
+also aborted, because an `aborted` settlement over a terminal machine hides
+work the next turn would silently restart.
+An abort observed after the outcome is computed does not rewrite it, and a
+settlement-channel rejection causally identical to the abort reason is
+forgiven, so the returned result and the settlement trace state one fact.
+A boundary entered with an already-aborted signal delivers nothing.
+That entry refusal precedes the ordinary settlement order: a pre-aborted
+resume reports `aborted` while preserving its suspended pending call rather
+than reporting `suspended` for work it did not deliver.
+Cancellation-coupled channel rejections obey this phase matrix:
+
+- **Before a host call or effect starts (and before apply acceptance):** an
+  identical start-channel rejection starts no host call or effect and latches
+  no control error. A recorded start receives one best-effort `aborted` finish.
+  An ordinary run boundary then settles by the precedence above; a
+  pre-acceptance `apply` instead rejects with that exact reason, records no
+  receipt, and leaves its key reusable.
+- **After a host call or effect starts but before its finish or outcome is
+  recorded:** an identical host, cleanup, observer, or in-flight-emission
+  rejection is cancellation evidence. Invocation-owned cleanup completes, a
+  started trace pair receives one `aborted` finish, and the ordinary boundary
+  settles by the precedence above. A distinct rejection remains a control
+  failure, produces the applicable error finish, and takes distinct-error
+  precedence.
+- **After a call finish is recorded but before the enclosing non-apply outcome
+  is computed:** an identical finish-sink or drain rejection leaves the
+  recorded finish unchanged, emits no corrective second finish, latches
+  nothing, and lets the enclosing boundary settle by the precedence above.
+- **After apply acceptance but before receipt publication:** every settlement
+  failure, the exact apply abort reason included, is folded into the current
+  `failed` receipt. Acceptance forbids throwing; the replacement receipt is
+  published, returned, and replayed, and the failure is not carried as a later
+  delivery error.
+- **After a non-apply outcome is computed or an apply receipt is published:**
+  an identical rejection is dropped without rewriting the outcome or receipt
+  and without poisoning a later boundary. A distinct non-apply settlement
+  rejection retains current-boundary control-error precedence; a distinct
+  post-publication apply rejection retains the published receipt and travels
+  on the delivery-failure channel to the next boundary that drains.
+On abort, the
 runtime shall not merely race the imperative
 wait and return while an invocation remains live: it shall let the selected
 rejection path settle and drive the actor to a quiescent state before returning
@@ -1563,12 +1694,13 @@ The `playbook.trace` copies are the host-agnostic runtime-boundary record requir
 ## Output
 
 The link compiler emits one TypeScript module per playbook.
-For an FSM that declares no `type: 'parallel'` state, it shall emit the thin
-shared-factory module defined below.
+For an FSM that declares no `type: 'parallel'` state — necessarily flat
+under [gears2fsm.md](gears2fsm.md)'s one-state-per-item mapping — it shall
+emit the thin shared-factory module defined below.
 For an FSM that declares a parallel state, it shall emit bespoke linked
 machinery satisfying this document's runtime contract and shall not invoke
-`createXStatePlaybookRuntime`, whose supported domain is single-region FSMs
-under [DR-019](../specs/decisions/019-shared-linked-runtime-factory.md).
+`createXStatePlaybookRuntime`, whose supported domain is flat single-region
+FSMs under [DR-019](../specs/decisions/019-shared-linked-runtime-factory.md).
 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
@@ -1613,7 +1745,10 @@ The thin emitted module:
   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`
+  §Boss-event mapping prescribes deterministic entry, naming with it the FSM
+  context member that event's own transition action copies the exact Boss
+  text into wherever the machine keeps one, so the failure-state retry of
+  §Control surface survives a restore; 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
@@ -1697,7 +1832,14 @@ The thin emitted module:
   before this contract carry no `compat` member and shall reject before interpretation.
 - Requires the containing public registry manifest to advertise the same `artifactSchema: 2`; the Captain host shall reject a missing or disagreeing registry value before constructing this runtime, and a bespoke runtime profile shall advertise the same schema without claiming this shared factory's `runtimeAbi`.
 - Default-exports the factory call as `createPlaybookRuntime`, typed
-  `PlaybookRuntimeFactory<PlaybookRuntimeOptions>`.
+  `PlaybookRuntimeFactory<PlaybookRuntimeOptions>`. A registry module loads
+  dynamically inside the host's caught boundary, so its eager module-scope
+  factory call fails fast there. The compiled session Captain module is the
+  exception: the shell and both CLI front ends import it statically, so it
+  shall defer its factory call to the first runtime request — an eager call
+  would turn a future `spec.compat` rejection into an uncaught module-load
+  error that takes even `--help` down, instead of the caught
+  host-construction boundary's setup diagnostic.
 - Exposes, under an `_internal` export, the pure helpers verification
   needs — at least the prompt composers its own machine uses, which may
   re-export the shared defaults when the spec does not override composition —
@@ -1801,7 +1943,7 @@ New behavior in any of these areas requires a separate slc spec.
 
 ## References
 
-[1]: [text2gears](text2gears.md) "First phase: text → GEARS spec items."
-[2]: [gears2fsm](gears2fsm.md) "Second phase: GEARS items → FSM artifact."
+[1]: text2gears.md "First phase: text → GEARS spec items."
+[2]: gears2fsm.md "Second phase: GEARS items → FSM artifact."
 [3]: https://stately.ai/docs/actors "XState actors — `createActor`, snapshots, abort signal handling."
 [4]: https://github.com/sindresorhus/p-queue#readme "p-queue concurrency and AbortSignal support."

package/src/runtime.d.ts

@@ -97,6 +97,7 @@ export type PlaybookRunResult = {
 } | {
     outcome: 'terminal';
     state: PlaybookState;
+    stateDescription?: string;
     output?: JsonValue;
 } | {
     outcome: 'suspended';

package/src/runtime.ts

@@ -132,6 +132,7 @@ export type PlaybookRunResult =
   | {
       outcome: 'terminal';
       state: PlaybookState;
+      stateDescription?: string;
       output?: JsonValue;
     }
   | {

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

@@ -168,6 +168,15 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
     entryEvent?: {
         type: string;
         textField: string;
+        /**
+         * DR-034: the FSM context member this machine's entry action copies the
+         * exact Boss text into. Where it is named, the failure-state retry
+         * builds its payload from that member of the live snapshot instead of
+         * from the process-local recorded event, so the action derives the same
+         * before and after `restore`. Absent: the recorded event stays the
+         * source and the action lives only as long as the process.
+         */
+        contextField?: string;
     };
     /**
      * Exact flat Boss-event contracts whose non-text fields the judge may
@@ -313,9 +322,10 @@ export declare function stateDescriptionsFromMachine(machine: AnyStateMachine):
  * (literal and dynamic) — and implements the full runtime lifecycle including
  * the optional parked-session snapshot capability (DR-014).
  *
- * Scope: machines that declare no parallel state (each snapshot exposes
- * exactly one playbook state id). Parallel-region FSMs keep their own linked
- * runtimes.
+ * Scope: flat single-region machines — no parallel state, no compound
+ * child states, and every root state's `meta.playbook.stateId` equal to its
+ * state key — so 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>;
 export {};