footprintjs 9.4.0 → 9.5.0

package/dist/lib/observer-queue/ring.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedRing = void 0;
+const DEFAULT_SAMPLE_EVERY = 10;
+class BoundedRing {
+    buffer;
+    policy;
+    sampleEvery;
+    /** Index of the oldest queued item — the single v1 cursor (see header). */
+    head = 0;
+    count = 0;
+    /** Arrivals seen while saturated in the current episode (`'sample'`). */
+    saturatedArrivals = 0;
+    pushes = 0;
+    delivered = 0;
+    drops = 0;
+    rejections = 0;
+    constructor(opts) {
+        if (!Number.isInteger(opts.capacity) || opts.capacity <= 0) {
+            throw new RangeError(`BoundedRing capacity must be a positive integer (got ${opts.capacity})`);
+        }
+        const sampleEvery = opts.sampleEvery ?? DEFAULT_SAMPLE_EVERY;
+        if (!Number.isInteger(sampleEvery) || sampleEvery <= 0) {
+            throw new RangeError(`BoundedRing sampleEvery must be a positive integer (got ${opts.sampleEvery})`);
+        }
+        this.buffer = new Array(opts.capacity);
+        this.policy = opts.policy;
+        this.sampleEvery = sampleEvery;
+    }
+    get size() {
+        return this.count;
+    }
+    get capacity() {
+        return this.buffer.length;
+    }
+    /** Lifetime counters — see {@link RingCounters}. */
+    getCounters() {
+        return { pushes: this.pushes, delivered: this.delivered, drops: this.drops, rejections: this.rejections };
+    }
+    /** Admit, evict-and-admit, refuse, or sample per policy — never throws. */
+    push(item) {
+        this.pushes += 1;
+        if (this.count < this.buffer.length) {
+            this.saturatedArrivals = 0; // new saturation episode starts fresh
+            this.store(item);
+            return { accepted: true };
+        }
+        if (this.policy === 'block') {
+            this.rejections += 1;
+            return { accepted: false };
+        }
+        if (this.policy === 'sample') {
+            this.saturatedArrivals += 1;
+            if (this.saturatedArrivals % this.sampleEvery !== 0) {
+                this.drops += 1; // the incoming item is sampled out — lost
+                return { accepted: false };
+            }
+            // The 1-in-N admission falls through to evict-and-store.
+        }
+        // 'drop-oldest' (and the 'sample' admission): evict the oldest — lost.
+        const evicted = this.buffer[this.head];
+        this.buffer[this.head] = undefined;
+        this.head = (this.head + 1) % this.buffer.length;
+        this.count -= 1;
+        this.drops += 1;
+        this.store(item);
+        return { accepted: true, evicted };
+    }
+    /** Pop the oldest queued item (FIFO). `undefined` when empty. */
+    shift() {
+        if (this.count === 0)
+            return undefined;
+        const item = this.buffer[this.head];
+        this.buffer[this.head] = undefined; // release the reference for GC
+        this.head = (this.head + 1) % this.buffer.length;
+        this.count -= 1;
+        this.delivered += 1;
+        return item;
+    }
+    store(item) {
+        this.buffer[(this.head + this.count) % this.buffer.length] = item;
+        this.count += 1;
+    }
+}
+exports.BoundedRing = BoundedRing;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmluZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9saWIvb2JzZXJ2ZXItcXVldWUvcmluZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXVDRzs7O0FBeUNILE1BQU0sb0JBQW9CLEdBQUcsRUFBRSxDQUFDO0FBRWhDLE1BQWEsV0FBVztJQUNMLE1BQU0sQ0FBdUI7SUFDN0IsTUFBTSxDQUFpQjtJQUN2QixXQUFXLENBQVM7SUFDckMsMkVBQTJFO0lBQ25FLElBQUksR0FBRyxDQUFDLENBQUM7SUFDVCxLQUFLLEdBQUcsQ0FBQyxDQUFDO0lBQ2xCLHlFQUF5RTtJQUNqRSxpQkFBaUIsR0FBRyxDQUFDLENBQUM7SUFFdEIsTUFBTSxHQUFHLENBQUMsQ0FBQztJQUNYLFNBQVMsR0FBRyxDQUFDLENBQUM7SUFDZCxLQUFLLEdBQUcsQ0FBQyxDQUFDO0lBQ1YsVUFBVSxHQUFHLENBQUMsQ0FBQztJQUV2QixZQUFZLElBQWlCO1FBQzNCLElBQUksQ0FBQyxNQUFNLENBQUMsU0FBUyxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsSUFBSSxJQUFJLENBQUMsUUFBUSxJQUFJLENBQUMsRUFBRSxDQUFDO1lBQzNELE1BQU0sSUFBSSxVQUFVLENBQUMsd0RBQXdELElBQUksQ0FBQyxRQUFRLEdBQUcsQ0FBQyxDQUFDO1FBQ2pHLENBQUM7UUFDRCxNQUFNLFdBQVcsR0FBRyxJQUFJLENBQUMsV0FBVyxJQUFJLG9CQUFvQixDQUFDO1FBQzdELElBQUksQ0FBQyxNQUFNLENBQUMsU0FBUyxDQUFDLFdBQVcsQ0FBQyxJQUFJLFdBQVcsSUFBSSxDQUFDLEVBQUUsQ0FBQztZQUN2RCxNQUFNLElBQUksVUFBVSxDQUFDLDJEQUEyRCxJQUFJLENBQUMsV0FBVyxHQUFHLENBQUMsQ0FBQztRQUN2RyxDQUFDO1FBQ0QsSUFBSSxDQUFDLE1BQU0sR0FBRyxJQUFJLEtB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RyxJQUFJLENBQUMsTUFBTSxDQUFDLE1BQU0sQ0FBQztRQUNqRCxJQUFJLENBQUMsS0FBSyxJQUFJLENBQUMsQ0FBQztRQUNoQixJQUFJLENBQUMsU0FBUyxJQUFJLENBQUMsQ0FBQztRQUNwQixPQUFPLElBQUksQ0FBQztJQUNkLENBQUM7SUFFTyxLQUFLLENBQUMsSUFBTztRQUNuQixJQUFJLENBQUMsTUFBTSxDQUFDLENBQUMsSUFBSSxDQUFDLElBQUksR0FBRyxJQUFJLENBQUMsS0FBSyxDQUFDLEdBQUcsSUFBSSxDQUFDLE1BQU0sQ0FBQyxNQUFNLENBQUMsR0FBRyxJQUFJLENBQUM7UUFDbEUsSUFBSSxDQUFDLEtBQUssSUFBSSxDQUFDLENBQUM7SUFDbEIsQ0FBQztDQUNGO0FBMUZELGtDQTBGQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogb2JzZXJ2ZXItcXVldWUvcmluZy50cyDigJQgUkZDLTAwMSBCbG9jayAyOiBib3VuZGVkIHJpbmcgd2l0aCBvdmVyZmxvdyBwb2xpY2llcy5cbiAqXG4gKiBQYXR0ZXJuOiAgRml4ZWQtY2FwYWNpdHkgY2lyY3VsYXIgYnVmZmVyIHdpdGggZXhwbGljaXQsIENPVU5URUQgb3ZlcmZsb3dcbiAqICAgICAgICAgICBiZWhhdmlvci4gVGhlIGRlZmVycmVkLW9ic2VydmVyIHF1ZXVlIG11c3QgbmV2ZXIgZ3JvdyB3aXRob3V0XG4gKiAgICAgICAgICAgYm91bmQgKGEgc2xvdyBjb25zdW1lciBjYW5ub3QgT09NIHRoZSBwcm9kdWNlciksIGFuZCBtdXN0IG5ldmVyXG4gKiAgICAgICAgICAgbG9zZSBhbiBldmVudCBzaWxlbnRseSAoZXZlcnkgbG9zcyBpbmNyZW1lbnRzIGBkcm9wc2ApLlxuICogUm9sZTogICAgIFN0b3JhZ2UgcHJpbWl0aXZlIHVuZGVyIHRoZSBtZXJnZWQgcXVldWUgKEJsb2NrIDMpLiBQdXJlIGRhdGFcbiAqICAgICAgICAgICBzdHJ1Y3R1cmUg4oCUIHplcm8gaW1wb3J0cywgemVybyBlbmdpbmUga25vd2xlZGdlLCBnZW5lcmljIG92ZXIgVC5cbiAqXG4gKiBPdmVyZmxvdyBwb2xpY2llcyAoUkZDLTAwMSDCpzUsIHdpdGggdGhlIGFjY2VwdGVkICdibG9jaycgcmVzb2x1dGlvbik6XG4gKiAgIC0gYCdkcm9wLW9sZGVzdCdgIOKAlCBldmljdCB0aGUgb2xkZXN0IHF1ZXVlZCBpdGVtIHRvIGFkbWl0IHRoZSBuZXcgb25lLlxuICogICAgIFRoZSBldmljdGVkIGl0ZW0gaXMgTE9TVCAoYGRyb3BzYCsrKSBhbmQgcmV0dXJuZWQgb24gdGhlIHB1c2ggcmVzdWx0XG4gKiAgICAgc28gdGhlIGNhbGxlciBjYW4gYWNjb3VudCBmb3IgaXQuIFNlcXVlbmNlIHN0YW1wcyBvbiBzdXJ2aXZpbmcgaXRlbXNcbiAqICAgICBrZWVwIGxvc3MgdmlzaWJsZSBhcyBzZXEgZ2FwcyAoaG9uZXN0IGxvc3MgYWNjb3VudGluZykuIERFRkFVTFRcbiAqICAgICBwb3N0dXJlIGZvciB0ZWxlbWV0cnktZ3JhZGUgZGVsaXZlcnkuXG4gKiAgIC0gYCdzYW1wbGUnYCDigJQgd2hpbGUgc2F0dXJhdGVkLCBhZG1pdCAxIGluIGBzYW1wbGVFdmVyeWAgYXJyaXZhbHNcbiAqICAgICAoZXZpY3RpbmcgdGhlIG9sZGVzdCB0byBtYWtlIHJvb20g4oCUIHRoYXQgZXZpY3Rpb24gaXMgYWxzbyBhIGNvdW50ZWRcbiAqICAgICBsb3NzKTsgcmVmdXNlIHRoZSByZXN0IChlYWNoIGEgY291bnRlZCBsb3NzKS4gS2VlcHMgYSB0aGlubmVkLFxuICogICAgIHN0aWxsLWZyZXNoIHN0cmVhbSB1bmRlciBzdXN0YWluZWQgb3ZlcmxvYWQuIFRoZSBzYXR1cmF0aW9uIGNvdW50ZXJcbiAqICAgICBpcyBlcGlzb2RlLXNjb3BlZDogaXQgcmVzZXRzIHdoZW5ldmVyIGEgcHVzaCBzdWNjZWVkcyB0aHJvdWdoIHRoZVxuICogICAgIG5vbi1mdWxsIHBhdGguXG4gKiAgIC0gYCdibG9jaydgIOKAlCB0aGUgcmluZyBSRUZVU0VTIHRoZSBuZXcgaXRlbSAoYGFjY2VwdGVkOiBmYWxzZWAsXG4gKiAgICAgYHJlamVjdGlvbnNgKyspIGFuZCBkcm9wcyBOT1RISU5HLiBJbiBhIHNpbmdsZS10aHJlYWRlZCBydW50aW1lIGFcbiAqICAgICBxdWV1ZSBjYW5ub3QgbGl0ZXJhbGx5IGJsb2NrIGl0cyBwcm9kdWNlcjsgdGhlIGRpc3BhdGNoZXIgKEJsb2NrIDUpXG4gKiAgICAgaW50ZXJwcmV0cyBhIHJlZnVzYWwgYXMgXCJkZWxpdmVyIHRoaXMgZXZlbnQgc3luY2hyb25vdXNseSBpbmxpbmVcIiDigJRcbiAqICAgICByZS1pbnRyb2R1Y2luZyBibG9ja2luZyBkZWxpdmVyeSBieSB0aGUgY29uc3VtZXIncyBFWFBMSUNJVCBjaG9pY2UuXG4gKiAgICAgUmVqZWN0aW9ucyBhcmUgTk9UIGxvc3NlczogdGhlIGV2ZW50IGlzIHN0aWxsIGRlbGl2ZXJlZCAoaW5saW5lKSwgc29cbiAqICAgICBgZHJvcHNgIHN0YXlzIHVudG91Y2hlZC5cbiAqXG4gKiBDb25zZXJ2YXRpb24gaW52YXJpYW50IChwcm9wZXJ0eS10ZXN0ZWQpOlxuICogICBwdXNoZXMgPT09IGRlbGl2ZXJlZCArIGRyb3BzICsgcmVqZWN0aW9ucyArIHNpemVcbiAqXG4gKiBDVVJTT1ItUkVBRFkgKGFtZW5kbWVudCBBMik6IHYxIGNvbnN1bWVzIGRlc3RydWN0aXZlbHkgdGhyb3VnaCBPTkUgY3Vyc29yXG4gKiAoYHNoaWZ0KClgIGFkdmFuY2VzIGBoZWFkYCkuIFRoZSBkZXNpZ25lZCB2MS4xIHBhdGgga2VlcHMgaXRlbXMgaW4gdGhlXG4gKiByaW5nIGFuZCBnaXZlcyBlYWNoIGxpc3RlbmVyIGl0cyBvd24gcmVhZCBjdXJzb3I7IGBoZWFkYCB0aGVuIGFkdmFuY2VzIHRvXG4gKiBgbWluKGN1cnNvcnMpYCAodGhlIHJlY2xhaW0gd2F0ZXJtYXJrKSBpbnN0ZWFkIG9mIG9uIHJlYWQuIFRoZSBzdG9yYWdlXG4gKiBsYXlvdXQgKGNvbnRpZ3VvdXMgY2lyY3VsYXIgd2luZG93LCBgaGVhZGAgKyBgY291bnRgKSBhbHJlYWR5IHN1cHBvcnRzXG4gKiB0aGF0IOKAlCBvbmx5IHRoZSBjb25zdW1wdGlvbiBzdXJmYWNlIGNoYW5nZXMuIERvY3VtZW50ZWQsIG5vdCBpbXBsZW1lbnRlZC5cbiAqL1xuXG4vKiogSG93IHRoZSByaW5nIHRyZWF0cyBhIHB1c2ggd2hlbiBpdCBpcyBhdCBjYXBhY2l0eSAoUkZDLTAwMSDCpzUpLiAqL1xuZXhwb3J0IHR5cGUgT3ZlcmZsb3dQb2xpY3kgPSAnYmxvY2snIHwgJ2Ryb3Atb2xkZXN0JyB8ICdzYW1wbGUnO1xuXG5leHBvcnQgaW50ZXJmYWNlIFJpbmdPcHRpb25zIHtcbiAgLyoqIE1heCBxdWV1ZWQgaXRlbXMuIFBvc2l0aXZlIGludGVnZXIuICovXG4gIHJlYWRvbmx5IGNhcGFjaXR5OiBudW1iZXI7XG4gIC8qKiBPdmVyZmxvdyBiZWhhdmlvciBhdCBjYXBhY2l0eSDigJQgc2VlIHRoZSBtb2R1bGUgaGVhZGVyLiAqL1xuICByZWFkb25seSBwb2xpY3k6IE92ZXJmbG93UG9saWN5O1xuICAvKipcbiAgICogYCdzYW1wbGUnYCBvbmx5OiBhZG1pdCAxIGluIHRoaXMgbWFueSBhcnJpdmFscyB3aGlsZSBzYXR1cmF0ZWQuXG4gICAqIFBvc2l0aXZlIGludGVnZXI7IGRlZmF1bHQgMTAuXG4gICAqL1xuICByZWFkb25seSBzYW1wbGVFdmVyeT86IG51bWJlcjtcbn1cblxuLyoqIE91dGNvbWUgb2Ygb25lIHtAbGluayBCb3VuZGVkUmluZy5wdXNofS4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgUmluZ1B1c2hSZXN1bHQ8VD4ge1xuICAvKiogVHJ1ZSB3aGVuIHRoZSBwdXNoZWQgaXRlbSBpcyBub3cgcXVldWVkLiAqL1xuICByZWFkb25seSBhY2NlcHRlZDogYm9vbGVhbjtcbiAgLyoqXG4gICAqIFRoZSBvbGRlc3QgaXRlbSwgd2hlbiBhZG1pdHRpbmcgdGhlIG5ldyBvbmUgZXZpY3RlZCBpdFxuICAgKiAoYCdkcm9wLW9sZGVzdCdgLCBvciBhIGAnc2FtcGxlJ2AgYWRtaXNzaW9uKS4gQWxyZWFkeSBjb3VudGVkIGluXG4gICAqIGBkcm9wc2Ag4oCUIHN1cmZhY2VkIHNvIGNhbGxlcnMgY2FuIGRvIHRoZWlyIG93biBsb3NzIGFjY291bnRpbmcuXG4gICAqL1xuICByZWFkb25seSBldmljdGVkPzogVDtcbn1cblxuLyoqIE1vbm90b25pYyBjb3VudGVycyDigJQgbmV2ZXIgcmVzZXQgZm9yIHRoZSBsaWZldGltZSBvZiB0aGUgcmluZy4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgUmluZ0NvdW50ZXJzIHtcbiAgLyoqIFRvdGFsIGBwdXNoKClgIGNhbGxzLiAqL1xuICByZWFkb25seSBwdXNoZXM6IG51bWJlcjtcbiAgLyoqIGBzaGlmdCgpYCBjYWxscyB0aGF0IHJldHVybmVkIGFuIGl0ZW0uICovXG4gIHJlYWRvbmx5IGRlbGl2ZXJlZDogbnVtYmVyO1xuICAvKiogSXRlbXMgTE9TVCDigJQgZXZpY3Rpb25zIHBsdXMgc2FtcGxlZC1vdXQgcmVmdXNhbHMuIE5ldmVyIHNpbGVudC4gKi9cbiAgcmVhZG9ubHkgZHJvcHM6IG51bWJlcjtcbiAgLyoqIGAnYmxvY2snYCByZWZ1c2FscyDigJQgTk9UIGxvc3NlczsgdGhlIGNhbGxlciBkZWxpdmVycyB0aGVzZSBpbmxpbmUuICovXG4gIHJlYWRvbmx5IHJlamVjdGlvbnM6IG51bWJlcjtcbn1cblxuY29uc3QgREVGQVVMVF9TQU1QTEVfRVZFUlkgPSAxMDtcblxuZXhwb3J0IGNsYXNzIEJvdW5kZWRSaW5nPFQ+IHtcbiAgcHJpdmF0ZSByZWFkb25seSBidWZmZXI6IEFycmF5PFQgfCB1bmRlZmluZWQ+O1xuICBwcml2YXRlIHJlYWRvbmx5IHBvbGljeTogT3ZlcmZsb3dQb2xpY3k7XG4gIHByaXZhdGUgcmVhZG9ubHkgc2FtcGxlRXZlcnk6IG51bWJlcjtcbiAgLyoqIEluZGV4IG9mIHRoZSBvbGRlc3QgcXVldWVkIGl0ZW0g4oCUIHRoZSBzaW5nbGUgdjEgY3Vyc29yIChzZWUgaGVhZGVyKS4gKi9cbiAgcHJpdmF0ZSBoZWFkID0gMDtcbiAgcHJpdmF0ZSBjb3VudCA9IDA7XG4gIC8qKiBBcnJpdmFscyBzZWVuIHdoaWxlIHNhdHVyYXRlZCBpbiB0aGUgY3VycmVudCBlcGlzb2RlIChgJ3NhbXBsZSdgKS4gKi9cbiAgcHJpdmF0ZSBzYXR1cmF0ZWRBcnJpdmFscyA9IDA7XG5cbiAgcHJpdmF0ZSBwdXNoZXMgPSAwO1xuICBwcml2YXRlIGRlbGl2ZXJlZCA9IDA7XG4gIHByaXZhdGUgZHJvcHMgPSAwO1xuICBwcml2YXRlIHJlamVjdGlvbnMgPSAwO1xuXG4gIGNvbnN0cnVjdG9yKG9wdHM6IFJpbmdPcHRpb25zKSB7XG4gICAgaWYgKCFOdW1iZXIuaXNJbnRlZ2VyKG9wdHMuY2FwYWNpdHkpIHx8IG9wdHMuY2FwYWNpdHkgPD0gMCkge1xuICAgICAgdGhyb3cgbmV3IFJhbmdlRXJyb3IoYEJvdW5kZWRSaW5nIGNhcGFjaXR5IG11c3QgYmUgYSBwb3NpdGl2ZSBpbnRlZ2VyIChnb3QgJHtvcHRzLmNhcGFjaXR5fSlgKTtcbiAgICB9XG4gICAgY29uc3Qgc2FtcGxlRXZlcnkgPSBvcHRzLnNhbXBsZUV2ZXJ5ID8/IERFRkFVTFRfU0FNUExFX0VWRVJZO1xuICAgIGlmICghTnVtYmVyLmlzSW50ZWdlcihzYW1wbGVFdmVyeSkgfHwgc2FtcGxlRXZlcnkgPD0gMCkge1xuICAgICAgdGhyb3cgbmV3IFJhbmdlRXJyb3IoYEJvdW5kZWRSaW5nIHNhbXBsZUV2ZXJ5IG11c3QgYmUgYSBwb3NpdGl2ZSBpbnRlZ2VyIChnb3QgJHtvcHRzLnNhbXBsZUV2ZXJ5fSlgKTtcbiAgICB9XG4gICAgdGhpcy5idWZmZXIgPSBuZXcgQXJyYXk8VCB8IHVuZGVmaW5lZD4ob3B0cy5jYXBhY2l0eSk7XG4gICAgdGhpcy5wb2xpY3kgPSBvcHRzLnBvbGljeTtcbiAgICB0aGlzLnNhbXBsZUV2ZXJ5ID0gc2FtcGxlRXZlcnk7XG4gIH1cblxuICBnZXQgc2l6ZSgpOiBudW1iZXIge1xuICAgIHJldHVybiB0aGlzLmNvdW50O1xuICB9XG5cbiAgZ2V0IGNhcGFjaXR5KCk6IG51bWJlciB7XG4gICAgcmV0dXJuIHRoaXMuYnVmZmVyLmxlbmd0aDtcbiAgfVxuXG4gIC8qKiBMaWZldGltZSBjb3VudGVycyDigJQgc2VlIHtAbGluayBSaW5nQ291bnRlcnN9LiAqL1xuICBnZXRDb3VudGVycygpOiBSaW5nQ291bnRlcnMge1xuICAgIHJldHVybiB7IHB1c2hlczogdGhpcy5wdXNoZXMsIGRlbGl2ZXJlZDogdGhpcy5kZWxpdmVyZWQsIGRyb3BzOiB0aGlzLmRyb3BzLCByZWplY3Rpb25zOiB0aGlzLnJlamVjdGlvbnMgfTtcbiAgfVxuXG4gIC8qKiBBZG1pdCwgZXZpY3QtYW5kLWFkbWl0LCByZWZ1c2UsIG9yIHNhbXBsZSBwZXIgcG9saWN5IOKAlCBuZXZlciB0aHJvd3MuICovXG4gIHB1c2goaXRlbTogVCk6IFJpbmdQdXNoUmVzdWx0PFQ+IHtcbiAgICB0aGlzLnB1c2hlcyArPSAxO1xuXG4gICAgaWYgKHRoaXMuY291bnQgPCB0aGlzLmJ1ZmZlci5sZW5ndGgpIHtcbiAgICAgIHRoaXMuc2F0dXJhdGVkQXJyaXZhbHMgPSAwOyAvLyBuZXcgc2F0dXJhdGlvbiBlcGlzb2RlIHN0YXJ0cyBmcmVzaFxuICAgICAgdGhpcy5zdG9yZShpdGVtKTtcbiAgICAgIHJldHVybiB7IGFjY2VwdGVkOiB0cnVlIH07XG4gICAgfVxuXG4gICAgaWYgKHRoaXMucG9saWN5ID09PSAnYmxvY2snKSB7XG4gICAgICB0aGlzLnJlamVjdGlvbnMgKz0gMTtcbiAgICAgIHJldHVybiB7IGFjY2VwdGVkOiBmYWxzZSB9O1xuICAgIH1cblxuICAgIGlmICh0aGlzLnBvbGljeSA9PT0gJ3NhbXBsZScpIHtcbiAgICAgIHRoaXMuc2F0dXJhdGVkQXJyaXZhbHMgKz0gMTtcbiAgICAgIGlmICh0aGlzLnNhdHVyYXRlZEFycml2YWxzICUgdGhpcy5zYW1wbGVFdmVyeSAhPT0gMCkge1xuICAgICAgICB0aGlzLmRyb3BzICs9IDE7IC8vIHRoZSBpbmNvbWluZyBpdGVtIGlzIHNhbXBsZWQgb3V0IOKAlCBsb3N0XG4gICAgICAgIHJldHVybiB7IGFjY2VwdGVkOiBmYWxzZSB9O1xuICAgICAgfVxuICAgICAgLy8gVGhlIDEtaW4tTiBhZG1pc3Npb24gZmFsbHMgdGhyb3VnaCB0byBldmljdC1hbmQtc3RvcmUuXG4gICAgfVxuXG4gICAgLy8gJ2Ryb3Atb2xkZXN0JyAoYW5kIHRoZSAnc2FtcGxlJyBhZG1pc3Npb24pOiBldmljdCB0aGUgb2xkZXN0IOKAlCBsb3N0LlxuICAgIGNvbnN0IGV2aWN0ZWQgPSB0aGlzLmJ1ZmZlclt0aGlzLmhlYWRdIGFzIFQ7XG4gICAgdGhpcy5idWZmZXJbdGhpcy5oZWFkXSA9IHVuZGVmaW5lZDtcbiAgICB0aGlzLmhlYWQgPSAodGhpcy5oZWFkICsgMSkgJSB0aGlzLmJ1ZmZlci5sZW5ndGg7XG4gICAgdGhpcy5jb3VudCAtPSAxO1xuICAgIHRoaXMuZHJvcHMgKz0gMTtcbiAgICB0aGlzLnN0b3JlKGl0ZW0pO1xuICAgIHJldHVybiB7IGFjY2VwdGVkOiB0cnVlLCBldmljdGVkIH07XG4gIH1cblxuICAvKiogUG9wIHRoZSBvbGRlc3QgcXVldWVkIGl0ZW0gKEZJRk8pLiBgdW5kZWZpbmVkYCB3aGVuIGVtcHR5LiAqL1xuICBzaGlmdCgpOiBUIHwgdW5kZWZpbmVkIHtcbiAgICBpZiAodGhpcy5jb3VudCA9PT0gMCkgcmV0dXJuIHVuZGVmaW5lZDtcbiAgICBjb25zdCBpdGVtID0gdGhpcy5idWZmZXJbdGhpcy5oZWFkXSBhcyBUO1xuICAgIHRoaXMuYnVmZmVyW3RoaXMuaGVhZF0gPSB1bmRlZmluZWQ7IC8vIHJlbGVhc2UgdGhlIHJlZmVyZW5jZSBmb3IgR0NcbiAgICB0aGlzLmhlYWQgPSAodGhpcy5oZWFkICsgMSkgJSB0aGlzLmJ1ZmZlci5sZW5ndGg7XG4gICAgdGhpcy5jb3VudCAtPSAxO1xuICAgIHRoaXMuZGVsaXZlcmVkICs9IDE7XG4gICAgcmV0dXJuIGl0ZW07XG4gIH1cblxuICBwcml2YXRlIHN0b3JlKGl0ZW06IFQpOiB2b2lkIHtcbiAgICB0aGlzLmJ1ZmZlclsodGhpcy5oZWFkICsgdGhpcy5jb3VudCkgJSB0aGlzLmJ1ZmZlci5sZW5ndGhdID0gaXRlbTtcbiAgICB0aGlzLmNvdW50ICs9IDE7XG4gIH1cbn1cbiJdfQ==

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/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/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;
+}