foottrace 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,18 @@
+/** Coordinates of an existing log within a recording/session, not a second event timeline. */
+export interface LogAddress {
+    /** Engine leg that first owned this log; unchanged by a same-executor root resume. */
+    readonly logRunId: string;
+    /** Actual mount runtime IDs, outermost first. Root log: []. Never static subflow IDs. */
+    readonly drillPath: readonly string[];
+}
+/**
+ * The committed prefix present when an event was emitted. Does NOT describe
+ * the emitter's staged writes, first-touch read view, or eventual own commit.
+ * Several events can share a position; this is not a total event order.
+ */
+export interface EmitSourcePosition extends LogAddress {
+    /** Engine leg that created the emitting frame (not the scope's memory namespace). */
+    readonly runId: string;
+    /** Inclusive index in the addressed log; -1 means only its fold base existed. */
+    readonly committedThroughIdx: number;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * honesty.ts — the ONE vocabulary for what a reader cannot see.
+ *
+ * WHY THIS FILE EXISTS. A recording cannot always answer what it is asked, and the library says
+ * so in several places, each in its own words: a slice carries `HonestyNote`s and, when it has no
+ * answer, a `missing` reason; a fed edge and an element birth carry a `basis`; a fold carries a
+ * `basis` and its `redacted` paths; a stored log reports `LogGap`s; a causal node carries
+ * `incompleteSources` and `truncated`. A reader that wants to EXPLAIN any of them to a person (a
+ * why-panel, an agent tool) kept its own table of code → sentence, and tables kept apart drift.
+ * This file is that table, once.
+ *
+ * WHAT IT HOLDS.
+ *   - `HONESTY_CODES` — a frozen, closed registry: code → the ONE sentence that says what the code
+ *     means. The shape of rustc's `--explain` and LSP's `Diagnostic.code`: the code is the stable
+ *     key a consumer BRANCHES on; the sentence is for whoever reads the screen. It is not the
+ *     per-instance `detail` a note carries (that names the key, the budget, the rows).
+ *   - `HonestyCode` / `RegisteredCode` — what makes the registry the owner and not a suggestion:
+ *     each public union of these codes (`HonestyNoteCode`, `MissingSliceReason`,
+ *     `MissingProvenanceReason`, `FedBasis`, `AttributionBasis`, `FoldBasis`, and since 9.33.0 `ValueBasis` /
+ *     `WriterBasis` — the basis twins of `commitValueAt` / `findLastWriter`) declares its members
+ *     through `RegisteredCode`, so a member the registry does not hold fails to COMPILE. And
+ *     `test/architecture/honesty-vocabulary.test.ts` asks the type checker for every exported type
+ *     alias of `foottrace` that is a union of string literals: each one is inside the
+ *     registry or is named, with its reason, as not an honesty vocabulary.
+ *
+ * NO OBJECT GAINS A FIELD from being registered. Three signals carry no code of their own — a
+ * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`) and
+ * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) — and a `truncated: { byDepth, byNodes }`
+ * field means `'truncated'`; they are registered so a reader explains them from the same place.
+ *
+ * NOT HERE: the two strings a redaction leaves where a value was. The engine writes those on every
+ * redacted run; the log's lives in its own leaf, `memory/placeholders.ts` (the scope channel's with
+ * the verdict, in FootPrint's `memory/redaction.ts`), so that an app which only runs charts does not carry these
+ * sentences in its bundle (`HONESTY_CODES` is a pure expression, so a bundler drops it wherever
+ * nothing reads it).
+ *
+ * WHY L0. This file imports NOTHING, and `slice/` and `time-travel/` (L3) type their codes through
+ * it, so it sits below them — the layer table is `scripts/layers.json`.
+ *
+ * @example
+ * ```typescript
+ * import { HONESTY_CODES } from 'foottrace';
+ *
+ * for (const { code } of forwardSlice.notes) console.log(code, '→', HONESTY_CODES[code]);
+ * // reads-not-recorded → This log carries no recorded read at all (the readTracking: 'off' signature), …
+ * HONESTY_CODES[foldedState.basis]; // 'log-only' → No initialState travelled with this log (…), …
+ * ```
+ */
+/**
+ * Every honesty code the trace readers (`foottrace`) speak, with the one sentence that says
+ * what it means.
+ *
+ * Frozen and closed: the keys are exactly the codes below, and {@link HonestyCode} is derived from
+ * them. A new code is one new line here: a union declared through {@link RegisteredCode} cannot hold
+ * a code that is not on it, and `test/architecture/honesty-vocabulary.test.ts` fails on an exported
+ * type alias of `foottrace` that is a union of string literals neither inside the registry
+ * nor named there as not an honesty vocabulary. The values are typed `string`, not literal types,
+ * on purpose: the sentences are for a screen and may be reworded; a consumer branches on the KEY.
+ */
+export declare const HONESTY_CODES: Readonly<{
+    'conservative-fed-edges': string;
+    'nested-rows': string;
+    'pre-run-origin': string;
+    'reads-not-recorded': string;
+    'unknown-key': string;
+    truncated: string;
+    'empty-log': string;
+    'never-written': string;
+    'not-an-array': string;
+    'per-write': string;
+    stage: string;
+    'append-verb': string;
+    'prefix-inference': string;
+    'whole-value': string;
+    'initial+log': string;
+    'log-only': string;
+    'log-gap': string;
+    'incomplete-sources': string;
+    redacted: string;
+    deleted: string;
+    'from-initial-state': string;
+}>;
+/** Any code in {@link HONESTY_CODES} — the key a reader looks an explanation up by. */
+export type HonestyCode = keyof typeof HONESTY_CODES;
+/**
+ * A union of honesty codes a type DECLARES: `T` must be a subset of {@link HonestyCode}, or the
+ * declaration fails to compile (TS2344).
+ *
+ * `RegisteredCode<T>` is `T` — an identity at the type level — so the union keeps exactly the
+ * members it was written with and does NOT widen to every code:
+ * `type FoldBasis = RegisteredCode<'initial+log' | 'log-only'>`.
+ */
+export type RegisteredCode<T extends HonestyCode> = T;

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

@@ -0,0 +1,125 @@
+/**
+ * keyPaths.ts — which rows of a commit log touch a state key. ONE answer (F3, 9.33.0).
+ *
+ * WHY THIS FILE EXISTS. A key query (`commitValueAt`, `findLastWriter`, `causalChain`, the slice
+ * layer) asks "which rows wrote `key`?". Each reader used to answer with its own `row.path === key`,
+ * so a row written INSIDE the key — `cfg␟b`, which every subflow seed of an object, every
+ * outputMapper merge-back and every fork child's namespace produces — was invisible to all of
+ * them, while the fold (`stateAt`, the live commit) applied it. The fold said `{a:1,b:2}`; the key
+ * queries said "never written". Every reader now asks here.
+ *
+ * THE PATH HALF (this file, L0 — it imports only the path codec and types):
+ *   - {@link relation} — how a row's path sits against a key's path. A segment prefix on the
+ *     DELIM-joined path, the way RFC 6901 prefixes a JSON Pointer: `cfg` is a prefix of `cfg␟a`,
+ *     never of `cfgX`. A row is `'exact'` (on the key), `'inside'` (below it — it wrote part of the
+ *     key's value) or `'around'` (above it — it wrote a container that holds the key).
+ *   - {@link buildWriterIndex} / {@link writerCandidates} — one pass over a log, then the rows that
+ *     can have written a key, found through its top-level key instead of a scan.
+ *
+ * THE RULES (defined here; the fold is L1 and the log readers L3, so `commitLogUtils.ts` applies
+ * them — `writersOf`, `findLastWriter`, `commitValueAt`):
+ *   - THE WRITER RULE — commit `c` WRITES key `K` iff `c` has a row `'exact'` or `'inside'` `K`,
+ *     or a row `'around'` `K` across which the value at `K` differs (compared over the whole commit,
+ *     not row by row: a value that changes and changes back inside one commit was not written).
+ *     A top-level key has no `'around'` rows, so for it the rule is the path check alone.
+ *     Why not every `'around'` row: `$update('cfg', { list: [3] })` is a `merge` row on `cfg`, but
+ *     it never reaches `cfg␟a` — counting it named the wrong writer of `cfg␟a`.
+ *   - THE VALUE RULE — the value of `K` at commit `i` is the fold of EVERY row under `K`'s top-level
+ *     key up to `i`, anchored at that key's last `set`/`delete`, read at `K`: the fold `stateAt`
+ *     does, restricted to one top-level key. Top-level keys never interact under the step, so the
+ *     restriction is exact. Folding only the rows that touch `K` is NOT: an array union
+ *     (`deepSmartMerge`) dedups the whole array, so a sibling element written beside `a␟1` changes
+ *     where a later merge on `a` leaves `a[1]`.
+ *
+ * @example
+ * ```typescript
+ * relation('cfg\u001Fb', 'cfg'); // 'inside' — the row wrote part of cfg
+ * relation('cfg', 'cfg\u001Fa'); // 'around' — the row wrote the container cfg.a lives in
+ * relation('cfgX', 'cfg');       // undefined — a different key, not a prefix match
+ * ```
+ */
+import type { CommitBundle } from './types.js';
+/**
+ * The WORK every key query has done — rows indexed and scanned, fold steps, around-verdicts, trie and
+ * ancestor steps, binary searches, a causal walk's own loops — summed across calls. A deterministic cost
+ * measure: `test/lib/memory/boundary/key-query-scaling.test.ts` asserts a causal walk's work grows linearly
+ * in the log by COUNTING it (a wall-clock ratio failed on a busy machine). Never read by the library; one
+ * integer add per unit of work it already does. Here, at L0, so every layer that does that work can count it.
+ */
+export declare const queryWork: {
+    units: number;
+};
+/** How a row's path sits against a key's path. `undefined` from {@link relation} means disjoint. */
+export type PathRelation = 'exact' | 'inside' | 'around';
+/**
+ * How the row path `rowPath` sits against the key `key` — both DELIM-joined `TraceEntry.path`
+ * strings (a top-level key is a one-segment path). `'exact'` when they are equal, `'inside'` when
+ * the row is below the key, `'around'` when the row is above it, `undefined` when neither is a
+ * segment prefix of the other.
+ */
+export declare function relation(rowPath: string, key: string): PathRelation | undefined;
+/** The top-level key a DELIM-joined path belongs to — its first segment. */
+export declare function rootOf(path: string): string;
+/**
+ * One written path in a {@link WriterIndex} — a node of the path TRIE built over a log. A node exists for
+ * every written path and every prefix of one.
+ */
+export interface PathNode {
+    /** The DELIM-joined path this node stands for. */
+    readonly path: string;
+    /** ARRAY positions of the commits with a row exactly on this path — ascending, one per commit. */
+    readonly positions: number[];
+    /** The subset of {@link positions} whose row here is a `set` or a `delete` (it decides the value alone). */
+    readonly totals: number[];
+    /** Positions of commits whose row with a non-`delete` verb sits on this path (the rest are deletes only). */
+    readonly writes: number[];
+    /** The next segment → its node. */
+    readonly children: Map<string, PathNode>;
+    /** Memo of {@link subtreePositions}. */
+    subtree?: readonly number[];
+}
+/**
+ * The positions in a log where each written path was written: a path trie per top-level key. Built in ONE
+ * pass (`O(total path segments)`); a key's candidates then cost `O(depth + matches)` — its node, its
+ * ancestors, its subtree — never a scan of every path under its top-level key.
+ */
+export interface WriterIndex {
+    /** Every top-level key → the root of its trie. */
+    readonly roots: ReadonlyMap<string, PathNode>;
+}
+/**
+ * One pass over `commitLog`: the path trie of every written path. Build it ONCE when a reader asks about
+ * many keys (a causal walk, a forward slice) — or let `commitLogUtils · logModel` memoise it for a frozen log.
+ */
+export declare function buildWriterIndex(commitLog: readonly CommitBundle[]): WriterIndex;
+/** Every path a row was written on, in trie order. */
+export declare function pathsWritten(index: WriterIndex): string[];
+/** The node for `key`, or undefined when no row was written on it or below it. */
+export declare function nodeAt(index: WriterIndex, key: string): PathNode | undefined;
+/** The nodes of `key`'s PROPER ancestors that exist in the index, top-level key first. */
+export declare function ancestorNodes(index: WriterIndex, key: string): PathNode[];
+/** Every commit with a row on `node`'s path or below it — ascending, memoised on the node. */
+export declare function subtreePositions(node: PathNode): readonly number[];
+/** The first index in an ascending list holding a value >= `value`. */
+export declare function lowerBound(sorted: readonly number[], value: number): number;
+/** The last value in an ascending list that is < `before`, or -1. */
+export declare function lastBefore(sorted: readonly number[], before: number): number;
+/** The values of an ascending list in the OPEN range (`after`, `before`). */
+export declare function between(sorted: readonly number[], after: number, before: number): readonly number[];
+/** The commits that can have written a key, split by what the writer rule still has to ask. */
+export interface WriterCandidates {
+    /** Commits with a row `'exact'` or `'inside'` the key — writers by the path alone. Ascending. */
+    readonly atOrInside: readonly number[];
+    /** Commits with a row `'around'` the key and none at or inside it — writers only if the value at the key changed. Ascending. */
+    readonly aroundOnly: readonly number[];
+}
+/** The path half of the writer rule over an index: every commit that can have written `key`. `O(depth + matches)`. */
+export declare function writerCandidates(index: WriterIndex, key: string): WriterCandidates;
+/** The ascending, de-duplicated union of ascending position lists. */
+export declare function ascendingUnion(lists: readonly (readonly number[])[]): number[];
+/**
+ * Did this commit reach `key` ONLY through rows inside it — at least one row `'inside'` the key, and no
+ * row on it or around it? Such a write changed part of the key's value, not the whole: the one test
+ * behind every `'nested-rows'` code (a slice note, a causal edge's `basis`, `findLastWriterWithBasis`).
+ */
+export declare function writesOnlyInside(bundle: CommitBundle, key: string): boolean;

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

@@ -0,0 +1,76 @@
+/**
+ * logModel.ts — the read model of ONE commit log: the writer rule and the value rule of `keyPaths.ts`,
+ * answered at a cost proportional to the answer, not to the log (F3, 9.33.0).
+ *
+ * WHY THIS FILE EXISTS. The rules are simple to state and expensive to apply naively: a key's writers
+ * include the commits AROUND it whose change reached it, and deciding that needs the value at the key
+ * before and after such a commit — a fold of its top-level key. Folding once per KEY made a causal walk
+ * over nested keys cubic in the log (every key re-scanned the log and re-folded its root). Here:
+ *
+ *   - the log is indexed ONCE (`keyPaths · buildWriterIndex`, a path trie): a key's candidates cost
+ *     O(depth + matches) — its node, its ancestors, its subtree — and the rows under a top-level key are
+ *     reached through the index, never a scan;
+ *   - each top-level key is folded ONCE (`verbs · foldKey`, copy-on-write), keeping its value before and
+ *     after every commit a verdict can ask about: a commit with a row on a path that has written paths
+ *     below it (it can be AROUND a written key), and a commit that writes THROUGH a string-valued
+ *     container (`nativeSet` replaces the string, and the characters a key read from it vanish — the one
+ *     way a row BESIDE a key moves it). A key's verdict is then two `nativeGet`s and a `deepEqual`;
+ *   - the last writer before a point is found LAZILY: the last write on or inside the key, then only the
+ *     around-candidates after it — most questions need no verdict at all.
+ *
+ * One shape keeps a per-key fold (memoised per key): a key that was never written, under a container that
+ * was only ever written WHOLE (its node has no written children, so no generation is kept there).
+ *
+ * A model of a FROZEN log (every engine log since F3: `EventLog · record` freezes each bundle and
+ * `getSnapshot` freezes the array) is memoised on the log — the record cannot change under it. A log that
+ * is not frozen (hand-built, parsed from JSON) gets a fresh model per question.
+ */
+import { type WriterIndex } from './keyPaths.js';
+import type { CommitBundle } from './types.js';
+import { type Touch } from './verbs.js';
+/** The read model of `log` — memoised when the log is frozen, fresh otherwise. */
+export declare function logModel(log: readonly CommitBundle[]): LogModel;
+/** The memoised model of a frozen log (built on first ask), or undefined for a log that is not frozen. */
+export declare function memoisedModel(log: readonly CommitBundle[]): LogModel | undefined;
+/** Does the commit hold a non-`delete` row on `key` or inside it? (A `delete` cannot replace a string container.) */
+export declare function writesAtOrInside(bundle: CommitBundle, key: string): boolean;
+/**
+ * Can this commit leave a STRING-valued container above `key` — a row around the key whose recorded value
+ * holds a string at the row's path or anywhere between it and the key? Only then can a later write beside the
+ * key move it (`nativeSet` replaces the string). A conservative, payload-only check: no fold.
+ */
+export declare function leavesStringAbove(bundle: CommitBundle, key: string): boolean;
+export declare class LogModel {
+    readonly log: readonly CommitBundle[];
+    readonly index: WriterIndex;
+    private readonly roots;
+    private readonly histories;
+    private readonly changesByKey;
+    private readonly writersByKey;
+    constructor(log: readonly CommitBundle[]);
+    private rootRows;
+    /** Refuse an answer that reaches a row whose verb the law does not know (one in commits `after` < c ≤ `end`). */
+    private refuseThrough;
+    /** Every row under `key`'s top-level key up to `end`, with its relation to `key` — through the index. */
+    rowsUnderRoot(key: string, end: number): Touch[];
+    private history;
+    /** A key never written, under a container only ever written whole: no generation is kept for it. */
+    private needsOwnFold;
+    /** Every commit across which the value at `key` changed — one fold for this key (the fallback shape). */
+    private ownChanges;
+    /**
+     * The commits in the OPEN range (`after`, `before`) with no row on or inside `key` across which the value
+     * at `key` changed — the AROUND half of the writer rule (and the string-container case beside it).
+     */
+    private changedAround;
+    /** Every commit that WROTE `key`, ascending (memoised per key). */
+    writersOf(key: string): readonly number[];
+    /** The ARRAY position of the last commit before `before` that wrote `key`, or -1. */
+    lastWriterBefore(key: string, before: number): number;
+    /**
+     * The value of `key` after commit `idx` (inclusive). The fold of the rows under its top-level key — but
+     * when its last total row up to `idx` is a `set` ON the key and nothing around it was written since, only
+     * the rows on and inside the key from that `set` on can move it, and only they are folded.
+     */
+    valueAt(key: string, idx: number): unknown;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * merge.ts — the union merge the `merge` verb applies. A leaf (L0, imports
+ * only the own-slot writer): `deepSmartMerge`, the law every replay, fold and reader
+ * of a recorded `merge` row runs. Re-exported from `utils.ts`, so no importer
+ * moved.
+ */
+/**
+ * Deep union merge helper.
+ * - Arrays (non-empty): union without duplicates (encounter order preserved)
+ * - Arrays (empty):     replace — src `[]` clears the destination array.
+ *   Rationale: writing `scope.tags = []` means "clear tags", not "append nothing".
+ *   Without this rule, an empty-array write silently becomes a no-op which is
+ *   impossible to distinguish from a bug.
+ * - Objects: recursive merge of own enumerable string keys, including special keys;
+ *   inherited destination values and setters never participate.
+ * - Primitives: source wins
+ *
+ * Terminates on a CYCLIC `src` (9.18.1, same law as {@link deepEqual}: a
+ * state value survives `structuredClone`, which preserves cycles). A `src`
+ * object re-entered while it is still being merged higher up the stack hands
+ * back the output being built for it, so the merged value mirrors the cycle
+ * instead of unrolling it forever. Only the ancestors on the stack are
+ * guarded — a shared (acyclic) `src` reference met again at a different
+ * `dst` merges against THAT `dst`, exactly as before.
+ */
+export declare function deepSmartMerge(dst: any, src: any): any;

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

@@ -0,0 +1,118 @@
+/**
+ * pathOps.ts — Native nested-path helpers (replaces lodash.get/set/has/mergewith)
+ *
+ * The DENIED set is the shared rule for three prototype-pollution selector
+ * segments (__proto__, constructor, prototype). Each operation's traversal
+ * contract is explicit below; merely using this module is not a sandbox.
+ *
+ * Selector operations read only own fields. Writers preflight the whole path
+ * before creating or copying any container, then place through putOwn.
+ *   - nativeGet — DENIED check + hasOwnProperty at every step.
+ *   - nativeHas — own-property existence only, including own denied names
+ *     and own undefined values; it does not use the DENIED rule.
+ *   - mergeContextWins — own-enumerable source keys, DENIED check, own-only
+ *     destination precedence. Inherited fields are never destination data.
+ *
+ * Diagnostic writers retain their distinct creation/merge laws in utils.ts,
+ * using the same isDeniedSegment predicate and shared own-slot writer.
+ *
+ * Paths may be dot-notation strings or pre-split (string|number)[] arrays.
+ */
+/** Is `segment` one of the three denied prototype-pollution selector names? */
+export declare function isDeniedSegment(segment: string | number): boolean;
+/**
+ * Get the value at `path` in `obj`, returning `defaultValue` if absent.
+ *
+ * Security: each path segment is checked against the DENIED list and requires
+ * an own property at every step, preventing prototype-chain reads.
+ * e.g. nativeGet({}, '__proto__') and nativeGet({}, 'constructor') both return
+ * `defaultValue` instead of leaking Object.prototype / the Object constructor.
+ */
+export declare function nativeGet(obj: any, path: string | (string | number)[], defaultValue?: any): any;
+/**
+ * Set an own path in a writer-owned container, creating missing intermediates.
+ * A denied selector is a no-op BEFORE any prefix is created. Inherited values
+ * and accessors do not participate; existing own accessors keep normal behavior.
+ */
+export declare function nativeSet(obj: any, path: string | (string | number)[], value: any): any;
+/**
+ * Remove the own property at `path` in `obj` (the replay primitive for the
+ * `delete` commit verb, #13c-B). No-op when any intermediate segment is
+ * missing — deleting an absent key has nothing to remove.
+ *
+ * Security: same DENIED + hasOwnProperty discipline as nativeGet — every
+ * segment is checked, so `nativeDelete(obj, '__proto__x')` and
+ * prototype-chain walks are inert.
+ */
+export declare function nativeDelete(obj: any, path: string | (string | number)[]): void;
+/** A container a writer may own: anything `typeof 'object'` and not null. */
+export declare function isContainer(value: unknown): value is object;
+/**
+ * `parent[key]` when `parent` is a container that OWNS `key` — the slot
+ * {@link nativeGet} would read, refusing the same prototype-pollution
+ * segments — else `undefined`. One step of a path walk.
+ */
+export declare function ownChild(parent: unknown, key: string | number): unknown;
+/**
+ * A SHALLOW copy of one container that keeps every slot the whole-state
+ * `structuredClone` this replaced kept — so a path copy and a deep clone give
+ * the same value at every path:
+ *   - a plain object (or a null-prototype one): its own enumerable keys, in
+ *     order, by spread — an own `__proto__` key stays a key; the result has
+ *     `Object.prototype`, as a clone's does;
+ *   - an array: its indices, holes and length (`slice`) AND any named
+ *     property a nested write hung off it (`slice` alone would drop those);
+ *   - anything else — a `Date`, `Map`, `Set`, typed array, a class instance —
+ *     is deep-cloned, which is what the whole-state clone did to it; and the
+ *     own enumerable properties the clone cannot carry (an expando a nested
+ *     write hung on a `Date`) are carried over by reference, so a later write
+ *     through it changes exactly its own path. Rare on a write path.
+ */
+export declare function shallowCopy<T extends object>(container: T): T;
+/**
+ * Make the containers on the way to `path`'s LEAF ones the writer owns, so
+ * the write that follows (`nativeSet` / `nativeDelete` / a verb arm) edits
+ * nothing it did not create.
+ *
+ * `root` must already be owned. Walking down, every container the writer did
+ * not create (`owned` does not hold it) is replaced, in its parent, by its
+ * {@link shallowCopy}, which the writer then owns. A denied segment anywhere
+ * refuses the entire walk before copying. Otherwise the walk stops at a
+ * missing / inherited / primitive intermediate (`nativeSet` makes a fresh
+ * own container from that point on). The leaf itself is never copied — the
+ * write replaces it.
+ *
+ * Cost: one shallow copy per container on the path that this writer has not
+ * already copied — O(depth × width), independent of everything the write
+ * does not pass through. A path of one segment (a root key, the common case)
+ * copies nothing here.
+ */
+export declare function ownSpine(root: any, path: string | (string | number)[], owned: WeakSet<object>): void;
+/**
+ * The root of a new generation: a shallow copy of `base` when it is a
+ * container (owned by the writer), else the historical deep clone of a
+ * non-container base (`undefined`, a primitive) so the callers' behaviour on
+ * such a base is unchanged.
+ */
+export declare function ownedRootOf(base: any, owned?: WeakSet<object>): any;
+/** Mark a value the writer just created (a fresh clone, a merge result) as owned. */
+export declare function own(value: unknown, owned: WeakSet<object> | undefined): void;
+/**
+ * Mark EVERY container of a tree the writer just created whole (a
+ * `structuredClone` result) as owned, so a later write through any of them
+ * edits it in place instead of copying it again. Walks own enumerable keys —
+ * the slots a path can address; a `Map`'s or `Set`'s entries are not. O(the
+ * tree's containers); a container already owned is not walked twice (a cycle
+ * inside the clone ends there).
+ */
+export declare function adopt(tree: unknown, owned: WeakSet<object>): void;
+/** Returns true if `obj` has an own property at every segment of `path`. */
+export declare function nativeHas(obj: any, path: string | (string | number)[]): boolean;
+/**
+ * Deep merge where destination wins for any defined value.
+ * Fills missing keys from `src`, but never overwrites defined keys in `dst`.
+ * Arrays are not recursed — dst array always wins when present.
+ *
+ * Replaces: `mergeWith(dst, src, (objValue) => objValue !== undefined ? objValue : undefined)`
+ */
+export declare function mergeContextWins(dst: any, src: any): any;

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

@@ -0,0 +1,56 @@
+/**
+ * paths.ts — the path codec: how a path of segments is written into a
+ * `TraceEntry.path` and read back. A leaf (L0, imports nothing): the commit
+ * log's address format, one owner. Re-exported from `utils.ts`, so no importer
+ * moved.
+ */
+/**
+ * The separator that joins path SEGMENTS into a `TraceEntry.path`.
+ *
+ * WHY NOT `'.'` — the ambiguity this exists to prevent: a state key may itself
+ * CONTAIN a dot, and this library creates such keys routinely. `$setValue`
+ * takes a KEY, not a path, so `$setValue('a.b', v)` makes one top-level key
+ * literally named `a.b`. With a dot separator that key's path and the nested
+ * path `['a', 'b']` would both encode as `"a.b"`, and every reader of the
+ * commit log — `applySmartMerge`, `commitValueAt`, `redactPatch`,
+ * `findLastWriter`, the slice layer — would have to guess which one a bundle
+ * meant. Splitting the wrong way writes into (or reads from) the wrong place.
+ *
+ * ASCII Unit-Separator is the choice because it cannot appear in a JS
+ * identifier and is vanishingly unlikely in a hand-written key, so the
+ * encoding stays unambiguous. It is NOT a display character: a path rendered
+ * straight to a UI or a log looks like one broken word. Split it with
+ * {@link pathSegments} — that, not this constant, is the contract consumers
+ * should hold.
+ */
+export declare const DELIM = "\u001F";
+/** A canonical encoded path, or its literal segments (dots inside a segment stay literal). */
+export type StateKey = string | ReadonlyArray<string | number>;
+/** Normalise a consumer key with the same codec the writer uses. */
+export declare function normaliseStateKey(key: StateKey): string;
+/**
+ * Normalises an array path into a stable string key using DELIM.
+ */
+export declare function normalisePath(path: (string | number)[]): string;
+/**
+ * The inverse of {@link normalisePath}: the SEGMENTS of a `TraceEntry.path`.
+ *
+ * A path in the commit log is DELIM-joined (see {@link DELIM}), which is not a
+ * display encoding — printing one verbatim shows a single broken-looking word,
+ * as a consumer rendering a path discovered. This is the supported way to take
+ * it apart; the delimiter itself stays an implementation detail, so a path can
+ * be read, rendered or re-joined without anyone hard-coding a control
+ * character.
+ *
+ * A single-segment path (the common case — a top-level state key) returns a
+ * one-element array, so callers need no special case.
+ *
+ * ```ts
+ * import { pathSegments } from 'foottrace/paths';
+ *
+ * for (const entry of bundle.trace) {
+ *   console.log(pathSegments(entry.path).join(' › ')); // 'order › lines'
+ * }
+ * ```
+ */
+export declare function pathSegments(path: string): string[];

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

@@ -0,0 +1,39 @@
+/**
+ * placeholders.ts — the string a redaction leaves where a value was, in the RECORD.
+ *
+ * WHY THIS FILE EXISTS. Before F4a six files each spelled a placeholder as a literal, and a spelling
+ * kept in six places is a placeholder a reader can no longer match on. Every `src/` file that writes
+ * the log's placeholder imports it from here, and `test/architecture/placeholders.test.ts` pins that
+ * no other `src/` file spells it.
+ *
+ * ONE STRING HERE, ITS TWIN ON THE VERDICT'S SIDE (C4, review N2). A redaction leaves one of two
+ * strings, and both are historical, so neither may change (stored recordings hold this one). Which
+ * one a reader sees depends on WHERE it reads, and each has the owner its reader has:
+ *   - {@link LOG_PLACEHOLDER} (`'REDACTED'`, here) is a RECORD byte: the commit log and everything
+ *     served from it — written into the log by the record's scrub (`memory/scrub.ts`, L2), and
+ *     passed by the two places that serve a mirror (`runner/ExecutionRuntime.ts`, the mirror's
+ *     seed; `engine/handlers/SubflowExecutor.ts`, a subflow's served state). The readers
+ *     (`slice/`, `time-travel/`) only name it in their docs: they meet it as data in the log;
+ *   - `SCOPE_PLACEHOLDER` (`'[REDACTED]'`) is the ENGINE's: the scope channel's retained reads and
+ *     writes, recorder events, the narrative. It lives beside the verdict that writes it
+ *     (FootPrint's `memory/redaction.ts`). Until C4 both sat in this file ("two placeholders, one leaf");
+ *     the record took the engine's string with it.
+ *
+ * WHY A LEAF OF ITS OWN (and not beside `honesty.ts · HONESTY_CODES`). Different readers, different
+ * reasons to change: this string is written on the engine's WRITE path on every redacted run, the
+ * honesty registry is read by a reader that explains a recording — and the registry's sentences have
+ * no business in the bundle of an app that only runs charts. This file imports NOTHING, so it is L0
+ * (the layer table is `scripts/layers.json`).
+ */
+/**
+ * What the COMMIT LOG and the redacted MIRROR carry where a value was scrubbed.
+ *
+ * `memory/scrub.ts · scrubPatch` writes it into the patch the log records (both encodings), and the
+ * mirror's seed is scrubbed with the same string (`runner/ExecutionRuntime.ts`), so a fold of the log
+ * reproduces it (`stateAt` → `FoldedState.redactedPaths`) and a slice or an element birth, which
+ * re-serve the log's bytes, show it too. A subflow's SERVED state is the subflow's own nested mirror
+ * (9.20.0): `subflowResults[*].treeContext.globalContext` under `getSnapshot({ redact: true })`, and
+ * `onSubflowExit.outputState` whenever a policy keeps that mirror — so those carry this string as
+ * well, not the scope channel's `SCOPE_PLACEHOLDER` (`memory/redaction.ts`).
+ */
+export declare const LOG_PLACEHOLDER = "REDACTED";

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

@@ -0,0 +1,45 @@
+/**
+ * recordCommit — one stage's commit onto the record (C1, L3). The one owner of a bundle's bytes and
+ * of where a commit lands: live state, the redacted mirror, the log.
+ *
+ * THE LAW:
+ *   1. No payload (the stage staged no write) → an EMPTY bundle goes to the log, and nothing else
+ *      moves: live state and the mirror keep their generation. Every executed stage is a cursor stop.
+ *   2. A payload → its names are read first, so a stamp that cannot be read fails the commit before
+ *      anything moves; then its raw rows build live state's next generation, `scrubPatch`
+ *      (`scrub.ts`, the record's own) puts the placeholder at each redacted path that holds a value
+ *      (in a spine copy, never in the raw patch), and the mirror and the log take the scrubbed rows —
+ *      never the raw ones. The redacted paths are data by now: the engine decided them per write
+ *      (`RecordFrame · write`); nothing here imports the engine's verdict (C4).
+ *   3. The bundle's KEY ORDER is the record's bytes: `overwrite`, `updates`, `redactedPaths`, `trace`,
+ *      `stage`, `stageId`, `runtimeStageId`, then `untrackedSources`, `tags` and `phase`, each only
+ *      when it has something to say (absent, never empty). `EventLog · record` appends `idx`. The
+ *      names are names: no redaction reads them, and no encoding (`commitValues`) changes them.
+ *
+ * The frame (`StageContext`) decides WHAT is committed — the payload, the names, whether the bundle
+ * is a continuation — and keeps what is not the record: retention, diagnostics, the dev-mode
+ * warnings and the commit observer.
+ */
+import type { EventLog } from './EventLog.js';
+import type { SharedMemory } from './SharedMemory.js';
+import type { TransactionBuffer } from './TransactionBuffer.js';
+import type { CommitPhase, UntrackedSource } from './types.js';
+/** One stage's net change, as `TransactionBuffer · commit` hands it over. */
+export type CommitPayload = ReturnType<TransactionBuffer['commit']>;
+/** What names a commit on the record, beside its payload (law 3). */
+export interface CommitStamp {
+    stage: string;
+    stageId: string;
+    runtimeStageId: string;
+    untrackedSources?: ReadonlySet<UntrackedSource>;
+    tags?: readonly string[];
+    phase?: CommitPhase;
+}
+/** Where a commit lands: live state always; the mirror and the log when the run keeps them. */
+export interface CommitTargets {
+    state: SharedMemory;
+    mirror?: SharedMemory;
+    log?: EventLog;
+}
+/** Record one commit (the module law). `payload` absent = the empty commit. */
+export declare function recordCommit(payload: CommitPayload | undefined, stamp: CommitStamp, into: CommitTargets): void;