@openparachute/vault 0.5.3-rc.3 → 0.6.0

package/src/live-match.ts

@@ -0,0 +1,310 @@
+/**
+ * In-process query matcher for live subscriptions (live-query SSE — design
+ * `design/2026-06-08-live-query-sse.md`).
+ *
+ * The snapshot path evaluates a `QueryOpts` against the DB via the SQL query
+ * engine (`core/src/notes.ts queryNotes`). The live path can't go back to the
+ * DB for every mutation — the changed note is already in hand from the
+ * post-commit hook — so this module re-implements the *supported subset* of
+ * the query predicate against a single in-memory `Note`.
+ *
+ * **Predicate parity is the contract.** For any supported query, the set of
+ * notes the snapshot SQL returns MUST equal the set this matcher accepts.
+ * `subscribe.test.ts` enforces that over a seeded corpus. Every clause below
+ * is written to mirror the exact SQL semantics in `queryNotes`:
+ *
+ *   - `tags` ("all"/"any") with descendant expansion — mirrors the per-input
+ *     `_tagsExpanded` JOINs (each input tag matches the input OR any declared
+ *     descendant). Expansion is resolved ONCE at subscribe time (see
+ *     `buildLiveMatcher`) and frozen into the matcher, exactly as the engine
+ *     freezes it for the snapshot query.
+ *   - `excludeTags` — raw exact-name match (engine does NOT expand excludes).
+ *   - `path` — case-insensitive exact (engine: `n.path = ? COLLATE NOCASE`).
+ *   - `pathPrefix` — prefix (engine: `n.path LIKE prefix || '%'`).
+ *   - `extension` — lower-cased, default "md" (engine: `LOWER(n.extension)`),
+ *     a note with no extension is treated as "md".
+ *   - `metadata` operator objects (eq/ne/gt/gte/lt/lte/in/not_in/exists) +
+ *     primitive exact-match — mirrors `buildOperatorClause` / the json_extract
+ *     shorthand. NULL-aware exactly like the SQL (`ne`/`not_in` match the
+ *     field-absent row; `eq null` matches absence).
+ *
+ *   - `hasTags` (presence) — `note.tags?.length > 0`, trivial + parity-safe.
+ *
+ * **Unsupported (rejected upstream with 400, never reach the matcher):**
+ * `search` (FTS) and `near` (graph BFS) — not evaluable against a single note;
+ * `hasLinks` — needs the `links` table (not on the in-hand note); date filters
+ * (`dateFrom`/`dateTo`/`dateFilter`) — parity risk + some need indexed columns;
+ * `cursor` — paging is meaningless for a live set. The subscribe route returns
+ * 400 for these BEFORE a subscription is created (see
+ * `unsupportedSubscriptionReason` + the route's raw-param checks).
+ *
+ * **Ignored (irrelevant to set membership):** `orderBy`, `limit`, `offset`,
+ * `ids`. The route strips `limit`/`offset` from the snapshot query so the
+ * snapshot is the COMPLETE matching set (parity with the unbounded matcher).
+ */
+
+import type { Note, QueryOpts, Store } from "../core/src/types.ts";
+import { SUPPORTED_OPS } from "../core/src/query-operators.ts";
+
+const OPS_SET: ReadonlySet<string> = new Set<string>(SUPPORTED_OPS);
+
+/**
+ * Frozen, pre-resolved form of a `QueryOpts` for fast per-note matching.
+ * Tag descendant expansion (a DB read) is done once here, not per event.
+ */
+export interface LiveMatcher {
+  /** The original supported opts (for diagnostics / parity tests). */
+  readonly opts: QueryOpts;
+  /**
+   * Per-input-tag expanded sets: `tagSets[i]` = `{tags[i]} ∪ descendants`.
+   * Mirrors `_tagsExpanded` in the engine. Empty when no `tags` filter.
+   * A note matches under "all" iff it carries ≥1 tag from EACH set; under
+   * "any" iff it carries ≥1 tag from the UNION.
+   */
+  readonly tagSets: string[][];
+  readonly tagMatch: "all" | "any";
+  readonly excludeTags: string[];
+  match(note: Note): boolean;
+}
+
+/**
+ * Query shapes a live subscription can't evaluate against a single note.
+ * The route layer rejects these with 400 before creating a subscription.
+ */
+export function unsupportedSubscriptionReason(opts: QueryOpts): string | null {
+  // `search` / `near` are parsed/handled by the notes route separately; the
+  // subscribe route detects them from raw query params. These guards catch the
+  // remaining shapes that the matcher can't faithfully evaluate against a
+  // single in-hand note (so snapshot and live would disagree).
+  if (opts.cursor) {
+    return "cursor pagination is not supported for live subscriptions";
+  }
+  if (opts.hasLinks !== undefined) {
+    return "has_links is not supported for live subscriptions (requires the links table)";
+  }
+  if (opts.dateFilter || opts.dateFrom || opts.dateTo) {
+    return "date filters are not supported for live subscriptions";
+  }
+  return null;
+}
+
+function metaValue(note: Note, key: string): unknown {
+  const m = note.metadata;
+  if (!m || typeof m !== "object") return undefined;
+  return (m as Record<string, unknown>)[key];
+}
+
+/**
+ * Compare two primitives the way SQLite's generated `meta_<field>` column
+ * would for ordering operators. Values stored via the indexed column are
+ * primitives; we compare numbers numerically and strings lexically, matching
+ * SQLite's type affinity for a column holding the JSON-extracted scalar.
+ */
+function cmp(a: unknown, b: unknown): number | null {
+  if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0;
+  // Booleans compare as their numeric form (SQLite stores 1/0).
+  const an = typeof a === "boolean" ? (a ? 1 : 0) : a;
+  const bn = typeof b === "boolean" ? (b ? 1 : 0) : b;
+  if (typeof an === "number" && typeof bn === "number") return an < bn ? -1 : an > bn ? 1 : 0;
+  const as = String(an);
+  const bs = String(bn);
+  return as < bs ? -1 : as > bs ? 1 : 0;
+}
+
+/** Loose equality mirroring the json_extract shorthand + operator `eq`. */
+function looseEq(actual: unknown, expected: unknown): boolean {
+  if (actual === expected) return true;
+  // Numbers vs numeric strings: the engine's operator path binds the raw
+  // value to an indexed numeric column, so `5` and `5` match; the shorthand
+  // path stringifies. Normalize via string compare as a backstop.
+  if (actual == null || expected == null) return actual === expected;
+  if (typeof actual === "boolean" || typeof expected === "boolean") {
+    return (actual ? 1 : 0) === (expected ? 1 : 0) || String(actual) === String(expected);
+  }
+  return String(actual) === String(expected);
+}
+
+function evalOperatorObject(actual: unknown, opObj: Record<string, unknown>): boolean {
+  for (const [op, expected] of Object.entries(opObj)) {
+    switch (op) {
+      case "eq":
+        if (expected === null) {
+          if (actual !== undefined && actual !== null) return false;
+        } else if (!looseEq(actual, expected)) {
+          return false;
+        }
+        break;
+      case "ne":
+        // SQL: (col IS NULL OR col <> ?) — absent field passes; equal fails.
+        if (expected === null) {
+          if (actual === undefined || actual === null) return false;
+        } else if (actual !== undefined && actual !== null && looseEq(actual, expected)) {
+          return false;
+        }
+        break;
+      case "gt":
+      case "gte":
+      case "lt":
+      case "lte": {
+        // SQL comparison operators yield NULL (→ excluded) when the column
+        // is NULL/absent.
+        if (actual === undefined || actual === null) return false;
+        const c = cmp(actual, expected);
+        if (c === null) return false;
+        if (op === "gt" && !(c > 0)) return false;
+        if (op === "gte" && !(c >= 0)) return false;
+        if (op === "lt" && !(c < 0)) return false;
+        if (op === "lte" && !(c <= 0)) return false;
+        break;
+      }
+      case "in": {
+        if (!Array.isArray(expected)) return false;
+        if (expected.length === 0) return false; // engine emits `0`
+        if (actual === undefined || actual === null) return false;
+        if (!expected.some((v) => looseEq(actual, v))) return false;
+        break;
+      }
+      case "not_in": {
+        if (!Array.isArray(expected)) return false;
+        if (expected.length === 0) break; // engine emits `1` (no-op pass)
+        // SQL: (col IS NULL OR col NOT IN (...)) — absent passes.
+        if (actual === undefined || actual === null) break;
+        if (expected.some((v) => looseEq(actual, v))) return false;
+        break;
+      }
+      case "exists": {
+        const present = actual !== undefined && actual !== null;
+        if (expected === true && !present) return false;
+        if (expected === false && present) return false;
+        break;
+      }
+      default:
+        // Unknown operator — the snapshot path would have thrown
+        // UNKNOWN_OPERATOR at query time, so this never matches.
+        return false;
+    }
+  }
+  return true;
+}
+
+/** True iff every key of `value` is a supported operator (operator-object). */
+function isOperatorObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const keys = Object.keys(value as object);
+  if (keys.length === 0) return false;
+  return keys.every((k) => OPS_SET.has(k));
+}
+
+/**
+ * Resolve a `QueryOpts` into a frozen `LiveMatcher`, expanding tag descendants
+ * once via the store (the same hierarchy the snapshot query uses). Call at
+ * subscribe time; the returned matcher is pure + sync for per-event use.
+ */
+export async function buildLiveMatcher(store: Store, opts: QueryOpts): Promise<LiveMatcher> {
+  const tags = opts.tags ?? [];
+  const tagMatch: "all" | "any" = opts.tagMatch ?? "all";
+  // Per-input expansion along the SAME axis the snapshot query uses
+  // (vault tag `expand` axis). `opts.expand` (default "subtypes") MUST be
+  // threaded through here so the live matcher and the snapshot query engine
+  // lower the IDENTICAL expansion — otherwise a subscription's snapshot and
+  // its live events would disagree on which notes match. `expandTags` already
+  // includes each input tag.
+  const tagSets: string[][] = [];
+  for (const t of tags) {
+    const set = await store.expandTags([t], opts.expand);
+    // Be defensive: ensure the root is present (expandTags always includes it
+    // for non-empty input, but the contract should not rely on it here).
+    set.add(t);
+    tagSets.push(Array.from(set));
+  }
+  const excludeTags = opts.excludeTags ?? [];
+
+  const matcher: LiveMatcher = {
+    opts,
+    tagSets,
+    tagMatch,
+    excludeTags,
+    match(note: Note): boolean {
+      return matchAgainst(note, opts, tagSets, tagMatch, excludeTags);
+    },
+  };
+  return matcher;
+}
+
+function matchAgainst(
+  note: Note,
+  opts: QueryOpts,
+  tagSets: string[][],
+  tagMatch: "all" | "any",
+  excludeTags: string[],
+): boolean {
+  const noteTags = note.tags ?? [];
+
+  // ---- tags ----
+  if (tagSets.length > 0) {
+    if (tagMatch === "any") {
+      const union = new Set(tagSets.flat());
+      if (!noteTags.some((t) => union.has(t))) return false;
+    } else {
+      // "all": for each input tag's expanded set, the note must carry ≥1.
+      for (const set of tagSets) {
+        if (set.length === 0) continue;
+        const s = new Set(set);
+        if (!noteTags.some((t) => s.has(t))) return false;
+      }
+    }
+  }
+
+  // ---- excludeTags (raw exact, no expansion — mirrors engine) ----
+  for (const ex of excludeTags) {
+    if (noteTags.includes(ex)) return false;
+  }
+
+  // ---- hasTags (presence) — ignored by the engine when a `tags` filter is
+  // also set (the tag filter already constrains to tagged notes), so mirror
+  // that: only apply when there's no `tags` filter. See queryNotes
+  // `filterByTags` short-circuit.
+  if (opts.hasTags !== undefined && tagSets.length === 0) {
+    const has = noteTags.length > 0;
+    if (opts.hasTags !== has) return false;
+  }
+
+  // ---- path (case-insensitive exact) ----
+  if (opts.path) {
+    if (!note.path || note.path.toLowerCase() !== opts.path.toLowerCase()) return false;
+  }
+
+  // ---- pathPrefix (case-insensitive — the engine uses `LIKE prefix || '%'`,
+  // and SQLite LIKE is ASCII-case-insensitive by default) ----
+  if (opts.pathPrefix) {
+    if (!note.path || !note.path.toLowerCase().startsWith(opts.pathPrefix.toLowerCase())) return false;
+  }
+
+  // ---- extension (lower-cased; default "md") ----
+  if (opts.extension !== undefined) {
+    const exts = Array.isArray(opts.extension) ? opts.extension : [opts.extension];
+    const cleaned = exts
+      .filter((e): e is string => typeof e === "string" && e.length > 0)
+      .map((e) => e.toLowerCase());
+    if (cleaned.length > 0) {
+      const noteExt = (note.extension ?? "md").toLowerCase();
+      if (!cleaned.includes(noteExt)) return false;
+    }
+  }
+
+  // ---- metadata ----
+  if (opts.metadata) {
+    for (const [key, value] of Object.entries(opts.metadata)) {
+      const actual = metaValue(note, key);
+      if (isOperatorObject(value)) {
+        if (!evalOperatorObject(actual, value)) return false;
+      } else {
+        // Primitive exact-match (json_extract shorthand). The engine compares
+        // the JSON-extracted scalar against the string/JSON form.
+        if (!looseEq(actual, value)) return false;
+      }
+    }
+  }
+
+  return true;
+}

package/src/routes.ts

@@ -11,7 +11,8 @@
  * and the Request, and returns a Response.
  */
 
-import type { Store, Note } from "../core/src/types.ts";
+import type { Store, Note, QueryOpts } from "../core/src/types.ts";
+import { TAG_EXPAND_MODES, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
 import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import { attachValidationStatus } from "../core/src/mcp.ts";
@@ -46,7 +47,7 @@ import {
 } from "../core/src/expand.ts";
 import { join, extname, normalize } from "path";
 import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
-import { assetsDir } from "./config.ts";
+import { assetsDir, readGlobalConfig, readVaultConfig } from "./config.ts";
 import { shouldAutoTranscribe } from "./auto-transcribe.ts";
 // usage.ts imports `assetsDir` from config.ts (neutral ground), so this import
 // of invalidateUsageCache does NOT form a cycle — routes.ts → usage.ts only.
@@ -435,6 +436,124 @@ function parseMetadataJsonAlias(url: URL): {
   return { metadata: parsed as Record<string, unknown> };
 }
 
+/**
+ * Parse + validate the `?expand=` tag-expansion axis (vault tag `expand` axis).
+ * Shared by `parseNotesQueryOpts` (structured + subscribe) AND the full-text
+ * search branch of `handleNotes` (which bypasses `parseNotesQueryOpts`), so the
+ * enum lives in exactly one place and `GET /notes?search=...&expand=bogus` is
+ * validated identically to the structured path.
+ *
+ * Returns `{ expand }` (undefined when absent/empty → store defaults to
+ * "subtypes") or `{ error }` (a 400 Response) on an unknown value.
+ */
+export function parseExpandParam(url: URL): { expand?: TagExpandMode; error?: Response } {
+  const expandParam = parseQuery(url, "expand");
+  if (expandParam === null || expandParam === "") return {};
+  if (!(TAG_EXPAND_MODES as readonly string[]).includes(expandParam)) {
+    return {
+      error: json(
+        {
+          error: `invalid \`expand\` value "${expandParam}" — must be one of ${TAG_EXPAND_MODES.map((m) => `"${m}"`).join(", ")}. Omit for the default ("subtypes": parent_names descendants).`,
+          code: "INVALID_QUERY",
+        },
+        400,
+      ),
+    };
+  }
+  return { expand: expandParam as TagExpandMode };
+}
+
+/**
+ * Parse the shared notes-query parameters (tags / excludeTags / path /
+ * pathPrefix / extension / metadata filters / date filters / sort / paging /
+ * cursor) into a `QueryOpts`, plus flags for the query shapes that the live
+ * subscription endpoint must reject (`search`, `near`, `cursor`).
+ *
+ * Factored out of `handleNotesInner`'s structured-query branch so the
+ * `/subscribe` route evaluates the SAME predicate the snapshot query does —
+ * predicate parity by construction, not copy-paste. `handleNotesInner` keeps
+ * its own inline parsing for the single-note (`id`) and full-text (`search`)
+ * branches; this helper covers the structured-query shape both endpoints share.
+ *
+ * Returns `{ error }` (a 400 Response) on a malformed metadata filter, exactly
+ * as the inline code did. `hasSearch` is surfaced from the raw `search` param
+ * (this helper does not itself build a search query — the caller routes that).
+ */
+export function parseNotesQueryOpts(url: URL): {
+  queryOpts?: QueryOpts;
+  hasSearch: boolean;
+  hasNear: boolean;
+  hasCursor: boolean;
+  error?: Response;
+} {
+  const hasSearch = parseQuery(url, "search") !== null && parseQuery(url, "search") !== "";
+  const hasNear = parseQuery(url, "near[note_id]") !== null;
+  const cursorParam = parseQuery(url, "cursor");
+  const hasCursor = cursorParam !== null && cursorParam !== "";
+
+  const tags = parseQueryList(url, "tag");
+  const bracket = parseMetaBrackets(url);
+  if (bracket.error) return { hasSearch, hasNear, hasCursor, error: bracket.error };
+  const metadataAlias = parseMetadataJsonAlias(url);
+  if (metadataAlias.error) return { hasSearch, hasNear, hasCursor, error: metadataAlias.error };
+  if (metadataAlias.metadata && bracket.metadata) {
+    return {
+      hasSearch,
+      hasNear,
+      hasCursor,
+      error: json(
+        {
+          error: "pass metadata filters as either the JSON `metadata=` param or bracket `meta[field][op]=` form, not both.",
+          code: "INVALID_QUERY",
+        },
+        400,
+      ),
+    };
+  }
+
+  // Tag-expansion axis (vault tag `expand` axis). Optional; absent →
+  // "subtypes" (resolved at the store, kept undefined here so it stays
+  // byte-identical to pre-axis behavior). Unknown value → 400 via the shared
+  // helper (same shape the search branch uses).
+  const expandParsed = parseExpandParam(url);
+  if (expandParsed.error) return { hasSearch, hasNear, hasCursor, error: expandParsed.error };
+  const expand = expandParsed.expand;
+
+  const queryOpts: QueryOpts = {
+    tags,
+    tagMatch: (parseQuery(url, "tag_match") as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
+    expand,
+    excludeTags: parseQueryList(url, "exclude_tag"),
+    hasTags: parseBoolOrUndef(parseQuery(url, "has_tags")),
+    hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
+    path: parseQuery(url, "path") ?? undefined,
+    pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
+    extension: parseExtensionFilter(url),
+    metadata: bracket.metadata ?? metadataAlias.metadata,
+    ...(bracket.dateFilter
+      ? { dateFilter: bracket.dateFilter }
+      : parseQuery(url, "date_field")
+        ? {
+            dateFilter: {
+              field: parseQuery(url, "date_field")!,
+              from: parseQuery(url, "date_from") ?? undefined,
+              to: parseQuery(url, "date_to") ?? undefined,
+            },
+          }
+        : {
+            dateFrom: parseQuery(url, "date_from") ?? undefined,
+            dateTo: parseQuery(url, "date_to") ?? undefined,
+          }),
+    sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
+    orderBy: parseQuery(url, "order_by") ?? undefined,
+    limit: parseInt10(parseQuery(url, "limit")) ?? 50,
+    offset: parseInt10(parseQuery(url, "offset")),
+    cursor: cursorParam ?? undefined,
+  };
+
+  return { queryOpts, hasSearch, hasNear, hasCursor };
+}
+
 /**
  * Parse include_metadata query param.
  * - absent/null → undefined (all metadata, default)
@@ -634,7 +753,17 @@ async function handleNotesInner(
       if (search) {
         const searchTags = parseQueryList(url, "tag");
         const limit = parseInt10(parseQuery(url, "limit")) ?? 50;
-        const rawResults = await store.searchNotes(search, { tags: searchTags, limit });
+        // Tag-expansion axis (vault tag `expand` axis). This branch bypasses
+        // `parseNotesQueryOpts`, so validate `?expand=` here too — otherwise
+        // `GET /notes?search=x&expand=bogus` would silently ignore the bad
+        // value. The validated mode is threaded into the search tag-narrowing.
+        const tagExpand = parseExpandParam(url);
+        if (tagExpand.error) return tagExpand.error;
+        const rawResults = await store.searchNotes(search, {
+          tags: searchTags,
+          limit,
+          expand: tagExpand.expand,
+        });
         // Tag-scope: drop any result the token isn't permitted to see. Filter
         // happens after the store query so an empty post-filter list still
         // returns 200 [] (consistent with "no matches"), not 403.
@@ -694,36 +823,16 @@ async function handleNotesInner(
       // Surface asymmetry: REST flattens to a query string; MCP takes a
       // nested `date_filter: { field, from, to }` object directly. Both
       // lower to the same store-level `dateFilter` shape.
-      const tags = parseQueryList(url, "tag");
-      const bracket = parseMetaBrackets(url);
-      if (bracket.error) return bracket.error;
-      // `?metadata=<json>` alias — the JSON-object form of the metadata
-      // filter, symmetric with the nested object MCP forwards. Before this,
-      // a `metadata=` param was silently dropped (the bracket grammar never
-      // matched it), so the query returned ALL tag-matching notes.
-      const metadataAlias = parseMetadataJsonAlias(url);
-      if (metadataAlias.error) return metadataAlias.error;
-      // Reject "both forms" loudly. If a caller passes BOTH the JSON
-      // `metadata=` param AND any `meta[...]` bracket param, there's no
-      // well-defined merge and silently picking a winner is exactly the
-      // class of bug we're fixing. Symmetric with the mixed shorthand/
-      // operator rejection inside parseMetaBrackets. Guard stays narrow —
-      // only the named `metadata` param triggers it.
-      if (metadataAlias.metadata && bracket.metadata) {
-        return json(
-          {
-            error: "pass metadata filters as either the JSON `metadata=` param or bracket `meta[field][op]=` form, not both.",
-            code: "INVALID_QUERY",
-          },
-          400,
-        );
-      }
-      // Opaque cursor for "since last checked" agent loops (vault#313).
-      // When present, switches the response shape to {notes, next_cursor}
-      // and routes through queryNotesPaged for keyset pagination. Mutually
-      // exclusive with the `near` graph-neighborhood scope (rebuilding the
-      // neighborhood per page isn't stable) — rejected below.
+      // Structured-query parsing is shared with the live `/subscribe` route
+      // (see `parseNotesQueryOpts`) so both endpoints lower an identical query
+      // string to the same `QueryOpts` — predicate parity by construction.
+      const parsed = parseNotesQueryOpts(url);
+      if (parsed.error) return parsed.error;
+      const queryOpts = parsed.queryOpts!;
       const cursorParam = parseQuery(url, "cursor");
+      // Opaque cursor for "since last checked" agent loops (vault#313) is
+      // mutually exclusive with the `near` graph-neighborhood scope (rebuilding
+      // the neighborhood per page isn't stable).
       const nearNoteIdEarly = parseQuery(url, "near[note_id]");
       if (cursorParam && nearNoteIdEarly) {
         return json(
@@ -736,50 +845,6 @@ async function handleNotesInner(
       }
       let results: Note[];
       let nextCursor: string | null = null;
-      const queryOpts = {
-        tags,
-        tagMatch: (parseQuery(url, "tag_match") as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
-        excludeTags: parseQueryList(url, "exclude_tag"),
-        hasTags: parseBoolOrUndef(parseQuery(url, "has_tags")),
-        hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
-        path: parseQuery(url, "path") ?? undefined,
-        pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
-        // Extension filter (vault#328). Accepts repeated `extension=`
-        // params for the array form: `?extension=csv&extension=yaml`.
-        // `parseQueryList` already returns undefined when no params
-        // are present, so the filter is silently skipped on a plain
-        // GET without the extension query.
-        extension: parseExtensionFilter(url),
-        // Bracket form and JSON-alias form are mutually exclusive (guarded
-        // above), so at most one of these is set.
-        metadata: bracket.metadata ?? metadataAlias.metadata,
-        // Date-range precedence chain (highest to lowest):
-        //   1. Bracket-style `meta[created_at][gte]=…` (canonical).
-        //   2. Flat `date_field=…&date_from=…&date_to=…` (deprecated).
-        //   3. Legacy `date_from=…&date_to=…` (no date_field, deprecated)
-        //      — filters on `n.created_at` by definition.
-        // The engine rejects combinations of `dateFilter` with the legacy
-        // `dateFrom`/`dateTo`, so we never set both shapes simultaneously.
-        ...(bracket.dateFilter
-          ? { dateFilter: bracket.dateFilter }
-          : parseQuery(url, "date_field")
-            ? {
-                dateFilter: {
-                  field: parseQuery(url, "date_field")!,
-                  from: parseQuery(url, "date_from") ?? undefined,
-                  to: parseQuery(url, "date_to") ?? undefined,
-                },
-              }
-            : {
-                dateFrom: parseQuery(url, "date_from") ?? undefined,
-                dateTo: parseQuery(url, "date_to") ?? undefined,
-              }),
-        sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
-        orderBy: parseQuery(url, "order_by") ?? undefined,
-        limit: parseInt10(parseQuery(url, "limit")) ?? 50,
-        offset: parseInt10(parseQuery(url, "offset")),
-        cursor: cursorParam ?? undefined,
-      };
       try {
         if (cursorParam) {
           const page = await store.queryNotesPaged(queryOpts);
@@ -1079,7 +1144,14 @@ async function handleNotesInner(
       // Explicit `transcribe: true` wins — if the caller asked, we honor that
       // regardless of the auto-transcribe toggle (back-compat).
       const explicitOptIn = body.transcribe === true;
-      const autoOptIn = !explicitOptIn && shouldAutoTranscribe(body.mimeType);
+      // Per-vault auto-transcribe: read THIS vault's `auto_transcribe.enabled`
+      // (vault.yaml) and pass it as the precedence-winning toggle. A vault that
+      // set its own value uses it; one that left it unset falls through to the
+      // global toggle inside `shouldAutoTranscribe` (per-vault → global → true).
+      const perVaultEnabled = vault
+        ? readVaultConfig(vault)?.auto_transcribe?.enabled
+        : undefined;
+      const autoOptIn = !explicitOptIn && shouldAutoTranscribe(body.mimeType, { perVaultEnabled });
       const attMeta = (explicitOptIn || autoOptIn)
         ? {
             transcribe_status: "pending" as const,
@@ -1895,16 +1967,36 @@ type VaultConfigLike = {
   name: string;
   description?: string;
   audio_retention?: "keep" | "until_transcribed" | "never";
+  auto_transcribe?: { enabled?: boolean };
 };
 
 const VALID_AUDIO_RETENTION = ["keep", "until_transcribed", "never"] as const;
 
+/**
+ * Resolve the effective auto-transcribe toggle for a vault's GET response, the
+ * SAME resolution `shouldAutoTranscribe` uses at the decision point:
+ * **per-vault → global → true**. A vault that set its own `auto_transcribe`
+ * shows that; one that left it unset shows the server-wide default (itself
+ * default-ON). This keeps the GET in lock-step with what the worker actually
+ * does, with no field-name drift.
+ */
+function resolveAutoTranscribeEnabled(vaultConfig: VaultConfigLike): boolean {
+  return (
+    vaultConfig.auto_transcribe?.enabled
+    ?? readGlobalConfig().auto_transcribe?.enabled
+    ?? true
+  );
+}
+
 function vaultResponse(vaultConfig: VaultConfigLike): Record<string, unknown> {
   return {
     name: vaultConfig.name,
     description: vaultConfig.description ?? null,
     config: {
       audio_retention: vaultConfig.audio_retention ?? "keep",
+      auto_transcribe: {
+        enabled: resolveAutoTranscribeEnabled(vaultConfig),
+      },
     },
   };
 }
@@ -1928,7 +2020,7 @@ export async function handleVault(
   if (req.method === "PATCH") {
     const body = await req.json() as {
       description?: string;
-      config?: { audio_retention?: string };
+      config?: { audio_retention?: string; auto_transcribe?: { enabled?: unknown } };
     };
     let dirty = false;
 
@@ -1952,6 +2044,28 @@ export async function handleVault(
       dirty = true;
     }
 
+    // auto_transcribe.enabled — PER-VAULT toggle persisted to THIS vault's
+    // vault.yaml (via `persist`, the same writeVaultConfig path as
+    // description/audio_retention). Flipping it for vault X affects only X;
+    // scribe's "link to vault X" PATCHes this and never touches other vaults.
+    // The worker reads the same per-vault field (per-vault → global → true).
+    // Validate the shape: when `auto_transcribe` is present it must carry a
+    // boolean `enabled`.
+    if (body.config?.auto_transcribe !== undefined) {
+      const enabled = body.config.auto_transcribe?.enabled;
+      if (typeof enabled !== "boolean") {
+        return json(
+          {
+            error: "invalid_auto_transcribe",
+            message: "auto_transcribe.enabled must be a boolean",
+          },
+          400,
+        );
+      }
+      vaultConfig.auto_transcribe = { ...vaultConfig.auto_transcribe, enabled };
+      dirty = true;
+    }
+
     if (dirty && persist) persist();
     return json(vaultResponse(vaultConfig));
   }