@sublang/playbook 8.0.0 → 10.0.0

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

@@ -8,8 +8,8 @@
 //                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
-import { RUNTIME_ABI, createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
+// 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;
 const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
@@ -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,12 +69,24 @@ function composePlayerPrompt(input, promptIdentity) {
 export const _internal = {
     composePlayerPrompt,
     VERBATIM_PAYLOAD_FIELDS,
+    UNFINISHED_FINAL_STATE_IDS,
 };
 const runtimeSpec = {
     label: 'REVIEW',
-    compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
+    // DR-022 / slc/link.md: the declaration carries the value current at link
+    // 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: 3, runtimeAbi: 1 },
     snapshotOptions: snapshotReviewOptions,
-    entryEvent: { type: 'START_REVIEW', textField: 'callerInput' },
+    entryEvent: {
+        type: 'START_REVIEW',
+        textField: 'callerInput',
+        // `copyStartInput` copies the entry text here, so the failure-state
+        // retry reads it back from the persisted machine snapshot and survives
+        // a continued session (DR-034).
+        contextField: 'callerInput',
+    },
     roleStates: {
         reviewInitial: {
             role: 'reviewer',
@@ -92,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,21 +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 {
-  RUNTIME_ABI,
   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,
@@ -76,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 =
@@ -85,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');
@@ -152,13 +158,25 @@ function composePlayerPrompt(
 export const _internal = {
   composePlayerPrompt,
   VERBATIM_PAYLOAD_FIELDS,
+  UNFINISHED_FINAL_STATE_IDS,
 };
 
 const runtimeSpec = {
   label: 'REVIEW',
-  compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
+  // DR-022 / slc/link.md: the declaration carries the value current at link
+  // 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: 3, runtimeAbi: 1 },
   snapshotOptions: snapshotReviewOptions,
-  entryEvent: { type: 'START_REVIEW', textField: 'callerInput' },
+  entryEvent: {
+    type: 'START_REVIEW',
+    textField: 'callerInput',
+    // `copyStartInput` copies the entry text here, so the failure-state
+    // retry reads it back from the persisted machine snapshot and survives
+    // a continued session (DR-034).
+    contextField: 'callerInput',
+  },
   roleStates: {
     reviewInitial: {
       role: 'reviewer',
@@ -180,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',
@@ -193,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
@@ -244,8 +245,9 @@ Each state shall declare:
 - a stable `id` (for `#id` targeting and Boss interrupts);
 - an intuitive state key (the property name under `states: { ... }`);
 - a one-line `description` (for inspector tools and documentation);
-- JSON-safe `meta: { playbook: { stateId, description, role? } }` repeating
-  its stable id and description so linked runtimes can discover active public
+- JSON-safe `meta: { playbook: { stateId, description, role? } }` naming the
+  state's public playbook identity per the identity rule below and repeating
+  its description so linked runtimes can discover active public
   identities through `snapshot.getMeta()` without private XState nodes. A
   delegated-role state shall also carry the canonical lowercase source role id in
   `meta.playbook.role`; every other state shall omit `role`;
@@ -258,6 +260,8 @@ Each state shall declare:
   and no `role`.
 
 The source item ID shall live in `invoke.input.sourceItem`, not in a comment — this keeps the GEARS-to-state mapping machine-readable.
+
+Outside a parallel group's regions, a state's `meta.playbook.stateId` shall equal its state key — the one identity a factory-backed linked runtime indexes by.
 A delegated state's `invoke.input.role` shall match the canonical lowercase id of its source item's named role.
 A direct Captain state shall not invent a `Captain` role binding.
 
@@ -650,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`.
@@ -748,6 +752,20 @@ an unhandled runtime error.
 Every machine shall declare at least one `type: 'final'` state (typically `done`) reachable on completion.
 A never-terminating machine is a defect: the runner has no completion signal.
 
+At least one is a floor, not a ceiling. A final state's `description` is the
+machine's published terminal meaning: a host that cannot read the machine's
+output quotes that description to report what the run did. It shall therefore
+be true of every arm that enters the state and of no other terminal outcome.
+Where Source declares more than one terminal outcome — an approval that
+completes the workflow and a failure the workflow reports to its caller
+instead of parking — each outcome shall get its own `type: 'final'` state
+whose description names it. Routing an approval arm and a failure, abort, or
+invalid-result arm into one final state is a defect of the same kind as a
+wrong result field, because the quoting host cannot detect the difference.
+This constrains only published meaning: the declared machine `output` still
+derives its status and fields from typed context, so a caller that does read
+the output is unaffected.
+
 Where Source declares a JSON-safe terminal result, the setup types shall
 declare that output and the root machine shall derive it from typed context
 through XState's machine `output` function. A final-state transition alone does