From 2e92fae27ffe15bc266f1825806a77a57b5f0d56 Mon Sep 17 00:00:00 2001 From: sechmachine <97589681+sechmachine727@users.noreply.github.com> Date: Thu, 30 Jul 2026 07:38:39 +0700 Subject: [PATCH] docs(openspec): archive phase3c gateway contracts --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/gateway-heartbeat-telemetry/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/provider-stream-policy/spec.md | 0 .../tasks.md | 0 .../specs/gateway-heartbeat-telemetry/spec.md | 26 +++++++++++++ openspec/specs/provider-stream-policy/spec.md | 37 +++++++++++++++++++ 12 files changed, 63 insertions(+) rename openspec/changes/{phase3c-gateway-heartbeat-telemetry => archive/2026-07-30-phase3c-gateway-heartbeat-telemetry}/.openspec.yaml (100%) rename openspec/changes/{phase3c-gateway-heartbeat-telemetry => archive/2026-07-30-phase3c-gateway-heartbeat-telemetry}/design.md (100%) rename openspec/changes/{phase3c-gateway-heartbeat-telemetry => archive/2026-07-30-phase3c-gateway-heartbeat-telemetry}/proposal.md (100%) rename openspec/changes/{phase3c-gateway-heartbeat-telemetry => archive/2026-07-30-phase3c-gateway-heartbeat-telemetry}/specs/gateway-heartbeat-telemetry/spec.md (100%) rename openspec/changes/{phase3c-gateway-heartbeat-telemetry => archive/2026-07-30-phase3c-gateway-heartbeat-telemetry}/tasks.md (100%) rename openspec/changes/{phase3c-provider-stream-policy => archive/2026-07-30-phase3c-provider-stream-policy}/.openspec.yaml (100%) rename openspec/changes/{phase3c-provider-stream-policy => archive/2026-07-30-phase3c-provider-stream-policy}/design.md (100%) rename openspec/changes/{phase3c-provider-stream-policy => archive/2026-07-30-phase3c-provider-stream-policy}/proposal.md (100%) rename openspec/changes/{phase3c-provider-stream-policy => archive/2026-07-30-phase3c-provider-stream-policy}/specs/provider-stream-policy/spec.md (100%) rename openspec/changes/{phase3c-provider-stream-policy => archive/2026-07-30-phase3c-provider-stream-policy}/tasks.md (100%) create mode 100644 openspec/specs/gateway-heartbeat-telemetry/spec.md create mode 100644 openspec/specs/provider-stream-policy/spec.md diff --git a/openspec/changes/phase3c-gateway-heartbeat-telemetry/.openspec.yaml b/openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/.openspec.yaml similarity index 100% rename from openspec/changes/phase3c-gateway-heartbeat-telemetry/.openspec.yaml rename to openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/.openspec.yaml diff --git a/openspec/changes/phase3c-gateway-heartbeat-telemetry/design.md b/openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/design.md similarity index 100% rename from openspec/changes/phase3c-gateway-heartbeat-telemetry/design.md rename to openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/design.md diff --git a/openspec/changes/phase3c-gateway-heartbeat-telemetry/proposal.md b/openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/proposal.md similarity index 100% rename from openspec/changes/phase3c-gateway-heartbeat-telemetry/proposal.md rename to openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/proposal.md diff --git a/openspec/changes/phase3c-gateway-heartbeat-telemetry/specs/gateway-heartbeat-telemetry/spec.md b/openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/specs/gateway-heartbeat-telemetry/spec.md similarity index 100% rename from openspec/changes/phase3c-gateway-heartbeat-telemetry/specs/gateway-heartbeat-telemetry/spec.md rename to openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/specs/gateway-heartbeat-telemetry/spec.md diff --git a/openspec/changes/phase3c-gateway-heartbeat-telemetry/tasks.md b/openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/tasks.md similarity index 100% rename from openspec/changes/phase3c-gateway-heartbeat-telemetry/tasks.md rename to openspec/changes/archive/2026-07-30-phase3c-gateway-heartbeat-telemetry/tasks.md diff --git a/openspec/changes/phase3c-provider-stream-policy/.openspec.yaml b/openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/.openspec.yaml similarity index 100% rename from openspec/changes/phase3c-provider-stream-policy/.openspec.yaml rename to openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/.openspec.yaml diff --git a/openspec/changes/phase3c-provider-stream-policy/design.md b/openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/design.md similarity index 100% rename from openspec/changes/phase3c-provider-stream-policy/design.md rename to openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/design.md diff --git a/openspec/changes/phase3c-provider-stream-policy/proposal.md b/openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/proposal.md similarity index 100% rename from openspec/changes/phase3c-provider-stream-policy/proposal.md rename to openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/proposal.md diff --git a/openspec/changes/phase3c-provider-stream-policy/specs/provider-stream-policy/spec.md b/openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/specs/provider-stream-policy/spec.md similarity index 100% rename from openspec/changes/phase3c-provider-stream-policy/specs/provider-stream-policy/spec.md rename to openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/specs/provider-stream-policy/spec.md diff --git a/openspec/changes/phase3c-provider-stream-policy/tasks.md b/openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/tasks.md similarity index 100% rename from openspec/changes/phase3c-provider-stream-policy/tasks.md rename to openspec/changes/archive/2026-07-30-phase3c-provider-stream-policy/tasks.md diff --git a/openspec/specs/gateway-heartbeat-telemetry/spec.md b/openspec/specs/gateway-heartbeat-telemetry/spec.md new file mode 100644 index 0000000..6b66d6c --- /dev/null +++ b/openspec/specs/gateway-heartbeat-telemetry/spec.md @@ -0,0 +1,26 @@ +# gateway-heartbeat-telemetry Specification + +## Purpose +TBD - created by archiving change phase3c-gateway-heartbeat-telemetry. Update Purpose after archive. +## 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 + +### Requirement: Delay and egress observations have one canonical meaning +Queue delay SHALL measure provider-queue residence, processing delay SHALL measure active gateway recovery/framing/QUIC work excluding queue and pacing, and pacing delay SHALL measure scheduler waiting only. Processing samples SHALL count complete provider media units rather than Verse fragments. Measured egress SHALL derive from transmitted-byte deltas over monotonic elapsed time and MUST NOT be copied from configured capacity. + +#### Scenario: One provider unit becomes multiple Verse frames +- **WHEN** one complete provider unit waits in the queue, traverses gateway processing, waits for pacing, and fragments into multiple Verse frames +- **THEN** each delay total includes only its defined interval and the heartbeat advances processing samples exactly once + diff --git a/openspec/specs/provider-stream-policy/spec.md b/openspec/specs/provider-stream-policy/spec.md new file mode 100644 index 0000000..3c8a863 --- /dev/null +++ b/openspec/specs/provider-stream-policy/spec.md @@ -0,0 +1,37 @@ +# provider-stream-policy Specification + +## Purpose +TBD - created by archiving change phase3c-provider-stream-policy. Update Purpose after archive. +## 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 + +### Requirement: Decode capabilities use registered ordered profiles +`CapabilityProfile.client_decode` SHALL be a non-empty ordered unique set containing only registered `h264-opus` and `hevc-opus` profile identifiers. It MUST NOT encode multiple capabilities in an opaque private token. + +#### Scenario: Independent peer advertises one registered profile +- **WHEN** an independent peer advertises one registered decode profile +- **THEN** canonical validation accepts that profile without requiring a combined private token + +### Requirement: Consumers share one ordered registered-profile intersection +Generated Protocol behavior SHALL select common registered profiles in the first peer's preference order. Provider consumers SHALL separately reject the resulting intersection when it cannot honor the immutable stream policy. + +#### Scenario: Policy-compatible profile overlaps +- **WHEN** the gateway advertises HEVC then H.264 and the client advertises only H.264 +- **THEN** the shared intersection selects `h264-opus` + +#### Scenario: No policy-compatible profile overlaps +- **WHEN** peers have no registered common profile +- **THEN** the shared intersection rejects admission without inventing a private combined token +