Durable Streams Compatibility
Golem implements the Durable Streams read, append, producer, deletion, expiry, and fork wire contracts on typed invocation-session paths. The unmodified @durable-streams/client can read, write, long-poll, subscribe with SSE, close, and delete Golem stream URLs. Golem does not claim to be an arbitrary-path generic stream store.
What is compatible
The following protocol areas apply and are covered by tests using the pinned, unmodified reference TypeScript client and by Golem’s HTTP and executor integration tests:
- JSON and byte creation, metadata, catch-up, long-poll, and SSE
-1,now, opaque offset resume, cursors, ETags, and binary SSE base64 encoding- append and atomic close, including idempotent producer duplicate, fencing, sequence-gap, and closed-stream behavior
- stream deletion and retained
410tombstones - sliding TTL and absolute expiry on a session
- exact-prefix forks, fork retries, sub-offsets, and source/fork divergence
- client-side subscription cancellation, which does not mutate the server stream
Golem also adds invocation-session manifests and cooperative session cancellation. Stream-Cancelled is a Golem response extension that identifies cancelled EOF.
Intentional differences
| Area | Golem behavior |
|---|---|
| Paths | Streams are declared by an agent method schema and live under {base}/invocations/{session}/streams/{slot}. Clients cannot create arbitrary paths or undeclared slots. |
| Types | JSON items are validated against the pinned method schema. Direct byte streams are opaque; other streams are JSON. |
| Deletion | Stream DELETE is a durable soft tombstone. Later authenticated/admitted GET, HEAD, POST, and DELETE return 410; PUT returns 409. The slot cannot be recreated within that existing session. |
| Retention | Golem retains stream and tombstone history with the agent oplog. There is no configurable retention horizon and no protocol 410 for data falling before a horizon. Retained history still consumes durable storage. |
| Expiry | Expiry applies to the complete invocation session. After expiry the family is 404, and a durable session can be freshly created with the same public session ID. This differs from a retained manual-delete tombstone. |
| Subscriptions | Reserved __ds subscription paths are not exposed and return 404. Use live=sse; generic subscription-management conformance areas do not apply. |
| Session cancellation | Session DELETE cooperatively cancels streams but does not interrupt agent computation, roll back state, or undo external effects. |
| Forks | A protocol fork is a Golem agent fork at the stream cut, not a storage-layer alias. It has an independent continuation and agent state. |
Do not treat manual deletion and expiry as equivalent. Manual deletion cannot
recreate a slot within its existing session. If that durable session later
expires, an explicit session PUT or eligible slot PUT can create a new
invocation under the same public session ID. Lazy POST returns 404 instead.
Upstream conformance suites
The upstream server-conformance-tests package assumes it can choose arbitrary paths, hard-delete and recreate a path, and manage generic subscriptions. Its runner has no path factory or capability filter, so it cannot be pointed at Golem unchanged.
Golem instead runs the unmodified reference client against real session-scoped routes and maintains equivalent scenarios for every applicable operation listed above. The following upstream areas are deliberately inapplicable:
- arbitrary stream-store path creation and enumeration
- hard deletion followed by recreation at the same stream URL
- retention-horizon behavior
__dssubscription resources
TTL/absolute-expiry and fork behavior are applicable and supported. For the exact statuses and headers, see Exposing Durable Streams over HTTP.