@openparachute/vault 0.7.0-rc.8 → 0.7.1

package/core/src/wikilinks.test.ts

@@ -1,7 +1,16 @@
 import { describe, it, expect, beforeEach } from "bun:test";
 import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
-import { parseWikilinks, syncWikilinks, resolveWikilink, resolveUnresolvedWikilinks, listUnresolvedWikilinks } from "./wikilinks.js";
+import {
+  parseWikilinks,
+  syncWikilinks,
+  resolveWikilink,
+  resolveWikilinkDetailed,
+  resolveUnresolvedWikilinks,
+  listUnresolvedWikilinks,
+  getContentWikilinkWarnings,
+  resolveOrQueueLink,
+} from "./wikilinks.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -142,6 +151,81 @@ describe("resolveWikilink", async () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Title fallback (additive — id/path/basename still win first)
+// ---------------------------------------------------------------------------
+
+describe("resolveWikilink — title fallback", async () => {
+  it("resolves via H1 title when path/basename both miss", async () => {
+    const note = await store.createNote("# My Real Title\n\nSome body text.", { path: "Inbox/2026-07-10-abc123" });
+    const id = resolveWikilink(db, "My Real Title");
+    expect(id).toBe(note.id);
+  });
+
+  it("matches the H1 title case-insensitively", async () => {
+    const note = await store.createNote("# My Real Title\n\nBody.", { path: "Inbox/xyz" });
+    const id = resolveWikilink(db, "my real title");
+    expect(id).toBe(note.id);
+  });
+
+  it("exact path match wins over a title match on a DIFFERENT note", async () => {
+    // A note literally path-named "My Real Title" ...
+    const byPath = await store.createNote("Path note body", { path: "My Real Title" });
+    // ... and an unrelated note whose H1 happens to be the same string.
+    await store.createNote("# My Real Title\n\nOther body.", { path: "Inbox/other" });
+    const id = resolveWikilink(db, "My Real Title");
+    expect(id).toBe(byPath.id);
+  });
+
+  it("basename match wins over title fallback", async () => {
+    const byBasename = await store.createNote("Body", { path: "Projects/Parachute/README" });
+    await store.createNote("# README\n\nOther body.", { path: "Inbox/other-readme" });
+    const id = resolveWikilink(db, "README");
+    expect(id).toBe(byBasename.id);
+  });
+
+  it("stays unresolved when two notes share the same H1 title (ambiguous)", async () => {
+    await store.createNote("# Shared Title\n\nA.", { path: "Inbox/a" });
+    await store.createNote("# Shared Title\n\nB.", { path: "Inbox/b" });
+    const id = resolveWikilink(db, "Shared Title");
+    expect(id).toBeNull();
+  });
+
+  it("does not fall through to title when basename is itself ambiguous", async () => {
+    // Two notes share basename "README" (ambiguous at step 3) AND a third
+    // note has an H1 title of "README" too — the ambiguous basename step
+    // must not be rescued by the title step.
+    await store.createNote("A", { path: "Folder1/README" });
+    await store.createNote("B", { path: "Folder2/README" });
+    await store.createNote("# README\n\nC.", { path: "Inbox/c" });
+    const id = resolveWikilink(db, "README");
+    expect(id).toBeNull();
+  });
+
+  it("ignores H2+ headings — only a literal single-# line counts", async () => {
+    await store.createNote("## Not An H1\n\nBody.", { path: "Inbox/h2" });
+    const id = resolveWikilink(db, "Not An H1");
+    expect(id).toBeNull();
+  });
+
+  it("resolveWikilinkDetailed reports the title match as resolved", async () => {
+    const note = await store.createNote("# Detailed Title\n\nBody.", { path: "Inbox/detail" });
+    const result = resolveWikilinkDetailed(db, "Detailed Title");
+    expect(result.resolved).toBe(true);
+    expect(result.note_id).toBe(note.id);
+    expect(result.path).toBe("Inbox/detail");
+  });
+
+  it("resolveWikilinkDetailed reports an ambiguous title match", async () => {
+    await store.createNote("# Dup Title\n\nA.", { path: "Inbox/dup-a" });
+    await store.createNote("# Dup Title\n\nB.", { path: "Inbox/dup-b" });
+    const result = resolveWikilinkDetailed(db, "Dup Title");
+    expect(result.resolved).toBe(false);
+    expect(result.ambiguous).toBe(true);
+    expect(result.candidates).toHaveLength(2);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Sync
 // ---------------------------------------------------------------------------
@@ -157,6 +241,16 @@ describe("syncWikilinks", async () => {
     expect(links[0].relationship).toBe("wikilink");
   });
 
+  it("creates a link via the title fallback when path/basename miss", async () => {
+    const target = await store.createNote("# Weekly Review\n\nBody.", { path: "Inbox/2026-07-10-abc123" });
+    const source = await store.createNote("See [[Weekly Review]]");
+
+    const links = await store.getLinks(source.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0].targetId).toBe(target.id);
+    expect(links[0].relationship).toBe("wikilink");
+  });
+
   it("tracks unresolved wikilinks", async () => {
     const source = await store.createNote("See [[Missing Note]]");
 
@@ -254,6 +348,116 @@ describe("syncWikilinks", async () => {
     expect(links[0].metadata?.display).toBe("intro");
     expect(links[0].metadata?.anchor).toBe("Introduction");
   });
+
+  // vault#570 — an ambiguous target (≥2 notes share the same basename/
+  // title) must be reported distinctly from a genuine miss, via
+  // `syncWikilinks`'s `ambiguous` array, and must NOT be linked or queued
+  // into `unresolved_wikilinks` (queuing implies "wait for this to be
+  // created", which doesn't describe an already-existing ambiguity).
+  it("returns ambiguous targets separately from unresolved, creates no link, and does not queue them", async () => {
+    const a = await store.createNote("A", { path: "Folder1/Dup" });
+    const b = await store.createNote("B", { path: "Folder2/Dup" });
+    // Empty content on create so the note exists (satisfying the
+    // `unresolved_wikilinks` FK) without triggering `syncWikilinks` yet —
+    // the manual call below is what's under test, and its return value
+    // isn't otherwise observable through the Store API.
+    const source = await store.createNote("");
+
+    const content = "See [[Dup]] and also [[Truly Missing]]";
+    const result = syncWikilinks(db, source.id, content);
+    expect(result.added).toBe(0);
+    expect(result.unresolved).toEqual(["Truly Missing"]);
+    expect(result.ambiguous).toEqual([{ target: "Dup", count: 2 }]);
+
+    const links = await store.getLinks(source.id, { direction: "outbound" });
+    expect(links.some((l) => l.targetId === a.id || l.targetId === b.id)).toBe(false);
+
+    const pending = db.prepare(
+      "SELECT target_path FROM unresolved_wikilinks WHERE source_id = ?",
+    ).all(source.id) as { target_path: string }[];
+    // Only the genuinely-missing target is queued — "Dup" is absent.
+    expect(pending.map((r) => r.target_path)).toEqual(["Truly Missing"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getContentWikilinkWarnings (vault#570) — read-only warning derivation
+// ---------------------------------------------------------------------------
+
+describe("getContentWikilinkWarnings", () => {
+  it("returns an unresolved_link warning for a content wikilink to a missing target", async () => {
+    const source = await store.createNote("See [[Nowhere]]");
+    const warnings = getContentWikilinkWarnings(db, source.id, "See [[Nowhere]]");
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]!.code).toBe("unresolved_link");
+    expect(warnings[0]!.target).toBe("Nowhere");
+    expect(warnings[0]!.relationship).toBe("wikilink");
+  });
+
+  it("returns an ambiguous_link warning (with candidate_count) for a content wikilink matching 2 notes", async () => {
+    await store.createNote("A", { path: "Folder1/Same" });
+    await store.createNote("B", { path: "Folder2/Same" });
+    const source = await store.createNote("See [[Same]]");
+    const warnings = getContentWikilinkWarnings(db, source.id, "See [[Same]]");
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]!.code).toBe("ambiguous_link");
+    expect(warnings[0]!.target).toBe("Same");
+    expect(warnings[0]!.candidate_count).toBe(2);
+  });
+
+  it("returns no warnings for a resolved wikilink, including a self-link", async () => {
+    const target = await store.createNote("Target", { path: "Resolvable" });
+    const source = await store.createNote("See [[Resolvable]]", { path: "Myself Again" });
+    expect(getContentWikilinkWarnings(db, source.id, "See [[Resolvable]]")).toEqual([]);
+    expect(getContentWikilinkWarnings(db, source.id, "See [[Myself Again]]")).toEqual([]);
+    void target;
+  });
+
+  it("returns no warnings when content has no wikilinks", () => {
+    expect(getContentWikilinkWarnings(db, "some-id", "plain text, no brackets")).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveOrQueueLink (vault#555 + vault#570) — discriminated outcome
+// ---------------------------------------------------------------------------
+
+describe("resolveOrQueueLink", () => {
+  it("returns {status: 'resolved', note_id} for a resolvable target", async () => {
+    const target = await store.createNote("Target", { path: "Findable" });
+    const source = await store.createNote("source");
+    const outcome = resolveOrQueueLink(db, source.id, "Findable", "knows");
+    expect(outcome.status).toBe("resolved");
+    if (outcome.status === "resolved") expect(outcome.note_id).toBe(target.id);
+  });
+
+  it("returns {status: 'queued'} and queues the pending row for a genuinely missing target", async () => {
+    const source = await store.createNote("source");
+    const outcome = resolveOrQueueLink(db, source.id, "Not There", "knows");
+    expect(outcome.status).toBe("queued");
+    const pending = db.prepare(
+      "SELECT target_path, relationship FROM unresolved_wikilinks WHERE source_id = ?",
+    ).all(source.id) as { target_path: string; relationship: string }[];
+    expect(pending).toEqual([{ target_path: "Not There", relationship: "knows" }]);
+  });
+
+  it("returns {status: 'ambiguous', candidates} and does NOT queue for a target matching 2 notes", async () => {
+    const a = await store.createNote("A", { path: "Folder1/Twice" });
+    const b = await store.createNote("B", { path: "Folder2/Twice" });
+    const source = await store.createNote("source");
+    const outcome = resolveOrQueueLink(db, source.id, "Twice", "knows");
+    expect(outcome.status).toBe("ambiguous");
+    if (outcome.status === "ambiguous") {
+      expect(outcome.candidates.map((c) => c.note_id).sort()).toEqual([a.id, b.id].sort());
+    }
+    const tableExists = (db.prepare("PRAGMA table_info(unresolved_wikilinks)").all() as unknown[]).length > 0;
+    if (tableExists) {
+      const pending = db.prepare(
+        "SELECT * FROM unresolved_wikilinks WHERE source_id = ?",
+      ).all(source.id) as unknown[];
+      expect(pending).toHaveLength(0);
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------

package/core/src/wikilinks.ts

@@ -1,9 +1,10 @@
 import { Database } from "bun:sqlite";
 import type { Note } from "./types.js";
 import * as linkOps from "./links.js";
-import { getNote } from "./notes.js";
+import { getNote, findNotesByTitle } from "./notes.js";
 import { chunkForInClause } from "./sql-in.js";
 import { transaction } from "./txn.js";
+import type { QueryWarning } from "./query-warnings.js";
 
 // ---------------------------------------------------------------------------
 // Parser — extract [[wikilinks]] from markdown content
@@ -128,6 +129,14 @@ function stripCode(content: string): string {
  * 3. Basename match — target matches the last segment of a path
  *    (e.g., "README" matches "Projects/Parachute/README"). Same
  *    cross-extension ambiguity policy as #2.
+ * 4. **Title fallback** (additive) — only tried when #2/#3 found NO
+ *    candidates at all (a clean miss, not an ambiguous one). Matches the
+ *    note whose H1 title (first `# ` line in its content, see
+ *    {@link findNotesByTitle}) equals the target, case-insensitively.
+ *    Resolves only when EXACTLY one note has that title; 2+ matches is
+ *    ambiguous and stays unresolved rather than guessing. Rescues links
+ *    into a note whose displayed title differs from its path/basename —
+ *    the top source of silently-broken wikilinks.
  */
 export function resolveWikilink(db: Database, target: string): string | null {
   // 1. Explicit extension form: `[[path.ext]]` where `.ext` is a
@@ -176,6 +185,12 @@ export function resolveWikilink(db: Database, target: string): string | null {
   `).all(target, `%/${target}`) as { id: string }[];
 
   if (basename.length === 1) return basename[0]!.id;
+  if (basename.length > 1) return null; // ambiguous basename — don't fall through to title
+
+  // 4. Title fallback — only reached on a clean miss (0 basename
+  // candidates). See the doc comment above for the ambiguity policy.
+  const byTitle = findNotesByTitle(db, target);
+  if (byTitle.length === 1) return byTitle[0]!.id;
 
   // Ambiguous or no match
   return null;
@@ -246,6 +261,21 @@ export function resolveWikilinkDetailed(db: Database, target: string): WikilinkR
     };
   }
 
+  // 4. Title fallback — only reached on a clean basename miss (0
+  // candidates), mirroring resolveWikilink.
+  const byTitle = findNotesByTitle(db, target);
+  if (byTitle.length === 1) {
+    const match = byTitle[0]!;
+    return { resolved: true, note_id: match.id, path: match.path ?? undefined, candidates: [] };
+  }
+  if (byTitle.length > 1) {
+    return {
+      resolved: false,
+      ambiguous: true,
+      candidates: byTitle.map((r) => ({ note_id: r.id, path: r.path ?? "" })),
+    };
+  }
+
   return { resolved: false, ambiguous: false, candidates: [] };
 }
 
@@ -306,6 +336,50 @@ export function listUnresolvedWikilinks(db: Database, limit = 50): { unresolved:
   return { unresolved, count: total };
 }
 
+/** One note's dangling outbound link, as surfaced on a note read (vault#555). */
+export interface BrokenLink {
+  target: string;
+  relationship: string;
+}
+
+/**
+ * Batch-fetch each note's pending `unresolved_wikilinks` rows — the
+ * `include_broken_links` surfacing on `query-notes` / `GET /notes`. ONE
+ * query for the whole page (mirrors `getLinksHydratedForNotes`'s batching),
+ * not one per note. Returns a map with an entry (possibly `[]`) for every
+ * requested id whenever the table exists; when the table has never been
+ * created (no note in this vault has ever had a broken link) every id maps
+ * to `[]` without a query attempt.
+ */
+export function getUnresolvedLinksForNotes(db: Database, noteIds: string[]): Map<string, BrokenLink[]> {
+  const result = new Map<string, BrokenLink[]>(noteIds.map((id) => [id, []]));
+  if (noteIds.length === 0) return result;
+
+  const rows: { source_id: string; target_path: string; relationship: string }[] = [];
+  try {
+    ensureRelationshipColumn(db);
+    for (const chunk of chunkForInClause(noteIds)) {
+      const placeholders = chunk.map(() => "?").join(", ");
+      rows.push(...db.prepare(
+        `SELECT source_id, target_path, relationship FROM unresolved_wikilinks WHERE source_id IN (${placeholders})`,
+      ).all(...chunk) as typeof rows);
+    }
+  } catch {
+    // Table doesn't exist — every id already maps to [] above.
+    return result;
+  }
+
+  for (const row of rows) {
+    result.get(row.source_id)?.push({ target: row.target_path, relationship: row.relationship || WIKILINK_REL });
+  }
+  return result;
+}
+
+/** Single-note convenience wrapper around {@link getUnresolvedLinksForNotes}. */
+export function getUnresolvedLinksForNote(db: Database, noteId: string): BrokenLink[] {
+  return getUnresolvedLinksForNotes(db, [noteId]).get(noteId) ?? [];
+}
+
 // ---------------------------------------------------------------------------
 // Sync — maintain wikilink-based links for a note
 // ---------------------------------------------------------------------------
@@ -313,19 +387,14 @@ export function listUnresolvedWikilinks(db: Database, limit = 50): { unresolved:
 const WIKILINK_REL = "wikilink";
 
 /**
- * Sync wikilink-based links for a note.
- * Parses content for [[wikilinks]], resolves targets, creates/removes links.
- *
- * Returns counts of changes made.
+ * Deduplicate parsed wikilinks by target (case-insensitively) — the same
+ * target mentioned multiple times in a note's content resolves to ONE
+ * link/warning, not one per mention. Shared by {@link syncWikilinks} (which
+ * mutates links/the pending-resolution table) and
+ * {@link getContentWikilinkWarnings} (which only reads) so the two can't
+ * drift on which targets they consider.
  */
-export function syncWikilinks(
-  db: Database,
-  noteId: string,
-  content: string,
-): { added: number; removed: number; unresolved: string[] } {
-  const parsed = parseWikilinks(content);
-
-  // Deduplicate by target (same target mentioned multiple times = one link)
+function dedupeWikilinkTargets(parsed: ParsedWikilink[]): Map<string, ParsedWikilink> {
   const targetMap = new Map<string, ParsedWikilink>();
   for (const wl of parsed) {
     const key = wl.target.toLowerCase();
@@ -333,17 +402,53 @@ export function syncWikilinks(
       targetMap.set(key, wl);
     }
   }
+  return targetMap;
+}
+
+/** One target's ambiguity — surfaced target string + how many notes it matched. */
+export interface AmbiguousWikilinkTarget {
+  target: string;
+  count: number;
+}
+
+/**
+ * Sync wikilink-based links for a note.
+ * Parses content for [[wikilinks]], resolves targets, creates/removes links.
+ *
+ * Returns counts of changes made. `unresolved` is content wikilinks whose
+ * target matched NO note (queued into `unresolved_wikilinks` for lazy
+ * backfill — see {@link resolveUnresolvedWikilinks}). `ambiguous` (vault#570)
+ * is content wikilinks whose target matched ≥2 notes — these are NEITHER
+ * linked NOR queued: a future note being created can't retroactively
+ * resolve an ambiguity between two notes that ALREADY exist, and queuing it
+ * would risk the pending-resolution sweep later linking to an arbitrary
+ * THIRD same-named note rather than reporting the collision. The caller
+ * (MCP `create-note`/`update-note`, REST `POST`/`PATCH /notes`) surfaces
+ * `ambiguous` as an `ambiguous_link` warning naming the target + match
+ * count, distinct from `unresolved`'s `unresolved_link`.
+ */
+export function syncWikilinks(
+  db: Database,
+  noteId: string,
+  content: string,
+): { added: number; removed: number; unresolved: string[]; ambiguous: AmbiguousWikilinkTarget[] } {
+  const targetMap = dedupeWikilinkTargets(parseWikilinks(content));
 
   // Resolve each unique target
   const resolvedLinks = new Map<string, { targetId: string; wl: ParsedWikilink }>();
   const unresolved: string[] = [];
+  const ambiguous: AmbiguousWikilinkTarget[] = [];
 
   for (const [key, wl] of targetMap) {
-    const targetId = resolveWikilink(db, wl.target);
-    if (targetId && targetId !== noteId) {
-      // Don't create self-links
-      resolvedLinks.set(targetId, { targetId, wl });
-    } else if (!targetId) {
+    const detail = resolveWikilinkDetailed(db, wl.target);
+    if (detail.resolved) {
+      // Don't create self-links — silently skipped, same as before.
+      if (detail.note_id !== noteId) {
+        resolvedLinks.set(detail.note_id!, { targetId: detail.note_id!, wl });
+      }
+    } else if (detail.ambiguous) {
+      ambiguous.push({ target: wl.target, count: detail.candidates.length });
+    } else {
       unresolved.push(wl.target);
     }
   }
@@ -385,10 +490,11 @@ export function syncWikilinks(
     }
   }
 
-  // Store unresolved wikilinks for later resolution
+  // Store unresolved wikilinks for later resolution. Ambiguous targets are
+  // deliberately NOT queued here — see the doc comment above.
   syncUnresolvedWikilinks(db, noteId, unresolved);
 
-  return { added, removed, unresolved };
+  return { added, removed, unresolved, ambiguous };
 }
 
 // ---------------------------------------------------------------------------
@@ -572,14 +678,29 @@ export function resolveUnresolvedWikilinks(
 /**
  * Resolve a structured-link `target` — an ID or a path/title — to a note
  * ID. ID lookup first (structured links accept "note ID or path" per the
- * tool docs; wikilinks never carry a raw ID), then the SAME path/basename
- * resolution `[[wikilinks]]` use ({@link resolveWikilink}: explicit
- * extension, exact path, basename).
+ * tool docs; wikilinks never carry a raw ID), then the SAME path/basename/
+ * title resolution `[[wikilinks]]` use ({@link resolveWikilink}: explicit
+ * extension, exact path, basename, then H1-title fallback on a clean miss).
  */
 export function resolveLinkTarget(db: Database, idOrPath: string): string | null {
-  const byId = db.prepare("SELECT id FROM notes WHERE id = ?").get(idOrPath) as { id: string } | null;
-  if (byId) return byId.id;
-  return resolveWikilink(db, idOrPath);
+  const detail = resolveLinkTargetDetailed(db, idOrPath);
+  return detail.resolved ? detail.note_id! : null;
+}
+
+/**
+ * Detailed counterpart to {@link resolveLinkTarget} — same ID-then-path/
+ * basename resolution order, but surfaces AMBIGUOUS (≥2 path/basename
+ * matches, vault#570) as a distinct outcome instead of collapsing it into
+ * the same `null` a genuine miss returns. An ID lookup is never ambiguous
+ * (the `id` column is the primary key), so ambiguity can only arise from
+ * the path/basename fallback — {@link resolveWikilinkDetailed}.
+ */
+export function resolveLinkTargetDetailed(db: Database, idOrPath: string): WikilinkResolution {
+  const byId = db.prepare("SELECT id, path FROM notes WHERE id = ?").get(idOrPath) as { id: string; path: string | null } | null;
+  if (byId) {
+    return { resolved: true, note_id: byId.id, path: byId.path ?? undefined, candidates: [] };
+  }
+  return resolveWikilinkDetailed(db, idOrPath);
 }
 
 /**
@@ -610,24 +731,112 @@ export function queueUnresolvedLink(
   ).run(sourceId, targetPath, relationship);
 }
 
+/** Outcome of {@link resolveOrQueueLink} — a discriminated union so callers can't confuse "queued" with "ambiguous" (vault#570; both used to collapse to the same `null`). */
+export type ResolveOrQueueOutcome =
+  | { status: "resolved"; note_id: string }
+  | { status: "ambiguous"; candidates: { note_id: string; path: string }[] }
+  | { status: "queued" };
+
+/**
+ * Drop any pending forward-ref queued for `sourceId` under `relationship`,
+ * regardless of the (stale) `target_path` it names. Used by the
+ * `reference`-field auto-link sync (core/src/store.ts's
+ * `syncReferenceFieldLinks`, vault#typed-reference-field) before re-resolving
+ * a changed field value — without this, a field that used to point at an
+ * unresolved target and is then changed to a different (or removed) value
+ * would leave the OLD forward-ref queued forever, since
+ * {@link queueUnresolvedLink}'s primary key includes `target_path` and a
+ * changed value queues under a NEW key rather than replacing the old row.
+ * Safe no-op when the table doesn't exist yet.
+ */
+export function clearQueuedLink(db: Database, sourceId: string, relationship: string): void {
+  try {
+    db.prepare(
+      "DELETE FROM unresolved_wikilinks WHERE source_id = ? AND relationship = ?",
+    ).run(sourceId, relationship);
+  } catch {
+    // Table may not exist yet — nothing to clear.
+  }
+}
+
 /**
  * Resolve a structured link NOW, or queue it for lazy resolution when the
  * target doesn't exist yet — mirroring the wikilink forward-ref contract
  * (a target created later, in this same batch or a future call, backfills
- * the edge automatically via {@link resolveUnresolvedWikilinks}). Returns
- * the resolved note ID, or `null` when queued. Callers MUST surface an
- * `unresolved_link` warning naming the target when this returns `null` —
- * the write itself never fails, but silence is never the fallback
- * (vault#555 — "the API should never silently do the wrong thing").
+ * the edge automatically via {@link resolveUnresolvedWikilinks}).
+ *
+ * Returns a {@link ResolveOrQueueOutcome}:
+ *   - `"resolved"` — the edge should be created against `note_id` now.
+ *   - `"ambiguous"` (vault#570) — the target matched ≥2 notes (e.g. two
+ *     notes sharing an H1 title). NEITHER linked nor queued — see
+ *     {@link syncWikilinks}'s doc comment for why queuing an ambiguous
+ *     target would be wrong. Callers MUST surface a distinct
+ *     `ambiguous_link` warning naming the target + `candidates.length`.
+ *   - `"queued"` — the target matched NO note; queued for lazy backfill.
+ *     Callers MUST surface an `unresolved_link` warning naming the target.
+ *
+ * The write itself never fails on either non-`"resolved"` outcome — silence
+ * is never the fallback (vault#555 — "the API should never silently do the
+ * wrong thing").
  */
 export function resolveOrQueueLink(
   db: Database,
   sourceId: string,
   target: string,
   relationship: string,
-): string | null {
-  const resolvedId = resolveLinkTarget(db, target);
-  if (resolvedId) return resolvedId;
+): ResolveOrQueueOutcome {
+  const detail = resolveLinkTargetDetailed(db, target);
+  if (detail.resolved) return { status: "resolved", note_id: detail.note_id! };
+  if (detail.ambiguous) return { status: "ambiguous", candidates: detail.candidates };
   queueUnresolvedLink(db, sourceId, target, relationship);
-  return null;
+  return { status: "queued" };
+}
+
+/**
+ * Content-wikilink counterpart of the `unresolved_link`/`ambiguous_link`
+ * warnings structured `links` already produce via {@link resolveOrQueueLink}
+ * (vault#570 — content-parsed `[[wikilinks]]` to a missing target used to
+ * fire NO write-time warning at all, even though the equivalent structured
+ * `links` entry did). READ-ONLY: does not mutate `unresolved_wikilinks` or
+ * create/remove any link — that mutation already happened inside
+ * {@link syncWikilinks} (called from `Store.createNote`/`updateNote`).
+ * Callers invoke this AFTER the note's content is committed, passing the
+ * SAME `noteId`/`content` pair, to recompute the identical per-target
+ * classification for the response's `warnings` array — single source of
+ * truth is {@link resolveWikilinkDetailed}, so this can't drift from what
+ * `syncWikilinks` actually did. Mirrors `syncWikilinks`'s target selection
+ * exactly: same lowercase-target dedupe key (via
+ * {@link dedupeWikilinkTargets}), same self-link skip (a wikilink resolving
+ * to the note's own id is neither linked nor warned about).
+ */
+export function getContentWikilinkWarnings(
+  db: Database,
+  noteId: string,
+  content: string,
+): QueryWarning[] {
+  const targetMap = dedupeWikilinkTargets(parseWikilinks(content));
+  const warnings: QueryWarning[] = [];
+
+  for (const [, wl] of targetMap) {
+    const detail = resolveWikilinkDetailed(db, wl.target);
+    if (detail.resolved) continue; // resolved (incl. self-link) — nothing to warn about
+    if (detail.ambiguous) {
+      warnings.push({
+        code: "ambiguous_link",
+        message: `wikilink target "${wl.target}" matched ${detail.candidates.length} notes — ambiguous, no link created. Use a more specific path, [[Target.ext]], or the note's ID to disambiguate.`,
+        target: wl.target,
+        relationship: WIKILINK_REL,
+        candidate_count: detail.candidates.length,
+      });
+    } else {
+      warnings.push({
+        code: "unresolved_link",
+        message: `wikilink target "${wl.target}" did not resolve to any note — queued and will backfill automatically if a matching note is created later.`,
+        target: wl.target,
+        relationship: WIKILINK_REL,
+      });
+    }
+  }
+
+  return warnings;
 }

package/package.json

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