test(gateway): bind qualification to immutable Protocol

2026-07-29 23:02:28 +07:00
parent f37f53eab2
commit 040ca73ce9
8 changed files with 100 additions and 15 deletions
@@ -0,0 +1,54 @@
+## Context
+
+P3C-029 through P3C-033 require raw, reproducible processing, payload-rate,
+fairness, cap, and impairment evidence. Existing focused tests cover the
+framer, bounded queues, native Apollo fake, and fair pacer, but do not emit the
+normative ten-minute or six-profile artifacts.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Run the three 20/50/80 Mbps encoded-payload profiles for ten wall-clock
+  minutes each after a recorded warm-up.
+- Measure the existing gateway framing path with a monotonic clock and retain
+  compressed raw latency samples plus full summary statistics.
+- Run the exact six Section 7.2 configurations once using a deterministic,
+  bounded virtual packet discipline and retain configured and observed values.
+- Exercise one real mTLS/QUIC fake-provider traversal for every media profile
+  and reuse the real fair-pacer implementation for fairness and cap evidence.
+
+**Non-Goals:**
+
+- Live Apollo/macOS/firewall qualification, real encoder fidelity, codec
+  processing, host network mutation, or multi-host scale.
+- A production impairment framework, new gateway API, dependency, cgo, or
+  sidecar.
+
+## Decisions
+
+- Implement the harness as an opt-in `go test` in package `gateway`. This
+  keeps qualification access to the actual unexported fair pacer without
+  adding a production API. Normal suites skip the long run unless an explicit
+  absolute evidence directory is supplied.
+- Use wall-clock duration and target-rate pacing for performance profiles.
+  Measure only receive-to-framed-payload processing; pacing wait and raw-file
+  writes stay outside the measured interval and are reported separately.
+- Stream every raw sample into gzip-compressed CSV while retaining one bounded
+  duration slice per profile for exact percentiles.
+- Use a fixed-seed virtual FIFO for impairment. It records no host claim and
+  identifies its queue discipline and deterministic topology explicitly.
+- Treat any payload mutation, p95 above 5 ms, catalog mismatch, fairness error
+  above 10%, cap excess above 5%, or step convergence beyond ten seconds as a
+  hard command failure.
+
+## Risks / Trade-offs
+
+- [Local virtual impairment cannot prove deployed route behavior] → label every
+  artifact deterministic and retain live Apollo/macOS/firewall as
+  deferred-owner-e2e.
+- [Raw samples can be large] → stream gzip output and bound in-memory samples
+  to the exact profile packet budget.
+- [Host load can invalidate latency] → record OS, architecture, Go version,
+  timing overhead, actual duration, packet count, and observed bitrate; fail
+  rather than substitute configured capacity for measured egress.