docs(gateway): archive candidate evidence contracts

2026-07-30 12:09:35 +07:00
parent 2c8023edf9
commit 1485f1e637
11 changed files with 6 additions and 6 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-30
@@ -0,0 +1,31 @@
+## Context
+
+The native production path and fair pacer already exist. The defect was evidence collection: provider sends waited synchronously for client delivery, RTT was arithmetic, CPU was available capacity, and the repository had no canonical Linux build target.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Observe concurrent source-shaped traversal without a duplicate transport.
+- Distinguish actual one-way delivery, acknowledged RTT, queue/processing/pacing, and consumed process CPU.
+- Produce reproducible inspectable Linux artifacts for the deployment architectures.
+
+**Non-Goals:**
+
+- A new transport, scheduler, dependency, codec operation, scanner, signer, or container framework.
+- Live provider/client/firewall evidence or Connection Server image remediation.
+
+## Decisions
+
+- Keep the existing provider fixture and production path; overlap its UDP sender with the public QUIC receiver.
+- Apply fixed-seed impairment before provider UDP injection and derive delivery statistics from decoded payload sequence and timestamps.
+- Use native ENet acknowledgement timing for RTT instead of doubling one-way completion.
+- Use OS process user plus system CPU for the isolated qualification command; retain memory, goroutine, and allocation series separately.
+- Build both Linux architectures with `CGO_ENABLED=0`, `GOWORK=off`, `-trimpath`, no VCS stamping, and an empty build ID, then inspect ELF and embedded Go settings.
+- Delete the dead exported pacer rather than consolidate it with the sole production `fairPacer`.
+
+## Risks / Trade-offs
+
+- [Short RTT smoke runs contain ENet smoothing history] → Classify the metric as acknowledged transport RTT and enforce profile tolerances on the full frozen run.
+- [Process CPU includes the bounded fixture/client harness] → Run only the named qualification test in an isolated process and label the scope exactly; never call it host-wide or binary-only CPU.
+- [No qualifying vulnerability scanner is installed] → Record unscanned status and deterministic dependency/artifact evidence without zero-finding claims.
@@ -0,0 +1,25 @@
+## Why
+
+The prior Phase 3C-G artifacts measured serialized simulator timing, runtime CPU capacity, and a Darwin test binary rather than the actual deployable gateway candidate. VER-009, VER-010, VER-015, and OPS-009 require observed production traversal, bounded resource evidence, and exact artifact provenance before engineering exit.
+
+## What Changes
+
+- Drive impairment concurrently through the source-shaped provider UDP, native recovery, bounded queue, production pacer, QUIC, and public decoder.
+- Measure RTT from actual Apollo ENet acknowledgements, one-way latency and jitter from delivery observations, and CPU from isolated process user/system consumption.
+- Remove the unused legacy pacer so qualification and production share one scheduler.
+- Build and inspect reproducible pure-Go Linux amd64 and arm64 gateway artifacts.
+- Report dependency, scanner, architecture, and security evidence only when actually generated.
+
+## Capabilities
+
+### New Capabilities
+
+- `gateway-deployment-artifact`: Reproducible, inspectable Linux gateway build and evidence requirements.
+
+### Modified Capabilities
+
+- `gateway-qualification`: Replace serialized/synthetic timing and CPU-capacity evidence with actual bounded traversal and process-consumption observations.
+
+## Impact
+
+This affects only the GPLv3 Data Plane qualification harness, resource evidence, production scheduler inventory, and gateway packaging target. It adds no dependency, cgo, sidecar, codec operation, direct provider route, Server dependency, or proprietary source. Live Apollo, macOS-client, physical-firewall, promotion scanning/signing, and Connection Server Phase 3C-C images remain outside this deterministic gate.
@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Reproducible pure-Go Linux gateway artifacts
+The candidate SHALL build the gateway with the normal immutable Protocol module boundary for Linux amd64 and arm64 using `CGO_ENABLED=0`, deterministic path/VCS/build-ID settings, and no sidecar. Two independent builds of each architecture MUST be byte-identical.
+
+#### Scenario: Both Linux architectures are built
+- **WHEN** the canonical gateway Linux target runs twice from the same frozen source and dependency inputs
+- **THEN** both amd64 and arm64 outputs are byte-identical pure-Go ELF executables with matching embedded GOOS, GOARCH, and cgo settings
+
+### Requirement: Artifact evidence is inspected and truthful
+Candidate evidence SHALL record exact source and Protocol revisions, artifact hashes, architecture, embedded dependency inventory, container configuration when built, and the actual scanner/signing status. It MUST NOT claim an SBOM, vulnerability result, signature, image architecture, or deployment that was not produced and inspected.
+
+#### Scenario: Supplemental scanner is unavailable
+- **WHEN** no qualifying vulnerability scanner is available in the frozen environment
+- **THEN** the artifact remains explicitly unscanned, deterministic compiler/dependency/boundary evidence is retained, and no zero-finding security claim is emitted
@@ -0,0 +1,23 @@
+## 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 process CPU, memory, goroutine, allocation, and provider-queue observations, and report count, min, median, p90, p95, p99, max, mean, standard deviation, timing overhead, and observed bitrate. Processing begins at complete provider-unit receipt and ends at QUIC handoff, excluding client transit and pacing. CPU SHALL be actual OS user plus system consumption of the isolated gateway qualification process and MUST NOT be GOMAXPROCS-times-wall capacity or unrelated parent test work. Any bypass, payload mutation, wall-duration violation, bitrate outside both lower and upper bounds, 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 resource samples plus a summary tied to the exact command, CPU scope, topology, source commit, immutable Protocol version, environment, and payload hash
+
+#### Scenario: Processing gate failure
+- **WHEN** any production path stage lacks a per-traversal observation, payload integrity fails, duration or bitrate bounds fail, measured p95 exceeds 5 ms, or idle capacity is reported as consumed CPU
+- **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. 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, jitter, 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 jitter remains observable within reviewed fixed-seed tolerances, RTT comes from real request/response acknowledgement timing, and raw statistics come from actual traversal
+
+#### 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
@@ -0,0 +1,18 @@
+## 1. Qualification observations
+
+- [x] 1.1 Reproduce synthetic doubled one-way RTT and serialized traversal
+- [x] 1.2 Overlap source-shaped provider sends with public QUIC receive and retain actual delivery observations
+- [x] 1.3 Measure RTT from Apollo ENet acknowledgements and verify fixed-seed jitter
+- [x] 1.4 Replace CPU capacity with isolated OS process consumption and prove idle/work/parent isolation
+
+## 2. Production and packaging
+
+- [x] 2.1 Prove the legacy pacer has no production caller and delete it
+- [x] 2.2 Build and inspect byte-reproducible pure-Go Linux amd64 and arm64 gateway artifacts
+- [x] 2.3 Generate final dependency/artifact evidence and record scanner/signing status truthfully
+
+## 3. Frozen verification
+
+- [x] 3.1 Pass focused race/resource/impairment tests and complete Data Plane verification
+- [x] 3.2 Freeze immutable Protocol consumer inputs and run corrected Section 7 qualification once
+- [x] 3.3 Retain raw artifacts and explicit live Apollo/macOS/firewall deferral
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-30
@@ -0,0 +1,29 @@
+## Context
+
+The native Apollo session and production QUIC gateway already quiesce media before terminal delivery. A public independent-client test proved that immediate `CloseWithError` can overtake the queued reliable stream frame, while waiting for client connection closure leaves tunnel ownership unbounded.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Deliver one terminal event before gateway-owned closure.
+- Bound closure when a client remains open or omits the receipt.
+- Preserve cleanup, input release, reservation, and durable state behavior.
+
+**Non-Goals:**
+
+- A generic acknowledgement or lifecycle framework.
+- Any Apollo protocol, media, Server authority, or dependency change.
+
+## Decisions
+
+- Reuse Protocol `control.ack.v1` type `0x03` as an empty terminal receipt.
+- Hold the receipt-state lock across the terminal write, arm one receipt slot only after a successful write, and consume it in the gateway rather than provider feedback.
+- Wait at most two seconds for receipt, then close and clean up regardless.
+- Serialize the bounded native event queue and evict one older feedback item only when necessary to retain a terminal event.
+
+## Risks / Trade-offs
+
+- [Client omits receipt] → Close at the two-second bound and retain durable cleanup behavior.
+- [Feedback queue is saturated] → Sacrifice one older nonterminal feedback event rather than lose terminal ownership.
+- [Receipt is malformed, duplicate, or early] → Fail the session closed without provider mutation.
@@ -0,0 +1,24 @@
+## Why
+
+P3C-018, P3C-019, P3C-021, and P3C-027 require terminal feedback, bounded cleanup, durable state, and explicit input release. A public independent-client regression proved that immediate QUIC closure loses the terminal event, while the old behavior left the tunnel open until the client closed it.
+
+## What Changes
+
+- Consume the Protocol-owned terminal receipt on `control.ack.v1` inside the gateway rather than forwarding it to Apollo.
+- Quiesce media before terminal delivery and close the gateway-owned tunnel after receipt or a bounded receipt deadline.
+- Guarantee a terminal event survives saturation of the bounded native feedback queue.
+- Preserve provider cleanup, reservation release, reconnectable disconnect reporting, and `cleanup_pending`.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `provider-session-lifecycle`: Make terminal delivery and gateway-owned bounded closure executable rather than dependent on client connection closure.
+
+## Impact
+
+The pure-Go GPLv3 gateway control and native Apollo session paths change. The Protocol repository remains the wire-contract owner; the Server remains the durable authority. No cgo, sidecar, direct provider route, decode/transcode path, dependency, or proprietary source is introduced. Failure to receive a valid receipt before the bound is a hard session close, not a fallback.
@@ -0,0 +1,23 @@
+## MODIFIED Requirements
+
+### Requirement: Provider terminal events end forwarding
+Encrypted provider termination and unexpected provider disconnect SHALL quiesce provider ingestion and queued/new media forwarding before the existing reliable typed terminal event is delivered. The client SHALL return the Protocol-owned terminal receipt after decoding that event. The gateway SHALL close the Verse tunnel after that receipt or a bounded receipt deadline even when the client keeps the connection open, release the session reservation, and report the appropriate durable provider/session state. The receipt MUST be consumed by the gateway and MUST NOT be forwarded to the provider. A fixed drain delay MUST NOT stand in for reliable control delivery.
+
+#### Scenario: Host termination closes the tunnel
+- **WHEN** the native provider emits an authenticated termination event and an independent client returns its terminal receipt
+- **THEN** queued and newly injected media cannot cross the Verse transport after observation, and the gateway closes the tunnel, releases the reservation, and completes the durable lifecycle transition
+
+#### Scenario: Unexpected provider disconnect is reconnectable
+- **WHEN** required provider transport disconnects without acknowledged provider termination
+- **THEN** forwarding stops, the final typed disconnect reaches the client, and the Server receives the existing reconnectable lifecycle state rather than a termination claim
+
+#### Scenario: Client omits terminal receipt
+- **WHEN** the terminal event is written but the client remains open without returning a valid receipt
+- **THEN** the gateway closes the tunnel at the bounded receipt deadline and continues cleanup without restoring media forwarding
+
+### Requirement: Cleanup failure remains durable
+Gateway cleanup MUST preserve `cleanup_pending` when provider input release, transport cleanup, authorized cancellation, or durable reporting fails.
+
+#### Scenario: Terminal cleanup fails
+- **WHEN** a provider terminal event is handled but required cleanup cannot complete
+- **THEN** the session is not reported reusable and durable state remains cleanup pending
@@ -0,0 +1,16 @@
+## 1. Regressions
+
+- [x] 1.1 Reproduce terminal event loss with an independent QUIC client and immediate gateway closure
+- [x] 1.2 Reproduce terminal loss behind a saturated native feedback queue
+
+## 2. Lifecycle repair
+
+- [x] 2.1 Consume the scoped terminal receipt without provider forwarding
+- [x] 2.2 Close acknowledged and non-acknowledged terminal tunnels within bounds
+- [x] 2.3 Preserve media quiescence, reservation release, durable state, and cleanup-pending
+
+## 3. Verification
+
+- [x] 3.1 Pin the final immutable Protocol version and pass focused lifecycle/race/resource checks
+- [x] 3.2 Pass complete Data Plane verification and the frozen normative Section 7 qualification
+- [x] 3.3 Record that deterministic fixtures do not prove live Apollo, macOS-client, or physical-firewall interoperability