@sublang/playbook 15.0.0 → 16.0.0

package/slc/prefix.md

@@ -0,0 +1,203 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# GEARS Prompt-Prefix Pass
+
+Optional optimization pass of a playbook (a state-machine agent orchestrating
+other agents).
+Reorders each acting prompt so that its static instructions come first and the
+runtime values relayed into it come last, giving every run of the same item an
+identical prompt prefix that an LLM provider's prompt cache can serve.
+
+- Source: a package of GEARS spec items produced by [text2gears](text2gears.md)
+  and, when scheduled, already rewritten by [optimize](optimize.md).
+- Target: the same package with eligible prompts laid out prefix-first.
+
+The pass is format-preserving: source and target are both GEARS packages, and
+the pass sits between [text2gears](text2gears.md) and
+[gears2fsm](gears2fsm.md), after [optimize](optimize.md) by pass-name order.
+A playbook compiled without this pass has identical observable behavior; the
+pass trades a compile-time rewrite for cheaper prompt processing at run time.
+
+Prompt caches are prefix caches: a provider serves the longest prefix it has
+already seen and processes everything after the first differing token afresh
+[[1]], [[2]], [[3]].
+A prompt that opens with this run's relayed request therefore shares nothing
+with the previous run's prompt for the same item, while one that opens with
+the item's instructions shares them all.
+
+## Formats
+
+| Role   | Format | Extension |
+| ------ | ------ | --------- |
+| source | gears  | .md       |
+| target | gears  | .md       |
+
+## Prompt regions
+
+Within an item's blockquote, each prompt line is one of:
+
+- a **relay line** — prompt content that begins with the literal quote marker
+  `>` (written `> > …` in the GEARS file), which is how
+  [text2gears](text2gears.md#authored-prompt-fragments) relays a runtime value
+  such as `> Original request: <caller-input>`;
+- a **blank line** — an empty prompt line, written `>`;
+- an **instruction line** — any other prompt line.
+
+A **relay block** is a maximal run of consecutive relay lines bounded by blank
+lines or the blockquote's edges, whether Source authored it as a separate
+quoted relay or set it apart with blank lines inside a fenced instruction.
+A relay line adjacent to an instruction line is authored content of that
+instruction — a quoted example inside a fenced instruction, for instance — and
+belongs to the instruction, not to a relay block.
+
+An instruction line may carry an inline `<placeholder>`, such as a configured
+model name; the pass never splits or rewrites an instruction line to isolate
+it.
+
+## Eligibility
+
+The pass shall rewrite an item only when **all** of the following hold:
+
+- The item is an acting item with a prompt: a direct-Captain, delegated-role,
+  or nested-playbook-call blockquote.
+  A script item (`Captain shall run:`) has no prompt and is never rewritten.
+- At least one relay block precedes an instruction line.
+  An item whose relay blocks already trail every instruction line is already
+  prefix-first and stays unchanged.
+- No instruction line depends on a relayed value standing before it — one
+  that refers to the relayed text as above or preceding, or that continues a
+  sentence the relay began.
+  A reference to the relayed text as below or following stays true after the
+  move.
+
+Judgment stays conservative: when eligibility is uncertain, the pass shall
+leave the item unchanged rather than guess.
+The pass shall not invent prompt lines, labels, or separators, and shall not
+rewrite, merge, split, or drop any line.
+
+Source prose that places a relay after an instruction, or an instruction at
+the end of the prompt, tells [text2gears](text2gears.md) how to compose the
+prompt faithfully; it does not make the item ineligible.
+This pass overrides that composition order by design, and `--no-optimize`
+restores it.
+
+## Rewriting
+
+For each eligible item, the pass shall rewrite only the blockquote:
+
+- Emit every line that is not part of a relay block, in its original order,
+  keeping each line byte-for-byte, dropping leading and trailing blank lines,
+  and replacing each run of removed relay blocks together with the blank lines
+  bounding it by the first of those blank lines where it separated two
+  remaining lines; every other blank line, such as one inside a fenced
+  template, stays where it is.
+- Emit one blank line.
+- Emit the relay blocks in their original order, each byte-for-byte, with one
+  blank line between consecutive blocks.
+- Keep the item's ID, heading, condition, acting clause, `Results:`, and any
+  other metadata unchanged.
+- Preserve every other item and every non-item section byte-for-byte,
+  including an `## Optimizations` section the optimize pass appended, except
+  a legacy `## Prefixed prompts` section (see [Provenance](#provenance)).
+
+Because no line changes, the target stays in the Source language and every
+authored fragment remains intact; only the order of relay blocks relative to
+instructions changes.
+
+E.g., the source item
+
+```markdown
+### REVIEW-2
+
+When Reviewer raises or keeps any finding, Captain shall relay the caller input and Reviewer's findings to Coder with the disposition prompt:
+
+> > Original request: <caller-input>
+> > Reviewer findings: <reviewer-output>
+>
+> For each review item, accept or reject it.
+> Report every disposition, all relevant run results, and every rebuttal.
+
+Results:
+- `committed`: Coder accepted at least one item and added one new review-fix commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
+- `rejectedAll`: Coder rejected every item and made no commit. Output shall include `coderOutput: <verbatim final text>`.
+```
+
+becomes
+
+```markdown
+### REVIEW-2
+
+When Reviewer raises or keeps any finding, Captain shall relay the caller input and Reviewer's findings to Coder with the disposition prompt:
+
+> For each review item, accept or reject it.
+> Report every disposition, all relevant run results, and every rebuttal.
+>
+> > Original request: <caller-input>
+> > Reviewer findings: <reviewer-output>
+
+Results:
+- `committed`: Coder accepted at least one item and added one new review-fix commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
+- `rejectedAll`: Coder rejected every item and made no commit. Output shall include `coderOutput: <verbatim final text>`.
+```
+
+## Provenance
+
+The pass shall record nothing beside the rewritten prompts, whose layout
+shows the rewrite.
+A `## Prefixed prompts` section an earlier version of this pass appended shall
+be removed — up to the next heading, and at the end of the file with the blank
+lines before it; when no item is eligible and no such section is present, the
+target shall be the source content unchanged.
+Re-running the pass is a no-op by layout: an item whose relays already trail
+is not eligible.
+
+A Source-to-GEARS fidelity checker therefore reads the layout from each prompt:
+it accepts an item either in Source order throughout or in the prefix-first
+layout, which requires each instruction and relay block of the fragments the
+item carries intact, blank lines inside a block included, and used exactly
+once, the instruction blocks in Source order, the relay blocks in Source order,
+and every relay after the last instruction, a relay Source joined directly to
+an instruction staying beside it with its authored boundary, a bare relay the
+prose authored free to trail, and one occurrence standing for one authored
+fragment.
+
+## Deterministic rewriting
+
+The adjacent `prefix-prompts.mjs` tool performs this rewrite exactly:
+
+```sh
+node "<definition-directory>/prefix-prompts.mjs" --source "<source.gears.md>" --target "<target.gears.md>" [--keep <ITEM-ID>]...
+```
+
+It reads the source, rewrites every item eligible by the mechanical rules
+above, removes a legacy `## Prefixed prompts` section, writes the target, and
+prints the rewritten item IDs — or reports that no item was eligible.
+`--keep` excludes an item the tool would otherwise rewrite.
+
+The pass shall use the tool rather than rewrite by hand:
+
+1. Read the source and decide, for each item with a relay block preceding an
+   instruction line, whether an instruction depends on a relay standing before
+   it; that judgment is the pass's only non-mechanical step.
+2. Run the tool with `--keep` for each item so excluded.
+3. Read the target and confirm that every rewritten item's instructions and
+   relays are intact and that nothing changed beyond the rewritten items and
+   the removal of a legacy `## Prefixed prompts` section.
+
+The tool writes only the declared target and never modifies the source.
+
+## Out of scope
+
+- Any change to prompt wording, conditions, result contracts, or item order.
+- Rewriting behaviors into one another; that is the [optimize](optimize.md)
+  pass.
+- Where a transport sends a prompt as one content block, the provider's cache
+  boundary is the transport's concern; this pass only makes the shared prefix
+  exist.
+
+## References
+
+[1]: https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching "Anthropic — Prompt caching: place static content at the beginning of the prompt"
+[2]: https://developers.openai.com/api/docs/guides/prompt-caching "OpenAI — Prompt caching: put stable instructions first, dynamic content at the end"
+[3]: https://ai.google.dev/gemini-api/docs/caching "Google — Gemini context caching: put large and common contents at the beginning of the prompt"

package/slc/slc.pin-inputs.json

@@ -1,7 +1,17 @@
 {
   "schema": "sublang.slc.pin-inputs.v1",
   "closures": {
-    "gears2fsm": ["text2gears.md", "link.md", "workflow-contracts.json"],
+    "text2gears": [
+      "workflow-contracts.json"
+    ],
+    "gears2fsm": [
+      "text2gears.md",
+      "link.md",
+      "workflow-contracts.json"
+    ],
+    "prefix": [
+      "prefix-prompts.mjs"
+    ],
     "link": [
       "text2gears.md",
       "gears2fsm.md",

package/slc/text2gears.md

@@ -157,13 +157,37 @@ Keep each declaration outside plain-text parentheses; explanatory symbols in
 parenthetical guidance use plain text, never separate backticks, because those
 backticks would declare extra required fields. Guidance may instead occur
 inside a field's complete annotation, including any parentheses there.
-For example, use `` `codeCommit` (new code-owned commit) `` or
-`` `codeCommit: <new code-owned commit>` ``, without backticks around code.
+For example, use `` `latestCommit` (new code-owned commit) `` or
+`` `latestCommit: <commit identity>` ``, without backticks around code.
+The commit a call itself creates is always declared as `latestCommit`, the
+canonical effect-owned property every linked runtime fills from the
+repository receipt and every terminal output projects from.
 An output property name shall match the same ASCII identifier pattern as a
 guard name: a kebab-case Source placeholder such as `<coder-output>` names the
 property `coderOutput` through the canonical kebab-token-to-camel-field mapping
 of [link](link.md), never a quoted kebab-case key, because downstream artifacts
 and calling playbooks consume these properties by name.
+A result shall declare an output property only where a consumer requires it:
+a later item's `<placeholder>`, the workflow's terminal return, or the
+workflow's declared public interface below.
+A detail the acting agent reports only within its final text — a reason, a
+summary, a list — travels in the result's verbatim final-text property and is
+not a separate judge-authored property.
+
+Where the selected pipeline supplies the
+[workflow contracts](workflow-contracts.json) catalog and the Source's basename
+is one of its `literalTargetBindings`, the compiled workflow is held to that
+builtin's declared output interface, because callers compiled against the
+catalog address it by that id: a result property whose value that interface
+returns shall take the interface's property name — `branch`, `issueSummary`,
+and `coderOutput` for `branch`; `evaluatedRevision` for the revision a clean
+review round evaluated — whether the value is semantic, presentation, or
+effect-owned, while the commit a call itself creates keeps the canonical
+`latestCommit` for the FSM to project into the interface's field.
+A Source placeholder that names such a value otherwise is an inconsistency
+between the Source and the catalog: leave the Target unwritten and report it
+as an incompatible compiler input rather than rename or invent.
+A Source outside those ids is named from its own words as above.
 
 A produced value consumed later shall have a declared producer: where any
 later item's blockquote reads a value through a `<placeholder>`, the item
@@ -172,14 +196,37 @@ whose relevant description names the produced output property, using the
 placeholder's exact identifier — this is what lets the FSM thread the value
 through typed context.
 A single-outcome producer then declares exactly one bullet naming the
-property; this consumed-output case is the sole one in which a
-single-outcome behavior carries a `Results:` label.
+property; this consumed-output case and the qualified-outcome case below are
+the two in which a single-outcome behavior carries a `Results:` label.
+The commit a call itself creates is the one exception to naming the property
+after the placeholder: its producer declares `latestCommit: <commit identity>`
+whatever placeholder a later prompt reads it through — `<code-commit>` or
+`<decide-commit>`, for instance — because the linked runtime fills that
+property from the repository receipt rather than from the player, and
+[gears2fsm](gears2fsm.md#context-and-prompts) binds the Source's placeholder
+to the retained commit.
+A placeholder the Source defines as a labelled section of another relayed
+value, naming the label that opens the section and the labels that end it —
+`<original-intent>` as the `Original intent:` section of the caller's request,
+which runs to the `Review scope:` line or to the end of the request, for
+instance — is derived, not produced: text2gears shall keep that defining
+sentence verbatim in the package introduction, or in the item's prose where the
+Source states it there, name the placeholder as the Source does, and declare no
+result property for it, because no player produces the value and
+[gears2fsm](gears2fsm.md#context-and-prompts) derives it from the relayed text.
 
 Where a later prompt relays a delegated player's whole final response as quoted context, the producer shall declare that property in the exact annotated form `` `<field>: <verbatim final text>` ``.
 The annotation makes the field runtime-owned: the adjudicator selects the result guard, while the linked runtime carries the player's canonical final text into that field instead of asking a judge to reproduce it.
 A distinct typed field extracted from that response remains judge-authored even when a later prompt quotes its exact value; quoting a field does not turn it into the player's whole final response.
 One property name shall not be annotated as verbatim in one result contract and judge-authored in another; text2gears shall choose distinct properties or report that the Source cannot be represented by the current contract.
 
+A Source statement that qualifies an outcome's evidence — what affirmatively
+supports it, what supports no outcome, such as "a progress report, status
+update, or promise of a later result supports no review outcome" — shall be
+carried in that outcome's result description, the only text the adjudicator
+reads when it selects the guard; left in the item's prose, it reaches no
+judge.
+
 Result metadata is compiler control data, not part of the acting agent's
 prompt.
 text2gears shall not put guard names, result-property schema, JSON control
@@ -194,12 +241,16 @@ Where Source restricts an initial Captain to routing, text2gears shall preserve
 only the authored question and delegation outcomes and shall not infer a
 direct-answer or terminal result merely because Captain is the acting agent.
 
-A single-outcome behavior whose output no later item consumes carries no
-`Results:` label; downstream,
+A single-outcome behavior whose output no later item consumes and whose
+outcome Source leaves unqualified carries no `Results:` label; downstream,
 [gears2fsm](gears2fsm.md#setup) gives its state the default single-outcome
 contract, so text2gears shall not invent a one-bullet `Results:` block for it.
 When a later item does consume its output, the produced-value rule above
-applies instead.
+applies instead; when Source qualifies the one outcome's evidence — what
+affirmatively supports it, what supports no outcome — the behavior carries
+exactly one `Results:` bullet naming that outcome and carrying the
+qualification, with an output property only where a consumer requires one,
+because the adjudicator reads the qualification nowhere else.
 
 When Source requires a terminal return to the caller, preserve every returned value or fact and its return condition as an explicit workflow output obligation in GEARS.
 Merely naming a value in a completion predicate or an acting result does not state that the workflow returns it.
@@ -215,10 +266,16 @@ when the answer changes its complete runtime prompt. It shall not emit a
 second item solely for "Boss answers," "after the question," or clearing the
 consumed question/reply. The FSM and linker own the same-leaf suspension,
 continuation blocks, and consumed-context cleanup.
-When such an authored result asks Boss and waits, its `Results:` description
-shall declare `question: <verbatim final text>` as an output property; the
-result name or prose saying that a question is asked is not the field
-declaration.
+Outside the decide-call-observe routing contract, an authored Boss question
+is the framework-owned `needsBossReply` outcome that
+[gears2fsm](gears2fsm.md#boss-reply-suspension) adds to every Captain- or
+player-invoking state: text2gears shall keep the question's conditions in the
+prompt and its continuation in the item's prose and shall declare no result
+for it, because a second guard for the same wait would give the adjudicator
+two equivalent outcomes.
+Only the routing contract's own `question` and `followUpQuestion` results
+declare the question, as `question: <verbatim final text>`; there, the result
+name or prose saying that a question is asked is not the field declaration.
 
 This rule is an exception to splitting by accumulated prompt content below.
 Split only when Source requires a genuinely different acting behavior after
@@ -395,6 +452,9 @@ Markdown escaping is Source syntax, not content: extraction shall resolve escape
 
 Partition items by every variable that determines prompt content — including accumulated state when the trigger alone doesn't.
 
+Conversely, do not split by trigger alone: where two or more triggers lead to one behavior with the same acting clause, prompt, and result contract — a nested call Source says a later path makes "with the same input as" an earlier path's, for instance — text2gears shall emit one item whose condition joins the triggers and shall keep each path's continuation as that item's prose.
+An item per trigger duplicates an identical prompt and multiplies the FSM's states without a content difference.
+
 ### Prune dead disjuncts
 
 Drop disjunctive branches incompatible with the rest of an item's condition or prompt.

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

@@ -1,5 +1,5 @@
 import type { AnyStateMachine, EventObject, PromiseActorLogic } from 'xstate';
-import type { CaptainResult, JsonValue, PlaybookEffectBoundary, PlaybookEffectBoundaryStart, PlaybookEffectLedger, PlaybookEffectLedgerCapability, NormalizedError, PlaybookPendingBossQuestion, PlaybookPorts, PlaybookRepositoryReceipt, PlaybookRuntimeFactory, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
+import type { CaptainResult, JsonValue, PlaybookEffectBoundary, PlaybookEffectBoundaryStart, PlaybookEffectLedger, PlaybookEffectLedgerCapability, NormalizedError, PlaybookFailureCause, PlaybookPendingBossQuestion, PlaybookPorts, PlaybookRepositoryReceipt, PlaybookRuntimeFactory, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
 export interface PlaybookPendingBossQuestionContext {
     questionId: string;
     resumeStateId: string;
@@ -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>;
 }
@@ -115,6 +115,34 @@ export declare const BOSS_REPLY_ERRORS: {
     readonly missingQuestion: "needsBossReply outcome missing 'question' field";
     readonly unregisteredState: (stateId: string) => string;
 };
+export declare const ABORTED_FAILURE_CAUSE: PlaybookFailureCause;
+export declare function runtimeDefectCause(reason: string): PlaybookFailureCause;
+export declare function playerFailureCause(input: {
+    readonly roleId: string;
+    readonly playerId?: string;
+    readonly error: unknown;
+}): PlaybookFailureCause;
+/**
+ * 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. 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 — 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;
+    causeOf(error: unknown): PlaybookFailureCause | undefined;
+}
+export declare function createFailureCauseRetention(): PlaybookFailureCauseRetention;
 interface XStateRepositoryOperationSettlement<T> {
     readonly status: 'fulfilled';
     readonly value: T;
@@ -168,6 +196,17 @@ 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 {
     runExclusive<T>(options: {
         readonly signal: AbortSignal;
@@ -195,6 +234,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;
@@ -389,6 +449,13 @@ export declare function normalizeErrorFull(err: unknown): NormalizedError | unde
 export declare function pendingBossQuestionFromContext(context: Record<string, unknown>): PlaybookPendingBossQuestionContext | undefined;
 /** Add clarification context without repeating the question in a live conversation. */
 export declare function composePlayerContinuation(input: Pick<PlaybookPlayerInput, 'pendingBossQuestion' | 'bossReply'>, body: string, resuming?: boolean): string;
+/**
+ * The block for one governed call, or `undefined` where the call is not
+ * effect-authorized — a call whose declared outcomes carry no
+ * `one-descendant-commit` disposition may commit nothing, so it is told
+ * nothing.
+ */
+export declare function effectAuthorizedPreExistingBlock(effectBoundary: Pick<PlaybookEffectBoundaryStart, 'dispositions'>, baseline: PlaybookRepositoryReceipt['baseline'] | undefined): string | undefined;
 /**
  * Default player-prompt composer (slc/link.md §Player prompt composition).
  * One callback-based pass substitutes each `<fieldName>` placeholder whose
@@ -424,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 {
@@ -461,7 +528,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`
@@ -490,10 +561,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 {};