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

package/src/contract-search.test.ts

@@ -316,6 +316,111 @@ describe("contract: search — escaping edge cases, tag-scope, warnings (#551)",
   });
 });
 
+describe("contract: search — recall + ranking legibility (WS2B/C, #551, schema v25)", () => {
+  it("a note's TITLE (path) is now searchable — a term appearing ONLY in path, not content", async () => {
+    await store.createNote("nothing in this body matches the query term", {
+      path: "quarterly-budget-review",
+    });
+    const res = await search("search=budget&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.some((n: any) => n.path === "quarterly-budget-review")).toBe(true);
+  });
+
+  it("a title match outranks a passing body-only mention — legible via the score field", async () => {
+    await store.createNote("only a passing mention of espresso here, nothing more", {
+      path: "coffee-notes",
+    });
+    await store.createNote("everything about espresso — brewing, grinding, tasting", {
+      path: "espresso",
+    });
+    const res = await search("search=espresso&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    const titleMatchIdx = body.findIndex((n: any) => n.path === "espresso");
+    const bodyMatchIdx = body.findIndex((n: any) => n.path === "coffee-notes");
+    expect(titleMatchIdx).toBeGreaterThanOrEqual(0);
+    expect(bodyMatchIdx).toBeGreaterThanOrEqual(0);
+    expect(titleMatchIdx).toBeLessThan(bodyMatchIdx);
+    for (const n of body) expect(typeof n.score).toBe("number");
+    const scoreOf = (path: string) => body.find((n: any) => n.path === path).score;
+    expect(scoreOf("espresso")).toBeGreaterThan(scoreOf("coffee-notes"));
+  });
+
+  it("score is present on the LEAN (default, no include_content) shape too", async () => {
+    await store.createNote(NOTES.bothWords);
+    const res = await search("search=widgets");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.length).toBeGreaterThan(0);
+    for (const n of body) expect(typeof n.score).toBe("number");
+  });
+
+  it("porter stemming: singular query matches a plural-only body word", async () => {
+    await store.createNote("the firefighters responded quickly to the call");
+    const res = await search("search=firefighter&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.some((n: any) => n.content.includes("firefighters"))).toBe(true);
+  });
+
+  it("a zero-result search with a nearby indexed term surfaces a search_did_you_mean warning", async () => {
+    await store.createNote("a note that discusses Vasquez and the incident report");
+    const res = await search("search=Vasqez");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    const w = warnings!.find((x: any) => x.code === "search_did_you_mean");
+    expect(w).toBeDefined();
+    expect(w.did_you_mean).toBe("vasquez");
+  });
+
+  it("a genuinely zero-result search with NO close vocabulary match carries no did_you_mean warning", async () => {
+    await store.createNote(NOTES.bothWords);
+    const res = await search("search=zzzznonexistentword");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    if (warnings) {
+      expect(warnings.some((w: any) => w.code === "search_did_you_mean")).toBe(false);
+    }
+  });
+
+  it("did_you_mean is suppressed for a tag-scoped session (no leak of vault-wide vocabulary)", async () => {
+    // Out-of-scope note carries the near-match term; the scoped token's
+    // own allowlist ("health") sees nothing else. The did_you_mean
+    // suggestion is computed against the WHOLE vault's FTS5 vocabulary
+    // regardless of scope, so a scoped caller must never see it — same
+    // "no leak" stance as `unknown_tag`'s did_you_mean.
+    await store.createNote("a note that discusses Vasquez and the incident report", { tags: ["work"] });
+    const scopedReq = new Request(`${BASE}/notes?search=Vasqez`, { method: "GET" });
+    const res = await handleNotes(scopedReq, store, "", undefined, {
+      allowed: new Set(["health"]),
+      raw: ["health"],
+    });
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings?.some((w: any) => w.code === "search_did_you_mean")).toBeFalsy();
+  });
+
+  it('search_mode:"advanced" — a lone leading hyphen gets a caller-actionable hint, not raw "no such column" text', async () => {
+    await store.createNote("espresso and coffee content");
+    const res = await search(`search=${encodeURIComponent("-espresso")}&search_mode=advanced`);
+    expect(res.status).toBe(400);
+    const body = await bodyOf(res);
+    expect(body.code).toBe("INVALID_QUERY");
+    expect(body.error_type).toBe("invalid_search_syntax");
+    expect(typeof body.hint).toBe("string");
+    expect(body.hint).toMatch(/BINARY operator/i);
+    expect(body.hint).not.toMatch(/^no such column/i);
+  });
+});
+
 describe("contract: search — MCP parity (#551)", () => {
   it("query-notes: literal-by-default finds punctuation content the same as REST", async () => {
     const tools = generateMcpTools(store);
@@ -356,4 +461,67 @@ describe("contract: search — MCP parity (#551)", () => {
     const desc = (await query.execute({ search: "mcpsortprobe", sort: "desc", include_content: true })) as any[];
     expect(desc.map((n: any) => n.content)).toEqual(["mcpsortprobe beta", "mcpsortprobe alpha"]);
   });
+
+  it("query-notes: title match outranks a body-only mention, and results carry a score (parity with REST)", async () => {
+    await store.createNote("only a passing mention of espresso here, nothing more", { path: "coffee-notes" });
+    await store.createNote("everything about espresso — brewing, grinding, tasting", { path: "espresso" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "espresso" })) as any[];
+    const titleIdx = result.findIndex((n: any) => n.path === "espresso");
+    const bodyIdx = result.findIndex((n: any) => n.path === "coffee-notes");
+    expect(titleIdx).toBeGreaterThanOrEqual(0);
+    expect(bodyIdx).toBeGreaterThanOrEqual(0);
+    expect(titleIdx).toBeLessThan(bodyIdx);
+    for (const n of result) expect(typeof n.score).toBe("number");
+  });
+
+  it("query-notes: a note's title (path) is searchable (parity with REST)", async () => {
+    await store.createNote("nothing in this body matches the query term", { path: "quarterly-budget-review" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "budget" })) as any[];
+    expect(result.some((n: any) => n.path === "quarterly-budget-review")).toBe(true);
+  });
+
+  it("query-notes: porter stemming matches a plural-only body word (parity with REST)", async () => {
+    await store.createNote("the firefighters responded quickly to the call");
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "firefighter", include_content: true })) as any[];
+    expect(result.some((n: any) => n.content.includes("firefighters"))).toBe(true);
+  });
+
+  it("query-notes: zero-result search with a nearby indexed term surfaces search_did_you_mean", async () => {
+    await store.createNote("a note that discusses Vasquez and the incident report");
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "Vasqez" })) as any;
+    // Zero notes + a non-empty warnings array — per the response-shape
+    // contract (vault#550) that's the `{notes, warnings}` envelope, not a
+    // bare array (a bare array can't carry `warnings` at all).
+    expect(Array.isArray(result)).toBe(false);
+    expect(result.notes).toEqual([]);
+    expect(result.warnings).toBeDefined();
+    const w = result.warnings.find((x: any) => x.code === "search_did_you_mean");
+    expect(w).toBeDefined();
+    expect(w.did_you_mean).toBe("vasquez");
+  });
+
+  it('query-notes: search_mode:"advanced" — a lone leading hyphen gets a caller-actionable hint, not raw "no such column" text', async () => {
+    await store.createNote("espresso and coffee content");
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    let err: any;
+    try {
+      await query.execute({ search: "-espresso", search_mode: "advanced" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeDefined();
+    expect(err.error_type).toBe("invalid_search_syntax");
+    expect(typeof err.hint).toBe("string");
+    expect(err.hint).toMatch(/BINARY operator/i);
+    expect(err.hint).not.toMatch(/^no such column/i);
+  });
 });

package/src/mcp-query-notes-search-scope.test.ts

@@ -134,3 +134,56 @@ describe("MCP query-notes search × tag-scope — combined enforcement (vault#55
     }
   });
 });
+
+/**
+ * NIT 1 (auth-561 review, #565): did_you_mean on a zero-result search is
+ * computed against the WHOLE vault's FTS5 vocabulary regardless of scope
+ * (`computeSearchDidYouMean` is scope-unaware by architecture, like every
+ * warning core produces). The MCP query-notes wrapper
+ * (`applyTagScopeWrappers`, src/mcp-tools.ts) strips the ENTIRE `warnings`
+ * array for a tag-scoped session, which covers `search_did_you_mean`
+ * generically — but the security property (a scoped token must not learn an
+ * out-of-scope note's vocabulary via a spelling suggestion) deserves a
+ * direct test, mirroring the REST test in src/contract-search.test.ts.
+ */
+function warningsOf(result: unknown): any[] {
+  if (result && typeof result === "object" && "warnings" in result && Array.isArray((result as any).warnings)) {
+    return (result as any).warnings;
+  }
+  return [];
+}
+
+describe("MCP query-notes did_you_mean × tag-scope suppression (#565 NIT 1)", () => {
+  test("a scoped session's zero-result search does NOT surface an out-of-scope term via search_did_you_mean", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    // The near-match term "Vasquez" lives ONLY in an out-of-scope note.
+    await store.createNote("a note that discusses Vasquez and the incident report", { tags: ["work"] });
+
+    const scopedTool = await queryNotesTool("journal", ["health"]);
+    const scopedResult = await scopedTool.execute({ search: "Vasqez" }); // typo → zero results
+    expect(idsOf(scopedResult)).toEqual([]);
+    // The wrapper strips warnings wholesale for a scoped session — no
+    // search_did_you_mean leaking the out-of-scope "vasquez".
+    expect(warningsOf(scopedResult).some((w: any) => w.code === "search_did_you_mean")).toBe(false);
+    // Belt-and-suspenders: the out-of-scope term must not appear ANYWHERE in
+    // the serialized response (no did_you_mean field slipping through under a
+    // different shape).
+    expect(JSON.stringify(scopedResult).toLowerCase()).not.toContain("vasquez");
+  });
+
+  test("control: an UNSCOPED session's zero-result search DOES surface the suggestion (proves it's suppressed by scope, not simply absent)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    await store.createNote("a note that discusses Vasquez and the incident report", { tags: ["work"] });
+
+    const unscopedTool = await queryNotesTool("journal", null);
+    const result = await unscopedTool.execute({ search: "Vasqez" });
+    expect(idsOf(result)).toEqual([]);
+    const w = warningsOf(result).find((x: any) => x.code === "search_did_you_mean");
+    expect(w).toBeDefined();
+    expect(w.did_you_mean).toBe("vasquez");
+  });
+});

package/src/onboarding-seed.test.ts

@@ -166,8 +166,11 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     expect(gs!.content).toContain("## Write gotchas");
     expect(gs!.content).toContain("if_updated_at"); // optimistic concurrency
     expect(gs!.content).toContain("force: true");
-    // schema-default back-fill: enum→first value, integer→0.
-    expect(gs!.content).toContain("first listed value");
+    // schema-default back-fill is explicit-`default`-only (vault#553 Decision B).
+    expect(gs!.content).toContain("explicit `default`");
+    expect(gs!.content).toContain("exists: false");
+    // indexed⇒strict type enforcement (vault#553 Decision A).
+    expect(gs!.content).toContain("field's TYPE is always enforced");
   });
 
   test("A3 (reshaped): the welcome ring resolves to real link edges; Getting Started has no dangling Surface Starter link", async () => {

package/src/routes.ts

@@ -13,7 +13,14 @@
 
 import type { Store, Note, QueryOpts } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
-import { collectUnknownTagWarnings, emptySearchWarning, ignoredParamWarning, type QueryWarning } from "../core/src/query-warnings.ts";
+import {
+  collectUnknownTagWarnings,
+  emptySearchWarning,
+  ignoredParamWarning,
+  computeSearchDidYouMean,
+  searchDidYouMeanWarning,
+  type QueryWarning,
+} from "../core/src/query-warnings.ts";
 import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "../core/src/search-query.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
 import { transactionAsync } from "../core/src/txn.ts";
@@ -24,7 +31,7 @@ import {
   contentRangeRequiresContent,
   type ContentRange,
 } from "../core/src/content-range.ts";
-import { attachValidationStatus, enforceStrictWrite } from "../core/src/mcp.ts";
+import { attachValidationStatus, enforceStrictWrite, applySchemaDefaults } from "../core/src/mcp.ts";
 import type { ValidationWarning } from "../core/src/schema-defaults.ts";
 import { logStrictBypass } from "./scopes.ts";
 import * as linkOps from "../core/src/links.ts";
@@ -48,7 +55,7 @@ import {
   tagScopeForbidden,
   tagsWithinScope,
 } from "./tag-scope.ts";
-import { ParentCycleError } from "../core/src/tag-schemas.ts";
+import { ParentCycleError, InvalidFieldDefaultError } from "../core/src/tag-schemas.ts";
 import { findTokensReferencingTag } from "./token-store.ts";
 
 /**
@@ -1103,6 +1110,22 @@ async function handleNotesInner(
             }
             throw e;
           }
+          // 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.
+          // Gated on `tagScope.allowed === null` (unscoped) — same stance
+          // as `collectUnknownTagWarnings` below: the FTS5 vocabulary spans
+          // the whole vault regardless of scope, so surfacing a suggestion
+          // to a scoped token would leak out-of-scope content's existence
+          // across the scope boundary. Unlike the MCP path, REST enforces
+          // tag-scope inline (no post-hoc wrapper to strip it for us), so
+          // the gate has to live here explicitly.
+          if (rawResults.length === 0 && tagScope.allowed === null) {
+            const suggestion = computeSearchDidYouMean(db, search);
+            if (suggestion) {
+              searchWarnings.push(searchDidYouMeanWarning(search, suggestion));
+            }
+          }
         }
         // Tag-scope: drop any result the token isn't permitted to see. Filter
         // happens after the store query so an empty post-filter list still
@@ -2668,6 +2691,18 @@ export async function handleTags(
           400,
         );
       }
+      if (err instanceof InvalidFieldDefaultError) {
+        // vault#553 Decision B — a declared `default` doesn't conform to its
+        // own field's type/enum. Own-field error (no cross-tag data), so no
+        // scrub needed. Mirrors IndexedFieldError's 400 shape/posture — see
+        // store.upsertTagRecord's pre-validate comment for why REST hits
+        // this (fail-fast, single violation) while MCP's update-tag usually
+        // reports it bundled via `TagFieldConflictError` instead.
+        return json(
+          { error: err.message, error_type: "invalid_field_default", field: err.field },
+          400,
+        );
+      }
       if (err instanceof ParentCycleError) {
         // vault#552: parent_names would close a cycle. Nothing was
         // persisted. Scope-scrub the cycle path for a tag-scoped caller —
@@ -3735,56 +3770,10 @@ export async function handleStorage(
   return json({ error: "Not found", error_type: "not_found" }, 404);
 }
 
-// ---------------------------------------------------------------------------
-// Tag schema defaults — same logic as core/src/mcp.ts applySchemaDefaults
-// ---------------------------------------------------------------------------
-
-// Returns the IDs of notes whose metadata was actually default-filled, so
-// the caller can re-read ONLY the mutated notes (and skip the re-read when
-// nothing changed). Mirrors the core/src/mcp.ts contract.
-async function applySchemaDefaults(store: Store, db: any, noteIds: string[], tags: string[]): Promise<string[]> {
-  const schemas = tagSchemaOps.getTagSchemaMap(db);
-  if (Object.keys(schemas).length === 0) return [];
-
-  const defaults: Record<string, unknown> = {};
-  for (const tag of tags) {
-    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 (Object.keys(defaults).length === 0) return [];
-
-  const mutated: string[] = [];
-  for (const noteId of noteIds) {
-    const note = await store.getNote(noteId);
-    if (!note) continue;
-    const existing = (note.metadata as Record<string, unknown>) ?? {};
-    const missing: Record<string, unknown> = {};
-    for (const [field, value] of Object.entries(defaults)) {
-      if (!(field in existing)) missing[field] = value;
-    }
-    if (Object.keys(missing).length === 0) continue;
-    await store.updateNote(noteId, {
-      metadata: { ...existing, ...missing },
-      skipUpdatedAt: true,
-    });
-    mutated.push(noteId);
-  }
-  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 "";
-  }
-}
+// applySchemaDefaults lives in core/src/mcp.ts (vault#553) — REST used to
+// carry a byte-identical duplicate; importing it means REST and MCP can
+// never drift on this behavior again, and the cloud runtime (which imports
+// core directly) inherits it without any handler-side code.
 
 function removeWikilinkBrackets(content: string, targetPath: string): string {
   const escaped = targetPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

package/src/vault.test.ts

@@ -979,7 +979,7 @@ describe("scoped MCP wrapper", async () => {
     closeAllStores();
   });
 
-  test("create-note with schema tag auto-populates defaults", async () => {
+  test("create-note with schema tag applies explicit defaults; undeclared fields stay absent (vault#553 Decision B)", async () => {
     const { generateScopedMcpTools } = await import("./mcp-tools.ts");
     const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
@@ -995,8 +995,8 @@ describe("scoped MCP wrapper", async () => {
     await vaultStore.upsertTagSchema("person", {
       description: "A person",
       fields: {
-        first_appeared: { type: "string", description: "When" },
-        relationship: { type: "string", description: "How" },
+        first_appeared: { type: "string", description: "When", default: "unknown" },
+        relationship: { type: "string", description: "How" }, // no default — stays absent
       },
     });
 
@@ -1004,19 +1004,19 @@ describe("scoped MCP wrapper", async () => {
     const createNote = tools.find((t) => t.name === "create-note")!;
     const queryNotes = tools.find((t) => t.name === "query-notes")!;
 
-    // Create a note tagged person with no metadata — defaults auto-populated
+    // Create a note tagged person with no metadata — the EXPLICIT default
+    // auto-populates; the field with no `default` stays absent.
     const result = await createNote.execute({
       content: "Alice",
       tags: ["person"],
     }) as any;
     expect(result.content).toBe("Alice");
 
-    // Verify defaults were written
     const fresh = await queryNotes.execute({ id: result.id }) as any;
-    expect(fresh.metadata.first_appeared).toBe("");
-    expect(fresh.metadata.relationship).toBe("");
+    expect(fresh.metadata.first_appeared).toBe("unknown");
+    expect(fresh.metadata.relationship).toBeUndefined();
 
-    // Create with explicit metadata — preserved
+    // Create with explicit metadata — preserved (overrides the default).
     const result2 = await createNote.execute({
       content: "Bob",
       tags: ["person"],
@@ -1029,7 +1029,7 @@ describe("scoped MCP wrapper", async () => {
     closeAllStores();
   });
 
-  test("update-note tags.add with schema auto-populates defaults", async () => {
+  test("update-note tags.add with schema applies explicit defaults; undeclared fields stay absent (vault#553 Decision B)", async () => {
     const { generateScopedMcpTools } = await import("./mcp-tools.ts");
     const { writeVaultConfig } = await import("./config.ts");
     const { getVaultStore, closeAllStores: close } = await import("./vault-store.ts");
@@ -1045,16 +1045,16 @@ describe("scoped MCP wrapper", async () => {
     await vaultStore.upsertTagSchema("person", {
       description: "A person",
       fields: {
-        first_appeared: { type: "string", description: "When" },
-        relationship: { type: "string", description: "How" },
+        first_appeared: { type: "string", description: "When", default: "unknown" },
+        relationship: { type: "string", description: "How" }, // no default — stays absent
       },
     });
     await vaultStore.upsertTagSchema("project", {
       description: "A project",
       fields: {
-        status: { type: "string", enum: ["active", "completed", "abandoned"], description: "Status" },
-        active: { type: "boolean", description: "Is active" },
-        priority: { type: "integer", description: "Priority level" },
+        status: { type: "string", enum: ["active", "completed", "abandoned"], description: "Status", default: "active" },
+        active: { type: "boolean", description: "Is active", default: false },
+        priority: { type: "integer", description: "Priority level" }, // no default — stays absent
       },
     });
     const tools = generateScopedMcpTools(vaultName);
@@ -1066,10 +1066,11 @@ describe("scoped MCP wrapper", async () => {
     const note = await createNote.execute({ content: "Alice" }) as any;
     await updateNote.execute({ id: note.id, tags: { add: ["person"] }, force: true });
     const after = await queryNotes.execute({ id: note.id }) as any;
-    expect(after.metadata.first_appeared).toBe("");
-    expect(after.metadata.relationship).toBe("");
+    expect(after.metadata.first_appeared).toBe("unknown");
+    expect(after.metadata.relationship).toBeUndefined();
 
-    // Tag note that already has partial metadata — only missing fields populated
+    // Tag note that already has partial metadata — only missing fields WITH a
+    // declared default get populated; the field with no default stays absent.
     const note2 = await createNote.execute({
       content: "Bob",
       metadata: { first_appeared: "2023-11" },
@@ -1077,22 +1078,22 @@ describe("scoped MCP wrapper", async () => {
     await updateNote.execute({ id: note2.id, tags: { add: ["person"] }, force: true });
     const after2 = await queryNotes.execute({ id: note2.id }) as any;
     expect(after2.metadata.first_appeared).toBe("2023-11"); // preserved
-    expect(after2.metadata.relationship).toBe(""); // added
+    expect(after2.metadata.relationship).toBeUndefined(); // no default — stays absent
 
-    // Tag with #project — enum defaults to first value, boolean to false, integer to 0
+    // Tag with #project — declared defaults land; `priority` (no default) stays absent.
     const note4 = await createNote.execute({ content: "My Project" }) as any;
     await updateNote.execute({ id: note4.id, tags: { add: ["project"] }, force: true });
     const after4 = await queryNotes.execute({ id: note4.id }) as any;
     expect(after4.metadata.status).toBe("active");
     expect(after4.metadata.active).toBe(false);
-    expect(after4.metadata.priority).toBe(0);
+    expect(after4.metadata.priority).toBeUndefined();
 
-    // Multiple schema tags at once — all defaults merged
+    // Multiple schema tags at once — all EXPLICIT defaults merged.
     const note5 = await createNote.execute({ content: "Multi" }) as any;
     await updateNote.execute({ id: note5.id, tags: { add: ["person", "project"] }, force: true });
     const after5 = await queryNotes.execute({ id: note5.id }) as any;
-    expect(after5.metadata.first_appeared).toBe("");
-    expect(after5.metadata.relationship).toBe("");
+    expect(after5.metadata.first_appeared).toBe("unknown");
+    expect(after5.metadata.relationship).toBeUndefined();
     expect(after5.metadata.status).toBe("active");
     expect(after5.metadata.active).toBe(false);
 
@@ -1566,9 +1567,12 @@ describe("scoped MCP wrapper", async () => {
     });
 
     const vaultStore = getVaultStore(vaultName);
+    // vault#553 Decision B: backfill is explicit-`default`-only — declare
+    // one so this test still exercises an actual defaults-write (and can
+    // assert it lands without bumping updatedAt).
     await vaultStore.upsertTagSchema("person", {
       description: "A person",
-      fields: { name: { type: "string" } },
+      fields: { name: { type: "string", default: "unknown" } },
     });
 
     const tools = generateScopedMcpTools(vaultName);
@@ -1581,7 +1585,7 @@ describe("scoped MCP wrapper", async () => {
     await updateNote.execute({ id: note.id, tags: { add: ["person"] }, force: true });
     const after = await queryNotes.execute({ id: note.id }) as any;
     expect(after.updatedAt).toBe(originalUpdatedAt);
-    expect(after.metadata.name).toBe("");
+    expect(after.metadata.name).toBe("unknown");
 
     close();
   });
@@ -2199,8 +2203,10 @@ describe("HTTP /notes", async () => {
   // mapped over the pre-defaults in-memory objects, so default-filled
   // metadata was missing from `POST /api/notes` responses.
   test("POST /notes response reflects post-applySchemaDefaults state (vault#316)", async () => {
+    // vault#553 Decision B: backfill is explicit-`default`-only — declare one
+    // so this test still exercises the post-defaults re-read mechanism.
     await store.upsertTagSchema("task", {
-      fields: { priority: { type: "string", enum: ["high", "low"] } },
+      fields: { priority: { type: "string", enum: ["high", "low"], default: "high" } },
     });
 
     // Single: default lands in the returned metadata and agrees with disk.
@@ -2211,7 +2217,7 @@ describe("HTTP /notes", async () => {
     );
     expect(single.status).toBe(201);
     const singleBody = await single.json() as any;
-    expect(singleBody.metadata?.priority).toBe("high"); // first enum value
+    expect(singleBody.metadata?.priority).toBe("high"); // explicit schema default
     const onDisk = await store.getNoteByPath("Inbox/task-1");
     expect((onDisk!.metadata as any)?.priority).toBe("high");