@openparachute/vault 0.6.5-rc.11 → 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/core/src/core.test.ts

@@ -4046,7 +4046,7 @@ describe("query-notes link expansion", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Tag hierarchy via tags.parent_names (post-v14, patterns/tag-data-model.md)
+// Tag hierarchy via tags.parent_names (post-v14, docs/contracts/tag-data-model.md)
 // ---------------------------------------------------------------------------
 
 describe("tag hierarchy (tags.parent_names)", async () => {
@@ -5107,7 +5107,7 @@ describe("schema inheritance via parent_names (vault#270)", async () => {
   });
 });
 
-describe("expandTagsWithDescendants (tag-scoped tokens — patterns/tag-scoped-tokens.md)", async () => {
+describe("expandTagsWithDescendants (tag-scoped tokens — docs/contracts/tag-scoped-tokens.md)", async () => {
   it("returns the union of root + every descendant per tags.parent_names", async () => {
     await store.upsertTagRecord("health/food", { parent_names: ["health"] });
     await store.upsertTagRecord("health/food/breakfast", { parent_names: ["health/food"] });
@@ -5143,10 +5143,10 @@ describe("expandTagsWithDescendants (tag-scoped tokens — patterns/tag-scoped-t
 });
 
 // ---------------------------------------------------------------------------
-// Tag record API — patterns/tag-data-model.md
+// Tag record API — docs/contracts/tag-data-model.md
 // ---------------------------------------------------------------------------
 
-describe("tag record API (patterns/tag-data-model.md)", async () => {
+describe("tag record API (docs/contracts/tag-data-model.md)", async () => {
   it("upsertTagRecord persists description + fields + relationships + parent_names", async () => {
     await store.upsertTagRecord("project", {
       description: "long-running deliverable",
@@ -5430,7 +5430,7 @@ describe("tag record API (patterns/tag-data-model.md)", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Schema migration v13 → v14 — patterns/tag-data-model.md
+// Schema migration v13 → v14 — docs/contracts/tag-data-model.md
 // ---------------------------------------------------------------------------
 
 describe("schema migration v13 → v14", async () => {
@@ -5809,7 +5809,7 @@ describe("schema migration v15 → v16", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Tag-scope auth post-v14 — patterns/tag-scoped-tokens.md
+// Tag-scope auth post-v14 — docs/contracts/tag-scoped-tokens.md
 // ---------------------------------------------------------------------------
 
 describe("tag-scope auth (post-v14 hierarchy)", async () => {
@@ -5824,7 +5824,7 @@ describe("tag-scope auth (post-v14 hierarchy)", async () => {
   });
 
   it("orphan sub-tag fallback: token for `health` still sees `#health/food` even with no declared hierarchy", async () => {
-    // Per patterns/tag-scoped-tokens.md §Storage details, the auth check
+    // Per docs/contracts/tag-scoped-tokens.md §Storage details, the auth check
     // also splits on '/' and matches the root verbatim against the raw
     // allowlist. This survives the v14 source-of-truth swap because the
     // fallback lives in src/tag-scope.ts, not in the resolver.

package/core/src/mcp.ts

@@ -1408,7 +1408,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "update-tag",
       requiredVerb: "write",
-      description: "Create or update a tag's identity row: description, indexed-field schemas, relationship-vocabulary map, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-patterns/patterns/tag-data-model.md.",
+      description: "Create or update a tag's identity row: description, indexed-field schemas, relationship-vocabulary map, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-vault/docs/contracts/tag-data-model.md.",
       inputSchema: {
         type: "object",
         properties: {

package/core/src/schema.ts

@@ -41,7 +41,7 @@ CREATE TABLE IF NOT EXISTS notes (
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
 -- declarations. One row per tag; no notes-as-config sidecars for these
--- concerns. See parachute-patterns/patterns/tag-data-model.md.
+-- concerns. See docs/contracts/tag-data-model.md.
 --
 -- description    — human-readable blurb (markdown).
 -- fields         — JSON: indexed metadata field declarations per
@@ -136,7 +136,7 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 -- scoped_tags is a JSON-encoded array of root tag names that constrain the
 -- token's effective access (intersection with the scopes column). NULL
 -- means unscoped — full vault access per scopes. Introduced in v13 per
--- patterns/tag-scoped-tokens.md. Hierarchy expansion is applied at auth
+-- docs/contracts/tag-scoped-tokens.md. Hierarchy expansion is applied at auth
 -- time via getTagDescendants; the column stores root names only.
 --
 -- vault_name (v16) binds the token to a single vault. NULL means the
@@ -443,7 +443,7 @@ export function initSchema(db: Database): void {
   // Migrate v13 → v14: tag-data-model reshape. Augment `tags` row with
   // description/fields/relationships/parent_names/timestamps; copy data
   // from the v6-era tag_schemas sidecar and from `_tags/<name>` config
-  // notes; drop tag_schemas after copy. See patterns/tag-data-model.md.
+  // notes; drop tag_schemas after copy. See docs/contracts/tag-data-model.md.
   migrateToV14(db);
 
   // Migrate v14 → v15: retire the `_schemas/<name>` and `_schema_defaults`
@@ -650,7 +650,7 @@ function migrateToV12(db: Database): void {
  * (current full-vault behavior); a JSON array of root tag names narrows the
  * token's access to notes carrying one of those tags or a sub-tag thereof
  * (hierarchy expansion via getTagDescendants at auth time). See
- * parachute-patterns/patterns/tag-scoped-tokens.md.
+ * docs/contracts/tag-scoped-tokens.md.
  */
 function migrateToV13(db: Database): void {
   if (hasTable(db, "tokens") && !hasColumn(db, "tokens", "scoped_tags")) {
@@ -659,7 +659,7 @@ function migrateToV13(db: Database): void {
 }
 
 /**
- * Migrate v13 → v14: tag-data-model reshape (patterns/tag-data-model.md).
+ * Migrate v13 → v14: tag-data-model reshape (docs/contracts/tag-data-model.md).
  *
  * Augments the `tags` table with five new columns and one timestamp pair,
  * then copies pre-existing data from two notes-as-config sidecars:

package/core/src/tag-hierarchy.ts

@@ -9,7 +9,7 @@
  * History: pre-v14 vaults stored hierarchy in notes-as-config at
  * `_tags/<name>`. The v14 migration (see core/src/schema.ts:migrateToV14)
  * lifts those parent declarations onto the tags row and the resolver here
- * was swapped accordingly. See parachute-patterns/patterns/tag-data-model.md.
+ * was swapped accordingly. See docs/contracts/tag-data-model.md.
  *
  * Resolution model:
  * - Lazy: built on first access, cached on the store.

package/core/src/tag-schemas.ts

@@ -4,7 +4,7 @@
  * Each tag row carries: human-readable description, indexed metadata field
  * declarations (`fields`), typed-link relationship declarations
  * (`relationships`), and the hierarchy parent list (`parent_names`).
- * See parachute-patterns/patterns/tag-data-model.md.
+ * See docs/contracts/tag-data-model.md.
  *
  * This module retains the historical `tag-schemas` filename and exports
  * (`TagSchema`, `listTagSchemas`, `getTagSchema`, `upsertTagSchema`,
@@ -51,7 +51,7 @@ export interface TagFieldSchema {
  * `{ target_tag, cardinality }` declaration — but `relationships` is now an
  * opaque vocabulary map (see `TagRelationshipMap` / `validateRelationships`),
  * so this is one valid value shape among many, not a required one.
- * See patterns/tag-data-model.md §Relationships.
+ * See docs/contracts/tag-data-model.md §Relationships.
  */
 export type TagRelCardinality = "one" | "optional" | "many" | "many-required";
 

package/core/src/types.ts

@@ -406,7 +406,7 @@ export interface Store {
 
   // Tag records — full v14 identity row (description + fields + typed
   // relationships + parent_names + timestamps). See
-  // parachute-patterns/patterns/tag-data-model.md.
+  // docs/contracts/tag-data-model.md.
   listTagRecords(): Promise<TagRecord[]>;
   getTagRecord(tag: string): Promise<TagRecord | null>;
   /**

package/package.json

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

package/src/admin-spa.ts

@@ -8,7 +8,8 @@
  *
  * Per-vault mount (vault#252): the SPA lives under `/vault/<name>/admin/*`
  * rather than the origin-rooted `/admin/*` it shipped with. The hub only
- * proxies `/vault/<name>/*` paths (per parachute-patterns/module-protocol),
+ * proxies `/vault/<name>/*` paths (per the module protocol —
+ * https://github.com/ParachuteComputer/parachute-hub/blob/main/docs/contracts/module-protocol.md),
  * so an origin-rooted SPA is unreachable through the hub. Asset URLs are
  * relative (Vite `base: "./"`), so the same bundle works at any mount
  * point — no rebuild per vault.

package/src/auth.ts

@@ -123,7 +123,7 @@ export interface AuthResult {
    * Tag-allowlist (root tag names) for tag-scoped tokens. NULL = unscoped
    * (current full-vault behavior). Hub-issued JWTs and legacy YAML keys
    * always have null — tag scoping is a per-token vault-DB attribute, not
-   * an OAuth-claim concern. See patterns/tag-scoped-tokens.md.
+   * an OAuth-claim concern. See docs/contracts/tag-scoped-tokens.md.
    */
   scoped_tags: string[] | null;
   /**

package/src/export-watch.ts

@@ -10,7 +10,7 @@
  * cursor captured at the *start* of the previous cycle. Vault writes are
  * HTTP-mediated and don't surface to filesystem watchers (the bun:sqlite DB
  * is opaque), so polling on `updated_at >= cursor` is the simplest robust
- * detection. See `parachute-patterns/cookbook/vault-portable-export.md`.
+ * detection. See `docs/contracts/vault-portable-export.md`.
  */
 
 import { ensureGitAvailable } from "./git-preflight.ts";

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/routes.ts

@@ -2089,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
@@ -2114,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;
     };
@@ -2211,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(

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

@@ -856,7 +856,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

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 {