foottrace 0.0.0-stage → 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,27 @@
+/** Read a recorded execution: replay, time travel, slicing and attribution. */
+export type { CommitIdx, ExecutionCounter, ExecutionIndex, RuntimeStageId } from './lib/ids/runtimeStageId.js';
+export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId, splitStageId, } from './lib/ids/runtimeStageId.js';
+export { UnknownVerbError } from './lib/memory/verbs.js';
+export type { CommitBundle, MemoryPatch, TraceEntry } from './lib/memory/types.js';
+export type { ExecutionTree } from './lib/memory/types.js';
+export { applySmartMerge } from './lib/memory/verbs.js';
+export type { ValueBasis, ValueBasisOptions, ValueWithBasis, WriterBasis, WriterWithBasis, } from './lib/memory/commitLogUtils.js';
+export { buildCommitIndex, commitIndexOf, commitValueAt, commitValueAtWithBasis, findCommit, findCommits, findLastWriter, findLastWriterWithBasis, inferLegacyPhases, recordsPhases, } from './lib/memory/commitLogUtils.js';
+export type { CommitPhase } from './lib/memory/types.js';
+export type { AxisRefusal, AxisSplit, BookendedAxis, FoldBasis, FoldedState, FoldSource, LogGap, Mark, Move, MoveRefusal, Stop, StopFilter, StopKind, TimeTravel, TimeTravelOptions, TimeTravelSource, TimeTravelStrategy, } from './lib/time-travel/index.js';
+export { commitStops, commitStopsStrategy, filterStops, isCommitBundle, splitAxis, stateAt, tagStops, timeTravel, } from './lib/time-travel/index.js';
+export type { CausalChainOptions, CausalEdge, CausalNode, ControlDependency, ControlDepLookup, EdgeWeigher, KeysReadLookup, } from './lib/memory/backtrack.js';
+export { causalChain, flattenCausalDAG, formatCausalChain } from './lib/memory/backtrack.js';
+export type { UntrackedSource } from './lib/memory/types.js';
+export type { ArrayProvenance, AttributionBasis, ElementBirth, FedBasis, ForwardEdge, ForwardNode, ForwardRead, ForwardSlice, ForwardSliceJSON, HonestyNote, HonestyNoteCode, KeyMoment, KeysReadSource, KeyTimeline, MissingProvenanceReason, MissingSliceReason, ReadsCoverage, SliceJSON, StateKey, VariableSlice, } from './lib/slice/index.js';
+export type { ForwardSliceForKeyOptions, KeyTimelineOptions, SliceForKeyOptions } from './lib/slice/index.js';
+export { arrayProvenance, elementProvenance, formatForwardSlice, formatSlice, formatTimeline, forwardSliceForKey, forwardSliceToJSON, keysReadFromExecutionTree, keysReadFromMap, keyTimeline, resolveKeysReadSource, sliceForKey, sliceToJSON, } from './lib/slice/index.js';
+export type { HonestyCode } from './lib/memory/honesty.js';
+export { HONESTY_CODES } from './lib/memory/honesty.js';
+export type { RangeEntry, RangeToken } from './lib/recorder/CommitRangeIndex.js';
+export { CommitRangeIndex } from './lib/recorder/CommitRangeIndex.js';
+export type { CommitValuesMode } from './lib/memory/types.js';
+export type { EmitSourcePosition, LogAddress } from './lib/memory/eventPosition.js';
+export { EXECUTION_DELIMITER, PATH_DELIMITER, isExecutionKey, joinPath, pathSegments as idPathSegments, stageIdOf, subflowSegmentsOf, } from './lib/ids/runtimeStageId.js';
+export { deepEqual } from './lib/memory/equality.js';
+export { serveRecord } from './lib/capture/freeze.js';

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

@@ -0,0 +1,91 @@
+/**
+ * freeze.ts — the ONE deep-freeze walk (moved here from `scope/protection/readonlyInput.ts` in F3),
+ * and the serve-time law for the commit log (9.44.2).
+ *
+ * WHY HERE. Saved trees freeze through this walk: the fold base served as
+ * `initialState` (`ExecutionRuntime · getFoldBase`), the
+ * dev-mode snapshot (`runner/snapshot.ts · servedSnapshot`), every state `stateAt` hands out
+ * (`time-travel/stateAt.ts`) and, since F3, every commit bundle (`EventLog · record`). `memory/` must
+ * not import `scope/` (that edge closed the memory ⇄ scope ⇄ recorder module cycle F0 removed), so the
+ * walk lives in this leaf folder, which imports nothing outside itself. Args use an ownership snapshot
+ * instead (`scope/protection/readonlyInput.ts · createFrozenArgs`): never freeze borrowed caller values.
+ *
+ * FREEZE WHAT CAN BE FROZEN, COPY WHAT CAN'T (9.44.2). `Object.freeze` cannot seal a Date's time, a
+ * Map's or Set's entries, a buffer's bytes, a RegExp (`compile()` rewrites a frozen one) or an Error
+ * (V8's own `stack` accessor writes through a frozen one). A fresh tree handed to one caller (a `stateAt`
+ * state, the dev-mode snapshot) is that caller's own, so freezing it is a guard and nothing more. The
+ * COMMIT LOG — each bundle, and the fold base — is served to every reader, so {@link freezeRecord}
+ * remembers that a record holds such a value, its first serve maps the containers on the way to each
+ * one (its open PATHS), and {@link serveRecord} hands a reader a copy of those paths only: a fresh copy
+ * of each such value, fresh frozen containers on the way to it, and every other part shared, frozen, as
+ * it is. Until 9.44.2 `snapshot.commitLog[i].overwrite.when.setTime(0)` rewrote every later snapshot,
+ * `stateAt`, `commitValueAt`, slice and cursor answer.
+ *
+ * Every walk here is ITERATIVE (an explicit stack): a record's depth is not bounded by the call stack.
+ *
+ * @example
+ * ```typescript
+ * import { deepFreeze, freezeRecord, serveRecord } from './freeze.js';
+ *
+ * const args = deepFreeze({ order: { lines: [{ sku: 'A' }] }, bytes: new Uint8Array([1]) });
+ * Object.isFrozen(args.order.lines[0]); // true
+ * Object.isFrozen(args.bytes); // false — a typed array cannot be frozen; it is skipped
+ *
+ * const record = freezeRecord({ when: new Date(0), tags: ['a'] });
+ * const served = serveRecord(record);
+ * served.when.setTime(5); // changes the reader's copy
+ * serveRecord(record).when.getTime(); // 0 — every serve is the record as recorded
+ * served.tags === record.tags; // true — the sealed part is shared, not copied
+ * serveRecord(freezeRecord({ n: 1 })); // a record freezing sealed whole: served as itself
+ * ```
+ */
+/**
+ * How {@link deepFreeze} walks an ARRAY.
+ *
+ * - `'every-key'` (the default) — every own property, as for any other object: the index elements
+ *   AND any expando (`arr.note = { … }`). The dev-mode snapshot relies on this contract.
+ * - `'indices'` — the index elements only, so no key string is allocated per element; this is what
+ *   keeps freezing a 10,000-element commit inside its budget (`bench/element-writes.ts`). An object
+ *   hung on an array EXPANDO is then left unfrozen, and unseen by {@link serveRecord} — the commit
+ *   log's named hole (`EventLog · record`; an array expando is out of contract for state).
+ */
+export type ArrayWalk = 'every-key' | 'indices';
+/**
+ * Freezes `obj` and every object reachable through its own properties, and returns `obj`.
+ *
+ * - An object that is ALREADY frozen is left as it is, and not descended — 9.32.0's contract, kept:
+ *   args may hold a caller's frozen object with live parts inside (a class instance a stage calls),
+ *   and freezing past it would break them. It is also what ends a cycle. The commit log never meets
+ *   one: its payloads are fresh `structuredClone`s.
+ * - ArrayBuffer views (typed arrays, `DataView`) are skipped: `Object.freeze` throws on a non-empty
+ *   typed array, so a `Uint8Array` in state, args or the fold base used to fail the run or the
+ *   snapshot here.
+ * - What `Object.freeze` cannot reach stays mutable — Map and Set contents, a Date's time, the
+ *   bytes behind a buffer. A frozen RegExp's `lastIndex` is read-only, so a `/g` or `/y` regex
+ *   taken from a frozen tree throws when `exec` or `replace` advance it. The commit log goes through
+ *   {@link freezeRecord} and {@link serveRecord} instead.
+ * - Functions are not descended (they are not values the engine stores).
+ */
+export declare function deepFreeze<T>(obj: T, arrays?: ArrayWalk): T;
+/**
+ * {@link deepFreeze} for a record many readers are SERVED (a commit bundle, the fold base), and two more
+ * things on the same walk:
+ *
+ *   - it remembers THAT the record holds a value freezing cannot seal — one flag; the record's first
+ *     serve maps WHERE (the containers on the way to each such value, its open paths), so the run pays
+ *     nothing more and {@link serveRecord} copies those paths and nothing else;
+ *   - a typed array or `DataView` that views a SLICE of a bigger buffer (a Node `Buffer` views its
+ *     shared pool) is replaced, in the record, by a copy of the bytes it views — the record keeps the
+ *     view's bytes, never the rest of the buffer (a resizable or shared buffer is kept as it is).
+ *
+ * A part frozen before is not frozen past (deepFreeze's contract) but is looked through, so a value
+ * freezing cannot seal inside it still opens the record. Returns `record`.
+ */
+export declare function freezeRecord<T extends object>(record: T, arrays?: ArrayWalk): T;
+/**
+ * The record as a reader may hold it — THE serve-time law: a record freezing sealed whole is served as
+ * itself (shared, no cost); any other as a copy of its open paths ({@link freezeRecord}): fresh frozen
+ * containers down to each value freezing cannot seal, a fresh copy of that value, and every other part
+ * shared, frozen, as it is. A copy is served the same way again.
+ */
+export declare function serveRecord<T>(record: T): T;

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

@@ -0,0 +1,18 @@
+/**
+ * The private L0 owner of own-slot writes. Selector validation belongs to
+ * pathOps: payload names (including `__proto__`) are ordinary data here.
+ * Neither operation flattens an existing own accessor or changes its flags.
+ */
+/**
+ * `target[name] = value`, preserving existing own-slot behavior while making
+ * a missing inherited name an OWN data property. Payload names such as
+ * `__proto__` are data, not setters or selector instructions. Shared by the
+ * record-serving and copy-on-write copies; this is not a public helper.
+ */
+export declare function putOwn(target: Record<string, unknown>, name: string | number, value: unknown): void;
+/**
+ * Nested diagnostic writers require a missing slot to be CREATED, not merely
+ * assigned. Keep that contract separate from putOwn: an out-of-range typed
+ * array index is an assignment no-op, but cannot be defined as an own slot.
+ */
+export declare function setOwnValue(target: Record<string, unknown>, name: string | number, value: unknown): void;

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

@@ -0,0 +1,57 @@
+/**
+ * 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

@@ -0,0 +1,173 @@
+/**
+ * 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

@@ -0,0 +1,105 @@
+/**
+ * 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)` (foottrace) folds the
+     * same log but its `commitIdx` is INCLUSIVE, because a reader's cursor asks
+     * "the state AT this stop", which must include that stop's own commit. Two
+     * folds over one log with opposite conventions: check which one you hold.
+     *
+     * One clone of the base per call, then every bundle replayed INTO that
+     * private copy (`applySmartMergeInto` — the live commit's copy-on-write law
+     * below the root, 9.29.0, so the fold and the live state agree at every
+     * path). The result is the caller's: it shares nothing with the base or
+     * the log.
+     *
+     * @deprecated Since 9.33.0 — use `stateAt` from `foottrace`, which folds the same log
+     * from the same base (`RuntimeSnapshot.initialState`) and says how it was derived (`basis`).
+     * Nothing in the library calls this; it stays for one minor and is then removed. Mind the
+     * index: `materialise(n)` folds commits `0..n-1`, `stateAt(source, n - 1)` the same commits.
+     */
+    materialise(stepIdx?: 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 (`foottrace/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;
+}