@blockcast/mmt-container 0.4.1 → 0.5.0-main.2c1f81817995

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockcast/mmt-container",
-  "version": "0.4.1",
+  "version": "0.5.0-main.2c1f81817995",
   "description": "MMTP/LOC container parsing for MMT over MoQ and SSM",
   "type": "module",
   "main": "dist/index.js",
@@ -14,10 +14,6 @@
       "import": "./dist/browser-runtime.js",
       "types": "./dist/index.d.ts"
     },
-    "./source-auth": {
-      "import": "./dist/source-auth.js",
-      "types": "./dist/source-auth.d.ts"
-    },
     "./mfu": {
       "import": "./dist/mfu-reassembler.js",
       "types": "./dist/mfu-reassembler.d.ts"
@@ -102,10 +98,6 @@
       "import": "./dist/multicast-auth-catalog.js",
       "types": "./dist/multicast-auth-catalog.d.ts"
     },
-    "./manifest-auth-plan": {
-      "import": "./dist/manifest-auth-plan.js",
-      "types": "./dist/manifest-auth-plan.d.ts"
-    },
     "./catalog-validator": {
       "import": "./dist/catalog-validator.js",
       "types": "./dist/catalog-validator.d.ts"
@@ -166,17 +158,16 @@
     "build": "tsc --emitDeclarationOnly && node build.mjs",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
-    "bench:source-auth": "node bench/source-auth-wasm.mjs",
     "bench:amt-hot-path": "node --expose-gc --max-semi-space-size=64 bench/amt-hot-path.mjs",
     "test:catalog-validator-public-api": "node test-vectors/catalog-validator-public-api.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@blockcast/fec-worker": "^0.4.1",
-    "@blockcast/mmt-base": "^0.4.1",
-    "@blockcast/mmt-fec": "^0.4.1",
-    "@blockcast/mmt-manifest-verify": "^0.4.1",
+    "@blockcast/fec-worker": "0.5.0-main.2c1f81817995",
+    "@blockcast/mmt-base": "0.5.0-main.2c1f81817995",
+    "@blockcast/mmt-fec": "0.5.0-main.2c1f81817995",
+    "@blockcast/mmt-manifest-verify": "0.5.0-main.2c1f81817995",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
     "ajv": "^8.17.1",

package/src/cmcd-producer.ts

@@ -14,13 +14,18 @@
  */
 
 import type { FecTrackStats } from '@blockcast/fec-worker'
-import type { ManifestVerificationStats } from '@blockcast/mmt-manifest-verify'
 import type { FecFailClosedReason } from './fec-manager.js'
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
+/** Source-auth counters for CMCD: records verified, and drops per reason. */
+export interface ManifestVerificationStats {
+  verified: number
+  failures: Record<string, number>
+}
+
 /** Transport state snapshot, built by the player wiring layer from SocketPool. */
 export interface TransportSnapshot {
   transport: 'native' | 'amt' | 'moq'

package/src/fec-manager.ts

@@ -46,6 +46,7 @@ import {
   type TrackKind,
 } from './block-policy.js'
 
+import { HeldLayerAdmission, heldLayerAnchorHorizon, type FecFailClosedReason } from './held-layer-admission.js'
 import type { MmtpDeliveryProvenance } from './mfu-reassembler.js'
 import type {
   FecWorkerClient,
@@ -291,21 +292,7 @@ export interface FecRepairLayer {
   repairSymbols: number
 }
 
-/**
- * Why a source track's FEC failed closed at runtime (fec-01 6.3.9): a repair
- * packet stated an RSB_length below a held layer's total B_i on that layer's
- * own repair track (`below_own_track_total`), or at or after the anchor, the
- * earliest block in SS_Start serial order whose repair carried >= B_i
- * (`below_anchored_total`). Repair for the track is refused from then on.
- */
-export interface FecFailClosedReason {
-  code: 'below_own_track_total' | 'below_anchored_total'
-  layer: number
-  total: number
-  rsbLength: number
-  ssStart: number
-  anchor?: number
-}
+export type { FecFailClosedReason } from './held-layer-admission.js'
 
 /** A {@link FecFailClosedReason} with the stream it closed, as reported to the fail-closed handler. */
 export interface FecFailClosedEvent extends FecFailClosedReason {
@@ -313,26 +300,6 @@ export interface FecFailClosedEvent extends FecFailClosedReason {
   catalogTrackName: string | undefined
 }
 
-interface HeldLayerState {
-  layer: number
-  repairTrackName: string
-  total: number
-  /** Earliest (serial order) block start whose repair carried >= total. */
-  anchor?: number
-  /** Latest (serial order) block start whose repair carried < total. */
-  latestBelow?: number
-  /** RSB_length that latestBelow's repair carried, for the fail-closed reason. */
-  latestBelowRsb?: number
-  /** Newest block start seen; anchor and latestBelow are retired behind it. */
-  newest?: number
-  /**
-   * The anchor fell behind the horizon, so no block that can still arrive
-   * precedes it: every later packet must carry >= total. Its serial is no
-   * longer compared, so SS_Start wrapping past it cannot misorder it.
-   */
-  settled?: boolean
-}
-
 interface ResolvedFECTrackConfig {
   blockProfile?: FecBlockProfile
   algorithm?: 'raptorq' | 'reed-solomon'
@@ -544,7 +511,7 @@ export class FECManager {
   // symbols its repair group carries. Same lifecycle as #blockRepairRsIds.
   #blockRsbLengths = new Map<string, number>()
   /** fec-01 6.3.9 anchor state per stream key, one entry per held layer. */
-  #heldLayerStates = new Map<string, HeldLayerState[]>()
+  #heldLayerStates = new Map<string, HeldLayerAdmission>()
   /** Streams whose FEC failed closed at runtime (fec-01 6.3.9). */
   #fecFailClosed = new Map<string, FecFailClosedReason>()
   #onFecFailClosed: ((event: FecFailClosedEvent) => void) | null = null
@@ -583,6 +550,9 @@ export class FECManager {
   // Receiver-local first-accepted-symbol time per block, bounded like
   // #blockPathCounts (see blockAnchorAtMs).
   #blockAnchorsMs = new Map<string, number>()
+  // The receipt time of the packet being fed, when it is not now: a datagram
+  // held on a miss and admitted later (withReceiptTime).
+  #receiptAtMs: number | undefined = undefined
   // Exact catalog identity observed on accepted symbols for each FEC block.
   // Conflicting identities collapse to null so recovery fails closed.
   #blockCatalogTrackNames = new Map<string, string | null>()
@@ -630,6 +600,9 @@ export class FECManager {
   // Worker recovery emits all K source symbols. Track recovery once per block
   // while routing only ESI slots that were absent from the direct source path.
   #workerRecoveredBlocks = new Set<string>()
+  // Worker-recovered blocks a recovered packet of which admission refused,
+  // until the decode's final symbol (7.2.7: the block is unrecovered).
+  #refusedRecoveries = new Set<string>()
 
   // How the multicast leg delivers symbols (see MulticastSymbolDelivery). The
   // provider declares it per transport join; absence keeps datagram semantics.
@@ -833,7 +806,14 @@ export class FECManager {
     | null = null
 
   // Worker-path callbacks — async recovery and stats from FecWorkerClient.
-  onBlockRecovered: ((sbn: number, packetId: number, data: ArrayBuffer, meta: FrameMeta, catalogTrackName?: string) => void) | null = null
+  /**
+   * A recovered source symbol. Return false when admission refused the
+   * packet it carries (bc-provenance v2, draft-ramadan-moq-multicast-01
+   * 7.2.7): the block is then unrecovered and stays open to its FEC deadline.
+   */
+  onBlockRecovered:
+    | ((sbn: number, packetId: number, data: ArrayBuffer, meta: FrameMeta, catalogTrackName?: string) => boolean | void)
+    | null = null
   onFecStatsUpdate: ((packetId: number, stats: FecTrackStats) => void) | null = null
 
   #encodeTrackName(catalogTrackName: string): string {
@@ -978,6 +958,7 @@ export class FECManager {
       this.#completedBlocks.delete(record.key)
       this.#cleanlyCompletedBlocks.delete(record.key)
       this.#workerRecoveredBlocks.delete(record.key)
+      this.#refusedRecoveries.delete(record.key)
       // The policy's terminal ledgers describe the same terminal state and
       // retire with it: a failed block must never outlive its failure record
       // as 'complete' (that would hide a loss from the release gate).
@@ -1444,7 +1425,7 @@ export class FECManager {
     catalogTrackName: string | undefined,
     delayMs: number,
   ): void {
-    const deadlineMs = performance.now() + delayMs
+    const deadlineMs = this.#notEarlierUnderReceipt(this.#receiptNow() + delayMs, this.#repairDeadlineAtMs.get(key))
     this.#repairDeadlineAtMs.set(key, deadlineMs)
     const armed = this.#repairDeadlines.get(key)
     if (armed?.handle != null) {
@@ -1464,7 +1445,7 @@ export class FECManager {
       timer.handle = null
       this.#requestRepair(sbn, packetId, catalogTrackName)
     }
-    timer.handle = setTimeout(onFire, delayMs)
+    timer.handle = setTimeout(onFire, Math.max(0, deadlineMs - performance.now()))
     this.#repairDeadlines.set(key, timer)
   }
 
@@ -1668,6 +1649,10 @@ export class FECManager {
     ssId = sbn,
   ): void {
     const streamKey = this.#streamKey(packetId, catalogTrackName)
+    // Arrival at FEC, not receipt (withReceiptTime): this bounds how far SS_ID
+    // can plausibly move between symbols this instance has seen, and a held
+    // datagram admitted late reached it no earlier than now. A block's ts is
+    // its anchor (#blockAnchorsMs), which does take the receipt time.
     const now = performance.now()
     const previous = (symbol === 'source' ? this.#sourceFrontiers : this.#highestSbn).get(streamKey)
     const anchor = this.#sourceAnchors.get(streamKey)
@@ -2017,7 +2002,10 @@ export class FECManager {
     delayMs: number,
   ): void {
     const key = this.#blockKey(sbn, packetId, catalogTrackName)
-    const waitAtMs = performance.now() + Math.max(1, Math.ceil(delayMs))
+    const waitAtMs = this.#notEarlierUnderReceipt(
+      this.#receiptNow() + Math.max(1, Math.ceil(delayMs)),
+      this.#blockWaitDeadlinesMs.get(key),
+    )
     // A held block's symbols (its own FETCH's repair symbols included) never
     // carry its wait past the hold: the hold is its presentation deadline.
     const holdAtMs = this.#repairHoldUntilMs.get(key)
@@ -2534,6 +2522,7 @@ export class FECManager {
     resetSet(this.#cleanlyCompletedBlocks)
     resetSet(this.#repairRequestedBlocks)
     resetSet(this.#workerRecoveredBlocks)
+    resetSet(this.#refusedRecoveries)
     resetSet(this.#startupAlignedPackets)
     resetSet(this.#startupPartialBlocks)
     resetSet(this.#startupRepairReadyPackets)
@@ -2668,6 +2657,7 @@ export class FECManager {
     dropSet(this.#cleanlyCompletedBlocks)
     dropSet(this.#repairRequestedBlocks)
     dropSet(this.#workerRecoveredBlocks)
+    dropSet(this.#refusedRecoveries)
     dropSet(this.#startupAlignedPackets)
     dropSet(this.#startupPartialBlocks)
     dropSet(this.#startupRepairReadyPackets)
@@ -2832,7 +2822,10 @@ export class FECManager {
     // The block's absolute anchor (fecBlockDeadlineMs): the receiver-local
     // time of its first accepted symbol, from which its presentation deadline
     // is measured.
-    if (!this.#blockAnchorsMs.has(blockKey)) this.#blockAnchorsMs.set(blockKey, performance.now())
+    // A datagram held and admitted later keeps its receipt time (fec-01 9).
+    const receivedAtMs = this.#receiptNow()
+    const anchorMs = this.#blockAnchorsMs.get(blockKey)
+    if (anchorMs === undefined || receivedAtMs < anchorMs) this.#blockAnchorsMs.set(blockKey, receivedAtMs)
     if (source === 'multicast') counts.multicastSymbols++
     else counts.moqSymbols++
     this.#blockPathCounts.set(blockKey, counts)
@@ -3023,6 +3016,18 @@ export class FECManager {
   blockAnchorAtMs(sbn: number, packetId: number, catalogTrackName?: string): number | undefined {
     return this.#blockAnchorsMs.get(this.#blockKey(sbn, packetId, catalogTrackName))
   }
+  /**
+   * How long ago (ms) the oldest open block of the stream, one with an FEC
+   * deadline, took its first accepted symbol; undefined with none open.
+   */
+  oldestOpenBlockAgeMs(packetId: number, catalogTrackName: string): number | undefined {
+    let oldest = Infinity
+    for (const key of this.#activeBlocks.keys()) {
+      if (!this.#belongsToStream(key, packetId, catalogTrackName)) continue
+      oldest = Math.min(oldest, this.#blockAnchorsMs.get(key) ?? Infinity)
+    }
+    return oldest === Infinity ? undefined : performance.now() - oldest
+  }
   /** Absolute fail deadline of a still-open block, or undefined. */
   blockDeadlineAtMs(sbn: number, packetId: number, catalogTrackName?: string): number | undefined {
     return this.#activeBlockDeadlinesMs.get(this.#blockKey(sbn, packetId, catalogTrackName))
@@ -3687,22 +3692,6 @@ export class FECManager {
         const blockKey = this.#blockKey(meta.sbn, packetId, recoveredCatalogTrackName)
         const cleanlyCompleted = this.#cleanlyCompletedBlocks.has(blockKey)
         if (!cleanlyCompleted) {
-          if (!this.#workerRecoveredBlocks.has(blockKey)) {
-            this.#traceLifecycle(
-              'recovered',
-              meta.sbn,
-              packetId,
-              recoveredCatalogTrackName,
-            )
-            this.#workerRecoveredBlocks.add(blockKey)
-            this.#fecStats.blocksRecovered++
-            this.#statsForPacket(packetId).blocksRecovered++
-            if (this.#workerRecoveredBlocks.size > 1000) {
-              dropOldest(this.#workerRecoveredBlocks, 500)
-            }
-            this.#noteBlockRepaired(blockKey, meta.sbn, packetId, recoveredCatalogTrackName)
-          }
-
           // RaptorQ returns the full K-symbol block, not only erased symbols.
           // The direct path already parsed every source ESI in #seenSymbols;
           // routing those symbols again injects duplicate MFU fragments and can
@@ -3710,23 +3699,46 @@ export class FECManager {
           const symbolKey = `${blockKey}:${esi}`
           if (!this.#seenSymbols.has(symbolKey)) {
             this.#seenSymbols.add(symbolKey)
-            this.onBlockRecovered?.(
+            const admitted = this.onBlockRecovered?.(
               meta.sbn,
               packetId,
               data,
               meta,
               recoveredCatalogTrackName,
             )
+            if (admitted === false) {
+              this.#refusedRecoveries.add(blockKey)
+              if (this.#refusedRecoveries.size > 1000) dropOldest(this.#refusedRecoveries, 500)
+            }
           }
         }
 
         // The worker emits recovered source symbols in ESI order. Complete the
         // block only after its final authored slot so assemblers receive every
         // missing symbol before their completion callback flushes buffered media.
+        // A decode one of whose recovered packets admission refused recovered
+        // nothing (7.2.7): the block stays open and fails at its FEC deadline.
+        const refused = esi >= meta.ssbLength! - 1 && this.#refusedRecoveries.delete(blockKey)
         if (
           esi >= meta.ssbLength! - 1 &&
+          !refused &&
           !this.#completedBlocks.has(blockKey)
         ) {
+          if (!cleanlyCompleted && !this.#workerRecoveredBlocks.has(blockKey)) {
+            this.#traceLifecycle(
+              'recovered',
+              meta.sbn,
+              packetId,
+              recoveredCatalogTrackName,
+            )
+            this.#workerRecoveredBlocks.add(blockKey)
+            this.#fecStats.blocksRecovered++
+            this.#statsForPacket(packetId).blocksRecovered++
+            if (this.#workerRecoveredBlocks.size > 1000) {
+              dropOldest(this.#workerRecoveredBlocks, 500)
+            }
+            this.#noteBlockRepaired(blockKey, meta.sbn, packetId, recoveredCatalogTrackName)
+          }
           this.cancelBlockTimeout(meta.sbn, packetId, recoveredCatalogTrackName)
           if (recoveredCatalogTrackName === undefined) {
             this.onBlockComplete?.(meta.sbn, packetId)
@@ -4106,77 +4118,26 @@ export class FECManager {
     const config = this.#trackConfigs.get(packetId)
     const layers = config?.repairLayers
     if (layers === undefined || layers.length === 0) return true
-    if (repairTrackName !== undefined && !layers.some((l) => l.repairTrackName === repairTrackName)) {
-      return false
+    let admission = this.#heldLayerStates.get(streamKey)
+    if (admission === undefined) {
+      admission = new HeldLayerAdmission(layers, config!.heldLayers)
+      this.#heldLayerStates.set(streamKey, admission)
     }
-    let states = this.#heldLayerStates.get(streamKey)
-    if (states === undefined) {
-      const held = new Set(config!.heldLayers ?? [0])
-      states = layers
-        .filter((l) => held.has(l.layer))
-        .map((l) => ({ layer: l.layer, repairTrackName: l.repairTrackName, total: l.rsIdOffset + l.repairSymbols }))
-      this.#heldLayerStates.set(streamKey, states)
-    }
-    const horizon = this.#layerAnchorHorizon(packetId)
-    // A repair may run ahead of the media, but one more than `horizon` past the
-    // source frontier must not move the held-layer state: advancing `newest` on
-    // it would retire every real anchor and skip this check until traffic caught
-    // up. Such a repair is still judged below the total: it is on its own track,
-    // or after any anchor by definition. With no anchor yet it says nothing.
-    // It is still admitted: in iso the frontier only moves when a repair places
-    // held sources, so dropping it would stall recovery after a long outage.
-    // IsoBlockLocator.placeRepair may still refuse the same repair as `ahead`:
-    // it measures from `newest`, which held sources move, not from this frontier.
-    const frontier = this.#sourceFrontiers.get(streamKey)?.sbn
-    const farAhead =
-      frontier !== undefined && serial32Precedes(frontier, ssStart) && serial32Distance(frontier, ssStart) > horizon
-    for (const state of states) {
-      let code: FecFailClosedReason['code'] | undefined
-      if (farAhead) {
-        if (rsbLength < state.total) {
-          if (state.layer > 0 && repairTrackName === state.repairTrackName) code = 'below_own_track_total'
-          else if (state.anchor !== undefined || state.settled) code = 'below_anchored_total'
-        }
-      } else {
-        // Serials more than `horizon` behind the newest block are retired, so
-        // every serial still compared sits inside one half-window and SS_Start
-        // wrapping on a long-running stream cannot reorder them.
-        if (state.newest === undefined || serial32Precedes(state.newest, ssStart)) state.newest = ssStart
-        const stale = (s: number) => serial32Distance(s, state.newest!) > horizon
-        if (state.latestBelow !== undefined && stale(state.latestBelow)) {
-          delete state.latestBelow
-          delete state.latestBelowRsb
-        }
-        if (state.anchor !== undefined && stale(state.anchor)) state.settled = true
-        if (rsbLength < state.total) {
-          if (state.layer > 0 && repairTrackName === state.repairTrackName) code = 'below_own_track_total'
-          else if (stale(ssStart)) continue // past retention: undecodable, anchors nothing
-          else if (state.settled || (state.anchor !== undefined && !serial32Precedes(ssStart, state.anchor))) code = 'below_anchored_total'
-          else if (state.latestBelow === undefined || serial32Precedes(state.latestBelow, ssStart)) {
-            state.latestBelow = ssStart
-            state.latestBelowRsb = rsbLength
-          }
-        } else if (!state.settled && !stale(ssStart)) {
-          if (state.anchor === undefined || serial32Precedes(ssStart, state.anchor)) state.anchor = ssStart
-          if (state.latestBelow !== undefined && !serial32Precedes(state.latestBelow, state.anchor)) {
-            code = 'below_anchored_total'
-            ssStart = state.latestBelow
-            rsbLength = state.latestBelowRsb!
-          }
-        }
-      }
-      if (code !== undefined) {
-        const reason: FecFailClosedReason = {
-          code, layer: state.layer, total: state.total, rsbLength, ssStart,
-          ...(state.anchor === undefined ? {} : { anchor: state.anchor }),
-        }
-        this.#fecFailClosed.set(streamKey, reason)
-        this.#onFecFailClosed?.({ ...reason, packetId, catalogTrackName })
-        console.warn(
-          `[FECManager] FEC failed closed (fec-01 6.3.9) packetId=${packetId} track=${catalogTrackName ?? '-'}: ${JSON.stringify(reason)}`,
-        )
-        return false
-      }
+    const verdict = admission.admit(
+      repairTrackName,
+      ssStart,
+      rsbLength,
+      this.#layerAnchorHorizon(packetId),
+      this.#sourceFrontiers.get(streamKey)?.sbn,
+    )
+    if (verdict === 'discard') return false
+    if (verdict !== undefined) {
+      this.#fecFailClosed.set(streamKey, verdict)
+      this.#onFecFailClosed?.({ ...verdict, packetId, catalogTrackName })
+      console.warn(
+        `[FECManager] FEC failed closed (fec-01 6.3.9) packetId=${packetId} track=${catalogTrackName ?? '-'}: ${JSON.stringify(verdict)}`,
+      )
+      return false
     }
     return true
   }
@@ -4187,11 +4148,9 @@ export class FECManager {
    * times K, capped at 2^30 so compared serials stay inside one half-window.
    */
   #layerAnchorHorizon(packetId: number): number {
-    const cap = 0x40000000
     let blocks: number | undefined
     try { blocks = this.isoRetentionBlocksForPacket(packetId) } catch { blocks = undefined }
-    const k = this.#trackConfigs.get(packetId)?.k ?? 0
-    return blocks === undefined || k <= 0 ? cap : Math.min(cap, blocks * k)
+    return heldLayerAnchorHorizon(blocks, this.#trackConfigs.get(packetId)?.k ?? 0)
   }
 
   /**
@@ -4542,6 +4501,36 @@ export class FECManager {
     queueMicrotask(() => this.#syncDecoderBlockOwners.delete(key))
   }
 
+  /**
+   * Run `fn` with `receivedAtMs` (performance.now() clock) as the receipt
+   * time of what it feeds. Within a consumer the bc-provenance profile
+   * governs, a datagram held on a miss and admitted later keeps its receipt
+   * time (fec-01 9): it anchors its block's ts and arms the block's
+   * deadlines from then, never later than they are already armed.
+   */
+  withReceiptTime(receivedAtMs: number, fn: () => void): void {
+    const outer = this.#receiptAtMs
+    this.#receiptAtMs = receivedAtMs
+    try {
+      fn()
+    } finally {
+      this.#receiptAtMs = outer
+    }
+  }
+
+  #receiptNow(): number {
+    return this.#receiptAtMs ?? performance.now()
+  }
+
+  /**
+   * A held packet admitted late arms from its (earlier) receipt time; that
+   * never pulls in a deadline later activity already armed. Outside a
+   * receipt scope a re-arm replaces the deadline, as a narrower bound may.
+   */
+  #notEarlierUnderReceipt(deadlineMs: number, armedMs: number | undefined): number {
+    return this.#receiptAtMs === undefined || armedMs === undefined ? deadlineMs : Math.max(deadlineMs, armedMs)
+  }
+
   /** Refresh deadlines after accepted block activity. */
   noteBlockActivity(
     sbn: number,
@@ -4778,6 +4767,7 @@ export class FECManager {
     this.#cleanlyCompletedBlocks.clear()
     this.#repairRequestedBlocks.clear()
     this.#workerRecoveredBlocks.clear()
+    this.#refusedRecoveries.clear()
     this.#syncDecoderBlockOwners.clear()
     this.#startupAlignedPackets.clear()
     this.#startupPartialBlocks.clear()

package/src/held-layer-admission.ts

@@ -0,0 +1,161 @@
+/**
+ * The fec-01 6.3.9 receiver check (held-layer anchored RSB_length), in one
+ * place. FECManager and MmtpFecSession both run their repair packets through
+ * HeldLayerAdmission; neither restates the rule.
+ */
+
+import { serial32Distance, serial32Precedes } from '@blockcast/mmt-base'
+
+/**
+ * Why a source track's FEC failed closed at runtime (fec-01 6.3.9): a repair
+ * packet stated an RSB_length below a held layer's total B_i on that layer's
+ * own repair track (`below_own_track_total`), or at or after the anchor, the
+ * earliest block in SS_Start serial order whose repair carried >= B_i
+ * (`below_anchored_total`). Repair for the track is refused from then on.
+ */
+export interface FecFailClosedReason {
+  code: 'below_own_track_total' | 'below_anchored_total'
+  layer: number
+  total: number
+  rsbLength: number
+  ssStart: number
+  anchor?: number
+}
+
+/** One repair layer as the catalog states it: B_i = rsIdOffset + repairSymbols. */
+export interface HeldLayerInput {
+  layer: number
+  repairTrackName: string
+  rsIdOffset: number
+  repairSymbols: number
+}
+
+interface HeldLayerState {
+  layer: number
+  repairTrackName: string
+  total: number
+  /** Earliest (serial order) block start whose repair carried >= total. */
+  anchor?: number
+  /** Latest (serial order) block start whose repair carried < total. */
+  latestBelow?: number
+  /** RSB_length that latestBelow's repair carried, for the fail-closed reason. */
+  latestBelowRsb?: number
+  /** Newest block start seen; anchor and latestBelow are retired behind it. */
+  newest?: number
+  /**
+   * The anchor fell behind the horizon, so no block that can still arrive
+   * precedes it: every later packet must carry >= total. Its serial is no
+   * longer compared, so SS_Start wrapping past it cannot misorder it.
+   */
+  settled?: boolean
+}
+
+/** The largest horizon compared, so every compared serial stays in one half-window. */
+const HORIZON_CAP = 0x40000000
+
+/**
+ * How far (in SS_Start symbols) behind the newest block a 6.3.9 anchor or
+ * below-total block can still matter: the iso retention in blocks times K,
+ * capped at 2^30. Unknown inputs give the cap.
+ */
+export function heldLayerAnchorHorizon(retentionBlocks: number | undefined, k: number): number {
+  return retentionBlocks === undefined || k <= 0 ? HORIZON_CAP : Math.min(HORIZON_CAP, retentionBlocks * k)
+}
+
+/**
+ * fec-01 6.3.9 anchored state for one FEC instance's held layers. For each
+ * held layer i with total B_i = O_i + P_i: the anchor is the earliest block,
+ * in SS_Start serial order, whose repair carried RSB_length >= B_i. The
+ * instance fails closed on (a) a packet on layer i's own repair track (i > 0)
+ * below B_i, or (b) any packet of the instance at or after the anchor below
+ * B_i. Blocks before the anchor (pre-append) stay valid at the previous total.
+ * The result is not latched here: the caller owns what failing closed means.
+ */
+export class HeldLayerAdmission {
+  readonly #layerNames: ReadonlySet<string>
+  readonly #states: HeldLayerState[]
+
+  constructor(layers: readonly HeldLayerInput[], heldLayers: readonly number[] = [0]) {
+    const held = new Set(heldLayers)
+    this.#layerNames = new Set(layers.map((l) => l.repairTrackName))
+    this.#states = layers
+      .filter((l) => held.has(l.layer))
+      .map((l) => ({ layer: l.layer, repairTrackName: l.repairTrackName, total: l.rsIdOffset + l.repairSymbols }))
+  }
+
+  /**
+   * Judges one repair packet, after the 4.5 discards and the size check and
+   * before it places a block. `repairTrackName` is the subscribed repair
+   * track, never inferred from RS_ID; without it only (b) runs. A packet on a
+   * repair track the catalog does not list is `'discard'` and anchors nothing.
+   * `sourceFrontier` is the newest source SS_ID, if any: a repair more than
+   * `horizon` past it is judged without moving the anchored state.
+   *
+   * @returns undefined to admit, `'discard'`, or the fail-closed reason.
+   */
+  admit(
+    repairTrackName: string | undefined,
+    ssStart: number,
+    rsbLength: number,
+    horizon: number,
+    sourceFrontier?: number,
+  ): FecFailClosedReason | 'discard' | undefined {
+    if (repairTrackName !== undefined && !this.#layerNames.has(repairTrackName)) return 'discard'
+    // A repair may run ahead of the media, but one more than `horizon` past the
+    // source frontier must not move the held-layer state: advancing `newest` on
+    // it would retire every real anchor and skip this check until traffic caught
+    // up. Such a repair is still judged below the total: it is on its own track,
+    // or after any anchor by definition. With no anchor yet it says nothing.
+    // It is still admitted: in iso the frontier only moves when a repair places
+    // held sources, so dropping it would stall recovery after a long outage.
+    // IsoBlockLocator.placeRepair may still refuse the same repair as `ahead`:
+    // it measures from `newest`, which held sources move, not from this frontier.
+    const farAhead =
+      sourceFrontier !== undefined &&
+      serial32Precedes(sourceFrontier, ssStart) &&
+      serial32Distance(sourceFrontier, ssStart) > horizon
+    for (const state of this.#states) {
+      let code: FecFailClosedReason['code'] | undefined
+      if (farAhead) {
+        if (rsbLength < state.total) {
+          if (state.layer > 0 && repairTrackName === state.repairTrackName) code = 'below_own_track_total'
+          else if (state.anchor !== undefined || state.settled) code = 'below_anchored_total'
+        }
+      } else {
+        // Serials more than `horizon` behind the newest block are retired, so
+        // every serial still compared sits inside one half-window and SS_Start
+        // wrapping on a long-running stream cannot reorder them.
+        if (state.newest === undefined || serial32Precedes(state.newest, ssStart)) state.newest = ssStart
+        const stale = (s: number) => serial32Distance(s, state.newest!) > horizon
+        if (state.latestBelow !== undefined && stale(state.latestBelow)) {
+          delete state.latestBelow
+          delete state.latestBelowRsb
+        }
+        if (state.anchor !== undefined && stale(state.anchor)) state.settled = true
+        if (rsbLength < state.total) {
+          if (state.layer > 0 && repairTrackName === state.repairTrackName) code = 'below_own_track_total'
+          else if (stale(ssStart)) continue // past retention: undecodable, anchors nothing
+          else if (state.settled || (state.anchor !== undefined && !serial32Precedes(ssStart, state.anchor))) code = 'below_anchored_total'
+          else if (state.latestBelow === undefined || serial32Precedes(state.latestBelow, ssStart)) {
+            state.latestBelow = ssStart
+            state.latestBelowRsb = rsbLength
+          }
+        } else if (!state.settled && !stale(ssStart)) {
+          if (state.anchor === undefined || serial32Precedes(ssStart, state.anchor)) state.anchor = ssStart
+          if (state.latestBelow !== undefined && !serial32Precedes(state.latestBelow, state.anchor)) {
+            code = 'below_anchored_total'
+            ssStart = state.latestBelow
+            rsbLength = state.latestBelowRsb!
+          }
+        }
+      }
+      if (code !== undefined) {
+        return {
+          code, layer: state.layer, total: state.total, rsbLength, ssStart,
+          ...(state.anchor === undefined ? {} : { anchor: state.anchor }),
+        }
+      }
+    }
+    return undefined
+  }
+}