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

package/slc/link.md

@@ -59,9 +59,17 @@ interface PlaybookSession {
   parentSessionId?: string;
   parentCallId?: string;
   depth: number;
+  playerSessions?: PlayerSessionStore;
   ports: PlaybookPorts;
 }
 
+interface PlayerSessionStore {
+  select(playerId: string): string | false;
+  update(playerId: string, resumeToken?: string): void;
+  snapshot(): Readonly<Record<string, string>>;
+  restore(tokens: Readonly<Record<string, string>>): void;
+}
+
 type JsonValue =
   | null
   | boolean
@@ -379,6 +387,11 @@ interface PlaybookTraceEvent {
 }
 ```
 
+A composing host may supply `playerSessions` as a frame-local view of player continuation owned by the root engagement tree.
+The runtime shall select through that view before allocating or tracing a player call and shall update or clear it from a validated player result before emitting the matching finish trace.
+Snapshot export and restore shall use the same view, failed restore shall leave its prior contents unchanged, and child disposal shall not clear host-owned continuation.
+A host that omits the view retains the runtime's private per-session continuation behavior.
+
 The trace types are `session.started`, `boss.input.received`,
 `judge.call.started`, `judge.call.finished`, `player.call.started`,
 `player.call.finished`, `captain.call.started`, `captain.call.finished`,
@@ -531,6 +544,7 @@ decides only the `callPlayer` invocation.
 The runtime shall compose the actual player prompt from the state's
 `PlayerInput`.
 `input.prompt` is the GEARS-derived domain prompt body and shall not be mutated, re-flowed, or treated as a place to store framework control instructions.
+A leading `>` inside that body is authored quoted-context content and shall reach the player unchanged.
 
 The composer may prepend structured labelled blocks from typed `PlayerInput`
 fields the FSM exposes (for example `Boss intent:`, `Review items:`,
@@ -731,6 +745,9 @@ clause (or equivalent typed output metadata). Backticked prose before that
 clause can name statuses, guards, or concepts such as `ok`, `aborted`, and
 `error`; those names are not output properties and shall never become required
 judge fields.
+For a delegated-player field annotated exactly `` `<field>: <verbatim final text>` ``, the judge shall select the guard but the runtime shall replace any judge-supplied value with the player's canonical non-empty final text before returning the actor output.
+The linker shall derive the complete `verbatimPayloadFields` set from those annotations across the FSM result maps.
+A field name that is annotated in one result map and unannotated in another is a link error because the shared adjudication strategy cannot give one property both ownership policies.
 For a direct Captain result, `question` and `response` are human-presentation
 fields owned by the visible call rather than fields authored by the hidden
 judge.
@@ -784,8 +801,8 @@ structured adjudication merely to present the same response.
 That visible-call presentation — visible Captain prose as the Boss
 presentation, a separate hidden adjudicator that never authors the
 `question`/`response` fields, and runtime injection of the visible
-`finalText` — stays scoped to visible-presentation playbooks such as CODE
-and DISCUSS. For a controller playbook, whose FSM declares the controller
+`finalText` — stays scoped to a working playbook whose FSM declares a visible
+direct-Captain state. For a controller playbook, whose FSM declares the controller
 decision-state class of [gears2fsm "Setup"](gears2fsm.md#setup), the
 Captain-call presentation admits the hidden controller form instead
 (DR-029): the decision and closing-reply Captain calls run
@@ -1174,6 +1191,23 @@ The `PlaybookRuntime` shall:
   failure cannot skip the parent disposal boundary or leave the runtime bound.
 
 The actor's `lastError` field shall be surfaced via `emitStatus` when the machine enters its `failed` state.
+Presence of linker-emitted `playerStates` selects the canonical
+factory-backed status profile. That profile shall emit the selected Boss event type
+before sending that event, exactly `→ <guard>` (with no payload-count or tally
+rider) when a settling actor output carries a guard, and
+`⤷ <Player>: <label>` only when the entered state appears in the
+linked module's `playerStates` metadata. It shall emit no raw state-id fallback
+for any other state. `playerStates` shall be a complete map of the FSM states
+that invoke the typed `player` actor; each value carries the exact player from
+that state's source-derived `meta.playbook.player` and the state's exact FSM
+description as `{ player, label }`. The factory shall reject an incomplete
+entry, a non-player state, or a player or label that differs from the FSM
+metadata. A schema-1 legacy module that predates this metadata
+shall preserve the prior factory status defaults, including no classification
+line, `Entered <stateId>.` for ordinary state entry, the single question line,
+and the unglyphed failure line. The new profile is opt-in so adding the seam
+does not silently reinterpret an already-linked artifact without an ABI or
+artifact-schema bump.
 For the default Captain runtime, an initial `ready` state and a terminal `done`
 state shall not emit human status. The terminal response is already visible
 Captain prose; a synthetic “entered done” message would present it twice.
@@ -1544,6 +1578,11 @@ The thin emitted module:
   and the canonical `<#>` → `irNumber` special case; the
   transition-event payload fields the FSM's Boss union declares; a
   non-default player binding where the linker inputs supplied one; the
+  complete `playerStates` status map derived from every FSM state that invokes
+  the typed `player` actor, with each `player` copied from that state's
+  source-derived `meta.playbook.player` (an empty map when there is no such
+  state); the
+  `verbatimPayloadFields` set derived from annotated result fields above; the
   `controlContextFields` projection of §Control surface; and any
   per-playbook strategy override (classifier, prompt composers,
   required-field extraction, status formatting) an earlier section of this
@@ -1579,7 +1618,13 @@ The thin emitted module:
     fields?: Readonly<Record<string, XStateBossEventFieldSpec>>;
   }
 
+  interface XStatePlayerStateStatus {
+    player: string;
+    label: string;
+  }
+
   bossEvents?: readonly XStateBossEventSpec[];
+  playerStates?: Readonly<Record<string, XStatePlayerStateStatus>>;
   placeholderFields?: Readonly<Record<string, string>>;
   ```
 
@@ -1629,6 +1674,7 @@ The thin emitted module:
   top-of-file header comment so the file is reproducible from the same
   inputs.
 - Sources the contract types (`PlayerResult`, `PlayerCallOptions`,
+  `PlayerSessionStore`,
   `CaptainResult`, `CaptainCallOptions`, `PlaybookPorts`, `PlaybookSession`,
   `PlaybookTraceEvent`,
   `PlaybookCallRequest`, `PlaybookCallResult`, `PlaybookCallStart`,

package/slc/text2gears.md

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

package/src/runtime.d.ts

@@ -7,6 +7,12 @@ export interface PlayerResult {
 export interface PlayerCallOptions {
     resume: string | false;
 }
+export interface PlayerSessionStore {
+    select(playerId: string): string | false;
+    update(playerId: string, resumeToken?: string): void;
+    snapshot(): Readonly<Record<string, string>>;
+    restore(tokens: Readonly<Record<string, string>>): void;
+}
 export interface CaptainCallOptions {
     visibility: 'visible' | 'hidden';
     resume: string | false;
@@ -106,6 +112,7 @@ export interface PlaybookSession {
     parentSessionId?: string;
     parentCallId?: string;
     depth: number;
+    playerSessions?: PlayerSessionStore;
     ports: PlaybookPorts;
 }
 export type PlaybookTraceType = 'session.started' | 'boss.input.received' | 'judge.call.started' | 'judge.call.finished' | 'player.call.started' | 'player.call.finished' | 'captain.call.started' | 'captain.call.finished' | 'playbook.call.started' | 'playbook.call.finished' | 'apply.started' | 'apply.finished' | 'fsm.transition' | 'status.emitted' | 'boss.input.settled' | 'session.disposed';

package/src/runtime.ts

@@ -19,6 +19,17 @@ export interface PlayerCallOptions {
   resume: string | false;
 }
 
+// DR-030: a composing host may supply one frame-local view of the root
+// engagement's player continuation. The runtime selects through this store
+// before tracing/calling and updates it from the validated result. Hosts that
+// omit it retain the runtime's private per-session store.
+export interface PlayerSessionStore {
+  select(playerId: string): string | false;
+  update(playerId: string, resumeToken?: string): void;
+  snapshot(): Readonly<Record<string, string>>;
+  restore(tokens: Readonly<Record<string, string>>): void;
+}
+
 export interface CaptainCallOptions {
   visibility: 'visible' | 'hidden';
   resume: string | false;
@@ -143,6 +154,7 @@ export interface PlaybookSession {
   parentSessionId?: string;
   parentCallId?: string;
   depth: number;
+  playerSessions?: PlayerSessionStore;
   ports: PlaybookPorts;
 }
 

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

@@ -67,6 +67,11 @@ export interface ScheduledStatus {
     message: string;
     data?: JsonValue;
 }
+/** Boss-facing identity for one FSM state whose invoked actor is `player`. */
+export interface XStatePlayerStateStatus {
+    player: string;
+    label: string;
+}
 export interface XStateBossEventFieldSpec {
     /** The judge supplies routing data; the runtime supplies exact Boss text. */
     source: 'judge' | 'text';
@@ -177,8 +182,10 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
      * recoverable FSM-result failures instead.
      */
     captainStrategy?: XStateCaptainStrategy<TOptions>;
-    /** Status line emitted after classification names an event. Default: none. */
+    /** Status line emitted after classification; canonical metadata defaults to the event type, legacy artifacts to none. */
     classificationStatus?: (event: EventObject) => string | undefined;
+    /** Complete FSM-derived Boss-facing metadata for every `player` state; its presence selects the canonical status profile. */
+    playerStates?: Readonly<Record<string, XStatePlayerStateStatus>>;
     /** Map a player-invoking state's input to the host player id. Default: lowercased player name. */
     resolvePlayerId?: (input: PlaybookPlayerInput, options: TOptions) => string;
     /** Compose the player prompt. Default: continuation blocks + `<field>` placeholder substitution. */
@@ -207,7 +214,7 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
     controlContextFields?: readonly string[];
     /** States that may suspend for a Boss reply. Default: targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
     resumableStateIds?: ReadonlySet<string>;
-    /** Human status lines for a root transition. Default: entry lines with question/failure surfacing. */
+    /** Human status lines for a root transition. Default: guard, declared-player, question, and failure lines. */
     statusesForState?: (state: PlaybookState, context: Record<string, unknown>, event: unknown) => readonly ScheduledStatus[];
     /** Detached JSON-safe transition-event descriptor. Default: `type` + `transitionEventFields` strings + validated output + normalized error. */
     normalizeTransitionEvent?: (event: unknown) => JsonValue | undefined;