@openparachute/vault 0.2.3 → 0.3.0-rc.1

package/core/src/mcp.ts

@@ -4,6 +4,8 @@ import * as noteOps from "./notes.js";
 import { filterMetadata } from "./notes.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
+import type { TagFieldSchema } from "./tag-schemas.js";
+import * as indexedFieldOps from "./indexed-fields.js";
 import {
   expandContent,
   DEFAULT_EXPAND_DEPTH,
@@ -101,10 +103,16 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           },
           tag_match: { type: "string", enum: ["any", "all"], description: "How to match multiple tags: 'any' (OR, default) or 'all' (AND)" },
           exclude_tags: { type: "array", items: { type: "string" }, description: "Exclude notes with these tags" },
+          has_tags: { type: "boolean", description: "Presence filter: true = only notes with at least one tag; false = only untagged notes. Ignored when `tag` is set." },
+          has_links: { type: "boolean", description: "Presence filter: true = only notes with at least one inbound or outbound link; false = only orphaned notes (no links in either direction)." },
           path: { type: "string", description: "Exact path match (case-insensitive)" },
           path_prefix: { type: "string", description: "Path prefix match (e.g., 'Projects/')" },
           search: { type: "string", description: "Full-text search query" },
-          metadata: { type: "object", description: "Filter by metadata values (exact match per key)" },
+          metadata: {
+            type: "object",
+            description: "Filter by metadata values. Each value is either a primitive (exact match, scans JSON) or an operator object: `{eq|ne|gt|gte|lt|lte|in|not_in|exists: value}`. Operator objects require the field to be declared `indexed: true` in a tag schema — they route through the backing B-tree index. Multiple operators on one field AND together (e.g. `{gt: 5, lt: 10}`). `in`/`not_in` take arrays; `exists` takes a boolean.",
+          },
+          order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. Direction is taken from `sort` (default 'asc'); `created_at` is appended as a stable tiebreaker." },
           date_from: { type: "string", description: "Start date (ISO, inclusive)" },
           date_to: { type: "string", description: "End date (ISO, exclusive)" },
           near: {
@@ -201,12 +209,15 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             tags,
             tagMatch: (params.tag_match as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
             excludeTags: params.exclude_tags as string[] | undefined,
+            hasTags: params.has_tags as boolean | undefined,
+            hasLinks: params.has_links as boolean | undefined,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
             metadata: params.metadata as Record<string, unknown> | undefined,
             dateFrom: params.date_from as string | undefined,
             dateTo: params.date_to as string | undefined,
             sort: params.sort as "asc" | "desc" | undefined,
+            orderBy: params.order_by as string | undefined,
             limit: (params.limit as number) ?? 50,
             offset: params.offset as number | undefined,
           });
@@ -348,7 +359,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 - \`links: { add: [{ target, relationship }], remove: [{ target, relationship }] }\` — add/remove links
 - When removing a wikilink-type link, \`[[brackets]]\` are also removed from content.
 - For batch: pass a \`notes\` array, each with an \`id\` field.
-- Optimistic concurrency: pass \`if_updated_at\` with the \`updated_at\` value you last read. The update is rejected with a conflict error if the note has changed since. Re-read the note, reconcile, and retry.`,
+- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -357,7 +368,8 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           path: { type: "string", description: "New path" },
           metadata: { type: "object", description: "Metadata to merge (keys are merged, not replaced wholesale)" },
           created_at: { type: "string", description: "New created_at timestamp" },
-          if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since." },
+          if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set." },
+          force: { type: "boolean", description: "Override the required `if_updated_at` check and run the update unconditionally. Use only for bulk migrations or scripted writes where concurrency is known-safe." },
           tags: {
             type: "object",
             properties: {
@@ -405,7 +417,8 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                 path: { type: "string" },
                 metadata: { type: "object" },
                 created_at: { type: "string" },
-                if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since." },
+                if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since. Required unless `force: true` is set on this item." },
+                force: { type: "boolean", description: "Override the required `if_updated_at` check for this item." },
                 tags: { type: "object" },
                 links: { type: "object" },
               },
@@ -423,6 +436,15 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         for (const item of items) {
           const note = requireNote(db, item.id as string);
 
+          // --- Safety-by-default: refuse mutations without a precondition ---
+          // The caller must either echo the note's last-seen `updated_at`
+          // (`if_updated_at`) so the conditional UPDATE can catch lost
+          // writes, or explicitly opt out with `force: true`. This runs
+          // *before* any DB writes so a rejection leaves the note untouched.
+          if (item.if_updated_at === undefined && item.force !== true) {
+            throw new PreconditionRequiredError(note.id, note.path ?? null);
+          }
+
           // --- Plan bracket cleanup for wikilink removals (no DB writes yet) ---
           // We compute the cleaned content so we can do the core UPDATE first
           // (with if_updated_at atomically) before any link deletions. If the
@@ -585,6 +607,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                 type: { type: "string", description: "Field type: string, boolean, integer" },
                 description: { type: "string" },
                 enum: { type: "array", items: { type: "string" }, description: "Allowed values (first is default)" },
+                indexed: { type: "boolean", description: "When true, a generated column + index are maintained on notes.metadata.<field>, making it queryable via metadata operator objects and order_by. Global: all tags declaring the field must agree on both type and indexed." },
               },
               required: ["type"],
             },
@@ -595,11 +618,76 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       execute: (params) => {
         const tag = params.tag as string;
         const existing = tagSchemaOps.getTagSchema(db, tag);
-        const mergedFields = { ...existing?.fields, ...(params.fields as any) };
-        return tagSchemaOps.upsertTagSchema(db, tag, {
+        const incomingFields = (params.fields as Record<string, TagFieldSchema> | undefined) ?? {};
+        const mergedFields: Record<string, TagFieldSchema> = {
+          ...(existing?.fields ?? {}),
+          ...incomingFields,
+        };
+
+        // Validate cross-tag consistency on fields being (re)declared in this
+        // call. `type` and `indexed` are global — all declarers must agree.
+        // `description` and `enum` are per-tag, so we don't compare them.
+        const otherSchemas = tagSchemaOps
+          .listTagSchemas(db)
+          .filter((s) => s.tag !== tag);
+        for (const [fieldName, spec] of Object.entries(incomingFields)) {
+          const incomingIndexed = spec.indexed === true;
+          for (const other of otherSchemas) {
+            const otherSpec = other.fields?.[fieldName];
+            if (!otherSpec) continue;
+            if (otherSpec.type !== spec.type) {
+              throw new Error(
+                `field "${fieldName}" type conflict: tag "${tag}" declares "${spec.type}"; tag "${other.tag}" declares "${otherSpec.type}". Types must agree across all declarers.`,
+              );
+            }
+            if ((otherSpec.indexed === true) !== incomingIndexed) {
+              throw new Error(
+                `field "${fieldName}" indexed-flag conflict: tag "${tag}" sets indexed=${incomingIndexed}; tag "${other.tag}" sets indexed=${otherSpec.indexed === true}. Must match across all declarers — change them atomically or not at all.`,
+              );
+            }
+          }
+          if (incomingIndexed) {
+            const mapped = indexedFieldOps.mapFieldType(spec.type);
+            if (!mapped) {
+              throw new Error(
+                `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
+              );
+            }
+            indexedFieldOps.validateFieldName(fieldName);
+          }
+        }
+
+        // Persist the schema first, then reconcile indexing lifecycle. An
+        // error here would leave the on-disk schema untouched, matching
+        // prior behavior.
+        const result = tagSchemaOps.upsertTagSchema(db, tag, {
           description: (params.description as string | undefined) ?? existing?.description,
           fields: Object.keys(mergedFields).length > 0 ? mergedFields : undefined,
         });
+
+        // Diff indexed state for this tag: what it indexed before vs. now.
+        const priorIndexed = new Set(
+          Object.entries(existing?.fields ?? {})
+            .filter(([, v]) => v.indexed === true)
+            .map(([k]) => k),
+        );
+        const nextIndexed = new Set(
+          Object.entries(mergedFields)
+            .filter(([, v]) => v.indexed === true)
+            .map(([k]) => k),
+        );
+        for (const fieldName of nextIndexed) {
+          const spec = mergedFields[fieldName]!;
+          const mapped = indexedFieldOps.mapFieldType(spec.type)!;
+          indexedFieldOps.declareField(db, fieldName, mapped, tag);
+        }
+        for (const fieldName of priorIndexed) {
+          if (!nextIndexed.has(fieldName)) {
+            indexedFieldOps.releaseField(db, fieldName, tag);
+          }
+        }
+
+        return result;
       },
     },
 
@@ -618,6 +706,17 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       },
       execute: async (params) => {
         const tag = params.tag as string;
+        // Release any indexed fields this tag declared before the schema
+        // row disappears. releaseField drops the generated column + index
+        // when the declarer set empties.
+        const schema = tagSchemaOps.getTagSchema(db, tag);
+        if (schema?.fields) {
+          for (const [fieldName, spec] of Object.entries(schema.fields)) {
+            if (spec.indexed === true) {
+              indexedFieldOps.releaseField(db, fieldName, tag);
+            }
+          }
+        }
         // Delete schema first (FK cascade would handle it, but be explicit)
         tagSchemaOps.deleteTagSchema(db, tag);
         return await store.deleteTag(tag);
@@ -733,3 +832,25 @@ function normalizeTags(tag: unknown): string[] | undefined {
 // conditional-UPDATE implementation that raises it.
 export { ConflictError } from "./notes.js";
 
+/**
+ * Thrown by the `update-note` MCP tool (and the REST PATCH handler) when a
+ * caller tries to mutate a note without either an `if_updated_at` token or
+ * an explicit `force: true` opt-out. The `if_updated_at` requirement is the
+ * safety-by-default posture — we'd rather refuse an ambiguous write than
+ * silently overwrite someone else's edit.
+ */
+export class PreconditionRequiredError extends Error {
+  code = "PRECONDITION_REQUIRED" as const;
+  note_id: string;
+  note_path: string | null;
+
+  constructor(noteId: string, notePath: string | null) {
+    super(
+      `precondition required: update-note rejects an item without \`if_updated_at\` (read the note's updated_at and echo it) or \`force: true\` (explicit override). note="${noteId}"`,
+    );
+    this.name = "PreconditionRequiredError";
+    this.note_id = noteId;
+    this.note_path = notePath;
+  }
+}
+

package/core/src/notes.ts

@@ -1,6 +1,11 @@
 import { Database } from "bun:sqlite";
 import type { Note, NoteIndex, QueryOpts, VaultStats } from "./types.js";
 import { normalizePath } from "./paths.js";
+import {
+  buildOperatorClause,
+  isOperatorObject,
+  requireIndexedField,
+} from "./query-operators.js";
 
 let idCounter = 0;
 
@@ -30,9 +35,15 @@ export function createNote(
   const metadata = opts?.metadata ? JSON.stringify(opts.metadata) : "{}";
   const path = normalizePath(opts?.path);
 
+  // `updated_at` is set to `created_at` on insert so a client whose optimistic
+  // concurrency check falls back to `createdAt` on a never-updated note
+  // (the common shape: `note.updatedAt ?? note.createdAt`) matches the stored
+  // value. Hook-style writes with `skipUpdatedAt` preserve this; real user
+  // edits bump it strictly upward, so `updated_at > created_at` still means
+  // "user-touched since creation."
   db.prepare(
-    `INSERT INTO notes (id, content, path, metadata, created_at) VALUES (?, ?, ?, ?, ?)`,
-  ).run(id, content, path, metadata, createdAt);
+    `INSERT INTO notes (id, content, path, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)`,
+  ).run(id, content, path, metadata, createdAt, createdAt);
 
   if (opts?.tags && opts.tags.length > 0) {
     tagNote(db, id, opts.tags);
@@ -81,15 +92,17 @@ export function getNotes(db: Database, ids: string[]): Note[] {
 export class ConflictError extends Error {
   code = "CONFLICT" as const;
   note_id: string;
+  note_path: string | null;
   current_updated_at: string | null;
   expected_updated_at: string;
 
-  constructor(noteId: string, current: string | null, expected: string) {
+  constructor(noteId: string, notePath: string | null, current: string | null, expected: string) {
     super(
       `conflict: note "${noteId}" has been modified (current updated_at=${current ?? "null"}, expected=${expected})`,
     );
     this.name = "ConflictError";
     this.note_id = noteId;
+    this.note_path = notePath;
     this.current_updated_at = current;
     this.expected_updated_at = expected;
   }
@@ -184,13 +197,13 @@ export function updateNote(
 }
 
 function throwConflictOrMissing(db: Database, id: string, expected: string): never {
-  const row = db.prepare("SELECT updated_at FROM notes WHERE id = ?").get(id) as
-    | { updated_at: string | null }
+  const row = db.prepare("SELECT updated_at, path FROM notes WHERE id = ?").get(id) as
+    | { updated_at: string | null; path: string | null }
     | undefined;
   if (!row) {
     throw new Error(`Note not found: "${id}"`);
   }
-  throw new ConflictError(id, row.updated_at, expected);
+  throw new ConflictError(id, row.path, row.updated_at, expected);
 }
 
 export function deleteNote(db: Database, id: string): void {
@@ -226,6 +239,26 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     }
   }
 
+  // Presence: has_tags. When specific tags were already supplied, skip —
+  // the existing join/condition already enforces that any result has tags.
+  const filterByTags = Boolean(opts.tags && opts.tags.length > 0);
+  if (opts.hasTags !== undefined && !filterByTags) {
+    conditions.push(
+      opts.hasTags
+        ? `EXISTS (SELECT 1 FROM note_tags ht WHERE ht.note_id = n.id)`
+        : `NOT EXISTS (SELECT 1 FROM note_tags ht WHERE ht.note_id = n.id)`,
+    );
+  }
+
+  // Presence: has_links (either direction counts).
+  if (opts.hasLinks !== undefined) {
+    conditions.push(
+      opts.hasLinks
+        ? `EXISTS (SELECT 1 FROM links hl WHERE hl.source_id = n.id OR hl.target_id = n.id)`
+        : `NOT EXISTS (SELECT 1 FROM links hl WHERE hl.source_id = n.id OR hl.target_id = n.id)`,
+    );
+  }
+
   // Exact path match (case-insensitive)
   if (opts.path) {
     conditions.push("n.path = ? COLLATE NOCASE");
@@ -238,11 +271,23 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     params.push(opts.pathPrefix + "%");
   }
 
-  // Metadata filters
+  // Metadata filters — operator objects route through the indexed generated
+  // column (fast, loud errors on non-indexed fields); primitives keep the
+  // existing JSON-scan exact-match behavior for backcompat.
   if (opts.metadata) {
     for (const [key, value] of Object.entries(opts.metadata)) {
-      conditions.push(`json_extract(n.metadata, '$.' || ?) = ?`);
-      params.push(key, typeof value === "string" ? value : JSON.stringify(value));
+      if (isOperatorObject(value)) {
+        requireIndexedField(db, key);
+        const { sql, params: opParams } = buildOperatorClause(
+          key,
+          value as Record<string, unknown>,
+        );
+        conditions.push(sql);
+        params.push(...opParams);
+      } else {
+        conditions.push(`json_extract(n.metadata, '$.' || ?) = ?`);
+        params.push(key, typeof value === "string" ? value : JSON.stringify(value));
+      }
     }
   }
 
@@ -256,7 +301,18 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     params.push(opts.dateTo);
   }
 
-  const orderBy = `n.created_at ${opts.sort === "desc" ? "DESC" : "ASC"}`;
+  const direction = opts.sort === "desc" ? "DESC" : "ASC";
+  let orderBy: string;
+  if (opts.orderBy) {
+    requireIndexedField(db, opts.orderBy);
+    // `orderBy` came from indexed_fields (validated on declaration), so
+    // the column name is safe to interpolate. Append created_at as a
+    // stable tiebreaker so two rows with the same indexed value have a
+    // deterministic order.
+    orderBy = `"meta_${opts.orderBy}" ${direction}, n.created_at ${direction}`;
+  } else {
+    orderBy = `n.created_at ${direction}`;
+  }
   const limit = typeof opts.limit === "number" ? opts.limit : 100;
   const offset = typeof opts.offset === "number" ? opts.offset : 0;
 
@@ -375,6 +431,90 @@ export function deleteTag(db: Database, name: string): { deleted: boolean; notes
   return { deleted: true, notes_untagged: notesUntagged };
 }
 
+// The UNIQUE PRIMARY KEY on tags.name means rename-to-existing is ambiguous:
+// do you drop the source, or retag-and-drop? Callers must pick — rename errors
+// out; mergeTags explicitly retags.
+export type RenameTagResult =
+  | { renamed: number }
+  | { error: "not_found" }
+  | { error: "target_exists" };
+
+export function renameTag(db: Database, oldName: string, newName: string): RenameTagResult {
+  if (oldName === newName) {
+    const exists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(oldName);
+    return exists ? { renamed: 0 } : { error: "not_found" };
+  }
+
+  const oldExists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(oldName);
+  if (!oldExists) return { error: "not_found" };
+
+  const newExists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(newName);
+  if (newExists) return { error: "target_exists" };
+
+  db.exec("BEGIN");
+  try {
+    // Order matters: the note_tags FK points at tags(name), and tag_schemas'
+    // FK cascades on delete. Seed the new row, move the schema + note_tags
+    // onto it, then drop the old row.
+    db.prepare("INSERT INTO tags (name) VALUES (?)").run(newName);
+    db.prepare("UPDATE tag_schemas SET tag_name = ? WHERE tag_name = ?").run(newName, oldName);
+    const updated = db.prepare("UPDATE note_tags SET tag_name = ? WHERE tag_name = ?").run(newName, oldName);
+    db.prepare("DELETE FROM tags WHERE name = ?").run(oldName);
+    db.exec("COMMIT");
+    return { renamed: Number(updated.changes) };
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+
+export function mergeTags(
+  db: Database,
+  sources: string[],
+  target: string,
+): { merged: Record<string, number>; target: string } {
+  // Dedup + drop target-in-sources (self-merge is a no-op).
+  const uniqueSources = Array.from(new Set(sources)).filter((s) => s !== target);
+
+  const merged: Record<string, number> = {};
+
+  db.exec("BEGIN");
+  try {
+    // Target might not exist yet. Seed it so INSERT OR IGNORE into note_tags
+    // can reference it; leave any existing schema on target untouched.
+    db.prepare("INSERT OR IGNORE INTO tags (name) VALUES (?)").run(target);
+
+    const retagStmt = db.prepare(
+      "INSERT OR IGNORE INTO note_tags (note_id, tag_name) SELECT note_id, ? FROM note_tags WHERE tag_name = ?",
+    );
+    const deleteNoteTagsStmt = db.prepare("DELETE FROM note_tags WHERE tag_name = ?");
+    const deleteTagStmt = db.prepare("DELETE FROM tags WHERE name = ?");
+    const countStmt = db.prepare("SELECT COUNT(*) as c FROM note_tags WHERE tag_name = ?");
+
+    for (const source of uniqueSources) {
+      const exists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(source);
+      if (!exists) {
+        merged[source] = 0;
+        continue;
+      }
+      const before = (countStmt.get(source) as { c: number }).c;
+      retagStmt.run(target, source);
+      deleteNoteTagsStmt.run(source);
+      // tag_schemas has ON DELETE CASCADE from tags(name), so dropping the
+      // tag row also drops its schema — which is what we want for a merge.
+      deleteTagStmt.run(source);
+      merged[source] = before;
+    }
+
+    db.exec("COMMIT");
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+
+  return { merged, target };
+}
+
 // ---- Lean note index shape ----
 
 /** Max code points in a NoteIndex preview. */
@@ -475,6 +615,9 @@ export function getVaultStats(
   const tagCountRow = db.prepare("SELECT COUNT(DISTINCT tag_name) as c FROM note_tags").get() as { c: number };
   const tagCount = tagCountRow.c;
 
+  const linkCountRow = db.prepare("SELECT COUNT(*) as c FROM links").get() as { c: number };
+  const linkCount = linkCountRow.c;
+
   return {
     totalNotes,
     earliestNote: earliestRow
@@ -486,6 +629,7 @@ export function getVaultStats(
     notesByMonth: monthRows,
     topTags: topTagRows,
     tagCount,
+    linkCount,
   };
 }
 
@@ -593,6 +737,8 @@ function rowToNote(row: NoteRow): Note {
     path: row.path ?? undefined,
     metadata,
     createdAt: row.created_at,
-    updatedAt: row.updated_at ?? undefined,
+    // Legacy notes (pre-#70) may have NULL updated_at. Fall back to created_at
+    // so the optimistic-concurrency contract always has a real token to echo.
+    updatedAt: row.updated_at ?? row.created_at,
   };
 }

package/core/src/query-operators.ts

@@ -0,0 +1,174 @@
+/**
+ * Metadata operator objects for `query-notes`.
+ *
+ * A metadata value that is a plain object whose keys are all drawn from
+ * {@link SUPPORTED_OPS} is treated as an operator query. Otherwise the value
+ * falls through to the existing exact-match behavior (primitive → JSON
+ * stringify compare).
+ *
+ * Operator queries route through the generated columns maintained by
+ * `indexed-fields`: `meta_<field>` on `notes`, backed by a B-tree index. The
+ * field must be declared `indexed: true` in some tag schema; otherwise we
+ * refuse with an actionable error (no silent fallback to a JSON scan, per the
+ * decision doc).
+ *
+ * See `Parachute/Decisions/2026-04-19-metadata-indexing-via-tag-schemas`.
+ */
+
+import { Database } from "bun:sqlite";
+import { getIndexedField, type IndexedField } from "./indexed-fields.js";
+
+export const SUPPORTED_OPS = [
+  "eq",
+  "ne",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "in",
+  "not_in",
+  "exists",
+] as const;
+
+export type QueryOp = (typeof SUPPORTED_OPS)[number];
+
+const OPS_SET: ReadonlySet<string> = new Set<string>(SUPPORTED_OPS);
+
+export class QueryError extends Error {
+  override name = "QueryError";
+  code: string;
+  constructor(message: string, code = "INVALID_QUERY") {
+    super(message);
+    this.code = code;
+  }
+}
+
+/**
+ * Returns true when `value` is a non-array, non-null, non-empty plain object.
+ * The presence of *any* plain-object value commits the caller to operator-
+ * parsing: a misspelled operator like `{ bogus: 5 }` is a loud error rather
+ * than a silent fallback to JSON-blob exact-match. Nested-object exact-match
+ * on the JSON blob was never a meaningful use case.
+ */
+export function isOperatorObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  return Object.keys(value as object).length > 0;
+}
+
+function validateOperatorObject(field: string, obj: Record<string, unknown>): void {
+  for (const key of Object.keys(obj)) {
+    if (!OPS_SET.has(key)) {
+      throw new QueryError(
+        `unknown operator "${key}" on metadata field "${field}". Supported: ${SUPPORTED_OPS.join(", ")}.`,
+        "UNKNOWN_OPERATOR",
+      );
+    }
+  }
+}
+
+/**
+ * Look up `field` in `indexed_fields` or throw a loud error suggesting the
+ * caller declare it via `update-tag` with `indexed: true`.
+ */
+export function requireIndexedField(db: Database, field: string): IndexedField {
+  const row = getIndexedField(db, field);
+  if (!row) {
+    throw new QueryError(
+      `metadata field "${field}" is not indexed. To use operator queries or order_by on this field, declare it via update-tag with indexed: true.`,
+      "FIELD_NOT_INDEXED",
+    );
+  }
+  return row;
+}
+
+/**
+ * Build a SQL fragment + bound params for an operator object on an indexed
+ * metadata field. Each operator maps to a single AND clause; an object like
+ * `{ gt: 5, lt: 10 }` composes as `meta_<field> > 5 AND meta_<field> < 10`.
+ */
+export function buildOperatorClause(
+  field: string,
+  opObj: Record<string, unknown>,
+): { sql: string; params: unknown[] } {
+  validateOperatorObject(field, opObj);
+  // `field` came from indexed_fields (which validated it via FIELD_NAME_RE
+  // when the declaration was recorded), so interpolating it into the column
+  // name is safe.
+  const col = `"meta_${field}"`;
+  const parts: string[] = [];
+  const params: unknown[] = [];
+
+  for (const [op, value] of Object.entries(opObj)) {
+    switch (op as QueryOp) {
+      case "eq":
+        if (value === null) {
+          parts.push(`${col} IS NULL`);
+        } else {
+          parts.push(`${col} = ?`);
+          params.push(value);
+        }
+        break;
+      case "ne":
+        if (value === null) {
+          parts.push(`${col} IS NOT NULL`);
+        } else {
+          // Preserve "field is set AND not equal" semantics — SQLite's `<>`
+          // returns NULL (not true) when the LHS is NULL, so a notes row
+          // that has no value for the field would be silently excluded. Be
+          // explicit: either the column is null, or the values differ.
+          parts.push(`(${col} IS NULL OR ${col} <> ?)`);
+          params.push(value);
+        }
+        break;
+      case "gt":
+      case "gte":
+      case "lt":
+      case "lte": {
+        const sym = op === "gt" ? ">" : op === "gte" ? ">=" : op === "lt" ? "<" : "<=";
+        parts.push(`${col} ${sym} ?`);
+        params.push(value);
+        break;
+      }
+      case "in":
+      case "not_in": {
+        if (!Array.isArray(value)) {
+          throw new QueryError(
+            `operator "${op}" on metadata field "${field}" expects an array`,
+            "INVALID_OPERATOR_VALUE",
+          );
+        }
+        if (value.length === 0) {
+          // Empty IN is a contradiction; empty NOT IN is a no-op. Emit SQL
+          // that matches these semantics without running a parameterless
+          // `IN ()` (which is a syntax error in SQLite).
+          parts.push(op === "in" ? "0" : "1");
+          break;
+        }
+        const placeholders = value.map(() => "?").join(", ");
+        if (op === "in") {
+          parts.push(`${col} IN (${placeholders})`);
+        } else {
+          parts.push(`(${col} IS NULL OR ${col} NOT IN (${placeholders}))`);
+        }
+        for (const v of value) params.push(v);
+        break;
+      }
+      case "exists":
+        if (typeof value !== "boolean") {
+          throw new QueryError(
+            `operator "exists" on metadata field "${field}" expects a boolean`,
+            "INVALID_OPERATOR_VALUE",
+          );
+        }
+        parts.push(value ? `${col} IS NOT NULL` : `${col} IS NULL`);
+        break;
+    }
+  }
+
+  return {
+    sql: parts.length === 1 ? parts[0]! : `(${parts.join(" AND ")})`,
+    params,
+  };
+}