foottrace 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,52 @@
+/**
+ * scrub.ts — the commit log's scrub: the placeholder at every redacted path of a patch (C4, L2).
+ *
+ * The RECORD's half of a redaction. A redacted path is DATA by the time it reaches here — the
+ * transaction buffer's `redactedPaths`, registered by `RecordFrame · write` from the scrub it was
+ * handed — and this file only writes `LOG_PLACEHOLDER` (`placeholders.ts`) where such a path holds
+ * a value. It never decides WHAT is secret: that is the engine's verdict (`redaction.ts`, L4 —
+ * `RedactionRule` and the write decision), which also owns the OTHER placeholder, the scope channel's
+ * `SCOPE_PLACEHOLDER`. Before C4 both halves lived in `redaction.ts`, so the record imported the
+ * engine's policy module to write a string.
+ *
+ * THE LAW:
+ *   1. A path is scrubbed only where it holds a DEFINED value — scrubbing never invents a field.
+ *   2. Paths are scrubbed in the set's order, against the tree as scrubbed so far: a path under one
+ *      already scrubbed finds a string, not a container, and is left alone.
+ *   3. The input patch is never edited. `scrubPatch` copies only the spine of each scrubbed path
+ *      (and nothing at all when nothing is scrubbed); `redactPatch` hands back a fresh deep copy.
+ */
+import type { MemoryPatch } from './types.js';
+/**
+ * The commit log's scrub: `patch` with {@link LOG_PLACEHOLDER} at every path in `redactedPaths` that
+ * holds a defined value — the copy `recordCommit` records and feeds the redacted mirror.
+ *
+ * CLONE-FREE (9.33.0). The patch is the transaction buffer's commit-time payload, already the record's
+ * own copy (`TransactionBuffer · commit` clones each surviving path once; the buffer is dropped at
+ * commit), so the scrub copies only what it must not edit in place:
+ *   - no path to scrub (no policy, no per-call mark — the common case) → `patch` ITSELF, no copy at all;
+ *   - otherwise → a new root and a shallow copy of each container on a scrubbed path (`pathOps ·
+ *     ownSpine`), every other subtree shared with `patch`. `patch` is never edited.
+ * The engine called the public {@link redactPatch} (a whole `structuredClone`) twice per commit before
+ * 9.33.0. The bytes are the same: a scrubbed path holds the placeholder, every other path the value the
+ * buffer cloned (pinned by the 9.18.1 / 9.19.1 redaction byte tests).
+ *
+ * Paths are scrubbed in the set's order, against the tree as scrubbed so far: a path under one already
+ * scrubbed finds a string, not a container, and is left alone (as before).
+ *
+ * INTERNAL — the result shares structure with `patch`. A caller outside the commit path wants
+ * {@link redactPatch}.
+ *
+ * @param redactedPaths DELIM-joined paths (`TransactionBuffer`'s `redactedPaths`; a bundle's
+ *   `redactedPaths` array works too).
+ */
+export declare function scrubPatch(patch: MemoryPatch, redactedPaths: Iterable<string>): MemoryPatch;
+/**
+ * Private historical copy-and-scrub helper, with its contract unchanged since FootPrint 4.x:
+ * a fresh deep copy of `patch` (`structuredClone`) with
+ * {@link LOG_PLACEHOLDER} at every listed path that holds a defined value. Shares nothing with `patch`
+ * and never edits it. (It lived in `memory/utils.ts` until 9.33.0 and in `memory/redaction.ts` until
+ * C4; the live commit path uses the clone-free {@link scrubPatch}.) Kept here to preserve the
+ * extracted implementation and its tests; this helper has no foottrace public entry point.
+ */
+export declare function redactPatch(patch: MemoryPatch, redactedSet: Set<string>): MemoryPatch;

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

@@ -0,0 +1,209 @@
+/**
+ * types.ts — the record's types: a bundle, its rows, its patches, its encoding, and the
+ * execution tree as the record's readers read it.
+ *
+ * Imports nothing. The standalone record names nothing outside itself: the engine's frame
+ * types — the stage snapshot, flow messages and retention dials — remain in FootPrint's
+ * `frameTypes.ts`. The closed record graph is enforced by scripts/check-layering.mjs.
+ */
+/** A flat key-value bag representing a state patch (overwrite or merge). */
+export interface MemoryPatch {
+    [key: string]: any;
+}
+/** A single entry in the chronological operation trace. */
+export interface TraceEntry {
+    /** Canonical path string (segments joined by DELIM). */
+    path: string;
+    /**
+     * Per-write read provenance (#P1) — the keys this stage had TRACKED-READ at
+     * the moment this path was (last) written: the temporal-prefix attribution
+     * that lets slices link a specific write to only the reads that could have
+     * fed it (a stage reading `a,b` and writing `x,y` no longer implies x←b).
+     * ABSENT unless the `writeProvenance: 'reads-prefix'` dial is on — charts
+     * that never enable it keep byte-identical commit logs. Read prefixes only
+     * grow during a stage, so under delta mode's one-entry-per-path dedup the
+     * LAST write's prefix == the union across all of that path's writes.
+     * Honest ceiling: a write with NO tracked reads before it records `[]` —
+     * "depended on no tracked reads" is information, not absence.
+     */
+    readKeys?: string[];
+    /**
+     * - `'set'`    — hard overwrite; `overwrite[path]` holds the full final value.
+     * - `'merge'`  — deep union merge; `updates[path]` holds the accumulated delta.
+     * - `'append'` — (#13c-B, produced only under {@link CommitValuesMode}
+     *   `'delta'`) the path's final value is its base value plus a tail of new
+     *   trailing elements; `overwrite[path]` holds ONLY the tail. Replay
+     *   reconstructs by concatenation. NOT idempotent — delta-mode bundles
+     *   carry exactly one trace entry per surviving path.
+     * - `'delete'` — (#13c-B, produced only under `'delta'`; absorbs backlog
+     *   B8) the key was explicitly removed via `deleteValue()`. Replay removes
+     *   the key. `overwrite[path]` still ENUMERATES the path (value
+     *   `undefined`) so key-set consumers keep seeing the changed key.
+     *
+     * `overwrite` values are therefore VERB-QUALIFIED: consumers that read
+     * `bundle.overwrite[key]` as "the full value written" must use
+     * `commitValueAt(commitLog, idx, key)` (from `foottrace`) when the
+     * log may contain delta-mode bundles.
+     */
+    verb: 'set' | 'merge' | 'append' | 'delete';
+}
+/**
+ * RFC-003 D2 — read paths that BYPASS read tracking:
+ * - `'args'`   — the stage called `getArgs()` / `$getArgs()` with non-empty
+ *   run input (frozen, untracked by design)
+ * - `'env'`    — the stage called `getEnv()` / `$getEnv()` with a non-empty
+ *   execution environment (frozen, untracked by design)
+ * - `'silent'` — the stage performed a silent read (`getValueSilent` /
+ *   `getValueDirect`) of a key it never tracked-read in the same stage.
+ *   Silent reads SHADOWED by a tracked read of the same key in the same
+ *   stage (TypedScope array-proxy internals, `$batchArray`) are NOT
+ *   flagged — their read→write edge is already captured.
+ */
+export type UntrackedSource = 'args' | 'env' | 'silent';
+/** The atomic bundle produced by TransactionBuffer.commit(). */
+export interface CommitBundle {
+    /** Auto-assigned step index (set by EventLog.record). */
+    idx?: number;
+    /** Human-readable stage name. */
+    stage: string;
+    /** Stable stage identifier (matches spec node id). */
+    stageId: string;
+    /** Unique per-execution-step identifier. Format: [subflowPath/]stageId#executionIndex */
+    runtimeStageId: string;
+    /** Chronological write log for deterministic replay. */
+    trace: TraceEntry[];
+    /** Paths that should be redacted in UI (sensitive data). */
+    redactedPaths: string[];
+    /** Hard overwrite patches. */
+    overwrite: MemoryPatch;
+    /** Deep merge patches. */
+    updates: MemoryPatch;
+    /**
+     * RFC-003 D2 honesty markers — untracked read paths this stage consumed
+     * (see {@link UntrackedSource}). ABSENT when the stage used none, so
+     * charts that never touch those paths keep byte-identical commit logs.
+     * Causal-slice consumers (`causalChain`/`formatCausalChain`) surface this
+     * as "slice may be incomplete here". Residual limitation (by design):
+     * values smuggled through JS closures are undetectable.
+     */
+    untrackedSources?: ReadonlyArray<UntrackedSource>;
+    /**
+     * Declared tags (9.21.0) — the names the author put on this stage at build
+     * time (`FlowChartBuilder.tag` / `options.tags`), stamped here by the
+     * traverser so a stored recording carries its own milestones without a
+     * consumer's id conventions. ABSENT when the stage declares none, so an
+     * untagged chart's log is byte-identical to 9.20.0 (the law
+     * `untrackedSources` keeps). Recorded on the FIRST bundle of each execution
+     * of the stage — the stage's own bundle, the one without a `phase` — so
+     * retry attempts stamp it once, a continuation (a fork child's `'repeat'`,
+     * a mount's `'exit'` after its merge-back) carries none, and a mount whose
+     * exit is its only bundle (no `outputMapper`) carries them on that bundle. Free strings: footprintjs assigns
+     * them no meaning; `tagStops` (foottrace) keeps a stop when any of
+     * them matches.
+     */
+    tags?: readonly string[];
+    /**
+     * Which CONTINUATION of a stage's execution this bundle is (9.39.0) —
+     * stamped by the WRITER. THE LAW: the FIRST bundle per `runtimeStageId` is
+     * the stage's own and carries NO `phase`; only a bundle after it can:
+     *
+     * - `'exit'` — a subflow mount's exit commit (`SubflowExecutor`) after its
+     *   merge-back bundle (`outputMapper`). A mount without a merge-back (a lazy
+     *   mount, every `parallelForEach` branch, any mount with no mapper) has
+     *   its exit as its ONLY bundle — its own, so no `phase`; the execution
+     *   tree names it a mount.
+     * - `'repeat'` — the fan-out's settle commit of a fork child's frame
+     *   (`ChildrenExecutor`), after the child's own bundle.
+     *
+     * A reader groups a stage's bundles by `runtimeStageId` and reads this
+     * field to know what each continuation is; it never infers it from the
+     * log's shape. A log written before 9.39.0 carries no `phase` anywhere —
+     * see `inferLegacyPhases` (foottrace) for how it is still read.
+     */
+    phase?: CommitPhase;
+}
+/** The continuation a bundle records — see {@link CommitBundle.phase}. */
+export type CommitPhase = 'exit' | 'repeat';
+/**
+ * Per-write read-provenance policy (#P1) — the fourth dial of the
+ * readTracking/writeTracking/commitValues family, same 6-site propagation
+ * pattern (executor option → ExecutionRuntime.use* → root StageContext →
+ * createNext/createChild inheritance → SubflowExecutor duck-push).
+ *
+ * - `'off'` (default) — zero cost, byte-identical commit logs.
+ * - `'reads-prefix'` — every committed {@link TraceEntry} carries
+ *   `readKeys`: the keys tracked-read BEFORE that write (temporal-prefix
+ *   attribution). Cost: one Set-to-array copy per write. Consumed by
+ *   `causalChain`'s `edgeAttribution: 'per-write'` and the slice layer.
+ */
+export type WriteProvenanceMode = 'off' | 'reads-prefix';
+/**
+ * Policy for how commit-bundle VALUES are encoded into the commit log
+ * (#13c-B) — completes the `readTracking`/`writeTracking` dial family.
+ * Unlike those two (which gate lossy snapshot bookkeeping), this dial is
+ * **lossless in both modes** — it changes the commit log's *encoding*,
+ * never its *information*; any step's full state stays exactly
+ * reconstructable by replay.
+ *
+ * - `'full'` (default) — every surviving `set` path stores the full final
+ *   value, one trace entry per operation. Byte-identical to the historical
+ *   behavior.
+ * - `'delta'` — two changes, both replay-covered by `applySmartMerge`:
+ *   1. **`append` detection**: when a path's net change is "the base array
+ *      plus new trailing elements" (strict prefix), the bundle records ONLY
+ *      the tail under a `verb: 'append'` trace entry — the growing-history
+ *      commit log becomes linear in tail size instead of O(N²) retained.
+ *      A real `verb: 'delete'` entry replaces the `set: undefined` flattening
+ *      for `deleteValue()` (closes the documented MemoryPatch limitation).
+ *   2. **One trace entry per surviving path** (append is not idempotent on
+ *      replay): the verb is resolved from the path's base→final relationship
+ *      and op mix; entries are ordered by each path's LAST touch.
+ *
+ * Honest cost note: append detection is NEW wall work — an O(|base|)
+ * structural prefix compare per array-set path per commit (today's
+ * `deepEqual` fast-fails on length in O(1) for a grown array). On a hit the
+ * commit gets cheaper in both wall and heap (the O(|final|) clone shrinks to
+ * O(|tail|)); on a miss it pays compare + full clone. `'full'` pays zero —
+ * the detection branch is mode-gated.
+ *
+ * Set via `new FlowChartExecutor(chart, { commitValues })` or
+ * `executor.setCommitValues(mode)` (before `run()`). The active mode is
+ * surfaced as the snapshot discriminant `RuntimeSnapshot.commitValues`.
+ */
+export type CommitValuesMode = 'full' | 'delta';
+/**
+ * The execution tree as the record's readers read it (C6): the fields a reader touches and
+ * nothing else. `commitStops` (and so `tagStops` and every strategy built on it) reads the mount
+ * marker (`subflowId`) and the root's `id`; `keysReadFromExecutionTree` reads the keys of
+ * `stageReads`; both key on `runtimeStageId` and walk `next` and `children`.
+ *
+ * A structural type the record owns, so the readers name nothing of the engine. The engine's
+ * `StageSnapshot` (`getSnapshot().executionTree`) is one — a supertype of it, so every caller
+ * that hands a snapshot's tree over compiles unchanged — and so is a stored recording's parsed
+ * JSON with these fields. Every field is optional: a reader that finds one absent reads on.
+ *
+ * @example
+ * ```typescript
+ * import { type ExecutionTree, keysReadFromExecutionTree } from 'foottrace';
+ *
+ * const tree: ExecutionTree = {
+ *   runtimeStageId: 'seed#0',
+ *   next: { runtimeStageId: 'decide#1', stageReads: { creditTier: 'A' } },
+ * };
+ * keysReadFromExecutionTree(tree).lookup('decide#1'); // ['creditTier']
+ * ```
+ */
+export interface ExecutionTree {
+    /** The stage's id (prefixed inside a subflow). `commitStops` reads the root's to place a subflow's seed. */
+    readonly id?: string;
+    /** `[subflowPath/]stageId#executionIndex` — what a reader keys on. A node without one is not a stage. */
+    readonly runtimeStageId?: string;
+    /** Present on a subflow mount: the stop there says `kind: 'mount'`. */
+    readonly subflowId?: string;
+    /** What the stage tracked-read, by key. Only the KEYS are read: a `'summary'` marker serves as well as a value. */
+    readonly stageReads?: Readonly<Record<string, unknown>>;
+    /** The stage that ran next. */
+    readonly next?: ExecutionTree;
+    /** The stages that ran as this one's children (a fork's branches, a decider's chosen branch). */
+    readonly children?: readonly ExecutionTree[];
+}

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

@@ -0,0 +1,73 @@
+/**
+ * utils.ts — nested-object helpers for the heap, and the memory leaves' one
+ * re-export surface.
+ *
+ * The helpers here (`setNestedValue`, `updateNestedValue`, `updateValue`,
+ * `getNestedValue`) walk a nested object by path with
+ * prototype-pollution protection. Everything else this file used to hold has an
+ * owner of its own and is re-exported, so no importer moved: the path codec
+ * (`paths.ts`), structural equality (`equality.ts`) and the union merge
+ * (`merge.ts`) at L0, and the verb law (`verbs.ts`) at L1 — `applySmartMerge`,
+ * `nextGeneration`, `applySmartMergeInto`, `dryFold`, `supersededByNextSet`.
+ * The log's scrub, `redactPatch`, moved out in 9.33.0; it is the record's own, `scrub.ts` (C4).
+ * The writers take an ADDRESS, a path prefix their caller computed, and never
+ * name one (C2: the engine decides where a stage writes, `runAddress.ts · runAddress`).
+ * Zero external dependencies.
+ */
+export { deepEqual } from './equality.js';
+export { deepSmartMerge } from './merge.js';
+export { DELIM, normalisePath, pathSegments } from './paths.js';
+export { applySmartMerge, applySmartMergeInto, dryFold, nextGeneration, supersededByNextSet } from './verbs.js';
+type NestedObject = {
+    [key: string]: any;
+};
+/**
+ * The two places a value at `path` can sit: under `address` (`runPath`, absent
+ * for the root address `[]`) and at the root (`globalPath`). `address` is a
+ * path prefix the caller computed — for the engine, a frame's run namespace
+ * (`runAddress.ts · runAddress`, C2), held by its record frame (`RecordFrame · address`, C3).
+ */
+export declare function getRunAndGlobalPaths(address?: readonly string[], path?: (string | number)[]): {
+    runPath: (string | number)[] | undefined;
+    globalPath: (string | number)[];
+};
+/**
+ * Refuse the WHOLE selector before creating a container or copying a generation.
+ * The address's array contract is checked even when another selector is denied.
+ * Payload keys are data, not selectors, and are deliberately not inspected.
+ * @internal Shared by the nested writers and SharedMemory's pre-copy boundary.
+ */
+export declare function isDeniedWritePath(address: readonly string[] | undefined, path: readonly (string | number)[] | undefined, field: string | number): boolean;
+/**
+ * Sets a value at a nested path under `address`, creating intermediate objects as needed.
+ * A denied address/path/field leaves `obj` unchanged, including its prototype.
+ */
+export declare function setNestedValue<T>(obj: NestedObject, address: readonly string[], path: string[], field: string, value: T, defaultValues?: unknown): NestedObject;
+/**
+ * Updates a value in the object at a nested path under `address`.
+ * A denied address/path/field leaves `obj` unchanged, including its prototype.
+ * - Arrays: concatenate
+ * - Objects: shallow merge at each level
+ * - Primitives: replace
+ */
+export declare function updateNestedValue<T>(obj: any, address: readonly string[], path: (string | number)[], field: string | number, value: T, defaultValues?: unknown): any;
+/**
+ * In-place value update with merge semantics.
+ * - Arrays (non-empty): concatenate onto existing
+ * - Arrays (empty):     direct replace — writing `[]` clears the field
+ * - Objects (non-empty): shallow merge (spread)
+ * - Objects (empty):    direct replace — writing `{}` clears the field
+ * - Primitives: direct assignment
+ *
+ * Note on empty arrays: both `value && Array.isArray(value)` and
+ * `Array.isArray(value)` evaluate the same for arrays — `[]` is truthy in
+ * JavaScript, so the `&&` guard was never the issue. The actual bug was the
+ * concat path: `[...cur, ...[]]` silently returned `cur` unchanged when `value`
+ * was `[]`, making `updateValue(obj, 'tags', [])` a no-op instead of a clear.
+ * The fix is the explicit `value.length === 0` early-return branch.
+ */
+export declare function updateValue(object: any, key: string | number, value: any): void;
+/**
+ * Gets a value at a nested path with prototype-pollution protection.
+ */
+export declare function getNestedValue(root: any, path: (string | number)[], field?: string | number): any;