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