@sublang/playbook 7.0.0 → 9.0.0

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

@@ -1,9 +1,10 @@
+import { type XStatePromptIdentity } from '@sublang/playbook/xstate-runtime';
 import { type PlayerInput, type ReviewInput } from './review.fsm.js';
 import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore } from '@sublang/playbook/runtime';
 export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore, };
 export type ReviewPlaybookOptions = ReviewInput;
 /** Keep every line of a relayed runtime value inside its authored quote. */
-declare function composePlayerPrompt(input: PlayerInput): string;
+declare function composePlayerPrompt(input: PlayerInput, promptIdentity: XStatePromptIdentity): string;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;

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

@@ -3,15 +3,14 @@
 //
 // Generated by slc/link.md (FSM-to-Runtime linker).
 // Source FSM:    ./review.fsm.ts
-// Player bind:   Coder→coder, Reviewer→reviewer (default lowercased binding)
+// Role metadata: Coder→coder, Reviewer→reviewer (canonical local roles)
 // Boss event:    deterministic START_REVIEW entry; exact Boss text becomes
 //                callerInput; pending player questions retain BOSS_REPLY
 // Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
 //                carried verbatim
-// Compat:        artifact schema 1 / runtime ABI 1
-import { RUNTIME_ABI, createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
+// Compat:        artifact schema 2 / runtime ABI 1
+import { createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { reviewMachine, } from './review.fsm.js';
-const OPTION_KEYS = new Set(['coderLlm', 'reviewerLlm']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
 const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 const VERBATIM_PAYLOAD_FIELDS = new Set([
@@ -27,15 +26,7 @@ function snapshotReviewOptions(value) {
     }
     const record = captured;
     for (const key of Object.keys(record)) {
-        if (!OPTION_KEYS.has(key)) {
-            throw new TypeError(`REVIEW runtime options.${key} is not declared`);
-        }
-    }
-    for (const key of OPTION_KEYS) {
-        const option = record[key];
-        if (typeof option !== 'string' || option.trim().length === 0) {
-            throw new TypeError(`REVIEW runtime options.${key} must be a non-empty string`);
-        }
+        throw new TypeError(`REVIEW runtime options.${key} is not declared`);
     }
     return captured;
 }
@@ -48,10 +39,14 @@ function quotedContinuation(value) {
     return value.replaceAll('\n', '\n> ');
 }
 /** Keep every line of a relayed runtime value inside its authored quote. */
-function composePlayerPrompt(input) {
+function composePlayerPrompt(input, promptIdentity) {
     const fields = input;
     const body = input.prompt.replace(PLACEHOLDER, (match, token, offset, source) => {
-        const value = fields[placeholderField(token)];
+        const value = token === 'coder-llm'
+            ? promptIdentity('coder')
+            : token === 'reviewer-llm'
+                ? promptIdentity('reviewer')
+                : fields[placeholderField(token)];
         if (typeof value !== 'string')
             return match;
         const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
@@ -76,28 +71,39 @@ export const _internal = {
 };
 const runtimeSpec = {
     label: 'REVIEW',
-    compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+    // DR-022 / slc/link.md: the declaration carries the value current at link
+    // time — a literal, never the loading engine's RUNTIME_ABI self-report,
+    // which would follow whatever engine loads the module and make the
+    // factory's skew check compare that engine with itself.
+    compat: { artifactSchema: 2, runtimeAbi: 1 },
     snapshotOptions: snapshotReviewOptions,
-    entryEvent: { type: 'START_REVIEW', textField: 'callerInput' },
-    playerStates: {
+    entryEvent: {
+        type: 'START_REVIEW',
+        textField: 'callerInput',
+        // `copyStartInput` copies the entry text here, so the failure-state
+        // retry reads it back from the persisted machine snapshot and survives
+        // a continued session (DR-034).
+        contextField: 'callerInput',
+    },
+    roleStates: {
         reviewInitial: {
-            player: 'Reviewer',
+            role: 'reviewer',
             label: 'REVIEW-1: Reviewer examines the latest commit against the caller input.',
         },
         addressFindings: {
-            player: 'Coder',
+            role: 'coder',
             label: 'REVIEW-2: Coder accepts or rejects every current review finding.',
         },
         reviewAfterCommit: {
-            player: 'Reviewer',
+            role: 'reviewer',
             label: 'REVIEW-3: Reviewer examines the new review-fix commit and repository state.',
         },
         reviewAfterRebuttal: {
-            player: 'Reviewer',
+            role: 'reviewer',
             label: 'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
         },
     },
-    composePlayerPrompt: (input) => composePlayerPrompt(input),
+    composePlayerPrompt: (input, promptIdentity) => composePlayerPrompt(input, promptIdentity),
     verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
     controlContextFields: [],
     transitionEventFields: [

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

@@ -3,18 +3,18 @@
 //
 // Generated by slc/link.md (FSM-to-Runtime linker).
 // Source FSM:    ./review.fsm.ts
-// Player bind:   Coder→coder, Reviewer→reviewer (default lowercased binding)
+// Role metadata: Coder→coder, Reviewer→reviewer (canonical local roles)
 // Boss event:    deterministic START_REVIEW entry; exact Boss text becomes
 //                callerInput; pending player questions retain BOSS_REPLY
 // Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
 //                carried verbatim
-// Compat:        artifact schema 1 / runtime ABI 1
+// Compat:        artifact schema 2 / runtime ABI 1
 
 import {
-  RUNTIME_ABI,
   createXStatePlaybookRuntime,
   snapshotJsonValue,
   type PlaybookPlayerInput,
+  type XStatePromptIdentity,
   type XStatePlaybookRuntimeSpec,
 } from '@sublang/playbook/xstate-runtime';
 import {
@@ -76,7 +76,6 @@ export type {
 
 export type ReviewPlaybookOptions = ReviewInput;
 
-const OPTION_KEYS = new Set(['coderLlm', 'reviewerLlm']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
 const CONTINUATION_PREAMBLE =
   'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
@@ -97,17 +96,7 @@ function snapshotReviewOptions(value: unknown): ReviewPlaybookOptions {
   }
   const record = captured as Readonly<Record<string, JsonValue>>;
   for (const key of Object.keys(record)) {
-    if (!OPTION_KEYS.has(key)) {
-      throw new TypeError(`REVIEW runtime options.${key} is not declared`);
-    }
-  }
-  for (const key of OPTION_KEYS) {
-    const option = record[key];
-    if (typeof option !== 'string' || option.trim().length === 0) {
-      throw new TypeError(
-        `REVIEW runtime options.${key} must be a non-empty string`,
-      );
-    }
+    throw new TypeError(`REVIEW runtime options.${key} is not declared`);
   }
   return captured as unknown as ReviewPlaybookOptions;
 }
@@ -124,12 +113,20 @@ function quotedContinuation(value: string): string {
 }
 
 /** Keep every line of a relayed runtime value inside its authored quote. */
-function composePlayerPrompt(input: PlayerInput): string {
+function composePlayerPrompt(
+  input: PlayerInput,
+  promptIdentity: XStatePromptIdentity,
+): string {
   const fields = input as unknown as Record<string, unknown>;
   const body = input.prompt.replace(
     PLACEHOLDER,
     (match: string, token: string, offset: number, source: string) => {
-      const value = fields[placeholderField(token)];
+      const value =
+        token === 'coder-llm'
+          ? promptIdentity('coder')
+          : token === 'reviewer-llm'
+            ? promptIdentity('reviewer')
+            : fields[placeholderField(token)];
       if (typeof value !== 'string') return match;
       const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
       return source.slice(lineStart, offset) === '> '
@@ -156,34 +153,47 @@ export const _internal = {
   VERBATIM_PAYLOAD_FIELDS,
 };
 
-const runtimeSpec: XStatePlaybookRuntimeSpec<ReviewPlaybookOptions> = {
+const runtimeSpec = {
   label: 'REVIEW',
-  compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+  // DR-022 / slc/link.md: the declaration carries the value current at link
+  // time — a literal, never the loading engine's RUNTIME_ABI self-report,
+  // which would follow whatever engine loads the module and make the
+  // factory's skew check compare that engine with itself.
+  compat: { artifactSchema: 2, runtimeAbi: 1 },
   snapshotOptions: snapshotReviewOptions,
-  entryEvent: { type: 'START_REVIEW', textField: 'callerInput' },
-  playerStates: {
+  entryEvent: {
+    type: 'START_REVIEW',
+    textField: 'callerInput',
+    // `copyStartInput` copies the entry text here, so the failure-state
+    // retry reads it back from the persisted machine snapshot and survives
+    // a continued session (DR-034).
+    contextField: 'callerInput',
+  },
+  roleStates: {
     reviewInitial: {
-      player: 'Reviewer',
+      role: 'reviewer',
       label:
         'REVIEW-1: Reviewer examines the latest commit against the caller input.',
     },
     addressFindings: {
-      player: 'Coder',
+      role: 'coder',
       label: 'REVIEW-2: Coder accepts or rejects every current review finding.',
     },
     reviewAfterCommit: {
-      player: 'Reviewer',
+      role: 'reviewer',
       label:
         'REVIEW-3: Reviewer examines the new review-fix commit and repository state.',
     },
     reviewAfterRebuttal: {
-      player: 'Reviewer',
+      role: 'reviewer',
       label:
         'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
     },
   },
-  composePlayerPrompt: (input: PlaybookPlayerInput) =>
-    composePlayerPrompt(input as PlayerInput),
+  composePlayerPrompt: (
+    input: PlaybookPlayerInput,
+    promptIdentity: XStatePromptIdentity,
+  ) => composePlayerPrompt(input as PlayerInput, promptIdentity),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   controlContextFields: [],
   transitionEventFields: [
@@ -193,7 +203,7 @@ const runtimeSpec: XStatePlaybookRuntimeSpec<ReviewPlaybookOptions> = {
     'answer',
     'questionId',
   ],
-};
+} satisfies XStatePlaybookRuntimeSpec<ReviewPlaybookOptions>;
 
 const createPlaybookRuntime: PlaybookRuntimeFactory<ReviewPlaybookOptions> =
   createXStatePlaybookRuntime(reviewMachine, runtimeSpec);

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

@@ -1,4 +1,4 @@
-import { type PlaybookRuntime, type ReviewPlaybookOptions } from './review.playbook.js';
+import { type PlaybookRuntime } from './review.playbook.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -7,24 +7,17 @@ export interface PlaybookSummaryPolicy {
         copyPastes: number;
     }, rounds: number): string;
 }
-export interface RegistryPlayer {
-    id: string;
-    adapter?: string;
-    model?: string;
-}
-export interface CreateReviewRuntimeOptions {
-    captainOptions: unknown;
-    players: readonly RegistryPlayer[];
-}
 export type ReviewOptions = Readonly<Record<string, never>>;
 export interface ReviewPlaybookRegistryEntry {
     id: 'review';
     command: 'review';
     intent: string;
+    artifactSchema: 2;
     requiredRoleIds: readonly ['coder', 'reviewer'];
+    concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
-    validateOptions(captainOptions: unknown): ReviewOptions;
-    createRuntime(options: CreateReviewRuntimeOptions): PlaybookRuntime;
+    validateOptions(optionSlice: unknown): ReviewOptions;
+    createRuntime(options: ReviewOptions): PlaybookRuntime;
 }
 export declare const reviewStateCountLabels: {
     readonly reviewInitial: "review round";
@@ -38,6 +31,5 @@ export declare function reviewSavedCountsLine(counts: {
 }, rounds: number): string;
 export declare const reviewSummaryPolicy: PlaybookSummaryPolicy;
 export declare function validateReviewOptions(optionSlice: unknown): ReviewOptions;
-export declare function createReviewRuntimeOptions({ captainOptions, players, }: CreateReviewRuntimeOptions): ReviewPlaybookOptions;
 export declare const reviewPlaybookRegistryEntry: ReviewPlaybookRegistryEntry;
 export default reviewPlaybookRegistryEntry;

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

@@ -44,30 +44,17 @@ export function validateReviewOptions(optionSlice) {
     }
     return Object.freeze({});
 }
-function playerIdentity(players, id) {
-    const player = players.find((entry) => entry.id === id);
-    const identity = player?.model ?? player?.adapter;
-    if (identity === undefined || identity.trim().length === 0) {
-        throw new Error(`REVIEW requires configured player ${id}`);
-    }
-    return identity;
-}
-export function createReviewRuntimeOptions({ captainOptions, players, }) {
-    validateReviewOptions(captainOptions);
-    return {
-        coderLlm: playerIdentity(players, 'coder'),
-        reviewerLlm: playerIdentity(players, 'reviewer'),
-    };
-}
 export const reviewPlaybookRegistryEntry = {
     id: 'review',
     command: 'review',
     intent: 'review the latest commit until no material correctness or spec findings remain',
+    artifactSchema: 2,
     requiredRoleIds: ['coder', 'reviewer'],
+    concurrentRoleSets: [],
     summaryPolicy: reviewSummaryPolicy,
     validateOptions: validateReviewOptions,
     createRuntime(options) {
-        return createPlaybookRuntime(createReviewRuntimeOptions(options));
+        return createPlaybookRuntime(options);
     },
 };
 export default reviewPlaybookRegistryEntry;

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

@@ -3,7 +3,6 @@
 
 import createPlaybookRuntime, {
   type PlaybookRuntime,
-  type ReviewPlaybookOptions,
 } from './review.playbook.js';
 
 export interface PlaybookSummaryPolicy {
@@ -15,27 +14,18 @@ export interface PlaybookSummaryPolicy {
   ): string;
 }
 
-export interface RegistryPlayer {
-  id: string;
-  adapter?: string;
-  model?: string;
-}
-
-export interface CreateReviewRuntimeOptions {
-  captainOptions: unknown;
-  players: readonly RegistryPlayer[];
-}
-
 export type ReviewOptions = Readonly<Record<string, never>>;
 
 export interface ReviewPlaybookRegistryEntry {
   id: 'review';
   command: 'review';
   intent: string;
+  artifactSchema: 2;
   requiredRoleIds: readonly ['coder', 'reviewer'];
+  concurrentRoleSets: readonly [];
   summaryPolicy: PlaybookSummaryPolicy;
-  validateOptions(captainOptions: unknown): ReviewOptions;
-  createRuntime(options: CreateReviewRuntimeOptions): PlaybookRuntime;
+  validateOptions(optionSlice: unknown): ReviewOptions;
+  createRuntime(options: ReviewOptions): PlaybookRuntime;
 }
 
 export const reviewStateCountLabels = {
@@ -99,39 +89,18 @@ export function validateReviewOptions(optionSlice: unknown): ReviewOptions {
   return Object.freeze({});
 }
 
-function playerIdentity(
-  players: readonly RegistryPlayer[],
-  id: 'coder' | 'reviewer',
-): string {
-  const player = players.find((entry) => entry.id === id);
-  const identity = player?.model ?? player?.adapter;
-  if (identity === undefined || identity.trim().length === 0) {
-    throw new Error(`REVIEW requires configured player ${id}`);
-  }
-  return identity;
-}
-
-export function createReviewRuntimeOptions({
-  captainOptions,
-  players,
-}: CreateReviewRuntimeOptions): ReviewPlaybookOptions {
-  validateReviewOptions(captainOptions);
-  return {
-    coderLlm: playerIdentity(players, 'coder'),
-    reviewerLlm: playerIdentity(players, 'reviewer'),
-  };
-}
-
 export const reviewPlaybookRegistryEntry: ReviewPlaybookRegistryEntry = {
   id: 'review',
   command: 'review',
   intent:
     'review the latest commit until no material correctness or spec findings remain',
+  artifactSchema: 2,
   requiredRoleIds: ['coder', 'reviewer'],
+  concurrentRoleSets: [],
   summaryPolicy: reviewSummaryPolicy,
   validateOptions: validateReviewOptions,
   createRuntime(options) {
-    return createPlaybookRuntime(createReviewRuntimeOptions(options));
+    return createPlaybookRuntime(options);
   },
 };
 

package/slc/gears2fsm.md

@@ -36,7 +36,7 @@ map for every actor kind the GEARS artifact uses, using typed actor logic such
 as `fromPromise<Output, Input>(...)` [[11]]:
 
 - `captain` for direct work performed by Captain;
-- `player` for work Captain delegates to a named player;
+- `player` for work Captain delegates to a named role;
 - `playbook` for a nested playbook call; and
 - `script` for a deterministic shell script an
   [optimizer-introduced script item](text2gears.md#script-behaviors-optimizer-introduced)
@@ -73,7 +73,7 @@ comment delimiters into a TypeScript target.
 `PlayerInput` shall be a typed object with at least:
 
 - `stateId`: the stable id of the invoking working leaf;
-- `player`: the [player](text2gears.md#players) Captain is to invoke;
+- `role`: the canonical lowercase local id derived from the [role](text2gears.md#roles) Captain is to delegate;
 - `sourceItem`: the GEARS item ID this state realizes;
 - `prompt`: the source item's full final prompt, verbatim;
 - `result`: a record whose keys are the valid guard names this invocation may return.
@@ -244,22 +244,25 @@ 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, player? } }` repeating
-  its stable id and description so linked runtimes can discover active public
+- JSON-safe `meta: { playbook: { stateId, description, role? } }` naming the
+  state's public playbook identity per the identity rule below and repeating
+  its description so linked runtimes can discover active public
   identities through `snapshot.getMeta()` without private XState nodes. A
-  delegated-player state shall also carry the exact source player in
-  `meta.playbook.player`; every other state shall omit `player`;
+  delegated-role state shall also carry the canonical lowercase source role id in
+  `meta.playbook.role`; every other state shall omit `role`;
 - 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 the same source-derived `player` as `meta.playbook.player`;
+  carrying the same source-derived `role` as `meta.playbook.role`;
 - if it invokes the `script` actor: `invoke.input` carrying `stateId`,
   `sourceItem`, `command`, and `result` (per [Setup](#setup)) — no `prompt`
-  and no `player`.
+  and no `role`.
 
 The source item ID shall live in `invoke.input.sourceItem`, not in a comment — this keeps the GEARS-to-state mapping machine-readable.
-A delegated state's `invoke.input.player` shall match its source item's named
-player. A direct Captain state shall not invent a `Captain` player binding.
+
+Outside a parallel group's regions, a state's `meta.playbook.stateId` shall equal its state key — the one identity a factory-backed linked runtime indexes by.
+A delegated state's `invoke.input.role` shall match the canonical lowercase id of its source item's named role.
+A direct Captain state shall not invent a `Captain` role binding.
 
 Every invoking working leaf — sequential or parallel, whatever its actor
 kind — shall carry the tag `playbook.busy`: the shared quiescence helper
@@ -281,7 +284,7 @@ invoke: {
     src: 'player',
     input: ({ context }): PlayerInput => ({
         stateId: '<stable-state-id>',
-        player: 'Reviewer',
+        role: 'reviewer',
         sourceItem: '<ITEM-A>',
         prompt: [
             'Flag any issues or improvements (numbered; no duplication).',
@@ -299,17 +302,17 @@ invoke: {
 
 For an item in which Captain acts directly, the corresponding invocation uses
 `src: 'captain'` and a `CaptainInput` with the same static mapping fields but no
-`player` field.
+`role` field.
 
 ## Mapping
 
 Each Source spec item shall map to exactly one state in Target.
 A state's `invoke.input.sourceItem` shall be that item's ID, and `invoke.input.prompt` shall carry the item's prompt verbatim.
 
-An item written as direct Captain work shall map to exactly one `captain`
-invocation. An item that prompts or relays to a named player shall map to
-exactly one `player` invocation. A nested-call item shall map to exactly one
-`playbook` invocation. A script item (`Captain shall run:`) shall map to
+An item written as direct Captain work shall map to exactly one `captain` invocation.
+An item that prompts or relays to a named role shall map to exactly one `player` invocation.
+A nested-call item shall map to exactly one `playbook` invocation.
+A script item (`Captain shall run:`) shall map to
 exactly one `script` invocation whose `input.command` carries the blockquote
 verbatim and whose `result` preserves the item's two guards in declared order.
 The compiler shall not infer one actor kind from a
@@ -333,10 +336,14 @@ Each member shall be a delegated-player item; a direct-Captain or nested-call
 member is malformed because those actor kinds share one Captain control lane or one
 pending-child slot. Each region shall contain a delegated-player working leaf
 and a local final state; the working leaf retains the item's stable state id,
-`sourceItem`, player, prompt, and result contract.
+`sourceItem`, role, prompt, and result contract.
+The members' canonical role ids shall be pairwise distinct; a repeated role in one group is malformed.
 The parallel parent shall use `onDone` as the join, which XState takes only
 after every region reaches final.
 
+The artifact shall export `concurrentRoleSets` as a deeply readonly array containing one role-id array per parallel group in first-item source order, with each inner array following that group's item order.
+An artifact with no parallel group shall export an empty array.
+
 Each branch shall assign only its own staged result.
 The join shall promote all staged results atomically before later work begins,
 so branch completion order cannot change downstream inputs.
@@ -527,8 +534,8 @@ the number of sequential child calls without an arbitrary runtime call limit.
 Prompts shall pass only the **specific extracted fields** the player needs.
 The compiler shall not dump `JSON.stringify(lastResult)` or any opaque blob: it leaks internal `guard` strings, wastes tokens, and confuses the LLM.
 
-Player bindings and per-run parameters shall flow in via the machine's `input` and be copied into context at start-up.
-The artifact shall not bake in player bindings, model names, or per-run values.
+Player bindings and prompt identities shall enter only through `PlaybookSession.roleBindings` at runtime call, prompt, and trace boundaries.
+The artifact shall not bake them into machine input, options, or context; model names and other host settings shall remain host policy rather than persisted FSM state.
 Host-owned configuration such as an enabled-playbook catalog shall remain
 immutable machine input/context for the session. Boss events and actor outputs
 shall not carry, replace, append to, or otherwise overwrite that catalog.
@@ -585,7 +592,7 @@ Phases may set typed routing fields so terminal outcomes return to the originati
 
 ## Boss control
 
-[Boss](text2gears.md#players) input enters the machine through three surfaces: pre-emptive interrupts on active states, typed entry events on idle or recoverable states, and Boss replies to player questions that suspended the FSM in a dedicated wait state.
+[Boss](text2gears.md#roles) input enters the machine through three surfaces: pre-emptive interrupts on active states, typed entry events on idle or recoverable states, and Boss replies to delegated-role questions that suspended the FSM in a dedicated wait state.
 
 ### Boss interrupts
 
@@ -667,12 +674,12 @@ the colon as the JSON field name.
 The linked runtime composes player prompts per [link.md "Player prompt composition"](link.md#player-prompt-composition), without adding a player-visible Boss-question instruction.
 
 The question record shall be
-`{ questionId, resumeStateId, sourceItem, player, question }`.
+`{ questionId, resumeStateId, sourceItem, asker, question }`, where `asker` is exactly `{ kind: 'captain' }` or `{ kind: 'role', roleId }`.
 `questionId` and `resumeStateId` shall both equal the stable working-leaf
 `stateId`.
-`questionId`, `resumeStateId`, and `sourceItem` shall come from the suspended
-working leaf's stable invocation metadata. `player` shall come from a delegated
-`PlayerInput`, or be the literal `Captain` for a direct-Captain state. Only
+`questionId`, `resumeStateId`, and `sourceItem` shall come from the suspended working leaf's stable invocation metadata.
+A delegated `PlayerInput` shall produce the role asker with its canonical local role id, while a direct-Captain state shall produce the Captain asker without inventing a role.
+Only
 `question` shall come from adjudicated actor output.
 
 A machine with at most one active Captain or player task may use the scalar
@@ -744,6 +751,20 @@ an unhandled runtime error.
 Every machine shall declare at least one `type: 'final'` state (typically `done`) reachable on completion.
 A never-terminating machine is a defect: the runner has no completion signal.
 
+At least one is a floor, not a ceiling. A final state's `description` is the
+machine's published terminal meaning: a host that cannot read the machine's
+output quotes that description to report what the run did. It shall therefore
+be true of every arm that enters the state and of no other terminal outcome.
+Where Source declares more than one terminal outcome — an approval that
+completes the workflow and a failure the workflow reports to its caller
+instead of parking — each outcome shall get its own `type: 'final'` state
+whose description names it. Routing an approval arm and a failure, abort, or
+invalid-result arm into one final state is a defect of the same kind as a
+wrong result field, because the quoting host cannot detect the difference.
+This constrains only published meaning: the declared machine `output` still
+derives its status and fields from typed context, so a caller that does read
+the output is unaffected.
+
 Where Source declares a JSON-safe terminal result, the setup types shall
 declare that output and the root machine shall derive it from typed context
 through XState's machine `output` function. A final-state transition alone does