footprintjs 9.3.0 → 9.5.0

package/dist/types/lib/observer-queue/deferredDispatcher.d.ts

@@ -0,0 +1,169 @@
+/**
+ * observer-queue/deferredDispatcher.ts — RFC-001 Block 5: deferred delivery façade.
+ *
+ * Pattern:  capture → enqueue → (microtask) flush → invoke, with per-listener
+ *           error isolation. Composes the whole pure pipeline: MergedQueue
+ *           (Block 3, which captures via Block 1) + FlushDriver (Block 4) +
+ *           a listener registry with timing/inflight accounting.
+ * Role:     The object the engine wiring (Block 6) will hold. Producers call
+ *           `capture()` (cheap, never throws, never blocks); listeners
+ *           receive envelopes at the next checkpoint, "one beat behind".
+ *           Pure module — zero engine imports.
+ *
+ * Delivery semantics (normative, RFC-001 §5 + amendments A2/A4):
+ *   - Per-listener FIFO: every listener sees envelopes in seq order
+ *     (invocation order; an async listener's COMPLETION order is its own
+ *     concern) — EXCEPT under `'block'` overflow, where a refused enqueue
+ *     is delivered inline and overtakes the queued backlog. `seq` always
+ *     records true arrival order, so order-sensitive consumers re-sort;
+ *     see the `'block'` caveat below.
+ *   - Error isolation: a throwing listener (sync) or rejecting listener
+ *     (async) never affects siblings or the producer. Both failure modes
+ *     route to the injected `onError`; a throwing `onError` is itself
+ *     swallowed.
+ *   - The flush NEVER awaits a listener. Async continuations are tracked in
+ *     an inflight set; `drain({ timeoutMs })` settles them
+ *     (`Promise.allSettled` + deadline, shaped like `flushAllDetached`).
+ *   - `'block'` overflow: a refused enqueue is delivered synchronously
+ *     INLINE from `capture()` — re-introducing blocking delivery by the
+ *     consumer's explicit choice. Ordering caveat (documented + tested): an
+ *     inline event overtakes the queued backlog — `'block'` trades global
+ *     ordering for zero loss and bounded memory. `seq` still tells the
+ *     true arrival order.
+ *   - Listener registry is idempotent by id (same id replaces, different
+ *     ids coexist) — mirrors the repo-wide recorder ID contract. Stats
+ *     accumulate per id across replacement; `removeListener` keeps the
+ *     id's accumulated stats for post-run reports.
+ *   - Events captured BEFORE any listener attaches stay queued — a listener
+ *     attached before the next checkpoint still receives the backlog.
+ *
+ * Per-listener time accounting (amendment A2 — "name the hog"): cumulative
+ * `totalMs` and per-checkpoint `lastFlushMs` of SYNC time per listener id —
+ * the time that actually blocks the flush. An async listener's continuation
+ * time is intentionally not attributed (it does not block delivery).
+ */
+import { type CaptureEnvelope, type CaptureHooks, type CapturePolicy } from '../capture/envelope.js';
+import { type FlushSyncResult } from './flushDriver.js';
+import { type EnqueueInput } from './mergedQueue.js';
+import { type OverflowPolicy } from './ring.js';
+/**
+ * One deferred observer. May return a Promise — the dispatcher tracks it in
+ * the inflight set but NEVER awaits it during a flush.
+ */
+export type DeferredListener = (envelope: CaptureEnvelope) => void | Promise<void>;
+export interface DispatchErrorContext {
+    readonly listenerId: string;
+    readonly envelope: CaptureEnvelope;
+    /** `'sync'` = listener threw; `'async'` = returned promise rejected. */
+    readonly phase: 'sync' | 'async';
+}
+/** Injected error sink — the wiring layer routes these (Block 6). */
+export type DispatchErrorHandler = (error: unknown, context: DispatchErrorContext) => void;
+export interface DeferredDispatcherOptions {
+    /** Queue bound — default 10 000 (see `MergedQueue`). */
+    readonly maxQueue?: number;
+    /** Overflow policy — default `'drop-oldest'`. */
+    readonly overflow?: OverflowPolicy;
+    /** `'sample'` overflow only — admit 1 in this many saturated arrivals. */
+    readonly sampleEvery?: number;
+    /** Default capture policy — default `'summary'`. */
+    readonly capturePolicy?: CapturePolicy;
+    /** Per-flush time budget, ms (A1) — default 2; `Infinity` = full drain. */
+    readonly flushBudgetMs?: number;
+    /** Listener-failure sink. No default — without it, failures are silent. */
+    readonly onError?: DispatchErrorHandler;
+    /** Capture seams (dev-warn, capturedAt clock) — see `CaptureHooks`. */
+    readonly hooks?: CaptureHooks;
+    /** Timing clock for budget + per-listener accounting. Injectable. */
+    readonly now?: () => number;
+    /** Checkpoint primitive — default `queueMicrotask`. Injectable. */
+    readonly schedule?: (cb: () => void) => void;
+}
+/** Per-listener accounting (A2/A4). */
+export interface ListenerStats {
+    /** Envelopes delivered (invocations, including ones that threw). */
+    readonly events: number;
+    /** Cumulative sync delivery time, ms. */
+    readonly totalMs: number;
+    /** Sync delivery time since the last flush started, ms. */
+    readonly lastFlushMs: number;
+}
+/** The Block 9 observability surface (amendment A4) — pure getter. */
+export interface DispatcherStats {
+    /** Current backlog. */
+    readonly depth: number;
+    /** Events LOST (overflow) — never silent; also visible as seq gaps. */
+    readonly drops: number;
+    /** Completed checkpoint flushes. */
+    readonly flushes: number;
+    /** Flushes cut short by `flushBudgetMs` (A1). */
+    readonly budgetExhausted: number;
+    /** p95 flush duration, ms (rolling window). */
+    readonly p95FlushMs: number;
+    /** `'block'`-policy refusals delivered synchronously inline. */
+    readonly inlineDeliveries: number;
+    /** Async listener continuations not yet settled. */
+    readonly inflight: number;
+    /** Per-listener time accounting — "name the hog" (A2). */
+    readonly perListener: Readonly<Record<string, ListenerStats>>;
+}
+/** Result of {@link DeferredDispatcher.drain} — `flushAllDetached` shape. */
+export interface DrainResult {
+    /** Async continuations seen settling fulfilled. Best-effort count — a
+     *  continuation that settles between checks is drained but may not be
+     *  counted (same semantics as `flushAllDetached`). */
+    readonly done: number;
+    /** Continuations whose listener promise rejected (routed to onError). */
+    readonly failed: number;
+    /** Still in flight (or queued) when the deadline expired. `0` = drained. */
+    readonly pending: number;
+}
+export declare class DeferredDispatcher {
+    private readonly queue;
+    private readonly driver;
+    private readonly listeners;
+    private readonly listenerStats;
+    /** Tracked async continuations — resolve `true` (ok) / `false` (failed). */
+    private readonly inflight;
+    private readonly onError?;
+    private readonly now;
+    private inlineDeliveries;
+    constructor(opts?: DeferredDispatcherOptions);
+    /** Idempotent by id — same id replaces (stats continue), ids coexist. */
+    addListener(id: string, listener: DeferredListener): void;
+    /** Stop delivering to `id`. Accumulated stats are kept for reports. */
+    removeListener(id: string): void;
+    /**
+     * Producer entry point: capture the event (seq-stamped, payload per
+     * policy) and stage it for the next checkpoint. Cheap; NEVER throws;
+     * never blocks — except under `'block'` overflow, where a refused
+     * enqueue is delivered synchronously inline (explicit consumer choice).
+     */
+    capture(input: EnqueueInput, policy?: CapturePolicy): void;
+    /**
+     * Terminal flush — synchronously deliver everything queued (end of run /
+     * shutdown). Async listener continuations are NOT awaited; follow with
+     * `drain()` for that.
+     */
+    flushNow(opts?: {
+        maxRounds?: number;
+    }): FlushSyncResult;
+    /**
+     * Flush the backlog, then settle all inflight async continuations —
+     * `Promise.allSettled` under a deadline, shaped like `flushAllDetached`.
+     * Loops while continuations spawn new captures, until quiescent or the
+     * deadline expires.
+     */
+    drain(opts?: {
+        timeoutMs?: number;
+    }): Promise<DrainResult>;
+    /** A4 — the stats object Block 9 consumes. Pure getter, fresh snapshot. */
+    getStats(): DispatcherStats;
+    private deliverNext;
+    /** Invoke every listener with full error isolation + time accounting. */
+    private deliver;
+    /** Track an async continuation; route its rejection; never reject. */
+    private track;
+    /** The error sink must never become an error source. */
+    private safeOnError;
+}

package/dist/types/lib/observer-queue/flushDriver.d.ts

@@ -0,0 +1,124 @@
+/**
+ * observer-queue/flushDriver.ts — RFC-001 Block 4: armed-once microtask batcher.
+ *
+ * Pattern:  Kernel-style bottom-half. Producers only set a flag ("work
+ *           pending") and return; the actual work runs at the next
+ *           scheduling checkpoint (a microtask), drains under a time
+ *           budget, and re-arms itself if backlog remains. Same shape as
+ *           the detach module's `microtaskBatchDriver` — accumulate during
+ *           the current sync slice, drain at the boundary.
+ * Role:     The scheduler of the deferred-observer pipeline. Owns WHEN
+ *           delivery happens; knows nothing about envelopes or listeners
+ *           (the dispatcher, Block 5, injects `depth`/`processNext`).
+ *           Pure module — zero imports, zero engine knowledge.
+ *
+ * Scheduling semantics (normative, RFC-001 §5 + amendment A1):
+ *   - `arm()` is idempotent: at most ONE pending flush exists (armed flag).
+ *     N captures between checkpoints ⇒ exactly 1 flush.
+ *   - A flush drains a SNAPSHOT: at most `depth()`-at-flush-start items.
+ *     Events enqueued BY listeners during the flush exceed the snapshot and
+ *     land at the NEXT checkpoint — listener-driven cascades cannot starve
+ *     the event loop.
+ *   - `flushBudgetMs` (default 2; `Infinity` = full snapshot drain): the
+ *     flush stops once the budget is exhausted, counts `budgetExhausted`,
+ *     and re-arms. At least ONE item is processed per flush regardless of
+ *     budget — guaranteed progress under any clock.
+ *   - If backlog remains after the flush (budget cut OR listener enqueues),
+ *     the driver re-arms for the next checkpoint.
+ *
+ * Why stage boundaries make this safe: the engine `await`s every stage, so
+ * the microtask queue runs at EVERY stage boundary — flushes are at most
+ * "one beat behind" the producing stage. See
+ * `docs/guides/execution-model.md` ("Stage boundaries are scheduling
+ * points") and the FAQ in `docs/design/rfc-001-deferred-observers.md`.
+ *
+ * Testability: `now` (clock) and `schedule` (checkpoint primitive) are
+ * injectable — tests pump flushes deterministically with a fake clock and
+ * a captured-callback scheduler; production uses `performance.now` and
+ * `queueMicrotask`.
+ */
+/** Result of one flush (also delivered to `onFlushEnd`). */
+export interface FlushOutcome {
+    /** Items processed in this flush. */
+    readonly processed: number;
+    /** True when the time budget cut the flush before the snapshot drained. */
+    readonly budgetExhausted: boolean;
+    /** True when backlog remained and the driver re-armed itself. */
+    readonly rearmed: boolean;
+}
+/** Result of a synchronous {@link FlushDriver.flushSync} drain. */
+export interface FlushSyncResult {
+    /** Items processed across all rounds. */
+    readonly drained: number;
+    /** Items still queued when `maxRounds` stopped a runaway cascade. */
+    readonly remaining: number;
+}
+export interface FlushDriverOptions {
+    /** Current backlog of the queue this driver drains. */
+    readonly depth: () => number;
+    /** Process exactly ONE queued item. Precondition: `depth() > 0`. */
+    readonly processNext: () => void;
+    /**
+     * Per-flush time budget in ms. Default 2. `Infinity` drains the full
+     * snapshot every checkpoint. Must be > 0.
+     */
+    readonly flushBudgetMs?: number;
+    /** Clock — default `performance.now` (falls back to `Date.now`). */
+    readonly now?: () => number;
+    /** Checkpoint primitive — default `queueMicrotask`. */
+    readonly schedule?: (cb: () => void) => void;
+    /** Fires before the first item of every flush (incl. `flushSync`). */
+    readonly onFlushStart?: () => void;
+    /** Fires after every flush with its outcome (incl. `flushSync`). */
+    readonly onFlushEnd?: (outcome: FlushOutcome) => void;
+}
+export interface FlushDriverStats {
+    /** Completed flushes (zero-work wakeups are not counted). */
+    readonly flushes: number;
+    /** Flushes cut short by `flushBudgetMs` (A1 — backlog visibility). */
+    readonly budgetExhausted: number;
+    /** Duration of the most recent flush, ms. */
+    readonly lastFlushMs: number;
+    /** p95 over the last {@link FLUSH_SAMPLE_WINDOW} flush durations, ms. */
+    readonly p95FlushMs: number;
+    /** True while a flush is scheduled but not yet run. */
+    readonly armed: boolean;
+}
+/** Rolling sample window for the p95 flush-duration stat (A4). */
+export declare const FLUSH_SAMPLE_WINDOW = 128;
+export declare class FlushDriver {
+    private readonly depth;
+    private readonly processNext;
+    private readonly flushBudgetMs;
+    private readonly now;
+    private readonly schedule;
+    private readonly onFlushStart?;
+    private readonly onFlushEnd?;
+    private armed;
+    private flushes;
+    private budgetExhaustedCount;
+    private lastFlushMs;
+    private readonly samples;
+    private sampleWriteIdx;
+    constructor(opts: FlushDriverOptions);
+    /**
+     * Request a flush at the next checkpoint. Idempotent — while one flush
+     * is pending, further arms are free no-ops (the armed-once invariant).
+     */
+    arm(): void;
+    /**
+     * Synchronous full drain — the terminal-flush primitive (end of run /
+     * shutdown). Repeats snapshot rounds until the queue is empty so
+     * listener-enqueued cascades drain too, capped at `maxRounds` so a
+     * listener that enqueues forever cannot hang the process (`remaining`
+     * reports what the cap left behind).
+     */
+    flushSync(opts?: {
+        maxRounds?: number;
+    }): FlushSyncResult;
+    getStats(): FlushDriverStats;
+    /** The microtask body — see the module-header semantics. */
+    private flush;
+    private recordFlush;
+    private p95FlushMs;
+}

package/dist/types/lib/observer-queue/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * observer-queue/ — RFC-001 deferred observer delivery, Blocks 2–5.
+ *
+ * The pure "one beat behind" pipeline:
+ *
+ *   producer ─► capture (Block 1, `capture/envelope`) ─► MergedQueue
+ *   (Block 3, seq-stamped over a BoundedRing, Block 2) ─► FlushDriver
+ *   (Block 4, armed-once microtask checkpoints, flushBudgetMs) ─►
+ *   DeferredDispatcher (Block 5, isolated listeners + inflight + stats)
+ *
+ * INTERNAL MODULE — deliberately NOT exported from the public footprintjs
+ * barrels yet. The engine wiring + public surface land with Blocks 6–10
+ * (see docs/design/rfc-001-deferred-observers.md). Zero engine imports:
+ * this directory may import only `../capture/` and its own files.
+ */
+export type { CaptureChannel, CaptureEnvelope, CaptureHooks, CapturePolicy, CaptureRequest, PayloadSummary, PayloadSummaryNode, PayloadSummaryType, } from '../capture/envelope.js';
+export { capture, PAYLOAD_SUMMARY_MAX_DEPTH, PAYLOAD_SUMMARY_MAX_ENTRIES, PAYLOAD_SUMMARY_MAX_NODES, summarizePayload, } from '../capture/envelope.js';
+export type { DeferredDispatcherOptions, DeferredListener, DispatchErrorContext, DispatchErrorHandler, DispatcherStats, DrainResult, ListenerStats, } from './deferredDispatcher.js';
+export { DeferredDispatcher } from './deferredDispatcher.js';
+export type { FlushDriverOptions, FlushDriverStats, FlushOutcome, FlushSyncResult } from './flushDriver.js';
+export { FLUSH_SAMPLE_WINDOW, FlushDriver } from './flushDriver.js';
+export type { EnqueueInput, EnqueueOutcome, EnqueueResult, MergedQueueOptions } from './mergedQueue.js';
+export { DEFAULT_MAX_QUEUE, MergedQueue } from './mergedQueue.js';
+export type { OverflowPolicy, RingCounters, RingOptions, RingPushResult } from './ring.js';
+export { BoundedRing } from './ring.js';

package/dist/types/lib/observer-queue/mergedQueue.d.ts

@@ -0,0 +1,85 @@
+/**
+ * observer-queue/mergedQueue.ts — RFC-001 Block 3: seq stamping + multi-channel merge.
+ *
+ * Pattern:  Single totally-ordered staging queue. All three observer
+ *           channels (`scope` / `flow` / `emit`) funnel through ONE queue;
+ *           the `seq` counter is assigned at capture under the single JS
+ *           thread, so drain order == arrival order ACROSS channels with no
+ *           cross-queue merge logic ever needed.
+ * Role:     Glue between the capture tier (Block 1) and the flush driver
+ *           (Block 4). Pure module — imports only `capture/envelope` and
+ *           the ring (Block 2); zero engine knowledge.
+ *
+ * Seq semantics (normative, RFC-001 §5):
+ *   - Stamped BEFORE admission — an event that is then dropped (overflow)
+ *     or refused (`'block'`) still consumed its seq. Drops therefore leave
+ *     VISIBLE gaps in the delivered stream (honest loss accounting), and
+ *     `'block'`-refused events delivered inline keep their true arrival
+ *     stamp even though they overtake the queued backlog.
+ *   - Monotonic, starts at 0, never reused for the lifetime of the queue.
+ *
+ * Enqueue outcomes:
+ *   - `'queued'`  — staged for the next flush (drop-oldest may have evicted
+ *     an older event to make room; that loss is counted, never silent).
+ *   - `'dropped'` — the event was sampled out at saturation. Lost; counted.
+ *   - `'inline'`  — `'block'` policy refused the enqueue. NOT lost: the
+ *     caller (the dispatcher, Block 5) must deliver the returned envelope
+ *     synchronously inline — blocking delivery by explicit consumer choice.
+ */
+import { type CaptureChannel, type CaptureEnvelope, type CaptureHooks, type CapturePolicy } from '../capture/envelope.js';
+import { type OverflowPolicy, type RingCounters } from './ring.js';
+/** RFC-001 §5 default queue bound. */
+export declare const DEFAULT_MAX_QUEUE = 10000;
+/** One observer event to merge — {@link capture}'s request minus `seq`. */
+export interface EnqueueInput {
+    readonly channel: CaptureChannel;
+    readonly method: string;
+    readonly runtimeStageId: string;
+    readonly runId: string;
+    /** LIVE payload — materialized per capture policy at enqueue time. */
+    readonly payload: unknown;
+}
+/** Fate of one enqueued event — see the module header. */
+export type EnqueueOutcome = 'queued' | 'dropped' | 'inline';
+export interface EnqueueResult {
+    /** The captured, seq-stamped envelope (built even when not queued). */
+    readonly envelope: CaptureEnvelope;
+    readonly outcome: EnqueueOutcome;
+}
+export interface MergedQueueOptions {
+    /** Ring capacity. Default {@link DEFAULT_MAX_QUEUE} (10 000). */
+    readonly maxQueue?: number;
+    /** Overflow policy at capacity. Default `'drop-oldest'`. */
+    readonly overflow?: OverflowPolicy;
+    /** `'sample'` only — admit 1 in this many saturated arrivals. */
+    readonly sampleEvery?: number;
+    /** Default capture policy when `enqueue` gets none. Default `'summary'`. */
+    readonly capturePolicy?: CapturePolicy;
+    /** Engine-free seams (dev-warn, clock) passed through to {@link capture}. */
+    readonly hooks?: CaptureHooks;
+}
+export declare class MergedQueue {
+    private readonly ring;
+    private readonly overflow;
+    private readonly defaultPolicy;
+    private readonly hooks?;
+    /** Arrival stamp — monotonic across ALL channels (see module header). */
+    private seq;
+    constructor(opts?: MergedQueueOptions);
+    /**
+     * Capture one event (seq-stamped at arrival) and stage it for deferred
+     * delivery. `policy` overrides the queue default per call — e.g. `'ref'`
+     * for payloads the caller proved immutable. Never throws.
+     */
+    enqueue(input: EnqueueInput, policy?: CapturePolicy): EnqueueResult;
+    /** Pop the oldest staged envelope (total arrival order across channels). */
+    shift(): CaptureEnvelope | undefined;
+    /** Current backlog. */
+    get depth(): number;
+    /** Ring capacity (the `maxQueue` bound). */
+    get capacity(): number;
+    /** The next seq to be assigned == total events captured so far. */
+    get nextSeq(): number;
+    /** Lifetime loss/delivery accounting — delegated to the ring. */
+    getCounters(): RingCounters;
+}

package/dist/types/lib/observer-queue/ring.d.ts

@@ -0,0 +1,99 @@
+/**
+ * observer-queue/ring.ts — RFC-001 Block 2: bounded ring with overflow policies.
+ *
+ * Pattern:  Fixed-capacity circular buffer with explicit, COUNTED overflow
+ *           behavior. The deferred-observer queue must never grow without
+ *           bound (a slow consumer cannot OOM the producer), and must never
+ *           lose an event silently (every loss increments `drops`).
+ * Role:     Storage primitive under the merged queue (Block 3). Pure data
+ *           structure — zero imports, zero engine knowledge, generic over T.
+ *
+ * Overflow policies (RFC-001 §5, with the accepted 'block' resolution):
+ *   - `'drop-oldest'` — evict the oldest queued item to admit the new one.
+ *     The evicted item is LOST (`drops`++) and returned on the push result
+ *     so the caller can account for it. Sequence stamps on surviving items
+ *     keep loss visible as seq gaps (honest loss accounting). DEFAULT
+ *     posture for telemetry-grade delivery.
+ *   - `'sample'` — while saturated, admit 1 in `sampleEvery` arrivals
+ *     (evicting the oldest to make room — that eviction is also a counted
+ *     loss); refuse the rest (each a counted loss). Keeps a thinned,
+ *     still-fresh stream under sustained overload. The saturation counter
+ *     is episode-scoped: it resets whenever a push succeeds through the
+ *     non-full path.
+ *   - `'block'` — the ring REFUSES the new item (`accepted: false`,
+ *     `rejections`++) and drops NOTHING. In a single-threaded runtime a
+ *     queue cannot literally block its producer; the dispatcher (Block 5)
+ *     interprets a refusal as "deliver this event synchronously inline" —
+ *     re-introducing blocking delivery by the consumer's EXPLICIT choice.
+ *     Rejections are NOT losses: the event is still delivered (inline), so
+ *     `drops` stays untouched.
+ *
+ * Conservation invariant (property-tested):
+ *   pushes === delivered + drops + rejections + size
+ *
+ * CURSOR-READY (amendment A2): v1 consumes destructively through ONE cursor
+ * (`shift()` advances `head`). The designed v1.1 path keeps items in the
+ * ring and gives each listener its own read cursor; `head` then advances to
+ * `min(cursors)` (the reclaim watermark) instead of on read. The storage
+ * layout (contiguous circular window, `head` + `count`) already supports
+ * that — only the consumption surface changes. Documented, not implemented.
+ */
+/** How the ring treats a push when it is at capacity (RFC-001 §5). */
+export type OverflowPolicy = 'block' | 'drop-oldest' | 'sample';
+export interface RingOptions {
+    /** Max queued items. Positive integer. */
+    readonly capacity: number;
+    /** Overflow behavior at capacity — see the module header. */
+    readonly policy: OverflowPolicy;
+    /**
+     * `'sample'` only: admit 1 in this many arrivals while saturated.
+     * Positive integer; default 10.
+     */
+    readonly sampleEvery?: number;
+}
+/** Outcome of one {@link BoundedRing.push}. */
+export interface RingPushResult<T> {
+    /** True when the pushed item is now queued. */
+    readonly accepted: boolean;
+    /**
+     * The oldest item, when admitting the new one evicted it
+     * (`'drop-oldest'`, or a `'sample'` admission). Already counted in
+     * `drops` — surfaced so callers can do their own loss accounting.
+     */
+    readonly evicted?: T;
+}
+/** Monotonic counters — never reset for the lifetime of the ring. */
+export interface RingCounters {
+    /** Total `push()` calls. */
+    readonly pushes: number;
+    /** `shift()` calls that returned an item. */
+    readonly delivered: number;
+    /** Items LOST — evictions plus sampled-out refusals. Never silent. */
+    readonly drops: number;
+    /** `'block'` refusals — NOT losses; the caller delivers these inline. */
+    readonly rejections: number;
+}
+export declare class BoundedRing<T> {
+    private readonly buffer;
+    private readonly policy;
+    private readonly sampleEvery;
+    /** Index of the oldest queued item — the single v1 cursor (see header). */
+    private head;
+    private count;
+    /** Arrivals seen while saturated in the current episode (`'sample'`). */
+    private saturatedArrivals;
+    private pushes;
+    private delivered;
+    private drops;
+    private rejections;
+    constructor(opts: RingOptions);
+    get size(): number;
+    get capacity(): number;
+    /** Lifetime counters — see {@link RingCounters}. */
+    getCounters(): RingCounters;
+    /** Admit, evict-and-admit, refuse, or sample per policy — never throws. */
+    push(item: T): RingPushResult<T>;
+    /** Pop the oldest queued item (FIFO). `undefined` when empty. */
+    shift(): T | undefined;
+    private store;
+}

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.3.0",
+  "version": "9.5.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",