@segmentstream-cloud/ontology 0.11.0 → 0.13.0

package/dist/service/mcp/tools.js

@@ -1,11 +1,14 @@
 import { Schema } from "effect";
+import { AGGREGATE_NAME_PATTERN } from "../../aggregate-routes.js";
 import { InvalidOntology } from "../../diagnostics.js";
+import { isValueMatched } from "../../manifest.js";
 import { GENERATED_UPSERT_PREFIX, humanize, mcpToolName } from "../../names.js";
 import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
 import { queryJsonSchema } from "../../query.js";
+import { measuresFor, RECORDS_OR_AGGREGATES } from "../../render.js";
 import { actionInputJsonSchema } from "../../runtime/generated-actions.js";
 import { actionDescription, requires } from "../descriptions.js";
-import { HistoryPage, Me } from "../schemas.js";
+import { AGGREGATE_FILTER_OPERATORS, AGGREGATE_GRANULARITIES, AGGREGATE_LIMITS, HistoryPage, Me, } from "../schemas.js";
 const DEFS = "#/$defs/";
 /**
  * A JSON Schema whose root is an object schema, as MCP requires of tool inputs and outputs: a root
@@ -94,12 +97,30 @@ function relatedHint(planned, traversal) {
                 `{"${traversal.opposite}": {"some": {"id": {"eq": "${id}"}}}}.`);
     }
 }
+/**
+ * How an agent reads the target of a value-matched relationship, which the service cannot traverse:
+ * the reference is an ordinary property, and the target lives in the warehouse.
+ */
+function matchedHints(planned) {
+    return planned.resolved.relationships.flatMap(({ name, relationship, target }) => {
+        if (relationship.cardinality !== "one" || !isValueMatched(relationship)) {
+            return [];
+        }
+        const property = Object.keys(relationship.on ?? {})[0] ?? "";
+        return [
+            `${name} is matched on ${property}; read ${target ?? "it"} through the workspace aggregates.`,
+        ];
+    });
+}
 function readTools(planned, schemas, built) {
     const { manifest } = built.plan.ontology;
     const { definition } = planned.resolved.entity;
     const label = definition.label.toLowerCase();
     const read = permissionOf(planned.name, READ_VERB);
-    const related = planned.traversals.map((traversal) => `- ${relatedHint(planned, traversal)}`);
+    const related = [
+        ...planned.traversals.map((traversal) => relatedHint(planned, traversal)),
+        ...matchedHints(planned),
+    ].map((hint) => `- ${hint}`);
     return [
         {
             name: mcpToolName(planned.name, "find"),
@@ -181,14 +202,140 @@ const GLOBAL_TOOLS = [
         target: { kind: "me" },
     },
 ];
+const AGGREGATE_NAME = {
+    type: "string",
+    pattern: AGGREGATE_NAME_PATTERN,
+    description: "<entity>.<property>, or a route from a measure's entity when it reaches the property's " +
+        "entity in several ways: <entity>.<relationship>.<property>, at most two relationships.",
+};
+const AGGREGATE_VALUE = {
+    anyOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }],
+};
+/** One `anyOf` branch per measure: a JSON Schema `enum` cannot describe its values. */
+function measureChoice({ name, entity, measure }) {
+    return {
+        const: name,
+        description: `${entity.label} · ${measure.label} (${measure.unit}): ${measure.description}`,
+    };
+}
+/** The aggregate tool's input for a caller: the request of `POST /api/ontology/aggregate`. */
+function aggregateInput(measures) {
+    return {
+        type: "object",
+        properties: {
+            measures: {
+                type: "array",
+                minItems: 1,
+                maxItems: AGGREGATE_LIMITS.measures,
+                uniqueItems: true,
+                items: { anyOf: measures.map(measureChoice) },
+                description: "What to compute, as <entity>.<measure>. Measures of several entities are each " +
+                    "computed over their own entity's rows, then combined on the dimensions.",
+            },
+            dimensions: {
+                type: "array",
+                maxItems: AGGREGATE_LIMITS.dimensions,
+                uniqueItems: true,
+                items: AGGREGATE_NAME,
+                description: "What to group by. Every dimension must be reachable from every measure's entity.",
+            },
+            filters: {
+                type: "array",
+                maxItems: AGGREGATE_LIMITS.filters,
+                description: "All must hold. A filter applies to each measure's entity that reaches it; the answer " +
+                    "warns about the others.",
+                items: {
+                    type: "object",
+                    properties: {
+                        dimension: AGGREGATE_NAME,
+                        operator: { enum: [...AGGREGATE_FILTER_OPERATORS] },
+                        value: { ...AGGREGATE_VALUE, description: "The value of equals." },
+                        values: {
+                            type: "array",
+                            minItems: 1,
+                            maxItems: AGGREGATE_LIMITS.values,
+                            items: AGGREGATE_VALUE,
+                            description: "The values of in, or the two inclusive bounds of between, for example " +
+                                '["2026-09-01", "2026-09-30"].',
+                        },
+                    },
+                    required: ["dimension", "operator"],
+                    additionalProperties: false,
+                },
+            },
+            granularity: {
+                enum: [...AGGREGATE_GRANULARITIES],
+                description: "Buckets the date or timestamp dimension granularityOf names.",
+            },
+            granularityOf: { ...AGGREGATE_NAME, description: "A requested date or timestamp dimension." },
+            orderBy: {
+                type: "array",
+                maxItems: AGGREGATE_LIMITS.orderBy,
+                items: {
+                    type: "object",
+                    properties: {
+                        measure: { type: "string", description: "A requested measure." },
+                        dimension: { type: "string", description: "A requested dimension." },
+                        direction: { enum: ["asc", "desc"] },
+                    },
+                    required: ["direction"],
+                    additionalProperties: false,
+                },
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: AGGREGATE_LIMITS.rows,
+                description: "At most 1000 rows; 100 by default.",
+            },
+        },
+        required: ["measures"],
+        additionalProperties: false,
+    };
+}
+const AGGREGATE_DESCRIPTION = "Numbers about the model: measures from one or several entities, grouped and filtered by " +
+    `properties of related entities. The rule: ${RECORDS_OR_AGGREGATES}.\n\n` +
+    "Examples, with entities sales, stock and product:\n" +
+    '- September revenue by brand: {"measures": ["sales.revenue"], "dimensions": ["product.brand"], ' +
+    '"filters": [{"dimension": "sales.order_date", "operator": "between", ' +
+    '"values": ["2026-09-01", "2026-09-30"]}]}\n' +
+    '- September units sold beside units in stock, by status: {"measures": ["sales.units", ' +
+    '"stock.on_hand"], "dimensions": ["product.status"], "filters": [{"dimension": ' +
+    '"sales.order_date", "operator": "between", "values": ["2026-09-01", "2026-09-30"]}]}\n\n' +
+    "Partitioned warehouse entities require a between filter on their date property; the error " +
+    "names it. Currency measures need a single-currency filter. " +
+    "Answers come from the warehouse, and stored records from its replica: execution.sources says " +
+    "how fresh each is, and execution.warnings says when a filter did not apply to a measure. " +
+    "Requires reading every entity the request reads, path intermediates included. Call describe " +
+    "for the model's measures and relationships.";
+function aggregateTool(manifest) {
+    return {
+        name: "aggregate",
+        title: "Aggregate measures",
+        description: AGGREGATE_DESCRIPTION,
+        inputSchema: aggregateInput(measuresFor(manifest)),
+        inputSchemaFor: (caller) => {
+            const measures = measuresFor(manifest, caller.permissions);
+            return measures.length === 0 ? undefined : aggregateInput(measures);
+        },
+        annotations: READ,
+        permissions: [],
+        target: { kind: "aggregate" },
+    };
+}
 /**
- * The MCP tools of an ontology: `describe` and `me`, then for every stored entity `find`, `get`,
+ * The MCP tools of an ontology: `describe` and `me`, `aggregate` when the ontology has measures,
+ * then for every stored entity `find`, `get`,
  * `history` and a tool per generated and authored action. Entities with a warehouse source have none,
  * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
  * `check` already refuses.
  */
 export function mcpTools(built) {
-    const tools = [...GLOBAL_TOOLS];
+    const { manifest } = built.plan.ontology;
+    const tools = [
+        ...GLOBAL_TOOLS,
+        ...(measuresFor(manifest).length > 0 ? [aggregateTool(manifest)] : []),
+    ];
     for (const planned of built.plan.entities) {
         if (planned.resolved.entity.definition.source !== undefined) {
             continue;
@@ -212,7 +359,19 @@ export function mcpTools(built) {
     }
     return tools;
 }
-/** The tools a caller may see: those whose every permission the caller's roles grant. */
+/**
+ * The tools a caller may see: those whose every permission the caller's roles grant, each with the
+ * caller's input schema.
+ */
 export function visibleTools(tools, caller) {
-    return tools.filter((tool) => tool.permissions.every((required) => isAllowed(required, caller)));
+    return tools.flatMap((tool) => {
+        if (!tool.permissions.every((required) => isAllowed(required, caller))) {
+            return [];
+        }
+        if (tool.inputSchemaFor === undefined) {
+            return [tool];
+        }
+        const inputSchema = tool.inputSchemaFor(caller);
+        return inputSchema === undefined ? [] : [{ ...tool, inputSchema }];
+    });
 }

package/dist/service/operations.d.ts

@@ -4,6 +4,7 @@ import { PermissionDenied } from "../errors.js";
 import type { Query, QueryResult } from "../query.js";
 import { CurrentPrincipal } from "./authentication.js";
 import type { AfterCommitHook } from "./config.js";
+import type { ReplicationKick } from "./replication.js";
 import { type ConnectionTransportFactory } from "./connections.js";
 import { InvalidActionInput, RequestId } from "./errors.js";
 import type { ApiPlan, PlannedAction, PlannedEntity, Traversal } from "./plan.js";
@@ -59,7 +60,7 @@ export interface Caller {
 }
 type Backend = OntologyBackend["Service"];
 /** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
-export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory): {
+export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick): {
     /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
     find: (planned: PlannedEntity, query: Query) => Effect.Effect<QueryResult<Readonly<Record<string, unknown>>>, PermissionDenied | import("../index.js").InvalidQuery, CurrentPrincipal>;
     /** One record. Requires `read` on the entity. */

package/dist/service/operations.js

@@ -145,7 +145,7 @@ function traverseOf(backend, targets, planned, traversal, id, query) {
         return page(yield* backend.find({ entity: traversal.target, query: { ...query, where } }));
     });
 }
-function runActionOf(backend, ontology, hooks, connections) {
+function runActionOf(backend, ontology, hooks, connections, replicate) {
     return (planned, { name, generated }, call) => Effect.gen(function* () {
         const principal = yield* CurrentPrincipal;
         const requestId = yield* RequestId;
@@ -161,9 +161,19 @@ function runActionOf(backend, ontology, hooks, connections) {
                 identityToken: call.identityToken,
                 audit: { action: `${planned.name}.${name}`, principalId: principal.id, requestId },
             }),
-            ...(hook === undefined
-                ? {}
-                : { afterCommit: afterCommitOf(hook, { requestId, generated }, ontology) }),
+            ...(hook || backend.replicationEnabled
+                ? {
+                    afterCommit: (committed) => Effect.gen(function* () {
+                        if (hook) {
+                            yield* afterCommitOf(hook, { requestId, generated }, ontology)(committed);
+                        }
+                        if (committed.edits.length > 0 &&
+                            (yield* backend.replicationEnabled ?? Effect.succeed(false))) {
+                            yield* replicate(call.identityToken);
+                        }
+                    }).pipe(Effect.catchCause((cause) => Effect.logWarning("ontology.replication.deferred", cause))),
+                }
+                : {}),
         });
         const { issues } = outcome.validation;
         if (!outcome.validation.ok && !call.validateOnly) {
@@ -199,7 +209,7 @@ function callerOf(backend) {
     });
 }
 /** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
-export function makeOperations(backend, plan, hooks, connections) {
+export function makeOperations(backend, plan, hooks, connections, replicate) {
     const targets = relationshipTargets(plan);
     return {
         /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
@@ -211,7 +221,7 @@ export function makeOperations(backend, plan, hooks, connections) {
         /** The records a relationship reaches from one record, as a page of the target entity. */
         traverse: (planned, traversal, id, query) => traverseOf(backend, targets, planned, traversal, id, query),
         /** Runs an action as the caller, with the action's after-commit hook and connections. */
-        runAction: runActionOf(backend, plan.ontology, hooks, connections),
+        runAction: runActionOf(backend, plan.ontology, hooks, connections, replicate),
         /** The caller's user, roles and permissions. It needs no permission. */
         caller: callerOf(backend),
     };

package/dist/service/plan.js

@@ -63,13 +63,19 @@ export function planApi(ontology, generatedActions) {
     const report = (path, message) => {
         diagnostics.push({ severity: "error", code: "reserved-name", path, message });
     };
+    // The service cannot read warehouse records, so a relationship to one has no route.
+    const warehouseBacked = new Set(ontology.entities
+        .filter((candidate) => candidate.entity.definition.source !== undefined)
+        .map((candidate) => candidate.name));
     const entities = ontology.entities.map((resolved) => ({
         name: resolved.name,
         resolved,
         traversals: resolved.entity.definition.source !== undefined
             ? []
             : [
-                ...resolved.relationships.map(declaredTraversal),
+                ...resolved.relationships
+                    .filter(({ target }) => target === undefined || !warehouseBacked.has(target))
+                    .map(declaredTraversal),
                 ...inverseTraversals(resolved.name, ontology.entities),
             ],
         actions: plannedActions(resolved, (entity) => generatedActions(entity, ontology), report),

package/dist/service/replication.d.ts

@@ -0,0 +1,5 @@
+import { Effect } from "effect";
+import type { OntologyEnvironment } from "./config.js";
+export type ReplicationKick = (identity: string | undefined) => Effect.Effect<void>;
+/** A fast path only. The committed history, not this request, makes delivery durable. */
+export declare function deployedReplication(environment: OntologyEnvironment, fetchImpl?: typeof fetch): ReplicationKick;

package/dist/service/replication.js

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+/** A fast path only. The committed history, not this request, makes delivery durable. */
+export function deployedReplication(environment, fetchImpl = fetch) {
+    return (identity) => {
+        if (!identity) {
+            return Effect.void;
+        }
+        return Effect.tryPromise(async () => {
+            const response = await fetchImpl(`${environment.segmentstreamUrl}/api/internal/v1/workspaces/` +
+                `${encodeURIComponent(environment.workspaceId)}/ontology/replication/drain`, {
+                method: "POST",
+                redirect: "error",
+                signal: AbortSignal.timeout(5000),
+                headers: {
+                    "x-segmentstream-runtime-identity": identity,
+                    "x-segmentstream-organization-id": environment.organizationId,
+                },
+            });
+            await response.body?.cancel();
+            if (!response.ok) {
+                throw new Error(`Replication wake-up returned HTTP ${response.status}.`);
+            }
+        }).pipe(Effect.catchCause((cause) => Effect.logWarning("ontology.replication.deferred", cause)));
+    };
+}

package/dist/service/runtime-contract.d.ts

@@ -189,6 +189,7 @@ declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segm
     readonly resolveApiKey: (key: Redacted.Redacted<string>) => Effect.Effect<Principal | undefined>;
     /** The manifest hash recorded in the `_ontology` catalog table, or `undefined` before the first. */
     readonly appliedHash: Effect.Effect<string | undefined>;
+    readonly replicationEnabled?: Effect.Effect<boolean>;
     /** The OAuth tables, for members who connect agents; without it, agents use API keys. */
     readonly oauth?: OAuthStore;
 }>;

package/dist/service/schemas.d.ts

@@ -4,7 +4,7 @@ import type { ApiPlan } from "./plan.js";
 export declare const IdParam: Schema.String;
 /** The schemas of one entity's records and queries. */
 export interface EntitySchemas {
-    /** System fields, properties and `<relationship>_id` per `rel.one`. */
+    /** System fields, properties and `<relationship>_id` per stored `rel.one`. */
     readonly record: Schema.Top;
     /** A record with the relationships a query may include. */
     readonly result: Schema.Top;
@@ -392,6 +392,13 @@ export declare const Graph: Schema.Struct<{
         readonly to: Schema.String;
         readonly inverse: Schema.String;
         readonly cardinality: Schema.Literals<readonly ["one", "many"]>;
+        /** The property pair of a relationship matched by value: one with a warehouse-backed end. */
+        readonly on: Schema.optionalKey<Schema.encodeKeys<Schema.Struct<{
+            readonly property: Schema.String;
+            readonly targetProperty: Schema.String;
+        }>, {
+            readonly targetProperty: "target_property";
+        }>>;
         readonly optional: Schema.Boolean;
         readonly phrase: Schema.Tuple<readonly [Schema.String, Schema.String]>;
         readonly forward: Schema.String;
@@ -414,6 +421,92 @@ export declare const SIGN_IN_CHECK_MAX_EMAIL_LENGTH = 320;
 export declare const SignInCheckRequest: Schema.Struct<{
     readonly email: Schema.String;
 }>;
+/** The bounds of a model-level aggregate (docs/ontology-aggregates-spec.md, "Request"). */
+export declare const AGGREGATE_LIMITS: {
+    readonly measures: 30;
+    readonly dimensions: 20;
+    readonly filters: 50;
+    readonly values: 100;
+    readonly orderBy: 50;
+    readonly rows: 1000;
+};
+export declare const AGGREGATE_FILTER_OPERATORS: readonly ["equals", "in", "isNull", "isNotNull", "between"];
+/** The operators of the per-entity shorthand, which bounds dates with `dateRange` instead. */
+export declare const ENTITY_AGGREGATE_FILTER_OPERATORS: readonly ["equals", "in", "isNull", "isNotNull"];
+export declare const AGGREGATE_GRANULARITIES: readonly ["day", "week", "month"];
+type AggregateValue = string | number | boolean;
+interface AggregateFilter<Operator extends string> {
+    readonly dimension: string;
+    readonly operator: Operator;
+    readonly value?: AggregateValue;
+    readonly values?: ReadonlyArray<AggregateValue>;
+}
+declare const AggregateValue: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean]>;
+interface AggregateOrdering {
+    readonly measure?: string;
+    readonly dimension?: string;
+    readonly direction: "asc" | "desc";
+}
+/**
+ * `POST /api/ontology/aggregate`. The service checks the shape and the bounds, resolves the names
+ * against its manifest and forwards the body unchanged; SegmentStream checks everything else.
+ */
+export declare const AggregateRequest: Schema.Codec<AggregateRequest>;
+export interface AggregateRequest {
+    readonly measures: ReadonlyArray<string>;
+    readonly dimensions?: ReadonlyArray<string>;
+    readonly filters?: ReadonlyArray<AggregateFilter<(typeof AGGREGATE_FILTER_OPERATORS)[number]>>;
+    readonly granularity?: (typeof AGGREGATE_GRANULARITIES)[number];
+    readonly granularityOf?: string;
+    readonly orderBy?: ReadonlyArray<AggregateOrdering>;
+    readonly limit?: number;
+}
+/**
+ * `POST /api/ontology/<entity>/aggregate`: SegmentStream's per-entity request, unchanged. Names are
+ * relative to the entity (`revenue`, `product.brand`), and `dateRange` bounds a partitioned entity.
+ */
+export declare const EntityAggregateRequest: Schema.Codec<EntityAggregateRequest>;
+export interface EntityAggregateRequest {
+    readonly dimensions: ReadonlyArray<string>;
+    readonly measures: ReadonlyArray<string>;
+    readonly dateRange?: {
+        readonly from: string;
+        readonly to: string;
+    };
+    readonly filters?: ReadonlyArray<AggregateFilter<(typeof ENTITY_AGGREGATE_FILTER_OPERATORS)[number]>>;
+    readonly granularity?: (typeof AGGREGATE_GRANULARITIES)[number];
+    readonly granularityOf?: string;
+    readonly orderBy?: ReadonlyArray<AggregateOrdering>;
+    readonly limit?: number;
+}
+/** SegmentStream's answer to an aggregate, which the service forwards unchanged. */
+export declare const AggregateResult: Schema.Struct<{
+    readonly fields: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly label: Schema.String;
+        readonly type: Schema.String;
+        readonly unit: Schema.optionalKey<Schema.String>;
+        readonly format: Schema.optionalKey<Schema.String>;
+        readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly implicit: Schema.optionalKey<Schema.Boolean>;
+        readonly additive: Schema.optionalKey<Schema.Boolean>;
+        readonly filters: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
+    readonly rows: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Boolean]>>>>;
+    readonly truncated: Schema.Boolean;
+    readonly execution: Schema.Struct<{
+        readonly elapsedMs: Schema.Number;
+        readonly bytesProcessed: Schema.optionalKey<Schema.String>;
+        readonly bytesBilled: Schema.optionalKey<Schema.String>;
+        readonly warnings: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly sources: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly entity: Schema.String;
+            readonly asOf: Schema.String;
+        }>>>;
+    }>;
+    readonly deploymentId: Schema.NullOr<Schema.String>;
+    readonly definitionDigest: Schema.String;
+}>;
 /** Whether the address may sign in, and with a code or a link. */
 export declare const SignInCheckResult: Schema.Union<readonly [Schema.Struct<{
     readonly allowed: Schema.Literal<false>;
@@ -448,7 +541,12 @@ export declare const ErrorSchemas: {
     rateLimited: Schema.Top;
     internal: Schema.Top;
     unavailable: Schema.Top;
+    invalidAggregateQuery: Schema.Top;
+    readForbidden: Schema.Top;
+    aggregateUnavailable: Schema.Top;
+    aggregateUpstreamUnavailable: Schema.Top;
     connectionRequired: Schema.Top;
     connectionResponseInvalid: Schema.Top;
     connectionUnavailable: Schema.Top;
 };
+export {};

package/dist/service/schemas.js

@@ -1,7 +1,7 @@
 import { BlobValue } from "../blob.js";
 import { Schema, SchemaTransformation } from "effect";
 import { wireStruct } from "../wire.js";
-import { OntologyManifestWire } from "../manifest.js";
+import { isValueMatched, OntologyManifestWire } from "../manifest.js";
 import { entityQuerySchemas, queryLinks } from "../query.js";
 import { ValidationIssue as RuntimeValidationIssue } from "../runtime/errors.js";
 import { Edit, HistoryEntry as RuntimeHistoryEntry } from "../runtime/history.js";
@@ -96,7 +96,8 @@ function recordFields(entity) {
         fields[name] = definition.optional ? Schema.NullOr(value) : value;
     }
     for (const { name, relationship } of entity.relationships) {
-        if (relationship.cardinality === "one") {
+        // A value-matched relationship's reference is the property its `on` names.
+        if (relationship.cardinality === "one" && !isValueMatched(relationship)) {
             const key = Id.annotate({ description: relationship.description });
             fields[`${name}_id`] = relationship.optional ? Schema.NullOr(key) : key;
         }
@@ -276,6 +277,8 @@ const GraphRelationship = Schema.Struct({
     to: Schema.String,
     inverse: Schema.String,
     cardinality: Schema.Literals(["one", "many"]),
+    /** The property pair of a relationship matched by value: one with a warehouse-backed end. */
+    on: Schema.optionalKey(Schema.Struct({ property: Schema.String, targetProperty: Schema.String }).pipe(Schema.encodeKeys({ targetProperty: "target_property" }))),
     optional: Schema.Boolean,
     phrase: Schema.Tuple([Schema.String, Schema.String]),
     forward: Schema.String.annotate({ examples: ["Lead is owned by one User"] }),
@@ -304,6 +307,143 @@ export const SignInCheckRequest = Schema.Struct({
         description: "The address the person typed, in any case.",
     }),
 }).annotate({ identifier: "SignInCheckRequest" });
+/** The bounds of a model-level aggregate (docs/ontology-aggregates-spec.md, "Request"). */
+export const AGGREGATE_LIMITS = {
+    measures: 30,
+    dimensions: 20,
+    filters: 50,
+    values: 100,
+    orderBy: 50,
+    rows: 1000,
+};
+export const AGGREGATE_FILTER_OPERATORS = [
+    "equals",
+    "in",
+    "isNull",
+    "isNotNull",
+    "between",
+];
+/** The operators of the per-entity shorthand, which bounds dates with `dateRange` instead. */
+export const ENTITY_AGGREGATE_FILTER_OPERATORS = ["equals", "in", "isNull", "isNotNull"];
+export const AGGREGATE_GRANULARITIES = ["day", "week", "month"];
+const AggregateValue = Schema.Union([Schema.String, Schema.Number, Schema.Boolean]);
+/** Which values each operator takes, with SegmentStream's own messages (`planner.ts`). */
+function filterValuesIssue(filter) {
+    const { operator, value, values } = filter;
+    switch (operator) {
+        case "equals":
+            return value === undefined || values !== undefined
+                ? "Equality filters require one value."
+                : undefined;
+        case "in":
+            return values === undefined ||
+                values.length === 0 ||
+                values.length > AGGREGATE_LIMITS.values ||
+                value !== undefined
+                ? "Membership filters require between 1 and 100 values."
+                : undefined;
+        case "between":
+            return value !== undefined || values?.length !== 2
+                ? "between needs two values in order."
+                : undefined;
+        default:
+            return value !== undefined || values !== undefined
+                ? "Null filters do not accept values."
+                : undefined;
+    }
+}
+function aggregateFilter(operators) {
+    const filter = closedStruct({
+        dimension: Schema.String.annotate({
+            description: "A property, or a path of to-one relationships ending in one.",
+        }),
+        operator: Schema.Literals(operators),
+        value: Schema.optionalKey(AggregateValue).annotate({ description: "The value of equals." }),
+        values: Schema.optionalKey(Schema.Array(AggregateValue).check(Schema.isMaxLength(AGGREGATE_LIMITS.values))).annotate({ description: "The values of in, or the two inclusive bounds of between." }),
+    }, "Unknown key; use dimension, operator, value and values");
+    return filter.check(Schema.makeFilter((candidate) => filterValuesIssue(candidate) ?? true));
+}
+const AggregateOrder = closedStruct({
+    measure: Schema.optionalKey(Schema.String),
+    dimension: Schema.optionalKey(Schema.String),
+    direction: Schema.Literals(["asc", "desc"]),
+}, "Unknown key; use measure or dimension, and direction");
+/** The fields both aggregate requests share, with their bounds. */
+const aggregateFields = {
+    granularity: Schema.optionalKey(Schema.Literals(AGGREGATE_GRANULARITIES)),
+    granularityOf: Schema.optionalKey(Schema.String).annotate({
+        description: "The requested date or timestamp dimension that granularity buckets.",
+    }),
+    orderBy: Schema.optionalKey(Schema.Array(AggregateOrder).check(Schema.isMaxLength(AGGREGATE_LIMITS.orderBy))),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: AGGREGATE_LIMITS.rows }))).annotate({ description: "At most 1000 rows; 100 by default." }),
+};
+/**
+ * `POST /api/ontology/aggregate`. The service checks the shape and the bounds, resolves the names
+ * against its manifest and forwards the body unchanged; SegmentStream checks everything else.
+ */
+export const AggregateRequest = closedStruct({
+    measures: Schema.Array(Schema.String)
+        .check(Schema.isMaxLength(AGGREGATE_LIMITS.measures))
+        .annotate({ description: "<entity>.<measure>, at least one." }),
+    dimensions: Schema.optionalKey(Schema.Array(Schema.String).check(Schema.isMaxLength(AGGREGATE_LIMITS.dimensions))).annotate({
+        description: "<entity>.<property>, or a route from a measure's entity: " +
+            "<entity>.<relationship>[.<relationship>].<property>.",
+    }),
+    filters: Schema.optionalKey(Schema.Array(aggregateFilter(AGGREGATE_FILTER_OPERATORS)).check(Schema.isMaxLength(AGGREGATE_LIMITS.filters))).annotate({ description: "All must hold." }),
+    ...aggregateFields,
+}, "Unknown key; use measures, dimensions, filters, granularity, granularityOf, orderBy and limit").annotate({ identifier: "AggregateRequest" });
+/**
+ * `POST /api/ontology/<entity>/aggregate`: SegmentStream's per-entity request, unchanged. Names are
+ * relative to the entity (`revenue`, `product.brand`), and `dateRange` bounds a partitioned entity.
+ */
+export const EntityAggregateRequest = closedStruct({
+    dimensions: Schema.Array(Schema.String)
+        .check(Schema.isMaxLength(AGGREGATE_LIMITS.dimensions))
+        .annotate({
+        description: "A property, or a path of to-one relationships: product.brand.",
+    }),
+    measures: Schema.Array(Schema.String)
+        .check(Schema.isMaxLength(AGGREGATE_LIMITS.measures))
+        .annotate({ description: "The entity's measures, at least one." }),
+    dateRange: Schema.optionalKey(closedStruct({
+        from: Schema.String.annotate({ format: "date" }),
+        to: Schema.String.annotate({ format: "date" }),
+    }, "Unknown key; use from and to")).annotate({ description: "Inclusive days of the entity's partition property." }),
+    filters: Schema.optionalKey(Schema.Array(aggregateFilter(ENTITY_AGGREGATE_FILTER_OPERATORS)).check(Schema.isMaxLength(AGGREGATE_LIMITS.filters))).annotate({ description: "All must hold." }),
+    ...aggregateFields,
+}, "Unknown key; use dimensions, measures, dateRange, filters, granularity, granularityOf, " +
+    "orderBy and limit").annotate({ identifier: "EntityAggregateRequest" });
+/** SegmentStream's answer to an aggregate, which the service forwards unchanged. */
+export const AggregateResult = Schema.Struct({
+    fields: Schema.Array(Schema.Struct({
+        name: Schema.String.annotate({ description: "A dimension identity or <entity>.<measure>." }),
+        label: Schema.String,
+        type: Schema.String,
+        unit: Schema.optionalKey(Schema.String),
+        format: Schema.optionalKey(Schema.String),
+        scope: Schema.optionalKey(Schema.Array(Schema.String)),
+        implicit: Schema.optionalKey(Schema.Boolean),
+        additive: Schema.optionalKey(Schema.Boolean).annotate({
+            description: "false when the measure's rows do not add up to a total.",
+        }),
+        filters: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+            description: "The filters the measure applied.",
+        }),
+    })),
+    rows: Schema.Array(Schema.Record(Schema.String, Schema.NullOr(Schema.Union([Schema.String, Schema.Boolean])))),
+    truncated: Schema.Boolean,
+    execution: Schema.Struct({
+        elapsedMs: Schema.Number,
+        bytesProcessed: Schema.optionalKey(Schema.String),
+        bytesBilled: Schema.optionalKey(Schema.String),
+        warnings: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+            description: "For example, a filter that did not apply to some measure's entity.",
+        }),
+        sources: Schema.optionalKey(Schema.Array(Schema.Struct({ entity: Schema.String, asOf: Schema.String }))).annotate({ description: "How fresh the replica of each stored entity read is." }),
+    }),
+    deploymentId: Schema.NullOr(Schema.String),
+    definitionDigest: Schema.String,
+}).annotate({ identifier: "AggregateResult" });
 /** Whether the address may sign in, and with a code or a link. */
 export const SignInCheckResult = Schema.Union([
     Schema.Struct({ allowed: Schema.Literal(false) }),
@@ -370,6 +510,14 @@ export const ErrorSchemas = {
     rateLimited: errorBody("RateLimited", 429, ["rate_limited"]),
     internal: errorBody("InternalError", 500, ["internal_error"]),
     unavailable: errorBody("ServiceUnavailable", 503, ["service_unavailable"]),
+    invalidAggregateQuery: errorBody("InvalidAggregateQuery", 400, ["invalid_aggregate_query"]),
+    readForbidden: errorBody("ReadForbidden", 403, ["forbidden"], {
+        permissions: Schema.optionalKey(Schema.Array(Schema.String)),
+    }),
+    aggregateUnavailable: errorBody("AggregateUnavailable", 503, ["aggregate_unavailable"], {
+        retryable: Schema.Boolean,
+    }),
+    aggregateUpstreamUnavailable: errorBody("AggregateUpstreamUnavailable", 502, ["aggregate_upstream_unavailable"], { retryable: Schema.Boolean }),
     connectionRequired: errorBody("ConnectionRequired", 409, ["connection_authorization_required", "connections_not_deployed"], { connection: Schema.String }),
     connectionResponseInvalid: errorBody("ConnectionResponseInvalid", 502, [
         "connection_response_invalid",