spec(protocol): define terminal event receipt

2026-07-30 10:48:08 +07:00
parent 37c041e13e
commit 5a33e8b2ed
8 changed files with 97 additions and 6 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-30
@@ -0,0 +1,26 @@
+## Context
+
+QUIC stream writes complete before peer receipt. The previous gateway avoided losing its last control frame by waiting for client-owned connection closure; immediate gateway closure reproduced event loss. `control.ack.v1` is already reliable and bidirectional, so no new flow is needed.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Represent peer receipt of the one terminal control event.
+- Keep the message bounded, direction-specific, and independent of provider data.
+
+**Non-Goals:**
+
+- General acknowledgements, retries, lifecycle state, or provider transport semantics.
+- Changes to JSON schemas or generated bindings.
+
+## Decisions
+
+- Assign client-direction `VGF1` type `0x03` with an empty payload to terminal receipt.
+- Permit it only after a terminal event; the Data Plane enforces session state and deadline.
+- Preserve all existing message bytes and meanings.
+
+## Risks / Trade-offs
+
+- [Older clients do not send the receipt] → The gateway closes at its bounded receipt deadline; compatibility does not transfer tunnel ownership back to the client.
+- [A stale receipt is replayed] → The gateway rejects receipts outside the single awaiting-terminal state.
@@ -0,0 +1,23 @@
+## Why
+
+A public independent QUIC regression proved that closing the gateway connection immediately after writing the reliable terminal event can discard that event, while waiting for the client to close leaves session ownership with the client. The registered bidirectional control flow needs one bounded receipt semantic so the gateway can close only after observed delivery or a fixed receipt deadline.
+
+## What Changes
+
+- Add a client-to-gateway terminal receipt to the existing bounded `VGF1` envelope on `control.ack.v1`.
+- Keep the receipt payload empty and valid only while one terminal event is awaiting receipt.
+- Preserve the existing IDR, FEC, termination, rumble, and HDR meanings.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `gateway-input-feedback`: Permit the narrowly scoped terminal receipt in the existing reliable control envelope.
+
+## Impact
+
+This changes the immutable Protocol semantics consumed by the GPLv3 Data Plane and independent Verse clients. It adds no schema field, dependency, provider address, credential, generic acknowledgement framework, or provider-facing message.
@@ -0,0 +1,23 @@
+## MODIFIED Requirements
+
+### Requirement: Bounded provider feedback control envelope
+The registered bidirectional reliable `control.ack.v1` flow SHALL define an ASCII `VGF1` envelope
+with a direction byte, type byte, big-endian payload length, and exact payload
+bytes. Only host termination, rumble, and HDR feedback SHALL be valid from the
+gateway to the client. Only IDR, FEC/loss feedback, and an empty terminal receipt
+SHALL be valid from the client to the gateway. The terminal receipt SHALL be
+valid only while the same session awaits receipt of its one terminal event and
+MUST NOT be forwarded to the provider. The envelope SHALL contain no provider
+address, certificate, credential, or opaque provider packet.
+
+#### Scenario: Host termination forwarding
+- **WHEN** the Apollo adapter receives an authenticated host termination packet
+- **THEN** the gateway forwards a bounded `VGF1` termination envelope over reliable Verse control and reports the provider state separately
+
+#### Scenario: Terminal event receipt
+- **WHEN** a client receives the reliable typed terminal event
+- **THEN** it sends the empty terminal receipt and the gateway owns bounded tunnel closure without forwarding the receipt to the provider
+
+#### Scenario: Unauthorized or malformed feedback
+- **WHEN** feedback is disabled by policy, has an invalid direction/type/length, contains a forbidden provider field, or sends a terminal receipt outside the awaiting-terminal state
+- **THEN** the gateway rejects it without forwarding or provider mutation
@@ -0,0 +1,9 @@
+## 1. Contract
+
+- [x] 1.1 Define the empty client-direction terminal receipt on `control.ack.v1`
+- [x] 1.2 Run complete Protocol verification and deterministic generation checks
+
+## 2. Immutable release
+
+- [ ] 2.1 Publish one new never-reused immutable Protocol version after final contract verification
+- [ ] 2.2 Resolve the version from separate empty consumer caches and record exact checksums
@@ -1,7 +1,7 @@
 # gateway-heartbeat-telemetry Specification

 ## Purpose
-TBD - created by archiving change phase3c-gateway-heartbeat-telemetry. Update Purpose after archive.
+Define the bounded, low-cardinality gateway observations carried by authenticated heartbeats and their canonical units and exclusions.
 ## 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`.
@@ -40,9 +40,11 @@ an implementation-specific release-all provider command.
 The registered bidirectional reliable `control.ack.v1` flow SHALL define an ASCII `VGF1` envelope
 with a direction byte, type byte, big-endian payload length, and exact payload
 bytes. Only host termination, rumble, and HDR feedback SHALL be valid from the
-gateway to the client; only IDR and FEC/loss feedback SHALL be valid from the
-client to the gateway. The envelope SHALL contain no provider address,
-certificate, credential, or opaque provider packet.
+gateway to the client. Only IDR, FEC/loss feedback, and an empty terminal receipt
+SHALL be valid from the client to the gateway. The terminal receipt SHALL be
+valid only while the same session awaits receipt of its one terminal event and
+MUST NOT be forwarded to the provider. The envelope SHALL contain no provider
+address, certificate, credential, or opaque provider packet.

 #### Scenario: Host termination forwarding
 - **WHEN** the Apollo adapter receives an authenticated host termination
@@ -50,9 +52,15 @@ certificate, credential, or opaque provider packet.
 - **THEN** the gateway forwards a bounded `VGF1` termination envelope over
  reliable Verse control and reports the provider state separately.

+#### Scenario: Terminal event receipt
+- **WHEN** a client receives the reliable typed terminal event
+- **THEN** it sends the empty terminal receipt and the gateway owns bounded
+  tunnel closure without forwarding the receipt to the provider.
+
 #### Scenario: Unauthorized or malformed feedback
 - **WHEN** feedback is disabled by policy, has an invalid direction/type/length,
-  or contains a forbidden provider field
+  contains a forbidden provider field, or sends a terminal receipt outside the
+  awaiting-terminal state
 - **THEN** the gateway rejects it without forwarding or provider mutation.

 ### Requirement: Policy-bound text clipboard envelope
@@ -1,7 +1,7 @@
 # provider-stream-policy Specification

 ## Purpose
-TBD - created by archiving change phase3c-provider-stream-policy. Update Purpose after archive.
+Define immutable provider stream-policy fields and the registered ordered decode-profile intersection shared by all generated bindings.
 ## 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.