footprintjs 9.44.0 → 9.44.2

package/dist/types/lib/capture/freeze.d.ts

@@ -1,21 +1,42 @@
 /**
- * freeze.ts — the ONE deep-freeze walk (moved here from `scope/protection/readonlyInput.ts` in F3).
+ * freeze.ts — the ONE deep-freeze walk (moved here from `scope/protection/readonlyInput.ts` in F3),
+ * and the serve-time law for the commit log (9.44.2).
  *
  * WHY HERE. Saved trees freeze through this walk: the fold base served as
  * `initialState` (`ExecutionRuntime · getFoldBase`), the
  * dev-mode snapshot (`runner/snapshot.ts · servedSnapshot`), every state `stateAt` hands out
  * (`time-travel/stateAt.ts`) and, since F3, every commit bundle (`EventLog · record`). `memory/` must
  * not import `scope/` (that edge closed the memory ⇄ scope ⇄ recorder module cycle F0 removed), so the
- * walk lives in this leaf, which imports nothing. Args use an ownership snapshot instead
- * (`scope/protection/readonlyInput.ts · createFrozenArgs`): never freeze borrowed caller values.
+ * walk lives in this leaf folder, which imports nothing outside itself. Args use an ownership snapshot
+ * instead (`scope/protection/readonlyInput.ts · createFrozenArgs`): never freeze borrowed caller values.
+ *
+ * FREEZE WHAT CAN BE FROZEN, COPY WHAT CAN'T (9.44.2). `Object.freeze` cannot seal a Date's time, a
+ * Map's or Set's entries, a buffer's bytes, a RegExp (`compile()` rewrites a frozen one) or an Error
+ * (V8's own `stack` accessor writes through a frozen one). A fresh tree handed to one caller (a `stateAt`
+ * state, the dev-mode snapshot) is that caller's own, so freezing it is a guard and nothing more. The
+ * COMMIT LOG — each bundle, and the fold base — is served to every reader, so {@link freezeRecord}
+ * remembers that a record holds such a value, its first serve maps the containers on the way to each
+ * one (its open PATHS), and {@link serveRecord} hands a reader a copy of those paths only: a fresh copy
+ * of each such value, fresh frozen containers on the way to it, and every other part shared, frozen, as
+ * it is. Until 9.44.2 `snapshot.commitLog[i].overwrite.when.setTime(0)` rewrote every later snapshot,
+ * `stateAt`, `commitValueAt`, slice and cursor answer.
+ *
+ * Every walk here is ITERATIVE (an explicit stack): a record's depth is not bounded by the call stack.
  *
  * @example
  * ```typescript
- * import { deepFreeze } from './freeze.js';
+ * import { deepFreeze, freezeRecord, serveRecord } from './freeze.js';
  *
  * const args = deepFreeze({ order: { lines: [{ sku: 'A' }] }, bytes: new Uint8Array([1]) });
  * Object.isFrozen(args.order.lines[0]); // true
  * Object.isFrozen(args.bytes); // false — a typed array cannot be frozen; it is skipped
+ *
+ * const record = freezeRecord({ when: new Date(0), tags: ['a'] });
+ * const served = serveRecord(record);
+ * served.when.setTime(5); // changes the reader's copy
+ * serveRecord(record).when.getTime(); // 0 — every serve is the record as recorded
+ * served.tags === record.tags; // true — the sealed part is shared, not copied
+ * serveRecord(freezeRecord({ n: 1 })); // a record freezing sealed whole: served as itself
  * ```
  */
 /**
@@ -25,8 +46,8 @@
  *   AND any expando (`arr.note = { … }`). The dev-mode snapshot relies on this contract.
  * - `'indices'` — the index elements only, so no key string is allocated per element; this is what
  *   keeps freezing a 10,000-element commit inside its budget (`bench/element-writes.ts`). An object
- *   hung on an array EXPANDO is then left unfrozen — the commit log's named hole
- *   (`EventLog · record`).
+ *   hung on an array EXPANDO is then left unfrozen, and unseen by {@link serveRecord} — the commit
+ *   log's named hole (`EventLog · record`; an array expando is out of contract for state).
  */
 export type ArrayWalk = 'every-key' | 'indices';
 /**
@@ -41,7 +62,30 @@ export type ArrayWalk = 'every-key' | 'indices';
  *   snapshot here.
  * - What `Object.freeze` cannot reach stays mutable — Map and Set contents, a Date's time, the
  *   bytes behind a buffer. A frozen RegExp's `lastIndex` is read-only, so a `/g` or `/y` regex
- *   taken from a frozen tree throws when `exec` or `replace` advance it.
+ *   taken from a frozen tree throws when `exec` or `replace` advance it. The commit log goes through
+ *   {@link freezeRecord} and {@link serveRecord} instead.
  * - Functions are not descended (they are not values the engine stores).
  */
 export declare function deepFreeze<T>(obj: T, arrays?: ArrayWalk): T;
+/**
+ * {@link deepFreeze} for a record many readers are SERVED (a commit bundle, the fold base), and two more
+ * things on the same walk:
+ *
+ *   - it remembers THAT the record holds a value freezing cannot seal — one flag; the record's first
+ *     serve maps WHERE (the containers on the way to each such value, its open paths), so the run pays
+ *     nothing more and {@link serveRecord} copies those paths and nothing else;
+ *   - a typed array or `DataView` that views a SLICE of a bigger buffer (a Node `Buffer` views its
+ *     shared pool) is replaced, in the record, by a copy of the bytes it views — the record keeps the
+ *     view's bytes, never the rest of the buffer (a resizable or shared buffer is kept as it is).
+ *
+ * A part frozen before is not frozen past (deepFreeze's contract) but is looked through, so a value
+ * freezing cannot seal inside it still opens the record. Returns `record`.
+ */
+export declare function freezeRecord<T extends object>(record: T, arrays?: ArrayWalk): T;
+/**
+ * The record as a reader may hold it — THE serve-time law: a record freezing sealed whole is served as
+ * itself (shared, no cost); any other as a copy of its open paths ({@link freezeRecord}): fresh frozen
+ * containers down to each value freezing cannot seal, a fresh copy of that value, and every other part
+ * shared, frozen, as it is. A copy is served the same way again.
+ */
+export declare function serveRecord<T>(record: T): T;

package/dist/types/lib/capture/valueKinds.d.ts

@@ -0,0 +1,57 @@
+/**
+ * valueKinds.ts — what KIND of value a record holds: the one classifier.
+ *
+ * WHY. Committed state is what survives `structuredClone` (an engine invariant), so the values a
+ * record holds are the kinds the clone keeps. Two laws need the kind, and both ask here:
+ *
+ *   - what counts as a CHANGE (`memory/equality.ts · deepEqual`): two values are equal when a record
+ *     holds the same thing for both, compared kind by kind. Until 9.44.2 only Date, Map and Set had a
+ *     kind; a RegExp, an Error, a boxed number, a buffer, a DataView or a Blob was compared as an
+ *     object with no own keys — equal to any other of its kind — so replacing one committed no row
+ *     and live state kept the old value;
+ *   - what a served record must COPY (`capture/freeze.ts · freezeRecord` / `serveRecord`):
+ *     `Object.freeze` seals only the kinds whose content is their own properties ({@link SEALABLE}).
+ *
+ * A leaf: imports nothing (`capture/` is L0, below `memory/`).
+ *
+ * @example
+ * ```typescript
+ * kindOf(new Date(0));                    // 'date'
+ * kindOf(new (class Point { x = 1 })());  // 'plain' — its clone is a plain object
+ * kindOf(new Blob(['a']));                // 'opaque' — its clone keeps content this library cannot read
+ * SEALABLE.date;                          // false — setTime writes a slot Object.freeze cannot reach
+ * ```
+ */
+/** Every kind a record can hold. */
+export type ValueKind = 
+/** An object the clone keeps as its own enumerable keys — a class instance included. */
+'plain' | 'array' | 'date' | 'regexp' | 'map' | 'set' | 'error'
+/** A boxed primitive: `new Number(1)`, `new String('a')`, `new Boolean(true)`, `Object(1n)`. */
+ | 'boxed'
+/** An `ArrayBuffer` (a `SharedArrayBuffer` too: shared memory is out of contract for state). */
+ | 'buffer'
+/** A typed array or a `DataView`. */
+ | 'view'
+/** Any other object the clone keeps as itself (a Blob, a File, a `DOMException`): content unread here. */
+ | 'opaque';
+/**
+ * Does `Object.freeze` seal every part of a value of this kind? True only where the content is the
+ * value's own properties (or a slot nothing can write). A `Record`, so a new kind does not compile
+ * until it is decided here.
+ */
+export declare const SEALABLE: {
+    readonly [K in ValueKind]: boolean;
+};
+/**
+ * The kind of an object, as a record holds it. A plain object or an array — the bulk of state —
+ * costs one `Array.isArray` and one `getPrototypeOf`; a built-in a tag and one brand-checked read.
+ * The brand is the value's own slot, so a subclass (a `Map` subclass is a `'map'`, Node's `Buffer` a
+ * `'view'`) and a value from another realm land on their kind.
+ *
+ * Any other object is classified by WHAT ITS CLONE IS, once per prototype: a class instance comes
+ * back a plain object (`'plain'`), a fake built-in (`Object.create(Date.prototype)`, or a class whose
+ * `Symbol.toStringTag` says `'Date'`) comes back `{}` (`'plain'`), and a host object comes back as
+ * itself (`'opaque'`). A prototype whose instance the clone refuses is `'opaque'` — remembered too:
+ * it cannot be held, and its commit will refuse it.
+ */
+export declare function kindOf(value: object): ValueKind;

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

@@ -13,11 +13,17 @@
  * (`verbs.ts · foldRows` detaches, `StageContext · retainedForm` clones) — pinned by
  * test/lib/memory/property/record-reachability.property.test.ts.
  *
- * Named holes — what `Object.freeze` cannot reach stays mutable: Map and Set contents, a Date's
- * time, the bytes of a typed array (skipped: a non-empty one cannot be frozen), and an object hung
- * on an array EXPANDO (arrays are walked by index — `deepFreeze`'s `'indices'` walk, which keeps
- * the freeze inside its budget). A frozen RegExp's `lastIndex` is read-only, so a `/g` or `/y`
- * regex read from a bundle throws when `exec` or `replace` advance it.
+ * What `Object.freeze` cannot seal — a Date's time, a Map's or Set's entries, a buffer's bytes, a
+ * RegExp, an Error's stack — is never handed out to a reader (9.44.2): `record` remembers that a
+ * bundle holds such a value (`capture/freeze.ts · freezeRecord`), and `list()` — like the public
+ * snapshot, `runner/snapshot.ts · servedSnapshot` — serves that bundle as a copy of its open paths
+ * (`serveRecord`, mapped at its first serve): fresh frozen containers down to each such value, a
+ * fresh copy of it, every other part the log's own. A reader edits only its own copy; every later
+ * serve reads the record as recorded. `recorded()` is the engine's own, unserved read. Named holes: an object hung on an array EXPANDO (arrays are walked
+ * by index — the `'indices'` walk, which keeps the freeze inside its budget; an expando is out of
+ * contract for state) and a `SharedArrayBuffer` (every copy shares its memory). A frozen RegExp's
+ * `lastIndex` is read-only, so a `/g` or `/y` regex read from a bundle throws when `exec` or
+ * `replace` advance it.
  */
 import type { EmitSourcePosition, LogAddress } from './eventPosition.js';
 import type { CommitBundle } from './types.js';
@@ -72,8 +78,20 @@ export declare class EventLog {
      * will no longer edit — its own object is the one frozen.
      */
     record(bundle: CommitBundle): void;
-    /** Gets all recorded commit bundles — the live array; every bundle in it is frozen. */
+    /**
+     * Every recorded commit bundle, AS SERVED (9.44.2): a new array each call; a bundle freezing sealed
+     * whole is the log's own (frozen) object, one holding a Date, Map, buffer … is a copy of its open
+     * paths (`capture/freeze.ts · serveRecord`) — the reader's own, so no edit reaches the log.
+     */
     list(): CommitBundle[];
+    /**
+     * @internal The bundles as the log holds them — each frozen, NOT served — in a new array, so a holder's
+     * `splice` reaches only its own. For the engine's own snapshot (`ExecutionRuntime · getSnapshot`, which
+     * a subflow mount takes once per mount), so the run serves nothing; a reader is served by `list()` and
+     * `getSnapshot().commitLog`. A known open door (CHANGELOG 9.44.2): a holder of these bundles can still
+     * edit a Date, Map or buffer inside them.
+     */
+    recorded(): CommitBundle[];
     /** Number of recorded commits. */
     get length(): number;
     /** Immutable identity of this log, absent until the engine binds it. */

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

@@ -1,8 +1,10 @@
 /**
- * equality.ts — structural equality of committed-state values. A leaf (L0,
- * imports nothing): what `TransactionBuffer`'s net-change filter, the admitted
- * record's compare and the borrowed-mutation guard all ask. Re-exported from
- * `utils.ts`, so no importer moved.
+ * equality.ts — structural equality of committed-state values: THE owner of
+ * "what counts as a change". What `TransactionBuffer`'s net-change filter, the
+ * admitted record's compare, the read model's writer rule and the
+ * borrowed-mutation guard all ask. Its one import is the classifier of value
+ * kinds (`capture/valueKinds.ts`, a leaf); re-exported from `utils.ts`, so no
+ * importer moved.
  */
 /**
  * Structural deep equality for committed-state values.
@@ -10,26 +12,42 @@
  * Used by {@link TransactionBuffer} to decide whether a stage actually CHANGED
  * a path or merely re-wrote / reverted it to the value it already held (a
  * "no-op write"), and by `borrowedMutation.firstDifferingPath` to find where a
- * borrowed read moved. Committed state must survive `structuredClone`, and
- * `structuredClone` keeps `Date`, `Map` and `Set` — so those are legal state
- * values (a `$setValue` bypasses the proxy's JSON round-trip) and this must
- * tell two of them apart. Before 9.22.0 it compared them as plain objects, and
- * a `Date`/`Map`/`Set` has no own enumerable keys: every pair was "equal", so
- * `$setValue('k', new Date(1999))` over a 2020 date was dropped as a no-op —
- * no trace row, state unchanged — and a `setFullYear` in place slipped past
- * the dev-mode guard.
+ * borrowed read moved. Committed state must survive `structuredClone`, so the
+ * values it can hold are the kinds the clone keeps, and two values are equal
+ * when a record holds the same thing for both. Every kind has ONE arm below
+ * (`equalPairs`' switch over `ValueKind` — a kind added to the union does not
+ * compile until it is compared). Before 9.22.0 a Date, Map or Set was compared
+ * as an object with no own keys, and until 9.44.2 so were a RegExp, an Error,
+ * a boxed primitive, an ArrayBuffer, a DataView and a Blob: any two of a kind
+ * were "equal", so `$setValue('re', /y/g)` over `/x/g` committed no row and
+ * live state kept the OLD value.
  *
  * Semantics:
  *   - reference / identical-primitive short-circuits first (cheap fast path)
  *   - `NaN` equals `NaN` (primitive compare falls back to `Object.is`)
+ *   - two values of different KINDS are never equal (a `Date` is never `{}`,
+ *     an array never `{ 0: … }`)
  *   - `Date`: same `getTime()` (two invalid dates are equal)
+ *   - `RegExp`: same `source` and `flags` (the clone resets `lastIndex`)
+ *   - `Error`: the same restored kind (one of the six built-in error names,
+ *     else `Error`), own `message`, `stack` and own `cause` (deep) — what the
+ *     clone keeps; any other own field is dropped by it, so it never counts
+ *     (the admitted record's law)
+ *   - a boxed primitive: the same wrapper type and the same primitive inside
+ *   - an `ArrayBuffer`: length, resizability and bytes; a typed array or a
+ *     `DataView`: its type and the bytes IT views — never the rest of its
+ *     buffer (a Node `Buffer` views a slice of a shared pool, and the record
+ *     keeps the view's bytes only: `capture/freeze.ts · freezeRecord`)
  *   - `Map`: same size AND, per key of `a`, `b` holds a deep-equal value —
  *     keys by `Map` identity (`SameValueZero`), values deep
  *   - `Set`: same size AND every member of `a` is deep-equal to SOME member
  *     of `b` (order-insensitive — a Set has no order to compare by)
- *   - a typed value against a plain value, or two different typed kinds → not
- *     equal (a `Date` is never `{}`)
- *   - arrays: equal length AND deep-equal element-wise (order-sensitive)
+ *   - an OPAQUE value (a Blob, a `DOMException` — content this library cannot
+ *     read): by the caller's {@link OpaqueRule} — equal only to itself by
+ *     default (replacing one is always a change), or, when both sides are
+ *     copies of one record, equal to any other of its kind
+ *   - arrays: equal length AND deep-equal element-wise (order-sensitive; an
+ *     array's expando keys are out of contract and not compared)
  *   - objects: identical set of keys that HOLD a value AND deep-equal per key.
  *     An own key whose value is `undefined` counts as ABSENT: it is this
  *     library's other spelling of a deleted key (`'full'` mode flattens
@@ -38,11 +56,13 @@
  *     mirror — reads the two spellings as one state. So must the net-change
  *     filter (9.19.1): `{}` and `{ k: undefined }` are not a change. Arrays
  *     are untouched — a slot holding `undefined` is still a slot.
- *   - mismatched kinds (array vs object, object vs null) → not equal
  *
  * Cost & safety:
- *   - Allocates NOTHING but transient `Object.keys` arrays — no clones. It is
- *     strictly cheaper than the `structuredClone` the commit already performs.
+ *   - Allocates only transient `Object.keys` arrays, an error's property
+ *     descriptors and a byte view per compared buffer — no clones (but one
+ *     probe clone per class prototype, remembered: `capture/valueKinds.ts ·
+ *     kindOf`). It is strictly cheaper than the `structuredClone` the commit
+ *     already performs.
  *   - Primitive comparisons (the bulk of state) are O(1) via the `===` /
  *     `Object.is` fast paths; only nested objects/arrays incur a walk, bounded
  *     by the value's own size.
@@ -54,4 +74,20 @@
  *     change. Dev mode still warns about cycles at write time
  *     (`ScopeFacade.setValue`) because they surprise narrative and JSON.
  */
-export declare function deepEqual(a: any, b: any): boolean;
+export declare function deepEqual(a: any, b: any, opaque?: OpaqueRule): boolean;
+/**
+ * How {@link deepEqual} compares two OPAQUE values (a Blob, a `DOMException` —
+ * content this library cannot read):
+ *
+ *   - `'identity'` (the default) — equal only to itself. The answer when one
+ *     side is a value a stage handed in: the net-change filter
+ *     (`TransactionBuffer`), the append check (`deltaEncoding`). A new object
+ *     is a change, because nothing can say it is not.
+ *   - `'copies'` — equal to any other of its kind. The answer when BOTH sides
+ *     are copies of one recorded value — a fold's generations (`logModel`,
+ *     `elementProvenance`), a retained read against live state
+ *     (`borrowedMutation`), the record replayed against the read-back
+ *     (`admission`): copies never share identity, so identity would call every
+ *     opaque value changed.
+ */
+export type OpaqueRule = 'identity' | 'copies';

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

@@ -402,8 +402,29 @@ export declare function useWalkLimit(limit: number): () => void;
  * inside one segment — and an ancestor whose NAME matches is masked whole
  * before the walk goes below it, so the name decides. Conservative: `true`
  * whenever in doubt.
+ *
+ * Linear in the length of `pattern.source`: every scan here is one forward
+ * pass ({@link classBodies}) or a regex that does constant work per position.
  */
 export declare function needsPath(pattern: RegExp): boolean;
+/**
+ * The body of each character class in `source`, left to right: the text
+ * between a `[` and the first `]` after it that no `\` escapes (a `\` takes
+ * the character after it along). ONE forward pass.
+ *
+ * It replaces `source.matchAll(/\[((?:\\[\s\S]|[^\]\\])*)\]/g)` and gives the
+ * same bodies for every string (pinned against that regex as the control,
+ * test/lib/memory/security/needs-path-linear.security.test.ts). The regex was
+ * quadratic: after a `[` that never closed it retried at every later `[`,
+ * each retry rescanning to the end — `\[` repeated 32,000 times took 0.7 s,
+ * and `setPolicy` runs once per stage's scope (CodeQL js/polynomial-redos).
+ * The pass stops at the first `[` that never closes instead: a later `[`
+ * starts its body where the failed scan was also between two tokens, so it
+ * reads the same tail the same way and closes nowhere either.
+ *
+ * @internal Exported for that test only — not on any public door.
+ */
+export declare function classBodies(source: string): string[];
 /**
  * THE TAINT RULE at a subflow mapper boundary (an `inputMapper` seeding a
  * subflow, an `outputMapper` merging it back): a key the mapper writes

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

@@ -187,7 +187,10 @@ export declare class ExecutionRuntime {
      * The frozen, detached fold base served as {@link RuntimeSnapshot.initialState}.
      * Computed once (the base never changes after construction) and shared —
      * safe because it is deeply frozen, so no holder can mutate it or reach the
-     * engine through it.
+     * engine through it; a base holding a Date, Map, buffer … (what freezing
+     * cannot seal) is served by the public snapshot as a copy of its open paths
+     * (`runner/snapshot.ts · servedSnapshot`, `capture/freeze.ts · serveRecord`,
+     * 9.44.2).
      */
     private getFoldBase;
     getPipelines(): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "9.44.0",
+  "version": "9.44.2",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -53,6 +53,7 @@
     "check:layering": "node scripts/check-layering.mjs",
     "check:doc-snippets": "node scripts/check-doc-snippets.mjs",
     "audit:family": "node scripts/audit-family-versions.mjs",
+    "audit:consumers": "node scripts/audit-consumers.mjs",
     "lint": "eslint '{src,test}/**/*.ts' --ext .ts",
     "lint:fix": "eslint '{src,test}/**/*.ts' --ext .ts --fix",
     "format:fix": "prettier --config .prettierrc.js --write '{src,test}/**/*.ts'",