foottrace 0.0.0-stage → 1.0.0

package/dist/esm/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/esm/lib/capture/valueKinds.js

@@ -0,0 +1,141 @@
+/**
+ * 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
+ * ```
+ */
+/**
+ * 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 const SEALABLE = /* @__PURE__ */ Object.freeze({
+    plain: true,
+    array: true,
+    boxed: true,
+    date: false, // setTime & co. write its time value
+    regexp: false, // compile() rewrites source and flags, even on a frozen one
+    map: false, // set / delete / clear
+    set: false, // add / delete / clear
+    error: false, // V8's own `stack` accessor writes through a frozen error
+    buffer: false, // its bytes, through any view; transfer() detaches it
+    view: false, // index writes, set, fill, sort, copyWithin …
+    opaque: false, // content this library cannot read — never assumed sealed
+});
+/** What a brand check returns, when it does not throw, for a value without the slot. */
+const NOT_BRAND = Symbol('not the brand');
+/**
+ * A built-in kind is known by its BRAND — an internal slot only the real thing has — never by its
+ * prototype: `Object.create(RegExp.prototype)` is not a RegExp (its clone is `{}`), and reading
+ * `source` from it throws. The candidate comes from `Object.prototype.toString` (one call), then ONE
+ * brand-checked read confirms it; a value that fails it is classified by its clone instead.
+ */
+const BRANDS = 
+/* @__PURE__ */ brandTable();
+function brandTable() {
+    const getter = (proto, key) => {
+        const get = proto && Object.getOwnPropertyDescriptor(proto, key)?.get;
+        return get ? (value) => get.call(value) : undefined;
+    };
+    const global = globalThis;
+    const isError = Error.isError;
+    const rows = [
+        ['Date', 'date', (value) => Date.prototype.getTime.call(value)],
+        ['RegExp', 'regexp', getter(RegExp.prototype, 'source')],
+        ['Map', 'map', getter(Map.prototype, 'size')],
+        ['Set', 'set', getter(Set.prototype, 'size')],
+        // An error's tag comes from its own [[ErrorData]] slot: no Error prototype carries a toStringTag. Where
+        // the brand check `Error.isError` is missing (Node 22), a tag a getter supplies is therefore a spoof.
+        ['Error', 'error', (value) => ((isError ? isError(value) : untagged(value)) ? true : NOT_BRAND)],
+        ['Number', 'boxed', (value) => Number.prototype.valueOf.call(value)],
+        ['String', 'boxed', (value) => String.prototype.valueOf.call(value)],
+        ['Boolean', 'boxed', (value) => Boolean.prototype.valueOf.call(value)],
+        ['BigInt', 'boxed', (value) => (global.BigInt?.prototype).valueOf.call(value)],
+        ['ArrayBuffer', 'buffer', getter(ArrayBuffer.prototype, 'byteLength')],
+        ['SharedArrayBuffer', 'buffer', getter(global.SharedArrayBuffer?.prototype, 'byteLength')],
+    ];
+    const table = new Map();
+    for (const [name, kind, check] of rows)
+        if (check)
+            table.set(`[object ${name}]`, { kind, check });
+    return table;
+}
+/** No `Symbol.toStringTag` on the value or its prototypes: its tag came from a slot. */
+function untagged(value) {
+    return value[Symbol.toStringTag] === undefined;
+}
+/** The kind of a built-in value, by its brand — `undefined` for anything else. */
+function builtinKind(value) {
+    if (ArrayBuffer.isView(value))
+        return 'view'; // a brand check of its own: [[ViewedArrayBuffer]]
+    const brand = BRANDS.get(Object.prototype.toString.call(value));
+    if (brand === undefined)
+        return undefined;
+    try {
+        return brand.check(value) === NOT_BRAND ? undefined : brand.kind;
+    }
+    catch {
+        return undefined; // the prototype without the slot
+    }
+}
+/** Prototypes classified by a probe clone of their first instance (see {@link kindOf}). */
+const PROBED = new WeakMap();
+/**
+ * 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 function kindOf(value) {
+    if (Array.isArray(value))
+        return 'array';
+    const proto = Object.getPrototypeOf(value);
+    if (proto === Object.prototype || proto === null)
+        return 'plain';
+    return builtinKind(value) ?? PROBED.get(proto) ?? probe(value, proto);
+}
+function probe(value, proto) {
+    let kind;
+    try {
+        const clone = structuredClone(value);
+        kind = clone === null || typeof clone !== 'object' ? 'opaque' : kindOfClone(clone);
+    }
+    catch {
+        kind = 'opaque';
+    }
+    PROBED.set(proto, kind);
+    return kind;
+}
+/** The kind of a CLONE — a value of this realm, so its prototype or its brand decides it. */
+function kindOfClone(clone) {
+    if (Array.isArray(clone))
+        return 'array';
+    const proto = Object.getPrototypeOf(clone);
+    if (proto === Object.prototype || proto === null)
+        return 'plain';
+    return builtinKind(clone) ?? 'opaque';
+}

package/dist/esm/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/esm/lib/ids/runtimeStageId.js

@@ -0,0 +1,193 @@
+/**
+ * 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 const PATH_DELIMITER = '/';
+/** Separates the (prefixed) stage id from the execution index. */
+export const EXECUTION_DELIMITER = '#';
+/**
+ * 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 function buildRuntimeStageId(stageId, executionIndex, subflowPath) {
+    const prefix = subflowPath ? `${subflowPath}${PATH_DELIMITER}` : '';
+    return `${prefix}${stageId}${EXECUTION_DELIMITER}${executionIndex}`;
+}
+/**
+ * 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 function parseRuntimeStageId(runtimeStageId) {
+    const hashIdx = runtimeStageId.lastIndexOf(EXECUTION_DELIMITER);
+    if (hashIdx === -1) {
+        return { stageId: runtimeStageId, executionIndex: 0, subflowPath: undefined };
+    }
+    const beforeHash = runtimeStageId.slice(0, hashIdx);
+    const executionIndex = parseInt(runtimeStageId.slice(hashIdx + 1), 10);
+    const lastSlash = beforeHash.lastIndexOf(PATH_DELIMITER);
+    if (lastSlash === -1) {
+        return { stageId: beforeHash, executionIndex, subflowPath: undefined };
+    }
+    return {
+        stageId: beforeHash.slice(lastSlash + 1),
+        executionIndex,
+        subflowPath: beforeHash.slice(0, lastSlash),
+    };
+}
+/**
+ * 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 function splitStageId(prefixedStageId) {
+    const lastSlash = prefixedStageId.lastIndexOf(PATH_DELIMITER);
+    if (lastSlash === -1) {
+        return { localStageId: prefixedStageId, subflowPath: undefined };
+    }
+    return {
+        localStageId: prefixedStageId.slice(lastSlash + 1),
+        subflowPath: prefixedStageId.slice(0, lastSlash),
+    };
+}
+/**
+ * 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 function isExecutionKey(key) {
+    return key.includes(EXECUTION_DELIMITER);
+}
+/**
+ * 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 function stageIdOf(runtimeStageId) {
+    const hashIdx = runtimeStageId.lastIndexOf(EXECUTION_DELIMITER);
+    return hashIdx === -1 ? runtimeStageId : runtimeStageId.slice(0, hashIdx);
+}
+/** The execution index of a runtimeStageId, or `NaN` when it carries none. */
+export function executionIndexOf(runtimeStageId) {
+    const hashIdx = runtimeStageId.lastIndexOf(EXECUTION_DELIMITER);
+    return hashIdx === -1 ? NaN : Number.parseInt(runtimeStageId.slice(hashIdx + 1), 10);
+}
+/**
+ * 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 function subflowPathOf(runtimeStageId) {
+    return splitStageId(stageIdOf(runtimeStageId)).subflowPath;
+}
+/** The subflow path of a runtimeStageId as segments (`['sf-a', 'sf-b']`); `[]` at the top level. */
+export function subflowSegmentsOf(runtimeStageId) {
+    const path = subflowPathOf(runtimeStageId);
+    return path === undefined ? [] : path.split(PATH_DELIMITER);
+}
+/** The non-empty segments of a subflow path or prefixed id (`'a//b/'` → `['a', 'b']`). */
+export function pathSegments(path) {
+    return path.split(PATH_DELIMITER).filter((s) => s.length > 0);
+}
+/** The last segment of a path or prefixed id (`'sf-a/sf-b'` → `'sf-b'`); the whole string when it has none. */
+export function lastSegmentOf(path) {
+    return path.slice(path.lastIndexOf(PATH_DELIMITER) + 1);
+}
+/** Join path segments with the grammar's delimiter (`joinPath('sf', 'stage')` → `'sf/stage'`). */
+export function joinPath(...segments) {
+    return segments.join(PATH_DELIMITER);
+}
+/** True when the (prefixed) id `id` sits INSIDE the subflow at `path` — at any depth below it. */
+export function isWithinSubflow(id, path) {
+    return id.startsWith(`${path}${PATH_DELIMITER}`);
+}
+/** Create a new execution counter starting at 0. */
+export function createExecutionCounter() {
+    return { value: 0 };
+}

package/dist/esm/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;
+}