@openparachute/vault 0.7.3-rc.13 → 0.7.3-rc.14

package/package.json

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

@@ -98,6 +98,18 @@ describe("buildSnapshotFrames — chunking + done flag", () => {
     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);
   });
+
+  it("is shape-agnostic — frames a lean NoteIndex entry verbatim", () => {
+    // A lean subscription hands `toNoteIndex`-projected entries; the framer
+    // serializes them byte-for-byte, no content field re-added.
+    const lean = { id: "x", byteSize: 3, preview: "abc", displayTitle: "abc", tags: ["chat"], metadata: {} };
+    const frames = buildSnapshotFrames([lean as any]);
+    expect(frames.length).toBe(1);
+    const f = JSON.parse(frames[0]!);
+    expect(f.done).toBe(true);
+    expect(f.notes).toEqual([lean]);
+    expect(f.notes[0].content).toBeUndefined();
+  });
 });
 
 describe("parseClientMessage", () => {
@@ -171,6 +183,15 @@ describe("validateWsSubscribeQuery — same rejects as the SSE route (byte-ident
     const v = validateWsSubscribeQuery(new URL("http://x/vault/v/api/subscribe?tag=chat&path_prefix=meetings/"));
     expect("queryOpts" in v).toBe(true);
   });
+  it("resolves include_content — default TRUE (full), `false`/`0` → lean, `true`/`1` → full", () => {
+    const at = (q: string) =>
+      validateWsSubscribeQuery(new URL(`http://x/vault/v/api/subscribe?tag=chat${q}`)) as { includeContent: boolean };
+    expect(at("").includeContent).toBe(true); // absent → full (byte-unchanged default)
+    expect(at("&include_content=false").includeContent).toBe(false); // opt into lean
+    expect(at("&include_content=0").includeContent).toBe(false);
+    expect(at("&include_content=true").includeContent).toBe(true);
+    expect(at("&include_content=1").includeContent).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

package/src/subscriptions.ts

@@ -63,6 +63,7 @@
 import type { Note, Store } from "../core/src/types.ts";
 import type { DeletedNoteRef, HookEvent, NoteHookPayload } from "../core/src/hooks.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
+import { toNoteIndex } from "../core/src/notes.ts";
 import { getVaultNameForStore } from "./vault-store.ts";
 import { noteWithinTagScope } from "./tag-scope.ts";
 import type { LiveMatcher } from "./live-match.ts";
@@ -98,6 +99,11 @@ interface Subscription {
   /** Raw root-tag allowlist (null = unscoped) — `noteWithinTagScope` arg. */
   readonly tagScopeRaw: string[] | null;
   readonly sink: SubscriptionSink;
+  /** When true, `upsert` payloads carry the lean `NoteIndex` projection
+   *  (`toNoteIndex`) instead of the full `Note` — for a subscription that opted
+   *  into `include_content=false` (list views). `remove` is unaffected (already
+   *  a thin `{id}` ref); the initial snapshot is projected at the route. */
+  readonly lean: boolean;
   /** 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
@@ -205,6 +211,9 @@ export class SubscriptionManager {
     tagScopeRaw: string[] | null;
     sink: SubscriptionSink;
     maxBuffered?: number;
+    /** Opt into the lean `NoteIndex` upsert shape (default false = full `Note`).
+     *  Set for a list subscription that requested `include_content=false`. */
+    lean?: boolean;
     /** SSE (default true) tracks unflushed frames; WS passes false. */
     tracksFlush?: boolean;
     /** SSE (default true) counts against the per-vault manager cap; WS passes
@@ -223,6 +232,7 @@ export class SubscriptionManager {
       tagScopeAllowed: args.tagScopeAllowed,
       tagScopeRaw: args.tagScopeRaw,
       sink: args.sink,
+      lean: args.lean ?? false,
       tracksFlush: args.tracksFlush ?? true,
       countsTowardCap,
       buffered: 0,
@@ -320,7 +330,9 @@ export class SubscriptionManager {
       const matches = sub.matcher.match(note) && inScope;
 
       if (matches) {
-        this.emit(sub, "upsert", { note });
+        // A lean subscription (list view, `include_content=false`) carries the
+        // same `NoteIndex` projection REST lists return — never the full body.
+        this.emit(sub, "upsert", { note: sub.lean ? toNoteIndex(note) : 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

package/src/ws-server.ts

@@ -31,6 +31,7 @@
 
 import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
 import type { Store } from "../core/src/types.ts";
+import { toNoteIndex } from "../core/src/notes.ts";
 import type { VaultConfig } from "./config.ts";
 import { readVaultConfig } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
@@ -229,6 +230,9 @@ export function createSubscribeWsBinding(deps: SubscribeWsDeps = {}): {
       closeWs(ws, WS_CLOSE.PROTOCOL, "invalid subscription query");
       return;
     }
+    // Lean list subscriptions (`include_content=false`) ship the `NoteIndex`
+    // projection — snapshot + live upserts — instead of full note bodies.
+    const lean = !validated.includeContent;
 
     let tagScopeAllowed: Set<string> | null;
     let matcher;
@@ -247,7 +251,10 @@ export function createSubscribeWsBinding(deps: SubscribeWsDeps = {}): {
       closeWs(ws, WS_CLOSE.PROTOCOL, "snapshot query failed");
       return;
     }
-    const frames = buildSnapshotFrames(snapshotNotes);
+    // Project AFTER the tag-scope filter (which reads note.tags). `toNoteIndex`
+    // is the SAME lean shape the REST list route returns, so a client that
+    // renders REST lists renders these snapshot frames unchanged.
+    const frames = buildSnapshotFrames(lean ? snapshotNotes.map(toNoteIndex) : snapshotNotes);
 
     // --- SYNCHRONOUS from here (no await) so no write interleaves between
     //     register and the snapshot flush.
@@ -261,6 +268,7 @@ export function createSubscribeWsBinding(deps: SubscribeWsDeps = {}): {
       tagScopeAllowed,
       tagScopeRaw: auth.scoped_tags,
       sink: new WsSink(ws),
+      lean,
       tracksFlush: false,
       countsTowardCap: false,
     });

package/src/ws-subscribe.test.ts

@@ -486,3 +486,90 @@ describe("WS live-query — bad query + cap", () => {
     expect(ok.kind).toBe("upgraded");
   });
 });
+
+describe("WS live-query — lean list subscriptions (include_content=false)", () => {
+  it("ships the lean NoteIndex snapshot shape — no bodies, has preview/displayTitle/byteSize", async () => {
+    await store.createNote("# Title line\n\nbody paragraph here", { tags: ["chat"] });
+    const { server } = makeServer();
+
+    const h = connect(server.port, `/vault/${VAULT}/api/subscribe?tag=chat&include_content=false`);
+    await h.ready();
+    h.send({ type: "auth", token: "good" });
+
+    const snap = await h.readSnapshot();
+    expect(snap.notes.length).toBe(1);
+    const n = snap.notes[0];
+    // Lean shape = what REST lists return: no `content`, but the index fields.
+    expect(n.content).toBeUndefined();
+    expect(typeof n.byteSize).toBe("number");
+    expect(typeof n.preview).toBe("string");
+    expect(n.displayTitle).toBe("Title line");
+    expect(n.tags).toEqual(["chat"]);
+    h.close();
+  });
+
+  it("a default subscription still ships FULL notes (regression: note-view path unchanged)", async () => {
+    await store.createNote("full body content", { tags: ["chat"] });
+    const { server } = makeServer();
+
+    // No include_content param → full content (the byte-unchanged default).
+    const h = connect(server.port, `/vault/${VAULT}/api/subscribe?tag=chat`);
+    await h.ready();
+    h.send({ type: "auth", token: "good" });
+
+    const snap = await h.readSnapshot();
+    expect(snap.notes[0].content).toBe("full body content");
+    // Full Note carries no lean-only fields.
+    expect(snap.notes[0].byteSize).toBeUndefined();
+    expect(snap.notes[0].preview).toBeUndefined();
+    h.close();
+  });
+
+  it("emits a LEAN upsert on a matching insert", async () => {
+    const { server } = makeServer();
+    const h = connect(server.port, `/vault/${VAULT}/api/subscribe?tag=chat&include_content=false`);
+    await h.ready();
+    h.send({ type: "auth", token: "good" });
+    await h.readSnapshot();
+
+    await store.createNote("live lean note", { tags: ["chat"] });
+    const m = await h.nextMessage();
+    expect(m.type).toBe("upsert");
+    expect(m.note.content).toBeUndefined();
+    expect(m.note.displayTitle).toBe("live lean note");
+    expect(typeof m.note.byteSize).toBe("number");
+    h.close();
+  });
+
+  it("emits a LEAN upsert when a note in the set CHANGES (live-update correctness)", async () => {
+    const note = await store.createNote("before", { tags: ["chat"] });
+    const { server } = makeServer();
+    const h = connect(server.port, `/vault/${VAULT}/api/subscribe?tag=chat&include_content=false`);
+    await h.ready();
+    h.send({ type: "auth", token: "good" });
+    await h.readSnapshot();
+
+    await store.updateNote(note.id, { content: "after edit" });
+    const m = await h.nextMessage();
+    expect(m.type).toBe("upsert");
+    expect(m.note.id).toBe(note.id);
+    expect(m.note.content).toBeUndefined();
+    expect(m.note.displayTitle).toBe("after edit");
+    h.close();
+  });
+
+  it("still emits a thin remove{id} under a lean subscription", async () => {
+    const note = await store.createNote("doomed lean", { tags: ["chat"] });
+    const { server } = makeServer();
+    const h = connect(server.port, `/vault/${VAULT}/api/subscribe?tag=chat&include_content=false`);
+    await h.ready();
+    h.send({ type: "auth", token: "good" });
+    await h.readSnapshot();
+
+    await store.deleteNote(note.id);
+    const m = await h.nextMessage();
+    expect(m.type).toBe("remove");
+    expect(m.id).toBe(note.id);
+    h.close();
+  });
+});

package/src/ws-subscribe.ts

@@ -30,7 +30,7 @@
  * visible to browser JS: 4400 protocol, 4401 unauthorized/expired/revoked,
  * 4403 scope, 4408 auth-timeout.
  */
-import type { Note, QueryOpts } from "../core/src/types.ts";
+import type { Note, NoteIndex, QueryOpts } from "../core/src/types.ts";
 import { parseNotesQueryOpts } from "./routes.ts";
 import { unsupportedSubscriptionReason } from "./live-match.ts";
 import { hasScopeForVault, type VaultVerb } from "./scopes.ts";
@@ -82,9 +82,20 @@ function json(data: unknown, status = 200): Response {
  * filters can't be evaluated against a single changed note. The 400 bodies +
  * `UNSUPPORTED_SUBSCRIPTION_QUERY` code are byte-identical to the SSE route (and
  * to the cloud door) so all three agree. Returns a ready 400 Response on
- * rejection, else the parsed `QueryOpts`.
+ * rejection, else the parsed `QueryOpts` plus the resolved `includeContent`
+ * intent.
+ *
+ * `include_content` — the lean-snapshot knob. Unlike the REST list
+ * route (which defaults `include_content=false`, i.e. lean), a live subscription
+ * defaults to `true` (FULL notes) so every already-deployed subscriber — cached
+ * notes-ui bundles, surface-client — keeps receiving byte-identical full-note
+ * snapshots/upserts. A subscriber opts INTO the lean `NoteIndex` wire shape (the
+ * same projection REST lists return) by passing `include_content=false`; list
+ * views do this, the single-note view leaves it default → full. Truthiness
+ * mirrors the REST route's `parseBool` (`true`/`1` → full; anything else → lean)
+ * so the two doors read the flag identically.
  */
-export function validateWsSubscribeQuery(url: URL): { error: Response } | { queryOpts: QueryOpts } {
+export function validateWsSubscribeQuery(url: URL): { error: Response } | { queryOpts: QueryOpts; includeContent: boolean } {
   if (url.searchParams.get("search")) {
     return {
       error: json(
@@ -118,7 +129,11 @@ export function validateWsSubscribeQuery(url: URL): { error: Response } | { quer
   if (unsupported) {
     return { error: json({ error: unsupported, code: "UNSUPPORTED_SUBSCRIPTION_QUERY" }, 400) };
   }
-  return { queryOpts };
+  // Default TRUE (full) — the live protocol has always shipped full notes;
+  // a subscriber opts into the lean shape with `include_content=false`.
+  const rawIncludeContent = url.searchParams.get("include_content");
+  const includeContent = rawIncludeContent === null ? true : rawIncludeContent === "true" || rawIncludeContent === "1";
+  return { queryOpts, includeContent };
 }
 
 /** 503 body for the per-vault WS-subscription cap (mirrors the SSE 503). */
@@ -149,11 +164,15 @@ export function urlFromQuery(q: string): URL {
  * exactly once per (re)connect. The consumer concatenates `notes` across frames
  * until `done:true`, then replaces its set (the SSE self-correcting-reconnect
  * semantics). Byte-shaped identically to the cloud door's `buildSnapshotFrames`.
+ *
+ * Shape-agnostic: the framing only `JSON.stringify`s each entry, so
+ * it carries whichever note shape the caller projected — full `Note` (the
+ * default) or the lean `NoteIndex` for an `include_content=false` subscription.
  */
-export function buildSnapshotFrames(notes: Note[]): string[] {
+export function buildSnapshotFrames(notes: Array<Note | NoteIndex>): string[] {
   const frames: string[] = [];
   const enc = new TextEncoder();
-  let batch: Note[] = [];
+  let batch: Array<Note | NoteIndex> = [];
   let batchBytes = 0;
   for (const note of notes) {
     const noteBytes = enc.encode(JSON.stringify(note)).byteLength + 1; // +1 ~ comma