@blockcast/mmt-container 0.1.0-main.ce3c8aeb7f68 → 0.1.0-main.d0bb31684c09

package/README.md

@@ -65,6 +65,8 @@ The package exposes a wide subpath surface so consumers can tree-shake aggressiv
 | `./loc` | LOC FEC extension headers (`FecSourceInfo`, `AuthTag`) |
 | `./codec-utils` | H.264 helpers — Annex-B ↔ AVCC, SPS/PPS extraction, `mmtpTimestampToMicros`, ADTS wrap |
 | `./fec-manager` | `FECManager` — per-track FEC decoder lifecycle (sync WASM + Worker variants) |
+| `./block-policy` | Keyframe-protected repair policy — `BlockClassifier`, `repairPriorityForClass`, `decideGap` |
+| `./conceal-timeline` | Sink concealment — `videoConcealModeForCodec`, `HoldLastTimeline`, `AudioGapConcealer` |
 | `./mmtp-router` | `MmtpRouter` — packet routing with two-phase FEC feed |
 | `./multicast-transport` | `MulticastTransport` — `window.multicast` gateway `subscribe({ consume: 'bytes' })` wrapper |
 | `./multicast-manager` | `MulticastManager` — backwards-compat facade composing transport + router + FEC |
@@ -82,7 +84,7 @@ The package exposes a wide subpath surface so consumers can tree-shake aggressiv
 | `./phase14-catalog-override` | Test-harness catalog override hook (`globalThis.__PHASE14_CATALOG_OVERRIDE`) |
 | `./align` | Group-id derivation (`groupIdForTicks`, `groupIdFor`, `driftCheck`) — shared with Go sender + Rust relay |
 | `./mmtp-decode-pipeline` | `MmtpDecodePipeline` — unified MoQ + multicast decode path |
-| `./mmtp-to-cmaf` | `MmtpToCmaf` + standalone segment builders (`encodeMultiSampleSegment`, `buildVideoInitSegment`, `generateGreenFillNAL`, `generateSilenceFrame`) |
+| `./mmtp-to-cmaf` | `MmtpToCmaf` + standalone segment builders (`encodeMultiSampleSegment`, `buildVideoInitSegment`, `generateSilenceFrame`) |
 | `./track-pipeline-setup` | `setupTrackPipeline` — shared wiring for both reference players |
 | `./track-session` | `TrackSession` + `SessionManager` — per-track state machine (Patent Claim 9) |
 
@@ -115,7 +117,7 @@ function parseMPUHeader(buf: Uint8Array, offset: number): MPUHeader
 function extractMFUPayload(packet: Uint8Array): MFUExtraction | null
 function extractFecPayloadId(packet: Uint8Array): { ssId: number } | null
 function extractRepairFecPayloadId(packet: Uint8Array): RepairFecId | null
-function parseAlFecMessage(buf: Uint8Array): AlFecConfig
+function parseAlFecMessage(buf: Uint8Array): AlFecMessage | null   // every FEC flow (Table C.3, Amd 1:2025)
 function parseMoqRepairFrame(buf: Uint8Array): MoqRepairFrame
 ```
 
@@ -190,14 +192,21 @@ interface FecCatalogConfig {
 }
 
 interface MulticastEndpoint {
-  protocol: "ssm" | "asm" | "amt"
+  protocol: "ssm" | "asm" | "amt" | "atsc3"
   sourceAddress?: string         // REQUIRED for SSM
   groupAddress: string
   port: number
   tracks: string[]
-  relayAddress?: string          // REQUIRED for AMT
+  // 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.
+
 interface TrackTimingConfig {
   groupDurationMs: number          // REQUIRED, positive integer
   groupDurationTicks?: number      // override when ms × timescale isn't integer
@@ -209,6 +218,45 @@ function resolveGroupDurationTicks(timing: TrackTimingConfig, timescale: number)
 function validateSwitchingSetTiming(...): { ok: true } | { ok: false; ... }
 ```
 
+#### Breaking: multicast emitter output (BLO-37834)
+
+`multicastFromConfig` / `multicastFromEnv` no longer emit
+`endpoints[].relayAddress` or `amtFallback`. Both are lifted into catalog-level
+`multicast.networkSource` (`{type: "amt", discovery, relay?}`), and a native
+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.
+
+Inputs are unchanged: `relayAddress` and `amtFallback` are still accepted and
+lifted. An input relay that would not survive into the emitted `networkSource`
+(two endpoints with different relays, one overridden by
+`amtFallback.relayDns` or an explicit `networkSource`, or one matched only by a
+`discovery: "driad"` entry, whose relay is a runtime discovery hint) now throws
+`conflicting_amt_relay` instead of being dropped. For that last case — wanting
+DRIAD *and* a named relay — emit both entries, `[{type: "amt", discovery:
+"manual", relay}, {type: "amt", discovery: "driad"}]`: readers join the first
+non-DRIAD AMT entry, so the manual one carries the relay while the DRIAD one
+keeps the discovery request. An `atsc3` endpoint now
+requires a `{type: "atsc3", …}` entry and throws `atsc3_requires_tuning`
+without one: that entry carries the frequency, PLP, service id and SLS URI,
+which is the only tuning information an ATSC3 receiver has, and the schema
+cannot enforce it because `networkSource` is optional there (a native join has
+none). `version`, `validUntil` and `enabled` are still emitted and still
+outside `$defs/multicast` (the BLO-3323 freshness model, tracked separately).
+
+`MulticastInputErrorKind` gains two members, `atsc3_requires_tuning` and
+`invalid_endpoints`. The union is exported, so a consumer that `switch`es on it
+exhaustively needs the two new arms to keep compiling.
+
+The package version stays `0.1.0`: consumers pin a libmmt commit (`file:` or the
+per-commit `0.1.0-main.<sha>` prerelease from `stamp-prerelease.mjs`), and a
+`0.2.0` would fall outside the `^0.1.0` range that siblings such as
+`mmt-render` declare.
+
 #### Track-role convention (Phase 14)
 
 This is **project-specific**, not in any IETF draft yet. The container's switching-set parser derives its internal role from the last `/`-segment of a track name. MMTP catalogs may also carry the publisher-owned `trackRole` dispatch tag; the canonical schema validates it as a non-empty string. `parseTrackRole` remains the name-based helper for base/delta/repair switching sets (`carp-catalog.ts:41-79`):
@@ -263,6 +311,47 @@ class FECManager {
 
 `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`)
+
+Every FEC block still gets in-band FEC decode. On top of that:
+
+- **Classification.** Each block is `keyframe | delta | unknown | audio`, from
+  first-arrival network source evidence only (MMTP R bit, MPU number, MFU
+  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
+  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
+  such a packetId without its own geometry runs `stream-geometry-absent`.
+- **Repair priority.** `wireRepairFetch` dispatches P0 (`keyframe`/`unknown`)
+  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
+  (`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
+  priorities come from `ResolveRepairTarget` (`catalogRepairTarget` reads
+  them from a catalog). A missing source priority omits the parameter; a
+  missing repair priority declines the delta/audio FETCH; each emits a
+  `repair-priority` lifecycle event. Abort MUST send FETCH_CANCEL, from the
+  abort handler.
+- **Stall vs conceal.** FEC tracks release frames in authored order; a frame
+  after a gap waits until every block that could hold the missing frames
+  resolved. When media was lost, the frame carries `gapBefore`
+  (`decideGap`): video stalls only when a RAP may be inside the gap; audio
+  never stalls. The same object is the manager's `gap` lifecycle event.
+- **Concealment** is hold-last-good-frame (`HoldLastTimeline`) plus exact
+  audio sizing (`AudioGapConcealer`). No bitstream is ever synthesised.
+
+Typed evidence is `RepairLifecycleEvent` version 2 and
+`MulticastManager.getBlockPolicyStats()`.
+
 This package depends on the FEC primitives from:
 - **`@blockcast/mmt-fec`** — RaptorQ WASM decoder + OTI codec + `computeFecTimeout`
 - **`@blockcast/fec-worker`** — Web Worker host, `FecWorkerClient`, `FecTrackStats`
@@ -293,7 +382,6 @@ Standalone helpers exported from the same module:
 | `encodeMultiSampleSegment(...)` | Multi-sample moof+mdat (one per FEC block — used by `CmafBlockAssembler`) |
 | `buildVideoInitSegment(avcC, w, h)` | ftyp + moov for AVC |
 | `buildAudioInitSegment(sampleRate, channels, asc?, timescale?)` | ftyp + moov for AAC / Opus |
-| `generateGreenFillNAL(avcC, w, h)` | Green-fill NAL when a FEC block fails (loss visible) |
 | `generateSilenceFrame(codec, sampleRate, channels)` | Audio silence frame for FEC-failed audio blocks |
 
 Per-track timestamp rebase (`#videoBaseTs` / `#audioBaseTs` at `mmtp-to-cmaf.ts:550-562`) prevents the negative-uint64 `tfdt` bug that kills Chromium MediaSource (`CHUNK_DEMUXER_ERROR_APPEND_FAILED`).
@@ -322,7 +410,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-scu` | green-fill count | Omitted when 0 |
 | `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 |

package/dist/block-policy.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Keyframe-protected FEC repair policy.
+ *
+ * Every FEC block still gets in-band FEC decode. What this module decides is
+ * (1) which blocks may hold a keyframe (RAP), so a block short of K at its
+ * repair deadline can be repaired over QUIC with the right priority, and
+ * (2) what a sink must do with the first frame released after a gap: stall
+ * until the next RAP, or conceal and keep playing.
+ *
+ * The two decisions are deliberately independent. Classification only sets
+ * repair priority. The stall/conceal decision is made again per released gap
+ * from the media that is actually missing, so a wrong classification can only
+ * lower a block's repair priority; it can never make playback wrong.
+ *
+ * Everything here is derived from catalog-authored timing and in-band MMTP
+ * evidence. There are no timers, no cadence heuristics, and no defaults: a
+ * track whose geometry cannot be derived exactly runs in the defined
+ * fail-closed mode `all-protected`, where every block is treated as possibly
+ * keyframe-bearing.
+ *
+ * All three players (moqtail, hang, Shaka) consume this one implementation.
+ */
+/**
+ * Repair class of one FEC block.
+ *
+ * - `keyframe`: the block holds (or held) a RAP / MPU start.
+ * - `delta`: the block provably holds only non-RAP video frames.
+ * - `unknown`: neither could be proven; treated exactly like `keyframe`.
+ * - `audio`: an audio block.
+ */
+export type BlockClass = 'keyframe' | 'delta' | 'unknown' | 'audio';
+/** Repair priority. Lower is more urgent. */
+export type RepairPriority = 0 | 1 | 2;
+export type TrackKind = 'video' | 'audio';
+/** P0 = keyframe/unknown (stall-preventing), P1 = audio, P2 = delta. */
+export declare function repairPriorityForClass(blockClass: BlockClass): RepairPriority;
+export type ClassifierMode = 'classifying' | 'all-protected';
+/** Why a track runs `all-protected`. */
+export type ClassifierReason = 'framerate-absent' | 'keyframe-cadence-absent' | 'keyframe-interval-not-integral' | 'block-spans-gop'
+/**
+ * The catalog keyframe interval is not an exact integer number of ticks
+ * in the media track's own timescale (ISO-BMFF `mdhd`), so released RAP
+ * spacing cannot be verified and hold-last cannot predict the next RAP.
+ * Nothing is wrong with the stream; the cadence is simply unprovable.
+ */
+ | 'keyframe-interval-not-media-integral'
+/**
+ * Another stream on this packetId was configured with its own geometry
+ * and this one was not, so no geometry provably belongs to it (ABR rungs
+ * sharing a packetId).
+ */
+ | 'stream-geometry-absent' | 'rap-not-mpu-start' | 'mpu-longer-than-gop' | 'block-not-contiguous' | 'rap-spacing-mismatch' | 'mpu-multiple-fragments' | 'block-wider-than-interleave';
+/** Raw catalog timing for one track. Never a resolved cadence. */
+export interface BlockClassifierGeometryInput {
+    readonly trackKind: TrackKind;
+    /** Catalog `framerate` (frames per second). */
+    readonly framerate?: number;
+    /** Catalog `fec.interleaveDepthMs`: the full FEC block span (§5.1). */
+    readonly interleaveDepthMs: number;
+    /** Catalog track `timescale` for `keyframeIntervalTicks`. */
+    readonly timescale?: number;
+    /** Catalog `keyframeIntervalTicks` (preferred when the timescale is present). */
+    readonly keyframeIntervalTicks?: number;
+    /** Catalog `keyframeIntervalMs`. */
+    readonly keyframeIntervalMs?: number;
+}
+/** Exact keyframe interval as a rational number of seconds: ticks / timescale. */
+export interface KeyframeInterval {
+    readonly ticks: number;
+    readonly timescale: number;
+}
+export type BlockClassifierGeometry = {
+    readonly trackKind: 'audio';
+} | {
+    readonly trackKind: 'video';
+    readonly mode: 'classifying';
+    /** F: one frame's duration in milliseconds (1000 / framerate). */
+    readonly frameDurationMs: number;
+    /** D: media units per FEC block (deriveFecInterleaveDepth). */
+    readonly interleaveUnits: number;
+    /** G: frames per GOP. */
+    readonly gopFrames: number;
+    readonly keyframeInterval: KeyframeInterval;
+} | {
+    readonly trackKind: 'video';
+    readonly mode: 'all-protected';
+    readonly reason: ClassifierReason;
+};
+/**
+ * Derive the per-track classifier geometry from raw catalog fields.
+ *
+ * `all-protected` is the policy's defined fail-closed state, not a default:
+ * it is returned with the exact reason. The only throw is for a value the
+ * catalog validator already rejects (a non-positive block span).
+ */
+export declare function deriveBlockClassifierGeometry(input: BlockClassifierGeometryInput): BlockClassifierGeometry;
+/**
+ * The keyframe interval expressed in a media track's timescale, or null when
+ * the geometry is not `classifying` or the interval is not an exact integer
+ * number of media ticks.
+ */
+export declare function keyframeIntervalMediaTicks(geometry: BlockClassifierGeometry, mediaTimescale: number): bigint | null;
+/**
+ * In-band evidence from ONE first-arrival source symbol received from the
+ * network. Recovered symbols and repair symbols never contribute, and the
+ * MFU `priority > 0x80` hint is not evidence.
+ */
+export interface SourceSymbolEvidence {
+    /** The MMTP header R (RAP) bit. */
+    readonly rap: boolean;
+    /** MPU_sequence_number, when parsed from this packet. */
+    readonly mpu?: number;
+    /**
+     * 0-based sample position within the MPU: the MFU DU-header
+     * `sample_number` minus one (ISO/IEC 23008-1 numbers samples from 1, and
+     * the parser rejects `sample_number` 0). Present only when this packet
+     * carried a DU header.
+     */
+    readonly idx?: number;
+    /** movie_fragment_sequence_number from the DU header, when present. */
+    readonly movieFragment?: number;
+    /**
+     * DU-header `offset`: the data unit's authored byte position within its
+     * sample (0 for a whole-sample data unit, the partition boundary for a
+     * subsample data unit). Present only with `idx`; absent reads as 0.
+     */
+    readonly offset?: number;
+    /**
+     * The MMTP header packet_sequence_number (contiguous per packet_id). Not
+     * classification evidence: FECManager uses it to bound how many blocks the
+     * producer can have started between two source symbols, so an outage is
+     * never mistaken for a source restart.
+     */
+    readonly packetSequenceNumber?: number;
+}
+export type ReclassificationEvidence = 'rap' | 'mpu-span' | 'window' | 'classifier-disabled';
+export type ClassifierChange = {
+    readonly kind: 'reclassified';
+    readonly sbn: number;
+    readonly from: BlockClass;
+    readonly to: BlockClass;
+    readonly evidence: ReclassificationEvidence;
+} | {
+    readonly kind: 'mode';
+    readonly mode: 'all-protected';
+    readonly reason: ClassifierReason;
+};
+/**
+ * Per-stream block classifier.
+ *
+ * Classes only move toward more protection or narrower evidence:
+ * `unknown→delta` and `unknown→keyframe` / `delta→keyframe` on evidence, and
+ * `delta→unknown` when an invariant disables classification. `keyframe` is
+ * terminal.
+ *
+ * The delta window rule rests on three premises, each guarded by an
+ * invariant that fires on positive evidence only:
+ *
+ * - P1: the source packets of one block are one contiguous run of the
+ *   stream's authored order, and blocks follow each other in SBN order
+ *   (`block-not-contiguous`). The producer assigns SS_IDs in authored order
+ *   and a block is the SS_ID range [SBN*K, SBN*K + K), so this holds for a
+ *   block that closes at K symbols in the middle of a frame: that frame's
+ *   fragments then land in two ADJACENT blocks, which is still one run each.
+ *   A frame split across adjacent blocks is not a violation.
+ * - P2: that run touches at most D media units, counting a frame continued
+ *   from the previous block (`block-wider-than-interleave`). The producer
+ *   counts a media-unit boundary only once the open block holds a symbol.
+ * - P3: an MPU starts with its only RAP and holds at most G frames
+ *   (`rap-not-mpu-start`, `mpu-longer-than-gop`, `rap-spacing-mismatch`), in
+ *   one movie fragment (`mpu-multiple-fragments`).
+ *
+ * P1 and P2 are what make a block's frames contiguous and lie within
+ * [idxMax − D + 1, idxMin + D − 1] of its MPU. What refutes P1 is a pair of
+ * source packets whose wire-stated authored order and SBN order disagree:
+ * a later MPU in an earlier block, a later data unit of one MPU (by
+ * movie_fragment_sequence_number, sample_number, then DU offset) in an
+ * earlier block, or one data unit in two blocks. That is the signature of a
+ * round-robin interleave, which scatters one run over several concurrent
+ * blocks. Non-adjacency alone is not: a sample larger than K packets
+ * legitimately spans blocks SBN..SBN+n.
+ */
+export declare class BlockClassifier {
+    #private;
+    constructor(geometry: BlockClassifierGeometry);
+    get geometry(): BlockClassifierGeometry;
+    get mode(): ClassifierMode;
+    get reason(): ClassifierReason | null;
+    /**
+     * Whether "same MPU on both sides of a gap" still proves the gap held no
+     * RAP. It stops holding for the rest of the epoch once a RAP was received
+     * inside an MPU or an MPU ran longer than a GOP.
+     */
+    get mpuBoundsRaps(): boolean;
+    /** Begin a fresh epoch (catalog change or track reset). */
+    reset(geometry?: BlockClassifierGeometry): void;
+    /**
+     * Retire this classifier (its stream moves to a new catalog epoch). Every
+     * block it had classified `delta` loses the evidence behind that class and
+     * reads `unknown` from now on; the returned changes say so.
+     */
+    retire(): ClassifierChange[];
+    /**
+     * The stream's SBN sequence restarted (FECManager source discontinuity:
+     * a publisher restart, or the SS_ID space wrapped). Authored order and SBN
+     * order are comparable only within one continuous sequence, so the P1
+     * ledger starts again.
+     */
+    noteSourceDiscontinuity(): void;
+    /** Register a block that exists without evidence (a vanished block). */
+    touch(sbn: number): void;
+    /** Forget a resolved block. */
+    forget(sbn: number): void;
+    classOf(sbn: number): BlockClass;
+    /** Record one first-arrival source symbol's evidence for block `sbn`. */
+    observe(sbn: number, evidence: SourceSymbolEvidence): ClassifierChange[];
+    /**
+     * Record a RAP frame released in order. Released MPU-start RAPs of MPUs m
+     * and m+n must be exactly n keyframe intervals apart in the media
+     * timescale, compared as integers.
+     *
+     * Comparing only consecutive MPUs would miss exactly the case the window
+     * rule cannot survive: a short MPU whose successor's RAP was lost (that
+     * RAP-bearing block is the one a wrong G calls delta), because the next
+     * released RAP then belongs to m+2. Every MPU is one interval long, so the
+     * span to any later released RAP proves or refutes all MPUs in between.
+     */
+    noteReleasedRap(mpu: number, presentationTime: bigint, mediaTimescale: number): ClassifierChange[];
+}
+export interface GapStreamIdentity {
+    readonly packetId: number;
+    /** Non-empty catalog identity, or null when the producer has no track name. */
+    readonly catalogTrackName: string | null;
+}
+/** What the sink knows about one side of a released gap. */
+export interface GapFrameEvidence {
+    /**
+     * Codec-aware RAP check: `MmtpContainerParser.isKeyframe(data, rapFlag,
+     * codec)`, bitstream-only for recovered frames. Never the priority hint.
+     */
+    readonly rap: boolean;
+    /**
+     * MPU_sequence_number of the frame. Omit it once the stream showed that
+     * an MPU boundary does not bound its RAPs (`BlockClassifier.mpuBoundsRaps`):
+     * same-MPU then no longer proves a gap lost only deltas.
+     */
+    readonly mpu?: number;
+    /** 0-based sample position within the MPU, when the geometry verifies it. */
+    readonly idx?: number;
+    /** Authored presentation time in `timescale` ticks. */
+    readonly pts?: bigint;
+    /** Authored sample duration in `timescale` ticks. */
+    readonly durationTicks?: number;
+    /** The media timescale of `pts` and `durationTicks`. */
+    readonly timescale?: number;
+}
+export type FrameGapAction = 'stall' | 'conceal';
+export type FrameGapReason = 'rap-lost' | 'rap-unknown' | 'discontinuity' | 'delta-lost' | 'rap-next' | 'audio-gap' | 'audio-discontinuity';
+/**
+ * The decision attached to the first frame released after a gap
+ * (`RoutedFrameMeta.gapBefore`). It is the same frozen object the manager
+ * emits as its `gap` repair lifecycle event, so a sink that acts on the frame
+ * and an observer that counts events see one fact.
+ */
+export interface FrameGapDecision {
+    readonly version: 2;
+    readonly type: 'gap';
+    readonly stream: GapStreamIdentity;
+    readonly trackKind: TrackKind;
+    readonly action: FrameGapAction;
+    readonly reason: FrameGapReason;
+    /** FEC blocks in the gap whose media was lost (failed or vanished). */
+    readonly blocks: readonly number[];
+    /** Missing video frames or audio access units, when exactly known. */
+    readonly missingFrames: number | null;
+    /** Authored duration of the missing media in milliseconds, when known. */
+    readonly missingMs: number | null;
+    /** Manager epoch of the stream when the decision was made. */
+    readonly epoch: number;
+}
+export interface DecideGapInput {
+    readonly stream: GapStreamIdentity;
+    readonly trackKind: TrackKind;
+    /** Last frame released before the gap. */
+    readonly before: GapFrameEvidence;
+    /** First frame released after the gap. */
+    readonly after: GapFrameEvidence;
+    /** The stream restarted (FEC SBN went backwards or the publisher reset). */
+    readonly discontinuity: boolean;
+    readonly blocks: readonly number[];
+    /**
+     * The most media units the gap can hold: the FEC blocks spanned from the
+     * frame before to the frame after, times D (media units per block,
+     * ceil(interleaveDepthMs / unit duration), §5.1). A block touches at most D
+     * units whether it closes at D or at K symbols. Null when the span or D is
+     * unknown. An audio PTS delta that implies more AUs than this is a clock
+     * jump, not loss, and re-anchors instead of concealing every slot.
+     */
+    readonly maxMissingUnits: number | null;
+    readonly epoch: number;
+}
+/**
+ * Pure stall/conceal decision for the first frame released after a gap.
+ *
+ * Video stalls only when a RAP may be inside the gap: the frame after it is
+ * not a RAP and either sits in another MPU (`rap-lost`) or the MPU cannot be
+ * proven on both sides (`rap-unknown`), or the stream restarted
+ * (`discontinuity`). A gap inside one MPU lost only deltas (`delta-lost`) and
+ * a RAP after the gap resynchronises by itself (`rap-next`). Audio never
+ * stalls: an exact gap is concealed per access unit (`audio-gap`), anything
+ * else re-anchors at the next frame (`audio-discontinuity`).
+ */
+export declare function decideGap(input: DecideGapInput): FrameGapDecision;
+//# sourceMappingURL=block-policy.d.ts.map

package/dist/block-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-policy.d.ts","sourceRoot":"","sources":["../src/block-policy.ts"],"names":[],"mappings":"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"}