@sublang/playbook 14.0.0 → 15.0.0

package/src/xstate-runtime.d.ts

@@ -1,5 +1,5 @@
 import { type AnyActorRef, type PromiseActorLogic, type SnapshotFrom } from 'xstate';
-import type { CaptainResult, JsonValue, NormalizedError, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookEffectLedger, PlaybookRepositoryDisposition, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookSuspendedCall, PlayerResult } from './runtime.js';
+import type { CaptainResult, JsonValue, NormalizedError, PlaybookFailureCause, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookEffectLedger, PlaybookRepositoryDisposition, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookSuspendedCall, PlayerResult } from './runtime.js';
 export * from './xstate-playbook-runtime.js';
 /**
  * Immutable cancellation provenance for one runtime operation. The captured
@@ -27,6 +27,12 @@ export declare function snapshotJsonValue(value: unknown, path?: string): JsonVa
 /** Validate session causality and detach its immutable identity from the host. */
 export declare function snapshotPlaybookSession(session: PlaybookSession): PlaybookSession;
 export declare function hiddenControlEnvelope(prompt: string): string;
+/**
+ * Attach one validated failure cause to an error object, returning it. A cause
+ * the closed validator rejects is dropped rather than published, and an error
+ * that refuses the property keeps its own cause-free identity (DR-063 §1).
+ */
+export declare function attachPlaybookFailureCause<E>(error: E, cause: unknown): E;
 export declare function normalizeError(error: unknown): NormalizedError;
 export interface PlaybookStateMetadata {
     stateId: string;
@@ -74,6 +80,8 @@ export type PlaybookSemanticReconciliation = {
 } | {
     readonly status: 'unresolved';
     readonly reason: PlaybookSemanticReconciliationReason;
+    /** DR-063 §1: why it stays unresolved, as a closed structured cause. */
+    readonly cause: PlaybookFailureCause;
     readonly evidence: PlaybookRetainedSemanticEvidence;
 };
 /**

package/src/xstate-runtime.js

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
 import { fromPromise, waitFor, } from 'xstate';
+import { assertPlaybookFailureCause } from './runtime.js';
 // DR-019: the generic linked-runtime factory and its strategy helpers live
 // in the sibling module and are re-exported here so linked artifacts import
 // one shared engine surface.
@@ -387,7 +389,74 @@ export function hiddenControlEnvelope(prompt) {
         'Now return exactly one JSON object and nothing else.',
     ].join('\n\n');
 }
+/**
+ * DR-063 §2: the marker property the runtime writes on the error it marks as
+ * the FSM failure. It is non-enumerable, so decorating a host-owned error
+ * changes nothing a host can observe by enumeration or serialization.
+ */
+const PLAYBOOK_FAILURE_CAUSE_PROPERTY = 'playbookCause';
+/**
+ * Attach one validated failure cause to an error object, returning it. A cause
+ * the closed validator rejects is dropped rather than published, and an error
+ * that refuses the property keeps its own cause-free identity (DR-063 §1).
+ */
+export function attachPlaybookFailureCause(error, cause) {
+    if (typeof error !== 'object' || error === null)
+        return error;
+    let validated;
+    try {
+        validated = assertPlaybookFailureCause(cause);
+    }
+    catch {
+        return error;
+    }
+    try {
+        Object.defineProperty(error, PLAYBOOK_FAILURE_CAUSE_PROPERTY, {
+            value: validated,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+    }
+    catch {
+        // A frozen or hostile error keeps no cause; the runtime's own slot still
+        // supplies one at the failed state.
+    }
+    return error;
+}
+/**
+ * DR-063 §2: a normalized error carries `cause` exactly when the underlying
+ * error carries a valid one. An `Error` carries it on the marker property the
+ * runtime writes; an already-normalized record carries it as `cause`, so the
+ * cause survives every re-normalization along the durable round trip.
+ */
+function playbookFailureCauseOf(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    let candidate;
+    try {
+        if (Object.hasOwn(error, PLAYBOOK_FAILURE_CAUSE_PROPERTY)) {
+            candidate = error[PLAYBOOK_FAILURE_CAUSE_PROPERTY];
+        }
+        else if (!(error instanceof Error) && Object.hasOwn(error, 'cause')) {
+            candidate = error.cause;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    if (candidate === undefined)
+        return undefined;
+    try {
+        return assertPlaybookFailureCause(candidate);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function normalizeError(error) {
+    const cause = playbookFailureCauseOf(error);
+    const withCause = (normalized) => cause === undefined ? normalized : { ...normalized, cause };
     if (error instanceof Error) {
         let name = 'Error';
         let message = 'Unknown error';
@@ -414,11 +483,11 @@ export function normalizeError(error) {
         catch {
             // A stack is optional at the public boundary.
         }
-        return {
+        return withCause({
             name,
             message,
             ...(stack ? { stack } : {}),
-        };
+        });
     }
     if (typeof error === 'string') {
         return { name: 'Error', message: error };
@@ -426,22 +495,22 @@ export function normalizeError(error) {
     try {
         assertJsonSafe(error);
         if (isRecord(error) && typeof error.message === 'string') {
-            return {
+            return withCause({
                 name: typeof error.name === 'string' && error.name.length > 0
                     ? error.name
                     : 'Error',
                 message: error.message,
                 ...(typeof error.stack === 'string' ? { stack: error.stack } : {}),
-            };
+            });
         }
-        return { name: 'Error', message: JSON.stringify(error) };
+        return withCause({ name: 'Error', message: JSON.stringify(error) });
     }
     catch {
         try {
-            return { name: 'Error', message: String(error) };
+            return withCause({ name: 'Error', message: String(error) });
         }
         catch {
-            return { name: 'Error', message: 'Unknown error' };
+            return withCause({ name: 'Error', message: 'Unknown error' });
         }
     }
 }
@@ -629,9 +698,56 @@ function projectionsEqual(left, right) {
     return (left.projectionDigest === right.projectionDigest &&
         projectionText(left.projection) === projectionText(right.projection));
 }
-function projectionPreservesBaseline(baseline, after) {
-    return Object.entries(baseline.projection).every(([path, entry]) => own(after.projection, path) &&
-        JSON.stringify(entry) === JSON.stringify(after.projection[path]));
+function projectionEntriesEqual(left, right, path) {
+    return (own(right.projection, path) &&
+        JSON.stringify(left.projection[path]) ===
+            JSON.stringify(right.projection[path]));
+}
+const EFFECT_PRE_EXISTING_LISTS = ['absorbed', 'altered', 'lost'];
+const EMPTY_PRE_EXISTING = Object.freeze({
+    absorbed: Object.freeze([]),
+    altered: Object.freeze([]),
+    lost: Object.freeze([]),
+});
+/**
+ * The pre-existing accounting a physical or logical receipt records
+ * (DR-062 §3): sorted unique baseline paths, pairwise disjoint, present
+ * exactly when one list is nonempty.
+ */
+function effectPreExisting(value, path, baseline) {
+    if (!isRecord(value))
+        throw new TypeError(`${path} must be an object`);
+    rejectUnknownKeys(value, EFFECT_PRE_EXISTING_LISTS, path);
+    const claimed = new Set();
+    const lists = EFFECT_PRE_EXISTING_LISTS.map((name) => {
+        const entries = value[name];
+        if (!Array.isArray(entries)) {
+            throw new TypeError(`${path}.${name} must be an array of baseline paths`);
+        }
+        let previous;
+        for (const entry of entries) {
+            if (typeof entry !== 'string' || entry.length === 0) {
+                throw new TypeError(`${path}.${name} must hold nonempty baseline paths`);
+            }
+            const member = entry;
+            if (previous !== undefined && member <= previous) {
+                throw new TypeError(`${path}.${name} must be sorted and unique`);
+            }
+            previous = member;
+            if (!own(baseline.projection, member)) {
+                throw new TypeError(`${path}.${name} names a path outside the baseline projection`);
+            }
+            if (claimed.has(member)) {
+                throw new TypeError(`${path} lists ${JSON.stringify(member)} twice`);
+            }
+            claimed.add(member);
+        }
+        return [name, entries];
+    });
+    if (claimed.size === 0) {
+        throw new TypeError(`${path} must name at least one baseline path`);
+    }
+    return Object.fromEntries(lists);
 }
 function effectObservation(value, path) {
     if (!isRecord(value))
@@ -672,7 +788,7 @@ function assertObservationIdentity(observation, identity, path) {
 function effectReceipt(value, path, expectedBaseline, expectedAfter, matchExpectedAfter = false, dispositions) {
     if (!isRecord(value))
         throw new TypeError(`${path} must be an object`);
-    rejectUnknownKeys(value, ['classification', 'baseline', 'after', 'commitOid'], path);
+    rejectUnknownKeys(value, ['classification', 'baseline', 'after', 'commitOid', 'preExisting'], path);
     if (typeof value.classification !== 'string' ||
         !EFFECT_RECEIPT_CLASSIFICATIONS.has(value.classification)) {
         throw new TypeError(`${path}.classification is not supported`);
@@ -718,18 +834,38 @@ function effectReceipt(value, path, expectedBaseline, expectedAfter, matchExpect
         !jsonValuesEqual(baseline, after)) {
         throw new TypeError(`${path} classified unchanged observations that differ`);
     }
+    // DR-062 §3: a receipt records the fate of every baseline entry, so the
+    // accounting and the two observations must agree exactly.
+    if (own(value, 'preExisting') &&
+        classification !== 'one-descendant-commit' &&
+        classification !== 'worktree-only-change' &&
+        classification !== 'observation-ambiguous') {
+        throw new TypeError(`${path}.preExisting is not permitted for ${classification}`);
+    }
+    const preExisting = own(value, 'preExisting')
+        ? effectPreExisting(value.preExisting, `${path}.preExisting`, baseline)
+        : EMPTY_PRE_EXISTING;
+    const consumed = new Set([...preExisting.absorbed, ...preExisting.altered]);
     if (classification === 'one-descendant-commit' &&
         after !== undefined &&
         (baseline.head === after.head ||
-            !projectionsEqual(baseline, after))) {
-        throw new TypeError(`${path} one-descendant-commit must change HEAD and preserve the projection`);
+            preExisting.lost.length > 0 ||
+            !Object.keys(after.projection).every((member) => own(baseline.projection, member) &&
+                projectionEntriesEqual(baseline, after, member)) ||
+            !Object.keys(baseline.projection).every((member) => own(after.projection, member) !== consumed.has(member)) ||
+            (consumed.size === 0) !== projectionsEqual(baseline, after))) {
+        throw new TypeError(`${path} one-descendant-commit must change HEAD and account for its complete baseline projection`);
     }
     if (classification === 'worktree-only-change' &&
         after !== undefined &&
         (baseline.head !== after.head ||
             projectionsEqual(baseline, after) ||
-            !projectionPreservesBaseline(baseline, after))) {
-        throw new TypeError(`${path} worktree-only-change must preserve HEAD and change the projection`);
+            preExisting.absorbed.length > 0 ||
+            preExisting.lost.length > 0 ||
+            !Object.keys(baseline.projection).every((member) => own(after.projection, member) &&
+                projectionEntriesEqual(baseline, after, member) !==
+                    consumed.has(member)))) {
+        throw new TypeError(`${path} worktree-only-change must preserve HEAD, change the projection, and account for every altered baseline entry`);
     }
     if ((classification === 'multiple-commits' ||
         classification === 'rewritten-or-non-descendant') &&
@@ -820,8 +956,137 @@ function retainedSemanticEvidence(candidate, finalText) {
         ...(typeof finalText === 'string' ? { finalText } : {}),
     });
 }
-function unresolvedSemanticEvidence(reason, evidence) {
-    return Object.freeze({ status: 'unresolved', reason, evidence });
+// ---------------------------------------------------------------------------
+// DR-063 §1: the evidence builder for a repository-decided failure. Every list
+// is sorted, unique, and bounded; `truncated` carries the count the bound
+// omitted. Nothing but repository paths, dispositions, classifications, and
+// revision identities enters a cause.
+// ---------------------------------------------------------------------------
+const FAILURE_PATH_BOUND = 32;
+function boundedFailurePaths(lists) {
+    const bounded = {};
+    let omitted = 0;
+    for (const [member, paths] of Object.entries(lists)) {
+        bounded[member] = paths.slice(0, FAILURE_PATH_BOUND);
+        omitted += Math.max(0, paths.length - FAILURE_PATH_BOUND);
+    }
+    if (omitted > 0)
+        bounded.truncated = omitted;
+    return bounded;
+}
+function sortedUniquePaths(paths) {
+    return [...new Set(paths)].sort();
+}
+/** After-projection entries the baseline did not hold, or holds differently. */
+function newOrChangedProjectionPaths(baseline, after) {
+    return sortedUniquePaths(Object.keys(after.projection).filter((path) => !Object.hasOwn(baseline.projection, path) ||
+        !isDeepStrictEqual(baseline.projection[path], after.projection[path])));
+}
+/** Entries that differ or are missing on either side of the two projections. */
+function divergentProjectionPaths(baseline, after) {
+    return sortedUniquePaths([
+        ...Object.keys(baseline.projection),
+        ...Object.keys(after.projection),
+    ].filter((path) => !Object.hasOwn(baseline.projection, path) ||
+        !Object.hasOwn(after.projection, path) ||
+        !isDeepStrictEqual(baseline.projection[path], after.projection[path])));
+}
+/**
+ * DR-063 §1: the cause of an unresolved repository-disposition mismatch, read
+ * from the disposition the accepted arm required and the receipt the host
+ * proved. The receipt states the failure; nothing here infers one.
+ */
+function playbookRepositoryFailureCause(required, receipt) {
+    const observed = receipt.classification;
+    const baselineHead = receipt.baseline.head;
+    const after = receipt.after;
+    const common = { required, observed, baselineHead };
+    const ambiguous = () => assertPlaybookFailureCause({
+        code: 'attribution-ambiguous',
+        evidence: {
+            ...common,
+            ...(after === undefined ? {} : { afterHead: after.head }),
+        },
+    });
+    const lost = receipt.preExisting?.lost ?? [];
+    if (lost.length > 0) {
+        return assertPlaybookFailureCause({
+            code: 'pre-existing-lost',
+            evidence: {
+                ...common,
+                ...(after === undefined ? {} : { afterHead: after.head }),
+                paths: boundedFailurePaths({ lost: sortedUniquePaths(lost) }),
+            },
+        });
+    }
+    if (observed === 'observation-ambiguous' && after === undefined) {
+        return assertPlaybookFailureCause({
+            code: 'observation-unstable',
+            evidence: common,
+        });
+    }
+    if (after === undefined)
+        return ambiguous();
+    const afterHead = after.head;
+    if (observed === 'multiple-commits') {
+        return assertPlaybookFailureCause({
+            code: 'commits-more-than-one',
+            evidence: { ...common, afterHead },
+        });
+    }
+    if (observed === 'rewritten-or-non-descendant') {
+        return assertPlaybookFailureCause({
+            code: 'history-rewritten',
+            evidence: { ...common, afterHead },
+        });
+    }
+    if (observed === 'concurrent-or-foreign-change') {
+        return assertPlaybookFailureCause({
+            code: 'foreign-change',
+            evidence: {
+                ...common,
+                afterHead,
+                paths: boundedFailurePaths({
+                    changed: divergentProjectionPaths(receipt.baseline, after),
+                }),
+            },
+        });
+    }
+    const uncommitted = newOrChangedProjectionPaths(receipt.baseline, after);
+    const altered = sortedUniquePaths(receipt.preExisting?.altered ?? []);
+    if (observed === 'observation-ambiguous' &&
+        afterHead !== baselineHead &&
+        (uncommitted.length > 0 || altered.length > 0)) {
+        return assertPlaybookFailureCause({
+            code: 'commit-residual',
+            evidence: {
+                ...common,
+                afterHead,
+                ...(receipt.commitOid === undefined
+                    ? {}
+                    : { commitOid: receipt.commitOid }),
+                paths: boundedFailurePaths({ uncommitted, altered }),
+            },
+        });
+    }
+    if (required === 'one-descendant-commit' &&
+        (observed === 'unchanged' || observed === 'worktree-only-change')) {
+        return assertPlaybookFailureCause({
+            code: 'commit-missing',
+            evidence: {
+                ...common,
+                afterHead,
+                paths: boundedFailurePaths({ uncommitted }),
+            },
+        });
+    }
+    return ambiguous();
+}
+function unresolvedSemanticEvidence(reason, evidence, cause = assertPlaybookFailureCause({
+    code: 'runtime-defect',
+    evidence: { reason },
+})) {
+    return Object.freeze({ status: 'unresolved', reason, cause, evidence });
 }
 /**
  * Reconcile one exact semantic candidate with host-owned effect evidence.
@@ -860,7 +1125,7 @@ export function reconcilePlaybookSemanticEvidence(input) {
             receipt.after !== undefined &&
             receipt.after.head === receipt.baseline.head);
     if (!dispositionMatches) {
-        return unresolvedSemanticEvidence('repository-disposition-mismatch', evidence);
+        return unresolvedSemanticEvidence('repository-disposition-mismatch', evidence, playbookRepositoryFailureCause(disposition, receipt));
     }
     let runtimeFields = Object.freeze({});
     if (input.runtimeFields !== undefined) {
@@ -1630,6 +1895,17 @@ export class NestedPlaybookCallError extends Error {
         if (normalized?.stack)
             this.stack = normalized.stack;
         this.result = result;
+        // DR-063 §2: the child's failure reaching its parent is `child-failed`,
+        // carrying the child's own cause when its normalized error published one.
+        attachPlaybookFailureCause(this, {
+            code: 'child-failed',
+            evidence: {
+                playbookId: result.playbookId,
+                ...(normalized?.cause === undefined
+                    ? {}
+                    : { cause: normalized.cause }),
+            },
+        });
     }
 }
 function validateState(state, path) {
@@ -1720,7 +1996,7 @@ function validateNormalizedError(error, path) {
     if (!isRecord(error)) {
         throw new TypeError(`${path} must be a normalized error`);
     }
-    rejectUnknownKeys(error, ['name', 'message', 'stack'], path);
+    rejectUnknownKeys(error, ['name', 'message', 'stack', 'cause'], path);
     requireNonEmptyString(error.name, `${path}.name`);
     if (typeof error.message !== 'string') {
         throw new TypeError(`${path}.message must be a string`);
@@ -1728,6 +2004,10 @@ function validateNormalizedError(error, path) {
     if (error.stack !== undefined && typeof error.stack !== 'string') {
         throw new TypeError(`${path}.stack must be a string`);
     }
+    // DR-063 §2: a normalized error may carry its structured cause, and an
+    // unrecognized shape is not a cause.
+    if (error.cause !== undefined)
+        assertPlaybookFailureCause(error.cause);
 }
 // DR-048: the completed child's compiled terminal record. It is runtime-owned
 // data read from the child's artifact, so a malformed one is a control-plane