CDC

Change data capture for one tenant at a time. Tails are per-tenant. Bind /api/v1/t/:tenant/… (or Studio's tenant switcher) and stream that tenant's committed row mutations.

Capability: Status (Live CDC: Yes). Wire shapes and auth: HTTP API.

WebSocket vs HTTP poll

Same path: GET /api/v1/t/:tenant/tail.

Mode	How	When
WebSocket	Request includes Upgrade: websocket; auth via ?token= (browsers cannot set WS auth headers)	Preferred live push. Studio tries this first.
HTTP poll	Ordinary GET; response {"cursor":…,"events":[…]}	Fallback when WS is unavailable, or any simple client

Optional query: ?after=<lsn> (resume), ?collection=<name> (filter).

Studio live mode prefers WebSocket, reconnects with backoff from the last cursor, and falls back to ~1.5s HTTP poll if the socket never opens.

LSN resume

Each event carries an advancing write-frame lsn. Resume with after=<that lsn> to receive only later events (gapless within retained history). The HTTP poll also returns a tip cursor. Poll again with after=<cursor> to stream forward without repeats.

WebSocket sends a first hello frame (type, tenant, cursor), then one text frame per event (same event object shape as HTTP).

Events are served from a bounded in-process ring (WAL checkpoints recycle log segments). If a consumer falls behind retention, reload a full snapshot of the collections you care about, then resume from the new tip. Studio does a fresh connect path rather than inventing missing history.

Event fields (operator view): lsn, op (upsert / delete), collection, id. Exact JSON: HTTP: CDC tail.

Snapshot pin

Studio time-travel sets the Eelgrass-Snapshot header on API calls. While a named snapshot is pinned, live CDC is off. You are looking at the past, not the live tip. Clear the pin to resume live mode.

Cross-tenant read models

There is no cross-tenant ACID and no engine-wide CDC multiplex. across tenants(…) does not execute yet (Status).

App-layer pattern: emit CDC from each tenant, maintain a read model, coordinate with sagas. Isolation rules: Tenants.

Related

• HTTP API: auth, tail query params, event JSON
• CLI: eelgrass serve / studio
• Studio: live grids
• Operations: layout and health