@segmentstream-cloud/ontology 0.12.0 → 0.14.0

package/dist/service/aggregate.js

@@ -0,0 +1,145 @@
+import { Effect, Schema } from "effect";
+import { resolveAggregateRoutes } from "../aggregate-routes.js";
+import { isAllowed, permissionOf, READ_VERB } from "../permissions.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { AggregateLimited, AggregateUnavailable, InvalidAggregateQuery, InvalidRequestBody, ReadDenied, RequestId, schemaIssues, } from "./errors.js";
+import { fixedWindowLimiter } from "./rate-limit.js";
+import { AggregateRequest, EntityAggregateRequest } from "./schemas.js";
+/**
+ * Aggregates one principal may run per minute, through both routes and the MCP tool together. Each
+ * runs a warehouse query with the deployment's credential, so one caller must not spend without
+ * bound.
+ */
+export const AGGREGATE_LIMIT = { limit: 30, windowMs: 60_000, maxKeys: 10_000 };
+function decode(schema, body) {
+    return Schema.decodeUnknownEffect(schema)(body, { errors: "all" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error.issue) })));
+}
+/**
+ * The first `orderBy` entry that names neither a requested measure nor a requested dimension, by
+ * its requested name or its identity. Ordering by anything else would read what the permission
+ * check never saw.
+ */
+function unrequestedOrder(request, routes) {
+    const dimensions = new Set([
+        ...(request.dimensions ?? []),
+        ...(routes.entities[0]?.dimensions ?? []).map(({ identity }) => identity),
+    ]);
+    for (const order of request.orderBy ?? []) {
+        if (order.measure !== undefined && !request.measures.includes(order.measure)) {
+            return order.measure;
+        }
+        if (order.dimension !== undefined && !dimensions.has(order.dimension)) {
+            return order.dimension;
+        }
+    }
+    return undefined;
+}
+/**
+ * A model-level request's entities, as the shared resolver finds them: each measure's entity,
+ * every entity on a dimension's or a filter's route, intermediates included, and every entity a
+ * filter names even where it does not apply.
+ */
+function modelTouched(manifest, body) {
+    return Effect.gen(function* () {
+        const request = yield* decode(AggregateRequest, body);
+        const routes = resolveAggregateRoutes(manifest, {
+            measures: request.measures,
+            dimensions: request.dimensions ?? [],
+            filters: (request.filters ?? []).map((filter) => filter.dimension),
+            ...(request.granularityOf === undefined ? {} : { granularityOf: request.granularityOf }),
+        });
+        if (!routes.ok) {
+            return yield* new InvalidAggregateQuery({ reason: routes.reason });
+        }
+        const unordered = unrequestedOrder(request, routes);
+        if (unordered !== undefined) {
+            return yield* new InvalidAggregateQuery({
+                reason: `orderBy names ${unordered}, which the request does not ask for.`,
+            });
+        }
+        return routes.touched;
+    });
+}
+/**
+ * A per-entity request's entities: the entity, and every entity along each relative name it
+ * groups, filters, buckets or orders by, following the manifest's `rel.one` relationships. As on
+ * SegmentStream's per-entity route, a path may follow a self-relationship (`manager.name`).
+ */
+function entityTouched(manifest, entity, body) {
+    return Effect.gen(function* () {
+        const request = yield* decode(EntityAggregateRequest, body);
+        const entities = new Map(manifest.entities.map((candidate) => [candidate.name, candidate]));
+        const touched = new Set([entity]);
+        const names = [
+            ...request.dimensions,
+            ...(request.filters ?? []).map((filter) => filter.dimension),
+            ...(request.granularityOf === undefined ? [] : [request.granularityOf]),
+            ...(request.orderBy ?? []).flatMap((order) => order.dimension === undefined ? [] : [order.dimension]),
+        ];
+        for (const name of names) {
+            const segments = name.split(".");
+            let current = entities.get(entity);
+            if (segments.some((segment) => segment === "")) {
+                return yield* new InvalidAggregateQuery({ reason: `${name} is not a valid name.` });
+            }
+            for (const relationshipName of segments.slice(0, -1)) {
+                const relationship = current?.relationships.find((candidate) => candidate.name === relationshipName);
+                if (current === undefined || relationship === undefined) {
+                    return yield* new InvalidAggregateQuery({
+                        reason: `${current?.name ?? entity} has no relationship ${relationshipName}.`,
+                    });
+                }
+                if (relationship.cardinality !== "one") {
+                    return yield* new InvalidAggregateQuery({
+                        reason: `${relationshipName} is not a to-one relationship of ${current.name}.`,
+                    });
+                }
+                current = entities.get(relationship.to);
+                touched.add(relationship.to);
+            }
+        }
+        return [...touched].sort();
+    });
+}
+/**
+ * The ontology service's aggregate facade (docs/ontology-aggregates-spec.md, "Surfaces"). Both
+ * routes and the MCP tool run as the caller:
+ * 0. the call counts against the caller's {@link AGGREGATE_LIMIT}, whichever way it came;
+ * 1. the request's shape and bounds are checked, and its names resolved against the service's own
+ *    manifest into every entity it reads;
+ * 2. the caller needs `<entity>:read` on all of them;
+ * 3. the body goes to SegmentStream unchanged with the workspace app credential, naming the entities
+ *    checked, or the answer is `aggregate_unavailable` where the deployment has no credential.
+ */
+export function makeAggregates(input) {
+    const { manifest, transport } = input;
+    const limiter = input.limiter ?? fixedWindowLimiter(AGGREGATE_LIMIT);
+    const run = (request) => Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const requestId = yield* RequestId;
+        const retryAfterSeconds = limiter.take(principal.id);
+        if (retryAfterSeconds !== undefined) {
+            return yield* new AggregateLimited({ retryAfterSeconds });
+        }
+        const touched = yield* request.touchedBy(request.body);
+        const missing = touched
+            .map((entity) => permissionOf(entity, READ_VERB))
+            .filter((permission) => !isAllowed(permission, principal));
+        if (missing.length > 0) {
+            return yield* new ReadDenied({ permissions: missing });
+        }
+        if (transport === undefined) {
+            return yield* new AggregateUnavailable();
+        }
+        return yield* transport({
+            ...(request.entity === undefined ? {} : { entity: request.entity }),
+            body: request.body,
+            requestId,
+            touched,
+        });
+    });
+    return {
+        model: (body) => run({ body, touchedBy: (value) => modelTouched(manifest, value) }),
+        entity: (entity) => (body) => run({ entity, body, touchedBy: (value) => entityTouched(manifest, entity, value) }),
+    };
+}

package/dist/service/api.d.ts

@@ -2,7 +2,7 @@ import { Layer, Schema } from "effect";
 import { HttpApi, HttpApiGroup, HttpApiMiddleware } from "effect/unstable/httpapi";
 import type { Ontology } from "../ontology.js";
 import { RequestId } from "./errors.js";
-import { type ApiPlan } from "./plan.js";
+import { type ApiPlan, type PlannedEntity } from "./plan.js";
 import type { GeneratedActionsProvider } from "./runtime-contract.js";
 import { type EntitySchemas } from "./schemas.js";
 /** The path every ontology route lives under. */
@@ -26,6 +26,8 @@ declare const ErrorResponses_base: HttpApiMiddleware.ServiceClass<ErrorResponses
 export declare class ErrorResponses extends ErrorResponses_base {
 }
 export declare const ErrorResponsesLive: Layer.Layer<ErrorResponses, never, never>;
+/** Whether an entity declares measures, and so has `POST /api/ontology/<entity>/aggregate`. */
+export declare function hasMeasures(planned: PlannedEntity): boolean;
 export interface BuiltApi {
     readonly plan: ApiPlan;
     readonly api: OntologyApi;
@@ -39,8 +41,8 @@ export interface DeriveApiOptions {
 /**
  * The HttpApi of an ontology: per entity `find`, `query`, `get`, `history`, a traversal per
  * relationship and inverse, and a route per generated and authored action; and the catalog, graph,
- * OpenAPI, status, caller (`me`), sign-in check and prose routes. There is no PUT, PATCH or DELETE:
- * every change is an action.
+ * OpenAPI, status, caller (`me`), sign-in check, prose and aggregate routes. There is no PUT, PATCH
+ * or DELETE: every change is an action.
  */
 export declare function deriveApi(ontology: Ontology, options?: DeriveApiOptions): OntologyApi;
 export {};

package/dist/service/api.js

@@ -1,5 +1,6 @@
 import { Effect, Layer, Schema } from "effect";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi, } from "effect/unstable/httpapi";
+import { AGGREGATE_ROUTE } from "../names.js";
 import { storageGroup } from "../storage/api.js";
 import { DownloadRequest, TransferGrant } from "../storage/sessions.js";
 import { permissionOf, READ_VERB } from "../permissions.js";
@@ -8,7 +9,7 @@ import { Authentication } from "./authentication.js";
 import { actionDescription, requires } from "./descriptions.js";
 import { InvalidRequestBody, RequestId, failureResponse } from "./errors.js";
 import { planApi, } from "./plan.js";
-import { ActionResponse, AsParams, Catalog, ErrorSchemas, Graph, HistoryPage, HistoryParams, IdParam, Me, SignInCheckRequest, SignInCheckResult, Status, actionRequest, entitySchemas, } from "./schemas.js";
+import { ActionResponse, AggregateRequest, AggregateResult, EntityAggregateRequest, AsParams, Catalog, ErrorSchemas, Graph, HistoryPage, HistoryParams, IdParam, Me, SignInCheckRequest, SignInCheckResult, Status, actionRequest, entitySchemas, } from "./schemas.js";
 /** The path every ontology route lives under. */
 export const BASE_PATH = "/api/ontology";
 /** The group of the global routes. Entity names are snake_case, so it cannot clash with one. */
@@ -52,6 +53,20 @@ const actionErrors = [
     ErrorSchemas.unprocessable,
     ErrorSchemas.internal,
 ];
+/**
+ * The facade's own refusals. SegmentStream's answers, success and errors alike, pass through as it
+ * sent them: its errors are `{ error, detail, requestId, retryable }`.
+ */
+const aggregateErrors = [
+    ErrorSchemas.invalidRequest,
+    ErrorSchemas.invalidAggregateQuery,
+    ErrorSchemas.readForbidden,
+    ErrorSchemas.unsupportedMediaType,
+    ErrorSchemas.rateLimited,
+    ErrorSchemas.internal,
+    ErrorSchemas.aggregateUpstreamUnavailable,
+    ErrorSchemas.aggregateUnavailable,
+];
 /** An action that calls connections also answers for the connections it could not use. */
 const connectionActionErrors = [
     ...actionErrors,
@@ -62,6 +77,23 @@ const connectionActionErrors = [
 function readPermission(entity) {
     return permissionOf(entity, READ_VERB);
 }
+/** Whether an entity declares measures, and so has `POST /api/ontology/<entity>/aggregate`. */
+export function hasMeasures(planned) {
+    return Object.keys(planned.resolved.entity.definition.measures ?? {}).length > 0;
+}
+/** The per-entity shorthand, which runs as the caller like the model-level route. */
+function entityAggregateEndpoint(planned) {
+    const { plural } = planned.resolved.entity.definition;
+    const endpoint = HttpApiEndpoint.post("aggregate", `${BASE_PATH}/${planned.name}/aggregate`, {
+        payload: EntityAggregateRequest,
+        success: AggregateResult,
+        error: aggregateErrors,
+    });
+    return documented(endpoint, `Aggregate ${plural.toLowerCase()}`, `The entity's measures, with names relative to it: revenue, product.brand. dateRange bounds a ` +
+        "partitioned entity. Requires reading the entity and every entity along each path it " +
+        "groups, filters or orders by. Answered as POST /api/ontology/aggregate is, and counted " +
+        "against the same limit.");
+}
 function traversalEndpoint(planned, traversal, target, targetNames) {
     const label = planned.resolved.entity.definition.label;
     const reach = traversal.kind === "one" ? `one ${targetNames.label}` : `many ${targetNames.plural}`;
@@ -85,11 +117,12 @@ function entityGroup(planned, schemas, names) {
     const own = schemas.get(planned.name);
     const { definition } = planned.resolved.entity;
     const base = `${BASE_PATH}/${planned.name}`;
+    const aggregate = hasMeasures(planned) ? [authenticated(entityAggregateEndpoint(planned))] : [];
     if (definition.source !== undefined) {
         return HttpApiGroup.make(planned.name).add(authenticated(HttpApiEndpoint.get("sourceCollection", base, {
             success: Schema.Never,
             error: recordErrors,
-        })));
+        })), ...aggregate);
     }
     const plural = definition.plural.toLowerCase();
     const read = requires([readPermission(planned.name)]);
@@ -127,7 +160,7 @@ function entityGroup(planned, schemas, names) {
         }), `Download ${property.name}`, `Requires ${planned.name}:read. Historical revisions must belong to this record and field.`)),
         ...planned.actions.map((action) => actionEndpoint(planned, action)),
     ];
-    const [first, ...rest] = endpoints.map(authenticated);
+    const [first, ...rest] = [...endpoints.map(authenticated), ...aggregate];
     return HttpApiGroup.make(planned.name)
         .add(first, ...rest)
         .annotateMerge(OpenApi.annotations({ title: definition.plural, description: definition.description }));
@@ -165,7 +198,20 @@ function serviceGroup() {
     }).middleware(ErrorResponses), "Whether an address may sign in", "Public and rate limited per client address. The app asks before it emails a code or a " +
         "sign-in link. Under the invited policy, an active member's address is allowed: with " +
         "code once they have signed in with Neon Auth, with link before; any other address, " +
-        "deactivated members included, is not. Under open, every address is allowed with link."))
+        "deactivated members included, is not. Under open, every address is allowed with link."), authenticated(documented(HttpApiEndpoint.post("aggregate", `${BASE_PATH}/${AGGREGATE_ROUTE}`, {
+        payload: AggregateRequest,
+        success: AggregateResult,
+        error: aggregateErrors,
+    }), "Aggregate measures across the ontology", "Numbers about the model: measures from several entities, grouped and filtered by " +
+        "properties of related entities. Look at or change records through find and actions; " +
+        "count, sum or compare through aggregate. Names are <entity>.<measure> and " +
+        "<entity>.<property>, or a route from a measure's entity: " +
+        "<entity>.<relationship>.<property>. Requires <entity>:read on every entity the " +
+        "request reads: each measure's entity, and every entity on a dimension's or a " +
+        "filter's route, and at most 30 aggregates a minute per caller, MCP included. The " +
+        "service then forwards the request to SegmentStream, which " +
+        "answers from the warehouse and the replica of stored records; its answer, errors " +
+        "included, is returned unchanged. Preview deployments answer aggregate_unavailable.")))
         .annotateMerge(OpenApi.annotations({ title: SERVICE_GROUP, description: "The ontology as a whole." }));
 }
 export function buildApi(plan) {
@@ -197,8 +243,8 @@ const runtimeGeneratedActions = (entity, ontology) => generatedActions(ontology,
 /**
  * The HttpApi of an ontology: per entity `find`, `query`, `get`, `history`, a traversal per
  * relationship and inverse, and a route per generated and authored action; and the catalog, graph,
- * OpenAPI, status, caller (`me`), sign-in check and prose routes. There is no PUT, PATCH or DELETE:
- * every change is an action.
+ * OpenAPI, status, caller (`me`), sign-in check, prose and aggregate routes. There is no PUT, PATCH
+ * or DELETE: every change is an action.
  */
 export function deriveApi(ontology, options = {}) {
     return buildApi(planApi(ontology, options.generatedActions ?? runtimeGeneratedActions)).api;

package/dist/service/authentication.d.ts

@@ -6,6 +6,7 @@ import type { Principal } from "../runtime.js";
 import type { NeonAuthEnvironment } from "./config.js";
 import { RequestId } from "./errors.js";
 import { OntologyBackend, type SignInIdentity } from "./runtime-contract.js";
+import { type RuntimeCredential, type RuntimeTokenVerifier } from "./runtime-identity.js";
 declare const CurrentPrincipal_base: Context.ServiceClass<CurrentPrincipal, "@segmentstream-cloud/ontology/CurrentPrincipal", Principal>;
 /** The principal the request runs as, provided by {@link Authentication}. */
 export declare class CurrentPrincipal extends CurrentPrincipal_base {
@@ -23,9 +24,10 @@ declare const Authentication_base: HttpApiMiddleware.ServiceClass<Authentication
     readonly bearer: HttpApiSecurity.Http;
 }, CurrentPrincipal, readonly [import("effect/Schema").Top, import("effect/Schema").Top, import("effect/Schema").Top], RequestId>>;
 /**
- * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token
- * or an API key, all as `Authorization: Bearer …`; without one, the app's Neon Auth session cookie.
- * Failures answer the request directly, before its input is decoded.
+ * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token,
+ * an API key or the deployment's runtime token acting as a member, all as `Authorization: Bearer …`;
+ * without one, the app's Neon Auth session cookie. Failures answer the request directly, before its
+ * input is decoded.
  */
 export declare class Authentication extends Authentication_base {
 }
@@ -115,6 +117,9 @@ type Authenticated = {
     readonly status: "rejected";
 } | {
     readonly status: "not_invited";
+} | {
+    readonly status: "forbidden";
+    readonly detail: string;
 } | {
     readonly status: "unavailable";
 };
@@ -125,6 +130,11 @@ export interface CredentialOptions {
      * an access token is rejected, as it was issued for the MCP server only.
      */
     readonly oauthResource?: string;
+    /**
+     * The deployment's own runtime token may authenticate here, acting as the member it names. Without
+     * it a runtime token is just an invalid token.
+     */
+    readonly runtime?: RuntimeCredential;
 }
 /** Resolves a bearer credential to a principal. */
 export declare function authenticate(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier, options?: CredentialOptions): Effect.Effect<Authenticated, never, OntologyBackend>;
@@ -147,7 +157,8 @@ export declare function withPrincipal<E, R>(credential: Redacted.Redacted<string
 }): Effect.Effect<HttpServerResponse.HttpServerResponse, E, Exclude<R, CurrentPrincipal> | RequestId>;
 /**
  * The {@link Authentication} middleware, verifying tokens with `verifyToken`. With `exchangeSession`,
- * a request without a bearer token may authenticate with the app's Neon Auth session cookie.
+ * a request without a bearer token may authenticate with the app's Neon Auth session cookie; with
+ * `verifyRuntime`, the deployment's own runtime token may act as the member it names.
  */
-export declare function authenticationLayer(verifyToken: TokenVerifier, exchangeSession?: SessionExchange): Layer.Layer<Authentication, never, OntologyBackend>;
+export declare function authenticationLayer(verifyToken: TokenVerifier, exchangeSession?: SessionExchange, verifyRuntime?: RuntimeTokenVerifier): Layer.Layer<Authentication, never, OntologyBackend>;
 export {};

package/dist/service/authentication.js

@@ -3,9 +3,10 @@ import { HttpServerRequest } from "effect/unstable/http";
 import { HttpApiMiddleware, HttpApiSecurity, OpenApi } from "effect/unstable/httpapi";
 import { createRemoteJWKSet, decodeJwt, errors, jwtVerify, } from "jose";
 import { API_KEY_PREFIX } from "../runtime/principals.js";
-import { RequestId, crossOriginSession, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
+import { RequestId, crossOriginSession, forbidden, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
 import { ACCESS_TOKEN_PREFIX, principalOfAccessToken } from "./oauth/protocol.js";
 import { OntologyBackend } from "./runtime-contract.js";
+import { ACT_AS_HEADER, logRuntimeRejection, runtimeCredential, } from "./runtime-identity.js";
 import { ErrorSchemas } from "./schemas.js";
 const CLOCK_TOLERANCE_SECONDS = 5;
 const JWKS_TIMEOUT_MS = 5_000;
@@ -13,9 +14,10 @@ const JWKS_TIMEOUT_MS = 5_000;
 export class CurrentPrincipal extends Context.Service()("@segmentstream-cloud/ontology/CurrentPrincipal") {
 }
 /**
- * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token
- * or an API key, all as `Authorization: Bearer …`; without one, the app's Neon Auth session cookie.
- * Failures answer the request directly, before its input is decoded.
+ * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token,
+ * an API key or the deployment's runtime token acting as a member, all as `Authorization: Bearer …`;
+ * without one, the app's Neon Auth session cookie. Failures answer the request directly, before its
+ * input is decoded.
  */
 export class Authentication extends HttpApiMiddleware.Service()("@segmentstream-cloud/ontology/Authentication", {
     security: {
@@ -274,6 +276,29 @@ function sessionMayAuthenticate(request) {
     const origin = request.headers.origin;
     return origin !== undefined && origin === requestOrigin(request);
 }
+/**
+ * The member a verified runtime caller acts for: the member `X-SegmentStream-Act-As` names, with the
+ * roles they hold now, while they are active and paired with the agent. Without the header, the
+ * runtime may call only the agent's own routes, which authenticate it themselves.
+ */
+function actingMember(actAs) {
+    return Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        if (actAs === undefined) {
+            return {
+                status: "forbidden",
+                detail: `The app's agent names the member it acts for in ${ACT_AS_HEADER}.`,
+            };
+        }
+        const member = backend.agents === undefined ? undefined : yield* backend.agents.actingMember(actAs);
+        return member === undefined
+            ? {
+                status: "forbidden",
+                detail: "The member is inactive or has not paired with the app's agent.",
+            }
+            : { status: "authenticated", principal: member };
+    });
+}
 /** Resolves a bearer credential to a principal. */
 export function authenticate(credential, verifyToken, options = {}) {
     return Effect.gen(function* () {
@@ -296,6 +321,21 @@ export function authenticate(credential, verifyToken, options = {}) {
                 ? { status: "rejected" }
                 : { status: "authenticated", principal: service };
         }
+        if (options.runtime !== undefined) {
+            const { verify, actAs } = options.runtime;
+            const runtime = yield* Effect.promise(() => verify(token));
+            switch (runtime.status) {
+                case "valid":
+                    return yield* actingMember(actAs);
+                case "invalid":
+                    yield* logRuntimeRejection(runtime.reason);
+                    return { status: "rejected" };
+                case "unavailable":
+                    return { status: "unavailable" };
+                case "other":
+                    break;
+            }
+        }
         const verification = yield* Effect.promise(() => verifyToken(token));
         if (verification.status !== "valid") {
             return verification.status === "invalid"
@@ -358,6 +398,8 @@ export function withPrincipal(credential, verifyToken, backend, effect, options
                 return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked.", options.challenge?.(false)));
             case "not_invited":
                 return toServerResponse(notInvited(requestId));
+            case "forbidden":
+                return toServerResponse(forbidden(requestId, outcome.detail));
             case "cross_origin":
                 return toServerResponse(crossOriginSession(requestId));
             case "unavailable":
@@ -369,16 +411,19 @@ export function withPrincipal(credential, verifyToken, backend, effect, options
 }
 /**
  * The {@link Authentication} middleware, verifying tokens with `verifyToken`. With `exchangeSession`,
- * a request without a bearer token may authenticate with the app's Neon Auth session cookie.
+ * a request without a bearer token may authenticate with the app's Neon Auth session cookie; with
+ * `verifyRuntime`, the deployment's own runtime token may act as the member it names.
  */
-export function authenticationLayer(verifyToken, exchangeSession) {
+export function authenticationLayer(verifyToken, exchangeSession, verifyRuntime) {
     return Layer.effect(Authentication, Effect.gen(function* () {
         const backend = yield* OntologyBackend;
         return Authentication.of({
             bearer: (httpEffect, { credential }) => Effect.gen(function* () {
                 const request = yield* HttpServerRequest.HttpServerRequest;
+                const runtime = runtimeCredential(verifyRuntime, request);
                 return yield* withPrincipal(credential, verifyToken, backend, httpEffect, {
                     session: { request, exchange: exchangeSession },
+                    ...(runtime === undefined ? {} : { runtime }),
                 });
             }),
         });

package/dist/service/catalog.d.ts

@@ -1,4 +1,4 @@
-import type { OntologyManifest } from "../manifest.js";
+import { type OntologyManifest } from "../manifest.js";
 /**
  * The catalog for a reader: the manifest, with each entity's actions narrowed to the ones the given
  * permissions may run. Without permissions it is the manifest itself.
@@ -10,6 +10,15 @@ export interface GraphRelationship {
     readonly to: string;
     readonly inverse: string;
     readonly cardinality: "one" | "many";
+    /** The property pair of a relationship matched by value: one with a warehouse-backed end. */
+    readonly on?: {
+        readonly property: string;
+        readonly targetProperty: string;
+    };
+    /**
+     * Whether the relationship may lead to nothing. Only a stored → stored `rel.one` can promise a
+     * record; a value-matched reference is never checked against its target.
+     */
     readonly optional: boolean;
     readonly phrase: readonly [string, string];
     /** The relationship read from the declaring entity: "Lead is owned by one User". */

package/dist/service/catalog.js

@@ -1,3 +1,4 @@
+import { isValueMatched } from "../manifest.js";
 import { isAllowed } from "../permissions.js";
 import { actionPermission } from "../render.js";
 /**
@@ -33,8 +34,15 @@ export function graphOf(manifest) {
         relationships: manifest.entities.flatMap((source) => source.relationships.map((relationship) => {
             const target = entities.get(relationship.to);
             const targetLabel = target?.label ?? relationship.to;
+            // Manifests before version 5 wrote `optional` on warehouse → stored relationships too.
+            const valueMatched = isValueMatched(relationship) ||
+                source.source !== undefined ||
+                target?.source !== undefined;
+            // As describe phrases them: nothing promises a value-matched relationship a record.
+            const one = valueMatched ? "at most one" : "one";
+            const many = valueMatched ? "" : "many ";
             const forwardTarget = relationship.cardinality === "one"
-                ? `one ${targetLabel}`
+                ? `${one} ${targetLabel}`
                 : `many ${target?.plural ?? relationship.to}`;
             return {
                 from: source.name,
@@ -42,10 +50,11 @@ export function graphOf(manifest) {
                 to: relationship.to,
                 inverse: relationship.inverse,
                 cardinality: relationship.cardinality,
-                optional: relationship.cardinality === "many" || relationship.optional === true,
+                ...(relationship.on !== undefined ? { on: relationship.on } : {}),
+                optional: relationship.cardinality === "many" || valueMatched || relationship.optional === true,
                 phrase: relationship.phrase,
                 forward: `${source.label} ${relationship.phrase[0]} ${forwardTarget}`,
-                backward: `${targetLabel} ${relationship.phrase[1]} many ${source.plural}`,
+                backward: `${targetLabel} ${relationship.phrase[1]} ${many}${source.plural}`,
                 description: relationship.description,
             };
         })),

package/dist/service/config.d.ts

@@ -3,6 +3,7 @@ import { BlobStorageBinding } from "../storage/provider.js";
 import type { Principal } from "../runtime.js";
 import { type ConnectionTransportFactory, type LocalConnectionContext } from "./connections.js";
 import type { OntologyServiceRuntime } from "./runtime-contract.js";
+import type { RuntimeIdentityConfig } from "./runtime-identity.js";
 /** The environment of the workspace deployment's ontology service. */
 export declare const ENVIRONMENT_VARIABLES: {
     readonly databaseUrl: "SEGMENTSTREAM_ONTOLOGY_DATABASE_URL";
@@ -11,6 +12,12 @@ export declare const ENVIRONMENT_VARIABLES: {
     readonly workspaceId: "SEGMENTSTREAM_WORKSPACE_ID";
     readonly organizationId: "SEGMENTSTREAM_ORGANIZATION_ID";
 };
+/**
+ * The workspace app credential (`ssw_…`), which Vercel injects into every service of a production
+ * deployment. The service forwards aggregates to SegmentStream with it; without it, aggregates are
+ * unavailable and everything else works.
+ */
+export declare const APP_CREDENTIAL_VARIABLE = "SEGMENTSTREAM_APP_CREDENTIAL";
 /**
  * The workspace's Neon Auth, which signs the app's users in. Provisioning sets both on workspaces
  * that have it; a service without them accepts SegmentStream app tokens and API keys only.
@@ -19,6 +26,17 @@ export declare const NEON_AUTH_ENVIRONMENT_VARIABLES: {
     readonly baseUrl: "NEON_AUTH_BASE_URL";
     readonly jwksUrl: "NEON_AUTH_JWKS_URL";
 };
+/**
+ * The deployment's own runtime callers, such as the app's agent: the issuer and the audience of the
+ * team's Vercel OIDC tokens, set together by the platform on deployments that have an agent. Without
+ * them a runtime token is an invalid token. Tokens must also name the project in Vercel's
+ * `VERCEL_PROJECT_ID`, as the agent runs in the same Vercel project as the ontology service.
+ */
+export declare const RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES: {
+    readonly issuer: "SEGMENTSTREAM_RUNTIME_OIDC_ISSUER";
+    readonly audience: "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE";
+    readonly projectId: "VERCEL_PROJECT_ID";
+};
 /** Where the workspace's Neon Auth issues and publishes the keys of its users' tokens. */
 export interface NeonAuthEnvironment {
     /** The Auth URL, such as `https://ep-….neon.tech/ontology/auth`. Its origin is the issuer. */
@@ -38,8 +56,18 @@ export interface OntologyEnvironment {
     readonly applicationId: string;
     readonly workspaceId: string;
     readonly organizationId: string;
+    /**
+     * The workspace app credential. With it, `/api/ontology/aggregate` forwards to SegmentStream at
+     * `segmentstreamUrl` for `workspaceId`; previews and local development have none.
+     */
+    readonly appCredential?: Redacted.Redacted<string>;
     /** Present once the workspace has Neon Auth: members then sign in with its tokens. */
     readonly neonAuth?: NeonAuthEnvironment;
+    /**
+     * Present on deployments with a runtime caller: the deployment's own Vercel OIDC tokens then
+     * authenticate, acting as the member `X-SegmentStream-Act-As` names.
+     */
+    readonly runtimeIdentity?: RuntimeIdentityConfig;
     /**
      * The local grant `segmentstream exec --connection …` passed, in development. Without it, actions
      * call connections through SegmentStream with the deployment's Vercel OIDC token.
@@ -88,7 +116,8 @@ export declare class OntologyServiceConfigError extends OntologyServiceConfigErr
 /**
  * Reads the service's configuration from the environment. It fails closed: a missing or invalid
  * variable throws {@link OntologyServiceConfigError} naming every missing variable, and never the
- * value of the database URL. The Neon Auth variables are optional, but only as a pair.
+ * value of the database URL. The Neon Auth and runtime identity variables are optional, but only as
+ * pairs. The app credential is optional and kept redacted.
  */
 export declare function configFromEnv(environment?: Readonly<Record<string, string | undefined>>): OntologyEnvironment;
 export {};