@blockcast/mmt-container 0.1.0 → 0.3.0-main.d9354616fdf2

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": ";AAwFO,SAAS,4BAA2D;AAG1E,QAAM,IAAI;AACV,QAAM,MAAM,EAAE,4BAA4B;AAC1C,MAAI,QAAQ,UAAa,QAAQ,KAAM,QAAO;AAC9C,MAAI,OAAO,QAAQ,UAAU;AAC5B,YAAQ,KAAK,4DAA4D;AACzE,WAAO;AAAA,EACR;AACA,QAAM,MAAM;AACZ,QAAM,SAAS,IAAI,QAAQ;AAC3B,MAAI,CAAC,MAAM,QAAQ,MAAM,GAAG;AAC3B,YAAQ,KAAK,kEAAkE;AAC/E,WAAO;AAAA,EACR;AAGA,QAAM,WAAmC,CAAC;AAC1C,aAAW,KAAK,QAAQ;AACvB,QAAI,OAAO,MAAM,YAAY,MAAM,MAAM;AACxC,YAAM,QAAQ;AACd,UAAI,OAAO,MAAM,MAAM,MAAM,YAAa,MAAM,MAAM,EAAa,SAAS,GAAG;AAC9E,iBAAS,KAAK,KAAwC;AAAA,MACvD;AAAA,IACD;AAAA,EACD;AACA,MAAI,SAAS,WAAW,EAAG,QAAO;AAClC,SAAO;AAAA,IACN,SAAS,OAAO,IAAI,SAAS,MAAM,WAAY,IAAI,SAAS,IAAe;AAAA,IAC3E,iBACC,OAAO,IAAI,iBAAiB,MAAM,WAAY,IAAI,iBAAiB,IAAe;AAAA,IACnF,QAAQ;AAAA,EACT;AACD;AAuBO,SAAS,gCACf,SACA,UACI;AACJ,MAAI,CAAC,SAAU,QAAO;AAEtB,aAAW,SAAS,SAAS,QAAQ;AAGpC,UAAM,OACL,MAAM,SAAS,WAAW,MAAM,KAAK,WAAW,OAAO,IAAI,UAAU;AAEtE,UAAM,SAAS,SAAS,UAAU,UAAU;AAE5C,UAAM,MACL,QAAQ,MAAM,KAAK,EAAE,YAAY,CAAC,GAAG,UAAU,EAAE;AAClD,UAAM,WAAW,IAAI,WAAW,MAAM,IAAI;AAW1C,UAAM,SAA8B;AAAA,MACnC,GAAI,YAAY,CAAC;AAAA,MACjB,WAAW,UAAU,aAAa,EAAE,MAAM,WAAW;AAAA,MACrD,OAAO,UAAU,SAAS;AAAA,IAC3B;AACA,QAAI,UAAU,cAAc,UAAa,MAAM,cAAc,QAAW;AACvE,aAAO,WAAW,IAAI,MAAM;AAAA,IAC7B;AACA,QAAI,UAAU,QAAQ,UAAa,MAAM,QAAQ,QAAW;AAC3D,aAAO,KAAK,IAAI,MAAM;AAAA,IACvB;AAEA,QAAI,WAAW,MAAM,IAAI,IAAI;AAI7B,IAAC,QAAgB,MAAM,IAAI;AAAA,EAC5B;AACA,SAAO;AACR;AAwBA,SAAS,kBAAkB,OAAiC;AAC3D,SAAO,OAAO,UAAU,YAAY,OAAO,UAAU,KAAK,KAAK,QAAQ;AACxE;AAYO,SAAS,4BACf,QACA,UACkB;AAClB,MAAI,CAAC,SAAU,QAAO;AAEtB,QAAM,SAAS,oBAAI,IAA2B;AAC9C,aAAW,KAAK,QAAQ;AACvB,QAAI,OAAO,GAAG,SAAS,SAAU,QAAO,IAAI,EAAE,MAAM,CAAC;AAAA,EACtD;AAIA,QAAM,mBAAmB,SAAS;AAClC,QAAM,qBAAqB,OAAO;AAAA,IACjC,CAAC,MAAM,EAAE,SAAS,WAAW,OAAO,EAAE,UAAU,YAAa,EAAE,MAAiB,SAAS;AAAA,EAC1F;AACA,QAAM,qBAAqB,OAAO;AAAA,IACjC,CAAC,MAAM,EAAE,SAAS,WAAW,OAAO,EAAE,UAAU,YAAa,EAAE,MAAiB,SAAS;AAAA,EAC1F;AAEA,aAAW,MAAM,SAAS,QAAQ;AACjC,UAAM,WAAW,OAAO,IAAI,GAAG,IAAI;AACnC,QAAI,aAAa,QAAW;AAK3B,UAAI,SAAS,QAAQ,UAAa,GAAG,QAAQ,OAAW,UAAS,MAAM,GAAG;AAC1E,UAAI,SAAS,cAAc,UAAa,GAAG,cAAc,QAAW;AACnE,iBAAS,YAAY,GAAG;AAAA,MACzB;AACA,UAAI,GAAG,SAAS,UAAa,SAAS,SAAS,OAAW,UAAS,OAAO,GAAG;AAC7E,UAAI,SAAS,cAAc,QAAQ;AAClC,cAAM,OAAO,SAAS,YAAY,GAAG;AACrC,YAAI,SAAS,SAAS,SAAS,OAAO;AACrC,gBAAM,IAAI;AAAA,YACT,qCAAqC,GAAG,IAAI;AAAA,UAC7C;AAAA,QACD;AACA,iBAAS,WAAW;AACpB,YAAI,SAAS,cAAc,UAAa,GAAG,cAAc,OAAW,UAAS,YAAY,GAAG;AAC5F,YAAI,SAAS,oBAAoB,UAAa,GAAG,oBAAoB,QAAW;AAC/E,mBAAS,kBAAkB,GAAG;AAAA,QAC/B;AACA,YAAI,CAAC,kBAAkB,SAAS,SAAS,GAAG;AAC3C,gBAAM,IAAI;AAAA,YACT,qCAAqC,GAAG,IAAI;AAAA,UAC7C;AAAA,QACD;AACA,YAAI,CAAC,kBAAkB,SAAS,eAAe,GAAG;AACjD,gBAAM,IAAI;AAAA,YACT,qCAAqC,GAAG,IAAI;AAAA,UAC7C;AAAA,QACD;AAAA,MACD;AAAA,IACD,OAAO;AACN,YAAM,YAAY,GAAG,aAAa;AAClC,UAAI,OAAO,cAAc,YAAY,UAAU,WAAW,GAAG;AAC5D,cAAM,IAAI;AAAA,UACT,qCAAqC,GAAG,IAAI;AAAA,QAC7C;AAAA,MACD;AAGA,YAAM,OAAO,GAAG,SAAS,GAAG,KAAK,SAAS,SAAS,IAAI,SAAY;AACnE,YAAM,iBACL,SAAS,UAAU,oBAAoB,QAAQ,oBAAoB;AACpE,YAAM,QAAQ,GAAG,SAAS;AAC1B,UAAI,cAAc,eAAe,OAAO,UAAU,YAAY,MAAM,WAAW,IAAI;AAClF,cAAM,IAAI;AAAA,UACT,qCAAqC,GAAG,IAAI,8BAA8B,SAAS,oEAA+D,QAAQ,OAAO;AAAA,QAClK;AAAA,MACD;AACA,YAAM,WAAW,GAAG;AACpB,UAAI,cAAc,UAAU,aAAa,SAAS,aAAa,OAAO;AACrE,cAAM,IAAI;AAAA,UACT,qCAAqC,GAAG,IAAI;AAAA,QAC7C;AAAA,MACD;AACA,UAAI,cAAc,UAAU,CAAC,kBAAkB,GAAG,SAAS,GAAG;AAC7D,cAAM,IAAI;AAAA,UACT,qCAAqC,GAAG,IAAI;AAAA,QAC7C;AAAA,MACD;AACA,UAAI,cAAc,UAAU,CAAC,kBAAkB,GAAG,eAAe,GAAG;AACnE,cAAM,IAAI;AAAA,UACT,qCAAqC,GAAG,IAAI;AAAA,QAC7C;AAAA,MACD;AACA,YAAM,QAAuB;AAAA,QAC5B,MAAM,GAAG;AAAA,QACT;AAAA,QACA;AAAA,MACD;AACA,UAAI,aAAa,OAAW,OAAM,WAAW;AAC7C,UAAI,GAAG,cAAc,OAAW,OAAM,YAAY,GAAG;AACrD,UAAI,GAAG,oBAAoB,OAAW,OAAM,kBAAkB,GAAG;AACjE,UAAI,SAAS,OAAW,OAAM,OAAO;AACrC,UAAI,GAAG,cAAc,OAAW,OAAM,YAAY,GAAG;AACrD,UAAI,GAAG,QAAQ,OAAW,OAAM,MAAM,GAAG;AACzC,aAAO,KAAK,KAAK;AACjB,aAAO,IAAI,GAAG,MAAM,KAAK;AAAA,IAC1B;AAAA,EACD;AACA,SAAO;AACR;",
+  "names": []
+}

package/dist/repair-fetch.d.ts

@@ -0,0 +1,270 @@
+/**
+ * D-28 shared repair-fetch scheduler.
+ *
+ * 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,
+ * keyframe-first admission, preemption, feeding symbols, and in-flight slot
+ * release — is identical across players and lives here. The Player owns the
+ * scheduler: one per `wireRepairFetch` call, and its disposer aborts
+ * everything.
+ *
+ * Priority (from the block's class, see `repairPriorityForClass`):
+ *   - P0 (keyframe / unknown) and P1 (audio) dispatch as soon as they are
+ *     enqueued, with no cap. Each has its own fail deadline, and a cap would
+ *     turn a recoverable protected block into a stall; their number is
+ *     already bounded by the blocks one fail window can hold.
+ *   - P2 (delta) dispatches only while no P0/P1 is queued or in flight,
+ *     earliest absolute fail deadline first. Enqueuing a P0/P1 aborts every
+ *     in-flight P2 (`repair-preempted`), which returns to the queue while its
+ *     block is unresolved. A P2 that never ran before its block resolved is
+ *     reported as `repair-deferred`.
+ *   - A block reclassified to a higher class while its P2 fetch is in flight
+ *     is re-issued at once under the new class's wire priority: the running
+ *     FETCH is aborted (FETCH_CANCEL) and a new one sent.
+ *
+ * Wire priority (draft-ramadan-moq-fec §11.4.5): every request carries the
+ * MoQ Transport SUBSCRIBER_PRIORITY its FETCH must use, derived from the two
+ * catalog priorities `ResolveRepairTarget` returns (see
+ * `repairFetchSubscriberPriority`): a keyframe-bearing (or unknown) block's
+ * FETCH is sent in the Source Media range at no more than the source
+ * track's priority, so it is delivered ahead of every repair track and not
+ * shed with repair data; a delta or audio FETCH is sent at no less than the
+ * fetched repair track's priority, so it is shed first.
+ *
+ * Deadline and admission (BLO-35597): a repair FETCH rides the reliable path,
+ * so its deadline is the block's PRESENTATION deadline, not the multicast
+ * reassembly deadline. The player states how long after a block's first
+ * symbol its media can still be presented (`presentationDelayMs`); from the
+ * block's receiver-local anchor that gives an absolute deadline, never earlier
+ * than the multicast wait and never later than the release gate's hold ceiling
+ * (`terminalRetentionMsForPacket`), which bounds how long any successor frame
+ * may wait behind the block. A FETCH is sent only when the measured
+ * reliable-path RTT (`reliableRttMs`) is less than the time left to that
+ * deadline -- a request that cannot come back in time is never sent, rather
+ * than sent and cancelled -- and an admitted FETCH holds the block open to
+ * that deadline, so the multicast span elapsing never aborts it.
+ *
+ * The scheduler arms no timers. A fetch ends when its transport completes or
+ * throws, when it is preempted, when any later scheduling event finds it past
+ * its presentation deadline, when its block resolves (recovered, or failed at
+ * that deadline), on track reset, or on dispose.
+ */
+import type { FecBlockProfile } from '@blockcast/mmt-base';
+import { type BlockClass } from './block-policy.js';
+import type { RepairLifecycleObserver } from './multicast-manager.js';
+/**
+ * The highest value in the Source Media priority range of
+ * draft-ramadan-moq-fec §10 (64..191): one below the repair range, which
+ * starts at `REPAIR_PRIORITY_MIN` (192).
+ */
+export declare const SOURCE_MEDIA_PRIORITY_MAX: number;
+/** What `ResolveRepairTarget` returns for one repair-bearing stream. */
+export interface RepairTarget {
+    /** The repair track to FETCH (base layer 0 of the block's source). */
+    readonly repairTrack: string;
+    /**
+     * The catalog `priority` of the SOURCE track the block belongs to, on the
+     * MoQ Transport scale (0..255, lower first), or null when the catalog
+     * carries none. Never a player constant: a keyframe repair must not be
+     * delivered behind the source it repairs, and only the catalog says what
+     * that source's priority is.
+     */
+    readonly sourcePriority: number | null;
+    /**
+     * The catalog priority of `repairTrack` (MoQ Transport scale). Layer 0
+     * that declares none has the value draft-ramadan-moq-fec §10 defines
+     * (240); `resolveRepairLayers` / `catalogRepairTarget` already apply it.
+     * Null only when the resolver cannot read the repair track's entry.
+     */
+    readonly repairPriority: number | null;
+}
+/** Resolve a packetId to its repair track and priorities 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.
+ *  `catalogRepairTarget` builds the answer from a catalog. */
+export type ResolveRepairTarget = (packetId: number, catalogTrackName?: string) => RepairTarget | null;
+/** One on-demand repair FETCH, as the scheduler hands it to the transport. */
+export interface RepairFetchRequest {
+    /** Repair track whose block `sbn` is fetched. */
+    readonly repairTrack: string;
+    /**
+     * The block's key, by `blockProfile` (BLO-35597 D2a):
+     * - `k-padded-v1`: the source block number, which IS the repair-track MoQ
+     *   group id (fetch `[sbn, sbn]`).
+     * - `iso-ssbg1-v1`: the block's 32-bit SS_Start. The MoQ group id is the
+     *   62-bit `extSsStart(wrapEpoch, sbn)`; a receiver that knows only a lost
+     *   SS_ID fetches `repairFetchRange(lostSsId, kMax, anchor)`, where `anchor`
+     *   is `{ previousBlockStart }` (the extended start of the last block
+     *   delimited before it) or `{ reference }` (an epoch reference). Never use
+     *   it as a group id directly.
+     */
+    readonly sbn: number;
+    /** The block profile `sbn` is keyed by (the catalog `fec.blockProfile`). */
+    readonly blockProfile: FecBlockProfile;
+    /** The source packetId the block belongs to. */
+    readonly packetId: number;
+    /**
+     * Aborts when the scheduler no longer wants the group: preemption by
+     * keyframe work, reprioritisation, block resolution, track reset, dispose.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * The SUBSCRIBER_PRIORITY parameter the FETCH MUST carry, on the MoQ
+     * Transport scale (0..255, lower delivered first), as
+     * draft-ramadan-moq-fec §11.4.5 requires. `undefined` means OMIT the
+     * parameter: the catalog carries no priority to derive it from, and the
+     * publisher then uses the value draft-ietf-moq-transport-16 §9.2.2.3
+     * defines for an omitted parameter (128, inside the Source Media range).
+     * A transport never substitutes a value of its own. A transport whose API
+     * uses another scale (moq-lite's higher-wins weight, say) maps this one
+     * without reordering it against the source and repair subscriptions.
+     */
+    readonly subscriberPriority: number | undefined;
+}
+/** 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.
+ *
+ *  Put `request.subscriberPriority` on the FETCH (see RepairFetchRequest).
+ *
+ *  When `request.signal` aborts, the transport MUST cancel the FETCH ON THE
+ *  WIRE, not merely stop reading: send FETCH_CANCEL for its Request ID
+ *  (draft-ietf-moq-transport-16 §9.18; STOP_SENDING on an open data stream
+ *  as well, §5.2), and do it from the abort handler itself, before it
+ *  returns. A relay that is never told keeps sending the group, so a
+ *  preempted delta repair keeps competing with the keyframe repair that
+ *  preempted it. The scheduler may issue the next request for the same block
+ *  (reprioritisation) as soon as it aborts one, and §11.4.5 allows at most
+ *  one repair FETCH outstanding per block and repair layer, so the cancel
+ *  must already be queued ahead of that request. A FETCH whose Request ID
+ *  is not known yet is cancelled as soon as FETCH_OK assigns it. */
+export type RepairFetchTransport = (request: RepairFetchRequest) => AsyncIterable<Uint8Array>;
+/** Why a request could not carry a catalog-derived priority. */
+export type RepairPriorityReason = 'source-priority-absent' | 'source-priority-invalid' | 'repair-priority-absent' | 'repair-priority-invalid';
+/**
+ * The wire priority of one repair request (draft-ramadan-moq-fec §11.4.5).
+ *
+ * - `carry`: send the FETCH with `subscriberPriority`.
+ * - `omit`: send it without SUBSCRIBER_PRIORITY. Only a keyframe-bearing or
+ *   unknown block's request is ever sent this way: the publisher then uses
+ *   128 (draft-ietf-moq-transport-16 §9.2.2.3), which lies in the Source
+ *   Media range, and without a catalog source priority there is no bound
+ *   below it to honour.
+ * - `decline`: send no FETCH. A delta or audio FETCH MUST carry a priority
+ *   at least its repair track's, so at least 192, and the omitted value (128)
+ *   would put best-effort repair ahead of every repair track. Unicast repair
+ *   is optional for those classes (§11.4.3, §11.4.4); in-band FEC and
+ *   concealment still apply.
+ */
+export type RepairFetchPriority = {
+    readonly kind: 'carry';
+    readonly subscriberPriority: number;
+} | {
+    readonly kind: 'omit';
+    readonly reason: RepairPriorityReason;
+} | {
+    readonly kind: 'decline';
+    readonly reason: RepairPriorityReason;
+};
+/**
+ * Derive the SUBSCRIBER_PRIORITY of a repair FETCH from the block's class and
+ * the catalog priorities of its source and repair tracks
+ * (draft-ramadan-moq-fec §11.4.5 and the §10 ranges):
+ *
+ * - keyframe / unknown: in the Source Media range and no greater than the
+ *   source track's priority, i.e. min(source, 191); omitted when the catalog
+ *   carries no source priority.
+ * - delta / audio: no lower than the fetched repair track's priority and at
+ *   least 192, i.e. max(repair, 192); declined when it carries none.
+ */
+export declare function repairFetchSubscriberPriority(blockClass: BlockClass, target: Pick<RepairTarget, 'sourcePriority' | 'repairPriority'>): RepairFetchPriority;
+export interface WireRepairFetchOptions {
+    resolveTarget: ResolveRepairTarget;
+    transport: RepairFetchTransport;
+    /**
+     * Maximum transport attempts per block (required). A retry happens only
+     * when the transport rejects with an error `shouldRetry` classifies as
+     * retryable, before any symbol was fed, while the block's deadline remains.
+     */
+    attemptLimit: number;
+    /** Classify a transport error as a transient publisher/relay retention race. */
+    shouldRetry?: (error: unknown) => boolean;
+    /**
+     * The measured round-trip time of the reliable path the transport fetches
+     * over, in ms (required). Read at every admission, so it tracks the live
+     * session. A value that is not finite and positive, or a throw, means the
+     * path offers no measurement: nothing can show the FETCH would come back in
+     * time, so none is sent (`rtt-unmeasured`). Never a default.
+     */
+    reliableRttMs: () => number;
+    /**
+     * How long after a block's first symbol arrived its media can still be
+     * presented, in ms (required): the player's own playout budget for the
+     * stream. Same fail-closed rule as `reliableRttMs`
+     * (`presentation-delay-unavailable`).
+     */
+    presentationDelayMs: (packetId: number, catalogTrackName?: string) => number;
+}
+/** Why the D-28 layer asked for a repair: the block's class at its deadline. */
+export type RepairSubscribeCallback = (sbn: number, packetId: number, catalogTrackName: string | undefined, blockClass: BlockClass) => void;
+/** Why the scheduler sent no FETCH for a block it was asked to repair. */
+export type RepairSkipReason = 
+/** The reliable path offered no RTT measurement; arrival cannot be shown. */
+'rtt-unmeasured'
+/** The measured RTT is not less than the time left to the deadline. */
+ | 'rtt-exceeds-budget'
+/** The player gave no usable presentation delay for the block's stream. */
+ | 'presentation-delay-unavailable';
+/** The subset of MulticastManager the scheduler drives. */
+export interface RepairFetchHost {
+    readonly fecManager: {
+        blockProfileForPacket(packetId: number): FecBlockProfile | undefined;
+        repairFetchTimeoutMsForBlock(sbn: number, packetId: number, catalogTrackName?: string): number;
+        /** Receiver-local time of the block's first accepted symbol, if any. */
+        blockAnchorAtMs(sbn: number, packetId: number, catalogTrackName?: string): number | undefined;
+        /** How long a terminal block stays authoritative: the release-gate hold ceiling. */
+        terminalRetentionMsForPacket(packetId: number): number;
+        /** Keep the block open to `untilAtMs` for an admitted FETCH. */
+        holdBlockForRepair(sbn: number, packetId: number, catalogTrackName: string | undefined, untilAtMs: number): boolean;
+        /** The admitted FETCH ended without delivering: back to the multicast wait. */
+        releaseRepairHold(sbn: number, packetId: number, catalogTrackName?: string): void;
+    };
+    onRepairSubscribe(cb: RepairSubscribeCallback): void;
+    addRepairLifecycleObserver(observer: RepairLifecycleObserver): () => void;
+    addTrackResetObserver(observer: (packetId: number, catalogTrackName: string) => void): () => void;
+    clearRepairForBlock(sbn: number, packetId: number, catalogTrackName?: string): void;
+    processRepairFromMoQ(packet: Uint8Array, ownerPacketId?: number, catalogTrackName?: string): void;
+    noteRepairScheduling(type: 'repair-preempted' | 'repair-deferred', sbn: number, packetId: number, catalogTrackName?: string): void;
+    /** A request whose wire priority the catalog could not supply. */
+    noteRepairPriority(action: 'omitted' | 'declined', reason: RepairPriorityReason, blockClass: BlockClass, sbn: number, packetId: number, catalogTrackName?: string): void;
+    /** A request the scheduler did not send (see RepairSkipReason). */
+    noteRepairSkipped(reason: RepairSkipReason, measurement: {
+        readonly rttMs: number | null;
+        readonly budgetMs: number;
+    }, sbn: number, packetId: number, catalogTrackName?: string): void;
+}
+/**
+ * Wire the D-28 repair-fetch scheduler 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: RepairFetchHost, 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAA0B,KAAK,UAAU,EAAuB,MAAM,mBAAmB,CAAA;AAChG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAMrE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAA0B,CAAA;AAEhE,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC;AAED;;;;;;;8DAO8D;AAC9D,MAAM,MAAM,mBAAmB,GAAG,CAChC,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,KACtB,YAAY,GAAG,IAAI,CAAA;AAExB,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAA;IACtC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAA;CAChD;AAED;;;;;;;;;;;;;;;;;oEAiBoE;AACpE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,aAAa,CAAC,UAAU,CAAC,CAAA;AAE7F,gEAAgE;AAChE,MAAM,MAAM,oBAAoB,GAC5B,wBAAwB,GACxB,yBAAyB,GACzB,wBAAwB,GACxB,yBAAyB,CAAA;AAE7B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,CAAA;AAMvE;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,gBAAgB,GAAG,gBAAgB,CAAC,GAC9D,mBAAmB,CAWrB;AAED,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,mBAAmB,CAAA;IAClC,SAAS,EAAE,oBAAoB,CAAA;IAC/B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;IACzC;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAC7E;AAED,gFAAgF;AAChF,MAAM,MAAM,uBAAuB,GAAG,CACpC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,UAAU,EAAE,UAAU,KACnB,IAAI,CAAA;AAET,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB;AAC1B,6EAA6E;AAC3E,gBAAgB;AAClB,uEAAuE;GACrE,oBAAoB;AACtB,2EAA2E;GACzE,gCAAgC,CAAA;AAEpC,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE;QACnB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAA;QACpE,4BAA4B,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;QAC9F,wEAAwE;QACxE,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;QAC7F,oFAAoF;QACpF,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;QACtD,gEAAgE;QAChE,kBAAkB,CAChB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAA;QACV,+EAA+E;QAC/E,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAClF,CAAA;IACD,iBAAiB,CAAC,EAAE,EAAE,uBAAuB,GAAG,IAAI,CAAA;IACpD,0BAA0B,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,IAAI,CAAA;IACzE,qBAAqB,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACjG,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnF,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjG,oBAAoB,CAClB,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,EAC5C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,GACxB,IAAI,CAAA;IACP,kEAAkE;IAClE,kBAAkB,CAChB,MAAM,EAAE,SAAS,GAAG,UAAU,EAC9B,MAAM,EAAE,oBAAoB,EAC5B,UAAU,EAAE,UAAU,EACtB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,GACxB,IAAI,CAAA;IACP,mEAAmE;IACnE,iBAAiB,CACf,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EACzE,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,GACxB,IAAI,CAAA;CACR;AAgCD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,sBAAsB,GAAG,MAAM,IAAI,CA2Z7F"}