@segmentstream-cloud/ontology 0.12.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.
@@ -32,7 +32,34 @@ SDK 0.12.0 adds warehouse replication enabled by default for all stored business
 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](../../docs/ontology-replication.md).
+[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
 
@@ -110,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 })`.
@@ -132,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`.
@@ -172,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.
@@ -257,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() };
+}