@sublang/playbook 7.0.0 → 9.0.0

package/slc/link.md

@@ -59,13 +59,27 @@ interface PlaybookSession {
   parentSessionId?: string;
   parentCallId?: string;
   depth: number;
+  roleBindings?: Readonly<Record<string, PlaybookRoleBinding>>;
   playerSessions?: PlayerSessionStore;
   ports: PlaybookPorts;
 }
 
+interface PlaybookRoleBinding {
+  readonly playerId: string;
+  readonly promptIdentity: string;
+}
+
+interface PlaybookPendingBossQuestion {
+  questionId: string;
+  asker: { kind: 'captain' } | { kind: 'role'; roleId: string };
+  question: string;
+  sourceItem?: string;
+}
+
 interface PlayerSessionStore {
-  select(playerId: string): string | false;
-  update(playerId: string, resumeToken?: string): void;
+  select(roleId: string): string | false;
+  // Called only for a replacement token or an authorized ok-status clear.
+  update(roleId: string, resumeToken?: string): void;
   snapshot(): Readonly<Record<string, string>>;
   restore(tokens: Readonly<Record<string, string>>): void;
 }
@@ -103,6 +117,30 @@ interface PlaybookPendingCall {
   childSessionId: string;
 }
 
+interface PlaybookSuspendedCall extends PlaybookPendingCall {
+  stateId: string;
+  text: string;
+  turnId?: number;
+}
+
+interface PlaybookRuntimeSnapshot {
+  schemaVersion: 3;
+  playbookId: string;
+  machine: JsonValue;
+  roleResumeTokens: { readonly [roleId: string]: string };
+  sequences: {
+    trace: number;
+    turn: number;
+    judgeCall: number;
+    playerCall: number;
+    playbookCall: number;
+    captainCall?: number;
+  };
+  state: PlaybookState;
+  pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
+  suspendedCall?: PlaybookSuspendedCall;
+}
+
 type PlaybookRunResult =
   | { outcome: 'quiescent' | 'no-action'; state: PlaybookState }
   | {
@@ -113,6 +151,7 @@ type PlaybookRunResult =
   | {
       outcome: 'terminal';
       state: PlaybookState;
+      stateDescription?: string;
       output?: JsonValue;
     }
   | {
@@ -146,12 +185,14 @@ 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.
 
-`PlaybookRuntimeOptions` is host-agnostic and carries only _per-run_ knobs such as identity strings (e.g., model names a playbook substitutes into prompt placeholders), strategy overrides the linker exposes, and — where the compiled playbook's policy needs a host seam — host-supplied port-shaped callbacks the linker exposes as option members whose types the artifact itself declares, so the six-member `PlaybookPorts` contract and the shared contract module stay free of host types.
+`PlaybookRuntimeOptions` is host-agnostic and carries only _per-run_ workflow knobs, strategy overrides the linker exposes, and — where the compiled playbook's policy needs a host seam — host-supplied port-shaped callbacks the linker exposes as option members whose types the artifact itself declares, so the six-member `PlaybookPorts` contract and the shared contract module stay free of host types.
 The link compiler emits a typed options interface per playbook based on the FSM's `CodingInput` (or equivalent).
 The CLI's absence of `--link-option` values does not mean that
 `PlaybookRuntimeOptions` is empty. CLI link options are compile-time inputs;
@@ -162,15 +203,16 @@ remain a required readonly runtime option passed through to machine input; the
 linker shall neither invent an empty catalog nor require it to be baked into a
 CLI link option.
 
-Player binding is a _linker-time_ input baked into the emitted runtime by default.
-A linker may also expose it via `PlaybookRuntimeOptions` for per-run remapping; the contract requires only that the runtime ship with a deterministic binding it applies at every `callPlayer` site.
+Concrete player binding and prompt identity are host policy and shall not enter `PlaybookRuntimeOptions`, machine input, or the emitted artifact.
+For a shell-hosted runtime, `PlaybookSession.roleBindings` shall carry exactly the runtime's local roles, map each to its resolved player id and current prompt identity, and be the sole source for call targeting, player-facing prompt identity, concurrency keys, and trace player ids.
+The host shall derive `promptIdentity` from the current effective model when present and the established adapter otherwise; a standalone runtime may omit the map and retain only its local role identity.
 
 ## PlaybookPorts contract
 
 ```typescript
 interface PlaybookPorts {
   callPlayer(
-    playerId: string,
+    roleId: string,
     prompt: string,
     signal: AbortSignal,
     options: PlayerCallOptions,
@@ -289,7 +331,7 @@ 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`.
+Every standalone linked runtime owns a private continuation map keyed by resolved player id when `roleBindings` is supplied and by local role id otherwise.
 Before reading a resolved direct-Captain or delegated-player result, the
 runtime shall validate, detach, and freeze it through the shared
 `validateCaptainResult` or `validatePlayerResult` helper. The accepted object
@@ -297,17 +339,18 @@ shape is exact: only the declared status and optional string fields are
 allowed, JSON-unsafe members reject, and caller mutation after resolution
 cannot change trace evidence or player continuity. Validation happens before
 adopting a resume token or reading final text.
-The first call to each player in a playbook session shall pass `{ resume: false }`; later calls shall pass the exact stored token.
-After a resolved call, the runtime shall replace the token when the result carries one or clear it when absent before interpreting `status`; a rejected call with no result leaves the prior token unchanged.
+The first call to each private continuation key in a standalone playbook session shall pass `{ resume: false }`; later calls shall pass the exact stored token, so two sequential roles explicitly bound to one player id share one token even without a supplied `PlayerSessionStore`.
+After a validated resolved call, the runtime shall replace the token when the result carries one, clear it only for an `ok` result that omits one, and preserve it for an `aborted` or `error` result that omits one; a rejected call with no result likewise leaves the prior token unchanged.
 After awaiting a host Captain or player promise, the runtime shall re-check the
 combined invocation/public-boundary signal before validating the result,
 adopting a resume token, or emitting a successful finish. A host promise that
 ignores cancellation and resolves late shall be paired as aborted and shall
 not mutate continuity or masquerade as success.
 The map survives actor reconstruction inside the same runtime and is discarded at `dispose`.
-The runtime shall keep an in-flight set keyed by resolved player id and reject
-a second concurrent call to the same id before crossing the host port. Calls
-to distinct resolved player ids may overlap.
+The runtime shall keep an in-flight set keyed by resolved player id when the
+host supplies binding metadata, otherwise by local role id, and reject a
+second concurrent call to the same key before crossing the host port.
+Calls to distinct keys may overlap.
 
 `callJudge` returns free-form text.
 The runtime parses it per the state's adjudication strategy (§Captain adjudication).
@@ -346,7 +389,7 @@ The runtime never speaks to LLMs directly and never touches host types beyond `P
 ## Playbook trace
 
 Every linked runtime shall emit a boundary-complete, ordered trace through `emitTelemetry` topic `playbook.trace`.
-Each payload shall carry `schemaVersion: 2`, the immutable session identity and
+Each payload shall carry `schemaVersion: 3`, the immutable session identity and
 causality, a contiguous one-based `sequence`, a Unix-millisecond `timestamp`, a
 trace `type`, event `payload`, and the runtime-local `turnId` / paired `callId`
 where applicable.
@@ -371,7 +414,7 @@ type PlaybookTraceType =
   | 'session.disposed';
 
 interface PlaybookTraceEvent {
-  schemaVersion: 2;
+  schemaVersion: 3;
   sessionId: string;
   playbookId: string;
   rootSessionId: string;
@@ -387,7 +430,7 @@ interface PlaybookTraceEvent {
 }
 ```
 
-A composing host may supply `playerSessions` as a frame-local view of player continuation owned by the root engagement tree.
+A composing host may supply `playerSessions` as a frame-local view of player continuation owned by the logical Captain session.
 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.
@@ -401,7 +444,7 @@ The trace types are `session.started`, `boss.input.received`,
 `boss.input.settled`, and `session.disposed`.
 Call pairs carry exact prompts and replies, normalized failures, actor and state
 identity, and their boundary-specific options.
-`apply.started` and `apply.finished` are the paired schema-2 boundary of an
+`apply.started` and `apply.finished` are the paired apply boundary of a
 executed `apply()` call on a runtime implementing the optional control surface
 (§Control surface): both carry the action id and idempotency `key` (plus the
 singular `stateId` on start when one exists), the pair shares one
@@ -423,7 +466,8 @@ described top-level `state` and its singular `stateId` when present, as well as
 its message and optional data; consumers shall not have to recover state
 identity from a nested ad hoc object.
 Judge results use `reply`; player start and finish payloads both carry the
-selected `resume`; Captain start and finish payloads both carry
+local `roleId`, the resolved `playerId` when host binding metadata is
+available, and the selected `resume`; Captain start and finish payloads both carry
 the exact composed prompt, the boundary's selected `visibility`, the direct
 invocation's `stateId` and `sourceItem`, and no player resume selection or
 resume token — a visible workflow call carries its runtime-owned
@@ -453,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.
@@ -498,51 +551,36 @@ Trace payloads never become Boss-visible status or prompt text.
 The link compiler shall accept:
 
 - The FSM artifact (path to a `.fsm.ts`).
-- A **player binding** mapping GEARS players (declared in the
-  [text2gears](text2gears.md#players) source) to opaque player-identifier
-  strings.
-  Where no binding is supplied, the linker shall apply the default
-  binding — each player to its lowercased name (e.g. `Coder` → `coder`)
-  — and record the applied binding in the emitted header.
 - An **adjudication strategy** (default: LLM-judge per state) and a
   **Boss-event mapping** (default: free-text judge classification).
   Both strategies are host-agnostic.
 
 The host's identity does not enter compilation; the linked module runs unchanged under any host that implements `PlaybookPorts`.
 
-## Player binding
+## Role identity
 
-Each delegated GEARS state names exactly one player
-(`player` actor `invoke.input.player`).
-The linker shall map every named player to a `playerId` string used in
-`PlaybookPorts.callPlayer(playerId, …)`.
-The host adapter routes that opaque string to its concrete primitive.
+Each delegated GEARS state names exactly one canonical local role id (`player` actor `invoke.input.role`).
+The linker shall retain that id in `PlaybookPorts.callPlayer(roleId, …)` without selecting a concrete player.
+The host shall bind that local role id explicitly when it constructs the runtime.
 Every direct-Captain and delegated-player invocation shall also carry its
 working leaf's explicit
 `stateId`; a linked runtime shall use that field for call identity and shall
 not infer one leaf from a structured root snapshot.
-Direct `captain` actor states bypass player binding and call
-`PlaybookPorts.callCaptain`; the linker shall not synthesize a player id named
-`captain` for them.
-
-For composite players declared with aliases (e.g., `Committer = Coder | Reviewer`), the linker shall resolve the alias **per source item**.
-Resolution inspects the `PlayerInput` fields populated at that state:
-
-- If only one `<playerName>Player` field is present, bind to that player.
-- If multiple are present, prefer the first-listed alternative in the alias declaration order.
-- If none are present, fall back to the alias's first alternative.
-
-Resolution shall be deterministic and recorded in the emitted module so future maintainers can audit it without re-running the linker.
-
-The linker shall not invent player identifiers beyond the recorded default
-binding, and shall not silently collapse aliases at the FSM level — composite
-players keep their `player: 'Committer'` value on `PlayerInput`; resolution
-decides only the `callPlayer` invocation.
+Direct `captain` actor states call `PlaybookPorts.callCaptain`; the linker shall not synthesize a local role or concrete player id named `captain` for them.
+The linker shall reject an alias-shaped role declaration rather than choose a runtime identity.
 
 ## Player prompt composition
 
 The runtime shall compose the actual player prompt from the state's
 `PlayerInput`.
+The shared-factory `composePlayerPrompt` seam shall receive an
+invocation-scoped `promptIdentity(roleId)` lookup as its second argument.
+The lookup shall return the current detached session binding's prompt identity,
+or the canonical local role id when bindings are absent, and shall reject an
+undeclared role.
+It shall expose neither the resolved player id nor the binding map, and the
+runtime shall not place the lookup or any value read through it in options,
+machine input, FSM context, or a persisted snapshot.
 `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.
 
@@ -632,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
@@ -687,7 +729,7 @@ classification is recoverable control input, not a public boundary rejection.
 If a recovered `BOSS_REPLY` names no question that is currently pending, it is
 such a malformed classification: emit the one recovery status, send no event,
 leave the actor unchanged, and return `no-action` after emissions drain.
-Host-owned runtime options, player bindings, and enabled-playbook catalogs are
+Host-owned runtime options, role-to-player bindings, and enabled-playbook catalogs are
 not Boss-event payload. The classifier schema and parser shall not invite or
 accept them, and classified prose shall never overwrite their machine context.
 Every recovered classifier object shall have exactly `type` plus the declared
@@ -705,14 +747,14 @@ aborted while the classifier finish emission was pending, return and trace the
 same structured `aborted` result against the unchanged actor.
 When the FSM supports a Boss-reply suspension state, the prompt shall inspect
 the actor snapshot context and include each exact pending Boss question,
-question id, and asking player so the judge can distinguish a reply from a
-fresh directive. With one pending question, a classified `BOSS_REPLY` that
-omits its optional id shall be filled with that sole id. With several pending
-questions, the classifier shall require a known id. A reply shall re-enter only
+question id, and discriminated Captain-or-role asker so the judge can distinguish a reply from a fresh directive.
+With one pending question, a classified `BOSS_REPLY` that omits its optional id shall be filled with that sole id.
+With several pending questions, the classifier shall require a known id.
+A reply shall re-enter only
 its recorded resume state and preserve the original intent, plan, prior child
 results, and Q+A continuation context.
-The classifier-facing pending-question block contains only `questionId`,
-`player`, and `question`. Internal `resumeStateId`, source-item identity, and
+The classifier-facing pending-question block contains only `questionId`, `asker`, and `question`.
+Internal `resumeStateId`, source-item identity, and
 other machine-routing fields remain authoritative in snapshot context and
 shall not be serialized into the judge prompt.
 The allowed fresh directives while parked include every applicable root entry
@@ -911,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
@@ -939,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
@@ -1031,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.
 
@@ -1114,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.
@@ -1167,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
@@ -1191,23 +1277,20 @@ 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
+Presence of linker-emitted `roleStates` 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.
+`⤷ <Role>: <label>` only when the entered state appears in the linked module's `roleStates` metadata.
+It shall emit no raw state-id fallback for any other state.
+`roleStates` shall be a complete map of the FSM states
+that invoke the typed `player` actor; each schema-2 value carries the exact
+local role from that state's source-derived `meta.playbook.role` and the state's exact FSM description as `{ role, label }`.
+The factory shall reject an
+incomplete entry, a non-player state, or a role or label that differs from the FSM metadata.
+Artifact schema `1` and a missing compatibility declaration
+shall reject before interpretation because their legacy `player` values may
+encode bindings or aliases rather than canonical local roles.
 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.
@@ -1223,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.
 
@@ -1245,22 +1333,22 @@ quiescent state with actor status `active`.
 At a safe capture point it shall return a JSON-safe
 `PlaybookRuntimeSnapshot` carrying:
 
-- `schemaVersion`: literal `2`.
+- `schemaVersion`: literal `3`.
 - `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
   (for example FSM `lastError`) normalized to `{ name, message, stack? }`
   first. The value is opaque to hosts.
-- `playerResumeTokens`: the resume-token map as a plain object
+- `roleResumeTokens`: the local-role resume-token projection as a plain object
   (§PlaybookPorts contract).
 - `sequences`: the live `trace`, `turn`, `judgeCall`, `playerCall`, and
   `playbookCall` counters, plus `captainCall` when the runtime supports direct
-  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.
+  Captain calls.
+  A direct-Captain-capable runtime shall persist it in every schema-version-3 export.
 - `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
+  a list of `{ questionId, asker, question, sourceItem? }`, where `asker` is
+  `{ kind: 'captain' }` or `{ kind: 'role', roleId }`, 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
@@ -1278,19 +1366,16 @@ 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
-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.
+schema version `3` and that `snapshot.playbookId` equals `session.playbookId` before touching state.
+Runtime snapshot schemas `1` and `2` shall reject before state binding because their token and pending-question fields conflate local roles, concrete players, and Captain identity.
 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
 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 (using the persisted global `trace` counter as a
-collision-safe floor for an absent legacy `captainCall`), and the
+`restore` shall bind the session and its current detached role bindings, restore the local-role token projection, the
+sequence counters, and the
 prior-state descriptor from the snapshot,
 prepare the shared nested bridge with the suspended-call descriptor or its
 explicit absence, restore a descriptor's call-to-turn map entry, construct
@@ -1401,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
@@ -1460,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
 
@@ -1479,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
@@ -1543,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
@@ -1593,17 +1745,19 @@ 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
   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; 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
+  transition-event payload fields the FSM's Boss union declares; the
+  complete `roleStates` status map derived from every FSM state that invokes
+  the typed `player` actor, with each `role` copied from that state's
+  source-derived `meta.playbook.role` (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
@@ -1641,13 +1795,13 @@ The thin emitted module:
     fields?: Readonly<Record<string, XStateBossEventFieldSpec>>;
   }
 
-  interface XStatePlayerStateStatus {
-    player: string;
+  interface XStateRoleStateStatus {
+    role: string;
     label: string;
   }
 
   bossEvents?: readonly XStateBossEventSpec[];
-  playerStates?: Readonly<Record<string, XStatePlayerStateStatus>>;
+  roleStates?: Readonly<Record<string, XStateRoleStateStatus>>;
   placeholderFields?: Readonly<Record<string, string>>;
   ```
 
@@ -1663,8 +1817,8 @@ The thin emitted module:
   runtime-owned arm to have lost payload detail under erasure shall report
   that gap rather than emit the entry.
 - Supplies `spec.compat` with the compatibility values current at link time:
-  `{ artifactSchema, runtimeAbi }`, where `artifactSchema` is `1` — the
-  schema number of the thin-module format this §Output defines — and
+  `{ artifactSchema, runtimeAbi }`, where `artifactSchema` is `2` — the
+  schema number of the local-role thin-module format this §Output defines — and
   `runtimeAbi` is the installed shared engine's `RUNTIME_ABI` self-report.
   The linker shall verify that the installed engine lists the emitted
   schema in `SUPPORTED_ARTIFACT_SCHEMAS` and treat its absence as a
@@ -1675,9 +1829,17 @@ The thin emitted module:
   declaration against the engine instance that actually loads the emitted
   module and fails construction on a mismatch, so an artifact linked under
   one engine cannot run silently skewed under another. Modules emitted
-  before this contract carry no `compat` member and remain loadable.
+  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 —
@@ -1693,7 +1855,7 @@ The thin emitted module:
   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
+- Records the linker inputs (FSM path and strategies) in a
   top-of-file header comment so the file is reproducible from the same
   inputs.
 - Sources the contract types (`PlayerResult`, `PlayerCallOptions`,
@@ -1781,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."