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

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;
@@ -759,6 +807,35 @@ export function clearQueuedLink(db: Database, sourceId: string, relationship: st
   }
 }
 
+/**
+ * Drop exactly ONE pending forward-ref — scoped by `targetPath` in addition
+ * to `sourceId`/`relationship` (the full `unresolved_wikilinks` primary
+ * key). Used by the `cardinality:"many"` reference-field array sync
+ * (core/src/store.ts's `syncReferenceFieldLinks`) when a SPECIFIC array
+ * element is removed from a field's value: unlike the scalar path (which
+ * owns the ENTIRE relationship namespace and can safely clear every queued
+ * row via {@link clearQueuedLink}), an array field can have MULTIPLE
+ * pending forward-refs under the same relationship at once (one per
+ * unresolved element) — blanket-clearing all of them on a single element's
+ * removal would silently drop the other still-pending elements' queue rows.
+ * Safe no-op when the table doesn't exist yet or nothing is queued for this
+ * exact (source, target, relationship) triple.
+ */
+export function clearQueuedLinkTarget(
+  db: Database,
+  sourceId: string,
+  relationship: string,
+  targetPath: string,
+): void {
+  try {
+    db.prepare(
+      "DELETE FROM unresolved_wikilinks WHERE source_id = ? AND relationship = ? AND target_path = ? COLLATE NOCASE",
+    ).run(sourceId, relationship, targetPath);
+  } catch {
+    // Table may not exist yet — nothing to clear.
+  }
+}
+
 /**
  * Resolve a structured link NOW, or queue it for lazy resolution when the
  * target doesn't exist yet — mirroring the wikilink forward-ref contract
@@ -840,3 +917,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.5",
   "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 } };
     };