@sublang/playbook 3.1.0 → 5.0.0

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

@@ -1,163 +1,154 @@
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
+/** One immutable host-catalog entry (id + command + intent only). */
 export type EnabledPlaybook = {
     readonly id: string;
     readonly command: string;
     readonly intent: string;
 };
-export type NormalizedError = {
-    readonly name: string;
-    readonly message: string;
-    readonly stack?: string;
-};
-export type PlaybookStateValue = string | {
-    readonly [key: string]: PlaybookStateValue;
-};
-export type PlaybookState = {
-    readonly value: PlaybookStateValue;
-    readonly activeStateIds: readonly string[];
-    readonly tags: readonly string[];
-    readonly status: 'active' | 'done' | 'error' | 'stopped';
-    readonly quiescent: boolean;
-    readonly stateId?: string;
-};
-export type CompletedCallResult = {
+/** The closed controller action set (DR-029; stable machine contract). */
+export type DecisionAction = 'respond' | 'start' | 'switch' | 'dismiss' | 'deliver' | 'runtime';
+/**
+ * A deterministic parse-resolved acting decision injected by the host
+ * (CAPTAIN-7 parse table): the turn's decision object, entering the decision
+ * state with no decision model call.
+ */
+export type ParsedActingDecision = {
+    readonly action: 'start' | 'switch';
     readonly playbookId: string;
-    readonly status: 'ok';
-    readonly output?: JsonValue;
+    readonly input: string;
 } | {
-    readonly playbookId: string;
-    readonly status: 'aborted' | 'error';
-    readonly error: NormalizedError;
+    readonly action: 'deliver';
+};
+/** Compact `{ name, message }` error evidence (never a raw Error). */
+export type CompactError = {
+    readonly name: string;
+    readonly message: string;
 };
-export type PendingBossQuestion = {
-    readonly questionId: ResumableStateId;
-    readonly resumeStateId: ResumableStateId;
-    readonly sourceItem: 'CAPTAIN-1' | 'CAPTAIN-3';
-    readonly player: 'Captain';
-    readonly question: string;
+/** Receipt evidence of an executed `runtime` action (disposition only). */
+export type SettlementReceiptEvidence = {
+    readonly disposition: 'executed' | 'rejected' | 'failed';
+    readonly reason?: string;
+    readonly error?: CompactError;
+};
+/**
+ * The controller-port settlement evidence the machine may retain: status,
+ * outcome-report facts, optional rejection reason, receipt disposition, and
+ * leaf-state summary — never a session id, call id, child state, stack
+ * ledger, resume token, or opaque runtime result (CAPPLAY-10).
+ */
+export type SettlementEvidence = {
+    readonly status: 'ok' | 'rejected' | 'failed';
+    readonly facts: readonly string[];
+    readonly reason?: string;
+    readonly receipt?: SettlementReceiptEvidence;
+    readonly leafStateSummary?: string;
 };
-export type ResumableStateId = 'routing' | 'reassessing';
 export type CaptainMachineInput = {
     readonly enabledPlaybooks: readonly EnabledPlaybook[];
-    readonly selfPlaybookId: string;
-    readonly bossIntent?: string;
-};
-export type CaptainMachineOutput = {
-    readonly response: string;
 };
+export type CaptainStateId = 'deciding' | 'answeringCommand' | 'reporting';
+export type CaptainSourceItem = 'CAPTAIN-1' | 'CAPTAIN-2' | 'CAPTAIN-3';
 export type CaptainInput = {
-    readonly stateId: ResumableStateId;
-    readonly sourceItem: 'CAPTAIN-1' | 'CAPTAIN-3';
+    readonly stateId: CaptainStateId;
+    readonly sourceItem: CaptainSourceItem;
     readonly prompt: string;
     readonly result: Record<string, string>;
-    readonly bossIntent: string;
-    readonly enabledPlaybooks: readonly EnabledPlaybook[];
-    readonly remainingPlan?: readonly JsonValue[];
-    readonly completedCallResults?: readonly CompletedCallResult[];
-    readonly pendingBossQuestion?: PendingBossQuestion;
-    readonly bossReply?: string;
-};
+    /**
+     * DR-013 A1 source-owned tool restriction: this playbook's policy forbids
+     * tools on every Captain call, so each state requests the empty allowlist.
+     */
+    readonly allowedTools: readonly string[];
+    /** The injected parse-resolved decision, when the host's parse decided the turn. */
+    readonly parsedDecision?: ParsedActingDecision;
+};
+/**
+ * Decision-state output: the validated selection under the stable controller
+ * guard contract — `respond` | `start` | `switch` | `dismiss` | `deliver` |
+ * `runtime`, with the payload fields DR-029 requires — plus the
+ * controller-port settlement evidence of the executed submission. The prose
+ * states (`answeringCommand`, `reporting`) carry the default single-outcome
+ * `done` contract.
+ */
 export type CaptainOutput = {
-    readonly guard: 'question';
-    readonly question: string;
+    readonly guard: 'respond';
+    readonly text: string;
+    readonly settlement: SettlementEvidence;
 } | {
-    readonly guard: 'delegation';
-    readonly remainingPlan: readonly JsonValue[];
-    readonly nextPlaybookId: string;
-    readonly nextPlaybookInput: string;
+    readonly guard: 'start';
+    readonly playbookId: string;
+    readonly input: string;
+    readonly settlement: SettlementEvidence;
 } | {
-    readonly guard: 'final';
-    readonly response: string;
+    readonly guard: 'switch';
+    readonly playbookId: string;
+    readonly input: string;
+    readonly settlement: SettlementEvidence;
 } | {
-    readonly guard: 'followUpQuestion';
-    readonly question: string;
+    readonly guard: 'dismiss';
+    readonly settlement: SettlementEvidence;
 } | {
-    readonly guard: 'continuing';
-    readonly remainingPlan: readonly JsonValue[];
-    readonly nextPlaybookId: string;
-    readonly nextPlaybookInput: string;
+    readonly guard: 'deliver';
+    readonly settlement: SettlementEvidence;
 } | {
-    readonly guard: 'needsBossReply';
-    readonly question: string;
-};
-export type PlaybookInput = {
-    readonly stateId: 'callPlaybook';
-    readonly sourceItem?: 'CAPTAIN-2';
-    readonly playbookId: string;
-    readonly text: string;
-    readonly playbookIdContext: 'nextPlaybookId';
-    readonly textContext: 'nextPlaybookInput';
+    readonly guard: 'runtime';
+    readonly actionId: string;
+    readonly settlement: SettlementEvidence;
+} | {
+    readonly guard: 'done';
 };
-export type PlaybookOutput = JsonValue | undefined;
 type Context = {
-    readonly bossIntent: string;
     readonly enabledPlaybooks: readonly EnabledPlaybook[];
-    readonly selfPlaybookId: string;
-    readonly remainingPlan: readonly JsonValue[];
-    readonly completedCallResults: readonly CompletedCallResult[];
-    readonly nextPlaybookId: string;
-    readonly nextPlaybookInput: string;
-    readonly callHistory: readonly string[];
-    readonly response?: string;
-    readonly pendingBossQuestion?: PendingBossQuestion;
-    readonly bossReply?: string;
+    readonly bossText: string;
+    readonly parsedDecision?: ParsedActingDecision;
+    readonly selectedAction?: DecisionAction;
+    readonly settlementStatus?: 'ok' | 'rejected' | 'failed';
+    readonly settlementFacts?: readonly string[];
+    readonly settlementReason?: string;
+    readonly receiptDisposition?: 'executed' | 'rejected' | 'failed';
+    readonly receiptReason?: string;
+    readonly receiptError?: CompactError;
+    readonly leafStateSummary?: string;
     readonly lastError?: JsonValue;
 };
-type BossIntentEvent = {
-    readonly type: 'BOSS_INTENT';
-    readonly bossIntent: string;
+type BossTurnEvent = {
+    readonly type: 'BOSS_TURN';
+    readonly bossText: string;
+};
+type ParsedRespondEvent = {
+    readonly type: 'PARSED_RESPOND';
+    readonly bossText: string;
 };
-type BossInterruptEvent = {
-    readonly type: 'BOSS_INTERRUPT';
-    readonly targetId: 'routing';
-    readonly bossIntent: string;
+type ParsedActionEvent = {
+    readonly type: 'PARSED_ACTION';
+    readonly bossText: string;
+    readonly decision: ParsedActingDecision;
 };
-type BossReplyEvent = {
-    readonly type: 'BOSS_REPLY';
-    readonly answer: string;
-    readonly questionId?: string;
+type ShutdownEvent = {
+    readonly type: 'SHUTDOWN';
 };
-export declare const captainMachine: import("xstate").StateMachine<Context, BossIntentEvent | BossInterruptEvent | BossReplyEvent, {
-    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<CaptainOutput, CaptainInput, import("xstate").EventObject>> | undefined;
+export type CaptainMachineEvent = BossTurnEvent | ParsedRespondEvent | ParsedActionEvent | ShutdownEvent;
+export declare const captainMachine: import("xstate").StateMachine<Context, BossTurnEvent | ParsedRespondEvent | ParsedActionEvent | ShutdownEvent, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<CaptainOutput, CaptainInput, import("xstate").EventObject>> | undefined;
 }, {
-    src: "playbook";
-    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
-    id: string | undefined;
-} | {
     src: "captain";
     logic: import("xstate").PromiseActorLogic<CaptainOutput, CaptainInput, import("xstate").EventObject>;
     id: string | undefined;
 }, {
-    type: "startRoutingFromBoss";
+    type: "startDecidedTurn";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "storeBossReply";
+    type: "startCommandTurn";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberInvalidBossReply";
+    type: "startParsedTurn";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "setRoutingQuestion";
+    type: "recordSettlement";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "storeRoutingDelegation";
-    params: import("xstate").NonReducibleUnknown;
-} | {
-    type: "appendSuccessfulChildResult";
-    params: import("xstate").NonReducibleUnknown;
-} | {
-    type: "appendRejectedChildResult";
-    params: import("xstate").NonReducibleUnknown;
-} | {
-    type: "storeFinalResponse";
-    params: import("xstate").NonReducibleUnknown;
-} | {
-    type: "setReassessQuestion";
-    params: import("xstate").NonReducibleUnknown;
-} | {
-    type: "storeContinuingCall";
+    type: "recordDecisionReplyFailure";
     params: import("xstate").NonReducibleUnknown;
 } | {
     type: "rememberInvalidActorOutput";
@@ -166,61 +157,55 @@ export declare const captainMachine: import("xstate").StateMachine<Context, Boss
     type: "rememberActorError";
     params: import("xstate").NonReducibleUnknown;
 }, {
-    type: "isRoutingInterrupt";
-    params: unknown;
-} | {
-    type: "canResumeRouting";
+    type: "start";
     params: unknown;
 } | {
-    type: "canResumeReassessing";
+    type: "respond";
     params: unknown;
 } | {
-    type: "hasBossIntent";
+    type: "switch";
     params: unknown;
 } | {
-    type: "isRoutingQuestion";
+    type: "dismiss";
     params: unknown;
 } | {
-    type: "isRoutingDelegation";
+    type: "deliver";
     params: unknown;
 } | {
-    type: "isReassessFinal";
+    type: "runtime";
     params: unknown;
 } | {
-    type: "isReassessQuestion";
+    type: "hasBossTurnText";
     params: unknown;
 } | {
-    type: "isReassessContinuing";
+    type: "hasCommandRespondText";
     params: unknown;
 } | {
-    type: "isPlaybookSuccessOutput";
+    type: "hasParsedActingDecision";
     params: unknown;
 } | {
-    type: "isAuthoredChildError";
+    type: "isDecisionReplyFailure";
     params: unknown;
-}, never, "done" | "failed" | "callPlaybook" | "awaitBossReply" | "ready" | "routing" | "reassessing", string, CaptainMachineInput, CaptainMachineOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+}, never, "failed" | "deciding" | "answeringCommand" | "reporting" | "hub" | "shutdown", string, CaptainMachineInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "captain";
     states: {
-        readonly ready: {
-            id: "ready";
-        };
-        readonly routing: {
-            id: "routing";
+        readonly hub: {
+            id: "hub";
         };
-        readonly callPlaybook: {
-            id: "callPlaybook";
+        readonly deciding: {
+            id: "deciding";
         };
-        readonly reassessing: {
-            id: "reassessing";
+        readonly answeringCommand: {
+            id: "answeringCommand";
         };
-        readonly awaitBossReply: {
-            id: "awaitBossReply";
+        readonly reporting: {
+            id: "reporting";
         };
         readonly failed: {
             id: "failed";
         };
-        readonly done: {
-            id: "done";
+        readonly shutdown: {
+            id: "shutdown";
         };
     };
 }>;