[AI-stack anchor] streams: no durable-CHAT integration — @netscript/fresh/ai seam (StreamDB shapes → Electric "Decoding failed")

[rickylabs]

Summary

@netscript/fresh/streams ships the generic StreamDB shape consumer (createNetScriptStreamDB + useLiveQuery) and documents it via the live-dashboard tutorial (a sagas / worker-executions data table) and web-layer/defer-streaming-ui.md. There is no durable-CHAT integration and no guidance that AI chat needs a different pattern. A developer building durable AI chat on netscript naturally reaches for the only documented streams-client surface (createNetScriptStreamDB + useLiveQuery) to back a chat transcript — and it does not work in the browser.

Symptom (real, from the eis-chat #13 build, alpha.18)

Backing a per-session chat transcript with a StreamDB collection — createNetScriptStreamDB({ streamPath, schema }) + useLiveQuery over a message collection — the server producer writes turns fine and the durable read endpoint returns the full transcript over plain HTTP (verified: GET /v1/stream/netscript/…/messages returns the rows, access-control-allow-origin: *, no auth required). But in the browser the ElectricSQL shape consumer throws:

[StreamDB] Stream consumer closed unexpectedly: TypeError: Decoding failed.   (db.js:271)
[chat-stream] preload FAILED TypeError: Decoding failed.

preload() rejects, useLiveQuery never populates, and the transcript only appears after a full page reload (the SSR seed). No optimistic user turn, no live tokens, no resume. The error is Electric's TextDecoder({ fatal: true }) on the shape stream (content-encoding: gzip; multibyte model output such as — / …). It is inherent to using the StreamDB shape consumer to back a chat transcript in the browser.

Root cause — wrong abstraction

StreamDB shapes (createNetScriptStreamDB + useLiveQuery) are for reactive data tables — exactly the sagas / worker-executions monitor the live-dashboard tutorial demonstrates. AI chat is a different pattern: it needs a TanStack-AI connection adapter that subscribes to the durable message stream and drives useChat (giving optimistic + live + resume + multi-tab). Per TanStack-AI's own docs (chat/connection-adapters.md, "Persistent Transports"), durable/multi-tab chat is a SubscribeConnectionAdapter passed to useChat — not a useLiveQuery shape. netscript ships the shape half and documents only that, so chat gets built on the wrong primitive.

The correct, first-party pattern (ElectricSQL "Durable Sessions")

• Package @durable-streams/tanstack-ai-transport:
  • client durableStreamConnection({ sendUrl, readUrl, initialOffset }) → useChat({ id, connection, live: true })
  • server toDurableChatSessionResponse({ stream: { writeUrl, headers }, newMessages, responseStream })
• The adapter swaps request/response for a sync paradigm: the chat client fetches history, then subscribes to the durable stream — optimistic + live + resume + multi-tab, natively, through useChat.
• readUrl is a proxy route the app builds (forwards offset + live + read auth to the durable read endpoint).
• Reference implementation: electric-sql/collaborative-ai-editor (chat + tool calls + model streams via the Durable Session pattern).
• Docs: durablestreams.com/tanstack-ai, electric-sql.com/blog/2026/01/12/durable-sessions-for-collaborative-ai, electric-sql.com/blog/2026/03/24/durable-transport-ai-sdks.

Ask

1. Ship a first-class durable-CHAT integration in @netscript/fresh/streams — re-export / wrap @durable-streams/tanstack-ai-transport (durableStreamConnection + toDurableChatSessionResponse) with netscript URL/auth resolution (the same getStreamsUrl / getStreamsAuth / buildStreamUrl seam createNetScriptStreamDB already uses), plus a documented /api/chat-stream proxy recipe. Given @netscript/plugin-streams is the durable-streams runtime, the AI transport is the missing client half.
2. Docs: explicitly distinguish StreamDB-shapes (data tables) vs Durable-Sessions (AI chat) in capabilities/streams.md + web-layer/defer-streaming-ui.md + the live-dashboard tutorial, and steer AI chat AWAY from createNetScriptStreamDB / useLiveQuery toward the durable connection adapter + useChat. Right now the only streams-client example is the shape consumer, which is a footgun for chat.
3. Possibly a bug to verify upstream: the generic createNetScriptStreamDB shape consumer throws TypeError: Decoding failed on gzip'd / multibyte shape streams in the browser (@durable-streams/state@0.3.1, db.js:271). Worth confirming whether the shape decoder needs TextDecoder({ stream: true }) or whether the streams runtime should not content-encoding: gzip a streaming shape — independent of the chat pattern, it affects any non-ASCII shape.

Context: eis-chat #13 durable-stream chat, netscript alpha.18. Related: the streams service is a proxy that forwards the durable-streams engine's content-encoding (plugins/streams/services/src/main.ts).

Part of #238

[rickylabs]

Update — root cause proven at the wire, plus a confirmed workaround + local fixes (leads for an enterprise-grade solution)

Since filing, I reproduced this live against the running streams runtime (:4437, alpha.18) and it is unambiguous: the streams runtime declares content-encoding: gzip on a body that is never gzip-compressed.

Wire proof

Direct GET of a durable chat stream on the streams service:

GET /v1/stream/netscript/eischat/sessions/<id>/messages   (upstream :4437)

HTTP/1.1 200 OK
content-encoding: gzip            ← claims gzip
content-type: application/json
transfer-encoding: chunked
access-control-expose-headers: …,content-encoding,…   ← deliberately exposed

body (first bytes, hex):  5b 7b 22 74 79 70 65 22 3a 22 54 45 58 54 …
                          =  [  {  "  t  y  p  e  " :  " T  E  X  T …

The body starts with 5b 7b ([{) — literal JSON. A real gzip stream starts with the magic bytes 1f 8b. So the payload is plain application/json mislabeled as gzip.

Every standards-compliant reader that honors content-encoding then fails:

consumer	error
browser fetch / DecompressionStream (Electric shape reader)	TypeError: Decoding failed
Deno fetch (auto-decompress)	TypeError: Invalid gzip header
curl --compressed	curl: (61) … incorrect header check

This is the single root cause behind the "Decoding failed" symptom in the original report — it is not specific to the Electric shape consumer; it breaks any compliant client, including a plain server-side proxy.

Confirmed workaround

Requesting identity encoding makes the runtime drop the bogus header and return the JSON as-is:

GET … with header:  Accept-Encoding: identity

HTTP/1.1 200 OK
content-type: application/json     ← no content-encoding at all
body:  [{"type":"TEXT_MESSAGE_START", …    ← clean

So the runtime can serve identity correctly; the bug is that its default response advertises gzip without compressing.

Local fixes I applied (consumer side) — as leads

In our app (durable AI chat via @durable-streams/tanstack-ai-transport) I worked around it entirely on the client/proxy side. These point at where an enterprise-grade runtime-side fix should land:

1. Accept-Encoding: identity on every durable READ — the readUrl proxy fetch and the SSR materializeSnapshotFromDurableStream call. Removes the mislabel by opting out of encoding negotiation. This is a band-aid every consumer will independently rediscover — hence this issue.

2. Do not forward the client abort signal into the upstream proxy fetch. A durable SSE read is a long poll the browser closes routinely (poll cycling, unmount, navigation). Piping the upstream body while tying it to the request AbortSignal turns every normal disconnect into an AbortError that the server adapter surfaces as an uncaught error. We re-stream through an explicit ReadableStream whose cancel() cancels the upstream reader instead — same cleanup, no noisy rejection. Worth checking the runtime's own proxy layer does the same when it fronts the durable-streams engine.

3. STREAM_NOT_FOUND (404) has no client retry. useChat({live:true}) opens its read subscription on mount; on a brand-new session the stream does not exist yet (the producer's createIfMissing runs only on the first write, which is after the subscription has already 404'd), so the first turn stalls until a hard refresh. We fixed it by calling ensureDurableChatSessionStream (create-only PUT) server-side before the client subscribes. An enterprise-grade runtime/client could instead: (a) treat a live read of a missing stream as "empty, up-to-date, keep polling" rather than a hard 404; or (b) have the client subscribe() retry STREAM_NOT_FOUND with backoff. Today a fresh-session subscribe is a guaranteed race.

Suggested runtime-side fix (the real one)

The streams service is a proxy in front of the durable-streams engine. The mislabel almost certainly comes from forwarding the engine's content-encoding: gzip header while the body has already been decompressed in transit (or the header is set unconditionally). Any of these makes it correct:

• if the proxy decompresses (or never compresses) the body, it must strip/rewrite content-encoding so it matches the bytes on the wire;
• honor Accept-Encoding negotiation end-to-end (identity when the client doesn't ask for gzip);
• or actually gzip the bytes when advertising gzip (magic 1f 8b).

Whichever path, the invariant is: content-encoding must describe the bytes actually sent. Right now it doesn't, and every downstream (@durable-streams/state shape reader, @durable-streams/client, any HTTP proxy) has to special-case it. Fixing it at the runtime removes the per-consumer Accept-Encoding: identity band-aid entirely.

Reproduced on netscript alpha.18; consumer stack is @durable-streams/tanstack-ai-transport@0.0.8 + @durable-streams/client@0.2.6 + @netscript/plugin-streams@0.0.1-alpha.18.

[rickylabs]

Folded into the NetScript AI Stack epic → #238.

That epic carries the full architectural research pass (Fable 5, rev. 2) that anchors on this issue. #219 splits into two tracked pieces there:

• Slice 0 — the gzip-mislabel bug fix (~15 LOC in plugins/streams/services/src/main.ts proxyHandler: strip content-encoding/content-length/hop-by-hop after the inner fetch). Ships first, standalone. Acceptance = deleting the three Accept-Encoding: identity workaround sites in the consumer.
• Slice 1 — the first-class durable-CHAT seam (@netscript/fresh/ai), which documents StreamDB-shapes (data tables) vs Durable-Sessions (AI chat) so a transcript is never built on the wrong primitive again.

Keeping this issue open as the anchor; sub-issues will be carved from the epic.