footprintjs 9.4.0 → 9.5.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "9.4.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",