@sublang/playbook 15.1.0 → 17.0.0

package/reference/sdlc/code.playbook/code.fsm.d.ts

@@ -1,31 +1,58 @@
+import type { PlaybookCallResult } from '@sublang/playbook/runtime';
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
-export type CodeStateId = 'runFirstPhase' | 'reviewFirstCommit' | 'runIrTask' | 'reviewIrTask';
+/** Canonical lowercase local id of the source role Coder. */
+export type CodeRole = 'coder';
+/** One role-id array per parallel group; CODE declares no parallel group. */
+export declare const concurrentRoleSets: readonly (readonly CodeRole[])[];
+/** Delegated-player working leaves (CODE-1, CODE-3). */
+export type WorkingStateId = 'firstPhase' | 'irTaskPhase';
+/** Working leaves that may suspend for, and resume from, a Boss reply. */
+export type ResumableStateId = WorkingStateId;
+/** Root `BOSS_INTERRUPT` targets. */
+export type JumpableStateId = WorkingStateId;
+/** Nested `review` call states (CODE-2, CODE-4). */
+export type ReviewStateId = 'reviewNewIntentPhase' | 'reviewIrTaskPhase';
 export type CodeSourceItem = 'CODE-1' | 'CODE-2' | 'CODE-3' | 'CODE-4';
-export type CodePhase = 'direct' | 'ir-created' | 'ir-task-more' | 'ir-task-final';
-export type PendingBossQuestion = {
-    readonly questionId: 'runFirstPhase' | 'runIrTask';
-    readonly resumeStateId: 'runFirstPhase' | 'runIrTask';
+/** The accepted phase outcome whose `review` call decides the next step. */
+export type PhaseOutcome = 'directCommit' | 'irCommit' | 'moreTasks' | 'finalTask';
+/** The literal nested-call target shared by both call states and guards. */
+declare const REVIEW_PLAYBOOK_ID = "review";
+export interface PendingBossQuestion {
+    readonly questionId: ResumableStateId;
+    readonly resumeStateId: ResumableStateId;
     readonly sourceItem: 'CODE-1' | 'CODE-3';
     readonly asker: {
         readonly kind: 'role';
-        readonly roleId: 'coder';
+        readonly roleId: CodeRole;
     };
     readonly question: string;
-};
-export type PlayerInput = {
-    readonly stateId: 'runFirstPhase' | 'runIrTask';
-    readonly role: 'coder';
-    readonly sourceItem: 'CODE-1' | 'CODE-3';
+}
+interface PlayerInputBase {
+    readonly role: CodeRole;
+    /** The source item's full final prompt, verbatim. */
     readonly prompt: string;
+    /** This state's local result contract: guard name → description. */
     readonly result: Readonly<Record<string, string>>;
-    readonly callerInput: string;
+    /** `<caller-input>`: the caller's complete coding request. */
+    readonly callerInput?: string;
+    /** `<run-results>`: relevant run results; empty when none were supplied. */
     readonly runResults: string;
-    readonly irNumber?: string;
     readonly pendingBossQuestion?: PendingBossQuestion;
     readonly bossReply?: string;
-};
+}
+export interface FirstPhasePlayerInput extends PlayerInputBase {
+    readonly stateId: 'firstPhase';
+    readonly sourceItem: 'CODE-1';
+}
+export interface IrTaskPhasePlayerInput extends PlayerInputBase {
+    readonly stateId: 'irTaskPhase';
+    readonly sourceItem: 'CODE-3';
+    /** `<ir-number>`: the IR whose next unfinished task this phase implements. */
+    readonly irNumber?: string;
+}
+export type PlayerInput = FirstPhasePlayerInput | IrTaskPhasePlayerInput;
 export type PlayerOutput = {
     readonly guard: 'directCommit';
     readonly coderOutput: string;
@@ -51,82 +78,116 @@ export type PlayerOutput = {
     readonly guard: 'needsBossReply';
     readonly question: string;
 };
-export type PlaybookInput = {
-    readonly stateId: 'reviewFirstCommit' | 'reviewIrTask';
+export interface PlaybookInput {
+    readonly stateId: ReviewStateId;
     readonly sourceItem: 'CODE-2' | 'CODE-4';
-    readonly playbookId: 'review';
+    readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
     readonly text: string;
-};
-export type ReviewOutput = {
+}
+/** A successful call yields the child's own JSON-safe machine output. */
+export type PlaybookOutput = JsonValue | undefined;
+/** Public output interface of the packaged builtin `review`. */
+export interface ReviewPassOutput {
     readonly noUnsettledFindings: true;
-    /**
-     * Exact repository revision at which the review scope was evaluated:
-     * the last review-fix commit when one landed, otherwise the clean
-     * round's receipt-observed HEAD (DR-045). Always present.
-     */
     readonly evaluatedRevision: string;
-};
-export type CompactError = {
+}
+export interface CompactError {
     readonly name: string;
     readonly message: string;
+}
+export interface ErrorRecord {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+}
+/** Sanitized completed-result evidence of the `review` call that ended CODE. */
+export type CompletedReviewResult = {
+    readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+    readonly status: 'ok';
+    readonly output?: JsonValue;
+} | {
+    readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+    readonly status: 'aborted' | 'error';
+    readonly error: CompactError;
 };
-export type CodePlaybookOutput = {
+/** Public output interface of the packaged builtin `code`. */
+export type CodeOutput = {
     readonly status: 'complete';
-    /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;
-    /** Exact repository revision the final passing review evaluated. */
     readonly finalEvaluatedRevision: string;
-    /** Every phase's review passed with no unsettled findings. */
     readonly allReviewsPassed: true;
 } | {
     readonly status: 'review-failed';
-    /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;
     readonly error: CompactError;
 };
-export type CodingInput = {
+export interface CodeInput {
+    /** Optional seed for `<run-results>`; `START_CODE` may supply its own. */
     readonly runResults?: string;
-};
-export type CodingContext = {
+}
+export interface CodeContext {
+    /** `<run-results>`: relevant run results relayed to every phase. */
     readonly runResults: string;
+    /** `<caller-input>`: the caller's coding request and relevant context. */
     readonly callerInput?: string;
+    /** `<code-commit>`: the accepted `latestCommit` of the latest phase. */
+    readonly codeCommit?: string;
+    /** `<coder-output>`: Coder's verbatim final text for the latest phase. */
     readonly coderOutput?: string;
-    readonly latestCommit?: string;
+    /** `<ir-number>`: the created or continued IR. */
     readonly irNumber?: string;
+    /** `<ir-task>`: the IR task the latest IR-task phase implemented. */
     readonly irTask?: string;
+    /** The accepted outcome of the phase under review. */
+    readonly phaseOutcome?: PhaseOutcome;
+    /** Revision evaluated by the latest passing review. */
     readonly evaluatedRevision?: string;
-    readonly phase?: CodePhase;
-    readonly completion?: 'complete' | 'review-failed';
+    /** Compact failure CODE reports when review did not pass a phase. */
     readonly reviewError?: CompactError;
-    readonly lastError?: unknown;
+    /** Sanitized evidence of the review result that ended CODE. */
+    readonly reviewEvidence?: CompletedReviewResult;
+    readonly lastError?: ErrorRecord;
     readonly pendingBossQuestion?: PendingBossQuestion;
     readonly bossReply?: string;
-};
-export type CodingEvent = {
+}
+export type CodeEvent = {
     readonly type: 'START_CODE';
     readonly callerInput: string;
+    readonly runResults?: string;
+} | {
+    readonly type: 'BOSS_INTERRUPT';
+    readonly targetId: JumpableStateId;
 } | {
     readonly type: 'BOSS_REPLY';
     readonly answer: string;
-    readonly questionId?: 'runFirstPhase' | 'runIrTask';
+    readonly questionId?: ResumableStateId;
 };
-export declare const codingMachine: import("xstate").StateMachine<CodingContext, {
+/**
+ * Recognizes an authored rejected child result: an aborted or error call, or
+ * a child that completed at its own authored failure terminal.
+ */
+export declare function authoredChildResult(error: unknown, expectedPlaybookId: string): PlaybookCallResult | undefined;
+export declare const codeMachine: import("xstate").StateMachine<CodeContext, {
     readonly type: "START_CODE";
     readonly callerInput: string;
+    readonly runResults?: string;
+} | {
+    readonly type: "BOSS_INTERRUPT";
+    readonly targetId: JumpableStateId;
 } | {
     readonly type: "BOSS_REPLY";
     readonly answer: string;
-    readonly questionId?: "runFirstPhase" | "runIrTask";
+    readonly questionId?: ResumableStateId;
 }, {
-    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>> | undefined;
 }, {
-    src: "playbook";
-    logic: import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>;
-    id: string | undefined;
-} | {
     src: "player";
     logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
     id: string | undefined;
+} | {
+    src: "playbook";
+    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
+    id: string | undefined;
 }, {
     type: "playbook.acceptedOutcome";
     params: {
@@ -138,91 +199,83 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
     type: "rememberActorError";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "startCoding";
+    type: "resetForInterrupt";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberDirectCommit";
-    params: import("xstate").NonReducibleUnknown;
-} | {
-    type: "rememberIrCommit";
+    type: "rememberBossReply";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberMoreTasks";
+    type: "rememberMalformedPlayerOutput";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberFinalTask";
+    type: "clearBossReplyContext";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberPendingQuestion";
+    type: "rememberAuthoredReviewFailure";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberBossReply";
+    type: "startCode";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberEmptyBossReplyError";
+    type: "rememberPhaseCommit";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "completeSuccessfully";
-    params: import("xstate").NonReducibleUnknown;
+    type: "setPendingBossQuestion";
+    params: {
+        readonly resumeStateId: ResumableStateId;
+    };
 } | {
-    type: "completeWithReviewFailure";
+    type: "rememberReviewPass";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "completeWithInvalidReviewOutput";
+    type: "rememberReviewNotPassed";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberMalformedPlayerOutput";
+    type: "rememberMalformedBossReply";
     params: import("xstate").NonReducibleUnknown;
 }, {
-    type: "needsBossReply";
+    type: "acceptDirectCommit";
     params: unknown;
 } | {
-    type: "isDirectCommit";
+    type: "acceptIrCommit";
     params: unknown;
 } | {
-    type: "isIrCommit";
+    type: "acceptMoreTasks";
     params: unknown;
 } | {
-    type: "isMoreTasks";
-    params: unknown;
-} | {
-    type: "isFinalTask";
+    type: "acceptFinalTask";
     params: unknown;
 } | {
     type: "authoredReviewFailure";
     params: unknown;
 } | {
-    type: "reviewApprovedDirect";
+    type: "needsBossReplyWithQuestion";
     params: unknown;
 } | {
-    type: "reviewApprovedIrCreated";
+    type: "validStartCode";
     params: unknown;
 } | {
-    type: "reviewApprovedMoreTasks";
+    type: "emptyBossReply";
     params: unknown;
 } | {
-    type: "reviewApprovedFinalTask";
+    type: "reviewPassedDirect";
     params: unknown;
 } | {
-    type: "emptyBossReply";
+    type: "reviewPassedNewIr";
     params: unknown;
 } | {
-    type: "resumesFirstPhase";
+    type: "reviewPassedNonfinalTask";
     params: unknown;
 } | {
-    type: "resumesIrTask";
+    type: "reviewPassedFinalTask";
     params: unknown;
-}, never, "done" | "failed" | "ready" | "awaitBossReply" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask" | "reportedReviewFailure", string, CodingInput, {
+}, never, "done" | "failed" | "ready" | "awaitBossReply" | "firstPhase" | "irTaskPhase" | "reviewNewIntentPhase" | "reviewIrTaskPhase" | "reviewFailed", string, CodeInput, {
     readonly status: "complete";
-    /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;
-    /** Exact repository revision the final passing review evaluated. */
     readonly finalEvaluatedRevision: string;
-    /** Every phase's review passed with no unsettled findings. */
     readonly allReviewsPassed: true;
 } | {
     readonly status: "review-failed";
-    /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;
     readonly error: CompactError;
 }, import("xstate").EventObject, import("xstate").MetaObject, {
@@ -231,17 +284,17 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
         readonly ready: {
             id: "ready";
         };
-        readonly runFirstPhase: {
-            id: "runFirstPhase";
+        readonly firstPhase: {
+            id: "firstPhase";
         };
-        readonly reviewFirstCommit: {
-            id: "reviewFirstCommit";
+        readonly reviewNewIntentPhase: {
+            id: "reviewNewIntentPhase";
         };
-        readonly runIrTask: {
-            id: "runIrTask";
+        readonly irTaskPhase: {
+            id: "irTaskPhase";
         };
-        readonly reviewIrTask: {
-            id: "reviewIrTask";
+        readonly reviewIrTaskPhase: {
+            id: "reviewIrTaskPhase";
         };
         readonly awaitBossReply: {
             id: "awaitBossReply";
@@ -249,12 +302,12 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
         readonly failed: {
             id: "failed";
         };
-        readonly reportedReviewFailure: {
-            id: "reportedReviewFailure";
+        readonly reviewFailed: {
+            id: "reviewFailed";
         };
         readonly done: {
             id: "done";
         };
     };
 }>;
-export default codingMachine;
+export default codeMachine;

package/reference/sdlc/code.playbook/code.fsm.introspect.d.ts

@@ -1,6 +1,6 @@
-import type { CodingContext, PlaybookInput, PlayerInput, codingMachine } from './code.fsm.js';
+import type { CodeContext, PlaybookInput, PlayerInput, codeMachine } from './code.fsm.js';
 export type TransitionGuard = (args: {
-    context: CodingContext;
+    context: CodeContext;
     event: unknown;
 }) => boolean;
 export interface InvokingTransition {
@@ -12,24 +12,24 @@ export interface InvokingTransition {
 export interface PlayerStateInfo {
     readonly stateId: string;
     readonly sourceItem: string;
-    readonly getInput: (context: CodingContext) => PlayerInput;
+    readonly getInput: (context: CodeContext) => PlayerInput;
     readonly transitions: readonly InvokingTransition[];
 }
 export interface NestedPlaybookStateInfo {
     readonly stateId: string;
     readonly sourceItem: string;
-    readonly getInput: (context: CodingContext) => PlaybookInput;
+    readonly getInput: (context: CodeContext) => PlaybookInput;
     readonly transitions: readonly InvokingTransition[];
 }
 export interface AwaitBossReplyInfo {
     readonly stateId: 'awaitBossReply';
     readonly bossReplyTransitions: readonly InvokingTransition[];
 }
-export declare function enumeratePlayerStates(machine: typeof codingMachine): readonly PlayerStateInfo[];
+export declare function enumeratePlayerStates(machine: typeof codeMachine): readonly PlayerStateInfo[];
 export declare const enumerateCaptainStates: typeof enumeratePlayerStates;
-export declare function enumerateNestedPlaybookStates(machine: typeof codingMachine): readonly NestedPlaybookStateInfo[];
-export declare function enumerateAwaitBossReply(machine: typeof codingMachine): AwaitBossReplyInfo;
-export declare function enumerateRootEvents(machine: typeof codingMachine): {
+export declare function enumerateNestedPlaybookStates(machine: typeof codeMachine): readonly NestedPlaybookStateInfo[];
+export declare function enumerateAwaitBossReply(machine: typeof codeMachine): AwaitBossReplyInfo;
+export declare function enumerateRootEvents(machine: typeof codeMachine): {
     readonly startCode: {
         readonly target: string;
     };

package/reference/sdlc/code.playbook/code.fsm.introspect.ts

@@ -2,14 +2,14 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import type {
-  CodingContext,
+  CodeContext,
   PlaybookInput,
   PlayerInput,
-  codingMachine,
+  codeMachine,
 } from './code.fsm.js';
 
 export type TransitionGuard = (args: {
-  context: CodingContext;
+  context: CodeContext;
   event: unknown;
 }) => boolean;
 
@@ -23,14 +23,14 @@ export interface InvokingTransition {
 export interface PlayerStateInfo {
   readonly stateId: string;
   readonly sourceItem: string;
-  readonly getInput: (context: CodingContext) => PlayerInput;
+  readonly getInput: (context: CodeContext) => PlayerInput;
   readonly transitions: readonly InvokingTransition[];
 }
 
 export interface NestedPlaybookStateInfo {
   readonly stateId: string;
   readonly sourceItem: string;
-  readonly getInput: (context: CodingContext) => PlaybookInput;
+  readonly getInput: (context: CodeContext) => PlaybookInput;
   readonly transitions: readonly InvokingTransition[];
 }
 
@@ -41,7 +41,7 @@ export interface AwaitBossReplyInfo {
 
 type RawInvoke = {
   src?: unknown;
-  input?: (args: { context: CodingContext }) => PlayerInput | PlaybookInput;
+  input?: (args: { context: CodeContext }) => PlayerInput | PlaybookInput;
   onDone?: unknown;
 };
 
@@ -60,7 +60,7 @@ type RawConfig = {
   states?: Readonly<Record<string, RawState>>;
 };
 
-function rawConfig(machine: typeof codingMachine): RawConfig {
+function rawConfig(machine: typeof codeMachine): RawConfig {
   return (machine as unknown as { config: RawConfig }).config;
 }
 
@@ -84,13 +84,13 @@ function transitions(value: unknown): readonly InvokingTransition[] {
 }
 
 export function enumeratePlayerStates(
-  machine: typeof codingMachine,
+  machine: typeof codeMachine,
 ): readonly PlayerStateInfo[] {
   const states = rawConfig(machine).states ?? {};
   return Object.entries(states).flatMap(([stateId, state]) => {
     const invoke = state.invoke;
     if (invoke?.src !== 'player' || invoke.input === undefined) return [];
-    const getInput = (context: CodingContext): PlayerInput =>
+    const getInput = (context: CodeContext): PlayerInput =>
       invoke.input?.({ context }) as PlayerInput;
     const input = getInput({ runResults: '' });
     return [
@@ -108,13 +108,13 @@ export function enumeratePlayerStates(
 export const enumerateCaptainStates = enumeratePlayerStates;
 
 export function enumerateNestedPlaybookStates(
-  machine: typeof codingMachine,
+  machine: typeof codeMachine,
 ): readonly NestedPlaybookStateInfo[] {
   const states = rawConfig(machine).states ?? {};
   return Object.entries(states).flatMap(([stateId, state]) => {
     const invoke = state.invoke;
     if (invoke?.src !== 'playbook' || invoke.input === undefined) return [];
-    const getInput = (context: CodingContext): PlaybookInput =>
+    const getInput = (context: CodeContext): PlaybookInput =>
       invoke.input?.({ context }) as PlaybookInput;
     const input = getInput({ runResults: '' });
     return [
@@ -129,7 +129,7 @@ export function enumerateNestedPlaybookStates(
 }
 
 export function enumerateAwaitBossReply(
-  machine: typeof codingMachine,
+  machine: typeof codeMachine,
 ): AwaitBossReplyInfo {
   const on = rawConfig(machine).states?.awaitBossReply?.on ?? {};
   return {
@@ -138,7 +138,7 @@ export function enumerateAwaitBossReply(
   };
 }
 
-export function enumerateRootEvents(machine: typeof codingMachine): {
+export function enumerateRootEvents(machine: typeof codeMachine): {
   readonly startCode: { readonly target: string };
 } {
   const on = rawConfig(machine).states?.ready?.on ?? {};