@indigoai-us/hq-cli 5.193.0 → 5.194.0

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

@@ -0,0 +1,113 @@
+/**
+ * `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 { type WritableEntityType } from "./identity.js";
+import { type EntityIndex } from "./tree.js";
+export declare const CAPS: {
+    readonly creates: 25;
+    readonly updates: 100;
+    readonly bytes: number;
+    readonly newAliasesPerEntity: 3;
+    readonly aliasesPerCandidate: 5;
+    readonly nameLength: 200;
+};
+export declare const MIN_CREATE_CONFIDENCE = 0.7;
+export interface Candidate {
+    input: string;
+    type: WritableEntityType;
+    name: string;
+    aliases: string[];
+    confidence: number;
+    evidence: string;
+}
+export interface ApplyReport {
+    schema: "hq-checkpoint-ontology-report.v1";
+    company: string;
+    run_id: string;
+    status: "applied" | "no_candidates" | "invalid_candidates";
+    planned_inputs: number;
+    planned_tokens: number;
+    candidates: number;
+    created: string[];
+    updated: string[];
+    matched: number;
+    session_links: Array<{
+        type: string;
+        canonical_name: string;
+        path: string;
+    }>;
+    /** Per input, the entities it resolved to: `link` for an existing entity, `create` for a new file. */
+    links: Array<{
+        input: string;
+        action: "link" | "create";
+        type: string;
+        canonical_name: string;
+        path: string;
+    }>;
+    rejected: Array<{
+        input: string;
+        type: string;
+        name: string;
+        reason: string;
+    }>;
+    deferred: Array<{
+        input: string;
+        type: string;
+        name: string;
+        reason: string;
+    }>;
+    suspect_duplicates: Array<{
+        name: string;
+        type: string;
+        paths: string[];
+    }>;
+    backrefs_added: number;
+    bytes_written: number;
+    inputs_done: string[];
+    inputs_pending: string[];
+    write_errors: Array<{
+        path: string;
+        reason: string;
+    }>;
+    duration_ms: number;
+}
+export interface ApplyOptions {
+    hqRoot: string;
+    runDir: string;
+    /** The payload company. Must equal the plan's company. */
+    company: string;
+    now?: Date;
+}
+export declare class ApplyError extends Error {
+    constructor(message: string);
+}
+/** Validate one raw candidate. Returns the candidate or a rejection reason. */
+export declare function parseCandidate(raw: unknown): Candidate | string;
+type Resolution = {
+    tier: 1;
+    target: string;
+    duplicates: string[];
+} | {
+    tier: 2;
+    target: string;
+} | {
+    tier: "ambiguous_alias";
+    paths: string[];
+} | {
+    tier: "suspect_duplicate";
+    paths: string[];
+} | {
+    tier: "type_conflict";
+    types: string[];
+} | {
+    tier: "new";
+};
+/** Design section 5.3, tiers 1 to 4. */
+export declare function resolveCandidate(index: EntityIndex, type: string, canonical: string): Resolution;
+export declare function applyOntologyRun(options: ApplyOptions): ApplyReport;
+export {};
+//# sourceMappingURL=apply.d.ts.map

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

@@ -0,0 +1,493 @@
+/**
+ * `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 { entitiesRoot, resolveOntologyCompany, safeWriteFile } from "./company.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, indexAlias, indexEntity, listSignalFiles, readSignal } from "./tree.js";
+export const CAPS = {
+    creates: 25,
+    updates: 100,
+    bytes: 200 * 1024,
+    newAliasesPerEntity: 3,
+    aliasesPerCandidate: 5,
+    nameLength: 200,
+};
+export const MIN_CREATE_CONFIDENCE = 0.7;
+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. */
+export 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 key(type, normalized) {
+    return `${type}\0${normalized}`;
+}
+/** Design section 5.3, tiers 1 to 4. */
+export function resolveCandidate(index, type, canonical) {
+    const normalized = normalizeEntityName(canonical, type);
+    const byCanonical = [...(index.canonical.get(key(type, normalized)) ?? [])].sort();
+    if (byCanonical.length > 0)
+        return { tier: 1, target: byCanonical[0], duplicates: byCanonical.slice(1) };
+    const byAlias = [...(index.alias.get(key(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(key(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" };
+}
+/**
+ * Aliases worth adding to the entity at `self`: new to it, and held by no
+ * other entity of any type, so an alias can never make a later match
+ * ambiguous. `own` holds the normalised names the entity already answers to.
+ */
+function freshAliases(index, type, self, own, names) {
+    const seen = new Set(own);
+    const out = [];
+    for (const raw of names) {
+        const alias = canonicalizeName(raw);
+        if (!alias || alias.length > CAPS.nameLength)
+            continue;
+        const normalized = normalizeEntityName(alias, type);
+        if (!normalized || seen.has(normalized) || isRejectedName(normalized))
+            continue;
+        const holders = [
+            ...(index.canonical.get(key(type, normalized)) ?? []),
+            ...(index.alias.get(key(type, normalized)) ?? []),
+        ];
+        if (holders.some((holder) => holder !== self))
+            continue;
+        if ([...(index.types.get(normalized) ?? [])].some((other) => other !== type))
+            continue;
+        seen.add(normalized);
+        out.push(alias);
+    }
+    return out;
+}
+/** The normalised names an indexed entity answers to, plus aliases queued this run. */
+function ownNames(index, rel, queued) {
+    const entity = index.byRel.get(rel);
+    return new Set([entity.canonical_name, ...entity.aliases, ...queued].map((name) => normalizeEntityName(name, entity.type)));
+}
+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: [],
+        rejected: [],
+        deferred: [],
+        suspect_duplicates: [],
+        backrefs_added: 0,
+        bytes_written: 0,
+        inputs_done: [],
+        inputs_pending: [],
+        write_errors: [],
+        duration_ms: 0,
+    };
+    const finish = () => {
+        report.duration_ms = Date.now() - started;
+        fs.writeFileSync(path.join(options.runDir, REPORT_FILE), `${JSON.stringify(report, null, 2)}\n`);
+        return report;
+    };
+    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);
+    const inputs = liveInputs(options.hqRoot, company, plan);
+    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) {
+            report.matched += 1;
+            const linked = index.byRel.get(resolved.target);
+            report.links.push({ input: candidate.input, action: "link", type: linked.type, canonical_name: linked.canonical_name, path: resolved.target });
+            if (resolved.tier === 1 && resolved.duplicates.length > 0) {
+                report.suspect_duplicates.push({ name: canonical, type: candidate.type, paths: [resolved.target, ...resolved.duplicates] });
+                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;
+        }
+        // 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;
+        }
+        // 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;
+        }
+        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;
+        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 });
+    }
+    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;
+        }
+        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;
+        // 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);
+    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

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

@@ -0,0 +1,40 @@
+/**
+ * Company resolution and write bounds for checkpoint ontology.
+ *
+ * The company always comes from the checkpoint payload and must be a key of
+ * `companies/manifest.yaml` with a directory at `companies/<slug>/`. Every
+ * write goes through {@link safeWriteFile}, which refuses any target whose
+ * real path leaves the allowed roots.
+ */
+export interface OntologyCompany {
+    slug: string;
+    /** The hq-flags company uid, or null when the company is local-only. */
+    cloudUid: string | null;
+    /** `<hqRoot>/companies/<slug>` */
+    dir: string;
+}
+export type CompanyResolution = {
+    ok: true;
+    company: OntologyCompany;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolveOntologyCompany(hqRoot: string, slug: string | null | undefined): CompanyResolution;
+/** The entity root (`companies/<co>/ontology/entities`) of a company. */
+export declare function entitiesRoot(company: OntologyCompany): string;
+/** The machine-local, unsynced state directory for a company. */
+export declare function stateRoot(hqRoot: string, company: OntologyCompany): string;
+export declare class WriteBoundsError extends Error {
+    constructor(message: string);
+}
+/**
+ * Write `content` to `target` only when it stays inside one of `roots` with no
+ * symlink anywhere between `anchor` (the HQ root) and the file. A root or a
+ * directory under it that is a symlink fails closed, and so does a target that
+ * is itself a symlink. Missing directories are created only after that check.
+ * The file is written to a temporary sibling and renamed, so a reader never
+ * sees half a file.
+ */
+export declare function safeWriteFile(anchor: string, roots: string[], target: string, content: string): void;
+//# sourceMappingURL=company.d.ts.map