footprintjs 9.3.0 → 9.5.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/envelope.d.ts

@@ -0,0 +1,169 @@
+/**
+ * capture/envelope.ts — RFC-001 Block 1: capture envelopes + payload summarizer.
+ *
+ * Pattern:  Point-in-time capture. An observer event is snapshotted into a
+ *           self-contained, immutable envelope at the moment it happens, so
+ *           DELIVERY can be deferred (RFC-001 "one beat behind") without the
+ *           payload drifting under later engine mutations.
+ * Role:     The capture tier of the deferred-observer pipeline
+ *           (`src/lib/observer-queue/`). Pure module — ZERO engine imports
+ *           (only `capture/` internals); the engine wiring is RFC-001
+ *           Blocks 6–10.
+ *
+ * Capture policies (RFC-001 §5):
+ *   - `'summary'` — bounded, reference-free summarization via
+ *     {@link summarizePayload}. Built on the SAME classification path as the
+ *     retention markers in `summarize.ts` (#14 / #13c-A), extended with
+ *     bounded structural descent. Structured-clone-safe by construction.
+ *   - `'clone'`   — `structuredClone` at capture time (the capture-tier
+ *     spelling of retention `'full'` — see the mapping notes in
+ *     `policies.ts`). If the payload is not clonable (functions, symbols,
+ *     live handles), capture DEGRADES to `'summary'` and reports through the
+ *     `warn` hook — a capture must never throw into the producer.
+ *   - `'ref'`     — pass-through of the live reference. The CALLER asserts
+ *     immutability for the delivery window (safe e.g. for committed-state
+ *     reads, proven immutable-after-swap in #13/#13b). Exempt from the
+ *     clone-safety guarantee — see the dev-warn seam below.
+ *
+ * Dev-warn seam (resolves the isDevMode-would-be-an-engine-import problem):
+ *   This module must not import `scope/detectCircular` (engine territory).
+ *   Instead, `capture()` accepts {@link CaptureHooks} with an optional
+ *   `warn` callback and invokes it on every `'ref'` capture and every
+ *   `'clone'` degradation. The WIRING layer (Block 6) binds `warn` to an
+ *   `isDevMode()`-gated, deduplicated console warner; the pure module stays
+ *   engine-free and silent by default (no hooks ⇒ no warning, zero cost).
+ *
+ * Summarizer bounds (documented contract, exported as constants):
+ *   - depth   ≤ {@link PAYLOAD_SUMMARY_MAX_DEPTH}   (3) — deeper structure
+ *     collapses to a classified leaf with `depthClipped: true`.
+ *   - breadth ≤ {@link PAYLOAD_SUMMARY_MAX_ENTRIES} (16) per object/array —
+ *     the remainder is dropped and flagged `truncated: true` (the honest
+ *     `size` still reports the real count).
+ *   - total   ≤ {@link PAYLOAD_SUMMARY_MAX_NODES}   (128) summary nodes per
+ *     payload — a global budget so wide×deep payloads stay O(1)-bounded.
+ *   - string previews ≤ `SUMMARY_PREVIEW_LENGTH` (80) chars.
+ *   Cycles are detected (ancestor set) and flagged `circular: true`;
+ *   throwing getters yield a `'unreadable'` leaf; symbol-keyed properties
+ *   are ignored (same as JSON / `Object.keys`); `Map`/`Set` are leaves with
+ *   their REAL entry count (no descent — matches `summarize.ts`).
+ */
+import { type SummaryValueType } from './summarize.js';
+/** Which observer channel produced a captured event (RFC-001 §5). */
+export type CaptureChannel = 'scope' | 'flow' | 'emit';
+/**
+ * How an event payload is materialized into the envelope (RFC-001 §5).
+ * See the module header for the full per-policy contract.
+ */
+export type CapturePolicy = 'summary' | 'clone' | 'ref';
+/**
+ * A captured observer event — self-contained and immutable (shallow-frozen
+ * at creation). `seq` is the arrival stamp assigned at capture under the
+ * single JS thread: it totally orders events ACROSS all three channels, is
+ * monotonic, and is gap-detectable (a dropped event leaves a visible hole
+ * in the delivered `seq` sequence — honest loss accounting).
+ */
+export interface CaptureEnvelope {
+    /** Arrival stamp — total order across channels; gaps reveal drops. */
+    readonly seq: number;
+    /** Producing observer channel. */
+    readonly channel: CaptureChannel;
+    /** Producing hook name — `'onWrite'`, `'onStageExecuted'`, `'onEmit'`, ... */
+    readonly method: string;
+    /** The execution step that produced the event (`stageId#executionIndex`). */
+    readonly runtimeStageId: string;
+    /** The run that produced the event (Convention 4 per-run scoping). */
+    readonly runId: string;
+    /**
+     * Per {@link CapturePolicy} — NEVER a live engine reference under
+     * `'summary'` / `'clone'`; under `'ref'` the caller asserted immutability.
+     */
+    readonly payload: unknown;
+    /** Capture wall-clock (ms epoch by default; injectable via hooks.now). */
+    readonly capturedAt: number;
+}
+/** The raw event description handed to {@link capture}. */
+export interface CaptureRequest {
+    /** Arrival stamp — assigned by the merged queue's counter (Block 3). */
+    readonly seq: number;
+    readonly channel: CaptureChannel;
+    readonly method: string;
+    readonly runtimeStageId: string;
+    readonly runId: string;
+    /** The LIVE payload — `capture()` materializes it per policy. */
+    readonly payload: unknown;
+}
+/**
+ * Engine-free seams injected by the wiring layer (Block 6). The pure module
+ * never imports dev-mode or clock infrastructure.
+ */
+export interface CaptureHooks {
+    /**
+     * Diagnostic sink — invoked on every `'ref'` capture (caller-asserted
+     * immutability) and every `'clone'` → `'summary'` degradation. Block 6
+     * binds this to an `isDevMode()`-gated, deduplicated warner.
+     */
+    readonly warn?: (message: string) => void;
+    /** Clock for `capturedAt` — defaults to `Date.now`. Injectable for tests. */
+    readonly now?: () => number;
+}
+/** Max nesting depth a payload summary descends before clipping. */
+export declare const PAYLOAD_SUMMARY_MAX_DEPTH = 3;
+/** Max entries summarized per object/array level before truncating. */
+export declare const PAYLOAD_SUMMARY_MAX_ENTRIES = 16;
+/** Global per-payload budget of summary nodes (wide×deep hard bound). */
+export declare const PAYLOAD_SUMMARY_MAX_NODES = 128;
+/**
+ * Leaf classification for a summary node — the `summarize.ts` family plus
+ * `'unreadable'` for properties whose getter threw during capture.
+ */
+export type PayloadSummaryType = SummaryValueType | 'unreadable';
+/**
+ * One node of a payload summary tree. Every field is a primitive, a plain
+ * object, or a plain array — structured-clone-safe by construction.
+ */
+export interface PayloadSummaryNode {
+    /** Classification — same rules as the retention markers (one code path). */
+    readonly type: PayloadSummaryType;
+    /** Honest size proxy: string length, array length, or key/entry count. */
+    readonly size?: number;
+    /** First `SUMMARY_PREVIEW_LENGTH` chars — primitives/strings only. */
+    readonly preview?: string;
+    /** Summarized own enumerable string-keyed properties (objects). */
+    readonly fields?: Readonly<Record<string, PayloadSummaryNode>>;
+    /** Summarized leading items (arrays). */
+    readonly items?: readonly PayloadSummaryNode[];
+    /** Entries were omitted here (breadth cap or node budget). */
+    readonly truncated?: boolean;
+    /** This value is an ancestor of itself — descent stopped. */
+    readonly circular?: true;
+    /** {@link PAYLOAD_SUMMARY_MAX_DEPTH} reached — children not descended. */
+    readonly depthClipped?: true;
+}
+/**
+ * Root of a payload summary — branded so consumers (and tests) can detect
+ * that a payload was summarized rather than cloned. Sibling of the
+ * `__readSummary` / `__writeSummary` retention markers.
+ */
+export interface PayloadSummary extends PayloadSummaryNode {
+    /** Discriminant — `'summary'`-policy envelope payloads carry this. */
+    readonly __payloadSummary: true;
+}
+/**
+ * Produce a bounded, reference-free, structured-clone-safe summary of an
+ * arbitrary payload. Never throws; never holds a reference into the source
+ * value (every node is a fresh object whose fields are primitives). Bounds
+ * are documented in the module header.
+ */
+export declare function summarizePayload(payload: unknown): PayloadSummary;
+/**
+ * Capture one observer event into an immutable {@link CaptureEnvelope}.
+ *
+ * Guarantees:
+ *   - Never throws into the producer (`'clone'` degradation, summarizer
+ *     never-throws contract).
+ *   - The returned envelope is shallow-frozen — `seq`/`channel`/... cannot
+ *     be reassigned. Under `'summary'`/`'clone'` the payload holds no live
+ *     reference into the source; under `'ref'` it intentionally does.
+ *   - Default policy is `'summary'` (cheapest safe tier).
+ */
+export declare function capture(request: CaptureRequest, policy?: CapturePolicy, hooks?: CaptureHooks): CaptureEnvelope;

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/engine/handlers/ContinuationResolver.d.ts

@@ -43,6 +43,18 @@ export declare class ContinuationResolver<TOut = any, TScope = any> {
      * Key: node.id, Value: visit count (0 = first visit).
      */
     private iterationCounters;
+    /**
+     * Total fn-bearing dynamic-next hops this traverser has followed.
+     *
+     * Fresh fn-bearing nodes bypass the per-node-id iteration counter (they
+     * are new nodes, often without stable ids — there is no back-edge to
+     * count). Without a bound, a stage that keeps returning a function-bearing
+     * dynamic `next` runs FOREVER on the flat trampoline (no stack overflow
+     * brakes it either). This run-total counter puts such chains under the
+     * same `maxIterations` budget (default 1000, tuned via
+     * `RunOptions.maxIterations`) that bounds loop edges.
+     */
+    private dynamicNextHops;
     private readonly onIterationUpdate?;
     private readonly maxIterations;
     constructor(deps: HandlerDeps<TOut, TScope>, nodeResolver: NodeResolver<TOut, TScope>, onIterationUpdate?: (nodeId: string, count: number) => void, maxIterations?: number);
@@ -62,8 +74,9 @@ export declare class ContinuationResolver<TOut = any, TScope = any> {
      * `onLoop` narrative), in the same order.
      *
      * Three dynamicNext patterns:
-     * - StageNode with fn → truly dynamic node, returned as-is (no iteration
-     *   tracking — it is a fresh node, not a back-edge).
+     * - StageNode with fn → truly dynamic node, returned as-is (no per-node
+     *   iteration tracking — it is a fresh node, not a back-edge — but the
+     *   run-total dynamic-hop budget applies; see `dynamicNextHops`).
      * - String ID → reference to an existing node, resolved via NodeResolver.
      * - StageNode without fn → reference by ID, resolved via NodeResolver.
      */

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

@@ -337,6 +337,9 @@ export interface RunOptions {
      * This is the binding constraint for loop-heavy pipelines — raise it for
      * legitimately long loops (`loopTo` chains run with a flat stack, so high
      * values are safe; memory for state/narrative still grows per iteration).
+     * Also bounds the run-total chain of function-bearing dynamic `next`
+     * continuations (fresh nodes returned from stages) — a runaway dynamic
+     * chain errors instead of running forever.
      * Propagates to subflows. Must be >= 1.
      */
     maxIterations?: number;

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) ────────────────────────────────────
      *

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