VerseVDI-Protocol/openspec/changes/gateway-terminal-receipt/design.md

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.