@pictor-sdk/video-android 0.1.0

package/src/previewCadence.ts

@@ -0,0 +1,950 @@
+import { resampleClip, type ResampleRequest } from '@pictor-sdk/video-core'
+import type { SpikeSample } from './compositionSpike'
+import type { SubmissionRecord } from './submissionScoring'
+
+/**
+ * Did the preview show the right frame at each output instant?
+ *
+ * ## The oracle this replaces
+ *
+ * The first version counted *source* frames and expected every one to appear.
+ * That reported a 2x clip — 6 seconds of source occupying 3 seconds — as
+ * delivering 98 of 180 frames with 58 missed intervals. The 180 was wrong: a
+ * preview has its own output rate, and at 30 fps three seconds of timeline has
+ * about 90 output instants, at each of which the resampling rule *skips* every
+ * second source frame by design. Requiring all 180 asked the preview to run at
+ * 60 fps and then scored it for refusing.
+ *
+ * So the oracle is the shared rule itself. `resampleClip` already decides which
+ * source frame belongs at each output instant, at a stated target rate, and it
+ * is the same function the exporter's contract is written against. Using it
+ * here means the preview and the export cannot disagree about what "correct"
+ * means.
+ *
+ * ## What is checked
+ *
+ * At each expected output instant, whether the picture on screen is the frame
+ * the rule names. Not whether every source frame appeared — above 1x most of
+ * them must not.
+ *
+ * @experimental
+ */
+
+/** One clip, as the playlist compiled it. @experimental */
+export interface CadenceClip {
+  name: string
+  /** Where the window sits on the project timeline. */
+  timelineStartUs: number
+  timelineEndUs: number
+  /** Clipping bounds in source time. */
+  sourceStartUs: number
+  sourceEndUs: number
+  speed: number
+  sourceFps: number
+}
+
+/**
+ * How far the preview may sit from the export's frame selection.
+ *
+ * The tolerance the rest of the video path is held to. A preview picture is
+ * temporally accurate when the frame it shows is within this of the frame the
+ * rule names, converted to project time — not when it is that exact frame.
+ *
+ * @experimental
+ */
+export const PREVIEW_TOLERANCE_US = 60_000
+
+/**
+ * How far a correctly rendered picture may be from its own frame's content.
+ *
+ * The level tolerance absorbs the codec: a flat grey through H.264 at 4:2:0 and
+ * back through a scaler does not return the exact value it went in as. The bar
+ * tolerance is a little over one source row at the fixture's height, which is
+ * what an interpolating scaler can move an edge by. Neither absorbs a flip, an
+ * offset or a wrong scale, which move the bar by whole per cents.
+ */
+const PARITY_LEVEL_TOLERANCE = 12
+const PARITY_BAR_TOLERANCE = 4 / 960
+
+/**
+ * What a run established, as three outcomes rather than two.
+ *
+ * `invalid` is not a soft failure — it is the absence of a measurement, and it
+ * must never be reachable by a run that simply had the probe switched off. A
+ * boolean cannot say that: `false` reads as "measured and wrong", and three
+ * device runs once reported `wrong=0, worstOffset=0.0 ms` because a shifted
+ * button meant nothing was scorable at all. That was a clean pass by absence of
+ * evidence and one paste from being reported as a fix working.
+ *
+ * @experimental
+ */
+export type Verdict = 'pass' | 'fail' | 'invalid'
+
+/** Rendering correctness, per clip. @experimental */
+export interface CadenceParity {
+  /** Submissions that carried a parity measurement. */
+  measured: number
+  /** Worst background-level error, 0..255. */
+  worstLevelDelta: number
+  /** Worst bar-position error, in 0..1 of height. */
+  worstBarDelta: number
+  /** Submissions whose rendering was outside tolerance. */
+  failures: number
+  pass: boolean
+}
+
+/** @experimental */
+export interface CadenceResult {
+  clip: string
+  /** Output instants the rule names for the whole clip. */
+  nominalInstants: number
+  /** Output instants the rule expects across the span actually covered. */
+  expectedInstants: number
+  /**
+   * Instants that could not be placed on the wall clock.
+   *
+   * No bracketing pair of player-clock samples inside one segment — the
+   * transport was paused or seeking across them. Counted and excluded from
+   * scoring rather than placed by extrapolation.
+   */
+  unplaceableInstants: number
+  /**
+   * How far the frame-derived clock sits from the player's, in microseconds.
+   *
+   * A diagnostic, never the anchor. Positive means pictures are handed over
+   * later than the project time they carry — the pipeline's systematic
+   * presentation delay.
+   *
+   * Anchoring on the frame-derived value would subtract this from every
+   * measurement and call a uniformly late pipeline punctual, which is why
+   * instants are placed from the player's clock and this is only reported.
+   */
+  frameDerivedOffsetUs: number
+  /**
+   * Instants before the first submission, and after the last.
+   *
+   * Named rather than absorbed. Scoring a clip over its nominal length would
+   * count every instant a run never reached as a missed deadline; excluding
+   * them silently would let a picture that arrived late or stopped early
+   * disappear from coverage instead. They are excluded from the identity check
+   * and reported here, and `leadingExcluded` in particular is the interval
+   * where the previous clip was still on screen — which is the seam, and is
+   * scored by the submission metric rather than by this one.
+   */
+  leadingExcluded: number
+  trailingExcluded: number
+  /** Instants where some frame was on screen. */
+  coveredInstants: number
+  /**
+   * Instants showing a different source frame from the one the rule names.
+   *
+   * The real failure: a missed deadline is the picture being wrong at a moment
+   * somebody was looking, not a source frame going unused.
+   */
+  wrongFrameInstants: number
+  /** Instants with no frame at all — the picture had not caught up. */
+  uncoveredInstants: number
+  /** Unique pictures submitted inside the span. */
+  submittedUnique: number
+  /**
+   * Source frames the rule says to skip.
+   *
+   * Above 1x this is most of them and is correct. Reported so a count of
+   * "missing" frames cannot be read as loss.
+   */
+  ruleSkippedSourceFrames: number
+  /** The interval between output instants, from the declared preview rate. */
+  outputIntervalUs: number
+  medianHoldUs: number
+  maxHoldUs: number
+  /**
+   * How long one picture should stay up, from the rule.
+   *
+   * At 2x a new source frame is due at every output instant; at 0.5x the rule
+   * repeats each one, so a hold of two instants is correct rather than a stall.
+   */
+  expectedHoldUs: number
+  /**
+   * Pictures held past their turn.
+   *
+   * Counted from the holds rather than from the covered span, because a stall
+   * at the end of a run produces no further submissions and would otherwise
+   * simply shorten the span it was scored over.
+   */
+  missedDeadlines: number
+  /**
+   * How far off the shown frame was, counted in source frames.
+   *
+   * Keyed by `shown - expected`, over every scored instant whose identity was
+   * established — the correct ones included, so the shape of the whole run is
+   * visible rather than only its tail. This is what separates a picture that is
+   * one source frame early from one that is a third of a second stale, and at
+   * 2x those are 8.3 ms and 330 ms of project time: the same count of "wrong
+   * instants" and completely different defects.
+   */
+  offsets: Record<string, number>
+  /**
+   * The largest offset, in project time rather than in source frames.
+   *
+   * The conversion that makes the count mean something. One source frame at
+   * speed `s` is `1 / sourceFps / s` of project time — 16.7 ms at 2x, 66.7 ms
+   * at 0.5x — so the same offset of three frames is 50 ms in one clip and 200
+   * ms in another. Judged against the synchronisation tolerance, not against
+   * zero: a preview consumes a live decoder at its own display rate and cannot
+   * seek to an exact source frame per instant the way an export does.
+   */
+  worstOffsetUs: number
+  /**
+   * Rendering correctness, against the frame each picture's own band names.
+   *
+   * Separate from everything above it. The rest of this result is about *which*
+   * frame was shown; this is about whether that frame was drawn correctly —
+   * colour, orientation and scale. A picture one source frame early and
+   * rendered perfectly scores zero here.
+   */
+  parity: CadenceParity
+  /**
+   * Instants that showed exactly the frame the export rule names.
+   *
+   * Reported, never required. It is the export contract's measure, kept here so
+   * the preview's tolerance is visible as a decision rather than as the absence
+   * of a check.
+   */
+  exactInstants: number
+  /**
+   * What this run established. @see Verdict
+   *
+   * `pass` only when identity was read from pixels, parity was measured, and
+   * both were clean. Anything unmeasured is `invalid`.
+   */
+  verdict: Verdict
+  /** Why, when the verdict is not a pass. */
+  verdictReason: string
+  /** Whether the acquired-identity evidence was usable at all. */
+  identity: CadenceIdentity
+  /**
+   * Wall-clock gaps between this clip's submissions.
+   *
+   * Per clip because the aggregate mixes rates: a 0.5x clip legitimately holds
+   * each picture for two output intervals, so a global p95 at 66.7 ms is the
+   * 0.5x clip behaving correctly and says nothing about whether the 2x clip
+   * stalled. Reported separately so a delay cannot hide inside a hold.
+   */
+  frameTimeUs: { p50: number; p95: number; p99: number; max: number; samples: number }
+  /**
+   * Every instant whose picture was not the one the rule names.
+   *
+   * Including the boundary instants the scored span excludes: those are the
+   * seam, and leaving them out of the identity check is how a wrong picture at
+   * a clip change disappears from both metrics at once.
+   */
+  wrong: WrongInstant[]
+  pass: boolean
+}
+
+/**
+ * Why an instant showed the wrong picture.
+ *
+ * The first three are decided in pixels and name one place to look. The fourth
+ * is what the metadata alone can support, which is less than it appears: on
+ * this device `SurfaceTexture` reports a system-clock value, so an instant
+ * classified without the marker cannot separate a frame acquired wrongly from a
+ * frame chosen wrongly, and says so rather than picking one.
+ *
+ * @experimental
+ */
+export type WrongInstantCause =
+  /**
+   * The expected frame's pixels were not in the ring when the instant needed
+   * them.
+   *
+   * Nothing downstream could have shown it. The fault is decode, acquisition or
+   * the copy into the ring — and the test is by that instant, not by the end of
+   * the clip, because every frame arrives eventually and a clip-global check
+   * would charge a frame that had simply not arrived yet to selection.
+   */
+  | 'not-delivered'
+  /**
+   * The expected frame's pixels were in the ring, and a different frame was
+   * submitted.
+   *
+   * The fault is the choice, not the supply.
+   */
+  | 'wrong-selection'
+  /**
+   * The submitted picture no longer held the frame its slot was filled with.
+   *
+   * A wrapped texture aliases storage the ring may redraw. This is that storage
+   * changing under a picture composition still holds, and it is the one cause
+   * here that is a correctness defect in the ring's own contract.
+   */
+  | 'storage-aliased'
+  /**
+   * The wrong picture, and the evidence cannot say whether it was acquired or
+   * chosen wrongly.
+   *
+   * What the metadata supports with the probe off. Not a third fault: a
+   * placeholder for an attribution not yet made.
+   */
+  | 'wrong-submitted-identity'
+  /**
+   * The right frame, submitted after the instant it belonged to.
+   *
+   * Only reachable without pixel identity. When the marker is readable, a frame
+   * matching the rule makes the instant correct however late it was submitted,
+   * so lateness stops being an identity fault and becomes a frame-time one.
+   * Its evidence — the ring's own submission time and project timestamp — is
+   * independent of the disputed pairing, which is why it survives there.
+   */
+  | 'late-delivery'
+  /** No submission covered the instant at all. */
+  | 'uncovered'
+
+/** @experimental */
+export interface WrongInstant {
+  projectUs: number
+  /** From the shared rule: the source frame that belongs at this instant. */
+  expectedSourceFrame: number
+  expectedSourcePtsUs: number
+  /** What was on screen, mapped back through the same speed. */
+  shownSourceFrame: number
+  shownPtsUs: number
+  /** What the texture said it held when that frame was acquired. */
+  acquiredTexturePtsUs: number
+  /** The frame index in the pixels of the slot, and of the submitted picture. */
+  acquiredMarker: number
+  submittedMarker: number
+  slot: number
+  frameId: number
+  submittedNs: number
+  cause: WrongInstantCause
+  /** True when the instant lies outside the scored span. */
+  boundary: boolean
+}
+
+/** What the texture timestamp turned out to be. @experimental */
+export type TimestampDomain =
+  /** Comparable with the clip's media time. */
+  | 'media'
+  /** A system-clock value: `System.nanoTime()`, as measured on this device. */
+  | 'system'
+  /** Nothing was recorded, so there is nothing to establish. */
+  | 'unknown'
+
+/** @experimental */
+export interface CadenceIdentity {
+  /**
+   * The domain the texture timestamps were established to be in.
+   *
+   * Recorded rather than assumed, and recorded even when it is the one that
+   * makes the check weaker. It was `media` by assumption for one whole run and
+   * the assumption was wrong by forty-eight hours.
+   */
+  timestampDomain: TimestampDomain
+  medianTextureSkewUs: number
+  /**
+   * Whether identity came from the pixels.
+   *
+   * When false, the fallback compares submitted timestamps — which on a
+   * `system` domain cannot uniquely associate a buffer with a frame. Every
+   * instant is then counted `identityUnverified` and the clip cannot pass. A
+   * fallback that quietly declared those instants correct would be restoring
+   * confidence the evidence does not support.
+   */
+  pixelIdentity: boolean
+  /** Instants whose identity could not be established either way. */
+  identityUnverified: number
+  /** Distinct frame indices read out of the ring for this clip. */
+  deliveredFrames: number
+  /** Bands that were read, and bands that failed. */
+  markersRead: number
+  markersFailed: number
+}
+
+/**
+ * The preview's own output rate.
+ *
+ * Stated rather than inferred from what arrived: an oracle that takes its
+ * expectation from the measurement cannot fail.
+ *
+ * @experimental
+ */
+export const PREVIEW_OUTPUT_FPS = 30
+
+/**
+ * Which source frame was on screen at `projectUs`, from what was submitted.
+ *
+ * The last submission at or before the instant — the same "last one at or
+ * before" rule `resampleClip` samples the source with, because a nearest-match
+ * would credit a frame that had not been shown yet.
+ */
+/**
+ * When an instant of project time happened, on the monotonic clock.
+ *
+ * Built from the player's own reported position paired with the monotonic time
+ * it was read at — two values the pump records together and neither derived
+ * from a frame. That independence is the point: an offset computed from
+ * submission records folds any systematic presentation delay into the anchor,
+ * so a pipeline uniformly late looks punctual to itself.
+ *
+ * Segmented by epoch and by whether the transport was running. A pause or a
+ * seek breaks the correspondence between project time and the wall clock
+ * entirely, and interpolating across one would place an instant at a moment
+ * that never occurred. Instants with no bracketing pair inside a single segment
+ * return null rather than a guess.
+ */
+function wallClockAt(
+  samples: readonly SpikeSample[],
+  projectUs: number,
+  intervalUs: number,
+): number | null {
+  let before: SpikeSample | null = null
+  let after: SpikeSample | null = null
+  for (const s of samples) {
+    if (!s.playing || s.positionUs < 0 || s.atNs <= 0) continue
+    if (s.positionUs <= projectUs && (before === null || s.positionUs > before.positionUs)) before = s
+    if (s.positionUs >= projectUs && (after === null || s.positionUs < after.positionUs)) after = s
+  }
+  /*
+    One interval past the last sample, and no further.
+
+    The final instant of a clip has nothing after it to bracket with, and
+    refusing it would make every real run end in an unplaceable instant and
+    report `invalid`. Extrapolating one interval at the project rate is exact
+    enough for a span that short; beyond it the transport may have stopped and
+    there is no evidence either way.
+  */
+  if (after === null) {
+    if (before === null || projectUs - before.positionUs > intervalUs) return null
+    return before.atNs + (projectUs - before.positionUs) * 1000
+  }
+  /*
+    And one interval before the first sample, symmetrically.
+
+    An instant can land just ahead of the earliest reading — the output grid and
+    the poller are not aligned, and the grid's rounding puts one instant of a
+    clip on the wrong side of it. The same bound applies: inside an interval the
+    project rate places it exactly, beyond it there is no evidence.
+  */
+  if (before === null) {
+    if (after.positionUs - projectUs > intervalUs) return null
+    return after.atNs - (after.positionUs - projectUs) * 1000
+  }
+  // Different segments: a pause or a seek sits between them.
+  if (before.epoch !== after.epoch) return null
+  if (after.positionUs === before.positionUs) return before.atNs
+  const t = (projectUs - before.positionUs) / (after.positionUs - before.positionUs)
+  return before.atNs + t * (after.atNs - before.atNs)
+}
+
+/**
+ * The picture on screen at an instant — as of that instant.
+ *
+ * Selected by when it was submitted, not only by what time it claims. Choosing
+ * the greatest `ptsUs` at or before the instant let a frame submitted long
+ * afterwards be credited to it: the screen showed something older at the time,
+ * and the late arrival made the instant correct retroactively. A frame that had
+ * not been handed to composition yet was not on screen, whatever its timestamp
+ * says.
+ *
+ * The instant's wall-clock time is derived from the clip's first submission and
+ * the project rate, which is 1x for the composition — the same assumption the
+ * audio pairing documents and relies on.
+ */
+function displayedAt(
+  submissions: readonly SubmissionRecord[],
+  projectUs: number,
+  atNs: number | null,
+  intervalNs: number,
+): SubmissionRecord | null {
+  /*
+    One output interval of slack, because an instant is an interval.
+
+    An output instant is not a point in time — it is the span during which its
+    picture should be on screen. A frame handed over anywhere inside that span
+    was shown for part of it, and excluding it would charge the grid's own
+    resolution to the pipeline. A frame arriving after the span has closed was
+    never on screen for it, which is the case this rule exists to exclude.
+  */
+  if (atNs === null) return null
+  const deadlineNs = atNs + intervalNs
+  let best: SubmissionRecord | null = null
+  for (const s of submissions) {
+    if (s.ptsUs > projectUs) continue
+    // Not yet submitted when the instant passed: it was not the picture.
+    if (s.submittedNs > deadlineNs) continue
+    if (best === null || s.submittedNs > best.submittedNs) best = s
+  }
+  return best
+}
+
+/** @experimental */
+export function checkCadence(
+  clip: CadenceClip,
+  submissions: readonly SubmissionRecord[],
+  outputFps = PREVIEW_OUTPUT_FPS,
+  /**
+   * How far the shown frame may be from the named one, in project time.
+   *
+   * Zero scores the export contract — exact selection, no tolerance — and the
+   * default scores the preview's. @see PREVIEW_TOLERANCE_US
+   */
+  toleranceUs = PREVIEW_TOLERANCE_US,
+  /**
+   * The player's own clock, paired with monotonic time.
+   *
+   * Where instants are placed on the wall clock. Empty means no instant can be
+   * placed, and the result is `invalid` rather than scored against a guess.
+   */
+  samples: readonly SpikeSample[] = [],
+): CadenceResult {
+  const request: ResampleRequest = {
+    sourceStartUs: clip.sourceStartUs as never,
+    sourceEndUs: clip.sourceEndUs as never,
+    speed: clip.speed,
+    sourceFps: clip.sourceFps,
+    targetFps: outputFps,
+  }
+  const plan = resampleClip(request)
+  const outputIntervalUs = Math.round(1_000_000 / outputFps)
+
+  const inClip = submissions
+    .filter((s) => s.ptsUs >= clip.timelineStartUs && s.ptsUs < clip.timelineEndUs)
+    .sort((a, b) => a.ptsUs - b.ptsUs)
+
+  /*
+    Is the texture's timestamp even in media time?
+
+    On this device it is not: `SurfaceTexture.getTimestamp` returns a
+    `System.nanoTime`-based value, about forty-nine hours of uptime, in the
+    domain of the release time rather than of the presentation timestamp.
+    Treating it as media time called every instant a wrong acquisition — a
+    broken check reporting a broken pipeline.
+
+    So the domain is tested rather than assumed, and when it does not hold the
+    identity check falls back to the paired metadata and says it could not
+    separate a wrong acquisition from a wrong promotion.
+  */
+  const skews = inClip
+    .filter((s) => s.texturePtsUs >= 0)
+    .map((s) => Math.abs(s.texturePtsUs - s.ptsUs))
+    .sort((a, b) => a - b)
+  const medianSkewUs = skews.length > 0 ? skews[Math.floor(skews.length / 2)]! : -1
+  const timestampDomain: TimestampDomain =
+    skews.length === 0 ? 'unknown' : medianSkewUs < 1_000_000 ? 'media' : 'system'
+  const unique = new Set(inClip.map((s) => s.ptsUs))
+
+  /*
+    What the pixels say arrived, and what they say was shown.
+
+    `delivered` is every distinct frame index the ring actually held during this
+    clip. It is what separates a frame that was never supplied from a frame that
+    was supplied and not chosen — the distinction the timestamps could not make,
+    and the reason for the band in the first place.
+  */
+  const delivered = new Set<number>()
+  let markersRead = 0
+  let markersFailed = 0
+  for (const record of inClip) {
+    if (record.acquiredMarker >= 0) delivered.add(record.acquiredMarker)
+    if (record.submittedMarker >= 0) markersRead += 1
+    else if (record.markerFailure !== '' && record.markerFailure !== 'unread') markersFailed += 1
+  }
+  const pixelIdentity = markersRead > 0
+
+  /*
+    Scored across the span actually covered, not the clip's nominal length.
+
+    A run that stopped early, or a seek that landed mid-clip, would otherwise
+    report every instant it never reached as a missed deadline.
+  */
+  const first = inClip.length > 0 ? inClip[0]!.ptsUs : 0
+  const last = inClip.length > 0 ? inClip[inClip.length - 1]!.ptsUs : 0
+  /*
+    The frame-derived offset, kept only as a cross-check.
+
+    It was the anchor once, and it should not have been: an offset computed from
+    submission records folds any systematic presentation delay into itself, so a
+    pipeline uniformly late measures as punctual. Instants are placed from the
+    player's own clock instead, and this is reported beside it — a growing
+    difference between the two *is* the presentation delay, which is worth
+    seeing rather than absorbing.
+  */
+  const clockOffsets = inClip
+    .filter((r) => r.submittedNs > 0)
+    .map((r) => r.submittedNs - r.ptsUs * 1000)
+    .sort((a, b) => a - b)
+  const playerOffsets = samples
+    .filter((s) => s.playing && s.atNs > 0 && s.positionUs >= 0)
+    .map((s) => s.atNs - s.positionUs * 1000)
+    .sort((a, b) => a - b)
+  /*
+    The difference between the two clocks, not either one's absolute value.
+
+    Both are monotonic-minus-project offsets and both are dominated by uptime —
+    reported raw, one read as 203,687 seconds, which says nothing. What is worth
+    seeing is how far apart they sit: the player says when a moment of project
+    time occurred, the frames say when a picture for it was handed over, and the
+    gap is the pipeline's systematic presentation delay. Anchoring on the frames
+    would subtract exactly that and call the result punctual.
+  */
+  const frameDerivedOffsetNs =
+    clockOffsets.length > 0 && playerOffsets.length > 0
+      ? clockOffsets[Math.floor(clockOffsets.length / 2)]! -
+        playerOffsets[Math.floor(playerOffsets.length / 2)]!
+      : 0
+
+  let expectedInstants = 0
+  let leadingExcluded = 0
+  let trailingExcluded = 0
+  let covered = 0
+  let wrong = 0
+  let unverified = 0
+  let unplaceable = 0
+  let exact = 0
+  const offsets: Record<string, number> = {}
+  // One source frame, in project time: 16.7 ms at 2x, 66.7 ms at 0.5x. The
+  // conversion that makes an offset comparable with the tolerance.
+  const sourceIntervalUs = clip.sourceFps > 0 ? 1_000_000 / clip.sourceFps / clip.speed : 0
+  const wrongInstants: WrongInstant[] = []
+  for (const frame of plan.frames) {
+    const projectUs = clip.timelineStartUs + Number(frame.outputPtsUs)
+    if (inClip.length === 0) continue
+    const boundary = projectUs < first || projectUs > last
+    if (projectUs < first) leadingExcluded += 1
+    else if (projectUs > last) trailingExcluded += 1
+    else expectedInstants += 1
+
+    const instantNs = wallClockAt(samples, projectUs, outputIntervalUs)
+    if (instantNs === null && !boundary) unplaceable += 1
+    const shown =
+      instantNs === null ? null : displayedAt(inClip, projectUs, instantNs, outputIntervalUs * 1000)
+    if (shown === null) {
+      /*
+        The boundary instants are checked too.
+
+        They are excluded from the *coverage* arithmetic because the run never
+        reached them, but their identity still matters: a leading instant is the
+        seam, where the previous clip is still on screen, and dropping it from
+        both metrics is how a wrong picture at a clip change goes unseen.
+      */
+      if (boundary) {
+        wrongInstants.push({
+          projectUs,
+          expectedSourceFrame: frame.sourceFrameIndex,
+          expectedSourcePtsUs: Number(frame.sourceTimeUs),
+          shownSourceFrame: -1,
+          shownPtsUs: -1,
+          acquiredTexturePtsUs: -1,
+          acquiredMarker: -1,
+          submittedMarker: -1,
+          slot: -1,
+          frameId: -1,
+          submittedNs: 0,
+          cause: 'uncovered',
+          boundary,
+        })
+      }
+      continue
+    }
+    if (!boundary) covered += 1
+
+    /*
+      Identity by source frame, not by timestamp.
+
+      The submitted PTS is project time and the rule names a source frame, so
+      the comparison maps the shown picture back through the same speed the
+      compiler applied. A tolerance of one source frame absorbs the rounding
+      between the two directions.
+    */
+    /*
+      What the texture holds, not what the record claims it holds.
+
+      The two are usually the same and the case where they are not is exactly a
+      wrong acquisition: the picture on screen is the texture's content, and
+      scoring the record's timestamp instead would call that instant correct.
+    */
+    const shownProjectUs = timestampDomain === 'media' ? shown.texturePtsUs : shown.ptsUs
+    const shownSourceUs = clip.sourceStartUs + (shownProjectUs - clip.timelineStartUs) * clip.speed
+    /*
+      The marker when there is one, the timestamp only when there is not.
+
+      A read band names the frame outright; the derived index is an inference
+      from the very association under test. When neither is available the
+      instant is unverified rather than assumed correct.
+    */
+    const derivedIndex = Math.floor((shownSourceUs * clip.sourceFps) / 1_000_000)
+    const shownIndex = shown.submittedMarker >= 0 ? shown.submittedMarker : derivedIndex
+    const verified = shown.submittedMarker >= 0 || timestampDomain === 'media'
+    if (!verified) {
+      if (!boundary) unverified += 1
+      continue
+    }
+    /*
+      Counted before it is judged, and counted whether or not it passes.
+
+      A pixel oracle can be exact, so it is: the rule names one source frame and
+      the band says which one arrived. But "wrong" spans a frame that is 8.3 ms
+      early and a frame that is a third of a second stale, and a count alone
+      cannot tell them apart.
+    */
+    const offset = shownIndex - frame.sourceFrameIndex
+    /*
+      Over the scored span only.
+
+      A boundary instant is one the run never reached, and what is on screen
+      there is the previous clip or the last picture of this one — an offset of
+      a few hundred frames that is not jitter and would swamp the distribution.
+      Those instants are still checked; they appear in `wrong` flagged
+      `boundary`, which is where they belong.
+    */
+    if (!boundary) {
+      const key = String(offset)
+      offsets[key] = (offsets[key] ?? 0) + 1
+    }
+
+    /*
+      Two contracts, and this is the preview's.
+
+      An export selects the exact frame `resampleClip` names: it drives the
+      decoder to a source time and gets that frame. A preview consumes a live
+      decoder at its own display rate, and above 1x the frame the rule names is
+      usually never produced at the instant it is wanted — measured at 2x, 31 to
+      37 of about 90 instants wanted a frame no slot ever held, against 0 to 1
+      the ring genuinely mis-chose. Requiring exact identity would be asking the
+      preview to seek per frame.
+
+      So the preview is judged temporally: the picture must be within
+      `PREVIEW_TOLERANCE_US` of project time from the frame the rule names, and
+      dropping frames during accelerated playback is permitted. This is an
+      acceptance decision, not a discovery that the identity check passed —
+      `exactInstants` and the offset distribution are reported either way, and
+      an export must still be scored against exact selection.
+    */
+    const offsetUs = Math.abs(offset) * sourceIntervalUs
+    // The derived index still needs its rounding slack; a band is exact.
+    const slack = shown.submittedMarker >= 0 ? 0 : sourceIntervalUs
+    if (offset === 0) exact += 1
+    if (offsetUs <= Math.max(toleranceUs, slack)) continue
+    if (!boundary) wrong += 1
+
+    /*
+      Three different faults, and they send the fix to three different places.
+
+      The texture's own timestamp is what separates them: if it disagrees with
+      the metadata the frame was recorded under, the pairing was wrong before
+      the ring saw it. If it agrees and a different frame is on screen, the ring
+      chose wrongly. If the right frame is on screen but arrived after its
+      instant, nothing chose wrongly and it was simply late.
+    */
+    const acquired = shown.texturePtsUs
+    /*
+      Late delivery first, because its evidence stands on its own.
+
+      Both terms are the ring's own records — when it submitted, and what
+      project time it recorded the frame under — and neither comes from the
+      texture. It survives the timestamp-domain problem intact, which is why it
+      stays a separate cause rather than folding into the unresolved one.
+    */
+    const late = shown.submittedNs > 0 && shown.ptsUs < projectUs - outputIntervalUs
+    /*
+      Available *by this instant*, not somewhere in the clip.
+
+      A clip-global check answers the wrong question: every frame arrives
+      eventually, so nothing is ever "not delivered" and a picture that simply
+      had not arrived yet is charged to selection. What decides the fault is
+      whether the named frame was in the ring when the instant needed it.
+    */
+    const hadItByThen = inClip.some(
+      (r) =>
+        r.acquiredMarker === frame.sourceFrameIndex &&
+        r.acquiredNs > 0 &&
+        r.acquiredNs <= shown.submittedNs,
+    )
+    /*
+      Three outcomes in pixels, and only three.
+
+      With identity read from the picture, "the right frame submitted late"
+      cannot produce a wrong instant: if the marker matches the rule's frame the
+      instant is correct, whenever it was submitted. So the pixel path asks only
+      whether the storage changed, whether the frame was there to show, and
+      whether something else was shown instead. `late-delivery` belongs to the
+      timestamp path, where identity is inferred from when a frame was recorded
+      rather than from what it contains.
+    */
+    let cause: WrongInstantCause
+    if (shown.submittedMarker >= 0) {
+      if (shown.acquiredMarker >= 0 && shown.submittedMarker !== shown.acquiredMarker) {
+        cause = 'storage-aliased'
+      } else if (!hadItByThen) cause = 'not-delivered'
+      else cause = 'wrong-selection'
+    } else if (late) cause = 'late-delivery'
+    else cause = 'wrong-submitted-identity'
+
+    wrongInstants.push({
+      projectUs,
+      expectedSourceFrame: frame.sourceFrameIndex,
+      expectedSourcePtsUs: Number(frame.sourceTimeUs),
+      shownSourceFrame: shownIndex,
+      shownPtsUs: shownProjectUs,
+      acquiredTexturePtsUs: acquired,
+      acquiredMarker: shown.acquiredMarker,
+      submittedMarker: shown.submittedMarker,
+      slot: shown.slot,
+      frameId: shown.frameId,
+      submittedNs: shown.submittedNs,
+      cause,
+      boundary,
+    })
+  }
+
+  const walls: number[] = []
+  for (let i = 1; i < inClip.length; i += 1) {
+    const gap = (inClip[i]!.submittedNs - inClip[i - 1]!.submittedNs) / 1000
+    if (gap > 0) walls.push(gap)
+  }
+  walls.sort((a, b) => a - b)
+  const tail = (fraction: number) =>
+    walls.length === 0
+      ? 0
+      : Math.round(walls[Math.min(walls.length - 1, Math.floor(walls.length * fraction))]!)
+  const frameTimes = {
+    p50: tail(0.5),
+    p95: tail(0.95),
+    p99: tail(0.99),
+    max: walls.length > 0 ? Math.round(walls[walls.length - 1]!) : 0,
+    samples: walls.length,
+  }
+
+  /*
+    Parity over the submissions, not over the instants.
+
+    Rendering is a property of a picture, and the same picture can cover several
+    instants; scoring it once per instant would weight a held frame more heavily
+    than a fleeting one for no reason.
+  */
+  let parityMeasured = 0
+  let worstLevelDelta = 0
+  let worstBarDelta = 0
+  let parityFailures = 0
+  for (const record of inClip) {
+    if (record.levelDelta < 0 || record.barDelta < 0) continue
+    parityMeasured += 1
+    if (record.levelDelta > worstLevelDelta) worstLevelDelta = record.levelDelta
+    if (record.barDelta > worstBarDelta) worstBarDelta = record.barDelta
+    if (record.levelDelta > PARITY_LEVEL_TOLERANCE || record.barDelta > PARITY_BAR_TOLERANCE) {
+      parityFailures += 1
+    }
+  }
+
+  const stamps = [...unique].sort((a, b) => a - b)
+  const holds: number[] = []
+  for (let i = 1; i < stamps.length; i += 1) holds.push(stamps[i]! - stamps[i - 1]!)
+  const repeats = Math.max(1, Math.round(1 / clip.speed))
+  const expectedHoldUs = outputIntervalUs * repeats
+  const missedDeadlines = holds.filter((h) => h > expectedHoldUs * 1.5).length
+  holds.sort((a, b) => a - b)
+
+  /*
+    Nothing measured is not a failing measurement.
+
+    Checked before anything is judged: a run with no submissions, no readable
+    band, or no parity reading has established nothing about this clip, and
+    saying `fail` would be as wrong as saying `pass`.
+  */
+  let verdict: Verdict = 'pass'
+  let verdictReason = ''
+  if (expectedInstants === 0) {
+    verdict = 'invalid'
+    verdictReason = 'no instants covered'
+  } else if (!pixelIdentity) {
+    verdict = 'invalid'
+    verdictReason = 'identity not read from pixels'
+  } else if (parityMeasured === 0) {
+    verdict = 'invalid'
+    verdictReason = 'rendering parity not measured'
+  } else if (unplaceable > 0) {
+    verdict = 'invalid'
+    verdictReason = `${unplaceable} instants could not be placed on the clock`
+  } else if (unverified > 0) {
+    verdict = 'invalid'
+    verdictReason = `${unverified} instants unverified`
+  } else if (wrong > 0) {
+    verdict = 'fail'
+    verdictReason = `${wrong} wrong instants`
+  } else if (covered !== expectedInstants) {
+    verdict = 'fail'
+    verdictReason = `${expectedInstants - covered} instants uncovered`
+  } else if (missedDeadlines > 0) {
+    verdict = 'fail'
+    verdictReason = `${missedDeadlines} missed deadlines`
+  } else if (parityFailures > 0) {
+    verdict = 'fail'
+    verdictReason = `${parityFailures} parity failures`
+  }
+
+  return {
+    clip: clip.name,
+    nominalInstants: plan.frames.length,
+    leadingExcluded,
+    trailingExcluded,
+    expectedInstants,
+    coveredInstants: covered,
+    wrongFrameInstants: wrong,
+    uncoveredInstants: expectedInstants - covered,
+    submittedUnique: unique.size,
+    ruleSkippedSourceFrames: plan.droppedSourceFrameCount,
+    outputIntervalUs,
+    medianHoldUs: holds.length > 0 ? holds[Math.floor(holds.length / 2)]! : 0,
+    maxHoldUs: holds.length > 0 ? holds[holds.length - 1]! : 0,
+    expectedHoldUs,
+    missedDeadlines,
+    parity: {
+      measured: parityMeasured,
+      worstLevelDelta,
+      worstBarDelta: Number(worstBarDelta.toFixed(5)),
+      failures: parityFailures,
+      // No measurement is not a pass: a run that never looked has not looked.
+      pass: parityMeasured > 0 && parityFailures === 0,
+    },
+    offsets,
+    unplaceableInstants: unplaceable,
+    frameDerivedOffsetUs: Math.round(frameDerivedOffsetNs / 1000),
+    exactInstants: exact,
+    worstOffsetUs: Math.round(
+      Object.keys(offsets).reduce((worst, k) => Math.max(worst, Math.abs(Number(k))), 0) *
+        (clip.sourceFps > 0 ? 1_000_000 / clip.sourceFps / clip.speed : 0),
+    ),
+    identity: {
+      timestampDomain,
+      medianTextureSkewUs: medianSkewUs,
+      pixelIdentity,
+      identityUnverified: unverified,
+      deliveredFrames: delivered.size,
+      markersRead,
+      markersFailed,
+    },
+    frameTimeUs: frameTimes,
+    wrong: wrongInstants,
+    // Every expected instant covered, by the frame the shared rule names, and
+    // no picture held past its turn.
+    /*
+      An unverified instant is not a passing one.
+
+      With the probe off and the timestamps in the system domain there is no
+      evidence about which frame was shown, and a check that reported that
+      absence as success would be the same mistake as the one the band was
+      built to correct.
+    */
+    /*
+      The preview contract: temporally accurate, correctly rendered, covered.
+
+      Exact export-frame identity is deliberately absent. `exactInstants` and
+      `offsets` record it, and `@see PREVIEW_TOLERANCE_US` for why requiring it
+      here would be requiring a per-frame seek.
+    */
+    pass: verdict === 'pass',
+    verdict,
+    verdictReason,
+  }
+}