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

package/.parachute/module.json

@@ -12,6 +12,7 @@
   "focus": "core",
   "adminCapabilities": ["config", "credentials"],
   "startCmd": ["parachute-vault", "serve"],
+  "websocket": true,
   "scopes": {
     "defines": ["vault:read", "vault:write", "vault:admin"]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.5-rc.12",
+  "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

@@ -0,0 +1,201 @@
+/**
+ * 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 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 { wsFrame, WsSink } from "./subscriptions.ts";
+import {
+  buildSnapshotFrames,
+  parseClientMessage,
+  vaultVerbRank,
+  sameTagScope,
+  validateWsSubscribeQuery,
+  subscriptionCapResponse,
+  urlFromQuery,
+  SNAPSHOT_CHUNK_MAX_NOTES,
+  WS_CLOSE,
+} from "./ws-subscribe.ts";
+import { unsupportedSubscriptionReason } from "./live-match.ts";
+import { FRAME_CORPUS, NOTE_A } from "./test-support/live-frame-corpus.ts";
+
+describe("live-frame parity — self-host WS bytes === corpus === cloud WS bytes", () => {
+  for (const c of FRAME_CORPUS) {
+    it(`${c.name}: WS message folds the event into \`type\` over the corpus payload`, () => {
+      const ws = wsFrame(c.event, 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);
+      const { type, ...rest } = parsedWs;
+      void type;
+      expect(rest).toEqual(c.data);
+
+      // BYTE parity of the inner payload: whatever value the event carries
+      // (`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(ws.includes(innerBytes)).toBe(true);
+    });
+  }
+});
+
+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: () => {} });
+    for (const c of FRAME_CORPUS) {
+      sink.send(c.event, c.data);
+      expect(sent.at(-1)).toBe(wsFrame(c.event, c.data));
+    }
+  });
+});
+
+describe("buildSnapshotFrames — chunking + done flag", () => {
+  it("empty set → exactly one done:true frame", () => {
+    const frames = buildSnapshotFrames([]);
+    expect(frames.length).toBe(1);
+    expect(JSON.parse(frames[0]!)).toEqual({ type: "snapshot", notes: [], done: true });
+  });
+
+  it("small set → one done:true frame carrying every note", () => {
+    const frames = buildSnapshotFrames([NOTE_A as any, NOTE_A as any]);
+    expect(frames.length).toBe(1);
+    const f = JSON.parse(frames[0]!);
+    expect(f.done).toBe(true);
+    expect(f.notes.length).toBe(2);
+  });
+
+  it("> SNAPSHOT_CHUNK_MAX_NOTES → multiple frames, only the last done:true, concat = full set", () => {
+    const many = Array.from({ length: SNAPSHOT_CHUNK_MAX_NOTES + 5 }, (_, i) => ({ ...NOTE_A, id: `n-${i}` }));
+    const frames = buildSnapshotFrames(many as any);
+    expect(frames.length).toBeGreaterThan(1);
+    const parsed = frames.map((f) => JSON.parse(f));
+    expect(parsed.filter((p) => p.done).length).toBe(1);
+    expect(parsed[parsed.length - 1]!.done).toBe(true);
+    parsed.slice(0, -1).forEach((p) => expect(p.done).toBe(false));
+    const concat = parsed.flatMap((p) => p.notes);
+    expect(concat.map((n: any) => n.id)).toEqual(many.map((n) => n.id));
+  });
+
+  it("each frame stays under the WS message ceiling with large notes", () => {
+    const big = Array.from({ length: 8 }, (_, i) => ({ ...NOTE_A, id: `big-${i}`, content: "x".repeat(200_000) }));
+    const frames = buildSnapshotFrames(big as any);
+    expect(frames.length).toBeGreaterThan(1);
+    for (const f of frames) expect(new TextEncoder().encode(f).byteLength).toBeLessThan(1_000_000);
+    expect(frames.flatMap((f) => JSON.parse(f).notes).length).toBe(8);
+  });
+});
+
+describe("parseClientMessage", () => {
+  it("valid auth", () => {
+    expect(parseClientMessage(JSON.stringify({ type: "auth", token: "t" }))).toEqual({ kind: "auth", token: "t" });
+  });
+  it("auth without a token → malformed", () => {
+    expect(parseClientMessage(JSON.stringify({ type: "auth" })).kind).toBe("malformed");
+    expect(parseClientMessage(JSON.stringify({ type: "auth", token: "" })).kind).toBe("malformed");
+  });
+  it("non-json / non-object → malformed", () => {
+    expect(parseClientMessage("not json").kind).toBe("malformed");
+    expect(parseClientMessage(JSON.stringify([1, 2])).kind).toBe("malformed");
+  });
+  it("other typed message → other", () => {
+    expect(parseClientMessage(JSON.stringify({ type: "hello" }))).toEqual({ kind: "other", type: "hello" });
+  });
+  it("decodes a Uint8Array frame", () => {
+    const bytes = new TextEncoder().encode(JSON.stringify({ type: "auth", token: "b" }));
+    expect(parseClientMessage(bytes)).toEqual({ kind: "auth", token: "b" });
+  });
+});
+
+describe("vaultVerbRank — narrow-or-equal ordering", () => {
+  it("ranks read < write < admin, -1 for none/other-vault", () => {
+    expect(vaultVerbRank(["vault:v:read"], "v")).toBe(0);
+    expect(vaultVerbRank(["vault:v:write"], "v")).toBe(1);
+    expect(vaultVerbRank(["vault:v:admin"], "v")).toBe(2);
+    expect(vaultVerbRank(["vault:other:read"], "v")).toBe(-1);
+    expect(vaultVerbRank([], "v")).toBe(-1);
+  });
+  it("a widen is strictly greater (the 4403 trigger)", () => {
+    expect(vaultVerbRank(["vault:v:admin"], "v") > vaultVerbRank(["vault:v:read"], "v")).toBe(true);
+    expect(vaultVerbRank(["vault:v:read"], "v") > vaultVerbRank(["vault:v:admin"], "v")).toBe(false);
+  });
+});
+
+describe("sameTagScope — the WS re-auth tag-scope-delta gate", () => {
+  it("both unscoped (null) → same", () => {
+    expect(sameTagScope(null, null)).toBe(true);
+  });
+  it("null vs scoped → differ (a drop/gain of scoping)", () => {
+    expect(sameTagScope(null, ["work/eng"])).toBe(false);
+    expect(sameTagScope(["work/eng"], null)).toBe(false);
+  });
+  it("same set (order/dupe-insensitive) → same", () => {
+    expect(sameTagScope(["a", "b"], ["b", "a"])).toBe(true);
+    expect(sameTagScope(["a", "a", "b"], ["b", "a"])).toBe(true);
+  });
+  it("different membership → differ", () => {
+    expect(sameTagScope(["work/eng"], ["work/sales"])).toBe(false);
+    expect(sameTagScope(["a"], ["a", "b"])).toBe(false);
+  });
+});
+
+describe("validateWsSubscribeQuery — same rejects as the SSE route (byte-identical bodies)", () => {
+  const reject = async (q: string) => {
+    const v = validateWsSubscribeQuery(new URL(`http://x/vault/v/api/subscribe?${q}`));
+    expect("error" in v).toBe(true);
+    const body = await (v as { error: Response }).error.json();
+    expect((v as { error: Response }).error.status).toBe(400);
+    expect(body.code).toBe("UNSUPPORTED_SUBSCRIPTION_QUERY");
+  };
+  it("rejects the URL-reachable unsupported shapes: search / near / cursor / has_links", async () => {
+    await reject("search=hi");
+    await reject("near[note_id]=abc");
+    await reject("cursor=xyz");
+    await reject("has_links=true");
+  });
+  it("accepts a supported query", () => {
+    const v = validateWsSubscribeQuery(new URL("http://x/vault/v/api/subscribe?tag=chat&path_prefix=meetings/"));
+    expect("queryOpts" in v).toBe(true);
+  });
+  it("shares the SSE route's queryOpts-level guard (cursor/has_links/date filters)", () => {
+    // The belt-and-suspenders layer both doors + the SSE route route through:
+    // a date filter isn't expressible as a flat URL param (removed 0.6.4), but
+    // if one ever reaches queryOpts it is rejected identically.
+    expect(unsupportedSubscriptionReason({ cursor: "x" } as any)).toBeTruthy();
+    expect(unsupportedSubscriptionReason({ hasLinks: true } as any)).toBeTruthy();
+    expect(unsupportedSubscriptionReason({ dateFrom: "2026-01-01" } as any)).toBeTruthy();
+    expect(unsupportedSubscriptionReason({ dateFilter: { field: "created_at" } } as any)).toBeTruthy();
+    expect(unsupportedSubscriptionReason({ tags: ["chat"] } as any)).toBeNull();
+  });
+});
+
+describe("misc pure helpers", () => {
+  it("subscriptionCapResponse → 503 SUBSCRIPTION_CAP_REACHED", async () => {
+    const res = subscriptionCapResponse();
+    expect(res.status).toBe(503);
+    expect((await res.json()).code).toBe("SUBSCRIPTION_CAP_REACHED");
+  });
+  it("urlFromQuery reconstructs searchParams from a raw query string", () => {
+    expect(urlFromQuery("?tag=chat&a=b").searchParams.get("tag")).toBe("chat");
+    expect(urlFromQuery("").search).toBe("");
+  });
+  it("WS_CLOSE carries the four application close codes", () => {
+    expect([WS_CLOSE.PROTOCOL, WS_CLOSE.UNAUTHORIZED, WS_CLOSE.FORBIDDEN, WS_CLOSE.AUTH_TIMEOUT]).toEqual([
+      4400, 4401, 4403, 4408,
+    ]);
+  });
+});

package/src/module-manifest.ts

@@ -48,6 +48,14 @@ export interface VaultModuleManifest {
   readonly paths: readonly string[];
   readonly health: string;
   readonly stripPrefix?: boolean;
+  /**
+   * When `true`, vault's daemon accepts WebSocket upgrades (the live-query WS
+   * binding) and the hub's ws-bridge forwards `Upgrade: websocket` requests on
+   * vault's mounts. DENY BY DEFAULT on the hub side. Carried onto the
+   * self-registered services.json row too (`ServiceEntry.websocket`); the hub
+   * honors either source. See `parachute-hub/src/ws-bridge.ts`.
+   */
+  readonly websocket?: boolean;
 }
 
 /**

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/self-register.test.ts

@@ -382,6 +382,25 @@ describe("self-register", () => {
     });
   });
 
+  test("websocket capability flows from manifest to row when set (hub ws-bridge gate)", () => {
+    withParachuteHome((home) => {
+      const { log, warn } = captureLogs();
+      selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => ({ ...TEST_MANIFEST, websocket: true }),
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+
+      const raw = readFileSync(join(home, "services.json"), "utf8");
+      const parsed = JSON.parse(raw) as { services: Record<string, unknown>[] };
+      expect(parsed.services[0]!.websocket).toBe(true);
+    });
+  });
+
   test("changed=true when installDir differs from prior row", () => {
     withParachuteHome(() => {
       const { log, warn } = captureLogs();

package/src/self-register.ts

@@ -191,6 +191,7 @@ export function selfRegister(deps: SelfRegisterDeps): SelfRegisterResult {
     displayName?: string;
     tagline?: string;
     stripPrefix?: boolean;
+    websocket?: boolean;
   } = {
     name: manifest.manifestName,
     port,
@@ -202,6 +203,9 @@ export function selfRegister(deps: SelfRegisterDeps): SelfRegisterResult {
   if (manifest.displayName !== undefined) entry.displayName = manifest.displayName;
   if (manifest.tagline !== undefined) entry.tagline = manifest.tagline;
   if (manifest.stripPrefix !== undefined) entry.stripPrefix = manifest.stripPrefix;
+  // Carry the live-query WS capability onto the row so the hub ws-bridge admits
+  // upgrades without having to read module.json (the row is its first source).
+  if (manifest.websocket !== undefined) entry.websocket = manifest.websocket;
 
   // Detect whether the existing row already matches (no-op idempotency
   // signal). We don't gate the write on this — `upsertService` itself is
@@ -232,7 +236,8 @@ export function selfRegister(deps: SelfRegisterDeps): SelfRegisterResult {
     priorRow.health !== health ||
     (priorRow as { displayName?: string }).displayName !== manifest.displayName ||
     (priorRow as { tagline?: string }).tagline !== manifest.tagline ||
-    (priorRow as { stripPrefix?: boolean }).stripPrefix !== manifest.stripPrefix;
+    (priorRow as { stripPrefix?: boolean }).stripPrefix !== manifest.stripPrefix ||
+    (priorRow as { websocket?: boolean }).websocket !== manifest.websocket;
 
   try {
     upsertImpl(entry);

package/src/server.ts

@@ -61,6 +61,7 @@ import {
 } from "./mirror-config.ts";
 import { GLOBAL_CONFIG_PATH } from "./config.ts";
 import { selfRegister } from "./self-register.ts";
+import { createSubscribeWsBinding, isWebSocketUpgrade } from "./ws-server.ts";
 import { warnLegacyGlobalApiKeys } from "./auth.ts";
 import pkg from "../package.json" with { type: "json" };
 
@@ -490,10 +491,18 @@ const hostname = resolveBindHostname();
   }
 }
 
+// Live-query WebSocket binding (WS-hibernation migration Phase 3). Same
+// subscription contract as the SSE route, WebSocket transport. Handlers +
+// upgrade decision live in ws-server.ts; the per-vault WS cap is closure state
+// there. Advertised via `"websocket": true` in `.parachute/module.json` so the
+// hub ws-bridge admits the upgrade.
+const subscribeWs = createSubscribeWsBinding();
+
 const server = Bun.serve({
   port,
   hostname,
   idleTimeout: 120, // seconds — webhook triggers can take a while
+  websocket: subscribeWs.handlers,
   async fetch(req, server) {
     const url = new URL(req.url);
     const path = url.pathname;
@@ -517,6 +526,22 @@ const server = Bun.serve({
       return new Response(null, { status: 204, headers: corsHeaders });
     }
 
+    // Live-query WebSocket upgrade — detected BEFORE the fetch pipeline because
+    // 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
+      if (verdict.kind === "response") {
+        for (const [k, v] of Object.entries(corsHeaders)) {
+          verdict.response.headers.set(k, v);
+        }
+        return verdict.response;
+      }
+      // "pass" → not a subscribe WS upgrade; fall through to the pipeline.
+    }
+
     try {
       const start = Date.now();
       const response = await route(req, path);

package/src/services-manifest.ts

@@ -15,6 +15,14 @@ export interface ServiceEntry {
   paths: string[];
   health: string;
   version: string;
+  /**
+   * When `true`, the hub's ws-bridge forwards `Upgrade: websocket` requests on
+   * this module's mounts to it (deny-by-default). Carried from the module's
+   * `.parachute/module.json` `websocket` field by self-registration; the hub
+   * honors either source. Optional + free-riding — extra fields survive the
+   * read/merge via the `...e` spread in `validateEntry` / `upsertService`.
+   */
+  websocket?: boolean;
 }
 
 export interface ServicesManifest {

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,6 +10,24 @@
  * connection-scoped, driving a live UI. Same event source, same predicate,
  * different durability.
  *
+ * ## 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 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`.
+ *
+ * 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
  *
  * All vault stores share the process-wide `defaultHookRegistry`
@@ -54,16 +74,19 @@ export const DEFAULT_MAX_SUBSCRIPTIONS_PER_VAULT = 100;
  * Default bound on a single subscription's pending (unflushed) event buffer.
  * If a slow client lets the buffer grow past this, the stream is closed — it
  * reconnects and re-snapshots rather than the server growing memory unbounded.
+ * Only enforced for flush-tracking sinks (SSE); the WS transport delegates
+ * outgoing-buffer bounds to the Bun runtime.
  */
 export const DEFAULT_MAX_BUFFERED_EVENTS = 1000;
 
-/** A serialized SSE frame ready to write to the wire. */
-type SseFrame = string;
-
+/**
+ * The abstract sink an event is rendered to. The manager calls `send(event,
+ * data)`; each transport formats for its wire. Returns `false` when the sink is
+ * gone (the manager then drops the subscription).
+ */
 export interface SubscriptionSink {
-  /** Enqueue a serialized SSE frame. Returns false if the sink is closed. */
-  write(frame: SseFrame): boolean;
-  /** Close the underlying stream (teardown). Idempotent. */
+  send(event: string, data: unknown): boolean;
+  /** Close the underlying stream/socket (teardown). Idempotent. */
   close(): void;
 }
 
@@ -75,14 +98,56 @@ interface Subscription {
   /** Raw root-tag allowlist (null = unscoped) — `noteWithinTagScope` arg. */
   readonly tagScopeRaw: string[] | null;
   readonly sink: SubscriptionSink;
-  /** Pending unflushed frame count (backpressure bound). */
+  /** SSE tracks unflushed frames to bound memory; WS delegates to the runtime. */
+  readonly tracksFlush: boolean;
+  /** Whether this sub counts against the per-vault manager cap (SSE) — the WS
+   *  transport enforces its own cap via the live-socket count at upgrade. */
+  readonly countsTowardCap: boolean;
+  /** Pending unflushed frame count (backpressure bound; SSE only). */
   buffered: number;
   readonly maxBuffered: number;
   closed: boolean;
 }
 
-function sseEvent(event: string, data: unknown): SseFrame {
-  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+/** 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 });
+}
+
+/** 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 {
+  send(data: string): unknown;
+  close(code?: number, reason?: string): unknown;
+}
+
+/** WebSocket sink: renders `(event, data)` to a `{ type, ...data }` message and
+ *  sends it on the socket. `sendRaw` is for pre-formatted frames (the chunked
+ *  snapshot the WS binding builds directly). A send on a dead socket returns
+ *  false → the manager drops the sub. */
+export class WsSink implements SubscriptionSink {
+  constructor(private readonly ws: WsLike) {}
+  send(event: string, data: unknown): boolean {
+    return this.sendRaw(wsFrame(event, data));
+  }
+  sendRaw(frame: string): boolean {
+    try {
+      this.ws.send(frame);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  close(): void {
+    try {
+      this.ws.close(1011, "subscription closed");
+    } catch {
+      /* already closing/closed */
+    }
+  }
 }
 
 export class SubscriptionManager {
@@ -140,9 +205,15 @@ export class SubscriptionManager {
     tagScopeRaw: string[] | null;
     sink: SubscriptionSink;
     maxBuffered?: number;
+    /** SSE (default true) tracks unflushed frames; WS passes false. */
+    tracksFlush?: boolean;
+    /** SSE (default true) counts against the per-vault manager cap; WS passes
+     *  false — the WS transport caps via the live-socket count at upgrade. */
+    countsTowardCap?: boolean;
   }): SubscriptionHandle | null {
+    const countsTowardCap = args.countsTowardCap ?? true;
     const current = this.countForVault(args.vaultName);
-    if (current >= this.maxPerVault) return null;
+    if (countsTowardCap && current >= this.maxPerVault) return null;
 
     this.ensureHooks();
 
@@ -152,12 +223,14 @@ export class SubscriptionManager {
       tagScopeAllowed: args.tagScopeAllowed,
       tagScopeRaw: args.tagScopeRaw,
       sink: args.sink,
+      tracksFlush: args.tracksFlush ?? true,
+      countsTowardCap,
       buffered: 0,
       maxBuffered: args.maxBuffered ?? DEFAULT_MAX_BUFFERED_EVENTS,
       closed: false,
     };
     this.subs.add(sub);
-    this.perVaultCount.set(args.vaultName, current + 1);
+    if (countsTowardCap) this.perVaultCount.set(args.vaultName, current + 1);
 
     return {
       /** Note that a previously-buffered frame flushed to the wire. */
@@ -172,9 +245,11 @@ export class SubscriptionManager {
     if (sub.closed) return;
     sub.closed = true;
     this.subs.delete(sub);
-    const n = this.perVaultCount.get(sub.vaultName) ?? 0;
-    if (n <= 1) this.perVaultCount.delete(sub.vaultName);
-    else this.perVaultCount.set(sub.vaultName, n - 1);
+    if (sub.countsTowardCap) {
+      const n = this.perVaultCount.get(sub.vaultName) ?? 0;
+      if (n <= 1) this.perVaultCount.delete(sub.vaultName);
+      else this.perVaultCount.set(sub.vaultName, n - 1);
+    }
     try {
       sub.sink.close();
     } catch {
@@ -182,33 +257,21 @@ export class SubscriptionManager {
     }
   }
 
-  /**
-   * Send a keepalive comment to every open subscription (the route's timer
-   * calls this). A `:` comment defeats idle-proxy timeouts; it's not an event
-   * so it never counts against the buffer bound.
-   */
-  keepaliveAll(): void {
-    for (const sub of this.subs) {
-      if (sub.closed) continue;
-      const ok = sub.sink.write(":\n\n");
-      if (!ok) this.remove(sub);
-    }
-  }
-
-  /** Emit a frame to one subscription, enforcing the buffer bound. */
-  private emit(sub: Subscription, frame: SseFrame): void {
+  /** Emit an `(event, data)` tuple to one subscription, enforcing the buffer
+   *  bound for flush-tracking (SSE) sinks. */
+  private emit(sub: Subscription, event: string, data: unknown): void {
     if (sub.closed) return;
-    if (sub.buffered >= sub.maxBuffered) {
+    if (sub.tracksFlush && sub.buffered >= sub.maxBuffered) {
       // Backpressure: client can't keep up. Close → it reconnects + re-snapshots.
       this.remove(sub);
       return;
     }
-    const ok = sub.sink.write(frame);
+    const ok = sub.sink.send(event, data);
     if (!ok) {
       this.remove(sub);
       return;
     }
-    sub.buffered++;
+    if (sub.tracksFlush) sub.buffered++;
   }
 
   /** Lazily register the three broad hooks (once per manager). */
@@ -244,7 +307,7 @@ export class SubscriptionManager {
         // the client ignores ids it never held. Documented low-sensitivity
         // existence leak (see design §scope-intersection).
         const ref = payload as DeletedNoteRef;
-        this.emit(sub, sseEvent("remove", { id: ref.id }));
+        this.emit(sub, "remove", { id: ref.id });
         continue;
       }
 
@@ -257,14 +320,14 @@ export class SubscriptionManager {
       const matches = sub.matcher.match(note) && inScope;
 
       if (matches) {
-        this.emit(sub, sseEvent("upsert", { note }));
+        this.emit(sub, "upsert", { note });
       } else if (event === "updated" && inScope) {
         // Left the set (predicate no longer true) BUT still within this
         // token's scope, so the sub could have held it — idempotent remove
         // (client drops the id if held, no-op otherwise). When the note is
         // OUT of scope the sub never had it; emitting would leak its id, so
         // we stay silent.
-        this.emit(sub, sseEvent("remove", { id: note.id }));
+        this.emit(sub, "remove", { id: note.id });
       }
       // created that doesn't match → nothing (it was never in the set).
     }
@@ -286,10 +349,5 @@ export interface SubscriptionHandle {
   close: () => void;
 }
 
-/** Serialize a snapshot frame (exported for the route + tests). */
-export function snapshotFrame(notes: Note[]): SseFrame {
-  return sseEvent("snapshot", { notes });
-}
-
 /** Process-wide manager — shared like `defaultHookRegistry`. */
 export const subscriptionManager = new SubscriptionManager();