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

package/core/src/notes.ts

@@ -851,6 +851,32 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     );
   }
 
+  // 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
+  // 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.
+  if (opts.hasBrokenLinks !== undefined) {
+    const unresolvedTableExists = db.prepare(
+      "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'unresolved_wikilinks'",
+    ).get() !== null;
+    if (!unresolvedTableExists) {
+      // No table yet means no note has ever had a broken link:
+      // hasBrokenLinks:true matches nothing; hasBrokenLinks:false is a
+      // no-op (every note already qualifies) — add no condition at all.
+      if (opts.hasBrokenLinks) conditions.push("0 = 1");
+    } else {
+      conditions.push(
+        opts.hasBrokenLinks
+          ? `EXISTS (SELECT 1 FROM unresolved_wikilinks ubl WHERE ubl.source_id = n.id)`
+          : `NOT EXISTS (SELECT 1 FROM unresolved_wikilinks ubl WHERE ubl.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) {
@@ -1238,6 +1264,7 @@ function toQueryHashInputs(opts: QueryOpts): QueryHashInputs {
     excludeTags: opts.excludeTags,
     hasTags: opts.hasTags,
     hasLinks: opts.hasLinks,
+    hasBrokenLinks: opts.hasBrokenLinks,
     path: opts.path,
     pathPrefix: opts.pathPrefix,
     extension: opts.extension,
@@ -1926,11 +1953,17 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       const candidates = db
         .prepare(`SELECT id, content FROM notes WHERE content IS NOT NULL AND content != '' AND (${orClauses})`)
         .all(...params) as { id: string; content: string }[];
-      const updateStmt = db.prepare("UPDATE notes SET content = ? WHERE id = ?");
+      // vault#555 fix 2 — this content rewrite is a real persisted-state
+      // change (the note's `#oldtag` references literally became
+      // `#newtag`) and must bump `updated_at` like any other content
+      // write, or a cursor/sync-poll loop never sees it. Shares the one
+      // `now` timestamp for the whole cascade (same convention as the
+      // tag-row rename pass above).
+      const updateStmt = db.prepare("UPDATE notes SET content = ?, updated_at = ? WHERE id = ?");
       for (const row of candidates) {
         const next = rewriteNoteBody(row.content, renames);
         if (next === row.content) continue;
-        updateStmt.run(next, row.id);
+        updateStmt.run(next, now, row.id);
         notesRewritten++;
       }
     }
@@ -1945,11 +1978,13 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       const candidates = db
         .prepare(`SELECT id, path FROM notes WHERE path IS NOT NULL AND (${orClauses})`)
         .all(...params) as { id: string; path: string }[];
-      const updateStmt = db.prepare("UPDATE notes SET path = ? WHERE id = ?");
+      // vault#555 fix 2 — same reasoning as the content rewrite above: a
+      // path rewrite is a real persisted-state change.
+      const updateStmt = db.prepare("UPDATE notes SET path = ?, updated_at = ? WHERE id = ?");
       for (const row of candidates) {
         const next = rewriteTagConfigPath(row.path, renames);
         if (next === row.path) continue;
-        updateStmt.run(next, row.id);
+        updateStmt.run(next, now, row.id);
         pathsRenamed++;
       }
     }

package/core/src/seed-packs.test.ts

@@ -291,6 +291,20 @@ describe("getting-started pack", () => {
     expect(GETTING_STARTED_CONTENT).toContain("over MCP");
   });
 
+  test("Getting Started carries the journaling / agent-memory / search conventions (vault#555)", () => {
+    expect(GETTING_STARTED_CONTENT).toContain("## A few shapes worth reusing");
+    // Journaling: indexed entry_date + mood enum.
+    expect(GETTING_STARTED_CONTENT).toContain("entry_date");
+    expect(GETTING_STARTED_CONTENT).toContain("mood");
+    // Agent-memory pattern: thread + messages + the if_exists:"ignore" crash-replay recipe.
+    expect(GETTING_STARTED_CONTENT).toContain("#thread");
+    expect(GETTING_STARTED_CONTENT).toContain("#message");
+    expect(GETTING_STARTED_CONTENT).toContain('if_exists: "ignore"');
+    // Search one-liner: literal by default, search_mode:"advanced" for FTS syntax.
+    expect(GETTING_STARTED_CONTENT).toContain("literal by default");
+    expect(GETTING_STARTED_CONTENT).toContain('search_mode: "advanced"');
+  });
+
   test("default vault-description constants orient + tell the AI to self-replace them", () => {
     for (const d of [DEFAULT_VAULT_DESCRIPTION, IMPORTED_VAULT_DESCRIPTION]) {
       expect(d.length).toBeGreaterThan(100);

package/core/src/seed-packs.ts

@@ -481,6 +481,29 @@ support operator queries (\`metadata: { held_on: { gte: "..." } }\`) and
 \`order_by\`; all tags declaring the same field must agree on its \`type\` and
 \`indexed\` flag.
 
+## A few shapes worth reusing
+
+Testers of this vault independently reinvented these — start from them instead:
+
+- **Journaling.** One tag (\`#journal\`) with an indexed \`entry_date\`
+  (\`{ type: "string", indexed: true }\`, ISO date) and a \`mood\` enum
+  (\`{ type: "string", enum: [...] }\`). Indexing \`entry_date\` (see "Only
+  \`indexed: true\` fields support operator queries" above) is what makes
+  date-range queries (\`metadata: { entry_date: { gte: "2026-01-01" } }\`) and
+  \`order_by: "entry_date"\` work.
+- **Agent memory (thread + messages, crash-replay-safe).** Model a
+  conversation as one \`#thread\` note (metadata: \`status\`, \`cursor\`) plus many
+  \`#message\` notes linked to it (\`relationship: "in-thread"\`), each carrying
+  its own \`status\`. If your write loop can crash and replay the same message,
+  give it a stable \`path\` (e.g. \`Threads/<thread-id>/msg-<n>\`) and create it
+  with \`if_exists: "ignore"\` — a retry after a crash safely returns the
+  already-written message instead of creating a duplicate, no
+  query-before-write round trip needed.
+- **Search.** \`query-notes { search: "..." }\` is literal by default — your
+  text is escaped, not parsed as FTS5 syntax, so punctuation like "didn't" or
+  "18.6" just works. Pass \`search_mode: "advanced"\` only when you actually
+  want FTS5 boolean/phrase/prefix syntax.
+
 ## Write gotchas
 
 A few behaviors worth knowing before you write at scale:

package/core/src/store.ts

@@ -741,22 +741,29 @@ export class BunSqliteStore implements Store {
         // Throws IndexedFieldError on an invalid identifier (e.g. kebab-case).
         indexedFieldOps.validateFieldName(fieldName);
       }
-      // Default-conformance pre-validate (vault#553 Decision B) — mirrors the
-      // indexed-type/name checks above: fail BEFORE any persistence so a bad
-      // `default` never gets written. Runs over EVERY field in the full
-      // (already-merged) `nextFields` map, not just indexed ones — a default
-      // that doesn't match its own field's type/enum is a tag-schema error
-      // regardless of queryability. This is the REST parity path: MCP's
-      // `update-tag` tool ALSO calls `collectTagFieldViolations` before
-      // reaching here (bundling every violation into one `TagFieldConflictError`
-      // — see that function's doc comment), so a conforming MCP call never
-      // trips this; a non-conforming one throws there first. REST has no such
-      // pre-check, so this is REST's only gate — same asymmetry as the
-      // indexed-type/name checks it sits beside.
+      // Default-conformance + type-vocabulary pre-validate (vault#553
+      // Decision B; vault#555 fix 4/5) — mirrors the indexed-type/name
+      // checks above: fail BEFORE any persistence so a bad `default` or an
+      // unrecognized `type` never gets written. Runs over EVERY field in the
+      // full (already-merged) `nextFields` map, not just indexed ones — both
+      // are tag-schema errors regardless of queryability. This is a
+      // DEFENSE-IN-DEPTH backstop, not the primary user-facing gate: both
+      // REST's `PUT /api/tags/:name` (`collectCrossTagFieldViolations` +
+      // `collectOwnFieldDefaultAndTypeViolations`, bundled 422) and MCP's
+      // `update-tag` (`collectTagFieldViolations`, same bundle) now
+      // pre-validate every field and report ALL violations together BEFORE
+      // ever reaching this chokepoint — a conforming call never trips this
+      // fail-fast loop. It stays here so any OTHER caller of
+      // `store.upsertTagRecord` (imports, migrations, scripts) still fails
+      // closed rather than persisting a lying schema.
       for (const [fieldName, spec] of Object.entries(nextFields ?? {})) {
-        const violation = tagSchemaOps.validateFieldDefault(fieldName, spec);
-        if (violation) {
-          throw new tagSchemaOps.InvalidFieldDefaultError(fieldName, violation.message);
+        const typeViolation = tagSchemaOps.validateFieldType(fieldName, spec);
+        if (typeViolation) {
+          throw new tagSchemaOps.InvalidFieldTypeError(fieldName, spec.type);
+        }
+        const defaultViolation = tagSchemaOps.validateFieldDefault(fieldName, spec);
+        if (defaultViolation) {
+          throw new tagSchemaOps.InvalidFieldDefaultError(fieldName, defaultViolation.message);
         }
       }
     }

package/core/src/tag-schemas.ts

@@ -190,6 +190,33 @@ export class InvalidFieldDefaultError extends Error {
   }
 }
 
+/**
+ * Thrown by `upsertTagRecord` (core/src/store.ts's chokepoint) when a
+ * field's declared `type` isn't one of the six recognized values (vault#555
+ * — `update-tag{fields:{weird:{type:"frobnicator"}}}` used to be accepted
+ * and persisted verbatim, no error, for any NON-indexed field: the only
+ * existing type check, `mapFieldType`, ran solely on `indexed: true` fields
+ * — see {@link validateFieldType}'s doc comment). Own-field validation leaf,
+ * same posture as `InvalidFieldDefaultError`.
+ */
+export class InvalidFieldTypeError extends Error {
+  code = "INVALID_FIELD_TYPE" as const;
+  error_type = "invalid_field_type" as const;
+  field: string;
+  type: string;
+  valid_types: readonly string[];
+
+  constructor(field: string, type: string) {
+    super(
+      `field "${field}" declares unknown type "${type}" — must be one of [${VALID_FIELD_TYPES.join(", ")}]`,
+    );
+    this.name = "InvalidFieldTypeError";
+    this.field = field;
+    this.type = type;
+    this.valid_types = VALID_FIELD_TYPES;
+  }
+}
+
 /**
  * Validate that a field's declared `default` (vault#553 Decision B) conforms
  * to its own `type` and (when declared) `enum`. Returns `null` when the
@@ -226,6 +253,73 @@ export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFi
   return null;
 }
 
+/**
+ * The full recognized vocabulary for `TagFieldSchema.type` — storage/
+ * advisory validation accepts all six; only `string`/`integer`/`boolean`
+ * are INDEXABLE (that narrower subset is `indexed-fields.ts`'s `TYPE_MAP`,
+ * enforced separately via `mapFieldType` for `indexed: true` fields).
+ * Matches `defaultMatchesType`'s switch and `schema-defaults.ts`'s
+ * `SchemaField.type` union — kept in lockstep by hand across the two
+ * deliberately-decoupled modules (see `validateFieldDefault`'s doc comment
+ * for why they don't cross-import).
+ */
+export const VALID_FIELD_TYPES = ["string", "number", "integer", "boolean", "array", "object"] as const;
+
+/**
+ * Validate that a field's declared `type` is one of the six recognized
+ * values (vault#555). Returns `null` when `type` is unset (own-field checks
+ * elsewhere already treat an unset type as "nothing to check against") or
+ * recognized; otherwise a {@link TagFieldViolation} with `reason:
+ * "invalid_type"`.
+ *
+ * Before this, a non-indexed field's `type` was NEVER validated anywhere —
+ * `mapFieldType` (the only existing type check) runs solely on fields
+ * declaring `indexed: true`. `update-tag{fields:{weird:{type:"frobnicator"}}}`
+ * on a plain (non-indexed) field silently persisted the bogus type
+ * verbatim; every later read of that field just skipped validation
+ * entirely (`valueMatchesType` in schema-defaults.ts has no vocabulary
+ * entry for it either). This is now the SINGLE gate — indexed fields still
+ * get their own, narrower `unsupported_indexed_type` check (which also
+ * covers a RECOGNIZED-but-unindexable type like `"array"`, a different
+ * case from a genuinely unknown token).
+ *
+ * Pure — never throws; callers ({@link collectTagFieldViolations}'s bundled
+ * MCP/REST report, and the store chokepoint's defense-in-depth pre-validate)
+ * each decide how to surface it.
+ */
+export function validateFieldType(field: string, spec: TagFieldSchema): TagFieldViolation | null {
+  if (!spec.type) return null;
+  if ((VALID_FIELD_TYPES as readonly string[]).includes(spec.type)) return null;
+  return {
+    field,
+    reason: "invalid_type",
+    message: `field "${field}" declares unknown type "${spec.type}" — must be one of [${VALID_FIELD_TYPES.join(", ")}]`,
+  };
+}
+
+/**
+ * Combined own-field `default` + `type` violation collection — no cross-tag
+ * lookups needed, so no `db` parameter (unlike
+ * {@link collectCrossTagFieldViolations}). Used by REST's `PUT
+ * /api/tags/:name` (vault#555 fix — folds these into the SAME bundled
+ * `tag_field_conflict` 422 report as the cross-tag checks, replacing the
+ * old fail-fast single-violation `invalid_field_default` 400) and reused by
+ * {@link collectTagFieldViolations} (MCP) so the two surfaces can't drift on
+ * what counts as an own-field violation.
+ */
+export function collectOwnFieldDefaultAndTypeViolations(
+  incomingFields: Record<string, TagFieldSchema>,
+): TagFieldViolation[] {
+  const violations: TagFieldViolation[] = [];
+  for (const [fieldName, spec] of Object.entries(incomingFields)) {
+    const typeViolation = validateFieldType(fieldName, spec);
+    if (typeViolation) violations.push(typeViolation);
+    const defaultViolation = validateFieldDefault(fieldName, spec);
+    if (defaultViolation) violations.push(defaultViolation);
+  }
+  return violations;
+}
+
 /** Same six-type vocabulary as `TagFieldSchema.type`'s doc comment. Unknown/unset types pass (nothing to check against). */
 function defaultMatchesType(value: unknown, type: string): boolean {
   switch (type) {
@@ -507,7 +601,8 @@ export interface TagFieldViolation {
     | "indexed_flag_conflict"
     | "unsupported_indexed_type"
     | "invalid_field_name"
-    | "invalid_default";
+    | "invalid_default"
+    | "invalid_type";
   message: string;
   /**
    * The conflicting declarer tag — present on the cross-tag reasons
@@ -625,18 +720,24 @@ export function collectCrossTagFieldViolations(
 
 /**
  * Full field-violation collection: {@link collectCrossTagFieldViolations}
- * PLUS the own-field checks (unsupported type for indexing, invalid
- * identifier, and — vault#553 Decision B — a non-conforming `default`).
- * Used by the MCP `update-tag` tool, which — unlike REST — had no prior
- * single-violation status-code contract to preserve for those checks (its
- * old inline loop threw an unstructured `Error` for them, same as
- * everything else pre-#554); collecting everything here is a strict
- * improvement. See {@link collectCrossTagFieldViolations}'s doc comment for
- * why REST calls that narrower function directly instead of this one — REST
- * gets the SAME `invalid_default` coverage via `store.upsertTagRecord`'s
- * fail-fast pre-validate (mirrors its indexed-type/name checks), just as a
- * single-violation `InvalidFieldDefaultError` → 400 rather than a bundled
- * `TagFieldConflictError` → 422.
+ * PLUS EVERY own-field check — {@link collectOwnFieldDefaultAndTypeViolations}
+ * (a non-conforming `default`, vault#553 Decision B; an unrecognized `type`,
+ * vault#555) AND the indexed-only checks (unsupported type for indexing,
+ * invalid identifier). Used by the MCP `update-tag` tool, which — unlike
+ * REST's indexed-type/name path — had no prior single-violation
+ * status-code contract to preserve for those two (its old inline loop threw
+ * an unstructured `Error` for them, same as everything else pre-#554);
+ * collecting everything here is a strict improvement. See
+ * {@link collectCrossTagFieldViolations}'s doc comment for why REST calls
+ * that narrower function directly for the CROSS-tag checks, then ALSO calls
+ * {@link collectOwnFieldDefaultAndTypeViolations} itself (vault#555 fix 5 —
+ * REST used to get `invalid_default` coverage only via
+ * `store.upsertTagRecord`'s fail-fast pre-validate, a single-violation
+ * `InvalidFieldDefaultError` → 400 that silently dropped every OTHER bad
+ * field in the same call; both surfaces now report every own-field default/
+ * type violation together, bundled with the cross-tag ones) — the
+ * indexed-type/name pair stays REST's own single-violation `400
+ * invalid_indexed_field` path (unchanged wire contract, vault#478).
  */
 export function collectTagFieldViolations(
   db: Database,
@@ -644,14 +745,9 @@ export function collectTagFieldViolations(
   incomingFields: Record<string, TagFieldSchema>,
 ): TagFieldViolation[] {
   const violations = collectCrossTagFieldViolations(db, tag, incomingFields);
+  violations.push(...collectOwnFieldDefaultAndTypeViolations(incomingFields));
 
   for (const [fieldName, spec] of Object.entries(incomingFields)) {
-    // Own-field default-conformance check (vault#553 Decision B) — applies
-    // to EVERY field (not just indexed ones); a bad default is a tag-schema
-    // error regardless of whether the field is queryable.
-    const defaultViolation = validateFieldDefault(fieldName, spec);
-    if (defaultViolation) violations.push(defaultViolation);
-
     if (spec.indexed === true) {
       const mapped = mapFieldType(spec.type);
       if (!mapped) {

package/core/src/types.ts

@@ -141,6 +141,15 @@ export interface QueryOpts {
   // `hasLinks` checks both directions — inbound or outbound counts as "has links".
   hasTags?: boolean;
   hasLinks?: boolean;
+  /**
+   * Presence filter on the `unresolved_wikilinks` table (vault#555):
+   * `true` → only notes with at least one dangling outbound link (a
+   * `[[wikilink]]` or structured `links` target that never resolved to a
+   * note); `false` → only notes with none. Safe on a vault where the
+   * `unresolved_wikilinks` table has never been created (no note has ever
+   * had a broken link) — `true` matches nothing, `false` is a no-op.
+   */
+  hasBrokenLinks?: boolean;
   path?: string;        // exact path match (case-insensitive)
   pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
   /**

package/core/src/wikilinks.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach } from "bun:test";
 import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
-import { parseWikilinks, syncWikilinks, resolveWikilink, resolveUnresolvedWikilinks } from "./wikilinks.js";
+import { parseWikilinks, syncWikilinks, resolveWikilink, resolveUnresolvedWikilinks, listUnresolvedWikilinks } from "./wikilinks.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -275,3 +275,115 @@ describe("path-based resolution", async () => {
     expect(links[0].targetId).toBe(target.id);
   });
 });
+
+// ---------------------------------------------------------------------------
+// unresolved_wikilinks relationship-column migration — atomicity (vault#555
+// wire+generalist must-fix; W7's migrateToV25-interruption lesson applied).
+// ---------------------------------------------------------------------------
+
+describe("ensureRelationshipColumn — crash-safe rebuild", () => {
+  /**
+   * Build a legacy (pre-vault#555) 2-column `unresolved_wikilinks` table with
+   * pending rows, on a store whose other tables already exist. Returns the
+   * source note's id (a real row so the FK is satisfiable when
+   * foreign_keys is on).
+   */
+  async function seedLegacyTable(): Promise<string> {
+    // A plain note (no wikilinks) doesn't create the v555 table.
+    const src = await store.createNote("plain body, no wikilinks", { path: "src-note" });
+    const tgt = await store.createNote("plain target", { path: "Target A" });
+    // Hand-build the pre-v555 shape (2-column PK, no `relationship`).
+    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"); // this one resolves to tgt after the migration
+    return src.id;
+  }
+
+  function hasRelationshipColumn(): boolean {
+    const cols = db.prepare("PRAGMA table_info(unresolved_wikilinks)").all() as { name: string }[];
+    return cols.some((c) => c.name === "relationship");
+  }
+
+  function tableExists(name: string): boolean {
+    const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = ?").get(name);
+    return row !== null;
+  }
+
+  it("a crash mid-rebuild (between RENAME and CREATE) rolls back — original table + pending rows intact, no orphan _pre_v555", async () => {
+    await seedLegacyTable();
+    expect(hasRelationshipColumn()).toBe(false); // legacy shape confirmed
+    const rowsBefore = (db.prepare("SELECT COUNT(*) AS c FROM unresolved_wikilinks").get() as { c: number }).c;
+    expect(rowsBefore).toBe(2);
+
+    // Monkey-patch db.exec to throw on the migration's CREATE — i.e. AFTER
+    // the RENAME has moved the table to _pre_v555 but BEFORE the new table
+    // exists. This is the exact interruption window the transaction wrapper
+    // must survive. BEGIN/RENAME/ROLLBACK all pass through untouched.
+    const origExec = db.exec.bind(db);
+    let crashed = false;
+    (db as unknown as { exec: (sql: string) => unknown }).exec = (sql: string) => {
+      if (!crashed && /CREATE TABLE unresolved_wikilinks \(/.test(sql)) {
+        crashed = true;
+        throw new Error("simulated crash between RENAME and CREATE");
+      }
+      return origExec(sql);
+    };
+
+    let thrown: unknown;
+    try {
+      // resolveUnresolvedWikilinks calls ensureRelationshipColumn first —
+      // the REAL heal path, not a hand-rolled copy.
+      resolveUnresolvedWikilinks(db, "Target A", "irrelevant-id");
+    } catch (e) {
+      thrown = e;
+    } finally {
+      (db as unknown as { exec: (sql: string) => unknown }).exec = origExec;
+    }
+
+    // The crash propagated (not swallowed).
+    expect(crashed).toBe(true);
+    expect((thrown as Error)?.message).toContain("simulated crash");
+
+    // ROLLBACK restored the ORIGINAL table exactly:
+    expect(tableExists("unresolved_wikilinks")).toBe(true); // NOT renamed away
+    expect(tableExists("unresolved_wikilinks_pre_v555")).toBe(false); // no orphan
+    expect(hasRelationshipColumn()).toBe(false); // still the legacy 2-col shape
+    const rowsAfter = (db.prepare("SELECT COUNT(*) AS c FROM unresolved_wikilinks").get() as { c: number }).c;
+    expect(rowsAfter).toBe(2); // pending rows NOT lost
+
+    // And a clean retry (no crash) fully recovers: migration runs, column
+    // added, rows preserved and backfilled as "wikilink".
+    resolveUnresolvedWikilinks(db, "nothing-matches-here", "irrelevant-id-2");
+    expect(hasRelationshipColumn()).toBe(true);
+    expect(tableExists("unresolved_wikilinks_pre_v555")).toBe(false);
+    const migratedRows = db.prepare("SELECT relationship FROM unresolved_wikilinks").all() as { relationship: string }[];
+    expect(migratedRows).toHaveLength(2);
+    expect(migratedRows.every((r) => r.relationship === "wikilink")).toBe(true);
+  });
+
+  it("a successful (uninterrupted) rebuild migrates + backfills as wikilink, and a pending forward-ref then resolves", async () => {
+    const srcId = await seedLegacyTable();
+
+    // Drive the heal through the real read path.
+    const before = listUnresolvedWikilinks(db);
+    expect(before.count).toBe(2);
+    expect(hasRelationshipColumn()).toBe(true); // listUnresolvedWikilinks healed it
+    expect(before.unresolved.every((u) => u.relationship === "wikilink")).toBe(true);
+
+    // "Target A" already exists (seedLegacyTable created it) — resolving now
+    // backfills the edge from the migrated pending row.
+    const targetA = await store.getNoteByPath("Target A");
+    const resolved = resolveUnresolvedWikilinks(db, "Target A", targetA!.id);
+    expect(resolved).toBe(1);
+    const links = await store.getLinks(srcId, { direction: "outbound" });
+    expect(links.some((l) => l.targetId === targetA!.id && l.relationship === "wikilink")).toBe(true);
+  });
+});