@openparachute/vault 0.7.2-rc.3 → 0.7.2-rc.4

package/core/src/aggregate.test.ts

@@ -214,6 +214,29 @@ describe("aggregateNotes — errors", () => {
     }
   });
 
+  // LB — a `type: "number"` (float) field can NEVER be `indexed: true`
+  // (only integer/boolean are indexable numeric shapes), so it legitimately
+  // never appears in `indexed_fields`. Before the fix, the FIELD_NOT_INDEXED
+  // thrown here carried the SAME generic "declare it via update-tag with
+  // indexed: true" hint every other unindexed field gets — advice that's
+  // impossible to satisfy for `number` specifically, dead-ending an agent
+  // that tries it and hits the SEPARATE "unsupported type ... for indexing"
+  // error. The hint must instead name the real fix: store as an integer.
+  it("FIELD_NOT_INDEXED on a type: \"number\" sum field carries an actionable hint, not the impossible generic \"declare indexed: true\" advice", async () => {
+    await store.upsertTagRecord("expense", { fields: { amount: { type: "number" } } });
+    await store.createNote("a", { tags: ["expense"], metadata: { amount: 9.99 } });
+    try {
+      aggregateNotes(db, { aggregate: { group_by: "tag", op: "sum", field: "amount" } });
+      throw new Error("expected throw");
+    } catch (e: any) {
+      expect(e.code).toBe("FIELD_NOT_INDEXED");
+      expect(e.message).not.toContain("declare it via update-tag with indexed: true");
+      const guidance = `${e.message} ${e.hint ?? ""}`.toLowerCase();
+      expect(guidance).toContain("integer");
+      expect(guidance).toMatch(/float|number|decimal/);
+    }
+  });
+
   it("throws INVALID_QUERY when the sum field is indexed but not numeric (TEXT-backed)", async () => {
     await store.upsertTagRecord("task", {
       fields: {

package/core/src/contract-taxonomy.test.ts

@@ -295,6 +295,28 @@ describe("contract: taxonomy — #552 (flipped from test.todo)", () => {
     expect(cleanReport.summary).toContain("clean");
   });
 
+  // LB — a DIRECT self-parent (`parent_names: [tag]` on tag itself) is a
+  // degenerate one-node cycle: `getTagDescendants` starts its traversal
+  // result at `{tag}`, and the moment it walks the tag's own self-edge it
+  // finds `tag` already `result.has(child)` and skips re-expanding it — so
+  // `descendants` never grows past size 1. `findHierarchyCycles`'s original
+  // gate (`descendants.has(tag) && descendants.size > 1`) requires size>1,
+  // so this exact case reported clean despite being a real cycle. Only
+  // reachable via guard-bypassing data (direct DB write / import) since
+  // `upsertTagRecord` rejects a self-parent at write time (see the "bare
+  // self-parent: also caught" assertion above, which exercises the WRITE
+  // guard — this test exercises the READ-side doctor scan on data that
+  // skipped that guard).
+  it("doctor flags a bare self-parent cycle (X declares parent_names: [X]), which the size>1 gate alone misses", async () => {
+    await store.upsertTagRecord("self-cyc", {});
+    db.prepare("UPDATE tags SET parent_names = ? WHERE name = ?").run(JSON.stringify(["self-cyc"]), "self-cyc");
+
+    const report = await store.doctor();
+    const finding = report.findings.find((f) => f.type === "parent_names_cycle" && f.subject === "self-cyc");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("error");
+  });
+
   it("dead_tag_metadata_reference does not false-positive on a schema-declared enum field whose values coincide with an unrelated live tag (vault#570)", async () => {
     // "archived" is a real, unrelated live tag — coincidentally sharing a
     // name with one of "status"'s declared enum values. Pre-fix, this ONE

package/core/src/query-operators.ts

@@ -101,13 +101,69 @@ function toBinding(field: string, op: string, value: unknown): SQLQueryBindings
   );
 }
 
+/**
+ * Best-effort lookup of a metadata field's declared `type` across every tag
+ * schema — used ONLY to sharpen the {@link requireIndexedField} error hint
+ * below when the field was never indexed. Scans `tags.fields` directly
+ * rather than going through `indexed_fields` (which by construction has no
+ * row for a type that can never BE indexed, e.g. `"number"`) or a
+ * per-note schema resolution (scoped to one note's tags, not "any tag
+ * anywhere"). Only reached on the FIELD_NOT_INDEXED error path — a full
+ * table scan here is fine since it runs once per rejected call, never on a
+ * hot path. Returns the type from the FIRST tag found declaring `field`
+ * (a cross-tag type conflict on the same field name is its own separate
+ * validation elsewhere, not this function's job); `undefined` when no tag
+ * declares this field name, or its `fields` JSON doesn't parse.
+ */
+function findDeclaredFieldType(db: Database, field: string): string | undefined {
+  const rows = db.prepare(
+    `SELECT fields FROM tags WHERE fields IS NOT NULL`,
+  ).all() as { fields: string | null }[];
+  for (const row of rows) {
+    if (!row.fields) continue;
+    try {
+      const parsed: unknown = JSON.parse(row.fields);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      const spec = (parsed as Record<string, unknown>)[field];
+      if (spec === null || typeof spec !== "object" || Array.isArray(spec)) continue;
+      const type = (spec as Record<string, unknown>).type;
+      if (typeof type === "string") return type;
+    } catch {
+      // Malformed `fields` JSON on some other tag — not this lookup's job
+      // to validate; skip and keep scanning.
+    }
+  }
+  return undefined;
+}
+
 /**
  * Look up `field` in `indexed_fields` or throw a loud error suggesting the
  * caller declare it via `update-tag` with `indexed: true`.
+ *
+ * That generic advice is IMPOSSIBLE to satisfy for a field whose schema
+ * declares `type: "number"` (a float) — only `integer`/`boolean` are
+ * indexable numeric shapes (see `indexed-fields.ts`'s `TYPE_MAP`), so
+ * `update-tag` with `indexed: true` on a `number` field itself throws
+ * "unsupported type ... for indexing". An agent that only sees the generic
+ * hint has no escape from that loop (LB — round-4 bug hunt). When the
+ * declared type is `"number"`, swap in a hint that names the actual fix:
+ * store the value as an integer (e.g. cents instead of dollars) and index
+ * THAT field instead.
  */
 export function requireIndexedField(db: Database, field: string): IndexedField {
   const row = getIndexedField(db, field);
   if (!row) {
+    if (findDeclaredFieldType(db, field) === "number") {
+      throw new QueryError(
+        `metadata field "${field}" is not indexed, and can never be: it's declared type: "number" (a float), and only integer/boolean fields are indexable numeric types. "declare indexed: true" will not work on this field.`,
+        "FIELD_NOT_INDEXED",
+        {
+          error_type: "field_not_indexed",
+          field,
+          hint: `"${field}" is a float ("number") field — float fields can't be server-side indexed, filtered with operators, used in order_by, or summed via aggregate. Store the value as an integer instead (e.g. cents rather than dollars) and declare indexed: true on THAT field to enable those.`,
+        },
+      );
+    }
     throw new QueryError(
       `metadata field "${field}" is not indexed. To use operator queries or order_by on this field, declare it via update-tag with indexed: true.`,
       "FIELD_NOT_INDEXED",

package/core/src/store.ts

@@ -15,6 +15,7 @@ import {
   resolveUnresolvedWikilinks,
   resolveOrQueueLink,
   clearQueuedLink,
+  requeueInboundWikilinksForDelete,
 } from "./wikilinks.js";
 import { pathTitle } from "./paths.js";
 import { timestampToMs } from "./cursor.js";
@@ -382,6 +383,13 @@ export class BunSqliteStore implements Store {
     // by design, hooks subscribing to "deleted" receive a DeletedNoteRef,
     // not a Note.
     const existing = noteOps.getNote(this.db, id);
+    // LB6: re-queue inbound wikilink edges BEFORE the FK cascade drops the
+    // `links` rows, so recreating a note at this path/title auto-heals the
+    // edge instead of leaving every referencing note's `[[link]]` dead until
+    // it's individually re-saved. See requeueInboundWikilinksForDelete's doc
+    // comment for why this must run pre-delete and what it deliberately
+    // excludes (typed `links`, not just wikilinks).
+    requeueInboundWikilinksForDelete(this.db, id);
     noteOps.deleteNote(this.db, id);
     if (existing?.path) this.invalidateConfigCachesForPath(existing.path);
     // Dispatch even when `existing` was null — the caller asked for a

package/core/src/tag-hierarchy.ts

@@ -372,6 +372,19 @@ export function computeExpandedTagCounts(
 export function findHierarchyCycles(h: TagHierarchy): string[] {
   const cycles: string[] = [];
   for (const tag of h.childrenOf.keys()) {
+    // Direct self-edge (`parent_names` lists the tag itself) — checked
+    // separately from the descendant-set gate below because
+    // `getTagDescendants` can't see it: its traversal seeds `result` with
+    // `{tag}` and then skips re-expanding any child already present in
+    // `result` (the visited-set that makes runtime traversal cycle-safe) —
+    // so a bare `X -> X` edge never grows `descendants` past size 1, and
+    // `descendants.size > 1` alone silently reports it clean. Only
+    // reachable via guard-bypassing data (a direct DB write, or an import
+    // that skips `upsertTagRecord`'s write-time cycle guard).
+    if (h.childrenOf.get(tag)?.has(tag)) {
+      cycles.push(tag);
+      continue;
+    }
     const descendants = getTagDescendants(h, tag);
     if (descendants.has(tag) && descendants.size > 1) {
       // tag reaches itself through a non-trivial path

package/core/src/wikilinks.test.ts

@@ -10,7 +10,10 @@ import {
   listUnresolvedWikilinks,
   getContentWikilinkWarnings,
   resolveOrQueueLink,
+  requeueInboundWikilinksForDelete,
+  getUnresolvedLinksForNote,
 } from "./wikilinks.js";
+import { findPath } from "./links.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -480,6 +483,178 @@ describe("path-based resolution", async () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// requeueInboundWikilinksForDelete (LB6) — a deleted note's inbound wikilink
+// edges must re-queue so recreating a note at the same path/title heals
+// them, instead of staying dead until the SOURCE note is individually
+// re-saved.
+// ---------------------------------------------------------------------------
+
+describe("delete → recreate re-resolves inbound wikilinks (LB6)", () => {
+  it("A [[Foo]] survives Foo's delete-then-recreate without touching A", async () => {
+    const a = await store.createNote("Link to [[Foo]]", { path: "A" });
+
+    // Foo doesn't exist yet — the link is queued, not yet live.
+    expect(await store.getLinks(a.id, { direction: "outbound" })).toHaveLength(0);
+    const pendingBefore = db.prepare(
+      "SELECT target_path FROM unresolved_wikilinks WHERE source_id = ?",
+    ).all(a.id) as { target_path: string }[];
+    expect(pendingBefore.map((r) => r.target_path)).toEqual(["Foo"]);
+
+    // Create Foo — the wikilink resolves and the edge + backlink exist.
+    const foo1 = await store.createNote("First Foo", { path: "Foo" });
+    let links = await store.getLinks(a.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.targetId).toBe(foo1.id);
+    expect(findPath(db, a.id, foo1.id)).not.toBeNull();
+    const backlinks = await store.getLinks(foo1.id, { direction: "inbound" });
+    expect(backlinks.some((l) => l.sourceId === a.id)).toBe(true);
+
+    // Delete Foo. Without the LB6 fix, `unresolved_wikilinks` stays empty —
+    // nothing pending — even though A's `[[Foo]]` text is untouched.
+    await store.deleteNote(foo1.id);
+    expect(await store.getLinks(a.id, { direction: "outbound" })).toHaveLength(0);
+    const pendingAfterDelete = db.prepare(
+      "SELECT target_path, relationship FROM unresolved_wikilinks WHERE source_id = ?",
+    ).all(a.id) as { target_path: string; relationship: string }[];
+    expect(pendingAfterDelete).toEqual([{ target_path: "Foo", relationship: "wikilink" }]);
+
+    // Recreate Foo (new note, new id — same path). A was never re-saved.
+    const foo2 = await store.createNote("Second Foo", { path: "Foo" });
+
+    // The A -> Foo edge is back, pointed at the NEW Foo, and find-path sees it.
+    links = await store.getLinks(a.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.targetId).toBe(foo2.id);
+    expect(links[0]!.relationship).toBe("wikilink");
+    expect(findPath(db, a.id, foo2.id)).not.toBeNull();
+
+    // A's content was never touched.
+    const reread = await store.getNote(a.id);
+    expect(reread!.content).toBe("Link to [[Foo]]");
+
+    // The pending row is consumed on resolution.
+    const pendingAfterRecreate = db.prepare(
+      "SELECT * FROM unresolved_wikilinks WHERE source_id = ?",
+    ).all(a.id);
+    expect(pendingAfterRecreate).toHaveLength(0);
+  });
+
+  it("only re-queues wikilink-relationship inbound edges, not explicit typed links", async () => {
+    const source = await store.createNote("A", { id: "src", path: "Src" });
+    const target = await store.createNote("B", { id: "tgt", path: "Tgt" });
+    await store.createLink("src", "tgt", "related-to"); // hand-authored typed link, not a wikilink
+
+    requeueInboundWikilinksForDelete(db, target.id);
+
+    // getUnresolvedLinksForNote tolerates the table not existing at all
+    // (no wikilink was ever parsed in this test) — a raw SELECT would throw.
+    expect(getUnresolvedLinksForNote(db, source.id)).toHaveLength(0);
+  });
+
+  it("re-queues via basename resolution, not just exact path, and recovers on recreate at the same path", async () => {
+    // Target lives at a nested path; source links via the bare basename —
+    // resolved through resolveWikilink's basename fallback (rule #3), not
+    // an exact path match.
+    const target = await store.createNote("# Weekly Review\n\nBody.", { path: "Projects/Weekly Review" });
+    const source = await store.createNote("See [[Weekly Review]]", { path: "A" });
+    expect(await store.getLinks(source.id, { direction: "outbound" })).toHaveLength(1);
+
+    await store.deleteNote(target.id);
+
+    const pending = db.prepare(
+      "SELECT target_path FROM unresolved_wikilinks WHERE source_id = ?",
+    ).all(source.id) as { target_path: string }[];
+    // The re-queued key is the RAW bracket text ("Weekly Review"), not the
+    // deleted note's full path — that's what the basename-fallback lazy
+    // resolver (`resolveUnresolvedWikilinks`'s `? LIKE '%/' || target_path`
+    // suffix match) actually matches on.
+    expect(pending.map((r) => r.target_path)).toEqual(["Weekly Review"]);
+
+    // Recreate at the SAME nested path — the suffix match backfills it.
+    const target2 = await store.createNote("# Weekly Review v2\n\nBody.", { path: "Projects/Weekly Review" });
+    const links = await store.getLinks(source.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.targetId).toBe(target2.id);
+  });
+
+  // BLOCKER (Fable review) — the delete→recreate re-heal must cover links
+  // that resolved via the H1-TITLE fallback and the explicit-EXTENSION form,
+  // not just path/basename. The re-queued row's target string is the raw
+  // bracket text (e.g. "John Doe" / "budget.csv"), which the OLD sweep
+  // matched against the new note by PATH TEXT ONLY — so a title- or
+  // extension-resolved link stayed queued (0 links rebuilt) forever. The
+  // sweep now runs each candidate through the SAME resolver write-time uses,
+  // so deferred resolution finally matches write-time on all four legs.
+  it("re-heals a TITLE-fallback link AND an EXTENSION-form link on delete→recreate at the same path+H1", async () => {
+    // A resolves to `people/jdoe` only via its H1 title "John Doe".
+    // B resolves to `budget` (ext csv) only via the explicit [[budget.csv]]
+    // form (the extension leg is exact-path, so `budget` lives at path
+    // "budget", disambiguating it from a same-named `.md` note).
+    const person = await store.createNote("# John Doe\n\nBio.", { path: "people/jdoe" });
+    const budget = await store.createNote("month,total\n2026-01,9000", { path: "budget", extension: "csv" });
+    const a = await store.createNote("met [[John Doe]] today", { path: "A" });
+    const b = await store.createNote("see [[budget.csv]]", { path: "B" });
+
+    // Both links live at write time (title fallback + extension form).
+    expect((await store.getLinks(a.id, { direction: "outbound" }))[0]?.targetId).toBe(person.id);
+    expect((await store.getLinks(b.id, { direction: "outbound" }))[0]?.targetId).toBe(budget.id);
+
+    await store.deleteNote(person.id);
+    await store.deleteNote(budget.id);
+
+    // Both re-queued with their raw bracket text — NOT the deleted notes' paths.
+    const pendingA = db.prepare("SELECT target_path FROM unresolved_wikilinks WHERE source_id = ?").all(a.id) as { target_path: string }[];
+    const pendingB = db.prepare("SELECT target_path FROM unresolved_wikilinks WHERE source_id = ?").all(b.id) as { target_path: string }[];
+    expect(pendingA.map((r) => r.target_path)).toEqual(["John Doe"]);
+    expect(pendingB.map((r) => r.target_path)).toEqual(["budget.csv"]);
+    expect(await store.getLinks(a.id, { direction: "outbound" })).toHaveLength(0);
+    expect(await store.getLinks(b.id, { direction: "outbound" })).toHaveLength(0);
+
+    // Recreate each at the SAME path + H1 (new note, new id). Neither A nor B
+    // is re-saved — only the deferred sweep can rebuild these edges.
+    const person2 = await store.createNote("# John Doe\n\nBio v2.", { path: "people/jdoe" });
+    const budget2 = await store.createNote("month,total\n2026-02,9500", { path: "budget", extension: "csv" });
+
+    // BOTH re-heal (RED before the sweep completion — title/ext legs missing).
+    const aLinks = await store.getLinks(a.id, { direction: "outbound" });
+    const bLinks = await store.getLinks(b.id, { direction: "outbound" });
+    expect(aLinks).toHaveLength(1);
+    expect(aLinks[0]!.targetId).toBe(person2.id);
+    expect(findPath(db, a.id, person2.id)).not.toBeNull();
+    expect(bLinks).toHaveLength(1);
+    expect(bLinks[0]!.targetId).toBe(budget2.id);
+
+    // Pending rows consumed on resolution.
+    expect(getUnresolvedLinksForNote(db, a.id)).toHaveLength(0);
+    expect(getUnresolvedLinksForNote(db, b.id)).toHaveLength(0);
+  });
+
+  // The completed sweep must NOT mis-resolve an AMBIGUOUS target — matching
+  // write-time's "don't guess" contract. A pending [[John Doe]] is swept when
+  // a same-titled note is created; if TWO notes already share that H1 by the
+  // time the sweep verifies, the resolver returns ambiguous and the row stays
+  // queued rather than the old path-only sweep's "link to whoever showed up."
+  // (Reached via a pathless first note — the sweep is path-gated, so it never
+  // fired to consume the row when only ONE John Doe existed.)
+  it("does not re-heal a title link when the target is ambiguous (two notes share the H1)", async () => {
+    const a = await store.createNote("met [[John Doe]]", { path: "A" });
+    expect(getUnresolvedLinksForNote(db, a.id).map((l) => l.target)).toEqual(["John Doe"]); // queued, no John Doe yet
+
+    // A PATHLESS note carrying the H1 — createNote's sweep is path-gated, so
+    // it does NOT fire here; A's pending row survives with one John Doe extant.
+    await store.createNote("# John Doe\n\nfirst.");
+    expect(getUnresolvedLinksForNote(db, a.id).map((l) => l.target)).toEqual(["John Doe"]); // still queued
+
+    // A SECOND note with the same H1, WITH a path → the sweep fires. Now two
+    // notes carry "John Doe" → resolveWikilinkDetailed is ambiguous → the row
+    // is left queued, nothing linked.
+    await store.createNote("# John Doe\n\nsecond.", { path: "people/jd" });
+    expect(await store.getLinks(a.id, { direction: "outbound" })).toHaveLength(0);
+    expect(getUnresolvedLinksForNote(db, a.id).map((l) => l.target)).toEqual(["John Doe"]);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // unresolved_wikilinks relationship-column migration — atomicity (vault#555
 // wire+generalist must-fix; W7's migrateToV25-interruption lesson applied).

package/core/src/wikilinks.ts

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
 import type { Note } from "./types.js";
 import * as linkOps from "./links.js";
-import { getNote, findNotesByTitle } from "./notes.js";
+import { getNote, findNotesByTitle, extractH1Title } from "./notes.js";
 import { chunkForInClause } from "./sql-in.js";
 import { transaction } from "./txn.js";
 import type { QueryWarning } from "./query-warnings.js";
@@ -619,11 +619,32 @@ function syncUnresolvedWikilinks(
 
 /**
  * Try to resolve pending wikilinks AND pending structured-link forward-refs
- * (vault#555) that point to a given path. Called when a note is created or
+ * (vault#555) that point to a given note. Called when a note is created or
  * its path changes. Each pending row materializes with ITS OWN relationship
  * (a structured link queued via {@link queueUnresolvedLink} backfills with
  * the caller's original relationship, not "wikilink").
  *
+ * Deferred resolution now covers all four legs of
+ * {@link resolveWikilinkDetailed}: exact path, basename, H1 title, and the
+ * explicit `path.ext` form. (Caveat: the candidate pre-filter below matches the
+ * title/ext legs via SQL `COLLATE NOCASE`, which case-folds ASCII only — a
+ * non-ASCII title differing from the target only in letter case is missed at
+ * the candidate stage and re-heals on the source's next save instead. Rare;
+ * tracked as a follow-up.) Before this, the sweep matched a pending row to
+ * the new note by PATH TEXT ONLY (`target_path = path OR path LIKE
+ * '%/'||target_path`) — so a `[[John Doe]]` that resolved at write time via
+ * the H1-title fallback (its note's displayed title differs from its path,
+ * e.g. `people/jdoe`), or a `[[Foo.csv]]` that resolved via the extension
+ * leg, silently never re-healed on a delete→recreate (the exact LB6 gap) and
+ * more broadly never backfilled when the target note was created AFTER the
+ * referencing note. Each candidate pending row is now VERIFIED through
+ * `resolveWikilinkDetailed` against the current DB — a row is healed only
+ * when its target string actually resolves to THIS note. An AMBIGUOUS target
+ * (≥2 notes now share the path/title) resolves to neither and stays queued,
+ * identical to write-time's "don't guess" contract — this also closes the
+ * pre-existing asymmetry where the path-only sweep would link an ambiguous
+ * `[[Foo]]` to whichever colliding note happened to be created.
+ *
  * Returns the number of links resolved.
  */
 export function resolveUnresolvedWikilinks(
@@ -632,13 +653,32 @@ export function resolveUnresolvedWikilinks(
   noteId: string,
 ): number {
   ensureRelationshipColumn(db);
-  let rows: { source_id: string; relationship: string }[];
+
+  // The newly-created / newly-repathed note supplies the two resolution keys
+  // the pending row's `target_path` (a bare path/basename string) can't carry
+  // on its own: the note's H1 title (title-fallback leg) and its extension
+  // (explicit `path.ext` leg). `getNote` is one indexed PK lookup; the title
+  // is parsed from content in JS (no separate query).
+  const note = getNote(db, noteId);
+  const h1Title = note?.content ? extractH1Title(note.content) : null;
+  const pathDotExt = note?.extension ? `${notePath}.${note.extension}` : null;
+
+  let rows: { source_id: string; target_path: string; relationship: string }[];
   try {
+    // Candidate pre-filter: every pending row whose `target_path` COULD
+    // resolve to this note under any resolveWikilinkDetailed leg — exact
+    // path, basename (target is the last path segment), H1 title, or the
+    // `path.ext` form. A `null` bind (no H1 heading / no extension) makes its
+    // clause never match (`target_path = NULL` is NULL, i.e. falsy in SQL).
+    // The verify step below is what enforces correctness; this clause only
+    // BOUNDS how many rows reach the (title-fallback-scanning) resolver.
     rows = db.prepare(`
-      SELECT source_id, relationship FROM unresolved_wikilinks
+      SELECT source_id, target_path, relationship FROM unresolved_wikilinks
       WHERE target_path = ? COLLATE NOCASE
          OR ? LIKE '%/' || target_path
-    `).all(notePath, notePath) as { source_id: string; relationship: string }[];
+         OR target_path = ? COLLATE NOCASE
+         OR target_path = ? COLLATE NOCASE
+    `).all(notePath, notePath, h1Title, pathDotExt) as typeof rows;
   } catch {
     return 0; // Table doesn't exist
   }
@@ -649,16 +689,24 @@ export function resolveUnresolvedWikilinks(
   for (const row of rows) {
     if (row.source_id === noteId) continue; // Skip self-links
 
+    // Verify against the SAME resolver write-time uses, so deferred
+    // resolution can't diverge from it: heal a pending row ONLY when its
+    // target string actually resolves to THIS note now. A miss or an
+    // ambiguous result leaves the row queued (surfaced as a visible broken
+    // link, and re-tried on the next matching note create).
+    const detail = resolveWikilinkDetailed(db, row.target_path);
+    if (!detail.resolved || detail.note_id !== noteId) continue;
+
     const relationship = row.relationship || WIKILINK_REL;
     linkOps.createLink(db, row.source_id, noteId, relationship);
     resolved++;
 
-    // Remove the unresolved entry (this exact relationship only — a
-    // source may have BOTH a wikilink and a structured-link forward-ref
-    // pending against the same target_path).
+    // Remove exactly this pending row — a source may have BOTH a wikilink and
+    // a structured-link forward-ref pending against the same target_path
+    // (distinct relationships), so scope the delete to all three PK columns.
     db.prepare(
-      "DELETE FROM unresolved_wikilinks WHERE source_id = ? AND relationship = ? AND (target_path = ? COLLATE NOCASE OR ? LIKE '%/' || target_path)",
-    ).run(row.source_id, relationship, notePath, notePath);
+      "DELETE FROM unresolved_wikilinks WHERE source_id = ? AND target_path = ? AND relationship = ?",
+    ).run(row.source_id, row.target_path, relationship);
   }
 
   return resolved;
@@ -840,3 +888,96 @@ export function getContentWikilinkWarnings(
 
   return warnings;
 }
+
+// ---------------------------------------------------------------------------
+// Delete-time re-queue (LB6) — a deleted note's INBOUND wikilink edges must
+// come back to life if a note is later recreated at the same path/title.
+// ---------------------------------------------------------------------------
+
+/**
+ * Before a note is deleted, re-queue every INBOUND `wikilink`-relationship
+ * edge pointing at it into `unresolved_wikilinks`, so that recreating a note
+ * matching the original `[[target]]` text (same path, basename, H1 title, or
+ * `path.ext` form — anything {@link resolveWikilinkDetailed} would have
+ * matched) auto-heals the edge via {@link resolveUnresolvedWikilinks} — which
+ * now verifies each pending row through that same resolver — exactly as if
+ * the link had never resolved in the first place.
+ *
+ * Without this, `deleteNote`'s `DELETE FROM notes` cascades the `links` row
+ * away (FK `ON DELETE CASCADE`) but leaves `unresolved_wikilinks` untouched —
+ * a note recreated at the deleted note's path never gets linked back to,
+ * because nothing is pending resolution for it. Only a re-save of the
+ * SOURCE note (which reparses its own content from scratch) would recover
+ * it; a fresh `[[Foo]]` reference elsewhere would work, but the ORIGINAL
+ * source note's edge stayed dead despite its unchanged `[[Foo]]` text.
+ *
+ * MUST be called BEFORE the note row is deleted — it needs both the `links`
+ * row (about to cascade away) and, per source, the CURRENT content (to
+ * recover the raw `[[target]]` text the resolver actually matched on: a
+ * resolved link's row retains the target NOTE id, not the original bracket
+ * text, and title-fallback / basename resolution mean that text can differ
+ * from the deleted note's own path).
+ *
+ * Scope: only `relationship = "wikilink"` inbound edges are re-queued.
+ * Explicit typed `links` (structured `links: [{target, relationship}]`
+ * entries, vault#555) are left alone — those are hand-authored associations
+ * the caller owns, not content-derived, so silently resurrecting them as a
+ * forward-ref on an unrelated future note would be surprising. A source
+ * that links to itself is never queued (wikilinks never create self-links,
+ * so no such inbound row can exist) and is skipped defensively anyway.
+ */
+export function requeueInboundWikilinksForDelete(db: Database, noteId: string): void {
+  let inbound: { source_id: string }[];
+  try {
+    inbound = db.prepare(
+      "SELECT DISTINCT source_id FROM links WHERE target_id = ? AND relationship = ?",
+    ).all(noteId, WIKILINK_REL) as { source_id: string }[];
+  } catch {
+    return; // links table missing (shouldn't happen post-schema-init, but never block a delete on this)
+  }
+  if (inbound.length === 0) return;
+
+  // Cheap string pre-filter (perf): a wikilink can only have resolved to the
+  // note being deleted if its raw target text equals one of THIS note's own
+  // resolution keys — its path, basename, H1 title, or `path.ext` form (the
+  // four legs {@link resolveWikilinkDetailed} matches on; every leg produces a
+  // target string equal to one of these, so the key set is a complete
+  // necessary-condition superset). Computed ONCE, then each source wikilink's
+  // target is gated on set membership BEFORE the expensive resolver call
+  // (whose title-fallback leg scans every note's content). Without this, a hub
+  // note with hundreds of inbound sources would fire hundreds of full-vault
+  // scans in one delete. The resolver still CONFIRMS each survivor — the
+  // pre-filter narrows, it doesn't decide.
+  const deleted = getNote(db, noteId);
+  const keys = new Set<string>();
+  const addKey = (s: string | null | undefined): void => {
+    const k = s?.trim().toLowerCase();
+    if (k) keys.add(k);
+  };
+  if (deleted?.path) {
+    addKey(deleted.path);
+    const slash = deleted.path.lastIndexOf("/");
+    addKey(slash >= 0 ? deleted.path.slice(slash + 1) : deleted.path); // basename
+    if (deleted.extension) addKey(`${deleted.path}.${deleted.extension}`);
+  }
+  if (deleted?.content) addKey(extractH1Title(deleted.content));
+  if (keys.size === 0) return; // no key any wikilink could have matched on
+
+  for (const { source_id } of inbound) {
+    if (source_id === noteId) continue; // defensive — wikilinks never self-link
+
+    const source = getNote(db, source_id);
+    if (!source || !source.content) continue;
+
+    const targetMap = dedupeWikilinkTargets(parseWikilinks(source.content));
+    for (const [, wl] of targetMap) {
+      // Skip the resolver unless this target text could match the deleted
+      // note by one of its resolution keys (necessary-condition pre-filter).
+      if (!keys.has(wl.target.trim().toLowerCase())) continue;
+      const detail = resolveWikilinkDetailed(db, wl.target);
+      if (detail.resolved && detail.note_id === noteId) {
+        queueUnresolvedLink(db, source_id, wl.target, WIKILINK_REL);
+      }
+    }
+  }
+}

package/package.json

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

package/src/routes.ts

@@ -178,6 +178,105 @@ function jsonWithWarnings(data: unknown, warnings: QueryWarning[], status = 200)
   return res;
 }
 
+/**
+ * Sane upper bound on a mutating-route JSON request body (LB7c). Without
+ * this, a giant field (most commonly a note's `content`) sails straight
+ * through `req.json()` and into wikilink parsing + the store write with no
+ * gate at all — reproduced at 50MB `content` -> 201 Created, RSS 92MB ->
+ * 663MB (memory-DoS via a single request). 10MB is generous for
+ * hand-authored or transcribed note content (multiple hours of dense
+ * transcript) while bounding the failure mode. Mirrors `/upload`'s
+ * `MAX_UPLOAD_BYTES` file-size gate for the JSON-body transport.
+ */
+export const MAX_JSON_BODY_BYTES = 10 * 1024 * 1024;
+
+function payloadTooLargeResponse(bytes: number): Response {
+  return json(
+    {
+      error: `Request body too large (${(bytes / 1024 / 1024).toFixed(1)}MB). Max: ${Math.round(MAX_JSON_BODY_BYTES / 1024 / 1024)}MB`,
+      error_type: "payload_too_large",
+      limit: MAX_JSON_BODY_BYTES,
+      got: bytes,
+    },
+    413,
+  );
+}
+
+/**
+ * Single choke point for every mutating route that reads a JSON request
+ * body (LB7 — door asymmetry fix). Three failure modes, all returning a
+ * clean 400/413 instead of falling through to server.ts's generic
+ * `{ error: "Internal server error" }` 500-with-no-`error_type` (LB7a), or
+ * silently succeeding on a wrong-shape body (LB7b — `null` used to throw a
+ * TypeError deep in the handler; `42`/`[]` used to sail through property
+ * access as `undefined` and create a blank note/no-op update):
+ *
+ *   1. **Oversize** — `Content-Length` over {@link MAX_JSON_BODY_BYTES}
+ *      rejects BEFORE `req.json()` even buffers/parses the body (the cheap
+ *      path). When the header is absent or understates the true size
+ *      (chunked transfer, a lying client), the parsed body's own
+ *      JSON-serialized size is checked as a backstop — one extra parse, but
+ *      still cheaper than letting the oversized value reach the store and
+ *      get re-processed (wikilink scan, indexing, etc.).
+ *   2. **Malformed JSON** — `req.json()` rejects; caught here rather than
+ *      propagating to the top-level handler.
+ *   3. **Wrong shape** — valid JSON, but not a plain object (`null`, an
+ *      array, or a bare primitive). Gated by `requireObject` (default
+ *      `true`); every current caller wants this — the parameter exists so a
+ *      future non-object-bodied route doesn't have to bypass the helper
+ *      entirely to opt out.
+ *
+ * Callers: check `.ok` and return `.response` on failure; `.body` is the
+ * parsed JSON value (still `any` — this validates SHAPE, not the specific
+ * fields a given route requires, which callers keep checking themselves).
+ */
+async function parseJsonBody(
+  req: Request,
+  opts?: { requireObject?: boolean },
+): Promise<{ ok: true; body: any } | { ok: false; response: Response }> {
+  const contentLengthHeader = req.headers.get("content-length");
+  if (contentLengthHeader) {
+    const declaredBytes = Number(contentLengthHeader);
+    if (Number.isFinite(declaredBytes) && declaredBytes > MAX_JSON_BODY_BYTES) {
+      return { ok: false, response: payloadTooLargeResponse(declaredBytes) };
+    }
+  }
+
+  const INVALID_JSON = Symbol("invalid-json");
+  const parsed = await req.json().catch(() => INVALID_JSON);
+  if (parsed === INVALID_JSON) {
+    return { ok: false, response: json({ error: "Invalid JSON body", error_type: "invalid_json" }, 400) };
+  }
+
+  if (!contentLengthHeader) {
+    const approxBytes = Buffer.byteLength(JSON.stringify(parsed) ?? "", "utf8");
+    if (approxBytes > MAX_JSON_BODY_BYTES) {
+      return { ok: false, response: payloadTooLargeResponse(approxBytes) };
+    }
+  }
+
+  const requireObject = opts?.requireObject ?? true;
+  if (requireObject && (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))) {
+    // The body PARSED as JSON but is the wrong SHAPE (a primitive/array/null,
+    // not an object) — a `invalid_request` per the taxonomy (parallel to
+    // `/tags/merge`'s `sources`/`target` shape errors). `invalid_json` is
+    // reserved for a genuine parse failure (the branch above).
+    return {
+      ok: false,
+      response: json(
+        {
+          error: "Request body must be a JSON object",
+          error_type: "invalid_request",
+          hint: `expected a JSON object body — got ${parsed === null ? "null" : Array.isArray(parsed) ? "an array" : typeof parsed}`,
+        },
+        400,
+      ),
+    };
+  }
+
+  return { ok: true, body: parsed };
+}
+
 /**
  * REST-only `removed_param` warning (vault#550) — the flat `date_field` /
  * `date_from` / `date_to` query-string params were removed at 0.6.4
@@ -1647,8 +1746,39 @@ async function handleNotesInner(
 
     // POST /notes — create (single or batch)
     if (method === "POST") {
-      const body = await req.json() as any;
+      const parsedBody = await parseJsonBody(req);
+      if (!parsedBody.ok) return parsedBody.response;
+      const body = parsedBody.body as any;
+      // `notes` (when present) must actually be an array — otherwise
+      // `items` below iterates whatever `body.notes` happens to be (e.g. a
+      // STRING iterates as one-character items), silently creating a batch
+      // of blank notes (LB7b).
+      if (body.notes !== undefined && !Array.isArray(body.notes)) {
+        return json(
+          {
+            error: "notes must be an array",
+            error_type: "invalid_request",
+            field: "notes",
+            hint: 'pass { "notes": [...] } for a batch, or a single note object with no `notes` key',
+          },
+          400,
+        );
+      }
       const items: any[] = body.notes ?? [body];
+      // Every batch item must itself be a plain object — a primitive/array
+      // entry would otherwise read as an all-`undefined` note (LB7b).
+      for (const item of items) {
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+          return json(
+            {
+              error: "each note must be a JSON object",
+              error_type: "invalid_request",
+              hint: 'each entry in "notes" (or the top-level body, for a single-note POST) must be an object, e.g. {"content": "..."}',
+            },
+            400,
+          );
+        }
+      }
 
       // Batch cap (#213): refuse oversized batches before doing any work. 500
       // is the cap (Benjamin's number) — tighter blast radius than 1000 for
@@ -2052,7 +2182,9 @@ async function handleNotesInner(
       if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
         return json({ error: "Not found", error_type: "not_found" }, 404);
       }
-      const body = await req.json() as { path: string; mimeType: string; transcribe?: boolean };
+      const parsedBody = await parseJsonBody(req);
+      if (!parsedBody.ok) return parsedBody.response;
+      const body = parsedBody.body as { path: string; mimeType: string; transcribe?: boolean };
       if (!body.path || !body.mimeType) {
         return json(
           { error: "path and mimeType are required", error_type: "missing_required_field", hint: "pass both `path` and `mimeType`" },
@@ -2235,7 +2367,9 @@ async function handleNotesInner(
       // Body is parsed up front so the `if_missing: "create"` branch
       // (vault#309) can fire when the note doesn't exist. Pre-#309
       // shape parsed the body only after the not-found check.
-      const body = await req.json() as any;
+      const parsedBody = await parseJsonBody(req);
+      if (!parsedBody.ok) return parsedBody.response;
+      const body = parsedBody.body as any;
       const note = await resolveNote(store, idOrPath);
       if (!note) {
         // vault#309 — `if_missing: "create"` turns this PATCH into a
@@ -3100,7 +3234,9 @@ export async function handleTags(
     if (tagScope.allowed && !tagScope.allowed.has(putTagName)) {
       return tagScopeForbidden(tagScope.raw ?? []);
     }
-    const body = (await req.json()) as {
+    const parsedBody = await parseJsonBody(req);
+    if (!parsedBody.ok) return parsedBody.response;
+    const body = parsedBody.body as {
       description?: string | null;
       fields?: Record<string, unknown> | null;
       relationships?: Record<string, unknown> | null;
@@ -3514,7 +3650,9 @@ export async function handleVault(
   }
 
   if (req.method === "PATCH") {
-    const body = await req.json() as {
+    const parsedBody = await parseJsonBody(req);
+    if (!parsedBody.ok) return parsedBody.response;
+    const body = parsedBody.body as {
       description?: string;
       config?: { audio_retention?: string; auto_transcribe?: { enabled?: unknown } };
     };

package/src/vault.test.ts

@@ -11,7 +11,7 @@ import { BunStore } from "./vault-store.ts";
 import { generateMcpTools } from "../core/src/mcp.ts";
 import { getLinksHydrated } from "../core/src/links.ts";
 import { buildVaultProjection } from "../core/src/vault-projection.ts";
-import { handleNotes, handleTags, handleFindPath, handleVault, handleUnresolvedWikilinks } from "./routes.ts";
+import { handleNotes, handleTags, handleFindPath, handleVault, handleUnresolvedWikilinks, MAX_JSON_BODY_BYTES } from "./routes.ts";
 import { expandTokenTagScope } from "./tag-scope.ts";
 import type { TagScopeCtx } from "./routes.ts";
 import { extractApiKey } from "./auth.ts";
@@ -4198,6 +4198,144 @@ describe("HTTP /notes", async () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// REST transport hardening — malformed/wrong-shape/oversize JSON bodies
+// (LB7). Before the fix: malformed JSON on POST /notes, POST
+// /notes/:id/attachments, and PUT /tags/:name threw past the handler into
+// server.ts's generic top-level catch — a 500 with no `error_type` (LB7a),
+// unlike the already-hardened /tags/merge and /tags/:name/rename routes,
+// which returned a clean 400 `invalid_json`. A syntactically-valid but
+// wrong-shape body (`null`, `42`, `[]`) either threw a TypeError deep in the
+// handler or sailed through property access as `undefined`, silently
+// creating a blank note / no-op update (LB7b). And nothing capped request
+// body size, so an oversized `content` field reached the store unbounded
+// (LB7c). Every assertion here MUST fail without the fix (parseJsonBody).
+// ---------------------------------------------------------------------------
+describe("REST transport hardening — malformed/wrong-shape/oversize JSON bodies (LB7)", async () => {
+  /** Raw (non-JSON.stringify'd) request body — for malformed-JSON cases mkReq can't express. */
+  function mkRawReq(method: string, path: string, rawBody: string): Request {
+    return new Request(`${BASE}${path}`, {
+      method,
+      body: rawBody,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  describe("malformed JSON -> clean 400 invalid_json, not a 500 (LB7a)", () => {
+    test("POST /notes", async () => {
+      const res = await handleNotes(mkRawReq("POST", "/notes", "{not valid json"), store, "");
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_json");
+    });
+
+    test("POST /notes/:id/attachments", async () => {
+      await store.createNote("x", { id: "att-malformed" });
+      const res = await handleNotes(
+        mkRawReq("POST", "/notes/att-malformed/attachments", "{not valid json"),
+        store,
+        "/att-malformed/attachments",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_json");
+    });
+
+    test("PATCH /notes/:idOrPath", async () => {
+      await store.createNote("x", { id: "patch-malformed" });
+      const res = await handleNotes(
+        mkRawReq("PATCH", "/notes/patch-malformed", "{not valid json"),
+        store,
+        "/patch-malformed",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_json");
+    });
+
+    test("PUT /tags/:name — parity with the already-hardened /tags/merge shape", async () => {
+      const res = await handleTags(mkRawReq("PUT", "/tags/malformed", "{not valid json"), store, "/malformed");
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_json");
+    });
+
+    test("PATCH /vault-info", async () => {
+      const cfg = { name: "default" } as { name: string };
+      const res = await handleVault(mkRawReq("PATCH", "/vault", "{not valid json"), store, cfg as any);
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_json");
+    });
+  });
+
+  // Wrong-SHAPE bodies parse fine as JSON but aren't the object a route
+  // expects — the taxonomy calls that `invalid_request` (parallel to
+  // /tags/merge's sources/target shape errors), NOT `invalid_json` (which is
+  // reserved for a genuine parse failure, asserted in the LB7a block above).
+  describe("wrong-shape (but syntactically valid) JSON body -> 400 invalid_request, not 500 or a silent blank write (LB7b)", () => {
+    test("POST /notes with a `null` body -> 400 invalid_request, not a 500 TypeError", async () => {
+      const res = await handleNotes(mkReq("POST", "/notes", null), store, "");
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_request");
+    });
+
+    test("POST /notes with a bare number body -> 400 invalid_request, not a silently-created blank note", async () => {
+      const res = await handleNotes(mkReq("POST", "/notes", 42), store, "");
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_request");
+      const after = await (await handleNotes(mkReq("GET", "/notes"), store, "")).json() as any[];
+      expect(after).toHaveLength(0); // no blank note landed
+    });
+
+    test("POST /notes with a bare array body -> 400 invalid_request, not a silently-created blank note", async () => {
+      const res = await handleNotes(mkReq("POST", "/notes", []), store, "");
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_request");
+      const after = await (await handleNotes(mkReq("GET", "/notes"), store, "")).json() as any[];
+      expect(after).toHaveLength(0);
+    });
+
+    test("POST /notes with notes: \"not-an-array\" -> 400 invalid_request, not per-character blank notes", async () => {
+      const res = await handleNotes(mkReq("POST", "/notes", { notes: "oops" }), store, "");
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_request");
+      expect(body.field).toBe("notes");
+      const after = await (await handleNotes(mkReq("GET", "/notes"), store, "")).json() as any[];
+      expect(after).toHaveLength(0);
+    });
+
+    test("POST /notes with a non-object item inside notes[] -> 400 invalid_request", async () => {
+      const res = await handleNotes(
+        mkReq("POST", "/notes", { notes: [{ content: "ok", path: "ok-one" }, 42] }),
+        store,
+        "",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("invalid_request");
+      const after = await (await handleNotes(mkReq("GET", "/notes"), store, "")).json() as any[];
+      expect(after).toHaveLength(0); // the whole batch is rejected, not a partial write
+    });
+  });
+
+  describe("oversize request body -> 413, not an unbounded write (LB7c)", () => {
+    test("POST /notes with an oversized content field is rejected", async () => {
+      const huge = "x".repeat(MAX_JSON_BODY_BYTES + 1024);
+      const res = await handleNotes(mkReq("POST", "/notes", { content: huge, path: "huge-note" }), store, "");
+      expect(res.status).toBe(413);
+      const body = await res.json() as any;
+      expect(body.error_type).toBe("payload_too_large");
+      const stored = await store.getNoteByPath("huge-note");
+      expect(stored).toBeNull();
+    });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // REST tag-scope confidentiality (security review). expand_links must not
 // inline out-of-scope wikilinked content; include_links must not hydrate