@openparachute/vault 0.7.0-rc.9 → 0.7.2-rc.3

package/core/src/paths.ts

@@ -19,6 +19,10 @@ export function normalizePath(path: string | null | undefined): string | null {
   if (path === null || path === undefined) return null;
 
   let p = path
+    .replace(/\0/g, "")           // strip NUL bytes — never valid in a path;
+                                   // belt for legacy/imported rows so a stored
+                                   // NUL can't reach the filesystem (writes
+                                   // reject NUL up front via validatePath)
     .trim()
     .replace(/\\/g, "/")          // backslash → forward slash
     .replace(/\.md$/i, "")         // strip .md extension

package/core/src/portable-md.test.ts

@@ -29,6 +29,7 @@ import { buildVaultProjection } from "./vault-projection.js";
 import {
   CaseCollisionError,
   emitYamlDoc,
+  exportVault,
   exportVaultToDir,
   importPortableVault,
   noteToPortable,
@@ -41,7 +42,9 @@ import {
   supportsInlineFrontmatter,
   toPortableMarkdown,
   toSidecarYaml,
+  type ExportSink,
   type PortableNote,
+  type SinkWriteResult,
 } from "./portable-md.js";
 
 // ---------------------------------------------------------------------------
@@ -416,6 +419,86 @@ describe("exportVaultToDir", async () => {
     expect(vault).toContain("name: test");
   });
 
+  // FIX 2(b) (vault#589) — a NUL-in-path note (a pre-fix poisoned row a
+  // write-capable token could have planted) must be SKIPPED with a warning +
+  // stat, never abort the whole export. Before the sink hardening the
+  // uncaught `writeFileSync` throw aborted the entire vault export, so one bad
+  // note broke backup/export for everyone.
+  //
+  // RED-without-fix: drop the try/catch from `FsExportSink.writeText` and this
+  // test's `exportVaultToDir` call throws (whole export aborts) instead of
+  // returning a partial-with-skip result. Verified manually during development.
+  it("hardened export sink: a NUL-in-path note is skipped, not fatal (vault#589)", async () => {
+    await store.createNote("clean one", { id: "c1", path: "clean/one" });
+    await store.createNote("clean two", { id: "c2", path: "clean/two" });
+    await store.createNote("poison", { id: "p1", path: "temp" });
+    // Simulate a pre-fix vault: inject a real NUL directly into the stored
+    // path, bypassing normalizePath (which now strips NUL). `char(0)` yields a
+    // NUL byte in the TEXT column that survives read-back into note.path.
+    store.db.prepare("UPDATE notes SET path = 'bad' || char(0) || 'path' WHERE id = ?").run("p1");
+
+    const outDir = join(tmpBase, "poisoned-out");
+    const stats = await exportVaultToDir(store, { outDir, exportedAt: "2026-05-13T00:00:00.000Z" });
+
+    // The export completes and every OTHER note is written ...
+    expect(existsSync(join(outDir, "clean/one.md"))).toBe(true);
+    expect(existsSync(join(outDir, "clean/two.md"))).toBe(true);
+    expect(stats.notes).toBe(2); // only the two clean notes counted as written
+
+    // ... while the poisoned note is skipped-with-reason (fs write failure),
+    // surfaced as a stat rather than a thrown, aborted export.
+    expect(stats.skipped_traversal).toBeGreaterThanOrEqual(1);
+    const poisonSkip = stats.skipped_notes.find((s) => s.reason.includes("fs write failed"));
+    expect(poisonSkip).toBeTruthy();
+  });
+
+  // BLOCKER (vault#589 review) — the skip-with-warn export belt (FIX 2b) is
+  // correct ONLY for per-NOTE writes. The STRUCTURAL writes (the vault.yaml
+  // manifest + per-tag schema sidecars) are global: a dir missing
+  // `.parachute/vault.yaml` is hard-rejected at restore/import, so a discarded
+  // `{ok:false}` there would produce a manifest-less "success" — a silently
+  // broken backup. Those must FAIL LOUDLY.
+  //
+  // RED-without-fix: with the structural writes discarding the sink result,
+  // both `exportVault` calls RESOLVE (no throw) and the manifest/schema is
+  // silently absent. Verified manually during development.
+  it("aborts loudly when the manifest write fails (structural, not skip-with-warn)", async () => {
+    await store.createNote("n", { id: "n1", path: "p" });
+    // Stub sink that fails ONLY the manifest write; everything else succeeds.
+    const sink: ExportSink = {
+      caseSensitive: true,
+      attachmentsEnabled: false,
+      writeText(relPath: string): SinkWriteResult {
+        if (relPath === join(SIDECAR_DIR, "vault.yaml")) {
+          return { ok: false, reason: "simulated EACCES on .parachute/" };
+        }
+        return { ok: true };
+      },
+      copyAttachment(): SinkWriteResult { return { ok: true }; },
+    };
+    await expect(exportVault(store, sink, { exportedAt: "2026-05-13T00:00:00.000Z" }))
+      .rejects.toThrow(/manifest/i);
+  });
+
+  it("aborts loudly when a schema sidecar write fails (structural, not skip-with-warn)", async () => {
+    await store.upsertTagSchema("task", { description: "A unit of work" });
+    await store.createNote("x", { id: "x1", tags: ["task"] });
+    // Fail ONLY the schema write; the manifest (and everything else) succeeds.
+    const sink: ExportSink = {
+      caseSensitive: true,
+      attachmentsEnabled: false,
+      writeText(relPath: string): SinkWriteResult {
+        if (relPath.startsWith(join(SIDECAR_DIR, "schemas"))) {
+          return { ok: false, reason: "simulated disk full" };
+        }
+        return { ok: true };
+      },
+      copyAttachment(): SinkWriteResult { return { ok: true }; },
+    };
+    await expect(exportVault(store, sink, { exportedAt: "2026-05-13T00:00:00.000Z" }))
+      .rejects.toThrow(/schema sidecar/i);
+  });
+
   it("writes per-tag schemas to .parachute/schemas/", async () => {
     await store.upsertTagSchema("task", {
       description: "A unit of work",
@@ -710,6 +793,84 @@ describe("importPortableVault", async () => {
     expect(await targetStore.getNote("k1")).toBeTruthy();
   });
 
+  // FIX 1 (vault#589) — blow-away must be all-or-nothing. Before the fix, the
+  // wipe + replay ran with NO enclosing transaction: a mid-replay throw (here a
+  // PathConflictError from two source files declaring the same `path`) left the
+  // vault WIPED + partially replayed, originals gone for good. The wrap rolls
+  // the whole thing back to the exact pre-import vault.
+  //
+  // RED-without-fix: temporarily change `importVault` to always call
+  // `importVaultReplay` unwrapped (drop the `transactionAsync`) and this test
+  // ends with 1 note (`n-first`), all three originals gone — the assertions
+  // below fail. Verified manually during development.
+  it("--blow-away is atomic — a mid-replay throw rolls back to the original vault (vault#589)", async () => {
+    // Target vault holds originals that MUST survive a failed restore.
+    const target = new SqliteStore(new Database(":memory:"));
+    await target.createNote("original one", { id: "orig1", path: "keep/one" });
+    await target.createNote("original two", { id: "orig2", path: "keep/two" });
+    await target.createNote("original three", { id: "orig3", path: "keep/three" });
+
+    // Hand-build a poisoned export: two notes declaring the SAME frontmatter
+    // `path` → the 2nd createNote throws PathConflictError mid-replay. Files
+    // walk in sorted order (first.md before second.md), so first.md lands, then
+    // second.md collides.
+    const inDir = join(tmpBase, "poison-collide");
+    mkdirSync(join(inDir, ".parachute"), { recursive: true });
+    writeFileSync(join(inDir, ".parachute", "vault.yaml"), "name: poison\nexport_format_version: 1\n");
+    writeFileSync(join(inDir, "first.md"), "---\nid: nfirst\npath: collide\n---\nfirst body\n");
+    writeFileSync(join(inDir, "second.md"), "---\nid: nsecond\npath: collide\n---\nsecond body\n");
+
+    // The blow-away import propagates the collision (rejects) ...
+    await expect(importPortableVault(target, { inDir, blowAway: true })).rejects.toThrow();
+
+    // ... and rolls back: all three ORIGINALS survive, and NONE of the
+    // poisoned import's notes landed. The vault is exactly as it was.
+    expect(await target.getNote("orig1")).toBeTruthy();
+    expect(await target.getNote("orig2")).toBeTruthy();
+    expect(await target.getNote("orig3")).toBeTruthy();
+    expect(await target.getNote("nfirst")).toBeNull();
+    expect(await target.getNote("nsecond")).toBeNull();
+    const all = await target.queryNotes({ limit: 100 });
+    expect(all.length).toBe(3);
+  });
+
+  // FIX 3 (vault#589) — duplicate-id and blank-id content files must be
+  // reported + skipped, not silently clobber (last-wins) or seed a bogus key.
+  it("reports duplicate + blank note ids instead of silently clobbering (vault#589)", async () => {
+    // Hand-build a tree: two files share id "dup" (distinct content); a third
+    // carries a whitespace-only id. Files walk sorted: aaa < bbb < ccc.
+    const inDir = join(tmpBase, "dup-ids");
+    mkdirSync(join(inDir, ".parachute"), { recursive: true });
+    writeFileSync(join(inDir, ".parachute", "vault.yaml"), "name: dup\nexport_format_version: 1\n");
+    writeFileSync(join(inDir, "aaa.md"), "---\nid: dup\npath: pa\n---\nfrom aaa\n");
+    writeFileSync(join(inDir, "bbb.md"), "---\nid: dup\npath: pb\n---\nfrom bbb\n");
+    writeFileSync(join(inDir, "ccc.md"), "---\nid: '   '\npath: pc\n---\nfrom ccc\n");
+
+    const target = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(target, { inDir });
+
+    // Exactly ONE note created — the FIRST of the id collision (aaa) — and the
+    // collision is NOT folded into "updated".
+    expect(stats.notes_created).toBe(1);
+    expect(stats.notes_updated).toBe(0);
+    const kept = await target.getNote("dup");
+    expect(kept).toBeTruthy();
+    expect(kept!.content.trimEnd()).toBe("from aaa"); // first-wins, deterministic
+
+    // Both the duplicate (bbb) and the blank-id (ccc) file are reported as
+    // skipped — surfaced in stats, not absorbed into the created/updated count.
+    expect(stats.skipped_duplicate_ids.length).toBe(2);
+    const dupEntry = stats.skipped_duplicate_ids.find((s) => s.reason.includes("duplicate id"));
+    expect(dupEntry).toBeTruthy();
+    expect(dupEntry!.path).toBe("pb");
+    const blankEntry = stats.skipped_duplicate_ids.find((s) => s.reason.includes("blank"));
+    expect(blankEntry).toBeTruthy();
+
+    // The whitespace-id file clobbered nothing — no bogus key, only "dup" exists.
+    const allNotes = await target.queryNotes({ limit: 100 });
+    expect(allNotes.length).toBe(1);
+  });
+
   it("restores tag schemas (description + fields)", async () => {
     await store.upsertTagSchema("task", {
       description: "A unit of work",

package/core/src/portable-md.ts

@@ -77,6 +77,7 @@ import { basename, join, relative, extname, dirname, resolve as resolvePath, sep
 import type { Store, Note, Link, Attachment } from "./types.js";
 import type { TagRecord } from "./tag-schemas.js";
 import { ParentCycleError } from "./tag-schemas.js";
+import { transactionAsync } from "./txn.js";
 
 // ---------------------------------------------------------------------------
 // Format constants
@@ -786,8 +787,23 @@ export class FsExportSink implements ExportSink {
         reason: `path-traversal: resolved write target "${fullResolved}" escapes export root "${this.rootResolved}"`,
       };
     }
-    mkdirSync(dirname(full), { recursive: true });
-    writeFileSync(full, content);
+    // Belt for already-poisoned vaults (vault#589 / FIX 2). A NUL-in-path note
+    // resolves WITHIN the export root (passing the traversal guard above) but
+    // then makes `writeFileSync` throw ("path contains null byte") — an
+    // uncaught throw here would abort the ENTIRE export, so one bad note breaks
+    // backup for every note. Any fs failure (NUL, EACCES, ENAMETOOLONG, …)
+    // becomes a skip-with-reason the caller records as a `skipped_notes` stat +
+    // a warning, exactly like the traversal skip, so the rest of the vault
+    // still exports.
+    try {
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, content);
+    } catch (err) {
+      return {
+        ok: false,
+        reason: `fs write failed for "${relPath}": ${(err as Error)?.message ?? String(err)}`,
+      };
+    }
     return { ok: true };
   }
 
@@ -812,8 +828,17 @@ export class FsExportSink implements ExportSink {
         reason: `path-traversal: dest "${destResolved}" escapes export root "${this.rootResolved}"`,
       };
     }
-    mkdirSync(dirname(destFull), { recursive: true });
-    copyFileSync(srcResolved, destResolved);
+    // Same belt as `writeText` (vault#589 / FIX 2): a NUL/otherwise-unwritable
+    // attachment dest must skip-with-reason, not abort the whole export.
+    try {
+      mkdirSync(dirname(destFull), { recursive: true });
+      copyFileSync(srcResolved, destResolved);
+    } catch (err) {
+      return {
+        ok: false,
+        reason: `fs copy failed for "${destRelPath}": ${(err as Error)?.message ?? String(err)}`,
+      };
+    }
     return { ok: true };
   }
 }
@@ -878,11 +903,29 @@ export async function exportVault(
     ...(opts.vaultName ? { name: opts.vaultName } : {}),
     ...(opts.vaultDescription ? { description: opts.vaultDescription } : {}),
   };
-  sink.writeText(join(SIDECAR_DIR, "vault.yaml"), emitYamlDoc(vaultMeta as unknown as Record<string, unknown>));
+  // The manifest is STRUCTURAL, not per-note: a portable-md export WITHOUT its
+  // `.parachute/vault.yaml` is unusable — restore (`importPortableVault`), CLI
+  // autodetect, and mirror-import all hard-reject a dir that lacks it. So the
+  // skip-with-warn belt that hardens per-note writes (vault#589 / FIX 2b) is
+  // exactly WRONG here: a discarded `{ok:false}` would produce a manifest-less
+  // "success" — a silently-broken backup. Fail LOUDLY instead. (Per-note
+  // content/attachment writes below stay skip-with-warn — one poisoned note
+  // must not abort the whole export.)
+  const manifestPath = join(SIDECAR_DIR, "vault.yaml");
+  const manifestWrite = sink.writeText(manifestPath, emitYamlDoc(vaultMeta as unknown as Record<string, unknown>));
+  if (!manifestWrite.ok) {
+    throw new Error(
+      `export aborted: failed to write the vault manifest "${manifestPath}": ${manifestWrite.reason}. ` +
+      `A portable-md export without its manifest is unusable (restore/import hard-rejects it), so this fails loudly rather than producing a manifest-less "success".`,
+    );
+  }
 
   // 2. Per-tag schemas. Only tags carrying at least one schema-shaped
   // field (description, fields, relationships, parent_names) get a file;
-  // tags that are just-a-name don't pollute the sidecar.
+  // tags that are just-a-name don't pollute the sidecar. Schemas are
+  // structural too — a dropped schema sidecar silently loses a tag's
+  // definition from the backup — so a write failure here also fails loudly
+  // (and never increments `schemasWritten` on a failed write).
   const tagRecords = await store.listTagRecords();
   let schemasWritten = 0;
   for (const tag of tagRecords) {
@@ -895,7 +938,14 @@ export async function exportVault(
     if (tag.parent_names !== undefined && tag.parent_names.length > 0) {
       doc.parent_names = tag.parent_names;
     }
-    sink.writeText(join(SIDECAR_DIR, "schemas", filename), emitYamlDoc(doc));
+    const schemaPath = join(SIDECAR_DIR, "schemas", filename);
+    const schemaWrite = sink.writeText(schemaPath, emitYamlDoc(doc));
+    if (!schemaWrite.ok) {
+      throw new Error(
+        `export aborted: failed to write schema sidecar "${schemaPath}" for tag "${tag.tag}": ${schemaWrite.reason}. ` +
+        `Tag schemas are structural — a partial export would silently drop a schema definition — so this fails loudly.`,
+      );
+    }
     schemasWritten++;
   }
 
@@ -1643,6 +1693,17 @@ export interface ImportStats {
    * imports — the cycle is warned, not fatal. Empty in the common case.
    */
   skipped_schema_parents: Array<{ tag: string; parent_names: string[]; reason: string }>;
+  /**
+   * Content files skipped because their frontmatter `id` couldn't be used as
+   * a note key (vault#589 / FIX 3): a DUPLICATE id (a later file shares an id
+   * with one already imported — the first wins, deterministically, since
+   * `listContentFiles()` walks in sorted path order) or a BLANK id
+   * (whitespace-only, e.g. `"   "`). Without this the later duplicate silently
+   * clobbered the earlier note (data loss folded into "updated N") and a
+   * blank id seeded a bogus map key. Each entry names the offending id, the
+   * skipped file's path, and why. Empty in the common case.
+   */
+  skipped_duplicate_ids: Array<{ id: string; path: string | undefined; reason: string }>;
   /** Set when the caller passed `blowAway: true`; counts notes removed. */
   notes_wiped: number;
   /**
@@ -1815,10 +1876,49 @@ export async function importVault(
     skipped_attachments: [],
     skipped_sidecars: [],
     skipped_schema_parents: [],
+    skipped_duplicate_ids: [],
     notes_wiped: 0,
     indexes_declared: 0,
   };
 
+  // Blow-away is all-or-nothing (vault#589 / FIX 1). A blow-away import wipes
+  // the vault (step 1) then replays every schema/note/link/attachment. If any
+  // replay step throws mid-flight — a `PathConflictError` from two source
+  // files sharing a path, a malformed record, a crash — an UNWRAPPED run would
+  // leave the vault wiped-and-partial with the originals gone for good. Wrap
+  // the wipe + the whole replay in ONE transaction so a failure rolls back to
+  // the exact pre-import vault. The transaction seam is re-entrant (SAVEPOINTs,
+  // vault#589) so the replay's own transactional writes (`upsertTagRecord`,
+  // `deleteTag` cascade, …) compose inside it rather than hitting SQLite's
+  // "cannot start a transaction within a transaction". Additive (non-blow-away)
+  // and dry-run imports are never destructive, so they replay unwrapped —
+  // exactly as before. Hook dispatch stays best-effort/reconciled: no
+  // registered hook does synchronous destructive work (the mirror arms a
+  // debounce; transcription only fires on attachment `created` and kicks an
+  // idempotent worker), so a rollback can't leave a half-applied side effect
+  // the sweep won't reconcile.
+  if (opts.blowAway && !opts.dryRun) {
+    await transactionAsync(store.db, () => importVaultReplay(store, source, opts, stats));
+  } else {
+    await importVaultReplay(store, source, opts, stats);
+  }
+
+  return stats;
+}
+
+/**
+ * The replay body of {@link importVault} — wipe (blow-away only) then restore
+ * schemas → notes → links → attachments → wikilinks → indexes, mutating the
+ * shared `stats`. Split out so `importVault` can run it either bare or inside a
+ * single `transactionAsync` (the atomic blow-away path); the restoration order
+ * and every skip/warn policy are unchanged from the pre-split code.
+ */
+async function importVaultReplay(
+  store: Store,
+  source: ImportSource,
+  opts: ImportEngineOptions,
+  stats: ImportStats,
+): Promise<void> {
   // 1. Optional wipe. Notes are deleted via the public Store API so hooks
   // fire (callers depend on `attachment.deleted` hooks for assets-dir
   // cleanup; we don't bypass that on blow-away). Deleted in bounded batches
@@ -2049,6 +2149,39 @@ export async function importVault(
       ...(links ? { links: links as PortableLink[] } : {}),
       ...(attachments ? { attachments: attachments as PortableAttachmentRef[] } : {}),
     };
+
+    // FIX 3 (vault#589) — guard the `seenNotes` key before it's set:
+    //   - A whitespace-only id ("   ") slips past the `!id` truthiness guard
+    //     above (non-empty string) but is not a real note key. Skip it rather
+    //     than seeding a bogus map entry / clobbering a real note.
+    //   - A DUPLICATE id means a LATER content file carries an id already
+    //     imported from an earlier file. The old `Map.set` silently
+    //     last-wins-clobbered the first note (data loss, folded into
+    //     "updated N"). Keep the FIRST (deterministic — `listContentFiles()`
+    //     returns sorted paths) and skip the later, recording the collision.
+    // Both cases land in `skipped_duplicate_ids` + a per-file `console.warn`
+    // so the operator sees the collision instead of it vanishing.
+    if (id.trim() === "") {
+      stats.skipped_duplicate_ids.push({
+        id,
+        path: portable.path,
+        reason: "blank (whitespace-only) id is not a valid note key",
+      });
+      // eslint-disable-next-line no-console
+      console.warn(`[import] skipped "${relPath}": blank (whitespace-only) \`id\` in frontmatter`);
+      continue;
+    }
+    if (seenNotes.has(id)) {
+      const kept = seenNotes.get(id)!;
+      stats.skipped_duplicate_ids.push({
+        id,
+        path: portable.path,
+        reason: `duplicate id "${id}" — already imported from an earlier file${kept.path ? ` (path="${kept.path}")` : ""}; kept the first, skipped this one`,
+      });
+      // eslint-disable-next-line no-console
+      console.warn(`[import] skipped "${relPath}": duplicate id "${id}" (kept the first file's note; this file's content is NOT imported)`);
+      continue;
+    }
     seenNotes.set(id, portable);
 
     if (opts.dryRun) {
@@ -2232,8 +2365,6 @@ export async function importVault(
       }
     }
   }
-
-  return stats;
 }
 
 /**

package/core/src/query-warnings.ts

@@ -34,6 +34,7 @@ import {
   type TagHierarchy,
 } from "./tag-hierarchy.js";
 import { chunkForInClause } from "./sql-in.js";
+import { escapeFtsToken } from "./search-query.js";
 
 export interface QueryWarning {
   code: string;
@@ -231,13 +232,15 @@ export function ignoredParamWarning(param: string, reason: string): QueryWarning
  *   - the FTS5 vocabulary — a `notes_fts_vocab` `fts5vocab('row')` table
  *     created here LAZILY and BEST-EFFORT (not part of the schema/
  *     migration — see the try/catch below) — the terms actually indexed,
- *     POST-tokenization/stemming (porter). A suggestion therefore
- *     sometimes reads as a stemmed form ("propoli" rather than "propolis")
- *     rather than the original dictionary word — an accepted tradeoff
- *     (documented in docs/HTTP_API.md) rather than maintaining a second,
- *     unstemmed index just for spelling suggestions.
+ *     POST-tokenization/stemming (porter). The closest CANDIDATE is found
+ *     against this stemmed vocabulary (small, deduped, cheap to
+ *     range-scan), but a stemmed candidate is never returned verbatim —
+ *     see `resolveSurfaceForm` below, which maps it back to a real word
+ *     before it's handed to the caller (vault#570 — a raw stem like
+ *     "propoli" or "cactu" isn't a word anyone would type).
  *   - tag names, when the caller passes `tagNames` (already cached by the
- *     caller's tag hierarchy — free to include).
+ *     caller's tag hierarchy — free to include, and already real words —
+ *     no de-stemming needed).
  *
  * `fts5vocab` is registered by the same FTS5 extension init as `notes_fts`
  * itself (not a separately-enabled module) so it's expected to be
@@ -263,6 +266,8 @@ export function computeSearchDidYouMean(
     const tokens = rawQuery.trim().split(/\s+/).filter(Boolean);
     if (tokens.length === 0) return undefined;
 
+    const tagNameSet = tagNames ? new Set(tagNames) : undefined;
+
     db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts_vocab USING fts5vocab(notes_fts, 'row')");
     const exactStmt = db.prepare("SELECT 1 FROM notes_fts_vocab WHERE term = ? LIMIT 1");
     const rangeStmt = db.prepare("SELECT term FROM notes_fts_vocab WHERE length(term) BETWEEN ? AND ?");
@@ -284,14 +289,19 @@ export function computeSearchDidYouMean(
       const hi = clean.length + 2;
       const rows = rangeStmt.all(lo, hi) as { term: string }[];
       const candidates = new Set<string>(rows.map((r) => r.term));
-      if (tagNames) for (const t of tagNames) candidates.add(t);
+      if (tagNameSet) for (const t of tagNameSet) candidates.add(t);
 
       const suggestion = suggestSimilarTag(candidates, lower);
-      if (suggestion && suggestion.toLowerCase() !== lower) {
-        changed = true;
-        return suggestion;
-      }
-      return tok;
+      if (!suggestion || suggestion.toLowerCase() === lower) return tok;
+
+      changed = true;
+      // A literal tag name is already a real word — return it verbatim. A
+      // vocabulary hit, though, came out of the PORTER-STEMMED index, so
+      // it's usually a truncated stem ("cactu" for "cactus") rather than a
+      // word a user would ever type (vault#570) — recover the real surface
+      // form before handing it back.
+      if (tagNameSet?.has(suggestion)) return suggestion;
+      return resolveSurfaceForm(db, suggestion) ?? suggestion;
     });
 
     if (!changed) return undefined;
@@ -301,6 +311,44 @@ export function computeSearchDidYouMean(
   }
 }
 
+/**
+ * Map a porter-stemmed vocabulary term ("cactu") back to the real
+ * dictionary word a note actually contains ("cactus") — vault#570 (issue
+ * #570's search polish item). `notes_fts` is porter-tokenized, so MATCHing
+ * the bare stem finds any note carrying a word that stems to it (the stem
+ * came FROM `notes_fts_vocab` in the first place, so at least one match is
+ * guaranteed). From there, tokenize that note's own path/content text —
+ * unstemmed, done here in JS with the same punctuation-stripping rule used
+ * above — and return the first token that literally STARTS WITH the stem.
+ * This works because Porter's rules are almost entirely suffix-stripping:
+ * the stem is near-always a prefix of the original word. Irregular cases
+ * (a stem that isn't a literal prefix) are a known, accepted limitation —
+ * same class as the porter tokenizer's irregular-plural gap documented in
+ * docs/HTTP_API.md — and simply fall back to the raw stem via the caller's
+ * `?? suggestion`, never worse than the pre-fix behavior.
+ *
+ * Bounded to a handful of rows (`LIMIT 5`) and wrapped in try/catch same as
+ * the caller — a nicety, never worth risking the search response itself.
+ */
+function resolveSurfaceForm(db: Database, stem: string): string | undefined {
+  try {
+    const rows = db
+      .prepare("SELECT path, content FROM notes_fts WHERE notes_fts MATCH ? LIMIT 5")
+      .all(escapeFtsToken(stem)) as { path: string | null; content: string | null }[];
+    for (const row of rows) {
+      const text = `${row.path ?? ""} ${row.content ?? ""}`;
+      for (const raw of text.split(/[^\p{L}\p{N}]+/gu)) {
+        if (!raw) continue;
+        const lower = raw.toLowerCase();
+        if (lower.length > stem.length && lower.startsWith(stem)) return lower;
+      }
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * `search_did_you_mean` warning (vault#551 WS2B) — wraps
  * {@link computeSearchDidYouMean}'s suggestion in the standard warning

package/core/src/schema-defaults.ts

@@ -57,7 +57,7 @@ export interface SchemaField {
    * `type_mismatch` warning that previously fired on every integer-shaped
    * field because the validator had no `"integer"` case. See vault#310.
    */
-  type?: "string" | "number" | "integer" | "boolean" | "array" | "object";
+  type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "reference";
   enum?: string[];
   description?: string;
   /**
@@ -369,6 +369,12 @@ function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
       return Array.isArray(value);
     case "object":
       return !!value && typeof value === "object" && !Array.isArray(value);
+    // `reference` (vault#typed-reference-field) validates like `string` —
+    // the write path (core/src/store.ts) separately resolves this value to
+    // a note and maintains a graph link; see tag-schemas.ts's
+    // `VALID_FIELD_TYPES` doc comment for the full contract.
+    case "reference":
+      return typeof value === "string";
   }
 }