footprintjs 9.44.3 → 9.46.0

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

@@ -2,35 +2,33 @@
  * 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, 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 verdict per write, 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 +38,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 +54,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 +123,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 +149,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 +188,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
@@ -257,64 +253,6 @@ export declare class StageContext {
      * 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;
-    /** Builds an absolute path inside the shared memory (run namespace). */
-    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`,
@@ -322,9 +260,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;
@@ -336,26 +278,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):
@@ -414,8 +336,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
@@ -447,21 +369,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
@@ -492,20 +409,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).

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

@@ -128,8 +128,9 @@ export declare class TransactionBuffer {
      */
     private detachedBase?;
     /**
-     * Where the stage writes (9.30.0): `['runs', runId]` for a run-namespaced
-     * stage, `[]` otherwise. Its containers are the stage's ADDRESS, not a value
+     * Where the stage writes (9.30.0): a path prefix its frame computed and
+     * hands over as data (C2 — for the engine, the frame's run namespace, or
+     * `[]` for the root). Its containers are the stage's ADDRESS, not a value
      * the stage reads (every read it makes is a key below it), so a shell a
      * write leaves there is no part of the read-back the record must hold.
      */
@@ -234,8 +235,8 @@ export declare class TransactionBuffer {
      * Keep the diff base exact under a read the working copy cannot answer.
      *
      * When `workingCopy` holds nothing at `path` — the stage deleted or unset
-     * it, or a write replaced a container above it — `StageContext ·
-     * readState` serves the read from LIVE committed state, exactly as 9.28.0
+     * it, or a write replaced a container above it — `RecordFrame · read`
+     * serves the read from LIVE committed state, exactly as 9.28.0
      * did, so the value it hands out is committed state itself. On 9.28.0 the
      * diff base was a whole-state clone taken at the stage's first write, and
      * an in-place edit of that value (out of contract — reads are borrowed)
@@ -275,7 +276,7 @@ export declare class TransactionBuffer {
      *  - a container still SHARED with committed state at the same position is
      *    replaced by a private deep copy when it is the value read, or by a
      *    shallow copy when it is a container on the way to it (so a read of
-     *    `runs/<id>/k` copies `k`, not every run's namespace);
+     *    `k` under a fork child's address copies `k`, not every child's namespace);
      *  - a container the stage STAGED (or anything else the buffer did not
      *    take from committed state) is handed back by reference, as before;
      *  - a container the buffer owns is walked on — and when it is the value

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

@@ -10,6 +10,8 @@
  * (`merge.ts`) at L0, and the verb law (`verbs.ts`) at L1 — `applySmartMerge`,
  * `nextGeneration`, `applySmartMergeInto`, `dryFold`, `supersededByNextSet`.
  * The log's scrub, `redactPatch`, moved to its owner `redaction.ts` in 9.33.0.
+ * The writers take an ADDRESS, a path prefix their caller computed, and never
+ * name one (C2: the engine decides where a stage writes, `StageContext.ts · runAddress`).
  * Zero external dependencies.
  */
 export { deepEqual } from './equality.js';
@@ -20,24 +22,26 @@ type NestedObject = {
     [key: string]: any;
 };
 /**
- * Resolves run-namespaced and global paths.
- * Each flowchart execution (run) stores data under `runs/{id}/` to prevent collisions.
+ * The two places a value at `path` can sit: under `address` (`runPath`, absent
+ * for the root address `[]`) and at the root (`globalPath`). `address` is a
+ * path prefix the caller computed — for the engine, a frame's run namespace
+ * (`StageContext.ts · runAddress`, C2), held by its record frame (`RecordFrame · address`, C3).
  */
-export declare function getRunAndGlobalPaths(runId?: string, path?: (string | number)[]): {
+export declare function getRunAndGlobalPaths(address?: readonly string[], path?: (string | number)[]): {
     runPath: (string | number)[] | undefined;
     globalPath: (string | number)[];
 };
 /**
- * Sets a value at a nested path, creating intermediate objects as needed.
+ * Sets a value at a nested path under `address`, creating intermediate objects as needed.
  */
-export declare function setNestedValue<T>(obj: NestedObject, runId: string, _path: string[], field: string, value: T, defaultValues?: unknown): NestedObject;
+export declare function setNestedValue<T>(obj: NestedObject, address: readonly string[], path: string[], field: string, value: T, defaultValues?: unknown): NestedObject;
 /**
- * Deep-merges a value into the object at the specified path.
+ * Deep-merges a value into the object at a nested path under `address`.
  * - Arrays: concatenate
  * - Objects: shallow merge at each level
  * - Primitives: replace
  */
-export declare function updateNestedValue<T>(obj: any, runId: string | undefined, _path: (string | number)[], field: string | number, value: T, defaultValues?: unknown): any;
+export declare function updateNestedValue<T>(obj: any, address: readonly string[], path: (string | number)[], field: string | number, value: T, defaultValues?: unknown): any;
 /**
  * In-place value update with merge semantics.
  * - Arrays (non-empty): concatenate onto existing

package/dist/types/lib/reactive/structuralWrite.d.ts

@@ -5,7 +5,7 @@
  * path inside the value I read, put this". The value it read is BORROWED —
  * before a stage's first staged write it is a bare reference into committed
  * shared memory, and committed state is immutable-after-swap (see
- * `StageContext.firstTouchState`). Editing it in place would corrupt every
+ * `RecordFrame · firstTouch`). Editing it in place would corrupt every
  * in-flight stage AND leave the commit log with nothing to record.
  *
  * So the write path never mutates. It COPIES the containers along the path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "9.44.3",
+  "version": "9.46.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",