@openparachute/vault 0.6.0-rc.1 → 0.6.0

package/core/src/portable-md.test.ts

@@ -794,6 +794,37 @@ describe("importPortableVault", async () => {
     expect(typed!.metadata).toEqual({ source: "git://x" });
   });
 
+  it("preserves an opaque relationship-vocabulary map across export → import → re-export (vault#428)", async () => {
+    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", note: "freeform" },
+    };
+    await store.upsertTagRecord("person", {
+      description: "a human",
+      relationships: vocab,
+    });
+    const outDir = join(tmpBase, "out");
+    await exportVaultToDir(store, { outDir, exportedAt: "2026-05-13T00:00:00.000Z" });
+
+    const target = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(target, { inDir: outDir });
+    expect(stats.schemas_restored).toBe(1);
+
+    // Imported value matches the original verbatim.
+    const restored = await target.getTagRecord("person");
+    expect(restored?.relationships).toEqual(vocab);
+
+    // Re-export from the restored store and confirm the schema file is
+    // byte-identical to the first export (deep round-trip stability).
+    const outDir2 = join(tmpBase, "out2");
+    await exportVaultToDir(target, { outDir: outDir2, exportedAt: "2026-05-13T00:00:00.000Z" });
+    const schemaA = readFileSync(join(outDir, SIDECAR_DIR, "schemas", "person.yaml"), "utf-8");
+    const schemaB = readFileSync(join(outDir2, SIDECAR_DIR, "schemas", "person.yaml"), "utf-8");
+    expect(schemaB).toBe(schemaA);
+  });
+
   it("skips typed links whose target is missing from the import set", async () => {
     // Source note has a typed link to a target we don't include in
     // the export (synthetic — write the .md file by hand).
@@ -862,6 +893,15 @@ describe("portable-md round-trip — byte-equivalent re-export after blow-away i
       description: "A long-running effort",
       fields: { status: { type: "string", enum: ["active", "done"] } },
     });
+    // Opaque relationship-vocabulary map (vault#428) — exercises that the
+    // round-trip preserves an arbitrary app-defined relationships shape,
+    // not just the historical { target_tag, cardinality } one.
+    await store.upsertTagRecord("project", {
+      relationships: {
+        "works-on": { from: "person", to: "project" },
+        "based-at": { from: "project", to: "place", note: "freeform" },
+      },
+    });
     const n1 = await store.createNote("alpha body", {
       id: "01HX001",
       path: "Inbox/alpha",

package/core/src/portable-md.ts

@@ -2091,11 +2091,29 @@ export function parseFrontmatter(raw: string): {
   frontmatter: Record<string, unknown>;
   content: string;
 } {
-  if (!raw.startsWith("---")) return { frontmatter: {}, content: raw };
-  const endIdx = raw.indexOf("\n---", 3);
-  if (endIdx === -1) return { frontmatter: {}, content: raw };
-  const yamlBlock = raw.slice(4, endIdx); // skip opening "---\n"
-  const content = raw.slice(endIdx + 4).replace(/^\n/, "");
+  // 1. Strip a leading UTF-8 BOM (U+FEFF) if present. Without this an
+  //    Obsidian export saved with a BOM (`---\n…`) fails the open
+  //    test and the whole file — frontmatter included — falls into the
+  //    body, silently losing id/tags/timestamps (contract FX-FENCE-BOM).
+  const src = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+
+  // 2. Line-scan close-fence (CRLF-aware). The opening line must be
+  //    EXACTLY `---`; the closing fence is the FIRST subsequent line that
+  //    is EXACTLY `---` — not `----`, not `---text`, not `  ---`. An
+  //    unclosed block means the whole file is body (never swallow). This
+  //    replaces the old `indexOf("\n---")` which wrongly matched `\n----`
+  //    and `\n---more` (contract §1.1, FX-FENCE-FOURDASH-OPEN).
+  const lines = src.split(/\r?\n/);
+  if (lines[0] !== "---") return { frontmatter: {}, content: src };
+
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") { closeIdx = i; break; }
+  }
+  if (closeIdx === -1) return { frontmatter: {}, content: src };
+
+  const yamlBlock = lines.slice(1, closeIdx).join("\n");
+  const content = lines.slice(closeIdx + 1).join("\n");
   return { frontmatter: parseBlock(yamlBlock, 0).value, content };
 }
 
@@ -2119,11 +2137,16 @@ function parseBlock(text: string, baseIndent: number): ParseResult {
   while (i < lines.length) {
     const line = lines[i]!;
     if (line.trim() === "") { i++; continue; }
+    // Skip `#`-comment lines (contract C3 / §1.2). A comment at the
+    // block's base level is not a key line; the parser must step over it.
+    if (line.trimStart().startsWith("#")) { i++; continue; }
     const indent = countLeadingSpaces(line);
     if (indent < baseIndent) break;
     if (indent > baseIndent) { i++; continue; } // shouldn't happen at this level
 
-    const kv = line.slice(baseIndent).match(/^([\w][\w-]*):\s*(.*)$/);
+    // Key regex (contract C2 / §1.2): dots allowed in keys, optional
+    // whitespace before the colon (`created.at:` / `key :` both parse).
+    const kv = line.slice(baseIndent).match(/^([\w][\w.-]*)\s*:\s*(.*)$/);
     if (!kv) { i++; continue; }
     const key = kv[1]!;
     const valueText = kv[2]!.trim();
@@ -2199,7 +2222,8 @@ function parseArrayBlock(lines: string[], start: number, arrayIndent: number): {
     // First content after `- `.
     const after = line.slice(indent + 2).trim();
     // Is this a scalar item (`- foo`) or an object item (`- key: value`)?
-    const objMatch = after.match(/^([\w][\w-]*):\s*(.*)$/);
+    // Key regex matches parseBlock's (contract C2): dots + optional space.
+    const objMatch = after.match(/^([\w][\w.-]*)\s*:\s*(.*)$/);
     if (!objMatch) {
       result.push(parseScalarOrInline(after));
       i++;
@@ -2251,7 +2275,7 @@ function parseArrayBlock(lines: string[], start: number, arrayIndent: number): {
       const sibIndent = countLeadingSpaces(sib);
       if (sibIndent !== itemIndent) break;
       if (sib.slice(sibIndent).startsWith("- ")) break;
-      const sibKv = sib.slice(sibIndent).match(/^([\w][\w-]*):\s*(.*)$/);
+      const sibKv = sib.slice(sibIndent).match(/^([\w][\w.-]*)\s*:\s*(.*)$/);
       if (!sibKv) break;
       const sibKey = sibKv[1]!;
       const sibValue = sibKv[2]!.trim();
@@ -2287,6 +2311,36 @@ function parseArrayBlock(lines: string[], start: number, arrayIndent: number): {
   return { value: result, consumed: i - start };
 }
 
+/**
+ * Quote-aware split of an inline-array body on top-level commas
+ * (contract C4 / §1.2). A comma inside a single- or double-quoted string
+ * does not separate items, so `"a, b", c` → `['"a, b"', 'c']`. Quote
+ * chars are preserved in the parts; `parseScalarOrInline` strips them via
+ * `unquote`. Mirrors the web parser's `splitInlineArray`.
+ */
+function splitInlineArray(inner: string): string[] {
+  const parts: string[] = [];
+  let buf = "";
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i]!;
+    if (quote) {
+      buf += ch;
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      buf += ch;
+    } else if (ch === ",") {
+      parts.push(buf);
+      buf = "";
+    } else {
+      buf += ch;
+    }
+  }
+  parts.push(buf);
+  return parts;
+}
+
 /**
  * Parse a scalar or inline form (`[a, b]`, `{ k: v }`). Used for the
  * value portion of `key: value` lines.
@@ -2295,7 +2349,10 @@ function parseScalarOrInline(s: string): unknown {
   if (s.startsWith("[") && s.endsWith("]")) {
     const inner = s.slice(1, -1).trim();
     if (inner === "") return [];
-    return inner.split(",").map((part) => parseScalarOrInline(part.trim()));
+    // Quote-aware split (contract C4 / §1.2): a comma inside a quoted
+    // string is NOT an item separator, so `["a, b", c]` → 2 items, not 3.
+    // Matches the web parser's `splitInlineArray`.
+    return splitInlineArray(inner).map((part) => parseScalarOrInline(part.trim()));
   }
   if (s.startsWith("{") && s.endsWith("}")) {
     const inner = s.slice(1, -1).trim();
@@ -2376,18 +2433,59 @@ function unquote(s: string): unknown {
 // Directory walking — shared with obsidian.ts
 // ---------------------------------------------------------------------------
 
-/** Recursively list all .md files in a directory, excluding hidden dirs
- *  (including `.parachute/` and `.obsidian/`). */
+/**
+ * Markdown-file classification (contract §1.7). Case-insensitive `.md`
+ * OR `.markdown`. `.mdx`, `.txt`, etc. are NOT markdown for the importer.
+ * Identical to the web parser's classifier.
+ */
+export function isMarkdownExtension(path: string): boolean {
+  return /\.(md|markdown)$/i.test(path);
+}
+
+/**
+ * Named intake-excluded directory/entry segments (contract §1.9). The
+ * generic `startsWith(".")` rule below subsumes the dot-prefixed ones;
+ * the named set is kept explicit for readability + to cover
+ * `__MACOSX`/`node_modules` (which do not start with ".").
+ */
+const EXCLUDED_SEGMENTS = new Set([
+  ".obsidian",
+  ".trash",
+  ".git",
+  ".parachute",
+  "__MACOSX",
+  "node_modules",
+]);
+
+/**
+ * Intake (file-selection) exclusion (contract §1.9). Excludes a source
+ * path if ANY `/`-segment is a named-excluded entry OR starts with "."
+ * (generic dotfile/dotdir). Applied identically by both parsers before
+ * parsing. The generic dot rule means legit dot-prefixed user files
+ * (`.daily-note.md`) ARE excluded — the chosen, consistent behavior.
+ */
+export function isExcludedPath(sourcePath: string): boolean {
+  for (const segment of sourcePath.split("/")) {
+    if (segment === "") continue;
+    if (EXCLUDED_SEGMENTS.has(segment)) return true;
+    if (segment.startsWith(".")) return true;
+  }
+  return false;
+}
+
+/** Recursively list all .md / .markdown files in a directory, excluding
+ *  hidden + named-internal dirs per the canonical `isExcludedPath` rule
+ *  (`.parachute/`, `.obsidian/`, `node_modules`, …). Legacy import path. */
 export function walkMarkdownFiles(dir: string): string[] {
   const results: string[] = [];
   function walk(current: string) {
     for (const entry of readdirSync(current)) {
-      if (entry.startsWith(".")) continue;
-      if (entry === "node_modules") continue;
+      // Per-segment exclusion: the named set + generic dotfile rule.
+      if (EXCLUDED_SEGMENTS.has(entry) || entry.startsWith(".")) continue;
       const full = join(current, entry);
       const stat = statSync(full);
       if (stat.isDirectory()) walk(full);
-      else if (stat.isFile() && extname(entry).toLowerCase() === ".md") results.push(full);
+      else if (stat.isFile() && isMarkdownExtension(entry)) results.push(full);
     }
   }
   walk(dir);
@@ -2417,15 +2515,43 @@ export function walkContentFiles(dir: string): string[] {
   return results.sort();
 }
 
+/**
+ * Canonical inline-tag regex (contract §1.3). `#` at line-start or after
+ * whitespace; body chars `[A-Za-z0-9_/-]` (slash for hierarchy); the tag
+ * MUST contain ≥1 non-numeric char (the middle `[A-Za-z_/-]`), so `#2024`
+ * is NOT a tag but `#v2`, `#2024-plan`, `#area/sub` are. Identical to the
+ * web parser's `INLINE_HASHTAG`.
+ */
+const INLINE_TAG_REGEX = /(?:^|\s)#([A-Za-z0-9_/-]*[A-Za-z_/-][A-Za-z0-9_/-]*)/g;
+
+/**
+ * Normalize + slug-validate a tag value (contract §1.4). Shared by inline
+ * tag extraction and frontmatter tag extraction (obsidian.ts re-exports
+ * this) so both surfaces validate identically. Returns null when the
+ * value is unusable (non-string non-scalar, empty, or fails slug rules).
+ */
+export function normalizeTagValue(v: unknown): string | null {
+  if (typeof v === "number" || typeof v === "boolean") {
+    return String(v).toLowerCase();
+  }
+  if (typeof v !== "string") return null;
+  const stripped = v.trim().replace(/^#/, "").toLowerCase();
+  if (stripped === "") return null;
+  // Slug-validate: lowercase alnum, underscore, hyphen, slash (hierarchy).
+  if (!/^[a-z0-9_/-]+$/.test(stripped)) return null;
+  return stripped;
+}
+
 /** Extract inline #tags from markdown content. Excludes tags in code blocks. */
 export function extractInlineTags(content: string): string[] {
   let stripped = content.replace(/```[\s\S]*?```/g, "");
   stripped = stripped.replace(/`[^`\n]+`/g, "");
   const tags = new Set<string>();
-  const regex = /(?:^|\s)#([\w][\w/-]*[\w]|[\w])/gm;
+  const regex = new RegExp(INLINE_TAG_REGEX.source, INLINE_TAG_REGEX.flags);
   let match: RegExpExecArray | null;
   while ((match = regex.exec(stripped)) !== null) {
-    tags.add(match[1]!.toLowerCase());
+    const tag = normalizeTagValue(match[1]!);
+    if (tag) tags.add(tag);
   }
   return [...tags];
 }

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.
@@ -30,10 +30,13 @@ CREATE TABLE IF NOT EXISTS notes (
 -- description    — human-readable blurb (markdown).
 -- fields         — JSON: indexed metadata field declarations per
 --                  query-operators.md. Replaces v6-era tag_schemas.fields.
--- relationships  — JSON: typed-link declarations
---                  ({ "rel": { target_tag, cardinality, description? } }).
---                  Cardinality vocabulary: one | optional | many | many-required.
---                  Phase 1 informational — declared but not enforced at write.
+-- relationships  — JSON: opaque relationship-vocabulary map. Keys are
+--                  relationship names; values are arbitrary JSON the declaring
+--                  app interprets (e.g. the Weaver's { "works-on": { from, to } }).
+--                  Stored + returned verbatim; only the top level is validated
+--                  (must be a JSON object/map). The historical typed shape
+--                  { "rel": { target_tag, cardinality, description? } } remains a
+--                  valid value. Not enforced at write time. See vault#428.
 -- parent_names   — JSON array of parent tag names. Replaces the v6-era
 --                  _tags/NAME config-note hierarchy.
 CREATE TABLE IF NOT EXISTS tags (
@@ -96,7 +99,7 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 
 -- Tokens: API authentication with OAuth-standard scopes.
 --
--- VESTIGIAL as of 0.6.0 (vault#282 Stage 2). Vault is a pure hub
+-- VESTIGIAL as of 0.5.0 (vault#282 Stage 2). Vault is a pure hub
 -- resource-server: it no longer mints (pvt_*) or validates rows in this
 -- table — auth runs through hub-issued JWTs + VAULT_AUTH_TOKEN + legacy YAML
 -- api_keys only. The table is KEPT (not dropped) because migrateVaultKeys
@@ -105,7 +108,7 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 -- leftover rows. A future cosmetic migration may drop it alongside
 -- oauth_clients/oauth_codes. 'tokens list' / 'tokens revoke' (CLI) still
 -- read/delete here for cleanup of leftover rows. See the field docs below for
--- the historical (pre-0.6.0) semantics.
+-- the historical (pre-0.5.0) semantics.
 --
 -- scopes is a whitespace-separated list of granted scopes (OAuth 2.0 §3.3)
 -- — e.g. "vault:read vault:write". Introduced in v12 alongside enforcement;
@@ -140,7 +143,7 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 -- session. Session-pinned list+revoke in manage-token filters on this.
 --
 -- revoked_at (v19) marked soft-revocation of vault-DB tokens. Vestigial
--- post-0.6.0 (vault#282 Stage 2) — the validation path that read it
+-- post-0.5.0 (vault#282 Stage 2) — the validation path that read it
 -- (resolveToken) was removed alongside the pvt_* mint.
 CREATE TABLE IF NOT EXISTS tokens (
   token_hash TEXT PRIMARY KEY,
@@ -183,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;
@@ -420,7 +440,7 @@ export function initSchema(db: Database): void {
   // Migrate v15 → v16: add `vault_name` column to tokens. Existing rows
   // backfilled to NULL ("server-wide / legacy" semantic) — at the time auth
   // accepted NULL for any vault so pre-v16 pvt_* tokens kept working. (pvt_*
-  // validation was dropped at 0.6.0 / vault#282 Stage 2; the column is now
+  // validation was dropped at 0.5.0 / vault#282 Stage 2; the column is now
   // vestigial.) See vault#257.
   migrateToV16(db);
 
@@ -449,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);
@@ -794,7 +819,7 @@ function migrateToV15(db: Database): void {
     // 2. Copy `_schema_defaults` note → schema_mappings.
     const mappingNote = db.prepare(
       "SELECT metadata FROM notes WHERE path = '_schema_defaults'",
-    ).get() as { metadata: string | null } | undefined;
+    ).get() as { metadata: string | null } | null;
     if (mappingNote?.metadata) {
       const insertMapping = db.prepare(
         "INSERT OR IGNORE INTO schema_mappings (schema_name, match_kind, match_value) VALUES (?, ?, ?)",
@@ -852,7 +877,7 @@ function migrateToV15(db: Database): void {
  * "server-wide / legacy" semantic. At the time, `authenticateVaultRequest`
  * accepted NULL for any vault so pre-v16 pvt_* tokens kept working. (pvt_*
  * validation + the `/vault/<name>/tokens` mint route were both removed at
- * 0.6.0 / vault#282 Stage 2 — the column + index are now vestigial; the
+ * 0.5.0 / vault#282 Stage 2 — the column + index are now vestigial; the
  * index still speeds the per-vault `listTokens` cleanup listing.)
  *
  * Wrapped in BEGIN IMMEDIATE / COMMIT (with try/catch ROLLBACK) per the
@@ -1074,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;
   }
@@ -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 !== "{}") {