@openparachute/vault 0.5.3-rc.3 → 0.6.0

package/.parachute/module.json

@@ -6,10 +6,21 @@
   "port": 1940,
   "paths": ["/vault/default"],
   "health": "/vault/default/health",
-  "managementUrl": "/admin/",
-  "uiUrl": "/admin/",
+  "managementUrl": "admin/",
+  "uiUrl": "admin/",
+  "configUiUrl": "/vault/admin/",
+  "focus": "core",
+  "adminCapabilities": ["config", "credentials"],
   "startCmd": ["parachute-vault", "serve"],
   "scopes": {
     "defines": ["vault:read", "vault:write", "vault:admin"]
-  }
+  },
+  "events": [
+    { "key": "note.created", "title": "A note was created" },
+    { "key": "note.updated", "title": "A note was updated" },
+    { "key": "note.deleted", "title": "A note was deleted" }
+  ],
+  "actions": [
+    { "key": "note.create", "title": "Create a note", "inputSchema": {} }
+  ]
 }

package/core/src/mcp.ts

@@ -3,6 +3,7 @@ import type { Store, Note } from "./types.js";
 import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import { QueryError } from "./query-operators.js";
+import { TAG_EXPAND_MODES, type TagExpandMode } from "./tag-hierarchy.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -165,6 +166,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             description: "Filter by tag(s)",
           },
           tag_match: { type: "string", enum: ["any", "all"], description: "How to match multiple tags: 'any' (OR, default) or 'all' (AND)" },
+          expand: {
+            type: "string",
+            enum: ["subtypes", "namespace", "both", "exact"],
+            description: "How each `tag` expands. 'subtypes' (DEFAULT): the tag plus its declared parent_names descendants — the semantic is-a axis (e.g. tag:entity also matches person/work). 'namespace': the tag plus everything filed under it by NAME (tag:entity also matches entity/archived) — the lexical filing axis. 'both': union of the two. 'exact': only the literal tag, no expansion. Omit for 'subtypes' (current behavior).",
+          },
           exclude_tags: {
             oneOf: [
               { type: "string" },
@@ -361,6 +367,18 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             "INVALID_QUERY",
           );
         }
+        // Tag-expansion axis (vault tag `expand` axis). Validate loudly so a
+        // typo'd value doesn't silently fall back to the default.
+        let expand: TagExpandMode | undefined;
+        if (params.expand !== undefined && params.expand !== null) {
+          if (typeof params.expand !== "string" || !(TAG_EXPAND_MODES as readonly string[]).includes(params.expand)) {
+            throw new QueryError(
+              `invalid \`expand\` value ${JSON.stringify(params.expand)} — must be one of ${TAG_EXPAND_MODES.map((m) => `"${m}"`).join(", ")}. Omit for the default ("subtypes").`,
+              "INVALID_QUERY",
+            );
+          }
+          expand = params.expand as TagExpandMode;
+        }
 
         // --- Full-text search ---
         let results: Note[];
@@ -376,6 +394,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           results = await store.searchNotes(params.search as string, {
             tags,
             limit: (params.limit as number) ?? 50,
+            expand,
           });
         } else {
           // --- Structured query ---
@@ -395,6 +414,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           const queryOpts = {
             tags,
             tagMatch: (params.tag_match as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
+            expand,
             excludeTags,
             hasTags: params.has_tags as boolean | undefined,
             hasLinks: params.has_links as boolean | undefined,

package/core/src/schema.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
 
-export const SCHEMA_VERSION = 20;
+export const SCHEMA_VERSION = 21;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record.
@@ -186,6 +186,23 @@ CREATE TABLE IF NOT EXISTS mcp_mint_ledger (
   revoked_at TEXT
 );
 
+-- Triggers (v21, vault frictionless-channel-setup PR 1): runtime, persisted,
+-- per-vault webhook triggers. Complements the static config.yaml trigger
+-- system — config.yaml triggers stay global; rows here are scoped to THIS
+-- vault's DB and fire only for events on this vault. The structured columns
+-- (events/when/action) are JSON-encoded; the action column carries the webhook
+-- URL, send mode, timeout, and an optional auth { bearer } for the JWT webhook
+-- path. Managed at runtime via the admin-scoped /api/triggers REST surface
+-- and re-registered on the live hook registry at boot. See src/triggers-api.ts.
+CREATE TABLE IF NOT EXISTS triggers (
+  name TEXT PRIMARY KEY,
+  events TEXT NOT NULL DEFAULT '[]',
+  "when" TEXT NOT NULL DEFAULT '{}',
+  action TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
 -- OAuth: registered clients (Dynamic Client Registration)
 -- VESTIGIAL after vault 0.4.x workstream E (2026-05-25). The standalone
 -- OAuth issuer that wrote these rows was retired (hub is the issuer now;
@@ -452,6 +469,11 @@ export function initSchema(db: Database): void {
   // version bump. See vault#403 (MGT — manage-token mints hub JWTs).
   migrateToV20(db);
 
+  // Migrate v20 → v21: ensure the `triggers` table exists (runtime per-vault
+  // webhook triggers). Created by SCHEMA_SQL's CREATE TABLE IF NOT EXISTS
+  // above, so this is a defensive confirmation hook for upgrading vaults.
+  migrateToV21(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1077,6 +1099,28 @@ function migrateToV20(db: Database): void {
   );
 }
 
+/**
+ * Migrate v20 → v21: ensure the `triggers` table exists (runtime per-vault
+ * webhook triggers — vault frictionless-channel-setup PR 1). SCHEMA_SQL's
+ * `CREATE TABLE IF NOT EXISTS` already covers fresh AND upgrading vaults
+ * (it runs unconditionally before the migration steps), so this is a
+ * defensive no-op confirmation for vaults created before v21. The reserved
+ * keyword `when` is quoted in the column definition. Idempotent.
+ */
+function migrateToV21(db: Database): void {
+  if (hasTable(db, "triggers")) return;
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS triggers (
+      name TEXT PRIMARY KEY,
+      events TEXT NOT NULL DEFAULT '[]',
+      "when" TEXT NOT NULL DEFAULT '{}',
+      action TEXT NOT NULL DEFAULT '{}',
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/store.ts

@@ -15,10 +15,12 @@ import { pathTitle } from "./paths.js";
 import { HookRegistry } from "./hooks.js";
 import {
   loadTagHierarchy,
-  getTagDescendants,
+  getTagExpansion,
   TAG_CONFIG_PREFIX,
   DEFAULT_TAG_NAME,
+  DEFAULT_TAG_EXPAND_MODE,
   type TagHierarchy,
+  type TagExpandMode,
 } from "./tag-hierarchy.js";
 import {
   loadSchemaConfig,
@@ -278,13 +280,25 @@ export class BunSqliteStore implements Store {
    *   the other tags' notes — wrong).
    *
    * Other filters (path, metadata, dates) still apply in both cases.
+   *
+   * `expand` axis (vault tag `expand` axis): `opts.expand` selects WHICH axis
+   * each tag expands along — `"subtypes"` (default, the parent_names path
+   * documented above, with the `_default` magic), `"namespace"` (lexical
+   * `tag/*`), `"both"` (union), or `"exact"` (no expansion). The `_default`
+   * universal-parent magic is a SUBTYPES-axis concept, so it fires only when
+   * the resolved mode includes subtypes (`"subtypes"`/`"both"`); under
+   * `"namespace"`/`"exact"` a literal `_default` tag is treated like any other.
    */
   private expandQueryTags(opts: QueryOpts): QueryOpts {
     if (!opts.tags || opts.tags.length === 0) return opts;
     const hierarchy = this.getTagHierarchy();
+    const mode: TagExpandMode = opts.expand ?? DEFAULT_TAG_EXPAND_MODE;
+    const subtypeAxis = mode === "subtypes" || mode === "both";
 
     let tags = opts.tags;
-    if (hierarchy.allTags.has(DEFAULT_TAG_NAME) && tags.includes(DEFAULT_TAG_NAME)) {
+    // `_default` collapse only applies on the subtypes axis — it's the
+    // universal *parent* (an is-a relationship), not a namespace prefix.
+    if (subtypeAxis && hierarchy.allTags.has(DEFAULT_TAG_NAME) && tags.includes(DEFAULT_TAG_NAME)) {
       const match = opts.tagMatch ?? "all";
       if (match === "any") {
         const { tags: _drop, ..._rest } = opts;
@@ -298,34 +312,61 @@ export class BunSqliteStore implements Store {
       opts = { ...opts, tags };
     }
 
-    if (hierarchy.childrenOf.size === 0) return opts;
-    const expanded = tags.map((t) => Array.from(getTagDescendants(hierarchy, t)));
+    // Subtypes fast-path: with no declared hierarchy there are no descendants,
+    // so the engine's `[tag]` fallback already produces the literal-tag join —
+    // skip attaching `_tagsExpanded` to stay byte-identical to pre-axis
+    // behavior. `exact` likewise needs no expansion. Namespace/both must still
+    // run (lexical expansion is independent of `parent_names`).
+    if (mode === "exact") return opts;
+    if (mode === "subtypes" && hierarchy.childrenOf.size === 0) return opts;
+
+    const expanded = tags.map((t) => Array.from(getTagExpansion(hierarchy, t, mode)));
     return { ...opts, _tagsExpanded: expanded } as QueryOpts;
   }
 
-  async searchNotes(query: string, opts?: { tags?: string[]; limit?: number }): Promise<Note[]> {
-    // Same hierarchy-expansion treatment as queryNotes — searching `#manual`
-    // should match notes tagged with any descendant tag. The underlying
-    // FTS path already uses `IN (...)` for tags, so we flatten the
-    // per-input expansions into a single union (search semantics are
-    // "any tag matches"). When `_default` is among the requested tags
-    // (and a `_default` row exists), the OR collapses to "every note" —
-    // drop the tag filter entirely so the search hits the full corpus
-    // and untagged notes are reachable.
+  async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]> {
+    // Same tag-expansion treatment as queryNotes, along the SAME `expand` axis
+    // (vault tag `expand` axis) — searching `#manual` should match notes
+    // tagged with any descendant under "subtypes", any `manual/*` under
+    // "namespace", etc. The underlying FTS path already uses `IN (...)` for
+    // tags, so we flatten the per-input expansions into a single union (search
+    // semantics are "any tag matches").
+    //
+    // `_default` collapse is a SUBTYPES-axis concept (the universal *parent*):
+    // when `_default` is among the requested tags and a `_default` row exists,
+    // the OR collapses to "every note" — drop the tag filter entirely so the
+    // search hits the full corpus and untagged notes are reachable. It fires
+    // only on the subtypes/both axes (mirrors `expandQueryTags`).
     if (opts?.tags && opts.tags.length > 0) {
+      const mode: TagExpandMode = opts.expand ?? DEFAULT_TAG_EXPAND_MODE;
+      const subtypeAxis = mode === "subtypes" || mode === "both";
       const hierarchy = this.getTagHierarchy();
-      if (hierarchy.allTags.has(DEFAULT_TAG_NAME) && opts.tags.includes(DEFAULT_TAG_NAME)) {
-        const { tags: _drop, ..._rest } = opts;
+      if (subtypeAxis && hierarchy.allTags.has(DEFAULT_TAG_NAME) && opts.tags.includes(DEFAULT_TAG_NAME)) {
+        const { tags: _drop, expand: _e, ..._rest } = opts;
         return noteOps.searchNotes(this.db, query, _rest);
       }
-      if (hierarchy.childrenOf.size > 0) {
+      // Subtypes fast-path: with no declared hierarchy there are no
+      // descendants, so the tags pass through unchanged (byte-identical to
+      // pre-axis behavior). `exact` likewise needs no expansion.
+      // Namespace/both must still run (lexical expansion is independent of
+      // `parent_names`).
+      const skipExpansion =
+        mode === "exact" || (mode === "subtypes" && hierarchy.childrenOf.size === 0);
+      if (!skipExpansion) {
         const expanded = new Set<string>();
         for (const t of opts.tags) {
-          for (const x of getTagDescendants(hierarchy, t)) expanded.add(x);
+          for (const x of getTagExpansion(hierarchy, t, mode)) expanded.add(x);
         }
-        return noteOps.searchNotes(this.db, query, { ...opts, tags: Array.from(expanded) });
+        const { expand: _e, ..._rest } = opts;
+        return noteOps.searchNotes(this.db, query, { ..._rest, tags: Array.from(expanded) });
       }
     }
+    // Strip the internal `expand` before passing to noteOps (it has no field
+    // for it; harmless but keep the boundary clean).
+    if (opts && "expand" in opts) {
+      const { expand: _e, ..._rest } = opts;
+      return noteOps.searchNotes(this.db, query, _rest);
+    }
     return noteOps.searchNotes(this.db, query, opts);
   }
 
@@ -340,11 +381,17 @@ export class BunSqliteStore implements Store {
   }
 
   async expandTagsWithDescendants(tags: string[]): Promise<Set<string>> {
+    // Thin `mode:"subtypes"` shim over the mode-aware `expandTags`, so existing
+    // callers (tag-scope auth, search) keep the exact descendant semantics.
+    return this.expandTags(tags, "subtypes");
+  }
+
+  async expandTags(tags: string[], mode: TagExpandMode = DEFAULT_TAG_EXPAND_MODE): Promise<Set<string>> {
     const expanded = new Set<string>();
     if (tags.length === 0) return expanded;
     const hierarchy = this.getTagHierarchy();
     for (const t of tags) {
-      for (const x of getTagDescendants(hierarchy, t)) expanded.add(x);
+      for (const x of getTagExpansion(hierarchy, t, mode)) expanded.add(x);
     }
     return expanded;
   }

package/core/src/tag-expand-axis.test.ts

@@ -0,0 +1,301 @@
+/**
+ * Tag-expansion axis (`expand`) tests — vault tag `expand` axis
+ * (design `design/2026-06-09-tag-expand-axis.md`).
+ *
+ * Covers the query engine (`store.queryNotes` → `expandQueryTags` →
+ * `_tagsExpanded`) and the mode-aware core helpers
+ * (`getTagExpansion`/`getTagNamespace`). REST + MCP + SSE parity are exercised
+ * in their own suites (`routes`/`mcp` here, `subscribe`/`live-match` in src/).
+ *
+ * The corpus deliberately separates the two axes so a mode that confuses them
+ * fails loudly:
+ *   - `entity` is the SUBTYPE parent of `person` (declared via parent_names).
+ *     `person` is NOT name-prefixed `entity/`.
+ *   - `entity/archived` is NAME-prefixed under `entity` but is NOT a declared
+ *     subtype (no parent_names link to `entity`).
+ *   - `entity/person` is BOTH a declared subtype-child of `entity` AND
+ *     name-prefixed `entity/` — the dedupe case.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import {
+  loadTagHierarchy,
+  getTagExpansion,
+  getTagNamespace,
+  getTagDescendants,
+} from "./tag-hierarchy.js";
+
+let store: SqliteStore;
+let db: Database;
+
+/**
+ * Seed the two-axis corpus and return the set of note ids by their kind so
+ * tests can assert membership without depending on insertion order.
+ */
+async function seedTwoAxisCorpus(s: SqliteStore) {
+  // SUBTYPE axis: person is-a entity (declared), but NOT filed under entity/.
+  await s.upsertTagRecord("entity", { description: "an entity" });
+  await s.upsertTagRecord("person", { parent_names: ["entity"] });
+  // NAMESPACE axis: entity/archived is filed under entity/ but declares no
+  // parent_names (pure filing, no is-a edge).
+  await s.upsertTagRecord("entity/archived", {});
+  // BOTH axes: entity/person is a declared subtype-child AND name-prefixed.
+  await s.upsertTagRecord("entity/person", { parent_names: ["entity"] });
+
+  const nEntity = await s.createNote("literal entity", { tags: ["entity"] });
+  const nPerson = await s.createNote("a person (subtype)", { tags: ["person"] });
+  const nArchived = await s.createNote("filed under entity/", { tags: ["entity/archived"] });
+  const nBoth = await s.createNote("subtype AND filed", { tags: ["entity/person"] });
+  const nUnrelated = await s.createNote("unrelated", { tags: ["work"] });
+
+  return {
+    entity: nEntity.id,
+    person: nPerson.id,
+    archived: nArchived.id,
+    both: nBoth.id,
+    unrelated: nUnrelated.id,
+  };
+}
+
+const idsOf = (notes: { id: string }[]) => new Set(notes.map((n) => n.id));
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("tag expand axis — core helpers", () => {
+  it("getTagNamespace returns the tag + lexically prefixed names, no parent_names subtypes", async () => {
+    await seedTwoAxisCorpus(store);
+    const h = loadTagHierarchy(db);
+    const ns = getTagNamespace(h, "entity");
+    // tag itself + name-prefixed entity/*
+    expect(ns).toContain("entity");
+    expect(ns).toContain("entity/archived");
+    expect(ns).toContain("entity/person");
+    // `person` is a subtype but NOT name-prefixed → must be absent.
+    expect(ns.has("person")).toBe(false);
+  });
+
+  it("getTagExpansion: subtypes = descendants, namespace = lexical, both = union, exact = literal", async () => {
+    await seedTwoAxisCorpus(store);
+    const h = loadTagHierarchy(db);
+
+    const subtypes = getTagExpansion(h, "entity", "subtypes");
+    // descendants via parent_names: entity, person, entity/person — NOT entity/archived
+    expect(subtypes).toEqual(getTagDescendants(h, "entity"));
+    expect(subtypes).toContain("person");
+    expect(subtypes).toContain("entity/person");
+    expect(subtypes.has("entity/archived")).toBe(false);
+
+    const ns = getTagExpansion(h, "entity", "namespace");
+    expect(ns).toContain("entity/archived");
+    expect(ns).toContain("entity/person");
+    expect(ns.has("person")).toBe(false);
+
+    const both = getTagExpansion(h, "entity", "both");
+    // union: subtype-only person + namespace-only entity/archived + shared
+    expect(both).toContain("person");
+    expect(both).toContain("entity/archived");
+    expect(both).toContain("entity/person");
+
+    const exact = getTagExpansion(h, "entity", "exact");
+    expect(exact).toEqual(new Set(["entity"]));
+  });
+
+  it("dedupe: entity/person (subtype AND name-prefixed) appears once under both", async () => {
+    await seedTwoAxisCorpus(store);
+    const h = loadTagHierarchy(db);
+    const both = getTagExpansion(h, "entity", "both");
+    const count = Array.from(both).filter((t) => t === "entity/person").length;
+    expect(count).toBe(1);
+  });
+
+  it("store.expandTags mirrors the helper modes and unions multi-tag input", async () => {
+    await seedTwoAxisCorpus(store);
+    expect(await store.expandTags(["entity"], "exact")).toEqual(new Set(["entity"]));
+    const ns = await store.expandTags(["entity"], "namespace");
+    expect(ns).toContain("entity/archived");
+    expect(ns.has("person")).toBe(false);
+    // default (no mode) === subtypes === expandTagsWithDescendants
+    const def = await store.expandTags(["entity"]);
+    expect(def).toEqual(await store.expandTagsWithDescendants(["entity"]));
+  });
+});
+
+describe("tag expand axis — query engine", () => {
+  it("subtypes (default / absent) is a pure regression: descendants only, no namespaced sibling", async () => {
+    const ids = await seedTwoAxisCorpus(store);
+
+    const absent = await store.queryNotes({ tags: ["entity"] });
+    const explicit = await store.queryNotes({ tags: ["entity"], expand: "subtypes" });
+
+    // Absent ≡ explicit "subtypes" — byte-identical result set.
+    expect(idsOf(explicit)).toEqual(idsOf(absent));
+
+    // Returns the literal + declared subtypes…
+    expect(idsOf(absent)).toEqual(new Set([ids.entity, ids.person, ids.both]));
+    // …and NOT the namespace-only sibling entity/archived.
+    expect(idsOf(absent).has(ids.archived)).toBe(false);
+  });
+
+  it("namespace returns tag + tag/* lexical, NOT parent_names-only subtypes", async () => {
+    const ids = await seedTwoAxisCorpus(store);
+    const res = await store.queryNotes({ tags: ["entity"], expand: "namespace" });
+    // entity (literal) + entity/archived + entity/person (name-prefixed)
+    expect(idsOf(res)).toEqual(new Set([ids.entity, ids.archived, ids.both]));
+    // `person` is a subtype but not name-prefixed → excluded.
+    expect(idsOf(res).has(ids.person)).toBe(false);
+  });
+
+  it("both = union of subtypes and namespace", async () => {
+    const ids = await seedTwoAxisCorpus(store);
+    const res = await store.queryNotes({ tags: ["entity"], expand: "both" });
+    expect(idsOf(res)).toEqual(
+      new Set([ids.entity, ids.person, ids.archived, ids.both]),
+    );
+  });
+
+  it("exact = literal tag only, no descendants", async () => {
+    const ids = await seedTwoAxisCorpus(store);
+    const res = await store.queryNotes({ tags: ["entity"], expand: "exact" });
+    expect(idsOf(res)).toEqual(new Set([ids.entity]));
+  });
+
+  it("dedupe: a note tagged with a both-axis tag is returned once under both", async () => {
+    await seedTwoAxisCorpus(store);
+    const res = await store.queryNotes({ tags: ["entity"], expand: "both" });
+    const bothCount = res.filter((n) => n.content === "subtype AND filed").length;
+    expect(bothCount).toBe(1);
+  });
+
+  it("_default magic stays subtypes-only: namespace on _default does NOT collapse to all notes", async () => {
+    // _default declared → universal subtype parent. With a namespaced child.
+    await store.upsertTagRecord("_default", { description: "universal" });
+    await store.upsertTagRecord("_default/scoped", {});
+    const nA = await store.createNote("a", { tags: ["alpha"] });
+    const nScoped = await store.createNote("scoped", { tags: ["_default/scoped"] });
+
+    // subtypes: _default expands to ALL tags → every note matches.
+    const sub = await store.queryNotes({ tags: ["_default"], expand: "subtypes" });
+    expect(idsOf(sub).has(nA.id)).toBe(true);
+
+    // namespace: _default is treated literally → only _default + _default/* —
+    // does NOT collapse to "all notes" (nA, tagged only `alpha`, is excluded).
+    const ns = await store.queryNotes({ tags: ["_default"], expand: "namespace" });
+    expect(idsOf(ns).has(nA.id)).toBe(false);
+    expect(idsOf(ns).has(nScoped.id)).toBe(true);
+  });
+
+  it("both + _default collapses to all-notes via the subtypes axis", async () => {
+    // `both` includes the subtypes axis, so the `_default` universal-parent
+    // magic must still fire — the union with the namespace axis can only widen
+    // the set, and subtypes alone already means "every note." Untagged notes
+    // included (the _default collapse drops the tag filter entirely).
+    await store.upsertTagRecord("_default", { description: "universal" });
+    const nTagged = await store.createNote("tagged", { tags: ["alpha"] });
+    const nUntagged = await store.createNote("untagged", {});
+
+    const res = await store.queryNotes({ tags: ["_default"], expand: "both" });
+    const got = idsOf(res);
+    expect(got.has(nTagged.id)).toBe(true);
+    expect(got.has(nUntagged.id)).toBe(true);
+    // Equivalent to the no-filter corpus.
+    const all = await store.queryNotes({});
+    expect(got).toEqual(idsOf(all));
+  });
+});
+
+describe("tag expand axis — MCP query-notes schema + handler", () => {
+  it("query-notes schema advertises the four expand values", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    const tools = generateMcpTools(store);
+    const q = tools.find((t) => t.name === "query-notes")!;
+    const props = (q.inputSchema as any).properties;
+    expect(props.expand).toBeDefined();
+    expect(props.expand.enum).toEqual(["subtypes", "namespace", "both", "exact"]);
+  });
+
+  it("query-notes handler honors expand=namespace", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    const ids = await seedTwoAxisCorpus(store);
+    const tools = generateMcpTools(store);
+    const q = tools.find((t) => t.name === "query-notes")!;
+    // Non-cursor structured query returns a flat array of note-index entries.
+    const res: any = await q.execute({ tag: "entity", expand: "namespace" });
+    const got = new Set<string>(res.map((n: any) => n.id));
+    expect(got).toEqual(new Set([ids.entity, ids.archived, ids.both]));
+    expect(got.has(ids.person)).toBe(false);
+  });
+
+  it("query-notes handler rejects an unknown expand value with INVALID_QUERY", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    const tools = generateMcpTools(store);
+    const q = tools.find((t) => t.name === "query-notes")!;
+    let err: any;
+    try {
+      await q.execute({ tag: "entity", expand: "bogus" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeDefined();
+    expect(err.code).toBe("INVALID_QUERY");
+  });
+});
+
+describe("tag expand axis — MCP search path honors expand", () => {
+  // Corpus shares the FTS term "fox" so search(tag=entity) differs ONLY by the
+  // expand axis — proving the search branch threads it into store.searchNotes.
+  async function seedSearchCorpus(s: SqliteStore) {
+    await s.upsertTagRecord("entity", { description: "entity root" });
+    await s.upsertTagRecord("person", { parent_names: ["entity"] }); // subtype, not name-prefixed
+    await s.upsertTagRecord("entity/archived", {}); // name-prefixed, not subtype
+    await s.createNote("fox literal", { tags: ["entity"] });
+    await s.createNote("fox subtype", { tags: ["person"] });
+    await s.createNote("fox filed", { tags: ["entity/archived"] });
+    await s.createNote("dog unrelated", { tags: ["entity"] }); // no "fox" → FTS excludes
+  }
+
+  it("search + tag, absent expand ≡ subtypes (descendants, no namespaced sibling)", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    await seedSearchCorpus(store);
+    const q = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+    const absent: any = await q.execute({ search: "fox", tag: "entity", include_content: true });
+    const sub: any = await q.execute({ search: "fox", tag: "entity", expand: "subtypes", include_content: true });
+    const absentSet = new Set(absent.map((n: any) => n.content));
+    expect(new Set(sub.map((n: any) => n.content))).toEqual(absentSet);
+    expect(absentSet).toEqual(new Set(["fox literal", "fox subtype"]));
+  });
+
+  it("search + tag + expand=namespace returns lexical tag/*, NOT subtype sibling", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    await seedSearchCorpus(store);
+    const q = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+    const res: any = await q.execute({ search: "fox", tag: "entity", expand: "namespace", include_content: true });
+    expect(new Set(res.map((n: any) => n.content))).toEqual(new Set(["fox literal", "fox filed"]));
+  });
+
+  it("search + tag + expand=exact returns only the literal-tagged match", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    await seedSearchCorpus(store);
+    const q = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+    const res: any = await q.execute({ search: "fox", tag: "entity", expand: "exact", include_content: true });
+    expect(res.map((n: any) => n.content)).toEqual(["fox literal"]);
+  });
+
+  it("search + expand=bogus is rejected with INVALID_QUERY before the search runs", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    await store.createNote("fox here", { tags: ["entity"] });
+    const q = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+    let err: any;
+    try {
+      await q.execute({ search: "fox", tag: "entity", expand: "bogus" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeDefined();
+    expect(err.code).toBe("INVALID_QUERY");
+  });
+});