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

package/core/src/attribution.test.ts

@@ -42,8 +42,12 @@ function rawRow(id: string) {
 }
 
 describe("write-attribution — schema", () => {
-  it("bumped SCHEMA_VERSION to 23", () => {
-    expect(SCHEMA_VERSION).toBe(23);
+  it("bumped SCHEMA_VERSION to at least 23 (write-attribution columns landed)", () => {
+    // Was a literal `toBe(23)` pin — that goes stale every time a later PR
+    // bumps SCHEMA_VERSION further (vault#553 bumped it to 24). This test's
+    // actual claim is "the write-attribution migration landed at/after v23",
+    // not "v23 is still current."
+    expect(SCHEMA_VERSION).toBeGreaterThanOrEqual(23);
   });
 
   it("the four columns exist and are indexed", () => {
@@ -230,7 +234,11 @@ describe("write-attribution — legacy backfill (v23 migration)", () => {
     const ver = (legacy.prepare("SELECT MAX(version) AS v FROM schema_version").get() as {
       v: number;
     }).v;
-    expect(ver).toBe(23);
+    // A v22 vault runs the WHOLE migration chain (v23 write-attribution +
+    // whatever landed after — v24's typed-index poison scan, vault#553),
+    // ending at the current SCHEMA_VERSION rather than a hardcoded literal
+    // that goes stale on every later bump.
+    expect(ver).toBe(SCHEMA_VERSION);
 
     // Legacy row: attribution columns exist now but are NULL (not fabricated).
     const old = legacy

package/core/src/contract-typed-index.test.ts

@@ -20,9 +20,11 @@
 import { describe, it, test, expect, beforeEach } from "bun:test";
 import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
-import { generateMcpTools } from "./mcp.js";
+import { generateMcpTools, SchemaValidationError } from "./mcp.js";
 import { TransitionConflictError } from "./notes.js";
+import * as noteOps from "./notes.js";
 import { TagFieldConflictError } from "./tag-schemas.js";
+import { initSchema, SCHEMA_VERSION } from "./schema.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -91,16 +93,231 @@ describe("contract: typed indexes — passing (lock in current behavior)", () =>
   });
 });
 
-describe("contract: typed indexes — todo (#553)", () => {
-  test.todo(
-    `#553: a write of a TEXT value to an indexed integer field is REJECTED (today: it is accepted with only an advisory type_mismatch warning, and the poisoned row then silently matches {gt: 100}-style range queries via SQLite's TEXT-sorts-above-INTEGER type-affinity ordering — reproduced live: metadata.n = "four" on an indexed integer field succeeds, and query {n: {gt: 100}} incorrectly returns it)`,
-  );
-  test.todo(
-    `#553: an unset enum field stays ABSENT — no first-value backfill — so exists:false correctly matches a note that never set the field (today: applySchemaDefaults in core/src/mcp.ts backfills the schema's first enum value onto every note that gains the tag, so "never set" is indistinguishable from "explicitly set to the default" and exists:false never matches)`,
-  );
-  test.todo(
-    `#553: the indexed-field type list is honest about what's actually indexable (core/src/mcp.ts's update-tag field-type description advertises "string, boolean, integer, number, array, object" but indexed-fields.ts's TYPE_MAP only supports string/integer/boolean — "number" and the container types are accepted as declared but silently un-indexable)`,
-  );
+describe("contract: typed indexes — Decision A: indexed ⇒ strict writes (#553, flipped from todo)", () => {
+  it("a write of a TEXT value to an indexed integer field is REJECTED, not just warned", async () => {
+    await store.upsertTagRecord("metric", { fields: { n: { type: "integer", indexed: true } } });
+    const create = generateMcpTools(store).find((t) => t.name === "create-note")!;
+
+    let err: any;
+    try {
+      await create.execute({ content: "x", tags: ["metric"], metadata: { n: "four" } });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(SchemaValidationError);
+    expect(err.violations).toHaveLength(1);
+    expect(err.violations[0].field).toBe("n");
+    expect(err.violations[0].reason).toBe("type_mismatch");
+    expect(err.violations[0].strict).toBe(true);
+    // Message names field + expected type + got type.
+    expect(err.violations[0].message).toContain("n");
+    expect(err.violations[0].message).toContain("integer");
+    expect(err.violations[0].message).toContain("string");
+
+    // Nothing was written — the poisoned row never lands, so it can never
+    // sort above a real integer under {gt: 100}-style range queries.
+    const all = await store.queryNotes({ tags: ["metric"] });
+    expect(all).toHaveLength(0);
+  });
+
+  it("rejects the same indexed-type violation on update-note", async () => {
+    await store.upsertTagRecord("metric", { fields: { n: { type: "integer", indexed: true } } });
+    const create = generateMcpTools(store).find((t) => t.name === "create-note")!;
+    const update = generateMcpTools(store).find((t) => t.name === "update-note")!;
+    const note = (await create.execute({ content: "x", tags: ["metric"], metadata: { n: 5 } })) as any;
+
+    await expect(
+      update.execute({ id: note.id, metadata: { n: "four" }, if_updated_at: note.updatedAt }),
+    ).rejects.toThrow(SchemaValidationError);
+
+    // Untouched — still the original, well-typed value.
+    const fresh = await store.getNote(note.id);
+    expect((fresh!.metadata as any).n).toBe(5);
+  });
+
+  it("a range query never matches a TEXT value on an indexed integer field (the poisoning is now unreachable)", async () => {
+    await store.upsertTagRecord("metric", { fields: { n: { type: "integer", indexed: true } } });
+    const create = generateMcpTools(store).find((t) => t.name === "create-note")!;
+    await create.execute({ content: "n=5", tags: ["metric"], metadata: { n: 5 } });
+    await expect(
+      create.execute({ content: "poison", tags: ["metric"], metadata: { n: "four" } }),
+    ).rejects.toThrow(SchemaValidationError);
+
+    const gt100 = await store.queryNotes({ tags: ["metric"], metadata: { n: { gt: 100 } } });
+    expect(gt100).toHaveLength(0);
+  });
+
+  it("a type_mismatch on a NON-indexed field stays advisory (unchanged behavior — the escalation is scoped to indexed:true)", async () => {
+    await store.upsertTagRecord("metric", { fields: { n: { type: "integer" } } });
+    const create = generateMcpTools(store).find((t) => t.name === "create-note")!;
+    const note = (await create.execute({ content: "x", tags: ["metric"], metadata: { n: "four" } })) as any;
+    // Write succeeded — advisory only.
+    expect(note.metadata.n).toBe("four");
+    expect(note.validation_status.warnings[0].reason).toBe("type_mismatch");
+    expect(note.validation_status.warnings[0].strict).toBeUndefined();
+  });
+});
+
+describe("contract: typed indexes — Decision B: explicit-default-only enum backfill (#553, flipped from todo)", () => {
+  it("an unset enum field stays ABSENT — no first-value backfill — so exists:false correctly matches", async () => {
+    await store.upsertTagRecord("task", {
+      fields: { status: { type: "string", enum: ["queued", "done"], indexed: true } }, // no `default`
+    });
+    const create = generateMcpTools(store).find((t) => t.name === "create-note")!;
+    const query = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+
+    const note = (await create.execute({ content: "x", tags: ["task"] })) as any;
+    expect(note.metadata?.status).toBeUndefined();
+    const onDisk = await store.getNote(note.id);
+    expect((onDisk!.metadata as any)?.status).toBeUndefined();
+
+    const unset = (await query.execute({
+      tag: "task",
+      metadata: { status: { exists: false } },
+    })) as any[];
+    expect(unset.map((n) => n.id)).toContain(note.id);
+
+    const set = (await query.execute({
+      tag: "task",
+      metadata: { status: { exists: true } },
+    })) as any[];
+    expect(set.map((n) => n.id)).not.toContain(note.id);
+  });
+
+  it("an EXPLICIT `default:` backfills as before — exists:true matches it", async () => {
+    await store.upsertTagRecord("task", {
+      fields: { status: { type: "string", enum: ["queued", "done"], default: "queued", indexed: true } },
+    });
+    const create = generateMcpTools(store).find((t) => t.name === "create-note")!;
+    const query = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+
+    const note = (await create.execute({ content: "x", tags: ["task"] })) as any;
+    expect(note.metadata.status).toBe("queued");
+
+    const set = (await query.execute({
+      tag: "task",
+      metadata: { status: { exists: true } },
+    })) as any[];
+    expect(set.map((n) => n.id)).toContain(note.id);
+  });
+
+  it("a non-conforming `default` is rejected as a tag-schema error, not silently stored", async () => {
+    const updateTag = generateMcpTools(store).find((t) => t.name === "update-tag")!;
+    let err: any;
+    try {
+      await updateTag.execute({
+        tag: "task",
+        fields: { status: { type: "string", enum: ["queued", "done"], default: "bogus" } },
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(TagFieldConflictError);
+    expect(err.violations.some((v: any) => v.reason === "invalid_default" && v.field === "status")).toBe(true);
+    // Nothing persisted.
+    expect((await store.getTagRecord("task"))?.fields ?? null).toBeFalsy();
+  });
+});
+
+describe("contract: typed indexes — Decision C: honest type list (#553, flipped from todo)", () => {
+  it("the update-tag field-type description clarifies only string/integer/boolean are indexable", () => {
+    const updateTag = generateMcpTools(store).find((t) => t.name === "update-tag")!;
+    const typeDesc = (updateTag.inputSchema as any).properties.fields.additionalProperties.properties.type.description as string;
+    // Honest about the full storage/advisory vocabulary AND the indexable subset.
+    expect(typeDesc).toContain("number");
+    expect(typeDesc).toContain("Only string/integer/boolean are INDEXABLE");
+  });
+
+  it("declaring indexed:true with an unindexable type (number) is rejected", async () => {
+    const updateTag = generateMcpTools(store).find((t) => t.name === "update-tag")!;
+    let err: any;
+    try {
+      await updateTag.execute({ tag: "metric", fields: { score: { type: "number", indexed: true } } });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(TagFieldConflictError);
+    expect(err.violations[0].reason).toBe("unsupported_indexed_type");
+  });
+
+  it("declaring a number field WITHOUT indexed:true is accepted (storage/advisory only)", async () => {
+    const updateTag = generateMcpTools(store).find((t) => t.name === "update-tag")!;
+    const result = await updateTag.execute({ tag: "metric", fields: { score: { type: "number" } } }) as any;
+    expect(result.fields.score.type).toBe("number");
+  });
+});
+
+describe("contract: typed indexes — Decision D: migrateToV24 poison coercion (#553, new)", () => {
+  it("coerces a lossless numeric string, leaves a genuinely non-coercible string, and is idempotent on re-run", async () => {
+    // Declare the field indexed AFTER notes already exist (real-data-like:
+    // a field indexed retroactively on a vault with pre-existing rows).
+    const clean = noteOps.createNote(db, "clean", { metadata: { n: 42 } });
+    const coercible = noteOps.createNote(db, "coercible", { metadata: { n: "5" } }); // clean numeric string
+    const nonCoercible = noteOps.createNote(db, "non-coercible", { metadata: { n: "hello" } });
+    const boolish = noteOps.createNote(db, "boolish", { metadata: { flag: "true" } });
+
+    await store.upsertTagRecord("metric", {
+      fields: {
+        n: { type: "integer", indexed: true },
+        flag: { type: "boolean", indexed: true },
+      },
+    });
+    noteOps.tagNote(db, clean.id, ["metric"]);
+    noteOps.tagNote(db, coercible.id, ["metric"]);
+    noteOps.tagNote(db, nonCoercible.id, ["metric"]);
+    noteOps.tagNote(db, boolish.id, ["metric"]);
+
+    // Re-running initSchema (idempotent by construction for every migration
+    // step) exercises migrateToV24's coercion pass over the poison just
+    // planted via the raw noteOps layer (bypassing the strict write gate —
+    // simulating data that predates it, or an operator-side bulk import).
+    initSchema(db);
+
+    const after = (id: string) => (noteOps.getNote(db, id)!.metadata as any);
+    expect(after(clean.id).n).toBe(42); // untouched — was already clean
+    expect(after(coercible.id).n).toBe(5); // coerced: "5" (string) → 5 (number)
+    expect(after(nonCoercible.id).n).toBe("hello"); // LEFT IN PLACE — never deleted or nulled
+    expect(after(boolish.id).flag).toBe(true); // coerced: "true" (string) → true (boolean)
+
+    // Doctor still surfaces the genuinely non-coercible one for operator cleanup.
+    const report = await store.doctor();
+    const finding = report.findings.find(
+      (f) => f.type === "mixed_type_indexed_field" && f.subject === "n",
+    );
+    expect(finding).toBeDefined();
+    expect(finding!.detail).toContain(nonCoercible.id);
+
+    // Idempotency: a second re-run coerces nothing further and doesn't
+    // touch the already-clean/already-coerced/already-left values.
+    initSchema(db);
+    expect(after(clean.id).n).toBe(42);
+    expect(after(coercible.id).n).toBe(5);
+    expect(after(nonCoercible.id).n).toBe("hello");
+    expect(after(boolish.id).flag).toBe(true);
+  });
+
+  it("coerces a number into a TEXT-indexed field losslessly", async () => {
+    const note = noteOps.createNote(db, "x", { metadata: { code: 12345 } });
+    await store.upsertTagRecord("item", { fields: { code: { type: "string", indexed: true } } });
+    noteOps.tagNote(db, note.id, ["item"]);
+
+    initSchema(db);
+    expect((noteOps.getNote(db, note.id)!.metadata as any).code).toBe("12345");
+  });
+
+  it("leaves array/object values in an indexed field untouched (never coercible, never deleted)", async () => {
+    const note = noteOps.createNote(db, "x", { metadata: { n: [1, 2, 3] } });
+    await store.upsertTagRecord("metric", { fields: { n: { type: "integer", indexed: true } } });
+    noteOps.tagNote(db, note.id, ["metric"]);
+
+    initSchema(db);
+    expect((noteOps.getNote(db, note.id)!.metadata as any).n).toEqual([1, 2, 3]);
+  });
+
+  it("is a no-op on a vault with zero indexed fields (schema_version still advances)", async () => {
+    const row = db.prepare("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1").get() as { version: number };
+    expect(row.version).toBe(SCHEMA_VERSION);
+  });
 });
 
 describe("contract: update-tag messaging — #553/#554 (flipped from todo)", () => {

package/core/src/core.test.ts

@@ -2081,8 +2081,11 @@ describe("MCP tools", async () => {
   // schema-default-filled field was missing from the returned note even
   // though it had just been written to disk.
   it("create-note response reflects post-applySchemaDefaults state (vault#316)", async () => {
+    // vault#553 Decision B: backfill is explicit-`default`-only now — declare
+    // one so this test still exercises the post-defaults re-read mechanism
+    // (the thing vault#316 is actually about).
     await store.upsertTagSchema("task", {
-      fields: { priority: { type: "string", enum: ["high", "low"] } },
+      fields: { priority: { type: "string", enum: ["high", "low"], default: "high" } },
     });
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;
@@ -2093,7 +2096,7 @@ describe("MCP tools", async () => {
       path: "Inbox/task-1",
       tags: ["task"],
     }) as any;
-    expect(single.metadata?.priority).toBe("high"); // first enum value
+    expect(single.metadata?.priority).toBe("high"); // explicit schema default
     // Disk and response agree.
     const onDisk = await store.getNoteByPath("Inbox/task-1");
     expect((onDisk!.metadata as any)?.priority).toBe("high");
@@ -3456,7 +3459,7 @@ describe("MCP tools", async () => {
     expect(links.some((l) => l.relationship === "wikilink")).toBe(true);
   });
 
-  it("create-note with schema tag auto-populates defaults", async () => {
+  it("create-note with schema tag leaves undeclared fields ABSENT (vault#553 Decision B — no implicit enum[0]/zero-value backfill)", async () => {
     await store.upsertTagSchema("person", {
       description: "A person",
       fields: {
@@ -3472,10 +3475,36 @@ describe("MCP tools", async () => {
 
     const result = await createNote.execute({ content: "Alice", tags: ["person"] }) as any;
     const fresh = await query.execute({ id: result.id }) as any;
-    expect(fresh.metadata.first_appeared).toBe("");
-    expect(fresh.metadata.active).toBe(false);
-    expect(fresh.metadata.priority).toBe(0);
+    // None of these fields declares a `default` — the pre-0.7.0 behavior
+    // (enum[0] / type zero-value backfill) is retired. "Never set" now stays
+    // genuinely absent instead of masquerading as "explicitly set to X" — in
+    // fact NO field got backfilled, so `metadata` itself stays empty/absent.
+    expect(fresh.metadata?.first_appeared).toBeUndefined();
+    expect(fresh.metadata?.active).toBeUndefined();
+    expect(fresh.metadata?.priority).toBeUndefined();
+    expect(fresh.metadata?.status).toBeUndefined();
+  });
+
+  it("create-note with schema tag applies EXPLICIT `default:` values only (vault#553 Decision B)", async () => {
+    await store.upsertTagSchema("employee", {
+      description: "An employee",
+      fields: {
+        active: { type: "boolean", default: true },
+        priority: { type: "integer", default: 3 },
+        status: { type: "string", enum: ["active", "archived"], default: "active" },
+        nickname: { type: "string" }, // no default — stays absent
+      },
+    });
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const query = tools.find((t) => t.name === "query-notes")!;
+
+    const result = await createNote.execute({ content: "Bob", tags: ["employee"] }) as any;
+    const fresh = await query.execute({ id: result.id }) as any;
+    expect(fresh.metadata.active).toBe(true);
+    expect(fresh.metadata.priority).toBe(3);
     expect(fresh.metadata.status).toBe("active");
+    expect(fresh.metadata.nickname).toBeUndefined();
   });
 
   // ---- query-notes input-shape tolerance (vault#214) ----
@@ -4616,8 +4645,9 @@ describe("update-note if_missing=create (vault#309)", async () => {
   });
 
   it("create branch applies tag-schema defaults when the new tag declares fields", async () => {
+    // vault#553 Decision B: backfill is explicit-`default`-only.
     await store.upsertTagSchema("task", {
-      fields: { priority: { type: "string", enum: ["high", "low"] } },
+      fields: { priority: { type: "string", enum: ["high", "low"], default: "high" } },
     });
     const tools = generateMcpTools(store);
     const update = tools.find((t) => t.name === "update-note")!;
@@ -4629,7 +4659,7 @@ describe("update-note if_missing=create (vault#309)", async () => {
     }) as any;
     expect(result.created).toBe(true);
     // Schema defaults populated metadata.priority on insert.
-    expect(result.metadata?.priority).toBeDefined();
+    expect(result.metadata?.priority).toBe("high");
   });
 
   it("create branch surfaces validation warnings just like create-note", async () => {

package/core/src/doctor.ts

@@ -196,28 +196,58 @@ const EXPECTED_JSON_TYPES: Record<string, Set<string>> = {
   TEXT: new Set(["text"]),
 };
 
+/** One vault-wide-scan result row from {@link findMixedTypeIndexedFieldNotes}. */
+export interface MixedTypeIndexedFieldRow {
+  id: string;
+  /** SQLite `json_type()` of the CURRENT `metadata.<field>` value — "text", "integer", "real", "true", "false", "array", "object" (never "null": absent/null keys are excluded upstream). */
+  jt: string;
+}
+
+/**
+ * Vault-wide detector: every note whose `metadata.<field>` JSON type
+ * disagrees with `sqliteType` (the field's declared indexed storage class —
+ * "INTEGER" or "TEXT"). Returns `[]` for an unknown `sqliteType` or when
+ * nothing mismatches. UNSCOPED — no tag-scope filtering (that's the caller's
+ * job; see `scanMixedTypeIndexedFields` below for the tag-scoped doctor
+ * finding, and `migrateToV24` in `core/src/schema.ts` for the unscoped
+ * migration consumer). `json_type(metadata, ?)` returns NULL when the key is
+ * absent — those notes simply don't declare the field and aren't a mismatch.
+ *
+ * Extracted (vault#553 Decision D) so the SAME detection query backs both
+ * the `mixed_type_indexed_field` doctor finding AND the `migrateToV24`
+ * startup migration's poison scan — one source of truth for "what counts as
+ * mismatched," so a fix to one can't silently diverge from the other.
+ */
+export function findMixedTypeIndexedFieldNotes(
+  db: Database,
+  field: string,
+  sqliteType: string,
+): MixedTypeIndexedFieldRow[] {
+  const expected = EXPECTED_JSON_TYPES[sqliteType];
+  if (!expected) return []; // unknown sqlite_type — nothing to compare against
+  const path = `$."${field}"`;
+  const rows = db
+    .prepare(
+      `SELECT id, json_type(metadata, ?) as jt FROM notes WHERE metadata IS NOT NULL AND metadata != '' AND json_valid(metadata)`,
+    )
+    .all(path) as { id: string; jt: string | null }[];
+  return rows.filter((r): r is MixedTypeIndexedFieldRow => r.jt !== null && !expected.has(r.jt));
+}
+
 function scanMixedTypeIndexedFields(db: Database, allowedTags: Set<string> | null): DoctorFinding[] {
   const findings: DoctorFinding[] = [];
   const noteInScope = makeNoteInScope(db, allowedTags);
   for (const f of listIndexedFields(db)) {
     if (allowedTags && !f.declarerTags.some((t) => allowedTags.has(t))) continue;
-    const expected = EXPECTED_JSON_TYPES[f.sqliteType];
-    if (!expected) continue; // unknown sqlite_type — nothing to compare against
-
-    // `json_type(metadata, ?)` returns NULL when the key is absent — those
-    // notes simply don't declare the field and aren't a mismatch. Only rows
-    // where the key IS present get compared.
-    const path = `$."${f.field}"`;
-    const rows = db
-      .prepare(
-        `SELECT id, json_type(metadata, ?) as jt FROM notes WHERE metadata IS NOT NULL AND metadata != '' AND json_valid(metadata)`,
-      )
-      .all(path) as { id: string; jt: string | null }[];
+
+    const rows = findMixedTypeIndexedFieldNotes(db, f.field, f.sqliteType);
+    if (rows.length === 0) continue;
+
     // Tag-scope (vault#552 auth fold): the note query above is vault-wide —
     // filter mismatches to IN-SCOPE notes so a scoped caller never sees an
     // out-of-scope note id (nor a count/exemplar reflecting one). If every
     // mismatch is on an out-of-scope note, the finding is dropped entirely.
-    const mismatches = rows.filter((r) => r.jt !== null && !expected.has(r.jt) && noteInScope(r.id));
+    const mismatches = rows.filter((r) => noteInScope(r.id));
     if (mismatches.length === 0) continue;
 
     // Also generalize the "Declared by" list to in-scope declarers only —

package/core/src/mcp.ts

@@ -5,7 +5,14 @@ import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import { QueryError } from "./query-operators.js";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "./tag-hierarchy.js";
-import { collectUnknownTagWarnings, emptySearchWarning, ignoredParamWarning, type QueryWarning } from "./query-warnings.js";
+import {
+  collectUnknownTagWarnings,
+  emptySearchWarning,
+  ignoredParamWarning,
+  computeSearchDidYouMean,
+  searchDidYouMeanWarning,
+  type QueryWarning,
+} from "./query-warnings.js";
 import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "./search-query.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
@@ -265,7 +272,9 @@ Response shape (vault#550 — three variants, pick by what you passed):
 - Cursor mode (\`cursor\` param present — including \`cursor: ""\` to bootstrap): \`{notes: [...], next_cursor}\`. See \`cursor\` below for the bootstrap flow.
 - Warnings present (e.g. an unrecognized \`tag\`) and NOT in cursor mode: \`{notes: [...], warnings: [...]}\`. Cursor mode + warnings compose: \`{notes, next_cursor, warnings}\`. Absent \`warnings\` key means nothing to flag — don't assume its presence either way.
 
-\`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.`,
+\`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.
+
+\`search\` indexes BOTH a note's title (\`path\`) and its \`content\` (vault#551 WS2C, schema v25) — a title match is weighted far above a passing body mention, so a dedicated note on a topic outranks another note that merely references it. Every result carries a \`score\` field (higher = more relevant; only meaningful as a RELATIVE comparison within one result set). Word matching also stems regular English affixes ("firefighter" matches "firefighters", "microbe" matches "microbes") — irregular plurals with a consonant change ("wolf"/"wolves") aren't covered by stemming. A search that returns ZERO results may carry a \`search_did_you_mean\` warning suggesting the closest indexed term when one looks like a likely typo (only unscoped sessions — tag-scoped tokens never see it, since the suggestion is computed vault-wide).`,
       inputSchema: {
         type: "object",
         properties: {
@@ -322,7 +331,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
           search: {
             type: "string",
             description:
-              'Full-text search query. Literal-by-default (vault#551): your text is escaped and phrase-quoted before reaching FTS5, so punctuation ("didn\'t", "eleven-day", "18.6") is matched as literal content rather than parsed as FTS5 query syntax. Pass `search_mode: "advanced"` for raw FTS5 syntax (boolean/phrase/prefix operators). `sort` is honored under search (see below) — default is relevance ranking.',
+              'Full-text search query, matched against BOTH a note\'s title (path) and its content — a title match ranks far above a passing body mention. Literal-by-default (vault#551): your text is escaped and phrase-quoted before reaching FTS5, so punctuation ("didn\'t", "eleven-day", "18.6") is matched as literal content rather than parsed as FTS5 query syntax. Pass `search_mode: "advanced"` for raw FTS5 syntax (boolean/phrase/prefix operators). `sort` is honored under search (see below) — default is relevance ranking. Matching stems regular affixes ("firefighter"/"firefighters") but not irregular plurals ("wolf"/"wolves"). Results carry a `score` field (higher = more relevant, relative within this result set only). A zero-result search may carry a `search_did_you_mean` warning (unscoped sessions only).',
           },
           search_mode: {
             type: "string",
@@ -603,6 +612,20 @@ Response shape (vault#550 — three variants, pick by what you passed):
               mode,
               sort: params.sort as "asc" | "desc" | undefined,
             });
+            // Zero-result `did_you_mean` (vault#551 WS2B) — cheap (a bounded
+            // FTS5-vocabulary scan) and ONLY computed on the already-rare
+            // empty-result path, mirroring `unknown_tag`'s did_you_mean.
+            // Scope-unaware by construction (same as `collectUnknownTagWarnings`
+            // above) — safe here because `applyTagScopeWrappers`'s
+            // `query-notes` wrapper (`src/mcp-tools.ts`) strips the ENTIRE
+            // `warnings` array for a tag-scoped session before it reaches the
+            // caller, so this never leaks out-of-scope vocabulary to one.
+            if (results.length === 0) {
+              const suggestion = computeSearchDidYouMean(db, params.search as string);
+              if (suggestion) {
+                queryWarnings.push(searchDidYouMeanWarning(params.search as string, suggestion));
+              }
+            }
           }
         } else {
           // --- Structured query ---
@@ -1588,15 +1611,16 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           description: { type: "string", description: "Human-readable description of what this tag means" },
           fields: {
             type: "object",
-            description: 'Metadata fields notes with this tag should have. E.g., { "status": { "type": "string", "enum": ["active", "archived"], "strict": true } }. Constraints are ADVISORY by default (violations surface as validation_status warnings; the write still succeeds). Mark a field `strict: true` to ENFORCE all its constraints — type + enum + required + cardinality flip to hard write rejections (vault#299).',
+            description: 'Metadata fields notes with this tag should have. E.g., { "status": { "type": "string", "enum": ["active", "archived"], "strict": true, "default": "active" } }. Constraints are ADVISORY by default (violations surface as validation_status warnings; the write still succeeds). Mark a field `strict: true` to ENFORCE all its constraints — type + enum + required + cardinality flip to hard write rejections (vault#299). Mark a field `indexed: true` to make it queryable — an indexed field\'s TYPE is ALWAYS enforced (a type-mismatched write is REJECTED, independent of `strict`) because a bad-typed value silently poisons range-query ordering (vault#553).',
             additionalProperties: {
               type: "object",
               properties: {
-                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object" },
+                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object — all six are accepted for storage + advisory validation. Only string/integer/boolean are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field)." },
                 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." },
-                strict: { type: "boolean", description: "vault#299. Default false (advisory). When true, ALL of this field's declared constraints (type + enum + required + cardinality) are ENFORCED — a violating write is rejected with a schema_validation error, not just warned. All-or-nothing per field; free-form fields on a strict tag simply leave strict off." },
+                enum: { type: "array", items: { type: "string" }, description: "Allowed values. Does NOT auto-backfill — a note that omits this field stays without it unless `default` is also set (vault#553; the pre-0.7.0 behavior of silently defaulting to the first enum value is retired). Set `default` explicitly if you want backfill." },
+                default: { description: "Explicit backfill value (vault#553) applied when a note gains this tag without setting the field. Must conform to this field's own `type` (and `enum`, if declared) — a non-conforming default is rejected (invalid_default / invalid_field_default) rather than silently stored. Omit entirely to leave the field ABSENT (not backfilled) on notes that don't set it — this is what makes `exists:false` a trustworthy \"never set\" query." },
+                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. Only string/integer/boolean are indexable. Indexed ⇒ a type-mismatched write is HARD-REJECTED (schema_validation), not just warned — vault#553." },
+                strict: { type: "boolean", description: "vault#299. Default false (advisory). When true, ALL of this field's declared constraints (type + enum + required + cardinality) are ENFORCED — a violating write is rejected with a schema_validation error, not just warned. All-or-nothing per field; free-form fields on a strict tag simply leave strict off. Note: `indexed: true` fields enforce their TYPE constraint regardless of this flag (vault#553)." },
                 required: { type: "boolean", description: "vault#299. The field must be present + non-null on a note with this tag. Advisory unless `strict: true`." },
                 cardinality: { type: "string", enum: ["one", "many"], description: "vault#299. 'one' (scalar, default) or 'many' (array). Advisory unless `strict: true`." },
               },
@@ -1953,18 +1977,33 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
  * for any field they omitted. Returns the IDs of the notes whose metadata was
  * actually written — callers use this to re-read ONLY the mutated notes (and
  * to skip the re-read entirely when nothing changed). The common no-schema /
- * no-defaults path returns an empty array.
+ * no-declared-defaults path returns an empty array.
+ *
+ * vault#553 Decision B: backfill is EXPLICIT-`default`-only. A field with no
+ * declared `default` is skipped entirely here — it stays genuinely absent on
+ * the note, not silently filled with the first enum value or a type
+ * zero-value (the pre-0.7.0 behavior, which made "never set" and
+ * "explicitly set to the default" indistinguishable and broke `exists:false`).
+ * Exported so `src/routes.ts` (REST create/PATCH) shares this ONE
+ * implementation instead of carrying its own copy — the two had drifted into
+ * a byte-identical duplicate pre-#553; centralizing here means the cloud
+ * runtime (which imports core directly, not `src/routes.ts`) automatically
+ * inherits this behavior with zero handler-side work.
  *
  * vault#299: this runs AFTER the create write (so AFTER the strict gate) and
  * intentionally does NOT re-run `enforceStrict`. Defaults are always
- * conforming by construction — `defaultForField` returns the first enum value
- * / the type's zero-value, so a default can never violate type/enum. And a
- * `required` strict field is already caught at the pre-write gate, so a note
- * that would need a default to satisfy `required` never reaches this filler
- * (the create was rejected first). Don't add a defaults path that could
- * inject a violating value without re-gating.
+ * conforming by construction — `store.upsertTagRecord` validates a field's
+ * `default` against its own `type`/`enum` BEFORE the schema can be persisted
+ * (`InvalidFieldDefaultError` / `TagFieldConflictError` reason
+ * `invalid_default`), so a default can never violate type/enum at read time
+ * here. And a `required` strict field is already caught at the pre-write
+ * gate, so a note that would need a default to satisfy `required` never
+ * reaches this filler (the create was rejected first) — declaring a
+ * `default` does NOT satisfy `required`; the caller must still set the field
+ * explicitly. Don't add a defaults path that could inject a violating value
+ * without re-gating.
  */
-async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<string[]> {
+export async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<string[]> {
   const schemas = tagSchemaOps.getTagSchemaMap(db);
   if (Object.keys(schemas).length === 0) return [];
 
@@ -1973,9 +2012,10 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
     const schema = schemas[tag];
     if (!schema?.fields) continue;
     for (const [field, fieldSchema] of Object.entries(schema.fields)) {
-      if (!(field in defaults)) {
-        defaults[field] = defaultForField(fieldSchema);
-      }
+      if (field in defaults) continue; // first tag that declares a REAL default wins
+      const value = defaultForField(fieldSchema);
+      if (value === undefined) continue; // no `default` declared — leave the slot open for a later tag
+      defaults[field] = value;
     }
   }
   if (Object.keys(defaults).length === 0) return [];
@@ -2001,13 +2041,13 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
   return mutated;
 }
 
-function defaultForField(field: { type: string; enum?: string[] }): unknown {
-  if (field.enum && field.enum.length > 0) return field.enum[0];
-  switch (field.type) {
-    case "boolean": return false;
-    case "integer": return 0;
-    default: return "";
-  }
+/**
+ * Resolve a field's backfill value — its declared `default` (vault#553
+ * Decision B), or `undefined` when none was declared (the field stays
+ * absent). Exported alongside `applySchemaDefaults` for `src/routes.ts`.
+ */
+export function defaultForField(field: { default?: unknown }): unknown {
+  return field.default;
 }
 
 // ---------------------------------------------------------------------------