@sublang/playbook 15.1.0 → 16.0.0

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

@@ -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,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;
@@ -222,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;
@@ -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 {
@@ -495,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`
@@ -524,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 {};