foottrace 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,295 @@
+/**
+ * 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 { nativeGet } from './pathOps.js';
+import { recordCommit } from './recordCommit.js';
+import { TransactionBuffer } from './TransactionBuffer.js';
+export class RecordFrame {
+    /** Live committed state — the heap every frame of the run shares. */
+    state;
+    /** The log the frame's commits land on, when the run keeps one. */
+    log;
+    /** The redacted mirror the frame's commits land on, when the run keeps one ({@link useMirror}). */
+    _mirror;
+    /** Where the frame reads and writes (law 1). */
+    _address;
+    /** The two dials (law 4, 5); absent → the record's defaults. */
+    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.
+     */
+    base;
+    /** The stage's staged writes — built at its first write (law 4), released at commit. */
+    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.
+     */
+    readKeys;
+    constructor(state, log, address = []) {
+        this.state = state;
+        this.log = log;
+        this._address = address;
+    }
+    /** Where the frame reads and writes (law 1). */
+    get address() {
+        return this._address;
+    }
+    /**
+     * 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) {
+        this._address = address;
+    }
+    /** The two dials the frame encodes under from its next buffer and its next read on (law 4, 5). */
+    useEncoding(encoding) {
+        this.encoding = encoding;
+    }
+    /** The redacted mirror, if the run keeps one. */
+    get mirror() {
+        return this._mirror;
+    }
+    /** Land every commit from now on on `mirror` too, with the scrubbed rows the log takes (`recordCommit`). */
+    useMirror(mirror) {
+        this._mirror = mirror;
+    }
+    /** The absolute path of `key` under `path`: the frame's address, then the path, then the key. */
+    at(path, key) {
+        // Every read and write builds one. The root's is the path and the key; under an address, an
+        // index loop — the double spread `[...address, ...path, key]` costs a third more per call
+        // (as `utils · pathUnder` found for the address and the path).
+        const address = this._address;
+        if (address.length === 0)
+            return [...path, key];
+        const out = new Array(address.length + path.length + 1);
+        for (let i = 0; i < address.length; i++)
+            out[i] = address[i];
+        for (let i = 0; i < path.length; i++)
+            out[address.length + i] = path[i];
+        out[out.length - 1] = key;
+        return out;
+    }
+    /**
+     * ── 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).
+     */
+    firstTouch() {
+        if (!this.base) {
+            this.base = this.state.getState();
+        }
+        return this.base;
+    }
+    /**
+     * 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.
+     */
+    getTransactionBuffer() {
+        if (!this.buffer) {
+            // Per-write provenance (#P1): hand the buffer a live view of this frame's read prefix —
+            // evaluated AT EACH WRITE, so each staged op captures exactly the reads that preceded it.
+            const readKeysProvider = this.encoding?.writeProvenance === 'reads-prefix' ? () => [...(this.readKeys ?? [])] : undefined;
+            // The frame's address (9.30.0: the admitted record reads the containers there as where the
+            // stage writes, never as a value it read).
+            this.buffer = new TransactionBuffer(this.firstTouch(), this.encoding?.commitValues, readKeysProvider, this._address);
+        }
+        return this.buffer;
+    }
+    /**
+     * 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, value, verb, scrub) {
+        const buffer = this.getTransactionBuffer();
+        const whole = scrub?.whole === true;
+        if (verb === 'merge')
+            buffer.merge(path, value, whole);
+        else if (verb === 'delete')
+            buffer.delete(path, whole);
+        else
+            buffer.set(path, value, whole);
+        if (scrub?.fields !== undefined)
+            buffer.markRedactedFields(path, scrub.fields);
+    }
+    /** Has the frame staged a write since its last release — does its buffer exist? */
+    get hasStaged() {
+        return this.buffer !== undefined;
+    }
+    /**
+     * 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, key) {
+        const at = this.at(path, key);
+        const fromSnapshot = this.buffer ? this.buffer.get(at) : nativeGet(this.firstTouch(), at);
+        if (typeof fromSnapshot !== 'undefined')
+            return fromSnapshot;
+        const live = this.state.getValue(this._address, path, key);
+        // Tier 2 after the first write: keep the diff base exact (see above).
+        if (this.buffer && live !== null && typeof live === 'object')
+            this.buffer.detachBase(at);
+        return live;
+    }
+    /** Put a tracked read's user-level key on the readKeys list (law 5) — a no-op unless the frame keeps one. */
+    noteRead(path, key) {
+        if (this.encoding?.writeProvenance === 'reads-prefix') {
+            (this.readKeys ??= new Set()).add(path.length > 0 ? [...path, key].join('.') : key);
+        }
+    }
+    /**
+     * 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) {
+        return this.state.getValue(this._address, [], key);
+    }
+    /** Live committed state at `key` at the root — typed as `SharedMemory · getValue` (`StageContext · getGlobal`). */
+    readGlobal(key) {
+        return this.state.getValue([], [], key);
+    }
+    /** Did a staged op touch `path` — on it, above it or below it? (A report's question; never the hot path.) */
+    wasStaged(path) {
+        return this.buffer !== undefined && this.buffer.wasStaged(path);
+    }
+    /**
+     * 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) {
+        return this.buffer ? this.buffer.peek(path) : nativeGet(this.firstTouch(), path);
+    }
+    /** The value at `path` in the first-touch base — committed state as the frame first touched it. */
+    baseAt(path) {
+        return nativeGet(this.firstTouch(), path);
+    }
+    /**
+     * 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) {
+        const payload = this.buffer?.commit();
+        recordCommit(payload, stampOf(), { state: this.state, mirror: this._mirror, log: this.log });
+    }
+    /**
+     * 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() {
+        this.buffer = undefined;
+        this.base = undefined;
+    }
+    /**
+     * 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() {
+        this.release();
+        this.readKeys = undefined;
+    }
+}

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

@@ -0,0 +1,46 @@
+/**
+ * SharedMemory — The shared state container for all flowchart execution
+ *
+ * Like a runtime heap with namespace isolation:
+ * - A value is written at an ADDRESS — a path prefix the caller computed
+ *   (C2: the engine's frame decides it, `runAddress.ts · runAddress`) — and read
+ *   there first, then at the root
+ * - Default values seed the root, and the container at an address when a
+ *   write creates it
+ * - Accepts commit bundles from TransactionBuffer
+ *
+ * COPY-ON-WRITE (9.29.0 — docs/design/2026-10-copy-on-write-commit.md):
+ * `context` is a GENERATION, and a generation is never edited. Every write —
+ * `applyPatch` (a stage commit), `setValue`, `updateValue` — builds the next
+ * generation by copying the root and the containers on each written path,
+ * shares every other subtree with the generation before it, and swaps. So a
+ * generation a stage captured (its first-touch view, its transaction
+ * buffer's diff base) stays exactly what it was, and a write costs O(what it
+ * wrote), not O(state).
+ */
+import type { MemoryPatch, TraceEntry } from './types.js';
+export declare class SharedMemory {
+    private context;
+    private _defaultValues?;
+    constructor(defaultValues?: unknown, initialContext?: unknown);
+    /** Gets a clone of the default values. */
+    getDefaultValues(): {} | undefined;
+    /** Updates a value at `address` + `path` using merge semantics, as a new generation (path copy + swap). */
+    updateValue(address: readonly string[], path: string[], key: string, value: unknown): void;
+    /** Sets a value at `address` + `path` using overwrite semantics, as a new generation (path copy + swap). */
+    setValue(address: readonly string[], path: string[], key: string, value: unknown): void;
+    /**
+     * A copy of the current generation's root whose containers on the way to
+     * `key` are owned — the in-place helpers above then edit only copies.
+     */
+    private ownedPathTo;
+    /**
+     * Reads a value from the store.
+     * Looks up at `address` first, falls back to the root.
+     */
+    getValue(address?: readonly string[], path?: string[], key?: string): any;
+    /** Gets the entire state as a JSON object — the current generation, by reference. Never mutate it. */
+    getState(): Record<string, unknown>;
+    /** Applies a commit bundle from TransactionBuffer: builds the next generation and swaps it in. */
+    applyPatch(overwrite: MemoryPatch, updates: MemoryPatch, trace: TraceEntry[]): void;
+}

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

@@ -0,0 +1,87 @@
+/**
+ * SharedMemory — The shared state container for all flowchart execution
+ *
+ * Like a runtime heap with namespace isolation:
+ * - A value is written at an ADDRESS — a path prefix the caller computed
+ *   (C2: the engine's frame decides it, `runAddress.ts · runAddress`) — and read
+ *   there first, then at the root
+ * - Default values seed the root, and the container at an address when a
+ *   write creates it
+ * - Accepts commit bundles from TransactionBuffer
+ *
+ * COPY-ON-WRITE (9.29.0 — docs/design/2026-10-copy-on-write-commit.md):
+ * `context` is a GENERATION, and a generation is never edited. Every write —
+ * `applyPatch` (a stage commit), `setValue`, `updateValue` — builds the next
+ * generation by copying the root and the containers on each written path,
+ * shares every other subtree with the generation before it, and swaps. So a
+ * generation a stage captured (its first-touch view, its transaction
+ * buffer's diff base) stays exactly what it was, and a write costs O(what it
+ * wrote), not O(state).
+ */
+import { mergeContextWins, ownedRootOf, ownSpine } from './pathOps.js';
+import { getNestedValue, getRunAndGlobalPaths, isDeniedWritePath, nextGeneration, setNestedValue, updateNestedValue, } from './utils.js';
+export class SharedMemory {
+    context = {};
+    _defaultValues;
+    constructor(defaultValues, initialContext) {
+        this._defaultValues = defaultValues;
+        const seed = mergeContextWins(initialContext || {}, defaultValues || {});
+        // Detached ONCE, here: `mergeContextWins` copies only the top level, so
+        // the seed's nested values are the caller's own objects. Before 9.29.0
+        // the first commit's whole-state clone detached them (and until then a
+        // caller mutating its `initialContext` changed live state with no row);
+        // nothing re-clones the state any more, so the seed is detached at
+        // construction — one clone per runtime, not one per commit.
+        this.context = Object.keys(seed).length > 0 ? structuredClone(seed) : seed;
+    }
+    /** Gets a clone of the default values. */
+    getDefaultValues() {
+        return this._defaultValues ? structuredClone(this._defaultValues) : undefined;
+    }
+    /** Updates a value at `address` + `path` using merge semantics, as a new generation (path copy + swap). */
+    updateValue(address, path, key, value) {
+        const next = this.ownedPathTo(address, path, key);
+        if (next === undefined)
+            return;
+        updateNestedValue(next, address, path, key, value, this.getDefaultValues());
+        this.context = next;
+    }
+    /** Sets a value at `address` + `path` using overwrite semantics, as a new generation (path copy + swap). */
+    setValue(address, path, key, value) {
+        const next = this.ownedPathTo(address, path, key);
+        if (next === undefined)
+            return;
+        setNestedValue(next, address, path, key, value, this.getDefaultValues());
+        this.context = next;
+    }
+    /**
+     * A copy of the current generation's root whose containers on the way to
+     * `key` are owned — the in-place helpers above then edit only copies.
+     */
+    ownedPathTo(address, path, key) {
+        if (isDeniedWritePath(address, path, key))
+            return undefined;
+        const owned = new WeakSet();
+        const root = ownedRootOf(this.context, owned);
+        const { runPath, globalPath } = getRunAndGlobalPaths(address, path);
+        ownSpine(root, [...(runPath || globalPath), key], owned);
+        return root;
+    }
+    /**
+     * Reads a value from the store.
+     * Looks up at `address` first, falls back to the root.
+     */
+    getValue(address, path, key) {
+        const { globalPath, runPath } = getRunAndGlobalPaths(address, path);
+        const value = runPath ? getNestedValue(this.context, runPath, key) : undefined;
+        return typeof value !== 'undefined' ? value : getNestedValue(this.context, globalPath, key);
+    }
+    /** Gets the entire state as a JSON object — the current generation, by reference. Never mutate it. */
+    getState() {
+        return this.context;
+    }
+    /** Applies a commit bundle from TransactionBuffer: builds the next generation and swaps it in. */
+    applyPatch(overwrite, updates, trace) {
+        this.context = nextGeneration(this.context, updates, overwrite, trace);
+    }
+}