@blockcast/mmt-container 0.1.0 → 0.3.0

package/dist/delivery-gap.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Receiver-measured multicast delivery gap (BLO-35597).
+ *
+ * The FEC layer gives a block's multicast symbols a late-symbol wait before it
+ * declares the block over: the catalog block span plus an allowance for the
+ * path's arrival jitter. The catalog can only signal a tolerance it knows in
+ * advance (`fec.reorderToleranceMs`); the path the receiver actually sits on
+ * is measured here, in-band, from the arrival times of the multicast
+ * datagrams themselves.
+ *
+ * Which statistic, and why not RFC 3550 interarrival jitter
+ * ---------------------------------------------------------
+ * The wait is an inactivity bound: a block fails when no symbol reaches it for
+ * the wait. What it has to outlast is therefore the longest silence the
+ * delivery path produces, not the path's average variation.
+ *
+ * RFC 3550 §6.4.1 `J` is a mean absolute transit-time difference smoothed with
+ * gain 1/16. It is the right number for sizing a playout buffer against steady
+ * jitter, and the wrong one for a bimodal path. On the path this was measured
+ * on (iPhone Safari over Wi-Fi, prod AMT, 2026-09-28, 36,657 datagrams in 57 s)
+ * arrivals were either back-to-back (p90 inter-arrival 2 ms) or stalled for
+ * one 802.11 power-save beacon interval (102.4 ms; 135 stalls of 50-110 ms,
+ * recurring every ~511 ms at the median). Applied to that trace, `J` has a p99
+ * of 6 ms: a wait of span + J expires inside every stall, and the stall's
+ * symbols then arrive at a block that has already been failed.
+ *
+ * So the estimator is the largest delivery gap observed over a trailing
+ * window: the time between consecutive multicast datagram arrivals, measured
+ * on the page thread where the FEC deadlines themselves run (a main-thread or
+ * bridge-batching delay is as real to those timers as a radio stall). It is
+ * receiver-wide rather than per stream because the stall is a property of the
+ * link every stream shares; a quiet stream learns the gap from a busy one.
+ *
+ * Only a gap that ended in delivery counts. A silence is closed by the first
+ * packet after it; if that packet is the in-sequence successor (MMTP
+ * packet_sequence_number + 1) of the last one its packet_id delivered, nothing
+ * of that flow was lost across the silence: its packets were held and then
+ * delivered, which is exactly the lateness a longer wait turns from a failed
+ * block into a completed one. If the sequence jumped, the silence was (at
+ * least partly) loss -- a tunnel outage, a publisher pause -- and waiting
+ * longer would not have delivered anything, so the gap is not taken as
+ * jitter.
+ *
+ * The trailing window is supplied by the caller from the catalog. It must be
+ * long enough to contain one recurrence of the stall it has to remember, and
+ * nothing here can know that recurrence in advance. The window is also the
+ * largest gap reported: a silence longer than the catalog horizon is outside
+ * what the estimator models (a backgrounded tab, a long GC), and every bound
+ * derived from the wait (block lifetime, terminal retention, the release
+ * gate's hold ceiling) must stay a catalog quantity rather than a measurement.
+ * `undefined` means no catalog horizon is known: nothing bounds the gap, so
+ * none is reported and the catalog tolerance alone applies.
+ */
+export declare class DeliveryGapEstimator {
+    #private;
+    /**
+     * @param windowMs trailing window in ms, which also caps the reported gap,
+     *   or undefined when the catalog gives none (no gap is reported).
+     */
+    setWindowMs(windowMs: number | undefined): void;
+    get windowMs(): number | undefined;
+    /**
+     * Record one multicast datagram arrival at receiver time `nowMs`, carrying
+     * MMTP `packetSequenceNumber` (32-bit, per packet_id) on `packetId`.
+     */
+    noteArrival(nowMs: number, packetId: number, packetSequenceNumber: number): void;
+    /**
+     * Largest gap observed within the window ending at `nowMs`, at most the
+     * window itself; 0 if none or when no window is set.
+     */
+    peakGapMs(nowMs: number): number;
+    /** Forget everything: a new delivery path starts with no measurement. */
+    reset(): void;
+}
+//# sourceMappingURL=delivery-gap.d.ts.map

package/dist/delivery-gap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-gap.d.ts","sourceRoot":"","sources":["../src/delivery-gap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,qBAAa,oBAAoB;;IAc/B;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAS/C,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAEjC;IAED;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,IAAI;IAsBhF;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAOhC,yEAAyE;IACzE,KAAK,IAAI,IAAI;CAwBd"}

package/dist/delivery-gap.js

@@ -0,0 +1,88 @@
+// src/delivery-gap.ts
+var DeliveryGapEstimator = class {
+  /** Most recent arrival, or undefined before the first one since reset. */
+  #lastArrivalMs;
+  /** Last MMTP packet_sequence_number seen per packet_id. */
+  #lastSequence = /* @__PURE__ */ new Map();
+  /**
+   * Monotonic deque of (arrivalMs, gapMs): gaps strictly decrease from head to
+   * tail, so the head is the window maximum. Amortized O(1) per arrival.
+   */
+  #times = [];
+  #gaps = [];
+  #head = 0;
+  #windowMs;
+  /**
+   * @param windowMs trailing window in ms, which also caps the reported gap,
+   *   or undefined when the catalog gives none (no gap is reported).
+   */
+  setWindowMs(windowMs) {
+    if (windowMs !== void 0 && !(Number.isFinite(windowMs) && windowMs > 0)) {
+      throw new Error(
+        `[DeliveryGap] window must be a finite positive ms value or undefined (got ${windowMs})`
+      );
+    }
+    this.#windowMs = windowMs;
+  }
+  get windowMs() {
+    return this.#windowMs;
+  }
+  /**
+   * Record one multicast datagram arrival at receiver time `nowMs`, carrying
+   * MMTP `packetSequenceNumber` (32-bit, per packet_id) on `packetId`.
+   */
+  noteArrival(nowMs, packetId, packetSequenceNumber) {
+    const last = this.#lastArrivalMs;
+    const previousSequence = this.#lastSequence.get(packetId);
+    this.#lastArrivalMs = nowMs;
+    this.#lastSequence.set(packetId, packetSequenceNumber);
+    if (last === void 0 || previousSequence === void 0) return;
+    if (this.#windowMs === void 0) return;
+    if (previousSequence + 1 >>> 0 !== packetSequenceNumber >>> 0) return;
+    const gap = nowMs - last;
+    this.#evict(nowMs);
+    while (this.#gaps.length > this.#head && this.#gaps[this.#gaps.length - 1] <= gap) {
+      this.#gaps.pop();
+      this.#times.pop();
+    }
+    this.#gaps.push(gap);
+    this.#times.push(nowMs);
+    this.#compact();
+  }
+  /**
+   * Largest gap observed within the window ending at `nowMs`, at most the
+   * window itself; 0 if none or when no window is set.
+   */
+  peakGapMs(nowMs) {
+    const windowMs = this.#windowMs;
+    if (windowMs === void 0) return 0;
+    this.#evict(nowMs);
+    return this.#gaps.length > this.#head ? Math.min(this.#gaps[this.#head], windowMs) : 0;
+  }
+  /** Forget everything: a new delivery path starts with no measurement. */
+  reset() {
+    this.#lastArrivalMs = void 0;
+    this.#lastSequence.clear();
+    this.#times = [];
+    this.#gaps = [];
+    this.#head = 0;
+  }
+  #evict(nowMs) {
+    const windowMs = this.#windowMs;
+    if (windowMs === void 0) return;
+    while (this.#times.length > this.#head && this.#times[this.#head] < nowMs - windowMs) {
+      this.#head++;
+    }
+  }
+  #compact() {
+    if (this.#head > 0 && this.#head * 2 >= this.#times.length) {
+      this.#times = this.#times.slice(this.#head);
+      this.#gaps = this.#gaps.slice(this.#head);
+      this.#head = 0;
+    }
+  }
+};
+export {
+  DeliveryGapEstimator
+};
+//# sourceMappingURL=delivery-gap.js.map

package/dist/delivery-gap.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/delivery-gap.ts"],
+  "sourcesContent": ["/**\n * Receiver-measured multicast delivery gap (BLO-35597).\n *\n * The FEC layer gives a block's multicast symbols a late-symbol wait before it\n * declares the block over: the catalog block span plus an allowance for the\n * path's arrival jitter. The catalog can only signal a tolerance it knows in\n * advance (`fec.reorderToleranceMs`); the path the receiver actually sits on\n * is measured here, in-band, from the arrival times of the multicast\n * datagrams themselves.\n *\n * Which statistic, and why not RFC 3550 interarrival jitter\n * ---------------------------------------------------------\n * The wait is an inactivity bound: a block fails when no symbol reaches it for\n * the wait. What it has to outlast is therefore the longest silence the\n * delivery path produces, not the path's average variation.\n *\n * RFC 3550 \u00A76.4.1 `J` is a mean absolute transit-time difference smoothed with\n * gain 1/16. It is the right number for sizing a playout buffer against steady\n * jitter, and the wrong one for a bimodal path. On the path this was measured\n * on (iPhone Safari over Wi-Fi, prod AMT, 2026-09-28, 36,657 datagrams in 57 s)\n * arrivals were either back-to-back (p90 inter-arrival 2 ms) or stalled for\n * one 802.11 power-save beacon interval (102.4 ms; 135 stalls of 50-110 ms,\n * recurring every ~511 ms at the median). Applied to that trace, `J` has a p99\n * of 6 ms: a wait of span + J expires inside every stall, and the stall's\n * symbols then arrive at a block that has already been failed.\n *\n * So the estimator is the largest delivery gap observed over a trailing\n * window: the time between consecutive multicast datagram arrivals, measured\n * on the page thread where the FEC deadlines themselves run (a main-thread or\n * bridge-batching delay is as real to those timers as a radio stall). It is\n * receiver-wide rather than per stream because the stall is a property of the\n * link every stream shares; a quiet stream learns the gap from a busy one.\n *\n * Only a gap that ended in delivery counts. A silence is closed by the first\n * packet after it; if that packet is the in-sequence successor (MMTP\n * packet_sequence_number + 1) of the last one its packet_id delivered, nothing\n * of that flow was lost across the silence: its packets were held and then\n * delivered, which is exactly the lateness a longer wait turns from a failed\n * block into a completed one. If the sequence jumped, the silence was (at\n * least partly) loss -- a tunnel outage, a publisher pause -- and waiting\n * longer would not have delivered anything, so the gap is not taken as\n * jitter.\n *\n * The trailing window is supplied by the caller from the catalog. It must be\n * long enough to contain one recurrence of the stall it has to remember, and\n * nothing here can know that recurrence in advance. The window is also the\n * largest gap reported: a silence longer than the catalog horizon is outside\n * what the estimator models (a backgrounded tab, a long GC), and every bound\n * derived from the wait (block lifetime, terminal retention, the release\n * gate's hold ceiling) must stay a catalog quantity rather than a measurement.\n * `undefined` means no catalog horizon is known: nothing bounds the gap, so\n * none is reported and the catalog tolerance alone applies.\n */\nexport class DeliveryGapEstimator {\n  /** Most recent arrival, or undefined before the first one since reset. */\n  #lastArrivalMs: number | undefined\n  /** Last MMTP packet_sequence_number seen per packet_id. */\n  #lastSequence = new Map<number, number>()\n  /**\n   * Monotonic deque of (arrivalMs, gapMs): gaps strictly decrease from head to\n   * tail, so the head is the window maximum. Amortized O(1) per arrival.\n   */\n  #times: number[] = []\n  #gaps: number[] = []\n  #head = 0\n  #windowMs: number | undefined\n\n  /**\n   * @param windowMs trailing window in ms, which also caps the reported gap,\n   *   or undefined when the catalog gives none (no gap is reported).\n   */\n  setWindowMs(windowMs: number | undefined): void {\n    if (windowMs !== undefined && !(Number.isFinite(windowMs) && windowMs > 0)) {\n      throw new Error(\n        `[DeliveryGap] window must be a finite positive ms value or undefined (got ${windowMs})`,\n      )\n    }\n    this.#windowMs = windowMs\n  }\n\n  get windowMs(): number | undefined {\n    return this.#windowMs\n  }\n\n  /**\n   * Record one multicast datagram arrival at receiver time `nowMs`, carrying\n   * MMTP `packetSequenceNumber` (32-bit, per packet_id) on `packetId`.\n   */\n  noteArrival(nowMs: number, packetId: number, packetSequenceNumber: number): void {\n    const last = this.#lastArrivalMs\n    const previousSequence = this.#lastSequence.get(packetId)\n    this.#lastArrivalMs = nowMs\n    this.#lastSequence.set(packetId, packetSequenceNumber)\n    if (last === undefined || previousSequence === undefined) return\n    if (this.#windowMs === undefined) return\n    // MMTP packet_sequence_number is a 32-bit counter that wraps.\n    if (((previousSequence + 1) >>> 0) !== (packetSequenceNumber >>> 0)) return\n    const gap = nowMs - last\n    this.#evict(nowMs)\n    // A gap no larger than the current tail can never become the maximum\n    // while the tail is still in the window, except as the newest entry.\n    while (this.#gaps.length > this.#head && this.#gaps[this.#gaps.length - 1] <= gap) {\n      this.#gaps.pop()\n      this.#times.pop()\n    }\n    this.#gaps.push(gap)\n    this.#times.push(nowMs)\n    this.#compact()\n  }\n\n  /**\n   * Largest gap observed within the window ending at `nowMs`, at most the\n   * window itself; 0 if none or when no window is set.\n   */\n  peakGapMs(nowMs: number): number {\n    const windowMs = this.#windowMs\n    if (windowMs === undefined) return 0\n    this.#evict(nowMs)\n    return this.#gaps.length > this.#head ? Math.min(this.#gaps[this.#head], windowMs) : 0\n  }\n\n  /** Forget everything: a new delivery path starts with no measurement. */\n  reset(): void {\n    this.#lastArrivalMs = undefined\n    this.#lastSequence.clear()\n    this.#times = []\n    this.#gaps = []\n    this.#head = 0\n  }\n\n  #evict(nowMs: number): void {\n    const windowMs = this.#windowMs\n    if (windowMs === undefined) return\n    while (this.#times.length > this.#head && this.#times[this.#head] < nowMs - windowMs) {\n      this.#head++\n    }\n  }\n\n  #compact(): void {\n    // Drop consumed head slots once they outnumber live ones.\n    if (this.#head > 0 && this.#head * 2 >= this.#times.length) {\n      this.#times = this.#times.slice(this.#head)\n      this.#gaps = this.#gaps.slice(this.#head)\n      this.#head = 0\n    }\n  }\n}\n"],
+  "mappings": ";AAqDO,IAAM,uBAAN,MAA2B;AAAA;AAAA,EAEhC;AAAA;AAAA,EAEA,gBAAgB,oBAAI,IAAoB;AAAA;AAAA;AAAA;AAAA;AAAA,EAKxC,SAAmB,CAAC;AAAA,EACpB,QAAkB,CAAC;AAAA,EACnB,QAAQ;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,YAAY,UAAoC;AAC9C,QAAI,aAAa,UAAa,EAAE,OAAO,SAAS,QAAQ,KAAK,WAAW,IAAI;AAC1E,YAAM,IAAI;AAAA,QACR,6EAA6E,QAAQ;AAAA,MACvF;AAAA,IACF;AACA,SAAK,YAAY;AAAA,EACnB;AAAA,EAEA,IAAI,WAA+B;AACjC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,YAAY,OAAe,UAAkB,sBAAoC;AAC/E,UAAM,OAAO,KAAK;AAClB,UAAM,mBAAmB,KAAK,cAAc,IAAI,QAAQ;AACxD,SAAK,iBAAiB;AACtB,SAAK,cAAc,IAAI,UAAU,oBAAoB;AACrD,QAAI,SAAS,UAAa,qBAAqB,OAAW;AAC1D,QAAI,KAAK,cAAc,OAAW;AAElC,QAAM,mBAAmB,MAAO,MAAQ,yBAAyB,EAAI;AACrE,UAAM,MAAM,QAAQ;AACpB,SAAK,OAAO,KAAK;AAGjB,WAAO,KAAK,MAAM,SAAS,KAAK,SAAS,KAAK,MAAM,KAAK,MAAM,SAAS,CAAC,KAAK,KAAK;AACjF,WAAK,MAAM,IAAI;AACf,WAAK,OAAO,IAAI;AAAA,IAClB;AACA,SAAK,MAAM,KAAK,GAAG;AACnB,SAAK,OAAO,KAAK,KAAK;AACtB,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAU,OAAuB;AAC/B,UAAM,WAAW,KAAK;AACtB,QAAI,aAAa,OAAW,QAAO;AACnC,SAAK,OAAO,KAAK;AACjB,WAAO,KAAK,MAAM,SAAS,KAAK,QAAQ,KAAK,IAAI,KAAK,MAAM,KAAK,KAAK,GAAG,QAAQ,IAAI;AAAA,EACvF;AAAA;AAAA,EAGA,QAAc;AACZ,SAAK,iBAAiB;AACtB,SAAK,cAAc,MAAM;AACzB,SAAK,SAAS,CAAC;AACf,SAAK,QAAQ,CAAC;AACd,SAAK,QAAQ;AAAA,EACf;AAAA,EAEA,OAAO,OAAqB;AAC1B,UAAM,WAAW,KAAK;AACtB,QAAI,aAAa,OAAW;AAC5B,WAAO,KAAK,OAAO,SAAS,KAAK,SAAS,KAAK,OAAO,KAAK,KAAK,IAAI,QAAQ,UAAU;AACpF,WAAK;AAAA,IACP;AAAA,EACF;AAAA,EAEA,WAAiB;AAEf,QAAI,KAAK,QAAQ,KAAK,KAAK,QAAQ,KAAK,KAAK,OAAO,QAAQ;AAC1D,WAAK,SAAS,KAAK,OAAO,MAAM,KAAK,KAAK;AAC1C,WAAK,QAAQ,KAAK,MAAM,MAAM,KAAK,KAAK;AACxC,WAAK,QAAQ;AAAA,IACf;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/duplicate-ledger.d.ts

@@ -0,0 +1,197 @@
+/**
+ * MmtpRouter's per-stream duplicate ledgers, retained for the stream's FEC
+ * horizon (BLO-36599).
+ *
+ * The router remembers three kinds of wire number per physical stream, so a
+ * second copy of a packet is not parsed or delivered twice:
+ *
+ * - packet_sequence_numbers received on the direct source path, which a
+ *   recovered FEC block must not deliver again;
+ * - packet_sequence_numbers already handed to the track packet callback;
+ * - Source FEC Payload IDs (SS_ID) already parsed for playback, which dedup an
+ *   overlap copy against its multicast twin.
+ *
+ * Each of these is useful for as long as FECManager can still re-deliver the
+ * number's packet, which ends when its FEC block goes terminal; the ledger
+ * keeps one further block lifetime of margin. A block's symbols all arrive
+ * within its span, the catalog's `interleaveDepthMs` (draft-ramadan-moq-fec
+ * §5.1). After its last symbol FECManager makes the block terminal within one
+ * block lifetime (the inactivity fail bound plus the D-28 repair grace, the
+ * value `blockLifetimeMsForPacket()` returns). FECManager keeps the terminal
+ * record longer than that (`terminalRetentionMsForPacket()`, for the in-order
+ * release gate), and that record itself counts late symbols as duplicates, so
+ * the ledger need not match it. Measured from a number's first arrival that is
+ *
+ *   retention = interleaveDepthMs + blockLifetime + blockLifetime
+ *
+ * The bound is a time, not a count, on purpose. A count would need the
+ * stream's symbol rate, and the catalog does not give one: the producer closes
+ * a block after D media units or after K source symbols, whichever comes
+ * first, so one span can hold several blocks (every large keyframe does) and K
+ * per span is not an upper bound on the rate. The fixed 2000-entry window this
+ * replaces held about 4 s of the 467 packet/s AMT stream and about 40 s of a
+ * 47 packet/s audio stream; this one holds each stream for its own horizon.
+ *
+ * The clock is read only when a stream moves to a new FEC block (or for a
+ * packet without an FEC coordinate), never per packet, and no timer is armed:
+ * the ledgers rotate lazily.
+ *
+ * A stream whose horizon cannot be derived while FEC still runs (the FEC
+ * manager reports no per-stream geometry, or the catalog gives no block span,
+ * in which case FECManager falls back to its fail bound and still recovers
+ * blocks) is still re-delivered packets by recovery, so it keeps the count
+ * window the router kept for every stream before this change: each ledger
+ * holds its newest COUNT_BOUNDED_GENERATION to 2 * COUNT_BOUNDED_GENERATION
+ * numbers. Only a router without an FEC manager keeps no ledger: nothing
+ * re-delivers a packet.
+ */
+/**
+ * Generation length, in numbers, of a ledger whose stream has no derivable FEC
+ * horizon. This is not a new bound: it is the window every stream kept before
+ * BLO-36599 (trim to the newest 2000 once past 4000), kept for exactly the
+ * streams the FEC horizon cannot describe.
+ */
+export declare const COUNT_BOUNDED_GENERATION = 2000;
+/**
+ * RFC 1982 serial-number order on a 32-bit wire counter (MMTP
+ * packet_sequence_number, SS_ID): true when `a` precedes `b`. The counters
+ * wrap, so plain `<` would report every wrap as a regression.
+ */
+export declare function serial32Precedes(a: number, b: number): boolean;
+/** The two FECManager values a stream's duplicate retention is derived from. */
+export interface DuplicateHorizonGeometry {
+    /** Catalog `fec.interleaveDepthMs`: the full FEC block span, in ms. */
+    readonly blockSpanMs: number;
+    /**
+     * FECManager's `blockLifetimeMsForPacket()`: the longest a block stays open
+     * after its last symbol. Its terminal record is kept at least this long.
+     */
+    readonly blockLifetimeMs: number;
+}
+/**
+ * How long a stream's duplicate ledgers keep a number, or why no FEC horizon
+ * is derivable. `'no-fec-manager'`: the router decodes no FEC, so nothing
+ * re-delivers a packet and the stream keeps no ledger. `'no-fec-geometry'`:
+ * the FEC manager cannot report per-stream geometry. `'no-block-span'`: the
+ * stream has no catalog FEC block span (FECManager reports interleaveDepthMs
+ * 0, which is also what a stream without FEC reports). FEC may still recover
+ * blocks in the last two cases, so they keep count-bounded ledgers.
+ */
+export type DuplicateHorizon = {
+    readonly kind: 'fec-horizon';
+    readonly retentionMs: number;
+} | {
+    readonly kind: 'none';
+    readonly reason: 'no-fec-manager' | 'no-fec-geometry' | 'no-block-span';
+};
+/** Derive a stream's duplicate retention from its FEC geometry; see the module comment. */
+export declare function duplicateRetentionMs(geometry: DuplicateHorizonGeometry): number;
+/**
+ * A set of wire numbers kept in two generations. Rotating retires the older
+ * generation and starts a new one, so a number stays a member from the moment
+ * it is added until the second rotation after that: at least one full
+ * generation. A number already present keeps its first-arrival generation, as
+ * a duplicate must be timed from the original. Additions are dropped while
+ * `gate.retaining` is false. While `gate.countBounded` is true the set rotates
+ * itself each time its newer generation reaches COUNT_BOUNDED_GENERATION.
+ *
+ * One Set holds both generations. A number is added once, so the Set's
+ * insertion order is generation order and the older generation is exactly its
+ * first `#olderCount` members; rotating deletes those in place. Two Sets with
+ * a clear() per rotation would reallocate and regrow a Set every generation.
+ */
+export declare class GenerationalNumberSet {
+    #private;
+    constructor(gate: {
+        readonly retaining: boolean;
+        readonly countBounded: boolean;
+    });
+    has(value: number): boolean;
+    add(value: number): void;
+    /** Retire the older generation; the current one becomes the older. */
+    rotate(): void;
+    clear(): void;
+    /**
+     * Keep every member but forget how many rotations have passed, so no floor
+     * is reported until two more rotations. A stream that starts timing its
+     * generations calls this: generations rotated by count say nothing about
+     * how long ago their members arrived.
+     */
+    restartAging(): void;
+    /**
+     * The earliest-arrived member, once it is known to have arrived at least one
+     * full generation ago; `undefined` before that.
+     *
+     * A rotation is triggered by an arriving packet, which is normally the
+     * first member of the new generation (a live stream adds its next packet
+     * within one packet interval otherwise). From the second rotation on, the
+     * older generation therefore began at a rotation, and its first member
+     * arrived about one generation length before now. Before the second
+     * rotation the first member may be a number that simply arrived early out of
+     * order, so no floor is reported.
+     */
+    get horizonFloor(): number | undefined;
+    get size(): number;
+}
+/**
+ * One physical stream's three duplicate ledgers and their shared generation
+ * clock. `advance()` runs once per packet (and once per recovered block) before
+ * any lookup, `predatesHorizon()` included. It does work only when the packet
+ * belongs to a different FEC block than the previous one, or carries no FEC
+ * coordinate on a stream with an FEC horizon; everything else is a Set lookup.
+ */
+export declare class StreamDuplicateLedgers {
+    #private;
+    /** packet_sequence_numbers received on the direct source path. */
+    readonly sourceSeqs: GenerationalNumberSet;
+    /** packet_sequence_numbers already handed to the track packet callback. */
+    readonly routedSeqs: GenerationalNumberSet;
+    /** SS_IDs already parsed for playback. */
+    readonly parsedSymbols: GenerationalNumberSet;
+    /**
+     * @param horizon resolves the stream's current horizon from its FEC
+     *   geometry. It is read when the stream moves to a new block, so a catalog
+     *   change applies from the next block.
+     * @param now the clock FECManager's deadlines use.
+     */
+    constructor(horizon: () => DuplicateHorizon, now?: () => number);
+    /**
+     * Note the FEC block (SBN) of the packet about to be looked up, or
+     * `undefined` for a packet without a Source FEC Payload ID. Returns whether
+     * the stream keeps ledgers; while it does not, lookups find nothing and
+     * additions are dropped. The horizon is read on the first packet after
+     * construction or clear(), and again whenever the block changes; a packet
+     * without a coordinate never re-reads it, so a stream without FEC
+     * coordinates resolves its horizon once, not per packet.
+     */
+    advance(sbn: number | undefined): boolean;
+    /**
+     * Whether a packet with these wire numbers predates every number the stream
+     * has kept for at least one full FEC horizon (BLO-36599).
+     *
+     * Within one publisher epoch this cannot happen to a usable packet: it
+     * would have been sent before a packet that arrived a whole horizon ago, so
+     * no FEC block could still recover it and no reorder window could still place
+     * it. A publisher that restarts resets packet_sequence_number and SS_ID,
+     * and its first packets land exactly here. The evidence is in-band: two
+     * wire counters compared against numbers the stream actually received, with
+     * the horizon derived from the catalog. No timer is armed and no count
+     * threshold is guessed.
+     *
+     * Limits, by construction: a stream without an FEC horizon (count-bounded
+     * ledgers, or none) reports nothing, and so does a stream younger than two
+     * timed generations; a restart whose new counters land inside the retained
+     * range is not evidence, and its old numbers age out of the ledgers within
+     * one horizon.
+     */
+    predatesHorizon(packetSequenceNumber: number, ssId: number | undefined): boolean;
+    /** Whether the stream keeps ledgers, for its FEC horizon or by count. */
+    get retaining(): boolean;
+    /** Whether the ledgers are bounded by count because no FEC horizon is derivable. */
+    get countBounded(): boolean;
+    /** Current retention in ms, or null while the stream has no FEC horizon. */
+    get retentionMs(): number | null;
+    /** Forget every number (a track reset); the next packet re-derives the horizon. */
+    clear(): void;
+}
+//# sourceMappingURL=duplicate-ledger.d.ts.map

package/dist/duplicate-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplicate-ledger.d.ts","sourceRoot":"","sources":["../src/duplicate-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAA;AAE5C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED,gFAAgF;AAChF,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9D;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,eAAe,CAAA;CACxE,CAAA;AAWL,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM,CAM/E;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAqB;;gBAQpB,IAAI,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;KAAE;IAIjF,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAI3B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMxB,sEAAsE;IACtE,MAAM,IAAI,IAAI;IAqBd,KAAK,IAAI,IAAI;IAOb;;;;;OAKG;IACH,YAAY,IAAI,IAAI;IAKpB;;;;;;;;;;;OAWG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAGrC;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;;GAMG;AACH,qBAAa,sBAAsB;;IACjC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAA;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAA;IAC1C,0CAA0C;IAC1C,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAA;IAW7C;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,gBAAgB,EAAE,GAAG,GAAE,MAAM,MAAgC;IAQxF;;;;;;;;OAQG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;IAwCzC;;;;;;;;;;;;;;;;;;OAkBG;IACH,eAAe,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;IAmBhF,yEAAyE;IACzE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,oFAAoF;IACpF,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,4EAA4E;IAC5E,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED,mFAAmF;IACnF,KAAK,IAAI,IAAI;CAqBd"}

package/dist/duplicate-ledger.js

@@ -0,0 +1,226 @@
+// src/duplicate-ledger.ts
+var COUNT_BOUNDED_GENERATION = 2e3;
+function serial32Precedes(a, b) {
+  const distance = b - a >>> 0;
+  return distance !== 0 && distance < 2147483648;
+}
+function assertPositiveMs(name, value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(
+      `[DuplicateLedger] ${name}=${value}. Derive a positive ${name} from the stream catalog through FECManager.`
+    );
+  }
+}
+function duplicateRetentionMs(geometry) {
+  assertPositiveMs("blockSpanMs", geometry.blockSpanMs);
+  assertPositiveMs("blockLifetimeMs", geometry.blockLifetimeMs);
+  const untilTerminalMs = geometry.blockLifetimeMs;
+  const terminalRecordMs = geometry.blockLifetimeMs;
+  return geometry.blockSpanMs + untilTerminalMs + terminalRecordMs;
+}
+var GenerationalNumberSet = class {
+  #members = /* @__PURE__ */ new Set();
+  #olderCount = 0;
+  #newerCount = 0;
+  #rotations = 0;
+  #floor = void 0;
+  #gate;
+  constructor(gate) {
+    this.#gate = gate;
+  }
+  has(value) {
+    return this.#members.has(value);
+  }
+  add(value) {
+    if (!this.#gate.retaining || this.#members.has(value)) return;
+    this.#members.add(value);
+    if (++this.#newerCount >= COUNT_BOUNDED_GENERATION && this.#gate.countBounded) this.rotate();
+  }
+  /** Retire the older generation; the current one becomes the older. */
+  rotate() {
+    let retiring = this.#olderCount;
+    if (retiring > 0) {
+      for (const value of this.#members) {
+        this.#members.delete(value);
+        if (--retiring === 0) break;
+      }
+    }
+    this.#olderCount = this.#newerCount;
+    this.#newerCount = 0;
+    this.#rotations++;
+    this.#floor = void 0;
+    for (const value of this.#members) {
+      this.#floor = value;
+      break;
+    }
+  }
+  clear() {
+    this.#members.clear();
+    this.#olderCount = 0;
+    this.#newerCount = 0;
+    this.restartAging();
+  }
+  /**
+   * Keep every member but forget how many rotations have passed, so no floor
+   * is reported until two more rotations. A stream that starts timing its
+   * generations calls this: generations rotated by count say nothing about
+   * how long ago their members arrived.
+   */
+  restartAging() {
+    this.#rotations = 0;
+    this.#floor = void 0;
+  }
+  /**
+   * The earliest-arrived member, once it is known to have arrived at least one
+   * full generation ago; `undefined` before that.
+   *
+   * A rotation is triggered by an arriving packet, which is normally the
+   * first member of the new generation (a live stream adds its next packet
+   * within one packet interval otherwise). From the second rotation on, the
+   * older generation therefore began at a rotation, and its first member
+   * arrived about one generation length before now. Before the second
+   * rotation the first member may be a number that simply arrived early out of
+   * order, so no floor is reported.
+   */
+  get horizonFloor() {
+    if (this.#rotations < 2 || this.#olderCount === 0) return void 0;
+    return this.#floor;
+  }
+  get size() {
+    return this.#members.size;
+  }
+};
+var StreamDuplicateLedgers = class {
+  #horizon;
+  #now;
+  #retentionMs = null;
+  #countBounded = false;
+  /** Whether the horizon was read since construction or the last clear(). */
+  #horizonRead = false;
+  #generationStartMs = 0;
+  #lastSbn = void 0;
+  /**
+   * @param horizon resolves the stream's current horizon from its FEC
+   *   geometry. It is read when the stream moves to a new block, so a catalog
+   *   change applies from the next block.
+   * @param now the clock FECManager's deadlines use.
+   */
+  constructor(horizon, now = () => performance.now()) {
+    this.#horizon = horizon;
+    this.#now = now;
+    this.sourceSeqs = new GenerationalNumberSet(this);
+    this.routedSeqs = new GenerationalNumberSet(this);
+    this.parsedSymbols = new GenerationalNumberSet(this);
+  }
+  /**
+   * Note the FEC block (SBN) of the packet about to be looked up, or
+   * `undefined` for a packet without a Source FEC Payload ID. Returns whether
+   * the stream keeps ledgers; while it does not, lookups find nothing and
+   * additions are dropped. The horizon is read on the first packet after
+   * construction or clear(), and again whenever the block changes; a packet
+   * without a coordinate never re-reads it, so a stream without FEC
+   * coordinates resolves its horizon once, not per packet.
+   */
+  advance(sbn) {
+    if (sbn !== void 0) {
+      if (sbn === this.#lastSbn) return this.retaining;
+      this.#lastSbn = sbn;
+    } else if (this.#horizonRead) {
+      if (this.#retentionMs !== null) this.#rotateIfDue(this.#now());
+      return this.retaining;
+    }
+    this.#horizonRead = true;
+    const horizon = this.#horizon();
+    if (horizon.kind === "none") {
+      if (horizon.reason === "no-fec-manager") {
+        this.#forget();
+      } else {
+        this.#retentionMs = null;
+        this.#countBounded = true;
+      }
+      return this.retaining;
+    }
+    const nowMs = this.#now();
+    this.#countBounded = false;
+    if (this.#retentionMs === null) {
+      this.#retentionMs = horizon.retentionMs;
+      this.#generationStartMs = nowMs;
+      this.sourceSeqs.restartAging();
+      this.routedSeqs.restartAging();
+      this.parsedSymbols.restartAging();
+      return true;
+    }
+    this.#retentionMs = horizon.retentionMs;
+    this.#rotateIfDue(nowMs);
+    return true;
+  }
+  /**
+   * Whether a packet with these wire numbers predates every number the stream
+   * has kept for at least one full FEC horizon (BLO-36599).
+   *
+   * Within one publisher epoch this cannot happen to a usable packet: it
+   * would have been sent before a packet that arrived a whole horizon ago, so
+   * no FEC block could still recover it and no reorder window could still place
+   * it. A publisher that restarts resets packet_sequence_number and SS_ID,
+   * and its first packets land exactly here. The evidence is in-band: two
+   * wire counters compared against numbers the stream actually received, with
+   * the horizon derived from the catalog. No timer is armed and no count
+   * threshold is guessed.
+   *
+   * Limits, by construction: a stream without an FEC horizon (count-bounded
+   * ledgers, or none) reports nothing, and so does a stream younger than two
+   * timed generations; a restart whose new counters land inside the retained
+   * range is not evidence, and its old numbers age out of the ledgers within
+   * one horizon.
+   */
+  predatesHorizon(packetSequenceNumber, ssId) {
+    if (this.#retentionMs === null) return false;
+    const seqFloor = this.sourceSeqs.horizonFloor;
+    if (seqFloor !== void 0 && serial32Precedes(packetSequenceNumber, seqFloor) && !this.sourceSeqs.has(packetSequenceNumber)) {
+      return true;
+    }
+    if (ssId === void 0) return false;
+    const ssIdFloor = this.parsedSymbols.horizonFloor;
+    return ssIdFloor !== void 0 && serial32Precedes(ssId, ssIdFloor) && !this.parsedSymbols.has(ssId);
+  }
+  /** Whether the stream keeps ledgers, for its FEC horizon or by count. */
+  get retaining() {
+    return this.#retentionMs !== null || this.#countBounded;
+  }
+  /** Whether the ledgers are bounded by count because no FEC horizon is derivable. */
+  get countBounded() {
+    return this.#countBounded;
+  }
+  /** Current retention in ms, or null while the stream has no FEC horizon. */
+  get retentionMs() {
+    return this.#retentionMs;
+  }
+  /** Forget every number (a track reset); the next packet re-derives the horizon. */
+  clear() {
+    this.#forget();
+    this.#lastSbn = void 0;
+    this.#horizonRead = false;
+  }
+  #forget() {
+    this.sourceSeqs.clear();
+    this.routedSeqs.clear();
+    this.parsedSymbols.clear();
+    this.#retentionMs = null;
+    this.#countBounded = false;
+  }
+  #rotateIfDue(nowMs) {
+    if (this.#retentionMs === null || nowMs - this.#generationStartMs < this.#retentionMs) return;
+    this.sourceSeqs.rotate();
+    this.routedSeqs.rotate();
+    this.parsedSymbols.rotate();
+    this.#generationStartMs = nowMs;
+  }
+};
+export {
+  COUNT_BOUNDED_GENERATION,
+  GenerationalNumberSet,
+  StreamDuplicateLedgers,
+  duplicateRetentionMs,
+  serial32Precedes
+};
+//# sourceMappingURL=duplicate-ledger.js.map