@openparachute/vault 0.6.0-rc.1 → 0.6.1

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/query-perf-routing.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Regression pins for the 2026-06-10 query-perf work:
+ *
+ *  1. Plain `{field: value}` metadata equality on an INDEXED field now routes
+ *     through the generated column as an index prefilter, keeping the
+ *     original json_extract clause as a residual predicate. Results must be
+ *     IDENTICAL to the JSON-scan path — property-tested here by giving every
+ *     note twin fields (`*_idx` indexed, `*_raw` not) carrying the SAME
+ *     value, then asserting every probe returns the same ids through both.
+ *
+ *  2. Tag membership is a semijoin (no `JOIN note_tags` + `DISTINCT n.*`),
+ *     so a note matched by SEVERAL tags in one query must still appear once.
+ *
+ *  3. `getLinksHydratedForNotes` (the batched include_links path) must agree
+ *     with per-note `getLinksHydrated`, including self-loops and links whose
+ *     endpoints are both on the page.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { queryNotes } from "./notes.js";
+import { getLinksHydrated, getLinksHydratedForNotes } from "./links.js";
+
+let db: Database;
+let store: SqliteStore;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("plain metadata equality: indexed routing is result-identical to the JSON scan", () => {
+  /**
+   * Edge values exercised through BOTH paths. Some of these never match
+   * (today's documented scan behavior — e.g. a JS number binds as its JSON
+   * text and SQLite won't equate INTEGER 5 with TEXT '5'); the pin is that
+   * indexed routing reproduces the scan's verdict EXACTLY, match or not.
+   */
+  const STORED_VALUES: unknown[] = [
+    "pending",
+    "",
+    "5",            // numeric-looking string
+    5,              // JSON number — affinity edge case vs "5"
+    0,
+    -1.5,
+    true,
+    false,
+    null,
+    "naïve-Ünïcode ✨",
+    { nested: { deep: 1 } },
+    ["a", "b"],
+    undefined,      // field absent from metadata
+  ];
+
+  const PROBES: unknown[] = [
+    "pending",
+    "",
+    "5",
+    5,
+    0,
+    -1.5,
+    true,
+    false,
+    null,
+    "naïve-Ünïcode ✨",
+    "missing-everywhere",
+  ];
+
+  async function seedTwinFieldFixture(sqliteType: "string" | "integer") {
+    // `status_idx` is indexed (string) via a tag schema; `status_raw` is not.
+    await store.upsertTagRecord("thing", {
+      fields: { status_idx: { type: sqliteType, indexed: true } },
+    });
+    for (let i = 0; i < STORED_VALUES.length; i++) {
+      const v = STORED_VALUES[i];
+      const metadata: Record<string, unknown> = { seq: i };
+      if (v !== undefined) {
+        metadata.status_idx = v;
+        metadata.status_raw = v;
+      }
+      await store.createNote(`note ${i}`, { tags: ["thing"], metadata });
+    }
+  }
+
+  for (const sqliteType of ["string", "integer"] as const) {
+    it(`every probe matches the same notes through the indexed and scan paths (${sqliteType} column)`, async () => {
+      await seedTwinFieldFixture(sqliteType);
+      for (const probe of PROBES) {
+        const viaIndexed = queryNotes(db, { metadata: { status_idx: probe } }).map((n) => n.id);
+        const viaScan = queryNotes(db, { metadata: { status_raw: probe } }).map((n) => n.id);
+        expect(viaIndexed).toEqual(viaScan);
+      }
+    });
+  }
+
+  it("string probe on the indexed field actually matches (sanity: not vacuous)", async () => {
+    await seedTwinFieldFixture("string");
+    const hits = queryNotes(db, { metadata: { status_idx: "pending" } });
+    expect(hits.length).toBe(1);
+    expect(hits[0]!.metadata?.seq).toBe(0);
+  });
+
+  it("indexed plain equality agrees with the operator form for string values", async () => {
+    await seedTwinFieldFixture("string");
+    for (const probe of ["pending", "", "missing-everywhere", "naïve-Ünïcode ✨"]) {
+      const plain = queryNotes(db, { metadata: { status_idx: probe } }).map((n) => n.id);
+      const operator = queryNotes(db, { metadata: { status_idx: { eq: probe } } }).map((n) => n.id);
+      expect(plain).toEqual(operator);
+    }
+  });
+
+  it("plain equality on a non-indexed field still works (no FIELD_NOT_INDEXED error)", async () => {
+    await store.createNote("a", { metadata: { color: "blue" } });
+    await store.createNote("b", { metadata: { color: "red" } });
+    const hits = queryNotes(db, { metadata: { color: "blue" } });
+    expect(hits.length).toBe(1);
+  });
+});
+
+describe("tag semijoin: no duplicate rows without DISTINCT", () => {
+  it("a note carrying several matching tags appears once under tag_match=any", async () => {
+    await store.upsertTagRecord("capture/voice", { parent_names: ["capture"] });
+    await store.upsertTagRecord("capture/text", { parent_names: ["capture"] });
+    // Tagged with the parent AND two children — the old JOIN produced 3 rows.
+    const note = await store.createNote("multi", {
+      tags: ["capture", "capture/voice", "capture/text"],
+    });
+    await store.createNote("single", { tags: ["capture/voice"] });
+
+    const viaExpansion = await store.queryNotes({ tags: ["capture"] });
+    expect(viaExpansion.map((n) => n.id).filter((id) => id === note.id).length).toBe(1);
+    expect(viaExpansion.length).toBe(2);
+
+    const viaAny = await store.queryNotes({
+      tags: ["capture", "capture/voice", "capture/text"],
+      tagMatch: "any",
+    });
+    expect(viaAny.map((n) => n.id).filter((id) => id === note.id).length).toBe(1);
+  });
+
+  it("tag_match=all still requires every input tag", async () => {
+    const both = await store.createNote("both", { tags: ["a", "b"] });
+    await store.createNote("only-a", { tags: ["a"] });
+    const hits = await store.queryNotes({ tags: ["a", "b"], tagMatch: "all" });
+    expect(hits.map((n) => n.id)).toEqual([both.id]);
+  });
+});
+
+describe("getLinksHydratedForNotes agrees with per-note getLinksHydrated", () => {
+  it("matches per-note hydration across self-loops, shared links, and isolated notes", async () => {
+    const a = await store.createNote("a", { tags: ["x"] });
+    const b = await store.createNote("b", { tags: ["y"], metadata: { k: 1 } });
+    const c = await store.createNote("c", { path: "Notes/c" });
+    const lonely = await store.createNote("lonely");
+
+    await store.createLink(a.id, b.id, "mentions");      // both endpoints on page
+    await store.createLink(b.id, a.id, "replies");       // reverse direction
+    await store.createLink(a.id, a.id, "self");          // self-loop
+    await store.createLink(c.id, a.id, "references");    // inbound from page note
+    await store.createLink(b.id, c.id, "cites", { via: "test" });
+
+    const pageIds = [a.id, b.id, c.id, lonely.id];
+    const batch = getLinksHydratedForNotes(db, pageIds);
+
+    for (const id of pageIds) {
+      const single = getLinksHydrated(db, id);
+      const batched = batch.get(id)!;
+      const key = (l: { sourceId: string; targetId: string; relationship: string }) =>
+        `${l.sourceId}→${l.targetId}:${l.relationship}`;
+      // Same link set per note…
+      expect(batched.map(key).sort()).toEqual(single.map(key).sort());
+      // …ordered newest-first like the single-note SQL.
+      const stamps = batched.map((l) => l.createdAt);
+      expect([...stamps].sort().reverse()).toEqual(stamps);
+      // …with identical hydrated summaries (path, tags, metadata).
+      const summaries = (ls: typeof single) =>
+        new Map(ls.map((l) => [key(l), JSON.stringify([l.sourceNote, l.targetNote])]));
+      expect(summaries(batched)).toEqual(summaries(single));
+    }
+
+    // The self-loop appears once in a's list (not duplicated by the
+    // source/target double-walk), matching the single-note query.
+    const selfLoops = batch.get(a.id)!.filter((l) => l.sourceId === a.id && l.targetId === a.id);
+    expect(selfLoops.length).toBe(1);
+
+    expect(batch.get(lonely.id)).toEqual([]);
+  });
+});
+
+describe("v22 keyset index", () => {
+  it("exists after initSchema and covers (updated_at, id)", () => {
+    const row = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='index' AND name='idx_notes_updated'")
+      .get();
+    expect(row).toBeTruthy();
+    const plan = db
+      .prepare(
+        `EXPLAIN QUERY PLAN
+         SELECT n.id FROM notes n
+         WHERE (n.updated_at > ? OR (n.updated_at = ? AND n.id > ?))
+         ORDER BY n.updated_at ASC, n.id ASC LIMIT 10`,
+      )
+      .all("2025-01-01", "2025-01-01", "x") as { detail: string }[];
+    const details = plan.map((r) => r.detail).join(" | ");
+    expect(details).toContain("idx_notes_updated");
+    expect(details).not.toContain("TEMP B-TREE");
+  });
+});

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 = 22;
 
 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,16 @@ 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);
+
+  // Migrate v21 → v22: composite index notes(updated_at, id) backing cursor
+  // keyset pagination and date_filter on updated_at — both were full table
+  // scans. See the 2026-06-10 query-perf measurements.
+  migrateToV22(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -794,7 +824,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 +882,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 +1104,52 @@ 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
+    )
+  `);
+}
+
+/**
+ * Migrate v21 → v22: composite B-tree on notes(updated_at, id).
+ *
+ * Two query shapes ride it (2026-06-10 perf measurements — both were full
+ * table scans + temp-B-tree sorts before):
+ *
+ *   1. Cursor keyset pagination (vault#313): the predicate
+ *      `updated_at > ? OR (updated_at = ? AND id > ?)` with
+ *      `ORDER BY updated_at ASC, id ASC` matches the composite key exactly,
+ *      so a "since last checked" poll seeks straight to the watermark and
+ *      streams in order — no scan, no sort.
+ *   2. `date_filter: { field: "updated_at" }` range queries (incremental
+ *      rebuild flows, vault#285 1.5).
+ *
+ * Lives here (not SCHEMA_SQL) following the idx_tokens_vault_name precedent:
+ * migrations run after every column-shape change, so the index statement
+ * never races an older table shape. Fresh vaults reach this through the
+ * same initSchema path — CREATE INDEX IF NOT EXISTS is idempotent.
+ */
+function migrateToV22(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+  db.exec("CREATE INDEX IF NOT EXISTS idx_notes_updated ON notes(updated_at, id)");
+}
+
 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;