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

package/src/routing.ts

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

package/src/server.ts

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

package/src/subscriptions.ts

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

package/src/vault-create.test.ts

@@ -358,11 +358,11 @@ describe("vault create — services.json registration (#208)", () => {
  * Default-pack seeding on create (originally demo-prep Workstream A — A1/A3;
  * reshaped for named seed packs).
  *
- * A freshly-created vault must contain the `welcome` pack (three-note welcome
- * web + the one capture tag Notes requires) and the `getting-started` guide — and
- * NOT the `surface-starter` pack, which is opt-in via `add-pack` (ratified
- * 2026-07-02). Idempotent + best-effort: the seed never fails a create and
- * never clobbers an edited note.
+ * A freshly-created vault must contain the `welcome` pack (the five-guide
+ * welcome ring + the capture/guide/pinned tags) and the `getting-started`
+ * guide — and NOT the `surface-starter` pack, which is opt-in via `add-pack`
+ * (ratified 2026-07-02). Idempotent + best-effort: the seed never fails a
+ * create and never clobbers an edited note.
  */
 describe("vault create — default pack seeding (welcome + getting-started)", () => {
   /** Read all (path, content) rows from a created vault's SQLite DB. */
@@ -400,23 +400,28 @@ describe("vault create — default pack seeding (welcome + getting-started)", ()
     const notes = readNotes("guided");
     const gs = notes.find((n) => n.path === "Getting Started");
     const welcome = notes.find((n) => n.path === "Welcome to your vault 🪂");
-    const tryLinking = notes.find((n) => n.path === "Try linking notes");
+    const captureAnything = notes.find((n) => n.path === "Capture anything");
+    const tagsGraph = notes.find((n) => n.path === "Tags and the graph");
     const connectAi = notes.find((n) => n.path === "Connect your AI");
+    const yoursToKeep = notes.find((n) => n.path === "Yours to keep");
     expect(gs).toBeDefined();
     expect(welcome).toBeDefined();
-    expect(tryLinking).toBeDefined();
+    expect(captureAnything).toBeDefined();
+    expect(tagsGraph).toBeDefined();
     expect(connectAi).toBeDefined();
+    expect(yoursToKeep).toBeDefined();
     expect(gs!.content).toContain("# Getting Started");
     // Surface Starter is out of the default seed — no note, no dangling link.
     expect(notes.find((n) => n.path === "Surface Starter")).toBeUndefined();
     expect(gs!.content).not.toContain("[[Surface Starter]]");
     expect(gs!.content).toContain("add-pack surface-starter");
 
-    // The ONE capture tag Notes requires arrives with the welcome pack —
-    // and nothing else (fresh-vault seed = 4 notes + 1 tag; the retired
+    // The capture tag Notes requires arrives with the welcome pack, alongside
+    // the guide (skill-file) + pinned tags — and nothing else (fresh-vault
+    // seed = 6 notes: the 5-guide ring + Getting Started. The retired
     // capture/text + capture/voice subtypes are no longer seeded).
-    expect(readTagNames("guided")).toEqual(["capture"]);
-    expect(notes).toHaveLength(4);
+    expect(readTagNames("guided").sort()).toEqual(["capture", "guide", "pinned"]);
+    expect(notes).toHaveLength(6);
   });
 
   test("seeding doesn't break --json stdout (notes seeded silently)", () => {

package/src/ws-server.ts

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