@openparachute/vault 0.6.5-rc.13 → 0.6.5-rc.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.5-rc.13",
+  "version": "0.6.5-rc.14",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/live-frame-parity.test.ts

@@ -1,21 +1,22 @@
 /**
- * Live-query frame PARITY + the pure WS helpers (WS-hibernation migration
- * Phase 3, self-host door).
+ * Live-query frame PARITY + the pure WS helpers (WS-hibernation migration,
+ * self-host door).
  *
  * The load-bearing CROSS-DOOR conformance check: for the shared frame corpus
- * (mirrored byte-for-byte from the cloud door), the self-host WS payload and the
- * self-host SSE `data:` body carry a byte-IDENTICAL serialization of the inner
- * payload (`notes` / `note` / `id`) — the ONLY difference is the `type`
- * discriminator the WS message folds in (plus the snapshot `done` chunk flag).
- * Because the corpus AND the `sseFrame`/`wsFrame` formatters are byte-shaped
- * identical to cloud's, this transitively proves: self-host WS bytes === corpus
- * === self-host SSE bytes === cloud WS/SSE bytes.
+ * (mirrored byte-for-byte from the cloud door), the self-host WS message folds
+ * the event name into a `type` discriminator (plus the snapshot `done` chunk
+ * flag) over an inner payload (`notes` / `note` / `id`) that serializes
+ * byte-IDENTICALLY to the corpus. Because the corpus AND the `wsFrame` formatter
+ * are byte-shaped identical to cloud's, this transitively proves: self-host WS
+ * bytes === corpus === cloud WS bytes. (SSE was the original transport; it was
+ * removed in Phase 5 — WebSocket is now the sole live transport, polling the
+ * client floor.)
  *
  * Plus unit coverage of the pure helpers that back the Bun.serve integration:
  * snapshot chunking, first-message parsing, verb-rank, and the query rejects.
  */
 import { describe, it, expect } from "bun:test";
-import { sseFrame, wsFrame, SseSink, WsSink, snapshotFrame } from "./subscriptions.ts";
+import { wsFrame, WsSink } from "./subscriptions.ts";
 import {
   buildSnapshotFrames,
   parseClientMessage,
@@ -30,23 +31,11 @@ import {
 import { unsupportedSubscriptionReason } from "./live-match.ts";
 import { FRAME_CORPUS, NOTE_A } from "./test-support/live-frame-corpus.ts";
 
-/** Strip the SSE `data:` body out of a single-event SSE frame. */
-function sseDataBody(frame: string): string {
-  const line = frame.split("\n").find((l) => l.startsWith("data:"))!;
-  return line.slice("data:".length).replace(/^ /, "");
-}
-
-describe("live-frame parity — self-host WS bytes === corpus === SSE data body", () => {
+describe("live-frame parity — self-host WS bytes === corpus === cloud WS bytes", () => {
   for (const c of FRAME_CORPUS) {
-    it(`${c.name}: identical inner payload across transports`, () => {
-      const sse = sseFrame(c.event, c.data);
+    it(`${c.name}: WS message folds the event into \`type\` over the corpus payload`, () => {
       const ws = wsFrame(c.event, c.data);
 
-      // SSE frame shape (byte-identical to the pre-WS-migration contract).
-      expect(sse).toBe(`event: ${c.event}\ndata: ${JSON.stringify(c.data)}\n\n`);
-      // SSE data body parses back to exactly the payload.
-      expect(JSON.parse(sseDataBody(sse))).toEqual(c.data);
-
       // WS message is `{ type, ...data }` — the event name folds into `type`.
       const parsedWs = JSON.parse(ws) as Record<string, unknown>;
       expect(parsedWs.type).toBe(c.event);
@@ -55,21 +44,16 @@ describe("live-frame parity — self-host WS bytes === corpus === SSE data body"
       expect(rest).toEqual(c.data);
 
       // BYTE parity of the inner payload: whatever value the event carries
-      // (`notes` / `note` / `id`) serializes IDENTICALLY in both frames AND
-      // equals the corpus serialization (the cross-door invariant).
+      // (`notes` / `note` / `id`) serializes IDENTICALLY to the corpus
+      // serialization (the cross-door invariant).
       const innerKey = c.event === "snapshot" ? "notes" : c.event === "upsert" ? "note" : "id";
       const innerBytes = JSON.stringify((c.data as Record<string, unknown>)[innerKey]);
-      expect(sse.includes(innerBytes)).toBe(true);
       expect(ws.includes(innerBytes)).toBe(true);
     });
   }
-
-  it("snapshotFrame() is the SSE snapshot frame for a note set", () => {
-    expect(snapshotFrame([NOTE_A as any])).toBe(sseFrame("snapshot", { notes: [NOTE_A] }));
-  });
 });
 
-describe("sink classes render through the ONE formatter each", () => {
+describe("sink classes render through the ONE formatter", () => {
   it("WsSink.send emits exactly wsFrame(event, data)", () => {
     const sent: string[] = [];
     const sink = new WsSink({ send: (d: string) => sent.push(d), close: () => {} });
@@ -78,15 +62,6 @@ describe("sink classes render through the ONE formatter each", () => {
       expect(sent.at(-1)).toBe(wsFrame(c.event, c.data));
     }
   });
-
-  it("SseSink.send emits exactly sseFrame(event, data); comment() emits `:\\n\\n`", () => {
-    const pushed: string[] = [];
-    const sink = new SseSink((f) => (pushed.push(f), true), () => {});
-    sink.send("upsert", { note: NOTE_A });
-    expect(pushed.at(-1)).toBe(sseFrame("upsert", { note: NOTE_A }));
-    sink.comment();
-    expect(pushed.at(-1)).toBe(":\n\n");
-  });
 });
 
 describe("buildSnapshotFrames — chunking + done flag", () => {

package/src/routing.ts

@@ -73,7 +73,6 @@ import {
   type TagScopeCtx,
   type WriteCtx,
 } from "./routes.ts";
-import { handleSubscribe } from "./subscribe.ts";
 import { handleTriggers } from "./triggers-api.ts";
 import { expandTokenTagScope } from "./tag-scope.ts";
 import {
@@ -883,10 +882,23 @@ export async function route(
   };
 
   if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6), vaultName, tagScope, writeCtx);
-  // Live-query SSE subscription (design 2026-06-08). Snapshot + scoped live
-  // upsert/remove events over text/event-stream. Auth + tag-scope already
-  // resolved above and threaded through, mirroring the /notes branch.
-  if (apiPath === "/subscribe") return handleSubscribe(req, store, vaultName, tagScope);
+  // Live-query SSE transport REMOVED (WS-hibernation migration Phase 5). The
+  // WebSocket binding (an `Upgrade: websocket` GET /subscribe, handled in
+  // server.ts before this pipeline) is now the SOLE live transport; polling
+  // GET /notes is the client floor beneath it. A non-WS GET /subscribe — a
+  // straggler on a cached pre-WS notes-ui bundle — gets a clean 410 Gone
+  // pointing at the WS binding so its consumer degrades to polling gracefully;
+  // NEVER a 500 or an unhandled path.
+  if (apiPath === "/subscribe") {
+    return Response.json(
+      {
+        error:
+          "The live-query SSE transport has been removed. Reconnect with an `Upgrade: websocket` request to GET /api/subscribe, or poll GET /notes.",
+        code: "SSE_TRANSPORT_REMOVED",
+      },
+      { status: 410 },
+    );
+  }
   if (apiPath.startsWith("/tags")) return handleTags(req, store, apiPath.slice(5), tagScope);
   if (apiPath === "/find-path") return handleFindPath(req, store, tagScope);
   if (apiPath === "/vault") {

package/src/server.ts

@@ -527,8 +527,9 @@ const server = Bun.serve({
     }
 
     // Live-query WebSocket upgrade — detected BEFORE the fetch pipeline because
-    // WS upgrades don't traverse `route()`. Non-upgrade requests (incl. the SSE
-    // fallback, which has no Upgrade header) fall straight through unchanged.
+    // WS upgrades don't traverse `route()`. Non-upgrade requests (incl. a
+    // straggler non-WS GET /subscribe, which now gets a 410 Gone in routing.ts —
+    // the SSE transport was removed in Phase 5) fall straight through unchanged.
     if (isWebSocketUpgrade(req)) {
       const verdict = subscribeWs.tryUpgrade(req, server, path);
       if (verdict.kind === "upgraded") return undefined; // Bun owns the socket now

package/src/subscriptions.ts

@@ -1,6 +1,8 @@
 /**
- * Live-query subscription registry (live-query SSE — design
- * `design/2026-06-08-live-query-sse.md`).
+ * Live-query subscription registry — fans out post-commit note events to live
+ * WebSocket subscriptions (originally an SSE fan-out — design
+ * `design/2026-06-08-live-query-sse.md`; the SSE transport was removed in
+ * Phase 5 of the WS-hibernation migration).
  *
  * A second consumer of the post-commit hook dispatcher (`core/src/hooks.ts`),
  * alongside the durable webhook-trigger sink. Where a trigger survives across
@@ -8,24 +10,23 @@
  * connection-scoped, driving a live UI. Same event source, same predicate,
  * different durability.
  *
- * ## Two transports, one contract (WS-hibernation migration, 2026-07-04)
+ * ## The live transport: WebSocket (WS-hibernation migration)
  *
  * The manager is transport-agnostic: it emits abstract `(event, data)` tuples
  * and a {@link SubscriptionSink} renders them for its wire.
- *   - {@link SseSink} renders `event:`/`data:` frames — bytes UNCHANGED from the
- *     original SSE contract (surface-client parses them identically).
- *   - {@link WsSink} renders a WebSocket message `{ type: event, ...data }` — the
- *     SSE `event:` name folds into a `type` discriminator; the inner payload
- *     (`note` / `id` / `notes`) serializes byte-for-byte identically to the SSE
- *     `data:` body. That parity is pinned by the shared frame-corpus fixture and
- *     is congruent with the cloud door (`parachute-cloud/workers/vault/src/
- *     live/subscriptions.ts`). See `parachute-cloud/workers/vault/docs/
- *     live-query-ws.md`.
+ *   - {@link WsSink} renders a WebSocket message `{ type: event, ...data }`. The
+ *     inner payload (`note` / `id` / `notes`) is pinned byte-for-byte against the
+ *     shared frame-corpus fixture and is congruent with the cloud door
+ *     (`parachute-cloud/workers/vault/src/live/subscriptions.ts`). See
+ *     `parachute-cloud/workers/vault/docs/live-query-ws.md`.
  *
- * Both transports share ONE process-wide {@link SubscriptionManager}. Self-host
- * has no hibernation (a self-run Bun box has no per-connection duration bill) —
- * the WS binding adds bidirectionality + contract-congruence with cloud, nothing
- * more. The Bun.serve WS integration lives in `ws-server.ts` + `ws-subscribe.ts`.
+ * WebSocket is the SOLE live transport as of Phase 5 — the earlier SSE binding
+ * was removed once cached notes-ui bundles converged, and polling (client-side)
+ * is the floor beneath live. All subscriptions share ONE process-wide
+ * {@link SubscriptionManager}. Self-host has no hibernation (a self-run Bun box
+ * has no per-connection duration bill) — the WS binding gives bidirectionality +
+ * contract-congruence with cloud, nothing more. The Bun.serve WS integration
+ * lives in `ws-server.ts` + `ws-subscribe.ts`.
  *
  * ## How fan-out works
  *
@@ -108,40 +109,14 @@ interface Subscription {
   closed: boolean;
 }
 
-/** SSE wire frame: `event: <name>\ndata: <json>\n\n`. The ONE place SSE bytes
- *  are formatted (route + tests + SseSink all route through it). */
-export function sseFrame(event: string, data: unknown): string {
-  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
-}
-
-/** WebSocket message: `{ type: <event>, ...data }`. The SSE `event:` name folds
- *  into `type`; the inner payload serializes identically to the SSE `data:`
- *  body. The ONE place WS bytes are formatted. */
+/** WebSocket message: `{ type: <event>, ...data }` — the event name becomes the
+ *  `type` discriminator and the inner payload (`note` / `id` / `notes`)
+ *  serializes as-is. The ONE place WS bytes are formatted. */
 export function wsFrame(event: string, data: unknown): string {
   const body = data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, unknown>) : {};
   return JSON.stringify({ type: event, ...body });
 }
 
-/** SSE sink: renders `(event, data)` to an SSE frame and hands it to `push`
- *  (the route's stream-queue writer). `push` returns false when the stream is
- *  gone. `comment()` emits a raw `:` keepalive (SSE-only; not part of the
- *  abstract contract). Bytes are byte-identical to the pre-migration SSE path. */
-export class SseSink implements SubscriptionSink {
-  constructor(
-    private readonly push: (frame: string) => boolean,
-    private readonly onClose: () => void,
-  ) {}
-  send(event: string, data: unknown): boolean {
-    return this.push(sseFrame(event, data));
-  }
-  comment(text = ""): boolean {
-    return this.push(`:${text}\n\n`);
-  }
-  close(): void {
-    this.onClose();
-  }
-}
-
 /** Minimal structural shape of a Bun `ServerWebSocket` (or a test double) that
  *  {@link WsSink} needs — keeps this module free of a hard Bun-server import. */
 export interface WsLike {
@@ -374,10 +349,5 @@ export interface SubscriptionHandle {
   close: () => void;
 }
 
-/** Serialize a snapshot SSE frame (exported for the SSE route + tests). */
-export function snapshotFrame(notes: Note[]): string {
-  return sseFrame("snapshot", { notes });
-}
-
 /** Process-wide manager — shared like `defaultHookRegistry`. */
 export const subscriptionManager = new SubscriptionManager();

package/src/ws-server.ts

@@ -14,7 +14,7 @@
  *   - `ws-subscribe.ts` — the PURE half (close codes, query validation, chunked
  *     snapshot, message parsing, verb-rank) shared byte-shaped with cloud.
  *   - `subscriptions.ts` — the transport-agnostic manager + `WsSink`
- *     (`{ type, ...data }`) / `SseSink` (`event:`/`data:`).
+ *     (`{ type, ...data }`), the sole live-transport sink since Phase 5.
  *   - this module — the Bun.serve upgrade decision + `open`/`message`/`close`
  *     handlers + the per-vault live-socket registry (the WS cap).
  *

package/src/subscribe.test.ts

@@ -1,609 +0,0 @@
-/**
- * Live-query SSE subscription tests (design 2026-06-08).
- *
- * Exercises the route handler end-to-end over a real `text/event-stream`
- * Response: snapshot correctness, live insert/update/delete events,
- * set-transition (matching→non-matching → remove; non-matching→matching →
- * upsert), the load-bearing SCOPE-INTERSECTION guarantee (a tag-scoped token
- * never receives out-of-scope notes in the snapshot OR live), `search`/`near`
- * → 400, and over-cap → 503.
- *
- * Hook dispatch is deferred (microtask + queued handler), so each mutation is
- * followed by `settle()` before asserting the stream contents.
- */
-
-import { describe, it, expect, beforeEach, afterEach } from "bun:test";
-import { Database } from "bun:sqlite";
-import { SqliteStore } from "../core/src/store.ts";
-import { HookRegistry } from "../core/src/hooks.ts";
-import { handleSubscribe } from "./subscribe.ts";
-import { SubscriptionManager } from "./subscriptions.ts";
-import { expandTokenTagScope } from "./tag-scope.ts";
-import type { TagScopeCtx } from "./routes.ts";
-
-const VAULT = "testvault";
-
-let db: Database;
-let hooks: HookRegistry;
-let store: SqliteStore;
-let manager: SubscriptionManager;
-
-beforeEach(() => {
-  db = new Database(":memory:");
-  hooks = new HookRegistry({ concurrency: 4, logger: { error() {} } });
-  store = new SqliteStore(db, { hooks });
-  // Manager registers its broad hooks on THIS store's registry, and resolves
-  // every event to VAULT (the test store isn't in the global vault WeakMap).
-  manager = new SubscriptionManager(hooks, { resolveVault: () => VAULT });
-});
-
-afterEach(() => {
-  manager.shutdown();
-  db.close();
-});
-
-/** Let deferred hook dispatch + handlers run. */
-async function settle(): Promise<void> {
-  // queueMicrotask → handler runs under the semaphore (async). A couple of
-  // macrotask ticks is plenty for the in-memory path.
-  await new Promise((r) => setTimeout(r, 10));
-}
-
-/** An SSE frame parsed off the wire. */
-interface Frame {
-  event: string;
-  data: any;
-}
-
-/**
- * Open an SSE reader over a subscribe Response. `frames()` returns everything
- * parsed so far; `close()` cancels the stream (→ subscription teardown).
- */
-function sseReader(res: Response) {
-  const reader = res.body!.getReader();
-  const decoder = new TextDecoder();
-  let buf = "";
-  const frames: Frame[] = [];
-  let done = false;
-
-  function drainBuffer() {
-    let idx: number;
-    while ((idx = buf.indexOf("\n\n")) !== -1) {
-      const raw = buf.slice(0, idx);
-      buf = buf.slice(idx + 2);
-      if (raw.startsWith(":")) continue; // keepalive comment
-      const lines = raw.split("\n");
-      let event = "message";
-      let dataStr = "";
-      for (const line of lines) {
-        if (line.startsWith("event:")) event = line.slice(6).trim();
-        else if (line.startsWith("data:")) dataStr += line.slice(5).trim();
-      }
-      frames.push({ event, data: dataStr ? JSON.parse(dataStr) : null });
-    }
-  }
-
-  // ONE continuous background read loop — a single outstanding `reader.read()`
-  // at a time (concurrent reads on one reader throw / steal chunks). It drains
-  // frames into `frames` as bytes arrive; `pump()` just waits a beat.
-  (async () => {
-    try {
-      while (true) {
-        const { value, done: d } = await reader.read();
-        if (d) {
-          done = true;
-          break;
-        }
-        if (value) {
-          buf += decoder.decode(value, { stream: true });
-          drainBuffer();
-        }
-      }
-    } catch {
-      done = true;
-    }
-  })();
-
-  return {
-    /** Wait a beat for in-flight frames to land. */
-    async pump() {
-      await new Promise((r) => setTimeout(r, 30));
-      return frames;
-    },
-    frames: () => frames,
-    isDone: () => done,
-    async close() {
-      await reader.cancel().catch(() => {});
-    },
-  };
-}
-
-function unscopedScope(): TagScopeCtx {
-  return { allowed: null, raw: null };
-}
-
-async function scopedTo(roots: string[]): Promise<TagScopeCtx> {
-  return { allowed: await expandTokenTagScope(store, roots), raw: roots };
-}
-
-function subscribeReq(query: string): Request {
-  return new Request(`http://localhost/vault/${VAULT}/api/subscribe?${query}`);
-}
-
-describe("handleSubscribe — snapshot", () => {
-  it("sends a snapshot of currently-matching notes", async () => {
-    await store.createNote("hello", { tags: ["chat"], metadata: {} });
-    await store.createNote("nope", { tags: ["other"] });
-
-    const res = await handleSubscribe(subscribeReq("tag=chat"), store, VAULT, unscopedScope(), manager);
-    expect(res.status).toBe(200);
-    expect(res.headers.get("Content-Type")).toBe("text/event-stream");
-
-    const r = sseReader(res);
-    await r.pump();
-    const snap = r.frames().find((f) => f.event === "snapshot");
-    expect(snap).toBeTruthy();
-    expect(snap!.data.notes.length).toBe(1);
-    expect(snap!.data.notes[0].content).toBe("hello");
-    await r.close();
-  });
-});
-
-describe("handleSubscribe — live events", () => {
-  it("emits upsert on a matching insert after connect", async () => {
-    const res = await handleSubscribe(subscribeReq("tag=chat"), store, VAULT, unscopedScope(), manager);
-    const r = sseReader(res);
-    await r.pump();
-    expect(r.frames().filter((f) => f.event === "snapshot").length).toBe(1);
-
-    await store.createNote("live one", { tags: ["chat"] });
-    await settle();
-    await r.pump();
-
-    const upserts = r.frames().filter((f) => f.event === "upsert");
-    expect(upserts.length).toBe(1);
-    expect(upserts[0]!.data.note.content).toBe("live one");
-    await r.close();
-  });
-
-  it("does NOT emit on a non-matching insert", async () => {
-    const res = await handleSubscribe(subscribeReq("tag=chat"), store, VAULT, unscopedScope(), manager);
-    const r = sseReader(res);
-    await r.pump();
-
-    await store.createNote("irrelevant", { tags: ["other"] });
-    await settle();
-    await r.pump();
-
-    expect(r.frames().filter((f) => f.event === "upsert").length).toBe(0);
-    await r.close();
-  });
-
-  it("emits remove on hard delete", async () => {
-    const note = await store.createNote("doomed", { tags: ["chat"] });
-    const res = await handleSubscribe(subscribeReq("tag=chat"), store, VAULT, unscopedScope(), manager);
-    const r = sseReader(res);
-    await r.pump();
-
-    await store.deleteNote(note.id);
-    await settle();
-    await r.pump();
-
-    const removes = r.frames().filter((f) => f.event === "remove");
-    expect(removes.length).toBe(1);
-    expect(removes[0]!.data.id).toBe(note.id);
-    await r.close();
-  });
-});
-
-describe("handleSubscribe — set transitions", () => {
-  it("matching → non-matching update emits remove", async () => {
-    // channel field indexed so the snapshot operator query works.
-    const { generateMcpTools } = await import("../core/src/mcp.ts");
-    const updateTag = generateMcpTools(store).find((t) => t.name === "update-tag")!;
-    await updateTag.execute({ tag: "msg", fields: { channel: { type: "string", indexed: true } } });
-
-    const note = await store.createNote("m", { tags: ["msg"], metadata: { channel: "general" } });
-    const res = await handleSubscribe(
-      subscribeReq("tag=msg&meta[channel][eq]=general"),
-      store,
-      VAULT,
-      unscopedScope(),
-      manager,
-    );
-    const r = sseReader(res);
-    await r.pump();
-    expect(r.frames().find((f) => f.event === "snapshot")!.data.notes.length).toBe(1);
-
-    // Move the note out of the set (channel → random).
-    await store.updateNote(note.id, { metadata: { channel: "random" } });
-    await settle();
-    await r.pump();
-
-    const removes = r.frames().filter((f) => f.event === "remove");
-    expect(removes.length).toBe(1);
-    expect(removes[0]!.data.id).toBe(note.id);
-    await r.close();
-  });
-
-  it("non-matching → matching update emits upsert", async () => {
-    const note = await store.createNote("m", { tags: ["other"] });
-    const res = await handleSubscribe(subscribeReq("tag=chat"), store, VAULT, unscopedScope(), manager);
-    const r = sseReader(res);
-    await r.pump();
-    expect(r.frames().find((f) => f.event === "snapshot")!.data.notes.length).toBe(0);
-
-    // Re-tag into the set. updateNote doesn't take tags directly; use tagNote
-    // then a metadata touch to fire an "updated" event carrying fresh tags.
-    await store.tagNote(note.id, ["chat"]);
-    await store.updateNote(note.id, { metadata: { touched: true } });
-    await settle();
-    await r.pump();
-
-    const upserts = r.frames().filter((f) => f.event === "upsert");
-    expect(upserts.length).toBeGreaterThanOrEqual(1);
-    expect(upserts.at(-1)!.data.note.tags).toContain("chat");
-    await r.close();
-  });
-});
-
-describe("handleSubscribe — SCOPE INTERSECTION (security)", () => {
-  it("snapshot withholds a note that MATCHES the predicate but is OUT OF SCOPE (predicate∧scope) (N3)", async () => {
-    // Both notes carry #work and so MATCH the `tag=work` predicate. Scope must
-    // still withhold the one outside the token's allowlist. The token is scoped
-    // to #work/eng, so #work/sales is in-predicate-but-out-of-scope.
-    await store.upsertTagRecord("work", { description: "work root" });
-    await store.upsertTagRecord("work/eng", { parent_names: ["work"] });
-    await store.upsertTagRecord("work/sales", { parent_names: ["work"] });
-    await store.createNote("eng note", { tags: ["work/eng"] });
-    await store.createNote("sales note", { tags: ["work/sales"] });
-
-    const scope = await scopedTo(["work/eng"]);
-    // Predicate `tag=work` matches BOTH (sales is a #work descendant) — only
-    // scope distinguishes them, exercising the AND-gate, not the predicate.
-    const res = await handleSubscribe(subscribeReq("tag=work"), store, VAULT, scope, manager);
-    const r = sseReader(res);
-    await r.pump();
-    const snap = r.frames().find((f) => f.event === "snapshot")!;
-    const contents = snap.data.notes.map((n: any) => n.content);
-    expect(contents).toContain("eng note");
-    expect(contents).not.toContain("sales note");
-    await r.close();
-  });
-
-  it("a live INSERT matching the predicate but OUT OF SCOPE never reaches a scoped stream (N3)", async () => {
-    await store.upsertTagRecord("work", { description: "work root" });
-    await store.upsertTagRecord("work/eng", { parent_names: ["work"] });
-    await store.upsertTagRecord("work/sales", { parent_names: ["work"] });
-    const scope = await scopedTo(["work/eng"]);
-    const res = await handleSubscribe(subscribeReq("tag=work"), store, VAULT, scope, manager);
-    const r = sseReader(res);
-    await r.pump();
-
-    // Out-of-scope but predicate-matching (#work/sales is a #work descendant).
-    await store.createNote("sales leak", { tags: ["work/sales"] });
-    await settle();
-    await r.pump();
-    expect(r.frames().filter((f) => f.event === "upsert").length).toBe(0);
-
-    // Sanity: an in-scope, predicate-matching insert DOES arrive.
-    await store.createNote("eng allowed", { tags: ["work/eng"] });
-    await settle();
-    await r.pump();
-    const upserts = r.frames().filter((f) => f.event === "upsert");
-    expect(upserts.length).toBe(1);
-    expect(upserts[0]!.data.note.content).toBe("eng allowed");
-    await r.close();
-  });
-
-  it("a live UPDATE of an out-of-scope predicate-matching note still never leaks (upsert OR remove) (M2)", async () => {
-    await store.upsertTagRecord("work", { description: "work root" });
-    await store.upsertTagRecord("work/sales", { parent_names: ["work"] });
-    const scope = await scopedTo(["work/eng"]);
-    // #work/sales matches `tag=work` but is OUT of the #work/eng scope.
-    const note = await store.createNote("sales secret", { tags: ["work/sales"] });
-    const res = await handleSubscribe(subscribeReq("tag=work"), store, VAULT, scope, manager);
-    const r = sseReader(res);
-    await r.pump();
-
-    await store.updateNote(note.id, { metadata: { touched: true } });
-    await settle();
-    await r.pump();
-    // No upsert (scope vetoes) AND no remove (would leak the uuid — M2).
-    expect(r.frames().filter((f) => f.event === "upsert").length).toBe(0);
-    expect(r.frames().filter((f) => f.event === "remove").length).toBe(0);
-    await r.close();
-  });
-
-  it("M2 — scoped sub gets NO remove when an OUT-OF-SCOPE note leaves the set", async () => {
-    // channel indexed so the snapshot operator query works.
-    const { generateMcpTools } = await import("../core/src/mcp.ts");
-    const updateTag = generateMcpTools(store).find((t) => t.name === "update-tag")!;
-    await updateTag.execute({ tag: "msg", fields: { channel: { type: "string", indexed: true } } });
-    await store.upsertTagRecord("work", { description: "work root" });
-    await store.upsertTagRecord("work/sales", { parent_names: ["work"] });
-
-    const scope = await scopedTo(["work/eng"]);
-    // A #work/sales note (out of scope) that currently matches the predicate
-    // tag=work ∧ channel=general.
-    const note = await store.createNote("sales", {
-      tags: ["msg", "work/sales"],
-      metadata: { channel: "general" },
-    });
-    const res = await handleSubscribe(
-      subscribeReq("tag=work&meta[channel][eq]=general"),
-      store,
-      VAULT,
-      scope,
-      manager,
-    );
-    const r = sseReader(res);
-    await r.pump();
-    // Out of scope → not in the snapshot either.
-    expect(r.frames().find((f) => f.event === "snapshot")!.data.notes.length).toBe(0);
-
-    // Move it out of the predicate set (channel → random). It was never in the
-    // scoped sub's set; emitting a remove would leak its uuid → must stay silent.
-    await store.updateNote(note.id, { metadata: { channel: "random" } });
-    await settle();
-    await r.pump();
-    expect(r.frames().filter((f) => f.event === "remove").length).toBe(0);
-    await r.close();
-  });
-
-  it("M2 — scoped sub DOES get a remove when an IN-SCOPE note it could see leaves the set", async () => {
-    const { generateMcpTools } = await import("../core/src/mcp.ts");
-    const updateTag = generateMcpTools(store).find((t) => t.name === "update-tag")!;
-    await updateTag.execute({ tag: "msg", fields: { channel: { type: "string", indexed: true } } });
-    await store.upsertTagRecord("work", { description: "work root" });
-    await store.upsertTagRecord("work/eng", { parent_names: ["work"] });
-
-    const scope = await scopedTo(["work/eng"]);
-    // In-scope note matching the predicate.
-    const note = await store.createNote("eng", {
-      tags: ["msg", "work/eng"],
-      metadata: { channel: "general" },
-    });
-    const res = await handleSubscribe(
-      subscribeReq("tag=work&meta[channel][eq]=general"),
-      store,
-      VAULT,
-      scope,
-      manager,
-    );
-    const r = sseReader(res);
-    await r.pump();
-    expect(r.frames().find((f) => f.event === "snapshot")!.data.notes.length).toBe(1);
-
-    // Leave the set (channel → random) while staying IN scope → a remove the
-    // sub legitimately needs (it held this id).
-    await store.updateNote(note.id, { metadata: { channel: "random" } });
-    await settle();
-    await r.pump();
-    const removes = r.frames().filter((f) => f.event === "remove");
-    expect(removes.length).toBe(1);
-    expect(removes[0]!.data.id).toBe(note.id);
-    await r.close();
-  });
-});
-
-describe("handleSubscribe — rejected query shapes", () => {
-  it("search → 400", async () => {
-    const res = await handleSubscribe(subscribeReq("search=hello"), store, VAULT, unscopedScope(), manager);
-    expect(res.status).toBe(400);
-    const body = await res.json();
-    expect(body.code).toBe("UNSUPPORTED_SUBSCRIPTION_QUERY");
-  });
-
-  it("near → 400", async () => {
-    const res = await handleSubscribe(
-      subscribeReq("near%5Bnote_id%5D=abc"),
-      store,
-      VAULT,
-      unscopedScope(),
-      manager,
-    );
-    expect(res.status).toBe(400);
-    const body = await res.json();
-    expect(body.code).toBe("UNSUPPORTED_SUBSCRIPTION_QUERY");
-  });
-
-  it("has_links → 400 (M1 — needs the links table)", async () => {
-    const res = await handleSubscribe(subscribeReq("has_links=true"), store, VAULT, unscopedScope(), manager);
-    expect(res.status).toBe(400);
-    const body = await res.json();
-    expect(body.code).toBe("UNSUPPORTED_SUBSCRIPTION_QUERY");
-    expect(body.error).toContain("has_links");
-  });
-
-  it("date filter → 400 (M1) — bracket date_filter on created_at", async () => {
-    // The flat `date_from` param was removed in 0.6.4 (vault#288) and is now
-    // ignored, so it no longer reaches the M1 date guard. Bracket-style is the
-    // only query-string date filter; assert it's still rejected for live subs.
-    const res = await handleSubscribe(
-      subscribeReq("meta%5Bcreated_at%5D%5Bgte%5D=2026-01-01"),
-      store,
-      VAULT,
-      unscopedScope(),
-      manager,
-    );
-    expect(res.status).toBe(400);
-    const body = await res.json();
-    expect(body.code).toBe("UNSUPPORTED_SUBSCRIPTION_QUERY");
-    expect(body.error).toContain("date");
-  });
-
-  it("flat date_from is ignored → subscription created (vault#288 removal)", async () => {
-    // Documents the breaking change: the removed flat param no longer reaches
-    // the date guard, so a sub that ONLY carries it is now a valid (unfiltered)
-    // subscription rather than a 400.
-    const res = await handleSubscribe(
-      subscribeReq("date_from=2026-01-01"),
-      store,
-      VAULT,
-      unscopedScope(),
-      manager,
-    );
-    expect(res.status).toBe(200);
-    expect(res.headers.get("Content-Type")).toBe("text/event-stream");
-    const r = sseReader(res);
-    await r.pump();
-    await r.close();
-  });
-
-  it("date filter → 400 (M1) — bracket date_filter on updated_at", async () => {
-    const res = await handleSubscribe(
-      subscribeReq("meta%5Bupdated_at%5D%5Bgte%5D=2026-01-01"),
-      store,
-      VAULT,
-      unscopedScope(),
-      manager,
-    );
-    expect(res.status).toBe(400);
-    const body = await res.json();
-    expect(body.code).toBe("UNSUPPORTED_SUBSCRIPTION_QUERY");
-    expect(body.error).toContain("date");
-  });
-});
-
-describe("handleSubscribe — snapshot completeness (M3)", () => {
-  it("a subscription matching >50 notes gets ALL of them in the snapshot", async () => {
-    // The default query limit is 50; seed 60 matching notes and assert the
-    // snapshot carries the full set (paging stripped for the snapshot query).
-    for (let i = 0; i < 60; i++) {
-      await store.createNote(`n${i}`, { tags: ["chat"] });
-    }
-    const res = await handleSubscribe(subscribeReq("tag=chat"), store, VAULT, unscopedScope(), manager);
-    const r = sseReader(res);
-    await r.pump();
-    const snap = r.frames().find((f) => f.event === "snapshot")!;
-    expect(snap.data.notes.length).toBe(60);
-    await r.close();
-  });
-});
-
-describe("handleSubscribe — expand axis snapshot↔live consistency", () => {
-  // vault tag `expand` axis (design 2026-06-09): a subscription's snapshot
-  // (query engine) and its live matcher MUST lower the IDENTICAL tag
-  // expansion. We seed the two-axis corpus, then for each `expand` mode assert
-  // the snapshot set EQUALS the set the live matcher would accept over every
-  // note in the vault.
-  async function seedTwoAxis() {
-    await store.upsertTagRecord("entity", { description: "entity root" });
-    await store.upsertTagRecord("person", { parent_names: ["entity"] }); // subtype, not name-prefixed
-    await store.upsertTagRecord("entity/archived", {}); // name-prefixed, not subtype
-    await store.upsertTagRecord("entity/person", { parent_names: ["entity"] }); // both
-    await store.createNote("literal", { tags: ["entity"] });
-    await store.createNote("subtype", { tags: ["person"] });
-    await store.createNote("filed", { tags: ["entity/archived"] });
-    await store.createNote("both", { tags: ["entity/person"] });
-    await store.createNote("unrelated", { tags: ["work"] });
-  }
-
-  for (const mode of ["subtypes", "namespace", "both", "exact"] as const) {
-    it(`expand=${mode}: snapshot set ≡ live-matcher acceptance`, async () => {
-      await seedTwoAxis();
-      const { buildLiveMatcher } = await import("./live-match.ts");
-
-      const res = await handleSubscribe(
-        subscribeReq(`tag=entity&expand=${mode}`),
-        store,
-        VAULT,
-        unscopedScope(),
-        manager,
-      );
-      expect(res.status).toBe(200);
-      const r = sseReader(res);
-      await r.pump();
-      const snap = r.frames().find((f) => f.event === "snapshot")!;
-      const snapIds = new Set<string>(snap.data.notes.map((n: any) => n.id));
-
-      // The matcher accepts/rejects each note in the vault — compute its set.
-      const matcher = await buildLiveMatcher(store, { tags: ["entity"], expand: mode });
-      const allNotes = await store.queryNotes({ limit: Number.MAX_SAFE_INTEGER });
-      const liveIds = new Set<string>(allNotes.filter((n) => matcher.match(n)).map((n) => n.id));
-
-      expect(liveIds).toEqual(snapIds);
-      await r.close();
-    });
-  }
-
-  it("expand=namespace: a live insert filed under entity/ arrives; a subtype-only insert does NOT", async () => {
-    await seedTwoAxis();
-    // The matcher freezes its tag expansion at subscribe time (mirroring the
-    // snapshot query — design "resolved ONCE at subscribe time"). So the tags
-    // these live notes carry must already be KNOWN at subscribe time:
-    //   - entity/inbox: name-prefixed → in the frozen namespace set.
-    //   - agent: declared subtype of entity, NOT name-prefixed → excluded by
-    //     namespace mode.
-    await store.upsertTagRecord("entity/inbox", {});
-    await store.upsertTagRecord("agent", { parent_names: ["entity"] });
-
-    const res = await handleSubscribe(
-      subscribeReq("tag=entity&expand=namespace"),
-      store,
-      VAULT,
-      unscopedScope(),
-      manager,
-    );
-    const r = sseReader(res);
-    await r.pump();
-
-    await store.createNote("new filed", { tags: ["entity/inbox"] }); // name-prefixed → upsert
-    await store.createNote("new subtype", { tags: ["agent"] }); // subtype-only → no upsert
-    await settle();
-    await r.pump();
-
-    const upserts = r.frames().filter((f) => f.event === "upsert");
-    const contents = upserts.map((u) => u.data.note.content);
-    expect(contents).toContain("new filed");
-    expect(contents).not.toContain("new subtype");
-    await r.close();
-  });
-
-  it("invalid expand value → 400 INVALID_QUERY before any stream opens", async () => {
-    const res = await handleSubscribe(
-      subscribeReq("tag=entity&expand=bogus"),
-      store,
-      VAULT,
-      unscopedScope(),
-      manager,
-    );
-    expect(res.status).toBe(400);
-    const body = await res.json();
-    expect(body.code).toBe("INVALID_QUERY");
-  });
-});
-
-describe("handleSubscribe — cap", () => {
-  it("over-cap subscribe → 503", async () => {
-    const capped = new SubscriptionManager(hooks, { maxPerVault: 1, resolveVault: () => VAULT });
-    const r1 = await handleSubscribe(subscribeReq("tag=chat"), store, VAULT, unscopedScope(), capped);
-    expect(r1.status).toBe(200);
-    const reader1 = sseReader(r1);
-    await reader1.pump();
-    expect(capped.countForVault(VAULT)).toBe(1);
-
-    const r2 = await handleSubscribe(subscribeReq("tag=chat"), store, VAULT, unscopedScope(), capped);
-    expect(r2.status).toBe(503);
-    const body = await r2.json();
-    expect(body.code).toBe("SUBSCRIPTION_CAP_REACHED");
-
-    await reader1.close();
-    capped.shutdown();
-  });
-
-  it("closing a stream frees a cap slot", async () => {
-    const capped = new SubscriptionManager(hooks, { maxPerVault: 1, resolveVault: () => VAULT });
-    const r1 = await handleSubscribe(subscribeReq("tag=chat"), store, VAULT, unscopedScope(), capped);
-    const reader1 = sseReader(r1);
-    await reader1.pump();
-    expect(capped.countForVault(VAULT)).toBe(1);
-
-    await reader1.close();
-    // Cancel propagates to the manager teardown.
-    await settle();
-    expect(capped.countForVault(VAULT)).toBe(0);
-    capped.shutdown();
-  });
-});

package/src/subscribe.ts

@@ -1,249 +0,0 @@
-/**
- * Live-query SSE subscribe route (live-query SSE — design
- * `design/2026-06-08-live-query-sse.md`).
- *
- *   GET /vault/<name>/api/subscribe?<query params>
- *
- * Sends an `event: snapshot` of the currently-matching (scoped) notes, then
- * live `upsert`/`remove` events as notes change. Auth + tag-scope are already
- * resolved by the caller (routing.ts) and threaded in — the same `?key=` /
- * header credential and the same `tagScope` the notes path uses. This route
- * adds NO new auth plumbing.
- *
- * The query string is parsed by the SAME `parseNotesQueryOpts` the structured
- * notes-query branch uses, so the snapshot predicate and the live matcher
- * evaluate an identical `QueryOpts`. `search` (FTS) and `near` (graph BFS) are
- * not evaluable against a single in-memory note, so a subscribe request using
- * them is rejected with 400 BEFORE any stream opens.
- */
-
-import type { Store, QueryOpts } from "../core/src/types.ts";
-import { parseNotesQueryOpts, type TagScopeCtx } from "./routes.ts";
-import { filterNotesByTagScope } from "./tag-scope.ts";
-import { buildLiveMatcher, unsupportedSubscriptionReason } from "./live-match.ts";
-import {
-  snapshotFrame,
-  subscriptionManager,
-  SseSink,
-  type SubscriptionManager,
-} from "./subscriptions.ts";
-
-/** Keepalive interval — `:` comment every ~25s to defeat idle-proxy timeouts. */
-const KEEPALIVE_MS = 25_000;
-
-function json(data: unknown, status = 200): Response {
-  return Response.json(data, { status });
-}
-
-/**
- * Handle `GET /api/subscribe`. `vaultName` + `tagScope` come from routing.ts
- * (auth already validated; tag-scope already expanded). `manager` is injectable
- * for tests; defaults to the process-wide singleton.
- */
-export async function handleSubscribe(
-  req: Request,
-  store: Store,
-  vaultName: string,
-  tagScope: TagScopeCtx,
-  manager: SubscriptionManager = subscriptionManager,
-): Promise<Response> {
-  if (req.method !== "GET") {
-    return json({ error: "Method not allowed", message: "subscribe is GET-only" }, 405);
-  }
-
-  const url = new URL(req.url);
-
-  // Reject the un-live-evaluable query shapes up front (before any stream).
-  if (url.searchParams.get("search")) {
-    return json(
-      {
-        error: "search (full-text) is not supported for live subscriptions — FTS can't be evaluated against a single changed note. Drop `search` or poll GET /notes?search=.",
-        code: "UNSUPPORTED_SUBSCRIPTION_QUERY",
-      },
-      400,
-    );
-  }
-  if (url.searchParams.get("near[note_id]")) {
-    return json(
-      {
-        error: "near (graph neighborhood) is not supported for live subscriptions — BFS can't be evaluated against a single changed note. Drop `near` or poll GET /notes?near[note_id]=.",
-        code: "UNSUPPORTED_SUBSCRIPTION_QUERY",
-      },
-      400,
-    );
-  }
-
-  const parsed = parseNotesQueryOpts(url);
-  if (parsed.error) return parsed.error;
-  const queryOpts = parsed.queryOpts!;
-
-  // Belt-and-suspenders: reject cursor (paging) too — meaningless for a live set.
-  const unsupported = unsupportedSubscriptionReason(queryOpts);
-  if (unsupported) {
-    return json({ error: unsupported, code: "UNSUPPORTED_SUBSCRIPTION_QUERY" }, 400);
-  }
-
-  // Build the in-process matcher (resolves tag descendants once, same
-  // hierarchy the snapshot query uses) — may throw QueryError on a malformed
-  // metadata filter shape; surface as 400, same as the notes path.
-  let matcher;
-  try {
-    matcher = await buildLiveMatcher(store, queryOpts);
-  } catch (e: any) {
-    if (e && e.name === "QueryError") {
-      return json({ error: e.message, code: e.code ?? "INVALID_QUERY" }, 400);
-    }
-    throw e;
-  }
-
-  // Snapshot: the scoped query result. queryNotes throws QueryError on e.g. a
-  // non-indexed metadata operator field — surface as 400 (no stream opened).
-  //
-  // Strip paging (M3): the live matcher ignores limit/offset, so a default
-  // limit:50 would truncate the snapshot while live events deliver the full
-  // set — snapshot ⊊ live. The snapshot must be the COMPLETE matching set.
-  // queryNotes defaults an ABSENT limit to 100 (not unlimited), so pass a
-  // large sentinel to fetch every matching row.
-  const SNAPSHOT_UNBOUNDED = Number.MAX_SAFE_INTEGER;
-  const snapshotOpts: QueryOpts = { ...queryOpts, limit: SNAPSHOT_UNBOUNDED, offset: undefined };
-  let snapshotNotes;
-  try {
-    const raw = await store.queryNotes(snapshotOpts);
-    snapshotNotes = filterNotesByTagScope(raw, tagScope.allowed, tagScope.raw);
-  } catch (e: any) {
-    if (e && e.name === "QueryError") {
-      return json({ error: e.message, code: e.code ?? "INVALID_QUERY" }, 400);
-    }
-    throw e;
-  }
-
-  // Cap check BEFORE opening a stream so we can return a real 503. (The
-  // in-`start` re-check below only guards the rare interleave race where two
-  // subscribes pass this check before either registers.)
-  if (!manager.hasCapacity(vaultName)) {
-    return json(
-      {
-        error: "subscription cap reached for this vault — too many concurrent live subscriptions. Retry shortly or close idle streams.",
-        code: "SUBSCRIPTION_CAP_REACHED",
-      },
-      503,
-    );
-  }
-
-  // ---- Build the SSE stream ----
-  //
-  // A pull ReadableStream with an internal frame queue. The manager's sink
-  // writes frames into the queue; `pull` drains them to the controller and
-  // notifies the manager (so the backpressure counter decrements). When the
-  // client disconnects, `cancel` fires → we unregister the subscription and
-  // clear the keepalive timer.
-  let handle: { flushed: () => void; close: () => void } | null = null;
-  let keepalive: ReturnType<typeof setInterval> | null = null;
-
-  const queue: string[] = [];
-  let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null;
-  let cancelled = false;
-  const encoder = new TextEncoder();
-
-  const flushQueue = () => {
-    if (!controllerRef || cancelled) return;
-    while (queue.length > 0) {
-      const frame = queue.shift()!;
-      try {
-        controllerRef.enqueue(encoder.encode(frame));
-      } catch {
-        // Controller closed underneath us — stop.
-        cancelled = true;
-        return;
-      }
-      handle?.flushed();
-    }
-  };
-
-  // SSE sink over the stream queue. `send(event, data)` and the `:` keepalive
-  // comment both route through this same push → the emitted bytes are identical
-  // to the pre-WS-migration SSE contract (surface-client parses them unchanged).
-  const push = (frame: string): boolean => {
-    if (cancelled) return false;
-    queue.push(frame);
-    flushQueue();
-    return true;
-  };
-  const sink = new SseSink(push, () => {
-    if (cancelled) return;
-    cancelled = true;
-    if (keepalive) {
-      clearInterval(keepalive);
-      keepalive = null;
-    }
-    try {
-      controllerRef?.close();
-    } catch {
-      /* already closed */
-    }
-  });
-
-  const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
-      controllerRef = controller;
-      // 1. Snapshot first — written into the queue and flushed on this tick.
-      queue.push(snapshotFrame(snapshotNotes));
-
-      // 2. Register the live subscription. Hook dispatch is deferred to a
-      //    microtask, and we register synchronously here within start(), so no
-      //    live event can slip in front of the snapshot. Over-cap → 503; we
-      //    can't return a Response from inside the stream, so the cap is also
-      //    checked below before constructing the Response. (Re-check here for
-      //    the race where two subscribes interleave.)
-      handle = manager.register({
-        vaultName,
-        matcher,
-        tagScopeAllowed: tagScope.allowed,
-        tagScopeRaw: tagScope.raw,
-        sink,
-      });
-      if (!handle) {
-        // Lost the cap race. Emit nothing further and close; the pre-check
-        // below normally catches this, so this path is rare.
-        flushQueue();
-        try {
-          controller.close();
-        } catch {
-          /* noop */
-        }
-        cancelled = true;
-        return;
-      }
-
-      flushQueue();
-
-      // 3. Keepalive comments.
-      keepalive = setInterval(() => {
-        if (cancelled) return;
-        sink.comment(); // `:\n\n` — byte-identical keepalive comment.
-      }, KEEPALIVE_MS);
-    },
-    pull() {
-      flushQueue();
-    },
-    cancel() {
-      cancelled = true;
-      if (keepalive) {
-        clearInterval(keepalive);
-        keepalive = null;
-      }
-      handle?.close();
-    },
-  });
-
-  return new Response(stream, {
-    status: 200,
-    headers: {
-      "Content-Type": "text/event-stream",
-      "Cache-Control": "no-cache, no-transform",
-      Connection: "keep-alive",
-      // Defeat nginx-style proxy buffering of the event stream.
-      "X-Accel-Buffering": "no",
-    },
-  });
-}