@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -0,0 +1,109 @@
+/**
+ * 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;
+/** The frontmatter keys a checkpoint may change in an existing file. */
+export declare const OWNED_KEYS: ReadonlySet<string>;
+export interface EntityPatch {
+    addAliases?: string[];
+    /** Exact alias strings to remove (reviewed wrong aliases). Applied before `addAliases`. */
+    removeAliases?: 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 appended, and removed
+ * only when `removeAliases` names them exactly; `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;
+/** A namespaced record in a source system, as the cloud schema's `external_refs` holds it. */
+export interface ExternalRef {
+    system: string;
+    namespace: string;
+    objectType?: string;
+    recordId: string;
+}
+export interface IdentityPatch {
+    externalIds: Record<string, string>;
+    webDomains: string[];
+    /** When set, the whole `external_refs` list; when absent, the key is left alone. */
+    externalRefs?: ExternalRef[];
+    lastUpdated: string;
+}
+/**
+ * Set `external_ids` and `web_domains` on an existing, valid entity file.
+ * A key whose value is already equal is left as it is; an absent key is
+ * appended at the end of the front matter. Nothing else changes except
+ * `last_updated`. When neither key changes the file is returned unchanged.
+ */
+export declare function setIdentityKeys(content: string, patch: IdentityPatch): 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,371 @@
+/**
+ * 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");
+}
+/** The frontmatter keys a checkpoint may change in an existing file. */
+export 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 appended, and removed
+ * only when `removeAliases` names them exactly; `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 remove = new Set(patch.removeAliases ?? []);
+    const kept = before.aliases.filter((alias) => !remove.has(alias));
+    const aliases = [...kept];
+    for (const alias of patch.addAliases ?? []) {
+        if (!aliases.includes(alias))
+            aliases.push(alias);
+    }
+    const signalCount = Math.max(before.signal_count, patch.signalCount ?? 0);
+    const removed = kept.length !== before.aliases.length;
+    const aliasesChanged = removed || 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 (removed)
+        lines = replaceTopLevelKey(lines, "aliases", renderAliases(aliases));
+    else 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;
+}
+function renderExternalIds(ids) {
+    const entries = Object.entries(ids);
+    if (entries.length === 0)
+        return "external_ids: {}";
+    return ["external_ids:", ...entries.map(([key, value]) => `  ${key}: ${quote(value)}`)].join("\n");
+}
+function renderExternalRefs(refs) {
+    if (refs.length === 0)
+        return "external_refs: []";
+    const lines = ["external_refs:"];
+    for (const ref of refs) {
+        lines.push(`  - system: ${quote(ref.system)}`, `    namespace: ${quote(ref.namespace)}`);
+        if (ref.objectType !== undefined)
+            lines.push(`    objectType: ${quote(ref.objectType)}`);
+        lines.push(`    recordId: ${quote(ref.recordId)}`);
+    }
+    return lines.join("\n");
+}
+function renderWebDomains(domains) {
+    if (domains.length === 0)
+        return "web_domains: []";
+    return ["web_domains:", ...domains.map((domain) => `  - ${quote(domain)}`)].join("\n");
+}
+/**
+ * Set `external_ids` and `web_domains` on an existing, valid entity file.
+ * A key whose value is already equal is left as it is; an absent key is
+ * appended at the end of the front matter. Nothing else changes except
+ * `last_updated`. When neither key changes the file is returned unchanged.
+ */
+export function setIdentityKeys(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}` };
+    for (const key of Object.keys(patch.externalIds)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(key))
+            return { ok: false, reason: "external_ids_key" };
+    }
+    const currentIds = (parsed.frontmatter.external_ids ?? {});
+    const currentDomains = (parsed.frontmatter.web_domains ?? []);
+    const currentRefs = parsed.frontmatter.external_refs ?? [];
+    const idsChanged = !isDeepStrictEqual(currentIds, patch.externalIds);
+    const domainsChanged = !isDeepStrictEqual(currentDomains, patch.webDomains);
+    const refsChanged = patch.externalRefs !== undefined && !isDeepStrictEqual(currentRefs, patch.externalRefs);
+    if (!idsChanged && !domainsChanged && !refsChanged)
+        return { ok: true, content, changed: false };
+    const newline = content.includes("\r\n") ? "\r\n" : "\n";
+    let lines = match[1].split(/\r?\n/);
+    if (idsChanged) {
+        const rendered = renderExternalIds(patch.externalIds);
+        lines = replaceTopLevelKey(lines, "external_ids", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    if (domainsChanged) {
+        const rendered = renderWebDomains(patch.webDomains);
+        lines = replaceTopLevelKey(lines, "web_domains", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    if (refsChanged) {
+        const rendered = renderExternalRefs(patch.externalRefs);
+        lines = replaceTopLevelKey(lines, "external_refs", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    const stamped = replaceTopLevelKey(lines, "last_updated", `last_updated: ${patch.lastUpdated}`);
+    if (!stamped)
+        return { ok: false, reason: "missing_owned_key" };
+    lines = stamped;
+    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 reparsed = parseEntityFile(next);
+    if (!reparsed)
+        return { ok: false, reason: "patch_unparseable" };
+    if (typeof validateEntityFrontmatter(reparsed.frontmatter) === "string")
+        return { ok: false, reason: "patch_invalid" };
+    const keys = new Set([...Object.keys(parsed.frontmatter), ...Object.keys(reparsed.frontmatter)]);
+    for (const key of keys) {
+        if (key === "external_ids" || key === "web_domains" || key === "last_updated")
+            continue;
+        if (key === "external_refs" && patch.externalRefs !== undefined)
+            continue;
+        if (!isDeepStrictEqual(parsed.frontmatter[key], reparsed.frontmatter[key])) {
+            return { ok: false, reason: `patch_changed_key:${key}` };
+        }
+    }
+    if (!isDeepStrictEqual(reparsed.frontmatter.external_ids ?? {}, patch.externalIds)) {
+        return { ok: false, reason: "patch_external_ids" };
+    }
+    if (!isDeepStrictEqual(reparsed.frontmatter.web_domains ?? [], patch.webDomains)) {
+        return { ok: false, reason: "patch_web_domains" };
+    }
+    if (refsChanged && !isDeepStrictEqual(reparsed.frontmatter.external_refs ?? [], patch.externalRefs)) {
+        return { ok: false, reason: "patch_external_refs" };
+    }
+    if (reparsed.frontmatter.last_updated !== patch.lastUpdated)
+        return { ok: false, reason: "patch_last_updated" };
+    if (reparsed.body !== parsed.body)
+        return { ok: false, reason: "patch_body" };
+    return { ok: true, content: next, changed: true };
+}
+/** 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,38 @@
+/**
+ * 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. */
+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;
+export {};
+//# 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. */
+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