@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/model-metrics.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedEntity } from "./analyze.js";
+import type { Diagnostic, DiagnosticCode } from "./diagnostics.js";
+import type { ModelMetricManifest } from "./manifest.js";
+type Report = (code: DiagnosticCode, path: string, message: string, severity?: Diagnostic["severity"]) => void;
+/** The most metrics a model declares. */
+export declare const MAXIMUM_MODEL_METRICS = 50;
+/** The most distinct entity metrics one model metric reads, references expanded. */
+export declare const MAXIMUM_MODEL_METRIC_INPUTS = 10;
+/** The most alignment groups one model metric declares. */
+export declare const MAXIMUM_ALIGNMENT_GROUPS = 5;
+/**
+ * Resolves and checks the metrics of the model, `defineOntology({ metrics })`, against the
+ * resolved entities, whose metrics were checked first (docs/ontology-aggregates-release-3-spec.md,
+ * "Declaring model metrics"). Returns the manifest form of each metric that passed, in declaration
+ * order: references expanded, names on the wire, inputs in reading order.
+ */
+export declare function resolveModelMetrics(input: {
+    readonly metrics: unknown;
+    readonly entities: ReadonlyArray<ResolvedEntity>;
+    readonly report: Report;
+}): ReadonlyArray<ModelMetricManifest>;
+export {};

package/dist/model-metrics.js

@@ -0,0 +1,545 @@
+import { dimensionTypeOf } from "./metric-filters.js";
+import { isRecord, nameToWire } from "./authoring-names.js";
+import { METRIC_AGGREGATES } from "./metric.js";
+import { EARLIER_QUERY_METRICS_ROUTE } from "./legacy.js";
+import { humanize, RESERVED_ENTITY_NAMES, SNAKE_CASE_NAME, toCamelCase } from "./names.js";
+/** The most metrics a model declares. */
+export const MAXIMUM_MODEL_METRICS = 50;
+/** The most distinct entity metrics one model metric reads, references expanded. */
+export const MAXIMUM_MODEL_METRIC_INPUTS = 10;
+/** The most alignment groups one model metric declares. */
+export const MAXIMUM_ALIGNMENT_GROUPS = 5;
+/** The deepest and the largest expression a model metric expands to. */
+const MAXIMUM_DEPTH = 30;
+const MAXIMUM_NODES = 1000;
+const SEPARATOR = ".";
+const UNITS = ["number", "currency", "ratio", "percent"];
+const FORMATS = ["decimal", "currency", "percent"];
+const ARITHMETIC = ["add", "subtract", "multiply", "divide"];
+/** What only an entity metric contains: an aggregate, its condition and the column it reads. */
+const AGGREGATE_NODES = [...METRIC_AGGREGATES, "filtered", "column"];
+const LITERAL = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/;
+const NAMES = "Model metrics require unique snake_case names and a description.";
+const AGGREGATES = "Model metrics combine entity metrics; declare the aggregate on its entity.";
+const CYCLE = "Metric references cannot form a cycle.";
+const COMPLEX = "Invalid or overly complex expression.";
+const NO_INPUT = 'A model metric reads at least one entity metric: m.ref("entity.metric").';
+const TOO_MANY_INPUTS = `A model metric reads at most ${MAXIMUM_MODEL_METRIC_INPUTS} entity metrics.`;
+const ALIGNMENT_SHAPE = "align is a list of groups, each naming every entity the metric reads with its property or " +
+    'null, such as [{ sales: "orderDate", plans: "month" }].';
+const ALL_NULL = "An alignment names a property for at least one entity.";
+const NESTED_ALIGN = "align belongs on the model metric, not on an argument of its expression.";
+const NO_WHERE = "A model metric takes no where; declare a filtered metric on the entity and read it.";
+const NO_BALANCE = "A model metric takes no balanceOver; declare the balance on the entity and read it.";
+function isBlank(value) {
+    return typeof value !== "string" || value.trim().length === 0;
+}
+/** The wire name of a name that round-trips: `planAttainment` or `plan_attainment`. */
+function wireNameOf(name) {
+    const wire = nameToWire(name);
+    return SNAKE_CASE_NAME.test(wire) && (name === wire || toCamelCase(wire) === name)
+        ? wire
+        : undefined;
+}
+/**
+ * The declared model metrics under their wire names, each a unique snake_case name, not an
+ * entity's and not a route's, with a description. A metric whose name is refused is not resolved
+ * further.
+ */
+function declare(input) {
+    const { metrics, entities, report } = input;
+    const declared = new Map();
+    for (const [name, metric] of Object.entries(metrics)) {
+        const wire = wireNameOf(name);
+        const path = `metrics.${wire ?? name}`;
+        if (wire === undefined || declared.has(wire) || !isRecord(metric)) {
+            report("invalid-metric", path, NAMES);
+            continue;
+        }
+        if (isBlank(metric.description)) {
+            report("invalid-metric", path, NAMES);
+        }
+        if (entities.has(wire)) {
+            report("duplicate-name", path, `${wire} is also an entity name.`);
+            continue;
+        }
+        if (RESERVED_ENTITY_NAMES.includes(wire) ||
+            wire === EARLIER_QUERY_METRICS_ROUTE) {
+            report("reserved-name", path, `${wire} is a reserved name.`);
+            continue;
+        }
+        declared.set(wire, { name: wire, path, metric });
+    }
+    return declared;
+}
+/** Whether an entity declares a metric, by wire names. */
+function declaresMetric(entity, metric) {
+    const metrics = entity?.entity.definition.metrics ?? {};
+    return metric !== undefined && Object.hasOwn(metrics, metric);
+}
+/**
+ * Expands every model metric: a reference to an entity metric becomes a `metric` node naming
+ * `entity.metric` in wire names, and a reference to another model metric that metric's expanded
+ * expression. A metric whose expansion fails maps to `undefined`; its reason is reported once, at
+ * the metric where it occurs.
+ */
+function expandAll(input) {
+    const { declared, entities, report } = input;
+    const expansions = new Map();
+    const pending = new Set();
+    const expand = (current) => {
+        if (expansions.has(current.name)) {
+            return expansions.get(current.name);
+        }
+        const reported = new Set();
+        const references = new Set();
+        let failed = false;
+        let nodes = 0;
+        const refuse = (code, message) => {
+            failed = true;
+            if (!reported.has(message)) {
+                reported.add(message);
+                report(code, current.path, message);
+            }
+            return undefined;
+        };
+        const unknown = (name) => refuse("unknown-metric", `${current.name} reads ${name}, which the ontology does not declare.`);
+        /** A reference: `entity.metric` in TypeScript names per segment, or a model metric's name. */
+        const reference = (name, depth) => {
+            if (typeof name !== "string" || name.length === 0) {
+                return refuse("invalid-metric", "Invalid expression operator or arity.");
+            }
+            if (name.includes(SEPARATOR)) {
+                const wire = name.split(SEPARATOR).map(nameToWire).join(SEPARATOR);
+                const [owner, metric, ...rest] = wire.split(SEPARATOR);
+                if (rest.length > 0 || !declaresMetric(entities.get(owner ?? ""), metric)) {
+                    return unknown(wire);
+                }
+                return { op: "metric", name: wire };
+            }
+            const wire = nameToWire(name);
+            const target = declared.get(wire);
+            if (target === undefined) {
+                return unknown(wire);
+            }
+            if (pending.has(wire)) {
+                return refuse("circular-metric", CYCLE);
+            }
+            const inner = expand(target);
+            references.add(wire);
+            if (inner === undefined) {
+                failed = true;
+                return undefined;
+            }
+            nodes += inner.nodes - 1;
+            if (depth + inner.depth > MAXIMUM_DEPTH || nodes > MAXIMUM_NODES) {
+                return refuse("invalid-metric", COMPLEX);
+            }
+            return inner.expression;
+        };
+        const visit = (node, depth) => {
+            nodes += 1;
+            if (depth > MAXIMUM_DEPTH || nodes > MAXIMUM_NODES || !isRecord(node)) {
+                return refuse("invalid-metric", COMPLEX);
+            }
+            const { op } = node;
+            // Options of an argument are not the metric's: only the root declares them.
+            if (depth > 0 && node.align !== undefined) {
+                refuse("invalid-alignment", NESTED_ALIGN);
+            }
+            if (AGGREGATE_NODES.includes(op)) {
+                return refuse("invalid-metric", AGGREGATES);
+            }
+            if (node.where !== undefined) {
+                refuse("invalid-metric", NO_WHERE);
+            }
+            if (node.balanceOver !== undefined) {
+                refuse("invalid-metric", NO_BALANCE);
+            }
+            if (op === "metric") {
+                return reference(node.name, depth);
+            }
+            if (op === "literal") {
+                const { value } = node;
+                if (typeof value !== "string" ||
+                    value.length >= 100 ||
+                    !LITERAL.test(value) ||
+                    !Number.isFinite(Number(value))) {
+                    return refuse("invalid-metric", "Literals must be finite numbers.");
+                }
+                return { op: "literal", value };
+            }
+            if (!ARITHMETIC.includes(op) || !Array.isArray(node.args) || node.args.length !== 2) {
+                return refuse("invalid-metric", "Invalid expression operator or arity.");
+            }
+            const args = node.args.map((arg) => visit(arg, depth + 1));
+            const [left, right] = args;
+            if (left === undefined || right === undefined) {
+                return undefined;
+            }
+            return { op: op, args: [left, right] };
+        };
+        pending.add(current.name);
+        const expression = visit(current.metric, 0);
+        pending.delete(current.name);
+        const expansion = failed || expression === undefined
+            ? undefined
+            : { expression, depth: depthOf(expression), nodes, references: [...references] };
+        expansions.set(current.name, expansion);
+        return expansion;
+    };
+    for (const candidate of declared.values()) {
+        expand(candidate);
+    }
+    return expansions;
+}
+function depthOf(expression) {
+    return "args" in expression ? 1 + Math.max(...expression.args.map(depthOf)) : 0;
+}
+/** The entity metrics an expanded expression reads, `entity.metric`, each once, in order. */
+function inputsOf(expression) {
+    if (expression.op === "metric") {
+        return [expression.name];
+    }
+    return "args" in expression ? [...new Set(expression.args.flatMap(inputsOf))] : [];
+}
+function ownerOf(input) {
+    return input.slice(0, input.indexOf(SEPARATOR));
+}
+/**
+ * The quantity an expression amounts to, by unit algebra: money times or over a number is money,
+ * money over money is a number, money times money is neither, and a sum with money is money.
+ * Records in `found` what the arithmetic does with two amounts of money.
+ */
+function quantityOf(input) {
+    const { expression, currency, found } = input;
+    if (expression.op === "metric") {
+        return currency(expression.name) ? "money" : "number";
+    }
+    if (!("args" in expression) || expression.args.length !== 2) {
+        return "number";
+    }
+    const [left, right] = expression.args.map((arg) => quantityOf({ expression: arg, currency, found }));
+    if (left === "neither" || right === "neither") {
+        return "neither";
+    }
+    const money = (left === "money" ? 1 : 0) + (right === "money" ? 1 : 0);
+    switch (expression.op) {
+        case "add":
+        case "subtract":
+            found.sum ||= money === 2;
+            return money > 0 ? "money" : "number";
+        case "multiply":
+            found.product ||= money === 2;
+            return money === 2 ? "neither" : money === 1 ? "money" : "number";
+        case "divide":
+            found.ratio ||= money === 2;
+            if (right === "money") {
+                return left === "money" ? "number" : "neither";
+            }
+            return left;
+        default:
+            return "number";
+    }
+}
+/** Why the declared unit contradicts the arithmetic of the currency inputs, if it does. */
+function unitIssue(input) {
+    const { unit, expression, currency } = input;
+    const found = { ratio: false, product: false, sum: false };
+    const quantity = quantityOf({ expression, currency, found });
+    if (unit === "currency" && quantity !== "money" && found.ratio) {
+        return "A ratio of two currency metrics is a ratio, not a currency.";
+    }
+    if (unit === "currency" && quantity !== "money" && found.product) {
+        return "A product of two currency metrics is not a currency.";
+    }
+    if ((unit === "ratio" || unit === "percent") && quantity === "money" && found.sum) {
+        return `A sum or difference of currency metrics is a currency, not a ${unit}.`;
+    }
+    return undefined;
+}
+/** A property an alignment may name: a declared property, or the `id` of a stored entity. */
+function dimensionOf(entity, property) {
+    const declared = entity.properties.find((candidate) => candidate.name === property);
+    if (declared !== undefined) {
+        return { type: declared.definition.type };
+    }
+    return entity.entity.definition.source === undefined && property === "id"
+        ? { type: "text" }
+        : undefined;
+}
+/**
+ * A model metric's alignment in wire names, each group naming every entity it reads, in reading
+ * order, or `undefined` when it is refused.
+ */
+function alignmentOf(input) {
+    const { metric, read, entities, refuse } = input;
+    const declared = metric.metric.align;
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared) || !declared.every(isRecord)) {
+        refuse("invalid-alignment", ALIGNMENT_SHAPE);
+        return undefined;
+    }
+    if (declared.length > 0 && read.length === 1) {
+        refuse("invalid-alignment", `${metric.name} reads one entity and needs no alignment.`);
+        return undefined;
+    }
+    if (declared.length > MAXIMUM_ALIGNMENT_GROUPS) {
+        refuse("invalid-alignment", `A model metric aligns at most ${MAXIMUM_ALIGNMENT_GROUPS} groups.`);
+        return undefined;
+    }
+    const aligned = new Set();
+    const groups = [];
+    let valid = true;
+    const invalid = (message) => {
+        valid = false;
+        refuse("invalid-alignment", message);
+    };
+    for (const group of declared) {
+        const members = Object.entries(group).map(([entity, property]) => ({
+            entity: nameToWire(entity),
+            property,
+        }));
+        const named = members.map(({ entity }) => entity);
+        if (named.length !== read.length ||
+            new Set(named).size !== named.length ||
+            !named.every((entity) => read.includes(entity))) {
+            invalid(`An alignment names every entity ${metric.name} reads exactly once.`);
+            continue;
+        }
+        const typed = [];
+        const wire = new Map();
+        for (const { entity, property } of members) {
+            if (property === null) {
+                wire.set(entity, null);
+                continue;
+            }
+            if (typeof property !== "string") {
+                invalid(ALIGNMENT_SHAPE);
+                continue;
+            }
+            const name = nameToWire(property);
+            const identity = `${entity}${SEPARATOR}${name}`;
+            const dimension = dimensionOf(entities.get(entity), name);
+            const type = dimension === undefined ? undefined : dimensionTypeOf(dimension.type);
+            if (dimension === undefined) {
+                invalid(`${entity} has no property ${name}.`);
+                continue;
+            }
+            if (type === undefined) {
+                invalid(`${identity} cannot be aligned: JSON and file properties are not dimensions.`);
+                continue;
+            }
+            if (aligned.has(identity)) {
+                invalid(`${identity} is aligned twice.`);
+            }
+            aligned.add(identity);
+            typed.push({ identity, type });
+            wire.set(entity, name);
+        }
+        if (members.every(({ property }) => property === null)) {
+            invalid(ALL_NULL);
+            continue;
+        }
+        const [first] = typed;
+        const differing = typed.find((candidate) => candidate.type !== first?.type);
+        if (first !== undefined && differing !== undefined) {
+            invalid(`${metric.name} aligns ${first.identity} with ${differing.identity}, whose types differ.`);
+        }
+        groups.push(Object.fromEntries(read.map((entity) => [entity, wire.get(entity) ?? null])));
+    }
+    return valid ? groups : undefined;
+}
+/** Whether two groups share a member: one entity aligned through the same property in both. */
+function sharesMember(group, other) {
+    return Object.entries(group).some(([entity, property]) => property !== null && other[entity] === property);
+}
+/** Why a group disagrees with a group of a metric it reads, on the entities that one names. */
+function disagreement(input) {
+    const { metric, group, source, inherited } = input;
+    for (const [entity, member] of Object.entries(inherited)) {
+        const own = group[entity] ?? null;
+        if (own === member) {
+            continue;
+        }
+        if (own !== null && member !== null) {
+            return (`${metric} aligns ${entity}${SEPARATOR}${own}, but ${source}, which it reads, aligns ` +
+                `${entity}${SEPARATOR}${member}.`);
+        }
+        if (own !== null) {
+            return (`${metric} aligns ${entity}${SEPARATOR}${own}, but ${source}, which it reads, gives ` +
+                `${entity} no counterpart.`);
+        }
+        return (`${metric} gives ${entity} no counterpart, but ${source}, which it reads, aligns ` +
+            `${entity}${SEPARATOR}${member}.`);
+    }
+    return undefined;
+}
+/**
+ * A model metric's effective alignment: its own groups, then every group of the model metrics it
+ * reads that it does not restate. A restated group must agree on every entity the read metric
+ * reads; an inherited group must name every entity this metric reads.
+ */
+function inheritAlignment(input) {
+    const { metric, read, own, sources, refuse } = input;
+    const groups = [...own];
+    let valid = true;
+    for (const source of sources) {
+        for (const inherited of source.align) {
+            const restated = groups.filter((group) => sharesMember(group, inherited));
+            const missing = read.find((entity) => !Object.hasOwn(inherited, entity));
+            for (const group of restated) {
+                const reason = disagreement({ metric, group, source: source.name, inherited });
+                if (reason !== undefined) {
+                    valid = false;
+                    refuse("invalid-alignment", reason);
+                }
+            }
+            if (restated.length > 0) {
+                continue;
+            }
+            if (missing !== undefined) {
+                valid = false;
+                refuse("invalid-alignment", `${metric} reads ${source.name}, whose alignment does not name ${missing}; align it ` +
+                    `in ${metric}.`);
+                continue;
+            }
+            groups.push(Object.fromEntries(read.map((entity) => [entity, inherited[entity] ?? null])));
+        }
+    }
+    if (valid && groups.length > MAXIMUM_ALIGNMENT_GROUPS) {
+        refuse("invalid-alignment", `A model metric aligns at most ${MAXIMUM_ALIGNMENT_GROUPS} groups.`);
+        return undefined;
+    }
+    return valid ? groups : undefined;
+}
+function formatOf(unit, format) {
+    if (format !== undefined) {
+        return format;
+    }
+    if (unit === "currency") {
+        return "currency";
+    }
+    return unit === "percent" ? "percent" : "decimal";
+}
+/**
+ * Resolves and checks the metrics of the model, `defineOntology({ metrics })`, against the
+ * resolved entities, whose metrics were checked first (docs/ontology-aggregates-release-3-spec.md,
+ * "Declaring model metrics"). Returns the manifest form of each metric that passed, in declaration
+ * order: references expanded, names on the wire, inputs in reading order.
+ */
+export function resolveModelMetrics(input) {
+    const { metrics, report } = input;
+    const entities = new Map(input.entities.map((candidate) => [candidate.name, candidate]));
+    if (metrics === undefined) {
+        return [];
+    }
+    if (!isRecord(metrics)) {
+        report("invalid-metric", "metrics", "metrics maps names to metrics built with m: { planAttainment: m.divide(…) }.");
+        return [];
+    }
+    const count = Object.keys(metrics).length;
+    if (count > MAXIMUM_MODEL_METRICS) {
+        report("invalid-metric", "metrics", `The ontology declares ${count} model metrics; the limit is ${MAXIMUM_MODEL_METRICS}.`);
+    }
+    const declared = declare({ metrics, entities, report });
+    const expansions = expandAll({ declared, entities, report });
+    const resolved = new Map();
+    /** A metric, after the model metrics it reads, whose alignment it inherits. */
+    const resolve = (metric) => {
+        const known = resolved.get(metric.name);
+        if (known !== undefined) {
+            return known;
+        }
+        const resolution = resolveMetric({
+            metric,
+            expansion: expansions.get(metric.name),
+            entities,
+            report,
+            resolveReference: (name) => resolve(declared.get(name)),
+        });
+        resolved.set(metric.name, resolution);
+        return resolution;
+    };
+    return [...declared.values()].flatMap((metric) => {
+        const { manifest } = resolve(metric);
+        return manifest === undefined ? [] : [manifest];
+    });
+}
+function resolveMetric(input) {
+    const { metric, expansion, entities, report, resolveReference } = input;
+    if (expansion === undefined) {
+        return {};
+    }
+    let refused = isBlank(metric.metric.description);
+    const refuse = (code, message) => {
+        refused = true;
+        report(code, metric.path, message);
+    };
+    const { expression } = expansion;
+    const { unit, format, label, description } = metric.metric;
+    const inputs = inputsOf(expression);
+    const read = [...new Set(inputs.map(ownerOf))];
+    if (inputs.length === 0) {
+        refuse("invalid-metric", NO_INPUT);
+    }
+    if (inputs.length > MAXIMUM_MODEL_METRIC_INPUTS) {
+        refuse("invalid-metric", TOO_MANY_INPUTS);
+    }
+    if (unit !== undefined && !UNITS.includes(unit)) {
+        refuse("invalid-metric", "Invalid metric unit.");
+    }
+    if (format !== undefined && !FORMATS.includes(format)) {
+        refuse("invalid-metric", "Invalid metric format.");
+    }
+    const currency = (name) => {
+        const owner = entities.get(ownerOf(name));
+        const declaredMetric = owner?.entity.definition.metrics?.[name.slice(ownerOf(name).length + 1)];
+        return declaredMetric?.unit === "currency";
+    };
+    const issue = unitIssue({ unit, expression, currency });
+    if (issue !== undefined) {
+        refuse("invalid-metric", issue);
+    }
+    // A metric that reads nothing has no entities to align.
+    const own = read.length === 0 ? undefined : alignmentOf({ metric, read, entities, refuse });
+    const sources = expansion.references.map((name) => ({
+        name,
+        align: resolveReference(name).align,
+    }));
+    // A read metric whose alignment was refused has said so; this one cannot inherit it.
+    const inheritable = sources.every((source) => source.align !== undefined);
+    const align = own === undefined || !inheritable
+        ? undefined
+        : inheritAlignment({
+            metric: metric.name,
+            read,
+            own,
+            sources: sources,
+            refuse,
+        });
+    if (read.length === 1 && !refused && align !== undefined) {
+        report("single-entity-model-metric", metric.path, `${metric.name} reads one entity; declare it as a metric of ${read[0]}.`, "warning");
+    }
+    if (align === undefined) {
+        return {};
+    }
+    if (refused) {
+        return { align };
+    }
+    return {
+        align,
+        manifest: {
+            name: metric.name,
+            label: typeof label === "string" ? label : humanize(metric.name),
+            description: description,
+            unit: (unit ?? "number"),
+            format: formatOf(unit, format),
+            expression: expression,
+            inputs,
+            align,
+        },
+    };
+}

package/dist/names.d.ts

@@ -0,0 +1,49 @@
+/** Ontology names: lowercase snake_case. */
+export declare const SNAKE_CASE_NAME: RegExp;
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export declare function toSnakeCase(name: string): string;
+export declare function toCamelCase(name: string): string;
+/** Historical property names accepted only as explicit rename sources. */
+export declare const LEGACY_MEMBER_NAME: RegExp;
+/** Stable entity identities, for example `ent_01J9Q4M8ZK`. */
+export declare const ENTITY_ID: RegExp;
+/** Properties every entity has. They are never declared and cannot be redeclared. */
+export declare const SYSTEM_PROPERTIES: readonly ["id", "created_at", "updated_at", "created_by", "updated_by"];
+export type SystemProperty = "id" | "createdAt" | "updatedAt" | "createdBy" | "updatedBy";
+/** Actions the platform generates for every entity; authored actions cannot use these names. */
+export declare const GENERATED_ACTIONS: readonly ["create", "update", "delete", "link", "unlink"];
+/** Prefix of the generated `upsert_by_<property>` actions. */
+export declare const GENERATED_UPSERT_PREFIX = "upsert_by_";
+/** The built-in role every active app user holds. */
+export declare const MEMBER_ROLE = "member";
+/** Implicit human feedback authority; never a stored or assignable role. */
+export declare const FEEDBACK_REPORTER_ROLE = "feedback_reporter";
+/** Suffix reserved for the history table each entity gets. */
+export declare const HISTORY_SUFFIX = "_history";
+/** The combinators of the query language, which take the place of field names in a `where`. */
+export declare const RESERVED_MEMBER_NAMES: readonly ["and", "or", "not"];
+/**
+ * The ontology service's route for metric queries across entities, `/api/ontology/query_metrics`,
+ * named as the MCP tool is. Each entity with metrics has `/api/ontology/<entity>/query_metrics`.
+ */
+export declare const QUERY_METRICS_ROUTE = "query_metrics";
+/** Routes of the ontology service under `/api/ontology/`, which an entity's routes would shadow. */
+export declare const RESERVED_ENTITY_NAMES: readonly ["chat", "query_metrics", "graph", "status", "describe", "openapi", "docs", "mcp", "me", "oauth", "agent", "workflows"];
+/** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
+export declare const MCP_READ_TOOLS: readonly ["find", "get", "history"];
+/** The MCP tools of the ontology as a whole. No entity tool can take them: they have no underscore. */
+export declare const MCP_GLOBAL_TOOLS: readonly ["discover", "me"];
+/**
+ * The metric tools, named as dbt names its MCP tools. Their names have an underscore, so `check`
+ * refuses an entity tool that takes one, such as entity `list`'s action `metrics`.
+ */
+export declare const MCP_METRIC_TOOLS: readonly ["list_metrics", "get_dimensions", "get_dimension_values", "query_metrics"];
+/** The longest tool name that Claude and OpenAI accept. */
+export declare const MCP_TOOL_NAME_MAX_LENGTH = 64;
+/** The MCP tool of an entity's read or action: `lead_find`, `lead_change_status`. */
+export declare function mcpToolName(entity: string, operation: string): string;
+/** `/api/ontology/<entity>/{id}/history`, which a relationship's traversal would shadow. */
+export declare const RESERVED_RELATIONSHIP_NAMES: readonly ["history"];
+export declare function isSystemProperty(name: string): boolean;
+/** `created_at` → `Created at`, `pilot_request` → `Pilot request`. */
+export declare function humanize(name: string): string;