@sublang/playbook 7.0.0 → 9.0.0

package/slc/text2gears.md

@@ -18,24 +18,24 @@ The second phase (spec items → state machine) is out of scope.
 | source | text   | .md       |
 | target | gears  | .md       |
 
-## Players
+## Roles
 
-Players name AI agents and the user.
+Roles name playbook-local delegated work functions.
 
-Two default players:
+Two fixed actors remain outside the role list:
 
 - Boss: the human user
 - Captain: the coordinating agent
 
-Source may declare additional players in an opening `Players:` section.
-A player may alias other players with `=` and `|`; Boss picks one at runtime.
+Source may declare delegated roles in an opening `Roles:` section.
+Each role shall be unique and shall not alias another role; concrete player selection and sharing belong to explicit host configuration.
+Role names shall also be unique after canonical lowercase-id derivation, so declarations such as `Coder` and `coder` reject rather than collapse to one manifest role.
 E.g.:
 
 - Coder
 - Reviewer
-- Committer = Coder | Reviewer
 
-Capitalize English player names (e.g., `Writer`); quote non-English names (e.g., `作者`) when needed to distinguish from prose.
+Capitalize English role names (e.g., `Writer`); quote non-English names (e.g., `作者`) when needed to distinguish from prose.
 
 ## Behaviors
 
@@ -47,15 +47,15 @@ will not be visible to downstream compilers or verification.
 The behavior kind shall be one of:
 
 - direct Captain work, written `Captain shall <behavior>:` without naming a
-  delegated player;
-- delegated player work, written `Captain shall prompt <Player>:` or the
-  existing `Captain shall relay ... to <Player> ...:` form; or
+  delegated role;
+- delegated-role work, written `Captain shall prompt <Role>:` or the
+  existing `Captain shall relay ... to <Role> ...:` form; or
 - a literal or dynamic nested playbook call as defined below.
 
 Direct Captain work means the coordinating Captain performs the behavior
 itself. It shall not be rewritten as `Captain shall prompt Captain`, because
-Captain is a distinct runtime actor rather than a player binding.
-Delegated work shall name the declared player that receives the prompt.
+Captain is a distinct runtime actor rather than a role binding.
+Delegated work shall name the declared role that receives the prompt.
 Prompts shall be blockquoted, one point per line.
 When Source already supplies the complete blockquoted acting prompt for a
 behavior, text2gears shall preserve those prompt lines exactly (apart from the
@@ -210,10 +210,11 @@ heading.
 Every item in one parallel group shall receive the same completed-prior-group
 inputs; no item prompt may depend on another member's result from the current
 group.
-Every member shall delegate to a named player, and the source shall permit
-those members to resolve to distinct players. Direct-Captain work shares one
+Every member shall delegate to a distinct named role; a group that repeats one canonical role is malformed because one role resolves to one player.
+Direct-Captain work shares one
 Captain session and nested calls share one pending-child stack slot, so neither
-kind may receive parallel-group metadata. If Source explicitly requires either
+kind may receive parallel-group metadata.
+If Source explicitly requires either
 unsupported kind to run concurrently, text2gears shall report that the source
 cannot be represented rather than silently serialize it or emit metadata the
 next phase cannot compile.
@@ -311,15 +312,15 @@ prose, acting prompts, and result descriptions follow the Source language,
 read per the matching localization of the GEARS definition [[1]].
 The four `Captain shall` acting-clause forms defined above (direct,
 delegated, nested playbook call, and script), guard names, and the
-`Players:` and `Results:` labels are fixed machine syntax and stay in this
+`Roles:` and `Results:` labels are fixed machine syntax and stay in this
 exact English form regardless of Source language.
 
 ## Transformation-spec sources
 
 A Source may itself be the normative specification of a transformation — e.g., a compiler phase definition, as when a meta pipeline compiles this file.
-Such a Source declares no players and prompts none; its implied procedure is that Captain performs the specified transformation on request.
+Such a Source declares no roles and prompts none; its implied procedure is that Captain performs the specified transformation on request.
 Compose Captain-acting spec items for it: when a transformation request names the specification's source and target, Captain shall carry out the transformation as specified.
-Prompts shall carry the specification's normative requirements as instructions to Captain — deduplicated, one point per line — without inventing players, triggers, or requirements the specification does not state.
+Prompts shall carry the specification's normative requirements as instructions to Captain — deduplicated, one point per line — without inventing roles, triggers, or requirements the specification does not state.
 
 ## Composition
 

package/src/runtime.d.ts

@@ -8,11 +8,15 @@ export interface PlayerCallOptions {
     resume: string | false;
 }
 export interface PlayerSessionStore {
-    select(playerId: string): string | false;
-    update(playerId: string, resumeToken?: string): void;
+    select(roleId: string): string | false;
+    update(roleId: string, resumeToken?: string): void;
     snapshot(): Readonly<Record<string, string>>;
     restore(tokens: Readonly<Record<string, string>>): void;
 }
+export interface PlaybookRoleBinding {
+    readonly playerId: string;
+    readonly promptIdentity: string;
+}
 export interface CaptainCallOptions {
     visibility: 'visible' | 'hidden';
     resume: string | false;
@@ -93,6 +97,7 @@ export type PlaybookRunResult = {
 } | {
     outcome: 'terminal';
     state: PlaybookState;
+    stateDescription?: string;
     output?: JsonValue;
 } | {
     outcome: 'suspended';
@@ -100,7 +105,7 @@ export type PlaybookRunResult = {
     pendingCall: PlaybookPendingCall;
 };
 export interface PlaybookPorts {
-    callPlayer(playerId: string, prompt: string, signal: AbortSignal, options: PlayerCallOptions): Promise<PlayerResult>;
+    callPlayer(roleId: string, prompt: string, signal: AbortSignal, options: PlayerCallOptions): Promise<PlayerResult>;
     callCaptain(prompt: string, signal: AbortSignal, options: CaptainCallOptions): Promise<CaptainResult>;
     callJudge(prompt: string, signal: AbortSignal): Promise<string>;
     callPlaybook(request: PlaybookCallRequest, signal: AbortSignal): Promise<PlaybookCallStart>;
@@ -117,12 +122,13 @@ export interface PlaybookSession {
     parentSessionId?: string;
     parentCallId?: string;
     depth: number;
+    roleBindings?: Readonly<Record<string, PlaybookRoleBinding>>;
     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';
 export interface PlaybookTraceEvent {
-    schemaVersion: 2;
+    schemaVersion: 3;
     sessionId: string;
     playbookId: string;
     rootSessionId: string;
@@ -138,15 +144,21 @@ export interface PlaybookTraceEvent {
 }
 export interface PlaybookPendingBossQuestion {
     questionId: string;
-    player: string;
+    asker: {
+        kind: 'captain';
+    } | {
+        kind: 'role';
+        roleId: string;
+    };
     question: string;
     sourceItem?: string;
 }
-interface PlaybookRuntimeSnapshotFields {
+export interface PlaybookRuntimeSnapshot {
+    schemaVersion: 3;
     playbookId: string;
     machine: JsonValue;
-    playerResumeTokens: {
-        readonly [playerId: string]: string;
+    roleResumeTokens: {
+        readonly [roleId: string]: string;
     };
     sequences: {
         trace: number;
@@ -158,14 +170,8 @@ interface PlaybookRuntimeSnapshotFields {
     };
     state: PlaybookState;
     pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
-}
-export type PlaybookRuntimeSnapshot = PlaybookRuntimeSnapshotFields & ({
-    schemaVersion: 1;
-    suspendedCall?: never;
-} | {
-    schemaVersion: 2;
     suspendedCall?: PlaybookSuspendedCall;
-});
+}
 export interface PlaybookControlAction {
     id: string;
     label: string;
@@ -210,4 +216,3 @@ export interface PlaybookRuntime {
     dispose(): Promise<void>;
 }
 export type PlaybookRuntimeFactory<Options = unknown> = (options: Options) => PlaybookRuntime;
-export {};

package/src/runtime.ts

@@ -19,17 +19,22 @@ 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
+// DR-032: a composing host may supply one frame-local role view of the
+// Captain session'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;
+  select(roleId: string): string | false;
+  update(roleId: string, resumeToken?: string): void;
   snapshot(): Readonly<Record<string, string>>;
   restore(tokens: Readonly<Record<string, string>>): void;
 }
 
+export interface PlaybookRoleBinding {
+  readonly playerId: string;
+  readonly promptIdentity: string;
+}
+
 export interface CaptainCallOptions {
   visibility: 'visible' | 'hidden';
   resume: string | false;
@@ -127,6 +132,7 @@ export type PlaybookRunResult =
   | {
       outcome: 'terminal';
       state: PlaybookState;
+      stateDescription?: string;
       output?: JsonValue;
     }
   | {
@@ -137,7 +143,7 @@ export type PlaybookRunResult =
 
 export interface PlaybookPorts {
   callPlayer(
-    playerId: string,
+    roleId: string,
     prompt: string,
     signal: AbortSignal,
     options: PlayerCallOptions,
@@ -163,6 +169,7 @@ export interface PlaybookSession {
   parentSessionId?: string;
   parentCallId?: string;
   depth: number;
+  roleBindings?: Readonly<Record<string, PlaybookRoleBinding>>;
   playerSessions?: PlayerSessionStore;
   ports: PlaybookPorts;
 }
@@ -186,7 +193,7 @@ export type PlaybookTraceType =
   | 'session.disposed';
 
 export interface PlaybookTraceEvent {
-  schemaVersion: 2;
+  schemaVersion: 3;
   sessionId: string;
   playbookId: string;
   rootSessionId: string;
@@ -203,19 +210,20 @@ export interface PlaybookTraceEvent {
 
 export interface PlaybookPendingBossQuestion {
   questionId: string;
-  player: string;
+  asker: { kind: 'captain' } | { kind: 'role'; roleId: string };
   question: string;
   sourceItem?: string;
 }
 
-// DR-014 §1 / DR-031 §5: JSON-safe capture of a parked or nested-call
+// DR-014 §1 / DR-031 §5 / DR-032: JSON-safe capture of a parked or nested-call
 // suspended session. `machine` is the opaque XState persisted snapshot;
-// pending Boss questions and a schema-2 suspended call are first-class so a
+// pending Boss questions and a suspended call are first-class so a
 // host never has to reconstruct durable ownership from presentation records.
-interface PlaybookRuntimeSnapshotFields {
+export interface PlaybookRuntimeSnapshot {
+  schemaVersion: 3;
   playbookId: string;
   machine: JsonValue;
-  playerResumeTokens: { readonly [playerId: string]: string };
+  roleResumeTokens: { readonly [roleId: string]: string };
   sequences: {
     trace: number;
     turn: number;
@@ -226,20 +234,9 @@ interface PlaybookRuntimeSnapshotFields {
   };
   state: PlaybookState;
   pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
+  suspendedCall?: PlaybookSuspendedCall;
 }
 
-export type PlaybookRuntimeSnapshot = PlaybookRuntimeSnapshotFields &
-  (
-    | {
-        schemaVersion: 1;
-        suspendedCall?: never;
-      }
-    | {
-        schemaVersion: 2;
-        suspendedCall?: PlaybookSuspendedCall;
-      }
-  );
-
 // DR-029: one currently valid, runtime-advertised control action. The id
 // is stable within the returned view; the label is runtime-written,
 // Boss-appropriate text derived from source state descriptions.

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

@@ -4,12 +4,17 @@ export interface PlaybookPendingBossQuestionContext {
     questionId: string;
     resumeStateId: string;
     sourceItem: string;
-    player: string;
+    asker: {
+        kind: 'captain';
+    } | {
+        kind: 'role';
+        roleId: string;
+    };
     question: string;
 }
 export interface PlaybookPlayerInput {
     stateId: string;
-    player: string;
+    role: string;
     sourceItem: string;
     prompt: string;
     result: Readonly<Record<string, string>>;
@@ -46,7 +51,7 @@ export type JudgePurpose = 'boss-input-classification' | 'player-output-adjudica
  * exercise composition/adjudication without a live runtime.
  */
 export interface RuntimeBoundaryCalls {
-    callPlayer(input: PlaybookPlayerInput, playerId: string, prompt: string, signal: AbortSignal): Promise<PlayerResult>;
+    callPlayer(input: PlaybookPlayerInput, roleId: string, prompt: string, signal: AbortSignal): Promise<PlayerResult>;
     callJudge(purpose: JudgePurpose, stateId: string | undefined, prompt: string, signal: AbortSignal): Promise<string>;
     callCaptain?(input: PlaybookCaptainInput, prompt: string, signal: AbortSignal, callOptions?: XStateCaptainCallOptions): Promise<CaptainResult>;
 }
@@ -68,10 +73,12 @@ export interface ScheduledStatus {
     data?: JsonValue;
 }
 /** Boss-facing identity for one FSM state whose invoked actor is `player`. */
-export interface XStatePlayerStateStatus {
-    player: string;
+export interface XStateRoleStateStatus {
+    role: string;
     label: string;
 }
+/** Invocation-scoped lookup exposed only while composing a player prompt. */
+export type XStatePromptIdentity = (roleId: string) => string;
 export interface XStateBossEventFieldSpec {
     /** The judge supplies routing data; the runtime supplies exact Boss text. */
     source: 'judge' | 'text';
@@ -144,8 +151,8 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
     label?: string;
     /**
      * Link-time compatibility declaration checked at construction against the
-     * loaded engine's self-report (DR-022). Absent: a legacy artifact emitted
-     * before the contract — constructed with no compatibility check.
+     * loaded engine's self-report (DR-022). Absent declarations reject because
+     * their overloaded player metadata has no safe local-role interpretation.
      */
     compat?: XStatePlaybookRuntimeCompat;
     /** Validate and JSON-snapshot the caller's per-run options. */
@@ -161,6 +168,15 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
     entryEvent?: {
         type: string;
         textField: string;
+        /**
+         * DR-034: the FSM context member this machine's entry action copies the
+         * exact Boss text into. Where it is named, the failure-state retry
+         * builds its payload from that member of the live snapshot instead of
+         * from the process-local recorded event, so the action derives the same
+         * before and after `restore`. Absent: the recorded event stays the
+         * source and the action lives only as long as the process.
+         */
+        contextField?: string;
     };
     /**
      * Exact flat Boss-event contracts whose non-text fields the judge may
@@ -182,14 +198,12 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
      * recoverable FSM-result failures instead.
      */
     captainStrategy?: XStateCaptainStrategy<TOptions>;
-    /** Status line emitted after classification; canonical metadata defaults to the event type, legacy artifacts to none. */
+    /** Status line emitted after classification; metadata defaults to the event type. */
     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;
+    /** Complete FSM-derived Boss-facing metadata for every `player` state. */
+    roleStates?: Readonly<Record<string, XStateRoleStateStatus>>;
     /** Compose the player prompt. Default: continuation blocks + `<field>` placeholder substitution. */
-    composePlayerPrompt?: (input: PlaybookPlayerInput) => string;
+    composePlayerPrompt?: (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity) => string;
     /** Compose the direct-Captain prompt. Default: continuation blocks + placeholder substitution with deterministic JSON rendering. */
     composeCaptainPrompt?: (input: PlaybookCaptainInput) => string;
     /** Linker-known exceptions to the default kebab-token → camel-field mapping. */
@@ -253,8 +267,6 @@ export declare function defaultComposePlayerPrompt(input: PlaybookPlayerInput, p
  * with lexicographically sorted keys at every depth.
  */
 export declare function defaultComposeCaptainPrompt(input: PlaybookCaptainInput, placeholderFields?: Readonly<Record<string, string>>): string;
-/** Default player binding: each player to its lowercased name. */
-export declare function defaultResolvePlayerId(input: PlaybookPlayerInput): string;
 /**
  * Default required-field extraction (slc/link.md §Captain adjudication).
  * Limited to the description's `Output shall include` / `输出应包含` clause;
@@ -278,8 +290,8 @@ export interface PlayerAdjudicationSpec {
  * long-form prose through judge JSON.
  */
 export declare function adjudicatePlayerOutput(spec: PlayerAdjudicationSpec, input: PlaybookPlayerInput, finalText: string, ports: PlaybookPorts, signal: AbortSignal, boundary?: RuntimeBoundaryCalls): Promise<PlaybookActorOutput>;
-export interface PlayerBridgeSpec {
-    resolvePlayerId: (input: PlaybookPlayerInput) => string;
+interface PlayerBridgeSpec {
+    resolveRoleId: (input: PlaybookPlayerInput) => string;
     composePlayerPrompt: (input: PlaybookPlayerInput) => string;
     adjudication: PlayerAdjudicationSpec;
     resumableStateIds: ReadonlySet<string>;
@@ -310,8 +322,10 @@ export declare function stateDescriptionsFromMachine(machine: AnyStateMachine):
  * (literal and dynamic) — and implements the full runtime lifecycle including
  * the optional parked-session snapshot capability (DR-014).
  *
- * Scope: machines that declare no parallel state (each snapshot exposes
- * exactly one playbook state id). Parallel-region FSMs keep their own linked
- * runtimes.
+ * Scope: flat single-region machines — no parallel state, no compound
+ * child states, and every root state's `meta.playbook.stateId` equal to its
+ * state key — so each snapshot exposes exactly one playbook state id.
+ * Parallel-region FSMs keep their own linked runtimes.
  */
 export declare function createXStatePlaybookRuntime<TOptions>(machine: AnyStateMachine, spec: XStatePlaybookRuntimeSpec<TOptions>): PlaybookRuntimeFactory<TOptions>;
+export {};