feat(git-sync): vendor pure converter + engine into @docmost/git-sync (Phase A.1)

First step of docs/git-sync-plan.md. New workspace package @docmost/git-sync
vendoring the PURE parts from docmost-sync (HEAD b03eb35):
- lib: markdown-converter, markdown-document, canonicalize, docmost-schema,
  node-ops, diff, and an extracted markdown-to-prosemirror (only the pure
  marked->HTML->generateJSON path from upstream collaboration.ts; no websocket).
- engine (pure, no IO): reconcile, layout, sanitize, stabilize, loop-guard.
Ported the upstream pure-module + round-trip corpus tests (vitest): 314 pass,
3 expected upstream known-limitation fails. tsc clean. No server wiring yet.

docmost-schema inlines getStyleProperty (as packages/mcp does — @tiptap/core
3.20.4 doesn't export it). IO engine (pull/push/git/settings) deferred to later
Phase A/B steps; the editor-ext idempotency gate (plan §13.1) is the next step.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/git-sync/src/engine/layout.ts

@@ -0,0 +1,177 @@
+/**
+ * Pure page-tree -> vault path mapping (SPEC §12).
+ *
+ * Given the flat list of page nodes for a space (as returned by
+ * `listAllSpacePages`), compute for every page a deterministic, collision-free
+ * destination: a folder path (root -> leaf ancestors) plus a file stem (the
+ * page's own name, no extension). This module is intentionally PURE and
+ * dependency-free apart from the sanitization helpers, so the whole tree ->
+ * path logic is unit-testable without any I/O. The names are COSMETIC; identity
+ * lives in each file's meta block (pageId / slugId).
+ */
+
+import { sanitizeTitle, disambiguate } from "./sanitize.js";
+
+/** Flat page node as returned by `listAllSpacePages` (no content). */
+export interface PageNode {
+  id: string;
+  title?: string;
+  slugId?: string;
+  parentPageId?: string | null;
+  hasChildren?: boolean;
+}
+
+/** A page's resolved vault destination: folder path + file stem. */
+export interface VaultEntry {
+  /** Folder path, root -> leaf (the page's ancestors). Empty for a root page. */
+  segments: string[];
+  /** The page's own file name without extension. */
+  stem: string;
+}
+
+/**
+ * Build the full vault layout for a space.
+ *
+ * Returns a Map keyed by pageId -> `{ segments, stem }`. The result is
+ * deterministic for a given input and guarantees every full destination path
+ * (`[...segments, stem].join("/")`) is unique, so no page can silently overwrite
+ * another.
+ *
+ * Disambiguation is layered:
+ *   1. Sibling collisions (same sanitized title under the same parent) are
+ *      resolved with a stable ` ~<slugId>` suffix (the suffix is itself
+ *      sanitized, since slugId/id is untrusted data that must never inject a
+ *      path separator).
+ *   2. A final full-path pass catches residual collisions that sibling-scoping
+ *      cannot see — e.g. two pages whose parents are BOTH outside the input set
+ *      both bucket at the root with `segments: []`.
+ */
+export function buildVaultLayout(pages: PageNode[]): Map<string, VaultEntry> {
+  // Index pages by id so the parent chain can be walked. Guard against
+  // duplicate ids in the input (first one wins).
+  const byId = new Map<string, PageNode>();
+  for (const p of pages) {
+    if (p && p.id && !byId.has(p.id)) byId.set(p.id, p);
+  }
+
+  // Resolve each node's display name once, deterministically, tracking sibling
+  // collisions per parent. `usedBySibling` maps a parent key -> set of names
+  // already taken under that parent. The bucket key is the node's parent ONLY
+  // when that parent is actually present in `byId`; otherwise (null parent, or
+  // an orphan whose parent is outside the input set) the node buckets at
+  // `"__root__"`. This is critical: orphans land at the vault root (see
+  // `folderSegmentsFor`), so they MUST share the root bucket with real root
+  // pages to be disambiguated against each other here — making `nameById` final
+  // before any `segments` are computed, so no ancestor name can drift later.
+  const usedBySibling = new Map<string, Set<string>>();
+  const nameById = new Map<string, string>();
+  for (const p of pages) {
+    if (p && p.id && !nameById.has(p.id)) {
+      const parentKey =
+        p.parentPageId && byId.has(p.parentPageId) ? p.parentPageId : "__root__";
+      nameById.set(p.id, nameForNode(p, parentKey, usedBySibling));
+    }
+  }
+
+  // Every id we index above MUST get a resolved name; this helper returns it
+  // and THROWS if it is somehow absent, rather than silently recomputing a
+  // DIFFERENT, non-disambiguated name (which would desync a folder segment from
+  // its target file).
+  const nameOf = (id: string): string => {
+    const name = nameById.get(id);
+    if (name === undefined) {
+      throw new Error(`buildVaultLayout: no resolved name for page id ${id}`);
+    }
+    return name;
+  };
+
+  // Build the folder path for a page by walking parentPageId to the root. The
+  // page's OWN name is the file stem; its ancestors become folders. A `visited`
+  // guard prevents an infinite loop on a malformed parent cycle.
+  const folderSegmentsFor = (node: PageNode): string[] => {
+    const ancestors: string[] = [];
+    const visited = new Set<string>();
+    let current: PageNode | undefined = node.parentPageId
+      ? byId.get(node.parentPageId)
+      : undefined;
+    while (current && current.id && !visited.has(current.id)) {
+      visited.add(current.id);
+      ancestors.unshift(nameOf(current.id));
+      current = current.parentPageId
+        ? byId.get(current.parentPageId)
+        : undefined;
+    }
+    return ancestors;
+  };
+
+  // First pass: compute the provisional { segments, stem } for every node.
+  const layout = new Map<string, VaultEntry>();
+  for (const p of pages) {
+    if (!p || !p.id || layout.has(p.id)) continue;
+    layout.set(p.id, {
+      segments: folderSegmentsFor(p),
+      stem: nameOf(p.id),
+    });
+  }
+
+  // Final full-path uniqueness pass — a belt-and-suspenders safety net. Note
+  // that cross-bucket (orphan/root) collisions are now resolved in the name pass
+  // above (orphans share the "__root__" bucket), so ancestor names are final
+  // before `segments` are built and this pass should rarely/never re-stem an
+  // ancestor. It only re-stems the colliding LATER leaf via the sanitized
+  // slugId/id, then (if still colliding) appends the id.
+  const usedPaths = new Set<string>();
+  const seenIds = new Set<string>();
+  const pathKey = (e: VaultEntry): string => [...e.segments, e.stem].join("/");
+  for (const p of pages) {
+    if (!p || !p.id || seenIds.has(p.id)) continue;
+    seenIds.add(p.id);
+    const entry = layout.get(p.id);
+    if (!entry) continue;
+
+    if (usedPaths.has(pathKey(entry))) {
+      // First attempt: disambiguate the stem with the sanitized slugId (or id).
+      entry.stem = disambiguate(entry.stem, sanitizeTitle(p.slugId ?? p.id));
+      if (usedPaths.has(pathKey(entry))) {
+        // Still colliding: append the (sanitized) id as a last resort. The id
+        // is globally unique, so this always resolves the collision.
+        entry.stem = disambiguate(entry.stem, sanitizeTitle(p.id));
+      }
+    }
+    usedPaths.add(pathKey(entry));
+  }
+
+  return layout;
+}
+
+/**
+ * Compute a deterministic, collision-free name for a node among its SIBLINGS.
+ * `usedBySibling` maps a parent key -> set of names already taken, so two
+ * siblings that sanitize to the same name get a stable ` ~slugId` suffix
+ * (SPEC §12). The suffix is itself passed through `sanitizeTitle`, because the
+ * slugId/id is a second untrusted-data channel that must never leak a path
+ * separator into the name. `parentKey` is supplied by the caller (it resolves
+ * to `"__root__"` for root pages AND for orphans whose parent is outside the
+ * input set, so they share one bucket). The name is COSMETIC; identity lives in
+ * the meta block.
+ */
+function nameForNode(
+  node: PageNode,
+  parentKey: string,
+  usedBySibling: Map<string, Set<string>>,
+): string {
+  let used = usedBySibling.get(parentKey);
+  if (!used) {
+    used = new Set<string>();
+    usedBySibling.set(parentKey, used);
+  }
+
+  let name = sanitizeTitle(node.title ?? "");
+  if (used.has(name)) {
+    // Sibling collision: disambiguate with the stable, sanitized slugId (fall
+    // back to the sanitized pageId if no slugId is present).
+    name = disambiguate(name, sanitizeTitle(node.slugId ?? node.id));
+  }
+  used.add(name);
+  return name;
+}

packages/git-sync/src/engine/loop-guard.ts

@@ -0,0 +1,29 @@
+/**
+ * Loop-guard primitives (SPEC §10). The sync engine must never re-pull its OWN
+ * write as if it were a remote edit: after a push, the next poll will see the
+ * page it just wrote with a fresh `updatedAt`. To suppress that, we key on two
+ * signals — the body HASH of what we pushed (this module) and the `updatedAt`
+ * returned by the write — recorded per page at push time.
+ *
+ * This module owns the PURE, deterministic body-hash. The CONSUMPTION on the
+ * pull side (comparing an incoming page's body hash against the last pushed hash
+ * to decide "this is our own write, ignore it") is a future increment — here we
+ * only PRODUCE the hash and the per-page push record (see `src/push.ts`).
+ */
+import { createHash } from "node:crypto";
+
+/**
+ * Stable hash of a page's markdown BODY (SPEC §10 "хэш тела"). Deterministic:
+ * the same input string always yields the same digest, a different input a
+ * different one. Used to recognize our own write later (loop suppression).
+ *
+ * We hash the body STRING as-is (UTF-8) with SHA-256 and return lowercase hex.
+ * SPEC §10 keys on the body hash rather than file bytes; callers decide WHAT
+ * counts as "the body" (here it is the exact string passed in — typically the
+ * self-contained markdown that was pushed). No normalization is applied: the
+ * caller is responsible for passing a canonical/stable representation if it
+ * wants hash equality across cosmetic-only differences.
+ */
+export function bodyHash(markdownBody: string): string {
+  return createHash("sha256").update(markdownBody, "utf8").digest("hex");
+}

packages/git-sync/src/engine/reconcile.ts

@@ -0,0 +1,200 @@
+/**
+ * Pure reconciliation planner (SPEC §5/§6/§8).
+ *
+ * Given the desired live set of files (computed from the current Docmost tree)
+ * and the set of files currently tracked in the vault, compute what to write,
+ * what to move (old path to remove), and what to delete. Identity is `pageId`
+ * (the stable file<->page anchor, SPEC §4): a page that keeps its pageId but
+ * changes relPath is a MOVE, not delete+add; a tracked pageId that is gone from
+ * the live tree is a DELETE.
+ *
+ * This module is intentionally PURE (no IO, no git) so the whole plan is
+ * unit-testable. The actual file writing / git operations happen in pull.ts.
+ */
+
+/** A page that SHOULD exist in the vault at a given path. */
+export interface LiveEntry {
+  pageId: string;
+  /** Vault-relative path (forward-slash), e.g. `Space/Parent/Child.md`. */
+  relPath: string;
+}
+
+/** A page currently tracked in the vault (pageId parsed from its meta). */
+export interface ExistingEntry {
+  pageId: string;
+  /** Vault-relative path (forward-slash) of the tracked file. */
+  relPath: string;
+}
+
+/** A page to (re)write at its destination path. */
+export interface WriteEntry {
+  pageId: string;
+  relPath: string;
+}
+
+/** A page that moved: written at its NEW relPath, with the OLD path removed. */
+export interface MovedEntry {
+  pageId: string;
+  fromRelPath: string;
+  toRelPath: string;
+  /**
+   * Whether the old path (`fromRelPath`) is SAFE to remove. False when another
+   * live page will (re)write that exact path (path reuse): removing it would
+   * destroy real data, so the caller must skip the removal. The move itself is
+   * still recorded (the new path is written regardless).
+   */
+  removeOldPath: boolean;
+}
+
+/** The full reconciliation plan. */
+export interface ReconciliationPlan {
+  /**
+   * Pages present in `live` -> (re)write at their relPath. This naturally
+   * covers add, content-update (same path) AND move (same pageId, new path),
+   * since every live page is (re)written regardless of whether it existed.
+   */
+  toWrite: WriteEntry[];
+  /**
+   * Vault-relative paths to delete because their tracked pageId is ABSENT from
+   * `live` (page removed/trashed). This set is ONLY absence-based deletions —
+   * the OLD paths of moved pages are NOT here (they live in `moved` and are
+   * applied separately by the caller). Keeping the two apart lets pull.ts gate
+   * absence deletions behind the incomplete-fetch suppression + mass-delete
+   * guard (SPEC §8) while still applying real moves.
+   */
+  toDelete: string[];
+  /**
+   * Tracked pages whose relPath changed. The caller writes the page at
+   * `toRelPath`, then removes `fromRelPath` — but ONLY after the new-path write
+   * succeeded. The old path is NOT in `toDelete`.
+   */
+  moved: MovedEntry[];
+}
+
+/**
+ * Compute the reconciliation plan.
+ *
+ * Rules:
+ *   - Every `live` page is written at its relPath (covers add + update + move).
+ *   - A tracked pageId present in `live` whose relPath changed is `moved`; its
+ *     OLD relPath goes into `moved` ONLY (the caller removes it after the new
+ *     path is written) and is NEVER added to `toDelete`.
+ *   - A tracked pageId NOT present in `live` is an ABSENCE delete; its relPath
+ *     is added to `toDelete`.
+ *
+ * Notes:
+ *   - Safety filter (no data loss): no path that is a live TARGET path of any
+ *     page is ever deleted/removed (a write owns it). This applies to BOTH the
+ *     absence `toDelete` set AND a moved page's old-path removal — if a moved
+ *     page's OLD path is reused by ANOTHER live page, the move records no old
+ *     path to remove, because that path will be (re)written.
+ *   - `existing` may legitimately contain duplicate pageIds (two stray files
+ *     carrying the same meta pageId); each such file that is not the live target
+ *     path is removed (as an absence/move) so the vault converges to exactly the
+ *     live set.
+ */
+export function planReconciliation(
+  live: LiveEntry[],
+  existing: ExistingEntry[],
+): ReconciliationPlan {
+  // Desired path for each live pageId.
+  const liveByPageId = new Map<string, string>();
+  // Set of all paths that WILL be written (never delete/remove one of these).
+  const liveTargetPaths = new Set<string>();
+  for (const e of live) {
+    liveByPageId.set(e.pageId, e.relPath);
+    liveTargetPaths.add(e.relPath);
+  }
+
+  const toWrite: WriteEntry[] = live.map((e) => ({
+    pageId: e.pageId,
+    relPath: e.relPath,
+  }));
+
+  const moved: MovedEntry[] = [];
+  // Absence-based deletions ONLY (tracked pageId absent from `live`). Use a Set
+  // so the same path coming from multiple existing rows is queued only once.
+  const toDeleteSet = new Set<string>();
+
+  for (const ex of existing) {
+    const liveRel = liveByPageId.get(ex.pageId);
+    if (liveRel === undefined) {
+      // Tracked page is gone from the live tree -> absence delete.
+      // Never queue a path a live page will (re)write (path reuse -> no loss).
+      if (!liveTargetPaths.has(ex.relPath)) toDeleteSet.add(ex.relPath);
+      continue;
+    }
+    if (liveRel !== ex.relPath) {
+      // Same pageId, different path -> a MOVE. Record it so the caller can write
+      // the new path first, then remove the old one. If the old path is itself a
+      // live target (reused by another page), it must NOT be removed — the write
+      // owns it — so flag `removeOldPath: false` (move still recorded).
+      moved.push({
+        pageId: ex.pageId,
+        fromRelPath: ex.relPath,
+        toRelPath: liveRel,
+        removeOldPath: !liveTargetPaths.has(ex.relPath),
+      });
+    }
+    // liveRel === ex.relPath -> content-update in place; nothing extra to do
+    // (the write above re-emits the file; identical bytes => git no-op).
+  }
+
+  const toDelete = [...toDeleteSet];
+
+  return { toWrite, toDelete, moved };
+}
+
+/**
+ * Below this many tracked files the mass-delete fraction guard is not applied
+ * (a tiny vault where deleting "most" files is normal, e.g. 1-of-2).
+ */
+export const MASS_DELETE_MIN_EXISTING = 4;
+/** Fraction of tracked files above which a delete plan is a suspected wipe. */
+export const MASS_DELETE_FRACTION = 0.5;
+
+/** Why absence-based deletions were (or were not) applied this cycle. */
+export type DeletionDecision =
+  | { apply: true }
+  | { apply: false; reason: "incomplete-fetch" | "empty-live" | "mass-delete" };
+
+/**
+ * Pure decision: should the ABSENCE-based deletions (`plan.toDelete`) be applied
+ * this cycle? Encapsulates the SPEC §8 safety invariants so they are unit-
+ * testable without live creds or git:
+ *
+ *   - `treeComplete === false` (a partial Docmost tree fetch) -> SUPPRESS. A page
+ *     missing from a partial tree is NOT proof of deletion (SPEC §8); we must not
+ *     delete merely-absent files this cycle. (Writes/updates/moves still happen.)
+ *   - The live fetch returned 0 pages while files are tracked -> SUPPRESS
+ *     (almost always a failed fetch, never a real "delete everything").
+ *   - The plan would delete more than `MASS_DELETE_FRACTION` of a non-trivial
+ *     vault -> SUPPRESS as a mass-deletion guard (defense in depth).
+ *
+ * Moves are NOT governed by this decision: a moved page IS present in `live`, so
+ * its old-path removal is real (handled by the caller separately).
+ */
+export function decideAbsenceDeletions(args: {
+  treeComplete: boolean;
+  liveCount: number;
+  existingCount: number;
+  deleteCount: number;
+}): DeletionDecision {
+  const { treeComplete, liveCount, existingCount, deleteCount } = args;
+
+  // No tracked files, or nothing to delete -> trivially fine to "apply".
+  if (existingCount === 0 || deleteCount === 0) return { apply: true };
+
+  if (!treeComplete) return { apply: false, reason: "incomplete-fetch" };
+
+  if (liveCount === 0) return { apply: false, reason: "empty-live" };
+
+  if (
+    existingCount >= MASS_DELETE_MIN_EXISTING &&
+    deleteCount > existingCount * MASS_DELETE_FRACTION
+  ) {
+    return { apply: false, reason: "mass-delete" };
+  }
+
+  return { apply: true };
+}

packages/git-sync/src/engine/roundtrip-helpers.ts

@@ -0,0 +1,77 @@
+/**
+ * Pure helpers extracted from the docmost-sync Phase-0 idempotency harness
+ * (`src/roundtrip.ts`). Only the IO-free comparison utilities are vendored —
+ * the CLI scaffold (`--fixture`/`--page`/`--corpus`, `loadSettings`, the
+ * `DocmostClient` live path and `process.exit`) is NOT vendored (plan §2.1:
+ * the roundtrip harness moves into the package's tests, not the engine).
+ */
+
+/**
+ * Recursively strip every `attrs.id` from a ProseMirror node tree. Block ids
+ * are regenerated by `markdownToProseMirror` (SPEC §11), so they must be
+ * ignored when comparing the semantic shape of two documents. Returns a NEW
+ * tree; the input is not mutated.
+ */
+export function stripBlockIds(node: any): any {
+  if (Array.isArray(node)) {
+    return node.map(stripBlockIds);
+  }
+  if (node && typeof node === "object") {
+    const out: any = {};
+    for (const key of Object.keys(node)) {
+      if (key === "attrs" && node.attrs && typeof node.attrs === "object") {
+        // Drop the `id` attr; keep every other attribute.
+        const { id, ...rest } = node.attrs as Record<string, unknown>;
+        void id;
+        out.attrs = stripBlockIds(rest);
+      } else {
+        out[key] = stripBlockIds(node[key]);
+      }
+    }
+    return out;
+  }
+  return node;
+}
+
+/**
+ * Find the first divergence between two values via a recursive deep compare.
+ * Returns a short path + the two differing values, or null if they are equal.
+ */
+export function firstDivergence(
+  a: any,
+  b: any,
+  path = "$",
+): { path: string; a: any; b: any } | null {
+  if (a === b) return null;
+
+  const ta = typeof a;
+  const tb = typeof b;
+  if (ta !== tb || a === null || b === null) {
+    return { path, a, b };
+  }
+  if (ta !== "object") {
+    return { path, a, b };
+  }
+
+  const aIsArr = Array.isArray(a);
+  const bIsArr = Array.isArray(b);
+  if (aIsArr !== bIsArr) return { path, a, b };
+
+  if (aIsArr) {
+    if (a.length !== b.length) {
+      return { path: `${path}.length`, a: a.length, b: b.length };
+    }
+    for (let i = 0; i < a.length; i++) {
+      const d = firstDivergence(a[i], b[i], `${path}[${i}]`);
+      if (d) return d;
+    }
+    return null;
+  }
+
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const k of keys) {
+    const d = firstDivergence(a[k], b[k], `${path}.${k}`);
+    if (d) return d;
+  }
+  return null;
+}

packages/git-sync/src/engine/sanitize.ts

@@ -0,0 +1,109 @@
+/**
+ * Deterministic filename strategy (SPEC §12).
+ *
+ * The file name is COSMETIC — the source of truth for the file<->page link is
+ * `pageId` / `slugId` inside the meta block, so renaming a file is safe. These
+ * functions are intentionally dependency-free and pure, so they are trivially
+ * unit-testable.
+ */
+
+// Printable characters forbidden in file names on common filesystems (mainly
+// Windows): / \ < > : " | ? *. Each match is replaced with a single "-".
+// Spaces are NOT in this set; whitespace is normalized separately below.
+// ASCII control characters (code points 0..31) are stripped in a separate pass
+// (see stripControlChars) to keep this literal free of embedded control bytes.
+const FORBIDDEN_PRINTABLE_RE = /[/\\<>:"|?*]/g;
+
+// Runs of whitespace (including tabs/newlines) collapse to a single space.
+const WHITESPACE_RUN_RE = /\s+/g;
+
+// Reserved Windows device names (case-insensitive). A bare match (with or
+// without an extension) is unusable as a file name, so it is prefixed with "_".
+const RESERVED_WINDOWS_NAMES = new Set([
+  "con",
+  "prn",
+  "aux",
+  "nul",
+  "com1",
+  "com2",
+  "com3",
+  "com4",
+  "com5",
+  "com6",
+  "com7",
+  "com8",
+  "com9",
+  "lpt1",
+  "lpt2",
+  "lpt3",
+  "lpt4",
+  "lpt5",
+  "lpt6",
+  "lpt7",
+  "lpt8",
+  "lpt9",
+]);
+
+// Cap on the sanitized length to stay well within filesystem path-component
+// limits (255 bytes on most FSes) while leaving room for an extension and a
+// disambiguation suffix.
+const MAX_LENGTH = 120;
+
+/**
+ * Replace every ASCII control character (code points 0..31) with "-". Done by
+ * scanning code points rather than a control-range regex literal, so the source
+ * file carries no embedded control bytes.
+ */
+function stripControlChars(input: string): string {
+  let out = "";
+  for (let i = 0; i < input.length; i++) {
+    out += input.charCodeAt(i) < 32 ? "-" : input[i];
+  }
+  return out;
+}
+
+/**
+ * Sanitize a page title into a safe file-name component (WITHOUT extension).
+ *
+ * Steps: replace forbidden / control characters with "-", collapse whitespace
+ * runs to a single space, trim, cap the length, then guard against an empty
+ * result, an all-dots result, or a reserved Windows device name by prefixing
+ * with "_".
+ */
+export function sanitizeTitle(title: string): string {
+  let name = stripControlChars(title ?? "")
+    .replace(FORBIDDEN_PRINTABLE_RE, "-")
+    .replace(WHITESPACE_RUN_RE, " ")
+    .trim();
+
+  if (name.length > MAX_LENGTH) {
+    name = name.slice(0, MAX_LENGTH).trim();
+  }
+
+  // Compare the base name (before the first dot) against reserved names, so
+  // both "CON" and "con.md" are caught.
+  const base = name.split(".")[0]?.toLowerCase() ?? "";
+  // A name that is empty, consists only of dots ("." / ".." / "..."), or is a
+  // reserved Windows device name is unusable as a path component. The all-dots
+  // case is a path-traversal hazard in particular: an unprefixed ".." would
+  // become a parent-directory segment and let a page escape the vault, so it
+  // MUST be neutralized here (becomes "_..", which is a literal file name).
+  if (
+    name.length === 0 ||
+    /^\.+$/.test(name) ||
+    RESERVED_WINDOWS_NAMES.has(base)
+  ) {
+    name = "_" + name;
+  }
+
+  return name;
+}
+
+/**
+ * Disambiguate a sanitized name when two siblings in the same folder collapse
+ * to the same name. Appends a stable suffix built from the page's `slugId`, so
+ * the result stays deterministic across runs (SPEC §12: `Title ~slugId`).
+ */
+export function disambiguate(name: string, slugId: string): string {
+  return `${name} ~${slugId}`;
+}

packages/git-sync/src/engine/stabilize.ts

@@ -0,0 +1,58 @@
+/**
+ * Normalize-on-write helper (SPEC §11 "Резолюция").
+ *
+ * git diffs byte-for-byte, so writing a page in a NON-fixpoint markdown form
+ * would make the next pull re-export it to a slightly different (but stable)
+ * form and produce a phantom diff -> churny commits. The converter has a couple
+ * of known one-pass asymmetries (a block image after a paragraph adds an empty
+ * paragraph; a diagram materializes `data-align`), all of which converge to a
+ * fixpoint after ONE `export -> import -> export` round-trip.
+ *
+ * So at write time we run exactly that one pass and persist the fixpoint form.
+ * Already-stable content is unaffected (the pass is idempotent), so re-pulls of
+ * unchanged pages produce identical bytes and git sees no diff.
+ */
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+  serializeDocmostMarkdownBody,
+  type DocmostMdMeta,
+} from "../lib/index.js";
+
+/**
+ * Meta object as `exportPageBody` builds it (SPEC §4). Kept byte-for-byte
+ * compatible so files produced here match `exportPageBody`'s output exactly.
+ */
+export interface PageMeta {
+  version: 1;
+  pageId: string;
+  slugId: string;
+  title: string;
+  spaceId: string;
+  parentPageId: string | null;
+}
+
+/**
+ * Produce the self-contained `.md` file text for a page from its raw
+ * ProseMirror `content` + identity meta, in the verified fixpoint form.
+ *
+ *   md1        = convertProseMirrorToMarkdown(content)
+ *   doc2       = markdownToProseMirror(md1)            // one import...
+ *   stableBody = convertProseMirrorToMarkdown(doc2)    // ...and re-export
+ *   file       = serializeDocmostMarkdownBody(meta, stableBody)
+ *
+ * The single export->import->export pass is the verified fixpoint (SPEC §11):
+ * idempotent for already-stable content, and the convergence point for the
+ * known converter asymmetries.
+ */
+export async function stabilizePageFile(
+  content: unknown,
+  meta: PageMeta,
+): Promise<string> {
+  const md1 = convertProseMirrorToMarkdown(content);
+  const doc2 = await markdownToProseMirror(md1);
+  const stableBody = convertProseMirrorToMarkdown(doc2);
+  // The meta shape is exactly what `exportPageBody` writes; cast to the lib's
+  // DocmostMdMeta (a superset with optional fields) for the serializer.
+  return serializeDocmostMarkdownBody(meta as DocmostMdMeta, stableBody);
+}