docs site streams the workspace SDK against a pre-v2 backend on merge #568

Summary

The docs site is itself an SSE consumer of the ingest wire, and it is bound to the workspace SDK rather than a published one. The v2 envelope stack (#554) changes that wire. So the moment the stack merges, docs-deploy publishes a landing page whose SDK expects v2, pointed at a WaveHouse Cloud backend still running released v0.1.x.

Found by a pre-push reviewer on #554. Filing rather than fixing there, because every remedy is either a production sequencing decision or an SDK compatibility change — neither belongs in a wire-format PR.

The chain

1. docs/package.json:24 declares "@wavehouse/sdk": "workspace:*", and docs/node_modules/@wavehouse/sdk is a symlink to clients/ts — the docs bundle is built from whatever is on the branch.
2. docs/src/components/LiveDemo.astro:131 points at https://iefrrvavd5akvphk7pq3.wavehouse.app and calls .stream() at line 461. That is a separately-deployed backend on its own release cadence.
3. That backend cannot be v2: the v2 envelope is introduced by this stack and has never been released. No probing needed — there is no version of WaveHouse in the wild that emits it.
4. A pre-v2 server sends no event: schema frame, so SSEStream._columns stays null. Every data frame then hits the no-schema branch in clients/ts/src/stream/sse.ts:612-620 and returns.

Why it is worse than an outage

The frames are dropped with a bounded console.warn (three per cause per connection) and no error callback. The connection itself succeeds, so setStream still renders live, and the REST/pipe backfill still paints the feed. What stops is everything driven off next — refreshCounts, bumpEpm, recordLatency. The hero panel sits there claiming to be live with a frozen event rate and a stale latency figure, and nothing anywhere reports an error.

ci.yml:548 runs docs-deploy on any push to main where changes.outputs.docs == 'true', which the stack is.

Options

1. Sequence the stats-backend upgrade with the merge. Smallest change, but leaves the window open between the two, and it is manual every time the wire moves.
2. Pin docs to the published @wavehouse/sdk. Removes the coupling permanently and makes the docs site demo what users actually install — arguably what it should have been doing all along. Costs the ability to dogfood unreleased SDK changes on the docs site.
3. Give the SDK a one-release fallback: when no schema has been announced and a frame carries a legacy data object, zip it as before. This closes the same silent death for every SDK user upgrading across the boundary, not just this page — the general version of the bug.

(2) and (3) are not exclusive, and (3) is the one that matters beyond our own site: right now any user who upgrades the SDK before the server gets the same silent stall, which is not the behaviour a breaking wire change should have.

Also worth a look

While probing the stats backend I hit a structured query that returned rows in the wrong order — order_by on event_ts desc came back ascending and stale, while max(event_ts) reported a value 16 minutes old. It may be pipe/cache behaviour rather than a query bug, but it did not look right and is worth a separate check.