@segmentstream-cloud/ontology 0.12.0 → 0.14.0

package/dist/service/agent/protocol.js

@@ -0,0 +1,59 @@
+import { randomInt } from "node:crypto";
+import { Schema } from "effect";
+/** How long a member has to open the connect link, sign in and approve the pairing. */
+export const PAIRING_TTL_MS = 10 * 60 * 1000;
+/**
+ * The letters and digits a pairing code uses: no 0/O, 1/I/L, so that a code read aloud or typed from
+ * a phone comes out right. 31 symbols, 8 of them: about 40 bits, against ten minutes of guessing by
+ * signed-in members only.
+ */
+export const PAIRING_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+export const PAIRING_CODE_LENGTH = 8;
+const PAIRING_CODE = new RegExp(`^[${PAIRING_CODE_ALPHABET}]{${PAIRING_CODE_LENGTH}}$`);
+/** A new pairing code, from the operating system's random source without modulo bias. */
+export function newPairingCode() {
+    let code = "";
+    for (let index = 0; index < PAIRING_CODE_LENGTH; index++) {
+        code += PAIRING_CODE_ALPHABET[randomInt(PAIRING_CODE_ALPHABET.length)];
+    }
+    return code;
+}
+/**
+ * A code as the member's browser sends it, in the canonical form it was hashed in: upper case,
+ * without the spaces or dashes someone may type between groups. `undefined` when it cannot be one.
+ */
+export function canonicalPairingCode(value) {
+    const code = value.replace(/[\s-]/g, "").toUpperCase();
+    return PAIRING_CODE.test(code) ? code : undefined;
+}
+const MAX_EXTERNAL_ID_LENGTH = 256;
+const MAX_DISPLAY_LENGTH = 200;
+/** A channel's name: `telegram`, `slack`. It is part of a URL path and of every identity. */
+export const Provider = Schema.String.check(Schema.isPattern(/^[a-z][a-z0-9_-]{0,31}$/)).annotate({
+    description: "The channel, such as telegram: lower case letters, digits, - and _.",
+});
+/** `POST /api/ontology/agent/pairings`: the account an unknown sender writes from. */
+export const PairingRequest = Schema.Struct({
+    provider: Provider,
+    external_id: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_EXTERNAL_ID_LENGTH)).annotate({ description: "The account's id on the channel." }),
+    display: Schema.optionalKey(Schema.NullOr(Schema.String.check(Schema.isMaxLength(MAX_DISPLAY_LENGTH))).annotate({
+        description: "How the channel names the account, shown to the member who approves.",
+    })),
+});
+/** An identity on the wire, as the member's connect page and settings show it. */
+export function identityForWire(identity) {
+    return {
+        id: identity.id,
+        provider: identity.provider,
+        external_id: identity.externalId,
+        display: identity.display,
+        created_at: identity.createdAt.toISOString(),
+    };
+}
+/** The member the agent acts for, as `GET …/identities/{provider}/{external_id}` answers. */
+export function memberForWire(input) {
+    return {
+        user: { id: input.principal.id, name: input.name },
+        roles: input.principal.roles,
+    };
+}

package/dist/service/agent/server.d.ts

@@ -0,0 +1,27 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type SessionExchange, type TokenVerifier } from "../authentication.js";
+import { RequestId } from "../errors.js";
+import { type RateLimit } from "../rate-limit.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
+/** The agent's endpoints, under the ontology service's path. */
+export declare const AGENT_PATH = "/api/ontology/agent";
+/**
+ * Pairings one client address may start per minute; each one is a row in the database. The agent's
+ * functions share a few egress addresses, so the limit leaves room for a busy channel.
+ */
+export declare const PAIRING_LIMIT: RateLimit;
+export interface AgentServerOptions {
+    readonly verifyToken: TokenVerifier;
+    /** The deployment's runtime tokens; `undefined` while runtime authentication is disabled. */
+    readonly verifyRuntime: RuntimeTokenVerifier | undefined;
+    readonly exchangeSession: SessionExchange | undefined;
+}
+/**
+ * The routes that pair channel accounts with members for the app's own agent. Runtime routes take
+ * only the deployment's runtime token. Member routes take a member's Neon Auth session or token, and
+ * refuse API keys and the runtime, even acting as a member: only the member pairs or unpairs.
+ * Without the agent tables, it serves nothing.
+ */
+export declare function agentLayer(options: AgentServerOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;

package/dist/service/agent/server.js

@@ -0,0 +1,235 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Layer, Redacted, Result, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { schemaIssues } from "../../runtime/validation.js";
+import { BASE_PATH } from "../api.js";
+import { CurrentPrincipal, withPrincipal, } from "../authentication.js";
+import { RequestId, errorBodyForWire, forbidden, notFound, rateLimited, toServerResponse, unauthorized, unavailable, } from "../errors.js";
+import { secretHash } from "../oauth/protocol.js";
+import { clientAddress, fixedWindowLimiter, } from "../rate-limit.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { logRuntimeRejection } from "../runtime-identity.js";
+import { PAIRING_TTL_MS, PairingRequest, canonicalPairingCode, identityForWire, memberForWire, newPairingCode, } from "./protocol.js";
+/** The agent's endpoints, under the ontology service's path. */
+export const AGENT_PATH = `${BASE_PATH}/agent`;
+const PAIRINGS_PATH = `${AGENT_PATH}/pairings`;
+const IDENTITIES_PATH = `${AGENT_PATH}/identities`;
+/**
+ * Pairings one client address may start per minute; each one is a row in the database. The agent's
+ * functions share a few egress addresses, so the limit leaves room for a busy channel.
+ */
+export const PAIRING_LIMIT = { limit: 60, windowMs: 60_000, maxKeys: 10_000 };
+/** A fresh code collides with a live one about never; a few attempts make it never in practice. */
+const CODE_ATTEMPTS = 3;
+const NO_STORE = { "cache-control": "no-store" };
+function json(body, status = 200) {
+    return HttpServerResponse.jsonUnsafe(body, { status, headers: NO_STORE });
+}
+function jsonBody(request) {
+    return Effect.map(Effect.orDie(request.text), (text) => {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
+function invalidBody(requestId, issues) {
+    return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+        error: "invalid_request",
+        detail: "The request body is invalid.",
+        requestId,
+        issues,
+    }), { status: 400 });
+}
+function pairingNotFound(requestId) {
+    return toServerResponse(notFound(requestId, "The pairing code expired or was already used. Send the agent a message for a new link."));
+}
+function routeParam(name) {
+    return Effect.map(HttpRouter.params, (params) => params[name] ?? "");
+}
+/**
+ * `POST /api/ontology/agent/pairings` (runtime): a sender the agent does not know gets a short code
+ * that a signed-in member approves on the app's connect page. Only the code's hash is stored.
+ */
+function createPairing(store, limiter) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const retryAfter = limiter.take(clientAddress(request));
+        if (retryAfter !== undefined) {
+            return toServerResponse(rateLimited(requestId, "Too many pairings; try again in a minute.", retryAfter));
+        }
+        const body = yield* jsonBody(request);
+        const decoded = Schema.decodeUnknownResult(PairingRequest)(body, {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        const { provider, external_id: externalId, display } = decoded.success;
+        const trimmedDisplay = display?.trim() || null;
+        for (let attempt = 0; attempt < CODE_ATTEMPTS; attempt++) {
+            const code = newPairingCode();
+            const expiresAt = new Date(Date.now() + PAIRING_TTL_MS);
+            const saved = yield* store.savePairing({
+                id: randomUUID(),
+                codeHash: secretHash(code),
+                provider,
+                externalId,
+                display: trimmedDisplay,
+                expiresAt,
+            });
+            if (saved) {
+                return json({ code, expires_at: expiresAt.toISOString() }, 201);
+            }
+        }
+        return yield* Effect.die(new Error("No free pairing code after several attempts."));
+    });
+}
+/** `GET /api/ontology/agent/pairings/:code` (member): what the connect page shows. */
+function describePairing(store) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const code = canonicalPairingCode(yield* routeParam("code"));
+        const pairing = code === undefined ? undefined : yield* store.findPairing(secretHash(code));
+        if (pairing === undefined) {
+            return pairingNotFound(requestId);
+        }
+        return json({
+            provider: pairing.provider,
+            display: pairing.display,
+            expires_at: pairing.expiresAt.toISOString(),
+        });
+    });
+}
+/**
+ * `POST /api/ontology/agent/pairings/:code/approve` (member): pairs the account with the signed-in
+ * member, once. The account's previous identity and the member's previous identity on the same
+ * channel stop working: each has one live identity per channel, so an approval tricked out of a
+ * member displaces their own account, which they notice.
+ */
+function approvePairing(store, member) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const code = canonicalPairingCode(yield* routeParam("code"));
+        const identity = code === undefined
+            ? undefined
+            : yield* store.approvePairing({
+                codeHash: secretHash(code),
+                userId: member.id,
+                identityId: randomUUID(),
+            });
+        if (identity === undefined) {
+            return pairingNotFound(requestId);
+        }
+        yield* Effect.logInfo("ontology.agent.paired").pipe(Effect.annotateLogs({ identityId: identity.id, provider: identity.provider, requestId }));
+        return json({ identity: identityForWire(identity) });
+    });
+}
+/**
+ * `GET /api/ontology/agent/identities/:provider/:external_id` (runtime): the member an account acts
+ * as, with the roles they hold now. 404 for an account nobody paired; 403 once its identity was
+ * revoked or its member deactivated.
+ */
+function resolveIdentity(store) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const provider = yield* routeParam("provider");
+        const externalId = yield* routeParam("external_id");
+        const identity = yield* store.findIdentity({ provider, externalId });
+        if (identity === undefined) {
+            return toServerResponse(notFound(requestId, "No member paired this account."));
+        }
+        if (identity.revokedAt !== null) {
+            return toServerResponse(forbidden(requestId, "The account's pairing was revoked."));
+        }
+        const member = yield* store.member(identity.userId);
+        if (member === undefined) {
+            return toServerResponse(forbidden(requestId, "The member is inactive."));
+        }
+        return json(memberForWire(member));
+    });
+}
+/** `GET /api/ontology/agent/identities` (member): the member's own live identities. */
+function listIdentities(store, member) {
+    return Effect.gen(function* () {
+        const identities = yield* store.listIdentities(member.id);
+        return json({ identities: identities.map(identityForWire) });
+    });
+}
+/** `DELETE /api/ontology/agent/identities/:id` (member): revokes one of the member's identities. */
+function revokeIdentity(store, member) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const id = yield* routeParam("id");
+        const revoked = yield* store.revokeIdentity({ id, userId: member.id });
+        if (!revoked) {
+            return toServerResponse(notFound(requestId, "You have no such identity."));
+        }
+        yield* Effect.logInfo("ontology.agent.unpaired").pipe(Effect.annotateLogs({ identityId: id, requestId }));
+        return HttpServerResponse.empty({ status: 204, headers: NO_STORE });
+    });
+}
+/**
+ * The routes that pair channel accounts with members for the app's own agent. Runtime routes take
+ * only the deployment's runtime token. Member routes take a member's Neon Auth session or token, and
+ * refuse API keys and the runtime, even acting as a member: only the member pairs or unpairs.
+ * Without the agent tables, it serves nothing.
+ */
+export function agentLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const store = backend.agents;
+        if (store === undefined) {
+            return;
+        }
+        const limiter = fixedWindowLimiter(PAIRING_LIMIT);
+        const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+        const bearerOf = (request) => Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+        const asRuntime = (answer) => (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const bearer = yield* bearerOf(request);
+            const token = Redacted.value(bearer);
+            const verified = options.verifyRuntime === undefined || token === ""
+                ? undefined
+                : yield* Effect.promise(() => options.verifyRuntime(token));
+            switch (verified?.status) {
+                case "valid":
+                    return yield* answer(request);
+                case "invalid":
+                    yield* logRuntimeRejection(verified.reason);
+                    return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked."));
+                case "unavailable":
+                    return toServerResponse(unavailable(requestId));
+                default:
+                    // Any other credential is authenticated as usual, so that it gets the usual 401, and
+                    // then refused: these routes are the agent's.
+                    return yield* withPrincipal(bearer, options.verifyToken, backend, Effect.succeed(toServerResponse(forbidden(requestId, "Only the app's agent calls this route."))));
+            }
+        });
+        const asMember = (answer) => (request) => Effect.gen(function* () {
+            const bearer = yield* bearerOf(request);
+            const decided = Effect.gen(function* () {
+                const requestId = yield* RequestId;
+                const principal = yield* CurrentPrincipal;
+                if (principal.kind !== "member") {
+                    return toServerResponse(forbidden(requestId, "Only a signed-in member can pair the app's agent."));
+                }
+                return yield* answer(request, principal);
+            });
+            return yield* withPrincipal(bearer, options.verifyToken, backend, decided, {
+                session: { request, exchange: options.exchangeSession },
+            });
+        });
+        yield* router.add("POST", PAIRINGS_PATH, asRuntime(createPairing(store, limiter)));
+        yield* router.add("GET", `${PAIRINGS_PATH}/:code`, asMember(() => describePairing(store)));
+        yield* router.add("POST", `${PAIRINGS_PATH}/:code/approve`, asMember((_, member) => approvePairing(store, member)));
+        yield* router.add("GET", IDENTITIES_PATH, asMember((_, member) => listIdentities(store, member)));
+        yield* router.add("GET", `${IDENTITIES_PATH}/:provider/:external_id`, asRuntime(() => resolveIdentity(store)));
+        yield* router.add("DELETE", `${IDENTITIES_PATH}/:id`, asMember((_, member) => revokeIdentity(store, member)));
+    }));
+}

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;