Accepted-image capture timing evidence
capture_timing schema 1 records source images a particular encoder session accepted and successfully converted. It is separate from the frozen vrr request and policy object. Neither changes pacing, encode timestamps, transport timestamps or receiver behavior. Source-time eligibility and effective VRR remain false; no source_cadence is emitted.
A shared capture producer can feed several matching consumers. Each consumer counts its own accepted subset. Images skipped before acceptance, repeated retained images, input-only loops and encoder probes contribute no observations. Watch consumers can observe their own images; their watch_or_input_only policy remains authoritative and grants no pacing authority.
Each successful display open or reopen gets a new nonzero capture epoch. Logical app-launch generation, capture epoch and encoder-session generation have different roles. The image carries its producer generation, epoch, sequence, route, ready time, raw presentation value/status, initialization-prefetch flag, immutable clock proof and per-frame source-time observation. Pool reuse clears the whole provenance; compatibility clones and frame construction copy it as a unit. Changing the current display cannot rewrite a retained frame’s or conversion clone’s evidence.
One atomic session-store write accepts a new image. Missing epochs/sequences, unknown or retired sessions, old epochs, duplicate/regressing sequences and changed generation/route/proof within an epoch are refused. Unknown mapping results and contradictory result, route, protocol, proof or observation fields are also refused. Refused writes do not advance evidence. The consumer retains its latest unpublished accepted snapshot and retries publication from existing encode iterations, so late registration can recover even while a static source produces only repeat encodes. The repeats add no observations. A new epoch starts accepted counts over. Teardown freezes the ending consumer’s value snapshot; later sessions and late writes cannot rewrite it. Until an accepted observation is published the object is absent.
Public clients[] and last_session use stream_instance_id and a process-scoped capture_instance_id. Process-local counters can form part of these opaque identifiers; clients must not interpret them as standalone generations or epochs. Public records omit numeric generation/epoch fields, source sequence, absolute times, process identities, private paths and namespace identifiers. Authenticated /polaris/v1/session/status diagnostics return only the requester’s own generation and may retain numeric generation/epoch, source sequence and raw presentation time for debugging. This separate capture_timing object remains available while Doctor is disabled or collecting and does not change its grading. It never substitutes another stream’s evidence or host-wide presentation counts.
The same authenticated response serves the requester’s own frozen vrr record as optional vrr, declared as session_vrr and session_vrr_host_pacing in docs/nova-contract.json. It is the record Doctor v2 is handed, carries the response’s session_generation, and is served while Doctor is disabled or collecting. It is absent when that stream has no record; another client’s, a Watch row’s or an ended session’s record never stands in. host_permission is permission rather than proof. effective and host_pacing.fresh require a host source-time sample at most two seconds old, and the receiver presentation and physical acceptance fields stay false.
The route is unknown, fixed_interval or source_driven; presentation clock is none or ext_image_copy_monotonic. Other capture routes retain missing presentation metadata. presentation_counts describe protocol syntax. plausibility_counts retain the coarse outcomes valid, missing, invalid, nonmonotonic, future, stale, before_epoch, prefetched_init and clock_unverified. Comparable-time outcomes come from the producer’s per-frame observation, rather than repeating a comparison against an old epoch proof. A protocol-valid time without that observation remains clock_unverified, even when the historical clock proof passed.
source_time has scope per_frame_observation. It reports a fixed result, mapped_available, per-result result_counts, and uncertainty_ns only for a mapped observation. Mapping requires matching epoch proof, verified producer and namespace, a then-current compositor lease, a fresh bounded local clock bracket, ready-time evidence, plausible time and strict source monotonicity within the epoch. A mapped observation records a past event; it grants no current lease or pacing authority. Absolute mapped and observation times stay out of public diagnostics and ended-session records.
The compositor’s monotonic presentation time maps to local steady time by adding the measured steady-minus-monotonic offset. Each new frame checks a fresh bracket against the epoch mapping. Default bounds are 20 microseconds for the live bracket, 50 microseconds for offset drift and 150 microseconds for combined uncertainty. Checked arithmetic and clock-duration representability failures refuse mapping. Stale means older than ready time by 100 milliseconds plus that frame’s uncertainty; future means later than ready time plus uncertainty. These are mapping evidence bounds, not stream-health or bitrate thresholds.
Initialization-prefetched images remain ineligible. Repeats and timeouts produce no new observation. An in-epoch capture-protocol reset cannot erase the producer’s last mapped source baseline: a backwards or equal timestamp is regressed_in_epoch and appears as coarse nonmonotonic. A new display epoch starts a new baseline. Missing ready time is ready_unavailable and coarse missing, distinct from a missing protocol time. Live lease failure, clock drift and unverifiable proof gates remain coarse clock_unverified; their detailed reason stays in source_time.result.
The Linux probe reads SO_PEERCRED from the actual connected Wayland socket. It checks process starttime before/after, compares repeated opened time-namespace descriptors by device and inode, and samples a bounded steady/CLOCK_MONOTONIC mapping. Missing, denied, unstable or mismatched observations fail closed. Socket credentials identify the socket peer and cannot by themselves establish the compositor’s identity.
For an owned labwc capture generation, the supervisor can hand off the exact child compositor’s pidfd after proving that its exec succeeded. The host verifies the supervisor’s credentials on that message, the descriptor’s kernel process identity, and the child’s parent/starttime facts. The retained lease binds the exact runtime instance and pinned Wayland socket object. Any attempted output mutation retires its authority, even when that operation fails or returns to the previous mode. Runtime retirement, observed socket replacement or process exit also removes authority permanently, even while a capture reader retains the descriptors. The collector checks that lease before and after reading the same peer facts used for namespace comparison. Only an exact peer match, equal time namespaces, a valid bounded clock mapping and a valid epoch can verify clock comparison. Unsupported or unavailable identity evidence remains unverified and does not prevent ordinary stream startup.
Public clock.producer_identity_reason is an additive schema 1 field. It contains only a fixed policy name: not_probed, no_authoritative_compositor_identity, compositor_generation_unavailable, compositor_generation_changed, compositor_identity_invalid, compositor_peer_pid_mismatch, compositor_peer_uid_mismatch, compositor_peer_starttime_unavailable, compositor_peer_starttime_mismatch, or authoritative_compositor_peer_matched. Unknown strings become identity_reason_unavailable; process identities, paths and arbitrary runtime strings are never copied. The existing clock.reason remains the aggregate epoch clock gate result. The clock object has scope capture_epoch_observation; its verified fields describe collection at epoch open, rather than current lease authority. Neither reason authorizes pacing.
clock_domain_verified, protocol-valid counts and observed source-driven capture never establish source-time encoding, physical VRR, device-visible picture/audio/controls or receiver presentation. Those require separate future implementation and hardware acceptance.