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

package/src/iso-block-locator.ts

@@ -0,0 +1,329 @@
+/**
+ * iso-ssbg1-v1 block location for one FEC stream (BLO-35597 iso:2/iso:3/iso:5).
+ *
+ * Under ISO/IEC 23008-1 C.5.2 the SS_ID increments by one per FEC source
+ * packet and wraps at 2^32, and a block is the SS_ID range
+ * `[SS_Start, SS_Start + SSB_length)` its Repair FEC Payload ID states (C.5.3).
+ * Block lengths vary, so `floor(SS_ID / K)` locates nothing: a source symbol
+ * belongs to a block only once a repair symbol has stated that block's range.
+ * A source that arrives first is held, unplaced, and handed back when a repair
+ * places it. Nothing here guesses a boundary.
+ *
+ * Coverage grows contiguously from the first block a repair states. When a
+ * repair states a block that starts after the end of known coverage, the SS_IDs
+ * between are one or more blocks whose every repair symbol was lost: they are
+ * kept as one repair-less span, which completes clean once all of its SS_IDs
+ * arrived (C.5.2 makes a gap in consecutive SS_IDs directly visible) and
+ * otherwise resolves through its catalog-derived deadline. That is the only
+ * way a block without repair completes: on the next block's SS_Start, never on
+ * a count of K source symbols.
+ */
+import {
+  isoBlockContains,
+  isoBlockEnd,
+  isoBlocksBehindLowerBound,
+  serial32Add,
+  serial32Distance,
+  serial32Precedes,
+} from '@blockcast/mmt-base'
+
+/** One block (or repair-less span) the locator knows the exact range of. */
+export interface IsoBlockRange {
+  readonly start: number
+  readonly length: number
+  /** True for SS_IDs between two stated blocks whose own repair never came. */
+  readonly span: boolean
+}
+
+/** A held source symbol handed back with its block coordinate. */
+export interface IsoPlacedSource<T> {
+  readonly ssId: number
+  readonly esi: number
+  readonly payload: T
+}
+
+/** What one repair symbol's `(SS_Start, SSB_length)` did to the locator. */
+export type IsoRepairPlacement<T> =
+  | {
+      readonly status: 'placed'
+      readonly block: IsoBlockRange
+      /** Sources this repair placed into `block`, in SS_ID order. */
+      readonly placed: readonly IsoPlacedSource<T>[]
+      /** The repair-less span this repair closed in front of `block`, if any. */
+      readonly span?: { readonly block: IsoBlockRange; readonly placed: readonly IsoPlacedSource<T>[] }
+    }
+  /** Not a block this stream can use; the repair symbol is dropped. */
+  | { readonly status: 'conflict' | 'overlap' | 'stale'; readonly reason: string }
+
+/**
+ * Retention: the locator is never without one. Every call that can grow it
+ * (`hold`, `placeRepair`) retires, behind the position it just saw, every
+ * block, span and held source more than `retentionBlocks` blocks back, by the
+ * one ISO horizon metric (`isoBlocksBehindLowerBound`). A block is measured
+ * from its last SS_ID, so it stays while any SS_ID of it is inside the
+ * horizon: a repair-less span has no length bound, and one measured from its
+ * start could be retired the moment it is created, before the sources it
+ * placed are fed. Held sources are additionally capped at the SS_IDs the
+ * horizon spans (`(retentionBlocks + 1) * kMax`): consecutive SS_IDs (C.5.2)
+ * cannot hold more inside it, so the cap only ever bites on a stream whose
+ * SS_IDs are not consecutive, and then the oldest arrival goes first.
+ */
+export class IsoBlockLocator<T> {
+  /** Known blocks and spans, in serial order of their start. */
+  readonly #blocks: IsoBlockRange[] = []
+  /** Held first-arrival sources whose block no repair has stated yet. */
+  readonly #held = new Map<number, T>()
+  /** End of contiguous coverage: the SS_ID the next unknown block starts at. */
+  #coverageEnd: number | undefined
+  readonly #kMax: number
+  #retentionBlocks: number
+  #heldEvicted = 0
+  #newest: number | undefined
+
+  /**
+   * @param kMax the catalog maximum K (`sourceSymbols`), the bound on SSB_length.
+   * @param retentionBlocks how many blocks behind the newest position the
+   *   locator keeps, derived by its owner from catalog timing; required, so
+   *   no locator exists without retention.
+   */
+  constructor(kMax: number, retentionBlocks: number) {
+    if (!Number.isSafeInteger(kMax) || kMax <= 0) {
+      throw new Error(`[IsoBlockLocator] maximum K must be a positive integer (got ${kMax})`)
+    }
+    this.#kMax = kMax
+    this.#retentionBlocks = IsoBlockLocator.#checkedRetention(retentionBlocks)
+  }
+
+  static #checkedRetention(retentionBlocks: number): number {
+    if (!Number.isSafeInteger(retentionBlocks) || retentionBlocks <= 0) {
+      throw new Error(
+        `[IsoBlockLocator] retention must be a positive integer number of blocks (got ${retentionBlocks})`,
+      )
+    }
+    return retentionBlocks
+  }
+
+  get kMax(): number {
+    return this.#kMax
+  }
+
+  /** Blocks behind the newest position the locator keeps. */
+  get retentionBlocks(): number {
+    return this.#retentionBlocks
+  }
+
+  /** Update the retention when the catalog timing it derives from changes. */
+  set retentionBlocks(retentionBlocks: number) {
+    this.#retentionBlocks = IsoBlockLocator.#checkedRetention(retentionBlocks)
+  }
+
+  /** The most sources held at once: the SS_IDs the retention horizon spans. */
+  get heldCapacity(): number {
+    return (this.#retentionBlocks + 1) * this.#kMax
+  }
+
+  /**
+   * The newest position the stream has reached (RFC 1982 order): the newest
+   * SS_ID of a source held, or fed once located (`observe`), or SS_Start of a
+   * placed repair, so no source the stream has fed follows it. Undefined
+   * before the first one.
+   */
+  get newest(): number | undefined {
+    return this.#newest
+  }
+
+  /** Advance `newest` to `position` if it is newer; retires nothing. */
+  observe(position: number): void {
+    if (this.#newest === undefined || serial32Precedes(this.#newest, position)) this.#newest = position
+  }
+
+  /** Held sources evicted by `heldCapacity` (never by the horizon itself). */
+  get heldEvicted(): number {
+    return this.#heldEvicted
+  }
+
+  /** Number of known blocks and spans. */
+  get blockCount(): number {
+    return this.#blocks.length
+  }
+
+  /** End of contiguous coverage, or undefined before the first repair. */
+  get coverageEnd(): number | undefined {
+    return this.#coverageEnd
+  }
+
+  /** Number of sources held for a block no repair has stated yet. */
+  get heldCount(): number {
+    return this.#held.size
+  }
+
+  /** The known block or span containing `ssId`, with its ESI. */
+  locate(ssId: number): { block: IsoBlockRange; esi: number } | null {
+    for (let i = this.#blocks.length - 1; i >= 0; i--) {
+      const block = this.#blocks[i]!
+      if (isoBlockContains(block.start, block.length, ssId)) {
+        return { block, esi: serial32Distance(block.start, ssId) }
+      }
+    }
+    return null
+  }
+
+  /** The known block or span starting exactly at `start`. */
+  blockAt(start: number): IsoBlockRange | undefined {
+    return this.#blocks.find((block) => block.start === start)
+  }
+
+  /** Known blocks and spans overlapping the SS_IDs strictly between `a` and `b`. */
+  blocksBetween(a: number, b: number): IsoBlockRange[] {
+    const first = (a + 1) >>> 0
+    const count = serial32Distance(a, b) - 1
+    if (!serial32Precedes(a, b) || count <= 0) return []
+    return this.#blocks.filter((block) => {
+      const toBlock = serial32Distance(first, block.start)
+      const fromBlock = serial32Distance(block.start, first)
+      return toBlock < count || fromBlock < block.length
+    })
+  }
+
+  /**
+   * Whether every SS_ID strictly between `a` and `b` lies in known coverage,
+   * so no block that could hold them is still to be stated by a repair.
+   */
+  coversBetween(a: number, b: number): boolean {
+    if (this.#coverageEnd === undefined) return false
+    if (!serial32Precedes(a, b) || serial32Distance(a, b) <= 1) return true
+    // The last SS_ID strictly before b must precede the coverage end.
+    return serial32Precedes((b - 1) >>> 0, this.#coverageEnd)
+  }
+
+  /**
+   * Hold a first-arrival source symbol whose block is not yet known. Returns
+   * false for a second copy of an SS_ID already held, so the first copy wins.
+   * Retires behind `ssId` (see the class note).
+   */
+  hold(ssId: number, payload: T): boolean {
+    if (this.#held.has(ssId)) return false
+    this.#held.set(ssId, payload)
+    this.retireBehind(ssId)
+    for (const oldest of this.#held.keys()) {
+      if (this.#held.size <= this.heldCapacity) break
+      this.#held.delete(oldest)
+      this.#heldEvicted++
+    }
+    return true
+  }
+
+  /** Whether `ssId` is held unplaced. */
+  isHeld(ssId: number): boolean {
+    return this.#held.has(ssId)
+  }
+
+  /**
+   * Apply one repair symbol's `(SS_Start, SSB_length)`. The first repair of a
+   * block states its range and places every held source in it; later repair
+   * symbols of the same block change nothing. A range that contradicts a
+   * known block (a different length, or an overlap with another block or a
+   * span) fails closed: the repair symbol is dropped and no block changes.
+   * A newly stated block retires behind its SS_Start (see the class note).
+   */
+  placeRepair(start: number, length: number): IsoRepairPlacement<T> {
+    if (!Number.isSafeInteger(length) || length <= 0 || length > this.#kMax) {
+      return { status: 'conflict', reason: `SSB_length ${length} is outside 1..${this.#kMax}` }
+    }
+    const known = this.blockAt(start)
+    if (known !== undefined) {
+      if (known.span) {
+        return { status: 'overlap', reason: `repair block ${start}+${length} falls inside a repair-less span` }
+      }
+      if (known.length !== length) {
+        return {
+          status: 'conflict',
+          reason: `repair SSB_length ${length} conflicts with ${known.length} for SS_Start ${start}`,
+        }
+      }
+      return { status: 'placed', block: known, placed: [] }
+    }
+    for (const block of this.#blocks) {
+      if (
+        isoBlockContains(block.start, block.length, start) ||
+        isoBlockContains(start, length, block.start)
+      ) {
+        return {
+          status: 'overlap',
+          reason: `repair block ${start}+${length} overlaps known block ${block.start}+${block.length}`,
+        }
+      }
+    }
+    let span: { block: IsoBlockRange; placed: IsoPlacedSource<T>[] } | undefined
+    if (this.#coverageEnd === undefined) {
+      // Reception starts at the first stated block. Held sources before it
+      // are the tail of blocks that began before the join: their range is
+      // never stated, so they are not FEC symbols of this receiver.
+      for (const ssId of this.#held.keys()) {
+        if (serial32Precedes(ssId, start)) this.#held.delete(ssId)
+      }
+      this.#coverageEnd = start
+    } else if (serial32Precedes(start, this.#coverageEnd)) {
+      return { status: 'stale', reason: `repair block ${start}+${length} precedes known coverage` }
+    } else if (start !== this.#coverageEnd) {
+      const spanBlock: IsoBlockRange = {
+        start: this.#coverageEnd,
+        length: serial32Distance(this.#coverageEnd, start),
+        span: true,
+      }
+      span = { block: spanBlock, placed: this.#claim(spanBlock) }
+      this.#blocks.push(spanBlock)
+    }
+    const block: IsoBlockRange = { start, length, span: false }
+    const placed = this.#claim(block)
+    this.#blocks.push(block)
+    this.#coverageEnd = isoBlockEnd(start, length)
+    this.retireBehind(start)
+    return span === undefined
+      ? { status: 'placed', block, placed }
+      : { status: 'placed', block, placed, span }
+  }
+
+  /**
+   * Retire every block and span whose last SS_ID, and every held source,
+   * lies more than `retentionBlocks` blocks behind `position`, with the shared
+   * lower-bound metric (`isoBlocksBehindLowerBound`) every ISO interleave
+   * horizon uses. Returns the retired block starts.
+   */
+  retireBehind(position: number): number[] {
+    this.observe(position)
+    const horizon = this.#retentionBlocks
+    const retired: number[] = []
+    for (let i = this.#blocks.length - 1; i >= 0; i--) {
+      const block = this.#blocks[i]!
+      const last = serial32Add(block.start, block.length - 1)
+      if (isoBlocksBehindLowerBound(last, position, this.#kMax) > horizon) {
+        retired.push(block.start)
+        this.#blocks.splice(i, 1)
+      }
+    }
+    for (const ssId of [...this.#held.keys()]) {
+      if (isoBlocksBehindLowerBound(ssId, position, this.#kMax) > horizon) this.#held.delete(ssId)
+    }
+    return retired
+  }
+
+  /** Forget everything (publisher restart, track reset). */
+  reset(): void {
+    this.#blocks.length = 0
+    this.#held.clear()
+    this.#coverageEnd = undefined
+    this.#newest = undefined
+  }
+
+  #claim(block: IsoBlockRange): IsoPlacedSource<T>[] {
+    const placed: IsoPlacedSource<T>[] = []
+    for (const [ssId, payload] of this.#held) {
+      if (!isoBlockContains(block.start, block.length, ssId)) continue
+      placed.push({ ssId, esi: serial32Distance(block.start, ssId), payload })
+      this.#held.delete(ssId)
+    }
+    placed.sort((x, y) => x.esi - y.esi)
+    return placed
+  }
+}