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

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.13",
   "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,226 @@
+/**
+ * Live-query frame PARITY + the pure WS helpers (WS-hibernation migration
+ * Phase 3, 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.
+ *
+ * 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 {
+  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";
+
+/** 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", () => {
+  for (const c of FRAME_CORPUS) {
+    it(`${c.name}: identical inner payload across transports`, () => {
+      const sse = sseFrame(c.event, c.data);
+      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);
+      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 in both frames AND
+      // equals 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", () => {
+  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));
+    }
+  });
+
+  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", () => {
+  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/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,21 @@ 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. the SSE
+    // fallback, which has no Upgrade header) 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/subscribe.ts

@@ -24,8 +24,8 @@ import { buildLiveMatcher, unsupportedSubscriptionReason } from "./live-match.ts
 import {
   snapshotFrame,
   subscriptionManager,
+  SseSink,
   type SubscriptionManager,
-  type SubscriptionSink,
 } from "./subscriptions.ts";
 
 /** Keepalive interval — `:` comment every ~25s to defeat idle-proxy timeouts. */
@@ -160,27 +160,28 @@ export async function handleSubscribe(
     }
   };
 
-  const sink: SubscriptionSink = {
-    write(frame: string): boolean {
-      if (cancelled) return false;
-      queue.push(frame);
-      flushQueue();
-      return true;
-    },
-    close(): void {
-      if (cancelled) return;
-      cancelled = true;
-      if (keepalive) {
-        clearInterval(keepalive);
-        keepalive = null;
-      }
-      try {
-        controllerRef?.close();
-      } catch {
-        /* already closed */
-      }
-    },
+  // 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) {
@@ -219,7 +220,7 @@ export async function handleSubscribe(
       // 3. Keepalive comments.
       keepalive = setInterval(() => {
         if (cancelled) return;
-        sink.write(":\n\n");
+        sink.comment(); // `:\n\n` — byte-identical keepalive comment.
       }, KEEPALIVE_MS);
     },
     pull() {