@openparachute/vault 0.6.5-rc.2 → 0.6.5

package/src/routes.ts

@@ -29,6 +29,10 @@ import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
 import { IndexedFieldError } from "../core/src/indexed-fields.ts";
 import { buildVaultProjection, resolveTagInheritance } from "../core/src/vault-projection.ts";
+import {
+  resolveTranscriptionCapability,
+  type TranscriptionCapability,
+} from "./transcription/capability.ts";
 import { loadSchemaConfig } from "../core/src/schema-defaults.ts";
 import {
   buildExpandVisibility,
@@ -2085,7 +2089,7 @@ export async function handleTags(
 
   // PUT /tags/:name — upsert tag identity row. Body accepts any combination
   // of { description, fields, relationships, parent_names }; omitted keys
-  // are preserved, explicit null clears. See patterns/tag-data-model.md.
+  // are preserved, explicit null clears. See docs/contracts/tag-data-model.md.
   if (req.method === "PUT") {
     // Canonical-bare-tag guard (vault#XXX): normalize the upserted tag NAME so
     // the existing-field merge read (store.getTagSchema below) and the upsert
@@ -2110,7 +2114,7 @@ export async function handleTags(
        * the MCP `update-tag` tool relies on (omitted keys preserved). The
        * Schema editor (vault#283) sends the full map + `replace_fields: true`
        * so removing a field row actually deletes the field. See
-       * patterns/tag-data-model.md.
+       * docs/contracts/tag-data-model.md.
        */
       replace_fields?: unknown;
     };
@@ -2207,7 +2211,7 @@ export async function handleTags(
     // Tag-scoped tokens reference root tags by name; deleting a referenced
     // tag would silently orphan the token's allowlist. Fail closed (409)
     // and name the offending tokens so the operator can revoke or re-mint
-    // before retrying. patterns/tag-scoped-tokens.md §Dependencies.
+    // before retrying. docs/contracts/tag-scoped-tokens.md §Dependencies.
     const referenced_by = findTokensReferencingTag(store.db, tagName);
     if (referenced_by.length > 0) {
       return json(
@@ -2328,11 +2332,24 @@ export async function handleVault(
   store: Store,
   vaultConfig: VaultConfigLike,
   persist?: () => void,
+  /**
+   * Injection seam (scribe-fold Phase 1) for the transcription capability
+   * probe on the GET landing. Production omits it and resolves the live
+   * default (scribe-http) provider's availability; tests inject a deterministic
+   * resolver. Kept separate from the `auto_transcribe` POLICY toggle: this
+   * reports whether transcription is actually POSSIBLE (a provider is
+   * configured AND available), which is what a surface gates its mic on.
+   */
+  resolveCapability: () => Promise<TranscriptionCapability> = resolveTranscriptionCapability,
 ): Promise<Response> {
   const url = new URL(req.url);
 
   if (req.method === "GET") {
     const result: Record<string, unknown> = vaultResponse(vaultConfig);
+    // Transcription capability flag — `enabled` iff a provider is configured
+    // and available. `minutes_remaining` is omitted (cloud/plan concern;
+    // self-host is unmetered). This is the field Notes gates the mic on.
+    result.transcription = await resolveCapability();
     if (parseBool(parseQuery(url, "include_stats"), false)) {
       result.stats = await store.getVaultStats();
     }

package/src/routing.test.ts

@@ -1631,7 +1631,7 @@ describe("scope enforcement on /api/*", () => {
     expect(res.status).toBe(401);
   });
 
-  // ----- tag-scoped tokens (patterns/tag-scoped-tokens.md) -----------------
+  // ----- tag-scoped tokens (docs/contracts/tag-scoped-tokens.md) -----------------
 
   /**
    * Mint a tag-scoped token. Mirrors `mintToken` above but threads
@@ -1745,7 +1745,7 @@ describe("scope enforcement on /api/*", () => {
   });
 
   // ----- Q6: orphan-sub-tag fail-open ------------------------------------
-  // patterns/tag-scoped-tokens.md §Storage: when a sub-tag has no declared
+  // docs/contracts/tag-scoped-tokens.md §Storage: when a sub-tag has no declared
   // schema, the string-form root authorizes. Token allowlisted for `health`
   // must see `#health/food` even when no `_tags/health/food` schema exists.
 

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 {
@@ -856,7 +855,7 @@ export async function route(
 
   const apiPath = apiMatch[1] ?? "";
 
-  // Tag-scoped tokens (patterns/tag-scoped-tokens.md): expand the token's
+  // Tag-scoped tokens (docs/contracts/tag-scoped-tokens.md): expand the token's
   // root-tag allowlist into `{root} ∪ descendants(root)` once per request,
   // so handlers can intersect against the note's tag set without re-walking
   // the `_tags/<name>` hierarchy on every check. `tagScope.allowed` is null
@@ -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

@@ -30,6 +30,20 @@ import { setTranscriptionWorker } from "./transcription-registry.ts";
 import { assetsDir } from "./routes.ts";
 import { resolveScribeAuthToken, ensureScribeBearer } from "./scribe-env.ts";
 import { getCachedScribeUrl } from "./scribe-discovery.ts";
+import { TranscribeCppProvider } from "./transcription/providers/transcribe-cpp.ts";
+import { ParakeetMlxProvider } from "./transcription/providers/parakeet-mlx.ts";
+import { OnnxAsrProvider } from "./transcription/providers/onnx-asr.ts";
+import {
+  resolveTranscriptionProviderName,
+  resolveTranscribeCppPaths,
+  transcribeCppInstalled,
+  resolveParakeetMlxBin,
+  resolveParakeetMlxModel,
+  resolveOnnxAsrBin,
+  resolveOnnxAsrModel,
+  parakeetMlxInstalled,
+  onnxAsrInstalled,
+} from "./transcription/select.ts";
 import { readEnvFile, setEnvVar } from "./config.ts";
 import { resolveBindHostname } from "./bind.ts";
 import { MirrorManager } from "./mirror-manager.ts";
@@ -47,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" };
 
@@ -107,40 +122,102 @@ registerConfiguredTriggers();
  * Authorization header on a 401 and transcription fails with a friendly
  * error captured on the transcript note.
  */
-const scribeUrl = getCachedScribeUrl();
 let transcriptionWorker: TranscriptionWorker | null = null;
-if (scribeUrl) {
-  // Generate + persist the shared bearer on first boot. Subsequent boots
-  // pick up the existing value and don't rotate. Loading the .env back
-  // into process.env happens above (`loadEnvFile()`); we re-load here to
-  // pick up the just-written value without restart.
-  const { created, token } = ensureScribeBearer(readEnvFile, setEnvVar);
-  if (created) {
-    process.env.SCRIBE_AUTH_TOKEN = token;
-    console.log("[transcribe] generated SCRIBE_AUTH_TOKEN (32 bytes, base64url) — mirror this value into scribe's config");
-  }
-  transcriptionWorker = startTranscriptionWorker({
-    vaultList: () => listVaults(),
-    getStore: (name) => getVaultStore(name),
-    scribeUrl,
-    scribeToken: resolveScribeAuthToken(),
-    resolveAssetsDir: (vault) => assetsDir(vault),
-    getAudioRetention: (vault) => readVaultConfig(vault)?.audio_retention ?? "keep",
-    getContextPredicates: (vault) => readVaultConfig(vault)?.transcription?.context,
-  });
-  // Event-driven hot path — the `attachment:created` hook fires the worker
-  // in a microtask instead of waiting for the 30s sweep.
+
+// Shared worker wiring: the event-driven `attachment:created` hot path + the
+// REST-retry registry. Same for whichever provider the worker was built with.
+function wireTranscriptionWorker(worker: TranscriptionWorker): void {
   registerTranscriptionHook(
     defaultHookRegistry,
-    transcriptionWorker,
+    worker,
     (store) => getVaultNameForStore(store as never),
   );
-  // Expose the worker to the REST retry endpoint so retries kick immediately
-  // instead of waiting for the sweep. Idempotent on second boot.
-  setTranscriptionWorker(transcriptionWorker);
-  console.log(`[transcribe] worker started → ${scribeUrl}`);
+  setTranscriptionWorker(worker);
+}
+
+// Fields the worker needs regardless of provider (queue/retention/context).
+const commonWorkerOpts = {
+  vaultList: () => listVaults(),
+  getStore: (name: string) => getVaultStore(name),
+  resolveAssetsDir: (vault: string) => assetsDir(vault),
+  getAudioRetention: (vault: string) => readVaultConfig(vault)?.audio_retention ?? "keep",
+  getContextPredicates: (vault: string) => readVaultConfig(vault)?.transcription?.context,
+};
+
+// Provider selection (scribe-fold Phase 2a). Default is `scribe-http` — unset
+// TRANSCRIPTION_PROVIDER means the existing scribe-http path runs unchanged.
+const providerName = resolveTranscriptionProviderName();
+if (providerName === "transcribe-cpp") {
+  // Local, no-Python provider: subprocess a transcribe-cli. Only start the
+  // worker when a runnable CLI + model are actually present — otherwise every
+  // pending item would terminal-fail with `missing_provider`. (v0.1.1 ships a
+  // library, not a CLI, so this gate stays closed until TRANSCRIBE_CPP_BIN or a
+  // build-from-source CLI exists.) `transcribeCppInstalled` is a cheap
+  // existsSync check (no spawn), matching `available()`.
+  const tcPaths = resolveTranscribeCppPaths();
+  if (transcribeCppInstalled(tcPaths)) {
+    transcriptionWorker = startTranscriptionWorker({
+      ...commonWorkerOpts,
+      provider: new TranscribeCppProvider({ binPath: tcPaths.binPath, modelPath: tcPaths.modelPath }),
+    });
+    wireTranscriptionWorker(transcriptionWorker);
+    console.log(`[transcribe] worker started → transcribe-cpp (${tcPaths.modelPath})`);
+  } else {
+    console.log(
+      "[transcribe] TRANSCRIPTION_PROVIDER=transcribe-cpp but no runnable transcribe-cli + model installed — see `parachute-vault transcription status` (v0.1.1 ships a library, not a CLI; set TRANSCRIBE_CPP_BIN or build one)",
+    );
+  }
+} else if (providerName === "parakeet-mlx" || providerName === "onnx-asr") {
+  // Python-based local providers (scribe-fold Phase 2b): subprocess the
+  // parakeet-mlx / onnx-asr CLI. Only start the worker when a runnable binary
+  // resolves (env override → managed venv → PATH) — otherwise every pending
+  // item would terminal-fail with `missing_provider`. Cheap existsSync check
+  // (no spawn), matching the providers' `available()`.
+  const installed = providerName === "parakeet-mlx" ? parakeetMlxInstalled() : onnxAsrInstalled();
+  if (installed) {
+    const provider =
+      providerName === "parakeet-mlx"
+        ? new ParakeetMlxProvider({
+            binPath: resolveParakeetMlxBin(),
+            model: resolveParakeetMlxModel(),
+          })
+        : new OnnxAsrProvider({ binPath: resolveOnnxAsrBin(), model: resolveOnnxAsrModel() });
+    transcriptionWorker = startTranscriptionWorker({ ...commonWorkerOpts, provider });
+    wireTranscriptionWorker(transcriptionWorker);
+    console.log(`[transcribe] worker started → ${providerName}`);
+  } else {
+    console.log(
+      `[transcribe] TRANSCRIPTION_PROVIDER=${providerName} but no runnable ${providerName} binary found — run \`parachute-vault transcription install\` (see \`transcription status\`)`,
+    );
+  }
 } else {
-  console.log("[transcribe] worker disabled (no scribe in services.json and SCRIBE_URL unset)");
+  // Default scribe-http path — behavior-preserving (Phase 1). Start the worker
+  // if scribe is discoverable; otherwise transcription is a no-op.
+  //
+  // Scribe URL resolution order (per `scribe-discovery.ts`): `SCRIBE_URL` env
+  // var, then `~/.parachute/services.json` `parachute-scribe` entry, then none.
+  //
+  // Bearer generation (vault#353): if neither `SCRIBE_AUTH_TOKEN` nor the
+  // legacy `SCRIBE_TOKEN` is set, generate a fresh 32-byte base64url bearer
+  // and persist it to vault's `.env` so subsequent restarts use the same
+  // value. The operator (or hub install) mirrors this bearer to scribe.
+  const scribeUrl = getCachedScribeUrl();
+  if (scribeUrl) {
+    const { created, token } = ensureScribeBearer(readEnvFile, setEnvVar);
+    if (created) {
+      process.env.SCRIBE_AUTH_TOKEN = token;
+      console.log("[transcribe] generated SCRIBE_AUTH_TOKEN (32 bytes, base64url) — mirror this value into scribe's config");
+    }
+    transcriptionWorker = startTranscriptionWorker({
+      ...commonWorkerOpts,
+      scribeUrl,
+      scribeToken: resolveScribeAuthToken(),
+    });
+    wireTranscriptionWorker(transcriptionWorker);
+    console.log(`[transcribe] worker started → ${scribeUrl}`);
+  } else {
+    console.log("[transcribe] worker disabled (no scribe in services.json and SCRIBE_URL unset)");
+  }
 }
 
 if (process.env.VAULT_AUTH_TOKEN?.trim()) {
@@ -206,9 +283,10 @@ if (listVaults().length === 0) {
       }
       writeGlobalConfig(globalConfig);
       console.log(`Auto-created vault "${vaultName}" (API key: ${fullKey})`);
-      // Seed the in-vault onboarding guide so a connected AI can self-orient and
-      // help set the vault up — same as the `create`/`init` CLI path. Idempotent
-      // + best-effort (never fails first boot). Mirrors createVault() in cli.ts.
+      // Seed the default packs (welcome web + capture tag, Getting Started
+      // guide) so a connected AI can self-orient and help set the vault up —
+      // same as the `create`/`init` CLI path. Idempotent + best-effort (never
+      // fails first boot). Mirrors createVault() in cli.ts.
       await seedOnboardingNotesBestEffort(getVaultStore(vaultName));
     } else if (firstBoot.source === "env-invalid") {
       // PARACHUTE_VAULT_NAME was set but failed validation — do NOT silently
@@ -413,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;
@@ -440,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();