@blockcast/mmt-container 0.3.0 → 0.4.0-main.71d61b2a53f2

package/node_modules/@blockcast/fec-worker/src/shred-worker-client.ts

@@ -1,222 +0,0 @@
-/**
- * @blockcast/fec-worker — Shred Worker Main-Thread Client
- *
- * Thin wrapper over the shred (Reed-Solomon) worker, mirroring
- * {@link FecWorkerClient}'s shape. Spawns one Worker, speaks the
- * {@link ShredWorkerCommand}/{@link ShredWorkerEvent} protocol, and keeps the
- * datagram read loop + wire parse + WASM FEC off the main thread.
- *
- * Typical wiring for a WebTransport datagram source (fully off-thread):
- *
- *   const client = new ShredWorkerClient(new URL("./shred-fec-worker.js", import.meta.url));
- *   client.onRecovered((data, meta) => renderRecoveredSet(data, meta));
- *   client.configure({ maxSlots: 5000, symbolSize: 512, wasmUrl: "/vendor/fec/mmt_wasm.js" });
- *   client.attachStream(wt.datagrams.readable); // transferred; main does no read() per packet
- *
- * For sources that demux on the main thread (moqtail OBJECT_DATAGRAM callback,
- * IWA multicast bridge), push each raw frame with {@link feedShred} instead.
- *
- * {@link feedShred} is a fire-and-forget `postMessage` with no native
- * backpressure, so a consumer that decodes slower than the ingest rate (a
- * backgrounded/throttled tab, WASM RS falling behind a ~4k shred/s feed) would
- * grow the worker's inbound message queue without limit — the queue lives in the
- * renderer process and has been observed to reach multiple GB, GC-thrashing the
- * page into a wedge. The client bounds it with an in-flight window keyed off the
- * worker's own periodic stats heartbeat (no per-frame ack round-trip); see
- * {@link ShredWorkerClientOptions.maxInflight}.
- */
-
-import type {
-	ShredWorkerCommand,
-	ShredWorkerConfig,
-	ShredWorkerEvent,
-	ShredWorkerStats,
-	ShredWorkerErrorCode,
-	RecoveredMeta,
-} from "./shred-worker-types.js";
-
-/** Construction-time options for {@link ShredWorkerClient}. */
-export interface ShredWorkerClientOptions {
-	/**
-	 * Cap on frames posted via {@link ShredWorkerClient.feedShred} but not yet
-	 * drained by the worker, before further frames are dropped ("skip-to-live" at
-	 * the worker boundary). Bounds the worker's inbound message queue — the sole
-	 * unbounded structure on the main-thread-demux (`feedShred`) path.
-	 *
-	 * The drain signal is the worker's periodic `stats` heartbeat: the monotonic
-	 * total of frames it has taken off the queue (`shredsRx + malformed +
-	 * versionMismatch`). No per-frame acknowledgement crosses the boundary, so the
-	 * bound is heartbeat-granular — size it above one heartbeat's worth of ingest
-	 * (default 250ms heartbeat × ~4k frames/s ≈ ~1k frames).
-	 *
-	 * Default {@link DEFAULT_MAX_INFLIGHT} (8192 frames ≈ ~10 MB at ~1.3 KB/frame).
-	 * Set to `0` (or any value `<= 0`) to disable the bound entirely — only do so
-	 * for a source with its own backpressure (e.g. a bounded {@link
-	 * ShredWorkerClient.attachStream} producer). Note the bound assumes `feedShred`
-	 * is the sole ingest path; mixing it with `attachStream` (whose frames also
-	 * advance the heartbeat total) makes the window under-count and benignly
-	 * disables the drop.
-	 */
-	maxInflight?: number;
-}
-
-/** Default {@link ShredWorkerClientOptions.maxInflight} (~10 MB of queued frames). */
-export const DEFAULT_MAX_INFLIGHT = 8192;
-
-export class ShredWorkerClient {
-	readonly #worker: Worker;
-	#onRecovered: ((data: ArrayBuffer, meta: RecoveredMeta) => void) | null = null;
-	#onStats: ((stats: ShredWorkerStats) => void) | null = null;
-	#onError: ((message: string, code?: ShredWorkerErrorCode) => void) | null = null;
-	#disposed = false;
-
-	/** feedShred in-flight backpressure accounting (see ShredWorkerClientOptions.maxInflight). */
-	readonly #maxInflight: number;
-	#sent = 0; // frames posted via feedShred (monotonic)
-	#processed = 0; // worker-consumed total from the last stats heartbeat (monotonic)
-	#droppedBackpressure = 0; // frames dropped by the in-flight guard (monotonic)
-
-	/**
-	 * @param workerOrUrl - A URL (a Worker is created internally, `type: module`)
-	 *   or a pre-created Worker (for testing via constructor injection).
-	 * @param opts - Optional {@link ShredWorkerClientOptions}.
-	 */
-	constructor(workerOrUrl: Worker | URL, opts: ShredWorkerClientOptions = {}) {
-		this.#maxInflight = opts.maxInflight ?? DEFAULT_MAX_INFLIGHT;
-		this.#worker =
-			workerOrUrl instanceof URL
-				? new Worker(workerOrUrl, { type: "module" })
-				: workerOrUrl;
-		this.#worker.onmessage = (e: MessageEvent<ShredWorkerEvent>) =>
-			this.#handleEvent(e.data);
-		this.#worker.onerror = (e) =>
-			this.#onError?.(formatWorkerError(e), "worker-runtime");
-		this.#worker.onmessageerror = () =>
-			this.#onError?.("failed to deserialize worker message", "worker-message");
-	}
-
-	/** Configure the decoder (WASM load + ShredFecBuffer construction happen in the worker). */
-	configure(config: ShredWorkerConfig): void {
-		if (this.#disposed) throw new Error("[ShredWorkerClient] disposed");
-		this.#post({ type: "configure", config });
-	}
-
-	/**
-	 * Hand the worker a stream of raw shred frames to batch-drain. The stream is
-	 * transferred — the caller must not use it afterward. One active stream at a
-	 * time; attaching a new one cancels the previous.
-	 */
-	attachStream(readable: ReadableStream<Uint8Array>): void {
-		if (this.#disposed) return;
-		this.#post({ type: "attachStream", readable }, [readable]);
-	}
-
-	/**
-	 * Feed one already-demuxed raw shred frame. `frame` is transferred zero-copy;
-	 * the caller must not access it afterward.
-	 *
-	 * Dropped (frame NOT transferred, so the caller's buffer stays intact) when the
-	 * in-flight window is full — i.e. the worker is more than `maxInflight` frames
-	 * behind. This is the memory bound: a slow/wedged consumer costs bounded
-	 * skip-to-live drops (see {@link droppedBackpressure}), never an unbounded
-	 * renderer-heap blow-up.
-	 */
-	feedShred(frame: ArrayBuffer): void {
-		if (this.#disposed) return;
-		if (this.#maxInflight > 0 && this.#sent - this.#processed >= this.#maxInflight) {
-			this.#droppedBackpressure++;
-			return;
-		}
-		this.#sent++;
-		this.#post({ type: "feedShred", frame }, [frame]);
-	}
-
-	/** Explicitly drive loss recovery (in addition to the worker's internal timer). */
-	recoverAll(nowMs: number = Date.now()): void {
-		if (this.#disposed) return;
-		this.#post({ type: "recoverAll", nowMs });
-	}
-
-	/** Register callback for recovered/completed FEC sets. `data` is a transferred buffer. */
-	onRecovered(cb: (data: ArrayBuffer, meta: RecoveredMeta) => void): void {
-		this.#onRecovered = cb;
-	}
-
-	/** Register callback for the coalesced stats heartbeat. */
-	onStats(cb: (stats: ShredWorkerStats) => void): void {
-		this.#onStats = cb;
-	}
-
-	/** Register callback for worker errors. */
-	onError(cb: (message: string, code?: ShredWorkerErrorCode) => void): void {
-		this.#onError = cb;
-	}
-
-	/**
-	 * Frames dropped by the in-flight backpressure guard since construction
-	 * (monotonic). Surface this in the UI so sustained loss is visible rather than
-	 * silent — a rising counter means the consumer can't keep pace with ingest.
-	 */
-	get droppedBackpressure(): number {
-		return this.#droppedBackpressure;
-	}
-
-	/**
-	 * Frames posted via {@link feedShred} but not yet reported drained by the
-	 * worker's last stats heartbeat (best-effort, heartbeat-granular; never < 0).
-	 */
-	get inflight(): number {
-		return Math.max(0, this.#sent - this.#processed);
-	}
-
-	/** Dispose the worker. Idempotent. */
-	dispose(): void {
-		if (this.#disposed) return;
-		this.#disposed = true;
-		try {
-			this.#worker.postMessage({ type: "dispose" } satisfies ShredWorkerCommand);
-		} catch {
-			/* worker may already be gone */
-		}
-		this.#worker.terminate();
-	}
-
-	#post(cmd: ShredWorkerCommand, transfer: Transferable[] = []): void {
-		this.#worker.postMessage(cmd, transfer);
-	}
-
-	#handleEvent(event: ShredWorkerEvent): void {
-		switch (event.type) {
-			case "recovered":
-				this.#onRecovered?.(event.data, event.meta);
-				break;
-			case "stats":
-				// The worker's monotonic consumed-frame total is the drain signal for
-				// the feedShred in-flight guard. shredsRx counts only valid frames;
-				// malformed + versionMismatch are consumed off the queue too, so the
-				// sum is the true "frames taken off the queue" and keeps the window
-				// from inflating (and false-dropping) on a malformed/skewed source.
-				this.#processed =
-					event.stats.shredsRx + event.stats.malformed + event.stats.versionMismatch;
-				this.#onStats?.(event.stats);
-				break;
-			case "error":
-				if (event.code) this.#onError?.(event.message, event.code);
-				else this.#onError?.(event.message);
-				break;
-		}
-	}
-}
-
-function formatWorkerError(event: ErrorEvent): string {
-	const parts = ["Worker error"];
-	if (event.message) parts.push(event.message);
-	if (event.filename) {
-		const loc = [event.filename];
-		if (event.lineno) loc.push(String(event.lineno));
-		if (event.colno) loc.push(String(event.colno));
-		parts.push(`at ${loc.join(":")}`);
-	}
-	if (event.error instanceof Error && event.error.stack) parts.push(event.error.stack);
-	return parts.join(": ");
-}

package/node_modules/@blockcast/fec-worker/src/shred-worker-types.ts

@@ -1,209 +0,0 @@
-/**
- * @blockcast/fec-worker — Shred (Reed-Solomon) Worker Protocol
- *
- * A sibling codec to the RaptorQ/MMTP worker (`fec-worker.ts`). Solana-style
- * shred streams carry a different FEC payload identity than MMTP source/repair
- * symbols — a shred is `(slot, fecSetIndex, localIndex, numData, numCoding,
- * isCoding, lastInSet)`, not a flat `ssId` — so they need their own command
- * shape. The transport harness (Worker spawn, onmessage plumbing, zero-copy
- * `toOwnedArrayBuffer` transfers) is shared; the decoder WASM is not.
- *
- * The worker owns the batch-drain: the consumer transfers a WebTransport
- * `datagrams.readable` (or any `ReadableStream<Uint8Array>` of raw shred
- * frames) into the Worker via {@link ShredWorkerCommand} `attachStream`, and
- * the read loop + wire parse + `ShredFecBuffer.add_shred` all run off the main
- * thread. Only recovered FEC sets (and coalesced stats) cross back. A
- * `feedShred` command covers sources that have already demuxed the shred bytes
- * on the main thread (e.g. a moqtail OBJECT_DATAGRAM callback, or the IWA
- * multicast bridge).
- *
- * Types here are importable from both main thread and Worker contexts.
- */
-
-// --- Wire format ------------------------------------------------------------
-
-/**
- * Wire header layout the worker parses. Mirrors the deployed shred player's
- * `onShredBytes` exactly (libmmt shred-forwarder `emit_frame`) so the off-thread
- * path is bit-identical to the proven on-thread path.
- *
- * v3 (28-byte header):
- *   [0]      version       u8   (3 or 4; any other version is dropped, not misframed)
- *   [1-8]    slot          u64 LE
- *   [9-12]   fecSetIndex   u32 LE
- *   [13-16]  localIndex    u32 LE   (data: 0..numData; coding: numData+position)
- *   [17]     flags         u8       (bit0 = DATA_COMPLETE, bit1 = IS_CODING_SHRED)
- *   [18]     numData       u8       (coding shreds only; 0 on data — WASM infers)
- *   [19]     numCoding     u8       (coding shreds only; 0 on data)
- *   [20-27]  sendTsUs      u64 LE   (µs since epoch, 0 when unstamped)
- *   [28+]    erasureShard           (equal length across the FEC set)
- *
- * DATA_COMPLETE (last data shred in the set) is passed to `add_shred` as its
- * `lastInSet` argument — the WASM uses it to infer numData for a set that
- * received only data shreds (no coding).
- *
- * v4 has the same 28-byte header, but its body is the full canonical Agave
- * shred (signature, headers, erasure shard, chained Merkle root, proof, and
- * the retransmitter signature on resigned variants) — the form a validator TVU
- * accepts (BLO-41383). The worker recovers the exact v3 erasure-shard view
- * from it with the forwarder's own `erasure_shard()` slice, so both versions
- * reach `add_shred` byte-identical:
- *   variant      = shred[64]; data 0x9_/0xb_, coding 0x6_/0x7_ (chained merkle;
- *                  0xb_/0x7_ resigned), must agree with IS_CODING_SHRED
- *   length       = 1203 (data) / 1228 (coding), exactly
- *   shard start  = 64 (data: after the signature) / 89 (coding headers)
- *   shard end    = length - (32 root + 20 * (variant & 0x0f) proof
- *                            + 64 retransmitter signature if resigned)
- */
-export const SHRED_WIRE_VERSION = 3;
-/** Wire version whose body is the full canonical shred (see above). */
-export const SHRED_WIRE_VERSION_FULL = 4;
-export const SHRED_HEADER_LEN = 28;
-export const SHRED_FLAG_DATA_COMPLETE = 0x01;
-export const SHRED_FLAG_IS_CODING = 0x02;
-
-// --- Config -----------------------------------------------------------------
-
-/** Per-decoder configuration for the shred FEC worker. */
-export interface ShredWorkerConfig {
-	/** Ring capacity in slots (matches `new ShredFecBuffer(maxSlots, symbolSize)`). */
-	maxSlots: number;
-	/** Symbol size in bytes (Solana shred payloads are fixed-size within a set). */
-	symbolSize: number;
-	/**
-	 * Module URL for the shred WASM (wasm-bindgen ESM exporting `default` init +
-	 * `ShredFecBuffer`). The worker `import()`s it and calls `await default()`.
-	 * Ignored when `self.__SHRED_WASM_BINDINGS__` is pre-injected (tests / custom
-	 * loaders), mirroring the RaptorQ worker's `__MMT_WASM_BINDINGS__` contract.
-	 */
-	wasmUrl?: string;
-	/**
-	 * How often (ms) the worker coalesces and posts a `stats` event. The read
-	 * loop never posts per-shred; only recovered frames and this heartbeat cross
-	 * the boundary. Default 250ms.
-	 */
-	statsIntervalMs?: number;
-	/**
-	 * How often (ms) the worker runs `try_recover_all(now)` to drain timed-out
-	 * FEC sets that `add_shred` didn't complete (loss scenarios). Default 50ms,
-	 * matching the player's on-thread recovery timer. Set to 0 to disable (the
-	 * consumer may instead drive it explicitly with `recoverAll`).
-	 */
-	recoverIntervalMs?: number;
-}
-
-// --- Stats ------------------------------------------------------------------
-
-/**
- * First-shred-per-slot sample, collected by the worker and drained into each
- * coalesced `stats` heartbeat. Lets the main thread run app-specific,
- * slot-derived stats (e.g. the turbine-leg latency estimator, per-slot latency
- * percentiles) WITHOUT re-parsing the wire header — the worker stays the single
- * source of truth for parsing, and these cross the boundary aggregated (a
- * handful per heartbeat), never per-packet.
- */
-export interface SlotSample {
-	/** Slot number (first shred of this slot the worker saw). */
-	slot: bigint;
-	/** Publisher send timestamp (µs since epoch) of that first shred, 0 when unstamped. */
-	sendTsUs: bigint;
-	/** Frame byte length of that first shred. */
-	bytes: number;
-}
-
-/** Aggregate shred-decode counters, emitted on the coalesced `stats` heartbeat. */
-export interface ShredWorkerStats {
-	/** Total shred frames parsed (data + coding). */
-	shredsRx: number;
-	/** Data (source) shreds observed. */
-	sourceShreds: number;
-	/** Coding (repair) shreds observed. */
-	repairShreds: number;
-	/** FEC sets completed (direct completion + FEC recovery). */
-	fecSetsCompleted: number;
-	/** Bytes handed back as recovered/completed sets. */
-	bytesReassembled: number;
-	/** Sets recovered specifically via `try_recover_all` (loss recovery). */
-	fecSetsRecovered: number;
-	/** Current `ShredFecBuffer.pending_fec_sets()`, or -1 when unavailable. */
-	pendingFecSets: number;
-	/** Frames dropped for being shorter than the v3 header. */
-	malformed: number;
-	/** Frames dropped for carrying a non-v3 version byte (forwarder/worker skew). */
-	versionMismatch: number;
-	/** Highest slot number observed (as a string — bigint isn't JSON-safe for UI). */
-	currentSlot: string;
-	/** First-shred-per-slot samples parsed since the previous heartbeat (drained each emit). */
-	slotSamples: SlotSample[];
-}
-
-/** Stable identities for worker failures whose message text carries live values. */
-export type ShredWorkerErrorCode =
-	| "wasm-load-failed"
-	| "wasm-bindings-missing"
-	| "not-configured"
-	| "stream-read-failed"
-	| "unknown-command"
-	| "worker-runtime"
-	| "worker-message";
-
-// --- Recovered frame metadata ----------------------------------------------
-
-/** Metadata attached to each recovered set the worker emits. */
-export interface RecoveredMeta {
-	/**
-	 * Slot the recovered set belongs to. Attributed on both the direct-completion
-	 * path and the identity-carrying recovery drain
-	 * (`try_recover_all_with_identity`); only 0n on the legacy `ShredReassembler`
-	 * fallback, which has no identity variant. Do NOT branch on `slot === 0n` as
-	 * "unattributed" — that would drop the majority of recovered sets.
-	 */
-	slot: bigint;
-	/** FEC set index within the slot (0 only on the legacy identity-less fallback). */
-	fecSetIndex: number;
-	/**
-	 * Publisher send timestamp (µs since epoch), 0 when unstamped/unknown. On
-	 * direct completion this is the completing shred's stamp; on the recovery
-	 * drain it is the set's first-seen shred stamp (shreds of a set are sent µs
-	 * apart, so the two are equivalent latency baselines).
-	 */
-	sendTsUs: bigint;
-	/** True when produced by loss recovery (`try_recover_all`) rather than direct completion. */
-	recovered: boolean;
-}
-
-// --- Commands (main -> worker) ----------------------------------------------
-
-/** Discriminated union of all commands sent from the main thread to the shred worker. */
-export type ShredWorkerCommand =
-	| { type: "configure"; config: ShredWorkerConfig }
-	| {
-			/**
-			 * Hand the worker a stream of raw shred frames to batch-drain. Each
-			 * chunk is one wire frame (one WebTransport datagram). The stream is
-			 * transferred (add to the postMessage transfer list) — the main thread
-			 * must not touch it afterward.
-			 */
-			type: "attachStream";
-			readable: ReadableStream<Uint8Array>;
-	  }
-	| {
-			/**
-			 * Feed one already-demuxed raw shred frame. `frame` is transferred
-			 * zero-copy — the caller must not access it after posting. Use this for
-			 * sources whose demux stays on the main thread (moqtail OBJECT_DATAGRAM
-			 * callback, IWA multicast bridge).
-			 */
-			type: "feedShred";
-			frame: ArrayBuffer;
-	  }
-	| { type: "recoverAll"; nowMs: number }
-	| { type: "dispose" };
-
-// --- Events (worker -> main) ------------------------------------------------
-
-/** Discriminated union of all events emitted from the shred worker to the main thread. */
-export type ShredWorkerEvent =
-	| { type: "recovered"; data: ArrayBuffer; meta: RecoveredMeta }
-	| { type: "stats"; stats: ShredWorkerStats }
-	| { type: "error"; message: string; code?: ShredWorkerErrorCode };

package/node_modules/@blockcast/fec-worker/src/transfer.ts

@@ -1,12 +0,0 @@
-/**
- * Return a fresh ArrayBuffer containing exactly the bytes in `view`.
- *
- * Worker outputs must not transfer buffers that might be owned by a WASM
- * binding or by a larger shared packet. A fresh JS-owned buffer gives
- * postMessage() exclusive ownership without detaching unrelated memory.
- */
-export function toOwnedArrayBuffer(view: Uint8Array): ArrayBuffer {
-	const copy = new Uint8Array(view.byteLength);
-	copy.set(view);
-	return copy.buffer;
-}

package/node_modules/@blockcast/mmt-alta-parse/README.md

@@ -1,181 +0,0 @@
-# @blockcast/mmt-alta-parse
-
-Zero-dependency leaf package that extracts the detached **ALTA authenticator trailer** from an MMTP source packet. ALTA (Authenticated Lightweight TESLA-like Algorithm) is Blockcast's sender-authentication scheme for multicast streams: each MMTP source packet carries a detached signature trailer that downstream consumers (the FEC worker, the FFI core) verify against a catalog-published public key. This package is **the parser only** — it locates the trailer, returns the raw authenticator bytes, and tells the caller where the signed payload ends. Signature verification (Ed25519 / P-256) lives in the consumer that has crypto and the public key in hand.
-
-It is split into a leaf package with zero `@blockcast/*` dependencies so both `@blockcast/mmt-container` (wire-path parsing) and `@blockcast/fec-worker` (FEC-recovered-source parsing) can share one implementation without creating a package cycle.
-
-## Install
-
-```bash
-pnpm add @blockcast/mmt-alta-parse
-```
-
-## Quick start
-
-```ts
-import { extractAltaTrailer } from "@blockcast/mmt-alta-parse"
-
-// `wirePacket` is a full MMTP packet as it came off the network (Uint8Array).
-const trailer = extractAltaTrailer(wirePacket)
-
-if (trailer === null) {
-  // Packet has no ALTA trailer. This is normal for:
-  //  - non-MPU packets (repair, signaling)
-  //  - unsigned streams
-  //  - malformed / truncated packets
-  return
-}
-
-// `trailer.auth`        — the authenticator bytes (no ext_type/ext_length prefix)
-// `trailer.signedEnd`   — byte offset where the signed payload ends inside wirePacket.
-//                         The signer signed wirePacket.subarray(0, signedEnd).
-
-const signedPayload = wirePacket.subarray(0, trailer.signedEnd)
-// Hand off to a verifier with the catalog-published public key:
-//   ed25519.verify_detached(trailer.auth, signedPayload, publicKey)
-```
-
-For FEC-recovered source symbols (where the upstream FEC pipeline has already stripped the 4-byte Source FEC Payload ID), pass `{ skipFecId: true }`:
-
-```ts
-const trailer = extractAltaTrailer(recoveredSymbol, { skipFecId: true })
-```
-
-## Exports
-
-Per `package.json` (single entry point, ESM only):
-
-| Export | Kind | Purpose |
-|--------|------|---------|
-| `extractAltaTrailer(packet, options?)` | function | Parse a wire MMTP packet and return its `AltaTrailer` or `null`. |
-| `AltaTrailer` | type | `{ auth: Uint8Array; signedEnd: number }` |
-| `MMTP_EXT_TYPE_ALTA_AUTH` | const `0xf0a1` | The MMTP header-extension `ext_type` assigned to the detached ALTA trailer. |
-| `MMTP_EXT_TRAILER_HEADER_SIZE` | const `4` | Fixed size of the trailer's `[ext_type][ext_length]` prefix (2 + 2 bytes BE). |
-
-The package has no runtime dependencies — `package.json` lists `"dependencies": {}`.
-
-## ALTA wire format
-
-The detached ALTA authenticator is appended **after** the declared MPU payload bytes and **before** the optional 4-byte Source FEC Payload ID. ISO/IEC 23008-1 defines `payload_length` as a length-after-field value: it includes the six MPU-header bytes following the field, the MFU data-unit header when present, and the media bytes. The MMTP header-extension `X` bit stays `0` — non-ALTA receivers treat the trailing bytes as data past `payload_length` and discard them per ISO/IEC 23008-1 §9.2.2 ("may be discarded without impacting correct processing").
-
-Wire layout for a signed source packet:
-
-```
-| MMTP hdr | length (2) | remaining MPU hdr (6) | MFU hdr? | MFU data | TRAILER | SS_ID? (4) |
-             \_______________________________________________________/
-                    payload_length bytes start after the field
-                                                                    ^
-                                                                    |
-                                                               signedEnd
-```
-
-In MPU-payload coordinates, `signedEnd` is exactly `2 + payload_length`; the returned packet-relative offset also includes the complete, possibly extended MMTP header.
-
-The trailer itself is:
-
-```
-| ext_type (2 BE) | ext_length (2 BE) | auth (ext_length bytes) |
-       0xf0a1
-```
-
-- `ext_type = 0xf0a1` identifies the trailer as ALTA. Anything else is rejected (`null` return).
-- `ext_length` is the authenticator length in bytes — 64 for Ed25519, 64 for P-256 raw `(r,s)`, or whatever the signer minted.
-- The signed range is everything from byte 0 through `signedEnd-1` of the wire packet — i.e. the MMTP header, MPU header, MFU header, and MFU payload, but **not** the trailer itself or the optional FEC payload ID.
-
-This is the **detached trailer** form (a.k.a. "Path 2 / 08-07") from `draft-ramadan-moq-mmt` §12. It coexists with FEC: the signer signs the source-packet bytes **before** they enter the FEC encoder, so a receiver that recovers a missing source symbol from repair gets the same signed bytes the sender minted. This is the "sign-before-encode" rule — see the parent monorepo Phase 8 spec.
-
-### When `extractAltaTrailer` returns `null`
-
-The function returns `null` (rather than throwing) for every non-trailer outcome — see `src/index.ts:69-115`:
-
-| Condition | Why |
-|-----------|-----|
-| Packet shorter than `MMTP_HEADER_SIZE + MPU_HEADER_SIZE` (20 B) | Truncated/malformed |
-| Packet type ≠ MPU (`0x00`) | Repair and signaling packets aren't signed per-packet |
-| Fragment type ≠ 2 (MFU) | Only timed or non-timed MFU media packets carry trailers |
-| `payload_length` cannot contain the MPU-header remainder, structurally required DU header, and media | The declaration ends inside headers or describes a header-only MFU |
-| `2 + payload_length` exceeds the pre-FEC packet boundary | Truncated/malformed declaration |
-| No bytes between MFU data and SS_ID for the 4-byte trailer header | Unsigned stream |
-| `ext_type` ≠ `0xf0a1` | Some other header-extension lives in that slot |
-| Declared `ext_length` does not end exactly at the SS_ID boundary | Malformed or ambiguous trailer suffix |
-
-Callers should treat `null` as "no signature on this packet" and route based on stream policy (require-signed vs allow-unsigned).
-
-## Verification flow (where this package fits)
-
-```
-                    catalog (CMSF)
-                          │
-                  alta.publicKey (SPKI bytes)
-                          │
-                          ▼
-   ┌─────────────────────────────────────────────────────┐
-   │ @blockcast/mmt-container :: mmtp-router             │
-   │   wirePacket → extractAltaTrailer(packet) ──────────┼──► this package
-   │                ⇒ { auth, signedEnd }                │
-   │                                                     │
-   │   feedSourceSymbol(..., { auth, payloadEnd: signedEnd })
-   └────────────────────────┬────────────────────────────┘
-                            │
-                            ▼
-   ┌─────────────────────────────────────────────────────┐
-   │ @blockcast/fec-worker (configured with publicKey)│
-   │   ed25519.verify_detached(auth,                     │
-   │                           symbol[0..payloadEnd],    │
-   │                           publicKey)                │
-   │   → emits altaVerified per packet → FecTrackStats   │
-   └─────────────────────────────────────────────────────┘
-```
-
-Concretely, in `packages/container/src/mmtp-router.ts:798`, the router calls `extractAltaTrailer(packet)` for every signed source packet on the wire, packages the result as `{ auth, payloadEnd: signedEnd }`, and hands it to the FEC manager. The FEC worker (configured with `alta.publicKey` from the CMSF catalog at `configure()` time) does the actual Ed25519 / P-256 verification and increments per-track `altaVerified` / `altaFailed` counters in `FecTrackStats`. Those counters surface in CMCD as `x-bc-alta-verified` (see `packages/container/src/cmcd-producer.ts:93`).
-
-## Why not TESLA
-
-TESLA (RFC 4082) is the IETF reference for sender-authenticated multicast: it uses delayed-disclosure of MAC keys to amortize signing cost, but at the protocol level it carries 10–20% authentication overhead per stream (depending on key chain depth and disclosure interval). ALTA is Blockcast's lighter variant — same threat model (verify each packet was minted by the legitimate sender, not a rogue injector on the multicast group), measurably lower overhead (~6.91% in production multicast tests). The parent monorepo's `CLAUDE.md` calls this out at `packages/alta/`. ALTA replaces the v2 stub verifier in v3.0 / Phase 8.
-
-## Relation to DRM
-
-ALTA and DRM solve **different** problems and are orthogonal:
-
-| | ALTA | DRM (Widevine / PlayReady / FairPlay / ClearKey) |
-|---|---|---|
-| Authenticates | the **sender** | the **receiver** |
-| Question | "Did this packet come from the legitimate broadcaster?" | "Is this device authorized to play this content?" |
-| Wire layer | Per-MMTP-packet detached trailer | Sample-level CENC encryption + license server |
-| Catalog field | `alta.publicKey` | `contentProtection[]` (planned in v4 / M7) |
-
-A stream can use both — ALTA on the multicast wire (so receivers reject injected packets), CENC + DRM at the sample level (so unauthorized devices can't play). They don't interact.
-
-## Specifications
-
-- **ISO/IEC 23008-1:2023** §9.2.2 (MMTP packet header), §9.2.3 (MPU/MFU header) — the host packet structure
-- **draft-ramadan-moq-mmt** §12 — detached authenticator trailer ("Path 2 / 08-07") wire format
-- **RFC 8032** — Ed25519 signature algorithm (a typical inhabitant of the trailer)
-- **NIST FIPS 186-4** — ECDSA over P-256 (alternative inhabitant)
-- **RFC 4082** — TESLA (the heavier scheme ALTA replaces; included for context, not a dependency)
-- ATSC A/331 §A — referenced by libmmt for catalog-style key/signaling distribution patterns
-
-This package is agnostic to the signature algorithm — it only carries opaque bytes.
-
-## Related packages
-
-| Package | Role |
-|---------|------|
-| `@blockcast/mmt-container` | Consumes this parser via `mmtp-router.ts`; provides the CMSF catalog that distributes `alta.publicKey` to the FEC worker. |
-| `@blockcast/fec-worker` | Verifier — receives `{ auth, payloadEnd }` and the catalog public key at configure time, performs the actual Ed25519 / P-256 verification, increments `altaVerified` / `altaFailed` in `FecTrackStats`. |
-| `@blockcast/mmt-fec` | Surfaces verification counters to the application via FEC stats snapshots. |
-
-## Testing
-
-```bash
-pnpm test            # vitest run
-pnpm test:watch      # vitest in watch mode
-pnpm typecheck       # tsc --noEmit
-pnpm build           # tsc → dist/
-```
-
-Direct tests in `src/index.test.ts` cover canonical complete/fragmented declarations, ALTA-only and ALTA+FEC suffixes, malformed lengths, and rejection of obsolete boundary conventions. Coverage is also exercised through the re-exported parser in `@blockcast/mmt-container`.
-
-## License
-
-Apache-2.0 — see `LICENSE`.