@sublang/playbook 9.0.0 → 11.0.0

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

@@ -1,13 +1,16 @@
-import { type XStatePromptIdentity } from '@sublang/playbook/xstate-runtime';
+import { type XStatePlaybookRuntimeFactory, type XStatePlaybookRuntimeConstruction, type XStatePromptIdentity } from '@sublang/playbook/xstate-runtime';
 import { type PlayerInput, type ReviewInput } from './review.fsm.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.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;
+export type ReviewPlaybookHostCapabilities = PlaybookHostConstructionCapabilities & XStatePlaybookRuntimeConstruction<ReviewPlaybookOptions, object>['hostCapabilities'];
 /** Keep every line of a relayed runtime value inside its authored quote. */
 declare function composePlayerPrompt(input: PlayerInput, promptIdentity: XStatePromptIdentity): string;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
+    UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string>;
 };
-declare const createPlaybookRuntime: PlaybookRuntimeFactory<ReviewPlaybookOptions>;
+declare const createPlaybookRuntime: XStatePlaybookRuntimeFactory<XStatePlaybookRuntimeConstruction<ReviewPlaybookOptions, ReviewPlaybookHostCapabilities>, 3>;
 export default createPlaybookRuntime;

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

@@ -8,7 +8,7 @@
 //                callerInput; pending player questions retain BOSS_REPLY
 // Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
 //                carried verbatim
-// Compat:        artifact schema 2 / runtime ABI 1
+// Compat:        artifact schema 3 / runtime ABI 1
 import { createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { reviewMachine, } from './review.fsm.js';
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
@@ -17,6 +17,7 @@ const VERBATIM_PAYLOAD_FIELDS = new Set([
     'reviewerOutput',
     'coderOutput',
 ]);
+const UNFINISHED_FINAL_STATE_IDS = new Set();
 function snapshotReviewOptions(value) {
     const captured = snapshotJsonValue(value, 'REVIEW runtime options');
     if (captured === null ||
@@ -68,6 +69,7 @@ function composePlayerPrompt(input, promptIdentity) {
 export const _internal = {
     composePlayerPrompt,
     VERBATIM_PAYLOAD_FIELDS,
+    UNFINISHED_FINAL_STATE_IDS,
 };
 const runtimeSpec = {
     label: 'REVIEW',
@@ -75,7 +77,7 @@ const runtimeSpec = {
     // 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 },
+    compat: { artifactSchema: 3, runtimeAbi: 1 },
     snapshotOptions: snapshotReviewOptions,
     entryEvent: {
         type: 'START_REVIEW',
@@ -103,9 +105,70 @@ const runtimeSpec = {
             label: 'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
         },
     },
+    outcomeAuthority: {
+        governedPlayerStates: {
+            reviewInitial: {
+                hasFindings: {
+                    fields: { reviewerOutput: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                noFindings: {
+                    fields: {},
+                    repositoryDisposition: 'unchanged',
+                },
+                needsBossReply: {
+                    fields: { question: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+            },
+            addressFindings: {
+                committed: {
+                    fields: { coderOutput: 'presentation' },
+                    repositoryDisposition: 'one-descendant-commit',
+                },
+                rejectedAll: {
+                    fields: { coderOutput: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                needsBossReply: {
+                    fields: { question: 'presentation' },
+                    repositoryDisposition: 'deferred',
+                },
+            },
+            reviewAfterCommit: {
+                hasFindings: {
+                    fields: { reviewerOutput: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                noFindings: {
+                    fields: {},
+                    repositoryDisposition: 'unchanged',
+                },
+                needsBossReply: {
+                    fields: { question: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+            },
+            reviewAfterRebuttal: {
+                hasFindings: {
+                    fields: { reviewerOutput: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                noFindings: {
+                    fields: {},
+                    repositoryDisposition: 'unchanged',
+                },
+                needsBossReply: {
+                    fields: { question: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+            },
+        },
+    },
     composePlayerPrompt: (input, promptIdentity) => composePlayerPrompt(input, promptIdentity),
     verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
     controlContextFields: [],
+    unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
     transitionEventFields: [
         'callerInput',
         'bossIntent',

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

@@ -8,20 +8,23 @@
 //                callerInput; pending player questions retain BOSS_REPLY
 // Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
 //                carried verbatim
-// Compat:        artifact schema 2 / runtime ABI 1
+// Compat:        artifact schema 3 / runtime ABI 1
 
 import {
   createXStatePlaybookRuntime,
   snapshotJsonValue,
   type PlaybookPlayerInput,
+  type XStatePlaybookRuntimeFactory,
+  type XStatePlaybookRuntimeConstruction,
   type XStatePromptIdentity,
-  type XStatePlaybookRuntimeSpec,
+  type XStatePlaybookRuntimeSpecV3,
 } from '@sublang/playbook/xstate-runtime';
 import {
   reviewMachine,
   type PlayerInput,
   type ReviewInput,
 } from './review.fsm.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 import type {
   CaptainCallOptions,
   CaptainResult,
@@ -75,6 +78,9 @@ export type {
 };
 
 export type ReviewPlaybookOptions = ReviewInput;
+export type ReviewPlaybookHostCapabilities =
+  PlaybookHostConstructionCapabilities &
+    XStatePlaybookRuntimeConstruction<ReviewPlaybookOptions, object>['hostCapabilities'];
 
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
 const CONTINUATION_PREAMBLE =
@@ -84,6 +90,7 @@ const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
   'reviewerOutput',
   'coderOutput',
 ]);
+const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set();
 
 function snapshotReviewOptions(value: unknown): ReviewPlaybookOptions {
   const captured = snapshotJsonValue(value, 'REVIEW runtime options');
@@ -151,6 +158,7 @@ function composePlayerPrompt(
 export const _internal = {
   composePlayerPrompt,
   VERBATIM_PAYLOAD_FIELDS,
+  UNFINISHED_FINAL_STATE_IDS,
 };
 
 const runtimeSpec = {
@@ -159,7 +167,7 @@ const runtimeSpec = {
   // 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 },
+  compat: { artifactSchema: 3, runtimeAbi: 1 },
   snapshotOptions: snapshotReviewOptions,
   entryEvent: {
     type: 'START_REVIEW',
@@ -190,12 +198,73 @@ const runtimeSpec = {
         'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
     },
   },
+  outcomeAuthority: {
+    governedPlayerStates: {
+      reviewInitial: {
+        hasFindings: {
+          fields: { reviewerOutput: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+        noFindings: {
+          fields: {},
+          repositoryDisposition: 'unchanged',
+        },
+        needsBossReply: {
+          fields: { question: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+      },
+      addressFindings: {
+        committed: {
+          fields: { coderOutput: 'presentation' },
+          repositoryDisposition: 'one-descendant-commit',
+        },
+        rejectedAll: {
+          fields: { coderOutput: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+        needsBossReply: {
+          fields: { question: 'presentation' },
+          repositoryDisposition: 'deferred',
+        },
+      },
+      reviewAfterCommit: {
+        hasFindings: {
+          fields: { reviewerOutput: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+        noFindings: {
+          fields: {},
+          repositoryDisposition: 'unchanged',
+        },
+        needsBossReply: {
+          fields: { question: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+      },
+      reviewAfterRebuttal: {
+        hasFindings: {
+          fields: { reviewerOutput: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+        noFindings: {
+          fields: {},
+          repositoryDisposition: 'unchanged',
+        },
+        needsBossReply: {
+          fields: { question: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+      },
+    },
+  },
   composePlayerPrompt: (
     input: PlaybookPlayerInput,
     promptIdentity: XStatePromptIdentity,
   ) => composePlayerPrompt(input as PlayerInput, promptIdentity),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   controlContextFields: [],
+  unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
   transitionEventFields: [
     'callerInput',
     'bossIntent',
@@ -203,9 +272,17 @@ const runtimeSpec = {
     'answer',
     'questionId',
   ],
-} satisfies XStatePlaybookRuntimeSpec<ReviewPlaybookOptions>;
+} satisfies XStatePlaybookRuntimeSpecV3<ReviewPlaybookOptions>;
 
-const createPlaybookRuntime: PlaybookRuntimeFactory<ReviewPlaybookOptions> =
-  createXStatePlaybookRuntime(reviewMachine, runtimeSpec);
+const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
+  XStatePlaybookRuntimeConstruction<
+    ReviewPlaybookOptions,
+    ReviewPlaybookHostCapabilities
+  >,
+  3
+> = createXStatePlaybookRuntime<
+  ReviewPlaybookOptions,
+  ReviewPlaybookHostCapabilities
+>(reviewMachine, runtimeSpec);
 
 export default createPlaybookRuntime;

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

@@ -1,4 +1,4 @@
-import { type PlaybookRuntime } from './review.playbook.js';
+import { type ReviewPlaybookHostCapabilities, type PlaybookRuntime } from './review.playbook.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -12,12 +12,19 @@ export interface ReviewPlaybookRegistryEntry {
     id: 'review';
     command: 'review';
     intent: string;
-    artifactSchema: 2;
+    artifactSchema: 3;
+    runtimeProfile: {
+        readonly kind: 'shared-factory';
+        readonly compat: {
+            readonly artifactSchema: 3;
+            readonly runtimeAbi: number;
+        };
+    };
     requiredRoleIds: readonly ['coder', 'reviewer'];
     concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): ReviewOptions;
-    createRuntime(options: ReviewOptions): PlaybookRuntime;
+    createRuntime(options: ReviewOptions, hostCapabilities: ReviewPlaybookHostCapabilities): PlaybookRuntime;
 }
 export declare const reviewStateCountLabels: {
     readonly reviewInitial: "review round";

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

@@ -48,13 +48,20 @@ export const reviewPlaybookRegistryEntry = {
     id: 'review',
     command: 'review',
     intent: 'review the latest commit until no material correctness or spec findings remain',
-    artifactSchema: 2,
+    artifactSchema: 3,
+    runtimeProfile: Object.freeze({
+        kind: 'shared-factory',
+        compat: createPlaybookRuntime.compat,
+    }),
     requiredRoleIds: ['coder', 'reviewer'],
     concurrentRoleSets: [],
     summaryPolicy: reviewSummaryPolicy,
     validateOptions: validateReviewOptions,
-    createRuntime(options) {
-        return createPlaybookRuntime(options);
+    createRuntime(options, hostCapabilities) {
+        return createPlaybookRuntime({
+            configuredOptions: options,
+            hostCapabilities,
+        });
     },
 };
 export default reviewPlaybookRegistryEntry;

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

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import createPlaybookRuntime, {
+  type ReviewPlaybookHostCapabilities,
   type PlaybookRuntime,
 } from './review.playbook.js';
 
@@ -20,12 +21,22 @@ export interface ReviewPlaybookRegistryEntry {
   id: 'review';
   command: 'review';
   intent: string;
-  artifactSchema: 2;
+  artifactSchema: 3;
+  runtimeProfile: {
+    readonly kind: 'shared-factory';
+    readonly compat: {
+      readonly artifactSchema: 3;
+      readonly runtimeAbi: number;
+    };
+  };
   requiredRoleIds: readonly ['coder', 'reviewer'];
   concurrentRoleSets: readonly [];
   summaryPolicy: PlaybookSummaryPolicy;
   validateOptions(optionSlice: unknown): ReviewOptions;
-  createRuntime(options: ReviewOptions): PlaybookRuntime;
+  createRuntime(
+    options: ReviewOptions,
+    hostCapabilities: ReviewPlaybookHostCapabilities,
+  ): PlaybookRuntime;
 }
 
 export const reviewStateCountLabels = {
@@ -94,13 +105,20 @@ export const reviewPlaybookRegistryEntry: ReviewPlaybookRegistryEntry = {
   command: 'review',
   intent:
     'review the latest commit until no material correctness or spec findings remain',
-  artifactSchema: 2,
+  artifactSchema: 3,
+  runtimeProfile: Object.freeze({
+    kind: 'shared-factory',
+    compat: createPlaybookRuntime.compat,
+  }),
   requiredRoleIds: ['coder', 'reviewer'],
   concurrentRoleSets: [],
   summaryPolicy: reviewSummaryPolicy,
   validateOptions: validateReviewOptions,
-  createRuntime(options) {
-    return createPlaybookRuntime(options);
+  createRuntime(options, hostCapabilities) {
+    return createPlaybookRuntime({
+      configuredOptions: options,
+      hostCapabilities,
+    });
   },
 };
 

package/slc/gears2fsm.md

@@ -222,12 +222,13 @@ teardown event. The completion rule of
 output clause binds only where Source declares a terminal result, which a
 controller Source does not.
 The controller decision state's direct-Captain result contract discriminates
-the closed action set of DR-029. Its guard discriminants are a stable
-compiler contract, not names the compiler may invent — `respond`, `start`,
-`switch`, `dismiss`, `deliver`, and `runtime` — with each guard's required
-payload fields:
+the closed action set of DR-029 as extended by DR-038. Its guard discriminants
+are a stable compiler contract, not names the compiler may invent — `respond`, `resume`,
+`start`, `switch`, `dismiss`, `deliver`, and `runtime` — with each guard's
+required payload fields:
 
 - `respond` requires `text`;
+- `resume` requires `playbookId` and carries no `input`;
 - `start` and `switch` each require `playbookId` and `input`;
 - `runtime` requires `actionId`;
 - `dismiss` and `deliver` require none — a `deliver` result in particular
@@ -653,7 +654,7 @@ Boss-reply suspension, because its hub already receives every Boss turn and a
 clarifying question to Boss is a `respond` selection over the closed action
 set. The rule below is therefore universal over workflow states and silent
 about that class; in particular, adding `needsBossReply` to the controller
-decision state would add a seventh outcome to a closed six-action contract
+decision state would add an eighth outcome to a closed seven-action contract
 whose guard discriminants [Setup](#setup) fixes, and is nonconformant.
 There is no source-level opt-in annotation and no `needsBossReply` result metadata in GEARS output.
 The FSM compiler shall preserve the GEARS blockquote as the state's domain `prompt` body and shall not inject any Boss-question instruction into `invoke.input.prompt`.