@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/dist/phase14-catalog-override.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Phase 14 catalog-override hook (test harness only).
+ *
+ * When `globalThis.__PHASE14_CATALOG_OVERRIDE` is set (injected by the
+ * 7point test via `page.addInitScript` — see
+ * packages/moq-server/tests/7point-validation.test.mjs `applyPhase14CatalogOverride`)
+ * the override's `tracks[]` are merged into whatever catalog the MoQ-delivered
+ * JSON produced:
+ *
+ *   - Dedupe by `track.name`.
+ *   - When both sides carry a track with the same name, the override's
+ *     `fec` config wins — this is how the 7point harness steers multi-track
+ *     tests onto the Phase 14 `video/base` + `video/delta` + `video/repair`
+ *     switching set without asking the publisher to change its catalog.
+ *   - Tracks present only in the override are appended as-is.
+ *   - Tracks present only in the MoQ catalog are preserved unchanged.
+ *
+ * This module is deliberately player-agnostic. It exposes:
+ *
+ *   getPhase14CatalogOverride()        — read + shape-check the global.
+ *   mergeOverrideIntoHangRenditions()  — merge into a `@moq/hang`
+ *                                        Catalog.Root `video.renditions` /
+ *                                        `audio.renditions` dict. Used by
+ *                                        hang-mmt-fec/js/watch/src/broadcast.ts.
+ *   mergeOverrideIntoCmsfTracks()      — merge into moqtail's CMSF-flat
+ *                                        `tracks[]` array. Used by
+ *                                        moqtail-private CMSFCatalog.from().
+ *
+ * Production builds never set the global, so all three helpers are no-ops at
+ * runtime unless the test harness opts in.
+ */
+import type { FecAlgorithm, FecCatalogConfig } from "./carp-catalog.js";
+/**
+ * A single override track entry — mirrors the fixture at
+ * `packages/moq-server/tests/fixtures/multi-track-catalog.json`.
+ *
+ * Kept intentionally permissive: the canonical fixture carries `name`,
+ * `altGroup`, `framerate`, and `fec`, but future 7point scenarios may extend
+ * with additional hints without wanting this module to gate-keep them.
+ */
+export interface Phase14OverrideTrack {
+    name: string;
+    /** CMSF packaging kind. Optional per track — when absent, the merge
+     *  derives it from the override's top-level `streamingFormat`. */
+    packaging?: "mmtp" | "cmaf" | "loc" | "timeline";
+    /** Required when packaging is `mmtp`; the current publisher emits MFU mode. */
+    mmtpMode?: "mpu" | "mfu";
+    /** Required when packaging is `mmtp`; copied into synthesized CMSF tracks. */
+    timescale?: number;
+    /** Required when packaging is `mmtp`; copied into synthesized CMSF tracks. */
+    groupDurationMs?: number;
+    /** Codec string. Optional per track — when absent, the merge inherits
+     *  from the existing video/audio rendition in the MoQ catalog (the
+     *  publisher's declaration). Throws only when neither the override nor
+     *  any existing rendition supplies one. */
+    codec?: string;
+    role?: "video" | "audio" | "timeline";
+    altGroup?: number;
+    framerate?: number;
+    fec?: Partial<FecCatalogConfig> & {
+        algorithm: FecAlgorithm;
+    };
+}
+/**
+ * The shape the 7point harness writes to `globalThis.__PHASE14_CATALOG_OVERRIDE`.
+ * Extra top-level fields (`version`, `streamingFormat`, ...) are ignored —
+ * the merge only consumes `tracks[]`.
+ */
+export interface Phase14CatalogOverride {
+    version?: string;
+    streamingFormat?: string;
+    tracks: Phase14OverrideTrack[];
+}
+/**
+ * Read `globalThis.__PHASE14_CATALOG_OVERRIDE` and return it only when it has
+ * a well-formed `tracks[]` array. Malformed values log + return `null` rather
+ * than throw so a broken fixture never kills the MoQ path for a real stream.
+ */
+export declare function getPhase14CatalogOverride(): Phase14CatalogOverride | null;
+/**
+ * Merge override tracks into a `@moq/hang` Catalog.Root-like object. The
+ * caller passes the already-parsed Catalog.Root (mutates in place and also
+ * returns it for convenience). No-op when `override` is null.
+ *
+ * Dedupe rule: override wins for `fec` config and `framerate`. Everything
+ * else (codec, container kind) is preserved from the MoQ-delivered rendition
+ * when it exists, or synthesised from the override when it does not.
+ *
+ * Typed `any` here rather than narrow-matching `Catalog.Root` because the
+ * upstream `@moq/hang` schema is branded (u53) and the container `kind` union
+ * varies by version (`loc` kind appears in hang-mmt-fec's fork). Matching
+ * that surface exactly would over-couple this module to a single upstream
+ * revision; the runtime shape we rely on (`.video.renditions` dict mutation)
+ * is stable.
+ */
+export declare function mergeOverrideIntoHangRenditions<T extends Record<string, any>>(catalog: T, override: Phase14CatalogOverride | null): T;
+/**
+ * Shape-minimal description of a CMSF track input (pre-validation JSON, not
+ * the parsed `CMSFTrack`). Keeps this module free of a hard dependency on
+ * moqtail-ts.
+ */
+type CmsfTrackJson = {
+    name: string;
+    packaging?: string;
+    mmtpMode?: string;
+    timescale?: number;
+    groupDurationMs?: number;
+    role?: string;
+    codec?: string;
+    framerate?: number;
+    fec?: unknown;
+    [k: string]: unknown;
+};
+/**
+ * Merge override tracks into a raw CMSF `tracks[]` JSON array (as produced
+ * by `JSON.parse(catalog.json)` inside `CMSFCatalog.from`).
+ *
+ * Dedupe by `name`. For name collisions, publisher-emitted `fec` + `framerate`
+ * are preserved (the publisher is ground truth for wire parameters). For new
+ * track names, missing `packaging` is derived from the override's top-level
+ * `streamingFormat`, and missing `codec` is inherited from any existing video
+ * track in the catalog. Throws on bad init when neither source supplies them.
+ */
+export declare function mergeOverrideIntoCmsfTracks(tracks: CmsfTrackJson[], override: Phase14CatalogOverride | null): CmsfTrackJson[];
+export {};
+//# sourceMappingURL=phase14-catalog-override.d.ts.map

package/dist/phase14-catalog-override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase14-catalog-override.d.ts","sourceRoot":"","sources":["../src/phase14-catalog-override.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAMxE;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb;sEACkE;IAClE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;IACjD,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACzB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;+CAG2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG;QAAE,SAAS,EAAE,YAAY,CAAA;KAAE,CAAC;CAC9D;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAC/B;AAMD;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,sBAAsB,GAAG,IAAI,CAkCzE;AAMD;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,+BAA+B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5E,OAAO,EAAE,CAAC,EACV,QAAQ,EAAE,sBAAsB,GAAG,IAAI,GACrC,CAAC,CA2CH;AAMD;;;;GAIG;AACH,KAAK,aAAa,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACrB,CAAC;AAMF;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE,aAAa,EAAE,EACvB,QAAQ,EAAE,sBAAsB,GAAG,IAAI,GACrC,aAAa,EAAE,CAuGjB"}

package/dist/phase14-catalog-override.js

@@ -0,0 +1,155 @@
+// src/phase14-catalog-override.ts
+function getPhase14CatalogOverride() {
+  const g = globalThis;
+  const raw = g["__PHASE14_CATALOG_OVERRIDE"];
+  if (raw === void 0 || raw === null) return null;
+  if (typeof raw !== "object") {
+    console.warn("[phase14-catalog-override] hook is not an object; ignoring");
+    return null;
+  }
+  const obj = raw;
+  const tracks = obj["tracks"];
+  if (!Array.isArray(tracks)) {
+    console.warn("[phase14-catalog-override] hook.tracks is not an array; ignoring");
+    return null;
+  }
+  const filtered = [];
+  for (const t of tracks) {
+    if (typeof t === "object" && t !== null) {
+      const entry = t;
+      if (typeof entry["name"] === "string" && entry["name"].length > 0) {
+        filtered.push(entry);
+      }
+    }
+  }
+  if (filtered.length === 0) return null;
+  return {
+    version: typeof obj["version"] === "string" ? obj["version"] : void 0,
+    streamingFormat: typeof obj["streamingFormat"] === "string" ? obj["streamingFormat"] : void 0,
+    tracks: filtered
+  };
+}
+function mergeOverrideIntoHangRenditions(catalog, override) {
+  if (!override) return catalog;
+  for (const track of override.tracks) {
+    const role = track.role === "audio" || track.name.startsWith("audio") ? "audio" : "video";
+    const bagKey = role === "audio" ? "audio" : "video";
+    const bag = catalog[bagKey] ?? { renditions: {}, priority: 1 };
+    const existing = bag.renditions[track.name];
+    const merged = {
+      ...existing ?? {},
+      container: existing?.container ?? { kind: "mmtp-fec" },
+      codec: existing?.codec ?? ""
+    };
+    if (existing?.framerate === void 0 && track.framerate !== void 0) {
+      merged["framerate"] = track.framerate;
+    }
+    if (existing?.fec === void 0 && track.fec !== void 0) {
+      merged["fec"] = track.fec;
+    }
+    bag.renditions[track.name] = merged;
+    catalog[bagKey] = bag;
+  }
+  return catalog;
+}
+function isPositiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function mergeOverrideIntoCmsfTracks(tracks, override) {
+  if (!override) return tracks;
+  const byName = /* @__PURE__ */ new Map();
+  for (const t of tracks) {
+    if (typeof t?.name === "string") byName.set(t.name, t);
+  }
+  const derivedPackaging = override.streamingFormat;
+  const existingVideoTrack = tracks.find(
+    (t) => t.role === "video" && typeof t.codec === "string" && t.codec.length > 0
+  );
+  const existingAudioTrack = tracks.find(
+    (t) => t.role === "audio" && typeof t.codec === "string" && t.codec.length > 0
+  );
+  for (const ot of override.tracks) {
+    const existing = byName.get(ot.name);
+    if (existing !== void 0) {
+      if (existing.fec === void 0 && ot.fec !== void 0) existing.fec = ot.fec;
+      if (existing.framerate === void 0 && ot.framerate !== void 0) {
+        existing.framerate = ot.framerate;
+      }
+      if (ot.role !== void 0 && existing.role === void 0) existing.role = ot.role;
+      if (existing.packaging === "mmtp") {
+        const mode = existing.mmtpMode ?? ot.mmtpMode;
+        if (mode !== "mpu" && mode !== "mfu") {
+          throw new Error(
+            `[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid mmtpMode`
+          );
+        }
+        existing.mmtpMode = mode;
+        if (existing.timescale === void 0 && ot.timescale !== void 0) existing.timescale = ot.timescale;
+        if (existing.groupDurationMs === void 0 && ot.groupDurationMs !== void 0) {
+          existing.groupDurationMs = ot.groupDurationMs;
+        }
+        if (!isPositiveInteger(existing.timescale)) {
+          throw new Error(
+            `[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid timescale`
+          );
+        }
+        if (!isPositiveInteger(existing.groupDurationMs)) {
+          throw new Error(
+            `[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid groupDurationMs`
+          );
+        }
+      }
+    } else {
+      const packaging = ot.packaging ?? derivedPackaging;
+      if (typeof packaging !== "string" || packaging.length === 0) {
+        throw new Error(
+          `[phase14-catalog-override] track "${ot.name}" has no packaging \u2014 supply per-track or set top-level streamingFormat`
+        );
+      }
+      const role = ot.role ?? (ot.name.endsWith("/repair") ? void 0 : "video");
+      const inheritedCodec = role === "audio" ? existingAudioTrack?.codec : existingVideoTrack?.codec;
+      const codec = ot.codec ?? inheritedCodec;
+      if (packaging !== "timeline" && (typeof codec !== "string" || codec.length === 0)) {
+        throw new Error(
+          `[phase14-catalog-override] track "${ot.name}" has no codec (packaging='${packaging}') \u2014 supply per-track or ensure the publisher catalog has a ${role ?? "video"} track to inherit from`
+        );
+      }
+      const mmtpMode = ot.mmtpMode;
+      if (packaging === "mmtp" && mmtpMode !== "mpu" && mmtpMode !== "mfu") {
+        throw new Error(
+          `[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid mmtpMode`
+        );
+      }
+      if (packaging === "mmtp" && !isPositiveInteger(ot.timescale)) {
+        throw new Error(
+          `[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid timescale`
+        );
+      }
+      if (packaging === "mmtp" && !isPositiveInteger(ot.groupDurationMs)) {
+        throw new Error(
+          `[phase14-catalog-override] track "${ot.name}" has packaging='mmtp' but no valid groupDurationMs`
+        );
+      }
+      const entry = {
+        name: ot.name,
+        packaging,
+        codec
+      };
+      if (mmtpMode !== void 0) entry.mmtpMode = mmtpMode;
+      if (ot.timescale !== void 0) entry.timescale = ot.timescale;
+      if (ot.groupDurationMs !== void 0) entry.groupDurationMs = ot.groupDurationMs;
+      if (role !== void 0) entry.role = role;
+      if (ot.framerate !== void 0) entry.framerate = ot.framerate;
+      if (ot.fec !== void 0) entry.fec = ot.fec;
+      tracks.push(entry);
+      byName.set(ot.name, entry);
+    }
+  }
+  return tracks;
+}
+export {
+  getPhase14CatalogOverride,
+  mergeOverrideIntoCmsfTracks,
+  mergeOverrideIntoHangRenditions
+};
+//# sourceMappingURL=phase14-catalog-override.js.map

package/dist/phase14-catalog-override.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/phase14-catalog-override.ts"],
+  "sourcesContent": ["/**\n * Phase 14 catalog-override hook (test harness only).\n *\n * When `globalThis.__PHASE14_CATALOG_OVERRIDE` is set (injected by the\n * 7point test via `page.addInitScript` \u2014 see\n * packages/moq-server/tests/7point-validation.test.mjs `applyPhase14CatalogOverride`)\n * the override's `tracks[]` are merged into whatever catalog the MoQ-delivered\n * JSON produced:\n *\n *   - Dedupe by `track.name`.\n *   - When both sides carry a track with the same name, the override's\n *     `fec` config wins \u2014 this is how the 7point harness steers multi-track\n *     tests onto the Phase 14 `video/base` + `video/delta` + `video/repair`\n *     switching set without asking the publisher to change its catalog.\n *   - Tracks present only in the override are appended as-is.\n *   - Tracks present only in the MoQ catalog are preserved unchanged.\n *\n * This module is deliberately player-agnostic. It exposes:\n *\n *   getPhase14CatalogOverride()        \u2014 read + shape-check the global.\n *   mergeOverrideIntoHangRenditions()  \u2014 merge into a `@moq/hang`\n *                                        Catalog.Root `video.renditions` /\n *                                        `audio.renditions` dict. Used by\n *                                        hang-mmt-fec/js/watch/src/broadcast.ts.\n *   mergeOverrideIntoCmsfTracks()      \u2014 merge into moqtail's CMSF-flat\n *                                        `tracks[]` array. Used by\n *                                        moqtail-private CMSFCatalog.from().\n *\n * Production builds never set the global, so all three helpers are no-ops at\n * runtime unless the test harness opts in.\n */\n\nimport type { FecAlgorithm, FecCatalogConfig } from \"./carp-catalog.js\";\n\n// ---------------------------------------------------------------------------\n// Override fixture shape (IETF draft-ietf-moq-catalogformat-01)\n// ---------------------------------------------------------------------------\n\n/**\n * A single override track entry \u2014 mirrors the fixture at\n * `packages/moq-server/tests/fixtures/multi-track-catalog.json`.\n *\n * Kept intentionally permissive: the canonical fixture carries `name`,\n * `altGroup`, `framerate`, and `fec`, but future 7point scenarios may extend\n * with additional hints without wanting this module to gate-keep them.\n */\nexport interface Phase14OverrideTrack {\n\tname: string;\n\t/** CMSF packaging kind. Optional per track \u2014 when absent, the merge\n\t *  derives it from the override's top-level `streamingFormat`. */\n\tpackaging?: \"mmtp\" | \"cmaf\" | \"loc\" | \"timeline\";\n\t/** Required when packaging is `mmtp`; the current publisher emits MFU mode. */\n\tmmtpMode?: \"mpu\" | \"mfu\";\n\t/** Required when packaging is `mmtp`; copied into synthesized CMSF tracks. */\n\ttimescale?: number;\n\t/** Required when packaging is `mmtp`; copied into synthesized CMSF tracks. */\n\tgroupDurationMs?: number;\n\t/** Codec string. Optional per track \u2014 when absent, the merge inherits\n\t *  from the existing video/audio rendition in the MoQ catalog (the\n\t *  publisher's declaration). Throws only when neither the override nor\n\t *  any existing rendition supplies one. */\n\tcodec?: string;\n\trole?: \"video\" | \"audio\" | \"timeline\";\n\taltGroup?: number;\n\tframerate?: number;\n\tfec?: Partial<FecCatalogConfig> & { algorithm: FecAlgorithm };\n}\n\n/**\n * The shape the 7point harness writes to `globalThis.__PHASE14_CATALOG_OVERRIDE`.\n * Extra top-level fields (`version`, `streamingFormat`, ...) are ignored \u2014\n * the merge only consumes `tracks[]`.\n */\nexport interface Phase14CatalogOverride {\n\tversion?: string;\n\tstreamingFormat?: string;\n\ttracks: Phase14OverrideTrack[];\n}\n\n// ---------------------------------------------------------------------------\n// Global reader\n// ---------------------------------------------------------------------------\n\n/**\n * Read `globalThis.__PHASE14_CATALOG_OVERRIDE` and return it only when it has\n * a well-formed `tracks[]` array. Malformed values log + return `null` rather\n * than throw so a broken fixture never kills the MoQ path for a real stream.\n */\nexport function getPhase14CatalogOverride(): Phase14CatalogOverride | null {\n\t// `globalThis` is defined in workers, service workers, and the main window;\n\t// it's the portable way to reach the test-injected hook from any context.\n\tconst g = globalThis as Record<string, unknown>;\n\tconst raw = g[\"__PHASE14_CATALOG_OVERRIDE\"];\n\tif (raw === undefined || raw === null) return null;\n\tif (typeof raw !== \"object\") {\n\t\tconsole.warn(\"[phase14-catalog-override] hook is not an object; ignoring\");\n\t\treturn null;\n\t}\n\tconst obj = raw as Record<string, unknown>;\n\tconst tracks = obj[\"tracks\"];\n\tif (!Array.isArray(tracks)) {\n\t\tconsole.warn(\"[phase14-catalog-override] hook.tracks is not an array; ignoring\");\n\t\treturn null;\n\t}\n\t// Shallow filter: keep only entries that at least have a string name.\n\t// Each consumer (hang or CMSF merge) validates shape further.\n\tconst filtered: Phase14OverrideTrack[] = [];\n\tfor (const t of tracks) {\n\t\tif (typeof t === \"object\" && t !== null) {\n\t\t\tconst entry = t as Record<string, unknown>;\n\t\t\tif (typeof entry[\"name\"] === \"string\" && (entry[\"name\"] as string).length > 0) {\n\t\t\t\tfiltered.push(entry as unknown as Phase14OverrideTrack);\n\t\t\t}\n\t\t}\n\t}\n\tif (filtered.length === 0) return null;\n\treturn {\n\t\tversion: typeof obj[\"version\"] === \"string\" ? (obj[\"version\"] as string) : undefined,\n\t\tstreamingFormat:\n\t\t\ttypeof obj[\"streamingFormat\"] === \"string\" ? (obj[\"streamingFormat\"] as string) : undefined,\n\t\ttracks: filtered,\n\t};\n}\n\n// ---------------------------------------------------------------------------\n// Hang renditions merge (moq-lib / hang-mmt-fec)\n// ---------------------------------------------------------------------------\n\n/**\n * Merge override tracks into a `@moq/hang` Catalog.Root-like object. The\n * caller passes the already-parsed Catalog.Root (mutates in place and also\n * returns it for convenience). No-op when `override` is null.\n *\n * Dedupe rule: override wins for `fec` config and `framerate`. Everything\n * else (codec, container kind) is preserved from the MoQ-delivered rendition\n * when it exists, or synthesised from the override when it does not.\n *\n * Typed `any` here rather than narrow-matching `Catalog.Root` because the\n * upstream `@moq/hang` schema is branded (u53) and the container `kind` union\n * varies by version (`loc` kind appears in hang-mmt-fec's fork). Matching\n * that surface exactly would over-couple this module to a single upstream\n * revision; the runtime shape we rely on (`.video.renditions` dict mutation)\n * is stable.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function mergeOverrideIntoHangRenditions<T extends Record<string, any>>(\n\tcatalog: T,\n\toverride: Phase14CatalogOverride | null,\n): T {\n\tif (!override) return catalog;\n\n\tfor (const track of override.tracks) {\n\t\t// Default role inference: names without an explicit role field are\n\t\t// treated as video unless the name suffix says audio.\n\t\tconst role: \"video\" | \"audio\" =\n\t\t\ttrack.role === \"audio\" || track.name.startsWith(\"audio\") ? \"audio\" : \"video\";\n\n\t\tconst bagKey = role === \"audio\" ? \"audio\" : \"video\";\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst bag: { renditions: Record<string, any>; priority?: number } =\n\t\t\tcatalog[bagKey] ?? { renditions: {}, priority: 1 };\n\t\tconst existing = bag.renditions[track.name];\n\n\t\t// Merge: override fills gaps, does NOT overwrite existing fec/framerate.\n\t\t// The publisher's real catalog is ground truth for wire parameters:\n\t\t// if the existing rendition already has a matching fec config, that's\n\t\t// what the publisher's packets actually carry. Overwriting it with a\n\t\t// fixture value (e.g. Phase 14 target K=768 when publisher emits K=4)\n\t\t// causes the FEC manager to wait for symbols that never arrive.\n\t\t// Only when the rendition is brand-new (no existing fec) do we seed\n\t\t// from the fixture.\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst merged: Record<string, any> = {\n\t\t\t...(existing ?? {}),\n\t\t\tcontainer: existing?.container ?? { kind: \"mmtp-fec\" },\n\t\t\tcodec: existing?.codec ?? \"\",\n\t\t};\n\t\tif (existing?.framerate === undefined && track.framerate !== undefined) {\n\t\t\tmerged[\"framerate\"] = track.framerate;\n\t\t}\n\t\tif (existing?.fec === undefined && track.fec !== undefined) {\n\t\t\tmerged[\"fec\"] = track.fec;\n\t\t}\n\n\t\tbag.renditions[track.name] = merged;\n\t\t// Reassign so a freshly-created bag is actually reachable on the\n\t\t// catalog when the MoQ side was missing video/audio entirely.\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t(catalog as any)[bagKey] = bag;\n\t}\n\treturn catalog;\n}\n\n// ---------------------------------------------------------------------------\n// CMSF tracks merge (moqtail-private)\n// ---------------------------------------------------------------------------\n\n/**\n * Shape-minimal description of a CMSF track input (pre-validation JSON, not\n * the parsed `CMSFTrack`). Keeps this module free of a hard dependency on\n * moqtail-ts.\n */\ntype CmsfTrackJson = {\n\tname: string;\n\tpackaging?: string;\n\tmmtpMode?: string;\n\ttimescale?: number;\n\tgroupDurationMs?: number;\n\trole?: string;\n\tcodec?: string;\n\tframerate?: number;\n\tfec?: unknown;\n\t[k: string]: unknown;\n};\n\nfunction isPositiveInteger(value: unknown): value is number {\n\treturn typeof value === \"number\" && Number.isInteger(value) && value > 0;\n}\n\n/**\n * Merge override tracks into a raw CMSF `tracks[]` JSON array (as produced\n * by `JSON.parse(catalog.json)` inside `CMSFCatalog.from`).\n *\n * Dedupe by `name`. For name collisions, publisher-emitted `fec` + `framerate`\n * are preserved (the publisher is ground truth for wire parameters). For new\n * track names, missing `packaging` is derived from the override's top-level\n * `streamingFormat`, and missing `codec` is inherited from any existing video\n * track in the catalog. Throws on bad init when neither source supplies them.\n */\nexport function mergeOverrideIntoCmsfTracks(\n\ttracks: CmsfTrackJson[],\n\toverride: Phase14CatalogOverride | null,\n): CmsfTrackJson[] {\n\tif (!override) return tracks;\n\n\tconst byName = new Map<string, CmsfTrackJson>();\n\tfor (const t of tracks) {\n\t\tif (typeof t?.name === \"string\") byName.set(t.name, t);\n\t}\n\n\t// Catalog-derived fallbacks (NOT magic numbers) \u2014 inherited from existing\n\t// publisher tracks. Used only when the override track doesn't carry them.\n\tconst derivedPackaging = override.streamingFormat;\n\tconst existingVideoTrack = tracks.find(\n\t\t(t) => t.role === \"video\" && typeof t.codec === \"string\" && (t.codec as string).length > 0,\n\t);\n\tconst existingAudioTrack = tracks.find(\n\t\t(t) => t.role === \"audio\" && typeof t.codec === \"string\" && (t.codec as string).length > 0,\n\t);\n\n\tfor (const ot of override.tracks) {\n\t\tconst existing = byName.get(ot.name);\n\t\tif (existing !== undefined) {\n\t\t\t// Preserve publisher-emitted fec + framerate \u2014 those describe what\n\t\t\t// is actually on the wire. Overwriting with fixture values causes\n\t\t\t// the player's FEC manager to wait for symbols that never arrive\n\t\t\t// when the fixture's K/P don't match the publisher's.\n\t\t\tif (existing.fec === undefined && ot.fec !== undefined) existing.fec = ot.fec;\n\t\t\tif (existing.framerate === undefined && ot.framerate !== undefined) {\n\t\t\t\texisting.framerate = ot.framerate;\n\t\t\t}\n\t\t\tif (ot.role !== undefined && existing.role === undefined) existing.role = ot.role;\n\t\t\tif (existing.packaging === \"mmtp\") {\n\t\t\t\tconst mode = existing.mmtpMode ?? ot.mmtpMode;\n\t\t\t\tif (mode !== \"mpu\" && mode !== \"mfu\") {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`[phase14-catalog-override] track \"${ot.name}\" has packaging='mmtp' but no valid mmtpMode`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\texisting.mmtpMode = mode;\n\t\t\t\tif (existing.timescale === undefined && ot.timescale !== undefined) existing.timescale = ot.timescale;\n\t\t\t\tif (existing.groupDurationMs === undefined && ot.groupDurationMs !== undefined) {\n\t\t\t\t\texisting.groupDurationMs = ot.groupDurationMs;\n\t\t\t\t}\n\t\t\t\tif (!isPositiveInteger(existing.timescale)) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`[phase14-catalog-override] track \"${ot.name}\" has packaging='mmtp' but no valid timescale`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tif (!isPositiveInteger(existing.groupDurationMs)) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`[phase14-catalog-override] track \"${ot.name}\" has packaging='mmtp' but no valid groupDurationMs`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t} else {\n\t\t\tconst packaging = ot.packaging ?? derivedPackaging;\n\t\t\tif (typeof packaging !== \"string\" || packaging.length === 0) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`[phase14-catalog-override] track \"${ot.name}\" has no packaging \u2014 supply per-track or set top-level streamingFormat`,\n\t\t\t\t);\n\t\t\t}\n\t\t\t// Role inference: repair tracks (ending in /repair) stay role-less\n\t\t\t// per CMSF convention; others default to video.\n\t\t\tconst role = ot.role ?? (ot.name.endsWith(\"/repair\") ? undefined : \"video\");\n\t\t\tconst inheritedCodec =\n\t\t\t\trole === \"audio\" ? existingAudioTrack?.codec : existingVideoTrack?.codec;\n\t\t\tconst codec = ot.codec ?? inheritedCodec;\n\t\t\tif (packaging !== \"timeline\" && (typeof codec !== \"string\" || codec.length === 0)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`[phase14-catalog-override] track \"${ot.name}\" has no codec (packaging='${packaging}') \u2014 supply per-track or ensure the publisher catalog has a ${role ?? \"video\"} track to inherit from`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst mmtpMode = ot.mmtpMode;\n\t\t\tif (packaging === \"mmtp\" && mmtpMode !== \"mpu\" && mmtpMode !== \"mfu\") {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`[phase14-catalog-override] track \"${ot.name}\" has packaging='mmtp' but no valid mmtpMode`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (packaging === \"mmtp\" && !isPositiveInteger(ot.timescale)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`[phase14-catalog-override] track \"${ot.name}\" has packaging='mmtp' but no valid timescale`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (packaging === \"mmtp\" && !isPositiveInteger(ot.groupDurationMs)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`[phase14-catalog-override] track \"${ot.name}\" has packaging='mmtp' but no valid groupDurationMs`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst entry: CmsfTrackJson = {\n\t\t\t\tname: ot.name,\n\t\t\t\tpackaging,\n\t\t\t\tcodec: codec as string,\n\t\t\t};\n\t\t\tif (mmtpMode !== undefined) entry.mmtpMode = mmtpMode;\n\t\t\tif (ot.timescale !== undefined) entry.timescale = ot.timescale;\n\t\t\tif (ot.groupDurationMs !== undefined) entry.groupDurationMs = ot.groupDurationMs;\n\t\t\tif (role !== undefined) entry.role = role;\n\t\t\tif (ot.framerate !== undefined) entry.framerate = ot.framerate;\n\t\t\tif (ot.fec !== undefined) entry.fec = ot.fec;\n\t\t\ttracks.push(entry);\n\t\t\tbyName.set(ot.name, entry);\n\t\t}\n\t}\n\treturn tracks;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/repair-fetch.d.ts

@@ -0,0 +1,58 @@
+/**
+ * D-28 shared repair-fetch shell.
+ *
+ * Player-agnostic orchestration for per-SBN on-demand MoQ FEC repair
+ * backfill. Each player (moqtail client, hang watch, Shaka MSF bridge)
+ * supplies only its protocol verb via {@link RepairFetchTransport}:
+ *
+ *   - moqtail: standalone FETCH (FetchType.Standalone) for group [sbn, sbn+1)
+ *   - moq-lite/hang: Subscribe with startGroup=sbn, endGroup=sbn (the relay
+ *     propagates startGroup upstream to pull the past group from the origin's
+ *     producer cache)
+ *
+ * Everything else — registration, fire-time repair-track resolution, per-fetch
+ * abort/timeout, feeding symbols, and in-flight slot release on failure — is
+ * identical across players and lives here.
+ */
+import type { MulticastManager } from './multicast-manager.js';
+/** Resolve a packetId to its repair track name at FIRE TIME.
+ *
+ *  Called on every repair request, never cached by the shell: ABR ladder
+ *  rungs can share a packetId (e.g. video/720p and video/360p both p:1), so
+ *  the mapping must reflect the track active when the request fires, not
+ *  when the shell was wired. Return null when the packetId has no
+ *  repair-bearing track — the request is released without a fetch. */
+export type ResolveRepairTarget = (packetId: number, catalogTrackName?: string) => {
+    repairTrack: string;
+} | null;
+/** Protocol-specific fetch of one FEC block's repair group.
+ *
+ *  Yield each repair object payload (MMTP packet bytes, ISO 23008-1 §C.5.3
+ *  Repair FEC Payload ID framing). Return when the group ends. MUST abort
+ *  promptly when `signal` fires — the shell bounds every fetch by the
+ *  block's remaining repair budget. */
+export type RepairFetchTransport = (repairTrack: string, sbn: number, packetId: number, signal: AbortSignal) => AsyncIterable<Uint8Array>;
+export interface WireRepairFetchOptions {
+    resolveTarget: ResolveRepairTarget;
+    transport: RepairFetchTransport;
+    /** Override the per-fetch timeout. Default: the budget between the resolved
+     *  K-symbol source horizon and the block fail bound. */
+    timeoutMsForPacket?: (packetId: number) => number;
+    /** Classify a transport error as a transient publisher/relay retention race.
+     *  Matching failures are retried only inside the block's remaining budget. */
+    shouldRetry?: (error: unknown) => boolean;
+    /** Delay between classified transient attempts. Default: 10ms. */
+    retryDelayMs?: number;
+}
+/**
+ * Wire the D-28 repair-fetch shell onto a MulticastManager.
+ *
+ * Call AFTER the manager has a repair-bearing FEC configuration (players gate
+ * this on the first fec-setup that carries a repairTrack) — registration arms
+ * the per-block repair deadlines in the FEC layer.
+ *
+ * Returns a dispose function that aborts outstanding fetches and stops new
+ * ones from being issued.
+ */
+export declare function wireRepairFetch(mc: MulticastManager, opts: WireRepairFetchOptions): () => void;
+//# sourceMappingURL=repair-fetch.d.ts.map

package/dist/repair-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair-fetch.d.ts","sourceRoot":"","sources":["../src/repair-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAE9D;;;;;;sEAMsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,CAChC,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,KACtB;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAA;AAEnC;;;;;uCAKuC;AACvC,MAAM,MAAM,oBAAoB,GAAG,CACjC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,KAChB,aAAa,CAAC,UAAU,CAAC,CAAA;AAE9B,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,mBAAmB,CAAA;IAClC,SAAS,EAAE,oBAAoB,CAAA;IAC/B;4DACwD;IACxD,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;IACjD;kFAC8E;IAC9E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;IACzC,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,sBAAsB,GAAG,MAAM,IAAI,CAqJ9F"}

package/dist/repair-fetch.js

@@ -0,0 +1,117 @@
+// src/repair-fetch.ts
+function wireRepairFetch(mc, opts) {
+  const inFlight = /* @__PURE__ */ new Map();
+  let disposed = false;
+  const requestKey = (sbn, packetId, catalogTrackName) => JSON.stringify([packetId, catalogTrackName ?? null, sbn]);
+  const removeResetObserver = mc.addTrackResetObserver(
+    (packetId, catalogTrackName) => {
+      for (const [key, request] of inFlight) {
+        if (request.packetId === packetId && request.catalogTrackName === catalogTrackName) {
+          request.controller.abort();
+          inFlight.delete(key);
+        }
+      }
+    }
+  );
+  const timeoutFor = (sbn, packetId, catalogTrackName) => opts.timeoutMsForPacket?.(packetId) ?? mc.fecManager.repairFetchTimeoutMsForBlock(
+    sbn,
+    packetId,
+    catalogTrackName
+  );
+  const clearRepair = (sbn, packetId, catalogTrackName) => {
+    if (catalogTrackName === void 0) mc.clearRepairForBlock(sbn, packetId);
+    else mc.clearRepairForBlock(sbn, packetId, catalogTrackName);
+  };
+  const clearRepairIfOwner = (key, request) => {
+    if (inFlight.get(key) !== request) return;
+    clearRepair(request.sbn, request.packetId, request.catalogTrackName);
+  };
+  const waitForRetry = (signal) => new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    let timer;
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, Math.max(1, opts.retryDelayMs ?? 10));
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  mc.onRepairSubscribe((sbn, packetId, catalogTrackName) => {
+    if (disposed) {
+      clearRepair(sbn, packetId, catalogTrackName);
+      return;
+    }
+    const target = opts.resolveTarget(packetId, catalogTrackName);
+    if (!target) {
+      clearRepair(sbn, packetId, catalogTrackName);
+      return;
+    }
+    const ctrl = new AbortController();
+    const key = requestKey(sbn, packetId, catalogTrackName);
+    const previous = inFlight.get(key);
+    previous?.controller.abort();
+    const request = { controller: ctrl, sbn, packetId, catalogTrackName };
+    inFlight.set(key, request);
+    const timeoutMs = timeoutFor(sbn, packetId, catalogTrackName);
+    const timer = setTimeout(() => ctrl.abort(), Math.max(1, timeoutMs));
+    void (async () => {
+      let fed = 0;
+      try {
+        while (!ctrl.signal.aborted) {
+          try {
+            for await (const packet of opts.transport(
+              target.repairTrack,
+              sbn,
+              packetId,
+              ctrl.signal
+            )) {
+              if (ctrl.signal.aborted) break;
+              if (inFlight.get(key) !== request) break;
+              fed++;
+              if (catalogTrackName === void 0) {
+                mc.processRepairFromMoQ(packet, packetId);
+              } else {
+                mc.processRepairFromMoQ(packet, packetId, catalogTrackName);
+              }
+            }
+            break;
+          } catch (err) {
+            if (fed > 0 || ctrl.signal.aborted || !opts.shouldRetry?.(err)) throw err;
+            await waitForRetry(ctrl.signal);
+          }
+        }
+        if (fed === 0) clearRepairIfOwner(key, request);
+      } catch (err) {
+        clearRepairIfOwner(key, request);
+        if (!ctrl.signal.aborted) {
+          console.warn(
+            `[RepairFetch] fetch failed pid=${packetId} sbn=${sbn} track=${target.repairTrack}:`,
+            err
+          );
+        }
+      } finally {
+        clearTimeout(timer);
+        if (inFlight.get(key) === request) inFlight.delete(key);
+      }
+    })();
+  });
+  return () => {
+    disposed = true;
+    removeResetObserver();
+    for (const request of inFlight.values()) {
+      clearRepair(request.sbn, request.packetId, request.catalogTrackName);
+      request.controller.abort();
+    }
+    inFlight.clear();
+  };
+}
+export {
+  wireRepairFetch
+};
+//# sourceMappingURL=repair-fetch.js.map

package/dist/repair-fetch.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/repair-fetch.ts"],
+  "sourcesContent": ["/**\n * D-28 shared repair-fetch shell.\n *\n * Player-agnostic orchestration for per-SBN on-demand MoQ FEC repair\n * backfill. Each player (moqtail client, hang watch, Shaka MSF bridge)\n * supplies only its protocol verb via {@link RepairFetchTransport}:\n *\n *   - moqtail: standalone FETCH (FetchType.Standalone) for group [sbn, sbn+1)\n *   - moq-lite/hang: Subscribe with startGroup=sbn, endGroup=sbn (the relay\n *     propagates startGroup upstream to pull the past group from the origin's\n *     producer cache)\n *\n * Everything else \u2014 registration, fire-time repair-track resolution, per-fetch\n * abort/timeout, feeding symbols, and in-flight slot release on failure \u2014 is\n * identical across players and lives here.\n */\n\nimport type { MulticastManager } from './multicast-manager.js'\n\n/** Resolve a packetId to its repair track name at FIRE TIME.\n *\n *  Called on every repair request, never cached by the shell: ABR ladder\n *  rungs can share a packetId (e.g. video/720p and video/360p both p:1), so\n *  the mapping must reflect the track active when the request fires, not\n *  when the shell was wired. Return null when the packetId has no\n *  repair-bearing track \u2014 the request is released without a fetch. */\nexport type ResolveRepairTarget = (\n  packetId: number,\n  catalogTrackName?: string,\n) => { repairTrack: string } | null\n\n/** Protocol-specific fetch of one FEC block's repair group.\n *\n *  Yield each repair object payload (MMTP packet bytes, ISO 23008-1 \u00A7C.5.3\n *  Repair FEC Payload ID framing). Return when the group ends. MUST abort\n *  promptly when `signal` fires \u2014 the shell bounds every fetch by the\n *  block's remaining repair budget. */\nexport type RepairFetchTransport = (\n  repairTrack: string,\n  sbn: number,\n  packetId: number,\n  signal: AbortSignal,\n) => AsyncIterable<Uint8Array>\n\nexport interface WireRepairFetchOptions {\n  resolveTarget: ResolveRepairTarget\n  transport: RepairFetchTransport\n  /** Override the per-fetch timeout. Default: the budget between the resolved\n   *  K-symbol source horizon and the block fail bound. */\n  timeoutMsForPacket?: (packetId: number) => number\n  /** Classify a transport error as a transient publisher/relay retention race.\n   *  Matching failures are retried only inside the block's remaining budget. */\n  shouldRetry?: (error: unknown) => boolean\n  /** Delay between classified transient attempts. Default: 10ms. */\n  retryDelayMs?: number\n}\n\n/**\n * Wire the D-28 repair-fetch shell onto a MulticastManager.\n *\n * Call AFTER the manager has a repair-bearing FEC configuration (players gate\n * this on the first fec-setup that carries a repairTrack) \u2014 registration arms\n * the per-block repair deadlines in the FEC layer.\n *\n * Returns a dispose function that aborts outstanding fetches and stops new\n * ones from being issued.\n */\nexport function wireRepairFetch(mc: MulticastManager, opts: WireRepairFetchOptions): () => void {\n  type InFlightRepair = {\n    controller: AbortController\n    sbn: number\n    packetId: number\n    catalogTrackName?: string\n  }\n  const inFlight = new Map<string, InFlightRepair>()\n  let disposed = false\n  const requestKey = (\n    sbn: number,\n    packetId: number,\n    catalogTrackName?: string,\n  ): string => JSON.stringify([packetId, catalogTrackName ?? null, sbn])\n\n  const removeResetObserver = mc.addTrackResetObserver(\n    (packetId, catalogTrackName) => {\n      for (const [key, request] of inFlight) {\n        if (\n          request.packetId === packetId &&\n          request.catalogTrackName === catalogTrackName\n        ) {\n          request.controller.abort()\n          inFlight.delete(key)\n        }\n      }\n    },\n  )\n\n  const timeoutFor = (\n    sbn: number,\n    packetId: number,\n    catalogTrackName?: string,\n  ): number =>\n    opts.timeoutMsForPacket?.(packetId) ??\n    mc.fecManager.repairFetchTimeoutMsForBlock(\n      sbn,\n      packetId,\n      catalogTrackName,\n    )\n  const clearRepair = (\n    sbn: number,\n    packetId: number,\n    catalogTrackName?: string,\n  ): void => {\n    if (catalogTrackName === undefined) mc.clearRepairForBlock(sbn, packetId)\n    else mc.clearRepairForBlock(sbn, packetId, catalogTrackName)\n  }\n  const clearRepairIfOwner = (key: string, request: InFlightRepair): void => {\n    if (inFlight.get(key) !== request) return\n    clearRepair(request.sbn, request.packetId, request.catalogTrackName)\n  }\n  const waitForRetry = (signal: AbortSignal): Promise<void> =>\n    new Promise((resolve) => {\n      if (signal.aborted) {\n        resolve()\n        return\n      }\n      let timer: ReturnType<typeof setTimeout>\n      const onAbort = () => {\n        clearTimeout(timer)\n        resolve()\n      }\n      timer = setTimeout(() => {\n        signal.removeEventListener('abort', onAbort)\n        resolve()\n      }, Math.max(1, opts.retryDelayMs ?? 10))\n      signal.addEventListener('abort', onAbort, { once: true })\n    })\n\n  mc.onRepairSubscribe((sbn, packetId, catalogTrackName) => {\n    if (disposed) {\n      clearRepair(sbn, packetId, catalogTrackName)\n      return\n    }\n\n    // Fire-time resolution \u2014 see ResolveRepairTarget.\n    const target = opts.resolveTarget(packetId, catalogTrackName)\n    if (!target) {\n      clearRepair(sbn, packetId, catalogTrackName)\n      return\n    }\n\n    const ctrl = new AbortController()\n    const key = requestKey(sbn, packetId, catalogTrackName)\n    const previous = inFlight.get(key)\n    previous?.controller.abort()\n    const request: InFlightRepair = { controller: ctrl, sbn, packetId, catalogTrackName }\n    inFlight.set(key, request)\n    const timeoutMs = timeoutFor(sbn, packetId, catalogTrackName)\n    const timer = setTimeout(() => ctrl.abort(), Math.max(1, timeoutMs))\n\n    void (async () => {\n      let fed = 0\n      try {\n        while (!ctrl.signal.aborted) {\n          try {\n            for await (const packet of opts.transport(\n              target.repairTrack,\n              sbn,\n              packetId,\n              ctrl.signal,\n            )) {\n              if (ctrl.signal.aborted) break\n              if (inFlight.get(key) !== request) break\n              fed++\n              if (catalogTrackName === undefined) {\n                mc.processRepairFromMoQ(packet, packetId)\n              } else {\n                mc.processRepairFromMoQ(packet, packetId, catalogTrackName)\n              }\n            }\n            break\n          } catch (err) {\n            if (fed > 0 || ctrl.signal.aborted || !opts.shouldRetry?.(err)) throw err\n            await waitForRetry(ctrl.signal)\n          }\n        }\n        // A fetch that ended without feeding anything cannot resolve the\n        // block; release the slot so failure accounting is not wedged. A\n        // fetch that fed symbols leaves resolution to the FEC layer\n        // (onRepairResolved clears the slot on completion OR failure).\n        if (fed === 0) clearRepairIfOwner(key, request)\n      } catch (err) {\n        // Range-not-retained, transport error, or abort: the block can only\n        // resolve via the fail bound now \u2014 release the slot immediately.\n        clearRepairIfOwner(key, request)\n        if (!ctrl.signal.aborted) {\n          console.warn(\n            `[RepairFetch] fetch failed pid=${packetId} sbn=${sbn} track=${target.repairTrack}:`,\n            err,\n          )\n        }\n      } finally {\n        clearTimeout(timer)\n        if (inFlight.get(key) === request) inFlight.delete(key)\n      }\n    })()\n  })\n\n  return () => {\n    disposed = true\n    removeResetObserver()\n    for (const request of inFlight.values()) {\n      clearRepair(request.sbn, request.packetId, request.catalogTrackName)\n      request.controller.abort()\n    }\n    inFlight.clear()\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}