@blockcast/mmt-container 0.1.0 → 0.3.0-main.0bde85f7082f

package/dist/sample-combiner.js

@@ -0,0 +1,595 @@
+// 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 SampleCombiner = class {
+  #maxBuffered;
+  #requireAuthoredSize;
+  #maxSegmentsPerSample;
+  #onAbandon;
+  #authoredSizes = /* @__PURE__ */ new Map();
+  /** Map iteration is insertion-ordered, so the first key is the oldest. */
+  #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.
+   */
+  #retired = /* @__PURE__ */ new Set();
+  #stats = {
+    combinedSamples: 0,
+    passthroughSamples: 0,
+    timedOutSamples: 0,
+    evictedSamples: 0
+  };
+  constructor(options) {
+    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");
+    }
+    this.#maxBuffered = maxBuffered;
+    this.#requireAuthoredSize = requireAuthoredSize;
+    this.#maxSegmentsPerSample = maxSegmentsPerSample;
+    this.#onAbandon = onAbandon;
+  }
+  /** Report one abandoned sample to the owner of any state keyed on it. */
+  #abandon(key) {
+    this.#onAbandon?.(identityOfKey(key));
+  }
+  /**
+   * 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);
+    this.#retired.delete(key);
+    this.#authoredSizes.set(key, size);
+    return this.#tryComplete(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) {
+      this.#stats.passthroughSamples++;
+      return fromPassthrough(mfu);
+    }
+    const offset = mfu.sampleOffset ?? 0;
+    const key = sampleKey(
+      mfu.catalogTrackName,
+      mfu.mpuSequenceNumber,
+      mfu.movieFragmentSequenceNumber,
+      mfu.sampleNumber
+    );
+    if (this.#retired.has(key)) {
+      return null;
+    }
+    const dataLen = mfu.data.byteLength;
+    const authoredSize = this.#authoredSizes.get(key);
+    if (offset === 0 && !this.#pending.has(key)) {
+      const passesThrough = authoredSize === void 0 ? !this.#requireAuthoredSize : dataLen === authoredSize;
+      if (passesThrough) {
+        this.#stats.passthroughSamples++;
+        this.#retire(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 = 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 >= 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 (this.#pending.size >= this.#maxBuffered) this.#evictOldestPending();
+      pending = { segments: /* @__PURE__ */ new Map(), startedAt: Date.now() };
+      this.#pending.set(key, pending);
+    }
+    pending.segments.set(offset, mfu);
+    if (authoredSize === void 0) return null;
+    return this.#tryComplete(key, authoredSize);
+  }
+  /**
+   * 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(key, size) {
+    const pending = 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;
+    this.#pending.delete(key);
+    this.#stats.combinedSamples++;
+    this.#retire(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(key) {
+    this.#authoredSizes.delete(key);
+    this.#retired.add(key);
+    while (this.#retired.size > this.#maxBuffered) {
+      const oldest = this.#retired.values().next().value;
+      if (oldest === void 0) break;
+      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() {
+    const oldest = this.#pending.keys().next().value;
+    if (oldest === void 0) return;
+    this.#pending.delete(oldest);
+    this.#stats.evictedSamples++;
+    this.#retire(oldest);
+    this.#abandon(oldest);
+  }
+  /**
+   * 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 [...this.#pending]) {
+      if (now - pending.startedAt > timeoutMs) {
+        this.#pending.delete(key);
+        this.#stats.timedOutSamples++;
+        this.#retire(key);
+        this.#abandon(key);
+      }
+    }
+  }
+  flush() {
+    this.#pending.clear();
+    this.#authoredSizes.clear();
+    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 this.#pending.keys()) {
+      if (trackNameOfKey(key) === catalogTrackName) this.#pending.delete(key);
+    }
+    for (const key of this.#authoredSizes.keys()) {
+      if (trackNameOfKey(key) === catalogTrackName) this.#authoredSizes.delete(key);
+    }
+    for (const key of this.#retired) {
+      if (trackNameOfKey(key) === catalogTrackName) this.#retired.delete(key);
+    }
+  }
+  get stats() {
+    return { ...this.#stats };
+  }
+  get pendingCount() {
+    return 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 this.#authoredSizes.size;
+  }
+  /** Retired keys still remembered. Diagnostic only, bounded by `maxBuffered`. */
+  get debugRetiredCount() {
+    return this.#retired.size;
+  }
+};
+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 ??= []).push(...seg.packetSequenceNumbers);
+    }
+    if (seg.repairedPacketSequenceNumbers !== void 0) {
+      (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