feat(gateway): relay complete encoded frames
This commit is contained in:
sechmachine
@@ -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.
|
||||
+35
@@ -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,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.
|
||||
+12
@@ -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
|
||||
@@ -5,14 +5,47 @@ Define the deterministic processing, impairment, pacing, and evidence boundaries
|
||||
for qualifying a frozen Phase 3C gateway candidate.
|
||||
## 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. Native queues SHALL remain bounded at 256 video packets and 16 audio or event units per session, retaining latest-unit replacement. 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.
|
||||
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 frames 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, min, median, p90, p95, p99, max, mean, standard deviation, and measured
|
||||
batched monotonic-clock overhead and method. 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. Native video queues SHALL retain at most 16 complete frames, 4 MiB,
|
||||
and 250 milliseconds; audio and event queues SHALL remain independently bounded
|
||||
at 16 units. 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 frame-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 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
|
||||
- **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-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
|
||||
- **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
|
||||
|
||||
### Requirement: Bounded impairment qualification
|
||||
|
||||
Reference in New Issue
Block a user