@openparachute/vault 0.4.0 → 0.4.3

package/core/src/schema-defaults.ts

@@ -1,34 +1,47 @@
 /**
- * Schema validation: resolves which schemas apply to a note (by path prefix
- * or tag), then validates the note's metadata against each. Writes are
- * never blocked — schemas are guidance. The MCP/REST layer surfaces a
- * `validation_status` block on create/update responses with any warnings
- * the agent can act on (missing required, type mismatch, enum mismatch).
+ * Schema validation: walk the tags carried by a note (plus their ancestors via
+ * `parent_names`), look up each ancestor's `fields` declaration, merge them
+ * (first-in-walk wins on conflict), and validate the note's metadata against
+ * the merged field map. Writes are never blocked — schemas are guidance. The
+ * MCP/REST layer surfaces a `validation_status` block on create/update
+ * responses with any warnings the agent can act on (type mismatch, enum
+ * mismatch, schema conflict).
  *
- * Storage (post-v15): schemas live in the `note_schemas` table; mapping
- * rules live in `schema_mappings`. Authoring is via `update-note-schema`
- * + `set-schema-mapping` (MCP/REST). The legacy `_schemas/<name>` and
- * `_schema_defaults` notes are retired but left in place — inert after
- * v15 (no resolver reads them).
+ * Storage: schemas live as `fields` columns on the `tags` table — same row
+ * that already carries description, relationships, and parent_names. Authoring
+ * is via `update-tag` (MCP) or PATCH /api/tags/:name (REST).
+ *
+ * This was a two-table subsystem (`note_schemas` + `schema_mappings`) prior
+ * to v17 — see vault#267. Removed in v17 because zero operator vaults used
+ * the path-prefix mapping kind, and tag-mapped schemas were fully redundant
+ * with `tags.fields`. The single-axis tag-driven validation lives here.
+ *
+ * Inheritance (vault#270, 2026-05-09):
+ * - A note's effective ancestor set = union of {tag ∪ ancestors(tag)} for each
+ *   tag on the note, walking `parent_names` recursively (cycle-safe).
+ * - `_default` is an implicit universal parent: if a tag named `_default`
+ *   exists in the tags table, it's appended to every note's effective ancestor
+ *   set (including untagged notes). The `tags.parent_names` column is never
+ *   auto-mutated — the magic lives at resolve time only.
+ * - Conflict resolution: first-in-walk wins. The walk visits each note tag
+ *   in order, then DFS through its `parent_names` array in declaration order,
+ *   so "first-in-`parent_names`-array wins" is the operator-controlled
+ *   precedence. Conflicts surface as advisory `schema_conflict` warnings; no
+ *   write blocking.
+ * - `_default` can technically carry its own `parent_names` and the resolver
+ *   handles it (cycle guard + visited Set), but the resulting interaction is
+ *   non-obvious — `_default` is usually appended last, so its ancestors
+ *   become low-precedence. Treat `_default` as a root tag in normal use.
  *
  * Resolution model:
  * - Lazy: rebuilt on first access, cached on the store.
- * - Invalidated when `note_schemas` or `schema_mappings` are mutated
- *   (table writes, not note writes).
- * - When no mappings exist and nothing else matches, validation is a
- *   no-op (status omitted).
+ * - Invalidated when `tags.fields` or `tags.parent_names` is mutated, when a
+ *   tag is deleted, renamed, or merged.
+ * - When no ancestor declares fields, validation is a no-op (status omitted).
  */
 
 import { Database } from "bun:sqlite";
 
-// ---------------------------------------------------------------------------
-// Legacy path prefixes — kept exported for any historical caller that still
-// references them. No resolver code reads notes-as-config post-v15.
-// ---------------------------------------------------------------------------
-
-export const SCHEMA_CONFIG_PREFIX = "_schemas/";
-export const SCHEMA_DEFAULTS_PATH = "_schema_defaults";
-
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -39,35 +52,44 @@ export interface SchemaField {
   description?: string;
 }
 
-export interface SchemaDefinition {
-  name: string;
-  description?: string;
-  fields: Record<string, SchemaField>;
-  required: string[];
-}
-
-export interface SchemaDefaults {
-  /** Path prefix → schema name. Longest prefix wins on tie. */
-  pathPrefixes: Array<{ prefix: string; schema: string }>;
-  /** Tag → schema name. */
-  tagToSchema: Map<string, string>;
-}
-
+/**
+ * Tag-record snapshot used by the resolver. Loaded from the `tags` table once
+ * and cached on the store. `allTags` carries every known name (so `_default`
+ * existence checks and query expansion can be answered without a re-read).
+ */
 export interface ResolvedSchemas {
-  defaults: SchemaDefaults;
-  definitions: Map<string, SchemaDefinition>;
+  /** Set of all known tag names (for `_default` magic + presence checks). */
+  allTags: Set<string>;
+  /** Per-tag own fields (only entries with at least one declaration). */
+  tagToFields: Map<string, Record<string, SchemaField>>;
+  /** Per-tag `parent_names` (only entries with at least one parent declared). */
+  tagToParents: Map<string, string[]>;
 }
 
 export interface ValidationWarning {
   field: string;
+  /** Tag whose schema declared the violated field (or won the conflict). */
   schema: string;
-  /** "missing_required" | "type_mismatch" | "enum_mismatch" */
-  reason: "missing_required" | "type_mismatch" | "enum_mismatch";
+  /**
+   * `type_mismatch` — value's type contradicts the declared `type`.
+   * `enum_mismatch` — string value not in the declared `enum`.
+   * `schema_conflict` — two ancestors declared the same field with
+   * different specs; first-in-walk wins, the loser surfaces here so the
+   * operator can resolve the disagreement.
+   */
+  reason: "type_mismatch" | "enum_mismatch" | "schema_conflict";
   message: string;
+  /**
+   * `schema_conflict` only — the tag whose declaration was overridden. Set
+   * when `reason === "schema_conflict"`; absent on type/enum mismatches.
+   * Surfaces structurally so agents don't have to regex `message` to find
+   * the loser.
+   */
+  loser_schema?: string;
 }
 
 export interface ValidationStatus {
-  /** Schema names that matched the note (for transparency). */
+  /** Tag names whose schemas contributed at least one field to the merged map. */
   schemas: string[];
   /** Empty when all checks pass. */
   warnings: ValidationWarning[];
@@ -99,55 +121,34 @@ function parseFieldsJson(raw: string | null): Record<string, SchemaField> {
   return fields;
 }
 
-function parseRequiredJson(raw: string | null): string[] {
+function parseParentsJson(raw: string | null): string[] {
   if (!raw) return [];
-  try {
-    const parsed = JSON.parse(raw);
-    if (!Array.isArray(parsed)) return [];
-    return parsed.filter((x): x is string => typeof x === "string");
-  } catch {
-    return [];
-  }
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { return []; }
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((x): x is string => typeof x === "string" && x.length > 0);
 }
 
 /**
- * Build the full resolution map from the `note_schemas` and `schema_mappings`
- * tables. Always returns a well-formed `ResolvedSchemas` even when the
- * tables are empty (empty maps).
+ * Build a resolution map from the `tags` table. Returns a well-formed
+ * `ResolvedSchemas` even when no tag declares fields (empty `tagToFields`).
  */
 export function loadSchemaConfig(db: Database): ResolvedSchemas {
-  const definitions = new Map<string, SchemaDefinition>();
-  const defRows = db.prepare(
-    `SELECT name, description, fields, required FROM note_schemas`,
-  ).all() as { name: string; description: string | null; fields: string | null; required: string | null }[];
-  for (const row of defRows) {
+  const allTags = new Set<string>();
+  const tagToFields = new Map<string, Record<string, SchemaField>>();
+  const tagToParents = new Map<string, string[]>();
+  const rows = db.prepare(
+    `SELECT name, fields, parent_names FROM tags`,
+  ).all() as { name: string; fields: string | null; parent_names: string | null }[];
+  for (const row of rows) {
     if (!row.name) continue;
-    definitions.set(row.name, {
-      name: row.name,
-      description: row.description ?? undefined,
-      fields: parseFieldsJson(row.fields),
-      required: parseRequiredJson(row.required),
-    });
-  }
-
-  const defaults: SchemaDefaults = {
-    pathPrefixes: [],
-    tagToSchema: new Map(),
-  };
-  const mappingRows = db.prepare(
-    `SELECT schema_name, match_kind, match_value FROM schema_mappings`,
-  ).all() as { schema_name: string; match_kind: string; match_value: string }[];
-  for (const row of mappingRows) {
-    if (row.match_kind === "path_prefix") {
-      defaults.pathPrefixes.push({ prefix: row.match_value, schema: row.schema_name });
-    } else if (row.match_kind === "tag") {
-      defaults.tagToSchema.set(row.match_value, row.schema_name);
-    }
+    allTags.add(row.name);
+    const fields = parseFieldsJson(row.fields);
+    if (Object.keys(fields).length > 0) tagToFields.set(row.name, fields);
+    const parents = parseParentsJson(row.parent_names);
+    if (parents.length > 0) tagToParents.set(row.name, parents);
   }
-  // Longest prefix wins — sort once at load so resolve is O(n) without re-sorts.
-  defaults.pathPrefixes.sort((a, b) => b.prefix.length - a.prefix.length);
-
-  return { defaults, definitions };
+  return { allTags, tagToFields, tagToParents };
 }
 
 // ---------------------------------------------------------------------------
@@ -155,41 +156,111 @@ export function loadSchemaConfig(db: Database): ResolvedSchemas {
 // ---------------------------------------------------------------------------
 
 /**
- * Find the schemas that apply to a note based on its path and tags. Returns
- * schema *names* in the order they were resolved (path-prefix first, then
- * each matching tag in declaration order). Names that don't have a row in
- * `note_schemas` are dropped.
+ * Walk-order accumulator for a single note's effective ancestor set. DFS
+ * through `parent_names` in declaration order, cycle-protected via a visited
+ * Set. The output array preserves first-encounter order so the field-merge
+ * pass can apply first-wins precedence.
+ *
+ * Exported so other consumers (vault projection, future hierarchy
+ * inspectors) can reuse the exact walk semantics rather than carrying
+ * their own copy. Mutating walks (push to `out`, add to `visited`) keep
+ * the implementation cheap; callers pass fresh accumulators.
  */
-export function resolveApplicableSchemas(
+export function walkAncestors(
+  startTag: string,
   resolved: ResolvedSchemas,
-  note: { path?: string | null; tags?: string[] },
-): string[] {
-  const names: string[] = [];
-  const seen = new Set<string>();
+  visited: Set<string>,
+  out: string[],
+): void {
+  if (visited.has(startTag)) return;
+  visited.add(startTag);
+  out.push(startTag);
+  const parents = resolved.tagToParents.get(startTag);
+  if (!parents) return;
+  for (const p of parents) {
+    walkAncestors(p, resolved, visited, out);
+  }
+}
 
-  if (note.path) {
-    for (const { prefix, schema } of resolved.defaults.pathPrefixes) {
-      if (note.path.startsWith(prefix)) {
-        if (!seen.has(schema) && resolved.definitions.has(schema)) {
-          names.push(schema);
-          seen.add(schema);
-        }
-        break; // longest match wins (sorted at load)
-      }
-    }
+interface MergedField {
+  spec: SchemaField;
+  sourceTag: string;
+}
+
+interface NoteResolution {
+  /** Walk-order tag list whose `fields` contributed at least one entry. */
+  effectiveTags: string[];
+  /** Field name → winning spec + source tag. First-in-walk wins. */
+  mergedFields: Map<string, MergedField>;
+  /** Conflict warnings — same field declared by ≥2 ancestors with diverging specs. */
+  conflicts: ValidationWarning[];
+}
+
+/**
+ * Resolve the effective schema for a note. Walks each note tag through its
+ * `parent_names` chain (cycle-safe), implicitly appends `_default` when the
+ * tag exists, and merges all encountered `fields` declarations with
+ * first-in-walk precedence. A note with no tags still picks up `_default`'s
+ * schema when one is declared.
+ *
+ * Internal — exported for tests. The public entry point is `validateNote`.
+ */
+export function resolveNoteSchemas(
+  resolved: ResolvedSchemas,
+  note: { tags?: string[] },
+): NoteResolution {
+  const visited = new Set<string>();
+  const order: string[] = [];
+
+  for (const tag of note.tags ?? []) {
+    walkAncestors(tag, resolved, visited, order);
+  }
+  if (resolved.allTags.has("_default")) {
+    walkAncestors("_default", resolved, visited, order);
   }
 
-  if (note.tags) {
-    for (const tag of note.tags) {
-      const schema = resolved.defaults.tagToSchema.get(tag);
-      if (schema && !seen.has(schema) && resolved.definitions.has(schema)) {
-        names.push(schema);
-        seen.add(schema);
+  const mergedFields = new Map<string, MergedField>();
+  const conflicts: ValidationWarning[] = [];
+
+  for (const tagName of order) {
+    const fields = resolved.tagToFields.get(tagName);
+    if (!fields) continue;
+    for (const [fieldName, spec] of Object.entries(fields)) {
+      const existing = mergedFields.get(fieldName);
+      if (!existing) {
+        mergedFields.set(fieldName, { spec, sourceTag: tagName });
+        continue;
       }
+      if (fieldSpecsEqual(existing.spec, spec)) continue;
+      conflicts.push({
+        field: fieldName,
+        schema: existing.sourceTag,
+        loser_schema: tagName,
+        reason: "schema_conflict",
+        message: `field '${fieldName}' has conflicting specs in ancestor tags '${existing.sourceTag}' (kept) and '${tagName}' (ignored)`,
+      });
     }
   }
 
-  return names;
+  const contributing = new Set<string>();
+  for (const { sourceTag } of mergedFields.values()) contributing.add(sourceTag);
+  const effectiveTags = order.filter((t) => contributing.has(t));
+
+  return { effectiveTags, mergedFields, conflicts };
+}
+
+function fieldSpecsEqual(a: SchemaField, b: SchemaField): boolean {
+  if (a.type !== b.type) return false;
+  if (!stringArraysEqual(a.enum, b.enum)) return false;
+  return true;
+}
+
+function stringArraysEqual(a: string[] | undefined, b: string[] | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
 }
 
 function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
@@ -209,79 +280,52 @@ function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
 }
 
 /**
- * Validate a note's metadata against each applicable schema and collect
- * warnings. Validation is non-blocking — the caller decides what to do with
- * the warnings (currently: surface them on the create/update response).
+ * Validate a note's metadata against the merged schema. Returns null when no
+ * ancestor declares any fields (so the caller can omit `validation_status`
+ * entirely). Otherwise returns the status with conflict warnings prepended,
+ * followed by per-field type/enum mismatches.
  *
- * Rules per field:
- * - In `required` and absent → `missing_required`
+ * Rules per merged field:
  * - Present and `type` declared and value's type doesn't match → `type_mismatch`
  * - Present and `enum` declared and value not in enum → `enum_mismatch`
  *
- * Fields not declared in the schema are ignored entirely (this isn't a
- * "strict" validator — it's a guide).
+ * Fields not declared by any ancestor's schema are ignored entirely (this
+ * isn't a "strict" validator — it's a guide). There is no `required` concept
+ * (post-v17); declarations are advisory only.
  */
-export function validateMetadata(
+export function validateNote(
   resolved: ResolvedSchemas,
-  schemaNames: string[],
-  metadata: Record<string, unknown> | undefined,
-): ValidationStatus {
-  const warnings: ValidationWarning[] = [];
-  const m = metadata ?? {};
-
-  for (const name of schemaNames) {
-    const def = resolved.definitions.get(name);
-    if (!def) continue;
+  note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> },
+): ValidationStatus | null {
+  const resolution = resolveNoteSchemas(resolved, note);
+  if (resolution.mergedFields.size === 0) return null;
 
-    for (const requiredField of def.required) {
-      if (!(requiredField in m) || m[requiredField] === undefined || m[requiredField] === null) {
-        warnings.push({
-          field: requiredField,
-          schema: name,
-          reason: "missing_required",
-          message: `'${requiredField}' is required by schema '${name}'`,
-        });
-      }
-    }
+  const m = note.metadata ?? {};
+  const warnings: ValidationWarning[] = [...resolution.conflicts];
 
-    for (const [fieldName, field] of Object.entries(def.fields)) {
-      if (!(fieldName in m)) continue;
-      const value = m[fieldName];
-      if (value === undefined || value === null) continue;
+  for (const [fieldName, { spec, sourceTag }] of resolution.mergedFields) {
+    if (!(fieldName in m)) continue;
+    const value = m[fieldName];
+    if (value === undefined || value === null) continue;
 
-      if (field.type && !valueMatchesType(value, field.type)) {
-        warnings.push({
-          field: fieldName,
-          schema: name,
-          reason: "type_mismatch",
-          message: `'${fieldName}' should be ${field.type} (schema '${name}')`,
-        });
-      }
+    if (spec.type && !valueMatchesType(value, spec.type)) {
+      warnings.push({
+        field: fieldName,
+        schema: sourceTag,
+        reason: "type_mismatch",
+        message: `'${fieldName}' should be ${spec.type} (tag '${sourceTag}')`,
+      });
+    }
 
-      if (field.enum && field.enum.length > 0 && typeof value === "string" && !field.enum.includes(value)) {
-        warnings.push({
-          field: fieldName,
-          schema: name,
-          reason: "enum_mismatch",
-          message: `'${fieldName}' must be one of [${field.enum.join(", ")}] (schema '${name}')`,
-        });
-      }
+    if (spec.enum && spec.enum.length > 0 && typeof value === "string" && !spec.enum.includes(value)) {
+      warnings.push({
+        field: fieldName,
+        schema: sourceTag,
+        reason: "enum_mismatch",
+        message: `'${fieldName}' must be one of [${spec.enum.join(", ")}] (tag '${sourceTag}')`,
+      });
     }
   }
 
-  return { schemas: schemaNames, warnings };
-}
-
-/**
- * Convenience: combine resolve + validate for a note. Returns null when no
- * schemas apply (so the caller can decide whether to omit the field on the
- * response or surface an empty status).
- */
-export function validateNote(
-  resolved: ResolvedSchemas,
-  note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> },
-): ValidationStatus | null {
-  const names = resolveApplicableSchemas(resolved, note);
-  if (names.length === 0) return null;
-  return validateMetadata(resolved, names, note.metadata);
+  return { schemas: resolution.effectiveTags, warnings };
 }

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 = 16;
+export const SCHEMA_VERSION = 17;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record
@@ -69,37 +69,12 @@ CREATE TABLE IF NOT EXISTS links (
 -- tags row directly. The CREATE TABLE was removed from SCHEMA_SQL after the
 -- v14 data migration drops the table; existing v6+ vaults pick up the
 -- migration on next boot. See migrateToV14.
-
--- Note schemas (v15): schema definitions used to validate notes by path
--- prefix or tag. Replaces the v6-era _schemas/NAME notes-as-config
--- convention. Validation is non-blocking — schemas surface warnings on
--- create/update responses, never reject the write. See
--- core/src/schema-defaults.ts and patterns/tag-data-model.md §Note schemas.
 --
--- name        — primary key; the schema identifier referenced by mappings.
--- description — human-readable blurb (markdown).
--- fields      — JSON: { fieldName: { type?, enum?, description? } }.
--- required    — JSON: string[] of required field names.
-CREATE TABLE IF NOT EXISTS note_schemas (
-  name TEXT PRIMARY KEY,
-  description TEXT,
-  fields TEXT,
-  required TEXT,
-  created_at TEXT,
-  updated_at TEXT
-);
-
--- Schema mappings (v15): replaces the singleton _schema_defaults note. One
--- row per match rule; the resolver walks the table at note-write time.
--- match_kind is constrained to 'path_prefix' or 'tag'. Composite PK so
--- (schema, kind, value) is naturally unique without an extra surrogate id.
--- ON DELETE CASCADE: dropping a schema cleans up its mappings.
-CREATE TABLE IF NOT EXISTS schema_mappings (
-  schema_name TEXT NOT NULL REFERENCES note_schemas(name) ON DELETE CASCADE,
-  match_kind TEXT NOT NULL CHECK (match_kind IN ('path_prefix', 'tag')),
-  match_value TEXT NOT NULL,
-  PRIMARY KEY (schema_name, match_kind, match_value)
-);
+-- note_schemas + schema_mappings (v15) were retired in v17 (vault#267).
+-- The two-table validation subsystem turned out to be a parallel path to
+-- the per-tag fields column with zero operator usage; v17 drops both
+-- tables and the six MCP tools that managed them. Validation now reads
+-- tags.fields exclusively — see core/src/schema-defaults.ts.
 
 -- Indexed fields: SSOT for generated columns and indexes on notes derived
 -- from tag-declared fields with indexed=true. One row per indexed metadata
@@ -209,7 +184,6 @@ CREATE INDEX IF NOT EXISTS idx_note_tags_tag ON note_tags(tag_name, note_id);
 CREATE INDEX IF NOT EXISTS idx_attachments_note ON attachments(note_id);
 CREATE INDEX IF NOT EXISTS idx_links_source ON links(source_id);
 CREATE INDEX IF NOT EXISTS idx_links_target ON links(target_id);
-CREATE INDEX IF NOT EXISTS idx_schema_mappings_match ON schema_mappings(match_kind, match_value);
 -- idx_tokens_vault_name is created in migrateToV16, not here. SCHEMA_SQL
 -- runs BEFORE migrations; an upgrading v15 vault doesn't yet have the
 -- vault_name column when this section evaluates, so the index has to
@@ -285,6 +259,13 @@ export function initSchema(db: Database): void {
   // New mints via per-vault routes write the column explicitly. See vault#257.
   migrateToV16(db);
 
+  // Migrate v16 → v17: rip the standalone `note_schemas` + `schema_mappings`
+  // subsystem. Validation now reads `tags.fields` exclusively. The two
+  // tables are dropped wholesale; if a vault carried rows we log a warning
+  // naming the dropped schemas/mappings so the operator can recreate them
+  // as `tags.fields` if needed. See vault#267.
+  migrateToV17(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -572,6 +553,10 @@ function migrateToV14(db: Database): void {
  * leaves the DB in either pre-v15 or post-v15 state, never partial.
  */
 function migrateToV15(db: Database): void {
+  // note_schemas was dropped in v17; on any v17+ vault (or a v14→v17 skip),
+  // this guard returns immediately and the function is effectively dead code.
+  // Left in place rather than deleted because removing it would change initSchema's
+  // migration call ordering. Safe to delete in a future cleanup.
   if (!hasTable(db, "note_schemas") || !hasTable(db, "notes")) return;
 
   // Short-circuit: if either destination table already has data, the
@@ -721,6 +706,93 @@ function migrateToV16(db: Database): void {
   db.exec("CREATE INDEX IF NOT EXISTS idx_tokens_vault_name ON tokens(vault_name)");
 }
 
+/**
+ * Migrate v16 → v17: rip `note_schemas` + `schema_mappings` (vault#267).
+ *
+ * The two-table validation subsystem from v15 turned out to be a parallel
+ * path to `tags.fields` with zero operator usage. v17 drops both tables
+ * outright. Fresh vaults never see them; upgrading vaults lose them.
+ *
+ * If an upgrading vault DID carry rows (which Aaron's didn't, but a future
+ * operator's might), the migration logs the dropped names + mapping rules
+ * so the operator can re-create them as `tags.fields` declarations on the
+ * relevant tag rows. We don't try to auto-migrate path_prefix mappings —
+ * the new validation surface is tag-axis only, and a path_prefix → tag
+ * translation has no faithful one-to-one shape.
+ *
+ * Wrapped in BEGIN IMMEDIATE / COMMIT / ROLLBACK per the v14/v15/v16
+ * pattern from vault#251 — DROP TABLE statements are individually atomic,
+ * but the wrap means a crash mid-migration leaves either pre-v17 or
+ * post-v17 state, never partial.
+ */
+function migrateToV17(db: Database): void {
+  const hasNoteSchemas = hasTable(db, "note_schemas");
+  const hasSchemaMappings = hasTable(db, "schema_mappings");
+  if (!hasNoteSchemas && !hasSchemaMappings) return;
+
+  // Snapshot any data so the operator can recreate as `tags.fields` if
+  // needed. Read BEFORE the transaction so we don't lose the warning if
+  // the DROP fails (the COMMIT below atomically swaps state).
+  let droppedSchemas: { name: string; description: string | null }[] = [];
+  let droppedMappings: { schema_name: string; match_kind: string; match_value: string }[] = [];
+  if (hasNoteSchemas) {
+    droppedSchemas = db.prepare(
+      "SELECT name, description FROM note_schemas",
+    ).all() as { name: string; description: string | null }[];
+  }
+  if (hasSchemaMappings) {
+    droppedMappings = db.prepare(
+      "SELECT schema_name, match_kind, match_value FROM schema_mappings",
+    ).all() as { schema_name: string; match_kind: string; match_value: string }[];
+  }
+
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    // Drop the index first — the index references the table; SQLite would
+    // tear it down on DROP TABLE but the explicit DROP keeps the order
+    // obvious if a future migration reads from sqlite_master mid-flight.
+    db.exec("DROP INDEX IF EXISTS idx_schema_mappings_match");
+    // schema_mappings has an FK to note_schemas — drop it first.
+    if (hasSchemaMappings) {
+      db.exec("DROP TABLE schema_mappings");
+    }
+    if (hasNoteSchemas) {
+      db.exec("DROP TABLE note_schemas");
+    }
+    db.exec("COMMIT");
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+
+  if (droppedSchemas.length > 0 || droppedMappings.length > 0) {
+    const schemaNames = droppedSchemas.map((s) => s.name).join(", ");
+    const tagMappings = droppedMappings.filter((m) => m.match_kind === "tag");
+    const pathMappings = droppedMappings.filter((m) => m.match_kind === "path_prefix");
+    const lines: string[] = [
+      `[vault] migrated to schema v17 (vault#267): note_schemas + schema_mappings retired.`,
+    ];
+    if (droppedSchemas.length > 0) {
+      lines.push(`  dropped schemas (${droppedSchemas.length}): ${schemaNames}`);
+    }
+    if (tagMappings.length > 0) {
+      const list = tagMappings.map((m) => `${m.match_value}→${m.schema_name}`).join(", ");
+      lines.push(
+        `  dropped tag mappings (${tagMappings.length}): ${list}`,
+        `  recreate as \`tags.fields\` declarations on the relevant tag rows.`,
+      );
+    }
+    if (pathMappings.length > 0) {
+      const list = pathMappings.map((m) => `${m.match_value}→${m.schema_name}`).join(", ");
+      lines.push(
+        `  dropped path_prefix mappings (${pathMappings.length}): ${list}`,
+        `  no path-prefix-driven validation in v17 — file vault#267 if you need this.`,
+      );
+    }
+    console.log(lines.join("\n"));
+  }
+}
+
 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;