@kedem/okdb 1.8.17 → 1.9.0

package/docs/processors.md

@@ -9,15 +9,29 @@ A **processor** maintains derived state from a source type's change log. You reg
 
 OKDB's own features (indexes, views, FTS, materializer, embeddings, time-machine) are built on this primitive — and it's a public extension point you can use directly.
 
+> **See also:** [Workers](worker-fleet.md) for _where_ a processor's work runs — the worker
+> population, claiming, and scaling. This doc defines _what_ a processor is and its **modes**
+> (the guarantee); worker-fleet.md covers placement.
+
 ---
 
-## Modes — where and when your handler runs
+## Modes — the delivery guarantee
+
+A mode names the **delivery guarantee**: how many instances run the handler. Handlers are always **closures** that run in **this process** — trusted derived work runs on the main event loop, chunked into cooperative quanta so a large drain never blocks the loop monolithically (see `plans/runtime-model/overview.md`). There is no worker-thread or worker-process placement choice: the only off-loop thread in the system is the function sandbox (for untrusted user code), never trusted processor work.
+
+| mode     | cardinality                         | cursor                      | use when                                                                                       |
+| -------- | ----------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- |
+| `inline` | every writer, inside commit         | —                           | derived state must be consistent the instant the write returns, and the work is cheap          |
+| `single` | exactly one claimant topology-wide  | durable (at-least-once)     | background derived work drained on the loop; the lease makes it 1-of-N across processes        |
+| `fanout` | every registered instance, own loop | ephemeral (resume-from-now) | N-of-N consumers: each instance runs its own copy, effects must be process-local or convergent |
+
+> **Deprecated aliases.** `single` and `fanout` were previously named `worker` and `async` (released in 1.8.x). The old names still work as **deprecated aliases** — `register()`/`setMode()` accept them and map to the canonical names, warning once per process. `stop.status().mode` always reports the canonical `single`/`fanout`/`inline`.
 
-| mode     | runs                                         | use when                                                                                             |
-| -------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `inline` | synchronously inside the writer's commit     | derived state must be consistent the instant the write returns, and the work is cheap                |
-| `async`  | post-commit, batched, on the main event loop | default for light/moderate derived work                                                              |
-| `worker` | post-commit, batched, on a **worker thread** | per-event work is CPU-heavy (parse / tokenize / encode / compress) and you want it off the main loop |
+**Cardinality contracts:**
+
+- `single` (1-of-N): a cluster-wide lease ensures exactly one process drains the log at a time. Others wait and take over if the holder dies. Use for derived state that must have a single authoritative writer. The drain runs on the holder's main loop, chunked; the cursor advances only on a successful drain (at-least-once → write idempotent handlers).
+- `fanout` (N-of-N): no lease; every registered instance runs independently from its own in-memory cursor (seeded to "now" at registration — no history replay on restart). Use for process-local derived state, or idempotent/convergent effects. `bootstrap` is always `'none'` — fanout processors do not run snapshot bootstraps.
+- `inline` (every writer): runs synchronously inside the commit. **M3 closure advisory**: a plain-closure inline handler is fine for a single writer process, but with multiple writer processes (HTTP cluster workers, fn runners, workers) other instances' writes silently bypass it — `register()` warns once. Declare `definition: { durable: true }` (your code reconstructs the handler on every instance at open — the views/indexes pattern) to silence it. `setMode(…, 'inline')` — which actively creates the multi-writer hazard — hard-rejects plain closures (`PROC_INLINE_REQUIRES_DURABLE_DEFINITION`).
 
 ---
 
@@ -25,7 +39,7 @@ OKDB's own features (indexes, views, FTS, materializer, embeddings, time-machine
 
 ```javascript
 const stop = env.processor.register('Order', {
-    mode: 'async',
+    mode: 'fanout',
     name: 'order-stats', // shown in admin / status
     cursorKey: 'order-stats', // durable resume key — unique per processor
     originMode: 'all', // 'self' | 'remote' | 'all'
@@ -43,87 +57,69 @@ stop.pause();
 stop.resume();
 ```
 
-`changes` are change-log records (`{ type, key, action, clock, ... }`). In `async` mode with the default `hydrateValues: true`, `put` records also carry `.value` (the current document). In `worker` mode you hydrate yourself — see below.
+The `handler` is always a **closure** (a function). The portable `handler: {module, export}` form — which ran on a worker thread — was removed alongside the worker-thread executor; passing it now throws. Move shared handler logic into a module your closure calls (`const apply = require('./my-handler'); handler: (changes, info) => apply(changes, info)`) if you want to reuse it across registrations.
+
+`changes` are change-log records (`{ type, key, action, clock, ... }`). With the default `hydrateValues: true`, `put` records also carry `.value` (the current document); otherwise read the document via `info.env.get(c.type, c.key)`.
 
 `originMode` filters by who wrote the change: `self` (this instance's writes only), `remote` (other instances/processes), or `all`.
 
+**`rebuild` (snapshot-bootstrap processors).** With `bootstrap: 'snapshot'` you may pass `rebuild: async () => { ... }` — a feature-owned **full rebuild** (scan the actual docs, then reposition the cursor via `setCursor` + `markSnapshotComplete`). It runs whenever the processor bootstraps with an **un-positioned cursor**: after a cursor reset (the admin ⟲ "full reprocess"), or when a build handoff was interrupted by a crash. Without it, the framework's only option is replaying the changelog from 0 — which is **not** a rebuild: sync-GC prunes the changelog (its horizon ignores processor cursors), so replay-from-0 can silently yield a partial derived store. FTS registers one (re-scans all docs of the type into every index, clearing first).
+
 ---
 
-## `worker` mode and `workerKey` (sharing)
+## Snapshot bootstrap and chunked drains
 
-`worker` mode runs your handler on a worker thread. It requires a **resolvable handler module** — a file path and export name, **not a closure** (closures can't cross the thread boundary; the worker loads the module in its own isolate):
+A `single` processor with `bootstrap: 'snapshot'` performs a cooperative snapshot scan on the main loop, yielding every batch so the event loop stays responsive while a large type is bootstrapped. Live drains use the same chunked `_flush` (a `FLUSH_QUANTUM` bounds each on-loop quantum, then yields). This is exactly the path FTS uses: every FTS-indexed type registers a `single`-mode processor whose closure handler hydrates + tokenizes + writes postings, drained on the loop in quanta. There is no shared worker thread and no `workerKey` — those were removed in the runtime-model rework.
 
-```javascript
-env.processor.register('Doc', {
-    mode: 'worker',
-    workerKey: `myfeature:${env.name}`, // optional — see below
-    cursorKey: 'myfeature:Doc',
-    originMode: 'all',
-    handler: { module: require.resolve('./my-handler.js'), export: 'handle' },
-});
-```
+The cursor only advances on a successful drain, so processing is **at-least-once**; make handlers idempotent. Derived state is eventually-consistent; if you need a deterministic "caught up" point, wait on `stop.status().lastClock` reaching the source clock.
 
-**`workerKey` controls sharing:**
+---
 
-- **Omit it** → a **dedicated** worker for this processor (the key defaults to the processor's own id). Best for isolation, or for genuinely parallel CPU work across separate threads.
-- **Set the same key** on several processors → they **share one** worker thread (and one OKDB instance), processing drains serially. This is what FTS does: every FTS-indexed type registers a `worker`-mode processor with `workerKey: 'fts:<env>'`, so the whole env's FTS indexing runs on a single shared worker. All processors sharing a key **must declare the same handler module/export** (validated at registration).
+## Cross-process behaviour
+
+Each processor takes a lease (the `'proc'` lock). With several processes open on the same env, exactly one runs each `single` processor; the others wait and take over if the holder dies. The lease-holding process drains on its own loop, so there is always a single writer to your derived store.
 
-The worker is **lazily spawned** on the first real work, **torn down after `workerIdleMs`** of idle (default 30 s), and **respawns automatically** (the cursor is durable, so no state is lost). If the worker dies or a single drain exceeds `drainTimeoutMs` (default 60 s), the in-flight work is retried — the cursor only advances on success, so processing is **at-least-once**; make handlers idempotent.
+A processor that hits an error **keeps its lease** (in-place `retry()`/`restart()` keeps its slot against standbys in other processes). Re-bootstrap reuses the held lease handle, and `tryAcquire` treats a fresh lease held by the same pid + processorId as a re-acquire — so an errored processor can never deadlock in `waiting` against its own heartbeat.
 
 ---
 
-## Writing a worker handler module
+## Cookbook
 
-The module loads in a fresh worker isolate, so it must be **self-contained** and **replay any state it needs from durable sources** (disk / the env) — in-process registrations made on the main thread are not visible to it.
+- **A background derived indexer (like FTS)** — `mode: 'single'`, closure handler, drained on the loop in chunked quanta.
+- **An immediate-consistency derived field** — `mode: 'inline'` (cheap work only; it runs on the write path).
+- **A light aggregate on the main loop** — `mode: 'fanout'`.
 
-```javascript
-// my-handler.js
-module.exports = {
-    // optional — called once at worker startup (open derived sub-DBs, read config, …)
-    async init({ env }) {
-        this.store = env.openDB?.('my-derived');
-    },
+---
 
-    // called per drain; `changes` are RAW (not hydrated) — read values via info.env
-    async handle(changes, info) {
-        const env = info.env; // the worker's own OKDBEnv — real reads/writes
-        for (const c of changes) {
-            if (c.action === 'put') {
-                const doc = c.value ?? env.get(c.type, c.key); // hydrate on demand
-                /* ...update your derived state via env / your sub-DBs... */
-            } else if (c.action === 'remove') {
-                /* ...handle deletion... */
-            }
-        }
-    },
-};
+## Runtime mode switching (M6)
 
-// A plain function export also works:
-//   module.exports = async function handle(changes, info) { ... }
-// register with export: 'handle' (or the function's name); it must resolve to a function.
-```
+`env.processor.setMode(logicalKey, mode)` (HTTP: `POST /api/processors/:logicalKey/mode`)
+switches a processor's mode at runtime through a durable config record (registry
+desired-state scope `'procmode'`) + a clock-boundary handoff:
 
-Rules, stated plainly:
+| transition        | mechanics                                                                                                                                                                    |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `single → fanout` | holder drains to clock C, releases the lease; every instance seeds its in-memory cursor at C                                                                                 |
+| `fanout → single` | instances stop at the flip; durable cursor seeded at max(C, head-at-observance); lease claiming begins                                                                       |
+| `* → inline`      | M3 gate re-checked (closures without a durable definition → rejected); gap-fill to head; a per-write version gate makes every writer observe the flip before its next commit |
+| `inline → *`      | inline stops on observance; the deferred cursor starts at the observance clock                                                                                               |
 
-- **Resolvable module + export**, never a closure.
-- The worker has its **own OKDB** open on the same path (background features off). It shares the underlying LMDB storage with the main process, so your writes are visible to it — and to readers/queries — immediately on commit.
-- **Raw changes**: in worker mode the framework does not pre-hydrate; read `info.env.get(c.type, c.key)` when you need the document.
-- **You don't manage the cursor** — the main thread owns it and advances it only when your `handle` resolves. Throwing makes the framework retry the range (at-least-once) → write **idempotent** handlers.
-- **Be worker-portable**: read schemas / config / definitions from disk in `init`, not from closures.
+Transitions are serialized per processor (a flip while one is unapplied → `PROC_MODE_FLIP_IN_FLIGHT`).
+Overlap windows double-run the deferred mode — the (already required) idempotency contract makes
+that safe. The per-write gate costs one boolean compare per write when no flip is pending.
 
 ---
 
-## Cross-process behaviour
-
-Each processor takes a lease (the `'proc'` lock). With several processes open on the same env, exactly one runs each processor; the others wait and take over if the holder dies. Worker sharing is per-process — the lease-holding process's worker does the work, so there is still a single writer to your derived store.
+## Instance processing policy
 
----
+The `processing` constructor option controls where **this instance** drains processors. It is independent of the mode declared at `register()`.
 
-## Cookbook
+| value    | behavior                                                                                                                |
+| -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `'auto'` | **default.** Self-process on the loop when no workers are configured; yield to the population when desired workers > 0. |
+| `'main'` | Self-process on the main event loop (diagnostic / single-process environments).                                         |
+| `'none'` | Never drain (passive/read-only instances). Used internally for HTTP cluster workers.                                    |
 
-- **A dedicated CPU-heavy indexer** — `mode: 'worker'`, no `workerKey`.
-- **Several indexers sharing one thread/OKDB (like FTS)** — `mode: 'worker'`, same `workerKey`.
-- **An immediate-consistency derived field** — `mode: 'inline'` (cheap work only; it runs on the write path).
-- **A light aggregate on the main loop** — `mode: 'async'`.
+> **Deprecated:** `processing: 'threads'` / `'processes'` (the old worker-thread/process pool) are accepted with a one-time deprecation warning and mapped to `'auto'` — the pool executor was removed in the runtime-model rework; trusted drains run on the loop.
 
-> Note: a `worker` processor adds first-index latency after idle (the lazy OKDB spawn ≈ a few hundred ms). Derived state is eventually-consistent; if you need a deterministic "caught up" point, wait on `stop.status().lastClock` reaching the source clock.
+`'auto'` is the recommended default for application code. When a population is configured via `db.workers.ensure()`, `'auto'` instances automatically stop claiming leases so population workers drain instead — no configuration change required at the embedder.

package/docs/queue.md

@@ -22,7 +22,10 @@ async function main() {
     const okdb = new OKDB('./db');
     await okdb.open();
 
-    const worker = okdb.queue.worker(
+    // process() runs the consumer IN THIS process (it takes a closure). For a consumer that
+    // runs on the worker population or a dedicated child, use worker(type, module) /
+    // spawn(type, module) — those cross a process boundary, so they take a module path.
+    const worker = okdb.queue.process(
         'send-email',
         async (payload, ctx) => {
             await ctx.markProgress('sending email');
@@ -37,7 +40,6 @@ async function main() {
         },
         {
             concurrency: 4,
-            pollInterval: 100,
             ttl: 30_000,
         },
     );
@@ -142,12 +144,12 @@ Notes:
 
 ---
 
-## Processing jobs with `worker(...)`
+## Processing jobs with `process(...)`
 
-Use a normal in-process worker like this:
+Use a normal in-process consumer like this:
 
 ```javascript
-const worker = okdb.queue.worker(
+const worker = okdb.queue.process(
     'send-email',
     async (payload, ctx) => {
         await ctx.markProgress('validating');
@@ -165,7 +167,6 @@ const worker = okdb.queue.worker(
     },
     {
         concurrency: 2,
-        pollInterval: 250,
         ttl: 30_000,
         onPermanentFail: async (job, err) => {
             console.error('permanently failed', job.id, err.message);
@@ -197,22 +198,31 @@ These local worker helpers now map to the same public queue API that remote work
 - `okdb.queue.markJobComplete(jobId, claimId, result?)`
 - `okdb.queue.markJobFail(jobId, claimId, error, code?)`
 
-### Important note
+### Placement: `process` vs `worker` vs `spawn`
 
-`worker(...)` runs in the **same Node process** unless you explicitly use `spawn(...)` or a separate worker process yourself.
+The three verbs split on **where the consumer runs** — and therefore on whether they take a closure or a module:
 
-That means:
+| Verb                         | Runs in                                     | 2nd arg                                | Lifetime                   |
+| ---------------------------- | ------------------------------------------- | -------------------------------------- | -------------------------- |
+| `queue.process(type, fn)`    | **this** Node process                       | a **closure**                          | dies with this instance    |
+| `queue.worker(type, module)` | the **worker population** (other processes) | a **module path** / `{module, export}` | durable; the fleet runs it |
+| `queue.spawn(type, module)`  | a **dedicated forked child**                | a **module path**                      | tied to the child          |
+
+A closure can't cross a process boundary, so `worker()`/`spawn()` require a module. Passing a closure to `worker()` is an error that points you at `process()`.
 
-- great for I/O-heavy jobs
-- not isolation from CPU-heavy work
+`process(...)` is great for I/O-heavy jobs but gives no isolation from CPU-heavy work — use `spawn()` (dedicated child) or `worker()` (population) for that.
 
 ---
 
 ## Worker options
 
+### No polling — event-driven wakeup
+
+A consumer does **not** poll. An idle lane sleeps on a wake handle and resumes immediately when work appears: a local `enqueue` (same process), a job finishing (frees a `max_concurrency` slot), or a cross-process queue write (the UDP bus POKE). The only timer is a long **backstop** (default 30 s, `OKDB_QUEUE_IDLE_MS`) that exists solely to cover a dropped bus POKE and to wake for time-scheduled jobs — the lane caps its sleep at the soonest future `when`, so delayed jobs still fire on time.
+
 ### `pollInterval`
 
-How long to sleep when the queue is empty.
+Optional. When set, it **caps the idle backstop** for this consumer (an upper bound on wakeup latency if a bus POKE is ever dropped). It is no longer a poll cadence — leave it unset to get the default 30 s backstop with instant event-driven pickup.
 
 ```javascript
 {
@@ -363,7 +373,7 @@ When a running job's claim expires, reconciliation moves it back to `pending`.
 For long-running jobs, call `ctx.heartbeat()` periodically:
 
 ```javascript
-okdb.queue.worker(
+okdb.queue.process(
     'import',
     async (payload, ctx) => {
         for (let i = 0; i < 10; i++) {

package/docs/subscriptions.md

@@ -0,0 +1,230 @@
+# Live Subscriptions
+
+Live subscriptions let a client watch a data environment for changes in real time over
+Server-Sent Events (SSE). OKDB uses a **signal-SSE + durable-session** model: the SSE
+stream carries only lightweight **signals** — never document data — and the client
+refetches the truth it needs from the normal query API.
+
+## The two-domain rule at the client edge
+
+OKDB internally separates the lossy **signal** plane (the UDP bus) from the durable
+**data** plane (LMDB). Subscriptions apply the same split to the client connection:
+
+- **SSE carries signals only** — `{ type, key, op, clock }`. No `value`, no `prevValue`.
+- **Data comes from the query API** — on a signal, the client refetches the affected
+  key(s)/queries (`get`/`query`, which already solve filter/sort/limit/pagination) and
+  reconciles its local view.
+- **The subscription is a durable, shared resource** — it lives in a dedicated `~sub`
+  environment (`sync:false`), reachable by every process on the same LMDB path. The
+  connection-owning worker is not a single point of truth.
+- **The client owns its view** (the matched set). The server never stores or maintains it.
+
+This makes subscriptions correct under clustering and multiple processes by construction
+(shared LMDB + path-local POKE), with no cross-worker IPC routing.
+
+## Endpoints
+
+All routes are under `/api/<dataEnv>/subscriptions`, where `<dataEnv>` is the real data
+environment whose changes you want to watch.
+
+| Method   | Path                                   | Purpose                                           |
+| -------- | -------------------------------------- | ------------------------------------------------- |
+| `GET`    | `/subscriptions?type=…&filter=…&sub=…` | Open the signal SSE stream; mint/accept a session |
+| `POST`   | `/subscriptions/:id/interests`         | Add/remove key interests (`{ add?, remove? }`)    |
+| `PUT`    | `/subscriptions/:id/interests`         | Replace the full interest set (`{ interests }`)   |
+| `POST`   | `/subscriptions/:id/filter`            | Set the enter-discovery filter (`{ filter }`)     |
+| `DELETE` | `/subscriptions/:id`                   | Close the session (interests cascade)             |
+
+`:id` is the `sessionId` issued in the first SSE frame.
+
+## The signal stream
+
+`GET /api/<dataEnv>/subscriptions` opens an SSE stream:
+
+1. **Open frame** — the server mints a `sessionId` (or accepts `?sub=<id>` to reuse one),
+   persists a durable `~sub` `session` record, and sends the id as the first frame:
+
+    ```
+    event: subscription:open
+    data: { "sessionId": "…", "env": "default", "type": "Order", "filter": null, "reconnect": false }
+    ```
+
+2. **Signals** — every change matching the session's interests/filter arrives as:
+
+    ```
+    id: <clock>
+    event: signal
+    data: { "type": "Order", "key": "o-42", "op": "put", "clock": 1234 }
+    ```
+
+    Signals never carry document data. The client refetches `Order/o-42` and updates its
+    view. `op` is `put` or `remove`; `clock` is the per-`(env,type)` changelog clock.
+
+3. **Heartbeat / liveness** — a periodic beat (default 30s) refreshes the session's TTL
+   (default 90s, skip-if-far so most beats are free) and re-checks `session.version` to
+   pick up control changes. A `: ping` SSE keepalive rides the same beat.
+
+4. **Disconnect** — a clean disconnect deletes the `session` (its `interest` rows cascade
+   via FK `onDelete`). An unclean drop is reaped by TTL. Nothing leaks.
+
+## Interests: keys vs. filter
+
+A session expresses what it tracks two ways (combine as needed):
+
+- **Explicit key interests** — for the keys the client currently shows. Register on enter,
+  deregister on leave. Best for small/specific sets; there is a configurable cap on the
+  number of explicit keys — push large/dynamic sets to a filter instead.
+- **A declarative filter** — a `sift` query on the type. The router does **forward-only**
+  enter-discovery: when a change to the type matches the filter and the session isn't
+  already tracking that key, it signals an **enter candidate**.
+
+Filters are declarative objects only (never functions — injection-safe), the same matcher
+items/views/FTS use.
+
+## Control plane (no IPC)
+
+Control is plain REST keyed by `sessionId`. Each control call is a **durable write to the
+`~sub` env plus a monotonic `version++`, committed atomically in one transaction**. The
+write emits a path-local `SYSTEM_POKE`, which the owning connection catches as a latency
+fast path; its heartbeat `version`-check is the correctness backstop, so a dropped POKE
+self-heals within one beat (bounded staleness). Any path-local node can serve a control
+write — the durable record is the single source of truth, so **no cross-worker IPC** is
+needed.
+
+```
+POST /api/<dataEnv>/subscriptions/<id>/interests   { "add": [{ "type": "Order", "key": "o-42" }] }
+PUT  /api/<dataEnv>/subscriptions/<id>/interests   { "interests": [{ "type": "Order", "key": "o-42" }] }
+POST /api/<dataEnv>/subscriptions/<id>/filter      { "filter": { "status": "open" } }
+DELETE /api/<dataEnv>/subscriptions/<id>
+```
+
+Unknown `sessionId` → `404`.
+
+## Reconnect = resync
+
+When a client reconnects with a still-live `?sub=<id>`, the server re-attaches to the same
+durable session and emits one control frame:
+
+```
+event: subscription:resync
+data: { "sessionId": "…", "version": 7 }
+```
+
+On `resync` the client re-runs its queries against current truth and **PUT-replaces** its
+full interest set (`PUT …/interests`). Replace, not append: this drops any stale
+pre-disconnect interests so they can't mis-route (the server also backstop-clears the
+interest set on reconnect to make additive clients safe). There is no persisted cursor
+anywhere — reconnect is always a resync to current state.
+
+A brand-new or TTL-expired `sessionId` is a normal fresh open (no `resync`). Cross-machine
+continuity is intentionally not provided — a client that reconnects to a different machine
+re-registers and resyncs.
+
+## Convergence, not per-transition
+
+The data change-feed is **coalesced current-state** for cross-process writes, so
+intermediate enter/leave transitions can be skipped. v2 guarantees **convergence to current
+state**, not a per-transition event log: the client only ever learns "something changed,
+here is the key," refetches, and reconciles. Design your client to be idempotent under
+coalesced signals.
+
+## Reference client
+
+```js
+// Minimal browser client. Holds a sessionId, refetches on each signal, and
+// PUT-replaces its interest set on (re)connect / resync.
+function subscribe(dataEnv, { type, filter } = {}) {
+    const view = new Map(); // key -> doc (the client owns its matched set)
+    let sessionId = sessionStorage.getItem('subId') || crypto.randomUUID();
+    sessionStorage.setItem('subId', sessionId);
+
+    const qs = new URLSearchParams({ sub: sessionId });
+    if (type) qs.set('type', type);
+    if (filter) qs.set('filter', JSON.stringify(filter));
+    const es = new EventSource(`/api/${dataEnv}/subscriptions?${qs}`);
+
+    // Re-declare the full interest set (PUT-replace, not append — race-safe on reconnect).
+    async function resync() {
+        const docs = await fetch(`/api/${dataEnv}/types/${type}/query`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ filter: filter || {} }),
+        }).then((r) => r.json());
+
+        view.clear();
+        for (const d of docs.items) view.set(d.key, d.value);
+
+        await fetch(`/api/${dataEnv}/subscriptions/${sessionId}/interests`, {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ interests: [...view.keys()].map((key) => ({ type, key })) }),
+        });
+        render(view);
+    }
+
+    es.addEventListener('subscription:open', (e) => {
+        sessionId = JSON.parse(e.data).sessionId; // accept the server's id
+        sessionStorage.setItem('subId', sessionId);
+        resync(); // initial set = a client query
+    });
+
+    // Reconnect → re-run queries + PUT-replace interests.
+    es.addEventListener('subscription:resync', () => resync());
+
+    // Signal → refetch the one key, reconcile the local view.
+    es.addEventListener('signal', async (e) => {
+        const { key } = JSON.parse(e.data);
+        const res = await fetch(`/api/${dataEnv}/types/${type}/${key}`);
+        if (res.status === 404) {
+            view.delete(key); // leave: deregister the interest
+            await control('POST', { remove: [{ type, key }] });
+        } else {
+            const doc = await res.json();
+            if (matches(doc.value, filter)) {
+                if (!view.has(key)) await control('POST', { add: [{ type, key }] }); // enter
+                view.set(key, doc.value);
+            } else if (view.has(key)) {
+                view.delete(key); // edited out → leave
+                await control('POST', { remove: [{ type, key }] });
+            }
+        }
+        render(view);
+    });
+
+    function control(method, body) {
+        return fetch(`/api/${dataEnv}/subscriptions/${sessionId}/interests`, {
+            method,
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+
+    return () => es.close(); // DELETE …/:id also closes server-side; close() lets TTL reap.
+}
+```
+
+Key contract points the client must honour:
+
+- **Register before refetch** on an enter candidate — register the provisional interest
+  first, then refetch; if the doc no longer matches, deregister and don't show it. This
+  closes the race where a change arrives in the refetch window.
+- **Deregister on leave** — when a key leaves the view, remove its interest.
+- **PUT-replace on reconnect/resync** — re-declare the whole set; never additively
+  re-register.
+- **Tolerate coalesced signals** — refetch is idempotent; the view converges to current
+  state.
+
+## Storage (`~sub` env)
+
+Subscription state lives in a dedicated environment named `~sub`, opened `sync:false`:
+
+- **`session`** — `{ sessionId, dataEnv, type, filter?, version, createdAt, expiresAt }`,
+  with per-doc TTL on `expiresAt`.
+- **`interest`** — `{ id, sessionId, type, key }`, with a `ref sessionId → session`,
+  `onDelete: cascade`, and a reverse index on `[type, key]` for O(interested sessions)
+  routing.
+
+The `~sub` _env_ name starts with `~` so its writes stay out of the data change-feed, while
+the non-`~` type names keep FK cascade and TTL working. `sync:false` keeps machine-bound
+session/heartbeat churn off replication; the path-local POKE still fires for control
+re-notify. The `~sub` env has no changelog (it is read by key/index, never tailed).