@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/metric-query-platform.js

@@ -0,0 +1,198 @@
+import { Data, Effect, Redacted } from "effect";
+import { MetricQueryUpstreamUnavailable } from "./errors.js";
+/**
+ * How long one metric query 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 METRIC_QUERY_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";
+/**
+ * The caller's read scopes of the stored entities the request reads scoped, base64url JSON of entity
+ * name to `where`, `me` resolved. SegmentStream keeps only each scope's rows wherever it reads the
+ * entity, confirms the scopes in `execution.rowScopes`, and answers `422
+ * scoped_aggregate_unavailable` for a scope the warehouse cannot apply.
+ */
+export const ROW_SCOPES_HEADER = "x-ontology-row-scopes";
+/**
+ * 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. */
+export 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.
+ */
+export 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}/metrics/query`, and its per-entity
+ * `…/entities/{entity}/metrics/query`, 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 platformMetricQueries(environment, fetchImpl = fetch) {
+    const { appCredential, segmentstreamUrl } = environment;
+    if (appCredential === undefined) {
+        return undefined;
+    }
+    if (!securePlatform(segmentstreamUrl)) {
+        Effect.runSync(Effect.logError("ontology.metric_query.insecure_platform").pipe(Effect.annotateLogs({
+            diagnostic: "SEGMENTSTREAM_URL is not https; metric queries 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}/metrics/query`
+        : `${workspace}/entities/${encodeURIComponent(entity)}/metrics/query`;
+    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(","),
+                        ...(input.rowScopes === undefined ? {} : { [ROW_SCOPES_HEADER]: input.rowScopes }),
+                    },
+                    body: JSON.stringify(input.body),
+                    redirect: "error",
+                    signal: AbortSignal.any([signal, AbortSignal.timeout(METRIC_QUERY_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.metric_query.upstream_failed").pipe(Effect.annotateLogs({ requestId, diagnostic: reason, error: describeError(error, redact) }), Effect.andThen(Effect.fail(new MetricQueryUpstreamUnavailable({ 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.metric_query.platform_refused"
+                : "ontology.metric_query.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 MetricQueryUpstreamUnavailable({
+                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/metric-query-scopes.d.ts

@@ -0,0 +1,43 @@
+import { type PermissionHolder, type ScopeWhere } from "../permissions.js";
+import type { OntologyModel } from "../runtime/model.js";
+/**
+ * Row scopes of metric queries (docs/ontology-scoped-permissions-spec.md, "Aggregates"). A metric
+ * query that reads an entity the caller reads through a scoped permission sends that scope along, so that
+ * SegmentStream keeps only the scope's rows wherever it reads the entity. `me` is the caller's user
+ * id, resolved here; a path from `me` needs the ontology's records to resolve, so a scope with one
+ * cannot travel yet and the metric query is refused, as before. A scope the service's own reads would
+ * compile to FALSE travels as one that matches nothing: resolving `me` would otherwise turn a marker
+ * on the wrong field into a valid comparison with the caller's id.
+ */
+/** The longest `x-ontology-row-scopes` SegmentStream accepts. */
+export declare const MAX_ROW_SCOPES_HEADER = 8192;
+/** The caller's read scopes of the entities a metric query reads, as SegmentStream applies them. */
+export type RowScopes = {
+    readonly ok: true;
+    readonly scopes: Readonly<Record<string, ScopeWhere>>;
+}
+/** `entity`'s scope cannot travel: it follows a path from `me`, or is too large to send. */
+ | {
+    readonly ok: false;
+    readonly entity: string;
+    readonly reason: "me_path" | "too_large";
+};
+/**
+ * Each touched entity the caller reads through a scope, with its `where` and `me` replaced by the
+ * caller's user id: a bare `me` compares as `{ eq: <id> }`, an operand `me` becomes the id. A scope
+ * the service's reads would compile to FALSE (an unknown field or operator, an operand of the wrong
+ * type, `me` on a field that is not a key, or a caller whose id is not a record id) matches nothing.
+ * A warehouse-backed entity has no stored model to check against; its scope travels as written and
+ * SegmentStream refuses it.
+ */
+export declare function rowScopesOf(touched: ReadonlyArray<string>, principal: PermissionHolder & {
+    readonly id: string;
+}, model: OntologyModel): RowScopes;
+/** `x-ontology-row-scopes`: base64url of the scopes' JSON, or `undefined` without any. */
+export declare function encodeRowScopes(scopes: Readonly<Record<string, ScopeWhere>>): string | undefined;
+/**
+ * Whether SegmentStream confirmed every scope it was sent: its answer's `execution.rowScopes` names
+ * exactly the scoped entities. A platform that predates row scopes ignores them and confirms none,
+ * so its answer, which counts rows the caller may not see, is never passed on.
+ */
+export declare function confirmsRowScopes(body: Readonly<Record<string, unknown>>, scopes: Readonly<Record<string, ScopeWhere>>): boolean;

package/dist/service/metric-query-scopes.js

@@ -0,0 +1,147 @@
+import { mePathOf } from "../me.js";
+import { readScope } from "../permissions.js";
+import { FILTER_OPERATORS, MANY_QUANTIFIERS } from "../query.js";
+import { isRecordId } from "../runtime/records.js";
+import { isWellFormedScope } from "../runtime/where.js";
+/**
+ * Row scopes of metric queries (docs/ontology-scoped-permissions-spec.md, "Aggregates"). A metric
+ * query that reads an entity the caller reads through a scoped permission sends that scope along, so that
+ * SegmentStream keeps only the scope's rows wherever it reads the entity. `me` is the caller's user
+ * id, resolved here; a path from `me` needs the ontology's records to resolve, so a scope with one
+ * cannot travel yet and the metric query is refused, as before. A scope the service's own reads would
+ * compile to FALSE travels as one that matches nothing: resolving `me` would otherwise turn a marker
+ * on the wrong field into a valid comparison with the caller's id.
+ */
+/** The longest `x-ontology-row-scopes` SegmentStream accepts. */
+export const MAX_ROW_SCOPES_HEADER = 8_192;
+/** No row: a scope `check` would have refused, as the service's own reads treat it. */
+const NO_ROWS = { or: [] };
+/** Query and wire names of field operators: their operands are values, never wheres. */
+const OPERATORS = new Set([
+    ...FILTER_OPERATORS,
+    "is_null",
+    "starts_with",
+    "has_any",
+]);
+const QUANTIFIERS = new Set(MANY_QUANTIFIERS);
+/** A path from `me`: only the ontology's records can resolve it. */
+class MePath extends Error {
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Each touched entity the caller reads through a scope, with its `where` and `me` replaced by the
+ * caller's user id: a bare `me` compares as `{ eq: <id> }`, an operand `me` becomes the id. A scope
+ * the service's reads would compile to FALSE (an unknown field or operator, an operand of the wrong
+ * type, `me` on a field that is not a key, or a caller whose id is not a record id) matches nothing.
+ * A warehouse-backed entity has no stored model to check against; its scope travels as written and
+ * SegmentStream refuses it.
+ */
+export function rowScopesOf(touched, principal, model) {
+    const scopes = {};
+    for (const entity of touched) {
+        const where = readScope(entity, principal);
+        if (where === undefined) {
+            continue;
+        }
+        const stored = model.entities.get(entity);
+        if (stored !== undefined && !isWellFormedScope(model, stored, { reader: principal, where })) {
+            scopes[entity] = NO_ROWS;
+            continue;
+        }
+        try {
+            scopes[entity] = resolveWhere(where, principal.id);
+        }
+        catch (error) {
+            if (error instanceof MePath) {
+                return { ok: false, entity, reason: "me_path" };
+            }
+            throw error;
+        }
+    }
+    const encoded = encodeRowScopes(scopes);
+    if (encoded !== undefined && encoded.length > MAX_ROW_SCOPES_HEADER) {
+        return { ok: false, entity: Object.keys(scopes).sort()[0], reason: "too_large" };
+    }
+    return { ok: true, scopes };
+}
+/** `x-ontology-row-scopes`: base64url of the scopes' JSON, or `undefined` without any. */
+export function encodeRowScopes(scopes) {
+    return Object.keys(scopes).length === 0
+        ? undefined
+        : Buffer.from(JSON.stringify(scopes), "utf8").toString("base64url");
+}
+/** The caller's id; a stored entity's scope with `me` was checked to have a record id. */
+function me(readerId) {
+    return isRecordId(readerId) ? readerId.toLowerCase() : readerId;
+}
+/** A `where`: `and`, `or` and `not` hold wheres; every other key a member's condition. */
+function resolveWhere(where, readerId) {
+    if (!isPlainObject(where)) {
+        return where;
+    }
+    return Object.fromEntries(Object.entries(where).map(([key, condition]) => {
+        if (key === "and" || key === "or") {
+            return [
+                key,
+                Array.isArray(condition)
+                    ? condition.map((sub) => resolveWhere(sub, readerId))
+                    : condition,
+            ];
+        }
+        if (key === "not") {
+            return [key, resolveWhere(condition, readerId)];
+        }
+        return [key, resolveMember(condition, readerId)];
+    }));
+}
+/**
+ * A field's or relationship's condition: bare `me`, an object of operators whose operands may be
+ * `me`, a to-many filter of quantifiers, or a related record's where.
+ */
+function resolveMember(condition, readerId) {
+    const hops = mePathOf(condition);
+    if (hops !== undefined) {
+        if (hops.length > 0) {
+            throw new MePath();
+        }
+        return { eq: me(readerId) };
+    }
+    if (!isPlainObject(condition)) {
+        return condition;
+    }
+    const keys = Object.keys(condition);
+    if (keys.length > 0 && keys.every((key) => OPERATORS.has(key))) {
+        return Object.fromEntries(Object.entries(condition).map(([operator, operand]) => {
+            const operandHops = mePathOf(operand);
+            if (operandHops === undefined) {
+                return [operator, operand];
+            }
+            if (operandHops.length > 0) {
+                throw new MePath();
+            }
+            return [operator, me(readerId)];
+        }));
+    }
+    if (keys.length > 0 && keys.every((key) => QUANTIFIERS.has(key))) {
+        return Object.fromEntries(Object.entries(condition).map(([quantifier, where]) => [
+            quantifier,
+            resolveWhere(where, readerId),
+        ]));
+    }
+    return resolveWhere(condition, readerId);
+}
+/**
+ * Whether SegmentStream confirmed every scope it was sent: its answer's `execution.rowScopes` names
+ * exactly the scoped entities. A platform that predates row scopes ignores them and confirms none,
+ * so its answer, which counts rows the caller may not see, is never passed on.
+ */
+export function confirmsRowScopes(body, scopes) {
+    const execution = body.execution;
+    const confirmed = isPlainObject(execution) ? execution.rowScopes : undefined;
+    const expected = Object.keys(scopes).sort();
+    return (Array.isArray(confirmed) &&
+        confirmed.length === expected.length &&
+        [...confirmed].sort().every((entity, index) => entity === expected[index]));
+}

package/dist/service/metric-query.d.ts

@@ -0,0 +1,48 @@
+import { Effect } from "effect";
+import type { Ontology } from "../ontology.js";
+import type { MetricQueryTransport, PlatformAnswer } from "./metric-query-platform.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { MetricQueryLimited, MetricQueriesUnavailable, MetricQueryUpstreamUnavailable, InvalidMetricQuery, InvalidRequestBody, ReadDenied, RequestId, ScopedMetricQueryUnavailable } from "./errors.js";
+import { type RateLimit, type RateLimiter } from "./rate-limit.js";
+/**
+ * Metric queries 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 METRIC_QUERY_LIMIT: RateLimit;
+/** Every way the facade refuses or fails a metric query before SegmentStream answers it. */
+export type MetricQueryFailure = MetricQueryLimited | InvalidRequestBody | InvalidMetricQuery | ReadDenied | ScopedMetricQueryUnavailable | MetricQueriesUnavailable | MetricQueryUpstreamUnavailable;
+/**
+ * Runs a metric query 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 QueryMetrics = (body: unknown) => Effect.Effect<PlatformAnswer, MetricQueryFailure, CurrentPrincipal | RequestId>;
+/** The service's metric queries: model-level, and the per-entity shorthand of each entity. */
+export interface MetricQueries {
+    /** `POST /api/ontology/query_metrics` and the MCP `query_metrics` tool. */
+    readonly model: QueryMetrics;
+    /** `POST /api/ontology/<entity>/query_metrics`, the shorthand `segmentstream.ontology.<entity>`. */
+    readonly entity: (entity: string) => QueryMetrics;
+}
+/**
+ * The ontology service's metric query 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 METRIC_QUERY_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; a read scope on any of them travels along,
+ *    `me` resolved, and SegmentStream keeps only the scope's rows wherever it reads that entity. A
+ *    scope with a path from `me` is refused with `ScopedMetricQueryUnavailable`;
+ * 3. the body goes to SegmentStream as it came, earlier names renamed (`withCurrentMetricQueryNames`),
+ *    with the workspace app credential, naming the entities checked, or the answer is
+ *    `aggregate_unavailable` where the deployment has no credential;
+ * 4. an answer to a scoped request must confirm every scope it was sent in `execution.rowScopes`,
+ *    and a scope SegmentStream cannot apply is refused with `ScopedMetricQueryUnavailable`: a platform
+ *    that ignored the scopes never answers a scoped caller.
+ */
+export declare function makeMetricQueries(input: {
+    readonly ontology: Ontology;
+    readonly transport: MetricQueryTransport | undefined;
+    /** One bucket per principal; {@link METRIC_QUERY_LIMIT} by default. */
+    readonly limiter?: RateLimiter;
+}): MetricQueries;

package/dist/service/metric-query.js

@@ -0,0 +1,200 @@
+import { Effect, Schema } from "effect";
+import { resolveMetricRoutes } from "../metric-routes.js";
+import { withCurrentMetricQueryNames } from "../legacy.js";
+import { isAllowed, permissionOf, READ_VERB } from "../permissions.js";
+import { ontologyModel } from "../runtime/model.js";
+import { confirmsRowScopes, encodeRowScopes, rowScopesOf } from "./metric-query-scopes.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { MetricQueryLimited, MetricQueriesUnavailable, InvalidMetricQuery, InvalidRequestBody, ReadDenied, RequestId, schemaIssues, ScopedMetricQueryUnavailable, } from "./errors.js";
+import { fixedWindowLimiter } from "./rate-limit.js";
+import { MetricQuery, EntityMetricQuery } from "./schemas.js";
+/**
+ * Metric queries one principal may run per minute, through both routes and the MCP tool together.
+ * Each runs a warehouse query with the deployment's credential, so one caller must not spend without
+ * bound.
+ */
+export const METRIC_QUERY_LIMIT = { limit: 30, windowMs: 60_000, maxKeys: 10_000 };
+function decode(schema, body) {
+    return Schema.decodeUnknownEffect(schema)(body, { errors: "all" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error.issue) })));
+}
+/**
+ * The first `orderBy` entry that names neither a requested metric nor a requested dimension, by
+ * its requested name or its identity. Ordering by anything else would read what the permission
+ * check never saw.
+ */
+function unrequestedOrder(request, routes) {
+    const dimensions = new Set([
+        ...(request.dimensions ?? []),
+        ...(routes.entities[0]?.dimensions ?? []).map(({ identity }) => identity),
+    ]);
+    for (const order of request.orderBy ?? []) {
+        if (order.metric !== undefined && !request.metrics.includes(order.metric)) {
+            return order.metric;
+        }
+        if (order.dimension !== undefined && !dimensions.has(order.dimension)) {
+            return order.dimension;
+        }
+    }
+    return undefined;
+}
+/**
+ * A model-level request's entities, as the shared resolver finds them: each metric's entity,
+ * every entity on a dimension's or a filter's route, intermediates included, and every entity a
+ * filter names even where it does not apply.
+ */
+function modelTouched(manifest, body) {
+    return Effect.gen(function* () {
+        const request = yield* decode(MetricQuery, body);
+        const routes = resolveMetricRoutes(manifest, {
+            metrics: request.metrics,
+            dimensions: request.dimensions ?? [],
+            filters: (request.filters ?? []).map((filter) => filter.dimension),
+            ...(request.granularityOf === undefined ? {} : { granularityOf: request.granularityOf }),
+        });
+        if (!routes.ok) {
+            return yield* new InvalidMetricQuery({ reason: routes.reason });
+        }
+        const unordered = unrequestedOrder(request, routes);
+        if (unordered !== undefined) {
+            return yield* new InvalidMetricQuery({
+                reason: `orderBy names ${unordered}, which the request does not ask for.`,
+            });
+        }
+        return routes.touched;
+    });
+}
+/**
+ * A per-entity request's entities: the entity, and every entity along each relative name it
+ * groups, filters, buckets or orders by, following the manifest's `rel.one` relationships. As on
+ * SegmentStream's per-entity route, a path may follow a self-relationship (`manager.name`).
+ */
+function entityTouched(manifest, entity, body) {
+    return Effect.gen(function* () {
+        const request = yield* decode(EntityMetricQuery, body);
+        const entities = new Map(manifest.entities.map((candidate) => [candidate.name, candidate]));
+        const touched = new Set([entity]);
+        const names = [
+            ...request.dimensions,
+            ...(request.filters ?? []).map((filter) => filter.dimension),
+            ...(request.granularityOf === undefined ? [] : [request.granularityOf]),
+            ...(request.orderBy ?? []).flatMap((order) => order.dimension === undefined ? [] : [order.dimension]),
+        ];
+        for (const name of names) {
+            const segments = name.split(".");
+            let current = entities.get(entity);
+            if (segments.some((segment) => segment === "")) {
+                return yield* new InvalidMetricQuery({ reason: `${name} is not a valid name.` });
+            }
+            for (const relationshipName of segments.slice(0, -1)) {
+                const relationship = current?.relationships.find((candidate) => candidate.name === relationshipName);
+                if (current === undefined || relationship === undefined) {
+                    return yield* new InvalidMetricQuery({
+                        reason: `${current?.name ?? entity} has no relationship ${relationshipName}.`,
+                    });
+                }
+                if (relationship.cardinality !== "one") {
+                    return yield* new InvalidMetricQuery({
+                        reason: `${relationshipName} is not a to-one relationship of ${current.name}.`,
+                    });
+                }
+                current = entities.get(relationship.to);
+                touched.add(relationship.to);
+            }
+        }
+        return [...touched].sort();
+    });
+}
+/**
+ * SegmentStream's answer to a scoped metric query: passed on when it confirms every scope; a refusal of
+ * a scope it cannot apply, or an answer that does not confirm the scopes, fails as the caller's
+ * {@link ScopedMetricQueryUnavailable}.
+ */
+function scopedAnswer(answer, scopes, requestId) {
+    const [first] = Object.keys(scopes).sort();
+    const { body } = answer;
+    if (body.error === "scoped_aggregate_unavailable") {
+        // SegmentStream's explanation is for operators; the caller gets the reason's code.
+        return Effect.logWarning("ontology.metric_query.row_scopes_unplannable").pipe(Effect.annotateLogs({
+            requestId,
+            diagnostic: typeof body.detail === "string" ? body.detail : "No detail.",
+            scoped: Object.keys(scopes).sort().join(","),
+        }), Effect.andThen(Effect.fail(new ScopedMetricQueryUnavailable({
+            entity: typeof body.entity === "string" ? body.entity : first,
+            reason: "unplannable",
+        }))));
+    }
+    if (answer.status < 200 || answer.status >= 300 || confirmsRowScopes(body, scopes)) {
+        return Effect.succeed(answer);
+    }
+    return Effect.logError("ontology.metric_query.row_scopes_unconfirmed").pipe(Effect.annotateLogs({
+        requestId,
+        diagnostic: "SegmentStream answered a scoped metric query without confirming its row scopes.",
+        scoped: Object.keys(scopes).sort().join(","),
+    }), Effect.andThen(Effect.fail(new ScopedMetricQueryUnavailable({
+        entity: first,
+        reason: "unconfirmed",
+    }))));
+}
+/**
+ * The ontology service's metric query 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 METRIC_QUERY_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; a read scope on any of them travels along,
+ *    `me` resolved, and SegmentStream keeps only the scope's rows wherever it reads that entity. A
+ *    scope with a path from `me` is refused with `ScopedMetricQueryUnavailable`;
+ * 3. the body goes to SegmentStream as it came, earlier names renamed (`withCurrentMetricQueryNames`),
+ *    with the workspace app credential, naming the entities checked, or the answer is
+ *    `aggregate_unavailable` where the deployment has no credential;
+ * 4. an answer to a scoped request must confirm every scope it was sent in `execution.rowScopes`,
+ *    and a scope SegmentStream cannot apply is refused with `ScopedMetricQueryUnavailable`: a platform
+ *    that ignored the scopes never answers a scoped caller.
+ */
+export function makeMetricQueries(input) {
+    const { ontology, transport } = input;
+    const { manifest } = ontology;
+    const limiter = input.limiter ?? fixedWindowLimiter(METRIC_QUERY_LIMIT);
+    const run = (request) => Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const requestId = yield* RequestId;
+        const retryAfterSeconds = limiter.take(principal.id);
+        if (retryAfterSeconds !== undefined) {
+            return yield* new MetricQueryLimited({ retryAfterSeconds });
+        }
+        const touched = yield* request.touchedBy(request.body);
+        const missing = touched
+            .map((entity) => permissionOf(entity, READ_VERB))
+            .filter((permission) => !isAllowed(permission, principal));
+        if (missing.length > 0) {
+            return yield* new ReadDenied({ permissions: missing });
+        }
+        // Counting rows a list hides would leak them: each read scope travels to the warehouse.
+        const rowScopes = rowScopesOf(touched, principal, ontologyModel(ontology));
+        if (!rowScopes.ok) {
+            return yield* new ScopedMetricQueryUnavailable({
+                entity: rowScopes.entity,
+                reason: rowScopes.reason,
+            });
+        }
+        if (transport === undefined) {
+            return yield* new MetricQueriesUnavailable();
+        }
+        const encoded = encodeRowScopes(rowScopes.scopes);
+        const answer = yield* transport({
+            ...(request.entity === undefined ? {} : { entity: request.entity }),
+            body: withCurrentMetricQueryNames(request.body),
+            requestId,
+            touched,
+            ...(encoded === undefined ? {} : { rowScopes: encoded }),
+        });
+        if (encoded === undefined) {
+            return answer;
+        }
+        return yield* scopedAnswer(answer, rowScopes.scopes, requestId);
+    });
+    return {
+        model: (body) => run({ body, touchedBy: (value) => modelTouched(manifest, value) }),
+        entity: (entity) => (body) => run({ entity, body, touchedBy: (value) => entityTouched(manifest, entity, value) }),
+    };
+}

package/dist/service/name-suggestions.d.ts

@@ -0,0 +1,3 @@
+/** Candidates must already be filtered for this authenticated caller's visibility. */
+export declare function suggestNames(name: string, candidates: ReadonlyArray<string>): Array<string>;
+export declare function suggestionDetail(detail: string, suggestions: ReadonlyArray<string>): string;