Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
29.7 KB
Raw Blame
/**
 * Page-level deduplication for Brain preferences and retired entries.
 *
 * The scope is intentionally narrow: detect EXACT duplicates after
 * Unicode/case normalisation of the rule text. This is the most
 * common case agents produce (two ingestion sessions covering the
 * same rule with different slugs), and it ships with a deterministic,
 * easily-auditable signal. Approximate near-duplicate detection
 * (shingle / MinHash / semantic) is a follow-up.
 *
 * The merge writes a `merged_into:` pointer on the secondary via
 * {@link setMergedInto} and optionally rewrites any `[[<secondary>]]`
 * wikilinks across the vault to point at the canonical page.
 */

import {
  existsSync,
  readFileSync,
  readdirSync,
  realpathSync,
  statSync,
  type Dirent,
} from "node:fs";
import { join, posix, relative, sep } from "node:path";

import { atomicWriteFileSync } from "../fs-atomic.ts";
import { realpathInsideVault } from "../path-safety.ts";
import { formatFrontmatter, parseFrontmatter, parseFrontmatterText } from "../vault.ts";
import { rewriteStorePreference, storePreferencePages } from "./preference-page-write.ts";
import { preferencesStoreOnly } from "./preference-store.ts";
import { compositeScopeKey, scopeFromFrontmatter } from "../scope-key.ts";
import { matchScope, mayDescend, resolveVaultScope } from "../vault-scope/index.ts";
import { pathCovers, type VaultScopeRules } from "../vault-scope/defaults.ts";
import { brainDirs, BRAIN_ROOT_REL } from "./paths.ts";
import { codeRegions } from "./wikilink.ts";
import {
  isMergeResolved,
  mergePointerLookup,
  readMergedInto,
  setMergedInto,
} from "./page-meta/page-id.ts";
import { normalizeForDedup } from "./text/normalize.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";

export interface PageRecord {
  /** Page identity (e.g. `pref-no-em-dashes`). */
  readonly id: string;
  /** Absolute path to the markdown file. */
  readonly path: string;
  /** Normalised dedup key (topic + principle, NFKC + casefold). */
  readonly key: string;
  /** Raw topic / principle for reporting. */
  readonly topic: string;
  readonly principle: string;
  /** Creation timestamp from frontmatter; missing entries fall back to mtime. */
  readonly createdAtMs: number;
  /**
   * The `merged_into:` pointer this page carries, or `null`. Present so
   * the grouping pass can tell a page a merge already resolved from one
   * still awaiting a decision, without a second read of the frontmatter.
   */
  readonly mergedInto: string | null;
}

export interface DedupCandidate {
  readonly key: string;
  /** All pages sharing this key, ordered by createdAtMs ascending. */
  readonly pages: ReadonlyArray<PageRecord>;
  /** Recommended canonical (oldest createdAtMs; ties broken by id ascending). */
  readonly canonical: PageRecord;
  /** Pages to merge into the canonical. */
  readonly secondaries: ReadonlyArray<PageRecord>;
}

export interface DedupReport {
  readonly candidates: ReadonlyArray<DedupCandidate>;
  /** Total pages scanned (preferences + retired). */
  readonly scanned: number;
}

function readPageRecords(vault: string): PageRecord[] {
  const dirs = brainDirs(vault);
  const out: PageRecord[] = [];
  const sources: Array<{ dir: string; prefix: string }> = [
    { dir: dirs.preferences, prefix: "pref-" },
    { dir: dirs.retired, prefix: "ret-" },
  ];
  for (const { dir, prefix } of sources) {
    if (!existsSync(dir)) continue;
    for (const name of readdirSync(dir)) {
      if (!name.endsWith(".md") || !name.startsWith(prefix)) continue;
      const path = join(dir, name);
      let meta: Record<string, unknown>;
      try {
        [meta] = parseFrontmatter(path);
      } catch {
        continue;
      }
      const id = typeof meta["id"] === "string" ? meta["id"] : name.replace(/\.md$/, "");
      const topic = typeof meta["topic"] === "string" ? meta["topic"] : "";
      const principle = typeof meta["principle"] === "string" ? meta["principle"] : "";
      const createdAtIso = typeof meta["created_at"] === "string" ? meta["created_at"] : "";
      const createdAtMs = createdAtIso ? Date.parse(createdAtIso) : statSync(path).mtimeMs;
      // Per-scope keying (t_37c05a34): fold the page's composite scope
      // (owner/session/project) into the dedup key so identical text in two
      // scopes is not collapsed. Additive: a scopeless page yields an empty
      // scope key, so its dedup key is byte-identical to the pre-scope world
      // and existing merges are never re-collapsed.
      const scopeKey = compositeScopeKey(scopeFromFrontmatter(meta));
      const contentKey = normalizeForDedup(`${topic}\0${principle}`);
      const key = scopeKey === "" ? contentKey : `${contentKey} ${scopeKey}`;
      out.push({
        id,
        path,
        key,
        topic,
        principle,
        createdAtMs: Number.isFinite(createdAtMs) ? createdAtMs : 0,
        mergedInto: readMergedInto(meta),
      });
    }
  }
  return out;
}

/**
 * Scan the vault and group pages by their dedup key. Only groups
 * with at least 2 members are returned. The "canonical" pick is the
 * page with the oldest `created_at` (and the lowest id as
 * tie-breaker), which biases toward keeping the first-recorded
 * version of any rule.
 *
 * Pages a merge already resolved leave the pool before the canonical is
 * picked (GitHub #180). Without that filter the pass re-proposed every
 * merge it had ever applied, forever: the pointer it writes is invisible
 * to the key, so the finished cluster looked exactly like an untouched
 * one to this function and to the six surfaces that read through it.
 * That was not only noise - re-applying rewrote a deliberate
 * `merged_into` at a new canonical, and on pages with no `created_at`
 * (where the ordering falls back to an mtime the merge itself moved) the
 * second pass reversed the pair and wrote a cycle.
 */
export function findDuplicateCandidates(vault: string): DedupReport {
  const records = readPageRecords(vault);
  const pointerOf = mergePointerLookup(records.map((r) => [r.id, r.mergedInto] as const));
  const byKey = new Map<string, PageRecord[]>();
  for (const r of records) {
    if (r.key.trim().length === 0) continue; // skip empty / malformed pages
    const arr = byKey.get(r.key);
    if (arr) arr.push(r);
    else byKey.set(r.key, [r]);
  }
  const candidates: DedupCandidate[] = [];
  for (const [key, group] of byKey) {
    // Resolved members are dropped rather than the whole group skipped:
    // a third page that duplicates the canonical after an earlier merge
    // is still a real finding.
    const live = group.filter((r) => !isMergeResolved(r.id, pointerOf));
    if (live.length < 2) continue;
    live.sort((a, b) => {
      if (a.createdAtMs !== b.createdAtMs) return a.createdAtMs - b.createdAtMs;
      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
    });
    const canonical = live[0]!;
    candidates.push({
      key,
      pages: Object.freeze(live.slice()),
      canonical,
      secondaries: Object.freeze(live.slice(1)),
    });
  }
  candidates.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
  return Object.freeze({
    scanned: records.length,
    candidates: Object.freeze(candidates),
  });
}

/**
 * One wikilink target spelling, and what it should become.
 *
 * `to` is OPTIONAL, and that is the whole reason this shape exists
 * rather than a pair of strings. A note-file delete has to know how many
 * inbound references it is about to strand and must rewrite none of
 * them, while a rename has to rewrite exactly the same set; running the
 * two through one matcher is what stops "what would change" and "what
 * changed" from becoming two different opinions of the same vault. An
 * absent `to` is match-only.
 */
export interface WikilinkRetarget {
  /** Target spelling to match, e.g. `Projects/Old` or `pref-foo`. */
  readonly from: string;
  /** Replacement spelling. Absent means count the matches, rewrite nothing. */
  readonly to?: string;
}

/**
 * One file the rewrite pass could not write, and the reason the
 * filesystem gave.
 *
 * Carried rather than thrown because the pass has already written the
 * files before it, and a throw discards the record of which ones those
 * were - see {@link retargetWikilinks} for the argument.
 */
export interface WikilinkRewriteFailure {
  /** Vault-relative POSIX path of the file that kept its old spellings. */
  readonly path: string;
  /** The filesystem's own message, never a re-description of it. */
  readonly reason: string;
}

/** What one {@link retargetWikilinks} pass read, matched and wrote. */
export interface WikilinkRetargetReport {
  /**
   * Every Markdown file the walk read, vault-relative POSIX, sorted.
   *
   * Carried rather than counted because a caller deciding whether a bare
   * `[[Basename]]` spelling unambiguously names one note needs the
   * population the rewrite would act on - and that is exactly this list,
   * not a second walk under a second rule set.
   */
  readonly files: ReadonlyArray<string>;
  /** Files holding at least one matched spelling, vault-relative, sorted. */
  readonly matched: ReadonlyArray<string>;
  /** Files this pass rewrote. Always empty when `apply` is false. */
  readonly rewritten: ReadonlyArray<string>;
  /**
   * Files whose bytes changed but could not be written, sorted by path.
   * Always empty when `apply` is false.
   */
  readonly failed: ReadonlyArray<WikilinkRewriteFailure>;
  /**
   * How many files the `readable` predicate refused. Zero when no
   * predicate was given.
   *
   * A count, never paths: this pass's reports cross tool boundaries, and
   * the filenames a caller may not read are exactly what the predicate
   * was supplied to withhold - naming them, or even counting them out
   * per directory, would hand the caller the existence leak the
   * predicate exists to prevent.
   */
  readonly withheld: number;
}

export interface RetargetWikilinksOptions {
  /**
   * Vault-relative directory to walk. Defaults to the Brain root, which
   * is where this function's first caller (the page merge) lives.
   *
   * A note-file rename passes `""` - the vault root - because a user
   * note is referenced from user notes and from Brain artifacts alike,
   * and a rewrite that saw only one of those would report a number that
   * looked like coverage and was not.
   */
  readonly root?: string;
  /** False walks and counts without writing a byte. Defaults to true. */
  readonly apply?: boolean;
  /**
   * Vault-relative POSIX prefixes this pass READS and REPORTS but never
   * writes, matched segment-wise via {@link pathCovers}.
   *
   * The note-file lifecycle passes `Brain/log` here. That tree is an
   * append-only record of what an agent said at an instant, so a rename
   * rewriting a spelling inside it would change what the record says was
   * said - and unlike a live wikilink, a log line is not a navigation
   * aid that goes stale, it is testimony. It is still read and still
   * reported as an inbound reference, because withholding the disclosure
   * would be the opposite defect.
   *
   * The page merge deliberately passes nothing: it repoints one page id
   * at the id it was declared a duplicate of, which is the same subject
   * under a new name rather than a different subject.
   */
  readonly neverRewrite?: ReadonlyArray<string>;
  /**
   * The vault-relative paths the caller may read. A file the predicate
   * refuses is never opened, never matched, never rewritten and never
   * NAMED in the report - it is counted in
   * {@link WikilinkRetargetReport.withheld} and nothing else. This is
   * the caller-reach gate for restricted sweeps: without it the walk
   * reads every matching page's bytes and would rewrite them, so a
   * restricted caller could both read the disclosure and write into
   * pages it cannot see. Absent, every walked file may be read.
   */
  readonly readable?: (rel: string) => boolean;
}

/**
 * Directory names never walked, whatever the root and whatever the
 * operator declared.
 *
 * These duplicate entries in `DEFAULT_VAULT_IGNORE_PATHS` on purpose: an
 * operator who declares `vault.ignore_paths` REPLACES that default list
 * rather than extending it, so a vault that excludes `Private` would
 * otherwise start walking `.git`. The vault scope below is the policy;
 * this set is the floor under it.
 */
const RETARGET_SKIP_DIRS: ReadonlySet<string> = new Set([
  ".git",
  ".obsidian",
  ".trash",
  ".stversions",
  "node_modules",
]);

/** One stretch of a document, and whether it is code. */
interface DocumentSegment {
  readonly text: string;
  readonly code: boolean;
}

/**
 * Split `raw` into alternating prose and code segments. Concatenating
 * every `text` back together reproduces `raw` byte for byte, which is
 * what lets the rewrite below transform the prose halves in place
 * without needing a second opinion about where the code was.
 *
 * Code is a fenced block or an inline code span, the regions every link
 * reader masks ({@link codeRegions}). A `[[Projects/Old]]` inside
 * either is a QUOTATION of a link - a tutorial showing the syntax, a
 * design note quoting a vault's contents, a README explaining how a
 * rename behaves - and rewriting it edits documentation into describing a
 * vault that never existed. It matters here because this walk's root
 * reaches every user note rather than `Brain/`.
 */
function segmentCode(raw: string): DocumentSegment[] {
  const out: DocumentSegment[] = [];
  let last = 0;
  for (const [start, end] of codeRegions(raw)) {
    if (start > last) out.push({ text: raw.slice(last, start), code: false });
    out.push({ text: raw.slice(start, end), code: true });
    last = end;
  }
  out.push({ text: raw.slice(last), code: false });
  return out;
}

/** Escape a literal for use inside a regular expression. */
function escapeForRegExp(literal: string): string {
  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}

/**
 * Apply one retarget to one stretch of prose. Wikilinks can carry
 * aliases (`[[target|some alias]]`) and section anchors
 * (`[[target#heading]]`); the target portion alone is replaced.
 */
function rewriteOne(raw: string, retarget: WikilinkRetarget): string {
  const to = retarget.to;
  if (to === undefined || to === retarget.from) return raw;
  const pattern = new RegExp(`\\[\\[${escapeForRegExp(retarget.from)}(?=[#|\\]])`, "g");
  return raw.replaceAll(`[[${retarget.from}]]`, `[[${to}]]`).replace(pattern, `[[${to}`);
}

/**
 * True when `segment` carries at least one `[[<from>]]`-shaped reference.
 *
 * CASE-SENSITIVE, and deliberately so. Obsidian resolves a wikilink
 * case-insensitively, so `[[projects/old]]` is a live reference this pass
 * leaves dangling while reporting `filesRewritten: 0` - a real gap, and
 * one that is NOT this module's to close alone. Every other resolver in
 * this project is case-sensitive on the same question:
 * `store/links.ts`'s ladder compares `d.basename = l.target_path` with
 * SQLite's default binary collation, and
 * `notes/note-title-resolver.ts:120` compares titles with `===`. Making
 * only the rewriter case-insensitive would give this pass a different
 * opinion of "a live reference" than the index and the title resolver
 * have, so a rename would repoint spellings the rest of the project still
 * reads as naming something else. Case-insensitive resolution is a
 * project-wide decision with a migration behind it, and taking it here
 * would be taking it in the one place least able to hold it.
 */
function mentionsIn(segment: string, from: string): boolean {
  return new RegExp(`\\[\\[${escapeForRegExp(from)}(?=[#|\\]])`).test(segment);
}

/** One Markdown file the walk admitted. */
interface WalkedFile {
  readonly abs: string;
  /** Vault-relative POSIX path. */
  readonly rel: string;
}

/** Vault-relative POSIX form of an absolute path under `vault`. */
function relOf(vault: string, abs: string): string {
  return relative(vault, abs).split(sep).join(posix.sep);
}

/** Realpath, or `null` when it cannot be resolved. */
function realpathOrNull(target: string): string | null {
  try {
    return realpathSync(target);
  } catch {
    return null;
  }
}

/**
 * Every `.md` file under `dir` this pass may read, depth-first, carrying
 * the vault-relative path every rule is judged on.
 *
 * Three refusals, none of which the walk needed while its only root was
 * `Brain/` and all of which it needs now that a note rename points it at
 * the vault:
 *
 *   - a symlink whose realpath leaves the vault is not followed, for
 *     files and directories alike. `vault/linked -> /tmp/OUTSIDE` is an
 *     ordinary Obsidian arrangement, and the previous walk read those
 *     bytes, rewrote them, and reported them under a vault-relative
 *     path they do not have. {@link realpathInsideVault} is the same
 *     predicate the doctor's `symlink-escape` lint asks.
 *   - a directory whose realpath has already been walked is not walked
 *     again, so a symlink cycle terminates at the first repeat instead
 *     of at the kernel's `ELOOP` some forty levels down - which read the
 *     same file dozens of times, rewrote it dozens of times, and
 *     inflated the carrier count the bare-basename decision is made
 *     from until one note read as two.
 *   - `vault.ignore_paths` / `vault.include_paths` are obeyed, through
 *     the {@link matchScope} / {@link mayDescend} pair every other
 *     walker in this project uses. A path the operator declared out of
 *     scope must not be rewritten, and must not be NAMED in a report
 *     that crosses a tool boundary either: the filenames inside an
 *     excluded directory are exactly what the exclusion was for.
 */
function markdownFilesUnder(vault: string, dir: string, rules: VaultScopeRules): WalkedFile[] {
  const out: WalkedFile[] = [];
  const stack: WalkedFile[] = [{ abs: dir, rel: relOf(vault, dir) }];
  const walkedDirs = new Set<string>();
  const dirReal = realpathOrNull(dir);
  if (dirReal !== null) walkedDirs.add(dirReal);
  while (stack.length > 0) {
    const current = stack.pop()!;
    let entries: Dirent[];
    try {
      entries = readdirSync(current.abs, { withFileTypes: true });
    } catch {
      continue;
    }
    // Sorted so that which of two aliasing spellings of one directory
    // wins the visited-set race is a property of the vault rather than
    // of readdir order, and a report crossing a tool boundary is
    // reproducible.
    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
    for (const entry of entries) {
      const abs = join(current.abs, entry.name);
      const rel = current.rel === "" ? entry.name : `${current.rel}${posix.sep}${entry.name}`;
      if (entry.isSymbolicLink() && !realpathInsideVault(abs, vault)) continue;
      let info;
      try {
        info = statSync(abs);
      } catch {
        continue;
      }
      if (info.isDirectory()) {
        if (RETARGET_SKIP_DIRS.has(entry.name)) continue;
        if (!mayDescend(rel, rules)) continue;
        const real = realpathOrNull(abs);
        if (real === null || walkedDirs.has(real)) continue;
        walkedDirs.add(real);
        stack.push({ abs, rel });
        continue;
      }
      if (!info.isFile()) continue;
      if (!entry.name.endsWith(".md")) continue;
      if (!matchScope(rel, rules).inScope) continue;
      out.push({ abs, rel });
    }
  }
  return out;
}

/**
 * Rewrite wikilink targets across a subtree of the vault, or count what
 * a rewrite would touch.
 *
 * This used to be `patchWikilinks`: Brain-scoped by a hard-coded
 * `join(vault, "Brain")` and keyed on one id-shaped target at a time. A
 * user note lives outside `Brain/`, is referenced from both sides of
 * that boundary, and is spelled three different ways in Obsidian
 * (`[[Projects/Old]]`, `[[Projects/Old.md]]`, `[[Old]]`), so neither
 * narrowing survived contact with a note-file rename. Both are now
 * caller decisions and the default is the old behaviour exactly.
 *
 * Retargets are applied longest-spelling-first so a shorter prefix
 * cannot consume a longer one's match, and every replacement is anchored
 * at `[[`, so a spelling that has already been rewritten is not a
 * candidate for the next retarget in the list.
 *
 * Reads each Markdown file once; writes only where the bytes change.
 *
 * A write that FAILS is recorded in {@link WikilinkRetargetReport.failed}
 * and the pass continues. Throwing was the previous behaviour and it is
 * the worse of the two: by the time one file cannot be written the pass
 * has already rewritten the files before it, and the throw discards the
 * only record of which those were - leaving the caller unable to tell a
 * rename that half-applied from one that never started. A caller that
 * needs a failure to be fatal reads `failed` and raises it itself, which
 * is what {@link patchWikilinks} does.
 */
export function retargetWikilinks(
  vault: string,
  retargets: ReadonlyArray<WikilinkRetarget>,
  opts: RetargetWikilinksOptions = {},
): WikilinkRetargetReport {
  const apply = opts.apply !== false;
  // Vault-identity write guard (context-integrity-gates, Unit J). A
  // counting pass writes nothing, so it asserts nothing: refusing to
  // COUNT against a foreign vault would deny a caller the blast radius
  // it needs in order to decide not to write.
  if (apply) assertVaultIdentityForWrite(vault);

  const root = opts.root === undefined ? BRAIN_ROOT_REL : opts.root;
  const abs = root === "" ? vault : join(vault, root);
  const empty = Object.freeze({
    files: Object.freeze([]),
    matched: Object.freeze([]),
    rewritten: Object.freeze([]),
    failed: Object.freeze([]),
    withheld: 0,
  });
  // Store-only (task 2.10): the legacy `Brain/` tree is read-only to this
  // machine (design D11a); the preferences the store's fold holds are
  // rewritten instead, each as the fields the rewrite changes.
  // A counting pass reads the same side the applying pass writes, so its
  // blast radius matches; only the writes are gated on `apply`.
  const storeOnly = preferencesStoreOnly(vault);
  if (!existsSync(abs) && !storeOnly) return empty;

  const rules = resolveVaultScope(vault).rules;
  const neverRewrite = opts.neverRewrite ?? [];
  const readable = opts.readable;
  const ordered = [...retargets].toSorted((a, b) => b.from.length - a.from.length);
  const files: string[] = [];
  const matched: string[] = [];
  const rewritten: string[] = [];
  const failed: WikilinkRewriteFailure[] = [];
  let withheld = 0;

  const rewriteText = (raw: string): string | null => {
    const segments = segmentCode(raw);
    const prose = segments.filter((segment) => !segment.code);
    if (!ordered.some((retarget) => prose.some((s) => mentionsIn(s.text, retarget.from)))) {
      return null;
    }
    return segments
      .map((segment) => (segment.code ? segment.text : ordered.reduce(rewriteOne, segment.text)))
      .join("");
  };
  const storePages = storeOnly
    ? storePreferencePages(vault).filter((page) => root === "" || pathCovers(root, page.rel))
    : [];
  for (const page of storePages) {
    if (readable !== undefined && !readable(page.rel)) {
      withheld += 1;
      continue;
    }
    files.push(page.rel);
    const raw = formatFrontmatter(page.meta, page.body);
    const next = rewriteText(raw);
    if (next === null) continue;
    matched.push(page.rel);
    if (!apply) continue;
    if (neverRewrite.some((prefix) => pathCovers(prefix, page.rel)) || next === raw) continue;
    try {
      const [nextMeta, nextBody] = parseFrontmatterText(next);
      if (rewriteStorePreference(vault, page, nextMeta, undefined, nextBody)) {
        rewritten.push(page.rel);
      }
    } catch (err) {
      failed.push({ path: page.rel, reason: err instanceof Error ? err.message : String(err) });
    }
  }

  for (const file of existsSync(abs) ? markdownFilesUnder(vault, abs, rules) : []) {
    // The legacy tree is read-only once switched (see above).
    if (storeOnly && pathCovers(BRAIN_ROOT_REL, file.rel)) continue;
    // Asked BEFORE the read, so a file the caller may not read contributes
    // nothing - not its bytes, not a match, not a rewrite, not its name.
    if (readable !== undefined && !readable(file.rel)) {
      withheld += 1;
      continue;
    }
    let raw: string;
    try {
      raw = readFileSync(file.abs, "utf8");
    } catch {
      continue;
    }
    files.push(file.rel);
    const segments = segmentCode(raw);
    const prose = segments.filter((segment) => !segment.code);
    if (ordered.some((retarget) => prose.some((s) => mentionsIn(s.text, retarget.from)))) {
      matched.push(file.rel);
    }
    if (!apply) continue;
    if (neverRewrite.some((prefix) => pathCovers(prefix, file.rel))) continue;
    const next = segments
      .map((segment) => (segment.code ? segment.text : ordered.reduce(rewriteOne, segment.text)))
      .join("");
    if (next === raw) continue;
    try {
      atomicWriteFileSync(file.abs, next);
      rewritten.push(file.rel);
    } catch (err) {
      failed.push({ path: file.rel, reason: err instanceof Error ? err.message : String(err) });
    }
  }

  return Object.freeze({
    files: Object.freeze(files.toSorted()),
    matched: Object.freeze(matched.toSorted()),
    rewritten: Object.freeze(rewritten.toSorted()),
    failed: Object.freeze(
      failed.toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
    ),
    withheld,
  });
}

/**
 * True when a page OTHER than `excludeRel` carries `basename` under the
 * retarget root: the bare-basename link spelling `[[basename]]` then
 * resolves to more than one page, and a retarget keyed on the spelling
 * alone would repoint links that meant the other page - silent
 * mis-linking of pages the caller never considered.
 *
 * The population is the retarget's own - same default root, same scope
 * rules - so a page whose links the pass would never touch cannot
 * manufacture a collision, and a page whose links it WOULD touch cannot
 * hide from one. A caller's `readable` predicate is deliberately not
 * applied: a withheld page still exists on disk, and existence is what
 * makes the spelling ambiguous.
 */
export function basenameCollides(
  vault: string,
  basename: string,
  excludeRel: string,
  opts: Pick<RetargetWikilinksOptions, "root"> = {},
): boolean {
  const root = opts.root === undefined ? BRAIN_ROOT_REL : opts.root;
  const abs = root === "" ? vault : join(vault, root);
  if (!existsSync(abs)) return false;
  const rules = resolveVaultScope(vault).rules;
  for (const file of markdownFilesUnder(vault, abs, rules)) {
    if (file.rel === excludeRel) continue;
    const name = file.rel.split("/").at(-1) ?? "";
    if (name.replace(/\.md$/, "") === basename) return true;
  }
  return false;
}

/**
 * A wikilink rewrite that gave up partway: `rewritten` files were
 * repointed before the write that refused.
 *
 * Carrying the count on the error is what lets the merge's fail-soft
 * caller report how far the pass got - the rewrite half landed, so a
 * bare message would leave the reader unable to tell how much of the
 * repoint the vault actually took.
 */
export class PatchWikilinksError extends Error {
  /** Files the pass rewrote before the one it could not. */
  readonly rewritten: number;
  constructor(rewritten: number, path: string, reason: string) {
    super(
      `patchWikilinks: rewrote ${rewritten} file(s), then could not write ` + `${path}: ${reason}`,
    );
    this.name = "PatchWikilinksError";
    this.rewritten = rewritten;
  }
}

/**
 * Rewrite every `[[<oldTarget>]]` reference inside `<vault>/Brain/`
 * to `[[<newTarget>]]`. Returns the number of files touched.
 *
 * The page merge's spelling of {@link retargetWikilinks}: one id-shaped
 * target, the Brain root, applied. Kept as its own name because that IS
 * the merge's whole vocabulary - a page id is not a path and has no
 * basename spelling - and widening the merge's call site would have made
 * it answer questions it does not ask.
 *
 * Raises a {@link PatchWikilinksError} on a write failure rather than
 * reporting it. The merge's caller counts files and has nowhere to put
 * the identity of one that did not take, so for THIS spelling a failure
 * has to be an error; the note-file lifecycle, which does have somewhere
 * to put it, reads `failed`.
 */
export function patchWikilinks(vault: string, oldTarget: string, newTarget: string): number {
  if (oldTarget === newTarget) {
    // Vault-identity write guard (context-integrity-gates, Unit J):
    // asserted on the no-op path too, so a caller pointed at a foreign
    // vault is refused whether or not its arguments happened to be equal.
    assertVaultIdentityForWrite(vault);
    return 0;
  }
  const report = retargetWikilinks(vault, [{ from: oldTarget, to: newTarget }]);
  const first = report.failed[0];
  if (first !== undefined) {
    throw new PatchWikilinksError(report.rewritten.length, first.path, first.reason);
  }
  return report.rewritten.length;
}

export interface MergePageResult {
  readonly canonical: string;
  readonly secondary: string;
  /** Files whose wikilinks were rewritten to point at the canonical. */
  readonly wikilinksUpdated: number;
}

/**
 * Merge a secondary page into a canonical one:
 *   1. Stamp `merged_into:` on the secondary.
 *   2. Rewrite `[[<secondary>]]` wikilinks to `[[<canonical>]]`.
 *
 * Returns the number of vault files touched by the wikilink patcher
 * so the caller can report it. Idempotent: calling twice with the
 * same arguments leaves the merged-into pointer in place and yields
 * `wikilinksUpdated: 0` on the second call.
 *
 * Raises `MergeChainError` rather than writing when the secondary
 * already points at a different canonical, or when the canonical
 * already resolves back through the secondary. Neither is reachable
 * from {@link findDuplicateCandidates} any more, which is the point: a
 * merge this pass proposes is one it has established is still open.
 */
export function mergePage(
  vault: string,
  secondaryId: string,
  canonicalId: string,
): MergePageResult {
  setMergedInto(vault, secondaryId, canonicalId);
  const touched = patchWikilinks(vault, secondaryId, canonicalId);
  return Object.freeze({
    canonical: canonicalId,
    secondary: secondaryId,
    wikilinksUpdated: touched,
  });
}