footprintjs 9.2.0 → 9.4.0

package/dist/types/advanced.d.ts

@@ -19,7 +19,7 @@
  *
  * Import via: import { ... } from 'footprint/advanced'
  */
-export type { CommitBundle, FlowControlType, FlowMessage, MemoryPatch, ReadSummaryMarker, ReadTrackingMode, StageSnapshot, TraceEntry, } from './lib/memory/index.js';
+export type { CommitBundle, FlowControlType, FlowMessage, MemoryPatch, ReadSummaryMarker, ReadTrackingMode, RetentionPolicy, StageSnapshot, TraceEntry, WriteSummaryMarker, WriteTrackingMode, } from './lib/memory/index.js';
 export { SharedMemory } from './lib/memory/index.js';
 export { StageContext } from './lib/memory/index.js';
 export { EventLog } from './lib/memory/index.js';

package/dist/types/index.d.ts

@@ -123,6 +123,19 @@ export type { ScopeFactory } from './lib/engine/index.js';
  * or call `executor.setReadTracking(mode)` before `run()`.
  */
 export type { ReadSummaryMarker, ReadTrackingMode } from './lib/memory/index.js';
+/**
+ * @category Configuration
+ *
+ * Write-tracking policy for `StageSnapshot.stageWrites` (#13c-A) — the
+ * sibling of `ReadTrackingMode`; both alias the shared `RetentionPolicy`
+ * family from `lib/capture`. `'full'` (default — per-write value clone,
+ * historical behavior) / `'summary'` (cheap `WriteSummaryMarker` per write)
+ * / `'off'` (no tracking; `stageWrites` absent and the `onCommit` mutations
+ * payload is empty — writes themselves still commit, and the commit log is
+ * unaffected). Pass as `new FlowChartExecutor(chart, { writeTracking })` or
+ * call `executor.setWriteTracking(mode)` before `run()`.
+ */
+export type { RetentionPolicy, WriteSummaryMarker, WriteTrackingMode } from './lib/memory/index.js';
 /** @category Contract & Validation */
 export type { SchemaKind, ValidationIssue, ValidationResult } from './lib/schema/index.js';
 /** @category Contract & Validation */

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

@@ -0,0 +1,16 @@
+/**
+ * capture/ — Shared value-capture / retention primitives (zero deps, leaf
+ * module — `memory/` imports it, never the reverse).
+ *
+ * One home for "what do we keep about a tracked operation's value?":
+ *   - `RetentionPolicy` — the `'full' | 'summary' | 'off'` family behind the
+ *     #14 `readTracking` and #13c-A `writeTracking` dials.
+ *   - `summarizeReadValue` / `summarizeWriteValue` — the parameterized
+ *     summary-marker builders sharing one classification path.
+ *
+ * RFC-001 (deferred observer delivery) builds its capture tier on this
+ * module — see the mapping notes in `policies.ts`.
+ */
+export type { RetentionPolicy } from './policies.js';
+export type { ReadSummaryMarker, SummaryValueType, WriteSummaryMarker } from './summarize.js';
+export { READ_PREVIEW_LENGTH, SUMMARY_PREVIEW_LENGTH, summarizeReadValue, summarizeWriteValue } from './summarize.js';

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

@@ -0,0 +1,42 @@
+/**
+ * policies.ts — The retention policy family shared by every snapshot-tracking
+ * dial (#14 `readTracking`, #13c-A `writeTracking`).
+ *
+ * RETENTION answers "what does the engine KEEP in its own snapshot state
+ * (`StageSnapshot.stageReads` / `stageWrites`, and therefore the commit
+ * observer's mutations payload) after the moment of the operation?" It is
+ * distinct from DELIVERY — what an observer receives at event time
+ * (`ScopeRecorder.onRead`/`onWrite` always deliver the live value, in every
+ * retention mode).
+ *
+ * ── RFC-001 (deferred observer delivery) mapping ──────────────────────────
+ * RFC-001's capture tier uses the vocabulary `'clone' | 'summary' | 'ref'`.
+ * When its Block 1 lands it builds on THIS module:
+ *
+ *   - RFC capture `'clone'`   ≈ retention `'full'` (alias at the module
+ *     boundary — same semantics: structuredClone at capture time).
+ *   - RFC capture `'summary'` ≈ retention `'summary'` (same marker shapes —
+ *     see `summarize.ts`).
+ *   - RFC capture `'ref'` is DELIVERY-tier only and is NOT implemented here
+ *     — reserved. Retention must never hold live references into engine
+ *     state: retained entries outlive the stage (the execution tree keeps
+ *     them for the whole run), while a `'ref'` is only safe within the
+ *     immutability window of the captured value. Holding one in retention
+ *     would either pin state generations (the #18 leak) or expose
+ *     later-mutated values as if they were point-in-time captures.
+ */
+/**
+ * How a tracked operation's value is retained in the per-stage snapshot view.
+ *
+ * - `'full'` — `structuredClone` the value at the moment of the operation
+ *   (the historical default for both dials; point-in-time, detached copy).
+ * - `'summary'` — retain a cheap marker (type + size proxy + short preview)
+ *   instead of the value. O(1)-ish per operation; no value clone.
+ * - `'off'` — retain nothing. The operation itself is unaffected (reads
+ *   still return values, writes still commit); only the snapshot bookkeeping
+ *   is skipped.
+ *
+ * `ReadTrackingMode` (#14) and `WriteTrackingMode` (#13c-A) are public
+ * aliases of this type — see `memory/types.ts`.
+ */
+export type RetentionPolicy = 'full' | 'summary' | 'off';

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

@@ -0,0 +1,65 @@
+/**
+ * summarize.ts — Cheap value summarization for `'summary'` retention.
+ *
+ * Extracted from `StageContext` (#14's `summarizeReadValue`) into a shared,
+ * brand-parameterized helper so both snapshot-tracking dials (#14
+ * `readTracking`, #13c-A `writeTracking`) — and later RFC-001's deferred
+ * observer capture tier — produce identical summaries from ONE code path.
+ *
+ * Deliberately avoids every O(value) operation: no clone, no serialization.
+ * See {@link ReadSummaryMarker} for the honest-cost contract.
+ */
+/** Max characters captured in a summary marker's `preview`. */
+export declare const SUMMARY_PREVIEW_LENGTH = 80;
+/**
+ * Compat alias for {@link SUMMARY_PREVIEW_LENGTH} — the name shipped with
+ * #14, kept so existing import paths (`memory/types`, the memory barrel)
+ * stay valid. Same constant; reads and writes share one preview cap.
+ */
+export declare const READ_PREVIEW_LENGTH = 80;
+/** `typeof` result, refined to 'array' / 'null' for objects. */
+export type SummaryValueType = 'string' | 'number' | 'boolean' | 'bigint' | 'symbol' | 'function' | 'object' | 'array' | 'null';
+/** Brand-free summary fields shared by both marker shapes. */
+interface ValueSummary {
+    /** `typeof` result, refined to 'array' / 'null' for objects. */
+    type: SummaryValueType;
+    /** Size proxy: string length, array length, or object key count. */
+    size?: number;
+    /** First {@link SUMMARY_PREVIEW_LENGTH} chars — primitives and strings only. */
+    preview?: string;
+}
+/**
+ * Marker recorded in `StageSnapshot.stageReads` under `readTracking: 'summary'`.
+ *
+ * Honest cost note: `size` is a cheap proxy (string length / array length /
+ * object key count), NOT a serialized byte count — computing real byte size
+ * would require an O(value) serialization, which is exactly the cost the
+ * summary mode removes. `preview` is only produced for primitives and strings
+ * (first {@link SUMMARY_PREVIEW_LENGTH} characters); objects and arrays carry
+ * no preview for the same reason.
+ */
+export interface ReadSummaryMarker extends ValueSummary {
+    /** Discriminant — lets snapshot consumers detect marker entries. */
+    __readSummary: true;
+}
+/**
+ * Marker recorded in `StageSnapshot.stageWrites` (and the commit observer's
+ * mutations payload) under `writeTracking: 'summary'` (#13c-A). Same fields
+ * and cost contract as {@link ReadSummaryMarker}; distinct brand so consumers
+ * can tell which dial produced an entry.
+ */
+export interface WriteSummaryMarker extends ValueSummary {
+    /** Discriminant — lets snapshot consumers detect marker entries. */
+    __writeSummary: true;
+}
+/**
+ * Summarize a tracked READ for `readTracking: 'summary'` (#14). Byte-identical
+ * output to the pre-extraction `StageContext`-local implementation.
+ */
+export declare function summarizeReadValue(value: unknown): ReadSummaryMarker;
+/**
+ * Summarize a tracked WRITE for `writeTracking: 'summary'` (#13c-A). Sibling
+ * of {@link summarizeReadValue} — same classification, distinct brand.
+ */
+export declare function summarizeWriteValue(value: unknown): WriteSummaryMarker;
+export {};

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

@@ -11,7 +11,7 @@ import { DiagnosticCollector } from './DiagnosticCollector.js';
 import { EventLog } from './EventLog.js';
 import { SharedMemory } from './SharedMemory.js';
 import { TransactionBuffer } from './TransactionBuffer.js';
-import type { FlowControlType, ReadTrackingMode, StageSnapshot } from './types.js';
+import type { FlowControlType, ReadTrackingMode, StageSnapshot, WriteTrackingMode } from './types.js';
 export declare class StageContext {
     private sharedMemory;
     /**
@@ -68,6 +68,19 @@ export declare class StageContext {
      * every mode.
      */
     private readTracking;
+    /**
+     * How tracked writes are recorded into `_stageWrites` (#13c-A) — the
+     * sibling of {@link readTracking}, with the same propagation pattern
+     * (inherited via {@link createNext}/{@link createChild}, pushed into
+     * subflow root contexts by `SubflowExecutor`). Governs the per-write
+     * `structuredClone` in {@link setObject}/{@link updateObject}. Affects the
+     * snapshot's `stageWrites` payload AND the commit observer's mutations
+     * payload (which is a spread of `_stageWrites`) — but NOT the write
+     * itself: the transaction buffer, the commit log, and shared state are
+     * identical in every mode, and `ScopeRecorder.onWrite` always fires with
+     * the live value.
+     */
+    private writeTracking;
     /** Observer called after commit() — used by ScopeFacade to fire ScopeRecorder.onCommit. */
     private _commitObserver?;
     constructor(runId: string, name: string, stageId: string, sharedMemory: SharedMemory, branchId?: string, eventLog?: EventLog, isDecider?: boolean);
@@ -94,6 +107,30 @@ export declare class StageContext {
     useReadTracking(mode: ReadTrackingMode): void;
     /** Returns the active read-tracking policy (used for subflow propagation). */
     getReadTracking(): ReadTrackingMode;
+    /**
+     * Set the write-tracking policy for this context (#13c-A). Same plumbing
+     * as {@link useReadTracking}: called at the root by
+     * `ExecutionRuntime.useWriteTracking()` (plumbed from `FlowChartExecutor`);
+     * descendants inherit via `createNext`/`createChild`, and `SubflowExecutor`
+     * pushes the parent context's mode into each subflow root.
+     */
+    useWriteTracking(mode: WriteTrackingMode): void;
+    /** Returns the active write-tracking policy (used for subflow propagation). */
+    getWriteTracking(): WriteTrackingMode;
+    /**
+     * Record a tracked user-level write into `_stageWrites`, policy-gated
+     * (#13c-A) — the single bookkeeping path for {@link setObject} and
+     * {@link updateObject}.
+     *
+     * Redaction takes precedence over the dial in EVERY mode: a redacted
+     * write stores the `'[REDACTED]'` placeholder under `'full'` AND
+     * `'summary'` (a summary marker would leak the value's preview/size),
+     * and stores nothing under `'off'` (entry skipped entirely — nothing to
+     * leak). The staged write itself is unaffected — redaction of the
+     * committed payload is handled by the transaction buffer's
+     * `redactedPaths`.
+     */
+    private trackWrite;
     /**
      * ── The first-touch state view (#13) ────────────────────────────────────
      *
@@ -194,6 +231,35 @@ export declare class StageContext {
         value: unknown;
         operation: 'set' | 'update' | 'delete';
     }>) => void): void;
+    /**
+     * Flush staged writes to shared memory and RELEASE the per-stage staging
+     * state (#13b).
+     *
+     * Commit is the stage's lifecycle end: `buffer` (2 full-state clones) and
+     * `stateView` (a reference that pins one full committed-state GENERATION —
+     * `applySmartMerge` clones + swaps the whole state per commit, so every
+     * stage's view is a distinct object) are only needed DURING execution, as
+     * the read snapshot + net-change diff base. The execution tree retains
+     * every StageContext for the lifetime of the run, so WITHOUT the release
+     * a long loop retains one state generation + two clones per executed
+     * stage — measured O(N²): 563.8MB at N=200 on an agent-style chart; a
+     * 500-iteration agent OOMed a default Node heap (backlog #18).
+     *
+     * RE-USE AFTER COMMIT stays correct because both fields re-create lazily:
+     * - a later READ re-anchors via {@link firstTouchState} on the CURRENT
+     *   committed state (which includes this stage's own flushed writes);
+     * - a later WRITE constructs a fresh buffer on that re-anchored view, so a
+     *   second commit diffs against post-first-commit state. The pre-release
+     *   buffer behaved the same for VALUES (its `workingCopy` was reset on
+     *   commit, falling reads through to live state) but kept the ORIGINAL
+     *   `baseSnapshot` as diff base — unreachable in practice: every engine
+     *   re-commit path (fork double-commit, subflow outputMapper double-commit)
+     *   stages nothing in between, and the two real "write after commit" sites
+     *   (SubflowExecutor seed → replaces the context; resume → fresh context
+     *   via `leaf.createNext`) never re-use a committed context's buffer.
+     * - `_stageWrites` / `_stageReads` are NOT released — `snapshotSelf()`
+     *   reads them post-run for the execution-tree snapshot.
+     */
     commit(): void;
     /**
      * Create (or return) this context's linked successor.

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

@@ -9,6 +9,6 @@ export { EventLog } from './EventLog.js';
 export { SharedMemory } from './SharedMemory.js';
 export { StageContext } from './StageContext.js';
 export { TransactionBuffer } from './TransactionBuffer.js';
-export type { CommitBundle, FlowControlType, FlowMessage, MemoryPatch, ReadSummaryMarker, ReadTrackingMode, ScopeFactory, StageSnapshot, TraceEntry, } from './types.js';
-export { READ_PREVIEW_LENGTH } from './types.js';
+export type { CommitBundle, FlowControlType, FlowMessage, MemoryPatch, ReadSummaryMarker, ReadTrackingMode, RetentionPolicy, ScopeFactory, StageSnapshot, TraceEntry, WriteSummaryMarker, WriteTrackingMode, } from './types.js';
+export { READ_PREVIEW_LENGTH, SUMMARY_PREVIEW_LENGTH } from './types.js';
 export { applySmartMerge, deepSmartMerge, DELIM, getNestedValue, getRunAndGlobalPaths, normalisePath, redactPatch, setNestedValue, updateNestedValue, updateValue, } from './utils.js';

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

@@ -1,8 +1,13 @@
 /**
  * types.ts — Core type definitions for the memory library
  *
- * Zero dependencies on old code or other libraries in this package.
+ * Zero dependencies on old code or other libraries in this package, with one
+ * deliberate exception: `capture/` — the standalone leaf module holding the
+ * shared retention-policy family and summary-marker builders (extracted from
+ * here in #13c-A so the read and write dials, and later RFC-001, share one
+ * implementation).
  */
+import type { RetentionPolicy } from '../capture/policies.js';
 /** A flat key-value bag representing a state patch (overwrite or merge). */
 export interface MemoryPatch {
     [key: string]: any;
@@ -45,6 +50,9 @@ export interface FlowMessage {
     iteration?: number;
     timestamp?: number;
 }
+export type { RetentionPolicy } from '../capture/policies.js';
+export type { ReadSummaryMarker, WriteSummaryMarker } from '../capture/summarize.js';
+export { READ_PREVIEW_LENGTH, SUMMARY_PREVIEW_LENGTH } from '../capture/summarize.js';
 /**
  * Policy for how tracked reads are recorded into `StageSnapshot.stageReads`.
  *
@@ -62,30 +70,30 @@ export interface FlowMessage {
  *
  * Set via `new FlowChartExecutor(chart, { readTracking })` or
  * `executor.setReadTracking(mode)` (before `run()`).
+ *
+ * Alias of the shared {@link RetentionPolicy} family (#13c-A) — kept as the
+ * shipped public name for the read dial.
  */
-export type ReadTrackingMode = 'full' | 'summary' | 'off';
+export type ReadTrackingMode = RetentionPolicy;
 /**
- * Marker recorded in `StageSnapshot.stageReads` under `readTracking: 'summary'`.
+ * Policy for how tracked writes are recorded into `StageSnapshot.stageWrites`
+ * (#13c-A) — the sibling of {@link ReadTrackingMode}.
+ *
+ * - `'full'` (default) — every tracked write `structuredClone`s the value into
+ *   the stage's write view. Byte-identical to the historical behavior.
+ * - `'summary'` — writes record a cheap {@link WriteSummaryMarker} instead of
+ *   the cloned value.
+ * - `'off'` — writes are not recorded at all; `stageWrites` is absent from the
+ *   snapshot. The writes themselves still commit to shared state and still
+ *   appear in the commit log — only the per-stage snapshot bookkeeping (and
+ *   therefore the commit observer's mutations payload) is affected.
  *
- * Honest cost note: `size` is a cheap proxy (string length / array length /
- * object key count), NOT a serialized byte count — computing real byte size
- * would require an O(value) serialization, which is exactly the cost the
- * summary mode removes. `preview` is only produced for primitives and strings
- * (first {@link READ_PREVIEW_LENGTH} characters); objects and arrays carry no
- * preview for the same reason.
+ * Set via `new FlowChartExecutor(chart, { writeTracking })` or
+ * `executor.setWriteTracking(mode)` (before `run()`). See
+ * `FlowChartExecutorOptions.writeTracking` for the full observable-consequence
+ * contract (onCommit payload, redaction precedence, what is OUT of scope).
  */
-export interface ReadSummaryMarker {
-    /** Discriminant — lets snapshot consumers detect marker entries. */
-    __readSummary: true;
-    /** `typeof` result, refined to 'array' / 'null' for objects. */
-    type: 'string' | 'number' | 'boolean' | 'bigint' | 'symbol' | 'function' | 'object' | 'array' | 'null';
-    /** Size proxy: string length, array length, or object key count. */
-    size?: number;
-    /** First {@link READ_PREVIEW_LENGTH} chars — primitives and strings only. */
-    preview?: string;
-}
-/** Max characters captured in {@link ReadSummaryMarker.preview}. */
-export declare const READ_PREVIEW_LENGTH = 80;
+export type WriteTrackingMode = RetentionPolicy;
 /** Serialisable representation of a stage's state (for debugging / visualisation). */
 export type StageSnapshot = {
     id: string;
@@ -98,7 +106,10 @@ export type StageSnapshot = {
     subflowId?: string;
     isDecider?: boolean;
     isFork?: boolean;
-    /** User-level writes made by this stage (pre-namespace keys → values). */
+    /** User-level writes made by this stage (pre-namespace keys → values).
+     *  Shape depends on {@link WriteTrackingMode}: cloned values under `'full'`
+     *  (default), {@link WriteSummaryMarker}s under `'summary'`, absent under
+     *  `'off'`. Redacted writes show `'[REDACTED]'` regardless of mode. */
     stageWrites?: Record<string, unknown>;
     /** User-level reads made by this stage (pre-namespace keys → values at read
      *  time). Shape depends on {@link ReadTrackingMode}: cloned values under

package/dist/types/lib/runner/ExecutionRuntime.d.ts

@@ -12,7 +12,7 @@
 import { EventLog } from '../memory/EventLog.js';
 import { SharedMemory } from '../memory/SharedMemory.js';
 import { StageContext } from '../memory/StageContext.js';
-import type { CommitBundle, ReadTrackingMode, StageSnapshot } from '../memory/types.js';
+import type { CommitBundle, ReadTrackingMode, StageSnapshot, WriteTrackingMode } from '../memory/types.js';
 /** Snapshot of a single recorder's collected data. */
 export interface RecorderSnapshot {
     id: string;
@@ -72,6 +72,16 @@ export declare class ExecutionRuntime {
      * the freshly-created continuation root.
      */
     useReadTracking(mode: ReadTrackingMode): void;
+    /**
+     * Set the write-tracking policy (#13c-A) on the root stage context — the
+     * sibling of {@link useReadTracking}, with identical plumbing: descendant
+     * contexts inherit via `createNext`/`createChild`; subflow root contexts
+     * inherit from their parent-mount context via `SubflowExecutor`. Called by
+     * `FlowChartExecutor.createTraverser()` when the executor's policy is not
+     * the default `'full'` — including the resume path, where it is applied to
+     * the freshly-created continuation root.
+     */
+    useWriteTracking(mode: WriteTrackingMode): void;
     /** Preserve the current rootStageContext for snapshots before changing it for resume. */
     preserveSnapshotRoot(): void;
     getPipelines(): string[];

package/dist/types/lib/runner/FlowChartExecutor.d.ts

@@ -22,7 +22,7 @@ import type { CombinedNarrativeEntry } from '../engine/narrative/narrativeTypes.
 import type { ManifestEntry } from '../engine/narrative/recorders/ManifestFlowRecorder.js';
 import type { FlowRecorder } from '../engine/narrative/types.js';
 import { type ExecutorResult, type RunOptions, type ScopeFactory, type SerializedPipelineStructure, type StageNode, type StreamHandlers, type SubflowResult } from '../engine/types.js';
-import type { ReadTrackingMode } from '../memory/types.js';
+import type { ReadTrackingMode, WriteTrackingMode } from '../memory/types.js';
 import type { FlowchartCheckpoint } from '../pause/types.js';
 import type { CombinedRecorder } from '../recorder/CombinedRecorder.js';
 import type { EmitRecorder } from '../recorder/EmitRecorder.js';
@@ -77,6 +77,40 @@ export interface FlowChartExecutorOptions<TScope = any> {
      * Equivalent to calling `executor.setReadTracking(mode)` before `run()`.
      */
     readTracking?: ReadTrackingMode;
+    /**
+     * Policy for `StageSnapshot.stageWrites` (#13c-A) — the sibling of
+     * {@link readTracking}; the two dials are independent. Default `'full'` —
+     * every tracked write `structuredClone`s the value into the stage's write
+     * view (the historical behavior). `'summary'` records a cheap
+     * `WriteSummaryMarker` (type/size/preview) per write; `'off'` records
+     * nothing — `stageWrites` is absent from the snapshot.
+     *
+     * Observable consequences — what the policy DOES govern:
+     * - `StageSnapshot.stageWrites` (markers under `'summary'`, absent under
+     *   `'off'`).
+     * - The commit observer payload: `ScopeRecorder.onCommit(mutations)`
+     *   receives the retained `_stageWrites` entries, so it carries the same
+     *   markers under `'summary'` and an empty mutations bag under `'off'` —
+     *   deferred/observer consumers see exactly what retention stored.
+     *
+     * What it does NOT govern:
+     * - The writes themselves: shared state, the transaction buffer, and the
+     *   COMMIT LOG are identical in every mode (commitLog values keep their
+     *   full payloads — the lossless linear-cost fix for those is #13c-B's
+     *   delta verb, out of scope here).
+     * - Per-op `ScopeRecorder.onWrite` events — they fire with live values
+     *   regardless (delivery tier, RFC-001's concern), so narrative output is
+     *   identical in every mode.
+     * - Redaction: a policy/per-call-redacted write stores `'[REDACTED]'`
+     *   under `'full'` AND `'summary'` (redaction takes precedence over the
+     *   dial; a marker would leak size/preview), and nothing under `'off'`.
+     *
+     * Caveat: under `'off'` a stage's SNAPSHOT is indistinguishable from one
+     * that wrote nothing — but unlike `readTracking: 'off'`, the commit log
+     * still records every net change, so "did it write?" stays answerable.
+     * Equivalent to calling `executor.setWriteTracking(mode)` before `run()`.
+     */
+    writeTracking?: WriteTrackingMode;
     /**
      * Custom error classifier for throttling detection. Return `true` if the
      * error represents a rate-limit or backpressure condition (the executor will
@@ -163,6 +197,14 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * for the mode semantics ('full' default / 'summary' / 'off').
      */
     setReadTracking(mode: ReadTrackingMode): void;
+    /**
+     * Set the write-tracking policy for `StageSnapshot.stageWrites` (#13c-A).
+     * Must be called before run(). Equivalent to the `writeTracking`
+     * constructor option — see {@link FlowChartExecutorOptions.writeTracking}
+     * for the mode semantics ('full' default / 'summary' / 'off'), the
+     * onCommit-payload consequence, and the redaction-precedence rule.
+     */
+    setWriteTracking(mode: WriteTrackingMode): void;
     /**
      * Returns a compliance-friendly report of all redaction activity from the
      * most recent run. Never includes actual values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "9.2.0",
+  "version": "9.4.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -57,6 +57,8 @@
     "bench:micro": "npx tsx bench/run.ts",
     "bench:baseline": "npx tsx bench/baseline.ts",
     "bench:depth": "npx tsx bench/depth-probe.ts",
+    "bench:heap": "NODE_OPTIONS=--expose-gc npx tsx bench/retained-heap.ts",
+    "bench:compare": "npx tsx bench/compare.ts",
     "bench:typecheck": "tsc -p bench/tsconfig.json",
     "docs": "typedoc",
     "docs:serve": "typedoc && npx serve docs",