@openparachute/vault 0.7.0-rc.9 → 0.7.1

package/src/aggregate-routes.test.ts

@@ -0,0 +1,230 @@
+/**
+ * REST face of aggregation / rollup queries (top new-feature ask from a UX
+ * round) — `GET /notes?aggregate[group_by]=…&aggregate[op]=…&aggregate[field]=…`.
+ *
+ * Core-level SQL correctness (count/sum semantics, group_by "tag", NULL
+ * groups, the FIELD_NOT_INDEXED / INVALID_QUERY error contract) is pinned
+ * in `core/src/aggregate.test.ts`; this suite covers the HTTP wiring: param
+ * parsing, 400s, the response shape, and — the part that can't be tested at
+ * the core layer since core stays scope-unaware — that a tag-scoped caller's
+ * rollup is computed only over notes it can see (no out-of-scope leakage,
+ * and no undercounting of in-scope notes). Fully sandboxed — in-memory
+ * SQLite, no daemon.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunStore } from "./vault-store.ts";
+import { handleNotes, type TagScopeCtx } from "./routes.ts";
+
+let db: Database;
+let store: BunStore;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new BunStore(db);
+});
+
+afterEach(() => {
+  db.close();
+});
+
+const BASE = "http://localhost/api";
+const NO_SCOPE: TagScopeCtx = { allowed: null, raw: null };
+
+function get(path: string, tagScope: TagScopeCtx = NO_SCOPE): Promise<Response> {
+  return handleNotes(new Request(`${BASE}/notes${path}`, { method: "GET" }), store, "", undefined, tagScope);
+}
+
+describe("REST GET /notes — aggregate: count by an indexed enum field", () => {
+  it("returns [{group, value}] rows", async () => {
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    await store.createNote("a", { tags: ["task"], metadata: { status: "open" } });
+    await store.createNote("b", { tags: ["task"], metadata: { status: "open" } });
+    await store.createNote("c", { tags: ["task"], metadata: { status: "done" } });
+
+    const res = await get("?aggregate[group_by]=status&aggregate[op]=count");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const byGroup = Object.fromEntries(body.map((r: any) => [r.group, r.value]));
+    expect(byGroup).toEqual({ open: 2, done: 1 });
+  });
+});
+
+describe("REST GET /notes — aggregate: sum a numeric field", () => {
+  it("sums per group", async () => {
+    await store.upsertTagRecord("expense", {
+      fields: {
+        category: { type: "string", indexed: true },
+        amount: { type: "integer", indexed: true },
+      },
+    });
+    await store.createNote("a", { tags: ["expense"], metadata: { category: "food", amount: 10 } });
+    await store.createNote("b", { tags: ["expense"], metadata: { category: "food", amount: 25 } });
+    await store.createNote("c", { tags: ["expense"], metadata: { category: "travel", amount: 100 } });
+
+    const res = await get("?aggregate[group_by]=category&aggregate[op]=sum&aggregate[field]=amount");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const byGroup = Object.fromEntries(body.map((r: any) => [r.group, r.value]));
+    expect(byGroup).toEqual({ food: 35, travel: 100 });
+  });
+});
+
+describe("REST GET /notes — aggregate respects a prefilter", () => {
+  it("a tag= prefilter narrows the input set before aggregating", async () => {
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    await store.createNote("a", { tags: ["task", "work"], metadata: { status: "open" } });
+    await store.createNote("b", { tags: ["task", "personal"], metadata: { status: "open" } });
+    await store.createNote("c", { tags: ["task", "work"], metadata: { status: "done" } });
+
+    const res = await get("?tag=work&aggregate[group_by]=status&aggregate[op]=count");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const byGroup = Object.fromEntries(body.map((r: any) => [r.group, r.value]));
+    expect(byGroup).toEqual({ open: 1, done: 1 });
+  });
+
+  it("a meta[field][op] prefilter narrows the input set before aggregating", async () => {
+    await store.upsertTagRecord("task", {
+      fields: {
+        status: { type: "string", indexed: true },
+        priority: { type: "string", indexed: true },
+      },
+    });
+    await store.createNote("a", { tags: ["task"], metadata: { status: "open", priority: "high" } });
+    await store.createNote("b", { tags: ["task"], metadata: { status: "open", priority: "low" } });
+    await store.createNote("c", { tags: ["task"], metadata: { status: "done", priority: "high" } });
+
+    const res = await get("?meta[priority][eq]=high&aggregate[group_by]=status&aggregate[op]=count");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const byGroup = Object.fromEntries(body.map((r: any) => [r.group, r.value]));
+    expect(byGroup).toEqual({ open: 1, done: 1 });
+  });
+});
+
+describe("REST GET /notes — aggregate errors", () => {
+  it("400s on a non-indexed group_by (FIELD_NOT_INDEXED)", async () => {
+    await store.createNote("a", { metadata: { status: "open" } });
+    const res = await get("?aggregate[group_by]=status&aggregate[op]=count");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.code).toBe("FIELD_NOT_INDEXED");
+  });
+
+  it("400s when op is \"sum\" without a field", async () => {
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    const res = await get("?aggregate[group_by]=status&aggregate[op]=sum");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.field).toBe("aggregate.field");
+  });
+
+  it("400s on an unrecognized op", async () => {
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    const res = await get("?aggregate[group_by]=status&aggregate[op]=average");
+    expect(res.status).toBe(400);
+  });
+
+  it("400s when group_by is present but op is missing", async () => {
+    const res = await get("?aggregate[group_by]=status");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.field).toBe("aggregate");
+  });
+
+  it("400s when aggregate is combined with cursor", async () => {
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    const res = await get("?aggregate[group_by]=status&aggregate[op]=count&cursor=");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.field).toBe("aggregate");
+  });
+
+  it("400s when aggregate is combined with near", async () => {
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    const anchor = await store.createNote("anchor", { tags: ["task"], metadata: { status: "open" } });
+    const res = await get(`?aggregate[group_by]=status&aggregate[op]=count&near[note_id]=${anchor.id}`);
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.field).toBe("aggregate");
+  });
+});
+
+describe("REST GET /notes — aggregate: group_by \"tag\"", () => {
+  it("counts by tag membership", async () => {
+    await store.createNote("a", { tags: ["work", "urgent"] });
+    await store.createNote("b", { tags: ["work"] });
+    await store.createNote("c", { tags: ["personal"] });
+
+    const res = await get("?aggregate[group_by]=tag&aggregate[op]=count");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const byGroup = Object.fromEntries(body.map((r: any) => [r.group, r.value]));
+    expect(byGroup).toEqual({ work: 2, urgent: 1, personal: 1 });
+  });
+});
+
+describe("REST GET /notes — aggregate: tag-scope respected (no out-of-scope leakage)", () => {
+  it("counts by an indexed field ONLY over notes the token can see", async () => {
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    // Two in-scope (#work) notes, two out-of-scope (#personal) notes — all
+    // sharing the SAME status values, so a leak would silently inflate the
+    // in-scope counts rather than surfacing as an obviously-wrong shape.
+    await store.createNote("a", { tags: ["task", "work"], metadata: { status: "open" } });
+    await store.createNote("b", { tags: ["task", "work"], metadata: { status: "done" } });
+    await store.createNote("c", { tags: ["task", "personal"], metadata: { status: "open" } });
+    await store.createNote("d", { tags: ["task", "personal"], metadata: { status: "open" } });
+
+    const scoped: TagScopeCtx = { allowed: new Set(["work"]), raw: ["work"] };
+    const res = await get("?aggregate[group_by]=status&aggregate[op]=count", scoped);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const byGroup = Object.fromEntries(body.map((r: any) => [r.group, r.value]));
+    // Only the two #work notes — the #personal "open" pair must not leak
+    // into (or inflate) the "open" group.
+    expect(byGroup).toEqual({ open: 1, done: 1 });
+  });
+
+  it("group_by \"tag\" never surfaces an out-of-scope tag name — including an out-of-scope CO-TAG on an otherwise-visible note", async () => {
+    // Note "a" is visible (carries "work"), but ALSO carries "urgent" —
+    // an out-of-scope co-tag. Narrowing which NOTES count isn't enough:
+    // "urgent" must not surface as a group just because its note is
+    // visible via a different tag.
+    await store.createNote("a", { tags: ["work", "urgent"] });
+    await store.createNote("b", { tags: ["personal", "secret-project"] });
+
+    const scoped: TagScopeCtx = { allowed: new Set(["work"]), raw: ["work"] };
+    const res = await get("?aggregate[group_by]=tag&aggregate[op]=count", scoped);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const groups = body.map((r: any) => r.group);
+    expect(groups).toEqual(["work"]);
+    expect(groups).not.toContain("urgent");
+    expect(groups).not.toContain("personal");
+    expect(groups).not.toContain("secret-project");
+  });
+
+  it("an out-of-scope token aggregating over a filter that matches NO visible notes returns an empty rollup, not an error", async () => {
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    await store.createNote("a", { tags: ["task", "personal"], metadata: { status: "open" } });
+
+    const scoped: TagScopeCtx = { allowed: new Set(["work"]), raw: ["work"] };
+    const res = await get("?aggregate[group_by]=status&aggregate[op]=count", scoped);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body).toEqual([]);
+  });
+
+  it("an unscoped token sees the full rollup (regression check against the scoped path above)", async () => {
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    await store.createNote("a", { tags: ["task", "work"], metadata: { status: "open" } });
+    await store.createNote("b", { tags: ["task", "personal"], metadata: { status: "open" } });
+
+    const res = await get("?aggregate[group_by]=status&aggregate[op]=count");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const byGroup = Object.fromEntries(body.map((r: any) => [r.group, r.value]));
+    expect(byGroup).toEqual({ open: 2 });
+  });
+});

package/src/contract-errors.test.ts

@@ -315,7 +315,7 @@ describe("contract: error taxonomy — #554 (flipped from todo)", () => {
     expect(record?.fields ?? null).toBeFalsy();
   });
 
-  // Positive control — every one of the six recognized types (indexable or
+  // Positive control — every one of the seven recognized types (indexable or
   // not) is accepted without complaint.
   it("REST PUT /api/tags/:name accepts every recognized field type", async () => {
     const req = new Request("http://localhost/api/tags/widget", {
@@ -328,6 +328,7 @@ describe("contract: error taxonomy — #554 (flipped from todo)", () => {
           d: { type: "boolean" },
           e: { type: "array" },
           f: { type: "object" },
+          g: { type: "reference" },
         },
       }),
     });

package/src/contract-search.test.ts

@@ -377,6 +377,23 @@ describe("contract: search — recall + ranking legibility (WS2B/C, #551, schema
     expect(w.did_you_mean).toBe("vasquez");
   });
 
+  it("did_you_mean suggests a real surface word, not a porter stem (vault#570)", async () => {
+    // "cactus" is porter-stemmed to "cactu" in notes_fts_vocab — the exact
+    // fragment cited as a live bug in issue #570. A close-but-wrong query
+    // must resolve back to the dictionary word a user actually typed
+    // ("cactus"), not the truncated stem.
+    await store.createNote("A desert cactus stores water efficiently.");
+    const res = await search("search=cactuz");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    const w = warnings!.find((x: any) => x.code === "search_did_you_mean");
+    expect(w).toBeDefined();
+    expect(w.did_you_mean).toBe("cactus");
+  });
+
   it("a genuinely zero-result search with NO close vocabulary match carries no did_you_mean warning", async () => {
     await store.createNote(NOTES.bothWords);
     const res = await search("search=zzzznonexistentword");

package/src/mcp-link-warnings-scope.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Tag-scope interaction with create-note/update-note's `unresolved_link` /
+ * `ambiguous_link` warnings (vault#555, vault#570).
+ *
+ * `applyTagScopeWrappers`'s `query-notes` wrapper (src/mcp-tools.ts) DROPS
+ * its `warnings` array for a tag-scoped session — `unknown_tag`/
+ * `did_you_mean`/`search_did_you_mean` are computed against the FULL
+ * vault-wide tag catalog / FTS5 vocabulary, so surfacing them to a scoped
+ * caller would leak an out-of-scope tag's/note's existence (see
+ * docs/HTTP_API.md's "Tag-scoped tokens never see unknown_tag/did_you_mean
+ * or search_did_you_mean" paragraph, and docs/contracts/tag-scoped-tokens.md).
+ *
+ * `create-note`/`update-note`'s link warnings are a DIFFERENT case: they
+ * describe the CALLER'S OWN note's own outgoing link, named by the caller —
+ * not a vault-wide vocabulary scan the caller wouldn't otherwise see. The
+ * existing `unresolved_link` warning (structured `links`, vault#555) was
+ * never gated by `applyTagScopeWrappers`'s `create-note`/`update-note`
+ * wrappers (see `wrapReadTool(tools, "create-note", ...)` /
+ * `"update-note"` in src/mcp-tools.ts — neither calls `scrubNoteLinks` or
+ * strips `.warnings`), and docs/HTTP_API.md's "never see" list names only
+ * the vault-wide-vocabulary warnings above, NOT `unresolved_link`.
+ *
+ * This test locks in that vault#570's new content-wikilink `unresolved_link`
+ * and the new `ambiguous_link` warning (both content and structured) follow
+ * that SAME existing pattern — present under a tag-scoped session, exactly
+ * as they are unscoped — rather than silently introducing a NEW special
+ * case one way or the other.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { writeVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import type { AuthResult } from "./auth.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-link-warnings-scope-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+});
+
+afterEach(() => {
+  clearVaultStoreCache();
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVault(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  getVaultStore(name);
+}
+
+function authFor(vaultName: string, scopedTags: string[] | null): AuthResult {
+  return {
+    permission: "full",
+    scopes: [`vault:${vaultName}:read`, `vault:${vaultName}:write`],
+    legacyDerived: false,
+    scoped_tags: scopedTags,
+    vault_name: null,
+    caller_jti: null,
+    actor: "test-user",
+    via: "api",
+  };
+}
+
+function toolsFor(vaultName: string, scopedTags: string[] | null) {
+  return generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags));
+}
+
+describe("create-note/update-note link warnings under a tag-scoped session (vault#570)", () => {
+  test("scoped create-note: content [[wikilink]] to a missing target still warns (unresolved_link) — same as unscoped", async () => {
+    seedVault("journal");
+    const tools = toolsFor("journal", ["health"]);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+
+    const result = (await createNote.execute({
+      content: "See [[Missing Health Note]].",
+      tags: ["health"],
+    })) as any;
+
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings[0].code).toBe("unresolved_link");
+    expect(result.warnings[0].target).toBe("Missing Health Note");
+  });
+
+  test("scoped create-note: content [[wikilink]] to an ambiguous target still warns (ambiguous_link), no edge — same as unscoped", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("A", { path: "Folder1/ScopedDup", tags: ["health"] });
+    await store.createNote("B", { path: "Folder2/ScopedDup", tags: ["health"] });
+
+    const tools = toolsFor("journal", ["health"]);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const result = (await createNote.execute({
+      content: "See [[ScopedDup]].",
+      tags: ["health"],
+    })) as any;
+
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings[0].code).toBe("ambiguous_link");
+    expect(result.warnings[0].candidate_count).toBe(2);
+    expect(await store.getLinks(result.id, { direction: "outbound" })).toHaveLength(0);
+  });
+
+  test("scoped update-note: content update introducing a [[wikilink]] to a missing target still warns", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    const note = await store.createNote("plain", { path: "ScopedUpdatable", tags: ["health"] });
+
+    const tools = toolsFor("journal", ["health"]);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = (await updateNote.execute({
+      id: note.id,
+      content: "now references [[Still Missing Scoped]]",
+      force: true,
+    })) as any;
+
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings[0].code).toBe("unresolved_link");
+    expect(result.warnings[0].target).toBe("Still Missing Scoped");
+  });
+
+  test("unscoped session sees the identical warning shape (parity check)", async () => {
+    seedVault("journal");
+    const tools = toolsFor("journal", null);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+
+    const result = (await createNote.execute({
+      content: "See [[Missing Health Note]].",
+    })) as any;
+
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings[0].code).toBe("unresolved_link");
+    expect(result.warnings[0].target).toBe("Missing Health Note");
+  });
+});

package/src/mcp-query-notes-aggregate-scope.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Tag-scope × `query-notes` `aggregate` mode (top new-feature ask from a UX
+ * round).
+ *
+ * A rollup response is `[{group, value}]` — no per-note `.tags` to post-hoc
+ * filter (`noteWithinTagScope`, `src/tag-scope.ts`), unlike every other
+ * `query-notes` shape. So `applyTagScopeWrappers`'s generic array-filter
+ * (`src/mcp-tools.ts`) is skipped for aggregate requests, and scope is
+ * instead enforced BEFORE aggregating via the `aggregateVisibility`
+ * predicate wired in `generateScopedMcpTools`: fetch every note the other
+ * filters match, narrow to the token's allowlist, THEN aggregate over just
+ * that visible id set (see `core/src/mcp.ts`'s aggregate branch). This
+ * suite is the self-verifying test for that path — mirrors the harness
+ * `src/mcp-query-notes-search-scope.test.ts` uses for the equivalent search
+ * × scope concern.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { writeVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import type { AuthResult } from "./auth.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-aggregate-scope-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+});
+
+afterEach(() => {
+  clearVaultStoreCache();
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVault(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  getVaultStore(name);
+}
+
+function authFor(vaultName: string, scopedTags: string[] | null): AuthResult {
+  return {
+    permission: "full",
+    scopes: [`vault:${vaultName}:read`, `vault:${vaultName}:write`],
+    legacyDerived: false,
+    scoped_tags: scopedTags,
+    vault_name: null,
+    caller_jti: null,
+    actor: "test-user",
+    via: "api",
+  };
+}
+
+async function queryNotesTool(vaultName: string, scopedTags: string[] | null) {
+  const tools = generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags));
+  return tools.find((t) => t.name === "query-notes")!;
+}
+
+function byGroup(result: unknown): Record<string, number> {
+  expect(Array.isArray(result)).toBe(true);
+  return Object.fromEntries((result as any[]).map((r) => [String(r.group), r.value]));
+}
+
+describe("MCP query-notes aggregate × tag-scope — indexed-field group_by", () => {
+  test("count by an indexed field is computed ONLY over notes the scoped token can see", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+
+    // Same status values on both sides of the scope boundary, so a leak
+    // would silently inflate the in-scope counts rather than producing an
+    // obviously-wrong shape.
+    await store.createNote("in-scope open 1", { tags: ["task", "health"], metadata: { status: "open" } });
+    await store.createNote("in-scope done", { tags: ["task", "health"], metadata: { status: "done" } });
+    await store.createNote("out-of-scope open 1", { tags: ["task", "work"], metadata: { status: "open" } });
+    await store.createNote("out-of-scope open 2", { tags: ["task", "work"], metadata: { status: "open" } });
+
+    const scopedTool = await queryNotesTool("journal", ["health"]);
+    const result = await scopedTool.execute({ aggregate: { group_by: "status", op: "count" } });
+    expect(byGroup(result)).toEqual({ open: 1, done: 1 });
+  });
+
+  test("sum of an indexed numeric field is computed ONLY over notes the scoped token can see", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("expense", {
+      fields: {
+        category: { type: "string", indexed: true },
+        amount: { type: "integer", indexed: true },
+      },
+    });
+    await store.createNote("in-scope", { tags: ["expense", "health"], metadata: { category: "food", amount: 10 } });
+    await store.createNote("out-of-scope", { tags: ["expense", "work"], metadata: { category: "food", amount: 1000 } });
+
+    const scopedTool = await queryNotesTool("journal", ["health"]);
+    const result = await scopedTool.execute({
+      aggregate: { group_by: "category", op: "sum", field: "amount" },
+    });
+    expect(byGroup(result)).toEqual({ food: 10 });
+  });
+
+  test("unscoped session sees the full rollup across both sides (control)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    await store.createNote("a", { tags: ["task", "health"], metadata: { status: "open" } });
+    await store.createNote("b", { tags: ["task", "work"], metadata: { status: "open" } });
+
+    const unscopedTool = await queryNotesTool("journal", null);
+    const result = await unscopedTool.execute({ aggregate: { group_by: "status", op: "count" } });
+    expect(byGroup(result)).toEqual({ open: 2 });
+  });
+
+  test("a scoped token with no visible matches gets an empty rollup, not an error or a leak", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });
+    await store.createNote("out-of-scope only", { tags: ["task", "work"], metadata: { status: "open" } });
+
+    const scopedTool = await queryNotesTool("journal", ["health"]);
+    const result = await scopedTool.execute({ aggregate: { group_by: "status", op: "count" } });
+    expect(result).toEqual([]);
+  });
+});
+
+describe("MCP query-notes aggregate × tag-scope — group_by \"tag\"", () => {
+  test("an out-of-scope tag name never appears as a group, even on a co-tagged in-scope note", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    // This note IS in scope (carries "health"), but also carries the
+    // out-of-scope tag "secret-project" — the rollup must not surface that
+    // second tag as a group just because the note itself is visible.
+    await store.createNote("co-tagged", { tags: ["health", "secret-project"] });
+    await store.createNote("out-of-scope only", { tags: ["work"] });
+
+    const scopedTool = await queryNotesTool("journal", ["health"]);
+    const result = await scopedTool.execute({ aggregate: { group_by: "tag", op: "count" } });
+    const groups = (result as any[]).map((r) => r.group);
+    expect(groups).toContain("health");
+    expect(groups).not.toContain("secret-project");
+    expect(groups).not.toContain("work");
+    // Belt-and-suspenders: the out-of-scope tag name must not appear ANYWHERE
+    // in the serialized response.
+    expect(JSON.stringify(result)).not.toContain("secret-project");
+    expect(JSON.stringify(result)).not.toContain("\"work\"");
+  });
+});
+
+describe("MCP query-notes aggregate — mutual exclusivity with search/near/cursor", () => {
+  test("aggregate + search is rejected", async () => {
+    seedVault("journal");
+    const tool = await queryNotesTool("journal", null);
+    await expect(
+      tool.execute({ search: "x", aggregate: { group_by: "tag", op: "count" } }),
+    ).rejects.toThrow();
+  });
+
+  test("aggregate + cursor is rejected", async () => {
+    seedVault("journal");
+    const tool = await queryNotesTool("journal", null);
+    await expect(
+      tool.execute({ cursor: "", aggregate: { group_by: "tag", op: "count" } }),
+    ).rejects.toThrow();
+  });
+
+  test("aggregate + near is rejected", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    const anchor = await store.createNote("anchor");
+    const tool = await queryNotesTool("journal", null);
+    await expect(
+      tool.execute({ near: { note_id: anchor.id }, aggregate: { group_by: "tag", op: "count" } }),
+    ).rejects.toThrow();
+  });
+});