@segmentstream-cloud/ontology 0.21.0 → 0.23.0

package/dist/model-measures.js

@@ -0,0 +1,543 @@
+import { dimensionTypeOf } from "./aggregate-filters.js";
+import { isRecord, nameToWire } from "./authoring-names.js";
+import { MEASURE_AGGREGATES } from "./measure.js";
+import { humanize, RESERVED_ENTITY_NAMES, SNAKE_CASE_NAME, toCamelCase } from "./names.js";
+/** The most measures a model declares. */
+export const MAXIMUM_MODEL_MEASURES = 50;
+/** The most distinct entity measures one model measure reads, references expanded. */
+export const MAXIMUM_MODEL_MEASURE_INPUTS = 10;
+/** The most alignment groups one model measure declares. */
+export const MAXIMUM_ALIGNMENT_GROUPS = 5;
+/** The deepest and the largest expression a model measure 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 measure contains: an aggregate, its condition and the column it reads. */
+const AGGREGATE_NODES = [...MEASURE_AGGREGATES, "filtered", "column"];
+const LITERAL = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/;
+const NAMES = "Model measures require unique snake_case names and a description.";
+const AGGREGATES = "Model measures combine entity measures; declare the aggregate on its entity.";
+const CYCLE = "Measure references cannot form a cycle.";
+const COMPLEX = "Invalid or overly complex expression.";
+const NO_INPUT = 'A model measure reads at least one entity measure: m.ref("entity.measure").';
+const TOO_MANY_INPUTS = `A model measure reads at most ${MAXIMUM_MODEL_MEASURE_INPUTS} entity measures.`;
+const ALIGNMENT_SHAPE = "align is a list of groups, each naming every entity the measure 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 measure, not on an argument of its expression.";
+const NO_WHERE = "A model measure takes no where; declare a filtered measure on the entity and read it.";
+const NO_BALANCE = "A model measure 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 measures under their wire names, each a unique snake_case name, not an
+ * entity's and not a route's, with a description. A measure whose name is refused is not resolved
+ * further.
+ */
+function declare(input) {
+    const { measures, entities, report } = input;
+    const declared = new Map();
+    for (const [name, measure] of Object.entries(measures)) {
+        const wire = wireNameOf(name);
+        const path = `measures.${wire ?? name}`;
+        if (wire === undefined || declared.has(wire) || !isRecord(measure)) {
+            report("invalid-measure", path, NAMES);
+            continue;
+        }
+        if (isBlank(measure.description)) {
+            report("invalid-measure", path, NAMES);
+        }
+        if (entities.has(wire)) {
+            report("duplicate-name", path, `${wire} is also an entity name.`);
+            continue;
+        }
+        if (RESERVED_ENTITY_NAMES.includes(wire)) {
+            report("reserved-name", path, `${wire} is a reserved name.`);
+            continue;
+        }
+        declared.set(wire, { name: wire, path, measure });
+    }
+    return declared;
+}
+/** Whether an entity declares a measure, by wire names. */
+function declaresMeasure(entity, measure) {
+    const measures = entity?.entity.definition.measures ?? {};
+    return measure !== undefined && Object.hasOwn(measures, measure);
+}
+/**
+ * Expands every model measure: a reference to an entity measure becomes a `measure` node naming
+ * `entity.measure` in wire names, and a reference to another model measure that measure's expanded
+ * expression. A measure whose expansion fails maps to `undefined`; its reason is reported once, at
+ * the measure 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-measure", `${current.name} reads ${name}, which the ontology does not declare.`);
+        /** A reference: `entity.measure` in TypeScript names per segment, or a model measure's name. */
+        const reference = (name, depth) => {
+            if (typeof name !== "string" || name.length === 0) {
+                return refuse("invalid-measure", "Invalid expression operator or arity.");
+            }
+            if (name.includes(SEPARATOR)) {
+                const wire = name.split(SEPARATOR).map(nameToWire).join(SEPARATOR);
+                const [owner, measure, ...rest] = wire.split(SEPARATOR);
+                if (rest.length > 0 || !declaresMeasure(entities.get(owner ?? ""), measure)) {
+                    return unknown(wire);
+                }
+                return { op: "measure", name: wire };
+            }
+            const wire = nameToWire(name);
+            const target = declared.get(wire);
+            if (target === undefined) {
+                return unknown(wire);
+            }
+            if (pending.has(wire)) {
+                return refuse("circular-measure", 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-measure", COMPLEX);
+            }
+            return inner.expression;
+        };
+        const visit = (node, depth) => {
+            nodes += 1;
+            if (depth > MAXIMUM_DEPTH || nodes > MAXIMUM_NODES || !isRecord(node)) {
+                return refuse("invalid-measure", COMPLEX);
+            }
+            const { op } = node;
+            // Options of an argument are not the measure'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-measure", AGGREGATES);
+            }
+            if (node.where !== undefined) {
+                refuse("invalid-measure", NO_WHERE);
+            }
+            if (node.balanceOver !== undefined) {
+                refuse("invalid-measure", NO_BALANCE);
+            }
+            if (op === "measure") {
+                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-measure", "Literals must be finite numbers.");
+                }
+                return { op: "literal", value };
+            }
+            if (!ARITHMETIC.includes(op) || !Array.isArray(node.args) || node.args.length !== 2) {
+                return refuse("invalid-measure", "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.measure, 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 measures an expanded expression reads, `entity.measure`, each once, in order. */
+function inputsOf(expression) {
+    if (expression.op === "measure") {
+        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 === "measure") {
+        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 measures is a ratio, not a currency.";
+    }
+    if (unit === "currency" && quantity !== "money" && found.product) {
+        return "A product of two currency measures is not a currency.";
+    }
+    if ((unit === "ratio" || unit === "percent") && quantity === "money" && found.sum) {
+        return `A sum or difference of currency measures 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 measure'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 { measure, read, entities, refuse } = input;
+    const declared = measure.measure.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", `${measure.name} reads one entity and needs no alignment.`);
+        return undefined;
+    }
+    if (declared.length > MAXIMUM_ALIGNMENT_GROUPS) {
+        refuse("invalid-alignment", `A model measure 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 ${measure.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(`${measure.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 measure it reads, on the entities that one names. */
+function disagreement(input) {
+    const { measure, 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 (`${measure} aligns ${entity}${SEPARATOR}${own}, but ${source}, which it reads, aligns ` +
+                `${entity}${SEPARATOR}${member}.`);
+        }
+        if (own !== null) {
+            return (`${measure} aligns ${entity}${SEPARATOR}${own}, but ${source}, which it reads, gives ` +
+                `${entity} no counterpart.`);
+        }
+        return (`${measure} gives ${entity} no counterpart, but ${source}, which it reads, aligns ` +
+            `${entity}${SEPARATOR}${member}.`);
+    }
+    return undefined;
+}
+/**
+ * A model measure's effective alignment: its own groups, then every group of the model measures it
+ * reads that it does not restate. A restated group must agree on every entity the read measure
+ * reads; an inherited group must name every entity this measure reads.
+ */
+function inheritAlignment(input) {
+    const { measure, 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({ measure, 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", `${measure} reads ${source.name}, whose alignment does not name ${missing}; align it ` +
+                    `in ${measure}.`);
+                continue;
+            }
+            groups.push(Object.fromEntries(read.map((entity) => [entity, inherited[entity] ?? null])));
+        }
+    }
+    if (valid && groups.length > MAXIMUM_ALIGNMENT_GROUPS) {
+        refuse("invalid-alignment", `A model measure 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 measures of the model, `defineOntology({ measures })`, against the
+ * resolved entities, whose measures were checked first (docs/ontology-aggregates-release-3-spec.md,
+ * "Declaring model measures"). Returns the manifest form of each measure that passed, in declaration
+ * order: references expanded, names on the wire, inputs in reading order.
+ */
+export function resolveModelMeasures(input) {
+    const { measures, report } = input;
+    const entities = new Map(input.entities.map((candidate) => [candidate.name, candidate]));
+    if (measures === undefined) {
+        return [];
+    }
+    if (!isRecord(measures)) {
+        report("invalid-measure", "measures", "measures maps names to measures built with m: { planAttainment: m.divide(…) }.");
+        return [];
+    }
+    const count = Object.keys(measures).length;
+    if (count > MAXIMUM_MODEL_MEASURES) {
+        report("invalid-measure", "measures", `The ontology declares ${count} model measures; the limit is ${MAXIMUM_MODEL_MEASURES}.`);
+    }
+    const declared = declare({ measures, entities, report });
+    const expansions = expandAll({ declared, entities, report });
+    const resolved = new Map();
+    /** A measure, after the model measures it reads, whose alignment it inherits. */
+    const resolve = (measure) => {
+        const known = resolved.get(measure.name);
+        if (known !== undefined) {
+            return known;
+        }
+        const resolution = resolveMeasure({
+            measure,
+            expansion: expansions.get(measure.name),
+            entities,
+            report,
+            resolveReference: (name) => resolve(declared.get(name)),
+        });
+        resolved.set(measure.name, resolution);
+        return resolution;
+    };
+    return [...declared.values()].flatMap((measure) => {
+        const { manifest } = resolve(measure);
+        return manifest === undefined ? [] : [manifest];
+    });
+}
+function resolveMeasure(input) {
+    const { measure, expansion, entities, report, resolveReference } = input;
+    if (expansion === undefined) {
+        return {};
+    }
+    let refused = isBlank(measure.measure.description);
+    const refuse = (code, message) => {
+        refused = true;
+        report(code, measure.path, message);
+    };
+    const { expression } = expansion;
+    const { unit, format, label, description } = measure.measure;
+    const inputs = inputsOf(expression);
+    const read = [...new Set(inputs.map(ownerOf))];
+    if (inputs.length === 0) {
+        refuse("invalid-measure", NO_INPUT);
+    }
+    if (inputs.length > MAXIMUM_MODEL_MEASURE_INPUTS) {
+        refuse("invalid-measure", TOO_MANY_INPUTS);
+    }
+    if (unit !== undefined && !UNITS.includes(unit)) {
+        refuse("invalid-measure", "Invalid measure unit.");
+    }
+    if (format !== undefined && !FORMATS.includes(format)) {
+        refuse("invalid-measure", "Invalid measure format.");
+    }
+    const currency = (name) => {
+        const owner = entities.get(ownerOf(name));
+        const declaredMeasure = owner?.entity.definition.measures?.[name.slice(ownerOf(name).length + 1)];
+        return declaredMeasure?.unit === "currency";
+    };
+    const issue = unitIssue({ unit, expression, currency });
+    if (issue !== undefined) {
+        refuse("invalid-measure", issue);
+    }
+    // A measure that reads nothing has no entities to align.
+    const own = read.length === 0 ? undefined : alignmentOf({ measure, read, entities, refuse });
+    const sources = expansion.references.map((name) => ({
+        name,
+        align: resolveReference(name).align,
+    }));
+    // A read measure 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({
+            measure: measure.name,
+            read,
+            own,
+            sources: sources,
+            refuse,
+        });
+    if (read.length === 1 && !refused && align !== undefined) {
+        report("single-entity-model-measure", measure.path, `${measure.name} reads one entity; declare it as a measure of ${read[0]}.`, "warning");
+    }
+    if (align === undefined) {
+        return {};
+    }
+    if (refused) {
+        return { align };
+    }
+    return {
+        align,
+        manifest: {
+            name: measure.name,
+            label: typeof label === "string" ? label : humanize(measure.name),
+            description: description,
+            unit: (unit ?? "number"),
+            format: formatOf(unit, format),
+            expression: expression,
+            inputs,
+            align,
+        },
+    };
+}

package/dist/ontology.d.ts

@@ -2,12 +2,13 @@ import { type AnalyzeOptions, type OntologyConfig, type ResolvedConnection, type
 import { type Diagnostic } from "./diagnostics.js";
 import type { AnyEntity } from "./entity.js";
 import { type OntologyManifest } from "./manifest.js";
+import type { ModelMeasures } from "./measure.js";
 import type { Role } from "./role.js";
 import type { SignInOptions } from "./sign-in.js";
 /** A checked ontology: the resolved definitions and the manifest built from them. */
-export interface Ontology<Entities extends ReadonlyArray<AnyEntity> = ReadonlyArray<AnyEntity>> {
+export interface Ontology<Entities extends ReadonlyArray<AnyEntity> = ReadonlyArray<AnyEntity>, Measures extends ModelMeasures = ModelMeasures> {
     /** The definition as given to `defineOntology`. */
-    readonly config: OntologyConfig<Entities>;
+    readonly config: OntologyConfig<Entities, Measures>;
     /** The built-in `User` first, then the declared entities in order. */
     readonly entities: ReadonlyArray<ResolvedEntity>;
     /** The built-in `member` role first, with the ontology's member permissions, then the declared roles. */
@@ -30,9 +31,9 @@ export declare function check(input: OntologyConfig | Ontology): ReadonlyArray<D
  * manifest's roles, whose permissions name entities the rebuilt ontology does not have, and whose
  * `user` table may predate properties this SDK added to the built-in `User`.
  */
-export declare function buildOntology<const Entities extends ReadonlyArray<AnyEntity>>(config: OntologyConfig<Entities>, options: AnalyzeOptions): Ontology<Entities>;
+export declare function buildOntology<const Entities extends ReadonlyArray<AnyEntity>, const Measures extends ModelMeasures = ModelMeasures>(config: OntologyConfig<Entities, Measures>, options: AnalyzeOptions): Ontology<Entities, Measures>;
 /**
  * Resolves and checks the ontology and builds its manifest. Throws {@link InvalidOntology}, carrying
  * every diagnostic, when `check` reports an error.
  */
-export declare function defineOntology<const Entities extends ReadonlyArray<AnyEntity>>(config: OntologyConfig<Entities>): Ontology<Entities>;
+export declare function defineOntology<const Entities extends ReadonlyArray<AnyEntity>, const Measures extends ModelMeasures = ModelMeasures>(config: OntologyConfig<Entities, Measures>): Ontology<Entities, Measures>;

package/dist/render.d.ts

@@ -1,4 +1,4 @@
-import type { ActionManifest, EntityManifest, MeasureManifest, OntologyManifest } from "./manifest.js";
+import type { ActionManifest, EntityManifest, MeasureManifest, ModelMeasureManifest, OntologyManifest } from "./manifest.js";
 export interface RenderOptions {
     /**
      * The permissions of the reader. Only the actions these permissions may run are listed, and only
@@ -50,6 +50,17 @@ export declare const RECORDS_OR_AGGREGATES = "look at or change records through
  * declaration order. Without permissions, every measure.
  */
 export declare function measuresFor(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): ReadonlyArray<NamedMeasure>;
+/**
+ * The measures of the model whose every input entity the reader may read, in declaration order.
+ * Reading a model measure is reading its inputs. Without permissions, every one.
+ */
+export declare function modelMeasuresFor(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): ReadonlyArray<ModelMeasureManifest>;
+/**
+ * A measure of the model as `describe`, the MCP tool and the instructions show it: its description,
+ * the entity measures it reads and how their properties align. `Ordered over planned units. Reads
+ * sales.ordered and plans.planned_units; sales.order_date aligns with plans.month.`
+ */
+export declare function modelMeasureDescription(measure: ModelMeasureManifest): string;
 /**
  * The entities one entity reaches, with the shortest routes to each: exactly the routes aggregate
  * resolution weighs ({@link shortestRoutesFrom}). Only then is the reader applied: a target they may
@@ -59,7 +70,8 @@ export declare function measuresFor(manifest: OntologyManifest, permissions?: Re
  */
 export declare function reachesOf(manifest: OntologyManifest, from: string, permissions?: ReadonlyArray<string>): ReadonlyArray<Reach>;
 /**
- * The aggregate part of the catalog's prose: every measure the reader may read, model-wide, and
- * per measure entity the entities it reaches. Empty when the reader may read no measure.
+ * The aggregate part of the catalog's prose: every measure the reader may read, model-wide, the
+ * measures of the model whose every input they may read, and per measure entity the entities it
+ * reaches. Empty when the reader may read no measure.
  */
 export declare function renderAggregates(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): string;