@indigoai-us/hq-cli 5.271.0 → 5.272.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [5.272.0] — 2026-09-28
+
+### Added
+
+- Add `hq core ontology merge-copies`, gated by
+  `checkpoint.ontology.merge-copies`. It merges each `<name> N.md` entity copy
+  into its own original (aliases, back-references, relationship links and
+  signal count), repoints links to the copy, and with `--delete` removes merged
+  copies from the vault. Dry run by default.
+
 ## [5.271.0] — 2026-09-28
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -5148,6 +5148,33 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "HQ installation to operate on";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "merge-copies";
+            readonly description: "Merge '<name> N.md' entity copies into their original, then delete them from the vault (dry run by default)";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--company <slug>";
+                readonly description: "company to change";
+            }, {
+                readonly flags: "--apply";
+                readonly description: "merge each copy into its original and re-point links (writes entity files)";
+            }, {
+                readonly flags: "--delete";
+                readonly description: "delete fully merged copies from the vault by exact key (after sync pushed the merge)";
+            }, {
+                readonly flags: "--limit <n>";
+                readonly description: "handle at most this many copies";
+            }, {
+                readonly flags: "--json";
+                readonly description: "print JSON";
+            }, {
+                readonly flags: "--hq-root <path>";
+                readonly description: "HQ installation to operate on";
+            }];
+            readonly subcommands: readonly [];
         }, {
             readonly name: "apply";
             readonly description: "Validate the run's entity candidates and write them to the payload company";

package/dist/command-catalog.generated.js

@@ -6657,6 +6657,41 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "merge-copies",
+                        "description": "Merge '<name> N.md' entity copies into their original, then delete them from the vault (dry run by default)",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--company <slug>",
+                                "description": "company to change"
+                            },
+                            {
+                                "flags": "--apply",
+                                "description": "merge each copy into its original and re-point links (writes entity files)"
+                            },
+                            {
+                                "flags": "--delete",
+                                "description": "delete fully merged copies from the vault by exact key (after sync pushed the merge)"
+                            },
+                            {
+                                "flags": "--limit <n>",
+                                "description": "handle at most this many copies"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "print JSON"
+                            },
+                            {
+                                "flags": "--hq-root <path>",
+                                "description": "HQ installation to operate on"
+                            }
+                        ],
+                        "subcommands": []
+                    },
                     {
                         "name": "apply",
                         "description": "Validate the run's entity candidates and write them to the payload company",

package/dist/commands/core-ontology.d.ts

@@ -9,12 +9,15 @@
  */
 import { Command } from "commander";
 import { type FlagReader } from "../lib/checkpoint-ontology/plan.js";
+import { type DeleteVaultKey } from "../lib/checkpoint-ontology/merge-copies.js";
 export declare const ONTOLOGY_PAYLOAD_FILE = "payload.json";
 /** The hq-flags read, scoped to the payload company. */
 export declare const registryFlagReader: FlagReader;
 export interface OntologyCommandDeps {
     readFlag?: FlagReader;
     now?: () => Date;
+    /** Builds the exact-key vault delete for a company uid. */
+    vaultDeleter?: (companyUid: string) => Promise<DeleteVaultKey>;
 }
 export declare function runOntologyPlan(hqRoot: string, runDirOption: string | undefined, deps?: OntologyCommandDeps): Promise<string>;
 export declare function runOntologyApply(hqRoot: string, runDirOption: string | undefined, deps?: OntologyCommandDeps): string;
@@ -24,5 +27,18 @@ export declare function runOntologyApply(hqRoot: string, runDirOption: string |
  * `checkpoint.ontology.multi-writer`.
  */
 export declare function runOntologyDuplicates(hqRoot: string, slug: string | undefined, json: boolean, deps?: OntologyCommandDeps): Promise<string>;
+export interface MergeCopiesCommandOptions {
+    apply?: boolean;
+    delete?: boolean;
+    limit?: number;
+    json?: boolean;
+}
+/**
+ * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
+ * original (`--apply`), then delete merged copies from the vault
+ * (`--delete`). Without either it only reports. Gated by
+ * `checkpoint.ontology.merge-copies` and `checkpoint.ontology.multi-writer`.
+ */
+export declare function runOntologyMergeCopies(hqRoot: string, slug: string | undefined, options: MergeCopiesCommandOptions, deps?: OntologyCommandDeps): Promise<string>;
 export declare function registerCoreOntologyCommand(core: Command): void;
 //# sourceMappingURL=core-ontology.d.ts.map

package/dist/commands/core-ontology.js

@@ -16,6 +16,9 @@ import { applyOntologyRun, ApplyError } from "../lib/checkpoint-ontology/apply.j
 import { resolveOntologyCompany, WriteBoundsError } from "../lib/checkpoint-ontology/company.js";
 import { findDuplicateGroups, summarizeMergeBack, } from "../lib/checkpoint-ontology/multi-writer.js";
 import { buildEntityIndex } from "../lib/checkpoint-ontology/tree.js";
+import { MERGE_COPIES_FLAG, mergeCopies, } from "../lib/checkpoint-ontology/merge-copies.js";
+import { callDeleteEndpoint } from "./files.js";
+import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 export const ONTOLOGY_PAYLOAD_FILE = "payload.json";
 class OntologyUsageError extends Error {
 }
@@ -124,6 +127,72 @@ export async function runOntologyDuplicates(hqRoot, slug, json, deps = {}) {
     }
     return lines.join("\n");
 }
+/** Delete one exact company vault key, refusing when the server would match anything else. */
+async function companyVaultDeleter(companyUid) {
+    const token = (await resolveVaultCredential()).token;
+    return async (key) => {
+        const preview = await callDeleteEndpoint({ token, companyUid, prefix: key, dryRun: true });
+        if (preview.matched === 0)
+            return 0;
+        if (preview.matched !== 1 || preview.keys.length !== 1 || preview.keys[0] !== key) {
+            throw new Error(`vault preview matched ${preview.matched} object(s), not exactly ${key}`);
+        }
+        return (await callDeleteEndpoint({ token, companyUid, prefix: key, dryRun: false })).deleted;
+    };
+}
+function mergeCopiesSummary(report) {
+    const held = report.plans.filter((plan) => plan.held).length;
+    const lines = [
+        `ontology merge-copies (${report.mode.replace("_", " ")}) in ${report.company}: ${report.plans.length} of ${report.copies_found} copies, ${held} held, ${report.skipped.length} skipped`,
+        `  merged ${report.merged.length}, relinked ${report.relinked.length}, deleted ${report.deleted.length}, not ready ${report.not_ready.length}, errors ${report.errors.length}`,
+        `  duplicate groups ${report.duplicate_groups_before} -> ${report.duplicate_groups_after}; broken entity links ${report.broken_links_before} -> ${report.broken_links_after}`,
+    ];
+    for (const plan of report.plans.filter((entry) => entry.held))
+        lines.push(`  held ${plan.copy}: ${plan.held}`);
+    for (const error of report.errors)
+        lines.push(`  error ${error.path}: ${error.error}`);
+    return lines.join("\n");
+}
+/**
+ * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
+ * original (`--apply`), then delete merged copies from the vault
+ * (`--delete`). Without either it only reports. Gated by
+ * `checkpoint.ontology.merge-copies` and `checkpoint.ontology.multi-writer`.
+ */
+export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
+    if (options.apply && options.delete) {
+        throw new OntologyUsageError("ontology: run --apply first, let sync push the merged files, then run --delete");
+    }
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1)) {
+        throw new OntologyUsageError("ontology: --limit must be a positive whole number");
+    }
+    const resolution = resolveOntologyCompany(hqRoot, slug);
+    if (!resolution.ok)
+        throw new OntologyUsageError(`ontology: company rejected: ${resolution.reason}`);
+    const company = resolution.company;
+    const readFlag = deps.readFlag ?? registryFlagReader;
+    for (const flag of [MERGE_COPIES_FLAG, MULTI_WRITER_FLAG]) {
+        if (!(await readFlag(flag, company))) {
+            return options.json ? JSON.stringify({ company: company.slug, skipped: `${flag} off` }) : `ontology merge-copies: skipped (${flag} is off)`;
+        }
+    }
+    const mode = options.apply ? "merge" : options.delete ? "delete" : "dry_run";
+    let deleteVaultKey;
+    if (mode === "delete") {
+        if (!company.cloudUid)
+            throw new OntologyUsageError("ontology: the company has no cloud_uid in the manifest");
+        deleteVaultKey = await (deps.vaultDeleter ?? companyVaultDeleter)(company.cloudUid);
+    }
+    const report = await mergeCopies({
+        hqRoot,
+        company,
+        mode,
+        now: deps.now?.() ?? new Date(),
+        ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(deleteVaultKey ? { deleteVaultKey } : {}),
+    });
+    return options.json ? JSON.stringify(report, null, 2) : mergeCopiesSummary(report);
+}
 function fail(error) {
     if (error instanceof OntologyUsageError || error instanceof ApplyError || error instanceof WriteBoundsError) {
         process.stderr.write(`${error.message}\n`);
@@ -163,6 +232,23 @@ export function registerCoreOntologyCommand(core) {
             fail(error);
         }
     });
+    ontology
+        .command("merge-copies")
+        .description("Merge '<name> N.md' entity copies into their original, then delete them from the vault (dry run by default)")
+        .requiredOption("--company <slug>", "company to change")
+        .option("--apply", "merge each copy into its original and re-point links (writes entity files)")
+        .option("--delete", "delete fully merged copies from the vault by exact key (after sync pushed the merge)")
+        .option("--limit <n>", "handle at most this many copies", (value) => Number(value))
+        .option("--json", "print JSON")
+        .option("--hq-root <path>", "HQ installation to operate on")
+        .action(async (options) => {
+        try {
+            process.stdout.write(`${await runOntologyMergeCopies(rootFor(options), options.company, options)}\n`);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
     ontology
         .command("apply")
         .description("Validate the run's entity candidates and write them to the payload company")

package/dist/commands/files.d.ts

@@ -62,6 +62,22 @@ export declare class FilesDeleteHttpError extends Error {
 export declare function formatFilesDeleteError(err: FilesDeleteHttpError, prefix: string): string;
 /** Injectable yes/no confirmation seam (stubbed in tests). */
 export type ConfirmFn = (message: string) => Promise<boolean>;
+/**
+ * POST /v1/files/delete. Throws FilesDeleteHttpError on any non-2xx so the one
+ * caller renders a single consistent error path.
+ *
+ * Scope is EITHER a company vault (`companyUid` set) OR the caller's personal
+ * vault (`personal: true`). For the personal case the server resolves the target
+ * person + bucket from the authenticated caller — we send NO uid, just the
+ * `personal` flag — so there is nothing for the client to get wrong or spoof.
+ */
+export declare function callDeleteEndpoint(params: {
+    token: string;
+    companyUid?: string;
+    personal?: boolean;
+    prefix: string;
+    dryRun: boolean;
+}): Promise<FilesDeleteResponse>;
 interface RunFilesDeleteParams {
     prefix: string;
     dryRun: boolean;

package/dist/commands/files.js

@@ -879,7 +879,7 @@ function realConfirm(message) {
  * person + bucket from the authenticated caller — we send NO uid, just the
  * `personal` flag — so there is nothing for the client to get wrong or spoof.
  */
-async function callDeleteEndpoint(params) {
+export async function callDeleteEndpoint(params) {
     const res = await vaultApiFetch({
         token: params.token,
         path: "/v1/files/delete",

package/dist/lib/checkpoint-ontology/merge-copies.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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.
+ */
+import { type OntologyCompany } from "./company.js";
+import { type EntityIndex } from "./tree.js";
+export declare const MERGE_COPIES_FLAG = "checkpoint.ontology.merge-copies";
+export type CopySkipReason = "no_original" | "original_invalid" | "identity_differs" | "not_in_duplicate_group";
+export interface CopySkip {
+    copy: string;
+    reason: CopySkipReason;
+}
+export interface CopyPair {
+    type: string;
+    /** Company-relative path of the copy. */
+    copy: string;
+    /** Company-relative path of the original it merges into. */
+    original: string;
+}
+export interface CopyPlan extends CopyPair {
+    add_aliases: string[];
+    /** Copy names the original lacks that another entity already holds, so they do not move. */
+    dropped_aliases: string[];
+    add_backrefs: number;
+    add_relationship_lines: number;
+    /** The copy's higher `signal_count`, when it is higher. */
+    raise_signal_count?: number;
+    /** Keys the checkpoint does not own whose values differ; the original's value stays. */
+    kept_original_keys: string[];
+    /** Entity files that link to the copy. */
+    inbound_links: string[];
+    /** Signal files whose `entity_refs` name the copy. */
+    signal_refs: string[];
+    /** Why the copy cannot be merged or deleted from here. */
+    held?: "signal_refs" | "linked_from_unwritable" | "merge_invalid";
+    detail?: string;
+    /** Body lines of the copy the merged original lacks; a copy with any is never deleted. */
+    unmerged_body_lines: number;
+}
+export interface MergeCopiesReport {
+    company: string;
+    mode: "dry_run" | "merge" | "delete";
+    duplicate_groups_before: number;
+    duplicate_groups_after: number;
+    copies_found: number;
+    plans: CopyPlan[];
+    skipped: CopySkip[];
+    merged: string[];
+    relinked: string[];
+    deleted: string[];
+    /** Deleted copies the vault no longer had (a resumed run, or never synced). */
+    vault_already_absent: string[];
+    /** Copies still carrying content, links or refs, so not deleted this run. */
+    not_ready: {
+        copy: string;
+        reason: string;
+    }[];
+    errors: {
+        path: string;
+        error: string;
+    }[];
+    /** Entity-file links whose target file does not exist. */
+    broken_links_before: number;
+    broken_links_after: number;
+    /** Links in `company-brief.md` to a copy; the brief is re-rendered by the next checkpoint. */
+    brief_links_to_copies: string[];
+}
+/** Deletes one exact vault key; resolves to the number of objects deleted. */
+export type DeleteVaultKey = (key: string) => Promise<number>;
+export interface MergeCopiesOptions {
+    hqRoot: string;
+    company: OntologyCompany;
+    mode: "dry_run" | "merge" | "delete";
+    /** Handle at most this many copies (sorted by path). */
+    limit?: number;
+    now: Date;
+    deleteVaultKey?: DeleteVaultKey;
+}
+/** Copies in scope, and the ones skipped with a reason. Read-only. */
+export declare function findCopyPairs(index: EntityIndex): {
+    pairs: CopyPair[];
+    skipped: CopySkip[];
+};
+/**
+ * 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 declare function mergeCopies(options: MergeCopiesOptions): Promise<MergeCopiesReport>;
+//# sourceMappingURL=merge-copies.d.ts.map

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

@@ -0,0 +1,521 @@
+/**
+ * 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.
+ */
+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 } 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";
+/** `<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;
+}
+/** Relationship lines of the copy that the original lacks (back-references excluded). */
+function missingRelationshipLines(originalContent, copyContent) {
+    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))
+            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 };
+}
+/** 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 ?? []) {
+            const copy = byRef.get(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})`;
+    });
+}
+/**
+ * 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);
+    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()) ?? []);
+    const leftover = (splitBody(copyContent)?.body.split(/\r?\n/) ?? [])
+        .map((line) => line.trim())
+        .filter((line) => line !== "" && !have.has(line)).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) {
+    const links = scanLinks(company);
+    const copies = new Set(allPairs.map((pair) => pair.copy));
+    const other = scanOtherLinks(company, copies);
+    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);
+        const merged = mergeCopy(index, pair, siblings, out.finals.get(pair.original) ?? onDisk, copyContent, now);
+        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,
+        };
+        const unwritable = inbound.filter((rel) => !rel.startsWith("ontology/entities/") || !isWritableEntityType(rel.split("/")[2]) || copies.has(rel));
+        if (typeof merged === "string") {
+            entry.held = "merge_invalid";
+            entry.detail = merged;
+        }
+        else if (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);
+            const reason = typeof current === "string"
+                ? "merge_invalid"
+                : current.changed
+                    ? "not_merged"
+                    : current.leftover > 0
+                        ? "unmerged_body"
+                        : inbound.length > 0
+                            ? "linked"
+                            : 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 found = findCopyPairs(index);
+    const pairs = options.limit !== undefined ? found.pairs.slice(0, Math.max(0, options.limit)) : found.pairs;
+    const before = scanLinks(company).broken;
+    const { plans, merges, finals, notReady } = plan(company, index, pairs, found.pairs, now);
+    const report = {
+        company: company.slug,
+        mode,
+        duplicate_groups_before: findDuplicateGroups(index).length,
+        duplicate_groups_after: 0,
+        copies_found: found.pairs.length,
+        plans,
+        skipped: found.skipped,
+        merged: [],
+        relinked: [],
+        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;
+            for (const rel of entry.inbound_links) {
+                try {
+                    const content = read(company, rel);
+                    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);
+                }
+                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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.271.0",
+  "version": "5.272.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {