@sublang/playbook 14.1.0 → 15.1.0

package/src/xstate-playbook-runtime.js

@@ -70,11 +70,11 @@ const GOVERNED_JUDGE_FAILURE_REASONS = [
     'corrective semantic candidate is invalid',
     'semantic correction budget is unavailable',
 ];
-const ABORTED_FAILURE_CAUSE = assertPlaybookFailureCause({
+export const ABORTED_FAILURE_CAUSE = assertPlaybookFailureCause({
     code: 'aborted',
     evidence: {},
 });
-function runtimeDefectCause(reason) {
+export function runtimeDefectCause(reason) {
     return assertPlaybookFailureCause({
         code: 'runtime-defect',
         evidence: { reason: reason.length === 0 ? 'unknown runtime defect' : reason },
@@ -98,7 +98,7 @@ function failureErrorCode(error) {
         return undefined;
     }
 }
-function playerFailureCause(input) {
+export function playerFailureCause(input) {
     return assertPlaybookFailureCause({
         code: 'player-failed',
         evidence: {
@@ -114,6 +114,49 @@ function playerFailureCause(input) {
         },
     });
 }
+/**
+ * DR-063 §1: the cause of an unresolved governed settlement. A reconciled
+ * mismatch supplies its own receipt-read cause; the reasons a runtime owns map
+ * to adjudication, abort, and runtime-defect codes. Shared with DECIDE's
+ * bespoke runtime, which decides the same reasons.
+ */
+export function governedSettlementCause(reason, error, aborted, supplied) {
+    if (supplied !== undefined)
+        return supplied;
+    if (aborted || reason.includes('aborted'))
+        return ABORTED_FAILURE_CAUSE;
+    if (GOVERNED_JUDGE_FAILURE_REASONS.includes(reason)) {
+        const transport = failureErrorEvidence(error);
+        return assertPlaybookFailureCause({
+            code: 'judge-failed',
+            evidence: {
+                reason,
+                ...(transport === undefined ? {} : { error: transport }),
+            },
+        });
+    }
+    return runtimeDefectCause(reason);
+}
+const FAILURE_CAUSE_RETENTION_LIMIT = 8;
+export function createFailureCauseRetention() {
+    const causes = new Map();
+    return {
+        retain(error, cause) {
+            if (error === undefined || error === null)
+                return;
+            causes.delete(error);
+            causes.set(error, cause);
+            while (causes.size > FAILURE_CAUSE_RETENTION_LIMIT) {
+                causes.delete(causes.keys().next().value);
+            }
+        },
+        causeOf(error) {
+            if (error === undefined || error === null)
+                return undefined;
+            return normalizeError(error).cause ?? causes.get(error);
+        },
+    };
+}
 // ---------------------------------------------------------------------------
 // DR-028: both call boundaries treat an `ok` result whose `finalText` is
 // missing, empty, or whitespace-only under one empty predicate, and that
@@ -578,7 +621,7 @@ function preExistingChangesBlock(baseline) {
  * `one-descendant-commit` disposition may commit nothing, so it is told
  * nothing.
  */
-function effectAuthorizedPreExistingBlock(effectBoundary, baseline) {
+export function effectAuthorizedPreExistingBlock(effectBoundary, baseline) {
     return effectBoundary.dispositions.includes('one-descendant-commit')
         ? preExistingChangesBlock(baseline)
         : undefined;
@@ -2186,15 +2229,17 @@ export function createXStatePlaybookRuntime(machine, spec) {
         let deferInspectionEmissions = false;
         let deferredInspectionEmissions = [];
         let controlPlaneError;
-        // DR-063 §2: the cause decided at the site the failure was decided, kept
-        // for the failures whose Error the compiled artifact builds itself and the
-        // runtime therefore cannot decorate. It is cleared at each Boss turn start
-        // and at each successful player result, so it is never stale, and it is
-        // only ever read as the cause of an error that carries none of its own.
-        let lastFailureCause;
-        const rememberFailureCause = (cause) => {
-            lastFailureCause = cause;
-        };
+        // DR-063 §2: the cause decided for a non-`ok` player result before the
+        // compiled artifact builds the Error that carries it and hands it to
+        // `markPlayerResultFailure`. It is cleared at each Boss turn start and at
+        // each successful result, so it is never stale.
+        let pendingResultFailureCause;
+        // DR-063 §2: the causes decided for thrown values that cannot carry the
+        // marker — a string, a frozen error — kept by identity for as long as the
+        // failure stands, so every surface that reads the FSM's own `lastError`
+        // publishes the cause decided for exactly that value, whatever turn reads
+        // it.
+        const failureCauses = createFailureCauseRetention();
         // Previous root-machine state for the inspect-driven telemetry /
         // status emitter. undefined before the first inspect firing.
         let priorState;
@@ -3102,33 +3147,13 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 },
             });
         }
-        // DR-063 §1: the cause of an unresolved governed settlement. A reconciled
-        // mismatch supplies its own receipt-read cause; the reasons this function
-        // owns map to adjudication, abort, and runtime-defect codes.
-        function governedSettlementCause(reason, error, aborted, supplied) {
-            if (supplied !== undefined)
-                return supplied;
-            if (aborted || reason.includes('aborted'))
-                return ABORTED_FAILURE_CAUSE;
-            if (GOVERNED_JUDGE_FAILURE_REASONS.includes(reason)) {
-                const transport = failureErrorEvidence(error);
-                return assertPlaybookFailureCause({
-                    code: 'judge-failed',
-                    evidence: {
-                        reason,
-                        ...(transport === undefined ? {} : { error: transport }),
-                    },
-                });
-            }
-            return runtimeDefectCause(reason);
-        }
         function unresolvedGovernedSettlement(reason, error, signal = activeSignal, cause) {
             const aborted = error !== undefined && signal?.aborted === true
                 ? Object.is(error, signal.reason)
                 : false;
             const decided = governedSettlementCause(reason, error, aborted, cause);
-            rememberFailureCause(decided);
             if (aborted) {
+                failureCauses.retain(error, decided);
                 return {
                     status: 'unresolved',
                     error: attachPlaybookFailureCause(error, decided),
@@ -3137,6 +3162,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             const failure = error instanceof Error
                 ? error
                 : new Error(`${label} governed outcome remains unresolved: ${reason}`);
+            failureCauses.retain(failure, decided);
             return {
                 status: 'unresolved',
                 error: attachPlaybookFailureCause(markFsmResultFailure(failure), decided),
@@ -3766,18 +3792,18 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         // the player, and the reported error are known, and a successful
                         // result clears it so no later failure inherits it.
                         if (result.status === 'ok') {
-                            lastFailureCause = undefined;
+                            pendingResultFailureCause = undefined;
                         }
                         else if (result.status === 'aborted') {
-                            rememberFailureCause(ABORTED_FAILURE_CAUSE);
+                            pendingResultFailureCause = ABORTED_FAILURE_CAUSE;
                         }
                         else {
-                            rememberFailureCause(playerFailureCause({
+                            pendingResultFailureCause = playerFailureCause({
                                 roleId,
                                 ...(playerId === undefined ? {} : { playerId }),
                                 error: result.error ??
                                     `callPlayer status ${JSON.stringify(result.status)}`,
-                            }));
+                            });
                         }
                         return result;
                     };
@@ -3850,9 +3876,10 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 }
             },
             markPlayerResultFailure(error) {
-                return lastFailureCause === undefined
-                    ? error
-                    : attachPlaybookFailureCause(error, lastFailureCause);
+                if (pendingResultFailureCause === undefined)
+                    return error;
+                failureCauses.retain(error, pendingResultFailureCause);
+                return attachPlaybookFailureCause(error, pendingResultFailureCause);
             },
             takeGovernedPlayerOutput(result) {
                 const settlement = governedPlayerSettlements.get(result);
@@ -4381,7 +4408,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
             }
             return {
                 ...normalized,
-                cause: lastFailureCause ?? runtimeDefectCause(normalized.message),
+                cause: failureCauses.causeOf(context.lastError) ??
+                    runtimeDefectCause(normalized.message),
             };
         }
         // DR-063 §2: a rejected player port or a result the runtime cannot read is
@@ -4394,7 +4422,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     ...(playerId === undefined ? {} : { playerId }),
                     error,
                 });
-            rememberFailureCause(cause);
+            failureCauses.retain(error, cause);
             return attachPlaybookFailureCause(error, cause);
         }
         function completeFailedStatuses(statuses, state, context) {
@@ -5691,9 +5719,15 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 const state = currentState();
                 if (state.status !== 'active' || !state.quiescent)
                     return undefined;
-                const machineSnapshot = 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, so
+                // a thrown value that refused the cause still explains itself after a
+                // restart.
+                const machineSnapshot = detachPersistedMachineSnapshot(actor.getPersistedSnapshot(), state.stateId === 'failed'
+                    ? { lastError: failedStateError(context ?? {}) }
+                    : {});
                 effectLedgerMirror = currentEffectLedger();
                 refreshRetainedEffectReconciliation(effectLedgerMirror);
                 syncDeferredReconciliationOverlay();
@@ -6128,9 +6162,10 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 activeAborts = abortReasonClassifier(signal);
                 activeAbortEmission = undefined;
                 controlPlaneError = undefined;
-                // DR-063 §2: each turn decides its own failures, so the slot never
-                // carries a previous turn's cause into this one.
-                lastFailureCause = undefined;
+                // DR-063 §2: each turn decides its own failures, so no pending result
+                // cause carries into this one; a cause decided for a parked failure
+                // stays bound to that failure.
+                pendingResultFailureCause = undefined;
                 let result;
                 let operationError;
                 // The boundary sentinel releases on every exit: a settlement defect

package/src/xstate-playbook-runtime.ts

@@ -284,12 +284,12 @@ const GOVERNED_JUDGE_FAILURE_REASONS: readonly string[] = [
   'semantic correction budget is unavailable',
 ];
 
-const ABORTED_FAILURE_CAUSE: PlaybookFailureCause = assertPlaybookFailureCause({
+export const ABORTED_FAILURE_CAUSE: PlaybookFailureCause = assertPlaybookFailureCause({
   code: 'aborted',
   evidence: {},
 });
 
-function runtimeDefectCause(reason: string): PlaybookFailureCause {
+export function runtimeDefectCause(reason: string): PlaybookFailureCause {
   return assertPlaybookFailureCause({
     code: 'runtime-defect',
     evidence: { reason: reason.length === 0 ? 'unknown runtime defect' : reason },
@@ -315,7 +315,7 @@ function failureErrorCode(error: unknown): string | undefined {
   }
 }
 
-function playerFailureCause(input: {
+export function playerFailureCause(input: {
   readonly roleId: string;
   readonly playerId?: string;
   readonly error: unknown;
@@ -336,6 +336,66 @@ function playerFailureCause(input: {
   });
 }
 
+/**
+ * DR-063 §1: the cause of an unresolved governed settlement. A reconciled
+ * mismatch supplies its own receipt-read cause; the reasons a runtime owns map
+ * to adjudication, abort, and runtime-defect codes. Shared with DECIDE's
+ * bespoke runtime, which decides the same reasons.
+ */
+export function governedSettlementCause(
+  reason: string,
+  error: unknown,
+  aborted: boolean,
+  supplied: PlaybookFailureCause | undefined,
+): PlaybookFailureCause {
+  if (supplied !== undefined) return supplied;
+  if (aborted || reason.includes('aborted')) return ABORTED_FAILURE_CAUSE;
+  if (GOVERNED_JUDGE_FAILURE_REASONS.includes(reason)) {
+    const transport = failureErrorEvidence(error);
+    return assertPlaybookFailureCause({
+      code: 'judge-failed',
+      evidence: {
+        reason,
+        ...(transport === undefined ? {} : { error: transport }),
+      },
+    });
+  }
+  return runtimeDefectCause(reason);
+}
+
+/**
+ * DR-063 §2: the causes decided for thrown values that cannot carry the
+ * marker — a string, a frozen error — kept by identity for as long as the
+ * failure stands, so every surface that reads the FSM's own `lastError`
+ * publishes the cause decided for exactly that value, whatever turn reads it.
+ * A value that carries the marker answers from it; the map is bounded, since
+ * only values that refuse the marker need an entry.
+ */
+export interface PlaybookFailureCauseRetention {
+  retain(error: unknown, cause: PlaybookFailureCause): void;
+  causeOf(error: unknown): PlaybookFailureCause | undefined;
+}
+
+const FAILURE_CAUSE_RETENTION_LIMIT = 8;
+
+export function createFailureCauseRetention(): PlaybookFailureCauseRetention {
+  const causes = new Map<unknown, PlaybookFailureCause>();
+  return {
+    retain(error, cause) {
+      if (error === undefined || error === null) return;
+      causes.delete(error);
+      causes.set(error, cause);
+      while (causes.size > FAILURE_CAUSE_RETENTION_LIMIT) {
+        causes.delete(causes.keys().next().value);
+      }
+    },
+    causeOf(error) {
+      if (error === undefined || error === null) return undefined;
+      return normalizeError(error).cause ?? causes.get(error);
+    },
+  };
+}
+
 
 // ---------------------------------------------------------------------------
 // DR-028: both call boundaries treat an `ok` result whose `finalText` is
@@ -1269,8 +1329,8 @@ function preExistingChangesBlock(
  * `one-descendant-commit` disposition may commit nothing, so it is told
  * nothing.
  */
-function effectAuthorizedPreExistingBlock(
-  effectBoundary: Pick<XStateEffectBoundarySeed, 'dispositions'>,
+export function effectAuthorizedPreExistingBlock(
+  effectBoundary: Pick<PlaybookEffectBoundaryStart, 'dispositions'>,
   baseline: PlaybookRepositoryReceipt['baseline'] | undefined,
 ): string | undefined {
   return effectBoundary.dispositions.includes('one-descendant-commit')
@@ -3577,15 +3637,17 @@ export function createXStatePlaybookRuntime<
     let deferInspectionEmissions = false;
     let deferredInspectionEmissions: Array<() => void> = [];
     let controlPlaneError: unknown;
-    // DR-063 §2: the cause decided at the site the failure was decided, kept
-    // for the failures whose Error the compiled artifact builds itself and the
-    // runtime therefore cannot decorate. It is cleared at each Boss turn start
-    // and at each successful player result, so it is never stale, and it is
-    // only ever read as the cause of an error that carries none of its own.
-    let lastFailureCause: PlaybookFailureCause | undefined;
-    const rememberFailureCause = (cause: PlaybookFailureCause): void => {
-      lastFailureCause = cause;
-    };
+    // DR-063 §2: the cause decided for a non-`ok` player result before the
+    // compiled artifact builds the Error that carries it and hands it to
+    // `markPlayerResultFailure`. It is cleared at each Boss turn start and at
+    // each successful result, so it is never stale.
+    let pendingResultFailureCause: PlaybookFailureCause | undefined;
+    // DR-063 §2: the causes decided for thrown values that cannot carry the
+    // marker — a string, a frozen error — kept by identity for as long as the
+    // failure stands, so every surface that reads the FSM's own `lastError`
+    // publishes the cause decided for exactly that value, whatever turn reads
+    // it.
+    const failureCauses = createFailureCauseRetention();
     // Previous root-machine state for the inspect-driven telemetry /
     // status emitter. undefined before the first inspect firing.
     let priorState: PlaybookState | undefined;
@@ -4865,30 +4927,6 @@ export function createXStatePlaybookRuntime<
       });
     }
 
-    // DR-063 §1: the cause of an unresolved governed settlement. A reconciled
-    // mismatch supplies its own receipt-read cause; the reasons this function
-    // owns map to adjudication, abort, and runtime-defect codes.
-    function governedSettlementCause(
-      reason: string,
-      error: unknown,
-      aborted: boolean,
-      supplied: PlaybookFailureCause | undefined,
-    ): PlaybookFailureCause {
-      if (supplied !== undefined) return supplied;
-      if (aborted || reason.includes('aborted')) return ABORTED_FAILURE_CAUSE;
-      if (GOVERNED_JUDGE_FAILURE_REASONS.includes(reason)) {
-        const transport = failureErrorEvidence(error);
-        return assertPlaybookFailureCause({
-          code: 'judge-failed',
-          evidence: {
-            reason,
-            ...(transport === undefined ? {} : { error: transport }),
-          },
-        });
-      }
-      return runtimeDefectCause(reason);
-    }
-
     function unresolvedGovernedSettlement(
       reason: string,
       error?: unknown,
@@ -4900,8 +4938,8 @@ export function createXStatePlaybookRuntime<
           ? Object.is(error, signal.reason)
           : false;
       const decided = governedSettlementCause(reason, error, aborted, cause);
-      rememberFailureCause(decided);
       if (aborted) {
+        failureCauses.retain(error, decided);
         return {
           status: 'unresolved',
           error: attachPlaybookFailureCause(error, decided),
@@ -4911,6 +4949,7 @@ export function createXStatePlaybookRuntime<
         error instanceof Error
           ? error
           : new Error(`${label} governed outcome remains unresolved: ${reason}`);
+      failureCauses.retain(failure, decided);
       return {
         status: 'unresolved',
         error: attachPlaybookFailureCause(
@@ -5835,19 +5874,17 @@ export function createXStatePlaybookRuntime<
             // the player, and the reported error are known, and a successful
             // result clears it so no later failure inherits it.
             if (result.status === 'ok') {
-              lastFailureCause = undefined;
+              pendingResultFailureCause = undefined;
             } else if (result.status === 'aborted') {
-              rememberFailureCause(ABORTED_FAILURE_CAUSE);
+              pendingResultFailureCause = ABORTED_FAILURE_CAUSE;
             } else {
-              rememberFailureCause(
-                playerFailureCause({
-                  roleId,
-                  ...(playerId === undefined ? {} : { playerId }),
-                  error:
-                    result.error ??
-                    `callPlayer status ${JSON.stringify(result.status)}`,
-                }),
-              );
+              pendingResultFailureCause = playerFailureCause({
+                roleId,
+                ...(playerId === undefined ? {} : { playerId }),
+                error:
+                  result.error ??
+                  `callPlayer status ${JSON.stringify(result.status)}`,
+              });
             }
             return result;
           };
@@ -5957,9 +5994,9 @@ export function createXStatePlaybookRuntime<
       },
 
       markPlayerResultFailure(error): Error {
-        return lastFailureCause === undefined
-          ? error
-          : attachPlaybookFailureCause(error, lastFailureCause);
+        if (pendingResultFailureCause === undefined) return error;
+        failureCauses.retain(error, pendingResultFailureCause);
+        return attachPlaybookFailureCause(error, pendingResultFailureCause);
       },
 
       takeGovernedPlayerOutput(result): GovernedPlayerSettlement | undefined {
@@ -6619,7 +6656,9 @@ export function createXStatePlaybookRuntime<
       }
       return {
         ...normalized,
-        cause: lastFailureCause ?? runtimeDefectCause(normalized.message),
+        cause:
+          failureCauses.causeOf(context.lastError) ??
+          runtimeDefectCause(normalized.message),
       };
     }
 
@@ -6638,7 +6677,7 @@ export function createXStatePlaybookRuntime<
             ...(playerId === undefined ? {} : { playerId }),
             error,
           });
-      rememberFailureCause(cause);
+      failureCauses.retain(error, cause);
       return attachPlaybookFailureCause(error, cause);
     }
 
@@ -8243,11 +8282,18 @@ export function createXStatePlaybookRuntime<
         }
         const state = currentState();
         if (state.status !== 'active' || !state.quiescent) return undefined;
+        const context = (actor.getSnapshot() as { context?: unknown })
+          .context as Record<string, unknown>;
+        // DR-063 §2: the failed state's `lastError` is persisted as every live
+        // surface publishes it, completed from the runtime's own cause slot, so
+        // a thrown value that refused the cause still explains itself after a
+        // restart.
         const machineSnapshot = detachPersistedMachineSnapshot(
           actor.getPersistedSnapshot(),
+          state.stateId === 'failed'
+            ? { lastError: failedStateError(context ?? {}) }
+            : {},
         );
-        const context = (actor.getSnapshot() as { context?: unknown })
-          .context as Record<string, unknown>;
         effectLedgerMirror = currentEffectLedger();
         refreshRetainedEffectReconciliation(effectLedgerMirror);
         syncDeferredReconciliationOverlay();
@@ -8763,9 +8809,10 @@ export function createXStatePlaybookRuntime<
         activeAborts = abortReasonClassifier(signal);
         activeAbortEmission = undefined;
         controlPlaneError = undefined;
-        // DR-063 §2: each turn decides its own failures, so the slot never
-        // carries a previous turn's cause into this one.
-        lastFailureCause = undefined;
+        // DR-063 §2: each turn decides its own failures, so no pending result
+        // cause carries into this one; a cause decided for a parked failure
+        // stays bound to that failure.
+        pendingResultFailureCause = undefined;
         let result: PlaybookRunResult | undefined;
         let operationError: unknown;
         // The boundary sentinel releases on every exit: a settlement defect

package/src/xstate-runtime.d.ts

@@ -44,7 +44,9 @@ export interface SnapshotNormalizationOptions {
     pendingCall?: PlaybookPendingCall;
 }
 export declare function normalizePlaybookSnapshot(snapshot: unknown, options?: SnapshotNormalizationOptions): PlaybookState;
-export declare function detachPersistedMachineSnapshot(persisted: unknown): JsonValue;
+export declare function detachPersistedMachineSnapshot(persisted: unknown, completion?: {
+    readonly lastError?: NormalizedError;
+}): JsonValue;
 /** Authority for one governed delegated-player output field (DR-040 §1). */
 export type PlaybookSemanticFieldAuthority = 'presentation' | 'semantic' | 'effect' | 'runtime';
 /** One already-validated state-local governed outcome declaration. */

package/src/xstate-runtime.js

@@ -607,8 +607,15 @@ export function normalizePlaybookSnapshot(snapshot, options = {}) {
 // DR-014 §1: deep-detach an XState persisted actor snapshot into strict
 // JSON for a PlaybookRuntimeSnapshot, normalizing any raw Error value
 // (for example FSM context `lastError`) instead of rejecting it.
-export function detachPersistedMachineSnapshot(persisted) {
-    return snapshotJsonValue(withErrorsNormalized(persisted, new Set()), 'persisted machine snapshot');
+// DR-063 §2: a runtime parked in its failure state supplies the `lastError`
+// it publishes live — completed with the cause it decided — and that record
+// replaces the context's own, which a thrown value may have refused to carry.
+export function detachPersistedMachineSnapshot(persisted, completion = {}) {
+    const detached = withErrorsNormalized(persisted, new Set());
+    const lastError = completion.lastError;
+    return snapshotJsonValue(lastError !== undefined && isRecord(detached) && isRecord(detached.context)
+        ? { ...detached, context: { ...detached.context, lastError } }
+        : detached, 'persisted machine snapshot');
 }
 function withErrorsNormalized(value, ancestors) {
     if (value instanceof Error)

package/src/xstate-runtime.ts

@@ -902,9 +902,19 @@ export function normalizePlaybookSnapshot(
 // DR-014 §1: deep-detach an XState persisted actor snapshot into strict
 // JSON for a PlaybookRuntimeSnapshot, normalizing any raw Error value
 // (for example FSM context `lastError`) instead of rejecting it.
-export function detachPersistedMachineSnapshot(persisted: unknown): JsonValue {
+// DR-063 §2: a runtime parked in its failure state supplies the `lastError`
+// it publishes live — completed with the cause it decided — and that record
+// replaces the context's own, which a thrown value may have refused to carry.
+export function detachPersistedMachineSnapshot(
+  persisted: unknown,
+  completion: { readonly lastError?: NormalizedError } = {},
+): JsonValue {
+  const detached = withErrorsNormalized(persisted, new Set());
+  const lastError = completion.lastError;
   return snapshotJsonValue(
-    withErrorsNormalized(persisted, new Set()),
+    lastError !== undefined && isRecord(detached) && isRecord(detached.context)
+      ? { ...detached, context: { ...detached.context, lastError } }
+      : detached,
     'persisted machine snapshot',
   );
 }