The fixed-GOP promise is stamped into provenance as "actually used" but is never measured on pass-through video

[Sagar-024]

Current behavior

FORMAT.md item 5 promises Fixed GOP (keyint = min-keyint, scenecut=0): "keyframes land exactly every gop_frames messages, so seek cost is uniform and predictable" (docs/FORMAT.md:79), and the presets section calls GOP length "effectively a training hyperparameter" (docs/FORMAT.md:84). The provenance record stamps gop_seconds, defined at docs/FORMAT.md:129 as "The keyframe interval actually used."

On the re-encode path the promise is real: x264 gets keyint=min-keyint=gop_frames, scenecut=0, and _enforce_encode_guarantees refuses any keyframe that lands off the grid (expected {keyframe_expected} (gop_frames={gop_frames}), src/hflow/video.py:683).

On the pass-through path nothing measures it:

• _validate_passthrough_video_payload (src/hflow/transform.py:479) checks one access unit per message, SPS/PPS on keyframes, first-message keyframe, and B-freedom. Cadence is not checked.
• _check_video_payload (src/hflow/doctor.py:96) checks the same two keyframe properties (SPS/PPS at :174, first message at :180) and never the interval between them.

The provenance record is written once per episode, identically for both paths (src/hflow/transform.py:895-896), so a pass-through episode is stamped with the configured interval no matter what its stream contains.

Controlled result

A 100-message pass-through source, conforming by every existing rule (AUD-first, one access unit per message, SPS/PPS on every keyframe, first message is a keyframe, zero B-frames), with keyframes deliberately placed off the grid. The transform accepts it, and every video check in the doctor passes (the only finding is the optional missing-episode-record warning):

doctor conforming:      True
provenance stamp:       gop_preset='vla' gop_seconds='1'
keyframe positions:     [0, 7, 8, 90, 91]
actual spacing:         [7, 1, 82, 1]
promised spacing:       every 30 messages (gop_seconds=1.0 at 30 fps -> gop_frames=30)

The file carries a provenance record asserting a 1.0 s keyframe interval ("actually used") while its real spacing is 7, 1, 82, 1, and hflow doctor reports it as conforming. Consumers following the vla read pattern ("a keyframe seek per sample") see a 12x swing in seek cost between neighboring windows, and the record that would tell them says 1.0 s.

Why now

#373 closed this family for B-frames: a stated FORMAT.md constraint is now checked in doctor and asserted by the encoder. Fixed GOP is the remaining constraint with no check anywhere, and the only one whose provenance field asserts a measurement. The per-message NAL walk that #354/#358 made cheap already yields is_keyframe per access unit, so measuring cadence rides an existing pass rather than adding a new one.

What to build

Open call, not assumed:

1. Refuse: SourceNotConforming (as B-frames are) when pass-through keyframe spacing deviates from the stamped interval. Risk: pass-through cannot be re-gridded without transcoding (v1 refuses), so this may reject real recordings.
2. Measure and stamp: stamp the measured interval, keeping configured and measured distinguishable. Provenance semantics change, so per the rule stated on Improve camera_frame_stats cold throughput on 1080p video without weakening per-frame evidence #365, cache/provenance identity must move with it.
3. Doctor finding: a new code (for example video-keyframe-cadence) reporting measured spacing against the stamped interval, leaving refusal policy to callers.

Any combination (measure always, refuse on gross deviation) is also plausible.

Definition of done

1. Pass-through keyframe cadence is measured from the access units the transform and doctor already walk.
2. Provenance never asserts an unmeasured interval: either the stamp reports the measurement or the deviation is reported.
3. Cadence deviations surface with a documented finding-code row.
4. The re-encode path is unchanged: the encoder still enforces and asserts the grid.
5. Existing conforming fixtures are unaffected; the fixture above lands as a test.

Non-goals

• Transcoding pass-through video
• Changing the GOP presets or BENCHMARKS.md
• New doctor severity levels

Validation

uv run ruff check --fix
uv run ruff format
uv run ty check
uv run pytest -q tests/test_transform.py tests/test_doctor.py tests/test_video.py
uv run pytest -q

[Sagar-024]

Taking this if accepted. The doctor side rides the same walk my #373 checks use, and the fixture above is a test waiting to land.

[kstonekuan]

Accepted and confirmed, labelled bug / advanced. The finding is exactly right, and the code says so plainly:

transform.py:696   gop_frames = max(1, round(gop_seconds * fps))   <- inside the re-encode branch only
transform.py:896   "gop_seconds": f"{gop_seconds:g}"               <- written for every episode, both paths
doctor.py:170,176  keyframe checks are SPS/PPS and first-message-is-keyframe. No spacing anywhere.

So gop_seconds on a pass-through episode is the configured value copied into the record, and "the keyframe interval actually used" is only true on the path that enforces it. Your 7, 1, 82, 1 fixture is a file that passes every existing rule while its provenance asserts 1.0 s.

Framing this as an open call rather than assuming a fix was the right instinct, so I am leaving it open deliberately rather than picking now. What makes it a decision and not a patch:

• Refusing is the consistent-with-B-frames answer, and pass-through exists precisely because re-encoding is what the caller is trying to avoid. A refusal cannot be worked around without transcoding, so it turns "we accept your conforming recording" into "we accept it if your encoder used our grid". That may be correct, but it narrows what pass-through means.
• Measuring and stamping is the honest-record answer and changes what a provenance field means. Per the rule I stated on Improve camera_frame_stats cold throughput on 1080p video without weakening per-frame evidence #365, provenance identity has to move with it, which means a version bump on the canonical format and every cached canonical becoming non-matching. Worth doing, not worth doing casually.
• A doctor finding alone is cheap and leaves the record still asserting something unmeasured, which is the actual complaint.

Please do not start implementing until this issue names one. The measurement is the valuable part and it is already done; picking wrong here costs more than the wait.

One thing worth adding to the record while it is open: whether a real-world conforming pass-through source (Egocentric-10K through the direct-H.264 adapter from #334, say) actually holds a fixed grid. If real recorders do keep cadence, option 1 is cheaper than it looks. If they do not, option 1 is off the table. That is a measurement, it is the kind you are good at, and it would settle the choice rather than argue it.

[Sagar-024]

Understood. Holding implementation. I'll measure Egocentric-10K through the #334 adapter to see if real pass-through sources hold a fixed grid, and post the data here to settle the refusal-vs-stamp choice. @kstonekuan

[Sagar-024]

The measurement you asked for, run against the corpus this repo already trusts: nominal-io/xplane-mcap (the 24,689-message corpus ensure_access_unit_delimiter was validated on), all H.264 video messages scanned with hflow's own instruments (_annex_b_nal_offsets_and_types, IDR = NAL type 5).

video messages scanned:          24689
messages WITHOUT an AUD NAL:     24689
keyframe-bearing messages (IDR): 103
our IDR count vs the corpus's own video/keyframes channel: 103 vs 103

keyframe spacing (102 intervals):
  spacing values: [39, 52, 65, 113, 130, 229, 231, 234, 248, 250]
  mean 241.09   median 250   min 39   max 250   stdev 37.58
  250 exactly: 93/102 intervals (91.18%)
  off-grid intervals: 9 (39 to 248 messages apart)

Verdict: mixed, and the deviation is real. The encoder's nominal grid is 250 and holds for 91% of intervals, but 9 intervals break it, the tightest at 39 messages: 6.4x shorter than nominal. Our detection is corroborated by the corpus's own 103-message video/keyframes channel, so this is not a detector artifact.

Two facts matter for the decision:

1. Not one of the 24,689 messages carries an AUD. This source is conforming only after the AUD repair path runs, and repair cannot change keyframe positions, so a repaired conforming pass-through stream from this corpus still holds an irregular grid.
2. Option 1 (refuse) would reject it. 9 irregular intervals out of 102 in a real recording that shipped and was used to validate this repo. If real recorders cannot be assumed grid-clean, refusal narrows pass-through to encoders configured exactly like ours, which is the narrowing your option-1 note predicted.

Measurement limitation, stated plainly: this is one corpus from one encoder (flight simulator, constant content type). It answers "does a real repaired pass-through source hold a grid" with no, but a single source is evidence, not a survey. If access to builddotai/Egocentric-10K is granted, the same script measures that corpus too.

My read of the data: option 2 (measure and stamp) fits what real sources do, with the doctor finding carrying the deviation signal. The call stays yours. @kstonekuan