@openparachute/vault 0.7.0-rc.6 → 0.7.0-rc.8

package/core/src/search-fts-v25.test.ts

@@ -0,0 +1,362 @@
+/**
+ * Search recall + ranking — schema v25 FTS rebuild (Wave 7 of the
+ * Reliability & Usability Program, WS2B/C, vault#551). Covers the
+ * MIGRATION-bearing risk this PR carries:
+ *
+ *   - a v24 vault (single-column `content`-only notes_fts) upgrades to the
+ *     v25 shape (path + content, porter stemming) via `migrateToV25`,
+ *     idempotently, without touching note data;
+ *   - a fresh vault gets the v25 shape directly from SCHEMA_SQL;
+ *   - post-migration, a note's TITLE (path) is searchable — impossible
+ *     pre-v25;
+ *   - existing body-text search keeps working (no regression);
+ *   - porter stemming matches regular-affix variants;
+ *   - bm25 ranking is weighted so a title match outranks a passing body
+ *     mention, and every result carries a legible `score`;
+ *   - the sync triggers keep the index correct across insert/update
+ *     (content-only, path-only, both)/delete, including notes with no path.
+ *
+ * See `src/contract-search.test.ts` for the REST/MCP-surface coverage
+ * (did_you_mean, the wrapped advanced-mode column-filter hint, sort
+ * override parity).
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { initSchema, SCHEMA_VERSION } from "./schema.js";
+import * as noteOps from "./notes.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("search — schema v25 FTS rebuild", () => {
+  it("bumped SCHEMA_VERSION to at least 25 (notes_fts path+content landed)", () => {
+    expect(SCHEMA_VERSION).toBeGreaterThanOrEqual(25);
+  });
+
+  it("a fresh vault gets the v25 notes_fts shape directly (path + content columns)", () => {
+    const cols = (db.prepare("PRAGMA table_info(notes_fts)").all() as { name: string }[]).map(
+      (r) => r.name,
+    );
+    expect(cols).toContain("path");
+    expect(cols).toContain("content");
+  });
+
+  it("a fresh vault: a note's title (path) is searchable even with unrelated body content", async () => {
+    await store.createNote("nothing relevant in the body here", {
+      path: "quarterly-budget-review",
+    });
+    const hits = await store.searchNotes("budget");
+    expect(hits.map((n) => n.path)).toContain("quarterly-budget-review");
+  });
+
+  it("a fresh vault: existing body search still works (no regression)", async () => {
+    await store.createNote("the widget shipped on time", { path: "unrelated-title" });
+    const hits = await store.searchNotes("widget");
+    expect(hits.map((n) => n.path)).toContain("unrelated-title");
+  });
+});
+
+describe("search — v24 → v25 migration (legacy vault upgrade)", () => {
+  /**
+   * Build a v24-shaped vault by hand: the OLD single-column notes_fts
+   * (content only), the OLD triggers (UPDATE OF content only — no path
+   * sync), and a handful of notes seeded BEFORE the migration runs —
+   * mirroring the real upgrade scenario (existing data, not a fresh DB).
+   * `initSchema` then drives the whole migration chain up through v25.
+   */
+  function buildLegacyV24Vault(): Database {
+    const legacy = new Database(":memory:");
+    legacy.exec(`
+      CREATE TABLE notes (
+        id TEXT PRIMARY KEY,
+        content TEXT DEFAULT '',
+        path TEXT,
+        metadata TEXT DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        updated_at TEXT,
+        extension TEXT NOT NULL DEFAULT 'md',
+        created_by TEXT,
+        created_via TEXT,
+        last_updated_by TEXT,
+        last_updated_via TEXT
+      );
+      CREATE TABLE tags (
+        name TEXT PRIMARY KEY,
+        description TEXT,
+        fields TEXT,
+        relationships TEXT,
+        parent_names TEXT,
+        created_at TEXT,
+        updated_at TEXT
+      );
+      CREATE TABLE note_tags (
+        note_id TEXT NOT NULL,
+        tag_name TEXT NOT NULL,
+        PRIMARY KEY (note_id, tag_name)
+      );
+      CREATE TABLE indexed_fields (
+        field TEXT PRIMARY KEY,
+        sqlite_type TEXT NOT NULL,
+        declarer_tags TEXT NOT NULL DEFAULT '[]'
+      );
+      CREATE TABLE schema_version (version INTEGER PRIMARY KEY, applied_at TEXT);
+      INSERT INTO schema_version (version, applied_at) VALUES (24, '2026-01-01T00:00:00.000Z');
+
+      CREATE VIRTUAL TABLE notes_fts USING fts5(
+        content,
+        content='notes',
+        content_rowid='rowid'
+      );
+      CREATE TRIGGER notes_fts_insert AFTER INSERT ON notes BEGIN
+        INSERT INTO notes_fts(rowid, content) VALUES (new.rowid, new.content);
+      END;
+      CREATE TRIGGER notes_fts_delete AFTER DELETE ON notes BEGIN
+        INSERT INTO notes_fts(notes_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+      END;
+      CREATE TRIGGER notes_fts_update AFTER UPDATE OF content ON notes BEGIN
+        INSERT INTO notes_fts(notes_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+        INSERT INTO notes_fts(rowid, content) VALUES (new.rowid, new.content);
+      END;
+    `);
+
+    // Seed BEFORE migration — real-data-like: some notes with a path, one
+    // without (path IS NULL — the coalesce-to-'' path must not throw).
+    const insert = legacy.prepare(
+      "INSERT INTO notes (id, content, path, created_at, updated_at) VALUES (?, ?, ?, ?, ?)",
+    );
+    insert.run(
+      "legacy-1",
+      "a dedicated writeup mentioning propolis only once in passing text",
+      "beekeeping-notes",
+      "2026-01-01T00:00:00.000Z",
+      "2026-01-01T00:00:00.000Z",
+    );
+    insert.run(
+      "legacy-2",
+      "nothing about the topic here at all",
+      "propolis",
+      "2026-01-02T00:00:00.000Z",
+      "2026-01-02T00:00:00.000Z",
+    );
+    insert.run(
+      "legacy-3",
+      "the firefighters responded quickly to the call",
+      null,
+      "2026-01-03T00:00:00.000Z",
+      "2026-01-03T00:00:00.000Z",
+    );
+    // Manually populate the OLD single-column FTS index (mirrors what the
+    // old triggers would have done on real inserts).
+    legacy.exec(`INSERT INTO notes_fts(rowid, content) SELECT rowid, content FROM notes`);
+
+    return legacy;
+  }
+
+  it("migrates a v24 vault to the current SCHEMA_VERSION without throwing", () => {
+    const legacy = buildLegacyV24Vault();
+    expect(() => initSchema(legacy)).not.toThrow();
+    const ver = (legacy.prepare("SELECT MAX(version) AS v FROM schema_version").get() as { v: number }).v;
+    expect(ver).toBe(SCHEMA_VERSION);
+  });
+
+  it("post-migration: notes_fts carries path + content columns", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    const cols = (legacy.prepare("PRAGMA table_info(notes_fts)").all() as { name: string }[]).map(
+      (r) => r.name,
+    );
+    expect(cols).toContain("path");
+    expect(cols).toContain("content");
+  });
+
+  it("post-migration: a note's TITLE is searchable (impossible pre-v25)", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    // "beekeeping-notes" (legacy-1's path) never appears in any note's body.
+    const hits = noteOps.searchNotes(legacy, "beekeeping");
+    expect(hits.map((n) => n.id)).toContain("legacy-1");
+  });
+
+  it("post-migration: existing body search still works (no regression from the rebuild)", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    const hits = noteOps.searchNotes(legacy, "firefighters");
+    expect(hits.map((n) => n.id)).toContain("legacy-3");
+  });
+
+  it("post-migration: porter stemming matches a regular-affix variant not present verbatim", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    // legacy-3's body has "firefighters" (plural) — singular query must match.
+    const hits = noteOps.searchNotes(legacy, "firefighter");
+    expect(hits.map((n) => n.id)).toContain("legacy-3");
+  });
+
+  it("post-migration: a title match ranks ABOVE a passing body-only mention, and both carry a score", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    // legacy-2's path IS "propolis" (title match); legacy-1's body mentions
+    // "propolis" once in passing (body-only match). Weighted bm25 must rank
+    // the title match first.
+    const hits = noteOps.searchNotes(legacy, "propolis");
+    const ids = hits.map((n) => n.id);
+    expect(ids.indexOf("legacy-2")).toBeLessThan(ids.indexOf("legacy-1"));
+    for (const n of hits) {
+      expect(typeof n.score).toBe("number");
+    }
+    const byId = new Map(hits.map((n) => [n.id, n.score!]));
+    expect(byId.get("legacy-2")!).toBeGreaterThan(byId.get("legacy-1")!);
+  });
+
+  it("post-migration: a note that had NO path (path IS NULL) survived the rebuild and stays body-searchable", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    const hits = noteOps.searchNotes(legacy, "firefighters");
+    expect(hits.some((n) => n.id === "legacy-3")).toBe(true);
+  });
+
+  it("post-migration: the FTS index isn't duplicated or corrupted — an integrity-check passes", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    // FTS5's built-in consistency check: throws if the shadow tables and
+    // the external-content table have drifted apart (e.g. double-inserted
+    // rows from a repopulation bug).
+    expect(() => legacy.exec(`INSERT INTO notes_fts(notes_fts) VALUES('integrity-check')`)).not.toThrow();
+  });
+
+  it("migration is idempotent — running initSchema twice does not duplicate rows or throw", () => {
+    const legacy = buildLegacyV24Vault();
+    initSchema(legacy);
+    expect(() => initSchema(legacy)).not.toThrow();
+    const hits = noteOps.searchNotes(legacy, "firefighter");
+    // Exactly one match, not duplicated by a second repopulation pass.
+    expect(hits.filter((n) => n.id === "legacy-3").length).toBe(1);
+    expect(() => legacy.exec(`INSERT INTO notes_fts(notes_fts) VALUES('integrity-check')`)).not.toThrow();
+  });
+
+  it("migration is idempotent on a vault that was ALREADY on v25 (e.g. a fresh vault) — no rebuild, no data loss", async () => {
+    // `store`/`db` from the outer beforeEach is already a fresh v25 vault.
+    await store.createNote("hello world", { path: "greeting" });
+    expect(() => initSchema(db)).not.toThrow();
+    const hits = await store.searchNotes("hello");
+    expect(hits.length).toBe(1);
+  });
+
+  /**
+   * MUST-FIX (generalist review, #565) — LOAD-BEARING regression guard: the
+   * whole DDL + repopulation runs inside ONE `transaction`, so a crash partway
+   * through can NEVER leave a recreated-but-EMPTY notes_fts (which the
+   * path-column idempotency guard would then treat as "done," leaving search
+   * permanently empty).
+   *
+   * This drives the REAL `migrateToV25` (via `initSchema`) and injects the
+   * crash by monkey-patching `db.prepare` to throw on the repopulation
+   * `INSERT INTO notes_fts(rowid, path, content)` statement — a faithful
+   * mid-migration interruption AFTER the rebuild DDL (which runs via
+   * `db.exec`, untouched by the patch) but during repopulation. It does NOT
+   * hand-roll its own copy of the DDL: an earlier draft did, which made it a
+   * generic "transaction() rolls back DDL" test that stayed green even against
+   * the pre-fix unwrapped-DDL code. Driving `initSchema` means the test
+   * actually guards `migrateToV25`'s OWN transaction wrapping — verified by
+   * reverting the fix locally (DDL moved back outside `transaction`) and
+   * confirming this test goes RED (the post-crash `ftsCols()` reads
+   * `["path","content"]`, the guard skips on restart, and recovery search is
+   * empty).
+   *
+   * The load-bearing assertion is (a): post-crash `ftsCols() === ["content"]`
+   * — the rollback restored the pre-v25 shape. Under the unwrapped-DDL
+   * regression the recreated table would still carry `path` here.
+   */
+  it("a REAL interrupted migrateToV25 (crash during repopulation) rolls back to the v24 shape — the next initSchema fully recovers, never silent-empty", () => {
+    const legacy = buildLegacyV24Vault();
+
+    const ftsCols = () =>
+      (legacy.prepare("PRAGMA table_info(notes_fts)").all() as { name: string }[]).map((c) => c.name);
+    const ftsShadowTables = () =>
+      (
+        legacy
+          .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'notes_fts%' ORDER BY name")
+          .all() as { name: string }[]
+      ).map((r) => r.name);
+
+    // Sanity: starts on the OLD single-column shape.
+    expect(ftsCols()).toEqual(["content"]);
+    const shadowsBefore = ftsShadowTables();
+
+    // Monkey-patch prepare so migrateToV25's repopulation INSERT throws —
+    // everything else (earlier migrations, the guard's PRAGMA, the
+    // repopulation SELECT, the DDL via db.exec) delegates to the real prepare.
+    const origPrepare = legacy.prepare.bind(legacy);
+    let injected = false;
+    (legacy as any).prepare = (sql: string) => {
+      if (!injected && /INSERT INTO notes_fts\(rowid, path, content\)/.test(sql)) {
+        injected = true;
+        throw new Error("simulated crash during notes_fts repopulation");
+      }
+      return origPrepare(sql);
+    };
+
+    // initSchema runs the whole migration chain; migrateToV25 throws mid-repopulation.
+    expect(() => initSchema(legacy)).toThrow("simulated crash during notes_fts repopulation");
+    // Positive control: the injection actually fired (not a vacuous pass).
+    expect(injected).toBe(true);
+
+    // Restore the real prepare for the assertions + recovery run.
+    (legacy as any).prepare = origPrepare;
+
+    // (a) LOAD-BEARING: rollback restored the v24 single-column shape. Under
+    //     the pre-fix shape (DDL OUTSIDE the transaction) this reads
+    //     ["path","content"], the hasColumn(notes_fts,"path") guard skips on
+    //     restart, and search stays silently empty forever.
+    expect(ftsCols()).toEqual(["content"]);
+    // schema_version never advanced past the fixture's 24.
+    expect(
+      (legacy.prepare("SELECT MAX(version) AS v FROM schema_version").get() as { v: number }).v,
+    ).toBe(24);
+    // No orphaned/duplicated FTS shadow tables — the set is exactly what it was.
+    expect(ftsShadowTables()).toEqual(shadowsBefore);
+    // The restored v24 index is intact + consistent (integrity-check passes).
+    expect(() => legacy.exec(`INSERT INTO notes_fts(notes_fts) VALUES('integrity-check')`)).not.toThrow();
+
+    // (b) A clean restart re-runs the REAL migration and fully populates
+    //     search — both a title-only term and a body term are findable.
+    initSchema(legacy);
+    expect(ftsCols()).toContain("path");
+    expect(noteOps.searchNotes(legacy, "beekeeping").map((n) => n.id)).toContain("legacy-1"); // title-only
+    expect(noteOps.searchNotes(legacy, "firefighters").map((n) => n.id)).toContain("legacy-3"); // body
+    expect(() => legacy.exec(`INSERT INTO notes_fts(notes_fts) VALUES('integrity-check')`)).not.toThrow();
+  });
+});
+
+describe("search — FTS sync triggers keep path + content current (schema v25)", () => {
+  it("a note created with no path is indexed fine (empty path, not an error)", async () => {
+    const note = await store.createNote("body text only, no title");
+    const hits = await store.searchNotes("body");
+    expect(hits.map((n) => n.id)).toContain(note.id);
+  });
+
+  it("a path-ONLY update (content untouched) is now synced to the index — pre-v25 this was invisible to notes_fts", async () => {
+    const note = await store.createNote("unrelated body text", { path: "oldtitle" });
+    expect((await store.searchNotes("oldtitle")).map((n) => n.id)).toContain(note.id);
+    await store.updateNote(note.id, { path: "newtitle" });
+    expect((await store.searchNotes("newtitle")).map((n) => n.id)).toContain(note.id);
+    expect((await store.searchNotes("oldtitle")).map((n) => n.id)).not.toContain(note.id);
+  });
+
+  it("deleting a note removes it from both the path and content index", async () => {
+    const note = await store.createNote("nothing in the body matches this term", {
+      path: "uniquetitleterm",
+    });
+    expect((await store.searchNotes("uniquetitleterm")).map((n) => n.id)).toContain(note.id);
+    expect((await store.searchNotes("nothing")).map((n) => n.id)).toContain(note.id);
+    await store.deleteNote(note.id);
+    expect((await store.searchNotes("uniquetitleterm")).map((n) => n.id)).not.toContain(note.id);
+    expect((await store.searchNotes("nothing")).map((n) => n.id)).not.toContain(note.id);
+  });
+});

package/core/src/store.ts

@@ -741,22 +741,29 @@ export class BunSqliteStore implements Store {
         // Throws IndexedFieldError on an invalid identifier (e.g. kebab-case).
         indexedFieldOps.validateFieldName(fieldName);
       }
-      // Default-conformance pre-validate (vault#553 Decision B) — mirrors the
-      // indexed-type/name checks above: fail BEFORE any persistence so a bad
-      // `default` never gets written. Runs over EVERY field in the full
-      // (already-merged) `nextFields` map, not just indexed ones — a default
-      // that doesn't match its own field's type/enum is a tag-schema error
-      // regardless of queryability. This is the REST parity path: MCP's
-      // `update-tag` tool ALSO calls `collectTagFieldViolations` before
-      // reaching here (bundling every violation into one `TagFieldConflictError`
-      // — see that function's doc comment), so a conforming MCP call never
-      // trips this; a non-conforming one throws there first. REST has no such
-      // pre-check, so this is REST's only gate — same asymmetry as the
-      // indexed-type/name checks it sits beside.
+      // Default-conformance + type-vocabulary pre-validate (vault#553
+      // Decision B; vault#555 fix 4/5) — mirrors the indexed-type/name
+      // checks above: fail BEFORE any persistence so a bad `default` or an
+      // unrecognized `type` never gets written. Runs over EVERY field in the
+      // full (already-merged) `nextFields` map, not just indexed ones — both
+      // are tag-schema errors regardless of queryability. This is a
+      // DEFENSE-IN-DEPTH backstop, not the primary user-facing gate: both
+      // REST's `PUT /api/tags/:name` (`collectCrossTagFieldViolations` +
+      // `collectOwnFieldDefaultAndTypeViolations`, bundled 422) and MCP's
+      // `update-tag` (`collectTagFieldViolations`, same bundle) now
+      // pre-validate every field and report ALL violations together BEFORE
+      // ever reaching this chokepoint — a conforming call never trips this
+      // fail-fast loop. It stays here so any OTHER caller of
+      // `store.upsertTagRecord` (imports, migrations, scripts) still fails
+      // closed rather than persisting a lying schema.
       for (const [fieldName, spec] of Object.entries(nextFields ?? {})) {
-        const violation = tagSchemaOps.validateFieldDefault(fieldName, spec);
-        if (violation) {
-          throw new tagSchemaOps.InvalidFieldDefaultError(fieldName, violation.message);
+        const typeViolation = tagSchemaOps.validateFieldType(fieldName, spec);
+        if (typeViolation) {
+          throw new tagSchemaOps.InvalidFieldTypeError(fieldName, spec.type);
+        }
+        const defaultViolation = tagSchemaOps.validateFieldDefault(fieldName, spec);
+        if (defaultViolation) {
+          throw new tagSchemaOps.InvalidFieldDefaultError(fieldName, defaultViolation.message);
         }
       }
     }

package/core/src/tag-schemas.ts

@@ -190,6 +190,33 @@ export class InvalidFieldDefaultError extends Error {
   }
 }
 
+/**
+ * Thrown by `upsertTagRecord` (core/src/store.ts's chokepoint) when a
+ * field's declared `type` isn't one of the six recognized values (vault#555
+ * — `update-tag{fields:{weird:{type:"frobnicator"}}}` used to be accepted
+ * and persisted verbatim, no error, for any NON-indexed field: the only
+ * existing type check, `mapFieldType`, ran solely on `indexed: true` fields
+ * — see {@link validateFieldType}'s doc comment). Own-field validation leaf,
+ * same posture as `InvalidFieldDefaultError`.
+ */
+export class InvalidFieldTypeError extends Error {
+  code = "INVALID_FIELD_TYPE" as const;
+  error_type = "invalid_field_type" as const;
+  field: string;
+  type: string;
+  valid_types: readonly string[];
+
+  constructor(field: string, type: string) {
+    super(
+      `field "${field}" declares unknown type "${type}" — must be one of [${VALID_FIELD_TYPES.join(", ")}]`,
+    );
+    this.name = "InvalidFieldTypeError";
+    this.field = field;
+    this.type = type;
+    this.valid_types = VALID_FIELD_TYPES;
+  }
+}
+
 /**
  * Validate that a field's declared `default` (vault#553 Decision B) conforms
  * to its own `type` and (when declared) `enum`. Returns `null` when the
@@ -226,6 +253,73 @@ export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFi
   return null;
 }
 
+/**
+ * The full recognized vocabulary for `TagFieldSchema.type` — storage/
+ * advisory validation accepts all six; only `string`/`integer`/`boolean`
+ * are INDEXABLE (that narrower subset is `indexed-fields.ts`'s `TYPE_MAP`,
+ * enforced separately via `mapFieldType` for `indexed: true` fields).
+ * Matches `defaultMatchesType`'s switch and `schema-defaults.ts`'s
+ * `SchemaField.type` union — kept in lockstep by hand across the two
+ * deliberately-decoupled modules (see `validateFieldDefault`'s doc comment
+ * for why they don't cross-import).
+ */
+export const VALID_FIELD_TYPES = ["string", "number", "integer", "boolean", "array", "object"] as const;
+
+/**
+ * Validate that a field's declared `type` is one of the six recognized
+ * values (vault#555). Returns `null` when `type` is unset (own-field checks
+ * elsewhere already treat an unset type as "nothing to check against") or
+ * recognized; otherwise a {@link TagFieldViolation} with `reason:
+ * "invalid_type"`.
+ *
+ * Before this, a non-indexed field's `type` was NEVER validated anywhere —
+ * `mapFieldType` (the only existing type check) runs solely on fields
+ * declaring `indexed: true`. `update-tag{fields:{weird:{type:"frobnicator"}}}`
+ * on a plain (non-indexed) field silently persisted the bogus type
+ * verbatim; every later read of that field just skipped validation
+ * entirely (`valueMatchesType` in schema-defaults.ts has no vocabulary
+ * entry for it either). This is now the SINGLE gate — indexed fields still
+ * get their own, narrower `unsupported_indexed_type` check (which also
+ * covers a RECOGNIZED-but-unindexable type like `"array"`, a different
+ * case from a genuinely unknown token).
+ *
+ * Pure — never throws; callers ({@link collectTagFieldViolations}'s bundled
+ * MCP/REST report, and the store chokepoint's defense-in-depth pre-validate)
+ * each decide how to surface it.
+ */
+export function validateFieldType(field: string, spec: TagFieldSchema): TagFieldViolation | null {
+  if (!spec.type) return null;
+  if ((VALID_FIELD_TYPES as readonly string[]).includes(spec.type)) return null;
+  return {
+    field,
+    reason: "invalid_type",
+    message: `field "${field}" declares unknown type "${spec.type}" — must be one of [${VALID_FIELD_TYPES.join(", ")}]`,
+  };
+}
+
+/**
+ * Combined own-field `default` + `type` violation collection — no cross-tag
+ * lookups needed, so no `db` parameter (unlike
+ * {@link collectCrossTagFieldViolations}). Used by REST's `PUT
+ * /api/tags/:name` (vault#555 fix — folds these into the SAME bundled
+ * `tag_field_conflict` 422 report as the cross-tag checks, replacing the
+ * old fail-fast single-violation `invalid_field_default` 400) and reused by
+ * {@link collectTagFieldViolations} (MCP) so the two surfaces can't drift on
+ * what counts as an own-field violation.
+ */
+export function collectOwnFieldDefaultAndTypeViolations(
+  incomingFields: Record<string, TagFieldSchema>,
+): TagFieldViolation[] {
+  const violations: TagFieldViolation[] = [];
+  for (const [fieldName, spec] of Object.entries(incomingFields)) {
+    const typeViolation = validateFieldType(fieldName, spec);
+    if (typeViolation) violations.push(typeViolation);
+    const defaultViolation = validateFieldDefault(fieldName, spec);
+    if (defaultViolation) violations.push(defaultViolation);
+  }
+  return violations;
+}
+
 /** Same six-type vocabulary as `TagFieldSchema.type`'s doc comment. Unknown/unset types pass (nothing to check against). */
 function defaultMatchesType(value: unknown, type: string): boolean {
   switch (type) {
@@ -507,7 +601,8 @@ export interface TagFieldViolation {
     | "indexed_flag_conflict"
     | "unsupported_indexed_type"
     | "invalid_field_name"
-    | "invalid_default";
+    | "invalid_default"
+    | "invalid_type";
   message: string;
   /**
    * The conflicting declarer tag — present on the cross-tag reasons
@@ -625,18 +720,24 @@ export function collectCrossTagFieldViolations(
 
 /**
  * Full field-violation collection: {@link collectCrossTagFieldViolations}
- * PLUS the own-field checks (unsupported type for indexing, invalid
- * identifier, and — vault#553 Decision B — a non-conforming `default`).
- * Used by the MCP `update-tag` tool, which — unlike REST — had no prior
- * single-violation status-code contract to preserve for those checks (its
- * old inline loop threw an unstructured `Error` for them, same as
- * everything else pre-#554); collecting everything here is a strict
- * improvement. See {@link collectCrossTagFieldViolations}'s doc comment for
- * why REST calls that narrower function directly instead of this one — REST
- * gets the SAME `invalid_default` coverage via `store.upsertTagRecord`'s
- * fail-fast pre-validate (mirrors its indexed-type/name checks), just as a
- * single-violation `InvalidFieldDefaultError` → 400 rather than a bundled
- * `TagFieldConflictError` → 422.
+ * PLUS EVERY own-field check — {@link collectOwnFieldDefaultAndTypeViolations}
+ * (a non-conforming `default`, vault#553 Decision B; an unrecognized `type`,
+ * vault#555) AND the indexed-only checks (unsupported type for indexing,
+ * invalid identifier). Used by the MCP `update-tag` tool, which — unlike
+ * REST's indexed-type/name path — had no prior single-violation
+ * status-code contract to preserve for those two (its old inline loop threw
+ * an unstructured `Error` for them, same as everything else pre-#554);
+ * collecting everything here is a strict improvement. See
+ * {@link collectCrossTagFieldViolations}'s doc comment for why REST calls
+ * that narrower function directly for the CROSS-tag checks, then ALSO calls
+ * {@link collectOwnFieldDefaultAndTypeViolations} itself (vault#555 fix 5 —
+ * REST used to get `invalid_default` coverage only via
+ * `store.upsertTagRecord`'s fail-fast pre-validate, a single-violation
+ * `InvalidFieldDefaultError` → 400 that silently dropped every OTHER bad
+ * field in the same call; both surfaces now report every own-field default/
+ * type violation together, bundled with the cross-tag ones) — the
+ * indexed-type/name pair stays REST's own single-violation `400
+ * invalid_indexed_field` path (unchanged wire contract, vault#478).
  */
 export function collectTagFieldViolations(
   db: Database,
@@ -644,14 +745,9 @@ export function collectTagFieldViolations(
   incomingFields: Record<string, TagFieldSchema>,
 ): TagFieldViolation[] {
   const violations = collectCrossTagFieldViolations(db, tag, incomingFields);
+  violations.push(...collectOwnFieldDefaultAndTypeViolations(incomingFields));
 
   for (const [fieldName, spec] of Object.entries(incomingFields)) {
-    // Own-field default-conformance check (vault#553 Decision B) — applies
-    // to EVERY field (not just indexed ones); a bad default is a tag-schema
-    // error regardless of whether the field is queryable.
-    const defaultViolation = validateFieldDefault(fieldName, spec);
-    if (defaultViolation) violations.push(defaultViolation);
-
     if (spec.indexed === true) {
       const mapped = mapFieldType(spec.type);
       if (!mapped) {

package/core/src/types.ts

@@ -57,6 +57,21 @@ export interface Note {
    * for the exact degree semantics (self-loop = 2 under `both`).
    */
   linkCount?: number;
+  /**
+   * Full-text search relevance score (vault#551 WS2C — ranking legibility).
+   * ONLY present on results from `search=`/`query-notes{search}` — every
+   * other read path (structured `queryNotes`, `getNoteById`, ...) leaves
+   * this `undefined`. Higher is more relevant — the sign-flipped weighted
+   * `bm25(notes_fts, SEARCH_WEIGHT_PATH, SEARCH_WEIGHT_CONTENT)` value (raw
+   * SQLite bm25 is negative-is-better; flipped here so external callers get
+   * the more intuitive "bigger number wins" convention). Meaningful only
+   * for RELATIVE comparison within one result set — the absolute magnitude
+   * has no fixed scale and isn't comparable across different queries. When
+   * an explicit `sort: "asc"|"desc"` overrides relevance ordering, `score`
+   * is still computed and returned (for legibility) even though it no
+   * longer determines the result order.
+   */
+  score?: number;
 }
 
 // ---- Link ----
@@ -248,6 +263,11 @@ export interface NoteIndex {
   preview: string;
   /** Opt-in link degree (see `Note.linkCount`). */
   linkCount?: number;
+  /** Full-text search relevance score (see `Note.score`). Carried onto the
+   *  lean shape too — search's default response IS the lean `NoteIndex[]`
+   *  (`include_content` is opt-in), so `score` would be invisible in the
+   *  common case if it only lived on the full `Note` shape. */
+  score?: number;
 }
 
 /** Link with hydrated note summaries. */