@sublang/playbook 15.1.0 → 17.0.0

package/src/runtime.ts

@@ -492,6 +492,8 @@ export type PlaybookRunResult =
     };
 
 export interface PlaybookPorts {
+  /** Acknowledge the durable start before work and its result before transition. */
+  recordStep?(step: PlaybookStepRecord, position?: PlaybookRuntimeSnapshot): Promise<void>;
   callPlayer(
     roleId: string,
     prompt: string,
@@ -508,6 +510,7 @@ export interface PlaybookPorts {
     request: PlaybookCallRequest,
     signal: AbortSignal,
   ): Promise<PlaybookCallStart>;
+  /** Mark question presentation with data.kind = "boss-question"; Captain relays it from pendingQuestions. */
   emitStatus(message: string, data?: unknown): Promise<void>;
   emitTelemetry(event: { topic: string; payload: unknown }): Promise<void>;
 }
@@ -639,6 +642,8 @@ export interface PlaybookEffectBoundary {
   readonly baseline: PlaybookRepositoryObservation;
   readonly after?: PlaybookRepositoryObservation;
   readonly physicalReceipt?: PlaybookRepositoryReceipt;
+  /** A later exact restoration permits replay of this standalone read-only call. */
+  readonly restored?: PlaybookRepositoryObservation;
   readonly finalText?: string;
   readonly semanticCandidate?: JsonValue;
   readonly initialSemanticCandidate?: JsonValue;
@@ -655,6 +660,7 @@ export type PlaybookEffectBoundaryStart = Omit<
   | 'attemptNumber'
   | 'after'
   | 'physicalReceipt'
+  | 'restored'
   | 'finalText'
   | 'semanticCandidate'
   | 'initialSemanticCandidate'
@@ -774,9 +780,29 @@ export interface PlaybookRuntimeSnapshot {
     readonly boundaryPrefix: number;
     readonly attemptId: string | null;
   };
+  /** Interrupted invocation, captured before its external call (DR-069). */
+  recoveryCheckpoint?: PlaybookRecoveryCheckpoint;
   suspendedCall?: PlaybookSuspendedCall;
 }
 
+export interface PlaybookRecoveryCheckpoint {
+  readonly id?: string;
+  readonly stateId: string;
+  readonly prompt: string;
+  readonly machine: JsonValue;
+  readonly boundaryPrefix: number;
+  /** Completed actor output supplied by the execution journal on restore. */
+  readonly result?: JsonValue;
+  readonly delivered?: true;
+}
+
+export interface PlaybookStepRecord {
+  readonly id: string;
+  readonly kind: 'player' | 'captain' | 'script';
+  readonly stateId: string;
+  readonly result?: JsonValue;
+}
+
 // DR-063 §3: what running an advertised action would do. `ready` is the only
 // standing that can change anything; `no-op` runs and changes nothing; a
 // `blocked` action cannot run at all. An absent standing reads as `ready`, so
@@ -805,6 +831,16 @@ export interface PlaybookControlAction {
 // the Boss-appropriate grounding a host may speak from; the state id is
 // internal and is absent from it whenever the runtime's source declares
 // no description for the state it is in.
+export interface PlaybookRecoveryOffer {
+  prompt: string;
+  description?: string;
+  /** Runtime-owned conditions to satisfy; these never authorize task completion. */
+  preparation?: string;
+  /** Saved observations and result choices for diagnosing the stopped step. */
+  evidence?: JsonValue;
+  continuation: { kind: 'reply' } | { kind: 'runtime'; actionId: string };
+}
+
 export interface PlaybookControlView {
   state: PlaybookState;
   stateDescription?: string;
@@ -812,6 +848,8 @@ export interface PlaybookControlView {
   pendingQuestions: readonly PlaybookPendingBossQuestion[];
   lastError?: NormalizedError;
   actions: readonly PlaybookControlAction[];
+  /** Context only for an explicitly authorized Captain preparation call. */
+  recovery?: PlaybookRecoveryOffer;
 }
 
 // DR-029: the receipt `apply()` returns says which of three things
@@ -820,7 +858,7 @@ export interface PlaybookControlView {
 export type PlaybookControlReceipt =
   | { disposition: 'rejected'; reason: string }
   | { disposition: 'executed'; run: PlaybookRunResult }
-  | { disposition: 'failed'; error: NormalizedError };
+  | { disposition: 'failed'; error: NormalizedError; run?: PlaybookRunResult };
 
 // DR-038 §2: link-authored metadata the Captain uses to decide whether a
 // quiescent generation is eligible for retention and whether a root terminal
@@ -838,7 +876,7 @@ export interface PlaybookRuntime {
   // a safe capture point (parked quiescence between public boundaries);
   // `restore` is an alternative to `init` that rehydrates the exported
   // snapshot under the same immutable session identity.
-  exportSnapshot?(): PlaybookRuntimeSnapshot | undefined;
+  exportSnapshot?(checkpoint?: { child?: PlaybookPendingCall }): PlaybookRuntimeSnapshot | undefined;
   restore?(
     session: PlaybookSession,
     snapshot: PlaybookRuntimeSnapshot,
@@ -879,6 +917,8 @@ export interface PlaybookRuntime {
   handleBossInput(turn: {
     text: string;
     signal: AbortSignal;
+    /** Called synchronously just before accepting the event, at most once. */
+    onAccepted?: () => void;
   }): Promise<PlaybookRunResult>;
   resumePlaybookCall(input: {
     callId: string;

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

@@ -63,7 +63,7 @@ export interface RuntimeBoundaryCalls {
      * with the cause the boundary decided at the call itself, where the role,
      * the resolved player, and the reported error are known.
      */
-    markPlayerResultFailure?(error: Error): Error;
+    markPlayerResultFailure?(error: Error, result?: PlayerResult): Error;
     callJudge(purpose: JudgePurpose, stateId: string | undefined, prompt: string, signal: AbortSignal): Promise<string>;
     callCaptain?(input: PlaybookCaptainInput, prompt: string, signal: AbortSignal, callOptions?: XStateCaptainCallOptions): Promise<CaptainResult>;
 }
@@ -125,17 +125,18 @@ export declare function playerFailureCause(input: {
 /**
  * DR-063 §1: the cause of an unresolved governed settlement. A reconciled
  * mismatch supplies its own receipt-read cause; the reasons a runtime owns map
- * to adjudication, abort, and runtime-defect codes. Shared with DECIDE's
- * bespoke runtime, which decides the same reasons.
+ * to adjudication, abort, and runtime-defect codes. Exported so linked
+ * machinery of an artifact's own decides the same reasons.
  */
 export declare function governedSettlementCause(reason: string, error: unknown, aborted: boolean, supplied: PlaybookFailureCause | undefined): PlaybookFailureCause;
 /**
  * DR-063 §2: the causes decided for thrown values that cannot carry the
- * marker — a string, a frozen error — kept by identity for as long as the
- * failure stands, so every surface that reads the FSM's own `lastError`
- * publishes the cause decided for exactly that value, whatever turn reads it.
- * A value that carries the marker answers from it; the map is bounded, since
- * only values that refuse the marker need an entry.
+ * marker — a string, a frozen error — and for the record a machine keeps in
+ * place of the thrown value, kept by identity for as long as the failure
+ * stands, so every surface that reads the FSM's own `lastError` publishes the
+ * cause decided for exactly that failure, whatever turn reads it. A value
+ * that carries the marker answers from it; the map is bounded, since only
+ * values that lack the marker need an entry.
  */
 export interface PlaybookFailureCauseRetention {
     retain(error: unknown, cause: PlaybookFailureCause): void;
@@ -195,7 +196,25 @@ interface XStateRepositoryDeferredRestoreResult {
     readonly effectLedger: PlaybookEffectLedger;
 }
 type XStateEffectBoundarySeed = Omit<PlaybookEffectBoundaryStart, 'playbookId' | 'canonicalWorktree' | 'baseline' | 'cohortId'>;
+/** One member's completion inside a repository cohort (DR-067 §1). */
+type XStateRepositoryCohortCompletion<T> = XStateRepositoryExclusiveCompletion<T> & {
+    readonly roleId: string;
+};
+interface XStateRepositoryCohortResult<T> {
+    readonly baseline: PlaybookRepositoryReceipt['baseline'];
+    readonly invocationId: string;
+    readonly operations: Readonly<Record<string, XStateRepositoryOperationSettlement<T> | XStateRepositoryOperationRejection>>;
+    readonly receipts: Readonly<Record<string, PlaybookRepositoryReceipt>>;
+    readonly effectLedger: PlaybookEffectLedger;
+}
 export interface XStateRepositoryCapability {
+    observe?(): Promise<PlaybookRepositoryReceipt['baseline']>;
+    acquire?(options: {
+        readonly signal: AbortSignal;
+    }): Promise<{
+        assertOwner(): Promise<void>;
+        release(): Promise<void>;
+    }>;
     runExclusive<T>(options: {
         readonly signal: AbortSignal;
         readonly effectBoundary: XStateEffectBoundarySeed;
@@ -222,6 +241,27 @@ export interface XStateRepositoryCapability {
         readonly signal: AbortSignal;
         readonly operationId: string;
     }): Promise<XStateRepositoryDeferredParked | XStateRepositoryDeferredRestoreResult>;
+    /**
+     * DR-067 §1 / PBRT-73: one repository claim over the working leaves of a
+     * parallel state entered together — every member an `unchanged` boundary
+     * of one cohort, the operations run concurrently under that claim, and
+     * one completion callback per member. Required for an artifact that
+     * declares a parallel state.
+     */
+    runCohort?<T>(options: {
+        readonly signal: AbortSignal;
+        readonly invocationId: string;
+        readonly roleIds: readonly string[];
+        readonly dispositionsByRole: Readonly<Record<string, readonly ['unchanged']>>;
+        readonly effectBoundaries: Readonly<Record<string, XStateEffectBoundarySeed>>;
+        readonly operations: Readonly<Record<string, (context: {
+            readonly baseline: PlaybookRepositoryReceipt['baseline'];
+            readonly identity: unknown;
+            readonly invocationId: string;
+            readonly roleId: string;
+        }) => Promise<T>>>;
+        readonly completeEffectBoundary: (completion: XStateRepositoryCohortCompletion<T>) => XStateRepositoryCompletionEvidence | Promise<XStateRepositoryCompletionEvidence>;
+    }): Promise<XStateRepositoryCohortResult<T>>;
 }
 /** The runtime ABI this engine implements (DR-022). */
 export declare const RUNTIME_ABI = 1;
@@ -327,14 +367,7 @@ interface XStatePlaybookRuntimeSpecBase<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.
-         */
+        /** @deprecated Step checkpoints now carry the accepted input directly. */
         contextField?: string;
     };
     /**
@@ -458,8 +491,8 @@ export declare function defaultBuildJudgePrompt(input: PlaybookPlayerInput, fina
  * so the judge omits it. Rendering the clause verbatim asked the judge for
  * `question`, `planningResult`, or `evaluatedRevision`, which the reconciler
  * rejects as a structural error, spending the single correction on a
- * self-inflicted defect. Exported so a bespoke linked runtime (DECIDE's
- * parallel machinery) renders the identical contract instead of restating it.
+ * self-inflicted defect. Exported so linked machinery of an artifact's own
+ * renders the identical contract instead of restating it.
  */
 export declare function renderGovernedOutcomeContract(guard: string, description: string, outcome: XStateGovernedOutcomeSpec | undefined): string[];
 export interface PlayerAdjudicationSpec {
@@ -483,6 +516,7 @@ interface PlayerBridgeSpec {
     adjudication: PlayerAdjudicationSpec;
     resumableStateIds: ReadonlySet<string>;
     allowsCorrectiveReplay?: (result: PlayerResult) => boolean;
+    run?: (input: PlaybookPlayerInput, signal: AbortSignal, execute: () => Promise<PlaybookActorOutput>) => Promise<PlaybookActorOutput>;
 }
 export declare function createPlayerBridge(spec: PlayerBridgeSpec, ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined, boundary?: RuntimeBoundaryCalls, onControlPlaneError?: (error: unknown) => void): PromiseActorLogic<PlaybookActorOutput, PlaybookPlayerInput>;
 /**
@@ -495,7 +529,11 @@ export declare function defaultBuildCaptainJudgePrompt(input: {
     readonly sourceItem: string;
     readonly result: Readonly<Record<string, string>>;
 }, finalText: string): string;
-/** Targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
+/**
+ * Targets of the FSM's `awaitBossReply` BOSS_REPLY transitions, plus — for
+ * the parallel shape gears2fsm compiles (DR-067) — the targets of each
+ * region wait leaf's branch-local BOSS_REPLY arms, resolved to state ids.
+ */
 export declare function resumableStateIdsFromMachine(machine: AnyStateMachine): ReadonlySet<string>;
 /**
  * Source state descriptions by state key, node id, and `meta.playbook`
@@ -524,10 +562,12 @@ export declare function terminalOutcomesFromMachine(machine: AnyStateMachine, la
  * the optional parked-session snapshot capability (DR-014) and the retained-
  * snapshot adoption capability (DR-038).
  *
- * 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.
+ * Scope: flat single-region machines — every root state's
+ * `meta.playbook.stateId` equal to its state key, so each snapshot exposes
+ * exactly one playbook state id — plus the parallel profile of DR-067: root
+ * `type: 'parallel'` states of the shape gears2fsm compiles, whose regions
+ * run as one all-`unchanged` repository cohort with keyed pending questions.
+ * A machine declaring a parallel state omits `adopt`.
  */
 export declare function createXStatePlaybookRuntime<TOptions, THostCapabilities extends object>(machine: AnyStateMachine, spec: XStatePlaybookRuntimeSpecV3<TOptions>): XStatePlaybookRuntimeFactory<XStatePlaybookRuntimeConstruction<TOptions, THostCapabilities>, 3>;
 export {};