footprintjs 9.48.2 → 10.0.0

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

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

package/dist/types/lib/ids/runtimeStageId.d.ts

@@ -1,173 +0,0 @@
-/**
- * runtimeStageId — unique identifier for each execution step during traversal.
- *
- * Format: [subflowPath/]stageId#executionIndex
- *
- * Components:
- *   stageId        — stable node ID from the builder ('call-llm', 'seed')
- *   executionIndex — monotonic counter incremented per stage execution (0, 1, 2...)
- *   subflowPath    — optional path for subflow stages ('sf-tools', 'sf-outer/sf-inner')
- *
- * Properties:
- *   - Unique within a run (executionIndex never repeats)
- *   - Execution-ordered (sort by executionIndex = execution order)
- *   - Human-readable ('sf-tools/execute-tool-calls#8')
- *   - Parseable (split on '#' for stageId and index, split stageId on '/' for subflow path)
- *
- * Naming-collision warning
- * ────────────────────────
- *   The parsed-output `.stageId` field below is the LOCAL form (segment
- *   after the last '/'). This is NOT the same as `spec.id` / `node.id`
- *   for subflow-nested stages, which carry the FULL prefixed form
- *   (`'sf-tools/execute-tool-calls'`). To compare safely, use
- *   `splitStageId(spec.id)` to decompose the prefixed form the same
- *   way `parseRuntimeStageId` decomposes a runtimeStageId.
- *
- * @example
- * ```
- * buildRuntimeStageId('call-llm', 5)                    // 'call-llm#5'
- * buildRuntimeStageId('execute-tool-calls', 8, 'sf-tools') // 'sf-tools/execute-tool-calls#8'
- * buildRuntimeStageId('validate', 3, 'sf-outer/sf-inner')  // 'sf-outer/sf-inner/validate#3'
- * ```
- *
- * ## The one owner (F7, 9.37.0)
- *
- * This module is the ONE place the grammar is spelled. Every reader asks it —
- * `isExecutionKey`, `stageIdOf`, `subflowPathOf`, `subflowSegmentsOf`,
- * `lastSegmentOf`, `isWithinSubflow` — and every composer joins through
- * `joinPath` / `buildRuntimeStageId`; no other file splits on `#` or `/`.
- * It builds, parses and reads ids, and imports nothing: it is the record's
- * (C6). The delimiters are RESERVED (RFC 3986 §2.2 style): the engine's id
- * doors refuse them in user-authored ids through ONE function,
- * `reservedIds.ts · refuseReservedId`, which reads them here — so
- * last-delimiter parsing is sound by construction rather than by hope. Stores
- * and the prefixer never refuse — they hold runtime ids and prefixed ids,
- * which carry the delimiters on purpose.
- */
-/** Separates subflow path segments from each other and from the stage id. */
-export declare const PATH_DELIMITER = "/";
-/** Separates the (prefixed) stage id from the execution index. */
-export declare const EXECUTION_DELIMITER = "#";
-declare const RUNTIME_STAGE_ID: unique symbol;
-declare const EXECUTION_INDEX: unique symbol;
-declare const COMMIT_IDX: unique symbol;
-/** A `[subflowPath/]stageId#executionIndex` string the grammar produced. Assignable to `string`. */
-export type RuntimeStageId = string & {
-    readonly [RUNTIME_STAGE_ID]: true;
-};
-/** The run-global, monotonic position of one stage execution (the `#N`). Assignable to `number`. */
-export type ExecutionIndex = number & {
-    readonly [EXECUTION_INDEX]: true;
-};
-/** A bundle's position in a commit log (`bundle.idx`). Assignable to `number`. */
-export type CommitIdx = number & {
-    readonly [COMMIT_IDX]: true;
-};
-/**
- * Build a runtimeStageId from its components.
- *
- * Note: The traverser does NOT use the subflowPath parameter — node.id already
- * includes the subflow prefix from the builder. This parameter exists for external
- * consumers constructing IDs from parsed components (round-trip via parseRuntimeStageId).
- */
-export declare function buildRuntimeStageId(stageId: string, executionIndex: number, subflowPath?: string): RuntimeStageId;
-/**
- * Parse a runtimeStageId into its components.
- *
- * IMPORTANT — naming collision: the returned `stageId` is the LOCAL
- * form (the segment between the last '/' and the '#'). This is NOT
- * the same as `spec.id` or `node.id` for subflow-nested stages,
- * which contain the FULL prefixed form.
- *
- *   parseRuntimeStageId('sf-tools/execute-tool-calls#8').stageId
- *   // → 'execute-tool-calls'   (LOCAL)
- *
- *   node.id  // (post-mount, in a spec that contains subflows)
- *   // → 'sf-tools/execute-tool-calls'   (FULL prefixed)
- *
- * To compare these two safely, use `splitStageId(node.id)` to get
- * the local form, OR reconstruct the full form via
- * `(subflowPath ? subflowPath + '/' : '') + stageId`.
- */
-export declare function parseRuntimeStageId(runtimeStageId: string): {
-    stageId: string;
-    executionIndex: ExecutionIndex;
-    subflowPath: string | undefined;
-};
-/**
- * Decompose a (possibly prefixed) stage id into its components.
- *
- * Use this when you have an id WITHOUT the `#N` execution suffix and
- * need the local stage name and/or the subflow path. Common sources
- * of such ids:
- *   - `spec.id` (post-mount the id includes any subflow prefix)
- *   - `CommitBundle.stageId` (post-mount id)
- *   - `node.id` from xyflow nodes built off the spec
- *   - the segment of `runtimeStageId` BEFORE the `#` (use
- *     `parseRuntimeStageId` directly for full runtimeStageId strings)
- *
- * Mirrors the decomposition `parseRuntimeStageId` performs on the
- * stageId portion of a runtimeStageId, so the two helpers stay in
- * lockstep on naming and behavior.
- *
- * @example
- * splitStageId('sf-tools/execute-tool-calls')
- * // → { localStageId: 'execute-tool-calls', subflowPath: 'sf-tools' }
- *
- * splitStageId('execute-tool-calls')
- * // → { localStageId: 'execute-tool-calls', subflowPath: undefined }
- *
- * splitStageId('sf-outer/sf-inner/validate')
- * // → { localStageId: 'validate', subflowPath: 'sf-outer/sf-inner' }
- */
-export declare function splitStageId(prefixedStageId: string): {
-    localStageId: string;
-    subflowPath: string | undefined;
-};
-/**
- * True when `key` names one EXECUTION (`…#N`) rather than a stage or a subflow
- * path. Its presence alone decides: the delimiter is reserved in every
- * user-authored id (`reservedIds.ts · refuseReservedId`), so only the grammar
- * puts it there.
- *
- * Asked where a map is keyed by both — `subflowResults` is dual-keyed by
- * subflow path AND by mount runtimeStageId.
- */
-export declare function isExecutionKey(key: string): boolean;
-/**
- * The FULL (subflow-prefixed) stage id of a runtimeStageId — everything before
- * the last `#`, i.e. what `node.id` / `CommitBundle.stageId` hold. A string
- * with no `#` is returned whole.
- *
- * @example stageIdOf('sf-tools/execute#8') // 'sf-tools/execute'
- */
-export declare function stageIdOf(runtimeStageId: string): string;
-/** The execution index of a runtimeStageId, or `NaN` when it carries none. */
-export declare function executionIndexOf(runtimeStageId: string): number;
-/**
- * The subflow path a runtimeStageId executes in (`'sf-a/sf-b'`), or
- * `undefined` at the top level. Reads the stage-id part, so it agrees with
- * `splitStageId(stageIdOf(rid)).subflowPath`.
- */
-export declare function subflowPathOf(runtimeStageId: string): string | undefined;
-/** The subflow path of a runtimeStageId as segments (`['sf-a', 'sf-b']`); `[]` at the top level. */
-export declare function subflowSegmentsOf(runtimeStageId: string): string[];
-/** The non-empty segments of a subflow path or prefixed id (`'a//b/'` → `['a', 'b']`). */
-export declare function pathSegments(path: string): string[];
-/** The last segment of a path or prefixed id (`'sf-a/sf-b'` → `'sf-b'`); the whole string when it has none. */
-export declare function lastSegmentOf(path: string): string;
-/** Join path segments with the grammar's delimiter (`joinPath('sf', 'stage')` → `'sf/stage'`). */
-export declare function joinPath(...segments: readonly string[]): string;
-/** True when the (prefixed) id `id` sits INSIDE the subflow at `path` — at any depth below it. */
-export declare function isWithinSubflow(id: string, path: string): boolean;
-/**
- * Shared mutable counter for execution index.
- * Passed by reference to child traversers (subflows) so they
- * continue the global numbering instead of restarting at 0.
- */
-export interface ExecutionCounter {
-    value: number;
-}
-/** Create a new execution counter starting at 0. */
-export declare function createExecutionCounter(): ExecutionCounter;
-export {};

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

@@ -1,105 +0,0 @@
-/**
- * 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 type { EmitSourcePosition, LogAddress } from './eventPosition.js';
-import type { CommitBundle } from './types.js';
-export declare class EventLog {
-    /** Base snapshot BEFORE the first stage mutates anything. */
-    private base;
-    /** Ordered list of commit bundles. */
-    private steps;
-    private sourceAddress?;
-    private sourceAddressRetired;
-    constructor(initialMemory: any);
-    /**
-     * 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(): any;
-    /**
-     * 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)` (footprintjs/trace) 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 `footprintjs/trace`, 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?: number): any;
-    /**
-     * 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 (`footprintjs/write`) hands over a bundle it
-     * will no longer edit — its own object is the one frozen.
-     */
-    record(bundle: CommitBundle): void;
-    /**
-     * Every recorded commit bundle, AS SERVED (9.44.2): a new array each call; a bundle freezing sealed
-     * whole is the log's own (frozen) object, one holding a Date, Map, buffer … is a copy of its open
-     * paths (`capture/freeze.ts · serveRecord`) — the reader's own, so no edit reaches the log.
-     */
-    list(): CommitBundle[];
-    /**
-     * @internal The bundles as the log holds them — each frozen, NOT served — in a new array, so a holder's
-     * `splice` reaches only its own. For the engine's own snapshot (`ExecutionRuntime · getSnapshot`, which
-     * a subflow mount takes once per mount), so the run serves nothing; a reader is served by `list()` and
-     * `getSnapshot().commitLog`. A known open door (CHANGELOG 9.44.2): a holder of these bundles can still
-     * edit a Date, Map or buffer inside them.
-     */
-    recorded(): CommitBundle[];
-    /** Number of recorded commits. */
-    get length(): number;
-    /** Immutable identity of this log, absent until the engine binds it. */
-    get address(): LogAddress | undefined;
-    /** @internal Bind once; resuming the same log must not rename its earlier positions. */
-    bindAddress(logRunId: string, drillPath: readonly string[]): void;
-    /** O(1) source-time capture. No counter, observer bookkeeping, or future commit prediction. */
-    capturePosition(runId: string): EmitSourcePosition | undefined;
-    /** Wipes history (useful for test resets). */
-    clear(): void;
-}

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

@@ -1,232 +0,0 @@
-/**
- * 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;
-}

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

@@ -1,46 +0,0 @@
-/**
- * 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;
-}