@openparachute/vault 0.7.0-rc.5 → 0.7.0-rc.7

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/seed-packs.ts

@@ -468,9 +468,9 @@ update-tag {
   tag: "meeting",
   description: "A meeting with notes",
   fields: {
-    held_on: { type: "string", indexed: true },              // queryable with operators
-    status:  { type: "string", enum: ["scheduled", "done"] }, // first enum value is the default
-    rating:  { type: "integer" }
+    held_on: { type: "string", indexed: true },                                         // queryable with operators
+    status:  { type: "string", enum: ["scheduled", "done"], default: "scheduled" },      // explicit default — declare one to auto-fill
+    rating:  { type: "integer" }                                                        // no default — stays unset until written
   }
 }
 \`\`\`
@@ -490,16 +490,23 @@ A few behaviors worth knowing before you write at scale:
   conflict error (re-read, reconcile, retry). For bulk/scripted writes where
   concurrency is known-safe, pass \`force: true\` to waive the *requirement to
   supply* it. \`append\`/\`prepend\`-only updates are exempt (no-conflict-by-design).
-- **A schema field's default is filled in on write, so it shows up even when you
-  didn't set it.** When a note gets a tag whose schema declares a field, the
-  missing field is back-filled: an \`enum\` field → its **first listed value**, an
-  \`integer\` → \`0\`, a \`boolean\` → \`false\`, a plain string → \`""\`. So a
-  \`rating: { type: "integer" }\` reads as \`0\` on notes nobody rated — that \`0\`
-  is "unset," not "rated zero." Order an \`enum\`'s values so the first is a sane
-  default, and don't read a back-filled \`0\`/\`""\`/\`false\` as a real value.
-- **Validation is advisory, never blocking.** A type/enum mismatch comes back as
-  a \`validation_status\` warning on the write response — the write still lands.
-  Read those warnings and self-correct on the next turn.
+- **A schema field only back-fills when you declare an explicit \`default\`.**
+  When a note gets a tag whose schema declares a field with a \`default\`, an
+  unset field is filled with THAT value. A field with no \`default\` stays
+  genuinely absent — \`query-notes { metadata: { rating: { exists: false } } }\`
+  reliably finds notes that never set \`rating\`. Declare \`default\` on a field
+  only when "unset" and "explicitly set to X" should read the same; leave it
+  off when you need to tell them apart.
+- **Validation is advisory, never blocking — EXCEPT an \`indexed: true\`
+  field's type.** A type/enum mismatch on a non-indexed field (or a
+  non-\`strict\` constraint on any field) comes back as a \`validation_status\`
+  warning and the write still lands — read those warnings and self-correct on
+  the next turn. An \`indexed: true\` field's TYPE is always enforced, though:
+  writing a string into an indexed \`integer\` field is REJECTED with a
+  \`schema_validation\` error, because a bad-typed value would otherwise
+  silently poison range queries (\`gt\`/\`gte\`/\`lt\`/\`lte\`) on that field. Mark a
+  field \`strict: true\` to enforce its OTHER constraints
+  (enum/required/cardinality) the same hard way.
 
 (Full design guide, with copy-paste examples: https://parachute.computer/scripting/)
 

package/core/src/store.ts

@@ -741,6 +741,24 @@ 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.
+      for (const [fieldName, spec] of Object.entries(nextFields ?? {})) {
+        const violation = tagSchemaOps.validateFieldDefault(fieldName, spec);
+        if (violation) {
+          throw new tagSchemaOps.InvalidFieldDefaultError(fieldName, violation.message);
+        }
+      }
     }
 
     // Persist the record + reconcile the indexed-field lifecycle atomically.

package/core/src/tag-schemas.ts

@@ -44,6 +44,25 @@ export interface TagFieldSchema {
   // "one" (scalar, default) or "many" (array). Advisory unless `strict:true`.
   // Distinct from relationship cardinality. vault#299.
   cardinality?: "one" | "many";
+  /**
+   * Explicit backfill value (vault#553 Decision B). When a note gains this
+   * tag and doesn't set the field, `applySchemaDefaults` (core/src/mcp.ts)
+   * writes THIS value onto the note. Undeclared (the default) means the
+   * field stays ABSENT on notes that don't set it — no more implicit
+   * first-enum-value / type-zero-value backfill. This is what makes
+   * `exists:false` trustworthy: "never set" and "explicitly set to the
+   * default" are now distinguishable states.
+   *
+   * Must conform to this field's own `type` (and `enum`, when declared) —
+   * `upsertTagRecord` (core/src/store.ts, the single chokepoint both REST
+   * and MCP funnel through) validates the default BEFORE persisting via
+   * {@link validateFieldDefault}; a non-conforming default is a tag-schema
+   * error (`invalid_field_default` / `TagFieldViolation` reason
+   * `"invalid_default"`), not a silent typo. `undefined` is JSON-serialized
+   * away by `JSON.stringify` — an omitted `default` key round-trips as "not
+   * declared", never as a stored `null`.
+   */
+  default?: unknown;
 }
 
 /**
@@ -147,6 +166,86 @@ export function getTagRecord(db: Database, tag: string): TagRecord | null {
  * for a tag-scoped caller (`scrubParentCycleError` in src/tag-scope.ts),
  * same posture as `TagFieldConflictError`.
  */
+/**
+ * Thrown by `upsertTagRecord` (core/src/store.ts's chokepoint — REST
+ * `PUT /api/tags/:name` and MCP `update-tag` both funnel through it) when a
+ * field's declared `default` (vault#553 Decision B) doesn't conform to that
+ * SAME field's own `type` (or `enum`, when declared). A bad default is a
+ * tag-schema authoring error, not silently-accepted junk that would poison
+ * every note gaining the tag — fail closed, same posture as
+ * `IndexedFieldError` and `ParentCycleError`. `error_type` is stamped
+ * directly (own-field validation leaf, one caller-facing shape) so the
+ * generic MCP domain-error mapping (`src/mcp-http.ts`) and REST's dedicated
+ * catch branch both surface it without a bespoke class-specific mapping.
+ */
+export class InvalidFieldDefaultError extends Error {
+  code = "INVALID_FIELD_DEFAULT" as const;
+  error_type = "invalid_field_default" as const;
+  field: string;
+
+  constructor(field: string, message: string) {
+    super(message);
+    this.name = "InvalidFieldDefaultError";
+    this.field = field;
+  }
+}
+
+/**
+ * Validate that a field's declared `default` (vault#553 Decision B) conforms
+ * to its own `type` and (when declared) `enum`. Returns `null` when the
+ * field has no `default` (the common case) or the default is valid;
+ * otherwise a {@link TagFieldViolation} with `reason: "invalid_default"`.
+ * Pure — never throws; the two callers (the store chokepoint's fail-fast
+ * pre-validate, and {@link collectTagFieldViolations}'s bundled MCP report)
+ * each decide how to surface it.
+ *
+ * Deliberately independent of `schema-defaults.ts`'s `valueMatchesType` (this
+ * module doesn't import that one, and vice versa — no cycle either way) so
+ * the two modules' type vocabularies can drift without cross-coupling; the
+ * rules are kept in lockstep by hand (string/number/integer/boolean/array/
+ * object, the SAME six as `TagFieldSchema.type`'s documented vocabulary).
+ */
+export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFieldViolation | null {
+  if (spec.default === undefined) return null;
+  const value = spec.default;
+  const typeOk = defaultMatchesType(value, spec.type);
+  if (!typeOk) {
+    return {
+      field,
+      reason: "invalid_default",
+      message: `field "${field}" declares default ${JSON.stringify(value)}, which does not match its own type "${spec.type}"`,
+    };
+  }
+  if (spec.enum && spec.enum.length > 0 && typeof value === "string" && !spec.enum.includes(value)) {
+    return {
+      field,
+      reason: "invalid_default",
+      message: `field "${field}" declares default "${value}", which is not one of its own enum values [${spec.enum.join(", ")}]`,
+    };
+  }
+  return null;
+}
+
+/** 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) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return !!value && typeof value === "object" && !Array.isArray(value);
+    default:
+      return true;
+  }
+}
+
 export class ParentCycleError extends Error {
   code = "PARENT_CYCLE" as const;
   error_type = "parent_cycle" as const;
@@ -403,7 +502,12 @@ function jsonOrNull(value: unknown): string | null {
  */
 export interface TagFieldViolation {
   field: string;
-  reason: "type_conflict" | "indexed_flag_conflict" | "unsupported_indexed_type" | "invalid_field_name";
+  reason:
+    | "type_conflict"
+    | "indexed_flag_conflict"
+    | "unsupported_indexed_type"
+    | "invalid_field_name"
+    | "invalid_default";
   message: string;
   /**
    * The conflicting declarer tag — present on the cross-tag reasons
@@ -522,12 +626,17 @@ export function collectCrossTagFieldViolations(
 /**
  * Full field-violation collection: {@link collectCrossTagFieldViolations}
  * PLUS the own-field checks (unsupported type for indexing, invalid
- * identifier). Used by the MCP `update-tag` tool, which — unlike REST — had
- * no prior single-violation status-code contract to preserve for those two
- * checks (its old inline loop threw an unstructured `Error` for them, same
- * as everything else pre-#554); collecting everything here is a strict
+ * 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.
+ * 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.
  */
 export function collectTagFieldViolations(
   db: Database,
@@ -537,6 +646,12 @@ export function collectTagFieldViolations(
   const violations = collectCrossTagFieldViolations(db, tag, 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.0-rc.5",
+  "version": "0.7.0-rc.7",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",