@sublang/playbook 4.0.0 → 6.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
@@ -193,6 +194,49 @@ Both direct-Captain states additionally receive the universal
 `needsBossReply` result. Their guards and actions shall use those exact
 case-sensitive names so the compiled adjudication contract remains stable.
 
+For a controller playbook — one whose Source declares DR-029's session-scoped
+controller policy: a session Captain that runs for the whole host session,
+receives every Boss turn, and operates the working playbooks from outside the
+engagement stack (DR-029) — the compiler shall apply the additive
+controller decision-state class below. The class joins the stable compiler
+contract beside the decide-call-observe vocabulary above; that vocabulary and
+the universal `needsBossReply` rule stay untouched for the artifacts that
+consume them.
+The controller machine shall be a session loop, not a finite errand: a
+quiescent conversational hub (tag `playbook.parked`) receives each Boss turn;
+the controller decision state decides it over the closed action set; a
+`respond` selection settles its turn in the decision call itself, its
+validated `text` being the turn's captain speech; an acting selection's host
+settlement becomes the outcome report grounding one closing-reply call; and
+the machine returns to the hub for the next turn. Returning to the hub after
+a settled turn completes the session loop's turn; it is not the idle-hub
+routing that [Transitions](#transitions) reserves for recovery.
+Because the hub receives every Boss turn, a controller state carries no
+Boss-reply suspension: the compiler shall not add `needsBossReply` to a
+controller machine's `invoke.input.result` maps — a clarifying question to
+Boss is a `respond` selection.
+The machine shall declare no terminal result output and shall keep exactly
+one reachable `type: 'final'` shutdown state entered only by the host's
+teardown event. The completion rule of
+[Errors and termination](#errors-and-termination) applies unamended: its
+output clause binds only where Source declares a terminal result, which a
+controller Source does not.
+The controller decision state's direct-Captain result contract discriminates
+the closed action set of DR-029. Its guard discriminants are a stable
+compiler contract, not names the compiler may invent — `respond`, `start`,
+`switch`, `dismiss`, `deliver`, and `runtime` — with each guard's required
+payload fields:
+
+- `respond` requires `text`;
+- `start` and `switch` each require `playbookId` and `input`;
+- `runtime` requires `actionId`;
+- `dismiss` and `deliver` require none — a `deliver` result in particular
+  carries no text payload: the host is authoritative for the delivered text,
+  so the contract declares no field for it.
+
+The decision state's guards and actions shall use those exact case-sensitive
+names so the compiled controller contract remains stable.
+
 ## States
 
 Each state shall declare:
@@ -200,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`.
@@ -555,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
@@ -588,11 +639,21 @@ cannot supply alone, the machine shall suspend that task in a quiescent wait
 state and resume the same task with the Q+A in the next prompt.
 This is a third Boss surface alongside `BOSS_INTERRUPT` and Boss entry events.
 
-Every captain- and player-invoking state supports this path.
+Every captain- and player-invoking state supports this path, with one
+exception the compiler shall apply, not infer: the states of a controller
+machine ([Setup](#setup), controller decision-state class) carry no
+Boss-reply suspension, because its hub already receives every Boss turn and a
+clarifying question to Boss is a `respond` selection over the closed action
+set. The rule below is therefore universal over workflow states and silent
+about that class; in particular, adding `needsBossReply` to the controller
+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, the compiler shall add
+For every captain- and player-invoking state outside a controller machine,
+the compiler shall add
 `needsBossReply` to the state's `invoke.input.result` map.
 The description shall be the standard adjudicator-facing text:
 

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
@@ -143,7 +151,7 @@ exactly one `pendingCall` is active.
 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) and strategy overrides the linker exposes.
+`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.
 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;
@@ -240,6 +248,10 @@ type PlaybookCallStart =
 
 `PlayerResult` mirrors the status, resume token, final text, and error fields of cligent's `PlayerRunResult` ([TMUX-033](https://github.com/sublang-ai/cligent/blob/main/specs/user/tmux-play.md#tmux-033)).
 The runtime treats `status !== 'ok'` as a player failure and routes it through the FSM's error path (§Abort).
+An `ok` player result whose `finalText` is missing, empty, or whitespace-only
+earns exactly one corrective re-ask: the same player call repeated under the
+stored resume selection, traced as its own player-call pair, before a second
+such result routes through the same error path.
 
 `callCaptain` runs a direct-Captain FSM actor against the host's Captain
 agent. The linked runtime shall pass
@@ -257,9 +269,13 @@ array requests a tool-free call, while omission preserves the host Captain's
 configured tools.
 `CaptainResult` carries no resume token or player-continuation selection.
 A non-`ok`
-result, or an `ok` result without non-empty `finalText`, shall record that
-failure on the call's single finish trace and reject the actor through the
-FSM's error path. These structured host-result failures are recoverable
+result, or an `ok` result whose `finalText` is missing, empty, or
+whitespace-only, shall record that failure on the call's single finish trace.
+A non-`ok` result shall then reject the actor through the FSM's error path
+with no corrective re-ask; an empty `ok` result shall first earn exactly one
+corrective re-ask — the same call repeated, traced as its own
+started/finished pair — and only a second such result shall reject the actor
+the same way. These structured host-result failures are recoverable
 workflow failures, not control-plane failures: the runtime shall let the actor
 take `onError`, drive it to quiescence, drain ordered emissions, and resolve
 the public method with `{ outcome: 'failed' }` carrying the failure state's
@@ -347,6 +363,8 @@ type PlaybookTraceType =
   | 'captain.call.finished'
   | 'playbook.call.started'
   | 'playbook.call.finished'
+  | 'apply.started'
+  | 'apply.finished'
   | 'fsm.transition'
   | 'status.emitted'
   | 'boss.input.settled'
@@ -369,14 +387,28 @@ 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`,
 `playbook.call.started`,
-`playbook.call.finished`, `fsm.transition`, `status.emitted`,
+`playbook.call.finished`, `apply.started`, `apply.finished`,
+`fsm.transition`, `status.emitted`,
 `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
+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
+session-unique `apply-<n>` call id and the boundary's turn id, and the finish
+adds the receipt `disposition` with its `reason`, normalized `error`, or
+projected `run` result, all JSON-safe. A repeated idempotency key returns the
+recorded receipt without a new pair.
 Direct-Captain start and finish payloads shall carry `allowedTools` exactly when
 the originating `CaptainCallOptions` selects it and shall omit the member when
 the call preserves the host Captain's configured tools.
@@ -392,16 +424,23 @@ 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
-the exact composed prompt, `visibility: 'visible'`, the direct invocation's
-`stateId` and `sourceItem`, and no player resume selection or resume token;
+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
+`resume: false` selection, while a hidden controller call
+(§Captain adjudication) omits the `resume` member altogether, its
+durable-conversation selection being host-owned;
 judge `purpose` is
 `boss-input-classification`, `player-output-adjudication`, or
 `captain-output-adjudication`; and every error uses
 `{ name, message, stack? }` rather than a raw string or `Error` instance.
 The Captain finish payload shall preserve the exact `CaptainResult` status and
 final text when present, while carrying any failure in normalized form.
-An `ok` result without `finalText` therefore retains status `ok` but also
-carries the normalized missing-text failure that makes the actor reject.
+An `ok` result without non-empty `finalText` therefore retains status `ok` but
+also carries the normalized missing-text failure; the corrective re-ask that
+follows (§PlaybookPorts contract) traces as its own started/finished pair, and,
+when that corrective call happens, only a second such finish makes the actor
+reject.
 If the Captain port rejects before returning a result, the finish instead
 carries explicit `status: 'aborted'` when the combined signal has aborted or
 `status: 'error'` otherwise. A finish boundary never omits status merely
@@ -505,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:`,
@@ -596,8 +636,17 @@ Where the current ready 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`.
-The default Captain's ready entry is
-`{ type: 'BOSS_INTENT', bossIntent: turn.text }`.
+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
+deterministic command-parse resolution, supplied through the linked options'
+controller port, to the rewritten machine's hub entry union —
+`{ type: 'BOSS_TURN', bossText: turn.text }` for an undecided turn,
+`{ type: 'PARSED_RESPOND', bossText: turn.text }` for a parse-resolved
+`respond`, `{ type: 'PARSED_ACTION', bossText: turn.text, decision }` carrying
+the injected parse-resolved decision object, and `{ type: 'SHUTDOWN' }` for the
+host's teardown resolution — and invokes no classifier judge call; the exact
+original text still rides only the runtime-owned textual payload field.
 All other non-empty turns shall use `callJudge` only to choose one of the FSM's
 event kinds and non-text routing fields, or no FSM action.
 The classifier prompt shall include the exact, unmodified `turn.text` in a
@@ -677,7 +726,7 @@ If a host forwards text beginning with `/` to `handleBossInput`, the runtime tre
 Hosts that receive structured control input shall resolve host-level concerns before choosing a playbook runtime.
 Once they call `handleBossInput`, they shall pass the Boss content as text and shall not pre-classify in-playbook FSM events or rely on slash forms as a runtime protocol.
 
-`BOSS_INTERRUPT` (or the FSM's equivalent explicit-state-jump event) is reached only by the judge choosing it and supplying its required target payload.
+Within `handleBossInput` classification, `BOSS_INTERRUPT` (or the FSM's equivalent explicit-state-jump event) is reached only by the judge choosing it and supplying its required target payload; `apply()` of a runtime-advertised action (§Control surface) is the second, runtime-validated path to the same events, and on neither path does the host fabricate an FSM event itself.
 It is _not_ an abort surface; aborts go through the abort signal and the strategies in §Abort.
 Hosts where the abort signal is terminal (e.g., SIGINT runs shutdown) shall not route abort to `BOSS_INTERRUPT`.
 
@@ -696,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.
@@ -746,6 +798,55 @@ presentation. The linked
 runtime shall not make a second visible Captain call or expose the hidden
 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 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
+`{ visibility: 'hidden' }` on the host's durable conversation, whose resume
+token the host pins and rotates (DR-029), and the decision call's reply
+is the `{ action, … }` control JSON itself — validated by the linked runtime
+against the declared decision-state contract rather than adjudicated through
+a separate judge call, with exactly one corrective re-ask appending the
+rejection reason and the restated reply contract (the DR-025 corrective
+pattern). Because the host owns that conversation, the `resume` member the
+runtime is required to pass on a controller call carries no continuity
+meaning: the runtime passes `resume: false` because it holds no token, and
+the host's pinned durable selection overrides it — a controller call shall
+never be read as a request for a fresh conversation.
+
+The validated selection is not itself an effect. The linked runtime shall
+submit it through the host-supplied controller port the linker exposed as an
+option member (§PlaybookRuntime contract) and shall take the returned
+settlement as the only evidence of what happened. That settlement, carried
+beside the selected action as the guard discriminant, is the decision
+invocation's own result — the actor output the decision state's `onDone` arms
+select on and its evidence action records — so the effect reports through the
+same invocation that decided it, with no second boundary and no host-sent
+event. A controller prose state (a parse-resolved `respond` reply, an acting
+turn's closing reply) settles on its declared single outcome and returns no
+prose to the machine at all.
+
+That reply is control data, never Boss presentation: the runtime
+shall not inject the `question` or `response` presentation fields into a
+controller result — no visible Captain call exists to own them. Controller
+prose reaches the Boss only as host-validated captain speech surfaced
+through the host's presentation seam, cligent `CaptainContext.emitReply`
+(DR-029). Because no prose returns to the machine and no presentation
+field is injected, the host's own `callCaptain` implementation is that seam:
+it already holds the `CaptainResult` of the call it just served, and it
+identifies which call that is from the paired `captain.call.started` boundary
+the runtime emits before invoking the port, whose identity carries the
+invoking `stateId` and `sourceItem` (§Playbook trace). No prose therefore
+needs a return path through the machine, and none exists.
+The visible-call `question`/`response` injection rule above and
+the `{ visibility: 'visible', resume: false }` workflow-call selection
+(§PlaybookPorts contract, §Captain prompt composition) stay the
+visible-presentation shape for non-controller playbooks.
+
 The adjudicator shall fail loudly on:
 
 - A guard the state does not declare,
@@ -791,9 +892,9 @@ independent cleanup evidence.
 ## Script execution
 
 Where the FSM declares the typed `script` actor from
-[gears2fsm "Setup"](gears2fsm.md#setup), the linked runtime shall provide
-its implementation through the shared factory (§Output); the linker shall
-not regenerate a script executor inside each emitted module.
+[gears2fsm "Setup"](gears2fsm.md#setup), a factory-backed linked runtime shall
+provide its implementation through the shared factory (§Output); the linker
+shall not regenerate a script executor inside a factory-backed emitted module.
 A script invocation is the one actor kind that runs without any agent:
 it makes no `callPlayer`, `callCaptain`, or `callJudge` call and needs no
 adjudication.
@@ -1090,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.
@@ -1170,6 +1288,162 @@ not `active` or whose state descriptor cannot be normalized shall fail
 A restore failure shall leave the runtime unbound so `dispose` remains
 callable and terminal.
 
+## Control surface (optional)
+
+A linked runtime may implement the optional control-surface capability of
+`@sublang/playbook/runtime` — `describe()` and `apply(...)` — so a host can
+observe the parked machine and execute a runtime-advertised recovery or jump
+action without fabricating an FSM event (DR-029). A runtime that
+implements either member shall implement both; every runtime the shared
+`createXStatePlaybookRuntime` factory constructs implements the pair. A
+runtime lacking the pair advertises no actions, and plain text delivery is
+the only verb against it. Presence is feature-detected like the
+parked-session snapshot capability; the pair changes no runtime ABI and no
+artifact or snapshot schema.
+
+```typescript
+interface PlaybookControlAction {
+  id: string;      // stable within the returned view
+  label: string;   // runtime-written, Boss-appropriate
+}
+
+interface PlaybookControlView {
+  state: PlaybookState;
+  stateDescription?: string;  // runtime-published meaning of the current state
+  context?: JsonValue;   // the runtime's authored projection, sanitized
+  pendingQuestions: readonly PlaybookPendingBossQuestion[];
+  lastError?: NormalizedError;
+  actions: readonly PlaybookControlAction[];
+}
+
+type PlaybookControlReceipt =
+  | { disposition: 'rejected'; reason: string }          // before any effect
+  | { disposition: 'executed'; run: PlaybookRunResult }
+  | { disposition: 'failed'; error: NormalizedError };   // effects may exist
+
+// Optional PlaybookRuntime members — both or neither:
+describe?(): PlaybookControlView;
+apply?(input: { actionId: string; key: string; signal: AbortSignal }): Promise<PlaybookControlReceipt>;
+```
+
+`describe()` shall be side-effect free — it emits no trace, status, or
+telemetry and moves no machine state — and is valid at parked quiescence
+outside an active `handleBossInput`/`resumePlaybookCall`/`apply` boundary;
+during an active boundary, before `init`, or after disposal begins it shall
+throw. The view carries the current normalized state descriptor, the state
+description defined below, the authored context projection defined below, the
+pending Boss questions with their stable ids, the last recorded error in
+normalized form, and the currently valid actions.
+
+`stateDescription` is the runtime's own Boss-facing statement of what its
+current state means, taken from the same source state descriptions the action
+labels below are written from. A controller host has no other grounding for a
+status answer, and an internal state id is not text a reply may repeat, so the
+runtime publishes the meaning rather than leaving the host to substitute the
+identifier for it. A state whose source declares no description carries no
+`stateDescription`: an id is never promoted into a description, so a host is
+never handed an identifier dressed as meaning.
+
+The view's `context` is an explicit projection the linked runtime **authors**,
+never an allow-by-default serialization of the FSM context (PBRT-52).
+Only the runtime knows which of its context members are safe and relevant
+for a controller prompt, while the host receiving the view cannot inspect an
+opaque blob for the player rosters, option values, and raw player output its
+own prompts must exclude; exporting by default makes the two obligations
+unsatisfiable together and gives every member added to an FSM later the wrong
+default. The rules:
+
+- The emitted module declares the projection in its `spec` as
+  `controlContextFields` — the FSM context member names its view exposes, in
+  the order it names them — and the factory exports those and nothing else.
+- A runtime naming no member carries no `context` at all, so a member is
+  private until an artifact names it and extending an FSM leaks nothing by
+  omission.
+- Sanitization sits on top of the projection, not in place of it: a named
+  member is still normalized (raw `Error` values normalized) and dropped when
+  it cannot be made JSON-safe, rather than thrown, since `describe` stays
+  side-effect free and total.
+- The two members the view surfaces first-class — the pending Boss question
+  and the last error — cannot be named. A projection naming either is a
+  construction error, failing runtime construction rather than being silently
+  ignored.
+- The host still composes its own prompt block from the projection rather than
+  pasting the projection in, so no runtime's exported value can forge a block
+  into an envelope the host owns.
+
+Actions derive from the live snapshot, only at the same safe point the
+parked-session snapshot uses (actor status `active`, quiescent, no pending
+nested call); anywhere else `actions` is empty while the rest of the view
+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.
+- **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
+  runtime shall advertise `jump:<stateId>`.
+
+A candidate whose event requires a payload the runtime cannot source from
+recorded state shall be excluded from `actions` — `apply` never invents free
+text and never enters Boss-input classification. A candidate whose *label*
+could only be an identifier is excluded on the same terms: a label never falls
+back to a target id or to the replayed event type, because a controller host
+names an executed or refused action by its label and never by its id, so an
+identifier used as a label defeats that substitution. A jump whose target
+publishes no description is therefore not advertised — borrowing another
+state's description would name the wrong state — and a retry falls back from
+its target's description to its own source state's, and is not advertised when
+neither exists.
+
+`apply({ actionId, key, signal })` shall revalidate the action against the
+live state and settle `{ disposition: 'rejected', reason }` with no effect
+when it is no longer advertised. It shall execute an accepted action at most
+once per idempotency `key`: the receipt is recorded at acceptance, before
+the settlement emissions, and a repeated key returns the recorded receipt
+verbatim with no revalidation, no execution, and no new trace pair within the
+runtime instance.
+Only accepted receipts (`executed` or `failed`) are recorded and final for
+their key. A rejection settles before acceptance and records nothing under
+its key — a later call with that key revalidates afresh, traces its own
+pair, and may execute once the action is advertised — and a key whose call
+threw before reaching acceptance (lifecycle misuse, invalid input, a
+pre-acceptance abort, a rejected start-boundary sink) likewise records
+nothing, so a later call with that key may execute. Executing sends the
+validated event through the same actor drive as `handleBossInput` — state
+transitions, player/judge boundaries, statuses, and traces flow unchanged —
+and settles `executed` with the projected run result, or `failed` with the
+normalized error when the run settles in the failure state, aborts, or a
+post-acceptance control-plane error lands (effects may exist). `signal`
+follows §Abort exactly as a Boss-turn signal does; an abort after acceptance
+settles the `failed` receipt rather than rejecting. The boundary traces as
+the paired `apply.started` / `apply.finished` events of §Playbook trace, and
+`apply` shares the single active-boundary sentinel with `handleBossInput`
+and `resumePlaybookCall`.
+
+Acceptance is also the line past which `apply` does not throw, and
+publication — the `apply.finished` emission — is the line past which its
+receipt no longer changes. A settlement failure after acceptance but before
+publication (a rejecting emission drain) settles the `failed` receipt carrying
+its normalized error, replacing the one recorded at acceptance so the finish
+trace, the returned receipt, and any replay of the key report one settlement.
+A settlement failure at or after publication (a rejecting `apply.finished`
+sink) does not: the disposition is already emitted, so no rewrite can make the
+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.
+
+The recorded receipts and the recorded last classified event are
+process-local: the schema-1 parked-session snapshot persists neither, and a
+restored runtime advertises a retry again only after its next classified
+event.
+
 ## Abort
 
 `handleBossInput.signal` is the abort surface.
@@ -1245,19 +1519,25 @@ The `playbook.trace` copies are the host-agnostic runtime-boundary record requir
 
 ## Output
 
-The link compiler emits **one thin** TypeScript module per playbook.
+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 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).
 The FSM-interpreter machinery — actor wiring, boundary tracing, Boss-event
 mapping, adjudication, script execution, nested-playbook bridging, session
 lifecycle, abort handling, and the optional parked-session snapshot
-capability — is not regenerated per artifact: it ships once as the shared
-`createXStatePlaybookRuntime(machine, spec)` factory exported by
+capability — is not regenerated for a factory-backed artifact: it ships once
+as the shared `createXStatePlaybookRuntime(machine, spec)` factory exported by
 `@sublang/playbook/xstate-runtime`, and the emitted module hands its FSM and
 a small per-playbook `spec` to that factory. Every behavioral section of
 this definition still binds the emitted module's runtime; the shared factory
 is how the emitted module satisfies them, so a runtime fix ships as a
 package release instead of a re-link of every artifact.
 
-The emitted module:
+The thin emitted module:
 
 - Imports the FSM artifact by relative path with an extension-bearing
   runtime specifier. When the linked TypeScript is part of a package that
@@ -1297,10 +1577,28 @@ The emitted module:
   exceptions not covered by the canonical kebab-token-to-camel-field mapping
   and the canonical `<#>` → `irNumber` special case; the
   transition-event payload fields the FSM's Boss union declares; a
-  non-default player binding where the linker inputs supplied one; and any
+  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
-  definition requires for that playbook. The metadata shall keep the shared
+  definition requires for that playbook.
+  `controlContextFields` is authored, not derived: the linker names the FSM
+  context members the playbook's controller view exposes and no others, in the
+  order the view should render them, omitting the member entirely where the
+  playbook exposes no context. It is the one spec member whose default is
+  *nothing* rather than everything — the factory exports no context for a
+  module that supplies none — so a module emitted without it advertises a
+  playbook with no Boss-visible context rather than one whose whole FSM
+  context is Boss-visible. The linker shall not name a member the view
+  surfaces first-class (the pending Boss question, the last error), which is a
+  construction error, and shall not name a member carrying a resolved player
+  roster, an option value, or player-authored text, which a controller host's
+  prompts are required to exclude or to fence. The metadata shall keep the shared
   classifier's reply contract exactly flat `{ type, ...declaredFields }` and
   distinguish judge-authored routing fields from exact-text fields the
   runtime attaches itself. Everything else — player/script/captain/nested actor
@@ -1320,7 +1618,13 @@ The 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>>;
   ```
 
@@ -1352,10 +1656,16 @@ The emitted module:
 - Default-exports the factory call as `createPlaybookRuntime`, typed
   `PlaybookRuntimeFactory<PlaybookRuntimeOptions>`.
 - Exposes, under an `_internal` export, the pure helpers verification
-  needs — at least the player-prompt and Captain-prompt composers
-  (`composePlayerPrompt` and `composeCaptainPrompt`), which may re-export
-  the shared defaults when the spec does not override composition — so
-  compilation-correctness tests can exercise composition without a host.
+  needs — at least the prompt composers its own machine uses, which may
+  re-export the shared defaults when the spec does not override composition —
+  so compilation-correctness tests can exercise composition without a host.
+  A playbook that calls players exposes `composePlayerPrompt`; a playbook
+  whose states make direct-Captain calls exposes `composeCaptainPrompt`. A
+  controller playbook that calls no players exposes no player composer:
+  there is no composition to verify, and a stub under that name would
+  describe work the module cannot do. `_internal` is not a public API — the
+  leading underscore says so — and nothing in it is semver-stable; a helper
+  a host is meant to call is a top-level export and is governed as one.
 - Holds no host-specific types and no host primitive calls. The runtime
   speaks only `PlaybookPorts` for every agent and host concern; the
   `node:child_process` dependency of §Script execution lives in the shared
@@ -1364,6 +1674,7 @@ The 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`,
@@ -1375,6 +1686,9 @@ The emitted module:
   dependency runs one way — from each linked module to the shared
   engine and contract, never the reverse.
 
+Both output profiles remain subject to the behavioral sections above and the
+verification requirements below.
+
 When a co-located integration test for the linked runtime already exists, the
 link compiler shall run it before reporting success and treat any failure as a
 generation failure. It shall not delete, skip, or weaken that suite to make a