@openparachute/vault 0.7.9-rc.2 → 0.7.9-rc.3

package/core/src/mcp.ts

@@ -23,7 +23,15 @@ import {
   resolveStructuredLinkNote,
   getUnresolvedLinksForNote,
   getUnresolvedLinksForNotes,
+  narrowByVisibleBrokenness,
+  sqlHasBrokenLinks,
+  getAmbiguousLinksForNote,
+  getAmbiguousLinksForNotes,
+  narrowByVisibleAmbiguity,
+  sqlHasAmbiguousLinks,
   getContentWikilinkWarnings,
+  ambiguousLinkWarning,
+  unresolvedLinkWarning,
 } from "./wikilinks.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -143,6 +151,17 @@ function structuredError(
   return Object.assign(new Error(message), fields);
 }
 
+function requireNoteReference(value: unknown): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw structuredError("`id` is required", {
+      error_type: "missing_required_field",
+      field: "id",
+      hint: "pass the note's id or path (or its unique H1 title)",
+    });
+  }
+  return value;
+}
+
 /**
  * Resolve a note identifier — tries ID first, then case-insensitive
  * path match, then (additive fallback) an H1-title match. Works
@@ -470,6 +489,23 @@ export interface GenerateMcpToolsOpts {
    * path with no extra fetch.
    */
   aggregateVisibility?: (note: Note) => boolean;
+  /**
+   * `ambiguityVisible` (vault#581 auth review) is an OPTIONAL per-note
+   * predicate gating everything the ambiguous-links surface discloses.
+   * `candidate_count` is derived VAULT-WIDE, so a stored `2` on a `[[Dup]]`
+   * split across scopes tells a tag-scoped reader that a note it cannot see
+   * exists — and `has_ambiguous_links: true` would let it sweep its whole
+   * in-scope corpus for such collisions. When provided, each persisted row
+   * is re-resolved and its candidates narrowed to the visible ones: a row
+   * is disclosed only when ≥2 remain, `candidate_count` is the visible
+   * count, and `has_ambiguous_links` is answered against that same narrowed
+   * view (see `narrowByVisibleAmbiguity` / `sqlHasAmbiguousLinks` in
+   * core/src/wikilinks.ts). Same contract as `nearTraversable`: core stays
+   * scope-unaware and only invokes the injected `(noteId) => boolean`
+   * closure. Omitted (unscoped / internal callers) → the persisted counts
+   * are returned as-is and the SQL filter answers directly, unchanged.
+   */
+  ambiguityVisible?: (noteId: string) => boolean;
   /**
    * `AttachmentTicketProvider` seam (vault attachment-tickets design,
    * Wave 1 — D10 "tools omitted when unwired"). When provided,
@@ -549,6 +585,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
   const nearTraversable = opts?.nearTraversable;
   const ifExistsVisible = opts?.ifExistsVisible;
   const aggregateVisibility = opts?.aggregateVisibility;
+  const ambiguityVisible = opts?.ambiguityVisible;
   // Write-attribution (vault#298) — captured once at tool-generation time
   // (a fresh tool set is generated per MCP request, so this is request-scoped)
   // and folded into every create/update the tools perform.
@@ -600,6 +637,28 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     {
       name: "query-notes",
       execute: async (params) => {
+        // --- Ambiguous-links scope split (vault#581 auth review) ---
+        // `requestedHasAmbiguous` is what the caller asked for;
+        // `sqlHasAmbiguous` is what is safe to push into SQL for a reader
+        // that will be narrowed by `narrowByVisibleAmbiguity` afterwards
+        // (`true` is a superset and stays; `false` is lifted). Identical for
+        // an unscoped reader, where no predicate is injected and the SQL
+        // filter alone is the whole answer.
+        const requestedHasAmbiguous = params.has_ambiguous_links as boolean | undefined;
+        const sqlHasAmbiguous = sqlHasAmbiguousLinks(requestedHasAmbiguous, Boolean(ambiguityVisible));
+
+        // --- Broken-links scope split (vault#239) ---
+        // Same shape as the ambiguity split above, one polarity stricter:
+        // NEITHER `true` nor `false` is safe to push into SQL for a scoped
+        // reader, because a note can be broken in that reader's sub-vault
+        // while carrying no `unresolved_wikilinks` row at all (its target's
+        // only candidates are invisible, so the row sits in
+        // `ambiguous_wikilinks`). `sqlHasBrokenLinks` lifts both and
+        // `narrowByVisibleBrokenness` re-decides per note. Identical for an
+        // unscoped reader, where the SQL filter alone is the whole answer.
+        const requestedHasBroken = params.has_broken_links as boolean | undefined;
+        const sqlHasBroken = sqlHasBrokenLinks(requestedHasBroken, Boolean(ambiguityVisible));
+
         // --- Link expansion config (shared across single + list paths) ---
         const expandLinks = params.expand_links === true;
         const expandMode = (params.expand_mode as ExpandMode) ?? "full";
@@ -671,7 +730,10 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             result.links = linkOps.getLinksHydrated(db, note.id);
           }
           if (params.include_broken_links) {
-            result.broken_links = getUnresolvedLinksForNote(db, note.id);
+            result.broken_links = getUnresolvedLinksForNote(db, note.id, ambiguityVisible);
+          }
+          if (params.include_ambiguous_links) {
+            result.ambiguous_links = getAmbiguousLinksForNote(db, note.id, ambiguityVisible);
           }
           if (params.include_attachments) {
             result.attachments = await store.getAttachments(note.id);
@@ -816,7 +878,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             excludeTags: aggExcludeTags,
             hasTags: params.has_tags as boolean | undefined,
             hasLinks: params.has_links as boolean | undefined,
-            hasBrokenLinks: params.has_broken_links as boolean | undefined,
+            hasBrokenLinks: sqlHasBroken,
+            hasAmbiguousLinks: sqlHasAmbiguous,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
             excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
@@ -842,7 +905,23 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           // set (reusing the `ids` semijoin `near` already pushes into SQL).
           // Core stays scope-unaware — it only invokes the plain closure.
           const aggAllMatches = await store.queryNotes({ ...aggFilterOpts, limit: 1000000 });
-          const aggVisibleIds = aggAllMatches.filter(aggregateVisibility).map((n) => n.id);
+          // vault#581 auth review: a rollup over `has_ambiguous_links` is the
+          // same oracle as the note-level filter (a non-zero count still
+          // reveals the collision), so narrow the visible id set by the
+          // reader's own view of each row before aggregating.
+          // vault#239: the `has_broken_links` rollup is the same oracle for
+          // the same reason — re-decide brokenness on the sub-vault too.
+          const aggVisibleIds = narrowByVisibleBrokenness(
+            db,
+            narrowByVisibleAmbiguity(
+              db,
+              aggAllMatches.filter(aggregateVisibility),
+              requestedHasAmbiguous,
+              ambiguityVisible,
+            ),
+            requestedHasBroken,
+            ambiguityVisible,
+          ).map((n) => n.id);
           // Always run the rollup, even on an empty visible set: ungrouped
           // count (vault#626) must return `[{group:null,value:0}]`, not `[]`.
           return await store.aggregateNotes({ ids: aggVisibleIds, aggregate: aggregateSpec });
@@ -939,7 +1018,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             excludeTags,
             hasTags: params.has_tags as boolean | undefined,
             hasLinks: params.has_links as boolean | undefined,
-            hasBrokenLinks: params.has_broken_links as boolean | undefined,
+            hasBrokenLinks: sqlHasBroken,
+            hasAmbiguousLinks: sqlHasAmbiguous,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
             excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
@@ -1022,7 +1102,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
               excludeTags,
               hasTags: params.has_tags as boolean | undefined,
               hasLinks: params.has_links as boolean | undefined,
-              hasBrokenLinks: params.has_broken_links as boolean | undefined,
+              hasBrokenLinks: sqlHasBroken,
+              hasAmbiguousLinks: sqlHasAmbiguous,
               path: params.path as string | undefined,
               pathPrefix: params.path_prefix as string | undefined,
               excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
@@ -1091,7 +1172,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             excludeTags,
             hasTags: params.has_tags as boolean | undefined,
             hasLinks: params.has_links as boolean | undefined,
-            hasBrokenLinks: params.has_broken_links as boolean | undefined,
+            hasBrokenLinks: sqlHasBroken,
+            hasAmbiguousLinks: sqlHasAmbiguous,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
             excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
@@ -1148,6 +1230,17 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           results = results.filter((n) => nearScope!.has(n.id));
         }
 
+        // vault#581 auth review — the `has_ambiguous_links` filter must
+        // answer on the reader's OWN sub-vault, not the whole vault. No-op
+        // unscoped (no predicate injected) and when the filter wasn't asked
+        // for. See `narrowByVisibleAmbiguity` for the superset contract and
+        // the page-shortening effect.
+        results = narrowByVisibleAmbiguity(db, results, requestedHasAmbiguous, ambiguityVisible);
+        // vault#239 — same rule for `has_broken_links`: the SQL filter was
+        // lifted for a scoped reader, so the real predicate is applied here
+        // on that reader's own sub-vault. No-op unscoped.
+        results = narrowByVisibleBrokenness(db, results, requestedHasBroken, ambiguityVisible);
+
         // --- Format output ---
         const includeContent = params.include_content === true; // default false for list
         // Range params require content in the response — on lists that
@@ -1219,7 +1312,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
         }
 
         // --- Hydrate links/attachments/broken-links per note if requested ---
-        if (params.include_links || params.include_attachments || params.include_broken_links) {
+        if (params.include_links || params.include_attachments || params.include_broken_links || params.include_ambiguous_links) {
           // Links hydrate for the WHOLE page in a constant number of
           // queries (see getLinksHydratedForNotes) — the per-note variant
           // cost (1 link query + 1 summary query + N tag queries) × page
@@ -1229,13 +1322,18 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             : null;
           // Same one-batched-query-for-the-page shape as links (vault#555).
           const brokenLinksByNote = params.include_broken_links
-            ? getUnresolvedLinksForNotes(db, (output as any[]).map((n: any) => n.id))
+            ? getUnresolvedLinksForNotes(db, (output as any[]).map((n: any) => n.id), ambiguityVisible)
+            : null;
+          // Same one-batched-query-for-the-page shape for the ambiguity twin (vault#581).
+          const ambiguousLinksByNote = params.include_ambiguous_links
+            ? getAmbiguousLinksForNotes(db, (output as any[]).map((n: any) => n.id), ambiguityVisible)
             : null;
           const enrichedOut: any[] = [];
           for (const n of output as any[]) {
             const enriched: any = { ...n };
             if (linksByNote) enriched.links = linksByNote.get(n.id) ?? [];
             if (brokenLinksByNote) enriched.broken_links = brokenLinksByNote.get(n.id) ?? [];
+            if (ambiguousLinksByNote) enriched.ambiguous_links = ambiguousLinksByNote.get(n.id) ?? [];
             if (params.include_attachments) enriched.attachments = await store.getAttachments(n.id);
             enrichedOut.push(enriched);
           }
@@ -1559,20 +1657,9 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
               if (outcome.status === "resolved") {
                 await store.createLink(sourceId, outcome.note_id, link.relationship);
               } else if (outcome.status === "ambiguous") {
-                pushLinkWarning(sourceId, {
-                  code: "ambiguous_link",
-                  message: `link target "${link.target}" (relationship "${link.relationship}") matched ${outcome.candidates.length} notes — ambiguous, no link created. Use a more specific path or the note's ID to disambiguate.`,
-                  target: link.target,
-                  relationship: link.relationship,
-                  candidate_count: outcome.candidates.length,
-                });
+                pushLinkWarning(sourceId, ambiguousLinkWarning(link.target, link.relationship, outcome.candidates.length));
               } else {
-                pushLinkWarning(sourceId, {
-                  code: "unresolved_link",
-                  message: `link target "${link.target}" (relationship "${link.relationship}") did not resolve to any note — queued and will backfill automatically if a matching note is created later.`,
-                  target: link.target,
-                  relationship: link.relationship,
-                });
+                pushLinkWarning(sourceId, unresolvedLinkWarning(link.target, link.relationship));
               }
             }
           }
@@ -1730,7 +1817,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             // branch using this same item's payload. Otherwise mirror the
             // existing `requireNote` behavior (throw "Note not found").
             // vault#309.
-            const resolved = resolveNote(db, item.id as string);
+            const idOrPath = requireNoteReference(item.id);
+            const resolved = resolveNote(db, idOrPath);
             if (!resolved) {
               if (item.if_missing === "create") {
                 // Treat the update payload as a create payload. Minimum:
@@ -1765,7 +1853,6 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
                 //     processed and used by Gitcoin's sync; the
                 //     misleading wording is fixed here so a future
                 //     reader doesn't trust it and break the workflow.
-                const idOrPath = item.id as string;
                 // Heuristic: if `path` isn't set AND the `id` looks like a
                 // path (contains "/" or doesn't match a typical opaque-id
                 // shape), use it as the path too. Otherwise treat it as a
@@ -2118,20 +2205,9 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
               if (outcome.status === "resolved") {
                 await store.createLink(sourceId, outcome.note_id, link.relationship, link.metadata);
               } else if (outcome.status === "ambiguous") {
-                pushLinkWarning(sourceId, {
-                  code: "ambiguous_link",
-                  message: `link target "${link.target}" (relationship "${link.relationship}") matched ${outcome.candidates.length} notes — ambiguous, no link created. Use a more specific path or the note's ID to disambiguate.`,
-                  target: link.target,
-                  relationship: link.relationship,
-                  candidate_count: outcome.candidates.length,
-                });
+                pushLinkWarning(sourceId, ambiguousLinkWarning(link.target, link.relationship, outcome.candidates.length));
               } else {
-                pushLinkWarning(sourceId, {
-                  code: "unresolved_link",
-                  message: `link target "${link.target}" (relationship "${link.relationship}") did not resolve to any note — queued and will backfill automatically if a matching note is created later.`,
-                  target: link.target,
-                  relationship: link.relationship,
-                });
+                pushLinkWarning(sourceId, unresolvedLinkWarning(link.target, link.relationship));
               }
             }
           }
@@ -2193,7 +2269,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     {
       name: "delete-note",
       execute: async (params) => {
-        const note = requireNote(db, params.id as string);
+        const note = requireNote(db, requireNoteReference(params.id));
         await store.deleteNote(note.id);
         return { deleted: true, id: note.id };
       },
@@ -3032,4 +3108,3 @@ export class BatchTooLargeError extends Error {
     this.got = got;
   }
 }
-

package/core/src/notes.ts

@@ -1053,8 +1053,9 @@ export function buildFilterConditions(db: Database, opts: QueryOpts): { conditio
   // Presence: has_broken_links (vault#555) — a dangling outbound wikilink or
   // structured `links` target that never resolved. The `unresolved_wikilinks`
   // table is created lazily (see wikilinks.ts:ensureUnresolvedTable) only when
-  // a link actually goes unresolved — a vault where nothing ever has won't
-  // have the table at all. Check existence first rather than reference it
+  // a link actually goes unresolved — migrateToV28 heals a pre-#555 2-column
+  // table at boot but does NOT create the table on a vault that never queued
+  // one. Check existence first rather than reference it
   // unconditionally: a read-only query filter shouldn't have the side effect
   // of creating a table, and a bare `EXISTS`/`NOT EXISTS` against a missing
   // table would throw "no such table" instead of the correct empty answer.
@@ -1076,6 +1077,28 @@ export function buildFilterConditions(db: Database, opts: QueryOpts): { conditio
     }
   }
 
+  // Presence: has_ambiguous_links (vault#581) — an outbound `[[wikilink]]` or
+  // structured `links`/`reference` target that matched ≥2 notes, so no link
+  // was created. Same lazily-created-table dance as `has_broken_links` above
+  // (`ambiguous_wikilinks` is only created once a link actually goes
+  // ambiguous), and for the same reasons: a read-only filter must not create
+  // the table, and a bare EXISTS against a missing one throws instead of
+  // answering "none".
+  if (opts.hasAmbiguousLinks !== undefined) {
+    const ambiguousTableExists = db.prepare(
+      "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'ambiguous_wikilinks'",
+    ).get() !== null;
+    if (!ambiguousTableExists) {
+      if (opts.hasAmbiguousLinks) conditions.push("0 = 1");
+    } else {
+      conditions.push(
+        opts.hasAmbiguousLinks
+          ? `EXISTS (SELECT 1 FROM ambiguous_wikilinks ual WHERE ual.source_id = n.id)`
+          : `NOT EXISTS (SELECT 1 FROM ambiguous_wikilinks ual WHERE ual.source_id = n.id)`,
+      );
+    }
+  }
+
   // ID set filter — used by `near` to push neighborhood scoping into SQL so
   // that LIMIT applies to the neighborhood, not the whole notes table.
   if (opts.ids !== undefined) {
@@ -1694,6 +1717,7 @@ function toQueryHashInputs(opts: QueryOpts): QueryHashInputs {
     hasTags: opts.hasTags,
     hasLinks: opts.hasLinks,
     hasBrokenLinks: opts.hasBrokenLinks,
+    hasAmbiguousLinks: opts.hasAmbiguousLinks,
     path: opts.path,
     pathPrefix: opts.pathPrefix,
     excludePathPrefix: opts.excludePathPrefix,
@@ -2767,6 +2791,8 @@ export function mergeTags(
     const deleteNoteTagsStmt = db.prepare("DELETE FROM note_tags WHERE tag_name = ?");
     const deleteTagStmt = db.prepare("DELETE FROM tags WHERE name = ?");
     const countStmt = db.prepare("SELECT COUNT(*) as c FROM note_tags WHERE tag_name = ?");
+    const sourceNoteIdsStmt = db.prepare("SELECT note_id FROM note_tags WHERE tag_name = ?");
+    const affectedIds = new Set<string>();
 
     for (const source of uniqueSources) {
       const exists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(source);
@@ -2775,6 +2801,11 @@ export function mergeTags(
         continue;
       }
       const before = (countStmt.get(source) as { c: number }).c;
+      // Collect BEFORE the delete so we can bump updated_at on every note
+      // whose tags actually change (vault#567).
+      for (const row of sourceNoteIdsStmt.all(source) as { note_id: string }[]) {
+        affectedIds.add(row.note_id);
+      }
       retagStmt.run(target, source);
       deleteNoteTagsStmt.run(source);
       // Dropping the tag row drops its identity (description, fields,
@@ -2783,6 +2814,24 @@ export function mergeTags(
       deleteTagStmt.run(source);
       merged[source] = before;
     }
+
+    // vault#567: a tags-only `update-note` already bumps `updated_at` so
+    // cursor/sync consumers see the retag. `merge-tags` used to skip the
+    // bump (flood-avoidance), which made the equivalent bulk retag
+    // invisible to since-last-check loops. Bump every note that actually
+    // lost a source tag; notes that never carried a merged-away source
+    // are left untouched. `updated_at_ms` moves with `updated_at`
+    // (vault#586) so the cursor keyset surfaces the change.
+    if (affectedIds.size > 0) {
+      const now = new Date().toISOString();
+      const nowMs = timestampToMs(now) ?? Date.now();
+      const bumpStmt = db.prepare(
+        "UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?",
+      );
+      for (const id of affectedIds) {
+        bumpStmt.run(now, nowMs, id);
+      }
+    }
   });
 
   return { merged, target };

package/core/src/schema-v28-unresolved-wikilinks.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Migration v27 → v28: fold the lazy unresolved_wikilinks relationship-column
+ * self-heal into the versioned chain (vault#567 item 2).
+ *
+ * The interesting path is an EXISTING vault whose `unresolved_wikilinks`
+ * table still has the pre-#555 2-column PK — not a fresh vault (those
+ * create the 3-column table lazily, or never create it). Gating is the
+ * load-bearing claim: a vault that never queued a dangling link must NOT
+ * grow the table on open.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { initSchema, SCHEMA_VERSION } from "./schema.js";
+import { SqliteStore } from "./store.js";
+import { ensureRelationshipColumn } from "./wikilinks.js";
+
+function hasTable(db: Database, name: string): boolean {
+  return !!db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
+}
+
+function columnNames(db: Database, table: string): string[] {
+  return (db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]).map((c) => c.name);
+}
+
+describe("SCHEMA_VERSION v28", () => {
+  it("bumped SCHEMA_VERSION to at least 28 (unresolved_wikilinks heal is versioned)", () => {
+    expect(SCHEMA_VERSION).toBeGreaterThanOrEqual(28);
+  });
+});
+
+describe("migrateToV28 — does NOT create unresolved_wikilinks on a vault that never needed it", () => {
+  it("a fresh vault (no dangling links) still has no unresolved_wikilinks table after initSchema", () => {
+    const db = new Database(":memory:");
+    const store = new SqliteStore(db);
+    expect(store).toBeDefined();
+    expect(hasTable(db, "unresolved_wikilinks")).toBe(false);
+    expect(
+      (db.prepare("SELECT MAX(version) AS v FROM schema_version").get() as { v: number }).v,
+    ).toBe(SCHEMA_VERSION);
+  });
+});
+
+describe("migrateToV28 — heals a pre-#555 2-column table at boot", () => {
+  let db: Database;
+  let store: SqliteStore;
+  let sourceId: string;
+
+  beforeEach(async () => {
+    db = new Database(":memory:");
+    store = new SqliteStore(db);
+    const src = await store.createNote("plain body, no wikilinks", { path: "src-note" });
+    await store.createNote("plain target", { path: "Target A" });
+    sourceId = src.id;
+    db.exec(`
+      CREATE TABLE unresolved_wikilinks (
+        source_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+        target_path TEXT NOT NULL COLLATE NOCASE,
+        PRIMARY KEY (source_id, target_path)
+      )
+    `);
+    db.prepare("INSERT INTO unresolved_wikilinks (source_id, target_path) VALUES (?, ?)").run(
+      src.id,
+      "Target B",
+    );
+    db.prepare("INSERT INTO unresolved_wikilinks (source_id, target_path) VALUES (?, ?)").run(
+      src.id,
+      "Target A",
+    );
+  });
+
+  it("initSchema rebuilds the 3-column PK and backfills relationship='wikilink'", () => {
+    expect(columnNames(db, "unresolved_wikilinks")).not.toContain("relationship");
+    initSchema(db);
+    expect(columnNames(db, "unresolved_wikilinks")).toContain("relationship");
+    expect(hasTable(db, "unresolved_wikilinks_pre_v555")).toBe(false);
+    const rows = db
+      .prepare("SELECT source_id, target_path, relationship FROM unresolved_wikilinks ORDER BY target_path")
+      .all() as { source_id: string; target_path: string; relationship: string }[];
+    expect(rows).toHaveLength(2);
+    expect(rows.every((r) => r.relationship === "wikilink")).toBe(true);
+    expect(rows.every((r) => r.source_id === sourceId)).toBe(true);
+    expect(
+      (db.prepare("SELECT MAX(version) AS v FROM schema_version").get() as { v: number }).v,
+    ).toBe(SCHEMA_VERSION);
+  });
+
+  it("is idempotent — a second initSchema neither throws nor duplicates rows", () => {
+    initSchema(db);
+    initSchema(db);
+    const count = (db.prepare("SELECT COUNT(*) AS c FROM unresolved_wikilinks").get() as { c: number }).c;
+    expect(count).toBe(2);
+    expect(columnNames(db, "unresolved_wikilinks")).toContain("relationship");
+  });
+
+  it("a 3-column table is a no-op (no rewrite)", () => {
+    initSchema(db); // first pass heals
+    const before = db.prepare("SELECT * FROM unresolved_wikilinks ORDER BY target_path").all();
+    ensureRelationshipColumn(db);
+    initSchema(db);
+    const after = db.prepare("SELECT * FROM unresolved_wikilinks ORDER BY target_path").all();
+    expect(after).toEqual(before);
+  });
+});

package/core/src/schema.ts

@@ -4,8 +4,9 @@ import { rebuildIndexes, listIndexedFields } from "./indexed-fields.js";
 import { findMixedTypeIndexedFieldNotes } from "./doctor.js";
 import { transaction } from "./txn.js";
 import { timestampToMs } from "./cursor.js";
+import { ensureRelationshipColumn } from "./wikilinks.js";
 
-export const SCHEMA_VERSION = 27;
+export const SCHEMA_VERSION = 28;
 
 /**
  * Deterministic last-resort epoch for a note whose `updated_at` AND
@@ -621,6 +622,13 @@ export function initSchema(db: Database): void {
   // already reads as "needs embedding." See vault semantic-search MVP plan.
   migrateToV27(db);
 
+  // Migrate v27 → v28: fold the lazy unresolved_wikilinks `relationship`
+  // column self-heal into the versioned chain (vault#567 item 2). Gated:
+  // no table → no-op; 3-column table → no-op; only a pre-#555 2-column
+  // table is rebuilt. Does not create the table on vaults that never
+  // queued an unresolved link, and does not rewrite notes.
+  migrateToV28(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1729,6 +1737,25 @@ function migrateToV27(db: Database): void {
   });
 }
 
+/**
+ * Migrate v27 → v28: version the unresolved_wikilinks relationship-column
+ * self-heal that used to run lazily on first touch (vault#567 item 2).
+ *
+ * COST: this does NOT rewrite every vault on open. `ensureRelationshipColumn`
+ * gates on PRAGMA table_info:
+ *   - table missing (most vaults — lazy creation, never queued a dangling
+ *     link) → return immediately, no CREATE;
+ *   - `relationship` already present (post-#555 / fresh 3-column table) →
+ *     return immediately;
+ *   - pre-#555 2-column table only → one atomic 4-statement rebuild of
+ *     `unresolved_wikilinks` (typically tiny; not a notes rewrite).
+ * Subsequent opens are the same PRAGMA no-op. The per-touch lazy call in
+ * `wikilinks.ts` stays as a no-op safety net after this version.
+ */
+function migrateToV28(db: Database): void {
+  ensureRelationshipColumn(db);
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;