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

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;

package/core/src/store.ts

@@ -12,16 +12,25 @@ import {
 } from "./indexed-fields.js";
 import {
   syncWikilinks,
+  parseWikilinks,
+  resolveWikilinkDetailed,
+  rewriteWikilinkTargets,
+  wikilinkPathForm,
+  wikilinkRenameCandidates,
   resolveUnresolvedWikilinks,
   resolveOrQueueLink,
   clearQueuedLink,
   clearQueuedLinkTarget,
+  clearAmbiguousLink,
+  clearAmbiguousLinkTarget,
+  refreshAmbiguousLinks,
+  noteResolutionKeys,
+  pathResolutionKeys,
   requeueInboundWikilinksForDelete,
 } from "./wikilinks.js";
 import { chunkForInClause } from "./sql-in.js";
-import { pathTitle } from "./paths.js";
 import { timestampToMs } from "./cursor.js";
-import { transaction } from "./txn.js";
+import { afterCommit, transaction } from "./txn.js";
 import { HookRegistry } from "./hooks.js";
 import {
   loadTagHierarchy,
@@ -257,6 +266,9 @@ export class BunSqliteStore implements Store {
       // resolved target.
       linkOps.deleteLinksBySourceRelationship(this.db, note.id, fieldName);
       clearQueuedLink(this.db, note.id, fieldName);
+      // vault#581 twin: a recorded ambiguity for the OLD value must go too,
+      // or the field would keep reporting a collision it no longer has.
+      clearAmbiguousLink(this.db, note.id, fieldName);
 
       if (typeof nextValue === "string" && nextValue.trim() !== "") {
         // Resolves now, or queues a lazy forward-ref on a miss — same
@@ -374,7 +386,10 @@ export class BunSqliteStore implements Store {
     // still-present-but-unresolved element stays queued (re-queued
     // idempotently above).
     for (const value of priorSet) {
-      if (!nextSet.has(value)) clearQueuedLinkTarget(this.db, noteId, fieldName, value);
+      if (!nextSet.has(value)) {
+        clearQueuedLinkTarget(this.db, noteId, fieldName, value);
+        clearAmbiguousLinkTarget(this.db, noteId, fieldName, value); // vault#581 twin
+      }
     }
   }
 
@@ -519,6 +534,10 @@ export class BunSqliteStore implements Store {
 
     if (note.path) {
       resolveUnresolvedWikilinks(this.db, note.path, note.id);
+      // vault#581 — this note becoming a NEW candidate can only make an
+      // existing ambiguity wider, but the recorded `candidate_count` has to
+      // stay honest. Bounded to rows whose target could name this note.
+      refreshAmbiguousLinks(this.db, noteResolutionKeys(note));
     }
 
     // Reference-field auto-link (vault#typed-reference-field) — no prior
@@ -601,71 +620,173 @@ export class BunSqliteStore implements Store {
       }
     }
 
-    const note = noteOps.updateNote(this.db, id, updates);
+    // vault#708 — the rename cascade has to know which brackets resolved to
+    // THIS note, and resolution is only observable BEFORE the path moves.
+    // So the plan (source note -> the exact bracket texts that pointed here)
+    // is computed against the pre-write index; `cascadeRename` applies it
+    // after, when the new path is known.
+    const cascadePlan = oldPath && updates.path !== undefined && oldPath !== updates.path
+      ? this.planCascadeRename(id, oldPath)
+      : undefined;
+
+    // Keep the note-row write and every derived index/cascade write in one
+    // atomic unit. Any later failure must leave the note and its indexes at
+    // the pre-update state rather than committing only the first SQL write.
+    const note = this.transaction(() => {
+      const note = noteOps.updateNote(this.db, id, updates);
+
+      // Wikilink sync runs against the *resulting* content. For append/prepend
+      // we don't have the new value pre-write — read it back off the returned
+      // note so a `[[Foo]]` introduced via append still creates the link.
+      if (updates.content !== undefined || updates.append !== undefined || updates.prepend !== undefined) {
+        syncWikilinks(this.db, id, note.content);
+      }
 
-    // Wikilink sync runs against the *resulting* content. For append/prepend
-    // we don't have the new value pre-write — read it back off the returned
-    // note so a `[[Foo]]` introduced via append still creates the link.
-    if (updates.content !== undefined || updates.append !== undefined || updates.prepend !== undefined) {
-      syncWikilinks(this.db, id, note.content);
-    }
+      if (updates.path !== undefined && note.path) {
+        if (cascadePlan && oldPath && oldPath !== note.path) {
+          this.cascadeRename(cascadePlan, note, oldPath);
+        }
+        resolveUnresolvedWikilinks(this.db, note.path, id);
+        // vault#581 — a rename is one of the two ways an ambiguity stops being
+        // ambiguous (the other is a delete). Sweep the OLD path's keys as well
+        // as the new ones: it's the target the collision was recorded under.
+        refreshAmbiguousLinks(this.db, [
+          ...pathResolutionKeys(oldPath, note.extension),
+          ...noteResolutionKeys(note),
+        ]);
+      }
 
-    if (updates.path !== undefined && note.path) {
-      if (oldPath && oldPath !== note.path) {
-        this.cascadeRename(oldPath, note.path);
+      // Reference-field auto-link sync (vault#typed-reference-field). Only
+      // when this call actually touched `metadata` — see the read above for
+      // why a content/tags/path-only update is skipped.
+      if (updates.metadata !== undefined) {
+        this.syncReferenceFieldLinks(note, priorMetadataForRefs);
       }
-      resolveUnresolvedWikilinks(this.db, note.path, id);
-    }
 
-    // Reference-field auto-link sync (vault#typed-reference-field). Only
-    // when this call actually touched `metadata` — see the read above for
-    // why a content/tags/path-only update is skipped.
-    if (updates.metadata !== undefined) {
-      this.syncReferenceFieldLinks(note, priorMetadataForRefs);
-    }
+      return note;
+    });
 
-    // Invalidate before the hook dispatch so any handler that re-queries
-    // the hierarchy from inside its own logic sees post-write state.
-    // `metadata` updates can change the `parents` field on a config note
-    // even when the path didn't change, so always invalidate when the
-    // current path is in a config namespace.
-    this.invalidateConfigCachesForPath(note.path, oldPath);
-    this.hooks.dispatch("updated", note, this);
+    // Dispatch and invalidate only once the whole surrounding transaction
+    // stack commits. In a multi-item transactionAsync batch the inner Store
+    // transaction is a SAVEPOINT, so "after the inner closure" is not yet
+    // post-commit; afterCommit carries these through to the outer boundary.
+    afterCommit(this.db, () => {
+      this.invalidateConfigCachesForPath(note.path, oldPath);
+      this.hooks.dispatch("updated", note, this);
+    });
 
     return note;
   }
 
   /**
-   * When a note is renamed, update [[wikilinks]] in other notes that referenced the old path.
-   * Matches both full path and basename references.
+   * Plan the rename cascade (vault#708) — for a note about to move off
+   * `oldPath`, the exact `[[bracket]]` texts in each source note that
+   * RESOLVED TO THIS NOTE, keyed by source id.
+   *
+   * MUST run before the path write: resolution is a property of the index,
+   * and once the row moves, `[[Rename]]` no longer means what it meant.
+   *
+   * The source set comes from the `links` rows pointing at this note
+   * (`relationship = 'wikilink'`) — an index-driven prefilter that already
+   * excludes the two classes the old basename-matching cascade corrupted:
+   *   - AMBIGUOUS brackets (`[[Rename]]` with `keep/Rename` AND `move/Rename`
+   *     present) never get a `links` row at all — they live in
+   *     `ambiguous_wikilinks` (vault#581/#707) and are healed by
+   *     `refreshAmbiguousLinks` after the rename, not by a text rewrite.
+   *   - brackets that resolved to a DIFFERENT same-basename note, whose
+   *     `links` row points elsewhere.
+   * The note itself is added to the set because a self-referencing bracket
+   * is deliberately never given a `links` row (`syncWikilinks` skips
+   * self-links) yet the old cascade rewrote it — parity.
+   *
+   * `links` rows only say "this note links here", not WHICH bracket did it
+   * (`syncWikilinks` dedupes by resolved target id and stores no bracket
+   * text), so every candidate source is re-parsed and each bracket
+   * re-resolved. That is also what keeps a source's OTHER same-named
+   * brackets untouched.
    */
-  private cascadeRename(oldPath: string, newPath: string): void {
-    const oldTitle = pathTitle(oldPath);
-    const newTitle = pathTitle(newPath);
-
-    const candidates = this.db.prepare(`
-      SELECT id, content FROM notes
-      WHERE content LIKE ? OR content LIKE ?
-    `).all(`%[[${oldPath}%`, `%[[${oldTitle}%`) as { id: string; content: string }[];
-
-    for (const row of candidates) {
-      let updated = row.content;
-
-      updated = updated.replace(
-        new RegExp(`\\[\\[${escapeRegex(oldPath)}([#|\\]])`, "g"),
-        `[[${newPath}$1`,
-      );
+  private planCascadeRename(id: string, oldPath: string): Map<string, string[]> {
+    const rows = this.db.prepare(
+      "SELECT source_id FROM links WHERE target_id = ? AND relationship = 'wikilink'",
+    ).all(id) as { source_id: string }[];
+    const sourceIds = new Set<string>(rows.map((r) => r.source_id));
+    sourceIds.add(id);
+
+    const plan = new Map<string, string[]>();
+    for (const sourceId of sourceIds) {
+      const row = this.db.prepare("SELECT content FROM notes WHERE id = ?")
+        .get(sourceId) as { content: string } | null;
+      if (!row?.content) continue;
+      const targets: string[] = [];
+      const seen = new Set<string>();
+      for (const wl of parseWikilinks(row.content)) {
+        const key = wl.target.toLowerCase();
+        if (seen.has(key)) continue;
+        seen.add(key);
+        // Only path-derived forms of the old path can be invalidated by a
+        // repath; an H1-title-fallback bracket keeps resolving and must not
+        // be touched.
+        if (!wikilinkPathForm(wl.target, oldPath)) continue;
+        const detail = resolveWikilinkDetailed(this.db, wl.target);
+        if (detail.resolved && detail.note_id === id) targets.push(wl.target);
+      }
+      if (targets.length > 0) plan.set(sourceId, targets);
+    }
+    return plan;
+  }
 
-      if (oldTitle !== newTitle && oldTitle !== oldPath) {
-        updated = updated.replace(
-          new RegExp(`\\[\\[${escapeRegex(oldTitle)}([#|\\]])`, "g"),
-          `[[${newTitle}$1`,
-        );
+  /**
+   * Apply a {@link planCascadeRename} plan after the path write: rewrite only
+   * the brackets that resolved to the renamed note, preserving each one's
+   * shape (basename stays a basename, full path stays a full path, an
+   * explicit `.ext` keeps its `.ext`). A basename widens to the full path
+   * only when the NEW basename would no longer resolve back to this note —
+   * i.e. the move created a fresh collision.
+   *
+   * Each rewritten source is re-parsed via `syncWikilinks`, so `links`,
+   * `unresolved_wikilinks` and `ambiguous_wikilinks` stay consistent with
+   * the new text.
+   */
+  private cascadeRename(plan: Map<string, string[]>, note: Note, oldPath: string): void {
+    if (plan.size === 0 || !note.path) return;
+    const newPath = note.path;
+
+    // One resolution per distinct bracket text, shared across sources.
+    const replacement = new Map<string, string>();
+
+    for (const [sourceId, targets] of plan) {
+      const row = this.db.prepare("SELECT content FROM notes WHERE id = ?")
+        .get(sourceId) as { content: string } | null;
+      if (!row?.content) continue;
+
+      const mapping = new Map<string, string>();
+      for (const target of targets) {
+        const key = target.toLowerCase();
+        let next = replacement.get(key);
+        if (next === undefined) {
+          const form = wikilinkPathForm(target, oldPath);
+          if (!form) continue;
+          const candidates = wikilinkRenameCandidates(form, newPath, note.extension);
+          // First candidate that actually resolves back to this note wins;
+          // if none does (e.g. every shape is now ambiguous), keep the
+          // preferred shape rather than inventing a third one.
+          next = candidates.find((c) => {
+            const detail = resolveWikilinkDetailed(this.db, c);
+            return detail.resolved && detail.note_id === note.id;
+          }) ?? candidates[0]!;
+          replacement.set(key, next);
+        }
+        if (next !== target) mapping.set(key, next);
       }
+      if (mapping.size === 0) continue;
 
+      const updated = rewriteWikilinkTargets(
+        row.content,
+        (target) => mapping.get(target.toLowerCase()) ?? null,
+      );
       if (updated !== row.content) {
-        noteOps.updateNote(this.db, row.id, { content: updated });
-        syncWikilinks(this.db, row.id, updated);
+        noteOps.updateNote(this.db, sourceId, { content: updated });
+        syncWikilinks(this.db, sourceId, updated);
       }
     }
   }
@@ -706,7 +827,13 @@ export class BunSqliteStore implements Store {
     // comment for why this must run pre-delete and what it deliberately
     // excludes (typed `links`, not just wikilinks).
     requeueInboundWikilinksForDelete(this.db, id);
+    // vault#581 — the deleted note's resolution keys, captured BEFORE the row
+    // goes away and swept AFTER, so a `[[Dup]]` that was ambiguous only
+    // because of THIS note resolves (or, if it was the last candidate,
+    // demotes to an ordinary broken link).
+    const ambiguityKeys = noteResolutionKeys(existing);
     noteOps.deleteNote(this.db, id);
+    refreshAmbiguousLinks(this.db, ambiguityKeys);
     if (existing?.path) this.invalidateConfigCachesForPath(existing.path);
     // Dispatch even when `existing` was null — the caller asked for a
     // deletion, and downstream consumers (e.g. the mirror) reconcile via
@@ -1601,7 +1728,3 @@ export class BunSqliteStore implements Store {
 export const SqliteStore = BunSqliteStore;
 /** @deprecated Renamed to `BunSqliteStore`. */
 export type SqliteStore = BunSqliteStore;
-
-function escapeRegex(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}

package/core/src/txn.test.ts

@@ -12,7 +12,7 @@
 
 import { describe, it, expect } from "bun:test";
 import { Database } from "bun:sqlite";
-import { transaction, transactionAsync, type TxnCapableDb } from "./txn.js";
+import { afterCommit, transaction, transactionAsync, type TxnCapableDb } from "./txn.js";
 
 /** A fake `TxnCapableDb` that records exec calls and can be told to throw on
  *  COMMIT and/or ROLLBACK — lets us drive the failure branches exactly. */
@@ -261,6 +261,38 @@ describe("transactionAsync", () => {
 });
 
 describe("transaction — re-entrancy via SAVEPOINTs (vault#589)", () => {
+  it("does not attempt rollback when an after-commit callback throws", () => {
+    const { db, calls } = fakeDb();
+    expect(() => transaction(db, () => {
+      afterCommit(db, () => { throw new Error("post-commit boom"); });
+    })).toThrow("post-commit boom");
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT"]);
+  });
+
+  it("runs nested after-commit work only after the outer commit", async () => {
+    const db = freshDb();
+    const calls: string[] = [];
+    await transactionAsync(db, async () => {
+      transaction(db, () => {
+        afterCommit(db, () => calls.push("after commit"));
+      });
+      expect(calls).toEqual([]);
+    });
+    expect(calls).toEqual(["after commit"]);
+  });
+
+  it("discards nested after-commit work when the outer transaction rolls back", async () => {
+    const db = freshDb();
+    const calls: string[] = [];
+    await expect(transactionAsync(db, async () => {
+      transaction(db, () => {
+        afterCommit(db, () => calls.push("after commit"));
+      });
+      throw new Error("outer boom");
+    })).rejects.toThrow("outer boom");
+    expect(calls).toEqual([]);
+  });
+
   it("a nested sync transaction uses SAVEPOINT/RELEASE, not a second BEGIN", () => {
     const { db, calls } = fakeDb();
     const out = transaction(db, () => {

package/core/src/txn.ts

@@ -76,6 +76,49 @@ export interface TxnCapableDb {
  */
 const txnDepth = new WeakMap<TxnCapableDb, number>();
 
+/**
+ * Post-commit callbacks, stacked per transaction frame. A nested transaction
+ * merges its callbacks into its parent when its SAVEPOINT is released; only
+ * the outermost successful commit runs them. A rollback discards the frame.
+ */
+const afterCommitFrames = new WeakMap<TxnCapableDb, Array<Array<() => void>>>();
+
+function enterAfterCommitFrame(db: TxnCapableDb): void {
+  const frames = afterCommitFrames.get(db) ?? [];
+  frames.push([]);
+  afterCommitFrames.set(db, frames);
+}
+
+function commitAfterCommitFrame(db: TxnCapableDb): void {
+  const frames = afterCommitFrames.get(db);
+  const callbacks = frames?.pop() ?? [];
+  const parent = frames?.at(-1);
+  if (parent) {
+    parent.push(...callbacks);
+    return;
+  }
+  afterCommitFrames.delete(db);
+  for (const callback of callbacks) callback();
+}
+
+function rollbackAfterCommitFrame(db: TxnCapableDb): void {
+  const frames = afterCommitFrames.get(db);
+  frames?.pop();
+  if (!frames || frames.length === 0) afterCommitFrames.delete(db);
+}
+
+/**
+ * Run a callback only after the surrounding transaction stack commits. When
+ * called outside a transaction it runs immediately. This keeps hooks and
+ * cache invalidation honest for synchronous store writes nested inside an
+ * outer {@link transactionAsync} batch.
+ */
+export function afterCommit(db: TxnCapableDb, callback: () => void): void {
+  const frame = afterCommitFrames.get(db)?.at(-1);
+  if (frame) frame.push(callback);
+  else callback();
+}
+
 /** One entry on the nesting stack: whether this frame owns the outer
  *  `BEGIN … COMMIT`/`ROLLBACK` (outermost) or a `SAVEPOINT` (nested), plus the
  *  depth to restore on exit. */
@@ -153,18 +196,38 @@ function rollbackTxn(db: TxnCapableDb, frame: TxnFrame): void {
  * below unchanged.
  */
 export function transaction<T>(db: TxnCapableDb, fn: () => T): T {
+  enterAfterCommitFrame(db);
   if (typeof db.transactionSync === "function") {
-    return db.transactionSync(fn);
+    let result: T;
+    try {
+      result = db.transactionSync(fn);
+    } catch (err) {
+      rollbackAfterCommitFrame(db);
+      throw err;
+    }
+    commitAfterCommitFrame(db);
+    return result;
+  }
+  let frame: TxnFrame;
+  try {
+    frame = enterTxn(db);
+  } catch (err) {
+    rollbackAfterCommitFrame(db);
+    throw err;
   }
-  const frame = enterTxn(db);
+  let result: T;
   try {
-    const result = fn();
+    result = fn();
     commitTxn(db, frame);
-    return result;
   } catch (err) {
+    rollbackAfterCommitFrame(db);
     rollbackTxn(db, frame);
     throw err;
   }
+  // The SQL transaction is already resolved. A callback error must propagate
+  // without attempting a misleading ROLLBACK after COMMIT.
+  commitAfterCommitFrame(db);
+  return result;
 }
 
 /**
@@ -188,13 +251,23 @@ export function transaction<T>(db: TxnCapableDb, fn: () => T): T {
  * than a second `BEGIN`. See the file header.
  */
 export async function transactionAsync<T>(db: TxnCapableDb, fn: () => Promise<T>): Promise<T> {
-  const frame = enterTxn(db);
+  enterAfterCommitFrame(db);
+  let frame: TxnFrame;
+  try {
+    frame = enterTxn(db);
+  } catch (err) {
+    rollbackAfterCommitFrame(db);
+    throw err;
+  }
+  let result: T;
   try {
-    const result = await fn();
+    result = await fn();
     commitTxn(db, frame);
-    return result;
   } catch (err) {
+    rollbackAfterCommitFrame(db);
     rollbackTxn(db, frame);
     throw err;
   }
+  commitAfterCommitFrame(db);
+  return result;
 }

package/core/src/types.ts

@@ -188,6 +188,17 @@ export interface QueryOpts {
    * had a broken link) — `true` matches nothing, `false` is a no-op.
    */
   hasBrokenLinks?: boolean;
+  /**
+   * Presence filter on the `ambiguous_wikilinks` table (vault#581):
+   * `true` → only notes with at least one AMBIGUOUS outbound link (a
+   * `[[wikilink]]` or structured `links` target that matched ≥2 notes, so
+   * no link was created and none was guessed at); `false` → only notes with
+   * none. Disjoint from `hasBrokenLinks`: a dangling target matched NOTHING,
+   * an ambiguous one matched too much. Safe on a vault where the
+   * `ambiguous_wikilinks` table has never been created (no link has ever
+   * been ambiguous) — `true` matches nothing, `false` is a no-op.
+   */
+  hasAmbiguousLinks?: boolean;
   path?: string;        // exact path match (case-insensitive)
   pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
   /**

package/core/src/vault-projection.ts

@@ -358,7 +358,14 @@ export function projectionToMarkdown(args: {
 
   const lines: string[] = [];
   lines.push(`You are connected to Parachute Vault "${vaultName}".`);
-  if (description && description.trim().length > 0) {
+  // vault#669 / cloud#87 recovery: a non-string description (poisoned
+  // via an unguarded write door) used to throw here (`description.trim
+  // is not a function`) and take down MCP `initialize` — the first
+  // frame, so the connected AI never reached a tool that could repair
+  // it. Skip a non-string the same way we skip null/empty: render the
+  // base brief. The write doors now reject this shape; this is the
+  // already-poisoned reconnect path.
+  if (typeof description === "string" && description.trim().length > 0) {
     lines.push("");
     lines.push(description.trim());
   }