@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/metric-routes.js

@@ -0,0 +1,498 @@
+import { User } from "./user.js";
+/** A route follows at most this many to-one relationships. */
+export const MAXIMUM_HOPS = 2;
+const SEPARATOR = ".";
+const COUNT_WORDS = ["no", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine"];
+/**
+ * The JSON Schema pattern of a metric query's name: `entity.member`, or a route of at most
+ * {@link MAXIMUM_HOPS} relationships from a metric entity, in snake_case segments.
+ */
+export const METRIC_QUERY_NAME_PATTERN = `^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*){1,${MAXIMUM_HOPS + 1}}$`;
+/** The built-in User is never replicated, so no route passes through it or ends at it. */
+export function isBuiltInUser(entity) {
+    return entity === User.name;
+}
+// The refusals that route resolution shares with backend-next's planner, word for word.
+export function hopLimitMessage() {
+    return `A path follows at most ${COUNT_WORDS[MAXIMUM_HOPS]} relationships.`;
+}
+export function userPathMessage() {
+    return "Paths cannot follow relationships to User.";
+}
+export function unknownRelationshipMessage(input) {
+    return `${input.entity} has no relationship ${input.relationship}.`;
+}
+/** A `rel.many`, or an inverse, which is to-many from the side that names it. */
+export function toManySegmentMessage(input) {
+    return `${input.relationship} is not a to-one relationship of ${input.entity}.`;
+}
+export function unknownPropertyMessage(input) {
+    return `${input.entity} has no property ${input.property}.`;
+}
+/** A bare metric name that is not a metric of the model. */
+export function unknownModelMetricMessage(name) {
+    return `The ontology has no metric named ${name}.`;
+}
+/** A filter that applies to some entities a model metric reads and cannot reach another. */
+export function partialFilterMessage(input) {
+    return (`${input.filter} does not apply to ${input.entity}, which ${input.metric} reads; align the ` +
+        "properties in the metric, or request its inputs instead.");
+}
+function entitiesByName(manifest) {
+    return new Map(manifest.entities.map((entity) => [entity.name, entity]));
+}
+/**
+ * The relationships a route may follow from an entity: its declared `rel.one`s, never an inverse,
+ * to entities of the manifest other than User.
+ */
+function edgesOf(entities, name) {
+    return (entities.get(name)?.relationships ?? [])
+        .filter((relationship) => relationship.cardinality === "one")
+        .filter((relationship) => entities.has(relationship.to) && !isBuiltInUser(relationship.to))
+        .map((relationship) => ({ relationship: relationship.name, target: relationship.to }));
+}
+function routesFrom(entities, from) {
+    const shortest = new Map();
+    let frontier = [{ relationships: [], entities: [from] }];
+    for (let hops = 1; hops <= MAXIMUM_HOPS; hops++) {
+        frontier = frontier.flatMap((route) => edgesOf(entities, route.entities.at(-1))
+            .filter((edge) => !route.entities.includes(edge.target))
+            .map((edge) => ({
+            relationships: [...route.relationships, edge.relationship],
+            entities: [...route.entities, edge.target],
+        })));
+        const reachedSooner = new Set(shortest.keys());
+        for (const route of frontier) {
+            const target = route.entities.at(-1);
+            if (!reachedSooner.has(target)) {
+                shortest.set(target, [...(shortest.get(target) ?? []), route]);
+            }
+        }
+    }
+    return shortest;
+}
+/**
+ * Every entity one entity reaches, with the shortest routes there, in the order they are first
+ * reached. Routes follow one to {@link MAXIMUM_HOPS} declared `rel.one`s, never inverses, never
+ * through User, and never visit an entity twice; several routes to one target are listed in
+ * declaration order. These are the routes metric query resolution weighs.
+ */
+export function shortestRoutesFrom(manifest, from) {
+    return routesFrom(entitiesByName(manifest), from);
+}
+/** The shortest routes from one entity to another, under {@link shortestRoutesFrom}'s rules. */
+export function shortestRoutes(manifest, input) {
+    return shortestRoutesFrom(manifest, input.from).get(input.to) ?? [];
+}
+/** Ends resolution with the reason the request is refused. It never leaves this module. */
+class Refusal extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+function refuse(reason) {
+    throw new Refusal(reason);
+}
+/**
+ * The ontology's entities and metrics of the model by name, and the shortest routes from each
+ * metric entity.
+ */
+class RouteCatalog {
+    entities;
+    metrics;
+    routes = new Map();
+    constructor(manifest) {
+        this.entities = entitiesByName(manifest);
+        this.metrics = new Map((manifest.metrics ?? []).map((metric) => [metric.name, metric]));
+    }
+    entity(name) {
+        return this.entities.get(name) ?? refuse(`${name} is not an entity of this ontology.`);
+    }
+    /** A metric of the model; a manifest before version 8 declares none. */
+    modelMetric(name) {
+        return this.metrics.get(name) ?? refuse(unknownModelMetricMessage(name));
+    }
+    /** Declared properties, and the `id` of a stored entity, which its replication view carries. */
+    hasProperty(entity, property) {
+        const stored = entity.source === undefined && !entity.builtIn;
+        return (entity.properties.some((candidate) => candidate.name === property) ||
+            (stored && property === "id"));
+    }
+    /** Whether `name` is the inverse of a relationship that another entity declares to this one. */
+    hasInverse(entity, name) {
+        return [...this.entities.values()].some((owner) => owner.relationships.some((relationship) => relationship.to === entity.name && relationship.inverse === name));
+    }
+    shortestRoutes(input) {
+        const { from, to } = input;
+        const reached = this.routes.get(from) ?? routesFrom(this.entities, from);
+        this.routes.set(from, reached);
+        return reached.get(to) ?? [];
+    }
+}
+/**
+ * The requested metrics, by entity. A bare name is a metric of the model, which reads the
+ * entities of its inputs; `entity.metric` is a metric of the entity.
+ */
+function requestedMetrics(input) {
+    const { catalog, metrics } = input;
+    const entities = new Map();
+    const model = [];
+    const metricEntity = (name) => {
+        const existing = entities.get(name);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const created = { entity: catalog.entity(name).name, requested: [], inputs: [], readers: [] };
+        entities.set(name, created);
+        return created;
+    };
+    if (metrics.length === 0) {
+        refuse("Request at least one metric.");
+    }
+    for (const [index, name] of metrics.entries()) {
+        const segments = name.split(SEPARATOR);
+        if (metrics.indexOf(name) !== index) {
+            refuse(`${name} is requested twice.`);
+        }
+        if (segments.length === 1 && name.length > 0) {
+            const metric = catalog.modelMetric(name);
+            model.push(metric);
+            for (const qualified of metric.inputs) {
+                const owner = metricEntity(qualified.slice(0, qualified.indexOf(SEPARATOR)));
+                owner.inputs.push(qualified.slice(qualified.indexOf(SEPARATOR) + 1));
+                if (!owner.readers.includes(metric)) {
+                    owner.readers.push(metric);
+                }
+            }
+            continue;
+        }
+        if (segments.length !== 2 || segments.some((segment) => segment.length === 0)) {
+            refuse(`${name} is not a metric name; write <entity>.<metric>.`);
+        }
+        const [entityName, metric] = segments;
+        const entity = catalog.entity(entityName);
+        if (!(entity.metrics ?? []).some((candidate) => candidate.name === metric)) {
+            refuse(`${entityName} has no metric ${metric}.`);
+        }
+        metricEntity(entityName).requested.push(metric);
+    }
+    return { entities, model };
+}
+/** The entities a model metric reads, each once, in the order of its inputs. */
+export function inputEntities(metric) {
+    return [...new Set(metric.inputs.map((input) => input.slice(0, input.indexOf(SEPARATOR))))];
+}
+/**
+ * Parses an identity, `entity.property`, or a route form, `root.relationship[.relationship].property`,
+ * whose root must own a requested metric. A written route follows the same relationships as a
+ * resolved one: declared `rel.one`s, never through User, never visiting an entity twice.
+ */
+function parseName(input) {
+    const { catalog, roots, name } = input;
+    const segments = name.split(SEPARATOR);
+    if (segments.length < 2 || segments.some((segment) => segment.length === 0)) {
+        refuse(`${name} is not a valid name; write <entity>.<property> or a route from a metric entity.`);
+    }
+    if (segments.length > MAXIMUM_HOPS + 2) {
+        refuse(hopLimitMessage());
+    }
+    const [rootName, ...rest] = segments;
+    const relationships = rest.slice(0, -1);
+    const property = rest.at(-1);
+    let entity = catalog.entity(rootName);
+    if (relationships.length > 0 && !roots.has(rootName)) {
+        refuse(`${name} is written as a route from ${rootName}, which owns no requested metric.`);
+    }
+    const entities = [entity.name];
+    for (const relationshipName of relationships) {
+        const relationship = entity.relationships.find((candidate) => candidate.name === relationshipName);
+        const segment = { entity: entity.name, relationship: relationshipName };
+        if (relationship === undefined) {
+            refuse(catalog.hasInverse(entity, relationshipName)
+                ? toManySegmentMessage(segment)
+                : unknownRelationshipMessage(segment));
+        }
+        if (relationship.cardinality !== "one") {
+            refuse(toManySegmentMessage(segment));
+        }
+        if (isBuiltInUser(relationship.to)) {
+            refuse(userPathMessage());
+        }
+        const target = catalog.entity(relationship.to);
+        if (entities.includes(target.name)) {
+            refuse(`${name} visits ${target.name} twice; a route never revisits an entity.`);
+        }
+        entities.push(target.name);
+        entity = target;
+    }
+    if (!catalog.hasProperty(entity, property)) {
+        refuse(unknownPropertyMessage({ entity: entity.name, property }));
+    }
+    const identity = `${entity.name}${SEPARATOR}${property}`;
+    if (relationships.length === 0) {
+        return { name, target: entity.name, property, identity };
+    }
+    return {
+        name,
+        target: entity.name,
+        property,
+        identity,
+        written: { root: rootName, route: { relationships, entities } },
+    };
+}
+/**
+ * The route one metric entity takes to a requested name: the written route when the name is a route
+ * form rooted at the entity; no relationship when the name is the entity's own property, which
+ * always wins; otherwise the shortest routes.
+ */
+function resolveName(input) {
+    const { catalog, from, requested } = input;
+    if (requested.written?.root === from) {
+        return { kind: "resolved", route: requested.written.route };
+    }
+    if (requested.target === from) {
+        return { kind: "resolved", route: { relationships: [], entities: [from] } };
+    }
+    const routes = catalog.shortestRoutes({ from, to: requested.target });
+    if (routes.length === 0) {
+        return { kind: "unreachable" };
+    }
+    if (routes.length > 1) {
+        return { kind: "ambiguous", routes };
+    }
+    return { kind: "resolved", route: routes[0] };
+}
+/**
+ * The member of an entity in the group of a model metric's alignment that an identity belongs to:
+ * a property, `null` when the entity has no counterpart, or `undefined` when no group has the
+ * identity.
+ */
+function memberOf(input) {
+    const { metric, entity, identity } = input;
+    const group = metric.align.find((candidate) => Object.entries(candidate).some(([owner, property]) => property !== null && `${owner}${SEPARATOR}${property}` === identity));
+    if (group === undefined || !Object.hasOwn(group, entity)) {
+        return undefined;
+    }
+    return group[entity] ?? null;
+}
+/**
+ * How the requested model metrics that read an entity align a requested name: the entity's own
+ * member of the group the name's identity belongs to, `null` when the entity has no counterpart, or
+ * `undefined` when none of them aligns it. Two that align it differently are refused: the entity
+ * computes its inputs once.
+ */
+function alignedMember(input) {
+    const { entity, requested } = input;
+    let aligned;
+    for (const reader of entity.readers) {
+        const member = memberOf({
+            metric: reader,
+            entity: entity.entity,
+            identity: requested.identity,
+        });
+        if (member === undefined) {
+            continue;
+        }
+        if (aligned !== undefined && aligned.member !== member) {
+            refuse(`${requested.identity} is aligned differently by ${aligned.by} and ${reader.name}.`);
+        }
+        aligned ??= { by: reader.name, member };
+    }
+    return aligned?.member;
+}
+function resolveFor(input) {
+    const { catalog, entity, requested } = input;
+    const member = alignedMember({ entity, requested });
+    if (member !== undefined) {
+        return { kind: "aligned", path: member };
+    }
+    return resolveName({ catalog, from: entity.entity, requested });
+}
+/**
+ * Two requested dimensions that are members of one alignment group of a requested model metric
+ * would group each of its entities twice by the same property.
+ */
+function refuseAlignedTwice(input) {
+    const { model, dimensions } = input;
+    for (const metric of model) {
+        for (const group of metric.align) {
+            const members = dimensions.filter(({ identity }) => Object.entries(group).some(([entity, property]) => property !== null && `${entity}${SEPARATOR}${property}` === identity));
+            const [first, second] = members;
+            if (first !== undefined && second !== undefined) {
+                refuse(`${second.identity} is aligned with ${first.identity}; request one of them.`);
+            }
+        }
+    }
+}
+/**
+ * A dimension that a metric entity cannot reach, named after its first requested metric, or after
+ * the first requested model metric that reads it.
+ */
+function unreachableMessage(entity, identity) {
+    const [requested] = entity.requested;
+    if (requested !== undefined) {
+        return `${entity.entity}${SEPARATOR}${requested} cannot reach ${identity}.`;
+    }
+    return `${entity.readers[0]?.name} reads ${entity.entity}, which cannot reach ${identity}.`;
+}
+function ambiguousRoute(input) {
+    const { from, requested, routes } = input;
+    const count = COUNT_WORDS[routes.length] ?? String(routes.length);
+    const listed = routes.map((route) => route.relationships.join(SEPARATOR)).join(", ");
+    const placeholder = routes[0].relationships.map(() => "<relationship>").join(SEPARATOR);
+    return (`${from} reaches ${requested.target} in ${count} ways (${listed}); ` +
+        `write the route as ${from}.${placeholder}.${requested.property}.`);
+}
+/** A list of names. Callers validate requests first; this keeps any other value from throwing. */
+function namesOf(field, value) {
+    if (!Array.isArray(value) || value.some((name) => typeof name !== "string")) {
+        refuse(`${field} must contain names written as entity.member.`);
+    }
+    return value;
+}
+function pathOf(route, property) {
+    return [...route.relationships, property].join(SEPARATOR);
+}
+/**
+ * Resolves the names of a model-level metric query against a manifest
+ * (docs/ontology-aggregates-spec.md, "Resolution"). It is the one place names and routes resolve: backend-next plans each metric
+ * entity from it, and the ontology service checks `<entity>:read` on every entity it touches.
+ *
+ * Pure: it reads only the manifest. It does not check partitions, currency, replication or metric
+ * operators, nor add scope parents, which the planner adds along the same relative path.
+ */
+export function resolveMetricRoutes(manifest, names) {
+    try {
+        return { ok: true, ...resolve(new RouteCatalog(manifest), names) };
+    }
+    catch (error) {
+        if (error instanceof Refusal) {
+            return { ok: false, reason: error.reason };
+        }
+        throw error;
+    }
+}
+function resolve(catalog, names) {
+    const metricNames = namesOf("metrics", names.metrics);
+    const dimensionNames = namesOf("dimensions", names.dimensions ?? []);
+    const filterNames = namesOf("filters", names.filters ?? []);
+    const requested = requestedMetrics({ catalog, metrics: metricNames });
+    const groups = requested.entities;
+    const touched = new Set(groups.keys());
+    const dimensions = dimensionNames.map((name) => parseName({ catalog, roots: groups, name }));
+    for (const [index, dimension] of dimensions.entries()) {
+        if (dimensions.findIndex((other) => other.identity === dimension.identity) !== index) {
+            refuse(`${dimension.identity} is requested twice.`);
+        }
+    }
+    refuseAlignedTwice({ model: requested.model, dimensions });
+    const { granularityOf } = names;
+    const bucketed = granularityOf === undefined
+        ? undefined
+        : (dimensions.find((dimension) => dimension.name === granularityOf || dimension.identity === granularityOf) ?? refuse("granularityOf must name a requested dimension."));
+    // Several filters may share a dimension; each distinct name resolves once.
+    const filters = [...new Set(filterNames)].map((name) => parseName({ catalog, roots: groups, name }));
+    // The entity a filter names is touched even where the filter does not apply, and so is every
+    // entity of a written route.
+    for (const filter of filters) {
+        touched.add(filter.target);
+        filter.written?.route.entities.forEach((entity) => touched.add(entity));
+    }
+    const routed = [...groups.values()].map((entity) => {
+        const dimensionRoutes = dimensions.map((dimension) => {
+            const resolution = resolveFor({ catalog, entity, requested: dimension });
+            if (resolution.kind === "aligned") {
+                return { identity: dimension.identity, path: resolution.path };
+            }
+            if (resolution.kind === "unreachable") {
+                refuse(unreachableMessage(entity, dimension.identity));
+            }
+            if (resolution.kind === "ambiguous") {
+                refuse(ambiguousRoute({ from: entity.entity, requested: dimension, routes: resolution.routes }));
+            }
+            resolution.route.entities.forEach((visited) => touched.add(visited));
+            return {
+                identity: dimension.identity,
+                path: pathOf(resolution.route, dimension.property),
+            };
+        });
+        return { entity, dimensionRoutes };
+    });
+    const reach = new Map();
+    const entities = routed.map(({ entity, dimensionRoutes }) => {
+        const applied = [];
+        const unappliedFilters = [];
+        const reached = new Map();
+        for (const filter of filters) {
+            const resolution = resolveFor({ catalog, entity, requested: filter });
+            if (resolution.kind === "aligned") {
+                if (resolution.path === null) {
+                    unappliedFilters.push(filter.name);
+                    reached.set(filter.name, "noCounterpart");
+                }
+                else {
+                    applied.push({ name: filter.name, path: resolution.path });
+                    reached.set(filter.name, "applied");
+                }
+                continue;
+            }
+            if (resolution.kind === "ambiguous") {
+                refuse(ambiguousRoute({ from: entity.entity, requested: filter, routes: resolution.routes }));
+            }
+            if (resolution.kind === "unreachable") {
+                unappliedFilters.push(filter.name);
+                reached.set(filter.name, "unreachable");
+                continue;
+            }
+            resolution.route.entities.forEach((visited) => touched.add(visited));
+            applied.push({ name: filter.name, path: pathOf(resolution.route, filter.property) });
+            reached.set(filter.name, "applied");
+        }
+        reach.set(entity.entity, reached);
+        const bucketedPath = bucketed === undefined
+            ? undefined
+            : dimensionRoutes.find((route) => route.identity === bucketed.identity)?.path;
+        return {
+            entity: entity.entity,
+            metrics: [...new Set([...entity.requested, ...entity.inputs])],
+            dimensions: dimensionRoutes,
+            filters: applied,
+            unappliedFilters,
+            ...(bucketedPath === undefined || bucketedPath === null
+                ? {}
+                : { granularityOf: bucketedPath }),
+        };
+    });
+    const model = requested.model.map((metric) => ({
+        name: metric.name,
+        inputs: metric.inputs,
+        entities: inputEntities(metric),
+    }));
+    for (const filter of filters) {
+        // A model metric's inputs are filtered alike, or the filter is refused: a filtered numerator
+        // over an unfiltered denominator would answer another question. Only the metric's own
+        // alignment may say that an entity it reads has no counterpart.
+        for (const metric of requested.model) {
+            const states = inputEntities(metric).map((entity) => {
+                const state = reach.get(entity)?.get(filter.name);
+                const exempt = state === "noCounterpart" &&
+                    memberOf({ metric, entity, identity: filter.identity }) === null;
+                return { entity, state: state === "noCounterpart" && !exempt ? "unreachable" : state };
+            });
+            const missed = states.find(({ state }) => state === "unreachable");
+            if (missed !== undefined && states.some(({ state }) => state === "applied")) {
+                refuse(partialFilterMessage({
+                    filter: filter.name,
+                    entity: missed.entity,
+                    metric: metric.name,
+                }));
+            }
+        }
+        if (entities.every((routes) => routes.unappliedFilters.includes(filter.name))) {
+            refuse(`No metric can reach ${filter.name}.`);
+        }
+    }
+    return { entities, touched: [...touched].sort(), model };
+}

package/dist/metric.d.ts

@@ -0,0 +1,172 @@
+import type { MetricQueryValue, MetricConditionOperator } from "./metric-filters.js";
+/**
+ * A condition on the rows an aggregate reads: a property of the metric's own entity, in TypeScript
+ * names, and an operator with literal values, as a request filter takes them.
+ */
+export interface MetricCondition {
+    readonly property: string;
+    readonly operator: MetricConditionOperator;
+    readonly value?: MetricQueryValue;
+    readonly values?: ReadonlyArray<MetricQueryValue>;
+}
+/**
+ * A condition as a `filtered` expression holds it: like a `column` expression, it names a property
+ * until `metricExpression` maps it to the property's column for the manifest.
+ */
+export interface MetricColumnCondition {
+    readonly column: string;
+    readonly operator: MetricConditionOperator;
+    readonly value?: MetricQueryValue;
+    readonly values?: ReadonlyArray<MetricQueryValue>;
+}
+/** The aggregates a metric expression may contain, `count` included. */
+export declare const METRIC_AGGREGATES: readonly ["count", "sum", "countDistinct", "avg", "min", "max"];
+export type MetricExpression = {
+    readonly op: "count";
+} | {
+    readonly op: "column" | "metric";
+    readonly name: string;
+} | {
+    readonly op: "literal";
+    readonly value: string;
+} | {
+    readonly op: "sum" | "countDistinct" | "avg" | "min" | "max" | "add" | "subtract" | "multiply" | "divide";
+    readonly args: ReadonlyArray<MetricExpression>;
+}
+/**
+ * One aggregate over the rows that meet every condition. The condition wraps the aggregate, so a
+ * platform that does not know `filtered` cannot compute the aggregate unfiltered.
+ */
+ | {
+    readonly op: "filtered";
+    readonly args: ReadonlyArray<MetricExpression>;
+    readonly where: ReadonlyArray<MetricColumnCondition>;
+};
+export interface MetricOptions {
+    readonly description: string;
+    readonly label?: string;
+    readonly unit?: "number" | "currency" | "ratio" | "percent";
+    readonly format?: "decimal" | "currency" | "percent";
+}
+/** What an aggregate declares about the rows it reads, beside a metric's options. */
+export interface AggregateDeclarations {
+    /** 1–10 conditions on properties of the entity, all of which the rows read must meet. */
+    readonly where?: ReadonlyArray<MetricCondition>;
+    /**
+     * The date or timestamp property the entity's rows are snapshots over, such as a daily stock
+     * table's date. Summing snapshots over days would overstate the balance, so a request must group
+     * by the property or filter it to one day. Arithmetic and references over the aggregate inherit
+     * it.
+     */
+    readonly balanceOver?: string;
+}
+/**
+ * The options of `count`, `sum`, `countDistinct`, `avg`, `min` and `max`: a metric's options with
+ * the aggregate's declarations, or the declarations alone for an aggregate that is an argument of
+ * arithmetic.
+ */
+export type AggregateOptions = (MetricOptions & AggregateDeclarations) | AggregateDeclarations;
+export type Metric = MetricExpression & Partial<MetricOptions> & {
+    /** An aggregate's conditions, as its builder's `where` option declares them. */
+    readonly where?: ReadonlyArray<MetricCondition | MetricColumnCondition>;
+    /** An aggregate's balance property, as its builder's `balanceOver` option declares it. */
+    readonly balanceOver?: string;
+    /** A metric of an entity reads that entity's rows only: alignment is for model metrics. */
+    readonly align?: never;
+};
+export type Metrics = Readonly<Record<string, Metric>>;
+/**
+ * One group of a model metric's alignment: every entity the metric reads, by its TypeScript name,
+ * with its property that stands for the others', or `null` when the entity has no counterpart, as a
+ * current snapshot has no date.
+ */
+export type AlignmentGroup = Readonly<Record<string, string | null>>;
+/** The options of a model metric: a metric's options and how its entities' properties align. */
+export interface ModelMetricOptions extends MetricOptions {
+    /**
+     * At most 5 groups of properties that stand for one another across the entities the metric
+     * reads, such as a sales date and a plan month. A request that groups or filters by one member of
+     * a group reads each entity through its own member. Properties of one group share a type, and a
+     * property appears in one group at most.
+     */
+    readonly align?: ReadonlyArray<AlignmentGroup>;
+}
+/**
+ * A metric of the model, declared in `defineOntology({ metrics })`: arithmetic over metrics of
+ * entities, `m.ref("entity.metric")`, and over other model metrics, `m.ref("name")`. It reads
+ * entity metrics and aggregates no rows of its own.
+ */
+export type ModelMetric = MetricExpression & Partial<MetricOptions> & {
+    readonly align?: ReadonlyArray<AlignmentGroup>;
+};
+export type ModelMetrics = Readonly<Record<string, ModelMetric>>;
+/** A model metric's options that declare an alignment, which only model metrics take. */
+type AlignedOptions = ModelMetricOptions & {
+    readonly align: ReadonlyArray<AlignmentGroup>;
+};
+/**
+ * An argument of arithmetic: any expression but one that declares an alignment, which belongs on
+ * the model metric itself.
+ */
+type Argument = MetricExpression & {
+    readonly align?: never;
+};
+/** Arithmetic of two expressions; with `align` among its options, a model metric. */
+interface Arithmetic {
+    (left: Argument, right: Argument, options: AlignedOptions): ModelMetric;
+    (left: Argument, right: Argument, options?: MetricOptions): Metric;
+}
+/** A reference to another metric; with `align` among its options, a model metric. */
+interface Reference {
+    (name: string, options: AlignedOptions): ModelMetric;
+    (name: string, options?: MetricOptions): Metric;
+}
+/**
+ * Arithmetic combines aggregates; references name another metric of the same entity. Every
+ * aggregate takes `where`, conditions on properties of the entity that the rows it reads must meet,
+ * and `balanceOver`, the date its rows are snapshots over. In `defineOntology({ metrics })`,
+ * references name metrics of entities, `m.ref("sales.revenue")`, or other model metrics, and
+ * arithmetic and references take `align`.
+ */
+export declare const m: {
+    readonly count: (options?: AggregateOptions) => Metric;
+    /** The sum of an integer or number property. */
+    readonly sum: (property: string, options?: AggregateOptions) => Metric;
+    /**
+     * The number of distinct non-null values of a text, email, url, select, integer, date or timestamp
+     * property. Distinct counts do not add up across groups.
+     */
+    readonly countDistinct: (property: string, options?: AggregateOptions) => Metric;
+    /** The average of an integer or number property, ignoring nulls. Averages do not add up. */
+    readonly avg: (property: string, options?: AggregateOptions) => Metric;
+    /** The least value of an integer or number property. Minimums do not add up. */
+    readonly min: (property: string, options?: AggregateOptions) => Metric;
+    /** The greatest value of an integer or number property. Maximums do not add up. */
+    readonly max: (property: string, options?: AggregateOptions) => Metric;
+    readonly ref: Reference;
+    readonly literal: (value: number | string, options?: MetricOptions) => Metric;
+    readonly add: Arithmetic;
+    readonly subtract: Arithmetic;
+    readonly multiply: Arithmetic;
+    readonly divide: Arithmetic;
+};
+/** The conditions an expression declares: an aggregate's `where` option, or a `filtered` node's. */
+export declare function conditionsOf(value: Metric | MetricExpression): ReadonlyArray<MetricCondition | MetricColumnCondition> | undefined;
+/** The balance property an expression node declares: an aggregate's `balanceOver` option. */
+export declare function balanceOf(value: Metric | MetricExpression): unknown;
+/**
+ * The balance properties a metric's own aggregates declare, top-level or inside arithmetic and
+ * `filtered` expressions, without duplicates. References are not followed: the platform inherits a
+ * referenced metric's balance itself.
+ */
+export declare function balancesOf(value: Metric | MetricExpression): ReadonlyArray<string>;
+/** The property a condition names: `property` as authored, `column` in a `filtered` expression. */
+export declare function conditionProperty(condition: object): unknown;
+/**
+ * Strip authoring options and resolve logical properties to physical columns for the manifest: a
+ * warehouse-backed property's `column`, or a stored property's replication view column, which is its
+ * wire name. An aggregate's `where` becomes the `filtered` expression that wraps it, its conditions
+ * naming columns too.
+ */
+export declare function metricExpression(value: MetricExpression, columns: ReadonlyMap<string, string>): MetricExpression;
+export {};