fresnel-fourier/phase4_iter9_plan.md

Iteration 9 — Phase 4 (plan)

The Phase 0 doc lays out α-7 in detail. Phase 4 just locks the implementation contract for Phase 6.

Implementation contract

File: src/picture.c::RequestEndPicture (line 440 area).

Change: replace

gettimeofday(&surface_object->timestamp, NULL);

with a monotonic per-context counter that produces small ns values.

State storage: driver_data->timestamp_counter (u64). Init to 0 wherever request_data is first set up (likely request.c::v4l2_request_init).

Counter cadence: increment by 1 (just enough to keep each frame's timestamp unique). For 3-frame test: ts will be 0, 1, 2 — followed by v4l2_timeval_to_ns returning 0, 1000 (since 1 µs = 1000 ns), 2000 ... wait, struct timeval is sec + usec. Mapping a counter to timeval:

driver_data->timestamp_counter++;
surface_object->timestamp.tv_sec = 0;
surface_object->timestamp.tv_usec = driver_data->timestamp_counter;

This gives tv_usec=1,2,3,... → v4l2_timeval_to_ns(tv) = tv_usec * 1000 = 1000, 2000, 3000, .... Matches kdirect's 0x2af8 = 10968 style.

For long runs (>~71 minutes at 1000 fps), tv_usec wraps. Each wrap is a uniqueness collision risk. Mitigation: increment tv_sec on wrap. Code:

driver_data->timestamp_counter++;
surface_object->timestamp.tv_sec = driver_data->timestamp_counter / 1000000;
surface_object->timestamp.tv_usec = driver_data->timestamp_counter % 1000000;

This is collision-free for u64 / 1e6 ≈ 5.84 × 10^11 seconds = ~18,500 years of decode. Future-proof.

LOC: ~10 (counter init in request.c + 4-line replacement in picture.c + new field in request.h).

Verification (Phase 7)

1. Build + install on fresnel.
2. Run libva H.264 sweep. Hash against kdirect's 1e7a0bc9….
3. Re-strace and confirm DPB.reference_ts is now small (~1000-3000) matching kdirect's pattern.
4. Run 5-codec regression sweep. All 4 non-H.264 anchors must hold.

Risks recap (from Phase 0)

• R-1 uniqueness: counter wraps in 18,500 years — non-issue.
• R-2 regression on VP9/MPEG-2/HEVC/VP8: change is uniform across codecs; same path. VP9/MPEG-2 currently PASS — switching to counter should be neutral or improve.
• R-3 consumer reads ts as wallclock: VAAPI surfaces don't expose timestamps to consumers.

Phase 5 review

Quick review by the same reviewer agent. Key questions:

• Does any other backend code read surface_object->timestamp as a real wallclock?
• Does the V4L2 framework do anything weird with timeval vs u64 ns conversion that could cause libva's gettimeofday-based ts and DPB.reference_ts to actually differ at the kernel observation point? (Critical for M-C hypothesis.)
• Is there an even simpler reason giant ns fail — e.g., a 32-bit truncation in the V4L2 buffer struct itself?