@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/checkpoint-ontology/multi-writer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Several checkpoint writers in one company vault (design section 20).
+ *
+ * Gated by `checkpoint.ontology.multi-writer`. Three parts:
+ *
+ * - The outbox records the exact bytes this machine's checkpoint wrote to
+ *   each entity file. Sync pushes an entity file only when it still matches
+ *   its outbox entry, so an old pulled copy is never uploaded (C1, C2).
+ * - Merge-back re-applies the monotone part of an entity version that sync
+ *   set aside after losing a push race (C3, C4). A version whose entity was
+ *   deleted stays aside (C6); one that differs in keys the checkpoint does
+ *   not own is merged for the owned keys and also stays aside (C8).
+ * - The duplicate scan reports entities of one type whose names collide, with
+ *   a proposed survivor. Nothing is deleted (C5, C7).
+ */
+import { type OntologyCompany } from "./company.js";
+import { type SignalBackRef } from "./entity-file.js";
+import { type EntityIndex } from "./tree.js";
+declare const OUTBOX_SCHEMA = "hq-ontology-outbox.v1";
+export declare const MERGED_BACKUPS_DIR = ".hq/conflict-backups/ontology-merged";
+interface OutboxEntry {
+    sha256: string;
+    written_at: string;
+}
+export interface Outbox {
+    schema: typeof OUTBOX_SCHEMA;
+    company: string;
+    entries: Record<string, OutboxEntry>;
+}
+export interface OutboxWrite {
+    /** Company-relative vault key, `ontology/entities/<type>/<file>.md`. */
+    rel: string;
+    content: string;
+}
+export declare function outboxPath(hqRoot: string, company: OntologyCompany): string;
+/** The company's outbox. A missing file is an empty outbox; an unreadable one throws. */
+export declare function readOutbox(hqRoot: string, company: OntologyCompany): Outbox;
+/**
+ * Record entity bytes this checkpoint wrote, and drop entries older than the
+ * retention window. An unreadable outbox is replaced: a lost entry only makes
+ * sync hold that file back, which is the safe direction.
+ */
+export declare function recordOutbox(hqRoot: string, company: OntologyCompany, writes: OutboxWrite[], now: Date): {
+    reset: boolean;
+};
+type MergeBackResult = "merged" | "kept_both" | "stale" | "deleted" | "identity_conflict" | "invalid" | "write_error";
+export interface MergeBackOutcome {
+    /** HQ-relative path of the set-aside version. */
+    backup: string;
+    /** Company-relative entity file it belongs to. */
+    target: string;
+    result: MergeBackResult;
+    /** For `kept_both`, the keys that differ (`body` for prose); for `invalid` and `write_error`, the reason. */
+    detail?: string;
+}
+/** Back-reference lines in a body, as refs `appendBackRefs` can re-add. */
+export declare function readBackRefs(body: string): SignalBackRef[];
+export interface MergeBackRun {
+    outcomes: MergeBackOutcome[];
+    /** Entity files rewritten; each was recorded in the outbox before it was written. */
+    writes: OutboxWrite[];
+    outbox_reset?: true;
+}
+/**
+ * Re-apply set-aside entity versions of this company to the current files
+ * (design 20.4). Never deletes an entity file and never re-creates one.
+ */
+export declare function mergeBackConflicts(hqRoot: string, company: OntologyCompany, now: Date): MergeBackRun;
+export interface DuplicateGroup {
+    type: string;
+    /** `same_name`: equal canonical names, or one's canonical name is the other's unshared alias. `similar_name`: canonical names match once spaces are removed. */
+    reason: "same_name" | "similar_name";
+    paths: string[];
+    /** Highest `signal_count`, then earliest `first_seen`, then a file that is not a numbered copy (`<slug> 2.md`), then path. */
+    survivor: string;
+}
+export interface DuplicateReport {
+    groups: number;
+    shown: DuplicateGroup[];
+}
+/** Groups of writable entities of one type whose names collide. Read-only. */
+export declare function findDuplicateGroups(index: EntityIndex): DuplicateGroup[];
+/** The duplicate scan for a company, capped for the apply report. */
+export declare function scanDuplicates(company: OntologyCompany, limit?: number): DuplicateReport;
+export interface MultiWriterStart {
+    merge_back: MergeBackOutcome[];
+    /** Why merge-back or the outbox write stopped, when it did. */
+    error?: string;
+    outbox_reset?: true;
+}
+/**
+ * The start of a checkpoint run: merge back set-aside versions (each merged
+ * file is recorded in the outbox before it is written). Runs in `plan`, so a
+ * run with no changed inputs still merges. Errors are returned, not thrown,
+ * so the rest of the checkpoint goes on.
+ */
+export declare function startMultiWriterRun(hqRoot: string, company: OntologyCompany, now: Date): MultiWriterStart;
+/** Count merge-back outcomes by result, for one-line summaries. */
+export declare function summarizeMergeBack(outcomes: MergeBackOutcome[]): string;
+export {};
+//# sourceMappingURL=multi-writer.d.ts.map

package/dist/lib/checkpoint-ontology/multi-writer.js

@@ -0,0 +1,394 @@
+/**
+ * Several checkpoint writers in one company vault (design section 20).
+ *
+ * Gated by `checkpoint.ontology.multi-writer`. Three parts:
+ *
+ * - The outbox records the exact bytes this machine's checkpoint wrote to
+ *   each entity file. Sync pushes an entity file only when it still matches
+ *   its outbox entry, so an old pulled copy is never uploaded (C1, C2).
+ * - Merge-back re-applies the monotone part of an entity version that sync
+ *   set aside after losing a push race (C3, C4). A version whose entity was
+ *   deleted stays aside (C6); one that differs in keys the checkpoint does
+ *   not own is merged for the owned keys and also stays aside (C8).
+ * - The duplicate scan reports entities of one type whose names collide, with
+ *   a proposed survivor. Nothing is deleted (C5, C7).
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { entityKey, freshAliases, ownNames } from "./aliases.js";
+import { entitiesRoot, safeWriteFile } from "./company.js";
+import { appendBackRefs, OWNED_KEYS, parseEntityFile, patchEntityFile, validateEntityFrontmatter, } from "./entity-file.js";
+import { isWritableEntityType, squash } from "./identity.js";
+import { buildEntityIndex, indexAlias } from "./tree.js";
+const OUTBOX_SCHEMA = "hq-ontology-outbox.v1";
+const OUTBOX_DIR = ".hq/ontology-outbox";
+const OUTBOX_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Where sync parks a losing local body (hq-cloud `CONFLICT_BACKUPS_DIR`). */
+const CONFLICT_BACKUPS_DIR = ".hq/conflict-backups";
+export const MERGED_BACKUPS_DIR = ".hq/conflict-backups/ontology-merged";
+const STALE_BACKUP_MS = 7 * 24 * 60 * 60 * 1000;
+const DUPLICATE_REPORT_LIMIT = 20;
+/**
+ * Keys that differ between two versions of a new entity for reasons that say
+ * nothing about its content. The vault's value stands and the difference is
+ * not reported.
+ */
+const IGNORED_ON_MERGE = new Set(["first_seen"]);
+/** hq-cloud `buildConflictBackupPath`: `<file>.md.<YYYY-MM-DDTHH-MM-SSZ>-<machine>.md`. */
+const BACKUP_NAME_RE = /^(.+\.md)\.(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z)-([a-f0-9]+|unknown)\.md$/;
+const TYPE_DIR_RE = /^[a-z][a-z0-9-]*$/;
+/** One back-reference line, as `appendBackRefs` and the gardener write it. */
+const BACKREF_LINE_RE = /^- Referenced in \[([A-Za-z_]+): (.*)\]\(([^)\s]+)\)\s*$/;
+function sha256(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+export function outboxPath(hqRoot, company) {
+    return path.join(hqRoot, ...OUTBOX_DIR.split("/"), `${company.slug}.json`);
+}
+/** The company's outbox. A missing file is an empty outbox; an unreadable one throws. */
+export function readOutbox(hqRoot, company) {
+    const empty = { schema: OUTBOX_SCHEMA, company: company.slug, entries: {} };
+    let raw;
+    try {
+        raw = fs.readFileSync(outboxPath(hqRoot, company), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return empty;
+        throw error;
+    }
+    const doc = JSON.parse(raw);
+    if (doc.schema !== OUTBOX_SCHEMA || doc.company !== company.slug || !doc.entries || typeof doc.entries !== "object") {
+        throw new Error("outbox has an unexpected shape");
+    }
+    return { schema: OUTBOX_SCHEMA, company: company.slug, entries: doc.entries };
+}
+/**
+ * Record entity bytes this checkpoint wrote, and drop entries older than the
+ * retention window. An unreadable outbox is replaced: a lost entry only makes
+ * sync hold that file back, which is the safe direction.
+ */
+export function recordOutbox(hqRoot, company, writes, now) {
+    let outbox;
+    let reset = false;
+    try {
+        outbox = readOutbox(hqRoot, company);
+    }
+    catch {
+        outbox = { schema: OUTBOX_SCHEMA, company: company.slug, entries: {} };
+        reset = true;
+    }
+    const cutoff = now.getTime() - OUTBOX_RETENTION_MS;
+    const entries = {};
+    for (const [rel, entry] of Object.entries(outbox.entries)) {
+        const at = Date.parse(entry?.written_at ?? "");
+        if (typeof entry?.sha256 === "string" && Number.isFinite(at) && at >= cutoff)
+            entries[rel] = entry;
+    }
+    for (const write of writes)
+        entries[write.rel] = { sha256: sha256(write.content), written_at: now.toISOString() };
+    const sorted = Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)));
+    const doc = { schema: OUTBOX_SCHEMA, company: company.slug, entries: sorted };
+    safeWriteFile(hqRoot, [path.join(hqRoot, ...OUTBOX_DIR.split("/"))], outboxPath(hqRoot, company), `${JSON.stringify(doc, null, 2)}\n`);
+    return { reset };
+}
+/** A directory that exists and is not a symlink. */
+function isRealDir(dir) {
+    try {
+        return fs.lstatSync(dir).isDirectory();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/** Set-aside entity versions of this company, oldest first per entity. */
+function listEntityBackups(hqRoot, company) {
+    const segments = [...CONFLICT_BACKUPS_DIR.split("/"), "companies", company.slug, "ontology", "entities"];
+    for (let i = 1; i <= segments.length; i += 1) {
+        if (!isRealDir(path.join(hqRoot, ...segments.slice(0, i))))
+            return [];
+    }
+    const root = path.join(hqRoot, ...segments);
+    const out = [];
+    for (const typeDir of fs.readdirSync(root, { withFileTypes: true })) {
+        // Other entity types (contacts, deals) belong to other writers.
+        if (!typeDir.isDirectory() || !TYPE_DIR_RE.test(typeDir.name) || !isWritableEntityType(typeDir.name))
+            continue;
+        for (const file of fs.readdirSync(path.join(root, typeDir.name), { withFileTypes: true })) {
+            const match = file.isFile() ? BACKUP_NAME_RE.exec(file.name) : null;
+            if (!match)
+                continue;
+            out.push({
+                full: path.join(root, typeDir.name, file.name),
+                hqRel: [...segments, typeDir.name, file.name].join("/"),
+                target: `ontology/entities/${typeDir.name}/${match[1]}`,
+                stampedAt: match[2],
+            });
+        }
+    }
+    return out.sort((a, b) => a.target.localeCompare(b.target) || a.stampedAt.localeCompare(b.stampedAt) || a.hqRel.localeCompare(b.hqRel));
+}
+/** The later of two ISO timestamps; an unparseable one loses. */
+function later(a, b) {
+    const ta = Date.parse(a);
+    const tb = Date.parse(b);
+    if (!Number.isFinite(ta))
+        return b;
+    if (!Number.isFinite(tb))
+        return a;
+    return tb > ta ? b : a;
+}
+/** Back-reference lines in a body, as refs `appendBackRefs` can re-add. */
+export function readBackRefs(body) {
+    const out = [];
+    for (const line of body.split(/\r?\n/)) {
+        const match = BACKREF_LINE_RE.exec(line);
+        if (match)
+            out.push({ signalType: match[1], preview: match[2], href: match[3] });
+    }
+    return out;
+}
+/** The body with back-reference lines and blank lines removed, for comparing prose. */
+function proseOf(body) {
+    return body
+        .split(/\r?\n/)
+        .filter((line) => !BACKREF_LINE_RE.test(line) && !/^##\s+Relationships\s*$/.test(line))
+        .map((line) => line.trimEnd())
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/** Keys the checkpoint does not own whose values differ, plus `body` for prose. */
+function unownedDifferences(backup, current) {
+    const keys = [...new Set([...Object.keys(backup.frontmatter), ...Object.keys(current.frontmatter)])].sort();
+    const out = keys.filter((key) => !OWNED_KEYS.has(key) && !IGNORED_ON_MERGE.has(key) && !isDeepStrictEqual(backup.frontmatter[key], current.frontmatter[key]));
+    if (proseOf(backup.body) !== proseOf(current.body))
+        out.push("body");
+    return out;
+}
+/**
+ * Re-apply set-aside entity versions of this company to the current files
+ * (design 20.4). Never deletes an entity file and never re-creates one.
+ */
+export function mergeBackConflicts(hqRoot, company, now) {
+    const run = { outcomes: [], writes: [] };
+    const backups = listEntityBackups(hqRoot, company);
+    if (backups.length === 0)
+        return run;
+    const index = buildEntityIndex(company.dir);
+    const entityRoot = entitiesRoot(company);
+    for (const backup of backups) {
+        const outcome = (result, detail) => run.outcomes.push({ backup: backup.hqRel, target: backup.target, result, ...(detail ? { detail } : {}) });
+        const saved = parseEntityFile(fs.readFileSync(backup.full, "utf8"));
+        const savedFields = saved ? validateEntityFrontmatter(saved.frontmatter) : "unparseable";
+        if (!saved || typeof savedFields === "string") {
+            outcome("invalid", `backup:${savedFields}`);
+            continue;
+        }
+        const savedUpdated = String(saved.frontmatter.last_updated);
+        const savedAt = Date.parse(savedUpdated);
+        if (!Number.isFinite(savedAt)) {
+            outcome("invalid", "backup:last_updated");
+            continue;
+        }
+        if (now.getTime() - savedAt > STALE_BACKUP_MS) {
+            outcome("stale");
+            continue;
+        }
+        const targetFull = path.join(company.dir, backup.target);
+        let targetStat;
+        try {
+            targetStat = fs.lstatSync(targetFull);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            outcome("deleted");
+            continue;
+        }
+        if (!targetStat.isFile()) {
+            outcome("invalid", "current:not_a_file");
+            continue;
+        }
+        const currentContent = fs.readFileSync(targetFull, "utf8");
+        const current = parseEntityFile(currentContent);
+        const currentFields = current ? validateEntityFrontmatter(current.frontmatter) : "unparseable";
+        if (!current || typeof currentFields === "string") {
+            outcome("invalid", `current:${currentFields}`);
+            continue;
+        }
+        if (savedFields.id !== currentFields.id || savedFields.type !== currentFields.type) {
+            outcome("identity_conflict");
+            continue;
+        }
+        if (!isWritableEntityType(currentFields.type)) {
+            outcome("invalid", "current:type_not_checkpoint_owned");
+            continue;
+        }
+        const differences = unownedDifferences(saved, current);
+        const type = currentFields.type;
+        const aliases = index.byRel.has(backup.target)
+            ? freshAliases(index, type, backup.target, ownNames(index, backup.target, []), savedFields.aliases)
+            : [];
+        const withRefs = appendBackRefs(currentContent, readBackRefs(saved.body));
+        const currentUpdated = String(current.frontmatter.last_updated);
+        const lastUpdated = later(currentUpdated, savedUpdated);
+        const patched = patchEntityFile(withRefs.content, {
+            addAliases: aliases,
+            signalCount: savedFields.signal_count,
+            lastUpdated,
+            // A later timestamp alone is a change too; otherwise the merge result
+            // would depend on which version this machine holds.
+            bodyChanged: withRefs.added > 0 || lastUpdated !== currentUpdated,
+        });
+        if (!patched.ok) {
+            outcome("write_error", patched.reason);
+            continue;
+        }
+        if (patched.changed) {
+            // Outbox first: a file sync may push must never lack its entry, and a
+            // failed outbox write leaves the file and the backup for the next run.
+            try {
+                if (recordOutbox(hqRoot, company, [{ rel: backup.target, content: patched.content }], now).reset)
+                    run.outbox_reset = true;
+            }
+            catch (error) {
+                outcome("write_error", `outbox:${error.name}`);
+                continue;
+            }
+            try {
+                safeWriteFile(hqRoot, [entityRoot], targetFull, patched.content);
+            }
+            catch (error) {
+                outcome("write_error", error.name);
+                continue;
+            }
+            run.writes = run.writes.filter((write) => write.rel !== backup.target);
+            run.writes.push({ rel: backup.target, content: patched.content });
+            for (const alias of aliases)
+                indexAlias(index, type, backup.target, alias);
+            const entity = index.byRel.get(backup.target);
+            if (entity)
+                entity.aliases = [...entity.aliases, ...aliases];
+        }
+        if (differences.length > 0) {
+            outcome("kept_both", differences.join(","));
+            continue;
+        }
+        const mergedFull = path.join(hqRoot, ...MERGED_BACKUPS_DIR.split("/"), ...backup.hqRel.split("/").slice(CONFLICT_BACKUPS_DIR.split("/").length));
+        fs.mkdirSync(path.dirname(mergedFull), { recursive: true });
+        fs.renameSync(backup.full, mergedFull);
+        outcome("merged");
+    }
+    return run;
+}
+/** A copy saved next to the original file, e.g. `hq-core 2.md`. */
+const NUMBERED_COPY = / \d+\.md$/;
+/** Groups of writable entities of one type whose names collide. Read-only. */
+export function findDuplicateGroups(index) {
+    const parent = new Map();
+    const find = (rel) => {
+        let root = rel;
+        while (parent.get(root) !== root)
+            root = parent.get(root);
+        parent.set(rel, root);
+        return root;
+    };
+    const union = (rels) => {
+        const list = [...rels].filter((rel) => isWritableEntityType(index.byRel.get(rel)?.type));
+        for (const rel of list)
+            if (!parent.has(rel))
+                parent.set(rel, rel);
+        for (const rel of list.slice(1)) {
+            const a = find(list[0]);
+            const b = find(rel);
+            if (a !== b)
+                parent.set(b, a);
+        }
+    };
+    // Only the matches `resolveCandidate` treats as one entity link files: equal
+    // canonical names, or a canonical name that is exactly one other file's
+    // alias. An alias several files share (a Slack id, "hq") is ambiguous, not
+    // a duplicate, and following it chains unrelated entities together.
+    const exactPairs = new Set();
+    const sameName = (rels) => {
+        if (rels.length < 2)
+            return;
+        union(rels);
+        for (const rel of rels)
+            exactPairs.add(rel);
+    };
+    const squashed = new Map();
+    for (const [name, rels] of index.canonical) {
+        const holders = index.alias.get(name);
+        const aliasHolder = holders && holders.size === 1 ? [...holders] : [];
+        sameName([...new Set([...rels, ...aliasHolder])]);
+        const [type, normalized] = name.split("\0");
+        const squashKey = entityKey(type, squash(normalized));
+        squashed.set(squashKey, [...(squashed.get(squashKey) ?? []), ...rels]);
+    }
+    // Canonical names that match once spaces and punctuation are removed.
+    for (const rels of squashed.values())
+        if (rels.length > 1)
+            union(rels);
+    const groups = new Map();
+    for (const rel of parent.keys()) {
+        const root = find(rel);
+        groups.set(root, [...(groups.get(root) ?? []), rel]);
+    }
+    const out = [];
+    for (const members of groups.values()) {
+        if (members.length < 2)
+            continue;
+        const paths = members.sort();
+        const ranked = [...paths].sort((a, b) => {
+            const ea = index.byRel.get(a);
+            const eb = index.byRel.get(b);
+            const fa = Date.parse(ea.first_seen ?? "");
+            const fb = Date.parse(eb.first_seen ?? "");
+            return (eb.signal_count - ea.signal_count ||
+                (Number.isFinite(fa) ? fa : Infinity) - (Number.isFinite(fb) ? fb : Infinity) ||
+                Number(NUMBERED_COPY.test(a)) - Number(NUMBERED_COPY.test(b)) ||
+                a.localeCompare(b));
+        });
+        out.push({
+            type: index.byRel.get(paths[0]).type,
+            reason: paths.filter((rel) => exactPairs.has(rel)).length >= 2 ? "same_name" : "similar_name",
+            paths,
+            survivor: ranked[0],
+        });
+    }
+    return out.sort((a, b) => b.paths.length - a.paths.length || a.paths[0].localeCompare(b.paths[0]));
+}
+/** The duplicate scan for a company, capped for the apply report. */
+export function scanDuplicates(company, limit = DUPLICATE_REPORT_LIMIT) {
+    const groups = findDuplicateGroups(buildEntityIndex(company.dir));
+    return { groups: groups.length, shown: groups.slice(0, limit) };
+}
+/**
+ * The start of a checkpoint run: merge back set-aside versions (each merged
+ * file is recorded in the outbox before it is written). Runs in `plan`, so a
+ * run with no changed inputs still merges. Errors are returned, not thrown,
+ * so the rest of the checkpoint goes on.
+ */
+export function startMultiWriterRun(hqRoot, company, now) {
+    let merged;
+    try {
+        merged = mergeBackConflicts(hqRoot, company, now);
+    }
+    catch (error) {
+        return { merge_back: [], error: `merge_back:${error.name}` };
+    }
+    return { merge_back: merged.outcomes, ...(merged.outbox_reset ? { outbox_reset: true } : {}) };
+}
+/** Count merge-back outcomes by result, for one-line summaries. */
+export function summarizeMergeBack(outcomes) {
+    const counts = new Map();
+    for (const outcome of outcomes)
+        counts.set(outcome.result, (counts.get(outcome.result) ?? 0) + 1);
+    return [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([result, n]) => `${n} ${result.replaceAll("_", " ")}`).join(", ");
+}
+//# sourceMappingURL=multi-writer.js.map

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -0,0 +1,193 @@
+/**
+ * `hq core ontology plan`: pick this run's inputs.
+ *
+ * Runs in the detached checkpoint sibling. It resolves the flag, finds the
+ * company's changed knowledge and signal files with a content-hash ledger,
+ * applies the per-run budget, and writes `<runDir>/ontology-plan.json` for the
+ * backend model to read. The model only fills a candidates file; everything
+ * that affects identity, scope and cost stays in code.
+ */
+import { type CompanyBriefResult } from "./company-brief.js";
+import { type OntologyCompany } from "./company.js";
+import { type MultiWriterStart } from "./multi-writer.js";
+import { type SyncClientVersions } from "./sync-client.js";
+export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
+/**
+ * Turns the step on like `checkpoint.ontology`, but only builds that check the
+ * sync client read it (CO-45, owner decision CO-D-005). Older CLI builds read
+ * only `checkpoint.ontology`, so this key can default on without starting the
+ * step next to an hq-cloud older than 6.18.7. Either key needs a sync client of
+ * 6.18.7 or later; see ./sync-client.ts.
+ */
+export declare const ONTOLOGY_SYNC_GATED_FLAG = "checkpoint.ontology.sync-gated";
+/**
+ * Several writers in one company vault (design section 20): record written
+ * entity bytes in the outbox, merge back set-aside versions, and report
+ * duplicate entities.
+ */
+export declare const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
+/**
+ * CO-59: consume the files touched by company checkpoints that were queued
+ * behind a busy sibling (see queued-touches.ts). On, the plan adds the
+ * company's queued touches to this run's session-touched set, and a run whose
+ * own payload names no company plans the company the parent picked for it
+ * (`ontology_company`), without that run's session text. Off, queued touches
+ * wait on disk and a company-less run skips the ontology step as before.
+ */
+export declare const QUEUED_TOUCHES_FLAG = "checkpoint.ontology.queued-touches";
+export declare const PLAN_FILE = "ontology-plan.json";
+export declare const CANDIDATES_FILE = "ontology-candidates.json";
+export declare const REPORT_FILE = "ontology-report.json";
+export declare const PLAN_SCHEMA = "hq-checkpoint-ontology-plan.v1";
+export declare const CANDIDATES_SCHEMA = "hq-checkpoint-ontology-candidates.v1";
+declare const LEDGER_SCHEMA = "hq-checkpoint-ontology-ledger.v1";
+export declare const BUDGET: {
+    readonly maxInputs: 20;
+    readonly maxTokens: 60000;
+    readonly chunkTokens: 12000;
+};
+type PendingReason = "session-touched";
+interface LedgerEntry {
+    sha256: string;
+    size: number;
+    mtime_ms: number;
+    state: "seen" | "pending" | "done";
+    reason?: PendingReason;
+    /** Next chunk to process for a file larger than one chunk. */
+    next_chunk?: number;
+    run?: string;
+}
+export interface Ledger {
+    schema: typeof LEDGER_SCHEMA;
+    company: string;
+    /** Latest entity `last_updated` when the ledger was seeded (design 14.3). */
+    boundary: string | null;
+    entries: Record<string, LedgerEntry>;
+}
+export interface PlanInput {
+    /** Candidate `input` value: the company-relative path, `#<chunk>` when chunked, or `session`. */
+    id: string;
+    kind: "knowledge" | "signal" | "session";
+    /** Company-relative path of the file to read; null for `session` (its text is in the plan). */
+    path: string | null;
+    audience: "company" | "session";
+    reason: PendingReason;
+    sha256: string | null;
+    est_tokens: number;
+    /** 1-based inclusive line range to read, for a file larger than one chunk. */
+    lines: [number, number] | null;
+    chunk: {
+        index: number;
+        count: number;
+    } | null;
+    /** For signals: `entity_refs` items with no entity file yet. */
+    missing_refs?: string[];
+    /** Run-directory-relative copy of `path` with annotator entity lists removed; same line numbers. */
+    read_path?: string;
+}
+export interface OntologyPlan {
+    schema: typeof PLAN_SCHEMA;
+    company: string;
+    run_id: string;
+    created_at: string;
+    first_run: boolean;
+    boundary: string | null;
+    /** Present only when `checkpoint.ontology.company-brief` was on for this plan. */
+    company_brief?: {
+        status: CompanyBriefResult["status"];
+        reason?: string;
+    };
+    /** Present only when `checkpoint.ontology.multi-writer` was on for this plan. */
+    multi_writer?: MultiWriterStart;
+    /** Present, as false, only when `checkpoint.ontology.no-link-aliases` was on for this plan. */
+    link_aliases?: false;
+    /** Set by checkpoint.ontology.first-name-people: apply defers a one-word person who may be an existing fuller name. */
+    first_name_people?: true;
+    /** Set by checkpoint.ontology.skip-ambiguous-concept-links: apply rejects a knowledge link to a concept whose name another type also holds. */
+    skip_ambiguous_concept_links?: true;
+    /** Set by checkpoint.ontology.dominant-sibling-link: apply redirects a knowledge link from a weak cross-type sibling to the one other files link to. */
+    dominant_sibling_link?: true;
+    /** Set by checkpoint.ontology.hub-mention-floor: apply rejects a knowledge link to an under-mentioned non-person hub. */
+    hub_mention_floor?: true;
+    /** Set by checkpoint.ontology.concept-project-link: apply links a knowledge concept with an ambiguous alias to the one project of that canonical name. */
+    concept_project_link?: true;
+    /** Set by checkpoint.ontology.named-evidence: apply rejects a knowledge link to the company's own entity, or a concept-project-link redirect, whose evidence does not name it as a word. */
+    named_evidence?: true;
+    inputs: PlanInput[];
+    /** The session's summary, decisions and learnings, for the `session` input. */
+    session_text: string | null;
+    pending_after_run: number;
+    budget: {
+        max_inputs: number;
+        max_tokens: number;
+        chunk_tokens: number;
+        planned_tokens: number;
+    };
+    candidates_file: string;
+    instructions: string[];
+}
+export interface CheckpointPayloadLike {
+    company?: unknown;
+    /**
+     * Set by `hq core checkpoint` only when the payload names no company and
+     * another company has queued touches (CO-59). Never scopes anything else.
+     */
+    ontology_company?: unknown;
+    /** The sibling backend `hq core checkpoint` spawned for this payload. */
+    backend?: unknown;
+    files?: unknown;
+    summary?: unknown;
+    decisions?: unknown;
+    learnings?: unknown;
+    insights?: unknown;
+}
+export type FlagReader = (flagKey: string, company: OntologyCompany) => Promise<boolean>;
+export interface PlanOptions {
+    hqRoot: string;
+    runDir: string;
+    payload: CheckpointPayloadLike;
+    readFlag: FlagReader;
+    now?: Date;
+    /** This machine's hq-cloud versions; defaults to reading them. */
+    syncClientVersions?: () => SyncClientVersions;
+}
+export type PlanOutcome = {
+    status: "skipped";
+    reason: string;
+    companyBrief?: CompanyBriefResult;
+    multiWriter?: MultiWriterStart;
+} | {
+    status: "planned";
+    plan: OntologyPlan;
+    planPath: string;
+    companyBrief?: CompanyBriefResult;
+};
+export declare const READ_PATH_INSTRUCTION = "When an input has read_path, read that file (relative to the run directory) instead of path, with the same line range. It is the same text with an older annotator's entity lists and entity links removed.";
+export declare const FIRST_NAME_PEOPLE_INSTRUCTION = "Name a person by the full name the input or the company's entities give. When neither gives more than a first name, name the person by that first name; do not leave them out.";
+export declare function readLedger(hqRoot: string, company: OntologyCompany): Ledger | null;
+export declare function writeLedger(hqRoot: string, company: OntologyCompany, ledger: Ledger): void;
+export declare function backendPreferencePath(hqRoot: string, company: OntologyCompany): string;
+/** The grok-backend flag value the last plan recorded; false when no plan has recorded one. */
+export declare function readBackendPreference(hqRoot: string, company: OntologyCompany): boolean;
+/**
+ * The company this run's ontology step works on: the payload's own company,
+ * or else the `ontology_company` the checkpoint parent picked for queued
+ * touches (`borrowed`).
+ */
+export declare function payloadOntologyCompany(payload: CheckpointPayloadLike): {
+    slug: string | null;
+    borrowed: boolean;
+};
+/** Plan this run. Never throws for a skip; returns the reason instead. */
+export declare function planOntologyRun(options: PlanOptions): Promise<PlanOutcome>;
+/**
+ * The cloud annotator wrote an `entities:` list into knowledge front matter and
+ * `[[ontology/entities/...]]` links into the text. Most are wrong, and a model
+ * told to ignore them still copies them (design section 18), so the model reads
+ * a copy without them. The list's lines are blanked rather than removed so the
+ * plan's line ranges still hold; a link becomes its label, or its last path
+ * segment. Returns null when the text has neither.
+ */
+export declare function stripAnnotations(text: string): string | null;
+export {};
+//# sourceMappingURL=plan.d.ts.map