@sublang/playbook 14.1.0 → 15.1.0

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),
                     },