Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/interop.yml
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,11 @@ jobs:
env:
MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs

- name: TS pair controls
if: ${{ !cancelled() && steps.setup.outcome == 'success' }}
run: nix develop --command just test ts-pair-controls
shell: bash -leo pipefail {0}

# Round-trips a PCR-paced TS through a relay and checks the subscriber's
# `export ts` output with TSDuck (tsp/tsanalyze from the nix devShell).
- name: TS compliance
Expand Down
15 changes: 15 additions & 0 deletions .github/workflows/nightly.yml
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,12 @@ jobs:
if: ${{ !cancelled() }}
run: nix develop --command just rs c-tests

- name: TS table alignment
if: ${{ !cancelled() }}
run: nix develop --command just test ts --pair
env:
MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs

# The TS exporter's PCR release timing. Everything else about the stream
# can be graded from a capture, but *when* the bytes were handed over
# cannot: the grader has to sit on the exporter's stdout for the length of
Expand All @@ -232,6 +238,15 @@ jobs:
if: ${{ !cancelled() }}
run: nix develop --command just test ts --live --duration 120

- name: Upload TS pair failure artifacts
if: failure()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: nightly-ts-pair
path: ${{ runner.temp }}/moq-test-runs
if-no-files-found: ignore
retention-days: 7

tests:
name: Tests (${{ matrix.recipe }})
runs-on: ubuntu-24.04-arm
Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,6 @@ session outcomes, and embedder refusals inside session outcomes.
- [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time
- [A watch and publish release ships assets()](/quest/m1/assets-release.md) - the release that lets the sites host the worklets
- [Dogfood hosted worklets](/quest/m1/dogfood-assets.md) - the moq.pro dashboard hosts the worklets and calls `assets()` after the release
- [TS pair acquisition](/quest/m1/ts-pair-acquisition.md) - fix the clean baseline and prove the grader's controls before #5328 enables its scheduled hard gate
- [Initial catalog routing](/quest/m1/initial-catalog-routing.md) - a usable fallback does not strand initial catalog acquisition with a spurious Unroutable
- [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause
- [END_OF_TRACK placement](/quest/m1/ietf-end-of-track-placement.md) - END_OF_TRACK rides the upstream's Location, and Rust's header stops claiming END_OF_GROUP
Expand Down
2 changes: 1 addition & 1 deletion quest/m1/initial-catalog-routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,4 @@ decision rather than an invented retry or compatibility layer.
- [Transport upgrade](/quest/m1/transport-upgrade/README.md) - existing handover and epoch contracts
- [TS duration fidelity](/quest/m0/ts-duration-fidelity.md) - previously captured only a short suffix, not zero-packet initial acquisition
- [Replacement catalog linger](/quest/m1/ts-follow-catalog-bound.md) - bounds a midstream stitch, not initial discovery
- [Pair acquisition](/quest/m1/ts-pair-acquisition.md) - independent grader/mux finding
- [Pair validation](/test/ts/README.md#table-anchoring-table-anchorpy) - independent grader/acquisition checks
60 changes: 0 additions & 60 deletions quest/m1/ts-pair-acquisition.md

This file was deleted.

4 changes: 4 additions & 0 deletions test/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,10 @@ drill-sensitivity *args:
ts *args:
./ts/run.sh "$@"

# Table-placement grader: acquisition, interleave, phase, drift and missing-table controls.
ts-pair-controls:
python3 ./ts/table-anchor.test.py

# Round-trip the EIT fixtures: the sparse schedule must survive and
# pending-version sections must be dropped at import.
[positional-arguments]
Expand Down
102 changes: 39 additions & 63 deletions test/ts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -389,76 +389,52 @@ checks to hard.

## Table anchoring (`table-anchor.py`)

Every other check here grades one stream in isolation, and no single stream can
answer the question this one asks: **are a table's emission points a property of
the broadcast, or of the exporter that happened to emit them?**

It matters because two exporters of one broadcast are how redundancy is built. A
receiver merging two legs, or cutting from one to the other, needs them to agree
about where the tables sit. If each leg emits to its own clock the two outputs
are not interchangeable, and the divergence is permanent rather than something a
longer run settles.

One stream cannot show this because a timer and an anchor look identical from
inside: both produce a table every so often. Only a second leg, joining at a
different moment, separates them.
Two exporters of the same broadcast must converge after acquisition. `--pair`
starts the second subscriber five seconds late and checks table placement on the
shared PCR timeline. This measures table alignment; it does not establish packet
identity, `--sync`, or ST 2022-7 compatibility.

```bash
just test ts --pair # round-trip twice, grade the pair
just test ts --pair --pair-join 20 --duration 60 # join the second leg 20s in
./table-anchor.py a.ts b.ts # grade two captures you already have
just test ts --pair
just test ts --pair --pair-join 20 --duration 60
just test ts-pair-controls
./table-anchor.py a.ts b.ts --report-json pair.json
```

The second subscriber joins late on purpose. Two exporters started together can
agree on a cadence by having started together, which is the confound; a leg that
joins mid-broadcast has to derive its emission points from the media, because it
has no shared history to derive them from.

**What gets graded is the overlap, not the run**, so `--pair` defaults to a 45 s
duration rather than the 20 s the other arms use, and refuses a run leaving less
than 25 s of it. At 20 s with a 5 s join the legs share 15 s, which is about
seven SDT emissions against a floor of eight — the table this mode exists to
check would quietly drop to report-only. Raise `--duration` when you raise
`--pair-join`. `--pair` cannot be combined with `--live`: they grade different
things.

The measurement is the PTS of the frame each table was emitted against. `export
ts` writes the tables that are due and then the frame's PES packets into one
buffer, so the first PES header after a table gives the PTS of the frame that
triggered it. **Agreement** is the emission points both legs used over those
either used, counted only inside the media time the two captures share, so a
late join costs nothing. 100 % means the emission points are a function of the
broadcast.
The CBR slot scheduler interleaves tables and PES, so the next PES timestamp does not
identify when a table was sent. The grader interpolates each table's packet
position between PCR samples. A match allows one packet of placement quantization
plus one PCR tick of rounding. Matching is one-to-one, so duplicates count.

The comparison starts at the later leg's **second video random-access PES**,
after its first acquired group, matching the exporter's late-join convergence
regression. This boundary comes from media markers, never from the tables under
test or a fixed time allowance. The end is the earlier leg's final PCR. Tables
that disappear cannot shorten their own scoring window. Captures with multiple
program clocks, variable bitrate, midstream PCR discontinuities, missing acquisition markers, or
broken packet framing are refused. PCR wrap is supported.

The default run lasts 45 seconds and requires 20 seconds of acquired shared
clock. PAT, declared PMTs, and every observed non-clock table must each have at
least eight emissions **on both legs**, with at least 90% agreement. Missing or
sparse tables fail rather than quietly becoming report-only. TDT/TOT remains
informational because its content follows wall-clock time; `--strict` grades it
as well. `--source` also requires the source's SI tables and PAT-declared PMTs, catching loss on both legs. These checks do not diagnose a process timer from cadence alone.

| Option | Meaning |
|---|---|
| `--min-agreement` | percent of shared emission points required per table (default 90) |
| `--min-emissions` | a table with fewer emissions in the overlap is reported, not graded (default 8) |
| `--min-window` | seconds of shared media required before any verdict is given (default 20) |
| `--strict` | fail on report-only tables too |
| `--report-json` | write the full report |

`--min-window` exists because a capture that came up short is the commonest way
this grades clean: too little shared media puts the slower tables under the
emission floor, and a table reported without a verdict reads as a pass. The
window is taken from the media the two captures carry, **not** from the
emissions being scored — deriving it from the emissions is itself a false pass,
since a leg that stops emitting a table halfway through would pull the upper
bound back to its own last emission and score its desertion as 100 %.

Two things are deliberately not graded. A table seen on only one leg is reported
without a verdict, because that is a carriage question rather than an anchoring
one. TDT/TOT is report-only whatever its agreement, since it carries wall-clock
time and is *supposed* to track a clock rather than the media.

Where both legs run the same period at different phase, the report says so
rather than leaving a percentage to interpret:

```
FAIL SDT/BAT 10 10 19 1 5.26%
both legs emit every 2.000s, 0.480s out of phase
-> a timer started with the exporter, not an anchor in the media
```
| `--min-agreement` | Required percentage of matched emissions (default 90) |
| `--min-emissions` | Required emissions per leg and table (default 8) |
| `--min-window` | Required seconds of acquired shared clock (default 20) |
| `--source` | Require the source's SI tables on both legs |
| `--strict` | Grade TDT/TOT too |
| `--report-json` | Save the window, tolerance, counts, and verdicts |

`just test ts-pair-controls` runs deterministic transport fixtures through the
actual grader. Identical streams, different PES interleave, late acquisition with
bootstrap tables, and PCR wrap must pass. Persistent phase shifts, accumulating
drift, disappearing/absent/sparse tables, and insufficient shared media must fail.
Controls run in PR CI; the real pair runs nightly and on manual TS validation.

## Open GOP (`open-gop.py`)

Expand Down
3 changes: 2 additions & 1 deletion test/ts/run.sh
Original file line number Diff line number Diff line change
Expand Up @@ -510,7 +510,8 @@ if [[ -n "$PAIR" ]]; then
fi
echo "### captured $(wc -c <"$SUB_TS" | tr -d ' ') + $(wc -c <"$SUB_B_TS" | tr -d ' ') bytes -> comparing table anchors"
echo
if ! python3 "$DIR/table-anchor.py" "$SUB_TS" "$SUB_B_TS" $STRICT \
if ! python3 "$DIR/table-anchor.py" "$SUB_TS" "$SUB_B_TS" --source "$SRC_TS" \
--report-json "$HARNESS_RUN/table-anchor.json" $STRICT \
${PASSTHRU[@]+"${PASSTHRU[@]}"}; then
echo >&2
echo "error: table anchor analysis failed (see round-trip logs below)" >&2
Expand Down
Loading
Loading