@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/checkpoint-ontology/merge-copies.js

@@ -0,0 +1,1086 @@
+/**
+ * Merge numbered entity copies (`<slug> 2.md`) into their original file and
+ * delete them (CO-54, owner decision CO-D-007 option 2).
+ *
+ * Gated by `checkpoint.ontology.merge-copies`. A copy is a file named
+ * `<slug> <n>.md` next to `<slug>.md` of the same type, with the same `id`,
+ * in one duplicate group. Other members of a group are never touched.
+ *
+ * Two steps, run separately so sync can push the merged original before its
+ * copy goes away:
+ *
+ * - merge: the copy's fresh aliases, back-references and relationship lines
+ *   are added to the original, `signal_count` takes the higher value, and
+ *   entity files that link to the copy are re-pointed at the original. Every
+ *   rewritten file is recorded in the outbox before it is written, so sync
+ *   pushes it. Keys the checkpoint does not own keep the original's value.
+ * - delete: a copy is deleted from the vault, by exact key, only when merging
+ *   it again would change nothing and no entity file or signal links to it.
+ *   The vault keeps every old version. The local file goes after the vault
+ *   delete succeeds, or when the vault no longer has the key.
+ *
+ * Copies of one original merge in path order, each into the result of the
+ * previous one, and none of them counts as holding a name the others move.
+ * A copy whose body has lines the merged original lacks (prose the merge does
+ * not carry) is merged but never deleted. A copy linked from any file the
+ * merge cannot rewrite (a copy, a knowledge file, a signal) is held.
+ *
+ * A signal whose `entity_refs` names a copy holds that copy: signals are
+ * server-owned, so the ref cannot be re-pointed from here. With `rewriteRefs`
+ * (flag `checkpoint.ontology.merge-rewrite-refs`) invoice and bill links and
+ * knowledge links are re-pointed at the survivor and the survivor receives
+ * the copy's `external_ids` and `web_domains`. A signal ref or a link from a
+ * source still holds the pair (`server_owned_refs`): the sync client cannot
+ * push those files. A link from another copy or an external id conflict also
+ * holds a pair.
+ *
+ * With `pairKind: "variants"` (flag `checkpoint.ontology.merge-variants`) the
+ * pairs are two-file duplicate groups whose canonical names differ only in
+ * case, spacing or punctuation; the survivor is the spaced name, then the
+ * higher `signal_count`, then path order. The copy's canonical name becomes
+ * an alias of the survivor. Merge and delete work as for numbered copies.
+ *
+ * With `pairKind: "listed"` (flag `checkpoint.ontology.merge-listed-pairs`)
+ * the pairs are exactly the `only` entries, reviewed by a person: no finder
+ * runs, so the names may differ. Each entry must name two entities of one
+ * type; a copy listed twice, or listed both as a copy and as an original, is
+ * skipped as `listed_conflict`. Holds, merge and delete work as for numbered
+ * copies.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { freshAliases, ownNames } from "./aliases.js";
+import { entitiesRoot, safeWriteFile } from "./company.js";
+import { appendBackRefs, OWNED_KEYS, parseEntityFile, patchEntityFile, setIdentityKeys } from "./entity-file.js";
+import { isWritableEntityType, normalizeEntityName } from "./identity.js";
+import { findDuplicateGroups, readBackRefs, recordOutbox } from "./multi-writer.js";
+import { buildEntityIndex, listSignalFiles, readSignal } from "./tree.js";
+export const MERGE_COPIES_FLAG = "checkpoint.ontology.merge-copies";
+/**
+ * `merge-copies --variants`: merge two-file duplicate groups whose canonical
+ * names differ only in spacing, case or punctuation (CO-65).
+ */
+export const MERGE_VARIANTS_FLAG = "checkpoint.ontology.merge-variants";
+/** `merge-copies --listed`: merge exactly the reviewed `--only` pairs (CO-74). */
+export const MERGE_LISTED_PAIRS_FLAG = "checkpoint.ontology.merge-listed-pairs";
+/**
+ * `merge-copies --rewrite-refs`: re-point signal `entity_refs`, invoice and
+ * bill links, source and knowledge links from a copy to its survivor, and
+ * carry the copy's `external_ids` and `web_domains` to the survivor.
+ */
+export const MERGE_REWRITE_REFS_FLAG = "checkpoint.ontology.merge-rewrite-refs";
+/** `<slug> <n>.md`, the name a file manager gives a second copy. */
+const COPY_NAME = /^(.+) (\d+)\.md$/;
+/** A relationship list item with a link, as the gardener and checkpoint write them. */
+const LINK_ITEM = /^- .*\]\([^)\n]+\)\s*$/;
+const BACKREF_ITEM = /^- Referenced in \[/;
+const MD_LINK = /\]\(([^)\n]+)\)/g;
+/** Keys that differ between copies for reasons that say nothing about content. */
+const IGNORED_KEYS = new Set(["first_seen", "confidence"]);
+function sectionLines(body) {
+    const match = /(^|\n)##\s+Relationships\s*\n([\s\S]*?)(?=\n##\s|$)/.exec(body);
+    return match ? match[2].split(/\r?\n/).map((line) => line.trimEnd()) : [];
+}
+function splitBody(content) {
+    const match = /^(---\r?\n[\s\S]*?\r?\n---\r?\n?)([\s\S]*)$/.exec(content);
+    return match ? { frontmatter: match[1], body: match[2] } : null;
+}
+/**
+ * A line of the copy whose every link points at the copy itself or at its
+ * original. Moved to the original it would link the survivor to itself or to
+ * the file about to be deleted, so it is neither moved nor unmerged content.
+ */
+function isPairSelfLine(line, pair) {
+    const targets = [...line.matchAll(MD_LINK)].map((match) => resolveLink(pair.copy, match[1]));
+    return targets.length > 0 && targets.every((target) => target === pair.copy || target === pair.original);
+}
+/** Relationship lines of the copy that the original lacks (back-references and self links excluded). */
+function missingRelationshipLines(originalContent, copyContent, pair) {
+    const original = splitBody(originalContent);
+    const copy = splitBody(copyContent);
+    if (!original || !copy)
+        return [];
+    const have = new Set(original.body.split(/\r?\n/).map((line) => line.trimEnd()));
+    const out = [];
+    for (const line of sectionLines(copy.body)) {
+        if (!LINK_ITEM.test(line) || BACKREF_ITEM.test(line) || have.has(line) || isPairSelfLine(line, pair))
+            continue;
+        have.add(line);
+        out.push(line);
+    }
+    return out;
+}
+/** Append lines to `## Relationships`, creating the section when it is missing. */
+function appendRelationshipLines(content, lines) {
+    if (lines.length === 0)
+        return content;
+    const parts = splitBody(content);
+    const body = parts.body;
+    const section = /(^|\n)(##\s+Relationships\s*\n)([\s\S]*?)(?=\n##\s|\s*$)/.exec(body);
+    let next;
+    if (section) {
+        const before = body.slice(0, section.index + section[1].length);
+        const kept = section[3].replace(/\s+$/, "");
+        const after = body.slice(section.index + section[0].length);
+        next = `${before}${section[2]}${kept ? `${kept}\n${lines.join("\n")}` : lines.join("\n")}\n${after}`;
+    }
+    else {
+        const trimmed = body.replace(/\s+$/, "");
+        next = `${trimmed.length > 0 ? `${trimmed}\n\n` : "\n"}## Relationships\n\n${lines.join("\n")}\n`;
+    }
+    return `${parts.frontmatter}${next}`;
+}
+/** Remove one entity from the name indexes so its names stop counting as taken. */
+function unindex(index, rel) {
+    index.byRel.delete(rel);
+    for (const map of [index.canonical, index.alias, index.squashed]) {
+        for (const [key, rels] of map) {
+            if (!rels.delete(rel))
+                continue;
+            if (rels.size === 0)
+                map.delete(key);
+        }
+    }
+}
+/** Copies in scope, and the ones skipped with a reason. Read-only. */
+export function findCopyPairs(index) {
+    const groupOf = new Map();
+    findDuplicateGroups(index).forEach((group, i) => {
+        for (const rel of group.paths)
+            groupOf.set(rel, i);
+    });
+    const pairs = [];
+    const skipped = [];
+    const candidates = [...index.byRel.values()]
+        .filter((entity) => isWritableEntityType(entity.type) && COPY_NAME.test(path.posix.basename(entity.rel)))
+        .sort((a, b) => a.rel.localeCompare(b.rel));
+    for (const copy of candidates) {
+        const base = COPY_NAME.exec(path.posix.basename(copy.rel))[1];
+        const original = `${path.posix.dirname(copy.rel)}/${base}.md`;
+        const target = index.byRel.get(original);
+        if (!target) {
+            skipped.push({ copy: copy.rel, reason: index.invalid.has(original) ? "original_invalid" : "no_original" });
+        }
+        else if (target.id !== copy.id || target.type !== copy.type) {
+            skipped.push({ copy: copy.rel, reason: "identity_differs" });
+        }
+        else if (groupOf.get(copy.rel) === undefined || groupOf.get(copy.rel) !== groupOf.get(original)) {
+            skipped.push({ copy: copy.rel, reason: "not_in_duplicate_group" });
+        }
+        else {
+            pairs.push({ type: copy.type, copy: copy.rel, original });
+        }
+    }
+    return { pairs, skipped };
+}
+/** The canonical name with case, spacing and punctuation removed. */
+function compactName(name, type) {
+    return normalizeEntityName(name, type).replace(/[^\p{L}\p{N}]/gu, "");
+}
+/**
+ * Two-file duplicate groups whose canonical names differ only in case, spacing
+ * or punctuation. Numbered copies are left to `findCopyPairs`. Read-only.
+ */
+export function findVariantPairs(index) {
+    const pairs = [];
+    const skipped = [];
+    for (const group of findDuplicateGroups(index)) {
+        const paths = [...group.paths].sort((a, b) => a.localeCompare(b));
+        const numbered = paths.filter((rel) => COPY_NAME.test(path.posix.basename(rel)));
+        if (numbered.length > 0) {
+            for (const rel of numbered)
+                skipped.push({ copy: rel, reason: "numbered_copy" });
+            continue;
+        }
+        if (paths.length !== 2) {
+            skipped.push({ copy: paths[0], reason: "group_size" });
+            continue;
+        }
+        const left = index.byRel.get(paths[0]);
+        const right = index.byRel.get(paths[1]);
+        if (!left || !right) {
+            skipped.push({ copy: paths[0], reason: "no_original" });
+            continue;
+        }
+        if (left.type !== right.type) {
+            skipped.push({ copy: paths[0], reason: "type_differs" });
+            continue;
+        }
+        const leftName = compactName(left.canonical_name, left.type);
+        const rightName = compactName(right.canonical_name, right.type);
+        if (leftName === "" || rightName === "" || leftName !== rightName) {
+            skipped.push({ copy: paths[0], reason: "names_differ" });
+            continue;
+        }
+        const leftSpaced = left.canonical_name.includes(" ");
+        const rightSpaced = right.canonical_name.includes(" ");
+        let originalRel = paths[0];
+        let copyRel = paths[1];
+        if (leftSpaced !== rightSpaced) {
+            originalRel = leftSpaced ? paths[0] : paths[1];
+            copyRel = leftSpaced ? paths[1] : paths[0];
+        }
+        else if (left.signal_count !== right.signal_count) {
+            originalRel = left.signal_count > right.signal_count ? paths[0] : paths[1];
+            copyRel = originalRel === paths[0] ? paths[1] : paths[0];
+        }
+        pairs.push({ type: left.type, copy: copyRel, original: originalRel });
+    }
+    pairs.sort((a, b) => a.copy.localeCompare(b.copy));
+    return { pairs, skipped };
+}
+/**
+ * The reviewed pairs themselves, for `pairKind: "listed"`. An entry is kept
+ * when both files are indexed entities of one writable type. Read-only.
+ */
+export function findListedPairs(index, only) {
+    const pairs = [];
+    const skipped = [];
+    const copyCount = new Map();
+    for (const entry of only)
+        copyCount.set(entry.copy, (copyCount.get(entry.copy) ?? 0) + 1);
+    const originals = new Set(only.map((entry) => entry.original));
+    for (const entry of only) {
+        const copy = index.byRel.get(entry.copy);
+        const original = index.byRel.get(entry.original);
+        if (copyCount.get(entry.copy) > 1 || originals.has(entry.copy) || entry.copy === entry.original) {
+            skipped.push({ copy: entry.copy, reason: "listed_conflict" });
+        }
+        else if (!copy || !original) {
+            skipped.push({ copy: entry.copy, reason: index.invalid.has(entry.original) ? "original_invalid" : "no_original" });
+        }
+        else if (copy.type !== original.type || !isWritableEntityType(copy.type)) {
+            skipped.push({ copy: entry.copy, reason: "type_differs" });
+        }
+        else {
+            pairs.push({ type: copy.type, copy: entry.copy, original: entry.original });
+        }
+    }
+    pairs.sort((a, b) => a.copy.localeCompare(b.copy));
+    return { pairs, skipped };
+}
+/** Resolve a relative link in `fromRel` to a company-relative path, or null. */
+function resolveLink(fromRel, href) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("#") || href.startsWith("/"))
+        return null;
+    let decoded;
+    try {
+        decoded = decodeURI(href.split("#")[0]);
+    }
+    catch {
+        return null;
+    }
+    const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(fromRel), decoded));
+    return resolved.startsWith("..") ? null : resolved;
+}
+function listEntityFiles(company) {
+    const root = entitiesRoot(company);
+    const out = [];
+    let types;
+    try {
+        types = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return out;
+        throw error;
+    }
+    for (const type of types.filter((entry) => entry.isDirectory())) {
+        for (const file of fs.readdirSync(path.join(root, type.name), { withFileTypes: true })) {
+            if (file.isFile() && file.name.endsWith(".md"))
+                out.push(`ontology/entities/${type.name}/${file.name}`);
+        }
+    }
+    return out.sort();
+}
+/** Company-relative `.md` files outside the entity tree and the rendered brief. */
+function listOtherFiles(company) {
+    const out = [];
+    const walk = (rel) => {
+        for (const entry of fs.readdirSync(path.join(company.dir, rel), { withFileTypes: true })) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const child = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (child !== "ontology/entities")
+                    walk(child);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md") && child !== "company-brief.md") {
+                out.push(child);
+            }
+        }
+    };
+    walk("");
+    return out.sort();
+}
+/**
+ * Files outside the entity tree that link to a copy, by markdown link,
+ * `[[ontology/entities/...]]` annotation or a front-matter `path:` entry.
+ * These files are not the merge's to rewrite, so a copy they name is held.
+ */
+function scanOtherLinks(company, copies) {
+    const out = new Map();
+    if (copies.size === 0)
+        return out;
+    const names = [...new Set([...copies].map((copy) => path.posix.basename(copy, ".md")))];
+    const add = (target, rel) => {
+        if (!copies.has(target))
+            return;
+        let set = out.get(target);
+        if (!set)
+            out.set(target, (set = new Set()));
+        set.add(rel);
+    };
+    for (const rel of listOtherFiles(company)) {
+        const content = read(company, rel);
+        if (!names.some((name) => content.includes(name) || content.includes(encodeURI(name))))
+            continue;
+        for (const match of content.matchAll(MD_LINK)) {
+            const target = resolveLink(rel, match[1]);
+            if (target)
+                add(target, rel);
+        }
+        for (const match of content.matchAll(/\[\[(ontology\/entities\/[^\]|\n]+?)(?:\|[^\]\n]*)?\]\]/g)) {
+            add(match[1].endsWith(".md") ? match[1] : `${match[1]}.md`, rel);
+        }
+        for (const match of content.matchAll(/^\s*(?:- )?path:\s*["']?(ontology\/entities\/[^"'\n]+?\.md)["']?\s*$/gm))
+            add(match[1], rel);
+    }
+    return out;
+}
+function scanLinks(company) {
+    const scan = { inbound: new Map(), broken: 0 };
+    for (const rel of listEntityFiles(company)) {
+        const content = fs.readFileSync(path.join(company.dir, rel), "utf8");
+        for (const match of content.matchAll(MD_LINK)) {
+            const target = resolveLink(rel, match[1]);
+            if (!target)
+                continue;
+            if (!fs.existsSync(path.join(company.dir, target)))
+                scan.broken += 1;
+            if (target === rel)
+                continue;
+            let set = scan.inbound.get(target);
+            if (!set)
+                scan.inbound.set(target, (set = new Set()));
+            set.add(rel);
+        }
+    }
+    return scan;
+}
+/** Signal files whose `entity_refs` name a copy, keyed by the copy's path. */
+function scanSignalRefs(company, copies) {
+    const out = new Map();
+    if (copies.size === 0)
+        return out;
+    const byRef = new Map();
+    for (const copy of copies) {
+        const [, , type, file] = copy.split("/");
+        byRef.set(`${type}/${file.slice(0, -3)}`, copy);
+    }
+    for (const rel of listSignalFiles(company.dir)) {
+        for (const ref of readSignal(company.dir, rel)?.refs ?? []) {
+            // Signals write refs both as `type/slug` and as `type/slug.md`.
+            const copy = byRef.get(ref.endsWith(".md") ? ref.slice(0, -3) : ref);
+            if (copy)
+                out.set(copy, [...(out.get(copy) ?? []), rel]);
+        }
+    }
+    return out;
+}
+/** Re-point every link in `content` that resolves to `copy` at `original`. */
+function relink(fromRel, content, copy, original) {
+    return content.replace(MD_LINK, (whole, href) => {
+        if (resolveLink(fromRel, href) !== copy)
+            return whole;
+        const hash = href.indexOf("#");
+        const target = hash === -1 ? href : href.slice(0, hash);
+        const fragment = hash === -1 ? "" : href.slice(hash);
+        const cut = target.lastIndexOf("/");
+        const name = path.posix.basename(original);
+        const encoded = target.slice(cut + 1).includes("%20") ? encodeURI(name) : name;
+        return `](${target.slice(0, cut + 1)}${encoded}${fragment})`;
+    });
+}
+const FRONT_RE = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/;
+const REL_REF = /^(\s*(?:- )?[A-Za-z_][A-Za-z0-9_]*:\s*)(["']?)(\.\.\/[^"'\n]+?\.md)\2\s*$/;
+const WIKI_LINK = /\[\[(ontology\/entities\/[^\]|\n]+?)(\|[^\]\n]*)?\]\]/g;
+const PATH_LINE = /^(\s*(?:- )?path:\s*)(["']?)(ontology\/entities\/[^"'\n]+?\.md)\2\s*$/;
+function frontLines(content) {
+    const match = FRONT_RE.exec(content);
+    if (!match)
+        return null;
+    return { start: match.index + match[0].indexOf(match[1]), lines: match[1].split(/\r?\n/) };
+}
+/** Put rewritten front-matter lines back; every byte outside them stays. */
+function withFrontLines(content, front, lines, newline) {
+    const originalLength = front.lines.join(newline).length;
+    return `${content.slice(0, front.start)}${lines.join(newline)}${content.slice(front.start + originalLength)}`;
+}
+function fileNewline(content) {
+    return content.includes("\r\n") ? "\r\n" : "\n";
+}
+/** In the front matter only, re-point a `../…md` value that resolves to `copy`. */
+function rewriteRelRefs(fromRel, content, copy, original) {
+    const front = frontLines(content);
+    if (!front)
+        return content;
+    const name = path.posix.basename(original);
+    let changed = false;
+    const lines = front.lines.map((line) => {
+        const match = REL_REF.exec(line);
+        if (!match || resolveLink(fromRel, match[3]) !== copy)
+            return line;
+        const value = match[3];
+        const cut = value.lastIndexOf("/");
+        changed = true;
+        return `${match[1]}${match[2]}${value.slice(0, cut + 1)}${name}${match[2]}`;
+    });
+    if (!changed)
+        return content;
+    return withFrontLines(content, front, lines, fileNewline(content));
+}
+/** Entity files whose front matter points at a copy through a relative ref. */
+function scanRelRefs(company, copies) {
+    const out = new Map();
+    if (copies.size === 0)
+        return out;
+    for (const rel of listEntityFiles(company)) {
+        const front = frontLines(read(company, rel));
+        if (!front)
+            continue;
+        for (const line of front.lines) {
+            const match = REL_REF.exec(line);
+            if (!match)
+                continue;
+            const target = resolveLink(rel, match[3]);
+            if (!target || !copies.has(target))
+                continue;
+            let set = out.get(target);
+            if (!set)
+                out.set(target, (set = new Set()));
+            set.add(rel);
+        }
+    }
+    return out;
+}
+function listItemBounds(lines, pathIndex) {
+    let start = pathIndex;
+    let dashIndent = -1;
+    while (start >= 0) {
+        const dash = /^(\s*)- /.exec(lines[start]);
+        if (dash) {
+            dashIndent = dash[1].length;
+            break;
+        }
+        start -= 1;
+    }
+    if (dashIndent < 0)
+        return null;
+    let keyIndent = -1;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (lines[i].trim() === "")
+            continue;
+        const indent = /^(\s*)/.exec(lines[i])[1].length;
+        if (indent <= dashIndent)
+            break;
+        keyIndent = indent;
+        break;
+    }
+    if (keyIndent < 0)
+        keyIndent = dashIndent + 1;
+    let end = start + 1;
+    while (end < lines.length) {
+        const line = lines[end];
+        const dash = /^(\s*)- /.exec(line);
+        if (dash && dash[1].length === dashIndent)
+            break;
+        if (line.trim() !== "" && /^(\s*)/.exec(line)[1].length < keyIndent)
+            break;
+        end += 1;
+    }
+    return { start, end };
+}
+function rewriteWikiLinks(content, copy, original) {
+    WIKI_LINK.lastIndex = 0;
+    return content.replace(WIKI_LINK, (whole, target, label) => {
+        const resolved = target.endsWith(".md") ? target : `${target}.md`;
+        if (resolved !== copy)
+            return whole;
+        const next = target.endsWith(".md") ? original : original.slice(0, -3);
+        return `[[${next}${label ?? ""}]]`;
+    });
+}
+/**
+ * Re-point markdown links, wiki-links, annotation `path:` lines and, when both
+ * ids are known, the `id:` of that same list item.
+ */
+function rewriteOtherFile(fromRel, content, copy, original, copyId, originalId) {
+    const linked = rewriteWikiLinks(relink(fromRel, content, copy, original), copy, original);
+    const newline = fileNewline(content);
+    const lines = linked.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const pathMatch = PATH_LINE.exec(lines[i]);
+        if (!pathMatch || pathMatch[3] !== copy)
+            continue;
+        lines[i] = `${pathMatch[1]}${pathMatch[2]}${original}${pathMatch[2]}`;
+        if (typeof copyId !== "string" || typeof originalId !== "string")
+            continue;
+        const bounds = listItemBounds(lines, i);
+        if (!bounds)
+            continue;
+        for (let j = bounds.start; j < bounds.end; j += 1) {
+            const idMatch = /^(\s*id:\s*)(["']?)([^"'\n]*?)\2(\s*)$/.exec(lines[j]);
+            if (idMatch && idMatch[3] === copyId)
+                lines[j] = `${idMatch[1]}${idMatch[2]}${originalId}${idMatch[2]}${idMatch[4]}`;
+        }
+    }
+    return lines.join(newline);
+}
+/** True when `content` still names `copy` by a link, wiki-link, path or front-matter ref. */
+function referencesCopy(fromRel, content, copy) {
+    MD_LINK.lastIndex = 0;
+    for (const match of content.matchAll(MD_LINK)) {
+        if (resolveLink(fromRel, match[1]) === copy)
+            return true;
+    }
+    WIKI_LINK.lastIndex = 0;
+    for (const match of content.matchAll(WIKI_LINK)) {
+        const target = match[1].endsWith(".md") ? match[1] : `${match[1]}.md`;
+        if (target === copy)
+            return true;
+    }
+    for (const line of content.split(/\r?\n/)) {
+        const pathMatch = PATH_LINE.exec(line);
+        if (pathMatch && pathMatch[3] === copy)
+            return true;
+    }
+    const front = frontLines(content);
+    if (front) {
+        for (const line of front.lines) {
+            const rel = REL_REF.exec(line);
+            if (rel && resolveLink(fromRel, rel[3]) === copy)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Signals and sources are written by the server pipeline and the sync
+ * client never pushes them, so a rewrite made here would not reach the
+ * vault (hq-cloud cloud-authoritative.ts).
+ */
+function isServerOwnedRel(rel) {
+    return rel.startsWith("signals/") || rel.startsWith("sources/");
+}
+const REF_KEYS = new Set(["system", "namespace", "objectType", "recordId"]);
+function refKey(ref) {
+    return `${ref.system}:${ref.namespace}:${ref.recordId}`.toLowerCase();
+}
+/** An `external_refs` entry, or null when it has another shape (so it is never rewritten). */
+function readRef(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const record = raw;
+    if (!Object.keys(record).every((key) => REF_KEYS.has(key)))
+        return null;
+    if (!Object.values(record).every((value) => typeof value === "string" && value.length > 0))
+        return null;
+    if (record.system === undefined || record.namespace === undefined || record.recordId === undefined)
+        return null;
+    return record;
+}
+/** `external_ids` and `web_domains` of a front matter, or "identity_shape". */
+function readIdentity(frontmatter) {
+    let ids = {};
+    if (frontmatter.external_ids !== undefined) {
+        const raw = frontmatter.external_ids;
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            return "identity_shape";
+        ids = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (typeof value !== "string")
+                return "identity_shape";
+            ids[key] = value;
+        }
+    }
+    if (frontmatter.web_domains !== undefined) {
+        if (!Array.isArray(frontmatter.web_domains) || !frontmatter.web_domains.every((domain) => typeof domain === "string")) {
+            return "identity_shape";
+        }
+    }
+    const domains = frontmatter.web_domains === undefined ? [] : frontmatter.web_domains;
+    const refs = [];
+    if (frontmatter.external_refs !== undefined) {
+        if (!Array.isArray(frontmatter.external_refs))
+            return "identity_shape";
+        for (const raw of frontmatter.external_refs) {
+            const ref = readRef(raw);
+            if (!ref)
+                return "identity_shape";
+            refs.push(ref);
+        }
+    }
+    return { ids, domains, refs };
+}
+/**
+ * The survivor's identity after taking in the copy's. Two different ids for
+ * one provider are a conflict unless `resolution` names one of them as
+ * primary; the other is then kept in `external_refs`.
+ */
+function unionIdentity(original, copy, resolution) {
+    const ids = { ...original.ids };
+    const addIds = [];
+    const conflicts = [];
+    const refs = [...original.refs];
+    const addRefs = [];
+    const seenRefs = new Set(refs.map(refKey));
+    const addRef = (ref) => {
+        const key = refKey(ref);
+        if (seenRefs.has(key))
+            return;
+        seenRefs.add(key);
+        refs.push(ref);
+        addRefs.push(key);
+    };
+    for (const ref of copy.refs)
+        addRef(ref);
+    for (const [key, value] of Object.entries(copy.ids)) {
+        if (!(key in ids)) {
+            ids[key] = value;
+            addIds.push(key);
+        }
+        else if (ids[key] !== value) {
+            const settle = Object.hasOwn(resolution ?? {}, key) ? resolution[key] : undefined;
+            if (!settle || (settle.primary !== ids[key] && settle.primary !== value)) {
+                conflicts.push(key);
+                continue;
+            }
+            const secondary = settle.primary === ids[key] ? value : ids[key];
+            ids[key] = settle.primary;
+            addRef({
+                system: key,
+                namespace: settle.namespace,
+                ...(settle.object_type !== undefined ? { objectType: settle.object_type } : {}),
+                recordId: secondary,
+            });
+        }
+    }
+    const domains = [...original.domains];
+    const addDomains = [];
+    const seen = new Set(original.domains.map((domain) => domain.toLowerCase().trim()));
+    for (const domain of copy.domains) {
+        const key = domain.toLowerCase().trim();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        domains.push(domain);
+        addDomains.push(domain);
+    }
+    return { ids, domains, refs, addIds, addDomains, addRefs, conflicts };
+}
+function frontMatterId(content) {
+    const id = parseEntityFile(content)?.frontmatter.id;
+    return typeof id === "string" ? id : null;
+}
+/**
+ * The original's content with the copy merged in. Never removes anything from
+ * the original. `siblings` are all copies of the same original; none of them
+ * counts as holding a name.
+ */
+function mergeCopy(index, pair, siblings, originalContent, copyContent, now) {
+    const original = parseEntityFile(originalContent);
+    const copy = parseEntityFile(copyContent);
+    if (!original || !copy)
+        return "unparseable";
+    const copyEntity = index.byRel.get(pair.copy);
+    const originalEntity = index.byRel.get(pair.original);
+    if (!copyEntity || !originalEntity)
+        return "not_indexed";
+    const scratch = {
+        ...index,
+        byRel: new Map(index.byRel),
+        canonical: new Map([...index.canonical].map(([k, v]) => [k, new Set(v)])),
+        alias: new Map([...index.alias].map(([k, v]) => [k, new Set(v)])),
+        squashed: new Map([...index.squashed].map(([k, v]) => [k, new Set(v)])),
+    };
+    for (const sibling of siblings)
+        unindex(scratch, sibling);
+    const own = ownNames(scratch, pair.original, []);
+    const names = [copyEntity.canonical_name, ...copyEntity.aliases];
+    const aliases = freshAliases(scratch, pair.type, pair.original, own, names);
+    const moved = new Set(aliases.map((alias) => normalizeEntityName(alias, pair.type)));
+    const dropped = names.filter((name) => {
+        const normalized = normalizeEntityName(name, pair.type);
+        return normalized !== "" && !own.has(normalized) && !moved.has(normalized);
+    });
+    const withRefs = appendBackRefs(originalContent, readBackRefs(copy.body));
+    const lines = missingRelationshipLines(withRefs.content, copyContent, pair);
+    const body = appendRelationshipLines(withRefs.content, lines);
+    const raise = copyEntity.signal_count > originalEntity.signal_count ? copyEntity.signal_count : undefined;
+    const patched = patchEntityFile(body, {
+        addAliases: aliases,
+        signalCount: copyEntity.signal_count,
+        lastUpdated: now.toISOString(),
+        bodyChanged: withRefs.added > 0 || lines.length > 0,
+    });
+    if (!patched.ok)
+        return patched.reason;
+    const have = new Set(splitBody(patched.content)?.body.split(/\r?\n/).map((line) => line.trim()) ?? []);
+    // The copy's `# Name` heading is not content: its name moves to an alias.
+    // The `## Relationships` heading is not content either: its lines count one by one.
+    const heading = `# ${copyEntity.canonical_name}`;
+    const leftover = (splitBody(copyContent)?.body.split(/\r?\n/) ?? [])
+        .map((line) => line.trim())
+        .filter((line) => line !== "" &&
+        line !== heading &&
+        !/^##\s+Relationships$/.test(line) &&
+        !have.has(line) &&
+        !(LINK_ITEM.test(line) && !BACKREF_ITEM.test(line) && isPairSelfLine(line, pair))).length;
+    const keys = [...new Set([...Object.keys(original.frontmatter), ...Object.keys(copy.frontmatter)])].sort();
+    const kept = keys.filter((key) => !OWNED_KEYS.has(key) && !IGNORED_KEYS.has(key) && !isDeepStrictEqual(original.frontmatter[key], copy.frontmatter[key]));
+    return {
+        content: patched.content,
+        changed: patched.changed,
+        aliases,
+        dropped,
+        backrefs: withRefs.added,
+        lines: lines.length,
+        ...(raise !== undefined ? { raise } : {}),
+        kept,
+        leftover,
+    };
+}
+function read(company, rel) {
+    return fs.readFileSync(path.join(company.dir, rel), "utf8");
+}
+/** Links to copies in the company brief (rendered, so reported and not rewritten). */
+function briefLinks(company, copies) {
+    let content;
+    try {
+        content = fs.readFileSync(path.join(company.dir, "company-brief.md"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = new Set();
+    for (const match of content.matchAll(MD_LINK)) {
+        const target = resolveLink("company-brief.md", match[1]);
+        if (target && copies.has(target))
+            out.add(target);
+    }
+    return [...out].sort();
+}
+function plan(company, index, pairs, allPairs, now, rewriteRefs, resolutions = new Map()) {
+    const links = scanLinks(company);
+    const copies = new Set(allPairs.map((pair) => pair.copy));
+    const other = scanOtherLinks(company, copies);
+    if (rewriteRefs) {
+        for (const [copy, rels] of scanRelRefs(company, copies)) {
+            let set = other.get(copy);
+            if (!set)
+                other.set(copy, (set = new Set()));
+            for (const rel of rels)
+                set.add(rel);
+        }
+    }
+    const signalRefs = scanSignalRefs(company, copies);
+    const siblingsOf = new Map();
+    for (const pair of allPairs)
+        siblingsOf.set(pair.original, [...(siblingsOf.get(pair.original) ?? []), pair.copy]);
+    const out = { plans: [], merges: new Map(), finals: new Map(), notReady: new Map() };
+    for (const pair of pairs) {
+        const inbound = [...new Set([...(links.inbound.get(pair.copy) ?? []), ...(other.get(pair.copy) ?? [])])].sort();
+        const refs = (signalRefs.get(pair.copy) ?? []).sort();
+        const siblings = siblingsOf.get(pair.original) ?? [pair.copy];
+        const copyContent = read(company, pair.copy);
+        const onDisk = read(company, pair.original);
+        let merged = mergeCopy(index, pair, siblings, out.finals.get(pair.original) ?? onDisk, copyContent, now);
+        let identity = null;
+        const resolution = resolutions.get(pair.copy);
+        if (rewriteRefs && typeof merged !== "string") {
+            const mergedFront = parseEntityFile(merged.content)?.frontmatter;
+            const copyFront = parseEntityFile(copyContent)?.frontmatter;
+            const mergedIdentity = mergedFront ? readIdentity(mergedFront) : "identity_shape";
+            const copyIdentity = copyFront ? readIdentity(copyFront) : "identity_shape";
+            if (!mergedFront || !copyFront || mergedIdentity === "identity_shape" || copyIdentity === "identity_shape") {
+                merged = "identity_shape";
+            }
+            else {
+                const union = unionIdentity(mergedIdentity, copyIdentity, resolution);
+                if (union.conflicts.length > 0) {
+                    identity = union;
+                }
+                else {
+                    const ids = setIdentityKeys(merged.content, {
+                        externalIds: union.ids,
+                        webDomains: union.domains,
+                        ...(union.addRefs.length > 0 ? { externalRefs: union.refs } : {}),
+                        lastUpdated: now.toISOString(),
+                    });
+                    if (!ids.ok) {
+                        merged = ids.reason;
+                    }
+                    else {
+                        merged = { ...merged, content: ids.content, changed: merged.changed || ids.changed };
+                        identity = union;
+                    }
+                }
+            }
+        }
+        const entry = {
+            ...pair,
+            add_aliases: typeof merged === "string" ? [] : merged.aliases,
+            dropped_aliases: typeof merged === "string" ? [] : merged.dropped,
+            add_backrefs: typeof merged === "string" ? 0 : merged.backrefs,
+            add_relationship_lines: typeof merged === "string" ? 0 : merged.lines,
+            ...(typeof merged !== "string" && merged.raise !== undefined ? { raise_signal_count: merged.raise } : {}),
+            kept_original_keys: typeof merged === "string" ? [] : merged.kept,
+            inbound_links: inbound,
+            signal_refs: refs,
+            unmerged_body_lines: typeof merged === "string" ? 0 : merged.leftover,
+        };
+        if (rewriteRefs && identity && identity.conflicts.length === 0 && typeof merged !== "string") {
+            entry.add_external_ids = identity.addIds;
+            entry.add_web_domains = identity.addDomains;
+            entry.add_external_refs = identity.addRefs;
+        }
+        const unwritable = rewriteRefs
+            ? inbound.filter((rel) => copies.has(rel))
+            : inbound.filter((rel) => !rel.startsWith("ontology/entities/") || !isWritableEntityType(rel.split("/")[2]) || copies.has(rel));
+        const serverOwned = rewriteRefs ? [...refs, ...inbound.filter(isServerOwnedRel)] : [];
+        if (typeof merged === "string") {
+            entry.held = "merge_invalid";
+            entry.detail = merged;
+        }
+        else if (identity && identity.conflicts.length > 0) {
+            entry.held = "external_id_conflict";
+            entry.detail = identity.conflicts.join(", ");
+        }
+        else if (serverOwned.length > 0) {
+            entry.held = "server_owned_refs";
+            entry.detail = [...new Set(serverOwned)].sort().join(", ");
+        }
+        else if (!rewriteRefs && refs.length > 0) {
+            entry.held = "signal_refs";
+        }
+        else if (unwritable.length > 0) {
+            entry.held = "linked_from_unwritable";
+            entry.detail = unwritable.join(", ");
+        }
+        else {
+            out.merges.set(pair.copy, merged);
+            out.finals.set(pair.original, merged.content);
+            // Deletion is judged against the original as it is on disk now.
+            const current = mergeCopy(index, pair, siblings, onDisk, copyContent, now);
+            let reason;
+            if (!rewriteRefs) {
+                reason =
+                    typeof current === "string"
+                        ? "merge_invalid"
+                        : current.changed
+                            ? "not_merged"
+                            : current.leftover > 0
+                                ? "unmerged_body"
+                                : inbound.length > 0
+                                    ? "linked"
+                                    : null;
+            }
+            else if (typeof current === "string") {
+                reason = "merge_invalid";
+            }
+            else {
+                const diskFront = parseEntityFile(onDisk)?.frontmatter;
+                const copyFront = parseEntityFile(copyContent)?.frontmatter;
+                const diskIdentity = diskFront ? readIdentity(diskFront) : "identity_shape";
+                const copyIdentity = copyFront ? readIdentity(copyFront) : "identity_shape";
+                if (!diskFront || !copyFront || diskIdentity === "identity_shape" || copyIdentity === "identity_shape") {
+                    reason = "merge_invalid";
+                }
+                else {
+                    const union = unionIdentity(diskIdentity, copyIdentity, resolution);
+                    const patched = setIdentityKeys(current.content, {
+                        externalIds: union.ids,
+                        webDomains: union.domains,
+                        ...(union.addRefs.length > 0 ? { externalRefs: union.refs } : {}),
+                        lastUpdated: now.toISOString(),
+                    });
+                    reason = union.conflicts.length > 0
+                        ? "external_id_conflict"
+                        : !patched.ok
+                            ? "merge_invalid"
+                            : current.changed || patched.changed
+                                ? "not_merged"
+                                : current.leftover > 0
+                                    ? "unmerged_body"
+                                    : inbound.length > 0
+                                        ? "linked"
+                                        : refs.length > 0
+                                            ? "signal_refs"
+                                            : null;
+                }
+            }
+            if (reason)
+                out.notReady.set(pair.copy, reason);
+        }
+        out.plans.push(entry);
+    }
+    return out;
+}
+function writeEntity(hqRoot, company, rel, content, now) {
+    // Outbox first: sync pushes an entity file only when its bytes match.
+    const write = { rel, content };
+    recordOutbox(hqRoot, company, [write], now);
+    safeWriteFile(hqRoot, [entitiesRoot(company)], path.join(company.dir, rel), content);
+}
+/**
+ * Plan, merge or delete numbered copies for one company. The dry run writes
+ * nothing; merge writes entity files only; delete removes vault keys and
+ * local copy files only.
+ */
+export async function mergeCopies(options) {
+    const { hqRoot, company, mode, now } = options;
+    const index = buildEntityIndex(company.dir);
+    const pairKind = options.pairKind ?? "numbered";
+    if (pairKind === "listed" && !options.only)
+        throw new Error("merge-copies: listed pairs need an only list");
+    const found = pairKind === "listed"
+        ? findListedPairs(index, options.only)
+        : pairKind === "variants"
+            ? findVariantPairs(index)
+            : findCopyPairs(index);
+    const listed = options.only
+        ? found.pairs.filter((pair) => options.only.some((entry) => entry.copy === pair.copy && entry.original === pair.original))
+        : found.pairs;
+    const pairs = options.limit !== undefined ? listed.slice(0, Math.max(0, options.limit)) : listed;
+    const before = scanLinks(company).broken;
+    const rewriteRefs = options.rewriteRefs === true;
+    const resolutions = new Map();
+    for (const entry of options.only ?? []) {
+        if (entry.resolve_external_ids)
+            resolutions.set(entry.copy, entry.resolve_external_ids);
+    }
+    const { plans, merges, finals, notReady } = plan(company, index, pairs, found.pairs, now, rewriteRefs, resolutions);
+    const report = {
+        company: company.slug,
+        mode,
+        pair_kind: pairKind,
+        duplicate_groups_before: findDuplicateGroups(index).length,
+        duplicate_groups_after: 0,
+        copies_found: found.pairs.length,
+        plans,
+        skipped: options.only
+            ? [
+                ...found.skipped,
+                ...found.pairs
+                    .filter((pair) => !listed.includes(pair))
+                    .map((pair) => ({ copy: pair.copy, reason: "not_listed" })),
+            ]
+            : found.skipped,
+        ...(options.only
+            ? {
+                only_unmatched: options.only.filter((entry) => !found.pairs.some((pair) => pair.copy === entry.copy && pair.original === entry.original)),
+            }
+            : {}),
+        merged: [],
+        relinked: [],
+        ...(rewriteRefs ? { rewritten: [] } : {}),
+        deleted: [],
+        vault_already_absent: [],
+        not_ready: [],
+        errors: [],
+        broken_links_before: before,
+        broken_links_after: before,
+        brief_links_to_copies: briefLinks(company, new Set(pairs.map((pair) => pair.copy))),
+    };
+    if (mode === "merge") {
+        // Originals first, once each with every copy merged in; then links, read
+        // back from disk so a relinked original keeps its merge.
+        for (const [original, content] of finals) {
+            try {
+                if (content === read(company, original))
+                    continue;
+                writeEntity(hqRoot, company, original, content, now);
+                report.merged.push(original);
+            }
+            catch (error) {
+                report.errors.push({ path: original, error: error.name });
+            }
+        }
+        for (const entry of plans) {
+            if (!merges.has(entry.copy))
+                continue;
+            const copyId = rewriteRefs ? frontMatterId(read(company, entry.copy)) : null;
+            const originalId = rewriteRefs ? frontMatterId(read(company, entry.original)) : null;
+            for (const rel of entry.inbound_links) {
+                try {
+                    const content = read(company, rel);
+                    if (!rewriteRefs) {
+                        const next = relink(rel, content, entry.copy, entry.original);
+                        if (next === content)
+                            continue;
+                        writeEntity(hqRoot, company, rel, next, now);
+                        if (!report.relinked.includes(rel))
+                            report.relinked.push(rel);
+                        continue;
+                    }
+                    const next = rel.startsWith("ontology/entities/")
+                        ? rewriteRelRefs(rel, relink(rel, content, entry.copy, entry.original), entry.copy, entry.original)
+                        : rewriteOtherFile(rel, content, entry.copy, entry.original, copyId, originalId);
+                    if (next === content)
+                        continue;
+                    if (referencesCopy(rel, next, entry.copy)) {
+                        report.errors.push({ path: rel, error: "link_not_rewritten" });
+                        continue;
+                    }
+                    if (rel.startsWith("ontology/entities/")) {
+                        writeEntity(hqRoot, company, rel, next, now);
+                        if (!report.relinked.includes(rel))
+                            report.relinked.push(rel);
+                    }
+                    else {
+                        safeWriteFile(hqRoot, [company.dir], path.join(company.dir, rel), next);
+                        if (!report.rewritten.includes(rel))
+                            report.rewritten.push(rel);
+                    }
+                }
+                catch (error) {
+                    report.errors.push({ path: rel, error: error.name });
+                }
+            }
+        }
+    }
+    if (mode === "delete") {
+        if (!options.deleteVaultKey)
+            throw new Error("merge-copies: delete needs a vault client");
+        for (const entry of plans) {
+            const reason = entry.held ?? notReady.get(entry.copy) ?? null;
+            if (reason) {
+                report.not_ready.push({ copy: entry.copy, reason });
+                continue;
+            }
+            try {
+                const deleted = await options.deleteVaultKey(entry.copy);
+                // 0 means the exact key is already gone (a run that stopped before the
+                // local removal, or a copy that never synced): finish the local side.
+                if (deleted !== 1 && deleted !== 0) {
+                    report.errors.push({ path: entry.copy, error: `vault_deleted_${deleted}` });
+                    continue;
+                }
+                fs.rmSync(path.join(company.dir, entry.copy), { force: true });
+                report.deleted.push(entry.copy);
+                if (deleted === 0)
+                    report.vault_already_absent.push(entry.copy);
+            }
+            catch (error) {
+                report.errors.push({ path: entry.copy, error: error.message || error.name });
+            }
+        }
+    }
+    const after = buildEntityIndex(company.dir);
+    report.duplicate_groups_after = findDuplicateGroups(after).length;
+    report.broken_links_after = scanLinks(company).broken;
+    return report;
+}
+//# sourceMappingURL=merge-copies.js.map