footprintjs 9.45.0 → 9.46.1

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

@@ -2,35 +2,35 @@
  * StageContext — Execution context for a single stage in a flowchart run
  *
  * Like a stack frame in a compiler/runtime:
- * - Reference to SharedMemory (accessing heap memory)
- * - TransactionBuffer for staging mutations (transaction buffer)
+ * - A RecordFrame — the record half (C3): the heap, the address, the
+ *   first-touch base, the lazy transaction buffer and every write's scrub
+ *   (C4), the readKeys list
  * - Links to parent/child/next contexts (call stack frames)
+ * - What belongs to a stage inside a run: retention of reads and writes, the
+ *   redaction decision per write (`redaction.ts · decideWrite`) and where the
+ *   frame writes (`runAddress.ts`), the dev-mode warnings, the commit observer
  * - DiagnosticCollector for logs, errors, metrics
  */
 import { type DiagnosticChannel, DiagnosticCollector } from './DiagnosticCollector.js';
-import { EventLog } from './EventLog.js';
+import type { EventLog } from './EventLog.js';
 import type { EmitSourcePosition } from './eventPosition.js';
 import type { RedactionVerdict } from './redaction.js';
 import { RedactionRule } from './redaction.js';
 import type { RunPolicy } from './runPolicy.js';
-import { SharedMemory } from './SharedMemory.js';
-import { TransactionBuffer } from './TransactionBuffer.js';
+import type { SharedMemory } from './SharedMemory.js';
 import type { CommitPhase, FlowControlType, StageSnapshot, UntrackedSource } from './types.js';
 export declare class StageContext {
-    private sharedMemory;
     /**
-     * Parallel redacted mirror of `sharedMemory`. Populated in `commit()` with
-     * the already-computed redacted patches (the same ones fed to `eventLog`).
-     * Present **only** when the executor has been told to maintain a redacted
-     * view — i.e. when a `RedactionPolicy` is configured. Otherwise undefined,
-     * zero extra work per commit.
-     *
-     * The mirror is read via `FlowChartExecutor.getSnapshot({ redact: true })`
-     * and is the foundation for the "export trace" / paste-into-viewer feature
-     * — consumers share the redacted view externally without leaking raw PII
-     * through `sharedState`.
+     * 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;
+     * the first-touch base; the lazy transaction buffer; the readKeys list.
+     * Every state read of this frame goes through it, and so does every
+     * commit. The mirror is present **only** when the run's policy keeps a
+     * redacted view (a `RedactionPolicy` is configured) — read via
+     * `FlowChartExecutor.getSnapshot({ redact: true })`, the foundation for
+     * sharing a trace without leaking raw PII through `sharedState`.
      */
-    private redactedSharedMemory?;
+    private readonly record;
     /**
      * The run's policy — the four dials, the redaction rule, the mirror flag
      * (`runPolicy.ts`, F5). Held BY REFERENCE: one frozen object per run (and
@@ -40,15 +40,6 @@ export declare class StageContext {
      * ({@link usePolicy}). Never edited; a change is a new object.
      */
     private policy;
-    private buffer?;
-    /**
-     * Committed-state view captured at this stage's FIRST touch (first read OR
-     * first write) — held by REFERENCE, never cloned. See
-     * {@link firstTouchState} for the algorithm and the immutability invariant
-     * that makes a bare reference safe.
-     */
-    private stateView?;
-    private eventLog?;
     /** The emitting frame's logical leg, never the mutable executor's current leg. */
     private emitRunId?;
     stageName: string;
@@ -65,7 +56,13 @@ export declare class StageContext {
      * none — the same once-per-execution law `_untrackedSources` keeps.
      */
     tags?: readonly string[];
-    runId: string;
+    /**
+     * The run this frame belongs to — its identity on every event, and the run
+     * namespace it reads and writes in ({@link runAddress}), read once, when the
+     * frame is built (C3). Only {@link useAddressOf} moves the address after
+     * that, and only before the first write.
+     */
+    readonly runId: string;
     /**
      * The run namespace this frame writes and reads in when that is not its own
      * `runId` — set once, before the frame's first write, by
@@ -128,11 +125,6 @@ export declare class StageContext {
      * tier (`ScopeFacade`, one per stage execution), not here.
      */
     private _committed;
-    /** Lazily-allocated ordered registry of keys tracked-read in THIS stage —
-     *  the source of the per-write prefix. Only allocated under the
-     *  `'reads-prefix'` dial; insertion-ordered (a Set) and monotonic, which
-     *  is what makes "last write's prefix == union" hold in delta mode. */
-    private _provenanceReads?;
     /** Tracked reads of a selected value ({@link selectedReads}). */
     private _selectedReads;
     /** Each object this frame read under a selected name → that read's verdict (`stageWrite` hands it on). */
@@ -159,7 +151,7 @@ export declare class StageContext {
     /**
      * Install a parallel redacted mirror. Subsequent `commit()` calls apply
      * the already-computed redacted patches — the ones the log records — to
-     * this mirror, beside the raw patches on `sharedMemory` (`recordCommit`).
+     * this mirror, beside the raw patches on the heap (`recordCommit`).
      * Child / next contexts inherit the mirror via `createNext` / `createChild`.
      *
      * Called on a runtime's root frame by `ExecutionRuntime` when the run's policy keeps a mirror.
@@ -198,6 +190,12 @@ export declare class StageContext {
      * {@link createChild} both call it, and it names no dial.
      */
     private inheritRun;
+    /**
+     * The ONE place this frame's policy changes: the frame holds it, and its
+     * record frame encodes under the same reference (`commitValues`,
+     * `writeProvenance` — `RecordFrame · useEncoding`), so the two never differ.
+     */
+    private adoptPolicy;
     /**
      * Record a tracked user-level write, policy-gated (#13c-A) — the single
      * bookkeeping path for {@link setObject} and {@link updateObject}. Holds
@@ -210,10 +208,10 @@ export declare class StageContext {
      * and stores nothing under `'off'` (entry skipped entirely — nothing to
      * leak). A field-level verdict scrubs a clone BEFORE the dial sees it, so
      * a summary preview can never show the secret either. The verdict is the
-     * one `stageWrite` asked the rule for BEFORE staging, carried to commit
-     * with the value. The staged write itself is unaffected — redaction of
-     * the committed payload is handled by the transaction buffer's
-     * `redactedPaths`.
+     * one `stageWrite` decided BEFORE staging, carried to commit with the
+     * value. The staged write itself is unaffected — redaction of the
+     * committed payload is the record frame's scrub of that write
+     * (`RecordFrame · write`, then `scrub.ts` at commit).
      */
     private trackWrite;
     /**
@@ -247,80 +245,21 @@ export declare class StageContext {
     /**
      * THE ONE FUNNEL every staged write passes through — facade writes AND
      * the paths that bypass the facade (subflow seed, `outputMapper`
-     * merge-back, resume re-seed). The ONE decision is made here: an explicit
-     * per-call flag makes the value secret outright (and marks the key for the
-     * rest of the run, the declare-once contract); otherwise the installed
-     * rule decides from the user-level path. It stages the write, registers
-     * the redacted paths the commit log and mirror will scrub (whole key, or
-     * the fields inside the value), and keeps the run's marked-keys set in
-     * step (a whole verdict marks its key; a delete clears the mark). Returns
-     * the verdict so the caller retains and reports under the same decision.
+     * merge-back, resume re-seed). Two owners (C4): the run's rule DECIDES,
+     * the record frame WRITES the verdict's bytes, in four steps
+     * (`redaction.ts`, "The write decision"):
+     *   1. the verdict — `decideWrite`, under the rule active as the write begins;
+     *   2. identity inheritance — `inheritByIdentity`, against this frame's
+     *      selected reads as they stand after step 1;
+     *   3. the bytes — `RecordFrame · write`, the op and its scrub (the whole
+     *      value, or the fields inside it);
+     *   4. the marks — `markStagedWrite`, only once the write staged, so a
+     *      write that fails to stage marks nothing.
+     * Each step reads the rule (and the selected reads) when it acts, as this
+     * funnel always did. Returns the verdict so the caller retains and reports
+     * under the same decision.
      */
     private stageWrite;
-    /**
-     * ── The first-touch state view (#13) ────────────────────────────────────
-     *
-     * WHAT: returns the committed shared state as it was at this stage's FIRST
-     * touch (first read or first write), capturing the reference on first call.
-     * Serves two consumers: reads before the first write ({@link readState})
-     * 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 firstTouchState;
-    /** Lazily creates the transaction buffer on the stage's FIRST WRITE (#13).
-     *
-     *  Reads NEVER construct it: read-your-writes only matters once a staged
-     *  write exists, so before that {@link getValue}/{@link getValueDirect}
-     *  serve from the first-touch state view 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
-     *  stage'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 firstTouchState}. */
-    getTransactionBuffer(): TransactionBuffer;
-    /**
-     * Where this frame writes and reads: `['runs', <id>]`, or `[]` (the root) with
-     * no run id. Handed to the record layer as data (C2): the buffer's address,
-     * and where `SharedMemory · getValue` looks before the root.
-     */
-    private get address();
-    /** Builds an absolute path inside the shared memory: this frame's {@link address}, then the path. */
-    private withNamespace;
-    /** The run namespace writes and reads go to: {@link addressRunId}, else `runId`. */
-    private get namespaceId();
     /**
      * Write and read at ANOTHER frame's address (its run namespace) while this
      * frame keeps its own identity on the record — `stage`, `stageId`,
@@ -328,9 +267,13 @@ export declare class StageContext {
      * (`SubflowExecutor · executeSubflow`, R13): the mount frame of a branch or
      * fork child lands its values where its parent writes, as before, and its
      * bundle now names the mount instead of the stage before it. Refused once
-     * the frame has staged anything — its buffer's address is fixed then.
+     * the frame has staged anything — its buffer's address is fixed then. The
+     * decision is the engine's (namespace ids, as since R13); the record frame
+     * takes the address it comes to (`RecordFrame · useAddress`).
      */
     useAddressOf(frame: StageContext): void;
+    /** The run namespace writes and reads go to: {@link addressRunId}, else `runId`. */
+    private get namespaceId();
     patch(path: string[], key: string, value: unknown, shouldRedact?: boolean): RedactionVerdict;
     set(path: string[], key: string, value: unknown): void;
     merge(path: string[], key: string, value: unknown, shouldRedact?: boolean): RedactionVerdict;
@@ -342,26 +285,6 @@ export declare class StageContext {
     updateGlobalContext(key: string, value: unknown): void;
     appendToArray(path: string[], key: string, items: unknown[], description?: string): void;
     mergeObject(path: string[], key: string, obj: Record<string, unknown>, description?: string): void;
-    /** Buffer-aware read, mirroring the eager engine's read order byte-for-byte:
-     *
-     *    1. staged writes + first-touch snapshot — `buffer.get` over its
-     *       workingCopy when the buffer exists, else `nativeGet` over the
-     *       zero-clone state view (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 run→global namespace fallback. The eager
-     *       engine had this exact live fallback for snapshot-missing keys;
-     *       byte-identity over purity. After the stage'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 stage that never writes
-     *  performs zero clones of the shared state. */
-    private readState;
     /**
      * Tracked read. The returned value is BORROWED — see the contract on
      * `ScopeFacade.getValue`. Read-tracking cost is policy-gated (#14):
@@ -420,8 +343,8 @@ export declare class StageContext {
      * those are engine reads (the subflow merge-back), not user reads.
      *
      * It also only looks at keys served from the PINNED source — the first-touch
-     * view or this stage's own buffer. A key absent from both was served by
-     * `readState`'s live fallback, which a parallel sibling's root-key commit can
+     * view or this stage's own buffer. A key absent from both was served by the
+     * read's live fallback (`RecordFrame · read`, tier 2), which a parallel sibling's root-key commit can
      * legitimately move; accusing the stage there would be a false alarm. For
      * the same reason it runs on the frame's FIRST commit only: the reads belong
      * to that round, and by the engine's second round (a fork double-commit, a
@@ -453,21 +376,16 @@ export declare class StageContext {
      * `outputMapper` (a lazy mount, every `parallelForEach` branch), whose exit
      * is its only bundle, records that bundle as its own, tags and all.
      *
-     * Commit is the stage's lifecycle end: `buffer` (its working copy and
-     * whatever private copies its reads took) and `stateView` (a reference that
-     * pins one committed-state GENERATION) are only needed DURING execution,
-     * as the read snapshot + net-change diff base. The execution tree retains
-     * every StageContext for the lifetime of the run, so WITHOUT the release a
-     * long loop retains one state generation per executed stage — measured
-     * O(N²) before copy-on-write (9.29.0), when each generation and each
-     * buffer was a whole-state clone: 563.8MB at N=200 on an agent-style
-     * chart; a 500-iteration agent OOMed a default Node heap (backlog #18).
-     * Generations now share every unchanged subtree, but a pinned one still
-     * keeps the containers later commits replaced alive.
+     * Commit is the stage's lifecycle end: the record frame's buffer and
+     * first-touch base are only needed DURING execution, as the read snapshot +
+     * net-change diff base, so the record frame releases them once the commit
+     * has landed and the observer has seen it (`RecordFrame · release` — why a
+     * frame that kept them would retain one state generation per executed
+     * stage, and why a re-used frame re-anchors on current state, is there).
      *
-     * RE-USE AFTER COMMIT stays correct because both fields re-create lazily:
-     * - a later READ re-anchors via {@link firstTouchState} on the CURRENT
-     *   committed state (which includes this stage's own flushed writes);
+     * RE-USE AFTER COMMIT stays correct because both re-create lazily:
+     * - a later READ re-anchors on the CURRENT committed state (which includes
+     *   this stage's own flushed writes);
      * - a later WRITE constructs a fresh buffer on that re-anchored view, so a
      *   second commit diffs against post-first-commit state. The pre-release
      *   buffer behaved the same for VALUES (its `workingCopy` was reset on
@@ -498,20 +416,18 @@ export declare class StageContext {
      * (M1: the transaction buffer holds writes until `commit()` flushes them).
      *
      * What is released, and why each one matters for the next attempt:
-     *  - `buffer`      — the staged writes themselves; the next attempt starts
-     *                    with nothing staged;
-     *  - `stateView`   — the first-touch anchor; the next attempt re-anchors on
-     *                    committed state as it stands NOW (a sibling fork branch
-     *                    may legitimately have committed in between);
+     *  - the record frame's staged state (`RecordFrame · discard`) — the buffer
+     *                    (the next attempt starts with nothing staged), the
+     *                    first-touch base (it re-anchors on committed state as
+     *                    it stands NOW — a sibling fork branch may legitimately
+     *                    have committed in between) and the readKeys list (#P1:
+     *                    a discarded attempt's reads must never reach the next
+     *                    attempt's `TraceEntry.readKeys`);
      *  - `_stageWrites` / `_pendingWrites` / `_stageReads` — the snapshot
      *                    payload; without the reset the execution tree would
      *                    report writes that were discarded, which is the exact
      *                    lie this feature exists to prevent (the pending map
      *                    holds bare references — dropping it un-clones nothing);
-     *  - `_provenanceReads` — the per-write read prefix (#P1); a discarded
-     *                    attempt's reads must never appear in the next attempt's
-     *                    `TraceEntry.readKeys`, or a backward slice would follow
-     *                    an edge that no committed write ever had;
      *  - `_untrackedSources` — the D2 honesty markers, released with the rest.
      *
      * What is deliberately KEPT: `debug` (logs, metrics, errors, flow messages).