@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/checkpoint-ontology/apply.js

@@ -0,0 +1,777 @@
+/**
+ * `hq core ontology apply`: turn the model's candidates into entity writes.
+ *
+ * Every rule that affects identity, scope or cost lives here (design
+ * sections 4.3, 5 and 14). The model output is untrusted input: a malformed
+ * candidate is rejected and counted, never repaired.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { entityKey, freshAliases, MAX_NAME_LENGTH, ownNames } from "./aliases.js";
+import { recordOutbox, scanDuplicates } from "./multi-writer.js";
+import { writeCompanyBrief } from "./company-brief.js";
+import { entitiesRoot, resolveOntologyCompany, safeWriteFile } from "./company.js";
+import { checkSyncClient, readSyncClientVersions } from "./sync-client.js";
+import { appendBackRefs, parseEntityFile, patchEntityFile, previewSignalContent, renderNewEntity, validateEntityFrontmatter, } from "./entity-file.js";
+import { canonicalizeName, entityId, isRejectedName, isWritableEntityType, normalizeEntityName, squash, toSlug, } from "./identity.js";
+import { CANDIDATES_FILE, CANDIDATES_SCHEMA, PLAN_FILE, PLAN_SCHEMA, REPORT_FILE, readLedger, writeLedger, } from "./plan.js";
+import { buildEntityIndex, countInboundLinks, indexAlias, indexEntity, listSignalFiles, readSignal } from "./tree.js";
+export const CAPS = {
+    creates: 25,
+    updates: 100,
+    bytes: 200 * 1024,
+    newAliasesPerEntity: 3,
+    aliasesPerCandidate: 5,
+    nameLength: MAX_NAME_LENGTH,
+};
+const MIN_CREATE_CONFIDENCE = 0.7;
+/** Inbound links the dominant sibling must have for each one the named entity has. */
+const DOMINANT_SIBLING_RATIO = 3;
+/** Inbound links the dominant sibling must have before a redirect. */
+const DOMINANT_SIBLING_MIN_INBOUND = 5;
+/** checkpoint.ontology.hub-mention-floor: other entity files that must link here before the floor applies. */
+const HUB_MIN_INBOUND = 50;
+/** checkpoint.ontology.hub-mention-floor: whole-word canonical-name mentions required to keep the link. */
+const HUB_MIN_MENTIONS = 2;
+export class ApplyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ApplyError";
+    }
+}
+function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/** Validate one raw candidate. Returns the candidate or a rejection reason. */
+function parseCandidate(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return "not_an_object";
+    const c = raw;
+    if (typeof c.input !== "string" || !c.input)
+        return "input";
+    if (!isWritableEntityType(c.type))
+        return "type";
+    if (typeof c.name !== "string" || !c.name.trim())
+        return "name";
+    if (c.name.length > CAPS.nameLength)
+        return "name_too_long";
+    if (typeof c.confidence !== "number" || !Number.isFinite(c.confidence) || c.confidence < 0 || c.confidence > 1) {
+        return "confidence";
+    }
+    const aliases = c.aliases === undefined ? [] : c.aliases;
+    if (!Array.isArray(aliases) || !aliases.every((alias) => typeof alias === "string"))
+        return "aliases";
+    return {
+        input: c.input,
+        type: c.type,
+        name: c.name,
+        aliases: aliases.slice(0, CAPS.aliasesPerCandidate),
+        confidence: c.confidence,
+        evidence: typeof c.evidence === "string" ? c.evidence : "",
+    };
+}
+function escapeRegExp(name) {
+    return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Whole-word, any-case matches of `name` in `text`, with Unicode letters and digits as word characters. Empty or whitespace-only names match nothing. */
+function countMentions(text, name) {
+    if (name.trim() === "")
+        return 0;
+    const pattern = new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(name)}(?![\\p{L}\\p{N}])`, "giu");
+    return text.match(pattern)?.length ?? 0;
+}
+/**
+ * checkpoint.ontology.named-evidence: true when `evidence` holds one of
+ * `names` as a word, matching case. A name inside a path, domain, handle, tag
+ * or identifier does not count: `indigoai-us/hq`, `getindigo.ai`,
+ * `C:\\Indigo\\hq`, `scope: company:indigo`, `Indigo:internal`, `@indigo`,
+ * `` `indigo` ``.
+ */
+export function evidenceNames(evidence, names) {
+    for (const raw of names) {
+        const name = raw.trim();
+        if (!name || !evidence)
+            continue;
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const word = new RegExp(`(?<![\\p{L}\\p{N}_\\-./\\\\@:\`#])${escaped}(?![\\p{L}\\p{N}_\\-/\\\\@\`]|[.:#][\\p{L}\\p{N}])`, "u");
+        if (word.test(evidence))
+            return true;
+    }
+    return false;
+}
+/** Design section 5.3, tiers 1 to 4. */
+function resolveCandidate(index, type, canonical) {
+    const normalized = normalizeEntityName(canonical, type);
+    const byCanonical = [...(index.canonical.get(entityKey(type, normalized)) ?? [])].sort();
+    if (byCanonical.length > 0)
+        return { tier: 1, target: byCanonical[0], duplicates: byCanonical.slice(1) };
+    const byAlias = [...(index.alias.get(entityKey(type, normalized)) ?? [])].sort();
+    if (byAlias.length === 1)
+        return { tier: 2, target: byAlias[0] };
+    if (byAlias.length > 1)
+        return { tier: "ambiguous_alias", paths: byAlias };
+    const squashed = [...(index.squashed.get(entityKey(type, squash(normalized))) ?? [])].sort();
+    if (squashed.length > 0)
+        return { tier: "suspect_duplicate", paths: squashed };
+    const otherTypes = [...(index.types.get(normalized) ?? [])].filter((other) => other !== type).sort();
+    if (otherTypes.length > 0)
+        return { tier: "type_conflict", types: otherTypes };
+    return { tier: "new" };
+}
+/**
+ * Existing entities of `type` that a new candidate probably is: one of the
+ * candidate's aliases is already their name or alias, or, for people, every
+ * word of their name (two words or more) is in the candidate's name
+ * (`Chaudhry Hassaan Saleem` and `Hassaan Saleem`).
+ */
+function overlappingEntities(index, type, canonical, aliases) {
+    const paths = new Set();
+    for (const alias of aliases) {
+        const normalized = normalizeEntityName(alias, type);
+        // A generic alias still counts when an existing entity already holds it.
+        if (!normalized)
+            continue;
+        for (const rel of index.canonical.get(entityKey(type, normalized)) ?? [])
+            paths.add(rel);
+        for (const rel of index.alias.get(entityKey(type, normalized)) ?? [])
+            paths.add(rel);
+    }
+    if (type === "person") {
+        const words = new Set(normalizeEntityName(canonical, type).split(" "));
+        const prefix = entityKey(type, "");
+        for (const [name, rels] of index.canonical) {
+            if (!name.startsWith(prefix))
+                continue;
+            const other = name.slice(prefix.length).split(" ");
+            if (other.length >= 2 && other.every((word) => words.has(word)))
+                for (const rel of rels)
+                    paths.add(rel);
+        }
+    }
+    return [...paths].sort();
+}
+/**
+ * Existing people a one-word person candidate may be: the word is the first
+ * word of their name or of one of their aliases, and that name has two words
+ * or more (`John` and `John Smith`). The model never sees the entity tree, so
+ * it cannot tell a first name that the company already holds in full.
+ */
+function firstNameOverlap(index, canonical) {
+    const words = normalizeEntityName(canonical, "person").split(" ");
+    if (words.length !== 1 || !words[0])
+        return [];
+    const prefix = entityKey("person", "");
+    const paths = new Set();
+    for (const map of [index.canonical, index.alias]) {
+        for (const [name, rels] of map) {
+            if (!name.startsWith(prefix))
+                continue;
+            const other = name.slice(prefix.length).split(" ");
+            if (other.length >= 2 && other[0] === words[0])
+                for (const rel of rels)
+                    paths.add(rel);
+        }
+    }
+    return [...paths].sort();
+}
+function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+/** Plan inputs that still match the tree. A changed file is skipped this run. */
+function liveInputs(hqRoot, company, plan) {
+    const ledger = readLedger(hqRoot, company);
+    const out = new Map();
+    for (const input of plan.inputs) {
+        if (input.kind === "session") {
+            out.set(input.id, input);
+            continue;
+        }
+        const rel = input.path ?? "";
+        const safe = /^(knowledge\/|signals\/[a-z_]+\/)/.test(rel) && !rel.split("/").includes("..");
+        let live = false;
+        if (safe) {
+            try {
+                live = sha256(fs.readFileSync(path.join(company.dir, rel))) === input.sha256;
+            }
+            catch {
+                live = false;
+            }
+        }
+        const entry = ledger?.entries[rel];
+        out.set(input.id, live && entry?.state === "pending" && entry.sha256 === input.sha256 ? input : null);
+    }
+    return out;
+}
+export function applyOntologyRun(options) {
+    const started = Date.now();
+    const now = (options.now ?? new Date()).toISOString();
+    const plan = readJson(path.join(options.runDir, PLAN_FILE));
+    if (plan.schema !== PLAN_SCHEMA)
+        throw new ApplyError("ontology plan has an unexpected schema");
+    if (plan.company !== options.company)
+        throw new ApplyError("ontology plan company does not match the payload company");
+    const resolution = resolveOntologyCompany(options.hqRoot, plan.company);
+    if (!resolution.ok)
+        throw new ApplyError(`ontology company rejected: ${resolution.reason}`);
+    const company = resolution.company;
+    const entityRoot = entitiesRoot(company);
+    const report = {
+        schema: "hq-checkpoint-ontology-report.v1",
+        company: company.slug,
+        run_id: plan.run_id,
+        status: "applied",
+        planned_inputs: plan.inputs.length,
+        planned_tokens: plan.budget.planned_tokens,
+        candidates: 0,
+        created: [],
+        updated: [],
+        matched: 0,
+        session_links: [],
+        links: [],
+        ...(plan.dominant_sibling_link === true ? { dominant_sibling_redirects: [] } : {}),
+        rejected: [],
+        deferred: [],
+        suspect_duplicates: [],
+        backrefs_added: 0,
+        bytes_written: 0,
+        inputs_done: [],
+        inputs_pending: [],
+        write_errors: [],
+        duration_ms: 0,
+    };
+    const outboxRels = new Set();
+    if (plan.multi_writer) {
+        report.multi_writer = {
+            conflicts: plan.multi_writer.merge_back ?? [],
+            outbox_recorded: 0,
+            ...(plan.multi_writer.error ? { error: plan.multi_writer.error } : {}),
+        };
+    }
+    // Design 20.4: the outbox entry is written before the entity file, so sync
+    // never sees a checkpoint write without one. A failed outbox write stops
+    // the entity write and leaves its inputs pending for the next run.
+    const recordBeforeWrite = (rel, content) => {
+        if (!report.multi_writer)
+            return null;
+        try {
+            if (recordOutbox(options.hqRoot, company, [{ rel, content }], options.now ?? new Date()).reset) {
+                report.multi_writer.outbox_reset = true;
+            }
+            return null;
+        }
+        catch (error) {
+            return `outbox:${error.name}`;
+        }
+    };
+    const finish = () => {
+        if (report.multi_writer)
+            report.multi_writer.outbox_recorded = outboxRels.size;
+        report.duration_ms = Date.now() - started;
+        fs.writeFileSync(path.join(options.runDir, REPORT_FILE), `${JSON.stringify(report, null, 2)}\n`);
+        return report;
+    };
+    // CO-45: the sync client can change between plan and apply, so check it
+    // again before anything is written.
+    const syncClient = checkSyncClient((options.syncClientVersions ?? readSyncClientVersions)());
+    if (!syncClient.ok) {
+        report.status = "sync_client_old";
+        report.skip_reason = syncClient.reason;
+        report.inputs_pending = plan.inputs.filter((i) => i.kind !== "session").map((i) => i.id);
+        return finish();
+    }
+    const candidatesPath = path.join(options.runDir, CANDIDATES_FILE);
+    if (!fs.existsSync(candidatesPath)) {
+        report.status = "no_candidates";
+        report.inputs_pending = plan.inputs.filter((i) => i.kind !== "session").map((i) => i.id);
+        return finish();
+    }
+    let rawCandidates;
+    try {
+        const doc = readJson(candidatesPath);
+        if (doc.schema !== CANDIDATES_SCHEMA || !Array.isArray(doc.candidates))
+            throw new Error("schema");
+        rawCandidates = doc.candidates;
+    }
+    catch {
+        report.status = "invalid_candidates";
+        report.inputs_pending = plan.inputs.filter((i) => i.kind !== "session").map((i) => i.id);
+        return finish();
+    }
+    report.candidates = rawCandidates.length;
+    const index = buildEntityIndex(company.dir);
+    // checkpoint.ontology.skip-ambiguous-concept-links: canonical names held by entities of more than one type.
+    // Names compare in the non-organization form for every type (lowercase, keeps + and #, no squashing),
+    // so "C++" and "C", or "AB" and "A B", stay distinct.
+    const crossTypeKey = (name) => normalizeEntityName(name, "concept");
+    const crossTypeNames = new Set();
+    if (plan.skip_ambiguous_concept_links === true) {
+        const typesByName = new Map();
+        for (const entity of index.byRel.values()) {
+            const name = crossTypeKey(entity.canonical_name);
+            if (name === "")
+                continue;
+            const types = typesByName.get(name) ?? new Set();
+            types.add(entity.type);
+            typesByName.set(name, types);
+        }
+        for (const [name, types] of typesByName)
+            if (types.size > 1)
+                crossTypeNames.add(name);
+    }
+    // checkpoint.ontology.dominant-sibling-link and checkpoint.ontology.hub-mention-floor:
+    // how many other entity files link to each entity.
+    const inbound = plan.dominant_sibling_link === true || plan.hub_mention_floor === true
+        ? countInboundLinks(company.dir, index)
+        : new Map();
+    const siblings = new Map();
+    if (plan.dominant_sibling_link === true) {
+        const grouped = new Map();
+        for (const entity of index.byRel.values()) {
+            const key = crossTypeKey(entity.canonical_name);
+            if (key === "")
+                continue;
+            const members = grouped.get(key) ?? [];
+            members.push({ rel: entity.rel, type: entity.type });
+            grouped.set(key, members);
+        }
+        for (const [key, members] of grouped) {
+            if (new Set(members.map((member) => member.type)).size < 2)
+                continue;
+            siblings.set(key, members.map((member) => member.rel));
+        }
+    }
+    const dominantSibling = (rel) => {
+        const group = siblings.get(crossTypeKey(index.byRel.get(rel).canonical_name));
+        if (!group)
+            return null;
+        let best = group[0];
+        for (const member of group) {
+            const count = inbound.get(member) ?? 0;
+            const bestCount = inbound.get(best) ?? 0;
+            if (count > bestCount || (count === bestCount && member.localeCompare(best) < 0))
+                best = member;
+        }
+        const relCount = inbound.get(rel) ?? 0;
+        const bestCount = inbound.get(best) ?? 0;
+        if (relCount >= bestCount)
+            return null;
+        if (bestCount >= DOMINANT_SIBLING_RATIO * relCount && bestCount >= DOMINANT_SIBLING_MIN_INBOUND)
+            return best;
+        return null;
+    };
+    // checkpoint.ontology.named-evidence: the company's own company entity.
+    const ownCompanyRel = `ontology/entities/company/${company.slug}.md`;
+    const isOwnCompany = (entity, rel) => entity.type === "company" && (rel === ownCompanyRel || crossTypeKey(entity.canonical_name) === crossTypeKey(company.slug));
+    const inputs = liveInputs(options.hqRoot, company, plan);
+    const inputTexts = new Map();
+    // The text the model was given for this input: the annotation-stripped copy
+    // when there is one, cut to the chunk's line range.
+    const inputText = (input) => {
+        const cached = inputTexts.get(input.id);
+        if (cached !== undefined)
+            return cached;
+        if (input.read_path !== undefined && input.read_path.split("/").includes("..")) {
+            throw new ApplyError("ontology plan read_path leaves the run directory");
+        }
+        const file = input.read_path !== undefined
+            ? path.join(options.runDir, input.read_path)
+            : path.join(company.dir, input.path);
+        let text = fs.readFileSync(file, "utf8");
+        if (input.lines !== null)
+            text = text.split("\n").slice(input.lines[0] - 1, input.lines[1]).join("\n");
+        inputTexts.set(input.id, text);
+        return text;
+    };
+    // checkpoint.ontology.hub-mention-floor: the final target of a knowledge link is a
+    // non-person entity many files link to, and the input names it fewer than twice.
+    const underMentionedHub = (input, rel, entity) => plan.hub_mention_floor === true &&
+        input.kind === "knowledge" &&
+        entity.type !== "person" &&
+        (inbound.get(rel) ?? 0) >= HUB_MIN_INBOUND &&
+        countMentions(inputText(input), entity.canonical_name) < HUB_MIN_MENTIONS;
+    const blocked = new Set();
+    const updates = new Map();
+    const update = (rel) => {
+        let pending = updates.get(rel);
+        if (!pending) {
+            pending = { aliases: [], backrefs: [], countSignals: false, inputs: new Set() };
+            updates.set(rel, pending);
+        }
+        return pending;
+    };
+    const inputOrder = new Map(plan.inputs.map((input, i) => [input.id, i]));
+    const ordered = rawCandidates
+        .map((raw, i) => ({ raw, i, parsed: parseCandidate(raw) }))
+        .sort((a, b) => {
+        const ai = typeof a.parsed === "string" ? Infinity : inputOrder.get(a.parsed.input) ?? Infinity;
+        const bi = typeof b.parsed === "string" ? Infinity : inputOrder.get(b.parsed.input) ?? Infinity;
+        return ai - bi || a.i - b.i;
+    });
+    for (const { raw, parsed } of ordered) {
+        if (typeof parsed === "string") {
+            const r = (raw ?? {});
+            report.rejected.push({ input: String(r.input ?? ""), type: String(r.type ?? ""), name: String(r.name ?? ""), reason: `invalid_${parsed}` });
+            continue;
+        }
+        const candidate = parsed;
+        const note = (list, reason) => list.push({ input: candidate.input, type: candidate.type, name: candidate.name, reason });
+        if (!inputs.has(candidate.input)) {
+            note(report.rejected, "input_not_in_plan");
+            continue;
+        }
+        const input = inputs.get(candidate.input);
+        if (!input) {
+            note(report.deferred, "input_changed");
+            continue;
+        }
+        const canonical = canonicalizeName(candidate.name);
+        const resolved = resolveCandidate(index, candidate.type, canonical);
+        if (input.kind === "session") {
+            // D2: session content never creates or aliases a shared entity.
+            if (resolved.tier === 1 || resolved.tier === 2) {
+                const entity = index.byRel.get(resolved.target);
+                if (!report.session_links.some((link) => link.path === resolved.target)) {
+                    report.session_links.push({ type: entity.type, canonical_name: entity.canonical_name, path: resolved.target });
+                }
+            }
+            else
+                note(report.rejected, "session_not_existing");
+            continue;
+        }
+        if (resolved.tier === 1 || resolved.tier === 2) {
+            const linked = index.byRel.get(resolved.target);
+            if (input.kind === "knowledge" &&
+                linked.type === "concept" &&
+                crossTypeNames.has(crossTypeKey(linked.canonical_name))) {
+                note(report.rejected, "ambiguous_type");
+                continue;
+            }
+            const redirect = input.kind === "knowledge" && plan.dominant_sibling_link === true ? dominantSibling(resolved.target) : null;
+            const targetRel = redirect ?? resolved.target;
+            const targetEntity = redirect ? index.byRel.get(targetRel) : linked;
+            if (plan.named_evidence === true &&
+                input.kind === "knowledge" &&
+                isOwnCompany(targetEntity, targetRel) &&
+                !evidenceNames(candidate.evidence, [candidate.name, ...candidate.aliases])) {
+                note(report.rejected, "unnamed_in_evidence");
+                continue;
+            }
+            if (underMentionedHub(input, targetRel, targetEntity)) {
+                note(report.rejected, "hub_under_mentioned");
+                continue;
+            }
+            report.matched += 1;
+            report.links.push({
+                input: candidate.input,
+                action: "link",
+                type: targetEntity.type,
+                canonical_name: targetEntity.canonical_name,
+                path: targetRel,
+            });
+            if (resolved.tier === 1 && resolved.duplicates.length > 0) {
+                report.suspect_duplicates.push({ name: canonical, type: candidate.type, paths: [resolved.target, ...resolved.duplicates] });
+            }
+            if (redirect) {
+                report.dominant_sibling_redirects?.push({ input: candidate.input, from: resolved.target, to: targetRel });
+                continue;
+            }
+            if (resolved.tier === 1 && resolved.duplicates.length > 0)
+                continue;
+            // checkpoint.ontology.no-link-aliases: the link is reported and the entity file is left as it is.
+            if (plan.link_aliases === false)
+                continue;
+            const pending = updates.get(resolved.target);
+            if (!pending && updates.size >= CAPS.updates) {
+                note(report.deferred, "cap_updates");
+                blocked.add(candidate.input);
+                continue;
+            }
+            const already = pending?.aliases ?? [];
+            const room = CAPS.newAliasesPerEntity - already.length;
+            const fresh = room > 0
+                ? freshAliases(index, candidate.type, resolved.target, ownNames(index, resolved.target, already), [canonical, ...candidate.aliases]).slice(0, room)
+                : [];
+            if (fresh.length > 0) {
+                const target = update(resolved.target);
+                target.aliases.push(...fresh);
+                target.inputs.add(candidate.input);
+                // Reserve them now so a later candidate cannot give the same alias
+                // to another entity in this run.
+                for (const alias of fresh)
+                    indexAlias(index, candidate.type, resolved.target, alias);
+            }
+            continue;
+        }
+        if (resolved.tier === "ambiguous_alias") {
+            // checkpoint.ontology.concept-project-link: a knowledge concept whose name is the
+            // canonical name of exactly one project links to that project. Nothing is written.
+            // Like the tier 1 and 2 links above, it runs before the stopword guard,
+            // which only stops new entities.
+            const projects = plan.concept_project_link === true && input.kind === "knowledge" && candidate.type === "concept"
+                ? [...(index.canonical.get(entityKey("project", normalizeEntityName(canonical, "project"))) ?? [])]
+                : [];
+            if (projects.length === 1) {
+                if (plan.named_evidence === true && !evidenceNames(candidate.evidence, [candidate.name, ...candidate.aliases])) {
+                    note(report.rejected, "unnamed_in_evidence");
+                    continue;
+                }
+                const linked = index.byRel.get(projects[0]);
+                if (underMentionedHub(input, projects[0], linked)) {
+                    note(report.rejected, "hub_under_mentioned");
+                    continue;
+                }
+                report.matched += 1;
+                report.links.push({ input: candidate.input, action: "link", type: linked.type, canonical_name: linked.canonical_name, path: projects[0] });
+                continue;
+            }
+        }
+        // A generic word never becomes a new entity, whatever else it collides with.
+        if (isRejectedName(normalizeEntityName(canonical, candidate.type))) {
+            note(report.rejected, "stopword");
+            continue;
+        }
+        if (resolved.tier === "ambiguous_alias") {
+            note(report.deferred, "ambiguous_alias");
+            continue;
+        }
+        if (resolved.tier === "suspect_duplicate") {
+            note(report.deferred, "suspect_duplicate");
+            report.suspect_duplicates.push({ name: canonical, type: candidate.type, paths: resolved.paths });
+            continue;
+        }
+        if (resolved.tier === "type_conflict") {
+            note(report.rejected, "type_conflict");
+            continue;
+        }
+        const overlap = overlappingEntities(index, candidate.type, canonical, candidate.aliases);
+        if (overlap.length > 0) {
+            note(report.deferred, "suspect_duplicate");
+            report.suspect_duplicates.push({ name: canonical, type: candidate.type, paths: overlap });
+            continue;
+        }
+        const firstName = plan.first_name_people === true && candidate.type === "person" ? firstNameOverlap(index, canonical) : [];
+        if (firstName.length > 0) {
+            note(report.deferred, "suspect_duplicate");
+            report.suspect_duplicates.push({ name: canonical, type: candidate.type, paths: firstName });
+            continue;
+        }
+        // Tier 5: create.
+        if (candidate.confidence < MIN_CREATE_CONFIDENCE) {
+            note(report.rejected, "low_confidence");
+            continue;
+        }
+        const slug = toSlug(canonical);
+        if (!slug) {
+            note(report.rejected, "empty_slug");
+            continue;
+        }
+        const rel = `ontology/entities/${candidate.type}/${slug}.md`;
+        const target = path.join(company.dir, rel);
+        if (fs.existsSync(target) || index.byRel.has(rel) || index.invalid.has(rel)) {
+            // Same file name, different id (`Acme, Inc.` and `Acme Inc`): the
+            // cloud file-writer's overwrite guard keeps the existing file too.
+            note(report.rejected, "slug_collision");
+            continue;
+        }
+        if (report.created.length >= CAPS.creates) {
+            note(report.deferred, "cap_creates");
+            blocked.add(candidate.input);
+            continue;
+        }
+        const aliases = freshAliases(index, candidate.type, rel, new Set([normalizeEntityName(canonical, candidate.type)]), candidate.aliases).slice(0, CAPS.newAliasesPerEntity);
+        const content = renderNewEntity({ type: candidate.type, canonicalName: canonical, aliases, confidence: candidate.confidence, now, signalCount: 0 });
+        const reparsed = parseEntityFile(content);
+        const fields = reparsed ? validateEntityFrontmatter(reparsed.frontmatter) : "unparseable";
+        if (typeof fields === "string" || fields.canonical_name !== canonical || fields.id !== entityId(candidate.type, canonical)) {
+            note(report.rejected, "roundtrip_failed");
+            continue;
+        }
+        const bytes = Buffer.byteLength(content, "utf8");
+        if (report.bytes_written + bytes > CAPS.bytes) {
+            note(report.deferred, "cap_bytes");
+            blocked.add(candidate.input);
+            continue;
+        }
+        const createOutboxError = recordBeforeWrite(rel, content);
+        if (createOutboxError) {
+            report.write_errors.push({ path: rel, reason: createOutboxError });
+            blocked.add(candidate.input);
+            continue;
+        }
+        try {
+            safeWriteFile(options.hqRoot, [entityRoot], target, content);
+        }
+        catch (error) {
+            report.write_errors.push({ path: rel, reason: error.name });
+            blocked.add(candidate.input);
+            continue;
+        }
+        report.bytes_written += bytes;
+        if (report.multi_writer)
+            outboxRels.add(rel);
+        report.created.push(rel);
+        report.links.push({ input: candidate.input, action: "create", type: candidate.type, canonical_name: canonical, path: rel });
+        indexEntity(index, { ...fields, rel, slug, last_updated: now, first_seen: now });
+    }
+    applySignalRefs(company, plan, inputs, index, update);
+    for (const rel of [...updates.keys()].sort()) {
+        const pending = updates.get(rel);
+        const entity = index.byRel.get(rel);
+        if (!entity || !isWritableEntityType(entity.type))
+            continue;
+        const target = path.join(company.dir, rel);
+        const original = fs.readFileSync(target, "utf8");
+        const withRefs = appendBackRefs(original, pending.backrefs);
+        // Design 14.2: max(stored, recount), so the result is the same on every
+        // machine and on a rerun, and never lowers a value the gardener wrote.
+        const patched = patchEntityFile(withRefs.content, {
+            addAliases: pending.aliases,
+            signalCount: pending.countSignals ? signalCountFor(company, rel) : undefined,
+            lastUpdated: now,
+            bodyChanged: withRefs.added > 0,
+        });
+        if (!patched.ok) {
+            report.write_errors.push({ path: rel, reason: patched.reason });
+            for (const id of pending.inputs)
+                blocked.add(id);
+            continue;
+        }
+        if (!patched.changed)
+            continue;
+        const bytes = Buffer.byteLength(patched.content, "utf8");
+        if (report.bytes_written + bytes > CAPS.bytes || report.updated.length >= CAPS.updates) {
+            for (const id of pending.inputs)
+                blocked.add(id);
+            const reason = report.updated.length >= CAPS.updates ? "cap_updates" : "cap_bytes";
+            report.deferred.push({ input: [...pending.inputs][0] ?? "", type: entity.type, name: entity.canonical_name, reason });
+            continue;
+        }
+        const patchOutboxError = recordBeforeWrite(rel, patched.content);
+        if (patchOutboxError) {
+            report.write_errors.push({ path: rel, reason: patchOutboxError });
+            for (const id of pending.inputs)
+                blocked.add(id);
+            continue;
+        }
+        try {
+            safeWriteFile(options.hqRoot, [entityRoot], target, patched.content);
+        }
+        catch (error) {
+            report.write_errors.push({ path: rel, reason: error.name });
+            for (const id of pending.inputs)
+                blocked.add(id);
+            continue;
+        }
+        report.bytes_written += bytes;
+        report.backrefs_added += withRefs.added;
+        if (report.multi_writer)
+            outboxRels.add(rel);
+        // An entity created earlier in this run is reported once, as created.
+        if (!report.created.includes(rel))
+            report.updated.push(rel);
+    }
+    commitLedger(options.hqRoot, company, plan, inputs, blocked, report);
+    // The plan rendered the brief before these entity writes; render it again so it matches them.
+    if (plan.company_brief && report.created.length + report.updated.length > 0) {
+        report.company_brief = writeCompanyBrief(options.hqRoot, company, options.now ?? new Date());
+    }
+    if (report.multi_writer) {
+        try {
+            report.multi_writer.duplicates = scanDuplicates(company);
+        }
+        catch (error) {
+            report.multi_writer.error = `duplicates:${error.name}`;
+        }
+    }
+    return finish();
+}
+let signalRefIndex = null;
+/** Distinct root signal files whose `entity_refs` name this entity file. */
+function signalCountFor(company, rel) {
+    if (!signalRefIndex || signalRefIndex.companyDir !== company.dir) {
+        const refs = new Map();
+        for (const signalRel of listSignalFiles(company.dir)) {
+            const signal = readSignal(company.dir, signalRel);
+            for (const ref of signal?.refs ?? []) {
+                let set = refs.get(ref);
+                if (!set)
+                    refs.set(ref, (set = new Set()));
+                set.add(signalRel);
+            }
+        }
+        signalRefIndex = { companyDir: company.dir, refs };
+    }
+    const ref = rel.replace(/^ontology\/entities\//, "").replace(/\.md$/, "");
+    return signalRefIndex.refs.get(ref)?.size ?? 0;
+}
+/**
+ * The deterministic signal path (design 14.2): every company-audience signal
+ * in the plan adds one back-reference line to each entity it references, and
+ * `signal_count` becomes max(stored, recount). No model output is used.
+ */
+function applySignalRefs(company, plan, inputs, index, update) {
+    signalRefIndex = null;
+    const seen = new Set();
+    for (const input of plan.inputs) {
+        if (input.kind !== "signal" || !inputs.get(input.id) || !input.path || seen.has(input.path))
+            continue;
+        seen.add(input.path);
+        const signal = readSignal(company.dir, input.path);
+        if (!signal)
+            continue;
+        for (const ref of signal.refs) {
+            const rel = `ontology/entities/${ref}.md`;
+            const entity = index.byRel.get(rel);
+            if (!entity || !isWritableEntityType(entity.type))
+                continue;
+            const pending = update(rel);
+            pending.countSignals = true;
+            pending.inputs.add(input.id);
+            pending.backrefs.push({
+                signalType: signal.type,
+                preview: previewSignalContent(signal.canonicalContent),
+                // Entity files sit three levels below the company root. The gardener
+                // writes `../../`, which appendBackRefs treats as the same target.
+                href: `../../../${input.path}`,
+            });
+        }
+    }
+}
+/** Mark finished inputs done. Blocked or changed inputs stay pending. */
+function commitLedger(hqRoot, company, plan, inputs, blocked, report) {
+    const ledger = readLedger(hqRoot, company);
+    if (!ledger)
+        return;
+    const fileInputs = plan.inputs
+        .filter((input) => input.kind !== "session")
+        .sort((x, y) => (x.path ?? "").localeCompare(y.path ?? "") || (x.chunk?.index ?? 0) - (y.chunk?.index ?? 0));
+    for (const input of fileInputs) {
+        const live = inputs.get(input.id);
+        const entry = input.path ? ledger.entries[input.path] : undefined;
+        if (!live || blocked.has(input.id) || !entry || entry.sha256 !== input.sha256 || entry.state !== "pending") {
+            report.inputs_pending.push(input.id);
+            continue;
+        }
+        if (input.chunk) {
+            // Chunks advance only in order, so a blocked chunk is retried first.
+            if ((entry.next_chunk ?? 0) !== input.chunk.index) {
+                report.inputs_pending.push(input.id);
+                continue;
+            }
+            entry.next_chunk = input.chunk.index + 1;
+            report.inputs_done.push(input.id);
+            if (entry.next_chunk < input.chunk.count)
+                continue;
+            delete entry.next_chunk;
+        }
+        else {
+            report.inputs_done.push(input.id);
+        }
+        entry.state = "done";
+        delete entry.reason;
+        entry.run = plan.run_id;
+    }
+    writeLedger(hqRoot, company, ledger);
+}
+//# sourceMappingURL=apply.js.map