@openparachute/vault 0.6.0-rc.1 → 0.6.1

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;
   }
@@ -572,7 +619,7 @@ export class BunSqliteStore implements Store {
     patch: {
       description?: string | null;
       fields?: Record<string, tagSchemaOps.TagFieldSchema> | null;
-      relationships?: Record<string, tagSchemaOps.TagRelationship> | null;
+      relationships?: tagSchemaOps.TagRelationshipMap | null;
       parent_names?: string[] | null;
     },
   ) {
@@ -730,7 +777,7 @@ export class BunSqliteStore implements Store {
     // Scope by noteId so a token authorized for note A can't delete note B's attachments.
     const row = this.db.prepare(
       "SELECT path FROM attachments WHERE id = ? AND note_id = ?",
-    ).get(attachmentId, noteId) as { path: string } | undefined;
+    ).get(attachmentId, noteId) as { path: string } | null;
     if (!row) return { deleted: false, path: null, orphaned: false };
 
     this.db.prepare("DELETE FROM attachments WHERE id = ? AND note_id = ?").run(attachmentId, noteId);
@@ -756,7 +803,7 @@ export class BunSqliteStore implements Store {
   async getAttachment(attachmentId: string): Promise<Attachment | null> {
     const row = this.db.prepare(
       "SELECT * FROM attachments WHERE id = ?",
-    ).get(attachmentId) as { id: string; note_id: string; path: string; mime_type: string; metadata: string | null; created_at: string } | undefined;
+    ).get(attachmentId) as { id: string; note_id: string; path: string; mime_type: string; metadata: string | null; created_at: string } | null;
     if (!row) return null;
     let metadata: Record<string, unknown> | undefined;
     if (row.metadata && row.metadata !== "{}") {

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");
+  });
+});

package/core/src/tag-hierarchy.ts

@@ -143,6 +143,86 @@ export function getTagDescendants(h: TagHierarchy, tag: string): Set<string> {
   return result;
 }
 
+/**
+ * Tag-expansion axis (vault tag `expand` axis — design
+ * `design/2026-06-09-tag-expand-axis.md`). A tag relates to others along two
+ * orthogonal axes; this selects which one (or both, or neither) a query expands
+ * along:
+ *
+ * - `"subtypes"` (DEFAULT): tag ∪ `parent_names` descendants. The semantic
+ *   is-a axis — today's always-on behavior, unchanged. `_default` universal
+ *   parent magic fires here.
+ * - `"namespace"`: tag ∪ {names lexically prefixed `tag/`}. The organizational
+ *   filing axis — purely lexical over the known tag set, no `parent_names`, no
+ *   `_default` magic.
+ * - `"both"`: union of subtypes and namespace.
+ * - `"exact"`: the literal tag only, no expansion.
+ */
+export type TagExpandMode = "subtypes" | "namespace" | "both" | "exact";
+
+export const TAG_EXPAND_MODES: readonly TagExpandMode[] = [
+  "subtypes",
+  "namespace",
+  "both",
+  "exact",
+] as const;
+
+export const DEFAULT_TAG_EXPAND_MODE: TagExpandMode = "subtypes";
+
+/**
+ * Lexical namespace expansion for a single tag: the tag itself plus every
+ * known tag name filed under it (`name === tag` OR `name` starts with
+ * `tag + "/"`). Purely a string-prefix match over `h.allTags` — namespacing is
+ * free-form (the slash in the tag *name*), declared nowhere, which is the whole
+ * point: subtyping is declared via `parent_names`, filing is not. No `_default`
+ * magic here — that's a subtypes-axis concept.
+ */
+export function getTagNamespace(h: TagHierarchy, tag: string): Set<string> {
+  // Pre-seeded with `tag` itself, so the loop only needs the strict `tag/*`
+  // prefix test (the `name === tag` case is already covered by the seed).
+  const result = new Set<string>([tag]);
+  const prefix = tag + "/";
+  for (const name of h.allTags) {
+    if (name.startsWith(prefix)) result.add(name);
+  }
+  return result;
+}
+
+/**
+ * Mode-aware single-tag expansion (vault tag `expand` axis). Returns the set of
+ * tag names a query for `tag` should match under `mode`. Always includes `tag`
+ * itself. Set semantics: a tag that is BOTH a declared subtype-child AND
+ * name-prefixed appears once.
+ *
+ * - `"subtypes"` → `getTagDescendants` (parent_names + `_default` magic).
+ * - `"namespace"` → `getTagNamespace` (lexical `tag/*`).
+ * - `"both"` → union of the two.
+ * - `"exact"` → `{tag}`.
+ */
+export function getTagExpansion(
+  h: TagHierarchy,
+  tag: string,
+  mode: TagExpandMode,
+): Set<string> {
+  switch (mode) {
+    case "exact":
+      return new Set<string>([tag]);
+    case "namespace":
+      return getTagNamespace(h, tag);
+    case "both": {
+      const union = new Set<string>(getTagDescendants(h, tag));
+      for (const name of getTagNamespace(h, tag)) union.add(name);
+      return union;
+    }
+    case "subtypes":
+    default:
+      // `default` is a defensive fallback — `TagExpandMode` already constrains
+      // the value to the four cases above; it can only be reached if an
+      // untyped caller passes a bad string.
+      return getTagDescendants(h, tag);
+  }
+}
+
 /**
  * Detect cycles in the declared hierarchy. Returns the list of tags
  * reachable from themselves via parent declarations. Used by