@sublang/playbook 15.1.0 → 17.0.0

package/slc/gears2fsm.md

@@ -141,9 +141,11 @@ generic Captain forms, wire `<boss-intent>` from `bossIntent`,
 `remainingPlan`, and `<completed-call-results>` from
 `completedCallResults`. Other non-identity placeholders shall retain the
 semantic typed field established by Source (for example `<#>` from
-`irNumber`). Leaving an ordinary runtime-value placeholder literal, replacing
-it with an empty default because its field was omitted, or making the linker
-recover it from untyped context is malformed.
+`irNumber`); a created-commit or labelled-section placeholder binds as
+[Context and prompts](#context-and-prompts) states. Leaving an ordinary
+runtime-value placeholder literal, replacing it with an empty default because
+its field was omitted, or making the linker recover it from untyped context is
+malformed.
 The corresponding `invoke.input` object shall include that field beside `prompt`; storing it only in machine context does not satisfy the actor-input contract.
 When Source declares a placeholder as the current identity of a local acting
 role, preserve the placeholder literal in the FSM prompt and do not add any
@@ -241,15 +243,16 @@ 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 as extended by DR-038. Its guard discriminants
+the closed action set of DR-029 as extended by DR-038 and DR-069. 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
+`start`, `switch`, `dismiss`, `deliver`, and `runtime`, plus `recover` when Source declares recovery preparation — 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`;
+- `recover`, when declared, requires no payload and selects host-owned preparation followed by runtime-validated continuation;
 - `dismiss` and `deliver` require none — a `deliver` result in particular
   carries no text payload: the host is authoritative for the delivered text,
   so the contract declares no field for it.
@@ -610,6 +613,37 @@ or remove remaining entries as evidence arrives, but it cannot grow or retain
 the same-length plan indefinitely; the initial finite array therefore bounds
 the number of sequential child calls without an arbitrary runtime call limit.
 
+A placeholder that reads the commit an earlier call created — `<code-commit>`,
+`<decide-commit>` — binds to a typed context field named by its canonical
+mapping, assigned from that call's accepted `latestCommit`, the effect-owned
+property the runtime fills from the repository receipt
+([text2gears](text2gears.md#result-contracts)); the actor input carries the
+field beside the prompt like any other relayed value.
+A placeholder the GEARS defines as a labelled section of another relayed
+text binds to a typed context field named by its canonical mapping. The
+definition names 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. The
+machine derives the field deterministically in the entry action or transition
+that stores the text and again in every action that replaces it, such as a
+fresh entry directive or an interrupt that restarts with new text:
+
+- the text as read is the text itself, except that where every non-blank line
+  begins with `>`, each line is read without that marker and one optional space
+  after it, the literal quote layer a quoted relay adds;
+- the section is the lines of the text as read from the first line that
+  begins with the opening label, the label removed, through the line before the
+  first later line that begins with an ending label, or through the last line,
+  with the result trimmed; a line that merely looks labelled, such as `Note:`
+  or `Constraints:`, stays in the section;
+- where no line begins with the opening label, or the section is empty once
+  trimmed — its label directly followed by an ending label or by the end of
+  the text — the field is the whole text as read, trimmed, so the request is
+  never lost.
+
+The derived field is ordinary context that actor inputs relay, never a player
+or judge output.
+
 Prompts shall pass only the **specific extracted fields** the player needs.
 The compiler shall not dump `JSON.stringify(lastResult)` or any opaque blob: it leaks internal `guard` strings, wastes tokens, and confuses the LLM.
 
@@ -663,6 +697,26 @@ The compiler shall update or reset those source-owned facts only at their actual
 Transitions shall be self-driving when source items define the next obligation.
 Routing to an idle hub is for recovery, unrecoverable Boss input, or one-shot entry events — not the happy path.
 
+Where an artifact-schema-3 delegated-player state's outcomes are governed by the
+linked runtime ([link.md "Captain adjudication"](link.md#captain-adjudication)),
+every accepted `onDone` arm — each arm that routes a declared outcome, not the
+malformed-output fallback — shall carry, first among its actions, the
+root-machine action
+`{ type: 'playbook.acceptedOutcome', params: { source: '<stateId>', target: '<target stateId>', acceptedOutcome: '<guard>' } }`,
+with the setup's `actions` declaring `'playbook.acceptedOutcome'` as a no-op
+that types those three string params.
+`target` names the state the next public snapshot shows for the arm: the arm's
+own target, or the parallel parent's `onDone` target where the arm's target is a
+region's final leaf that completes that parent, because the machine leaves that
+leaf before the snapshot; an arm that completes the join only when every
+sibling region is already final therefore splits into two arms guarded on that
+condition, each naming the state it reaches.
+The linked runtime retains the marker until the next public snapshot confirms
+`source` in the prior snapshot and `target` in the new one, and only then
+publishes the outcome's accepted trace and `→ <acceptedOutcome>` status; an arm
+without the marker accepts its outcome silently, and the host counts none of the
+work it saved.
+
 ### Auto-advance on approval
 
 A review/approval state's success outcome shall **target the next workflow step**, not idle back to a hub.
@@ -726,8 +780,7 @@ current event, not solely from the context that action will populate.
 For an omitted event value, use an existing context seed only where Source
 permits it; do not manufacture a required constructor value to satisfy a
 context-only entry guard. The linked runtime sends the entry event normally;
-its `entryEvent.contextField` declaration supports failure retry and does not
-copy fresh text into context before the guard.
+entry metadata does not copy fresh text into context before the guard.
 An entry event's copy action shall not clear per-run parameters the event omits: an absent optional field falls back to the existing (input-seeded) context value.
 The two surfaces shall not be collapsed. `BOSS_INTERRUPT` always carries its
 target id and may additionally carry typed Boss-supplied fields such as an
@@ -750,7 +803,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 an eighth outcome to a closed seven-action contract
+decision state would add an unauthorized outcome to its closed controller 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`.
@@ -811,6 +864,12 @@ Where several questions are pending, the classifier prompt and event shall
 require `questionId` and shall reject an omitted or unknown id without moving
 the FSM.
 
+Every exit from a Captain- or player-invoking state other than into its own
+Boss-reply wait — an accepted outcome, the malformed-output fallback, an actor
+error — and every non-reply exit from a wait shall clear that state's pending
+question and reply context, so a call that fails after resuming leaves no
+stale question for the next turn's classifier to offer.
+
 The scalar `awaitBossReply` state and every local branch wait are quiescent for
 the runtime drive boundary.
 They shall allow a fresh root entry event or interrupt to abandon the relevant
@@ -882,6 +941,16 @@ 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
 not satisfy a declared output contract.
+Where the selected pipeline supplies the
+[workflow contracts](workflow-contracts.json) catalog and the compiled Source's
+basename is one of its `literalTargetBindings`, the declared terminal output
+shall be exactly that builtin's public interface — its variants, `status`
+constants, property names, and requiredness — derived from typed context,
+because callers compiled against the catalog consume it by those names; an
+authored outcome the interface cannot express is an inconsistency between the
+Source and the catalog, reported as an incompatible compiler input under
+[Nested playbook calls](#nested-playbook-calls) rather than expressed by an
+invented or renamed outcome.
 Fields that Source requires in every terminal output shall be required in the
 TypeScript output type. In particular, a declared `{ response }` result shall
 compile as `{ response: string }`, not `{ response?: string }`; reaching the

package/slc/link.md

@@ -38,15 +38,20 @@ The link compiler shall not modify the FSM artifact and shall not re-derive Capt
 
 ## Optional deterministic materialization
 
-For an ordinary flat workflow using only `player` and `script` actors,
-the supported prompt profile below, shared remaining strategies, and primitive configured options, the linker may
+For an ordinary workflow using only `player` and `script` actors — flat, or
+with root parallel groups of the [Parallel groups](gears2fsm.md#parallel-groups)
+shape — the supported prompt profile below, shared remaining strategies, and primitive configured options, the linker may
 use the adjacent `materialize-link.mjs` tool to emit the thin module.
 The complete definition below remains binding; the tool replaces repetitive
 module generation, not semantic analysis or emitted conformance verification.
 Read the actual FSM and supply every erased or authored contract exactly.
 Do not use `flat-defaults` or `flat-quoted-relays` when another custom composer, classifier, required-field
 extractor, session-derived input mapping, controller strategy, nested call,
-parallel state, or compound state is needed.
+or compound state other than such a parallel group is needed.
+Despite their names, every profile accepts those parallel groups: the tool
+takes each region working leaf's role and label under its stable state id
+like any other player state, declares nothing further, and leaves the
+compiled shape to the factory preflight, which rejects any other form.
 
 Invoke the tool with the actual definition directory, source FSM, and declared
 target; supply a JSON descriptor on standard input:
@@ -60,7 +65,7 @@ node "<definition-directory>/materialize-link.mjs" --fsm "<source.fsm.ts>" --out
   "label": "EXAMPLE",
   "options": {},
   "inputMapping": {},
-  "entryEvent": { "type": "BOSS_TASK", "textField": "bossIntent", "contextField": "bossIntent" },
+  "entryEvent": { "type": "BOSS_TASK", "textField": "bossIntent" },
   "bossEvents": [],
   "outcomeAuthority": {
     "governedPlayerStates": {
@@ -101,6 +106,12 @@ session-derived input values are outside this profile; do not widen their
 contracts to an unconstrained primitive.
 The tool adds optional string `cwd` for script-bearing machines; it does not
 put `cwd` in FSM input unless the descriptor explicitly maps it.
+When the linked module is part of a package that compiles and ships
+JavaScript siblings, supply the optional `fsmSpecifier` — the `.js` sibling
+the build emits for the source FSM, such as `./code.fsm.js`, in the same
+directory and with the same basename — so the emitted import satisfies the
+NodeNext rule under Output; omit it for a source-only host, where the tool
+derives the specifier from the `--fsm` path.
 An explicit `entryEvent: null` selects the shared classifier only where this
 definition permits no deterministic entry; it does not relax entry rules.
 `bossEvents` retains the exact additional erased event fields, source ownership,
@@ -125,8 +136,9 @@ correct the identified problem before treating linking as successful.
 
 ### Experimental labelled-string and nested-call profile
 
-`flat-labelled-relays` is an unmeasured candidate for flat single-region
-machines with delegated players, scripts, and nested `playbook` calls. It
+`flat-labelled-relays` is an unmeasured candidate for machines with flat
+root states or root parallel groups of that shape, whose delegated players,
+scripts, and nested `playbook` calls it supports. It
 requires the installed shared `composePlayerContinuation` API. It leaves
 nested input composition, child targets, result guards, recovery, and terminal
 semantics in the unchanged FSM; the shared factory provides the nested bridge.
@@ -154,8 +166,8 @@ source tokens. Undeclared empty relay lines retain their authored text.
 The emitted verification composer has the same identity and optional third
 resume arguments as the runtime; the shared helper owns fresh/resumed Q&A.
 Structured rendering, custom classifiers/extractors/controllers, direct
-Captain actors, compound/parallel topology, and constrained/nonprimitive
-options remain unsupported. Source-derived metadata and all existing
+Captain actors, compound topology other than such a parallel group, and
+constrained/nonprimitive options remain unsupported. Source-derived metadata and all existing
 conformance checks remain mandatory. This profile changes no runtime bridge,
 workflow semantics, or measured performance claim.
 
@@ -184,6 +196,8 @@ 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;
@@ -354,6 +368,7 @@ interface PlaybookEffectBoundary {
   readonly baseline: PlaybookRepositoryObservation;
   readonly after?: PlaybookRepositoryObservation;
   readonly physicalReceipt?: PlaybookRepositoryReceipt;
+  readonly restored?: PlaybookRepositoryObservation;
   readonly finalText?: string;
   readonly semanticCandidate?: JsonValue;
   readonly initialSemanticCandidate?: JsonValue;
@@ -393,6 +408,7 @@ type PlaybookEffectBoundaryStart = Omit<
   | 'finalText'
   | 'semanticCandidate'
   | 'initialSemanticCandidate'
+  | 'restored'
 >;
 
 type PlaybookEffectLogicalOperationStart = Omit<
@@ -454,6 +470,23 @@ interface PlaybookEffectLedgerCapability {
   ): Promise<PlaybookEffectLedger>;
 }
 
+interface PlaybookRecoveryCheckpoint {
+  readonly id?: string;
+  readonly stateId: string;
+  readonly prompt: string;
+  readonly machine: JsonValue;
+  readonly boundaryPrefix: number;
+  readonly result?: JsonValue;
+  readonly delivered?: true;
+}
+
+interface PlaybookStepRecord {
+  readonly id: string;
+  readonly kind: 'player' | 'captain' | 'script';
+  readonly stateId: string;
+  readonly result?: JsonValue;
+}
+
 interface PlaybookRuntimeSnapshot {
   schemaVersion: 4;
   playbookId: string;
@@ -484,6 +517,8 @@ interface PlaybookRuntimeSnapshot {
     readonly boundaryPrefix: number;
     readonly attemptId: string | null;
   };
+  /** Interrupted invocation, captured before its external call (DR-069). */
+  recoveryCheckpoint?: PlaybookRecoveryCheckpoint;
   suspendedCall?: PlaybookSuspendedCall;
 }
 
@@ -568,7 +603,7 @@ interface XStatePlaybookRuntimeConstruction<
 
 The shared type-only contract module shall export `PlaybookRepositoryDisposition`, `PlaybookRepositoryObservation`, `PlaybookRepositoryReceipt`, `PlaybookEffectBoundary`, `PlaybookEffectBoundaryStart`, `PlaybookEffectLogicalOperation`, `PlaybookEffectLedger`, `PlaybookEffectLedgerCommand`, `PlaybookEffectLedgerCommandBatch`, and `PlaybookEffectLedgerCapability`; the executable `@sublang/playbook/xstate-runtime` module shall export `assertPlaybookEffectLedger`, `emptyPlaybookEffectLedger`, and `isPlaybookEffectLedgerMonotonicExtension` over those types.
 That executable module shall also export the centralized schema-3 semantic surface: `PlaybookSemanticFieldAuthority`, `PlaybookSemanticOutcomeSpec`, `PlaybookSemanticEvidenceInput`, `PlaybookReconciledSemanticOutput`, `PlaybookRetainedSemanticEvidence`, `PlaybookSemanticReconciliationReason`, `PlaybookSemanticReconciliation`, `PlaybookSemanticCandidateStructureError`, and `reconcilePlaybookSemanticEvidence`.
-The pure reconciler shall accept the declared state-local outcomes, an unknown semantic candidate, and optional unknown `finalText`, repository receipt, and runtime-field evidence; shall return a detached frozen `resolved` or `deferred` decision with exact output and retained evidence, or an `unresolved` decision with retained evidence and one closed reason from `missing-presentation-evidence`, `missing-repository-receipt`, `invalid-repository-receipt`, `repository-disposition-mismatch`, `missing-effect-evidence`, `missing-runtime-evidence`, and `inconsistent-runtime-evidence`; and shall reserve `PlaybookSemanticCandidateStructureError` for candidate defects eligible for the bounded correction path rather than effect-evidence disagreement.
+The pure reconciler shall accept the declared state-local outcomes, an unknown semantic candidate, and optional unknown `finalText`, repository receipt, and runtime-field evidence; shall return a detached frozen `resolved` or `deferred` decision with exact output and retained evidence, or an `unresolved` decision with retained evidence and one closed reason from `no-matching-outcome`, `missing-presentation-evidence`, `missing-repository-receipt`, `invalid-repository-receipt`, `repository-disposition-mismatch`, `missing-effect-evidence`, `missing-runtime-evidence`, and `inconsistent-runtime-evidence`; and shall reserve `PlaybookSemanticCandidateStructureError` for candidate defects eligible for the bounded correction path rather than effect-evidence disagreement.
 The empty ledger shall be exactly `{ schemaVersion: 1, revision: 0, boundaries: [], logicalOperations: [] }`, and revision shall be zero if and only if both ordered ledgers are empty.
 The validator shall capture the complete supplied ledger once as detached frozen JSON and enforce every closed member, identity, ordering, receipt, cross-reference, correction-budget, and logical-operation invariant represented above.
 One optional host-owned UUID `cohortId` shall identify every member of exactly one contiguous, distinct-role, all-`unchanged` physical cohort in declared role order; every member shall share attempt, playbook, runtime-session, turn, canonical-worktree, and baseline identity and shall be uniformly started or uniformly complete, complete members shall carry the identical after observation and receipt, and the id shall never be reused by another group.
@@ -630,8 +665,8 @@ Boss text supplied by the entry event is not a required startup option unless So
 A generated entry guard that requires the text already in context is likewise
 not independent Source evidence; it is a producer defect when the entry action
 has yet to copy the event's text. Do not compensate with a required option or
-invented startup task. `entryEvent.contextField` supplies failure-retry text;
-it does not populate fresh entry context before FSM guards execute.
+invented startup task. Entry metadata does not populate fresh context before
+FSM guards execute. Interrupted-step checkpoints retain accepted input.
 A source-appropriate optional seed may remain, and genuine required bootstrap catalogs or other options shall not be erased or filled with invented defaults.
 
 Concrete player binding and prompt identity are host policy and shall not enter `PlaybookRuntimeOptions`, machine input, or the emitted artifact.
@@ -642,6 +677,7 @@ The host shall derive `promptIdentity` from the current effective model when pre
 
 ```typescript
 interface PlaybookPorts {
+  recordStep?(step: PlaybookStepRecord, position?: PlaybookRuntimeSnapshot): Promise<void>;
   callPlayer(
     roleId: string,
     prompt: string,
@@ -1239,7 +1275,7 @@ undeclared extra key, so hidden adjudication cannot replace, paraphrase, or
 decorate prose Boss already saw.
 For an artifact-schema-3 governed delegated-player call, the shared engine
 shall instead use one semantic reconciler for both the default linked runtime
-and any bespoke linked runtime that adopts schema `3`.
+and any linked machinery of an artifact's own that adopts schema `3`.
 That reconciler shall retain the validated player's exact non-empty
 `finalText` as opaque presentation evidence, let the hidden adjudicator read
 it only as semantic evidence, and require the adjudicator's detached
@@ -1257,8 +1293,8 @@ authored placeholder or guidance, with every presentation-, effect-, or
 runtime-owned field named as runtime-supplied to omit — so the judge is never asked for a
 field it does not own; the artifact's description text stays unchanged.
 The shared engine shall export that rendering as `renderGovernedOutcomeContract`
-on `@sublang/playbook/xstate-runtime`, and a bespoke linked runtime shall
-render its judge prompt through it rather than restate the contract.
+on `@sublang/playbook/xstate-runtime`, and linked machinery of an artifact's
+own shall render its judge prompt through it rather than restate the contract.
 The reconciler shall construct the complete actor output rather than accept a
 cross-authority object from the judge: every presentation-owned payload field
 shall receive the canonical `finalText.trim()` value; every effect-owned
@@ -1271,6 +1307,13 @@ field.
 It shall reject an absent required field, an undeclared or extra field, a
 field supplied by the wrong authority, an invalid value, or any mutually
 inconsistent candidate before FSM delivery.
+When no outcome matches, a governed judge may instead return exactly
+`{ blocked: <nonempty explanation> }`.
+The shared reconciler retains this candidate and returns `no-matching-outcome`
+with its explanation as a `runtime-defect` cause; it authorizes neither a
+corrective judge nor an FSM outcome.
+Both shared and bespoke judge prompts shall state this alternative explicitly
+instead of forcing a match when the declared results are incomplete.
 
 For a non-deferred candidate, reconciliation shall require a complete durable
 physical receipt, or the complete cumulative logical receipt of a deferred
@@ -1344,7 +1387,8 @@ Two default adjudication strategies, in selection order:
   answer keyed to exactly one of the declared guards: a nongoverned player uses
   `{ guard, …structuralPayloadFields }`, while a governed schema-3 player uses
   `{ guard, …semanticOwnedPayloadFields }` and explicitly forbids every other
-  payload field. Both forms exclude the runtime-injected direct-Captain
+  payload field. The governed form also permits the blocked report above when no outcome matches.
+  Both forms exclude the runtime-injected direct-Captain
   `question` and `response` fields above. The prompt shall identify hidden control work,
   prohibit tool use, file inspection, and external evidence, direct the judge
   to decide only from the supplied actor output and declared outcomes, and
@@ -1875,7 +1919,8 @@ rehydrate it in a later process (DR-014). A runtime that implements either
 member shall implement both. When generated for a runtime whose host needs
 durability, the pair shall behave as follows.
 
-`exportSnapshot()` shall return `undefined` unless the runtime is at a safe
+A shared runtime may also receive the internal step-start snapshot for its current invocation or `exportSnapshot({child})` for a bridge-owned child during startup; these capture stopped positions without execution.
+Ordinary `exportSnapshot()` shall return `undefined` unless the runtime is at a safe
 capture point: initialized, not disposing or disposed, no active
 `handleBossInput`/`resumePlaybookCall` boundary, and the root actor at a
 quiescent state with actor status `active`.
@@ -1960,9 +2005,11 @@ A linked runtime may implement the optional adoption capability of
 initialization path distinct from `init` and same-engagement `restore`.
 Adoption may bind a retained generation to a fresh valid `PlaybookSession`
 identity. Every runtime the shared `createXStatePlaybookRuntime` factory
-constructs implements `adopt`, regardless of whether the artifact supplies
-retained-generation classification metadata; a bespoke runtime may omit it,
-and hosts feature-detect the capability by member presence.
+constructs for a flat machine implements `adopt`, regardless of whether the
+artifact supplies retained-generation classification metadata; one it
+constructs for a machine that declares a parallel state omits it, as linked
+machinery of an artifact's own may, and hosts feature-detect the capability
+by member presence.
 
 Before actor construction or any player-session-store, port, trace, status,
 or telemetry effect, `adopt` shall validate and detach the target session, the
@@ -2053,9 +2100,9 @@ and detached from that declaration. Absence means the runtime contributes no
 retained generation; presence supplies only terminal classification metadata
 and does not itself supply the adoption operation.
 Every runtime the shared `createXStatePlaybookRuntime` factory constructs from
-a supplied `unfinishedFinalStateIds` spec member shall expose the marker; a
-bespoke runtime opts into classification only by implementing the public member
-itself.
+a supplied `unfinishedFinalStateIds` spec member shall expose the marker;
+linked machinery of an artifact's own opts into classification only by
+implementing the public member itself.
 
 ## Control surface (optional)
 
@@ -2082,6 +2129,14 @@ interface PlaybookControlAction {
   reason?: PlaybookControlActionReason;   // why it is not `ready`
 }
 
+interface PlaybookRecoveryOffer {
+  prompt: string;
+  description?: string;
+  preparation?: string;
+  evidence?: JsonValue;
+  continuation: { kind: 'reply' } | { kind: 'runtime'; actionId: string };
+}
+
 interface PlaybookControlView {
   state: PlaybookState;
   stateDescription?: string;  // runtime-published meaning of the current state
@@ -2089,12 +2144,13 @@ interface PlaybookControlView {
   pendingQuestions: readonly PlaybookPendingBossQuestion[];
   lastError?: NormalizedError;
   actions: readonly PlaybookControlAction[];
+  recovery?: PlaybookRecoveryOffer;
 }
 
 type PlaybookControlReceipt =
   | { disposition: 'rejected'; reason: string }          // before any effect
   | { disposition: 'executed'; run: PlaybookRunResult }
-  | { disposition: 'failed'; error: NormalizedError };   // effects may exist
+  | { disposition: 'failed'; error: NormalizedError; run?: PlaybookRunResult };   // effects may exist
 
 // Optional PlaybookRuntime members — both or neither:
 describe?(): PlaybookControlView;
@@ -2115,6 +2171,7 @@ throw. The view carries the current normalized state descriptor, the state
 description defined below, the authored context projection defined below, the
 pending Boss questions with their stable ids, the last recorded error in
 normalized form, and the currently valid actions.
+The shared runtime owns the optional recovery context and invocation checkpoint; linked artifacts need no recovery-specific source, event, or actor.
 
 `stateDescription` is the runtime's own Boss-facing statement of what its
 current state means, taken from the same source state descriptions the action
@@ -2167,25 +2224,17 @@ parked-session snapshot uses (actor status `active`, quiescent, no pending
 nested call); anywhere else `actions` is empty while the rest of the view
 still describes the state.
 While effect-possible outcome evidence remains unresolved, the view shall omit its pending Boss questions and state description and shall replace every ordinary action with exactly `reconcile:unresolved-effect` labeled `Retry unresolved effect reconciliation` and `abandon:unresolved-effect` labeled `Abandon unresolved workflow attempt`.
-Otherwise two ordinary families exist, labeled from source state descriptions:
-
-- **Failure-state retry** — while the singular state id is the recoverable
-  failure state and the live snapshot accepts the retry event sourced below,
-  the runtime shall advertise `retry:<EVENT_TYPE>` replaying exactly that
-  event. Where the emitted module's entry-event declaration names the FSM
-  context member the machine's entry action copies the exact Boss text into
-  (DR-034), the retry event is that deterministic entry event built from the
-  live snapshot's member — excluded when the member is absent, not a string,
-  or blank, and never falling back to the record. Where it names no member,
-  the retry event is the recorded last classified event (the event a public
-  Boss boundary sent that drove the run into `failed`, kept with its recorded
-  payload), and there is none while the runtime holds none. The member is
-  declared, never inferred from a context member that happens to match the
-  entry event's text field.
+A valid invocation checkpoint is the only source of a retry: it retries only the stopped invocation after its effect checks, using `retry:<EVENT_TYPE>` for the same entry target or `retry:step` otherwise.
+Saved-result assessment (`retry:adjudication`) never repeats the player and is not offered for an output the machine has already received (checkpoint `delivered: true`), and verified read-only restoration (`retry:restored-step`) records an exact baseline check before replay.
+These retries have standing `ready`; an unsafe checkpoint grants no replay. Saved-result assessment withholds ordinary state jumps. Reconciliation and abandonment remain available whenever effects are unresolved, even alongside an eligible assessment or restoration.
+Ordinary retry and jump actions use source state descriptions and require assessment and unresolved-effect fences to be absent:
+
+- **Failure-state retry** — a valid invocation checkpoint retries that step only; a completed saved result is consumed without executing the operation again. No checkpoint means no retry. Legacy `entryEvent.contextField` metadata is ignored.
 - **Jump entries** — for each registered resumable state id whose
   explicit-state-jump event (`BOSS_INTERRUPT` with that `targetId`, optional
   textual fields omitted) the live snapshot accepts, guards included, the
-  runtime shall advertise `jump:<stateId>`.
+  runtime shall advertise `jump:<stateId>`, except that a jump out of a governed
+  failure must also pass the full failed-attempt effect check above.
 
 A candidate whose event requires a payload the runtime cannot source from
 recorded state shall be excluded from `actions` — `apply` never invents free
@@ -2195,9 +2244,8 @@ back to a target id or to the replayed event type, because a controller host
 names an executed or refused action by its label and never by its id, so an
 identifier used as a label defeats that substitution. A jump whose target
 publishes no description is therefore not advertised — borrowing another
-state's description would name the wrong state — and a retry falls back from
-its target's description to its own source state's, and is not advertised when
-neither exists.
+state's description would name the wrong state — and a retry requires the
+interrupted invocation's source description.
 
 `apply({ actionId, key, signal })` shall revalidate the action against the
 live state and settle `{ disposition: 'rejected', reason }` with no effect
@@ -2213,7 +2261,7 @@ pair, and may execute once the action is advertised — and a key whose call
 threw before reaching acceptance (lifecycle misuse, invalid input, a
 pre-acceptance abort, a rejected start-boundary sink) likewise records
 nothing, so a later call with that key may execute.
-Executing an ordinary retry or jump sends the validated event through the same actor drive as `handleBossInput` — state
+Executing a jump sends the validated event through the same actor drive as `handleBossInput` — state
 transitions, player/judge boundaries, statuses, and traces flow unchanged —
 and settles `executed` with the projected run result, or `failed` with the
 normalized error when the run settles in the failure state, aborts, or a
@@ -2246,12 +2294,18 @@ signal's own abort reason, in which case it evidences the cancellation and is
 dropped, not latched
 ([DR-036](../specs/decisions/036-coherent-abort-settlement.md)).
 
-The recorded receipts and the recorded last classified event are
-process-local: the durable runtime snapshot persists neither. A restored
-runtime therefore advertises the retry of a declared entry-event source
-immediately — that payload rides the persisted machine snapshot — while a
-module declaring no source advertises a retry again only after its next
-classified event.
+Recorded control receipts are process-local. Invocation checkpoints retain the original input and accepted output across restoration; a restored runtime offers only the currently valid step controls.
+
+The optional `PlaybookPorts.recordStep(step, position?)` lets a durable host save ordinary work without understanding machine internals.
+The shared runtime records player, direct-Captain and script starts before execution and their actor results before advancing.
+The runtime owns the complete stopped position, including accepted Boss input; the host joins nested frames and atomically stores starts and results; retention changes wait for settlement.
+An invocation inside a parallel region records its start and result without a single-invocation recovery position, including when only its last region is resuming.
+Sequential invocations after the join use ordinary checkpoints.
+A custom runtime that cannot provide a position remains runnable, but a crash without a supported position returns to Captain with recorded work preserved.
+Automatic recovery requires a failed or quiescent outcome produced by an operation in the same turn; resuming or adopting an older stop starts no preparation.
+The store identifies the step that owns a saved position, so a consumed result cannot be attached to a later stopped snapshot.
+Only internal step-start capture creates a synthetic failed position; public snapshot capture returns the actual stopped state.
+Opening or reporting an interrupted run executes no work; Boss chooses the next action after checking outside effects and stopping any surviving worker.
 
 ## Abort
 
@@ -2360,6 +2414,10 @@ The runtime shall emit, at minimum:
   semantics matter to Boss — e.g., `respondToReview`, `failed`). The
   default is to emit on every transition and let the host filter; hosts
   may bind a stricter rule.
+  Mark both a player-question status and its waiting marker with status data
+  `{ kind: "boss-question" }`; the session Captain replaces those statuses with
+  its own clear reply, using the complete pending question from the control view.
+  Keep the original question in state and telemetry, and deliver Boss input unchanged.
 - One `emitTelemetry` per state transition under a namespaced topic
   (recommended `playbook.fsm.state`), with structured `from`, `to`, `event`,
   `previousState`, and `state` fields. Descriptors carry the JSON-safe XState
@@ -2387,14 +2445,19 @@ Every linked artifact shall emit an `unfinishedFinalStateIds` set beside its res
 The set shall contain exactly the stable ids of root `type: 'final'` states whose terminal outcomes leave the procedure unfinished, and shall be explicitly empty when no terminal outcome does.
 The linker shall not infer the set from a state description, opaque output, or procedure prose.
 The linker shall reject a declared id that does not name a root final state, and the shared factory shall independently reject it at construction before runtime effects.
-For a factory-backed artifact the set is a `spec` member; a bespoke artifact shall retain equivalent linked metadata, and the artifact declaration is not itself the public runtime retention marker or an adoption capability.
-For an FSM that declares no `type: 'parallel'` state — necessarily flat
-under [gears2fsm.md](gears2fsm.md)'s one-state-per-item mapping — it shall
+For a factory-backed artifact the set is a `spec` member; linked machinery of an artifact's own shall retain equivalent linked metadata, and the artifact declaration is not itself the public runtime retention marker or an adoption capability.
+For every FSM [gears2fsm.md](gears2fsm.md) produces — flat under its
+one-state-per-item mapping, or carrying root parallel groups of its
+[Parallel groups](gears2fsm.md#parallel-groups) shape — the linker shall
 emit the thin shared-factory module defined below.
-For an FSM that declares a parallel state, it shall emit bespoke linked
-machinery satisfying this document's runtime contract and shall not invoke
-`createXStatePlaybookRuntime`, whose supported domain is flat single-region
-FSMs under [DR-019](../specs/decisions/019-shared-linked-runtime-factory.md).
+The shared factory interprets such a parallel group through its parallel
+profile under [DR-067](../specs/decisions/067-parallel-proposals-through-the-shared-factory.md), deriving the regions, their leaves, and the
+cohort of working leaves from the FSM and its exported `concurrentRoleSets`,
+so the emitted module declares nothing further for it; bespoke linked
+machinery is no longer the prescribed output for any such FSM.
+Linked machinery of an artifact's own that satisfies this document's runtime
+contract remains a valid implementation for an artifact outside this package
+and declares the `bespoke` registry profile below, so hosts keep accepting it.
 The FSM-interpreter machinery — actor wiring, boundary tracing, Boss-event
 mapping, adjudication, script execution, nested-playbook bridging, session
 lifecycle, abort handling, and the optional parked-session snapshot and
@@ -2510,8 +2573,9 @@ The thin emitted module:
   error.
   `NO_ACTION` and `BOSS_REPLY` are runtime-owned event types the factory
   supplies itself — `NO_ACTION` as exactly `{ type: 'NO_ACTION' }`, and
-  `BOSS_REPLY` as an optional judge-selected `questionId` plus the exact-text
-  `answer` the runtime attaches. `bossEvents` shall carry no entry for either
+  `BOSS_REPLY` as a judge-selected `questionId` — optional while one question
+  is pending and required, from the pending ids, while several are — plus the
+  exact-text `answer` the runtime attaches. `bossEvents` shall carry no entry for either
   type; supplying one is a construction error, so a linker that judges a
   runtime-owned arm to have lost payload detail under erasure shall report
   that gap rather than emit the entry.
@@ -2553,8 +2617,11 @@ The thin emitted module:
   host-construction boundary's setup diagnostic.
 - Exposes, under an `_internal` export, the pure helpers verification
   needs — at least the prompt composers its own machine uses, which may
-  re-export the shared defaults when the spec does not override composition —
-  so compilation-correctness tests can exercise composition without a host.
+  re-export the shared defaults when the spec does not override composition,
+  and the `VERBATIM_PAYLOAD_FIELDS` and `UNFINISHED_FINAL_STATE_IDS` sets the
+  spec declares, which the linked-ownership check reads back — so
+  compilation-correctness tests can exercise composition and ownership
+  without a host.
   A playbook that calls players exposes `composePlayerPrompt`; a playbook
   whose states make direct-Captain calls exposes `composeCaptainPrompt`. A
   controller playbook that calls no players exposes no player composer: