feat: viz-plane ingestion contract + benchmark suite (I1–I7)

[rxdu]

Summary

Defines and measures the viz-plane ingestion contract — the third stage of the XMotion observability chain (telemetry S1 → messaging M9 → viz), held to the same measured-claims discipline. Reference bar: hebi-charts-class low-overhead ingestion — the robot must not be able to tell it is being watched.

• docs/ingestion_contract.md — normative requirements I1–I7: bounded per-sample cost, alloc-free steady state, producer-never-blocks with counted overflow, render-rate independence, observer invisibility, bounded memory, measured claims. Includes the ingestion-path map (RingBuffer/BufferRegistry → RtLinePlotWidget; DataStream/DoubleBuffer → SceneManager, with file:line refs), a budget table pinned from the first run, and a conformance table.
• tests/benchmarks/ingestion/ + scripts/bench_ingestion.sh — percentile harness (p50/p99/p99.9/max), alloc-gated measured sections, hardware-context JSON, smoke ctest. Zero src/ changes — the suite drives public API only.

First numbers (i7-8700, xvfb/llvmpipe)

Ring write p50 21.6 ns / p99 43.8 ns · stream push p50 10.3 ns · 100 kHz paced ingest invariant across headless / 60 fps / stalled render (producer-never-blocks proven) · 60 s @ 100 kHz soak: RSS growth 0.

Conformance verdict

Req	Status
I1 cost, I4 render-independence, I6 bounded memory	conform (≥2× budget margin)
I3 never-blocks	proven — but all drop/overwrite paths are silent and uncounted (principal gap)
I2 alloc-free	POD proven; no slot pre-sizing for heap-owning payloads
I5 observer invisibility	pending hardware-GL rerun (llvmpipe software rasterization competes for cores and confounds the A/B)
I7 measured claims	suite + pinned JSON done; CI regression gate not yet wired

Remediation list (ordered)

1. Overflow/overwrite/refusal counters on RingBuffer/DoubleBuffer (I3 — silent loss is unobservable today)
2. CI regression gate vs pinned reference (I7)
3. DataStream/DoubleBuffer slot pre-sizing for heap payloads (I2)
4. Optional seqlock latest-slot for the scene path if a payload profile ever breaches budget
5. Re-run the observer A/B on hardware GL to pin the invisibility number (one command on a real display: ./scripts/bench_ingestion.sh)

Test plan

• Full build clean; 123/123 tests pass (serial, xvfb) incl. new smoke bench
• Bench JSON parses; alloc gates 0 in every measured section
• Reproduced by supervisor: independent smoke run, 16 benchmark rows