fix(footnotes): guard insert against nested/bare definitions, skip definitions-only paste, doc + reorder fixes (#228)

Must-fix:
- insertInlineFootnote could glue a footnoteReference inside an EXISTING
  definition (nested footnotesList, or a bare footnoteDefinition with no list
  wrapper), which canonicalize then dropped as an orphan — silently losing the
  definition's prose. Now: (a) the body/notes boundary is computed from the first
  top-level block that IS or CONTAINS (recursively) a footnotesList/
  footnoteDefinition, not just a top-level list; and (b) the insertNodesAfterAnchor
  core skips footnotesList/footnoteDefinition subtrees entirely (skipSubtreeTypes),
  so an anchor whose only match is inside a definition -> inserted:false (clean
  abort, no write). Added tests: nested-definition, bare-definition, and
  body-before-nested-list-still-inserts.
- editor-ext footnote-canonicalize header listed `markdownToProseMirror` among the
  canonicalizing MCP paths; it is the NON-canonicalizing primitive. Replaced with
  `markdownToProseMirrorCanonical` (+ note that the plain primitive is for comment
  bodies) and added copy_page_content.
- Client paste: canonicalizePastedFootnotes now skips a definitions-ONLY paste
  (no footnoteReference anywhere) — canonicalizing it would strip the
  reference-less list and yield an EMPTY paste. Added a test.

Suggestions:
- docmost_transform now runs validateDocStructure/validateDocUrls on the RAW
  transform output BEFORE canonicalizeFootnotes (mirrors updatePageJson), so a
  too-deep doc gives the intended max-depth error instead of a stack overflow.
- docmost_transform tool description now states the RESULT is footnote-canonical
  (dryRun diff may show tidy-ups; idempotent after first run).
- insertFootnote: dropped the dead `result ? … : undefined` ternaries and the
  `as any` casts (result is always set by the time we return; the not-found path
  throws and aborts mutatePage). `const r = result!;`.

Tests / architecture:
- Added a LIVE-plugin golden case: the real footnoteSyncPlugin leaves a list with
  non-empty content after it in place, and canonicalize agrees (placement parity
  is now a driven property, not a hand-set expected).
- Added generateFootnoteId uuidv7 shape + uniqueness test.
- Item 9: added the ENFORCEMENT-RULE comments at the server parseProsemirrorContent
  and the MCP canonicalizer header (any NEW full-doc persist path MUST canonicalize;
  fragments/append/prepend and comment bodies MUST NOT). Kept per-call-site over a
  brittle grep CI test (the replace-vs-fragment + comment-vs-page nuance makes a
  single wrapper unsafe).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/client/src/features/editor/extensions/markdown-clipboard.canonicalize.test.ts

@@ -117,6 +117,32 @@ describe("canonicalizePastedFootnotes", () => {
     editor.destroy();
   });
 
+  it("leaves a definitions-ONLY paste untouched (no references -> no empty paste)", () => {
+    // A whole-block paste of ONLY definitions (a footnotesList with no matching
+    // footnoteReference anywhere in the selection). Canonicalizing it would strip
+    // the reference-less list -> an EMPTY paste, losing the pasted text. The hook
+    // must leave such a block untouched.
+    const { editor, schema } = makeSchema();
+    const slice = new Slice(
+      Fragment.fromArray([
+        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "a" }, [
+            schema.nodes.paragraph.create(null, [schema.text("note A")]),
+          ]),
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "b" }, [
+            schema.nodes.paragraph.create(null, [schema.text("note B")]),
+          ]),
+        ]),
+      ]),
+      0,
+      0,
+    );
+    const out = canonicalizePastedFootnotes(slice, schema);
+    expect(out).toBe(slice); // returned unchanged (same reference, content kept)
+    expect(listIds(out)).toEqual(["a", "b"]);
+    editor.destroy();
+  });
+
   it("leaves an open (partial) slice untouched even if it carries a list", () => {
     // An open slice (openStart/openEnd > 0) is a partial selection, not a
     // standalone block, so it is returned as-is BEFORE any footnote handling.

apps/client/src/features/editor/extensions/markdown-clipboard.ts

@@ -8,6 +8,7 @@ import {
   htmlToMarkdown,
   canonicalizeFootnotes,
   FOOTNOTES_LIST_NAME,
+  FOOTNOTE_REFERENCE_NAME,
 } from "@docmost/editor-ext";
 import type { Schema } from "@tiptap/pm/model";
 
@@ -165,15 +166,28 @@ export const MarkdownClipboard = Extension.create({
  * for the paste/sync plugins to merge. Residual: when the pasted block is merged
  * into a doc that already has footnotes, ordering RELATIVE to the pre-existing
  * footnotes is still governed by the sync plugin (which does not reorder).
+ *
+ * Also requires at least one footnoteReference in the selection: a definitions-ONLY
+ * paste (`[^a]: …` with no `[^a]` reference in the same block) has no references,
+ * so canonicalizeFootnotes would drop the whole list and the paste would come out
+ * EMPTY — losing the pasted text. Such a block is left as-is for the sync plugin.
  */
 export function canonicalizePastedFootnotes(slice: Slice, schema: Schema): Slice {
   if (slice.openStart !== 0 || slice.openEnd !== 0) return slice;
 
   let hasFootnotesList = false;
+  let hasReference = false;
   slice.content.forEach((node) => {
     if (node.type.name === FOOTNOTES_LIST_NAME) hasFootnotesList = true;
+    if (node.type.name === FOOTNOTE_REFERENCE_NAME) hasReference = true;
+    node.descendants((child) => {
+      if (child.type.name === FOOTNOTE_REFERENCE_NAME) hasReference = true;
+    });
   });
   if (!hasFootnotesList) return slice;
+  // No reference anywhere -> a definitions-only paste; canonicalizing would strip
+  // the reference-less list (empty paste). Leave it untouched.
+  if (!hasReference) return slice;
 
   const content = slice.content.toJSON();
   if (!Array.isArray(content)) return slice;

apps/server/src/core/page/services/page.service.ts

@@ -1328,6 +1328,12 @@ export class PageService {
     // (Future consolidation, architecture B: the import services persist via a
     // different path; folding all of these into one "prepare JSON for persist"
     // helper would centralize the canonicalize call — left as follow-up.)
+    //
+    // ENFORCEMENT RULE (#228): any NEW FULL-document persist path MUST call
+    // `canonicalizeFootnotes(json)` before writing (see createPage and
+    // updatePageContent 'replace'); append/prepend FRAGMENT writes MUST NOT (it
+    // would drop or duplicate footnotes — that is exactly why this is per-call-site
+    // rather than a single wrapper here).
     try {
       jsonToNode(prosemirrorJson);
     } catch (err) {