@openparachute/vault 0.5.1 → 0.5.2-rc.2

package/core/src/core.test.ts

@@ -972,6 +972,33 @@ describe("vault stats", async () => {
     expect(stats.topTags).toEqual([]);
     expect(stats.tagCount).toBe(0);
     expect(stats.linkCount).toBe(0);
+    expect(stats.contentBytes).toBe(0);
+  });
+
+  it("contentBytes sums ASCII content as raw byte length", async () => {
+    // "hello" = 5 bytes, "world!" = 6 bytes — for pure ASCII, bytes == chars.
+    await store.createNote("hello");
+    await store.createNote("world!");
+    const stats = await store.getVaultStats();
+    expect(stats.contentBytes).toBe(11);
+  });
+
+  it("contentBytes counts UTF-8 BYTES, not characters (multibyte)", async () => {
+    // The whole point of CAST(content AS BLOB): SQLite's bare LENGTH() would
+    // return the CHARACTER count, undercounting multibyte content.
+    //   - "é"  is U+00E9 → 2 bytes in UTF-8 (1 char)
+    //   - "你好" is 2 CJK chars → 6 bytes (3 bytes each)
+    //   - "😀" is 1 grapheme / 2 UTF-16 code units → 4 bytes in UTF-8
+    const content = "é你好😀";
+    const expectedBytes = Buffer.byteLength(content, "utf8"); // 2 + 6 + 4 = 12
+    expect(expectedBytes).toBe(12);
+    // And it's strictly MORE than the JS character count — proves we're not
+    // accidentally counting chars.
+    expect(expectedBytes).toBeGreaterThan([...content].length);
+
+    await store.createNote(content);
+    const stats = await store.getVaultStats();
+    expect(stats.contentBytes).toBe(expectedBytes);
   });
 
   it("counts total notes and tagCount", async () => {
@@ -1041,6 +1068,7 @@ describe("vault stats", async () => {
     expect(stats).toHaveProperty("topTags");
     expect(stats).toHaveProperty("tagCount");
     expect(stats).toHaveProperty("linkCount");
+    expect(stats).toHaveProperty("contentBytes");
   });
 
   it("counts resolved wikilinks in linkCount", async () => {
@@ -2131,6 +2159,113 @@ describe("MCP tools", async () => {
     expect(await store.getLinks("a", { direction: "outbound" })).toHaveLength(0);
   });
 
+  // vault feedback #8 — echo hydrated links on the update response when the
+  // request mutated links OR `include_links` is set, so callers don't re-query.
+  it("update-note echoes hydrated links when the update mutates links", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b", path: "beta", tags: ["t"] });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      id: "a",
+      links: { add: [{ target: "b", relationship: "mentions" }] },
+      force: true,
+    }) as any;
+    expect(Array.isArray(result.links)).toBe(true);
+    expect(result.links).toHaveLength(1);
+    // Hydrated shape matches query-notes' include_links output.
+    const link = result.links[0];
+    expect(link.sourceId).toBe("a");
+    expect(link.targetId).toBe("b");
+    expect(link.relationship).toBe("mentions");
+    expect(link.targetNote.path).toBe("beta");
+    expect(link.targetNote.tags).toEqual(["t"]);
+  });
+
+  it("update-note echoes links on removal (post-removal set)", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    await store.createLink("a", "b", "mentions");
+    await store.createLink("a", "c", "mentions");
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      id: "a",
+      links: { remove: [{ target: "b", relationship: "mentions" }] },
+      force: true,
+    }) as any;
+    expect(result.links).toHaveLength(1);
+    expect(result.links[0].targetId).toBe("c");
+  });
+
+  it("update-note with include_links echoes links even without a mutation", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createLink("a", "b", "mentions");
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      id: "a",
+      content: "updated",
+      include_links: true,
+      force: true,
+    }) as any;
+    expect(result.content).toBe("updated");
+    expect(result.links).toHaveLength(1);
+    expect(result.links[0].targetId).toBe("b");
+  });
+
+  it("update-note without a link mutation or flag does NOT echo links", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createLink("a", "b", "mentions");
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({ id: "a", content: "updated", force: true }) as any;
+    expect(result.content).toBe("updated");
+    expect(result).not.toHaveProperty("links");
+  });
+
+  it("update-note batch echoes links per-item (only on the mutated/flagged item)", async () => {
+    await store.createNote("A", { id: "a" });
+    await store.createNote("B", { id: "b" });
+    await store.createNote("C", { id: "c" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      notes: [
+        // Item 0 mutates links → echoes.
+        { id: "a", links: { add: [{ target: "b", relationship: "mentions" }] }, force: true },
+        // Item 1 only edits content, no flag → no links key.
+        { id: "c", content: "C updated", force: true },
+      ],
+    }) as any[];
+    expect(result).toHaveLength(2);
+    expect(result[0].links).toHaveLength(1);
+    expect(result[0].links[0].targetId).toBe("b");
+    expect(result[1]).not.toHaveProperty("links");
+  });
+
+  it("update-note if_missing=create with include_links echoes links (no link mutation)", async () => {
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    // The created note has no links yet and the payload declares none, so the
+    // echo is driven purely by the explicit `include_links` flag — closing the
+    // create-on-missing × flag-only matrix gap. Hydrated `links` key is present
+    // (empty array), not absent.
+    const result = await updateNote.execute({
+      id: "fresh-note",
+      content: "brand new",
+      if_missing: "create",
+      include_links: true,
+    }) as any;
+    expect(result.created).toBe(true);
+    expect(result.content).toBe("brand new");
+    expect(Array.isArray(result.links)).toBe(true);
+    expect(result.links).toHaveLength(0);
+  });
+
   it("update-note removes wikilink brackets when removing wikilink-type link", async () => {
     await store.createNote("Target", { id: "target", path: "People/Alice" });
     const source = await store.createNote("See [[People/Alice]] for details", { id: "source" });
@@ -4932,43 +5067,65 @@ describe("tag record API (patterns/tag-data-model.md)", async () => {
     expect(idxZebra).toBeGreaterThan(idxAlpha);
   });
 
-  it("update-tag MCP rejects an invalid cardinality", async () => {
+  // ---- relationships is an opaque vocabulary map (vault#428) ----
+  // Vault no longer enforces the historical { target_tag, cardinality }
+  // shape. Apps (the Weaver / structural-link picker) declare a freeform
+  // vocabulary; vault stores + returns it verbatim. The old typed shape is
+  // still a valid value, so the loosening is a backwards-compatible superset.
+
+  it("update-tag MCP persists the opaque relationship-vocabulary map verbatim (vault#428)", async () => {
     const tools = generateMcpTools(store);
     const update = tools.find((t) => t.name === "update-tag")!;
-    await expect(
-      update.execute({
-        tag: "project",
-        relationships: {
-          owned_by: { target_tag: "person", cardinality: "bogus" },
-        },
-      }),
-    ).rejects.toThrow(/cardinality/);
+    const vocab = {
+      "works-on": { from: "person", to: "project" },
+      "member-of": { from: "person", to: "organization" },
+      "partner-of": { from: "person", to: "person" },
+      "based-at": { from: "project", to: "place" },
+    };
+    await update.execute({ tag: "person", relationships: vocab });
+    const r = await store.getTagRecord("person");
+    expect(r?.relationships).toEqual(vocab);
   });
 
-  it("update-tag MCP accepts every cardinality in the named vocabulary", async () => {
+  it("update-tag MCP round-trips nested arbitrary relationship values verbatim", async () => {
     const tools = generateMcpTools(store);
     const update = tools.find((t) => t.name === "update-tag")!;
-    for (const card of ["one", "optional", "many", "many-required"]) {
-      await update.execute({
-        tag: `tag-${card}`,
-        relationships: {
-          rel: { target_tag: "other", cardinality: card },
-        },
-      });
-      const r = await store.getTagRecord(`tag-${card}`);
-      expect(r?.relationships?.rel?.cardinality).toBe(card);
-    }
+    const vocab = {
+      rel: { from: "a", to: "b", note: "freeform", weight: 3, optional: true, tags: ["x", "y"] },
+    };
+    await update.execute({ tag: "thing", relationships: vocab });
+    const r = await store.getTagRecord("thing");
+    expect(r?.relationships).toEqual(vocab);
+  });
+
+  it("update-tag MCP still accepts the historical typed shape (backwards-compat)", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-tag")!;
+    const typed = { owned_by: { target_tag: "person", cardinality: "one", description: "DRI" } };
+    await update.execute({ tag: "project", relationships: typed });
+    const r = await store.getTagRecord("project");
+    expect(r?.relationships).toEqual(typed);
+  });
+
+  it("update-tag MCP accepts what used to be rejected (no inner-shape enforcement)", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-tag")!;
+    // Formerly rejected: non-vocabulary cardinality + missing target_tag.
+    const formerlyInvalid = {
+      a: { target_tag: "person", cardinality: "bogus" },
+      b: { cardinality: "one" },
+    };
+    await update.execute({ tag: "loose", relationships: formerlyInvalid });
+    const r = await store.getTagRecord("loose");
+    expect(r?.relationships).toEqual(formerlyInvalid);
   });
 
-  it("update-tag MCP rejects a relationship missing target_tag", async () => {
+  it("update-tag MCP rejects a top-level array for relationships (must be a map)", async () => {
     const tools = generateMcpTools(store);
     const update = tools.find((t) => t.name === "update-tag")!;
     await expect(
-      update.execute({
-        tag: "project",
-        relationships: { owned_by: { cardinality: "one" } },
-      }),
-    ).rejects.toThrow(/target_tag/);
+      update.execute({ tag: "project", relationships: ["not", "a", "map"] as unknown as Record<string, unknown> }),
+    ).rejects.toThrow();
   });
 
   it("update-tag MCP sets parent_names and the hierarchy invalidates", async () => {

package/core/src/expand-visibility.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { initSchema } from "./schema.js";
+import { createNote } from "./notes.js";
+import { expandContent, type ExpandContext } from "./expand.js";
+import type { Note } from "./types.js";
+
+/**
+ * Security regression (vault security review — tag-scope confidentiality).
+ *
+ * `expandContent`'s optional `isVisible` predicate is the seam that keeps
+ * core scope-unaware while letting the server enforce tag scope during
+ * wikilink inlining. These tests pin the load-bearing invariant: when the
+ * predicate rejects a target, the wikilink is left UNRESOLVED — byte-for-byte
+ * identical to a genuinely-missing target, so the response can't reveal that
+ * the out-of-scope note exists. They MUST fail if the predicate is removed.
+ */
+
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  initSchema(db);
+});
+
+function ctx(over: Partial<ExpandContext> = {}): ExpandContext {
+  return { db, mode: "full", expanded: new Set<string>(), ...over };
+}
+
+describe("expandContent isVisible predicate (tag-scope confidentiality)", () => {
+  it("inlines an in-scope target's content when no predicate is set (baseline)", () => {
+    createNote(db, "SECRET BODY", { path: "Secret", tags: ["personal"] });
+    const out = expandContent("see [[Secret]]", ctx(), 1);
+    expect(out).toContain("SECRET BODY");
+  });
+
+  it("leaves an out-of-scope wikilink unresolved — no content inlined", () => {
+    createNote(db, "SECRET BODY", { path: "Secret", tags: ["personal"] });
+    // Predicate: only #work notes are visible. The target is #personal.
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    const out = expandContent("see [[Secret]]", ctx({ isVisible }), 1);
+    expect(out).not.toContain("SECRET BODY");
+    // The wikilink stays literal.
+    expect(out).toBe("see [[Secret]]");
+  });
+
+  it("out-of-scope target is INDISTINGUISHABLE from a missing target", () => {
+    // Case A: target exists but is out of scope.
+    createNote(db, "SECRET BODY", { path: "Secret", tags: ["personal"] });
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    const outOfScope = expandContent("see [[Secret]]", ctx({ isVisible }), 1);
+
+    // Case B: target genuinely does not exist (fresh db, same predicate).
+    const db2 = new Database(":memory:");
+    initSchema(db2);
+    const missing = expandContent("see [[Secret]]", { db: db2, mode: "full", expanded: new Set(), isVisible }, 1);
+
+    // Byte-identical output → existence is not leaked.
+    expect(outOfScope).toBe(missing);
+    expect(outOfScope).toBe("see [[Secret]]");
+  });
+
+  it("a second reference to an out-of-scope note does NOT render `(expanded above)`", () => {
+    // Pins that an out-of-scope note never enters the `expanded` set — else a
+    // repeat reference would render `(expanded above)` and leak existence via
+    // a different output than a missing target.
+    createNote(db, "SECRET BODY", { path: "Secret", tags: ["personal"] });
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    const out = expandContent("[[Secret]] and again [[Secret]]", ctx({ isVisible }), 1);
+    expect(out).toBe("[[Secret]] and again [[Secret]]");
+    expect(out).not.toContain("expanded above");
+    expect(out).not.toContain("SECRET BODY");
+  });
+
+  it("multi-hop (depth>1) does not leak out-of-scope content at any depth", () => {
+    // in-scope #work note → wikilinks an out-of-scope #personal note.
+    createNote(db, "DEEP SECRET", { path: "Deep", tags: ["personal"] });
+    createNote(db, "intro [[Deep]]", { path: "Mid", tags: ["work"] });
+    createNote(db, "top [[Mid]]", { path: "Top", tags: ["work"] });
+
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    // Depth 3 — would walk Top → Mid → Deep without the predicate.
+    const out = expandContent("[[Top]]", ctx({ isVisible }), 3);
+    // The in-scope Mid IS inlined; the out-of-scope Deep is NOT.
+    expect(out).toContain("intro");
+    expect(out).not.toContain("DEEP SECRET");
+    // The Deep wikilink stays literal inside Mid's inlined content.
+    expect(out).toContain("[[Deep]]");
+  });
+
+  it("predicate is also honored in summary mode", () => {
+    createNote(db, "x", {
+      path: "Secret",
+      tags: ["personal"],
+      metadata: { summary: "SECRET SUMMARY" },
+    });
+    const isVisible = (n: Note) => (n.tags ?? []).includes("work");
+    const out = expandContent("see [[Secret]]", ctx({ mode: "summary", isVisible }), 1);
+    expect(out).not.toContain("SECRET SUMMARY");
+    expect(out).toBe("see [[Secret]]");
+  });
+});

package/core/src/expand.ts

@@ -22,6 +22,22 @@ export interface ExpandContext {
   mode: ExpandMode;
   /** Note IDs already expanded in this query. Shared across all expansions. */
   expanded: Set<string>;
+  /**
+   * Optional visibility predicate (tag-scope confidentiality, vault security
+   * review). When set and it returns `false` for a resolved target note, the
+   * wikilink is left UNRESOLVED — byte-identical to the not-found/unresolved
+   * branch, so an out-of-scope target is indistinguishable from a missing one
+   * (we never reveal existence differently across the scope boundary).
+   *
+   * Core stays scope-unaware: the server constructs this predicate from its
+   * tag-scope machinery and injects it; core only ever *calls* it. When
+   * unset (every unscoped caller), expansion behaves exactly as before.
+   *
+   * Applied at every hop — multi-hop (`expand_depth > 1`) expansion runs the
+   * predicate on each resolved target before inlining, so a deep chain can't
+   * tunnel out-of-scope content through an in-scope intermediary.
+   */
+  isVisible?: (note: Note) => boolean;
 }
 
 /**
@@ -62,14 +78,26 @@ export function expandContent(
     const noteId = resolveWikilink(ctx.db, target);
     if (!noteId) return match; // unresolved or ambiguous — leave as-is
 
+    // Resolve the target BEFORE the dedup check so the visibility gate can run
+    // first — an out-of-scope target must never enter `expanded` (otherwise a
+    // second reference to it would render `(expanded above)` and leak its
+    // existence via a different output than a genuinely-missing target).
+    const note = noteOps.getNote(ctx.db, noteId);
+    if (!note) return match; // shouldn't happen, but be safe
+
+    // Tag-scope confidentiality (vault security review): if a visibility
+    // predicate is installed and the resolved target is out of scope, leave
+    // the wikilink UNRESOLVED — byte-identical to the not-found / unresolved
+    // branches above. The out-of-scope case must be indistinguishable from a
+    // missing target so the response can't leak the target's existence. Runs
+    // at every hop, so multi-hop expansion can't tunnel out-of-scope content.
+    if (ctx.isVisible && !ctx.isVisible(note)) return match;
+
     if (ctx.expanded.has(noteId)) {
       return `${match} (expanded above)`;
     }
     ctx.expanded.add(noteId);
 
-    const note = noteOps.getNote(ctx.db, noteId);
-    if (!note) return match; // shouldn't happen, but be safe
-
     if (ctx.mode === "summary") {
       // Summary mode doesn't recurse: depth > 1 has no additional effect.
       return renderSummary(note);