@blockcast/mmt-container 0.1.0-main.0399efef1f07

package/dist/sample-combiner.js

@@ -0,0 +1,616 @@
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/sample-combiner.ts
+function sampleKey(catalogTrackName, mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber) {
+  return JSON.stringify([catalogTrackName ?? null, mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber]);
+}
+function trackNameOfKey(key) {
+  const name = JSON.parse(key)[0];
+  return name ?? void 0;
+}
+function identityOfKey(key) {
+  const [name, mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber] = JSON.parse(key);
+  return {
+    catalogTrackName: name ?? void 0,
+    mpuSequenceNumber,
+    movieFragmentSequenceNumber,
+    sampleNumber
+  };
+}
+var SAMPLE_COMBINE_ERROR_CODES = [
+  "duplicate-subsample-offset",
+  "overlapping-subsample",
+  "exceeds-authored-size",
+  "too-many-subsample-segments"
+];
+var SampleCombineError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SampleCombineError";
+  }
+};
+var _maxBuffered, _requireAuthoredSize, _maxSegmentsPerSample, _onAbandon, _authoredSizes, _pending, _retired, _stats, _SampleCombiner_instances, abandon_fn, tryComplete_fn, retire_fn, evictOldestPending_fn;
+var SampleCombiner = class {
+  constructor(options) {
+    __privateAdd(this, _SampleCombiner_instances);
+    __privateAdd(this, _maxBuffered);
+    __privateAdd(this, _requireAuthoredSize);
+    __privateAdd(this, _maxSegmentsPerSample);
+    __privateAdd(this, _onAbandon);
+    __privateAdd(this, _authoredSizes, /* @__PURE__ */ new Map());
+    /** Map iteration is insertion-ordered, so the first key is the oldest. */
+    __privateAdd(this, _pending, /* @__PURE__ */ new Map());
+    /**
+     * Bounded, insertion-ordered set of recently-completed sample keys, so a
+     * late duplicate or FEC-recovered retransmission is dropped rather than
+     * re-emitted or misread as a fresh whole sample.
+     */
+    __privateAdd(this, _retired, /* @__PURE__ */ new Set());
+    __privateAdd(this, _stats, {
+      combinedSamples: 0,
+      passthroughSamples: 0,
+      timedOutSamples: 0,
+      evictedSamples: 0
+    });
+    const { maxBuffered, requireAuthoredSize, maxSegmentsPerSample, onAbandon } = options;
+    if (!Number.isInteger(maxBuffered) || maxBuffered <= 0) {
+      throw new Error("[SampleCombiner] maxBuffered must be a positive integer");
+    }
+    if (!Number.isInteger(maxSegmentsPerSample) || maxSegmentsPerSample <= 0) {
+      throw new Error("[SampleCombiner] maxSegmentsPerSample must be a positive integer");
+    }
+    __privateSet(this, _maxBuffered, maxBuffered);
+    __privateSet(this, _requireAuthoredSize, requireAuthoredSize);
+    __privateSet(this, _maxSegmentsPerSample, maxSegmentsPerSample);
+    __privateSet(this, _onAbandon, onAbandon);
+  }
+  /**
+   * Register the authored sample size from the host's own FT=1 parse. Per
+   * moqcast #37, FT=1 for a movie fragment publishes before any FT=2 sample
+   * referencing it, so a host driving FT=1 as it arrives registers each
+   * sample's size before that sample's own data unit(s) arrive.
+   *
+   * On a lossy path FT=1 can still *arrive* late, after data units this
+   * combiner has already buffered. Registering a size therefore re-drives the
+   * completion check and returns the combined sample when the buffered data
+   * units already satisfy the newly-known size. Callers MUST consume the
+   * return value: for a sample carried by a single data unit there is no
+   * later {@link SampleCombiner.addMfu} to re-enter, so discarding it
+   * silently drops the sample.
+   *
+   * Registering also clears the key from the retired set. Retirement exists
+   * to drop data units that arrive *passively* after a sample completed — a
+   * late duplicate, an FEC-recovered retransmission. A host calling this
+   * method is instead asserting that a sample with this identity is authored
+   * now, which is what happens when a publisher restarts and its MPU
+   * sequence numbers begin again, or when MPU sequence wraps. Without this,
+   * such a stream would silently drop every sample whose identity collided
+   * with a retired one until the bounded set aged the key out.
+   */
+  registerAuthoredSize(catalogTrackName, mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber, size) {
+    const key = sampleKey(catalogTrackName, mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber);
+    __privateGet(this, _retired).delete(key);
+    __privateGet(this, _authoredSizes).set(key, size);
+    return __privateMethod(this, _SampleCombiner_instances, tryComplete_fn).call(this, key, size);
+  }
+  /**
+   * Add one reassembled data unit. Returns the combined sample once every
+   * constituent data unit has arrived and totals the authored size.
+   */
+  addMfu(mfu) {
+    if (mfu.movieFragmentSequenceNumber === void 0 || mfu.sampleNumber === void 0) {
+      __privateGet(this, _stats).passthroughSamples++;
+      return fromPassthrough(mfu);
+    }
+    const offset = mfu.sampleOffset ?? 0;
+    const key = sampleKey(
+      mfu.catalogTrackName,
+      mfu.mpuSequenceNumber,
+      mfu.movieFragmentSequenceNumber,
+      mfu.sampleNumber
+    );
+    if (__privateGet(this, _retired).has(key)) {
+      return null;
+    }
+    const dataLen = mfu.data.byteLength;
+    const authoredSize = __privateGet(this, _authoredSizes).get(key);
+    if (offset === 0 && !__privateGet(this, _pending).has(key)) {
+      const passesThrough = authoredSize === void 0 ? !__privateGet(this, _requireAuthoredSize) : dataLen === authoredSize;
+      if (passesThrough) {
+        __privateGet(this, _stats).passthroughSamples++;
+        __privateMethod(this, _SampleCombiner_instances, retire_fn).call(this, key);
+        return fromPassthrough(mfu);
+      }
+    }
+    const thisEnd = offset + dataLen;
+    if (authoredSize !== void 0 && thisEnd > authoredSize) {
+      throw new SampleCombineError(
+        "exceeds-authored-size",
+        "combined subsample data would exceed the registered authored sample size"
+      );
+    }
+    const existing = __privateGet(this, _pending).get(key);
+    if (existing !== void 0) {
+      if (existing.segments.has(offset)) {
+        throw new SampleCombineError(
+          "duplicate-subsample-offset",
+          "subsample data unit duplicates an offset already held for this sample"
+        );
+      }
+      if (existing.segments.size >= __privateGet(this, _maxSegmentsPerSample)) {
+        throw new SampleCombineError(
+          "too-many-subsample-segments",
+          "a sample already holds the maximum number of subsample data units"
+        );
+      }
+      for (const [segOffset, seg] of existing.segments) {
+        const segEnd = segOffset + seg.data.byteLength;
+        if (offset < segEnd && segOffset < thisEnd) {
+          throw new SampleCombineError(
+            "overlapping-subsample",
+            "subsample data unit overlaps a preceding data unit's byte range"
+          );
+        }
+      }
+    }
+    let pending = existing;
+    if (pending === void 0) {
+      if (__privateGet(this, _pending).size >= __privateGet(this, _maxBuffered)) __privateMethod(this, _SampleCombiner_instances, evictOldestPending_fn).call(this);
+      pending = { segments: /* @__PURE__ */ new Map(), startedAt: Date.now() };
+      __privateGet(this, _pending).set(key, pending);
+    }
+    pending.segments.set(offset, mfu);
+    if (authoredSize === void 0) return null;
+    return __privateMethod(this, _SampleCombiner_instances, tryComplete_fn).call(this, key, authoredSize);
+  }
+  /**
+   * Discard samples whose oldest held segment has waited past `timeoutMs`.
+   * Mirrors {@link MFUReassembler}'s clock-driven shape; the per-data-unit
+   * deadline inside {@link MFUReassembler} already bounds each constituent,
+   * so this is a backstop against a host that registers an authored size but
+   * never supplies every subsample DU.
+   */
+  cleanupTimeouts(timeoutMs) {
+    const now = Date.now();
+    for (const [key, pending] of [...__privateGet(this, _pending)]) {
+      if (now - pending.startedAt > timeoutMs) {
+        __privateGet(this, _pending).delete(key);
+        __privateGet(this, _stats).timedOutSamples++;
+        __privateMethod(this, _SampleCombiner_instances, retire_fn).call(this, key);
+        __privateMethod(this, _SampleCombiner_instances, abandon_fn).call(this, key);
+      }
+    }
+  }
+  flush() {
+    __privateGet(this, _pending).clear();
+    __privateGet(this, _authoredSizes).clear();
+    __privateGet(this, _retired).clear();
+  }
+  /**
+   * Drop one stream's in-flight, registered-size, and retired state while
+   * preserving every other stream (mirrors
+   * {@link MFUReassembler.resetStream}).
+   */
+  resetStream(catalogTrackName) {
+    for (const key of __privateGet(this, _pending).keys()) {
+      if (trackNameOfKey(key) === catalogTrackName) __privateGet(this, _pending).delete(key);
+    }
+    for (const key of __privateGet(this, _authoredSizes).keys()) {
+      if (trackNameOfKey(key) === catalogTrackName) __privateGet(this, _authoredSizes).delete(key);
+    }
+    for (const key of __privateGet(this, _retired)) {
+      if (trackNameOfKey(key) === catalogTrackName) __privateGet(this, _retired).delete(key);
+    }
+  }
+  get stats() {
+    return { ...__privateGet(this, _stats) };
+  }
+  get pendingCount() {
+    return __privateGet(this, _pending).size;
+  }
+  /**
+   * Registered authored sizes still held. Diagnostic only: it exists so tests
+   * and health reporting can assert this table stays bounded, since an
+   * unbounded one is invisible from `pendingCount` alone.
+   */
+  get debugAuthoredSizeCount() {
+    return __privateGet(this, _authoredSizes).size;
+  }
+  /** Retired keys still remembered. Diagnostic only, bounded by `maxBuffered`. */
+  get debugRetiredCount() {
+    return __privateGet(this, _retired).size;
+  }
+};
+_maxBuffered = new WeakMap();
+_requireAuthoredSize = new WeakMap();
+_maxSegmentsPerSample = new WeakMap();
+_onAbandon = new WeakMap();
+_authoredSizes = new WeakMap();
+_pending = new WeakMap();
+_retired = new WeakMap();
+_stats = new WeakMap();
+_SampleCombiner_instances = new WeakSet();
+/** Report one abandoned sample to the owner of any state keyed on it. */
+abandon_fn = function(key) {
+  var _a;
+  (_a = __privateGet(this, _onAbandon)) == null ? void 0 : _a.call(this, identityOfKey(key));
+};
+/**
+ * Emit the sample when its held data units are byte-adjacent from zero and
+ * total `size`. Completion is a protocol event, never a timer.
+ */
+tryComplete_fn = function(key, size) {
+  const pending = __privateGet(this, _pending).get(key);
+  if (pending === void 0) return null;
+  let expected = 0;
+  const sortedOffsets = [...pending.segments.keys()].sort((a, b) => a - b);
+  for (const segOffset of sortedOffsets) {
+    if (segOffset !== expected) return null;
+    expected += pending.segments.get(segOffset).data.byteLength;
+  }
+  if (expected !== size) return null;
+  __privateGet(this, _pending).delete(key);
+  __privateGet(this, _stats).combinedSamples++;
+  __privateMethod(this, _SampleCombiner_instances, retire_fn).call(this, key);
+  return fromSegments(pending.segments, sortedOffsets);
+};
+/**
+ * Retire a sample's key: free its registered authored size and remember the
+ * key in a bounded recency set. Called on every path that removes a sample
+ * -- completion, passthrough, eviction, and timeout -- so `#authoredSizes`
+ * cannot accumulate entries for samples that never complete, and so a later
+ * data unit for a discarded sample is dropped rather than starting a fresh
+ * buffer or being misread as a whole sample.
+ *
+ * The recency set holds `maxBuffered` keys. A duplicate delayed by more
+ * than that many retirements escapes it; on a reliable path there is no
+ * such duplicate, and on a lossy path the per-data-unit deadline in
+ * {@link MFUReassembler} bounds the delay well inside this window.
+ */
+retire_fn = function(key) {
+  __privateGet(this, _authoredSizes).delete(key);
+  __privateGet(this, _retired).add(key);
+  while (__privateGet(this, _retired).size > __privateGet(this, _maxBuffered)) {
+    const oldest = __privateGet(this, _retired).values().next().value;
+    if (oldest === void 0) break;
+    __privateGet(this, _retired).delete(oldest);
+  }
+};
+/**
+ * Discard the oldest pending sample by insertion order. This is the only
+ * backstop against one FEC-lost subsample data unit wedging
+ * {@link SampleCombiner.addMfu} for every future sample once `maxBuffered`
+ * is reached, for a host that never drives
+ * {@link SampleCombiner.cleanupTimeouts}.
+ */
+evictOldestPending_fn = function() {
+  const oldest = __privateGet(this, _pending).keys().next().value;
+  if (oldest === void 0) return;
+  __privateGet(this, _pending).delete(oldest);
+  __privateGet(this, _stats).evictedSamples++;
+  __privateMethod(this, _SampleCombiner_instances, retire_fn).call(this, oldest);
+  __privateMethod(this, _SampleCombiner_instances, abandon_fn).call(this, oldest);
+};
+function fromPassthrough(mfu) {
+  return {
+    mpuSequenceNumber: mfu.mpuSequenceNumber,
+    movieFragmentSequenceNumber: mfu.movieFragmentSequenceNumber ?? 0,
+    sampleNumber: mfu.sampleNumber ?? 0,
+    data: mfu.data,
+    mmtpTimestamp: mfu.timestamp,
+    timestamp: mfu.timestamp,
+    rapFlag: mfu.rapFlag,
+    priority: mfu.priority,
+    packetSequenceNumbers: mfu.packetSequenceNumbers,
+    repairedPacketSequenceNumbers: mfu.repairedPacketSequenceNumbers,
+    catalogTrackName: mfu.catalogTrackName,
+    subsampleCount: 1,
+    fragmentCount: mfu.fragmentCount,
+    source: mfu.source,
+    // One data unit in, one sample out: its provenance IS the sample's.
+    deliveryProvenance: mfu.deliveryProvenance
+  };
+}
+function fromSegments(segments, sortedOffsets) {
+  const totalSize = sortedOffsets.reduce((sum, offset) => sum + segments.get(offset).data.byteLength, 0);
+  const data = new Uint8Array(totalSize);
+  let packetSequenceNumbers;
+  let repairedPacketSequenceNumbers;
+  let writeOffset = 0;
+  let first;
+  let fragmentCount = 0;
+  let combinedProvenance = sortedOffsets.length === 0 ? "unknown" : "multicast";
+  for (const offset of sortedOffsets) {
+    const seg = segments.get(offset);
+    combinedProvenance = combinedProvenance === "mixed" || seg.deliveryProvenance === "mixed" ? "mixed" : combinedProvenance === "unknown" || seg.deliveryProvenance === "unknown" ? "unknown" : "multicast";
+    data.set(seg.data, writeOffset);
+    writeOffset += seg.data.byteLength;
+    fragmentCount += seg.fragmentCount;
+    if (seg.packetSequenceNumbers !== void 0) {
+      (packetSequenceNumbers ?? (packetSequenceNumbers = [])).push(...seg.packetSequenceNumbers);
+    }
+    if (seg.repairedPacketSequenceNumbers !== void 0) {
+      (repairedPacketSequenceNumbers ?? (repairedPacketSequenceNumbers = [])).push(...seg.repairedPacketSequenceNumbers);
+    }
+    if (first === void 0) first = seg;
+  }
+  return {
+    mpuSequenceNumber: first.mpuSequenceNumber,
+    movieFragmentSequenceNumber: first.movieFragmentSequenceNumber,
+    sampleNumber: first.sampleNumber,
+    data,
+    mmtpTimestamp: first.timestamp,
+    timestamp: first.timestamp,
+    rapFlag: first.rapFlag,
+    priority: first.priority,
+    packetSequenceNumbers,
+    repairedPacketSequenceNumbers,
+    catalogTrackName: first.catalogTrackName,
+    subsampleCount: segments.size,
+    fragmentCount,
+    source: first.source,
+    deliveryProvenance: combinedProvenance
+  };
+}
+if (void 0) {
+  const { describe, test, expect } = void 0;
+  const combiner = (overrides = {}) => new SampleCombiner({
+    maxBuffered: 10,
+    requireAuthoredSize: false,
+    maxSegmentsPerSample: 8,
+    ...overrides
+  });
+  const mfu = (mpu, movie, sample, offset, data, timestamp, rapFlag, deliveryProvenance = "multicast") => ({
+    mpuSequenceNumber: mpu,
+    data: new Uint8Array(data),
+    timestamp,
+    fragmentCount: 1,
+    rapFlag,
+    sampleNumber: sample,
+    movieFragmentSequenceNumber: movie,
+    sampleOffset: offset,
+    packetSequenceNumbers: [offset],
+    deliveryProvenance
+  });
+  describe("SampleCombiner", () => {
+    test("whole-sample DU passes through immediately with no registered size", () => {
+      const c = combiner();
+      const out = c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true));
+      expect(out).not.toBeNull();
+      expect(out.data).toEqual(new Uint8Array([1, 2, 3, 4, 5]));
+      expect(out.subsampleCount).toBe(1);
+      expect(c.pendingCount).toBe(0);
+    });
+    test("whole-sample DU passes through when it matches the registered size", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 1, 9, 17, 5);
+      const out = c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true));
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5]));
+    });
+    test("subsample data units combine once the authored size is met", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 1, 9, 17, 10);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull();
+      expect(c.pendingCount).toBe(1);
+      const out = c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 1001n, false));
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
+      expect(out?.subsampleCount).toBe(2);
+      expect(out?.rapFlag).toBe(true);
+      expect(out?.timestamp).toBe(1000n);
+      expect(c.pendingCount).toBe(0);
+      expect(c.stats.combinedSamples).toBe(1);
+    });
+    test("subsample data units combine out of order", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 1, 9, 17, 10);
+      expect(c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 1001n, false))).toBeNull();
+      const out = c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true));
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
+    });
+    test("subsample without a registered size never completes", () => {
+      const c = combiner();
+      expect(c.addMfu(mfu(1, 9, 17, 3, [1, 2, 3], 1001n, false))).toBeNull();
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3], 1000n, true))).toBeNull();
+      expect(c.pendingCount).toBe(1);
+    });
+    test("requireAuthoredSize buffers an offset-zero DU instead of guessing complete", () => {
+      const c = combiner({ requireAuthoredSize: true });
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull();
+      expect(c.pendingCount).toBe(1);
+      c.registerAuthoredSize(void 0, 1, 9, 17, 10);
+      const out = c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 1001n, false));
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
+    });
+    test("duplicate offset is rejected", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 1, 9, 17, 10);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull();
+      expect(() => c.addMfu(mfu(1, 9, 17, 0, [9, 9, 9, 9, 9], 2000n, true))).toThrow(SampleCombineError);
+    });
+    test("overlapping subsample is rejected", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 1, 9, 17, 10);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull();
+      expect(() => c.addMfu(mfu(1, 9, 17, 3, [9, 9, 9, 9, 9], 2000n, true))).toThrow(SampleCombineError);
+    });
+    test("exceeding the authored size is rejected", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 1, 9, 17, 8);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull();
+      expect(() => c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 2000n, false))).toThrow(SampleCombineError);
+    });
+    test("exceeding maxSegmentsPerSample is rejected", () => {
+      const c = combiner({ maxSegmentsPerSample: 2 });
+      c.registerAuthoredSize(void 0, 1, 9, 17, 100);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2], 1000n, true))).toBeNull();
+      expect(c.addMfu(mfu(1, 9, 17, 2, [3, 4], 1001n, false))).toBeNull();
+      expect(() => c.addMfu(mfu(1, 9, 17, 4, [5, 6], 1002n, false))).toThrow(SampleCombineError);
+    });
+    test("reports every abandoned sample so its per-sample state can be freed", () => {
+      const abandoned = [];
+      const c = combiner({ maxBuffered: 2, onAbandon: (s) => abandoned.push(s) });
+      c.registerAuthoredSize(void 0, 1, 9, 17, 10);
+      c.registerAuthoredSize(void 0, 1, 9, 18, 10);
+      c.registerAuthoredSize(void 0, 1, 9, 19, 10);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull();
+      expect(c.addMfu(mfu(1, 9, 18, 0, [2, 2, 2, 2, 2], 1001n, true))).toBeNull();
+      expect(abandoned).toEqual([]);
+      expect(c.addMfu(mfu(1, 9, 19, 0, [3, 3, 3, 3, 3], 1002n, true))).toBeNull();
+      expect(abandoned).toEqual([{
+        catalogTrackName: void 0,
+        mpuSequenceNumber: 1,
+        movieFragmentSequenceNumber: 9,
+        sampleNumber: 17
+      }]);
+      c.cleanupTimeouts(-1);
+      expect(abandoned.map((s) => s.sampleNumber)).toEqual([17, 18, 19]);
+      const d = combiner({ maxBuffered: 2, onAbandon: (s) => abandoned.push(s) });
+      d.registerAuthoredSize(void 0, 1, 9, 20, 10);
+      expect(d.addMfu(mfu(1, 9, 20, 0, [4, 4, 4, 4, 4], 1003n, true))).toBeNull();
+      expect(d.addMfu(mfu(1, 9, 20, 5, [5, 5, 5, 5, 5], 1004n, false))).not.toBeNull();
+      expect(abandoned.map((s) => s.sampleNumber)).toEqual([17, 18, 19]);
+    });
+    test("a full combiner evicts the oldest pending sample instead of throwing", () => {
+      const c = combiner({ maxBuffered: 2 });
+      c.registerAuthoredSize(void 0, 1, 9, 17, 10);
+      c.registerAuthoredSize(void 0, 1, 9, 18, 10);
+      c.registerAuthoredSize(void 0, 1, 9, 19, 10);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull();
+      expect(c.addMfu(mfu(1, 9, 18, 0, [2, 2, 2, 2, 2], 1001n, true))).toBeNull();
+      expect(c.pendingCount).toBe(2);
+      expect(c.addMfu(mfu(1, 9, 19, 0, [3, 3, 3, 3, 3], 1002n, true))).toBeNull();
+      expect(c.pendingCount).toBe(2);
+      expect(c.stats.evictedSamples).toBe(1);
+      expect(c.addMfu(mfu(1, 9, 18, 5, [8, 8, 8, 8, 8], 2001n, false))?.data).toEqual(new Uint8Array([2, 2, 2, 2, 2, 8, 8, 8, 8, 8]));
+      expect(c.addMfu(mfu(1, 9, 19, 5, [9, 9, 9, 9, 9], 2002n, false))?.data).toEqual(new Uint8Array([3, 3, 3, 3, 3, 9, 9, 9, 9, 9]));
+      c.registerAuthoredSize(void 0, 1, 9, 20, 10);
+      expect(c.addMfu(mfu(1, 9, 20, 0, [4, 4, 4, 4, 4], 3000n, true))).toBeNull();
+      expect(c.addMfu(mfu(1, 9, 20, 5, [7, 7, 7, 7, 7], 3001n, false))?.data).toEqual(new Uint8Array([4, 4, 4, 4, 4, 7, 7, 7, 7, 7]));
+    });
+    test("a completed sample frees its authored size and drops a late duplicate", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 1, 9, 17, 10);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull();
+      expect(c.addMfu(mfu(1, 9, 17, 5, [6, 7, 8, 9, 10], 1001n, false))).not.toBeNull();
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 2000n, true))).toBeNull();
+    });
+    test("resetStream drops one track and preserves the others", () => {
+      const c = combiner();
+      c.registerAuthoredSize("video/720p", 1, 9, 17, 10);
+      c.registerAuthoredSize("audio", 1, 9, 17, 10);
+      const video = { ...mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true), catalogTrackName: "video/720p" };
+      const audio = { ...mfu(1, 9, 17, 0, [2, 2, 2, 2, 2], 1000n, true), catalogTrackName: "audio" };
+      expect(c.addMfu(video)).toBeNull();
+      expect(c.addMfu(audio)).toBeNull();
+      c.resetStream("video/720p");
+      expect(c.pendingCount).toBe(1);
+      const audioTail = { ...mfu(1, 9, 17, 5, [3, 3, 3, 3, 3], 1001n, false), catalogTrackName: "audio" };
+      expect(c.addMfu(audioTail)?.data).toEqual(new Uint8Array([2, 2, 2, 2, 2, 3, 3, 3, 3, 3]));
+    });
+    test("flush clears registered authored sizes", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 1, 9, 17, 5);
+      c.flush();
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5]));
+    });
+    test("a healthy stream accumulates no bookkeeping", () => {
+      const c = combiner({ maxBuffered: 4, requireAuthoredSize: true });
+      for (let i = 0; i < 1e3; i++) {
+        expect(c.registerAuthoredSize(void 0, 1, 9, i, 10)).toBeNull();
+        expect(c.addMfu(mfu(1, 9, i, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull();
+        expect(c.addMfu(mfu(1, 9, i, 5, [2, 2, 2, 2, 2], 1001n, false))).not.toBeNull();
+      }
+      expect(c.stats.combinedSamples).toBe(1e3);
+      expect(c.pendingCount).toBe(0);
+      expect(c.debugAuthoredSizeCount).toBe(0);
+      expect(c.debugRetiredCount).toBeLessThanOrEqual(4);
+    });
+    test("samples that never complete release their authored size", () => {
+      const c = combiner({ maxBuffered: 4, requireAuthoredSize: true });
+      for (let i = 0; i < 1e3; i++) {
+        expect(c.registerAuthoredSize(void 0, 1, 9, i, 10)).toBeNull();
+        expect(c.addMfu(mfu(1, 9, i, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull();
+      }
+      c.cleanupTimeouts(-1);
+      expect(c.pendingCount).toBe(0);
+      expect(c.debugAuthoredSizeCount).toBe(0);
+    });
+    test("a late authored size completes an already-buffered sample", () => {
+      const c = combiner({ requireAuthoredSize: true });
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 2, 3, 4, 5], 1000n, true))).toBeNull();
+      expect(c.pendingCount).toBe(1);
+      const out = c.registerAuthoredSize(void 0, 1, 9, 17, 5);
+      expect(out?.data).toEqual(new Uint8Array([1, 2, 3, 4, 5]));
+      expect(out?.subsampleCount).toBe(1);
+      expect(c.pendingCount).toBe(0);
+    });
+    test("a rejected data unit does not evict a live sample", () => {
+      const c = combiner({ maxBuffered: 2 });
+      for (const s of [17, 18, 19]) c.registerAuthoredSize(void 0, 1, 9, s, 10);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull();
+      expect(c.addMfu(mfu(1, 9, 18, 0, [2, 2, 2, 2, 2], 1001n, true))).toBeNull();
+      expect(c.pendingCount).toBe(2);
+      expect(() => c.addMfu(mfu(1, 9, 19, 8, [9, 9, 9, 9, 9], 2000n, false))).toThrow(SampleCombineError);
+      expect(c.stats.evictedSamples).toBe(0);
+      expect(c.pendingCount).toBe(2);
+      expect(c.addMfu(mfu(1, 9, 17, 5, [3, 3, 3, 3, 3], 2001n, false))?.data).toEqual(new Uint8Array([1, 1, 1, 1, 1, 3, 3, 3, 3, 3]));
+    });
+    test("an evicted sample is retired rather than reopened", () => {
+      const c = combiner({ maxBuffered: 1 });
+      for (const s of [17, 18]) c.registerAuthoredSize(void 0, 1, 9, s, 10);
+      expect(c.addMfu(mfu(1, 9, 17, 0, [1, 1, 1, 1, 1], 1000n, true))).toBeNull();
+      expect(c.addMfu(mfu(1, 9, 18, 0, [2, 2, 2, 2, 2], 1001n, true))).toBeNull();
+      expect(c.stats.evictedSamples).toBe(1);
+      expect(c.addMfu(mfu(1, 9, 17, 5, [3, 3, 3, 3, 3], 2000n, false))).toBeNull();
+      expect(c.pendingCount).toBe(1);
+    });
+  });
+  describe("sample-level delivery provenance", () => {
+    test("one non-multicast subsample makes the whole sample non-exclusive", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 1, 1, 1, 4);
+      expect(c.addMfu(mfu(1, 1, 1, 0, [1, 2], 100n, true, "multicast"))).toBeNull();
+      const done = c.addMfu(mfu(1, 1, 1, 2, [3, 4], 100n, false, "mixed"));
+      expect(done).not.toBeNull();
+      expect(done.subsampleCount).toBe(2);
+      expect(done.deliveryProvenance).toBe("mixed");
+    });
+    test("an unattributed subsample degrades the sample to unknown", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 2, 1, 1, 4);
+      expect(c.addMfu(mfu(2, 1, 1, 0, [1, 2], 100n, true, "multicast"))).toBeNull();
+      const done = c.addMfu(mfu(2, 1, 1, 2, [3, 4], 100n, false, "unknown"));
+      expect(done).not.toBeNull();
+      expect(done.deliveryProvenance).toBe("unknown");
+    });
+    test("an all-multicast sample stays multicast-exclusive", () => {
+      const c = combiner();
+      c.registerAuthoredSize(void 0, 3, 1, 1, 4);
+      expect(c.addMfu(mfu(3, 1, 1, 0, [1, 2], 100n, true, "multicast"))).toBeNull();
+      const done = c.addMfu(mfu(3, 1, 1, 2, [3, 4], 100n, false, "multicast"));
+      expect(done).not.toBeNull();
+      expect(done.deliveryProvenance).toBe("multicast");
+    });
+    test("a passthrough sample inherits its data unit provenance verbatim", () => {
+      const c = combiner();
+      const done = c.addMfu(mfu(4, 1, 1, 0, [1, 2], 100n, true, "mixed"));
+      expect(done).not.toBeNull();
+      expect(done.subsampleCount).toBe(1);
+      expect(done.deliveryProvenance).toBe("mixed");
+    });
+  });
+}
+export {
+  SAMPLE_COMBINE_ERROR_CODES,
+  SampleCombineError,
+  SampleCombiner
+};
+//# sourceMappingURL=sample-combiner.js.map