feat(protocol): carry stream policy and gateway telemetry

2026-07-30 01:45:48 +07:00
parent 59741761ce
commit d26f8b60f8
17 changed files with 991 additions and 42 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-29
@@ -0,0 +1,36 @@
+## Context
+
+The Data Plane already collects process-wide atomic counters and gauges. Only active connections and egress Kbps cross the authenticated heartbeat boundary.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Carry the existing low-cardinality observations with explicit units.
+- Bound every numeric field and enumerate provider state.
+- Keep registration capacity distinct from measured traffic.
+
+**Non-Goals:**
+
+- Add session, route, endpoint, credential, label, or payload fields.
+- Define a new telemetry transport.
+- Publish a Protocol version.
+
+## Decisions
+
+- Nest the values in required `GatewayTelemetry` so heartbeat telemetry is one strict atomic contract.
+- Use cumulative counters and microsecond delay totals plus processing samples; consumers can derive rates/averages without losing raw observations.
+- Keep loss as parts per million and provider state as a bounded enum.
+
+## Risks / Trade-offs
+
+- [Cumulative counters approach signed integer limits] → Bound at signed 64-bit and saturate consumer conversions.
+- [New required object breaks RC6] → Test locally and publish only under separate immutable-version authorization.
+
+## Migration Plan
+
+Regenerate all bindings locally, update both consumers through the temporary workspace, and stop at the immutable publication boundary.
+
+## Open Questions
+
+None.
@@ -0,0 +1,23 @@
+## Why
+
+Gateway heartbeat currently carries active sessions and one egress rate but cannot transport the required observed process and provider-path telemetry.
+
+## What Changes
+
+- Add one required bounded low-cardinality telemetry object to authenticated gateway heartbeat.
+- Cover counters, delay totals/samples, control RTT/loss/jitter, pending reliability, reconnects, and provider state.
+- Keep configured capacity exclusively in registration and measured egress in heartbeat.
+
+## Capabilities
+
+### New Capabilities
+
+- `gateway-heartbeat-telemetry`: Authenticated heartbeats carry bounded observed gateway telemetry without routes, sessions, credentials, or payload data.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+The control-v1 schema, generated Go/Rust/Swift bindings, conformance checks, and both unpublished consumers require coordinated local updates. RC6 remains unchanged.
@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Heartbeat carries observed gateway telemetry
+Every authenticated `GatewayHeartbeat` SHALL carry the bounded process-level counters, delay totals and samples, control RTT/loss/jitter, pending reliable work, reconnect count, and provider state defined by `GatewayTelemetry`.
+
+#### Scenario: Valid telemetry heartbeat
+- **WHEN** a gateway reports its current observed snapshot
+- **THEN** Go, Rust, and Swift bindings accept the same bounded low-cardinality values and units
+
+### Requirement: Heartbeat telemetry excludes sensitive dimensions
+Heartbeat telemetry MUST reject unknown fields and MUST NOT include session, route, endpoint, credential, label, or payload values.
+
+#### Scenario: Secret or high-cardinality field is attempted
+- **WHEN** a heartbeat contains an unregistered session, route, endpoint, credential, or payload field
+- **THEN** strict contract validation rejects it before authenticated transport
@@ -0,0 +1,11 @@
+## 1. Contract
+
+- [x] 1.1 Add bounded GatewayTelemetry to every heartbeat
+- [x] 1.2 Add Go, Rust, and Swift strict conformance checks
+- [x] 1.3 Regenerate bindings and prove deterministic output
+
+## 2. Consumer Boundary
+
+- [x] 2.1 Verify local Data Plane and Server consumers through a temporary workspace
+- [ ] 2.2 Publish one new never-reused immutable Protocol version under separate authorization
+- [ ] 2.3 Resolve from empty caches and pin exact checksums in both consumers
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-29
@@ -0,0 +1,37 @@
+## Context
+
+The Server resolves an immutable stream-policy version, but RC6 provider work carries only its identifier. The Data Plane consequently cannot distinguish the authorized settings from local defaults.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Carry only the effective launch settings required by the provider boundary.
+- Generate identical validation from the canonical schema for all bindings.
+- Preserve the policy-version identifier for audit correlation.
+
+**Non-Goals:**
+
+- Publish or mutate RC6.
+- Add provider-specific capability negotiation to Protocol.
+- Expose provider work or policy internals to Verse clients.
+
+## Decisions
+
+- Use one required nested `ProviderStreamPolicy` value in `ProviderSessionWork`; this keeps the policy settings atomic and avoids repeating validation.
+- Carry the Server-selected target bitrate rather than all policy bounds because Apollo ANNOUNCE consumes one configured bitrate.
+- Permit canonical `H264`, `HEVC`, and `AV1` values in the contract. A provider implementation must reject values it cannot honor rather than silently downgrade them.
+- Carry `audio_enabled` even though the current Apollo path cannot truthfully disable audio; the Data Plane must fail closed for that combination.
+
+## Risks / Trade-offs
+
+- [New required field breaks RC6 consumers] → Publish only under a separately authorized new immutable version and pin both consumers after empty-cache resolution.
+- [Provider capabilities differ] → Validate the effective policy against the selected provider before readiness.
+
+## Migration Plan
+
+Regenerate and verify bindings locally, update both consumers through a temporary workspace only, then stop at the publication boundary. RC6 remains unchanged.
+
+## Open Questions
+
+None.
@@ -0,0 +1,23 @@
+## Why
+
+Provider work identifies an immutable stream-policy version but omits the effective settings, allowing a gateway to launch Apollo with unrelated hard-coded media parameters.
+
+## What Changes
+
+- Add the effective resolution, frame rate, codec, selected bitrate, and audio policy to authenticated provider work.
+- Require generated Go, Rust, and Swift bindings to validate the same bounded stream-policy contract.
+- Keep the new contract unpublished until a new immutable Protocol version is separately authorized.
+
+## Capabilities
+
+### New Capabilities
+
+- `provider-stream-policy`: Authenticated provider work carries the exact effective stream policy consumed by the provider launch.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+The control-v1 schema, generated bindings, conformance fixtures, and downstream Server and Data Plane consumers require coordinated local updates. RC6 remains immutable and unchanged.
@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Provider work carries the effective stream policy
+Authenticated `ProviderSessionWork` SHALL carry the immutable policy version and its effective resolution, frame rate, codec, target bitrate, and audio-enabled decision.
+
+#### Scenario: Gateway receives an effective policy
+- **WHEN** the Server issues provider work for an admitted session
+- **THEN** the work identifies the policy version and includes the effective bounded stream-policy values
+
+### Requirement: Stream-policy bindings share one strict contract
+Generated Go, Rust, and Swift bindings MUST reject missing, unknown, out-of-range, or unsupported stream-policy wire values according to the canonical schema.
+
+#### Scenario: Invalid policy is rejected consistently
+- **WHEN** provider work contains an unknown codec or a value outside the canonical bounds
+- **THEN** every generated binding rejects the work before it can reach provider setup
@@ -0,0 +1,11 @@
+## 1. Contract
+
+- [x] 1.1 Add bounded effective stream policy to ProviderSessionWork
+- [x] 1.2 Add Go, Rust, and Swift conformance coverage
+- [x] 1.3 Regenerate bindings and prove deterministic output
+
+## 2. Consumer Boundary
+
+- [x] 2.1 Verify local Server and Data Plane consumers through a temporary workspace
+- [ ] 2.2 Publish one new never-reused immutable Protocol version under separate authorization
+- [ ] 2.3 Resolve from empty caches and pin exact checksums in both consumers