feat(gateway): relay complete encoded frames

2026-07-30 22:47:48 +07:00
parent f12ed6c685
commit 786c96b110
22 changed files with 1023 additions and 159 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-30
@@ -0,0 +1,26 @@
+## Context
+
+The current harness sends one fixed 1,179-byte payload per logical sample. It reaches the production path but does not represent encoded frames at 60/120 FPS or exercise realistic fragmentation, reassembly, queue bytes, and keyframe pressure.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Deterministically generate complete variable-size frame units at exact profile frame rates and target bitrates.
+- Include bounded periodic keyframes while preserving exact aggregate bytes.
+- Measure the existing production path and independent reassembly with frame-level accounting.
+
+**Non-Goals:**
+
+- A real encoder, codec parsing, a second simulator, or a normative run before immutable Protocol publication.
+
+## Decisions
+
+- Derive bytes per fixed interval from bitrate and FPS, distribute integer remainder deterministically, and shift bounded bytes into periodic keyframes while keeping the interval total exact.
+- Carry a deterministic frame index/pattern only in the generated payload bytes; no codec semantics are claimed.
+- Keep the existing path/impairment/resource driver and change its unit from datagram payload to complete frame.
+
+## Risks / Trade-offs
+
+- [Keyframes can exceed queue budget] → use the reviewed 1 MiB frame ceiling and production byte-bound queue.
+- [Short smoke windows have rounding effects] → assert exact generated totals and report measured duration separately from normative ten-minute gates.
@@ -0,0 +1,24 @@
+## Why
+
+The existing fixed-profile harness treats each 1,179-byte datagram as an encoded frame, so its reported frame rate, frame boundaries, bitrate, queue pressure, and processing evidence do not model the named 60/120 FPS profiles.
+
+## What Changes
+
+- Generate deterministic variable-size encoded frame units at the named frame rates and target bitrates, including bounded keyframes.
+- Traverse native Apollo recovery, production queues, the production pacer, QUIC framing, and independent reassembly.
+- Assert frame count/rate, bitrate, exact bytes and boundaries, clean loss attribution, latency, and resource bounds.
+- Keep short smoke tests separate and leave all prior normative artifacts unchanged.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `gateway-qualification`: Fixed-profile evidence measures complete encoded frame units rather than one datagram per frame.
+
+## Impact
+
+The existing qualification harness and canonical qualification specification only. No codec operation, production dependency, or normative run before immutable consumer publication. Requirements: P3C-002, P3C-008, P3C-029, P3C-030, P3C-033, VER-009, VER-010, OPS-015.
@@ -0,0 +1,12 @@
+## 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, byte/count/latency-bounded production queues, the production fair pacer, Protocol complete-frame fragmentation, Verse framing/QUIC, and an independent bounded client reassembler for 1080p60 H.264 at 20 Mbps, 1440p120 HEVC at 50 Mbps, and 4K60 HEVC at 80 Mbps. The source fixture SHALL emit deterministic variable-size complete encoded frame units at the named 60/120 FPS rate, preserve exact target bytes over each fixed interval, and include bounded larger keyframes without codec operation. After a recorded warm-up, the frozen candidate SHALL run each profile for ten wall-clock minutes, preserve every frame's bytes and boundary, retain every monotonic processing sample plus bounded provider-queue observations, and report frame count, frame rate, bitrate, 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-frame 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 or boundary mutation, frame-rate/count mismatch, 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 frame/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-frame observation, stage accounting does not balance, payload or frame boundaries change, duration, frame-rate, frame-count, 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
@@ -0,0 +1,19 @@
+## 1. Red fixed-profile model
+
+- [x] 1.1 Add deterministic frame-count, frame-rate, bitrate, keyframe, byte-total, and boundary regressions
+- [x] 1.2 Prove the current 1,179-byte one-frame model fails the required profiles
+
+## 2. Production-path qualification
+
+- [x] 2.1 Replace packet payload generation with bounded variable-size complete frame units
+- [x] 2.2 Carry frame-level source, recovery, queue, QUIC, delivery, and loss attribution through the existing path
+- [x] 2.3 Assert frame rate/count, bitrate bounds, exact bytes/boundaries, processing latency, and resource bounds
+
+## 3. Verification
+
+- [x] 3.1 Run short production-path smoke tests for all three profiles and affected impairment accounting
+- [x] 3.2 Validate the active OpenSpec change strictly
+
+## 4. Frozen qualification
+
+- [ ] 4.1 Run the single normative Section 7 qualification after immutable Protocol consumer resolution