docs(openspec): archive gateway completion changes

2026-08-10 08:58:46 +07:00
parent 68608a76a2
commit 6264e9c2dc
17 changed files with 96 additions and 36 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-30
@@ -0,0 +1,33 @@
+## Context
+
+`FragmentPayload` currently stops at 16 × 1,179 bytes and the independent test client assumes ordered fragments. Native Apollo output enters count-only buffered channels, so realistic complete frames have neither a byte ceiling nor an explicit residence bound.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Implement Protocol datagram-v2 for complete encoded frames up to 1 MiB.
+- Reassemble bounded duplicate/reordered QUIC datagrams independently.
+- Bound native video queue count, bytes, and residence time while retaining latest-frame replacement and drop telemetry.
+
+**Non-Goals:**
+
+- Codec inspection, retransmission, provider fallback, generic queue/transport APIs, or Server behavior changes.
+
+## Decisions
+
+- Keep the existing `Frame`/QUIC path and add version-aware encode/decode rather than a second transport.
+- Use one sequence per provider frame and the Protocol 1,177-byte fragment size.
+- Keep the existing native video channel at 16 entries, add exact atomic byte
+  accounting capped at 4 MiB, and use per-entry timers for the 250 ms residence
+  bound. This matches the Protocol's reviewed incomplete-unit timeout and covers
+  bounded keyframe serialization; the transport performs a final stale check.
+- Audio and events keep their independent existing limits.
+
+## Risks / Trade-offs
+
+- [Latest-frame eviction drops decodable dependencies] → preserve truthful drops and existing IDR feedback; never grow memory or block every session.
+- [Large frames multiply fragment sends] → cap both complete bytes and fragment count before allocation.
+- [Expiry races with dequeue or cleanup] → stop each package-private timer on
+  dequeue/replacement, serialize channel expiry and close, and retain the
+  transport stale check.
@@ -0,0 +1,24 @@
+## Why
+
+The production gateway cannot forward complete encoded video frames larger than 18,864 bytes, and its native video queue is bounded only by entry count. Realistic Phase 3C frame distributions therefore fail before QUIC delivery or can consume unreviewed memory.
+
+## What Changes
+
+- Implement the Protocol-owned complete-frame datagram profile and independent bounded client reassembly.
+- Relay full recovered Apollo frames without mutation or unrelated sequence splitting.
+- Bound native video queuing by frame count, encoded bytes, and residence time with latest-frame replacement and truthful drops.
+- Preserve independent audio and event bounds and all no-transcode/provider isolation rules.
+
+## Capabilities
+
+### New Capabilities
+
+- `complete-encoded-frame-transport`: Production fragmentation, reassembly, and byte/latency/count-bounded native frame queuing.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+Gateway framing, native Apollo media queues, QUIC send/receive tests, telemetry, and bounded resource checks. No new dependency or Server change. Requirements: P3C-006–P3C-009, P3C-025, P3C-026, P3C-028, P3C-030, P3C-038, VER-001, VER-006, VER-010.
@@ -0,0 +1,35 @@
+## ADDED Requirements
+
+### Requirement: Production transport preserves complete encoded frames
+The gateway SHALL carry each recovered Apollo encoded frame as one Protocol datagram-v2 sequence, preserve exact bytes and frame boundaries through the production media queue, pacer, QUIC transport, and independent reassembler, and reject frames outside Protocol bounds before forwarding.
+
+#### Scenario: Large source-shaped frame
+- **WHEN** Apollo UDP/FEC recovers a valid encoded frame above 18,864 bytes within the reviewed maximum
+- **THEN** the independent client receives one byte-identical frame with the same boundary
+
+#### Scenario: Invalid fragment stream
+- **WHEN** fragments are oversized, inconsistent, conflicting duplicates, outside the reorder/state/time bounds, or claim an oversized frame
+- **THEN** the client emits no partial payload and bounded state is released
+
+### Requirement: Native video queue has count byte and latency bounds
+The native provider video queue SHALL retain at most 16 complete frames, at
+most 4 MiB of encoded frame bytes, and no frame for more than 250 milliseconds.
+It SHALL replace the oldest entry when full, expire stale entries independently
+of queue activity, and increment truthful drop telemetry for every replacement
+or expiry. Cleanup and cancellation MUST stop expiry work and release all queued
+payload references.
+
+#### Scenario: Sustained realistic frames
+- **WHEN** a provider produces realistic variable-size complete frames faster than a slow Verse reader can forward them
+- **THEN** retained entries, bytes, and age remain within the reviewed per-session limits and newer frames continue to progress
+
+#### Scenario: Session cleanup
+- **WHEN** a session terminates, disconnects, or is cancelled with queued video
+- **THEN** queued frames are released, blocked readers wake, and no media crosses after quiescence
+
+### Requirement: Other provider queues remain independently bounded
+Audio and provider event queues SHALL retain independent count and payload bounds and MUST NOT share the video byte budget.
+
+#### Scenario: Video saturation
+- **WHEN** the video queue reaches its byte or age bound
+- **THEN** audio and terminal event delivery retain their existing independent bounded capacity
@@ -0,0 +1,20 @@
+## 1. Red production path
+
+- [x] 1.1 Add a public Apollo-UDP-to-independent-client regression for complete frames above 18,864 bytes
+- [x] 1.2 Add malformed, duplicate, reorder, timeout, and maximum-allocation reassembly cases
+
+## 2. Complete-frame transport
+
+- [x] 2.1 Implement negotiated datagram-v2 fragmentation and bounded independent reassembly
+- [x] 2.2 Prove deterministic 1080p60, 1440p120, and 4K60 frame distributions preserve exact bytes and boundaries
+
+## 3. Native queue bounds
+
+- [x] 3.1 Add sustained realistic-frame regressions for count, byte, latency, cleanup, cancellation, slow-reader, and amplification bounds
+- [x] 3.2 Bound the existing native video channel by 16 entries, 4 MiB, and 250 ms with latest-frame replacement and truthful drops
+- [x] 3.3 Preserve independent bounded audio and terminal event paths
+
+## 4. Verification
+
+- [x] 4.1 Run focused framing, native media, queue, race, cancellation, and resource checks
+- [x] 4.2 Run strict OpenSpec validation and the final affected Data Plane verification once
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-30
@@ -0,0 +1,28 @@
+## Context
+
+The repository already produces reproducible pure-Go Linux binaries and can read exact Go module/build metadata. A standard deterministic document is missing; adding an external SBOM tool is unnecessary for this bounded artifact.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Generate byte-stable SPDX 2.3 JSON with Go standard library encoding.
+- Describe the repository, Protocol dependency, all resolved modules, both Linux binaries, relationships, hashes, architectures, notices, and truthful licenses.
+
+**Non-Goals:**
+
+- Vulnerability scanning, signing, image remediation, public release, or inferred license conclusions.
+
+## Decisions
+
+- Use a small repository command that reads each binary with
+  `debug/buildinfo`, verifies Linux architecture and cgo settings, and compares
+  embedded module inventories before sorting every package and relationship.
+- Use fixed SPDX identifiers and a source-date timestamp supplied by the caller; reject dirty/ambiguous inputs rather than embedding current time.
+- Use `NOASSERTION` for unavailable concluded/declared license evidence and record no vulnerability result.
+
+## Risks / Trade-offs
+
+- [Go module metadata lacks complete license conclusions] → retain notices and use `NOASSERTION`.
+- [Artifact paths make output host-dependent] → encode architecture, filename, size, and digest only.
+- [A hand-built serializer could drift] → validate required SPDX fields and require byte-identical double generation.
@@ -0,0 +1,24 @@
+## Why
+
+The gateway has reproducible Linux binaries and a dependency inventory but no deterministic standard SBOM, while OPS-009 and the Phase 3C gateway plan require one for engineering exit.
+
+## What Changes
+
+- Generate byte-stable SPDX 2.3 JSON using repository, Go module, and artifact metadata.
+- Record exact source revision, immutable Protocol version/checksum, module relationships, Linux artifact hashes and architectures, and truthful license fields.
+- Retain notices/provenance and use `NOASSERTION` where license evidence is unavailable.
+- Keep vulnerability scanning, signing, and Phase 3C-C image remediation explicitly separate.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `gateway-deployment-artifact`: Require an inspected deterministic standard SBOM for shipped gateway binaries.
+
+## Impact
+
+Data Plane packaging tooling, deterministic tests, Makefile targets, canonical deployment-artifact OpenSpec, and evidence records. Uses Go standard library only; no new dependency. Requirements: SYS-019, P3C-002, P3C-035, OPS-009, VER-015, VER-017.
@@ -0,0 +1,12 @@
+## MODIFIED Requirements
+
+### Requirement: Artifact evidence is inspected and truthful
+Candidate evidence SHALL record exact source and immutable Protocol revisions/checksums, artifact hashes, architecture, embedded dependency inventory, container configuration when built, and the actual scanner/signing status. It SHALL include one byte-stable SPDX 2.3 JSON SBOM for the shipped Linux gateway artifacts containing the source package, resolved Go modules, dependency and generated-from relationships, artifact hashes and architectures, retained notices/provenance, and truthful license fields using `NOASSERTION` where evidence is unavailable. It MUST NOT claim a vulnerability result, signature, image architecture, deployment, or license conclusion that was not produced and inspected.
+
+#### Scenario: Deterministic gateway SBOM
+- **WHEN** the canonical SBOM command runs twice with the same clean source revision, Protocol module/checksum, module graph, source date, and Linux artifacts
+- **THEN** both SPDX JSON outputs are byte-identical and every declared artifact/module relationship and hash matches the inspected inputs
+
+#### Scenario: Supplemental scanner is unavailable
+- **WHEN** no qualifying vulnerability scanner is available in the frozen environment
+- **THEN** the artifact remains explicitly unscanned and unsigned, the deterministic SBOM/compiler/dependency/boundary evidence is retained, and no zero-finding security claim is emitted
@@ -0,0 +1,14 @@
+## 1. Red deterministic contract
+
+- [x] 1.1 Add a focused test requiring SPDX 2.3 fields, source/Protocol/module relationships, two architectures, and exact artifact hashes
+- [x] 1.2 Prove current packaging cannot produce the required standard SBOM
+
+## 2. Standard-library generator
+
+- [x] 2.1 Implement bounded deterministic SPDX JSON generation from explicit build and Go module metadata
+- [x] 2.2 Record truthful license fields, notices/provenance, unscanned status, and no signing claim
+
+## 3. Verification
+
+- [x] 3.1 Prove byte-stable regeneration and rejection of dirty, missing, mismatched, or ambiguous inputs
+- [x] 3.2 Reconcile the deployment-artifact canonical spec and run strict validation
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-30
@@ -0,0 +1,72 @@
+## 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.
+
+The complete-frame fixture also must preserve the pinned Apollo source schedule. For each frame it derives packets per millisecond from the raw UDP block size at 80% of 1 Gbps, limits source batches to both 64 KiB and 64 packets, and carries the next-send time into the following frame. Waiting is context-cancellable. This is qualification-fixture behavior only; production transport and queue behavior remain unchanged.
+
+Because the bounded fixture uses loopback rather than a physical 1 Gbps link, v8 writes the first shard of a batch successfully, captures that actual monotonic emission start, and schedules the next batch no earlier than that start plus the current batch's raw-block serialization interval. The persistent schedule carries across frames. A delayed batch therefore remains late instead of collapsing overdue batches into a catch-up burst.
+
+The retained v6 qualification run passed its then-current checks but is superseded because its tight-loop sender contradicted the pinned Apollo schedule. Private Linux runs 123 and 124 remain failed evidence. One local v8 sustained run passed on Darwin, but it is neither Linux proof nor normative Section 7 evidence.
+
+The later Darwin non-sustained pre-CI invocation was not green and was not retried. Its 1440p120 profile delivered the exact 6,250,000 bytes in 120 frames plus all 6,483 source and warm-up shards with zero drops, but measured 46,973.13 kbps over an implied approximately 1.0644383 seconds and failed the 5% throughput gate. At that point, private Linux full verification/artifact retention and the replacement v10 normative run were still open.
+
+Private Linux run 125 at the frozen v8 harness head is retained as failed evidence. Its exact 33-datagram gap between successful fixture writes and production `MediaIngress` equaled the Linux socket's 33 measured kernel UDP drops. The complete-frame queue, fair pacer, QUIC fragmentation, and public decoder were downstream and did not account for the loss.
+
+The one authorized v8 Section 7 invocation at production candidate `55afea72a1487fa071501615d806e68efc0a436b` was consumed and failed. Its directory `gateway-rc10-55afea7` is retained byte-for-byte with two partial processing files and no manifest. The failure occurred at payload sequence 16801 after 16,834 provider frames had been recovered and enqueued; the provider queue reached 15 entries and dropped one valid frame while source-write and ingress accounting remained balanced at the diagnostic boundary. This attempt is failed evidence and is not eligible for retry or relabeling.
+
+The production fair pacer previously limited instantaneous recovery to 5 ms by moving an overdue flow's schedule to `now-5ms`, but silently discarded every additional valid scheduling interval. Repeated host stalls therefore accumulated complete frames in the existing provider queue until its 250 ms residence horizon correctly expired one. The repair keeps the 5 ms instantaneous ceiling, carries only the remaining debt up to that existing horizon, and shortens later nominal intervals by at most one twenty-first. That 20/21 interval is exactly 5% above nominal rate; once the debt reaches zero, the flow returns to its unchanged nominal interval. Per-flow debt and the shared nominal fair-share calculation preserve the existing eight-flow fairness and rolling aggregate cap through the existing 25% and 50% capacity changes.
+
+Private Linux run 127/job 481 at exact source `122080ab342d20585d9a45db0017337b9ece570a` is retained as failed evidence. `TestQualificationLossAndSteppedThroughputBounds` reported the 25% step's 11-second convergence sentinel and a 5,207,475-byte five-second maximum. No artifact was uploaded and the run was not retried. The retained log `/private/tmp/versevdi-gitea-run-127-job-481.log` has SHA-256 `2b368413d4b0e954c64ba6f6dcefb1e165166d773b6d8f84ee372bc2c92ff5f1`. The failure exposed a measurement-unit defect: capacity samples were emitted only after complete logical-payload reassembly and were compared with a payload-derived target even though the pacer reserves encoded public datagram bytes. It did not establish a production pacer defect, and `122080ab` is superseded as a final source candidate.
+
+Qualification v9 observes every raw public QUIC datagram immediately after the independent client's `ReceiveDatagram` returns and before the existing decoder/reassembler. Capacity convergence and rolling five-second maxima use those monotonic receive times and encoded lengths. Their target bytes per second and five-second cap derive from `qualificationMediaPacerKbps(profile, reduction) * 1000 / 8`. Complete logical-payload observations remain separate and continue to own payload integrity, loss, reorder, latency, throughput, and queue assertions. The first public delivery at or after a step anchors the four consecutive 250 ms windows so an arbitrary control-plane timestamp cannot split the first observed datagram pair. The delivery-after-step boundary, 90%-105% window bounds, ten-second convergence ceiling, and rolling-five-second 105% gate are unchanged.
+
+Private Linux run 128/job 482 was the single push-triggered attempt at exact source `22433e5c45c179e9d487b59e5d80f1dcf3b285ce`. Linux `make verify`, the sustained gate, strict OpenSpec, deterministic artifact generation, upload, and the clean-checkout step passed. Artifact 28's binaries and SPDX matched the frozen hashes and source metadata. The retained log `/private/tmp/versevdi-gitea-run-128-job-482.log` has SHA-256 `6f5852dce815ba87a55d61aae34cb2fce17a1a62c5ee50e18c0034259ad0a029`. The workflow requested 30 retention days, but Gitea 1.27 floored the positive request delay and the API recorded `2026-08-09T23:18:18+07:00` through `2026-09-07T23:18:18+07:00`, exactly 2,505,600 seconds or 29 elapsed days. The run was not retried. It is passing Linux execution and artifact-byte evidence but retention-nonconforming, so it neither satisfies the private Linux artifact gate nor authorizes normative Section 7. The local 31-day request compensates for verified platform rounding without changing the acceptance threshold; a separately authorized future run must prove an API interval of at least 2,592,000 seconds.
+
+At exact source `c0e362c0285d267f8af4087d07943822311f60e1`, the first Section 7 process created mode-0750 `gateway-rc10-c0e362c` and stopped before fixture startup because the sandbox denied its required loopback bind. The directory remains empty as environment-boundary evidence. The separately authorized escalated attempt retained `gateway-rc10-c0e362c-a2`, passed the v9 runtime checks, and wrote 16 files with manifest SHA-256 `61ea55140dfe6b37332de03879ac33206dd5d47763d09fb0fc2f65bb1f8e02b4`. Independent review denied normative acceptance: the constrained logical CSV and manifest aggregates did not persist every raw public QUIC datagram receive offset/encoded length, and `fairness.csv.gz` lacked manifest transition offsets. A2 therefore remains runtime-passing but normative-raw-evidence-incomplete, without mutation or relabeling.
+
+Qualification v10 keeps the logical impairment CSV unchanged and adds only `impairment-constrained-1080p60-h264-wire.csv.gz`. One monotonic epoch is captured before the constrained delivery and transition sequence. The bounded CSV interleaves two explicit transition records with every public datagram observation in monotonic order using `record_type,reduction_percent,transition_after_ns,received_after_ns,encoded_bytes`; transition-only and delivery-only fields remain empty and are validated as such. Its maximum row count is derived from the existing constrained job bound, the frame-fragment count, and the two configured transitions rather than a captured-run row constant. The manifest binds the file name, SHA-256, compressed bytes, total/delivery/transition row counts, timebase, exact transition offsets, and each capacity summary's recomputation source. Each impairment step is recomputed from every delivery at or after its transition through completion, preserving the original v9 classifier semantics even after the next transition. Fairness remains stage-bounded because `runQualificationFleetStage` records each capacity stage as a separate slice; its summaries retain their 25% and 50% offsets relative to the existing fairness CSV epoch.
+
+The independent parser's caller explicitly selects smoke or normative authority. Normative validation requires exactly 10,000 sent logical units and always enforces the ten-second convergence and 105% rolling-cap gates; retained `sent` data cannot weaken them. Both wire and fairness readers reject compressed input before hashing when it exceeds a writer-derived bound, feed gzip output through a bounded standard-library reader before CSV parsing, and bound fields, offsets, flows, and encoded lengths from the canonical row count, schema, time horizon, and writer values. Aggregate-only v9 data and malformed schema/hash/count/order/transition/length or oversized inputs remain rejected.
+
+Private Linux run 129/job 483 and artifact 29 at `c0e362c0285d267f8af4087d07943822311f60e1` passed execution, artifact-byte, and at-least-30-elapsed-day retention checks. Its subsequent v9 a2 qualification remains runtime-passing but normative-raw-evidence-incomplete. Exact v10 source `ce3b3079837c5745f95a51c98eb6204363962ae7` then passed its one private Linux push attempt in run 130/job 484: `make verify`, the sustained gate, strict OpenSpec, deterministic artifact build/upload, and clean checkout all passed. The retained run log is SHA-256 `7e23011db2cb3118ca6cd940cfdc59ba4b536de39276d6b6a74c5862c745b0fa`. Artifact 30's ZIP is SHA-256 `59f938f9187255ad015fa5608b49909e89a065e4f5ba515b7450608b8048b1cc` at 12,957,227 bytes; its amd64 binary is `33ecd42cee0e01bc15aa87aa0610bfb165b2a2b379133110271c98d717584cc1` at 12,367,020 bytes, its arm64 binary is `4b6fc560e23fd8e283219f63ac4a33881863d12644676fb6e5a7d9fc4523182b` at 11,525,817 bytes, and its source-correct SPDX is `a1c2ae2bc4a8c0e0dea67ac53dbf8bb6135399cecb8d6fd153e9b59174ec35b9` at 8,090 bytes. The API recorded exactly 2,592,000 seconds of retention. The binaries remain unchanged because v10 changes retained test evidence only; the SPDX truthfully remains unscanned and unsigned.
+
+Two subsequent ce3 elevated-execution preflights were denied before `CreateProcess`. No `go test` process started, no target was created, and neither event consumed a qualification attempt; they remain environment/approval history rather than runtime failures. The later owner-approved elevated direct command ran exactly once at ce3 with immutable Protocol RC10, exited zero, and passed `TestSection7Qualification` in 1,917.92 seconds (package 1,918.491 seconds). It produced mode-0750 `gateway-rc10-ce3b307` with 17 files totaling 4,179,714 bytes and a passed v10 manifest SHA-256 `53f1e24a3182887d496b745826af20c7b220a3a0cc2e1682baf1eb746f4c240d`.
+
+Independent review recomputed 36,000/72,000/36,000 processing frames and 11.25 GB of exact payload, including payload digests, statistics, isolated resources, and all eight logical impairment files. It also recomputed the constrained wire artifact's 15,060 rows as 15,058 ordered 1,200/25-byte deliveries plus canonical 25%/50% transitions, including full-tail convergence and maxima. The fairness artifact retained 70,916 rows; stage-bounded recomputation reproduced Jain index `0.9999999546920958`, maximum share error `0.0003749275708101844`, and the two-second 25%/50% convergence/maxima. Identity, hashes, bounded grammar, and preservation checks found no material mismatch. These results remain deterministic fixture evidence only and do not prove live Apollo, the native macOS client, a physical firewall or route, a real encoder, multi-host operation, Phase 3C-C, vulnerability scanning, signing, deployment, or promotion.
+
+The ingress repair follows reviewed behavior rather than copying implementation source:
+
+- Apollo `adc5c5a0bd80831ce495434bb16aee2cd4175fb8`, GPL-3.0, `src/stream.cpp:1463-1474,1573-1627`, supplies the 80%-of-1-Gbps raw-block pacing, 64-KiB/64-packet batch cap, and cross-frame send schedule used by the fixture.
+- Moonlight common-C pin `2ea47752c3051d72a64bcca190024e8b354fa1ef`, GPL-3.0, `src/VideoStream.c:28-35,331-333` and `src/PlatformSockets.c:364-405`, supplies the reviewed 2,048-video-packet receive-buffer request and dedicated receive-thread behavior. The cited `VideoStream.c` blob is byte-identical at the local standalone `703a06946861ff82cd33e5e13c59c1b017f7ded9` checkout.
+
+The native provider therefore requests `2,048 * 1,072 = 2,195,456` bytes with `SetReadBuffer()` on the connected video socket immediately after dialing it. A setter error aborts setup; an OS-imposed cap is accepted without privilege or getter dependence. A dedicated drain owns a fixed 2,048-slot FIFO pool. Every slot is 1,433 bytes (`apolloMediaMaximumPacket + 1`), so oversized datagrams remain observably invalid rather than being truncated into the accepted range; packet storage is 2,934,784 bytes (about 2.80 MiB) plus fixed index and timestamp metadata. The existing single decrypt/FEC processor consumes those slots. When every slot is occupied, the drain keeps reading into one fixed 1,433-byte scratch buffer and counts each accepted-size discard in both ingress and drop telemetry; oversized datagrams retain the existing rejection semantics. Socket close cancels the blocking read, and media channels close only after the unchanged audio reader, video drain, and video processor exit. Audio and control behavior are unchanged.
+
+## 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.
+- Keep video decrypt/FEC single-threaded; only the bounded connected-socket drain is separated so crypto stalls cannot become unexplained kernel loss.
+- Preserve valid scheduling debt after bounded host stalls instead of converting it into provider-queue residence; repay it within the existing fair pacer without a new queue, interface, or configured headroom.
+- Classify constrained-capacity evidence from actual public datagram observations and configured wire capacity; do not infer transport timing from completed logical frames.
+- Persist constrained public-wire observations and transition events in one bounded monotonic-offset CSV, recompute impairment summaries from each transition through completion, and bind both impairment and stage-bounded fairness capacity summaries to their retained raw sources.
+- Select smoke versus normative evidence validation through trusted caller input and bound compressed bytes, decompressed bytes, fields, offsets, flows, and encoded lengths before independent CSV parsing.
+
+## 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.
+- [A stalled video processor exhausts the user-space pool] → keep draining into one fixed scratch buffer and attribute accepted-size overflow to existing ingress/drop counters rather than kernel loss or unbounded allocation.
+- [Debt repayment creates a burst or aggregate oversubscription] → retain the 5 ms instantaneous ceiling and limit repayment to a 20/21 nominal interval per flow, with every rolling five-second aggregate window bounded to 105%.
@@ -0,0 +1,46 @@
+## 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.
+
+The v6 complete-frame fixture subsequently exposed a source-fidelity defect on ordinary Linux runners: it emitted every UDP shard in one tight loop, unlike pinned Apollo's bounded intra-frame rate and batch schedule. The affected v6 qualification evidence remains retained but is superseded for candidate-readiness purposes.
+
+Private Linux run 125 then demonstrated a separate production-ingress defect after source pacing was corrected: 33 successful fixture writes missing from `MediaIngress` matched 33 measured kernel UDP drops while decrypt/FEC, queue, pacer, QUIC, and client counters remained downstream of the shortfall.
+
+The consumed v8 Section 7 attempt at `55afea72` subsequently failed after accumulated host scheduling delays exposed the production pacer's discarded schedule debt beyond its 5 ms instantaneous catch-up allowance. The retained partial evidence remains failed and supersedes `55afea72` as a final executable candidate.
+
+Private Linux run 127/job 481 at exact source `122080ab342d20585d9a45db0017337b9ece570a` then failed `TestQualificationLossAndSteppedThroughputBounds`: the 25% capacity step reported the 11-second convergence sentinel and 5,207,475 bytes in the measured five-second window. The run produced no artifact and was not retried. Its retained log is `/private/tmp/versevdi-gitea-run-127-job-481.log`, SHA-256 `2b368413d4b0e954c64ba6f6dcefb1e165166d773b6d8f84ee372bc2c92ff5f1`; `122080ab` is superseded as a final source candidate.
+
+Private Linux run 128/job 482 was the single push-triggered attempt at exact source `22433e5c45c179e9d487b59e5d80f1dcf3b285ce`. Linux `make verify`, the sustained gate, strict OpenSpec, deterministic artifact generation, upload, and the clean-checkout step passed. Artifact 28's binaries and SPDX matched the frozen hashes and source metadata. The retained log `/private/tmp/versevdi-gitea-run-128-job-482.log` has SHA-256 `6f5852dce815ba87a55d61aae34cb2fce17a1a62c5ee50e18c0034259ad0a029`. The workflow requested 30 retention days, but Gitea 1.27 floored the positive request delay and its API scheduled exactly 29 elapsed days. The run was not retried: it is passing Linux execution and artifact-byte evidence but retention-nonconforming, so it does not satisfy the private Linux artifact gate or authorize normative Section 7. The local 31-day request preserves the at-least-30-elapsed-day requirement; a separately authorized future run must prove `expires_at - created_at >= 2,592,000` seconds.
+
+At exact source `c0e362c0285d267f8af4087d07943822311f60e1`, the first Section 7 attempt created `gateway-rc10-c0e362c` and stopped at the sandbox loopback-bind boundary, leaving that mode-0750 directory empty. The separately authorized escalated attempt `gateway-rc10-c0e362c-a2` then passed the v9 runtime gates and retained 16 files; its manifest has SHA-256 `61ea55140dfe6b37332de03879ac33206dd5d47763d09fb0fc2f65bb1f8e02b4`. Independent review denied normative acceptance because v9 retained only logical impairment rows and aggregate capacity summaries: it did not retain the raw public datagram timestamps/lengths or fairness transition offsets needed to recompute those summaries. Both attempts remain preserved without relabeling; a2 is runtime-passing but normative-raw-evidence-incomplete.
+
+Private Linux run 129/job 483 and artifact 29 at `c0e362c0285d267f8af4087d07943822311f60e1` passed execution, artifact-byte, and at-least-30-elapsed-day retention checks. That Linux result remains valid, while the later v9 a2 qualification remains runtime-passing but normative-raw-evidence-incomplete. Neither classification is relabeled.
+
+Immutable v10 source `ce3b3079837c5745f95a51c98eb6204363962ae7` passed its single private Linux push attempt, run 130/job 484, including `make verify`, the sustained gate, strict OpenSpec, deterministic build/upload, and the clean-checkout gate. Artifact 30 retained the unchanged amd64 and arm64 binaries plus a source-correct, unscanned, unsigned SPDX for exactly 2,592,000 API-recorded seconds. Two later elevated-execution preflights were denied before `CreateProcess`; neither created the target nor consumed a qualification attempt. The subsequent owner-approved direct command ran exactly once, exited zero, and wrote the 17-file v10 `gateway-rc10-ce3b307` bundle with passed manifest SHA-256 `53f1e24a3182887d496b745826af20c7b220a3a0cc2e1682baf1eb746f4c240d`.
+
+Independent review recomputed all three processing profiles, 11.25 GB of payload, all eight logical impairment files, the 15,060-row constrained public-wire artifact, and the 70,916-row fairness artifact from the retained v10 evidence. It reproduced ordered 25%/50% transitions, full-tail impairment convergence and maxima, stage-bounded fairness convergence and maxima, Jain index `0.9999999546920958`, maximum share error `0.0003749275708101844`, and every bound manifest identity/hash/grammar value without a material mismatch. This closes only deterministic fixture evidence: live Apollo, the native macOS client, the physical firewall and route, a real encoder, multi-host operation, Phase 3C-C, scanning, signing, deployment, and promotion remain outside this result.
+
+## 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.
+- Decouple native video socket draining from the single decrypt/FEC processor with a fixed provider-scoped receive pool and request the source-backed video receive-buffer size.
+- Retain bounded valid per-flow pacing debt after a host stall and repay it at no more than 5% above nominal fair share.
+- Measure capacity convergence and rolling caps from each raw public QUIC datagram's observed length and receive time while retaining completed logical-payload observations for integrity and traversal results.
+- Persist the constrained public datagram observations and capacity transitions under one monotonic epoch, bind their hash/counts into the v10 manifest, and retain fairness transition offsets for independent recomputation. Impairment summaries use the full delivery tail after each transition; trusted caller input selects normative validation, and bounded readers reject oversized compressed, decompressed, and field data.
+- 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 qualification harness and its canonical specification, plus the already-reviewed native Apollo video ingress in `gateway/apollo_native.go` and production fair pacer in `gateway/telemetry.go`. This v10 correction changes test-only retained evidence, not production behavior. Downstream complete-frame queues, audio/control ingress, codec/FEC formats, QUIC, dependencies, and public interfaces remain unchanged. No codec operation or normative rerun is included. Requirements: P3C-002, P3C-008, P3C-029, P3C-030, P3C-033, VER-009, VER-010, OPS-015.
@@ -0,0 +1,69 @@
+## 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.
+
+Within each complete frame the source fixture SHALL reproduce pinned Apollo's source schedule by deriving packets per millisecond from the raw UDP block size at 80% of 1 Gbps, bounding each source batch to the smaller of 64 KiB or 64 packets, capturing the monotonic batch start immediately after the first successful shard write, scheduling the next batch no earlier than that start plus the current batch's raw-block serialization interval, carrying that schedule across frames, and making pacing waits context-cancellable. A delayed batch SHALL remain late rather than trigger an overdue catch-up burst.
+
+Native Apollo video ingress SHALL request a 2,195,456-byte socket receive buffer before media ping or worker startup and SHALL drain the connected video socket into a fixed FIFO pool of exactly 2,048 slots before the existing single decrypt/FEC processor. Each slot and the saturation scratch buffer SHALL be `apolloMediaMaximumPacket + 1` bytes so oversized datagrams remain rejected. A full pool SHALL NOT stop socket draining: each successfully read accepted-size discard SHALL increment both media-ingress and media-drop telemetry without allocation, while oversized reads SHALL retain the existing rejection accounting. Socket closure SHALL cancel the video read, and video/audio channels SHALL close only after the audio reader, video drain, and video processor exit. Audio and control ingress SHALL remain unchanged.
+
+The production fair pacer SHALL retain its 5 ms instantaneous catch-up ceiling. When a flow resumes later than that ceiling, it SHALL carry the remaining valid schedule debt only within the existing 250 ms provider-queue horizon and SHALL repay that debt using an interval no shorter than 20/21 of its nominal equal-tier fair-share interval. It SHALL return to the nominal interval when the debt is repaid. Simultaneous debt across eight equal-tier flows and the existing 25% and 50% capacity changes SHALL preserve the existing share-error contract and SHALL NOT exceed 105% of configured aggregate capacity in any rolling five-second window.
+
+Capacity-step convergence and rolling-cap evidence SHALL use the monotonic receive time and encoded length of every raw public QUIC datagram observed immediately after the independent client's `ReceiveDatagram` returns and before decode or reassembly. For each reduction, target bytes per second and the five-second cap SHALL derive from the configured public-wire rate, `qualificationMediaPacerKbps(profile, reduction) * 1000 / 8`. Completed logical-payload observations SHALL remain separate and SHALL continue to measure payload integrity, loss, reorder, latency, throughput, and queue behavior. An impairment capacity step SHALL include every delivery observation at or after its recorded transition through constrained-run completion; a later transition SHALL NOT truncate the earlier step's retained tail. It SHALL anchor measurement windows at the first such public delivery, require four consecutive 250 ms windows between 90% and 105% of its target, converge within ten seconds, and remain at or below 105% in every rolling five-second window.
+
+The constrained profile SHALL retain a bounded gzip CSV containing exactly two capacity-transition records and every observed raw public datagram delivery under one monotonic epoch captured before the constrained sequence. The schema SHALL distinguish transition and delivery records and SHALL contain `record_type`, `reduction_percent`, `transition_after_ns`, `received_after_ns`, and `encoded_bytes`; fields not applicable to a record type SHALL remain empty and SHALL be rejected when populated. The manifest SHALL bind the file name, SHA-256, compressed byte count, total row count, delivery row count, transition row count, monotonic timebase, exact 25% and 50% transition offsets, and each capacity summary's raw recomputation source. The row bound SHALL derive from the configured constrained-job and fragment bounds rather than a prior run's observed row count.
+
+The retained fairness manifest SHALL bind its 25% and 50% transition offsets to the monotonic epoch of `fairness.csv.gz`. Fairness recomputation SHALL remain bounded to each separately collected `runQualificationFleetStage` capacity slice. An independent parser SHALL be able to reconstruct each stage and reproduce the rolling-five-second maximum, configured cap, and exact two-second fairness convergence from the retained raw files and manifest alone. The parser SHALL select normative versus smoke validation only from trusted caller input; normative validation SHALL require exactly 10,000 sent logical units and SHALL enforce the ten-second convergence and 105% rolling-cap gates unconditionally. Compressed, decompressed, row, field, offset, flow, and encoded-length limits SHALL derive from canonical writer schemas, configured row limits, and canonical run horizons and SHALL be enforced before CSV parsing can allocate an unbounded record. Missing raw-wire evidence; a wrong file hash, size, or count; duplicate or missing transitions; negative or nonmonotonic offsets; invalid encoded lengths; completed-logical-frame substitution; populated not-applicable fields; oversized input; or a summary mismatch SHALL fail qualification evidence acceptance.
+
+#### 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
+
+#### Scenario: Source-shaped Apollo pacing is preserved
+- **WHEN** the fixture emits 1,072-byte encrypted video shards with 1,040-byte raw blocks for consecutive complete frames
+- **THEN** it uses 96 packets per millisecond, batches at most 63 shards, records each batch after its first successful shard write, starts each later batch no earlier than the prior batch's raw serialization interval, carries the schedule into the following frame, and emits no shard after a cancelled pacing wait
+
+#### Scenario: Video crypto processing stalls
+- **WHEN** the first video AEAD operation is blocked while a 662-shard keyframe arrives
+- **THEN** all 662 successful connected-socket reads reach media-ingress accounting before processing resumes, and after release the exact complete frame traverses recovery, the bounded production queue, pacer, QUIC, and independent reassembly
+
+#### Scenario: Video ingress pool saturates
+- **WHEN** all 2,048 fixed video slots are occupied
+- **THEN** accepted-size datagrams are deliberately discarded through the fixed scratch buffer and counted as ingress plus drops, oversized datagrams remain rejected, and cancellation closes every media worker without a race or leak
+
+#### Scenario: Repeated media-loop host stalls
+- **WHEN** three approximately 95 ms scheduling debts are introduced at separated completed-public-frame barriers while source recovery continues
+- **THEN** the pacer limits instantaneous catch-up to 5 ms, repays each remaining debt at no more than 5% above nominal fair share, preserves every frame in exact order and bytes without provider or gateway drops, stays within the existing queue bounds, and closes cleanly on cancellation
+
+#### Scenario: Capacity measurement crosses a short transition phase
+- **WHEN** a constrained 1080p flow carries nonzero bounded debt through the approximately 1.572-second 25% phase before the 50% transition
+- **THEN** convergence and rolling-cap checks use the observed 1,200-byte and 25-byte public datagrams against the configured wire targets, while the separately retained completed-payload observations cannot substitute for transport delivery timing
+
+#### Scenario: Aggregate-only capacity evidence is retained
+- **WHEN** a qualification bundle contains logical-frame impairment rows and aggregate capacity summaries but omits raw public-wire rows or fairness transition offsets
+- **THEN** independent evidence validation rejects the bundle as incomplete even if its in-process runtime assertions passed
+
+#### Scenario: Raw capacity evidence is independently recomputed
+- **WHEN** v10 validation reads the retained constrained wire CSV, fairness CSV, and manifest transitions
+- **THEN** it validates bounded schema, hashes, sizes, counts, monotonic offsets, encoded datagram lengths, and transition uniqueness, then exactly reproduces the full-after-transition impairment targets, four consecutive 250 ms convergence windows, every rolling-five-second maximum, and stage-bounded fairness two-second alignment
+
+#### Scenario: Retained counts cannot weaken normative gates
+- **WHEN** a purported normative bundle retains a sent count other than 10,000 or retains an 11-second convergence or over-cap summary
+- **THEN** validation rejects it regardless of any retained field value, while explicitly selected smoke validation still requires exact raw-summary recomputation
+
+#### Scenario: Retained CSV exceeds bounded evidence grammar
+- **WHEN** a wire or fairness gzip exceeds its canonical compressed or decompressed limit or contains an overlong field, out-of-horizon offset, unknown flow, or out-of-range encoded length
+- **THEN** validation rejects it through the bounded standard-library reader before an unbounded CSV record can be allocated
+
+## ADDED Requirements
+
+### Requirement: Retained private Linux candidate artifact
+A retained private Linux candidate artifact SHALL have API metadata whose `expires_at - created_at` interval is at least 30 elapsed days (2,592,000 seconds). Workflow intent, cleanup lag, and a local copy SHALL NOT substitute for the recorded API interval. A shorter interval SHALL fail the artifact-retention gate even when execution and artifact bytes pass. The workflow request MAY exceed 30 calendar days only to compensate for verified platform rounding; the acceptance threshold remains at least 30 elapsed days.
+
+#### Scenario: Platform rounding shortens retention
+- **WHEN** a private Linux candidate run passes execution and artifact-byte checks but its artifact API metadata records less than 2,592,000 seconds between creation and expiry
+- **THEN** the artifact-retention gate remains failed until a separately authorized candidate run records an interval of at least 2,592,000 seconds
@@ -0,0 +1,52 @@
+## 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
+
+- [x] 4.1 Run the earlier single normative Section 7 qualification after immutable Protocol consumer resolution; later audit findings superseded that candidate
+
+## 5. Pinned Apollo source-fidelity remediation
+
+- [x] 5.1 Retain the v6 qualification attempt and mark its passing result superseded by the tight-loop source defect
+- [x] 5.2 Implement v8 post-first-write, non-collapsing complete-frame UDP pacing with persistent cross-frame carry and verify the focused, race, short-resource, and cross-platform compile checks that passed
+- [x] 5.3 Preserve private Linux runs 123 and 124 as failed evidence, the passing local v8 Darwin sustained run as non-Linux and non-normative, and the un-retried failed Darwin non-sustained pre-CI invocation with its exact throughput evidence
+- [x] 5.4 Run private Linux full verification and retain deterministic Linux artifacts for the frozen v10 evidence descendant
+- [x] 5.5 Run one separately approved replacement v10 normative Section 7 qualification
+
+## 6. Native video ingress remediation
+
+- [x] 6.1 Preserve run 125 and reproduce its pre-decrypt shortfall with a public 662-shard blocked-AEAD regression
+- [x] 6.2 Add the video-only 2,195,456-byte socket-buffer request, fixed 2,048-slot drain, single processor, overflow accounting, and bounded cancellation tests
+- [x] 6.3 Freeze the reviewed production repair through private Linux full verification and artifact retention before running the replacement normative qualification
+
+## 7. Fair-pacer schedule-debt remediation
+
+- [x] 7.1 Preserve the consumed failed `55afea72` v8 attempt and its two partial files without retry, relabeling, or modification
+- [x] 7.2 Reproduce repeated host-stall queue expiry through the public native path and add bounded one-flow/eight-flow debt, fairness, rolling-cap, and capacity-step regressions
+- [x] 7.3 Retain the 5 ms instantaneous ceiling, carry valid debt within the 250 ms queue horizon, and repay it at no more than 5% above nominal fair share
+- [x] 7.4 Freeze and verify a new executable candidate on private Linux before any separately authorized replacement normative run
+
+## 8. Public-wire capacity measurement correction
+
+- [x] 8.1 Preserve run 127/job 481 at `122080ab` as failed evidence with its exact log hash, no artifact, and no retry
+- [x] 8.2 Observe raw independent-client QUIC datagram lengths/times in-process and derive v9 capacity convergence and caps from configured wire rate while keeping logical payload observations separate; this did not persist sufficient raw evidence for independent proof
+- [x] 8.3 Preserve run 128/job 482 as passing Linux execution and artifact-byte evidence but retention-nonconforming, with no retry
+- [x] 8.4 Freeze the 31-day-request descendant and prove artifact 30 records exactly 30 elapsed days before closing tasks 5.4, 5.5, 6.3, and 7.4
+
+## 9. Retained public-wire evidence correction
+
+- [x] 9.1 Preserve the first empty `gateway-rc10-c0e362c` environment-boundary attempt and the runtime-passing but normative-raw-evidence-incomplete `gateway-rc10-c0e362c-a2` bundle without mutation or relabeling
+- [x] 9.2 Persist bounded v10 constrained public-wire rows and fairness transition offsets; recompute each impairment step from its transition through completion and fairness from its separate stage; select normative authority explicitly; and bound compressed, decompressed, row, field, time, flow, and encoded-length parsing