foottrace 0.0.0-stage → 1.0.0

package/dist/esm/lib/memory/EventLog.js

@@ -0,0 +1,147 @@
+/**
+ * EventLog — Time-travel snapshot storage for flowchart execution
+ *
+ * Like git history: stores commit bundles (diffs), not full snapshots.
+ *
+ * THE RECORD IS IMMUTABLE FROM `record` (F3, ruling R3). Every bundle is deep-frozen as it is
+ * recorded — the bundle, `overwrite` and `updates` at every depth, the trace and each row, the
+ * row's `readKeys`, `redactedPaths`, `tags`, `untrackedSources` — so a holder of a snapshot can no
+ * longer rewrite the history every later answer is folded from: an assignment into a bundle throws
+ * a `TypeError` in strict code. Safe because nothing outside the log holds a bundle's containers:
+ * the log's payload is the commit's own copy (`recordCommit` hands it the output of
+ * `scrubPatch`), and live state, the redacted mirror and write retention each take their own copy
+ * (`verbs.ts · foldRows` detaches, `StageContext · retainedForm` clones) — pinned by
+ * test/lib/memory/property/record-reachability.property.test.ts.
+ *
+ * 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 { freezeRecord, serveRecord } from '../capture/freeze.js';
+import { applySmartMergeInto } from './utils.js';
+export class EventLog {
+    /** Base snapshot BEFORE the first stage mutates anything. */
+    base;
+    /** Ordered list of commit bundles. */
+    steps = [];
+    sourceAddress;
+    sourceAddressRetired = false;
+    constructor(initialMemory) {
+        // Normalised to an object: the base is a STATE, and every fold over it
+        // (`materialise`, `stateAt`) applies path writes to it. `undefined` —
+        // what a run with no `initialContext` used to store here — made every
+        // one of those folds throw on the first `set`.
+        this.base = initialMemory === undefined ? {} : structuredClone(initialMemory);
+    }
+    /**
+     * The fold BASE — the state as it stood before the first commit.
+     *
+     * This is the other half of the commit log: bundles are DIFFS, so a log
+     * alone cannot reconstruct state that was seeded before the run (an
+     * executor `initialContext`, `defaultValuesForContext`, a resume's
+     * `checkpoint.sharedState`, a subflow's `inputMapper` seed). Travelling
+     * with the log — `RuntimeSnapshot.initialState` — is what lets an OFFLINE
+     * consumer fold; without it the honest answer is a partial one
+     * (`stateAt`'s `basis: 'log-only'`).
+     *
+     * Returns a fresh detached clone on every call — the caller owns it.
+     */
+    getInitialState() {
+        return structuredClone(this.base);
+    }
+    /**
+     * Reconstructs the full state at any given step.
+     * Replays commits from the beginning — O(n) but low memory footprint.
+     *
+     * INDEX CONVENTION — `stepIdx` is EXCLUSIVE: `materialise(3)` folds commits
+     * 0, 1 and 2. `stateAt(source, commitIdx)` (foottrace) folds the
+     * same log but its `commitIdx` is INCLUSIVE, because a reader's cursor asks
+     * "the state AT this stop", which must include that stop's own commit. Two
+     * folds over one log with opposite conventions: check which one you hold.
+     *
+     * One clone of the base per call, then every bundle replayed INTO that
+     * private copy (`applySmartMergeInto` — the live commit's copy-on-write law
+     * below the root, 9.29.0, so the fold and the live state agree at every
+     * path). The result is the caller's: it shares nothing with the base or
+     * the log.
+     *
+     * @deprecated Since 9.33.0 — use `stateAt` from `foottrace`, which folds the same log
+     * from the same base (`RuntimeSnapshot.initialState`) and says how it was derived (`basis`).
+     * Nothing in the library calls this; it stays for one minor and is then removed. Mind the
+     * index: `materialise(n)` folds commits `0..n-1`, `stateAt(source, n - 1)` the same commits.
+     */
+    materialise(stepIdx = this.steps.length) {
+        const out = structuredClone(this.base);
+        for (let i = 0; i < stepIdx; i++) {
+            const { overwrite, updates, trace } = this.steps[i];
+            applySmartMergeInto(out, updates, overwrite, trace);
+        }
+        return out;
+    }
+    /**
+     * Persists a commit bundle for a finished stage, and FREEZES it (see the module doc): the bundle
+     * is stamped with its position, then deep-frozen, then appended. The engine hands it a bundle
+     * built for the log alone; a caller of this class (`foottrace/write`) hands over a bundle it
+     * will no longer edit — its own object is the one frozen.
+     */
+    record(bundle) {
+        bundle.idx = this.steps.length;
+        freezeRecord(bundle, 'indices');
+        this.steps.push(bundle);
+    }
+    /**
+     * 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() {
+        return this.steps.map(serveRecord);
+    }
+    /**
+     * @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() {
+        return this.steps.slice();
+    }
+    /** Number of recorded commits. */
+    get length() {
+        return this.steps.length;
+    }
+    /** Immutable identity of this log, absent until the engine binds it. */
+    get address() {
+        return this.sourceAddress;
+    }
+    /** @internal Bind once; resuming the same log must not rename its earlier positions. */
+    bindAddress(logRunId, drillPath) {
+        if (this.sourceAddressRetired)
+            return;
+        this.sourceAddress ??= Object.freeze({ logRunId, drillPath: Object.freeze([...drillPath]) });
+    }
+    /** O(1) source-time capture. No counter, observer bookkeeping, or future commit prediction. */
+    capturePosition(runId) {
+        if (!this.sourceAddress)
+            return undefined;
+        return Object.freeze({ runId, ...this.sourceAddress, committedThroughIdx: this.steps.length - 1 });
+    }
+    /** Wipes history (useful for test resets). */
+    clear() {
+        this.steps = [];
+        // A reset prefix cannot reuse old coordinates, even if another stage of
+        // the SAME leg binds it again. Keep clear's data behavior, but retire
+        // addressing for this log; known coordinates require a fresh EventLog.
+        this.sourceAddress = undefined;
+        this.sourceAddressRetired = true;
+    }
+}

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

@@ -0,0 +1,232 @@
+/**
+ * RecordFrame — the record half of one stage's frame (C3, L3).
+ *
+ * What a stage's frame needs to READ and WRITE the record, and nothing about the stage inside a run:
+ * where it writes (its address), what it read first (the first-touch base), what it staged (the lazy
+ * transaction buffer) and which of it the log must not show (the scrub of each write), which keys it
+ * read (the readKeys list), and where a commit lands (live state, the redacted mirror, the log —
+ * through `recordCommit`). The engine's frame (`StageContext`, L4) composes one and keeps the rest:
+ * retention, diagnostics, the dev-mode warnings, the commit observer and the redaction DECISION —
+ * which value is secret (`redaction.ts · decideWrite`); the frame writes the bytes it is handed (C4).
+ *
+ * THE LAW:
+ *   1. ADDRESS. The frame reads and writes at its address, a path prefix the engine computed and hands
+ *      over as data (C2: `['runs', <id>]` or `[]`, the root). It moves only before the first write:
+ *      the buffer keeps the address it was built at (the engine refuses a later move).
+ *   2. FIRST TOUCH. The committed generation the frame first touched — its first read OR first write —
+ *      is held by reference, never cloned: the read view before the first write and the buffer's
+ *      net-change diff base after it.
+ *   3. TWO TIERS. A read is served from the stage's own view (the buffer's working copy once the stage
+ *      wrote, else the first-touch base); a key absent there is served from LIVE state (at the
+ *      address, then the root). After the first write the buffer's diff base is first given a private
+ *      copy at that path (`TransactionBuffer · detachBase`).
+ *   4. LAZY BUFFER. The buffer is built at the first write — on the first-touch base, at the address,
+ *      under the encoding. A frame that never writes builds none, and its commit is the empty bundle.
+ *   5. READ KEYS. Under `writeProvenance: 'reads-prefix'` every noted read puts its user-level key
+ *      (dotted for a nested path) on the frame's list, once, in order; each staged row carries a copy
+ *      of the list as it stands when the row is staged.
+ *   6. COMMIT, RELEASE, DISCARD. `commit` takes the buffer's payload (none = the empty commit), then
+ *      the names, and hands both to `recordCommit`. `release` drops the buffer and the base; a frame
+ *      touched again re-anchors on the state as it stands then. The readKeys list survives a release,
+ *      and goes with `discard` (a failed attempt never happened).
+ *   7. WRITE. `write(path, value, verb, scrub?)` is the one way to stage: `set`, `merge` or `delete`
+ *      at an absolute path (the address already joined — `at`), with the bytes of a redaction
+ *      verdict. `whole` → the log and the mirror carry `LOG_PLACEHOLDER` at the path; `fields` → at
+ *      each field inside the value (a literal key and, when dotted, the nested path) — wherever it
+ *      holds a value at commit (`scrub.ts`). No scrub → the value as it is. The frame never decides
+ *      a scrub, and nothing outside it reaches its buffer.
+ */
+import type { OpVerb } from './deltaEncoding.js';
+import type { EventLog } from './EventLog.js';
+import { type CommitStamp } from './recordCommit.js';
+import type { SharedMemory } from './SharedMemory.js';
+import type { CommitValuesMode, WriteProvenanceMode } from './types.js';
+/**
+ * The two dials that shape a frame's bytes: the log's value encoding and the per-row read prefix.
+ * Held by reference and swapped whole (`useEncoding`), never edited — the engine hands the run's
+ * frozen policy itself. Absent: `'full'` values and no read prefix.
+ */
+export interface RecordEncoding {
+    readonly commitValues: CommitValuesMode;
+    readonly writeProvenance: WriteProvenanceMode;
+}
+/**
+ * What a stage can stage (law 7) — the transaction buffer's op verbs (`deltaEncoding.ts · OpVerb`), one
+ * union. `append` is not one: it is how the log encodes a grown array (`'delta'`).
+ */
+export type WriteVerb = OpVerb;
+/**
+ * The bytes of a redaction verdict for one write (law 7): which of it the commit log and the redacted
+ * mirror must not show. The engine decides it (`redaction.ts · decideWrite`); the frame only writes it.
+ */
+export interface WriteScrub {
+    /** The whole value: `LOG_PLACEHOLDER` at the write's path. */
+    readonly whole?: boolean;
+    /** Dot-paths INSIDE the value, relative to it: `LOG_PLACEHOLDER` at each one that holds a value. */
+    readonly fields?: readonly string[];
+}
+export declare class RecordFrame {
+    /** Live committed state — the heap every frame of the run shares. */
+    readonly state: SharedMemory;
+    /** The log the frame's commits land on, when the run keeps one. */
+    readonly log?: EventLog;
+    /** The redacted mirror the frame's commits land on, when the run keeps one ({@link useMirror}). */
+    private _mirror?;
+    /** Where the frame reads and writes (law 1). */
+    private _address;
+    /** The two dials (law 4, 5); absent → the record's defaults. */
+    private encoding?;
+    /**
+     * The committed generation at the frame's FIRST touch (law 2) — held by REFERENCE, never cloned.
+     * See {@link firstTouch} for the algorithm and the immutability invariant that makes a bare
+     * reference safe.
+     */
+    private base?;
+    /** The stage's staged writes — built at its first write (law 4), released at commit. */
+    private buffer?;
+    /**
+     * Keys tracked-read so far, in order (law 5) — the source of each staged row's `readKeys`. Only
+     * allocated under `'reads-prefix'`; insertion-ordered (a Set) and monotonic, which is what makes
+     * "last write's prefix == union" hold in delta mode.
+     */
+    private readKeys?;
+    constructor(state: SharedMemory, log?: EventLog, address?: readonly string[]);
+    /** Where the frame reads and writes (law 1). */
+    get address(): readonly string[];
+    /**
+     * Read and write at `address` from now on — before the frame's first write (law 1): the buffer keeps
+     * the address it was built at. The engine's one caller, `StageContext · useAddressOf`, refuses a move
+     * once the frame has staged.
+     */
+    useAddress(address: readonly string[]): void;
+    /** The two dials the frame encodes under from its next buffer and its next read on (law 4, 5). */
+    useEncoding(encoding: RecordEncoding): void;
+    /** The redacted mirror, if the run keeps one. */
+    get mirror(): SharedMemory | undefined;
+    /** Land every commit from now on on `mirror` too, with the scrubbed rows the log takes (`recordCommit`). */
+    useMirror(mirror: SharedMemory | undefined): void;
+    /** The absolute path of `key` under `path`: the frame's address, then the path, then the key. */
+    at(path: readonly string[], key: string): string[];
+    /**
+     * ── The first-touch base (#13) ───────────────────────────────────────────
+     *
+     * WHAT: returns the committed shared state as it was at this frame's FIRST touch (first read or
+     * first write), capturing the reference on first call. Serves two consumers: reads before the first
+     * write ({@link read}) and the transaction buffer's diff base ({@link getTransactionBuffer}).
+     *
+     * WHY A BARE REFERENCE IS SAFE — the invariant this rests on: committed state is
+     * immutable-after-swap. Every write to `SharedMemory` builds the NEXT generation and swaps it in
+     * (copy-on-write, 9.29.0: `applyPatch` via `nextGeneration`, and `setValue`/`updateValue` too) — it
+     * copies the root and the containers on each written path, shares the rest, and never edits a
+     * container of the generation a stage captured here. Holding the reference therefore gives this
+     * stage a stable snapshot at zero cost — no clone, which is the entire point of #13. The transaction
+     * buffer's net-change diff base rests on the same guarantee: it IS this view.
+     *
+     * WHY FIRST TOUCH, not first write: the pre-#13 eager engine cloned the state into the buffer at
+     * the stage's first ACCESS, anchoring both its snapshot reads and its commit baseline (the
+     * net-change diff base) there. #13's first cut anchored the lazy buffer at first WRITE — observably
+     * different when something else commits in the gap between this stage's first read and its first
+     * write. That gap is REACHABLE: fork siblings are namespace-isolated for run-scoped keys (each child
+     * writes under `runs/<childId>/`), but ROOT-level keys are shared — written via `setGlobal` from
+     * consumer scope code and, critically, by `SubflowInputMapper`'s output mapping
+     * (`parentContext.setGlobal`), which is exactly what runs when a subflow is a fork branch. A
+     * sibling's root-key commit landing in the gap would shift this stage's diff base, making its
+     * CommitBundle record a phantom change (or swallow a real one) relative to the eager engine.
+     * Anchoring the view at first touch restores the EXACT eager semantics — sequential AND parallel —
+     * at zero clone cost.
+     *
+     * Read visibility is two-tier, matching eager byte-for-byte: keys present in the view at first
+     * touch read repeatably from it; keys ABSENT from it fall back to LIVE state (the eager engine's
+     * exact fallback — a mid-flight sibling root-key write was always visible to reads, and stays
+     * visible; only the DIFF BASE is pinned).
+     */
+    private firstTouch;
+    /**
+     * The transaction buffer, created lazily on the frame's FIRST WRITE (#13).
+     *
+     * Reads NEVER construct it: read-your-writes only matters once a staged write exists, so before that
+     * {@link read} serves from the first-touch base and {@link commit} records an empty bundle — all with
+     * ZERO `structuredClone`s of the shared state.
+     *
+     * The buffer's base is the FIRST-TOUCH view, NOT the live state at write time: under parallel forks
+     * a sibling may have committed between this frame's first read and this write, and the net-change
+     * diff base must stay anchored at first touch to match the eager engine — see {@link firstTouch}.
+     *
+     * Private since C4: every write goes through {@link write}, so the scrub travels with the op.
+     */
+    private getTransactionBuffer;
+    /**
+     * Stage one write (law 7): `verb` at `path` — an absolute path, the address already joined
+     * ({@link at}) — and the bytes of its redaction verdict. The first write builds the buffer (law 4).
+     *
+     * The scrub registers paths, never values: `whole` marks the op's own path, `fields` each field
+     * inside the value (a literal key and, when dotted, the nested path); `recordCommit` puts the
+     * log's placeholder wherever one of them holds a value at commit, for the mirror and the log only
+     * (`scrub.ts`). Live state takes the value as it is. A path marked by a write that the net-change
+     * filter drops goes with it.
+     */
+    write(path: (string | number)[], value: unknown, verb: WriteVerb, scrub?: WriteScrub): void;
+    /** Has the frame staged a write since its last release — does its buffer exist? */
+    get hasStaged(): boolean;
+    /**
+     * The frame's read, mirroring the eager engine's read order byte-for-byte (law 3):
+     *
+     *    1. staged writes + first-touch snapshot — `buffer.get` over its workingCopy when the buffer
+     *       exists, else `nativeGet` over the zero-clone first-touch base (the buffer's base IS that
+     *       view, so the two tiers agree on content);
+     *    2. LIVE state via `SharedMemory · getValue` for keys absent from the snapshot — including its
+     *       address→root fallback. The eager engine had this exact live fallback for snapshot-missing
+     *       keys; byte-identity over purity. After the frame's first write such a value can be the very
+     *       container the buffer's diff base holds at the path (the stage deleted or unset it, or
+     *       replaced a container above it), so the base is detached there first
+     *       (`TransactionBuffer · detachBase`): an in-place edit of the value (out of contract) written
+     *       back is recorded, as on 9.28.0, whose base was a clone taken at the first write.
+     *
+     * Reads never construct the buffer (#13): a frame that never writes performs zero clones of the
+     * shared state.
+     */
+    read(path: string[], key?: string): unknown;
+    /** Put a tracked read's user-level key on the readKeys list (law 5) — a no-op unless the frame keeps one. */
+    noteRead(path: readonly string[], key: string): void;
+    /**
+     * Live committed state at `key`: at the frame's address, else at the root — never the stage's own
+     * view. Typed as `SharedMemory · getValue` types it, which `StageContext · getRoot` hands on.
+     */
+    readLive(key: string): any;
+    /** Live committed state at `key` at the root — typed as `SharedMemory · getValue` (`StageContext · getGlobal`). */
+    readGlobal(key: string): any;
+    /** Did a staged op touch `path` — on it, above it or below it? (A report's question; never the hot path.) */
+    wasStaged(path: (string | number)[]): boolean;
+    /**
+     * The value at `path` in what the stage has seen — its working copy once it wrote, else its
+     * first-touch base — WITHOUT taking a private copy: for a report that only compares.
+     */
+    peek(path: (string | number)[]): unknown;
+    /** The value at `path` in the first-touch base — committed state as the frame first touched it. */
+    baseAt(path: (string | number)[]): unknown;
+    /**
+     * Record what the frame staged (law 6): the buffer's payload first — none, the empty commit, when
+     * it staged nothing (#13: zero clones) — then the names (`stampOf()`), read once the payload is
+     * built, and both to `recordCommit`. User code can run while the payload is built (a getter on a
+     * staged value, which the net-change compare and the clone invoke); what it adds to the names —
+     * an untracked read, say — is on the bundle.
+     */
+    commit(stampOf: () => CommitStamp): void;
+    /**
+     * End the frame's hold on state (#13b, law 6): drop the buffer (its working copy and whatever private
+     * copies its reads took) and the first-touch base (a reference that pins one committed-state
+     * GENERATION). Both re-create lazily: a later read re-anchors on the CURRENT committed state, and a
+     * later write builds a fresh buffer on it — so a second commit diffs against the state after the
+     * first. Without the release, the execution tree — which retains every frame for the lifetime of
+     * the run — retains one state generation per executed stage (measured O(N²) before copy-on-write;
+     * a 500-iteration agent OOMed a default Node heap, backlog #18).
+     */
+    release(): void;
+    /**
+     * Throw away everything the frame staged and read (law 6): the buffer, the first-touch base (the next
+     * attempt re-anchors on committed state as it stands NOW) and the readKeys list — a discarded
+     * attempt's reads must never reach the next attempt's `TraceEntry.readKeys`, or a backward slice
+     * would follow an edge that no committed write ever had. Nothing is recorded.
+     */
+    discard(): void;
+}