fix(gateway): isolate qualification evidence

openspec/changes/correct-gateway-qualification-evidence/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-30

openspec/changes/correct-gateway-qualification-evidence/design.md

@@ -0,0 +1,31 @@
+## Context
+
+The qualification driver already reaches the production Apollo-to-QUIC path, but its source shaper reorders jitter even when reorder is disabled, its packet accounting cannot identify unexplained loss, and in-process resource counters include the provider/client driver.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Attribute every source unit to one bounded production-path outcome.
+- Keep impairment axes independently configured and observed.
+- Sample CPU, heap, allocation, and goroutine use from the gateway process only.
+- Record measured monotonic-clock overhead.
+
+**Non-Goals:**
+
+- No second simulator, profiling service, production dependency, or expanded impairment matrix.
+- No larger queues or relaxed acceptance limits without measured need.
+
+## Decisions
+
+- Reuse the existing source-boundary shaper, preserve source order unless explicit reorder is enabled, and limit catch-up to one media serialization interval. Record the fixed-seed applied-delay standard deviation separately from the jitter observed after ordered traversal.
+- Assign stable source sequence identifiers and retain per-stage counts so injected loss, provider/FEC drop, queue replacement, QUIC failure, and client miss are disjoint.
+- Reuse the established gateway child-test pattern for the actual gateway server; the Apollo fixture and QUIC client remain in the parent driver. A token-protected loopback test control endpoint starts and stops bounded child-owned recording and returns aggregate stage state.
+- Stream queue, processing, and pacing samples from the production `sendMedia` boundary to child-owned raw evidence. Sample child `RUSAGE_SELF`, Go heap, allocations, and goroutines once per second with independent per-run baselines.
+- Measure clock overhead as the median elapsed time per read across 1,000 batches of 100 monotonic reads and record that method.
+
+## Risks / Trade-offs
+
+- [Ordered release suppresses some delivered jitter] → Retain both the applied fixed-seed delay distribution and the separately observed ordered-traversal jitter.
+- [Stage attribution double-counts a unit] → Record one terminal outcome per source sequence and validate accounting equality.
+- [Process sampling perturbs qualification] → Use bounded low-rate samples and include the sampling method in evidence.

openspec/changes/correct-gateway-qualification-evidence/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+RC8 qualification evidence cannot support candidate readiness because clean traffic loses packets without stage attribution, reorder-off jitter reorders traffic, and resource counters include the provider/client driver rather than the gateway process alone.
+
+## What Changes
+
+- Attribute every production-path packet outcome at the source fixture, native provider queue, gateway forwarding, QUIC, and public-client stages.
+- Preserve source order for reorder-off profiles while retaining configured latency and jitter; inject bounded reorder only when enabled.
+- Measure gateway CPU, heap, allocations, and goroutines from the gateway process only, with isolated per-profile counters.
+- Measure and record bounded nonzero monotonic-clock overhead using a batched method.
+- Retain the existing six-profile matrix and real provider-to-public-client traversal.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `gateway-qualification`: Require attributable clean-path delivery, independent impairment axes, gateway-process-only resource evidence, and truthful timing-overhead evidence.
+
+## Impact
+
+P3C-002, P3C-026, P3C-028, P3C-029, and P3C-033; the GPL Data Plane qualification driver, production gateway subprocess boundary, raw evidence, and append-only Phase 3C-G evidence. No Protocol wire contract, provider route, transcode path, or closed Server dependency is introduced.

openspec/changes/correct-gateway-qualification-evidence/specs/gateway-qualification/spec.md

@@ -0,0 +1,27 @@
+## MODIFIED Requirements
+
+### Requirement: Fixed media processing qualification
+The qualification harness SHALL drive pinned-mTLS Apollo management, encrypted RTSP, ENet, and provider UDP through native source validation, `readUDPMedia`, recovery/FEC, bounded production queues, the production fair pacer, Verse framing/QUIC, and a public or independent client decoder for 1080p60 H.264 at 20 Mbps, 1440p120 HEVC at 50 Mbps, and 4K60 HEVC at 80 Mbps. After a recorded warm-up, the frozen candidate SHALL run each profile for ten wall-clock minutes, preserve encoded payload bytes, retain every monotonic processing sample plus bounded provider-queue observations, and report count, min, median, p90, p95, p99, max, mean, standard deviation, measured batched monotonic-clock overhead and method, and observed bitrate. Processing begins at complete provider-unit receipt and ends at QUIC handoff, excluding client transit and pacing. Queue delay SHALL measure provider-queue residence, processing SHALL measure gateway work before pacing, and pacing delay SHALL measure scheduler waiting. CPU, heap, allocations, and goroutines SHALL be measured from the isolated gateway process only; CPU SHALL be actual OS user plus system consumption and MUST NOT include idle wall capacity or unrelated parent fixture/client work. Successive profiles SHALL use independent resource-counter baselines. Any bypass, payload mutation, wall-duration violation, bitrate outside both lower and upper bounds, unexplained clean-path loss, zero or unbounded clock overhead, or p95 above 5 ms SHALL fail.
+
+#### Scenario: Healthy fixed profile
+- **WHEN** a frozen candidate runs one fixed profile for the normative duration in the isolated qualification command
+- **THEN** the harness emits compressed raw path and gateway-process resource samples plus a summary tied to the exact command, CPU scope, timing-overhead method, topology, source commit, immutable Protocol version, environment, and payload hash
+
+#### Scenario: Processing gate failure
+- **WHEN** any production path stage lacks a per-traversal observation, stage accounting does not balance, payload integrity fails, duration or bitrate bounds fail, measured p95 exceeds 5 ms, parent work changes gateway CPU, idle capacity is reported as consumed CPU, or timing overhead is absent
+- **THEN** the qualification command exits unsuccessfully without recording a passing candidate
+
+### Requirement: Bounded impairment qualification
+The harness SHALL run exactly the baseline, latency, jitter, loss, reorder, and constrained Section 7.2 profiles once by applying fixed-seed impairment at the source-shaped provider network boundary while traffic concurrently traverses the production gateway path. Baseline SHALL cover all three media profiles and the other profiles SHALL cover 1080p60. The harness MUST NOT serialize a complete provider-to-client traversal per source unit. Reorder-off profiles SHALL preserve source order through an ordered delay queue whose catch-up is limited to one media serialization interval; the fixed-seed applied-delay distribution and jitter observed after ordered traversal SHALL be reported separately. Loss-only traffic SHALL NOT gain implicit reorder. Reorder-on profiles SHALL inject and record only the fixed bounded reorder pattern. Each source unit SHALL have one attributable outcome across source emission, injected drop, native provider/FEC handling, bounded queue replacement, gateway forwarding, QUIC send/receive, and public-client delivery. Each artifact SHALL retain raw impairment and queue observations and record tool version, exact command/configuration, environment, candidate commit, immutable Protocol version, direction, queue discipline, topology, fixed seed, observed one-way latency, acknowledged Apollo ENet RTT, applied and observed jitter, injected and unexplained loss, reorder, throughput, drops, and capacity-step statistics.
+
+#### Scenario: Complete six-profile run
+- **WHEN** the frozen candidate runs impairment qualification
+- **THEN** one result exists for each named profile, configured and observed impairment axes remain separately attributable, reorder-off profiles preserve source order, RTT comes from real request/response acknowledgement timing, and raw statistics come from actual traversal
+
+#### Scenario: Clean production traversal
+- **WHEN** 10,000 source packets traverse a zero-loss baseline profile
+- **THEN** stage accounting identifies every packet and fails on any unexplained loss while each fixed media bitrate remains within its reviewed healthy-path contract
+
+#### Scenario: Unsupported or unbounded configuration
+- **WHEN** a profile name, packet count, queue bound, loss, reorder, or bandwidth step falls outside the fixed catalog
+- **THEN** the harness rejects it before allocating or running traffic

openspec/changes/correct-gateway-qualification-evidence/tasks.md

@@ -0,0 +1,23 @@
+## 1. Loss Attribution
+
+- [x] 1.1 Add a 10,000-packet production-path regression that records source, injected-drop, provider/FEC, queue, gateway, QUIC, and public-client outcomes
+- [x] 1.2 Reproduce and repair unexplained zero-loss baseline loss without relaxing bounds or hiding drops
+- [x] 1.3 Prove all three fixed baseline bitrates meet the healthy-path contract
+
+## 2. Impairment Semantics
+
+- [x] 2.1 Add fixed-seed regressions for reorder-off jitter, loss-only order, and bounded reorder-on behavior
+- [x] 2.2 Repair the existing source-boundary shaper and retain separately attributable configured and observed axes
+
+## 3. Resource and Timing Attribution
+
+- [x] 3.1 Add child-process regressions proving gateway-only CPU, heap, allocation, and goroutine samples
+- [x] 3.2 Prove parent CPU isolation, idle/work behavior, and independent per-profile counter baselines
+- [x] 3.3 Measure and record bounded nonzero batched monotonic-clock overhead and method
+
+## 4. Verification and Evidence
+
+- [x] 4.1 Run focused production-path, race, fuzz, cancellation, slow-reader, amplification, parser-resource, and bounded soak checks
+- [ ] 4.2 Run strict OpenSpec validation, normal-module verification, and reproducible Linux artifact inspection
+- [ ] 4.3 Freeze all executable inputs and run the corrected normative Section 7 qualification once for the candidate
+- [ ] 4.4 Preserve failed attempts and append superseding evidence and ledger rows without rewriting RC8