feat(bench): decouple the harness from the engine with served read-only workloads

[azimafroozeh]

What & why

Problem. A benchmark should measure the system as it is deployed. Ours measures a library: omnigraph-bench links the engine in-process, so the only surface with a number is embedded execution on a local file system. The deployed surface, omnigraph-server over HTTP, has none (execution: server is refused at admission), and measuring a new engine revision means rebuilding the harness, because the engine is a build dependency of the bench binary.

Why coupling was the wrong shape. A harness that shares a process with its SUT conflates three things that a black-box benchmark keeps apart: the clock (it stopped at the engine's Arrow batches, not at a request boundary), the provenance (the worker's own build and machine stood in for the server's), and the artifact (a fresh bench build per engine commit instead of the server image CI already publishes). The result measured one surface and had to be rebuilt to measure any new revision.

Solution. The bench becomes an out-of-process client over the public API for read-only workloads: same GQT workloads, same record schema, two execution targets. #923 gave the GQT runner the server target; this PR gives the bench its admission, timing, provenance and records. No engine, server or API change.

• Admission. GqtEnvironment gains the target and network_position axes (embedded serialization unchanged; a served definition must declare network_position). The served program must be idempotent read-only end to end, loop bodies and verification suffixes included; restarts, mutations, loads, settings prefixes and index requirements are refused before any request.
• Timing. One fresh client process per repetition; the server is never seeded, reset or restarted (long-running-server, reset: none). The interval is end-to-end client latency, request serialization through row decoding; warm-up and assertions are outside it.
• Provenance. A typed deployment receipt declares the server's build, artifact digest, backend and dataset witness. Records keep it as declared-deployment beside the observed client build and machine; absent server counters stay null, never zero; every served record is claim_eligible: false. Projection transform 5 separates declared from observed columns.
• Credential hygiene. The bearer token comes from a named environment variable outside the LANCE_ and OMNIGRAPH_ namespaces, travels only on the worker's bounded stdin, is redacted from diagnostics in raw, JSON-escaped and form-encoded spellings; durable evidence stores the SHA-256 of the normalized endpoint.
• Catalog and CI. 16 served twins (query-shapes-served, traversal-served) as separate workload files, measured text byte-identical to the embedded source, the 40 historical point identities unchanged. gqt_served_smoke.rs boots the server binary and runs omnigraph-gqt --server end to end in the served CI cell, which builds with cargo test --no-run so its three steps share one feature world.

Backing issue / RFC

• Implements the served execution surface of RFC 0039 (docs/rfcs/0039-end-to-end-benchmark.md) for read-only workloads; the RFC gains its served exception in this diff.

Checklist

• Focused: served read-only acquisition, one logical change
• Tests: 29 in gqt_served_tests.rs (admission, receipt, endpoint, token, evidence exclusivity, projection, measured HTTP against a local listener); catalog_cli pins the 16 selectors and twin parity; the 40-identity golden unchanged; three served_*.gqt corpus cases pin served rows equal to in-process rows; gqt_server_binary_round_trip runs the CLI end to end
• Public docs: bench README, benchmarks/README.md, docs/dev/testing.md, docs/dev/ci.md, RFC 0039
• Release note: changelog.d/served-read-benchmarks.added.md
• Invariants: none weakened; invariant 13 (evidence matches the boundary) is the one touched, and served records stay claim-ineligible

Local verification

• omnigraph-bench run e2e-query-count-served --server … --graph … --server-receipt … --server-token-env … --repetitions 3, release client against an unmodified release server built from 980498d6, same host, local FS: three repetitions on three fresh client PIDs, server alive throughout, receipt hashes equal in every sample, no token in retained output. Diagnostic run, no archive written.
• cargo tree -e features -i omnigraph-cluster with and without no-dev: dev-dependencies add failpoints and test-util, hence cargo test --no-run in the CI cell rather than cargo build --bins.

Notes for reviewers

• Server provenance is declaration, not attestation: the public API cannot prove build or artifact facts, so served records are declared-deployment and never claim-eligible. Kept to avoid a new API.
• Served and embedded intervals have different boundaries (request vs Arrow batches) and are never pooled.
• PROJECTION_TRANSFORM_VERSION 4 → 5: an existing projection is refused and rebuilt from the archive; record format and historical bytes unchanged.
• Receipts admit local-fs only; the S3-rooted server is a later phase. Explicit --dataset/--queries pairs refuse --server.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	⚠️ Failed 2026-10-10T14:02:05.146633Z	dd7d2dc	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.