@blockcast/mmt-container 0.3.0 → 0.4.0-main.1e94b11199ea

package/README.md

@@ -180,12 +180,13 @@ type FecAlgorithm = "none" | "raptorq" | "reed-solomon"
 
 interface FecCatalogConfig {
   algorithm: FecAlgorithm        // §3.1
-  sourceSymbols: number          // K (REQUIRED)
+  blockProfile?: "iso-ssbg1-v1"  // REQUIRED unless algorithm is "none"; never defaulted (BLO-35597)
+  sourceSymbols: number          // K (REQUIRED): K_max, the largest SSB_length of any block
   repairSymbols: number          // P (REQUIRED)
   symbolSize: number             // T, 8-byte aligned (REQUIRED)
   interleaveDepthMs?: number     // FEC block span in MILLISECONDS, default 0 (single-group blocks)
   repairTrack: string            // §6.1 — required
-  mode?: "interleaved" | "object"
+  mode?: "interleaved" | "object"  // extension; "object" (per-frame object blocks) is retired: @blockcast/mmt-fec refuses it
   uep?: { keyRatio: number; deltaRatio: number }   // §9.1 — Unequal Error Protection
   deltaFailWindowBlocks?: number                   // D-11, base track only
   deltaProbeIntervalMs?: number                    // D-13, base track only
@@ -197,15 +198,14 @@ interface MulticastEndpoint {
   groupAddress: string
   port: number
   tracks: string[]
-  // relayAddress?: string — deprecated, read-only (see Breaking, below)
 }
 
 // Relay/tuning discovery is catalog-level, not per-endpoint:
 //   multicast.networkSource: [{ type: "amt", discovery: "driad" | "manual",
 //                               relay?: string, port?: number }]
 // `relay` is REQUIRED for discovery: "manual"; "driad" resolves it at runtime.
-// An endpoint-level `relayAddress` is retired — the schema and moq-rs both
-// reject it.
+// An endpoint-level `relayAddress` is retired — the schema, moq-rs and
+// `validateCmsfMmtpCatalog` (`multicast_relay_address`) all reject it.
 
 interface TrackTimingConfig {
   groupDurationMs: number          // REQUIRED, positive integer
@@ -227,9 +227,14 @@ multicast catalog omits `networkSource` entirely (BLO-37926). A reader that
 still looks for `relayAddress` or `amtFallback` reads `undefined`: read
 `networkSource` instead (`catalogAmtNetworkSource` in `./catalog-network-source`
 resolves a dialable AMT relay from it, skipping `discovery: "driad"` entries
-whose `relay` is a DNS name for a runtime lookup rather than an address), and
-keep accepting `relayAddress` from catalogs published before this change until
-every emitter is on it.
+whose `relay` is a DNS name for a runtime lookup rather than an address).
+
+#### Breaking: endpoint `relayAddress` is rejected on read
+
+`validateCmsfMmtpCatalog` now throws `CmsfCatalogValidationError` with code
+`multicast_relay_address` for a catalog carrying `endpoints[].relayAddress`,
+and `MulticastEndpointConfig.relayAddress` is gone: `MulticastManager.join`
+takes its relay only from `amtRelay` / `amtRelayPort`.
 
 Inputs are unchanged: `relayAddress` and `amtFallback` are still accepted and
 lifted. An input relay that would not survive into the emitted `networkSource`
@@ -292,7 +297,8 @@ Codec-agnostic FEC decode service. Owns per-track decoder instances (sync WASM v
 
 ```ts
 interface FECManagerConfig {
-  k?: number
+  blockProfile?: FecBlockProfile // "iso-ssbg1-v1"; required for every FEC track, validated with parseFecBlockProfile
+  k?: number              // K_max (largest SSB_length), never a block stride
   symbolSize?: number     // T (bytes per symbol). NOT repair count.
   interleaveDepthMs?: number // FEC block span in MILLISECONDS — see MIN_INTERLEAVE_DEPTH_MS in fec-manager.ts
   fps?: number
@@ -314,6 +320,15 @@ class FECManager {
 
 `FECManager.configure()` takes `symbolSize` (bytes per symbol, T). Repair count is a distinct parameter and must never be passed in its place.
 
+FEC blocks follow one block profile, `iso-ssbg1-v1` (ISO/IEC 23008-1 Annex C ssbg_mode1, BLO-35597):
+
+- A source symbol is `u16 length || packet || 00h` padding to T.
+- A block is K' = SSB_length symbols keyed by its 32-bit SS_Start, and SS_ID increments by one per FEC source packet, wrapping at 2^32 (RFC 1982 serial arithmetic). Blocks are variable-length (SSB_length ≤ K), so K is an upper bound and never a stride: no block number is computed from an SS_ID.
+- A source symbol is placed in a block only once a repair symbol states that block's (SS_Start, SSB_length); until then it is held. Repair ESI = SSB_length + RS_ID.
+- The `sbn` in `getBlockStates()`, the block callbacks, and `RepairFetchRequest` is that SS_Start block key (the name is historical). The MoQ repair group id is the 62-bit wrap-epoch-extended SS_Start (`extSsStart` in `@blockcast/mmt-fec`), never the 32-bit key itself.
+
+`blockProfile` is never defaulted and never inferred from the wire. The retired Blockcast-private token `k-padded-v1` (zero-padded K-symbol blocks) is refused wherever a profile is read: `parseFecBlockProfile` throws for it (and for an absent token), and `FECManager` track configuration, `setupFecWorkerForTrack`, and `wireRepairFetch` all validate through it.
+
 `interleaveDepthMs` is the full FEC block span in **milliseconds** per CARP §5.1, valid range 33 ms (interactive / gaming, `MIN_INTERLEAVE_DEPTH_MS`) to 10 000 ms (broadcast ATSC 3.0). `configure()` warns if a positive value below `MIN_INTERLEAVE_DEPTH_MS` (33) is passed — that is almost certainly a raw frame count, not milliseconds — and such sub-floor values never drive the block timeout (the established timeout is preserved instead of collapsing to ~0).
 
 ### Keyframe-protected repair (`./block-policy`, `./conceal-timeline`)
@@ -325,9 +340,10 @@ Every FEC block still gets in-band FEC decode. On top of that:
   DU-header sample position) against catalog geometry (framerate,
   `interleaveDepthMs`, keyframe interval). Geometry that cannot be derived
   exactly, or any violated invariant, runs the track `all-protected` (every
-  video block `unknown`). Vanished blocks are materialised from SBN evidence.
-  A frame split across ADJACENT blocks (a K-close) is expected; only source
-  packets whose authored order and SBN order disagree (a round-robin
+  video block `unknown`). A block every symbol of which vanished is
+  materialised from the surrounding block evidence. A frame split across
+  ADJACENT blocks (a block closing at K symbols) is expected; only source
+  packets whose authored order and block order disagree (a round-robin
   interleave) trip `block-not-contiguous`. Pass the catalog track name to
   `configureTrackFec(packetId, config, catalogTrackName)` so ABR rungs that
   share a packetId each classify with their own framerate and GOP; a rung on
@@ -336,8 +352,10 @@ Every FEC block still gets in-band FEC decode. On top of that:
   and P1 (`audio`) immediately; P2 (`delta`) only while no P0/P1 is queued or
   in flight, earliest deadline first, preempted by any new P0/P1. No timers.
 - **FETCH priority (draft-ramadan-moq-fec §11.4.5).** The transport gets one
-  `RepairFetchRequest { repairTrack, sbn, packetId, signal,
-  subscriberPriority }` and puts `subscriberPriority` on the FETCH
+  `RepairFetchRequest { repairTrack, sbn, blockProfile, packetId, signal,
+  subscriberPriority }`, FETCHes the block's repair group (MoQ group id
+  `extSsStart(wrapEpoch, sbn)`, never `sbn` itself), and puts
+  `subscriberPriority` on the FETCH
   (`undefined` = omit the parameter; the publisher then uses 128,
   draft-ietf-moq-transport-16 §9.2.2.3). P0 requests carry
   `min(sourcePriority, 191)`; P1/P2 carry `max(repairPriority, 192)`. Both
@@ -415,7 +433,6 @@ Vendor keys emitted (BLO-1044):
 | `x-bc-fec-algo` | FEC config | `none` / `raptorq` / `reed-solomon` |
 | `x-bc-fec-k`, `x-bc-fec-p` | FEC config | source / repair counts |
 | `x-bc-fec-recovery` | `recoveryRate` | Block-level recovery, 4 decimal places |
-| `x-bc-alta-verified`, `x-bc-alta-failures` | ALTA stats | Omitted when ALTA disabled (D-09) |
 | `x-bc-transport` | `TransportSnapshot.transport` | `native` / `amt` / `moq` |
 | `x-bc-multicast-group`, `x-bc-multicast-source`, `x-bc-amt-relay` | endpoint | Omitted when null |
 | `x-bc-play-mode` | Phase 14 D-12 | `full` / `base-only` / `single-track` |
@@ -498,7 +515,7 @@ Roles are required by:
 | `@blockcast/fec-worker` | Web-Worker-hosted FEC client (`FecWorkerClient`, `FecTrackStats`, `FrameMeta`, `FecBlockSnapshot`). Direct dependency. |
 | `@blockcast/mmt-transport` | Higher-level transport manager (MoQ + SSM + AMT + DRIAD). Consumes this package's parser. |
 | `@blockcast/mmt-base` | Canonical MMTP/MPU/MFU, AL-FEC signaling, and payload-boundary parser leaf. Direct dependency. |
-| `@blockcast/mmt-alta-parse` | ALTA sender-authentication trailer parser. Direct dependency. |
+| `@blockcast/mmt-manifest-verify` | Signed per-group manifest verifier (source provenance), run at router admission. Direct dependency. |
 | `@blockcast/mmt-render` | Reference renderer + `AudioRingBuffer` (canonical location). The `audio-ring-buffer` re-export here is deprecated. |
 
 ## Testing