@segmentstream-cloud/ontology 0.11.0 → 0.13.0

package/dist/service/aggregate-platform.js

@@ -0,0 +1,189 @@
+import { Data, Effect, Redacted } from "effect";
+import { AggregateUpstreamUnavailable } from "./errors.js";
+/**
+ * How long one aggregate may take end to end, the response included. BigQuery answers most within
+ * seconds; the margin covers a cold warehouse and the hops to and from SegmentStream.
+ */
+export const AGGREGATE_TIMEOUT_MS = 60_000;
+/** The header that carries the service's request id to SegmentStream, as connection calls do. */
+const REQUEST_ID_HEADER = "x-segmentstream-request-id";
+/**
+ * The hash of the manifest the service resolved and checked the request against. SegmentStream
+ * answers `409 ontology_version_mismatch` when its deployed manifest differs, so a request checked
+ * against one ontology never runs against another.
+ */
+export const MANIFEST_HASH_HEADER = "x-ontology-manifest-hash";
+/**
+ * The entities the service checked `<entity>:read` on, sorted and comma-separated. SegmentStream
+ * answers `409 aggregate_scope_mismatch` when it would read any other, so the service's resolution
+ * and SegmentStream's can never drift apart unnoticed.
+ */
+export const TOUCHED_HEADER = "x-ontology-touched";
+/**
+ * Statuses that refuse the deployment rather than the caller: its credential, its admission or the
+ * route itself. Passing them on would make the caller sign in again or look for a missing route.
+ */
+const DEPLOYMENT_FAULTS = {
+    401: "credential_rejected",
+    403: "credential_rejected",
+    404: "upstream_misconfigured",
+};
+/** SegmentStream would read beyond what the service checked: this deployment's SDK is behind. */
+export const SCOPE_MISMATCH = "aggregate_scope_mismatch";
+/** Statuses whose `Retry-After` the caller receives as SegmentStream sent it. */
+const RETRY_AFTER_STATUSES = new Set([429, 503]);
+/** A `Retry-After` value: seconds or an HTTP date. Anything else is not passed on. */
+const RETRY_AFTER_VALUE = /^[0-9A-Za-z ,:+-]{1,64}$/;
+/** The most of SegmentStream's body an operator log keeps. */
+const SNIPPET_LENGTH = 500;
+/** How many causes deep an operator log follows a failed call. */
+const CAUSE_DEPTH = 3;
+/** Hosts a deployment may reach over plain http: the machine itself, in development. */
+const LOOPBACK_HOSTS = new Set(["localhost", "[::1]"]);
+/** The call ended without an answer; `aborted` when the caller went away first. */
+class CallFailed extends Data.TaggedError("CallFailed") {
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The credential travels only to SegmentStream over TLS, or over plain http to this machine. */
+function securePlatform(origin) {
+    const { protocol, hostname } = new URL(origin);
+    if (protocol === "https:") {
+        return true;
+    }
+    return (protocol === "http:" && (LOOPBACK_HOSTS.has(hostname) || /^127(?:\.\d{1,3}){3}$/.test(hostname)));
+}
+/**
+ * A failed call for the operator: name, message and stack, then each cause, with every occurrence
+ * of the credential replaced.
+ */
+function describeError(error, redact, depth = 0) {
+    if (!(error instanceof Error)) {
+        return redact(String(error));
+    }
+    const code = error.code;
+    const head = error.stack ?? `${error.name}: ${error.message}`;
+    const own = typeof code === "string" ? `${head} [${code}]` : head;
+    const cause = error.cause !== undefined && depth < CAUSE_DEPTH
+        ? `\ncaused by: ${describeError(error.cause, redact, depth + 1)}`
+        : "";
+    return redact(`${own}${cause}`);
+}
+function parseObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return isRecord(parsed) ? { body: parsed } : { error: new TypeError("Not a JSON object.") };
+    }
+    catch (error) {
+        return { error };
+    }
+}
+/**
+ * SegmentStream's `POST /api/v1/workspaces/{id}/aggregate`, and its per-entity
+ * `…/entities/{entity}/aggregate`, called with the workspace app credential. `undefined` when the deployment has none, or when SegmentStream's origin is plain
+ * http to another machine, which is logged once. Every request names the manifest it was checked
+ * against, and a redirect is refused, so the credential never leaves for another origin.
+ *
+ * Every answer but a 2xx is logged with both request ids, the status and the start of the body; a
+ * failed call with its message, stack and causes. The credential is redacted from all of them. A
+ * caller who goes away interrupts the call, which is not SegmentStream's failure.
+ */
+export function platformAggregates(environment, fetchImpl = fetch) {
+    const { appCredential, segmentstreamUrl } = environment;
+    if (appCredential === undefined) {
+        return undefined;
+    }
+    if (!securePlatform(segmentstreamUrl)) {
+        Effect.runSync(Effect.logError("ontology.aggregate.insecure_platform").pipe(Effect.annotateLogs({
+            diagnostic: "SEGMENTSTREAM_URL is not https; aggregates are unavailable.",
+            platform: segmentstreamUrl,
+        })));
+        return undefined;
+    }
+    const credential = Redacted.value(appCredential);
+    const redact = (text) => text.split(credential).join("[redacted]");
+    const workspace = `${segmentstreamUrl}/api/v1/workspaces/` + encodeURIComponent(environment.workspaceId);
+    const urlOf = (entity) => entity === undefined
+        ? `${workspace}/aggregate`
+        : `${workspace}/entities/${encodeURIComponent(entity)}/aggregate`;
+    const exchange = (input) => Effect.tryPromise({
+        try: async (signal) => {
+            try {
+                const response = await fetchImpl(urlOf(input.entity), {
+                    method: "POST",
+                    headers: {
+                        authorization: `Bearer ${credential}`,
+                        "content-type": "application/json",
+                        accept: "application/json",
+                        [REQUEST_ID_HEADER]: input.requestId,
+                        [MANIFEST_HASH_HEADER]: environment.manifestHash,
+                        [TOUCHED_HEADER]: input.touched.join(","),
+                    },
+                    body: JSON.stringify(input.body),
+                    redirect: "error",
+                    signal: AbortSignal.any([signal, AbortSignal.timeout(AGGREGATE_TIMEOUT_MS)]),
+                });
+                const text = await response.text();
+                return {
+                    status: response.status,
+                    text,
+                    retryAfter: response.headers.get("retry-after"),
+                    platformRequestId: response.headers.get("x-request-id"),
+                };
+            }
+            catch (error) {
+                throw new CallFailed({ error, aborted: signal.aborted });
+            }
+        },
+        catch: (error) => error instanceof CallFailed ? error : new CallFailed({ error, aborted: false }),
+    });
+    /** No answer: a timeout or an unreachable SegmentStream. */
+    const unanswered = (error, requestId) => {
+        const reason = error instanceof DOMException && error.name === "TimeoutError" ? "timeout" : "unreachable";
+        return Effect.logWarning("ontology.aggregate.upstream_failed").pipe(Effect.annotateLogs({ requestId, diagnostic: reason, error: describeError(error, redact) }), Effect.andThen(Effect.fail(new AggregateUpstreamUnavailable({ reason }))));
+    };
+    /** An answer: passed on, or a 502 when it faults the deployment or is not a JSON object. */
+    const judge = (answer, requestId) => Effect.gen(function* () {
+        const parsed = parseObject(answer.text);
+        const body = "body" in parsed ? parsed.body : undefined;
+        const fault = DEPLOYMENT_FAULTS[answer.status] ?? (body === undefined ? "invalid_response" : undefined);
+        const platformRequestId = typeof body?.requestId === "string" ? body.requestId : answer.platformRequestId;
+        if (fault !== undefined || answer.status < 200 || answer.status >= 300) {
+            const code = typeof body?.error === "string" ? body.error : undefined;
+            const level = fault !== undefined || code === SCOPE_MISMATCH
+                ? Effect.logError
+                : answer.status >= 500
+                    ? Effect.logWarning
+                    : Effect.logInfo;
+            yield* level(fault === undefined
+                ? "ontology.aggregate.platform_refused"
+                : "ontology.aggregate.upstream_failed").pipe(Effect.annotateLogs({
+                requestId,
+                platformRequestId: platformRequestId ?? "none",
+                status: answer.status,
+                diagnostic: fault ?? code ?? "refused",
+                body: redact(answer.text.slice(0, SNIPPET_LENGTH)),
+                ...("error" in parsed ? { error: describeError(parsed.error, redact) } : {}),
+            }));
+        }
+        if (fault !== undefined || body === undefined) {
+            return yield* new AggregateUpstreamUnavailable({
+                reason: fault ?? "invalid_response",
+                status: answer.status,
+            });
+        }
+        const retryAfter = RETRY_AFTER_STATUSES.has(answer.status) &&
+            answer.retryAfter !== null &&
+            RETRY_AFTER_VALUE.test(answer.retryAfter)
+            ? answer.retryAfter
+            : undefined;
+        return {
+            status: answer.status,
+            text: answer.text,
+            body,
+            ...(retryAfter === undefined ? {} : { retryAfter }),
+        };
+    });
+    return (input) => exchange(input).pipe(Effect.catchTag("CallFailed", (failed) => failed.aborted ? Effect.interrupt : unanswered(failed.error, input.requestId)), Effect.flatMap((answer) => judge(answer, input.requestId)));
+}

package/dist/service/aggregate.d.ts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+import type { OntologyManifest } from "../manifest.js";
+import type { AggregateTransport, PlatformAnswer } from "./aggregate-platform.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { AggregateLimited, AggregateUnavailable, AggregateUpstreamUnavailable, InvalidAggregateQuery, InvalidRequestBody, ReadDenied, RequestId } from "./errors.js";
+import { type RateLimit, type RateLimiter } from "./rate-limit.js";
+/**
+ * Aggregates one principal may run per minute, through both routes and the MCP tool together. Each
+ * runs a warehouse query with the deployment's credential, so one caller must not spend without
+ * bound.
+ */
+export declare const AGGREGATE_LIMIT: RateLimit;
+/** Every way the facade refuses or fails an aggregate before SegmentStream answers it. */
+export type AggregateFailure = AggregateLimited | InvalidRequestBody | InvalidAggregateQuery | ReadDenied | AggregateUnavailable | AggregateUpstreamUnavailable;
+/**
+ * Runs an aggregate as the caller, whatever the transport: the HTTP route passes the parsed body,
+ * the MCP tool its arguments. Its answer is SegmentStream's, error statuses included.
+ */
+export type Aggregate = (body: unknown) => Effect.Effect<PlatformAnswer, AggregateFailure, CurrentPrincipal | RequestId>;
+/** The service's aggregates: model-level, and the per-entity shorthand of each entity. */
+export interface Aggregates {
+    /** `POST /api/ontology/aggregate` and the MCP `aggregate` tool. */
+    readonly model: Aggregate;
+    /** `POST /api/ontology/<entity>/aggregate`, the shorthand `segmentstream.ontology.<entity>`. */
+    readonly entity: (entity: string) => Aggregate;
+}
+/**
+ * The ontology service's aggregate facade (docs/ontology-aggregates-spec.md, "Surfaces"). Both
+ * routes and the MCP tool run as the caller:
+ * 0. the call counts against the caller's {@link AGGREGATE_LIMIT}, whichever way it came;
+ * 1. the request's shape and bounds are checked, and its names resolved against the service's own
+ *    manifest into every entity it reads;
+ * 2. the caller needs `<entity>:read` on all of them;
+ * 3. the body goes to SegmentStream unchanged with the workspace app credential, naming the entities
+ *    checked, or the answer is `aggregate_unavailable` where the deployment has no credential.
+ */
+export declare function makeAggregates(input: {
+    readonly manifest: OntologyManifest;
+    readonly transport: AggregateTransport | undefined;
+    /** One bucket per principal; {@link AGGREGATE_LIMIT} by default. */
+    readonly limiter?: RateLimiter;
+}): Aggregates;

package/dist/service/aggregate.js

@@ -0,0 +1,145 @@
+import { Effect, Schema } from "effect";
+import { resolveAggregateRoutes } from "../aggregate-routes.js";
+import { isAllowed, permissionOf, READ_VERB } from "../permissions.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { AggregateLimited, AggregateUnavailable, InvalidAggregateQuery, InvalidRequestBody, ReadDenied, RequestId, schemaIssues, } from "./errors.js";
+import { fixedWindowLimiter } from "./rate-limit.js";
+import { AggregateRequest, EntityAggregateRequest } from "./schemas.js";
+/**
+ * Aggregates one principal may run per minute, through both routes and the MCP tool together. Each
+ * runs a warehouse query with the deployment's credential, so one caller must not spend without
+ * bound.
+ */
+export const AGGREGATE_LIMIT = { limit: 30, windowMs: 60_000, maxKeys: 10_000 };
+function decode(schema, body) {
+    return Schema.decodeUnknownEffect(schema)(body, { errors: "all" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error.issue) })));
+}
+/**
+ * The first `orderBy` entry that names neither a requested measure nor a requested dimension, by
+ * its requested name or its identity. Ordering by anything else would read what the permission
+ * check never saw.
+ */
+function unrequestedOrder(request, routes) {
+    const dimensions = new Set([
+        ...(request.dimensions ?? []),
+        ...(routes.entities[0]?.dimensions ?? []).map(({ identity }) => identity),
+    ]);
+    for (const order of request.orderBy ?? []) {
+        if (order.measure !== undefined && !request.measures.includes(order.measure)) {
+            return order.measure;
+        }
+        if (order.dimension !== undefined && !dimensions.has(order.dimension)) {
+            return order.dimension;
+        }
+    }
+    return undefined;
+}
+/**
+ * A model-level request's entities, as the shared resolver finds them: each measure's entity,
+ * every entity on a dimension's or a filter's route, intermediates included, and every entity a
+ * filter names even where it does not apply.
+ */
+function modelTouched(manifest, body) {
+    return Effect.gen(function* () {
+        const request = yield* decode(AggregateRequest, body);
+        const routes = resolveAggregateRoutes(manifest, {
+            measures: request.measures,
+            dimensions: request.dimensions ?? [],
+            filters: (request.filters ?? []).map((filter) => filter.dimension),
+            ...(request.granularityOf === undefined ? {} : { granularityOf: request.granularityOf }),
+        });
+        if (!routes.ok) {
+            return yield* new InvalidAggregateQuery({ reason: routes.reason });
+        }
+        const unordered = unrequestedOrder(request, routes);
+        if (unordered !== undefined) {
+            return yield* new InvalidAggregateQuery({
+                reason: `orderBy names ${unordered}, which the request does not ask for.`,
+            });
+        }
+        return routes.touched;
+    });
+}
+/**
+ * A per-entity request's entities: the entity, and every entity along each relative name it
+ * groups, filters, buckets or orders by, following the manifest's `rel.one` relationships. As on
+ * SegmentStream's per-entity route, a path may follow a self-relationship (`manager.name`).
+ */
+function entityTouched(manifest, entity, body) {
+    return Effect.gen(function* () {
+        const request = yield* decode(EntityAggregateRequest, body);
+        const entities = new Map(manifest.entities.map((candidate) => [candidate.name, candidate]));
+        const touched = new Set([entity]);
+        const names = [
+            ...request.dimensions,
+            ...(request.filters ?? []).map((filter) => filter.dimension),
+            ...(request.granularityOf === undefined ? [] : [request.granularityOf]),
+            ...(request.orderBy ?? []).flatMap((order) => order.dimension === undefined ? [] : [order.dimension]),
+        ];
+        for (const name of names) {
+            const segments = name.split(".");
+            let current = entities.get(entity);
+            if (segments.some((segment) => segment === "")) {
+                return yield* new InvalidAggregateQuery({ reason: `${name} is not a valid name.` });
+            }
+            for (const relationshipName of segments.slice(0, -1)) {
+                const relationship = current?.relationships.find((candidate) => candidate.name === relationshipName);
+                if (current === undefined || relationship === undefined) {
+                    return yield* new InvalidAggregateQuery({
+                        reason: `${current?.name ?? entity} has no relationship ${relationshipName}.`,
+                    });
+                }
+                if (relationship.cardinality !== "one") {
+                    return yield* new InvalidAggregateQuery({
+                        reason: `${relationshipName} is not a to-one relationship of ${current.name}.`,
+                    });
+                }
+                current = entities.get(relationship.to);
+                touched.add(relationship.to);
+            }
+        }
+        return [...touched].sort();
+    });
+}
+/**
+ * The ontology service's aggregate facade (docs/ontology-aggregates-spec.md, "Surfaces"). Both
+ * routes and the MCP tool run as the caller:
+ * 0. the call counts against the caller's {@link AGGREGATE_LIMIT}, whichever way it came;
+ * 1. the request's shape and bounds are checked, and its names resolved against the service's own
+ *    manifest into every entity it reads;
+ * 2. the caller needs `<entity>:read` on all of them;
+ * 3. the body goes to SegmentStream unchanged with the workspace app credential, naming the entities
+ *    checked, or the answer is `aggregate_unavailable` where the deployment has no credential.
+ */
+export function makeAggregates(input) {
+    const { manifest, transport } = input;
+    const limiter = input.limiter ?? fixedWindowLimiter(AGGREGATE_LIMIT);
+    const run = (request) => Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const requestId = yield* RequestId;
+        const retryAfterSeconds = limiter.take(principal.id);
+        if (retryAfterSeconds !== undefined) {
+            return yield* new AggregateLimited({ retryAfterSeconds });
+        }
+        const touched = yield* request.touchedBy(request.body);
+        const missing = touched
+            .map((entity) => permissionOf(entity, READ_VERB))
+            .filter((permission) => !isAllowed(permission, principal));
+        if (missing.length > 0) {
+            return yield* new ReadDenied({ permissions: missing });
+        }
+        if (transport === undefined) {
+            return yield* new AggregateUnavailable();
+        }
+        return yield* transport({
+            ...(request.entity === undefined ? {} : { entity: request.entity }),
+            body: request.body,
+            requestId,
+            touched,
+        });
+    });
+    return {
+        model: (body) => run({ body, touchedBy: (value) => modelTouched(manifest, value) }),
+        entity: (entity) => (body) => run({ entity, body, touchedBy: (value) => entityTouched(manifest, entity, value) }),
+    };
+}

package/dist/service/api.d.ts

@@ -2,7 +2,7 @@ import { Layer, Schema } from "effect";
 import { HttpApi, HttpApiGroup, HttpApiMiddleware } from "effect/unstable/httpapi";
 import type { Ontology } from "../ontology.js";
 import { RequestId } from "./errors.js";
-import { type ApiPlan } from "./plan.js";
+import { type ApiPlan, type PlannedEntity } from "./plan.js";
 import type { GeneratedActionsProvider } from "./runtime-contract.js";
 import { type EntitySchemas } from "./schemas.js";
 /** The path every ontology route lives under. */
@@ -26,6 +26,8 @@ declare const ErrorResponses_base: HttpApiMiddleware.ServiceClass<ErrorResponses
 export declare class ErrorResponses extends ErrorResponses_base {
 }
 export declare const ErrorResponsesLive: Layer.Layer<ErrorResponses, never, never>;
+/** Whether an entity declares measures, and so has `POST /api/ontology/<entity>/aggregate`. */
+export declare function hasMeasures(planned: PlannedEntity): boolean;
 export interface BuiltApi {
     readonly plan: ApiPlan;
     readonly api: OntologyApi;
@@ -39,8 +41,8 @@ export interface DeriveApiOptions {
 /**
  * The HttpApi of an ontology: per entity `find`, `query`, `get`, `history`, a traversal per
  * relationship and inverse, and a route per generated and authored action; and the catalog, graph,
- * OpenAPI, status, caller (`me`), sign-in check and prose routes. There is no PUT, PATCH or DELETE:
- * every change is an action.
+ * OpenAPI, status, caller (`me`), sign-in check, prose and aggregate routes. There is no PUT, PATCH
+ * or DELETE: every change is an action.
  */
 export declare function deriveApi(ontology: Ontology, options?: DeriveApiOptions): OntologyApi;
 export {};

package/dist/service/api.js

@@ -1,5 +1,6 @@
 import { Effect, Layer, Schema } from "effect";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi, } from "effect/unstable/httpapi";
+import { AGGREGATE_ROUTE } from "../names.js";
 import { storageGroup } from "../storage/api.js";
 import { DownloadRequest, TransferGrant } from "../storage/sessions.js";
 import { permissionOf, READ_VERB } from "../permissions.js";
@@ -8,7 +9,7 @@ import { Authentication } from "./authentication.js";
 import { actionDescription, requires } from "./descriptions.js";
 import { InvalidRequestBody, RequestId, failureResponse } from "./errors.js";
 import { planApi, } from "./plan.js";
-import { ActionResponse, AsParams, Catalog, ErrorSchemas, Graph, HistoryPage, HistoryParams, IdParam, Me, SignInCheckRequest, SignInCheckResult, Status, actionRequest, entitySchemas, } from "./schemas.js";
+import { ActionResponse, AggregateRequest, AggregateResult, EntityAggregateRequest, AsParams, Catalog, ErrorSchemas, Graph, HistoryPage, HistoryParams, IdParam, Me, SignInCheckRequest, SignInCheckResult, Status, actionRequest, entitySchemas, } from "./schemas.js";
 /** The path every ontology route lives under. */
 export const BASE_PATH = "/api/ontology";
 /** The group of the global routes. Entity names are snake_case, so it cannot clash with one. */
@@ -52,6 +53,20 @@ const actionErrors = [
     ErrorSchemas.unprocessable,
     ErrorSchemas.internal,
 ];
+/**
+ * The facade's own refusals. SegmentStream's answers, success and errors alike, pass through as it
+ * sent them: its errors are `{ error, detail, requestId, retryable }`.
+ */
+const aggregateErrors = [
+    ErrorSchemas.invalidRequest,
+    ErrorSchemas.invalidAggregateQuery,
+    ErrorSchemas.readForbidden,
+    ErrorSchemas.unsupportedMediaType,
+    ErrorSchemas.rateLimited,
+    ErrorSchemas.internal,
+    ErrorSchemas.aggregateUpstreamUnavailable,
+    ErrorSchemas.aggregateUnavailable,
+];
 /** An action that calls connections also answers for the connections it could not use. */
 const connectionActionErrors = [
     ...actionErrors,
@@ -62,6 +77,23 @@ const connectionActionErrors = [
 function readPermission(entity) {
     return permissionOf(entity, READ_VERB);
 }
+/** Whether an entity declares measures, and so has `POST /api/ontology/<entity>/aggregate`. */
+export function hasMeasures(planned) {
+    return Object.keys(planned.resolved.entity.definition.measures ?? {}).length > 0;
+}
+/** The per-entity shorthand, which runs as the caller like the model-level route. */
+function entityAggregateEndpoint(planned) {
+    const { plural } = planned.resolved.entity.definition;
+    const endpoint = HttpApiEndpoint.post("aggregate", `${BASE_PATH}/${planned.name}/aggregate`, {
+        payload: EntityAggregateRequest,
+        success: AggregateResult,
+        error: aggregateErrors,
+    });
+    return documented(endpoint, `Aggregate ${plural.toLowerCase()}`, `The entity's measures, with names relative to it: revenue, product.brand. dateRange bounds a ` +
+        "partitioned entity. Requires reading the entity and every entity along each path it " +
+        "groups, filters or orders by. Answered as POST /api/ontology/aggregate is, and counted " +
+        "against the same limit.");
+}
 function traversalEndpoint(planned, traversal, target, targetNames) {
     const label = planned.resolved.entity.definition.label;
     const reach = traversal.kind === "one" ? `one ${targetNames.label}` : `many ${targetNames.plural}`;
@@ -85,11 +117,12 @@ function entityGroup(planned, schemas, names) {
     const own = schemas.get(planned.name);
     const { definition } = planned.resolved.entity;
     const base = `${BASE_PATH}/${planned.name}`;
+    const aggregate = hasMeasures(planned) ? [authenticated(entityAggregateEndpoint(planned))] : [];
     if (definition.source !== undefined) {
         return HttpApiGroup.make(planned.name).add(authenticated(HttpApiEndpoint.get("sourceCollection", base, {
             success: Schema.Never,
             error: recordErrors,
-        })));
+        })), ...aggregate);
     }
     const plural = definition.plural.toLowerCase();
     const read = requires([readPermission(planned.name)]);
@@ -127,7 +160,7 @@ function entityGroup(planned, schemas, names) {
         }), `Download ${property.name}`, `Requires ${planned.name}:read. Historical revisions must belong to this record and field.`)),
         ...planned.actions.map((action) => actionEndpoint(planned, action)),
     ];
-    const [first, ...rest] = endpoints.map(authenticated);
+    const [first, ...rest] = [...endpoints.map(authenticated), ...aggregate];
     return HttpApiGroup.make(planned.name)
         .add(first, ...rest)
         .annotateMerge(OpenApi.annotations({ title: definition.plural, description: definition.description }));
@@ -165,7 +198,20 @@ function serviceGroup() {
     }).middleware(ErrorResponses), "Whether an address may sign in", "Public and rate limited per client address. The app asks before it emails a code or a " +
         "sign-in link. Under the invited policy, an active member's address is allowed: with " +
         "code once they have signed in with Neon Auth, with link before; any other address, " +
-        "deactivated members included, is not. Under open, every address is allowed with link."))
+        "deactivated members included, is not. Under open, every address is allowed with link."), authenticated(documented(HttpApiEndpoint.post("aggregate", `${BASE_PATH}/${AGGREGATE_ROUTE}`, {
+        payload: AggregateRequest,
+        success: AggregateResult,
+        error: aggregateErrors,
+    }), "Aggregate measures across the ontology", "Numbers about the model: measures from several entities, grouped and filtered by " +
+        "properties of related entities. Look at or change records through find and actions; " +
+        "count, sum or compare through aggregate. Names are <entity>.<measure> and " +
+        "<entity>.<property>, or a route from a measure's entity: " +
+        "<entity>.<relationship>.<property>. Requires <entity>:read on every entity the " +
+        "request reads: each measure's entity, and every entity on a dimension's or a " +
+        "filter's route, and at most 30 aggregates a minute per caller, MCP included. The " +
+        "service then forwards the request to SegmentStream, which " +
+        "answers from the warehouse and the replica of stored records; its answer, errors " +
+        "included, is returned unchanged. Preview deployments answer aggregate_unavailable.")))
         .annotateMerge(OpenApi.annotations({ title: SERVICE_GROUP, description: "The ontology as a whole." }));
 }
 export function buildApi(plan) {
@@ -197,8 +243,8 @@ const runtimeGeneratedActions = (entity, ontology) => generatedActions(ontology,
 /**
  * The HttpApi of an ontology: per entity `find`, `query`, `get`, `history`, a traversal per
  * relationship and inverse, and a route per generated and authored action; and the catalog, graph,
- * OpenAPI, status, caller (`me`), sign-in check and prose routes. There is no PUT, PATCH or DELETE:
- * every change is an action.
+ * OpenAPI, status, caller (`me`), sign-in check, prose and aggregate routes. There is no PUT, PATCH
+ * or DELETE: every change is an action.
  */
 export function deriveApi(ontology, options = {}) {
     return buildApi(planApi(ontology, options.generatedActions ?? runtimeGeneratedActions)).api;

package/dist/service/catalog.d.ts

@@ -1,4 +1,4 @@
-import type { OntologyManifest } from "../manifest.js";
+import { type OntologyManifest } from "../manifest.js";
 /**
  * The catalog for a reader: the manifest, with each entity's actions narrowed to the ones the given
  * permissions may run. Without permissions it is the manifest itself.
@@ -10,6 +10,15 @@ export interface GraphRelationship {
     readonly to: string;
     readonly inverse: string;
     readonly cardinality: "one" | "many";
+    /** The property pair of a relationship matched by value: one with a warehouse-backed end. */
+    readonly on?: {
+        readonly property: string;
+        readonly targetProperty: string;
+    };
+    /**
+     * Whether the relationship may lead to nothing. Only a stored → stored `rel.one` can promise a
+     * record; a value-matched reference is never checked against its target.
+     */
     readonly optional: boolean;
     readonly phrase: readonly [string, string];
     /** The relationship read from the declaring entity: "Lead is owned by one User". */

package/dist/service/catalog.js

@@ -1,3 +1,4 @@
+import { isValueMatched } from "../manifest.js";
 import { isAllowed } from "../permissions.js";
 import { actionPermission } from "../render.js";
 /**
@@ -33,8 +34,15 @@ export function graphOf(manifest) {
         relationships: manifest.entities.flatMap((source) => source.relationships.map((relationship) => {
             const target = entities.get(relationship.to);
             const targetLabel = target?.label ?? relationship.to;
+            // Manifests before version 5 wrote `optional` on warehouse → stored relationships too.
+            const valueMatched = isValueMatched(relationship) ||
+                source.source !== undefined ||
+                target?.source !== undefined;
+            // As describe phrases them: nothing promises a value-matched relationship a record.
+            const one = valueMatched ? "at most one" : "one";
+            const many = valueMatched ? "" : "many ";
             const forwardTarget = relationship.cardinality === "one"
-                ? `one ${targetLabel}`
+                ? `${one} ${targetLabel}`
                 : `many ${target?.plural ?? relationship.to}`;
             return {
                 from: source.name,
@@ -42,10 +50,11 @@ export function graphOf(manifest) {
                 to: relationship.to,
                 inverse: relationship.inverse,
                 cardinality: relationship.cardinality,
-                optional: relationship.cardinality === "many" || relationship.optional === true,
+                ...(relationship.on !== undefined ? { on: relationship.on } : {}),
+                optional: relationship.cardinality === "many" || valueMatched || relationship.optional === true,
                 phrase: relationship.phrase,
                 forward: `${source.label} ${relationship.phrase[0]} ${forwardTarget}`,
-                backward: `${targetLabel} ${relationship.phrase[1]} many ${source.plural}`,
+                backward: `${targetLabel} ${relationship.phrase[1]} ${many}${source.plural}`,
                 description: relationship.description,
             };
         })),

package/dist/service/config.d.ts

@@ -11,6 +11,12 @@ export declare const ENVIRONMENT_VARIABLES: {
     readonly workspaceId: "SEGMENTSTREAM_WORKSPACE_ID";
     readonly organizationId: "SEGMENTSTREAM_ORGANIZATION_ID";
 };
+/**
+ * The workspace app credential (`ssw_…`), which Vercel injects into every service of a production
+ * deployment. The service forwards aggregates to SegmentStream with it; without it, aggregates are
+ * unavailable and everything else works.
+ */
+export declare const APP_CREDENTIAL_VARIABLE = "SEGMENTSTREAM_APP_CREDENTIAL";
 /**
  * The workspace's Neon Auth, which signs the app's users in. Provisioning sets both on workspaces
  * that have it; a service without them accepts SegmentStream app tokens and API keys only.
@@ -38,6 +44,11 @@ export interface OntologyEnvironment {
     readonly applicationId: string;
     readonly workspaceId: string;
     readonly organizationId: string;
+    /**
+     * The workspace app credential. With it, `/api/ontology/aggregate` forwards to SegmentStream at
+     * `segmentstreamUrl` for `workspaceId`; previews and local development have none.
+     */
+    readonly appCredential?: Redacted.Redacted<string>;
     /** Present once the workspace has Neon Auth: members then sign in with its tokens. */
     readonly neonAuth?: NeonAuthEnvironment;
     /**
@@ -88,7 +99,8 @@ export declare class OntologyServiceConfigError extends OntologyServiceConfigErr
 /**
  * Reads the service's configuration from the environment. It fails closed: a missing or invalid
  * variable throws {@link OntologyServiceConfigError} naming every missing variable, and never the
- * value of the database URL. The Neon Auth variables are optional, but only as a pair.
+ * value of the database URL. The Neon Auth variables are optional, but only as a pair. The app
+ * credential is optional and kept redacted.
  */
 export declare function configFromEnv(environment?: Readonly<Record<string, string | undefined>>): OntologyEnvironment;
 export {};

package/dist/service/config.js

@@ -9,6 +9,12 @@ export const ENVIRONMENT_VARIABLES = {
     workspaceId: "SEGMENTSTREAM_WORKSPACE_ID",
     organizationId: "SEGMENTSTREAM_ORGANIZATION_ID",
 };
+/**
+ * The workspace app credential (`ssw_…`), which Vercel injects into every service of a production
+ * deployment. The service forwards aggregates to SegmentStream with it; without it, aggregates are
+ * unavailable and everything else works.
+ */
+export const APP_CREDENTIAL_VARIABLE = "SEGMENTSTREAM_APP_CREDENTIAL";
 /**
  * The workspace's Neon Auth, which signs the app's users in. Provisioning sets both on workspaces
  * that have it; a service without them accepts SegmentStream app tokens and API keys only.
@@ -70,7 +76,8 @@ function checkDatabaseUrl(name, value) {
 /**
  * Reads the service's configuration from the environment. It fails closed: a missing or invalid
  * variable throws {@link OntologyServiceConfigError} naming every missing variable, and never the
- * value of the database URL. The Neon Auth variables are optional, but only as a pair.
+ * value of the database URL. The Neon Auth variables are optional, but only as a pair. The app
+ * credential is optional and kept redacted.
  */
 export function configFromEnv(environment = process.env) {
     const read = (name) => environment[name]?.trim() ?? "";
@@ -107,6 +114,9 @@ export function configFromEnv(environment = process.env) {
                 storageMaintenanceKey: Redacted.make(read("SEGMENTSTREAM_ONTOLOGY_STORAGE_MAINTENANCE_KEY")),
             }
             : {}),
+        ...(read(APP_CREDENTIAL_VARIABLE)
+            ? { appCredential: Redacted.make(read(APP_CREDENTIAL_VARIABLE)) }
+            : {}),
         ...(neonAuth === undefined ? {} : { neonAuth }),
         ...(localConnections === undefined ? {} : { localConnections }),
     };