@segmentstream-cloud/ontology 0.11.0 → 0.13.0

package/README.md

@@ -11,7 +11,7 @@ action and is kept in history.
 TypeScript definitions, handler records and SDK calls use camelCase: `jobTitle`,
 `assignedOwnerId`, `createdAt`, and `changeStatus`. The SDK converts ontology names,
 select identifiers and declared action input fields to snake_case for the generated
-REST API, version 4 manifest and storage. TypeScript helpers and options stay
+REST API, version 6 manifest and storage. TypeScript helpers and options stay
 camelCase. JSON property contents, provider payloads, opaque action results and
 historical change names remain data and are preserved. `formatManifest` serializes
 the canonical wire contract shared by REST, storage and future transports.
@@ -28,6 +28,39 @@ one Effect version.
 `ontology/` is a package of its own. The SDK is an ES module, so `ontology/package.json`
 must set `"type": "module"`.
 
+SDK 0.12.0 adds warehouse replication enabled by default for all stored business entities,
+fields and business relationships. Existing history captures immutable snapshots and the
+service wakes the publisher after commits. Upgrade and redeploy to activate it; workspace
+configuration can disable replication or exclude individual entities, fields and relationships. See
+[setup and recovery](https://github.com/segmentstream/segmentstream/blob/main/docs/ontology-replication.md).
+
+SDK 0.13.0 writes manifest version 6. Relationships may target warehouse-backed entities, from
+stored or warehouse-backed entities, matched by value through `on`, and `unique` is allowed on
+warehouse-backed properties as an unenforced assertion. Upgrading: 0.12 accepted an explicit `onDelete`, or `optional: true`, on a
+warehouse → stored relationship; 0.13.0 `check` refuses both, so remove them. See
+[ontology aggregates](https://github.com/segmentstream/segmentstream/blob/main/docs/ontology-aggregates.md#relationships).
+
+SDK 0.13.0 also serves aggregates. Upgrade notes:
+
+- `POST /api/ontology/aggregate`, the MCP tool `aggregate` and, for each entity with measures,
+  `POST /api/ontology/<entity>/aggregate` answer measures of the model as the caller. The
+  service checks `<entity>:read` on every entity a request touches, then forwards it to
+  SegmentStream with `SEGMENTSTREAM_APP_CREDENTIAL`. Previews and local development have no
+  credential and answer `503 aggregate_unavailable`.
+- `m.countDistinct(property)` counts the distinct values of a text, email, url, select,
+  integer, date or timestamp property.
+- Stored entities may declare `measures`, computed over their replicated records; the built-in
+  `User` cannot.
+- `aggregate` is reserved for the route and the MCP tool: rename an entity with that name
+  before upgrading.
+- Under `signIn: { policy: "open" }`, anyone who signs in holds `member`, so `check` refuses a
+  `member` whose wildcard (`*:read`, the default, or `*:*`) would let strangers read
+  warehouse-backed entities through aggregates. Grant those to `member` by name
+  (`trendtoys_sales:read`), or keep the `invited` policy.
+
+See [ontology aggregates](https://github.com/segmentstream/segmentstream/blob/main/docs/ontology-aggregates.md)
+and [ontology analytics](https://github.com/segmentstream/segmentstream/blob/main/docs/ontology-aggregates-spec.md).
+
 ## Define the ontology
 
 ```ts
@@ -104,8 +137,10 @@ export default defineOntology({
 - `p.text`, `p.email`, `p.url`, `p.integer`, `p.number`, `p.boolean`, `p.date`,
   `p.timestamp`, `p.select` and `p.json` declare properties. `managed: true` keeps a
   property out of the generated `update` action.
-- `rel.one` and `rel.many` declare relationships. `User` is the built-in entity for app
-  users and service principals.
+- `rel.one` and `rel.many` declare relationships. Between stored entities, `rel.one` adds a
+  key and `rel.many` a join table. With a warehouse-backed end, `rel.one` declares one `on`
+  pair and is matched by value. `User` is the built-in entity for app users and service
+  principals.
 - `role(name, { description, permissions })` declares a role: a named set of permissions.
   `member` is built in: every active app user holds it, with the permissions of
   `defineOntology({ member })`.
@@ -126,8 +161,8 @@ A permission is `<entity>:<verb>`. The verbs are `read`, the generated `create`,
 `delete`, `link` and `unlink`, and the names of authored actions. A role may use `*` for the
 entity, the verb or both: `lead:*`, `*:read`, `*:*`.
 
-- Reads require `<entity>:read`: lists, queries, records, history, and both entities of a
-  relationship traversal. `include` and a filter through a relationship require `read` on
+- Reads require `<entity>:read`: lists, queries, records, history, both entities of a
+  relationship traversal, and every entity an aggregate touches. `include` and a filter through a relationship require `read` on
   the related entity. A missing permission answers 403 with `<permission> is required.`
 - Each action requires one permission. The generated `upsert_by_<property>` requires both
   `<entity>:create` and `<entity>:update`.
@@ -166,15 +201,16 @@ database pool. `configFromEnv()` reads these variables (`ENVIRONMENT_VARIABLES`,
 optional `NEON_AUTH_ENVIRONMENT_VARIABLES`). It throws `OntologyServiceConfigError` when
 one is missing or invalid, and never repeats the database URL.
 
-| Variable                              | Purpose                                                                   |
-| ------------------------------------- | ------------------------------------------------------------------------- |
-| `SEGMENTSTREAM_ONTOLOGY_DATABASE_URL` | Pooled connection string of the `ontology_app` role.                      |
-| `SEGMENTSTREAM_URL`                   | SegmentStream origin. It issues and verifies app tokens.                  |
-| `SEGMENTSTREAM_APPLICATION_ID`        | App tokens must be issued for this application.                           |
-| `SEGMENTSTREAM_WORKSPACE_ID`          | The workspace of the app.                                                 |
-| `SEGMENTSTREAM_ORGANIZATION_ID`       | The organization of the workspace.                                        |
-| `NEON_AUTH_BASE_URL`                  | Optional. The workspace's Neon Auth URL; its origin issues users' tokens. |
-| `NEON_AUTH_JWKS_URL`                  | Optional, set with the base URL. The keys that verify those tokens.       |
+| Variable                              | Purpose                                                                                      |
+| ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `SEGMENTSTREAM_ONTOLOGY_DATABASE_URL` | Pooled connection string of the `ontology_app` role.                                         |
+| `SEGMENTSTREAM_URL`                   | SegmentStream origin. It issues and verifies app tokens, and receives aggregates over https. |
+| `SEGMENTSTREAM_APPLICATION_ID`        | App tokens must be issued for this application.                                              |
+| `SEGMENTSTREAM_WORKSPACE_ID`          | The workspace of the app.                                                                    |
+| `SEGMENTSTREAM_ORGANIZATION_ID`       | The organization of the workspace.                                                           |
+| `NEON_AUTH_BASE_URL`                  | Optional. The workspace's Neon Auth URL; its origin issues users' tokens.                    |
+| `NEON_AUTH_JWKS_URL`                  | Optional, set with the base URL. The keys that verify those tokens.                          |
+| `SEGMENTSTREAM_APP_CREDENTIAL`        | Optional. The workspace app credential; without it, aggregates answer 503.                   |
 
 The platform sets these variables in the workspace deployment, the Neon Auth pair once the
 workspace has Neon Auth.
@@ -251,4 +287,4 @@ Apache-2.0
 
 ## Entity sources and aggregates
 
-Entities with a warehouse source declare mapped properties and measures without storage tables or record operations. See [ontology aggregates](../../docs/ontology-aggregates.md) for declaration rules, source verification, workspace authorization and the overlap release.
+Entities with a warehouse source declare mapped properties, measures and relationships without storage tables or record operations. Stored entities may declare measures too; they are computed over the entity's replication view, whose columns are the properties' snake_case names. See [ontology aggregates](https://github.com/segmentstream/segmentstream/blob/main/docs/ontology-aggregates.md) for declaration rules, relationship paths, source verification, workspace authorization and the overlap release.

package/dist/aggregate-routes.d.ts

@@ -0,0 +1,95 @@
+import type { OntologyManifest } from "./manifest.js";
+/**
+ * The names of a model-level aggregate request, as `/api/ontology/aggregate` and the platform's
+ * `POST …/aggregate` receive them: wire snake_case, `entity.member`.
+ */
+export interface AggregateNames {
+    /** `entity.measure`. */
+    readonly measures: readonly string[];
+    /** An identity, `entity.property`, or a route, `rootEntity.relationship[.relationship].property`. */
+    readonly dimensions?: readonly string[];
+    /** The dimension name of every filter, in the same forms as dimensions. */
+    readonly filters?: readonly string[];
+    /** A requested dimension, by its requested name or its identity. */
+    readonly granularityOf?: string;
+}
+/** How one measure entity reads every requested name. Paths are relative to the entity. */
+export interface EntityRoutes {
+    readonly entity: string;
+    /** The entity's requested measures, without the entity prefix, in request order. */
+    readonly measures: readonly string[];
+    /** Every requested dimension, in request order: `brand`, `product.brand`, `product.region.name`. */
+    readonly dimensions: readonly {
+        readonly identity: string;
+        readonly path: string;
+    }[];
+    /** The filters that apply to the entity, by their requested dimension name. */
+    readonly filters: readonly {
+        readonly name: string;
+        readonly path: string;
+    }[];
+    /** The requested filter names that do not apply to the entity: it cannot reach them. */
+    readonly unappliedFilters: readonly string[];
+    /** The path of the bucketed dimension, when the request names one. */
+    readonly granularityOf?: string;
+}
+export type AggregateRoutes = {
+    readonly ok: true;
+    /** The measure entities, in the order their first measure was requested. */
+    readonly entities: readonly EntityRoutes[];
+    /** Every entity the request reads, sorted: each needs `<entity>:read`. */
+    readonly touched: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** A route follows at most this many to-one relationships. */
+export declare const MAXIMUM_HOPS = 2;
+/**
+ * The JSON Schema pattern of an aggregate name: `entity.member`, or a route of at most
+ * {@link MAXIMUM_HOPS} relationships from a measure entity, in snake_case segments.
+ */
+export declare const AGGREGATE_NAME_PATTERN = "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*){1,3}$";
+/** To-one relationships followed from an entity, and every entity visited, both ends included. */
+export interface AggregateRoute {
+    readonly relationships: readonly string[];
+    readonly entities: readonly string[];
+}
+/** The built-in User is never replicated, so no route passes through it or ends at it. */
+export declare function isBuiltInUser(entity: string): boolean;
+export declare function hopLimitMessage(): string;
+export declare function userPathMessage(): string;
+export declare function unknownRelationshipMessage(input: {
+    readonly entity: string;
+    readonly relationship: string;
+}): string;
+/** A `rel.many`, or an inverse, which is to-many from the side that names it. */
+export declare function toManySegmentMessage(input: {
+    readonly entity: string;
+    readonly relationship: string;
+}): string;
+export declare function unknownPropertyMessage(input: {
+    readonly entity: string;
+    readonly property: string;
+}): string;
+/**
+ * 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 aggregate resolution weighs.
+ */
+export declare function shortestRoutesFrom(manifest: OntologyManifest, from: string): ReadonlyMap<string, readonly AggregateRoute[]>;
+/** The shortest routes from one entity to another, under {@link shortestRoutesFrom}'s rules. */
+export declare function shortestRoutes(manifest: OntologyManifest, input: {
+    readonly from: string;
+    readonly to: string;
+}): readonly AggregateRoute[];
+/**
+ * Resolves the names of a model-level aggregate against a manifest (docs/ontology-aggregates-spec.md,
+ * "Resolution"). It is the one place names and routes resolve: backend-next plans each measure
+ * 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 measure
+ * operators, nor add scope parents, which the planner adds along the same relative path.
+ */
+export declare function resolveAggregateRoutes(manifest: OntologyManifest, names: AggregateNames): AggregateRoutes;

package/dist/aggregate-routes.js

@@ -0,0 +1,332 @@
+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 an aggregate name: `entity.member`, or a route of at most
+ * {@link MAXIMUM_HOPS} relationships from a measure entity, in snake_case segments.
+ */
+export const AGGREGATE_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}.`;
+}
+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 aggregate 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 by name, and the shortest routes from each measure entity. */
+class RouteCatalog {
+    entities;
+    routes = new Map();
+    constructor(manifest) {
+        this.entities = entitiesByName(manifest);
+    }
+    entity(name) {
+        return this.entities.get(name) ?? refuse(`${name} is not an entity of this ontology.`);
+    }
+    /** 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 measures, grouped by entity in the order each entity's first measure appears. */
+function measureEntities(input) {
+    const { catalog, measures } = input;
+    const groups = new Map();
+    if (measures.length === 0) {
+        refuse("Request at least one measure.");
+    }
+    for (const [index, name] of measures.entries()) {
+        const segments = name.split(SEPARATOR);
+        if (measures.indexOf(name) !== index) {
+            refuse(`${name} is requested twice.`);
+        }
+        if (segments.length !== 2 || segments.some((segment) => segment.length === 0)) {
+            refuse(`${name} is not a measure name; write <entity>.<measure>.`);
+        }
+        const [entityName, measure] = segments;
+        const entity = catalog.entity(entityName);
+        if (!(entity.measures ?? []).some((candidate) => candidate.name === measure)) {
+            refuse(`${entityName} has no measure ${measure}.`);
+        }
+        groups.set(entityName, [...(groups.get(entityName) ?? []), measure]);
+    }
+    return groups;
+}
+/**
+ * Parses an identity, `entity.property`, or a route form, `root.relationship[.relationship].property`,
+ * whose root must own a requested measure. 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 measure 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 measure.`);
+    }
+    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 measure 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] };
+}
+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 aggregate against a manifest (docs/ontology-aggregates-spec.md,
+ * "Resolution"). It is the one place names and routes resolve: backend-next plans each measure
+ * 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 measure
+ * operators, nor add scope parents, which the planner adds along the same relative path.
+ */
+export function resolveAggregateRoutes(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 measureNames = namesOf("measures", names.measures);
+    const dimensionNames = namesOf("dimensions", names.dimensions ?? []);
+    const filterNames = namesOf("filters", names.filters ?? []);
+    const groups = measureEntities({ catalog, measures: measureNames });
+    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.`);
+        }
+    }
+    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].map(([entity, measures]) => {
+        const firstMeasure = `${entity}${SEPARATOR}${measures[0]}`;
+        const dimensionRoutes = dimensions.map((dimension) => {
+            const resolution = resolveName({ catalog, from: entity, requested: dimension });
+            if (resolution.kind === "unreachable") {
+                refuse(`${firstMeasure} cannot reach ${dimension.identity}.`);
+            }
+            if (resolution.kind === "ambiguous") {
+                refuse(ambiguousRoute({ from: 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, measures, dimensionRoutes };
+    });
+    const entities = routed.map(({ entity, measures, dimensionRoutes }) => {
+        const applied = [];
+        const unappliedFilters = [];
+        for (const filter of filters) {
+            const resolution = resolveName({ catalog, from: entity, requested: filter });
+            if (resolution.kind === "ambiguous") {
+                refuse(ambiguousRoute({ from: entity, requested: filter, routes: resolution.routes }));
+            }
+            if (resolution.kind === "unreachable") {
+                unappliedFilters.push(filter.name);
+                continue;
+            }
+            resolution.route.entities.forEach((visited) => touched.add(visited));
+            applied.push({ name: filter.name, path: pathOf(resolution.route, filter.property) });
+        }
+        const bucketedPath = bucketed === undefined
+            ? undefined
+            : dimensionRoutes.find((route) => route.identity === bucketed.identity)?.path;
+        return {
+            entity,
+            measures,
+            dimensions: dimensionRoutes,
+            filters: applied,
+            unappliedFilters,
+            ...(bucketedPath === undefined ? {} : { granularityOf: bucketedPath }),
+        };
+    });
+    for (const filter of filters) {
+        if (entities.every((routes) => routes.unappliedFilters.includes(filter.name))) {
+            refuse(`No measure can reach ${filter.name}.`);
+        }
+    }
+    return { entities, touched: [...touched].sort() };
+}