@segmentstream-cloud/ontology 0.12.0 → 0.13.0

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 }),
     };

package/dist/service/errors.d.ts

@@ -30,6 +30,38 @@ declare const SignInCheckLimited_base: Schema.Class<SignInCheckLimited, Schema.T
 /** A client asked `POST /api/ontology/sign-in/check` too often; it may ask again after this. */
 export declare class SignInCheckLimited extends SignInCheckLimited_base {
 }
+declare const InvalidAggregateQuery_base: Schema.Class<InvalidAggregateQuery, Schema.TaggedStruct<"InvalidAggregateQuery", {
+    readonly reason: Schema.String;
+}>, Cause.YieldableError>;
+/** An aggregate request the ontology cannot answer; the reason is written for the caller. */
+export declare class InvalidAggregateQuery extends InvalidAggregateQuery_base {
+}
+declare const ReadDenied_base: Schema.Class<ReadDenied, Schema.TaggedStruct<"ReadDenied", {
+    readonly permissions: Schema.$Array<Schema.String>;
+}>, Cause.YieldableError>;
+/** The caller lacks `<entity>:read` on entities an aggregate reads: every such permission. */
+export declare class ReadDenied extends ReadDenied_base {
+}
+declare const AggregateUnavailable_base: Schema.Class<AggregateUnavailable, Schema.TaggedStruct<"AggregateUnavailable", {}>, Cause.YieldableError>;
+/** The deployment has no workspace app credential: previews and local development. */
+export declare class AggregateUnavailable extends AggregateUnavailable_base {
+}
+declare const AggregateLimited_base: Schema.Class<AggregateLimited, Schema.TaggedStruct<"AggregateLimited", {
+    readonly retryAfterSeconds: Schema.Number;
+}>, Cause.YieldableError>;
+/** A principal ran more aggregates than its window allows; it may run more after this. */
+export declare class AggregateLimited extends AggregateLimited_base {
+}
+declare const AggregateUpstreamUnavailable_base: Schema.Class<AggregateUpstreamUnavailable, Schema.TaggedStruct<"AggregateUpstreamUnavailable", {
+    readonly reason: Schema.Literals<readonly ["unreachable", "timeout", "invalid_response", "credential_rejected", "upstream_misconfigured"]>;
+    readonly status: Schema.optionalKey<Schema.Number>;
+}>, Cause.YieldableError>;
+/**
+ * SegmentStream did not answer an aggregate usably, or its answer faults the deployment rather than
+ * the caller. The operator log keeps the details; the caller learns only the reason.
+ */
+export declare class AggregateUpstreamUnavailable extends AggregateUpstreamUnavailable_base {
+}
 export interface ErrorBody {
     readonly error: string;
     readonly detail: string;

package/dist/service/errors.js

@@ -20,6 +20,50 @@ export class InvalidRequestBody extends Schema.TaggedError()("InvalidRequestBody
 /** A client asked `POST /api/ontology/sign-in/check` too often; it may ask again after this. */
 export class SignInCheckLimited extends Schema.TaggedError()("SignInCheckLimited", { retryAfterSeconds: Schema.Number }) {
 }
+/** An aggregate request the ontology cannot answer; the reason is written for the caller. */
+export class InvalidAggregateQuery extends Schema.TaggedError()("InvalidAggregateQuery", { reason: Schema.String }) {
+}
+/** The caller lacks `<entity>:read` on entities an aggregate reads: every such permission. */
+export class ReadDenied extends Schema.TaggedError()("ReadDenied", {
+    permissions: Schema.Array(Schema.String),
+}) {
+}
+/** The deployment has no workspace app credential: previews and local development. */
+export class AggregateUnavailable extends Schema.TaggedError()("AggregateUnavailable", {}) {
+}
+/** A principal ran more aggregates than its window allows; it may run more after this. */
+export class AggregateLimited extends Schema.TaggedError()("AggregateLimited", {
+    retryAfterSeconds: Schema.Number,
+}) {
+}
+/**
+ * SegmentStream did not answer an aggregate usably, or its answer faults the deployment rather than
+ * the caller. The operator log keeps the details; the caller learns only the reason.
+ */
+export class AggregateUpstreamUnavailable extends Schema.TaggedError()("AggregateUpstreamUnavailable", {
+    reason: Schema.Literals([
+        "unreachable",
+        "timeout",
+        "invalid_response",
+        "credential_rejected",
+        "upstream_misconfigured",
+    ]),
+    status: Schema.optionalKey(Schema.Number),
+}) {
+}
+const UPSTREAM_DETAILS = {
+    unreachable: "SegmentStream could not be reached. Try again shortly.",
+    timeout: "SegmentStream did not answer in time. Try again shortly.",
+    invalid_response: "SegmentStream answered with an unexpected response.",
+    credential_rejected: "SegmentStream refused the deployment's credential.",
+    upstream_misconfigured: "SegmentStream does not serve aggregates for this deployment.",
+};
+/** `a`, `a and b`, `a, b and c`. */
+function listed(values) {
+    return values.length <= 1
+        ? values.join("")
+        : `${values.slice(0, -1).join(", ")} and ${values.at(-1)}`;
+}
 export function toServerResponse(response) {
     return HttpServerResponse.jsonUnsafe(errorBodyForWire(response.body), {
         status: response.status,
@@ -279,6 +323,64 @@ export function expectedFailure(error, requestId) {
             },
         };
     }
+    if (Predicate.isTagged(error, "ReadDenied")) {
+        const { permissions } = error;
+        return {
+            status: 403,
+            body: {
+                error: "forbidden",
+                detail: `${listed(permissions)} ${permissions.length === 1 ? "is" : "are"} required.`,
+                requestId,
+                permissions,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "AggregateLimited")) {
+        const { retryAfterSeconds } = error;
+        return {
+            status: 429,
+            body: {
+                error: "rate_limited",
+                detail: `Too many aggregates. Wait ${retryAfterSeconds} seconds, then try again.`,
+                requestId,
+                retryable: true,
+            },
+            headers: { "retry-after": String(retryAfterSeconds) },
+        };
+    }
+    if (Predicate.isTagged(error, "InvalidAggregateQuery")) {
+        return {
+            status: 400,
+            body: {
+                error: "invalid_aggregate_query",
+                detail: error.reason,
+                requestId,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "AggregateUnavailable")) {
+        return {
+            status: 503,
+            body: {
+                error: "aggregate_unavailable",
+                detail: "Aggregates are available in production deployments.",
+                requestId,
+                retryable: false,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "AggregateUpstreamUnavailable")) {
+        const { reason } = error;
+        return {
+            status: 502,
+            body: {
+                error: "aggregate_upstream_unavailable",
+                detail: UPSTREAM_DETAILS[reason],
+                requestId,
+                retryable: reason === "unreachable" || reason === "timeout",
+            },
+        };
+    }
     if (Predicate.isTagged(error, "ConnectionError")) {
         return connectionFailure(error, requestId);
     }

package/dist/service/handlers.d.ts

@@ -1,5 +1,6 @@
 import { Layer } from "effect";
 import { type HttpApiGroup } from "effect/unstable/httpapi";
+import type { Aggregates } from "./aggregate.js";
 import { type BuiltApi } from "./api.js";
 import type { AfterCommitHook } from "./config.js";
 import type { ReplicationKick } from "./replication.js";
@@ -12,4 +13,4 @@ import { OntologyBackend } from "./runtime-contract.js";
  */
 export declare const SIGN_IN_CHECK_LIMIT: RateLimit;
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
-export declare function handlersLayer(built: BuiltApi, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick): Layer.Layer<HttpApiGroup.Service<"ontology", string>, never, OntologyBackend>;
+export declare function handlersLayer(built: BuiltApi, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick, aggregates: Aggregates): Layer.Layer<HttpApiGroup.Service<"ontology", string>, never, OntologyBackend>;