footprintjs 8.0.0 → 8.2.0

package/dist/lib/runner/checkpointSanitize.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * checkpointSanitize — clone-resilience helpers for `buildPauseCheckpoint`.
+ *
+ * The pause checkpoint is detached via one `structuredClone` of the assembled
+ * checkpoint. The JSON-safe contract governs what CONSUMERS put into a
+ * checkpoint (pauseData, shared state) — but the execution tree's diagnostic
+ * bags (`logs`/`errors`/`metrics`/`evals`) accept ANY value at write time
+ * without cloning (`$debug`/`$error`/`$metric`/`$eval` route through
+ * `DiagnosticCollector`, which stores raw references). A `$debug`'d function
+ * in any stage of a pausing run would make the whole-checkpoint clone throw
+ * `DataCloneError` — swallowing the pause.
+ *
+ * That violates the library's error-isolation grain: observability side-bags
+ * never abort traversal anywhere else. These helpers restore the grain:
+ *
+ *   - `sanitizeDiagnosticBags` — replace non-cloneable diagnostic values with
+ *     marker strings (`'[non-serializable: function]'`) so the pause survives.
+ *   - `describeCheckpointCloneFailure` — when the clone STILL fails after
+ *     sanitization (the non-cloneable lives in consumer-owned data, e.g.
+ *     `pauseData`), name the offending checkpoint field(s) and point at the
+ *     JSON-safe contract instead of letting a naked `DataCloneError` escape.
+ *
+ * Both run ONLY on the clone-failure path of a pause — never on the hot path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeCheckpointCloneFailure = exports.sanitizeDiagnosticBags = void 0;
+/** The StageSnapshot fields written by `$debug`/`$error`/`$metric`/`$eval`. */
+const DIAGNOSTIC_BAGS = ['logs', 'errors', 'metrics', 'evals'];
+/** `true` when `structuredClone` accepts the value as-is. */
+function isCloneable(value) {
+    try {
+        structuredClone(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Human-readable kind for the `[non-serializable: …]` marker. */
+function describeKind(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value !== 'object')
+        return typeof value;
+    return value.constructor?.name ?? 'object';
+}
+/** Plain data container we can rebuild entry-by-entry without lying about the type. */
+function isPlainObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Deep-replace non-cloneable values with `'[non-serializable: <kind>]'`
+ * marker strings, preserving everything `structuredClone` accepts.
+ *
+ * Fast path: a cloneable value is returned AS-IS (no copy — the caller
+ * clones the whole checkpoint right after). Only containers that actually
+ * hold a non-cloneable leaf are rebuilt, and only KNOWN container shapes
+ * (array / Map / Set / plain object) are rebuilt entry-by-entry — exotic
+ * non-cloneables (Promise, WeakMap, class instances holding a function, …)
+ * become a typed marker rather than a misleading empty shell. Pure cycles
+ * pass the fast path untouched (`structuredClone` supports them); a cycle
+ * is only broken — with a marker — when it shares a container with a
+ * non-cloneable value.
+ */
+function sanitizeValue(value, seen) {
+    if (isCloneable(value))
+        return value;
+    if (value !== null && typeof value === 'object') {
+        if (seen.has(value))
+            return '[non-serializable: circular]';
+        seen.add(value);
+        if (Array.isArray(value)) {
+            return value.map((v) => sanitizeValue(v, seen));
+        }
+        if (value instanceof Map) {
+            return new Map([...value].map(([k, v]) => [sanitizeValue(k, seen), sanitizeValue(v, seen)]));
+        }
+        if (value instanceof Set) {
+            return new Set([...value].map((v) => sanitizeValue(v, seen)));
+        }
+        if (isPlainObject(value)) {
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, sanitizeValue(v, seen)]));
+        }
+    }
+    return `[non-serializable: ${describeKind(value)}]`;
+}
+/**
+ * Walk a `StageSnapshot` tree (via `next` + `children`) and sanitize the four
+ * diagnostic bags on every node IN PLACE.
+ *
+ * In-place is safe and intentional: `StageContext.getSnapshot()` builds fresh
+ * node objects on every call, but the bag fields on those fresh nodes ALIAS
+ * the live `DiagnosticCollector` bags. We replace the node's bag REFERENCE
+ * with a sanitized copy — the live engine bags are never mutated, so a
+ * same-executor resume keeps the original diagnostic values.
+ */
+function sanitizeDiagnosticBags(tree) {
+    const seen = new WeakSet();
+    const visit = (node) => {
+        for (const bag of DIAGNOSTIC_BAGS) {
+            const bagValue = node[bag];
+            if (bagValue !== undefined && !isCloneable(bagValue)) {
+                node[bag] = sanitizeValue(bagValue, seen);
+            }
+        }
+        if (node.next)
+            visit(node.next);
+        if (node.children)
+            for (const child of node.children)
+                visit(child);
+    };
+    visit(tree);
+    return tree;
+}
+exports.sanitizeDiagnosticBags = sanitizeDiagnosticBags;
+/**
+ * Build the DESCRIPTIVE error for a checkpoint that still cannot be cloned
+ * after diagnostic-bag sanitization — i.e. the non-cloneable value lives in
+ * consumer-owned data (a genuine JSON-safe contract violation). Probes each
+ * top-level checkpoint field individually so the message names the offending
+ * field family. Never lets a naked `DataCloneError` escape.
+ */
+function describeCheckpointCloneFailure(checkpoint, cause) {
+    const failing = Object.entries(checkpoint)
+        .filter(([, value]) => !isCloneable(value))
+        .map(([field]) => field);
+    const fields = failing.length > 0 ? failing.join(', ') : 'unknown';
+    return new Error('FlowChartExecutor: cannot build the pause checkpoint — non-serializable value(s) in ' +
+        `checkpoint field(s): ${fields}. The checkpoint contract is JSON-safe (no functions, no ` +
+        "class instances). Check the pauseData returned by the pausable stage's execute(), and any " +
+        'subflow state captured at the pause. Diagnostic values from $debug/$metric/$error/$eval ' +
+        'are sanitized automatically and never cause this error. ' +
+        'See docs/guides/execution-model.md ("Pause / resume — what a checkpoint captures").', { cause });
+}
+exports.describeCheckpointCloneFailure = describeCheckpointCloneFailure;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2hlY2twb2ludFNhbml0aXplLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2xpYi9ydW5uZXIvY2hlY2twb2ludFNhbml0aXplLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFBQTs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0F1Qkc7OztBQUlILCtFQUErRTtBQUMvRSxNQUFNLGVBQWUsR0FBRyxDQUFDLE1BQU0sRUFBRSxRQUFRLEVBQUUsU0FBUyxFQUFFLE9BQU8sQ0FBVSxDQUFDO0FBRXhFLDZEQUE2RDtBQUM3RCxTQUFTLFdBQVcsQ0FBQyxLQUFjO0lBQ2pDLElBQUksQ0FBQztRQUNILGVBQWUsQ0FBQyxLQUFLLENBQUMsQ0FBQztRQUN2QixPQUFPLElBQUksQ0FBQztJQUNkLENBQUM7SUFBQyxNQUFNLENBQUM7UUFDUCxPQUFPLEtBQUssQ0FBQztJQUNmLENBQUM7QUFDSCxDQUFDO0FBRUQsa0VBQWtFO0FBQ2xFLFNBQVMsWUFBWSxDQUFDLEtBQWM7SUFDbEMsSUFBSSxLQUFLLEtBQUssSUFBSTtRQUFFLE9BQU8sTUFBTSxDQUFDO0lBQ2xDLElBQUksT0FBTyxLQUFLLEtBQUssUUFBUTtRQUFFLE9BQU8sT0FBTyxLQUFLLENBQUM7SUFDbkQsT0FBTyxLQUFLLENBQUMsV0FBVyxFQUFFLElBQUksSUFBSSxRQUFRLENBQUM7QUFDN0MsQ0FBQztBQUVELHVGQUF1RjtBQUN2RixTQUFTLGFBQWEsQ0FBQyxLQUFhO0lBQ2xDLE1BQU0sS0FBSyxHQUFHLE1BQU0sQ0FBQyxjQUFjLENBQUMsS0FBSyxDQUFrQixDQUFDO0lBQzVELE9BQU8sS0FBSyxLQUFLLE1BQU0sQ0FBQyxTQUFTLElBQUksS0FBSyxLQUFLLElBQUksQ0FBQztBQUN0RCxDQUFDO0FBRUQ7Ozs7Ozs7Ozs7Ozs7R0FhRztBQUNILFNBQVMsYUFBYSxDQUFDLEtBQWMsRUFBRSxJQUFxQjtJQUMxRCxJQUFJLFdBQVcsQ0FBQyxLQUFLLENBQUM7UUFBRSxPQUFP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Q0FBQyxDQUFDLEVBQUUsS0FBSyxDQUFDLEVBQUUsRUFBRSxDQUFDLENBQUMsV0FBVyxDQUFDLEtBQUssQ0FBQyxDQUFDO1NBQzFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsS0FBSyxDQUFDLEVBQUUsRUFBRSxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQzNCLE1BQU0sTUFBTSxHQUFHLE9BQU8sQ0FBQyxNQUFNLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUM7SUFDbkUsT0FBTyxJQUFJLEtBQUssQ0FDZCxzRkFBc0Y7UUFDcEYsd0JBQXdCLE1BQU0sMkRBQTJEO1FBQ3pGLDRGQUE0RjtRQUM1RiwwRkFBMEY7UUFDMUYsMERBQTBEO1FBQzFELHFGQUFxRixFQUN2RixFQUFFLEtBQUssRUFBRSxDQUNWLENBQUM7QUFDSixDQUFDO0FBZEQsd0VBY0MiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIGNoZWNrcG9pbnRTYW5pdGl6ZSDigJQgY2xvbmUtcmVzaWxpZW5jZSBoZWxwZXJzIGZvciBgYnVpbGRQYXVzZUNoZWNrcG9pbnRgLlxuICpcbiAqIFRoZSBwYXVzZSBjaGVja3BvaW50IGlzIGRldGFjaGVkIHZpYSBvbmUgYHN0cnVjdHVyZWRDbG9uZWAgb2YgdGhlIGFzc2VtYmxlZFxuICogY2hlY2twb2ludC4gVGhlIEpTT04tc2FmZSBjb250cmFjdCBnb3Zlcm5zIHdoYXQgQ09OU1VNRVJTIHB1dCBpbnRvIGFcbiAqIGNoZWNrcG9pbnQgKHBhdXNlRGF0YSwgc2hhcmVkIHN0YXRlKSDigJQgYnV0IHRoZSBleGVjdXRpb24gdHJlZSdzIGRpYWdub3N0aWNcbiAqIGJhZ3MgKGBsb2dzYC9gZXJyb3JzYC9gbWV0cmljc2AvYGV2YWxzYCkgYWNjZXB0IEFOWSB2YWx1ZSBhdCB3cml0ZSB0aW1lXG4gKiB3aXRob3V0IGNsb25pbmcgKGAkZGVidWdgL2AkZXJyb3JgL2AkbWV0cmljYC9gJGV2YWxgIHJvdXRlIHRocm91Z2hcbiAqIGBEaWFnbm9zdGljQ29sbGVjdG9yYCwgd2hpY2ggc3RvcmVzIHJhdyByZWZlcmVuY2VzKS4gQSBgJGRlYnVnYCdkIGZ1bmN0aW9uXG4gKiBpbiBhbnkgc3RhZ2Ugb2YgYSBwYXVzaW5nIHJ1biB3b3VsZCBtYWtlIHRoZSB3aG9sZS1jaGVja3BvaW50IGNsb25lIHRocm93XG4gKiBgRGF0YUNsb25lRXJyb3JgIOKAlCBzd2FsbG93aW5nIHRoZSBwYXVzZS5cbiAqXG4gKiBUaGF0IHZpb2xhdGVzIHRoZSBsaWJyYXJ5J3MgZXJyb3ItaXNvbGF0aW9uIGdyYWluOiBvYnNlcnZhYmlsaXR5IHNpZGUtYmFnc1xuICogbmV2ZXIgYWJvcnQgdHJhdmVyc2FsIGFueXdoZXJlIGVsc2UuIFRoZXNlIGhlbHBlcnMgcmVzdG9yZSB0aGUgZ3JhaW46XG4gKlxuICogICAtIGBzYW5pdGl6ZURpYWdub3N0aWNCYWdzYCDigJQgcmVwbGFjZSBub24tY2xvbmVhYmxlIGRpYWdub3N0aWMgdmFsdWVzIHdpdGhcbiAqICAgICBtYXJrZXIgc3RyaW5ncyAoYCdbbm9uLXNlcmlhbGl6YWJsZTogZnVuY3Rpb25dJ2ApIHNvIHRoZSBwYXVzZSBzdXJ2aXZlcy5cbiAqICAgLSBgZGVzY3JpYmVDaGVja3BvaW50Q2xvbmVGYWlsdXJlYCDigJQgd2hlbiB0aGUgY2xvbmUgU1RJTEwgZmFpbHMgYWZ0ZXJcbiAqICAgICBzYW5pdGl6YXRpb24gKHRoZSBub24tY2xvbmVhYmxlIGxpdmVzIGluIGNvbnN1bWVyLW93bmVkIGRhdGEsIGUuZy5cbiAqICAgICBgcGF1c2VEYXRhYCksIG5hbWUgdGhlIG9mZmVuZGluZyBjaGVja3BvaW50IGZpZWxkKHMpIGFuZCBwb2ludCBhdCB0aGVcbiAqICAgICBKU09OLXNhZmUgY29udHJhY3QgaW5zdGVhZCBvZiBsZXR0aW5nIGEgbmFrZWQgYERhdGFDbG9uZUVycm9yYCBlc2NhcGUuXG4gKlxuICogQm90aCBydW4gT05MWSBvbiB0aGUgY2xvbmUtZmFpbHVyZSBwYXRoIG9mIGEgcGF1c2Ug4oCUIG5ldmVyIG9uIHRoZSBob3QgcGF0aC5cbiAqL1xuXG5pbXBvcnQgdHlwZSB7IFN0YWdlU25hcHNob3QgfSBmcm9tICcuLi9tZW1vcnkvdHlwZXMuanMnO1xuXG4vKiogVGhlIFN0YWdlU25hcHNob3QgZmllbGRzIHdyaXR0ZW4gYnkgYCRkZWJ1Z2AvYCRlcnJvcmAvYCRtZXRyaWNgL2AkZXZhbGAuICovXG5jb25zdCBESUFHTk9TVElDX0JBR1MgPSBbJ2xvZ3MnLCAnZXJyb3JzJywgJ21ldHJpY3MnLCAnZXZhbHMnXSBhcyBjb25zdDtcblxuLyoqIGB0cnVlYCB3aGVuIGBzdHJ1Y3R1cmVkQ2xvbmVgIGFjY2VwdHMgdGhlIHZhbHVlIGFzLWlzLiAqL1xuZnVuY3Rpb24gaXNDbG9uZWFibGUodmFsdWU6IHVua25vd24pOiBib29sZWFuIHtcbiAgdHJ5IHtcbiAgICBzdHJ1Y3R1cmVkQ2xvbmUodmFsdWUpO1xuICAgIHJldHVybiB0cnVlO1xuICB9IGNhdGNoIHtcbiAgICByZXR1cm4gZmFsc2U7XG4gIH1cbn1cblxuLyoqIEh1bWFuLXJlYWRhYmxlIGtpbmQgZm9yIHRoZSBgW25vbi1zZXJpYWxpemFibGU6IOKApl1gIG1hcmtlci4gKi9cbmZ1bmN0aW9uIGRlc2NyaWJlS2luZCh2YWx1ZTogdW5rbm93bik6IHN0cmluZyB7XG4gIGlmICh2YWx1ZSA9PT0gbnVsbCkgcmV0dXJuICdudWxsJztcbiAgaWYgKHR5cGVvZiB2YWx1ZSAhPT0gJ29iamVjdCcpIHJldHVybiB0eXBlb2YgdmFsdWU7XG4gIHJldHVybiB2YWx1ZS5jb25zdHJ1Y3Rvcj8ubmFtZSA/PyAnb2JqZWN0Jztcbn1cblxuLyoqIFBsYWluIGRhdGEgY29udGFpbmVyIHdlIGNhbiByZWJ1aWxkIGVudHJ5LWJ5LWVudHJ5IHdpdGhvdXQgbHlpbmcgYWJvdXQgdGhlIHR5cGUuICovXG5mdW5jdGlvbiBpc1BsYWluT2JqZWN0KHZhbHVlOiBvYmplY3QpOiBib29sZWFuIHtcbiAgY29uc3QgcHJvdG8gPSBPYmplY3QuZ2V0UHJvdG90eXBlT2YodmFsdWUpIGFzIG9iamVjdCB8IG51bGw7XG4gIHJldHVybiBwcm90byA9PT0gT2JqZWN0LnByb3RvdHlwZSB8fCBwcm90byA9PT0gbnVsbDtcbn1cblxuLyoqXG4gKiBEZWVwLXJlcGxhY2Ugbm9uLWNsb25lYWJsZSB2YWx1ZXMgd2l0aCBgJ1tub24tc2VyaWFsaXphYmxlOiA8a2luZD5dJ2BcbiAqIG1hcmtlciBzdHJpbmdzLCBwcmVzZXJ2aW5nIGV2ZXJ5dGhpbmcgYHN0cnVjdHVyZWRDbG9uZWAgYWNjZXB0cy5cbiAqXG4gKiBGYXN0IHBhdGg6IGEgY2xvbmVhYmxlIHZhbHVlIGlzIHJldHVybmVkIEFTLUlTIChubyBjb3B5IOKAlCB0aGUgY2FsbGVyXG4gKiBjbG9uZXMgdGhlIHdob2xlIGNoZWNrcG9pbnQgcmlnaHQgYWZ0ZXIpLiBPbmx5IGNvbnRhaW5lcnMgdGhhdCBhY3R1YWxseVxuICogaG9sZCBhIG5vbi1jbG9uZWFibGUgbGVhZiBhcmUgcmVidWlsdCwgYW5kIG9ubHkgS05PV04gY29udGFpbmVyIHNoYXBlc1xuICogKGFycmF5IC8gTWFwIC8gU2V0IC8gcGxhaW4gb2JqZWN0KSBhcmUgcmVidWlsdCBlbnRyeS1ieS1lbnRyeSDigJQgZXhvdGljXG4gKiBub24tY2xvbmVhYmxlcyAoUHJvbWlzZSwgV2Vha01hcCwgY2xhc3MgaW5zdGFuY2VzIGhvbGRpbmcgYSBmdW5jdGlvbiwg4oCmKVxuICogYmVjb21lIGEgdHlwZWQgbWFya2VyIHJhdGhlciB0aGFuIGEgbWlzbGVhZGluZyBlbXB0eSBzaGVsbC4gUHVyZSBjeWNsZXNcbiAqIHBhc3MgdGhlIGZhc3QgcGF0aCB1bnRvdWNoZWQgKGBzdHJ1Y3R1cmVkQ2xvbmVgIHN1cHBvcnRzIHRoZW0pOyBhIGN5Y2xlXG4gKiBpcyBvbmx5IGJyb2tlbiDigJQgd2l0aCBhIG1hcmtlciDigJQgd2hlbiBpdCBzaGFyZXMgYSBjb250YWluZXIgd2l0aCBhXG4gKiBub24tY2xvbmVhYmxlIHZhbHVlLlxuICovXG5mdW5jdGlvbiBzYW5pdGl6ZVZhbHVlKHZhbHVlOiB1bmtub3duLCBzZWVuOiBXZWFrU2V0PG9iamVjdD4pOiB1bmtub3duIHtcbiAgaWYgKGlzQ2xvbmVhYmxlKHZhbHVlKSkgcmV0dXJuIHZhbHVlO1xuICBpZiAodmFsdWUgIT09IG51bGwgJiYgdHlwZW9mIHZhbHVlID09PSAnb2JqZWN0Jykge1xuICAgIGlmIChzZWVuLmhhcyh2YWx1ZSkpIHJldHVybiAnW25vbi1zZXJpYWxpemFibGU6IGNpcmN1bGFyXSc7XG4gICAgc2Vlbi5hZGQodmFsdWUpO1xuICAgIGlmIChBcnJheS5pc0FycmF5KHZhbHVlKSkge1xuICAgICAgcmV0dXJuIHZhbHVlLm1hcCgodikgPT4gc2FuaXRpemVWYWx1ZSh2LCBzZWVuKSk7XG4gICAgfVxuICAgIGlmICh2YWx1ZSBpbnN0YW5jZW9mIE1hcCkge1xuICAgICAgcmV0dXJuIG5ldyBNYXAoWy4uLnZhbHVlXS5tYXAoKFtrLCB2XSkgPT4gW3Nhbml0aXplVmFsdWUoaywgc2VlbiksIHNhbml0aXplVmFsdWUodiwgc2VlbildKSk7XG4gICAgfVxuICAgIGlmICh2YWx1ZSBpbnN0YW5jZW9mIFNldCkge1xuICAgICAgcmV0dXJuIG5ldyBTZXQoWy4uLnZhbHVlXS5tYXAoKHYpID0+IHNhbml0aXplVmFsdWUodiwgc2VlbikpKTtcbiAgICB9XG4gICAgaWYgKGlzUGxhaW5PYmplY3QodmFsdWUpKSB7XG4gICAgICByZXR1cm4gT2JqZWN0LmZyb21FbnRyaWVzKE9iamVjdC5lbnRyaWVzKHZhbHVlKS5tYXAoKFtrLCB2XSkgPT4gW2ssIHNhbml0aXplVmFsdWUodiwgc2VlbildKSk7XG4gICAgfVxuICB9XG4gIHJldHVybiBgW25vbi1zZXJpYWxpemFibGU6ICR7ZGVzY3JpYmVLaW5kKHZhbHVlKX1dYDtcbn1cblxuLyoqXG4gKiBXYWxrIGEgYFN0YWdlU25hcHNob3RgIHRyZWUgKHZpYSBgbmV4dGAgKyBgY2hpbGRyZW5gKSBhbmQgc2FuaXRpemUgdGhlIGZvdXJcbiAqIGRpYWdub3N0aWMgYmFncyBvbiBldmVyeSBub2RlIElOIFBMQUNFLlxuICpcbiAqIEluLXBsYWNlIGlzIHNhZmUgYW5kIGludGVudGlvbmFsOiBgU3RhZ2VDb250ZXh0LmdldFNuYXBzaG90KClgIGJ1aWxkcyBmcmVzaFxuICogbm9kZSBvYmplY3RzIG9uIGV2ZXJ5IGNhbGwsIGJ1dCB0aGUgYmFnIGZpZWxkcyBvbiB0aG9zZSBmcmVzaCBub2RlcyBBTElBU1xuICogdGhlIGxpdmUgYERpYWdub3N0aWNDb2xsZWN0b3JgIGJhZ3MuIFdlIHJlcGxhY2UgdGhlIG5vZGUncyBiYWcgUkVGRVJFTkNFXG4gKiB3aXRoIGEgc2FuaXRpemVkIGNvcHkg4oCUIHRoZSBsaXZlIGVuZ2luZSBiYWdzIGFyZSBuZXZlciBtdXRhdGVkLCBzbyBhXG4gKiBzYW1lLWV4ZWN1dG9yIHJlc3VtZSBrZWVwcyB0aGUgb3JpZ2luYWwgZGlhZ25vc3RpYyB2YWx1ZXMuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBzYW5pdGl6ZURpYWdub3N0aWNCYWdzKHRyZWU6IFN0YWdlU25hcHNob3QpOiBTdGFnZVNuYXBzaG90IHtcbiAgY29uc3Qgc2VlbiA9IG5ldyBXZWFrU2V0PG9iamVjdD4oKTtcbiAgY29uc3QgdmlzaXQgPSAobm9kZTogU3RhZ2VTbmFwc2hvdCk6IHZvaWQgPT4ge1xuICAgIGZvciAoY29uc3QgYmFnIG9mIERJQUdOT1NUSUNfQkFHUykge1xuICAgICAgY29uc3QgYmFnVmFsdWUgPSBub2RlW2JhZ107XG4gICAgICBpZiAoYmFnVmFsdWUgIT09IHVuZGVmaW5lZCAmJiAhaXNDbG9uZWFibGUoYmFnVmFsdWUpKSB7XG4gICAgICAgIG5vZGVbYmFnXSA9IHNhbml0aXplVmFsdWUoYmFnVmFsdWUsIHNlZW4pIGFzIFJlY29yZDxzdHJpbmcsIHVua25vd24+O1xuICAgICAgfVxuICAgIH1cbiAgICBpZiAobm9kZS5uZXh0KSB2aXNpdChub2RlLm5leHQpO1xuICAgIGlmIChub2RlLmNoaWxkcmVuKSBmb3IgKGNvbnN0IGNoaWxkIG9mIG5vZGUuY2hpbGRyZW4pIHZpc2l0KGNoaWxkKTtcbiAgfTtcbiAgdmlzaXQodHJlZSk7XG4gIHJldHVybiB0cmVlO1xufVxuXG4vKipcbiAqIEJ1aWxkIHRoZSBERVNDUklQVElWRSBlcnJvciBmb3IgYSBjaGVja3BvaW50IHRoYXQgc3RpbGwgY2Fubm90IGJlIGNsb25lZFxuICogYWZ0ZXIgZGlhZ25vc3RpYy1iYWcgc2FuaXRpemF0aW9uIOKAlCBpLmUuIHRoZSBub24tY2xvbmVhYmxlIHZhbHVlIGxpdmVzIGluXG4gKiBjb25zdW1lci1vd25lZCBkYXRhIChhIGdlbnVpbmUgSlNPTi1zYWZlIGNvbnRyYWN0IHZpb2xhdGlvbikuIFByb2JlcyBlYWNoXG4gKiB0b3AtbGV2ZWwgY2hlY2twb2ludCBmaWVsZCBpbmRpdmlkdWFsbHkgc28gdGhlIG1lc3NhZ2UgbmFtZXMgdGhlIG9mZmVuZGluZ1xuICogZmllbGQgZmFtaWx5LiBOZXZlciBsZXRzIGEgbmFrZWQgYERhdGFDbG9uZUVycm9yYCBlc2NhcGUuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBkZXNjcmliZUNoZWNrcG9pbnRDbG9uZUZhaWx1cmUoY2hlY2twb2ludDogUmVjb3JkPHN0cmluZywgdW5rbm93bj4sIGNhdXNlOiB1bmtub3duKTogRXJyb3Ige1xuICBjb25zdCBmYWlsaW5nID0gT2JqZWN0LmVudHJpZXMoY2hlY2twb2ludClcbiAgICAuZmlsdGVyKChbLCB2YWx1ZV0pID0+ICFpc0Nsb25lYWJsZSh2YWx1ZSkpXG4gICAgLm1hcCgoW2ZpZWxkXSkgPT4gZmllbGQpO1xuICBjb25zdCBmaWVsZHMgPSBmYWlsaW5nLmxlbmd0aCA+IDAgPyBmYWlsaW5nLmpvaW4oJywgJykgOiAndW5rbm93bic7XG4gIHJldHVybiBuZXcgRXJyb3IoXG4gICAgJ0Zsb3dDaGFydEV4ZWN1dG9yOiBjYW5ub3QgYnVpbGQgdGhlIHBhdXNlIGNoZWNrcG9pbnQg4oCUIG5vbi1zZXJpYWxpemFibGUgdmFsdWUocykgaW4gJyArXG4gICAgICBgY2hlY2twb2ludCBmaWVsZChzKTogJHtmaWVsZHN9LiBUaGUgY2hlY2twb2ludCBjb250cmFjdCBpcyBKU09OLXNhZmUgKG5vIGZ1bmN0aW9ucywgbm8gYCArXG4gICAgICBcImNsYXNzIGluc3RhbmNlcykuIENoZWNrIHRoZSBwYXVzZURhdGEgcmV0dXJuZWQgYnkgdGhlIHBhdXNhYmxlIHN0YWdlJ3MgZXhlY3V0ZSgpLCBhbmQgYW55IFwiICtcbiAgICAgICdzdWJmbG93IHN0YXRlIGNhcHR1cmVkIGF0IHRoZSBwYXVzZS4gRGlhZ25vc3RpYyB2YWx1ZXMgZnJvbSAkZGVidWcvJG1ldHJpYy8kZXJyb3IvJGV2YWwgJyArXG4gICAgICAnYXJlIHNhbml0aXplZCBhdXRvbWF0aWNhbGx5IGFuZCBuZXZlciBjYXVzZSB0aGlzIGVycm9yLiAnICtcbiAgICAgICdTZWUgZG9jcy9ndWlkZXMvZXhlY3V0aW9uLW1vZGVsLm1kIChcIlBhdXNlIC8gcmVzdW1lIOKAlCB3aGF0IGEgY2hlY2twb2ludCBjYXB0dXJlc1wiKS4nLFxuICAgIHsgY2F1c2UgfSxcbiAgKTtcbn1cbiJdfQ==

package/dist/types/lib/memory/StageContext.d.ts

@@ -66,7 +66,9 @@ export declare class StageContext {
     useRedactedMirror(mirror: SharedMemory): void;
     /** Returns the redacted mirror if installed, else undefined. */
     getRedactedSharedMemory(): SharedMemory | undefined;
-    /** Lazily creates the transaction buffer (pay clone cost only if stage writes). */
+    /** Lazily creates the transaction buffer on the stage's FIRST state access —
+     *  reads included, so read-only stages currently pay the clone cost too.
+     *  (Truly lazy-on-write is backlog Phase-3 #13.) */
     getTransactionBuffer(): TransactionBuffer;
     /** Builds an absolute path inside the shared memory (run namespace). */
     private withNamespace;

package/dist/types/lib/runner/FlowChartExecutor.d.ts

@@ -107,6 +107,16 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * scope. See `test/lib/pause/cross-executor-resume.test.ts`.
      */
     private _hasRunBefore;
+    /**
+     * Re-entrancy guard. `run()` and `resume()` mutate per-run instance state
+     * (traverser, runId, execution counter, checkpoint) and clear attached
+     * recorders — a second concurrent entry on the SAME executor would
+     * interleave runIds and cross-contaminate recorder/narrative state, and
+     * `getCheckpoint()` would return whichever run paused last. One executor =
+     * one in-flight execution; create an executor per concurrent run.
+     * See docs/guides/execution-model.md.
+     */
+    private _isExecuting;
     private readonly flowChartArgs;
     /**
      * Create a FlowChartExecutor.
@@ -143,6 +153,11 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      *
      * The checkpoint is JSON-serializable — store it in Redis, Postgres, localStorage, etc.
      *
+     * It is fully DETACHED from engine state: every field was deep-copied at
+     * pause time (see `buildPauseCheckpoint`). Holding, mutating, or persisting
+     * it cannot affect the executor, and a later same-executor resume cannot
+     * mutate a checkpoint you already stored.
+     *
      * @example
      * ```typescript
      * const result = await executor.run({ input });
@@ -198,6 +213,47 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * ```
      */
     resume(checkpoint: FlowchartCheckpoint, resumeInput?: unknown, options?: Pick<RunOptions, 'signal' | 'env' | 'maxDepth'>): Promise<ExecutorResult>;
+    /**
+     * Build a fully DETACHED checkpoint from a caught PauseSignal.
+     *
+     * Every field is deep-copied via one `structuredClone` of the assembled
+     * checkpoint, because the raw pieces alias live engine state:
+     *
+     *   - `sharedState` IS `SharedMemory`'s internal context object — the alias
+     *     only detaches at the next commit (`applySmartMerge` rebuilds it), and
+     *     after a pause there is no next commit until resume.
+     *   - `executionTree` nodes are fresh, but their `logs`/`errors`/`metrics`/
+     *     `evals`/`stageReads`/`flowMessages` fields reference live
+     *     `DiagnosticCollector` bags that keep accumulating on same-executor
+     *     resume.
+     *   - `subflowStates` values are shallow copies whose NESTED objects alias
+     *     subflow memory, and they get seeded back into live runtimes on resume.
+     *   - `subflowResults` values stay referenced by the traverser's results map.
+     *
+     * The checkpoint is persisted by contract ("store in Redis/Postgres") — it
+     * must never share structure with the engine. Pause is not a hot path; the
+     * clone cost is irrelevant.
+     *
+     * The JSON-safe checkpoint contract (no functions, no class instances)
+     * governs CONSUMER-owned data — but the executionTree's diagnostic bags
+     * accept ANY value at write time without cloning ($debug/$error/$metric/
+     * $eval store raw references), so a contract-compliant run can still carry
+     * a non-cloneable diagnostic. Observability side-bags never abort traversal
+     * anywhere else in the library, so they must not abort the pause either:
+     * on clone failure we sanitize the diagnostic bags (non-cloneable values
+     * become '[non-serializable: …]' markers — the live engine bags are never
+     * touched) and retry. If the retry STILL fails, the violation is in
+     * consumer-owned data (realistically `pauseData` — a function in shared
+     * state already rejects at stage entry when TransactionBuffer clones the
+     * context) and we throw a DESCRIPTIVE contract error naming the offending
+     * checkpoint field(s). A naked DataCloneError never escapes.
+     *
+     * Subflow scope capture (`subflowStates`) survives ONLY on the signal — the
+     * nested runtimes are GC'd as the stack unwinds. Promoting it onto the
+     * checkpoint here lets cross-executor resume restore pre-pause subflow
+     * scope (e.g. an Agent's `scope.history`). Empty `{}` for root-level pauses.
+     */
+    private buildPauseCheckpoint;
     /**
      * Find a StageNode in the compiled graph by ID.
      * Handles subflow paths by drilling into registered subflows.
@@ -395,6 +451,11 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      *
      *   The commit log is already redacted at write-time regardless of this
      *   flag, and the execution tree carries only structural metadata.
+     *
+     * **Treat `sharedState` as READ-ONLY.** In production it is a live view of
+     * the engine's working memory (zero copy cost) — mutating it corrupts
+     * engine state. In dev mode (`enableDevMode()`) it is a deep-frozen CLONE,
+     * so any consumer mutation throws loudly instead of corrupting silently.
      */
     getSnapshot(options?: {
         redact?: boolean;

package/dist/types/lib/runner/checkpointSanitize.d.ts

@@ -0,0 +1,44 @@
+/**
+ * checkpointSanitize — clone-resilience helpers for `buildPauseCheckpoint`.
+ *
+ * The pause checkpoint is detached via one `structuredClone` of the assembled
+ * checkpoint. The JSON-safe contract governs what CONSUMERS put into a
+ * checkpoint (pauseData, shared state) — but the execution tree's diagnostic
+ * bags (`logs`/`errors`/`metrics`/`evals`) accept ANY value at write time
+ * without cloning (`$debug`/`$error`/`$metric`/`$eval` route through
+ * `DiagnosticCollector`, which stores raw references). A `$debug`'d function
+ * in any stage of a pausing run would make the whole-checkpoint clone throw
+ * `DataCloneError` — swallowing the pause.
+ *
+ * That violates the library's error-isolation grain: observability side-bags
+ * never abort traversal anywhere else. These helpers restore the grain:
+ *
+ *   - `sanitizeDiagnosticBags` — replace non-cloneable diagnostic values with
+ *     marker strings (`'[non-serializable: function]'`) so the pause survives.
+ *   - `describeCheckpointCloneFailure` — when the clone STILL fails after
+ *     sanitization (the non-cloneable lives in consumer-owned data, e.g.
+ *     `pauseData`), name the offending checkpoint field(s) and point at the
+ *     JSON-safe contract instead of letting a naked `DataCloneError` escape.
+ *
+ * Both run ONLY on the clone-failure path of a pause — never on the hot path.
+ */
+import type { StageSnapshot } from '../memory/types.js';
+/**
+ * Walk a `StageSnapshot` tree (via `next` + `children`) and sanitize the four
+ * diagnostic bags on every node IN PLACE.
+ *
+ * In-place is safe and intentional: `StageContext.getSnapshot()` builds fresh
+ * node objects on every call, but the bag fields on those fresh nodes ALIAS
+ * the live `DiagnosticCollector` bags. We replace the node's bag REFERENCE
+ * with a sanitized copy — the live engine bags are never mutated, so a
+ * same-executor resume keeps the original diagnostic values.
+ */
+export declare function sanitizeDiagnosticBags(tree: StageSnapshot): StageSnapshot;
+/**
+ * Build the DESCRIPTIVE error for a checkpoint that still cannot be cloned
+ * after diagnostic-bag sanitization — i.e. the non-cloneable value lives in
+ * consumer-owned data (a genuine JSON-safe contract violation). Probes each
+ * top-level checkpoint field individually so the message names the offending
+ * field family. Never lets a naked `DataCloneError` escape.
+ */
+export declare function describeCheckpointCloneFailure(checkpoint: Record<string, unknown>, cause: unknown): Error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "8.0.0",
+  "version": "8.2.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -53,7 +53,11 @@
     "lint:fix": "eslint '{src,test}/**/*.ts' --ext .ts --fix",
     "format:fix": "prettier --config .prettierrc.js --write '{src,test}/**/*.ts'",
     "format": "prettier --config .prettierrc.js --list-different '{src,test}/**/*.ts'",
-    "bench": "npx tsx bench/run.ts",
+    "bench": "npm run bench:micro && npm run bench:baseline && npm run bench:depth",
+    "bench:micro": "npx tsx bench/run.ts",
+    "bench:baseline": "npx tsx bench/baseline.ts",
+    "bench:depth": "npx tsx bench/depth-probe.ts",
+    "bench:typecheck": "tsc -p bench/tsconfig.json",
     "docs": "typedoc",
     "docs:serve": "typedoc && npx serve docs",
     "test:coverage": "vitest run --coverage --coverage.reporter=json-summary --coverage.reporter=text-summary --coverage.reportsDirectory=coverage",