footprintjs 10.0.1 → 10.2.0

package/dist/esm/lib/filter/evaluator.js

@@ -0,0 +1,135 @@
+/**
+ * filter/evaluator -- Prisma-style filter evaluator for decision rules.
+ *
+ * Pure function. Takes a WhereFilter, a value getter, and a redaction checker.
+ * Evaluates each condition, records the result, returns matched/conditions.
+ *
+ * All keys in the filter are ANDed (all must match for the rule to match).
+ * Decoupled from ScopeFacade — receives callbacks, not scope.
+ *
+ * A LEAF module of its own (P2, 10.1): `decide()` (decide/) and the attempt rule table (attempt/decision.ts) share
+ * this one law, and neither may reach the other's dependencies through it. In decide/ it made `attempt/` reach
+ * `scope/` (decide.ts imports the scope runtime), so a `scope → attempt` edge — `scope.$call` — closed a module
+ * cycle.
+ */
+import { summarizeValue } from '../capture/summarize.js';
+import { isDevMode } from '../devMode.js';
+import { SCOPE_PLACEHOLDER } from '../memory/redaction.js';
+const OPERATOR_HANDLERS = {
+    eq: (a, t) => a === t,
+    ne: (a, t) => a !== t,
+    gt: (a, t) => a > t,
+    gte: (a, t) => a >= t,
+    lt: (a, t) => a < t,
+    lte: (a, t) => a <= t,
+    in: (a, t) => {
+        if (!Array.isArray(t))
+            return false;
+        if (t.length > MAX_IN_ARRAY_SIZE) {
+            throw new Error(`in/notIn array exceeds maximum size of ${MAX_IN_ARRAY_SIZE}`);
+        }
+        return t.includes(a);
+    },
+    notIn: (a, t) => {
+        if (!Array.isArray(t))
+            return true; // not in a non-array = vacuously true
+        if (t.length > MAX_IN_ARRAY_SIZE) {
+            throw new Error(`in/notIn array exceeds maximum size of ${MAX_IN_ARRAY_SIZE}`);
+        }
+        return !t.includes(a);
+    },
+};
+// -- Security: prototype pollution denylist ----------------------------------
+const DENIED_KEYS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+    'toString',
+    'valueOf',
+    'hasOwnProperty',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+    '__defineGetter__',
+    '__defineSetter__',
+    '__lookupGetter__',
+    '__lookupSetter__',
+]);
+// -- Constants ---------------------------------------------------------------
+const MAX_IN_ARRAY_SIZE = 1000;
+const MAX_VALUE_LEN = 80;
+// -- Evaluator ---------------------------------------------------------------
+/**
+ * Evaluates a Prisma-style filter against scope values.
+ *
+ * ## Empty filter → NO match (anti-vacuous-truth — inverts Prisma/SQL)
+ *
+ * A filter with no evaluable conditions (`{}`, or only denied/non-object
+ * keys) returns `matched: false`. This deliberately INVERTS the Prisma/SQL
+ * intuition where `where: {}` matches everything: in a decision rule, a rule
+ * that asserts nothing should never win a branch — "all zero conditions
+ * passed" is vacuous truth, and silently routing on it would fabricate
+ * decision evidence. Want a catch-all? Use the explicit `defaultBranch`
+ * argument of `decide()` instead of an empty `when`.
+ *
+ * ## Unknown operators → condition fails (+ dev-mode warning)
+ *
+ * An operator outside the supported set (`eq, ne, gt, gte, lt, lte, in,
+ * notIn`) records a failed condition — the rule can never spuriously match
+ * through a typo (`gte` misspelled `gle`). With dev mode enabled
+ * (`enableDevMode()`), a console warning names the unknown operator and key.
+ *
+ * @param getValueFn - Reads a value from scope by key (raw, for comparison)
+ * @param isRedactedFn - Checks if a key is redacted (for evidence display)
+ * @param filter - The WhereFilter to evaluate
+ * @returns { matched, conditions } — matched = all conditions passed
+ */
+export function evaluateFilter(getValueFn, isRedactedFn, filter) {
+    const conditions = [];
+    let allMatched = true;
+    for (const [key, ops] of Object.entries(filter)) {
+        // Security: denied keys cause rule to fail (consistent with unknown operator behavior)
+        if (DENIED_KEYS.has(key)) {
+            allMatched = false;
+            continue;
+        }
+        if (!ops || typeof ops !== 'object')
+            continue;
+        const actual = getValueFn(key);
+        const redacted = isRedactedFn(key);
+        const displayValue = redacted ? SCOPE_PLACEHOLDER : summarizeValue(actual, MAX_VALUE_LEN);
+        // Evaluate each operator in the FilterOps for this key
+        for (const [op, threshold] of Object.entries(ops)) {
+            const handler = OPERATOR_HANDLERS[op];
+            if (!handler) {
+                // Unknown operator: treat as failed condition so rule doesn't spuriously match
+                if (isDevMode()) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[footprint] decide()/select() filter: unknown operator "${op}" on key "${key}" — ` +
+                        `condition never matches (valid operators: ${Object.keys(OPERATOR_HANDLERS).join(', ')})`);
+                }
+                conditions.push({ key, op, threshold, actualSummary: displayValue, result: false, redacted });
+                allMatched = false;
+                continue;
+            }
+            const result = handler(actual, threshold);
+            conditions.push({
+                key,
+                op,
+                threshold,
+                actualSummary: displayValue,
+                result,
+                redacted,
+            });
+            if (!result)
+                allMatched = false;
+        }
+    }
+    // Empty filter (no evaluable conditions) should NOT match — prevents vacuous
+    // truth. NOTE: this deliberately inverts Prisma/SQL `where: {}` ("match
+    // everything") — see the function JSDoc. Catch-alls belong in decide()'s
+    // explicit defaultBranch, not in an empty rule.
+    if (conditions.length === 0)
+        return { matched: false, conditions };
+    return { matched: allMatched, conditions };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXZhbHVhdG9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL2xpYi9maWx0ZXIvZXZhbHVhdG9yLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7O0dBYUc7QUFFSCxPQUFPLEVBQUUsY0FBYyxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFFekQsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLGVBQWUsQ0FBQztBQUMxQyxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQU0zRCxNQUFNLGlCQUFpQixHQUErQjtJQUNwRCxFQUFFLEVBQUUsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDLEtBQUssQ0FBQztJQUNyQixFQUFFLEVBQUUsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDLEtBQUssQ0FBQztJQUNyQixFQUFFLEVBQUUsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBRSxDQUFZLEdBQUksQ0FBWTtJQUMzQyxHQUFHLEVBQUUsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBRSxDQUFZLElBQUssQ0FBWTtJQUM3QyxFQUFFLEVBQUUsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBRSxDQUFZLEdBQUksQ0FBWTtJQUMzQyxHQUFHLEVBQUUsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FBRSxDQUFZLElBQUssQ0FBWTtJQUM3QyxFQUFFLEVBQUUsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEVBQUU7UUFDWCxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDLENBQUM7WUFBRSxPQUFPLEtBQUssQ0FBQztRQUNwQyxJQUFJLENBQUMsQ0FBQyxNQUFNLEdBQUcsaUJBQWlCLEVBQUUsQ0FBQztZQUNqQyxNQUFNLElBQUksS0FBSyxDQUFDLDBDQUEwQyxpQkFBaUIsRUFB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LEtBQUssQ0FBQztnQkFDbkIsU0FBUztZQUNYLENBQUM7WUFFRCxNQUFNLE1BQU0sR0FBRyxPQUFPLENBQUMsTUFBTSxFQUFFLFNBQVMsQ0FBQyxDQUFDO1lBQzFDLFVBQVUsQ0FBQyxJQUFJLENBQUM7Z0JBQ2QsR0FBRztnQkFDSCxFQUFFO2dCQUNGLFNBQVM7Z0JBQ1QsYUFBYSxFQUFFLFlBQVk7Z0JBQzNCLE1BQU07Z0JBQ04sUUFBUTthQUNULENBQUMsQ0FBQztZQUVILElBQUksQ0FBQyxNQUFNO2dCQUFFLFVBQVUsR0FBRyxLQUFLLENBQUM7UUFDbEMsQ0FBQztJQUNILENBQUM7SUFFRCw2RUFBNkU7SUFDN0Usd0VBQXdFO0lBQ3hFLHlFQUF5RTtJQUN6RSxnREFBZ0Q7SUFDaEQsSUFBSSxVQUFVLENBQUMsTUFBTSxLQUFLLENBQUM7UUFBRSxPQUFPLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRSxVQUFVLEVBQUUsQ0FBQztJQUVuRSxPQUFPLEVBQUUsT0FBTyxFQUFFLFVBQVUsRUFBRSxVQUFVLEVBQUUsQ0FBQztBQUM3QyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBmaWx0ZXIvZXZhbHVhdG9yIC0tIFByaXNtYS1zdHlsZSBmaWx0ZXIgZXZhbHVhdG9yIGZvciBkZWNpc2lvbiBydWxlcy5cbiAqXG4gKiBQdXJlIGZ1bmN0aW9uLiBUYWtlcyBhIFdoZXJlRmlsdGVyLCBhIHZhbHVlIGdldHRlciwgYW5kIGEgcmVkYWN0aW9uIGNoZWNrZXIuXG4gKiBFdmFsdWF0ZXMgZWFjaCBjb25kaXRpb24sIHJlY29yZHMgdGhlIHJlc3VsdCwgcmV0dXJucyBtYXRjaGVkL2NvbmRpdGlvbnMuXG4gKlxuICogQWxsIGtleXMgaW4gdGhlIGZpbHRlciBhcmUgQU5EZWQgKGFsbCBtdXN0IG1hdGNoIGZvciB0aGUgcnVsZSB0byBtYXRjaCkuXG4gKiBEZWNvdXBsZWQgZnJvbSBTY29wZUZhY2FkZSDigJQgcmVjZWl2ZXMgY2FsbGJhY2tzLCBub3Qgc2NvcGUuXG4gKlxuICogQSBMRUFGIG1vZHVsZSBvZiBpdHMgb3duIChQMiwgMTAuMSk6IGBkZWNpZGUoKWAgKGRlY2lkZS8pIGFuZCB0aGUgYXR0ZW1wdCBydWxlIHRhYmxlIChhdHRlbXB0L2RlY2lzaW9uLnRzKSBzaGFyZVxuICogdGhpcyBvbmUgbGF3LCBhbmQgbmVpdGhlciBtYXkgcmVhY2ggdGhlIG90aGVyJ3MgZGVwZW5kZW5jaWVzIHRocm91Z2ggaXQuIEluIGRlY2lkZS8gaXQgbWFkZSBgYXR0ZW1wdC9gIHJlYWNoXG4gKiBgc2NvcGUvYCAoZGVjaWRlLnRzIGltcG9ydHMgdGhlIHNjb3BlIHJ1bnRpbWUpLCBzbyBhIGBzY29wZSDihpIgYXR0ZW1wdGAgZWRnZSDigJQgYHNjb3BlLiRjYWxsYCDigJQgY2xvc2VkIGEgbW9kdWxlXG4gKiBjeWNsZS5cbiAqL1xuXG5pbXBvcnQgeyBzdW1tYXJpemVWYWx1ZSB9IGZyb20gJy4uL2NhcHR1cmUvc3VtbWFyaXplLmpzJztcbmltcG9ydCB0eXBlIHsgRmlsdGVyQ29uZGl0aW9uLCBXaGVyZUZpbHRlciB9IGZyb20gJy4uL2RlY2lkZS90eXBlcy5qcyc7XG5pbXBvcnQgeyBpc0Rldk1vZGUgfSBmcm9tICcuLi9kZXZNb2RlLmpzJztcbmltcG9ydCB7IFNDT1BFX1BMQUNFSE9MREVSIH0gZnJvbSAnLi4vbWVtb3J5L3JlZGFjdGlvbi5qcyc7XG5cbi8vIC0tIE9wZXJhdG9yIGRpc3BhdGNoIHRhYmxlIC0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS1cblxudHlwZSBPcGVyYXRvckZuID0gKGFjdHVhbDogdW5rbm93biwgdGhyZXNob2xkOiB1bmtub3duKSA9PiBib29sZWFuO1xuXG5jb25zdCBPUEVSQVRPUl9IQU5ETEVSUzogUmVjb3JkPHN0cmluZywgT3BlcmF0b3JGbj4gPSB7XG4gIGVxOiAoYSwgdCkgPT4gYSA9PT0gdCxcbiAgbmU6IChhLCB0KSA9PiBhICE9PSB0LFxuICBndDogKGEsIHQpID0+IChhIGFzIG51bWJlcikgPiAodCBhcyBudW1iZXIpLFxuICBndGU6IChhLCB0KSA9PiAoYSBhcyBudW1iZXIpID49ICh0IGFzIG51bWJlciksXG4gIGx0OiAoYSwgdCkgPT4gKGEgYXMgbnVtYmVyKSA8ICh0IGFzIG51bWJlciksXG4gIGx0ZTogKGEsIHQpID0+IChhIGFzIG51bWJlcikgPD0gKHQgYXMgbnVtYmVyKSxcbiAgaW46IChhLCB0KSA9PiB7XG4gICAgaWYgKCFBcnJheS5pc0FycmF5KHQpKSByZXR1cm4gZmFsc2U7XG4gICAgaWYgKHQubGVuZ3RoID4gTUFYX0lOX0FSUkFZX1NJWkUpIHtcbiAgICAgIHRocm93IG5ldyBFcnJvcihgaW4vbm90SW4gYXJyYXkgZXhjZWVkcyBtYXhpbXVtIHNpemUgb2YgJHtNQVhfSU5fQVJSQVlfU0laRX1gKTtcbiAgICB9XG4gICAgcmV0dXJuIHQuaW5jbHVkZXMoYSk7XG4gIH0sXG4gIG5vdEluOiAoYSwgdCkgPT4ge1xuICAgIGlmICghQXJyYXkuaXNBcnJheSh0KSkgcmV0dXJuIHRydWU7IC8vIG5vdCBpbiBhIG5vbi1hcnJheSA9IHZhY3VvdXNseSB0cnVlXG4gICAgaWYgKHQubGVuZ3RoID4gTUFYX0lOX0FSUkFZX1NJWkUpIHtcbiAgICAgIHRocm93IG5ldyBFcnJvcihgaW4vbm90SW4gYXJyYXkgZXhjZWVkcyBtYXhpbXVtIHNpemUgb2YgJHtNQVhfSU5fQVJSQVlfU0laRX1gKTtcbiAgICB9XG4gICAgcmV0dXJuICF0LmluY2x1ZGVzKGEpO1xuICB9LFxufTtcblxuLy8gLS0gU2VjdXJpdHk6IHByb3RvdHlwZSBwb2xsdXRpb24gZGVueWxpc3QgLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLVxuXG5jb25zdCBERU5JRURfS0VZUyA9IG5ldyBTZXQoW1xuICAnX19wcm90b19fJyxcbiAgJ2NvbnN0cnVjdG9yJyxcbiAgJ3Byb3RvdHlwZScsXG4gICd0b1N0cmluZycsXG4gICd2YWx1ZU9mJyxcbiAgJ2hhc093blByb3BlcnR5JyxcbiAgJ2lzUHJvdG90eXBlT2YnLFxuICAncHJvcGVydHlJc0VudW1lcmFibGUnLFxuICAnX19kZWZpbmVHZXR0ZXJfXycsXG4gICdfX2RlZmluZVNldHRlcl9fJyxcbiAgJ19fbG9va3VwR2V0dGVyX18nLFxuICAnX19sb29rdXBTZXR0ZXJfXycsXG5dKTtcblxuLy8gLS0gQ29uc3RhbnRzIC0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLVxuXG5jb25zdCBNQVhfSU5fQVJSQVlfU0laRSA9IDEwMDA7XG5jb25zdCBNQVhfVkFMVUVfTEVOID0gODA7XG5cbi8vIC0tIEV2YWx1YXRvciAtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS1cblxuLyoqXG4gKiBFdmFsdWF0ZXMgYSBQcmlzbWEtc3R5bGUgZmlsdGVyIGFnYWluc3Qgc2NvcGUgdmFsdWVzLlxuICpcbiAqICMjIEVtcHR5IGZpbHRlciDihpIgTk8gbWF0Y2ggKGFudGktdmFjdW91cy10cnV0aCDigJQgaW52ZXJ0cyBQcmlzbWEvU1FMKVxuICpcbiAqIEEgZmlsdGVyIHdpdGggbm8gZXZhbHVhYmxlIGNvbmRpdGlvbnMgKGB7fWAsIG9yIG9ubHkgZGVuaWVkL25vbi1vYmplY3RcbiAqIGtleXMpIHJldHVybnMgYG1hdGNoZWQ6IGZhbHNlYC4gVGhpcyBkZWxpYmVyYXRlbHkgSU5WRVJUUyB0aGUgUHJpc21hL1NRTFxuICogaW50dWl0aW9uIHdoZXJlIGB3aGVyZToge31gIG1hdGNoZXMgZXZlcnl0aGluZzogaW4gYSBkZWNpc2lvbiBydWxlLCBhIHJ1bGVcbiAqIHRoYXQgYXNzZXJ0cyBub3RoaW5nIHNob3VsZCBuZXZlciB3aW4gYSBicmFuY2gg4oCUIFwiYWxsIHplcm8gY29uZGl0aW9uc1xuICogcGFzc2VkXCIgaXMgdmFjdW91cyB0cnV0aCwgYW5kIHNpbGVudGx5IHJvdXRpbmcgb24gaXQgd291bGQgZmFicmljYXRlXG4gKiBkZWNpc2lvbiBldmlkZW5jZS4gV2FudCBhIGNhdGNoLWFsbD8gVXNlIHRoZSBleHBsaWNpdCBgZGVmYXVsdEJyYW5jaGBcbiAqIGFyZ3VtZW50IG9mIGBkZWNpZGUoKWAgaW5zdGVhZCBvZiBhbiBlbXB0eSBgd2hlbmAuXG4gKlxuICogIyMgVW5rbm93biBvcGVyYXRvcnMg4oaSIGNvbmRpdGlvbiBmYWlscyAoKyBkZXYtbW9kZSB3YXJuaW5nKVxuICpcbiAqIEFuIG9wZXJhdG9yIG91dHNpZGUgdGhlIHN1cHBvcnRlZCBzZXQgKGBlcSwgbmUsIGd0LCBndGUsIGx0LCBsdGUsIGluLFxuICogbm90SW5gKSByZWNvcmRzIGEgZmFpbGVkIGNvbmRpdGlvbiDigJQgdGhlIHJ1bGUgY2FuIG5ldmVyIHNwdXJpb3VzbHkgbWF0Y2hcbiAqIHRocm91Z2ggYSB0eXBvIChgZ3RlYCBtaXNzcGVsbGVkIGBnbGVgKS4gV2l0aCBkZXYgbW9kZSBlbmFibGVkXG4gKiAoYGVuYWJsZURldk1vZGUoKWApLCBhIGNvbnNvbGUgd2FybmluZyBuYW1lcyB0aGUgdW5rbm93biBvcGVyYXRvciBhbmQga2V5LlxuICpcbiAqIEBwYXJhbSBnZXRWYWx1ZUZuIC0gUmVhZHMgYSB2YWx1ZSBmcm9tIHNjb3BlIGJ5IGtleSAocmF3LCBmb3IgY29tcGFyaXNvbilcbiAqIEBwYXJhbSBpc1JlZGFjdGVkRm4gLSBDaGVja3MgaWYgYSBrZXkgaXMgcmVkYWN0ZWQgKGZvciBldmlkZW5jZSBkaXNwbGF5KVxuICogQHBhcmFtIGZpbHRlciAtIFRoZSBXaGVyZUZpbHRlciB0byBldmFsdWF0ZVxuICogQHJldHVybnMgeyBtYXRjaGVkLCBjb25kaXRpb25zIH0g4oCUIG1hdGNoZWQgPSBhbGwgY29uZGl0aW9ucyBwYXNzZWRcbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGV2YWx1YXRlRmlsdGVyPFQgZXh0ZW5kcyBvYmplY3Q+KFxuICBnZXRWYWx1ZUZuOiAoa2V5OiBzdHJpbmcpID0+IHVua25vd24sXG4gIGlzUmVkYWN0ZWRGbjogKGtleTogc3RyaW5nKSA9PiBib29sZWFuLFxuICBmaWx0ZXI6IFdoZXJlRmlsdGVyPFQ+LFxuKTogeyBtYXRjaGVkOiBib29sZWFuOyBjb25kaXRpb25zOiBGaWx0ZXJDb25kaXRpb25bXSB9IHtcbiAgY29uc3QgY29uZGl0aW9uczogRmlsdGVyQ29uZGl0aW9uW10gPSBbXTtcbiAgbGV0IGFsbE1hdGNoZWQgPSB0cnVlO1xuXG4gIGZvciAoY29uc3QgW2tleSwgb3BzXSBvZiBPYmplY3QuZW50cmllcyhmaWx0ZXIpKSB7XG4gICAgLy8gU2VjdXJpdHk6IGRlbmllZCBrZXlzIGNhdXNlIHJ1bGUgdG8gZmFpbCAoY29uc2lzdGVudCB3aXRoIHVua25vd24gb3BlcmF0b3IgYmVoYXZpb3IpXG4gICAgaWYgKERFTklFRF9LRVlTLmhhcyhrZXkpKSB7XG4gICAgICBhbGxNYXRjaGVkID0gZmFsc2U7XG4gICAgICBjb250aW51ZTtcbiAgICB9XG4gICAgaWYgKCFvcHMgfHwgdHlwZW9mIG9wcyAhPT0gJ29iamVjdCcpIGNvbnRpbnVlO1xuXG4gICAgY29uc3QgYWN0dWFsID0gZ2V0VmFsdWVGbihrZXkpO1xuICAgIGNvbnN0IHJlZGFjdGVkID0gaXNSZWRhY3RlZEZuKGtleSk7XG4gICAgY29uc3QgZGlzcGxheVZhbHVlID0gcmVkYWN0ZWQgPyBTQ09QRV9QTEFDRUhPTERFUiA6IHN1bW1hcml6ZVZhbHVlKGFjdHVhbCwgTUFYX1ZBTFVFX0xFTik7XG5cbiAgICAvLyBFdmFsdWF0ZSBlYWNoIG9wZXJhdG9yIGluIHRoZSBGaWx0ZXJPcHMgZm9yIHRoaXMga2V5XG4gICAgZm9yIChjb25zdCBbb3AsIHRocmVzaG9sZF0gb2YgT2JqZWN0LmVudHJpZXMob3BzIGFzIFJlY29yZDxzdHJpbmcsIHVua25vd24+KSkge1xuICAgICAgY29uc3QgaGFuZGxlciA9IE9QRVJBVE9SX0hBTkRMRVJTW29wXTtcbiAgICAgIGlmICghaGFuZGxlcikge1xuICAgICAgICAvLyBVbmtub3duIG9wZXJhdG9yOiB0cmVhdCBhcyBmYWlsZWQgY29uZGl0aW9uIHNvIHJ1bGUgZG9lc24ndCBzcHVyaW91c2x5IG1hdGNoXG4gICAgICAgIGlmIChpc0Rldk1vZGUoKSkge1xuICAgICAgICAgIC8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBuby1jb25zb2xlXG4gICAgICAgICAgY29uc29sZS53YXJuKFxuICAgICAgICAgICAgYFtmb290cHJpbnRdIGRlY2lkZSgpL3NlbGVjdCgpIGZpbHRlcjogdW5rbm93biBvcGVyYXRvciBcIiR7b3B9XCIgb24ga2V5IFwiJHtrZXl9XCIg4oCUIGAgK1xuICAgICAgICAgICAgICBgY29uZGl0aW9uIG5ldmVyIG1hdGNoZXMgKHZhbGlkIG9wZXJhdG9yczogJHtPYmplY3Qua2V5cyhPUEVSQVRPUl9IQU5ETEVSUykuam9pbignLCAnKX0pYCxcbiAgICAgICAgICApO1xuICAgICAgICB9XG4gICAgICAgIGNvbmRpdGlvbnMucHVzaCh7IGtleSwgb3AsIHRocmVzaG9sZCwgYWN0dWFsU3VtbWFyeTogZGlzcGxheVZhbHVlLCByZXN1bHQ6IGZhbHNlLCByZWRhY3RlZCB9KTtcbiAgICAgICAgYWxsTWF0Y2hlZCA9IGZhbHNlO1xuICAgICAgICBjb250aW51ZTtcbiAgICAgIH1cblxuICAgICAgY29uc3QgcmVzdWx0ID0gaGFuZGxlcihhY3R1YWwsIHRocmVzaG9sZCk7XG4gICAgICBjb25kaXRpb25zLnB1c2goe1xuICAgICAgICBrZXksXG4gICAgICAgIG9wLFxuICAgICAgICB0aHJlc2hvbGQsXG4gICAgICAgIGFjdHVhbFN1bW1hcnk6IGRpc3BsYXlWYWx1ZSxcbiAgICAgICAgcmVzdWx0LFxuICAgICAgICByZWRhY3RlZCxcbiAgICAgIH0pO1xuXG4gICAgICBpZiAoIXJlc3VsdCkgYWxsTWF0Y2hlZCA9IGZhbHNlO1xuICAgIH1cbiAgfVxuXG4gIC8vIEVtcHR5IGZpbHRlciAobm8gZXZhbHVhYmxlIGNvbmRpdGlvbnMpIHNob3VsZCBOT1QgbWF0Y2gg4oCUIHByZXZlbnRzIHZhY3VvdXNcbiAgLy8gdHJ1dGguIE5PVEU6IHRoaXMgZGVsaWJlcmF0ZWx5IGludmVydHMgUHJpc21hL1NRTCBgd2hlcmU6IHt9YCAoXCJtYXRjaFxuICAvLyBldmVyeXRoaW5nXCIpIOKAlCBzZWUgdGhlIGZ1bmN0aW9uIEpTRG9jLiBDYXRjaC1hbGxzIGJlbG9uZyBpbiBkZWNpZGUoKSdzXG4gIC8vIGV4cGxpY2l0IGRlZmF1bHRCcmFuY2gsIG5vdCBpbiBhbiBlbXB0eSBydWxlLlxuICBpZiAoY29uZGl0aW9ucy5sZW5ndGggPT09IDApIHJldHVybiB7IG1hdGNoZWQ6IGZhbHNlLCBjb25kaXRpb25zIH07XG5cbiAgcmV0dXJuIHsgbWF0Y2hlZDogYWxsTWF0Y2hlZCwgY29uZGl0aW9ucyB9O1xufVxuIl19

package/dist/esm/lib/ids/idempotencyKey.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ids/idempotencyKey.ts — the ONE format rule for an idempotency key (design §3.3, packet P3). A leaf: the attempt
+ * law (`attempt/effect.ts · admitIdempotencyKey`, a key a stage's rule or a `$call` gives) and the checkpoint decoder
+ * (`pause/record.ts`, a key a paused execution carries to its resume) both ask it, so a key a stored checkpoint
+ * smuggles in is held to the same rule as one the code made.
+ *
+ * 1–255 printable ASCII characters (`\x21`–`\x7e`), no space: a key travels in a request header
+ * (`Idempotency-Key`), so a CR/LF could forge one, and 255 is Stripe's limit, inside every header limit. The
+ * problem names the rule, never the value.
+ */
+/** The longest idempotency key. */
+export declare const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+/** Why `value` is not an idempotency key, or `undefined` when it is one. */
+export declare function idempotencyKeyProblem(value: unknown): string | undefined;

package/dist/esm/lib/ids/idempotencyKey.js

@@ -0,0 +1,24 @@
+/**
+ * ids/idempotencyKey.ts — the ONE format rule for an idempotency key (design §3.3, packet P3). A leaf: the attempt
+ * law (`attempt/effect.ts · admitIdempotencyKey`, a key a stage's rule or a `$call` gives) and the checkpoint decoder
+ * (`pause/record.ts`, a key a paused execution carries to its resume) both ask it, so a key a stored checkpoint
+ * smuggles in is held to the same rule as one the code made.
+ *
+ * 1–255 printable ASCII characters (`\x21`–`\x7e`), no space: a key travels in a request header
+ * (`Idempotency-Key`), so a CR/LF could forge one, and 255 is Stripe's limit, inside every header limit. The
+ * problem names the rule, never the value.
+ */
+/** The longest idempotency key. */
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+const KEY_CHARACTERS = /^[\x21-\x7e]+$/;
+/** Why `value` is not an idempotency key, or `undefined` when it is one. */
+export function idempotencyKeyProblem(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+        return `must be a string of 1–${MAX_IDEMPOTENCY_KEY_LENGTH} characters`;
+    }
+    if (!KEY_CHARACTERS.test(value)) {
+        return 'must be printable ASCII with no space or control character — it travels in a request header';
+    }
+    return undefined;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaWRlbXBvdGVuY3lLZXkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvbGliL2lkcy9pZGVtcG90ZW5jeUtleS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7O0dBU0c7QUFFSCxtQ0FBbUM7QUFDbkMsTUFBTSxDQUFDLE1BQU0sMEJBQTBCLEdBQUcsR0FBRyxDQUFDO0FBRTlDLE1BQU0sY0FBYyxHQUFHLGdCQUFnQixDQUFDO0FBRXhDLDRFQUE0RTtBQUM1RSxNQUFNLFVBQVUscUJBQXFCLENBQUMsS0FBYztJQUNsRCxJQUFJLE9BQU8sS0FBSyxLQUFLLFFBQVEsSUFBSSxLQUFLLENBQUMsTUFBTSxLQUFLLENBQUMsSUFBSSxLQUFLLENBQUMsTUFBTSxHQUFHLDBCQUEwQixFQUFFLENBQUM7UUFDakcsT0FBTyx5QkFBeUIsMEJBQTBCLGFBQWEsQ0FBQztJQUMxRSxDQUFDO0lBQ0QsSUFBSSxDQUFDLGNBQWMsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQztRQUNoQyxPQUFPLDZGQUE2RixDQUFDO0lBQ3ZHLENBQUM7SUFDRCxPQUFPLFNBQVMsQ0FBQztBQUNuQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBpZHMvaWRlbXBvdGVuY3lLZXkudHMg4oCUIHRoZSBPTkUgZm9ybWF0IHJ1bGUgZm9yIGFuIGlkZW1wb3RlbmN5IGtleSAoZGVzaWduIMKnMy4zLCBwYWNrZXQgUDMpLiBBIGxlYWY6IHRoZSBhdHRlbXB0XG4gKiBsYXcgKGBhdHRlbXB0L2VmZmVjdC50cyDCtyBhZG1pdElkZW1wb3RlbmN5S2V5YCwgYSBrZXkgYSBzdGFnZSdzIHJ1bGUgb3IgYSBgJGNhbGxgIGdpdmVzKSBhbmQgdGhlIGNoZWNrcG9pbnQgZGVjb2RlclxuICogKGBwYXVzZS9yZWNvcmQudHNgLCBhIGtleSBhIHBhdXNlZCBleGVjdXRpb24gY2FycmllcyB0byBpdHMgcmVzdW1lKSBib3RoIGFzayBpdCwgc28gYSBrZXkgYSBzdG9yZWQgY2hlY2twb2ludFxuICogc211Z2dsZXMgaW4gaXMgaGVsZCB0byB0aGUgc2FtZSBydWxlIGFzIG9uZSB0aGUgY29kZSBtYWRlLlxuICpcbiAqIDHigJMyNTUgcHJpbnRhYmxlIEFTQ0lJIGNoYXJhY3RlcnMgKGBcXHgyMWDigJNgXFx4N2VgKSwgbm8gc3BhY2U6IGEga2V5IHRyYXZlbHMgaW4gYSByZXF1ZXN0IGhlYWRlclxuICogKGBJZGVtcG90ZW5jeS1LZXlgKSwgc28gYSBDUi9MRiBjb3VsZCBmb3JnZSBvbmUsIGFuZCAyNTUgaXMgU3RyaXBlJ3MgbGltaXQsIGluc2lkZSBldmVyeSBoZWFkZXIgbGltaXQuIFRoZVxuICogcHJvYmxlbSBuYW1lcyB0aGUgcnVsZSwgbmV2ZXIgdGhlIHZhbHVlLlxuICovXG5cbi8qKiBUaGUgbG9uZ2VzdCBpZGVtcG90ZW5jeSBrZXkuICovXG5leHBvcnQgY29uc3QgTUFYX0lERU1QT1RFTkNZX0tFWV9MRU5HVEggPSAyNTU7XG5cbmNvbnN0IEtFWV9DSEFSQUNURVJTID0gL15bXFx4MjEtXFx4N2VdKyQvO1xuXG4vKiogV2h5IGB2YWx1ZWAgaXMgbm90IGFuIGlkZW1wb3RlbmN5IGtleSwgb3IgYHVuZGVmaW5lZGAgd2hlbiBpdCBpcyBvbmUuICovXG5leHBvcnQgZnVuY3Rpb24gaWRlbXBvdGVuY3lLZXlQcm9ibGVtKHZhbHVlOiB1bmtub3duKTogc3RyaW5nIHwgdW5kZWZpbmVkIHtcbiAgaWYgKHR5cGVvZiB2YWx1ZSAhPT0gJ3N0cmluZycgfHwgdmFsdWUubGVuZ3RoID09PSAwIHx8IHZhbHVlLmxlbmd0aCA+IE1BWF9JREVNUE9URU5DWV9LRVlfTEVOR1RIKSB7XG4gICAgcmV0dXJuIGBtdXN0IGJlIGEgc3RyaW5nIG9mIDHigJMke01BWF9JREVNUE9URU5DWV9LRVlfTEVOR1RIfSBjaGFyYWN0ZXJzYDtcbiAgfVxuICBpZiAoIUtFWV9DSEFSQUNURVJTLnRlc3QodmFsdWUpKSB7XG4gICAgcmV0dXJuICdtdXN0IGJlIHByaW50YWJsZSBBU0NJSSB3aXRoIG5vIHNwYWNlIG9yIGNvbnRyb2wgY2hhcmFjdGVyIOKAlCBpdCB0cmF2ZWxzIGluIGEgcmVxdWVzdCBoZWFkZXInO1xuICB9XG4gIHJldHVybiB1bmRlZmluZWQ7XG59XG4iXX0=

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

@@ -13,12 +13,28 @@
  */
 import type { CommitPhase, EmitSourcePosition, UntrackedSource } from 'foottrace';
 import type { EventLog, SharedMemory } from 'foottrace/write';
+import type { AttemptContext, AttemptRecord, AttemptSummary, LateWrite } from '../attempt/types.js';
+import type { StructuredErrorInfo } from '../errors/errorInfo.js';
+import { type TerminalFailureContext, NativeFailureState } from '../errors/terminalFailure.js';
 import { type DiagnosticChannel, DiagnosticCollector } from './DiagnosticCollector.js';
 import type { FlowControlType, StageSnapshot } from './frameTypes.js';
 import type { RedactionVerdict } from './redaction.js';
 import { RedactionRule } from './redaction.js';
 import type { RunPolicy } from './runPolicy.js';
+/**
+ * How many call and observed attempt records one stage execution keeps (P2) — a stage that calls in a loop must
+ * not grow the execution tree without bound. The rest are counted (`StageSnapshot.attemptsDropped`) and still
+ * fired on `onAttempt`. A stage's OWN attempt records are never displaced: its policy's ceiling bounds them.
+ */
+export declare const MAX_CALL_RECORDS = 1000;
 export declare class StageContext {
+    #private;
+    /** @internal Ownership of an escaping failure. Shared only by sequential frames, never serialized. */
+    failureState: NativeFailureState;
+    /** @internal The native frame stamp, independent of mutable recorder event context. */
+    get failureIdentity(): NonNullable<TerminalFailureContext['stage']> | undefined;
+    /** @internal Stamped before observers; never inherited by another frame or persisted. */
+    bindFailureIdentity(runId: string, runtimeStageId: string): void;
     /**
      * The record half of this frame (`RecordFrame.ts`, L3, C3): the heap and,
      * when the run keeps them, the redacted mirror and the log; the address;
@@ -138,6 +154,41 @@ export declare class StageContext {
      * stages that never touch an untracked path pay nothing.
      */
     private _untrackedSources?;
+    /**
+     * The attempts of this frame's execution (10.1) — its own under the attempt runner, appended as each attempt ends
+     * (`FlowchartTraverser · executeStage`), and those of the calls it made (P2, {@link reportCallAttempt}) — read
+     * by {@link snapshotSelf}. Append-only
+     * evidence like `debug`: NOT cleared by {@link discardStaged} (the earlier attempts are the point) and never
+     * part of a commit bundle. Lazily allocated: a stage without a policy pays nothing.
+     */
+    private _attempts?;
+    /** The attempt series at a glance, stamped once when it ends. */
+    private _attemptSummary?;
+    /** Facts collected for this execution only; retry discards deliberately keep them. */
+    private _attention?;
+    /**
+     * The attempt now running (P1b) — set by `StageRunner` before the scope is built, so the facade can hand it out
+     * (`scope.$attempt()`) and fence its own attempt. Absent for a stage the attempt runner does not run.
+     */
+    private _attempt?;
+    /** The run's signal, for the attempt a stage outside the runner reports (attempt 1 of 1). */
+    private _runSignal?;
+    /** Every attempt up to this number has ENDED without an answer — its scope is fenced (0 = none). */
+    private _endedThrough;
+    /** Writes an attempt tried after it ended — dropped at the scope, kept here as names. Lazily allocated. */
+    private _lateWrites?;
+    /**
+     * Where a call's attempt records are reported (P2) — the engine's `onAttempt` for this stage execution, set by
+     * `FlowchartTraverser · executeStage` with the stage's own traversal context (and its correlation).
+     */
+    private _attemptReporter?;
+    /** Calls made so far, per stage attempt — the `k` of a call's series. Lazily allocated. */
+    private _callOrdinals?;
+    /** Per stage attempt, the signal its calls stop by (`callsEndedSignal`). Lazily allocated. */
+    private _callsEnded?;
+    /** Call and observed records kept on the frame, and those past {@link MAX_CALL_RECORDS}. */
+    private _callRecords;
+    private _attemptsDropped;
     /** Observer called after commit() — used by ScopeFacade to fire ScopeRecorder.onCommit. */
     private _commitObserver?;
     constructor(runId: string, name: string, stageId: string, sharedMemory: SharedMemory, branchId?: string, eventLog?: EventLog, isDecider?: boolean);
@@ -404,6 +455,8 @@ export declare class StageContext {
      *   reads them post-run for the execution-tree snapshot.
      */
     commit(phase?: CommitPhase): void;
+    /** Whether this frame has committed — a call's record arriving after it is late (P2, `ScopeFacade · call`). */
+    get committed(): boolean;
     /**
      * Throw away everything this stage has STAGED, without committing any of it.
      *
@@ -429,14 +482,81 @@ export declare class StageContext {
      *                    holds bare references — dropping it un-clones nothing);
      *  - `_untrackedSources` — the D2 honesty markers, released with the rest.
      *
-     * What is deliberately KEPT: `debug` (logs, metrics, errors, flow messages).
-     * Diagnostics are the append-only record of what every attempt did, and the
-     * retry feature's whole point is that the earlier attempts stay visible.
+     * What is deliberately KEPT: `debug` (logs, metrics, errors, flow messages)
+     * and the attempt records (10.1). Both are the append-only record of what
+     * every attempt did, and the retry feature's whole point is that the earlier
+     * attempts stay visible.
      *
      * No commit is recorded and no observer fires — a discarded attempt is not a
      * cursor stop, because from shared state's point of view it never happened.
      */
     discardStaged(): void;
+    /** Append one attempt's record — the attempt runner calls this as each attempt ends. */
+    recordAttempt(record: AttemptRecord): void;
+    /** Stamp the series' summary — once, when the runner ends the series. */
+    endAttempts(summary: AttemptSummary): void;
+    /** Reset only at the node's execution stamp, never between attempts. */
+    beginAttention(): void;
+    /** Delegate the explicit retained-error fact; attention owns validation of its proof. */
+    markStageFailure(): void;
+    /**
+     * The crash-safe record (10.1, P6): an attempt that ended is noted in the run's sink AT ONCE, beside this frame's
+     * log — so a process killed before the stage commits (mid-retry) still leaves every attempt that ended. The
+     * record is the one the tree keeps: frozen, `structuredClone`-safe, its error the SERVED form (no `raw`), so the
+     * note needs no second redaction pass. Without a sink the log does nothing (`EventLog · note`).
+     */
+    private noteAttempt;
+    /** The attempts of this execution so far, in order — its own and its calls'; `undefined` when there are none. */
+    get attempts(): readonly AttemptRecord[] | undefined;
+    /** The ended series' summary; `undefined` while it runs and without a policy. */
+    get attemptSummary(): AttemptSummary | undefined;
+    /** The attempt about to run (and the run's signal) — `StageRunner` sets both before it builds the scope. */
+    useAttempt(attempt: AttemptContext | undefined, runSignal: AbortSignal | undefined): void;
+    /** The attempt now running; `undefined` for a stage the attempt runner does not run. */
+    get attempt(): AttemptContext | undefined;
+    /** The run's signal, as `StageRunner` last saw it. */
+    get runSignal(): AbortSignal | undefined;
+    /**
+     * Attempt `attempt` ended without an answer: from now on its scope is fenced — a write, an emit or a read
+     * through it is refused (`ScopeFacade`). The runner calls this the moment the attempt's signal aborts.
+     */
+    endAttempt(attempt: number): void;
+    /** Whether attempt `attempt` has ended — its scope may no longer touch the stage. */
+    hasAttemptEnded(attempt: number): boolean;
+    /** Record a write an ended attempt tried — a name, never the value. Append-only evidence like the attempts. */
+    recordLateWrite(write: LateWrite): void;
+    /** This execution's own idempotency key may be made of a selected value (or was carried by a checkpoint). */
+    private _effectKeyTainted;
+    /** A touching `$call` with NO key started in this execution — the stage may not be re-run by a resume. */
+    private _keylessEffect;
+    /**
+     * Start an execution's side-effect bookkeeping (`FlowchartTraverser · executeStage`, before attempt 1) — reset,
+     * because a frame can be re-used by a later execution. `keyTainted`: the stage's own key may be made of a selected
+     * value, so a key a `$call` passes on (`$attempt().idempotencyKey`) is served the same way.
+     */
+    beginEffects(keyTainted: boolean): void;
+    get effectKeyTainted(): boolean;
+    /** A keyless touching `$call` started: an `interrupt()` after it would re-send it on resume (`StageRunner`). */
+    markKeylessEffect(): void;
+    get hasKeylessEffect(): boolean;
+    /** Where this execution's call records are reported — the engine sets it before the stage runs. */
+    useAttemptReporter(report: ((record: AttemptRecord, structuredError: StructuredErrorInfo | undefined) => void) | undefined): void;
+    /**
+     * The signal the calls of stage attempt `stageAttempt` run under besides its own (P2): aborted when that attempt is
+     * over — however it ended — and when the frame commits, so no call outlives the attempt that made it (no
+     * background retry, no wait, no listener left on the run's signal). Already aborted after the commit.
+     */
+    callsEndedSignal(stageAttempt: number): AbortSignal;
+    /** End the calls of `stageAttempt` (every attempt's when `undefined`) — `reason` when the attempt's signal gave one. */
+    private endCalls;
+    /** The next call's ordinal within stage attempt `stageAttempt`, 1-based (`attempt/call.ts · callSeries`). */
+    nextCallOrdinal(stageAttempt: number): number;
+    /**
+     * A call's (or an observed) attempt record: kept beside the stage's own attempts — the first
+     * {@link MAX_CALL_RECORDS}, the rest counted — and reported to the run's `onAttempt` either way. Like the stage's
+     * records, NOT cleared by {@link discardStaged}: a failed attempt's calls are evidence too.
+     */
+    reportCallAttempt(record: AttemptRecord, structuredError: StructuredErrorInfo | undefined): void;
     /**
      * Create (or return) this context's linked successor.
      *