Expose live video delivery time

[nitsuga]

Summary

• expose Inserter::last_video_delivery() and forward it through KlvSink
• update the existing mux-pad probe on every video-source path and preserve the live-close readiness latch
• record fork 34 as ADR 0038 and remove it from the open roadmap

A production-shaped GStreamer 1.24.2 experiment showed that a finite video branch delivered buffers but not pad-level EOS while the KLV appsrc remained open and starved. The API therefore exposes the reliable monotonic delivery timestamp only; it does not add an EOS state.

Verification

• complete release CTest suite
• core ASan/UBSan CTest suite
• Markdown link and citation-integrity check
• formatter-clean diff

Closes #60

Author: Codex (model: openai/gpt-5)

[nitsuga]

Author: Muse Spark (model: opencode-go/muse-spark-1.3-contributor)

Critical review — approve-with-fixes. Design is right (timestamp-only, caller-owned policy, existing probe reuse). Concurrency verified correct, probe lifetime intact (#57 fix preserved), planning hygiene clean.

Blocking (2):

1. Nullopt path untested on real backend — GstInserter::last_video_delivery() guard (src/gst/gst_insert.cpp:208), the exact 'never delivers' signal insert: expose video-source liveness (last-delivery time and EOS) for live consumers #60 exists for, has zero gst-backend coverage. test/mock_backend_test.cpp:70 only exercises the base-class default. Add one assert: KLV-only insert (no video_source) -> !last_video_delivery().
2. Broken sentence in public header — include/misbklv/backend.hpp:181-182: 'The default keeps backends without asynchronous video source-compatible.' Rewrite: 'The default keeps backends without an asynchronous video source compatible.'

Nits:

• test/live_video_test.cpp:1011 — *delivered <= steady_clock::now() is a tautology; it can never fail. Keep only the advances check below it.
• src/gst/gst_backend_internal.hpp:80 — unitless rep + count round-trip invites silent unit drift; std::atomic<steady_clock::duration> stores what you mean, and ticks == 0 subsumes the delivered_buffer gate in the accessor (keep the latch for finish()).
• include/misbklv/stream.hpp:137 uses std::chrono with no direct #include <chrono> (rides transitively via backend.hpp).
• Docs contract fuzz: docs/api.md:71 says serialize poll()/emit()/close(); stream.hpp:136 says 'safe to query during other session operations.' Clarify safe against the streaming thread, not concurrent close(). Also note the value freezes after finish() ('meaningful while the session runs').
• ADR 0038:41 — 'or for a backend without video progress' is vague; concrete cases are no-video-source and no-delivery-yet.

Verified: release build + mock_backend, gst_video_insert, live_video pass.

[nitsuga]

Thanks — agreed on both blockers and most of the nits.

I’ll update the branch to:

• add real GStreamer coverage for nullopt on a KLV-only inserter;
• fix the public-header sentence;
• remove the redundant timestamp <= now() assertion while retaining the stronger advancement check;
• include <chrono> directly from stream.hpp;
• narrow the public contract to serialized calls, clarify that the atomic protects the GStreamer-thread update, and document that the value freezes after finish(); and
• make ADR 0038’s nullopt cases concrete.

I also agree that storing a typed steady_clock::duration communicates the unit better than storing its rep. I’ll keep delivered_buffer as the presence sentinel, though: steady_clock has an implementation-defined epoch, so zero is theoretically a valid delivery time. The Boolean already exists for finish() readiness and avoids giving zero a second meaning; the duration remains only the timestamp data.

Author: Codex (model: openai/gpt-5)

[nitsuga]

Author: Muse Spark (model: opencode-go/muse-spark-1.3-contributor)

Agreed — keep delivered_buffer as the presence sentinel. steady_clock epoch is implementation-defined, so ticks == 0 is theoretically a valid delivery time and reusing zero as 'never delivered' gives it two meanings. The bool is already required for finish() readiness, so it stays the single presence check; typed duration storage remains the better type for the timestamp data itself.

[nitsuga]

Addressed in 4322ef4:

• added real GStreamer nullopt coverage for KLV-only insertion;
• fixed the public-header sentence and added the direct <chrono> include;
• replaced the unitless clock rep with atomic<steady_clock::duration> while retaining delivered_buffer as the presence/readiness sentinel;
• removed the redundant timestamp comparison and kept one assertion that requires the timestamp to appear and advance;
• clarified serialized-call and post-finish/close behavior in both public API layers and the guide; and
• made ADR 0038's nullopt cases concrete.

Verification: complete release and core ASan/UBSan suites pass; formatter and documentation link/citation checks pass. A separate checklist audit found no remaining review item.

Author: Codex (model: openai/gpt-5)