@indigoai-us/hq-cli 5.193.1 → 5.194.0

package/dist/lib/checkpoint-ontology/entity-file.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Read, validate, create and patch ontology entity files.
+ *
+ * The cloud read model validates every synced entity file (hq-pro
+ * `validator.ts`): required frontmatter fields, and `id` equal to
+ * sha256(type:canonical_name) unless `identity_version >= 2`. Every file this
+ * module produces is re-parsed and validated before it is written.
+ *
+ * Existing files are patched in place. Only three frontmatter keys are
+ * rewritten (`aliases`, `signal_count`, `last_updated`); every other line is
+ * kept byte for byte, and the result is checked to parse to the same values
+ * for every other key.
+ */
+export interface ParsedEntityFile {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export interface EntityFields {
+    id: string;
+    type: string;
+    canonical_name: string;
+    aliases: string[];
+    signal_count: number;
+    identity_version?: number;
+}
+/**
+ * Parse with the YAML 1.2 core schema, as the cloud's `yaml` package does.
+ * js-yaml's default schema would turn unquoted timestamps into Date objects.
+ */
+export declare function parseEntityFile(content: string): ParsedEntityFile | null;
+/**
+ * The hq-pro validator rules this writer can break. Returns the entity's
+ * identity fields, or a reason string when the file is invalid.
+ */
+export declare function validateEntityFrontmatter(fm: Record<string, unknown>): EntityFields | string;
+export interface NewEntity {
+    type: string;
+    canonicalName: string;
+    aliases: string[];
+    confidence: number;
+    now: string;
+    signalCount: number;
+}
+/** A new entity file in the cloud schema, with a `# Name` heading. */
+export declare function renderNewEntity(entity: NewEntity): string;
+export interface EntityPatch {
+    addAliases?: string[];
+    signalCount?: number;
+    lastUpdated: string;
+    /** The caller changed the body, so `last_updated` moves even with no key change. */
+    bodyChanged?: boolean;
+}
+export type PatchResult = {
+    ok: true;
+    content: string;
+    changed: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Patch an existing, valid entity file. Aliases are only appended, and
+ * `signal_count` never goes down. When nothing but `last_updated` would
+ * change, the file is returned unchanged so a rerun writes nothing.
+ */
+export declare function patchEntityFile(content: string, patch: EntityPatch): PatchResult;
+export interface SignalBackRef {
+    signalType: string;
+    preview: string;
+    href: string;
+}
+/** hq-pro `previewSignalContent`: first 80 characters, one line. */
+export declare function previewSignalContent(canonicalContent: string): string;
+/**
+ * hq-pro `appendBackRefsToBody`: add `- Referenced in [<type>: <preview>](<href>)`
+ * lines to `## Relationships`, keyed on the link target. Existing lines are
+ * never removed or reworded.
+ */
+export declare function appendBackRefs(fullContent: string, refs: SignalBackRef[]): {
+    content: string;
+    added: number;
+};
+//# sourceMappingURL=entity-file.d.ts.map

package/dist/lib/checkpoint-ontology/entity-file.js

@@ -0,0 +1,264 @@
+/**
+ * Read, validate, create and patch ontology entity files.
+ *
+ * The cloud read model validates every synced entity file (hq-pro
+ * `validator.ts`): required frontmatter fields, and `id` equal to
+ * sha256(type:canonical_name) unless `identity_version >= 2`. Every file this
+ * module produces is re-parsed and validated before it is written.
+ *
+ * Existing files are patched in place. Only three frontmatter keys are
+ * rewritten (`aliases`, `signal_count`, `last_updated`); every other line is
+ * kept byte for byte, and the result is checked to parse to the same values
+ * for every other key.
+ */
+import { isDeepStrictEqual } from "node:util";
+import yaml from "js-yaml";
+import { entityId } from "./identity.js";
+// Same delimiters as hq-pro `parser.ts`.
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/**
+ * Parse with the YAML 1.2 core schema, as the cloud's `yaml` package does.
+ * js-yaml's default schema would turn unquoted timestamps into Date objects.
+ */
+export function parseEntityFile(content) {
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match)
+        return null;
+    let raw;
+    try {
+        raw = yaml.load(match[1], { schema: yaml.CORE_SCHEMA });
+    }
+    catch {
+        return null;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    return { frontmatter: raw, body: match[2] };
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/**
+ * The hq-pro validator rules this writer can break. Returns the entity's
+ * identity fields, or a reason string when the file is invalid.
+ */
+export function validateEntityFrontmatter(fm) {
+    if (typeof fm.id !== "string" || fm.id === "")
+        return "id";
+    if (typeof fm.type !== "string" || fm.type === "")
+        return "type";
+    if (typeof fm.canonical_name !== "string" || fm.canonical_name === "")
+        return "canonical_name";
+    if (!isStringArray(fm.aliases))
+        return "aliases";
+    if (typeof fm.confidence !== "number" || fm.confidence < 0 || fm.confidence > 1)
+        return "confidence";
+    if (fm.status !== "draft" && fm.status !== "confirmed")
+        return "status";
+    if (!isStringArray(fm.domain))
+        return "domain";
+    if (typeof fm.first_seen !== "string" || fm.first_seen === "")
+        return "first_seen";
+    if (typeof fm.last_updated !== "string" || fm.last_updated === "")
+        return "last_updated";
+    if (typeof fm.signal_count !== "number" || !Number.isInteger(fm.signal_count) || fm.signal_count < 0) {
+        return "signal_count";
+    }
+    let identityVersion;
+    if (fm.identity_version !== undefined) {
+        if (typeof fm.identity_version !== "number" || !Number.isInteger(fm.identity_version) || fm.identity_version < 1) {
+            return "identity_version";
+        }
+        identityVersion = fm.identity_version;
+    }
+    if ((identityVersion ?? 1) < 2 && fm.id !== entityId(fm.type, fm.canonical_name))
+        return "id_mismatch";
+    return {
+        id: fm.id,
+        type: fm.type,
+        canonical_name: fm.canonical_name,
+        aliases: fm.aliases,
+        signal_count: fm.signal_count,
+        ...(identityVersion === undefined ? {} : { identity_version: identityVersion }),
+    };
+}
+/** A YAML double-quoted scalar. JSON string syntax is valid YAML. */
+function quote(value) {
+    return JSON.stringify(value);
+}
+function renderAliases(aliases) {
+    if (aliases.length === 0)
+        return "aliases: []";
+    return ["aliases:", ...aliases.map((alias) => `  - ${quote(alias)}`)].join("\n");
+}
+/** A new entity file in the cloud schema, with a `# Name` heading. */
+export function renderNewEntity(entity) {
+    return [
+        "---",
+        `id: ${entityId(entity.type, entity.canonicalName)}`,
+        `type: ${entity.type}`,
+        `canonical_name: ${quote(entity.canonicalName)}`,
+        renderAliases(entity.aliases),
+        `confidence: ${entity.confidence}`,
+        "status: draft",
+        "domain: []",
+        `first_seen: ${entity.now}`,
+        `last_updated: ${entity.now}`,
+        `signal_count: ${entity.signalCount}`,
+        "---",
+        "",
+        `# ${entity.canonicalName}`,
+        "",
+    ].join("\n");
+}
+const OWNED_KEYS = new Set(["aliases", "signal_count", "last_updated"]);
+/**
+ * Replace one top-level key in a raw frontmatter block. The key's value may
+ * span several lines (a block sequence); continuation lines are the ones that
+ * start with whitespace or `- `. Returns null when the key is absent.
+ */
+function replaceTopLevelKey(lines, key, rendered) {
+    const start = lines.findIndex((line) => line === `${key}:` || line.startsWith(`${key}: `) || line.startsWith(`${key}:\t`));
+    if (start === -1)
+        return null;
+    let end = start + 1;
+    while (end < lines.length && (/^\s/.test(lines[end]) || lines[end].startsWith("- ") || lines[end] === "-"))
+        end += 1;
+    return [...lines.slice(0, start), ...rendered.split("\n"), ...lines.slice(end)];
+}
+/**
+ * Append alias items to a block-style `aliases:` sequence, leaving the existing
+ * item lines untouched. Falls back to re-rendering the whole key for flow style
+ * (`aliases: []`, `aliases: [a, b]`). Returns null when the key is absent.
+ */
+function appendAliases(lines, all, added) {
+    const start = lines.findIndex((line) => line === "aliases:" || /^aliases:\s*(#.*)?$/.test(line));
+    if (start === -1)
+        return replaceTopLevelKey(lines, "aliases", renderAliases(all));
+    let end = start + 1;
+    while (end < lines.length && (/^\s/.test(lines[end]) || lines[end].startsWith("- ") || lines[end] === "-"))
+        end += 1;
+    const firstItem = lines.slice(start + 1, end).find((line) => /^\s*- /.test(line) || /^\s*-$/.test(line));
+    const indent = firstItem ? /^(\s*)/.exec(firstItem)[1] : "  ";
+    return [...lines.slice(0, end), ...added.map((alias) => `${indent}- ${quote(alias)}`), ...lines.slice(end)];
+}
+/**
+ * Patch an existing, valid entity file. Aliases are only appended, and
+ * `signal_count` never goes down. When nothing but `last_updated` would
+ * change, the file is returned unchanged so a rerun writes nothing.
+ */
+export function patchEntityFile(content, patch) {
+    const match = FRONTMATTER_RE.exec(content);
+    const parsed = parseEntityFile(content);
+    if (!match || !parsed)
+        return { ok: false, reason: "unparseable" };
+    const before = validateEntityFrontmatter(parsed.frontmatter);
+    if (typeof before === "string")
+        return { ok: false, reason: `invalid_existing:${before}` };
+    const aliases = [...before.aliases];
+    for (const alias of patch.addAliases ?? []) {
+        if (!aliases.includes(alias))
+            aliases.push(alias);
+    }
+    const signalCount = Math.max(before.signal_count, patch.signalCount ?? 0);
+    const aliasesChanged = aliases.length !== before.aliases.length;
+    const countChanged = signalCount !== before.signal_count;
+    if (!aliasesChanged && !countChanged && !patch.bodyChanged)
+        return { ok: true, content, changed: false };
+    const newline = content.includes("\r\n") ? "\r\n" : "\n";
+    let lines = match[1].split(/\r?\n/);
+    if (aliasesChanged)
+        lines = appendAliases(lines, aliases, aliases.slice(before.aliases.length));
+    if (lines && countChanged)
+        lines = replaceTopLevelKey(lines, "signal_count", `signal_count: ${signalCount}`);
+    if (lines)
+        lines = replaceTopLevelKey(lines, "last_updated", `last_updated: ${patch.lastUpdated}`);
+    if (!lines)
+        return { ok: false, reason: "missing_owned_key" };
+    const head = content.slice(0, content.indexOf(match[1]));
+    const tail = content.slice(content.indexOf(match[1]) + match[1].length);
+    const next = `${head}${lines.join(newline)}${tail}`;
+    const check = checkPatched(parsed.frontmatter, next, aliases, signalCount, patch.lastUpdated);
+    if (check)
+        return { ok: false, reason: check };
+    return { ok: true, content: next, changed: true };
+}
+/** The patched file must validate and keep every key it does not own. */
+function checkPatched(original, next, aliases, signalCount, lastUpdated) {
+    const reparsed = parseEntityFile(next);
+    if (!reparsed)
+        return "patch_unparseable";
+    if (typeof validateEntityFrontmatter(reparsed.frontmatter) === "string")
+        return "patch_invalid";
+    const keys = new Set([...Object.keys(original), ...Object.keys(reparsed.frontmatter)]);
+    for (const key of keys) {
+        if (OWNED_KEYS.has(key))
+            continue;
+        if (!isDeepStrictEqual(original[key], reparsed.frontmatter[key]))
+            return `patch_changed_key:${key}`;
+    }
+    if (!isDeepStrictEqual(reparsed.frontmatter.aliases, aliases))
+        return "patch_aliases";
+    if (reparsed.frontmatter.signal_count !== signalCount)
+        return "patch_signal_count";
+    if (reparsed.frontmatter.last_updated !== lastUpdated)
+        return "patch_last_updated";
+    return null;
+}
+/** hq-pro `previewSignalContent`: first 80 characters, one line. */
+export function previewSignalContent(canonicalContent) {
+    const collapsed = canonicalContent.replace(/\s+/g, " ").trim();
+    return collapsed.length > 80 ? collapsed.slice(0, 80) : collapsed;
+}
+/**
+ * The company-relative target of a back-reference link. The gardener writes
+ * `../../signals/...` and hq-cli writes `../../../signals/...`; both name the
+ * same signal.
+ */
+function backRefTarget(href) {
+    return href.replace(/^(?:\.\.\/)+/, "");
+}
+/**
+ * hq-pro `appendBackRefsToBody`: add `- Referenced in [<type>: <preview>](<href>)`
+ * lines to `## Relationships`, keyed on the link target. Existing lines are
+ * never removed or reworded.
+ */
+export function appendBackRefs(fullContent, refs) {
+    if (refs.length === 0)
+        return { content: fullContent, added: 0 };
+    const fmMatch = /^(---\r?\n[\s\S]*?\r?\n---\r?\n?)([\s\S]*)$/.exec(fullContent);
+    if (!fmMatch)
+        return { content: fullContent, added: 0 };
+    const frontmatter = fmMatch[1];
+    const body = fmMatch[2];
+    const sectionMatch = /(^|\n)(##\s+Relationships\s*\n)([\s\S]*?)(?=\n##\s|\s*$)/.exec(body);
+    const existing = new Set();
+    if (sectionMatch) {
+        for (const link of sectionMatch[3].matchAll(/\]\(([^)]+)\)/g))
+            existing.add(backRefTarget(link[1]));
+    }
+    const fresh = [];
+    for (const ref of refs) {
+        if (existing.has(backRefTarget(ref.href)))
+            continue;
+        existing.add(backRefTarget(ref.href));
+        fresh.push(ref);
+    }
+    if (fresh.length === 0)
+        return { content: fullContent, added: 0 };
+    const newLines = fresh.map((ref) => `- Referenced in [${ref.signalType}: ${ref.preview}](${ref.href})`).join("\n");
+    let nextBody;
+    if (sectionMatch) {
+        const before = body.slice(0, sectionMatch.index + sectionMatch[1].length);
+        const header = sectionMatch[2];
+        const section = sectionMatch[3].replace(/\s+$/, "");
+        const after = body.slice(sectionMatch.index + sectionMatch[0].length);
+        nextBody = `${before}${header}${section ? `${section}\n${newLines}` : newLines}\n${after}`;
+    }
+    else {
+        const trimmed = body.replace(/\s+$/, "");
+        nextBody = `${trimmed.length > 0 ? `${trimmed}\n\n` : "\n"}## Relationships\n\n${newLines}\n`;
+    }
+    return { content: `${frontmatter}${nextBody}`, added: fresh.length };
+}
+//# sourceMappingURL=entity-file.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * Entity identity rules shared with the hq-pro ontology.
+ *
+ * `normalizeEntityName` and `toSlug` are ports of hq-pro
+ * `src/ontology/entity-normalize.ts` and `src/ontology/file-writer.ts`, and
+ * `entityId` is hq-pro `generateEntityId`. The read model validates every
+ * synced entity file with these rules, so they must match byte for byte.
+ */
+/** The entity types this writer creates or updates. */
+export declare const WRITABLE_ENTITY_TYPES: readonly ["person", "project", "company", "concept"];
+export type WritableEntityType = (typeof WRITABLE_ENTITY_TYPES)[number];
+export declare function isWritableEntityType(value: unknown): value is WritableEntityType;
+/**
+ * hq-pro `normalizeEntityName`. Organisation types drop punctuation and
+ * trailing corporate suffixes; every other type keeps `+` and `#` so `C` and
+ * `C++` stay distinct.
+ */
+export declare function normalizeEntityName(name: string, type?: string): string;
+/** hq-pro `toSlug`: the entity file name without `.md`. */
+export declare function toSlug(canonicalName: string): string;
+/** hq-pro `generateEntityId`: sha256 of `<type>:<canonical_name>`. */
+export declare function entityId(type: string, canonicalName: string): string;
+/**
+ * The canonical form of a new name: NFC, trimmed, internal whitespace
+ * collapsed to one space. The id is hashed from exactly this string.
+ */
+export declare function canonicalizeName(raw: string): string;
+/** A normalised name with its spaces removed (`recall ai` → `recallai`). */
+export declare function squash(normalized: string): string;
+/**
+ * True when a name must not become a new entity: empty, one character, only
+ * digits, or a single common word. `github` and `slack` are here because the
+ * common-noun use dominates; the real companies already exist in the tree
+ * and are matched by tiers 1 and 2 before this filter runs.
+ */
+export declare function isRejectedName(normalized: string): boolean;
+//# sourceMappingURL=identity.d.ts.map

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

@@ -0,0 +1,95 @@
+/**
+ * Entity identity rules shared with the hq-pro ontology.
+ *
+ * `normalizeEntityName` and `toSlug` are ports of hq-pro
+ * `src/ontology/entity-normalize.ts` and `src/ontology/file-writer.ts`, and
+ * `entityId` is hq-pro `generateEntityId`. The read model validates every
+ * synced entity file with these rules, so they must match byte for byte.
+ */
+import { createHash } from "node:crypto";
+/** The entity types this writer creates or updates. */
+export const WRITABLE_ENTITY_TYPES = ["person", "project", "company", "concept"];
+export function isWritableEntityType(value) {
+    return typeof value === "string" && WRITABLE_ENTITY_TYPES.includes(value);
+}
+const CORPORATE_SUFFIXES = new Set([
+    "inc", "incorporated", "llc", "llp", "lp", "ltd", "limited", "corp", "corporation",
+    "co", "company", "gmbh", "ag", "sa", "sas", "srl", "bv", "nv", "plc", "pty", "pte",
+    "kg", "oy", "ab", "as", "spa",
+]);
+const ORG_NORMALIZED_TYPES = new Set([
+    "company", "contact", "deal", "contract", "invoice", "account", "journal-entry",
+    "ar-invoice", "ap-bill",
+]);
+/**
+ * hq-pro `normalizeEntityName`. Organisation types drop punctuation and
+ * trailing corporate suffixes; every other type keeps `+` and `#` so `C` and
+ * `C++` stay distinct.
+ */
+export function normalizeEntityName(name, type) {
+    if (type !== undefined && !ORG_NORMALIZED_TYPES.has(type)) {
+        return name.toLowerCase().replace(/[^a-z0-9+#]+/g, " ").trim();
+    }
+    const base = name.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+    if (base === "")
+        return "";
+    let tokens = base.split(" ").filter((token) => token !== "");
+    while (tokens.length > 1 && CORPORATE_SUFFIXES.has(tokens[tokens.length - 1])) {
+        tokens = tokens.slice(0, -1);
+    }
+    return tokens.join(" ");
+}
+/** hq-pro `toSlug`: the entity file name without `.md`. */
+export function toSlug(canonicalName) {
+    return canonicalName
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/** hq-pro `generateEntityId`: sha256 of `<type>:<canonical_name>`. */
+export function entityId(type, canonicalName) {
+    return createHash("sha256").update(`${type}:${canonicalName}`).digest("hex");
+}
+/**
+ * The canonical form of a new name: NFC, trimmed, internal whitespace
+ * collapsed to one space. The id is hashed from exactly this string.
+ */
+export function canonicalizeName(raw) {
+    return raw.normalize("NFC").replace(/\s+/g, " ").trim();
+}
+/** A normalised name with its spaces removed (`recall ai` → `recallai`). */
+export function squash(normalized) {
+    return normalized.replace(/ /g, "");
+}
+/**
+ * Names that are never created as entities. The gardener's false positives on
+ * indigo were mostly single common words linked as entities ("metadata",
+ * "For", "AI", "Index", "personal").
+ */
+const STOPWORDS = new Set([
+    "a", "an", "the", "and", "or", "for", "to", "of", "in", "on", "at", "by", "with", "from",
+    "ai", "api", "app", "apps", "data", "index", "metadata", "personal", "private", "public",
+    "user", "users", "team", "teams", "company", "companies", "project", "projects", "product",
+    "system", "service", "services", "tool", "tools", "file", "files", "doc", "docs", "readme",
+    "config", "configuration", "test", "tests", "update", "updates", "new", "note", "notes",
+    "plan", "summary", "overview", "architecture", "conventions", "environment", "setup",
+    "meeting", "meetings", "customer", "customers", "client", "clients", "agent", "agents",
+    "worker", "workers", "session", "sessions", "task", "tasks", "issue", "issues", "bug",
+    "bugs", "feature", "features", "release", "releases", "email",
+]);
+/**
+ * True when a name must not become a new entity: empty, one character, only
+ * digits, or a single common word. `github` and `slack` are here because the
+ * common-noun use dominates; the real companies already exist in the tree
+ * and are matched by tiers 1 and 2 before this filter runs.
+ */
+export function isRejectedName(normalized) {
+    if (normalized.length < 2)
+        return true;
+    if (/^[0-9 ]+$/.test(normalized))
+        return true;
+    return STOPWORDS.has(normalized);
+}
+//# sourceMappingURL=identity.js.map

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

@@ -0,0 +1,124 @@
+/**
+ * `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 OntologyCompany } from "./company.js";
+export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
+export declare const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
+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";
+export declare const LEDGER_SCHEMA = "hq-checkpoint-ontology-ledger.v1";
+export declare const BUDGET: {
+    readonly maxInputs: 20;
+    readonly maxTokens: 60000;
+    readonly chunkTokens: 12000;
+};
+export type PendingReason = "session-touched" | "shared" | "first-run-gap" | "missing-refs";
+export 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[];
+}
+export interface OntologyPlan {
+    schema: typeof PLAN_SCHEMA;
+    company: string;
+    run_id: string;
+    created_at: string;
+    first_run: boolean;
+    boundary: string | null;
+    shared_inputs: boolean;
+    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;
+    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;
+}
+export type PlanOutcome = {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "planned";
+    plan: OntologyPlan;
+    planPath: string;
+};
+export declare function ledgerPath(hqRoot: string, company: OntologyCompany): string;
+export declare function readLedger(hqRoot: string, company: OntologyCompany): Ledger | null;
+export declare function writeLedger(hqRoot: string, company: OntologyCompany, ledger: Ledger): void;
+/** Company-relative paths of the payload's touched files that are inside this company. */
+export declare function sessionTouched(hqRoot: string, company: OntologyCompany, files: unknown): Set<string>;
+/** 1-based line ranges, each at most `chunkTokens` tokens (bytes / 4). */
+export declare function chunkLines(content: string, chunkTokens: number): Array<[number, number]>;
+/**
+ * Update the ledger with the current tree and return it. New or changed files
+ * become pending when this machine should process them (design 14.1) and
+ * seen otherwise. The first run seeds from the entity boundary (design 14.3).
+ */
+export declare function refreshLedger(company: OntologyCompany, existing: Ledger | null, touched: Set<string>, sharedInputs: boolean): {
+    ledger: Ledger;
+    firstRun: boolean;
+};
+/** Plan this run. Never throws for a skip; returns the reason instead. */
+export declare function planOntologyRun(options: PlanOptions): Promise<PlanOutcome>;
+//# sourceMappingURL=plan.d.ts.map