@segmentstream-cloud/ontology 0.12.0 → 0.13.0

package/dist/render.d.ts

@@ -1,8 +1,9 @@
-import type { ActionManifest, OntologyManifest } from "./manifest.js";
+import type { ActionManifest, EntityManifest, OntologyManifest } from "./manifest.js";
 export interface RenderOptions {
     /**
-     * The permissions of the reader. Only the actions these permissions may run are listed. Without
-     * it, every action is listed with the permission it requires and the roles that grant it.
+     * The permissions of the reader. Only the actions these permissions may run are listed, and only
+     * the measures and routes of entities they may read. Without it, every action is listed with the
+     * permission it requires and the roles that grant it, and every measure and route.
      */
     readonly as?: ReadonlyArray<string>;
 }
@@ -16,3 +17,46 @@ export declare function actionPermission(entity: string, action: ActionManifest)
  * the console, the CLI and the service describe the same ontology.
  */
 export declare function renderCatalog(manifest: OntologyManifest, options?: RenderOptions): string;
+/**
+ * The catalog as `describe` answers a reader: {@link renderCatalog} with the reader's permissions,
+ * or everything without them.
+ */
+export declare function describeCatalog(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): string;
+type MeasureManifest = NonNullable<EntityManifest["measures"]>[number];
+/** A measure as aggregates name it: `<entity>.<measure>`. */
+export interface NamedMeasure {
+    readonly name: string;
+    readonly entity: EntityManifest;
+    readonly measure: MeasureManifest;
+}
+/**
+ * An entity a measure entity reaches, and the shortest routes there the reader may follow:
+ * `product.region`. `ambiguous` when the resolver finds several shortest routes, readable or not,
+ * so a request must write the route.
+ */
+export interface Reach {
+    readonly target: string;
+    readonly routes: ReadonlyArray<string>;
+    readonly ambiguous: boolean;
+}
+/** The rule every surface repeats (docs/ontology-aggregates-spec.md, "Three ways to ask"). */
+export declare const RECORDS_OR_AGGREGATES = "look at or change records through find and actions; count, sum or compare through aggregate";
+/**
+ * Every measure of the entities the reader may read, warehouse-backed and stored alike, in
+ * declaration order. Without permissions, every measure.
+ */
+export declare function measuresFor(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): ReadonlyArray<NamedMeasure>;
+/**
+ * The entities one entity reaches, with the shortest routes to each: exactly the routes aggregate
+ * resolution weighs ({@link shortestRoutesFrom}). Only then is the reader applied: a target they may
+ * not read is left out, and so is any route through an entity they may not read, which the service
+ * would refuse. A target keeps `ambiguous` from before that filter, so a route is never shown as the
+ * only one when the resolver would ask for it to be written.
+ */
+export declare function reachesOf(manifest: OntologyManifest, from: string, permissions?: ReadonlyArray<string>): ReadonlyArray<Reach>;
+/**
+ * The aggregate part of the catalog's prose: every measure the reader may read, model-wide, and
+ * per measure entity the entities it reaches. Empty when the reader may read no measure.
+ */
+export declare function renderAggregates(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): string;
+export {};

package/dist/render.js

@@ -1,3 +1,4 @@
+import { shortestRoutesFrom } from "./aggregate-routes.js";
 import { isAllowed, permissionOf, READ_VERB, rolesGranting } from "./permissions.js";
 import { REFERENCE_ANNOTATION } from "./property.js";
 /** What an action of the manifest requires; version 1 manifests leave it implicit. */
@@ -24,11 +25,14 @@ function withDescription(head, description) {
 function formatValue(value) {
     return typeof value === "string" ? value : JSON.stringify(value);
 }
-function propertyLines(property) {
+/** A warehouse-backed property's `unique` is an assertion the platform does not enforce. */
+function propertyLines(input) {
+    const { property, warehouseBacked } = input;
+    const unique = warehouseBacked ? "unique, not enforced" : "unique";
     const traits = [
         property.type,
         ...(property.optional ? ["optional"] : []),
-        ...(property.unique ? ["unique"] : []),
+        ...(property.unique ? [unique] : []),
         ...(property.default !== undefined ? [`default ${formatValue(property.default)}`] : []),
         ...(property.min !== undefined ? [`min ${property.min}`] : []),
         ...(property.max !== undefined ? [`max ${property.max}`] : []),
@@ -43,18 +47,40 @@ function propertyLines(property) {
         ...options.map((option) => `${INDENT}${option}`),
     ];
 }
+/**
+ * The inverse of a relationship as its target reads it. A value-matched inverse, one with `on`, has
+ * no route: a warehouse-backed source is read through aggregates, a stored one by its `on` property.
+ */
+function inverseLine(source, relationship) {
+    const { on, phrase, inverse } = relationship;
+    if (on === undefined) {
+        return `${phrase[1]} many ${source.plural} (${inverse})`;
+    }
+    if (source.source !== undefined) {
+        return `${phrase[1]} ${source.plural} (${inverse}), through aggregates`;
+    }
+    return `${phrase[1]} ${source.plural} (${inverse}), matched on ${on.property}`;
+}
 function relationshipLines(entity, entities, all) {
     const declared = entity.relationships.map((relationship) => {
+        const { on, phrase, name } = relationship;
         const target = entities.get(relationship.to);
+        const label = target?.label ?? relationship.to;
         const optional = relationship.optional === true ? ", optional" : "";
-        const head = relationship.cardinality === "one"
-            ? `${relationship.phrase[0]} one ${target?.label ?? relationship.to} (${relationship.name})${optional}`
-            : `${relationship.phrase[0]} many ${target?.plural ?? relationship.to} (${relationship.name})`;
+        let head = `${phrase[0]} one ${label} (${name})${optional}`;
+        if (relationship.cardinality === "many") {
+            head = `${phrase[0]} many ${target?.plural ?? relationship.to} (${name})`;
+        }
+        else if (on !== undefined) {
+            // Value-matched: nothing promises a match, and the key is the declared property pair.
+            const key = `${on.property} = ${label}.${on.targetProperty}`;
+            head = `${phrase[0]} at most one ${label} (${name}), matched on ${key}`;
+        }
         return withDescription(head, relationship.description);
     });
     const inverses = all.flatMap((source) => source.relationships
         .filter((relationship) => relationship.to === entity.name)
-        .map((relationship) => `${relationship.phrase[1]} many ${source.plural} (${relationship.inverse})`));
+        .map((relationship) => inverseLine(source, relationship)));
     return [...declared, ...inverses];
 }
 function inputType(schema) {
@@ -143,10 +169,8 @@ function renderEntity(entity, manifest, entities, options) {
         ...(entity.source
             ? [`${INDENT}Source: ${entity.source.asset}; key: ${entity.source.key.join(", ")}.`]
             : []),
-        ...section("Properties", entity.properties.flatMap(propertyLines)),
-        ...(entity.source
-            ? section("Measures", (entity.measures ?? []).map((measure) => `${measure.name}: ${measure.description} (${measure.unit}).`))
-            : []),
+        ...section("Properties", entity.properties.flatMap((property) => propertyLines({ property, warehouseBacked: entity.source !== undefined }))),
+        ...section("Measures", (entity.measures ?? []).map((measure) => `${measure.name}: ${measure.description} (${measure.unit}).`)),
         ...section("Relationships", relationshipLines(entity, entities, manifest.entities)),
         ...section(reader === undefined ? "Actions" : "Actions you may run", actions.flatMap((action) => actionLines(action, reader === undefined
             ? requirement("Requires", actionPermission(entity.name, action), manifest.roles)
@@ -180,5 +204,87 @@ export function renderCatalog(manifest, options = {}) {
         options.as === undefined ||
         isAllowed(entity.permissions?.read ?? `${entity.name}:read`, { permissions: options.as }))
         .map((entity) => renderEntity(entity, manifest, entities, options));
-    return `${[...sections, renderRoles(manifest.roles)].join("\n\n")}\n`;
+    const aggregates = renderAggregates(manifest, options.as);
+    return `${[...sections, renderRoles(manifest.roles), ...(aggregates === "" ? [] : [aggregates])].join("\n\n")}\n`;
+}
+/**
+ * The catalog as `describe` answers a reader: {@link renderCatalog} with the reader's permissions,
+ * or everything without them.
+ */
+export function describeCatalog(manifest, permissions) {
+    return renderCatalog(manifest, permissions === undefined ? {} : { as: permissions });
+}
+/** The rule every surface repeats (docs/ontology-aggregates-spec.md, "Three ways to ask"). */
+export const RECORDS_OR_AGGREGATES = "look at or change records through find and actions; count, sum or compare through aggregate";
+/** Whether the reader may read the entity; without a reader, everything is described. */
+function readable(entity, permissions) {
+    return permissions === undefined || isAllowed(permissionOf(entity, READ_VERB), { permissions });
+}
+/**
+ * Every measure of the entities the reader may read, warehouse-backed and stored alike, in
+ * declaration order. Without permissions, every measure.
+ */
+export function measuresFor(manifest, permissions) {
+    return manifest.entities
+        .filter((entity) => readable(entity.name, permissions))
+        .flatMap((entity) => (entity.measures ?? []).map((measure) => ({
+        name: `${entity.name}.${measure.name}`,
+        entity,
+        measure,
+    })));
+}
+/**
+ * The entities one entity reaches, with the shortest routes to each: exactly the routes aggregate
+ * resolution weighs ({@link shortestRoutesFrom}). Only then is the reader applied: a target they may
+ * not read is left out, and so is any route through an entity they may not read, which the service
+ * would refuse. A target keeps `ambiguous` from before that filter, so a route is never shown as the
+ * only one when the resolver would ask for it to be written.
+ */
+export function reachesOf(manifest, from, permissions) {
+    return [...shortestRoutesFrom(manifest, from)].flatMap(([target, routes]) => {
+        const followed = routes.filter((route) => route.entities.every((entity) => readable(entity, permissions)));
+        return followed.length === 0
+            ? []
+            : [
+                {
+                    target,
+                    routes: followed.map((route) => route.relationships.join(".")),
+                    ambiguous: routes.length > 1,
+                },
+            ];
+    });
+}
+/** `sales reaches product (product), region (product.region or listing.region; write the route).` */
+function reachLine(entity, reaches) {
+    const targets = reaches.map(({ target, routes, ambiguous }) => `${target} (${routes.join(" or ")}${ambiguous ? "; write the route" : ""})`);
+    return `${entity} reaches ${targets.join(", ")}.`;
+}
+/**
+ * The aggregate part of the catalog's prose: every measure the reader may read, model-wide, and
+ * per measure entity the entities it reaches. Empty when the reader may read no measure.
+ */
+export function renderAggregates(manifest, permissions) {
+    const measures = measuresFor(manifest, permissions);
+    if (measures.length === 0) {
+        return "";
+    }
+    const owners = [...new Set(measures.map(({ entity }) => entity.name))];
+    const reachLines = owners.flatMap((owner) => {
+        const reaches = reachesOf(manifest, owner, permissions);
+        return reaches.length === 0 ? [] : [reachLine(owner, reaches)];
+    });
+    const measureLines = measures.map(({ name, measure }) => `${name} (${measure.unit}): ${sentence(measure.description)}`);
+    return [
+        `Aggregates: ${RECORDS_OR_AGGREGATES} (POST /api/ontology/aggregate, or the aggregate tool).`,
+        `${INDENT}Measures, as <entity>.<measure>:`,
+        ...measureLines.map((line) => `${INDENT}${INDENT}${line}`),
+        ...(reachLines.length === 0
+            ? []
+            : [
+                `${INDENT}Group and filter by <entity>.<property>. Where a target says write the route, ` +
+                    "name it from the measure's entity: <entity>.<relationship>.<property>. Through " +
+                    "to-one relationships:",
+                ...reachLines.map((line) => `${INDENT}${INDENT}${line}`),
+            ]),
+    ].join("\n");
 }

package/dist/replication/model.d.ts

@@ -1,4 +1,4 @@
-import type { OntologyManifest } from "../manifest.js";
+import { type OntologyManifest } from "../manifest.js";
 /** The resolved projection for one immutable generation. `id` is always included. */
 export interface ReplicationSelection {
     readonly entityId: string;

package/dist/replication/model.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { isValueMatched } from "../manifest.js";
 import { queryFields } from "../query.js";
 export function resolveReplicationSelection(manifest, exclusions = []) {
     const entities = manifest.entities.filter((entity) => !entity.builtIn && !entity.source);
@@ -18,13 +19,22 @@ export function resolveReplicationSelection(manifest, exclusions = []) {
         if (item.relationships?.some((relationship) => !relationships.has(relationship))) {
             throw new Error(`Unknown replication relationship on ${entity.name}.`);
         }
+        // A value-matched relationship has no `<name>_id`: its reference is the property `on` names.
+        const matched = entity.relationships.find((relationship) => item.relationships?.includes(relationship.name) && isValueMatched(relationship));
+        if (matched !== undefined) {
+            throw new Error(`${entity.name}.${matched.name} is matched by value; exclude its property ` +
+                `${matched.on?.property ?? ""} instead.`);
+        }
     }
     const included = entities.filter((entity) => !exclusions.some((item) => item.entityId === entity.id && item.disabled));
     const selection = included.map((entity) => {
         const excluded = exclusions.find((item) => item.entityId === entity.id);
+        const keyed = entity.relationships.filter((relationship) => relationship.cardinality === "one" && !isValueMatched(relationship));
         const excludedFields = new Set([
             ...(excluded?.fields ?? []),
-            ...(excluded?.relationships ?? []).map((relationship) => `${relationship}_id`),
+            ...keyed
+                .filter((relationship) => excluded?.relationships?.includes(relationship.name))
+                .map((relationship) => `${relationship.name}_id`),
         ]);
         return {
             entityId: entity.id,

package/dist/service/aggregate-platform.d.ts

@@ -0,0 +1,60 @@
+import { 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 declare const AGGREGATE_TIMEOUT_MS = 60000;
+/**
+ * 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 declare 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 declare const TOUCHED_HEADER = "x-ontology-touched";
+/** SegmentStream would read beyond what the service checked: this deployment's SDK is behind. */
+export declare const SCOPE_MISMATCH = "aggregate_scope_mismatch";
+/** SegmentStream's answer: its status, its JSON body as sent, and that body parsed. */
+export interface PlatformAnswer {
+    readonly status: number;
+    readonly text: string;
+    readonly body: Readonly<Record<string, unknown>>;
+    /** SegmentStream's `Retry-After`, on a 429 or a 503 that sent one. */
+    readonly retryAfter?: string;
+}
+/**
+ * Sends a checked aggregate to SegmentStream: model-level, or the per-entity shorthand of `entity`.
+ * `touched` is every entity the service required `<entity>:read` on.
+ */
+export type AggregateTransport = (input: {
+    readonly entity?: string;
+    readonly body: unknown;
+    readonly requestId: string;
+    readonly touched: ReadonlyArray<string>;
+}) => Effect.Effect<PlatformAnswer, AggregateUpstreamUnavailable>;
+/**
+ * Where a deployment sends aggregates: its platform, its workspace and its app credential, with the
+ * hash of the manifest it serves.
+ */
+export interface AggregateEnvironment {
+    readonly segmentstreamUrl: string;
+    readonly workspaceId: string;
+    readonly appCredential?: Redacted.Redacted<string>;
+    readonly manifestHash: string;
+}
+/**
+ * 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 declare function platformAggregates(environment: AggregateEnvironment, fetchImpl?: typeof fetch): AggregateTransport | undefined;

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;