deino-tide: SSE with backpressure and replay
Streaming cones without drowning the client — the stream is part of the manifest.
A forecast is not always a single response. As a simulation unfolds, the cone widens — scenarios branch, probabilities shift, entropy settles — and the client wants to watch it happen, not wait for it to finish. deino-tide is the SSE stream that carries that unfolding, and it carries it without drowning the client.
Server-Sent Events are a simple, one-way streaming protocol: the server pushes frames, the client reads them. The simplicity is the appeal and the trap. A naive SSE stream that pushes faster than the client can read will either block the server or drop frames — and in a platform where the stream is part of the audit record, dropping frames is not an option. deino-tide handles backpressure and replay so the stream is complete without the server stalling.
Backpressure: the stream respects the reader
Backpressure is the property that the producer slows down when the consumer is slow. In deino-tide, the SSE stream is driven by the simulation’s progress — scenarios produced, probabilities normalized in deino-oracle — and the frames are pushed at the rate the client can absorb. If the client falls behind, the stream does not drop; it waits. The simulation produces; the tide carries; the client reads. No frame is lost to a faster producer than consumer.
Replay: the stream is part of the manifest
The stream is not a throwaway UI affordance. It is part of the provenance. A client that watched a cone unfold saw the same frames the manifest records, and a third party replaying the decision can replay the stream — not just the final output, but the intermediate states that led to it. The stream is part of the manifest; the manifest is part of the stream. An auditor who asks what the client saw gets the stream, not a reconstruction of it.
The stream is not a UI affordance; it is part of the provenance. An auditor who asks what the client saw gets the stream, not a reconstruction of it.
Why SSE and not WebSocket
SSE is one-way, over HTTP, and that is the right shape for a forecast stream. The client does not need to send frames to the server; it needs to receive them. WebSocket is bidirectional and more complex, and for a cone that unfolds in one direction, the bidirectionality is cost without benefit. SSE is also reconnectable by protocol — the client drops, reconnects, and resumes — which is how the tide survives a flaky connection without losing the audit record. The simplicity is the property.
- Backpressure: the stream produces at the rate the client can read; no frame is dropped to a faster producer.
- Replay: the stream is part of the manifest — the intermediate states are provenance, not just the final output.
- SSE over WebSocket: one-way, HTTP, reconnectable. The bidirectionality of WebSocket is cost without benefit for a cone that unfolds one way.
- Authed, not per-request rate-limited: the tide is a stream, not a polled endpoint — rate limits live on the request that starts it.
The cone as a stream
The product surface is a probability cone — scenarios with probabilities, sorted descending, entropy in nats — and the cone is more useful as a stream than as a snapshot. A CRO watching the cone widen sees the uncertainty resolve or sharpen in real time; a snapshot hides the process. deino-tide streams the cone as it forms, with the normalization invariant (INV-1) holding at every frame: probabilities sum to one, scenarios sorted, entropy honest. The stream is the cone, and the cone is the deliverable. We are pre-revenue, building the POC; the tide streams, and the calibration that would make the cone trustworthy is gated (Gate 1b) until it is filled.
A snapshot hides the process; a stream shows it. For a cone, the process — widening, sharpening, settling — is the decision-relevant part. The tide carries the process, not just the result.
— deino-tide design note