@sublang/playbook 15.0.0 → 15.1.0

package/README.md

@@ -107,7 +107,7 @@ SLC's `playbook` pipeline has three phases:
 2. **GEARS → FSM** ([slc/gears2fsm.md](slc/gears2fsm.md)) — maps each item to an XState state that invokes the Captain, a player, another playbook, or a local script.
 3. **FSM → runtime** ([slc/link.md](slc/link.md)) — links the machine to a host-independent interface for user input, agent calls, status, and telemetry.
 
-The default [optimization pass](slc/optimize.md) replaces eligible mechanical steps with local shell scripts; `--no-optimize` skips it.
+The default passes run between the first two phases: the [optimization pass](slc/optimize.md) replaces eligible mechanical steps with local shell scripts, and the [prompt-prefix pass](slc/prefix.md) moves each prompt's relayed runtime values after its instructions so repeated runs share a cacheable prompt prefix; `--no-optimize` skips both.
 Inspect the complete [Captain](reference/sdlc/captain.md), [CODE](reference/sdlc/code.md), [REVIEW](reference/sdlc/review.md), and [DECIDE](reference/sdlc/decide.md) examples.
 
 ## Contributing

package/docs/embedding.md

@@ -445,21 +445,23 @@ const url = import.meta.resolve('@sublang/playbook/slc/link.md');
 const link = await readFile(fileURLToPath(url), 'utf8');
 ```
 
-The four specs are [`slc/text2gears.md`](../slc/text2gears.md),
+The five specs are [`slc/text2gears.md`](../slc/text2gears.md),
 [`slc/gears2fsm.md`](../slc/gears2fsm.md),
 [`slc/link.md`](../slc/link.md) — the FSM-to-runtime contract that
-`@sublang/playbook/runtime` projects into TypeScript — and
-[`slc/optimize.md`](../slc/optimize.md).
+`@sublang/playbook/runtime` projects into TypeScript —
+[`slc/optimize.md`](../slc/optimize.md), and
+[`slc/prefix.md`](../slc/prefix.md).
 
-Five supporting assets use the same resolution mechanism:
+Six supporting assets use the same resolution mechanism:
 
 | Asset | Purpose |
 | --- | --- |
 | [`slc/workflow-contracts.json`](../slc/workflow-contracts.json) | Public output schemas and default literal target bindings for the builtin REVIEW, DECIDE, CODE, BRANCH, and PR workflows; compilers and embedders can read them without importing workflow implementations. |
 | [`slc/materialize-link.mjs`](../slc/materialize-link.mjs) | Optional CLI that emits a thin linked module from a supported FSM and JSON descriptor; see the profiles and invocation in `slc/link.md`. |
 | [`slc/scaffold-fsm.mjs`](../slc/scaffold-fsm.mjs) | Optional CLI that initializes an incomplete typed FSM from supported GEARS source. |
+| [`slc/prefix-prompts.mjs`](../slc/prefix-prompts.mjs) | CLI that performs the prompt-prefix pass's rewrite of a GEARS package exactly; see the invocation in `slc/prefix.md`. |
 | [`slc/experiments/fsm-scaffold-guidance.md`](../slc/experiments/fsm-scaffold-guidance.md) | Opt-in compiler guidance for the initializer, outside ordinary phase discovery. |
-| [`slc/slc.pin-inputs.json`](../slc/slc.pin-inputs.json) | SLC semantic-input closures for `gears2fsm` and `link`, including the workflow catalog and, for `link`, the materializer. Other phases use SLC's inline-input discovery. |
+| [`slc/slc.pin-inputs.json`](../slc/slc.pin-inputs.json) | SLC semantic-input closures for `gears2fsm`, `prefix`, and `link`, including the workflow catalog, the prefix tool, and, for `link`, the materializer. Other phases use SLC's inline-input discovery. |
 
 For example, resolve `@sublang/playbook/slc/workflow-contracts.json`, read it
 with `readFile`, and parse the result as JSON to inspect the published workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "15.0.0",
+  "version": "15.1.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -46,6 +46,8 @@
     "slc/gears2fsm.md",
     "slc/text2gears.md",
     "slc/optimize.md",
+    "slc/prefix.md",
+    "slc/prefix-prompts.mjs",
     "reference/sdlc/captain.md",
     "reference/sdlc/code.md",
     "reference/sdlc/review.md",

package/reference/sdlc/code.playbook/bin/repository-effects.js

@@ -520,8 +520,6 @@ function projectionText(projection) {
   return JSON.stringify(projection);
 }
 
-const MISSING_CONTENT_IDENTITY = Object.freeze({ kind: 'missing' });
-
 function hasPath(projection, path) {
   return Object.prototype.hasOwnProperty.call(projection, path);
 }
@@ -555,9 +553,9 @@ function sameTreeEntry(left, right) {
   return left.mode === right.mode && left.oid === right.oid;
 }
 
-// The baseline recorded nothing at the path: a deleted worktree entry, or a
+// The entry records nothing at the path: a deleted worktree entry, or a
 // staged deletion whose index holds no object.
-function baselineEntryIsDeletion(entry) {
+function entryIsDeletion(entry) {
   return entry.worktree === undefined
     ? entry.indexMode === '000000'
     : entry.worktree.kind === 'missing';
@@ -615,14 +613,57 @@ function sameContentIdentity(left, right) {
   );
 }
 
+// A worktree deletion loses the Boss's content only when neither the after
+// index nor the after HEAD tree holds it; content the after HEAD cannot
+// produce fails closed as lost.
+async function deletionRetainsContent(baseline, after, path, entry, afterEntry) {
+  try {
+    const baselineIdentity = await baselineContentIdentity(after.worktree, entry);
+    if (
+      afterEntry.kind === 'ordinary' &&
+      afterEntry.indexMode !== undefined &&
+      afterEntry.indexMode !== '000000'
+    ) {
+      const indexIdentity = await blobContentIdentity(
+        after.worktree,
+        afterEntry.indexMode,
+        afterEntry.indexOid,
+      );
+      if (sameContentIdentity(baselineIdentity, indexIdentity)) return true;
+    }
+    if (baseline.head === after.head) return false;
+    const treeEntry = await afterTreeEntry(after.worktree, after.head, path);
+    if (treeEntry === undefined || treeEntry.mode === '160000') return false;
+    const treeIdentity = await blobContentIdentity(
+      after.worktree,
+      treeEntry.mode,
+      treeEntry.oid,
+    );
+    return sameContentIdentity(baselineIdentity, treeIdentity);
+  } catch {
+    return false;
+  }
+}
+
 // DR-062 §1: the fate of one baseline projection entry at the end of a
 // governed call — `preserved`, `altered-uncommitted`, `altered-committed`,
-// `absorbed`, or `lost`.
+// `absorbed`, or `lost`. Loss is decided before alteration: a kind that
+// admits no content matching, a worktree deletion whose content survives in
+// neither the index nor the new HEAD, and a commit that dropped the path all
+// leave the Boss's content nowhere.
 async function baselineEntryFate(baseline, after, path, entry) {
   if (hasPath(after.projection, path)) {
-    return JSON.stringify(after.projection[path]) === JSON.stringify(entry)
-      ? 'preserved'
-      : 'altered-uncommitted';
+    const afterEntry = after.projection[path];
+    if (JSON.stringify(afterEntry) === JSON.stringify(entry)) {
+      return 'preserved';
+    }
+    if (nonComparableBaselineEntry(entry)) return 'lost';
+    if (entryIsDeletion(afterEntry) && !entryIsDeletion(entry)) {
+      return (await deletionRetainsContent(baseline, after, path, entry, afterEntry))
+        ? 'altered-uncommitted'
+        : 'lost';
+    }
+    return 'altered-uncommitted';
   }
   // The entry left the working tree, so only a commit this call made can hold
   // the Boss's content; a call that moved no HEAD made none.
@@ -635,15 +676,15 @@ async function baselineEntryFate(baseline, after, path, entry) {
       // carried no change of the Boss's and his content is nowhere.
       return 'lost';
     }
-    if (baselineEntryIsDeletion(entry)) {
+    if (entryIsDeletion(entry)) {
       return treeEntry === undefined ? 'absorbed' : 'lost';
     }
-    if (treeEntry?.mode === '160000') return 'lost';
+    // A commit that dropped the path, or replaced it with a gitlink, carries
+    // no content of the Boss's to compare.
+    if (treeEntry === undefined || treeEntry.mode === '160000') return 'lost';
     const [baselineIdentity, treeIdentity] = await Promise.all([
       baselineContentIdentity(after.worktree, entry),
-      treeEntry === undefined
-        ? MISSING_CONTENT_IDENTITY
-        : blobContentIdentity(after.worktree, treeEntry.mode, treeEntry.oid),
+      blobContentIdentity(after.worktree, treeEntry.mode, treeEntry.oid),
     ]);
     return sameContentIdentity(baselineIdentity, treeIdentity)
       ? 'absorbed'

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

@@ -1,3 +1,4 @@
+import { normalizeErrorCompact, normalizeErrorFull } from '../../../src/xstate-runtime.js';
 import { type PlayerInput, type DecideEvent, type DecideInput, type PendingBossQuestion } from './decide.fsm.js';
 import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlayerResult, PlayerSessionStore, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlAction, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType } from '@sublang/playbook/runtime';
@@ -25,15 +26,6 @@ declare function buildAdjudicatorPrompt(input: PlayerInput, playerOutput: string
     readonly error: string;
 }): string;
 declare function combineSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal;
-declare function normalizeErrorCompact(err: unknown): {
-    name: string;
-    message: string;
-} | undefined;
-declare function normalizeErrorFull(err: unknown): {
-    name: string;
-    message: string;
-    stack?: string;
-} | undefined;
 declare function pendingQuestionsFromContext(context: Record<string, unknown>): PendingBossQuestion[];
 declare function pendingQuestionsForState(state: PlaybookState, context: Record<string, unknown>): PendingBossQuestion[];
 export declare const createPlaybookRuntime: PlaybookRuntimeFactory<DecidePlaybookRuntimeConstruction>;

package/reference/sdlc/decide.playbook/decide.playbook.js

@@ -19,7 +19,7 @@ import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
 import { createActor, fromPromise } from 'xstate';
 import { createAcceptedOutcomeConsumer, } from '../../../src/accepted-outcome.js';
-import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, composePlayerContinuation, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, terminalOutcomesFromMachine, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
+import { ABORTED_FAILURE_CAUSE, assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, attachPlaybookFailureCause, combineAbortSignals, composePlayerContinuation, createFailureCauseRetention, createNestedPlaybookBridge, detachPersistedMachineSnapshot, effectAuthorizedPreExistingBlock, governedSettlementCause, normalizeError, normalizeErrorCompact, normalizeErrorFull, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, playerFailureCause, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, runtimeDefectCause, snapshotJsonValue, snapshotPlaybookSession, terminalOutcomesFromMachine, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
 import decideMachine from './decide.fsm.js';
 function snapshotDecideRuntimeOptions(value) {
     const captured = snapshotJsonValue(value, 'DECIDE runtime options');
@@ -453,15 +453,6 @@ function parseGovernedSemanticCandidate(raw) {
 function combineSignals(a, b) {
     return combineAbortSignals(a, b);
 }
-function normalizeErrorCompact(err) {
-    if (err === undefined || err === null)
-        return undefined;
-    const normalized = normalizeError(err);
-    return { name: normalized.name, message: normalized.message };
-}
-function normalizeErrorFull(err) {
-    return err === undefined || err === null ? undefined : normalizeError(err);
-}
 // DR-028's unified empty predicate: a missing, empty, or whitespace-only
 // `finalText` on an `ok` player result is the one shape that earns exactly
 // one corrective re-ask before the existing failure path applies. Mirrors
@@ -691,7 +682,7 @@ function normalizedTransitionEvent(event) {
     }
     return snapshotJsonValue(descriptor, 'FSM event');
 }
-function telemetryPayload(previousState, state, event, context, hiddenQuestionId) {
+function telemetryPayload(previousState, state, event, context, hiddenQuestionId, failedError) {
     const pendingBossQuestions = pendingQuestionsForState(state, context).filter(({ questionId }) => questionId !== hiddenQuestionId);
     const prior = previousState ?? state;
     const payload = {
@@ -702,7 +693,7 @@ function telemetryPayload(previousState, state, event, context, hiddenQuestionId
         state,
         ...(pendingBossQuestions.length > 0 ? { pendingBossQuestions } : {}),
         ...(state.activeStateIds.includes('failed')
-            ? { lastError: normalizeErrorFull(context.lastError) ?? null }
+            ? { lastError: failedError ?? normalizeErrorFull(context.lastError) ?? null }
             : {}),
     };
     assertJsonSafe(payload);
@@ -751,6 +742,59 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
     const semanticCompletionQueue = new PQueue({ concurrency: 1 });
     const governedOutputsByBoundaryId = new Map();
     const governedFailuresByBoundaryId = new Map();
+    // 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 (mirrors the shared
+    // factory).
+    const failureCauses = createFailureCauseRetention();
+    let failureSequence = 0;
+    const playerCallFailures = new Map();
+    const governedFailureOccurrences = new Map();
+    const recordFailure = (occurrences, key, cause) => {
+        occurrences.set(key, { cause, sequence: ++failureSequence });
+    };
+    const failedStateError = (context) => {
+        const normalized = normalizeErrorFull(context.lastError);
+        if (normalized === undefined || normalized.cause !== undefined) {
+            return normalized;
+        }
+        return {
+            ...normalized,
+            cause: failureCauses.causeOf(context.lastError) ??
+                runtimeDefectCause(normalized.message),
+        };
+    };
+    const playerResultFailureCause = (roleId, playerId, result) => result.status === 'aborted'
+        ? ABORTED_FAILURE_CAUSE
+        : playerFailureCause({
+            roleId,
+            ...(playerId === undefined ? {} : { playerId }),
+            error: result.error ??
+                `callPlayer status ${JSON.stringify(result.status)}`,
+        });
+    // A rejected player port or a result the runtime cannot read is a
+    // `player-failed` failure named by role; the turn's own abort is `aborted`.
+    // A cancellation the runtime itself issued — a proposal cancelled because
+    // its sibling failed — is not this player's failure and decides nothing, so
+    // the originator's cause stands; every other failure is decided afresh and
+    // recorded as this call's occurrence, whatever an earlier failure threw.
+    const decidePlayerCallFailure = (error, roleId, playerId, signal, callId) => {
+        const turn = currentSignal;
+        const turnAborted = turn !== undefined && turn.aborted;
+        if (!turnAborted && signal.aborted)
+            return;
+        const cause = turn !== undefined && turn.aborted && Object.is(error, turn.reason)
+            ? ABORTED_FAILURE_CAUSE
+            : playerFailureCause({
+                roleId,
+                ...(playerId === undefined ? {} : { playerId }),
+                error,
+            });
+        attachPlaybookFailureCause(error, cause);
+        failureCauses.retain(error, cause);
+        recordFailure(playerCallFailures, callId, cause);
+    };
     const governedEvidenceByBoundaryId = new Map();
     const governedReceiptsByBoundaryId = new Map();
     const governedPlayerOutputs = new WeakMap();
@@ -1325,7 +1369,12 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
         const roleId = input.role;
         const playerId = resolvedPlayerId(roleId);
         const playerKey = continuationKey(roleId, playerId);
-        const freshPrompt = composeInvocationPrompt(input);
+        // DR-062 §4: composed from this call's own baseline observation, so the
+        // prompt the trace records is the prompt the player is sent.
+        const withPreExisting = (text) => continuation?.preExistingBlock === undefined
+            ? text
+            : `${text}\n\n${continuation.preExistingBlock}`;
+        const freshPrompt = withPreExisting(composeInvocationPrompt(input));
         let resume;
         try {
             signal.throwIfAborted();
@@ -1339,7 +1388,9 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             latchControlPlaneError(error, signal);
             throw error;
         }
-        const prompt = resume === false ? freshPrompt : composeInvocationPrompt(input, true);
+        const prompt = resume === false
+            ? freshPrompt
+            : withPreExisting(composeInvocationPrompt(input, true));
         const callId = continuation?.callId ?? `player-${++playerCallSequence}`;
         const identity = {
             stateId: input.stateId,
@@ -1382,6 +1433,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                 // A rejected call produced no authoritative result, so the previous
                 // token remains untouched. This also covers a coder promise that
                 // resolves after its invocation signal was cancelled.
+                decidePlayerCallFailure(error, roleId, playerId, signal, callId);
                 latchControlPlaneError(error, signal);
                 try {
                     await emitFailure(error);
@@ -1396,6 +1448,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                 result = validatePlayerResult(rawResult);
             }
             catch (error) {
+                decidePlayerCallFailure(error, roleId, playerId, signal, callId);
                 latchControlPlaneError(error, signal);
                 try {
                     await emitFailure(error);
@@ -1468,10 +1521,22 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             correctionBudget: { limit: 1, spent: false },
         };
     };
-    const unresolvedGovernedEvidence = (boundaryId, reason, error) => {
-        governedFailuresByBoundaryId.set(boundaryId, error instanceof Error
+    // DR-063 §1/§2: the cause of an unresolved governed settlement is decided
+    // here — a reconciled mismatch supplies its receipt-read cause, an abort or
+    // a refused adjudication its own code, anything else a runtime defect — and
+    // rides the failure the boundary throws.
+    const unresolvedGovernedEvidence = (boundaryId, reason, error, cause) => {
+        const aborted = error !== undefined &&
+            currentSignal?.aborted === true &&
+            Object.is(error, currentSignal.reason);
+        const decided = governedSettlementCause(reason, error, aborted, cause);
+        const failure = error instanceof Error
             ? error
-            : new Error(`DECIDE governed outcome remains unresolved: ${reason}`));
+            : new Error(`DECIDE governed outcome remains unresolved: ${reason}`);
+        attachPlaybookFailureCause(failure, decided);
+        failureCauses.retain(failure, decided);
+        recordFailure(governedFailureOccurrences, boundaryId, decided);
+        governedFailuresByBoundaryId.set(boundaryId, failure);
     };
     const spendSemanticCorrectionBudget = async (boundary, receipt, finalText, semanticCandidate) => {
         const ledger = readEffectLedger();
@@ -1700,7 +1765,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                 semanticCandidate,
             });
             if (reconciliation.status === 'unresolved') {
-                unresolvedGovernedEvidence(boundary.boundaryId, reconciliation.reason);
+                unresolvedGovernedEvidence(boundary.boundaryId, reconciliation.reason, undefined, reconciliation.cause);
                 return { finalText, semanticCandidate, unresolved: true };
             }
             const output = reconciliation.output;
@@ -1861,7 +1926,14 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                         member.envelope = envelope;
                         if (envelope.result.status !== 'ok' &&
                             !cohortOperations.signal.aborted) {
-                            cohortOperations.abort(new Error(`DECIDE proposal cohort ${roleId} returned status ${JSON.stringify(envelope.result.status)}`));
+                            // DR-063 §2: the cancellation carries the cause of the result
+                            // that caused it, recorded as this member's occurrence, so the
+                            // cohort fails for this member.
+                            const cause = playerResultFailureCause(roleId, resolvedPlayerId(roleId), envelope.result);
+                            const cancellation = attachPlaybookFailureCause(new Error(`DECIDE proposal cohort ${roleId} returned status ${JSON.stringify(envelope.result.status)}`), cause);
+                            failureCauses.retain(cancellation, cause);
+                            recordFailure(playerCallFailures, member.callId, cause);
+                            cohortOperations.abort(cancellation);
                         }
                         return envelope.result;
                     }
@@ -1928,9 +2000,38 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                 for (const result of acknowledgedResults.values()) {
                     governedPlayerOutputs.delete(result);
                 }
-                throw acknowledgementFailures.length === 1
+                const failure = acknowledgementFailures.length === 1
                     ? acknowledgementFailures[0]
                     : new AggregateError(acknowledgementFailures, 'DECIDE proposal cohort reconciliation failed');
+                // DR-063 §2: a cohort fails for the member whose failure was decided
+                // first — a rejected or non-`ok` player call, a refused adjudication,
+                // a mismatched receipt — in decision order, not in the order the
+                // players finished or the values they threw. That cause rides every
+                // error the failure can surface as: the cancellation, each member's
+                // own rejection, and the aggregate of both, never an abort.
+                const origin = cohortOperations.signal.aborted
+                    ? cohortOperations.signal.reason
+                    : undefined;
+                const first = ROLE_IDS.flatMap((roleId) => {
+                    const member = members[roleId];
+                    const occurrence = member === undefined
+                        ? undefined
+                        : (playerCallFailures.get(member.callId) ??
+                            governedFailureOccurrences.get(member.effectBoundary.boundaryId));
+                    return occurrence === undefined ? [] : [occurrence];
+                }).sort((left, right) => left.sequence - right.sequence)[0];
+                const originCause = first?.cause ??
+                    failureCauses.causeOf(failure) ??
+                    (origin === undefined ? undefined : failureCauses.causeOf(origin));
+                if (originCause !== undefined) {
+                    for (const candidate of [failure, origin, ...acknowledgementFailures]) {
+                        if (candidate === undefined)
+                            continue;
+                        attachPlaybookFailureCause(candidate, originCause);
+                        failureCauses.retain(candidate, originCause);
+                    }
+                }
+                throw failure;
             }
             for (const roleId of releaseOrder) {
                 const member = members[roleId];
@@ -1993,6 +2094,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                     const envelope = await runPlayerCall(input, signal, {
                         callId: active.effectBoundary.callId,
                         resume: active.playerContinuation,
+                        preExistingBlock: effectAuthorizedPreExistingBlock(active.effectBoundary, active.baseline),
                     });
                     active.result.resolve(envelope.result);
                     const acknowledgedResult = await active.acknowledged.promise;
@@ -2018,8 +2120,13 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             const settled = await deferredEffects.repository.runExclusive({
                 signal,
                 effectBoundary,
-                operation: async () => {
-                    envelope = await runPlayerCall(input, signal, { callId });
+                // DR-062 §4: the call's own baseline, supplied by the host that
+                // captured it under this exclusive claim.
+                operation: async (context) => {
+                    envelope = await runPlayerCall(input, signal, {
+                        callId,
+                        preExistingBlock: effectAuthorizedPreExistingBlock(effectBoundary, context?.baseline),
+                    });
                     return envelope.result;
                 },
                 completeEffectBoundary: completionEvidenceFor(input, input.role, resolvedPlayerId(input.role), signal),
@@ -2064,7 +2171,10 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                 ({ roleId, playerId, callId, result } = await callPlayer(input, combined));
             }
             if (result.status !== 'ok') {
-                throw new Error(`${roleLabel(roleId)}${playerId === undefined ? '' : ` (${playerId})`} returned status "${result.status}"${result.error ? `: ${result.error}` : ''}`);
+                // DR-063 §2: the failure Error built for a non-`ok` result carries
+                // the cause decided for that exact result.
+                const cause = playerResultFailureCause(roleId, playerId, result);
+                throw attachPlaybookFailureCause(new Error(`${roleLabel(roleId)}${playerId === undefined ? '' : ` (${playerId})`} returned status "${result.status}"${result.error ? `: ${result.error}` : ''}`), cause);
             }
             const finalText = result.finalText ?? '';
             if (isEmptyFinalText(finalText)) {
@@ -2181,7 +2291,9 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             const context = snapshot.context;
             const fsmPayload = telemetryPayload(prior, state, event.event, context, hiddenDeferredOperationId === undefined
                 ? undefined
-                : 'commitCoderProposal');
+                : 'commitCoderProposal', state.activeStateIds.includes('failed')
+                ? failedStateError(context)
+                : undefined);
             const describedFsmPayload = snapshotJsonValue(fsmPayload, 'described FSM telemetry');
             void enqueueTracedEmission('fsm.transition', fsmPayload, { turnId: currentTurnId }, (emissionPorts) => emissionPorts.emitTelemetry({
                 topic: TELEMETRY_TOPIC,
@@ -2218,7 +2330,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                     continue;
                 }
                 const lastError = activeStateId === 'failed'
-                    ? normalizeErrorCompact(context.lastError)
+                    ? normalizeErrorCompact(failedStateError(context))
                     : undefined;
                 const description = STATE_DESCRIPTIONS[activeStateId];
                 if (description === undefined)
@@ -2226,7 +2338,9 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                 const roleState = ROLE_STATES.find((candidate) => candidate.stateId === activeStateId);
                 scheduleStatus(roleState === undefined
                     ? '◆ workflow failed; awaiting Boss recovery.'
-                    : `⤷ ${roleLabel(roleState.role)}: ${description}`, activeStateId, lastError === undefined ? undefined : { lastError });
+                    : `⤷ ${roleLabel(roleState.role)}: ${description}`, activeStateId, lastError === undefined
+                    ? undefined
+                    : snapshotJsonValue({ lastError }, 'DECIDE failed status data'));
             }
         }
         catch (error) {
@@ -2357,13 +2471,15 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             signal,
             operationId,
             effectBoundary,
-            operation: async ({ playerContinuation }) => {
+            operation: async ({ playerContinuation, baseline }) => {
                 if (playerContinuation !== false &&
                     (typeof playerContinuation !== 'string' ||
                         playerContinuation.trim() === '')) {
                     throw new TypeError('DECIDE bound deferred player continuation is invalid');
                 }
                 active.playerContinuation = playerContinuation;
+                // DR-062 §4: the continuation's own baseline.
+                active.baseline = baseline;
                 readiness.resolve({ status: 'ready' });
                 return active.result.promise;
             },
@@ -2566,7 +2682,9 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
         const actions = deriveControlCandidates().map(({ action }) => ({
             ...action,
         }));
-        const lastError = normalizeErrorFull(context.lastError);
+        const lastError = state.stateId === 'failed'
+            ? failedStateError(context)
+            : normalizeErrorFull(context.lastError);
         const stateDescription = unresolved || state.stateId === undefined
             ? undefined
             : STATE_DESCRIPTIONS[state.stateId];
@@ -2614,6 +2732,8 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
         const turnId = ++turnSequence;
         const callId = `apply-${++applyCallSequence}`;
         currentTurnId = turnId;
+        playerCallFailures.clear();
+        governedFailureOccurrences.clear();
         currentSignal = signal;
         currentAborts = abortReasonClassifier(signal);
         controlPlaneError = undefined;
@@ -2862,7 +2982,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             return abortedResult(signal);
         }
         if (state.activeStateIds.includes('failed')) {
-            const error = normalizeErrorFull(context.lastError);
+            const error = failedStateError(context);
             return {
                 outcome: 'failed',
                 state,
@@ -3052,8 +3172,12 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             const state = currentState();
             if (state.status !== 'active' || !state.quiescent)
                 return undefined;
-            const machine = detachPersistedMachineSnapshot(actor.getPersistedSnapshot());
             const context = actor.getSnapshot().context;
+            // DR-063 §2: the failed state's `lastError` is persisted as every live
+            // surface publishes it, completed from the runtime's own cause slot.
+            const machine = detachPersistedMachineSnapshot(actor.getPersistedSnapshot(), state.stateId === 'failed'
+                ? { lastError: failedStateError(context) }
+                : {});
             if (deferredEffects !== undefined) {
                 synchronizeDeferredProjection(readEffectLedger());
             }
@@ -3189,6 +3313,8 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             }
             const turnId = ++turnSequence;
             currentTurnId = turnId;
+            playerCallFailures.clear();
+            governedFailureOccurrences.clear();
             currentSignal = turn.signal;
             currentAborts = abortReasonClassifier(turn.signal);
             controlPlaneError = undefined;
@@ -3319,7 +3445,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                         : {
                             outcome: 'failed',
                             state,
-                            error: normalizeErrorFull(effectiveError) ?? {
+                            error: failedStateError({ lastError: effectiveError }) ?? {
                                 name: 'Error',
                                 message: String(effectiveError),
                             },
@@ -3344,7 +3470,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                 result = {
                     outcome: drainAborted ? 'aborted' : 'failed',
                     state,
-                    error: normalizeErrorFull(effectiveError) ?? {
+                    error: failedStateError({ lastError: effectiveError }) ?? {
                         name: 'Error',
                         message: String(effectiveError),
                     },