@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/service.js

@@ -0,0 +1,526 @@
+import { Cause, Context, Effect, Layer, Redacted } from "effect";
+import { HttpRouter, HttpServer, HttpServerError, HttpServerRequest } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { storageMaintenanceAuthenticationLayer } from "../storage/maintenance-auth.js";
+import { validateDeploymentStorage } from "../storage/provider.js";
+import { captureRuntimeFailure } from "../internal/diagnostics.js";
+import { deploymentFromEnv, DeploymentAdmissionError, requireDeploymentCapability, } from "../deployment.js";
+import { RuntimeDeployment } from "../runtime/deployment.js";
+import { nameToWire } from "../authoring-names.js";
+import { bundledNavigationCatalog } from "../navigation-artifact.js";
+import { parsePageCatalog } from "../navigation-catalog.js";
+import { isAllowed } from "../permissions.js";
+import { sqlServiceRuntime } from "../runtime/service-binding.js";
+import { neonSignInLinks, segmentstreamSignInLinks } from "../runtime/sign-in-links.js";
+import { memberFileRoutes } from "./member-file-routes.js";
+import { attachmentsLayer } from "./agent/attachments.js";
+import { filesLayer } from "./agent/files.js";
+import { platformConversations } from "./agent/conversations.js";
+import { conversationRoutes } from "./agent/conversation-routes.js";
+import { makeChatDelivery } from "./chat/delivery.js";
+import { platformDeliveryArchive } from "./chat/archive.js";
+import { chatRoutes } from "./chat/routes.js";
+import { agentLayer } from "./agent/server.js";
+import { agentTasksLayer } from "./agent/tasks.js";
+import { makeMetricQueries } from "./metric-query.js";
+import { platformMetricQueries } from "./metric-query-platform.js";
+import { platformWarehouseQueries, WarehouseQueries } from "./warehouse-platform.js";
+import { ErrorResponsesLive, buildApi } from "./api.js";
+import { CurrentPrincipal, authenticationLayer, neonAuthSessionExchange, tokenVerifier, withPrincipal, } from "./authentication.js";
+import { currentCaller } from "./caller-context.js";
+import { OntologyServiceConfigError, } from "./config.js";
+import { RequestId, failureResponse, internalError, errorBodyForWire, routeNotFound, toServerResponse, } from "./errors.js";
+import { deployedConnections, localConnections } from "./connections.js";
+import { DocsRoute } from "./docs.js";
+import { handlersLayer } from "./handlers.js";
+import { deployedReplication } from "./replication.js";
+import { mcpLayer } from "./mcp/server.js";
+import { runtimeAllows } from "./mcp/runtime-policy.js";
+import { suggestNames } from "./name-suggestions.js";
+import { observeMcpRequest } from "./mcp/request-log.js";
+import { oauthLayer } from "./oauth/server.js";
+import { federationLayer } from "./federation-server.js";
+import { channelSessionLayer } from "./channel/sessions.js";
+import { channelSignInLayer } from "./channel/sign-in.js";
+import { telegramAppProvider } from "./channel/providers/telegram.js";
+import { planApi } from "./plan.js";
+import { deployedWebhookTokenVerifier, deployedWebhookVerifier } from "./webhooks.js";
+import { vercelWorkflowEngine, workflowStarter, workflowsLayer } from "./workflows.js";
+import { deploymentWorkflowEngine } from "./workflow-deployment.js";
+import { OntologyBackend } from "./runtime-contract.js";
+import { runtimeCredential, runtimeTokenVerifier, } from "./runtime-identity.js";
+/** The header every response carries: the hash of the manifest the service serves. */
+export const ONTOLOGY_HASH_HEADER = "x-ontology-hash";
+/** The header every response carries: the correlation id quoted in error bodies and logs. */
+export const REQUEST_ID_HEADER = "x-request-id";
+function runtimeFailureValues(config) {
+    const storage = config.blobStorage ? Redacted.value(config.blobStorage) : undefined;
+    const password = URL.parse(Redacted.value(config.databaseUrl))?.password;
+    let decodedPassword = password;
+    try {
+        decodedPassword = password === undefined ? undefined : decodeURIComponent(password);
+    }
+    catch {
+        // Diagnostic redaction must not replace the original failure on an invalid URI escape.
+    }
+    return [
+        Redacted.value(config.databaseUrl),
+        password,
+        decodedPassword,
+        config.appCredential ? Redacted.value(config.appCredential) : undefined,
+        config.cronSecret ? Redacted.value(config.cronSecret) : undefined,
+        config.webhookSecret ? Redacted.value(config.webhookSecret) : undefined,
+        config.storageMaintenanceKey ? Redacted.value(config.storageMaintenanceKey) : undefined,
+        storage?.accessKeyId,
+        storage?.secretAccessKey,
+    ];
+}
+function afterCommitHooks(plan, hooks = {}) {
+    const actions = new Set(plan.entities.flatMap(({ name, actions: planned }) => planned.map((action) => `${name}.${action.name}`)));
+    const entries = Object.entries(hooks).map(([key, hook]) => [key.split(".").map(nameToWire).join("."), hook]);
+    const unknown = Object.keys(hooks).filter((key) => !actions.has(key.split(".").map(nameToWire).join(".")));
+    if (unknown.length > 0) {
+        throw new OntologyServiceConfigError({
+            message: `afterCommit names actions the ontology does not have: ${unknown.join(", ")}.`,
+        });
+    }
+    if (new Set(entries.map(([key]) => key)).size !== entries.length) {
+        throw new OntologyServiceConfigError({
+            message: "afterCommit names collide after snake_case conversion.",
+        });
+    }
+    return new Map(entries);
+}
+/**
+ * Requests that match no route, and defects that escape a route's own error handling, still get a
+ * JSON error with the request id.
+ */
+function unmatchedRoutes(plan, verifyToken, exchangeSession, verifyRuntime) {
+    return Layer.unwrap(Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        return HttpRouter.middleware()((httpEffect) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const request = yield* HttpServerRequest.HttpServerRequest;
+            const bare = toServerResponse(routeNotFound(requestId));
+            const notFound = Effect.gen(function* () {
+                if (request.method !== "POST") {
+                    return bare;
+                }
+                const url = new URL(request.url, "http://ontology.local");
+                const path = url.pathname;
+                const match = /^\/api\/ontology\/([a-z][a-z0-9_]*)\/actions\/([A-Za-z][A-Za-z0-9_]*)$/.exec(path);
+                const entity = match === null ? undefined : plan.entities.find(({ name }) => name === match[1]);
+                if (match === null || entity === undefined) {
+                    return bare;
+                }
+                // Route matching precedes Authentication. Reuse its credential/session checks, but keep
+                // the original bare 404 for every authentication failure on an unmatched route.
+                const credential = yield* HttpApiBuilder.securityDecode(HttpApiSecurity.bearer).pipe(Effect.provideService(HttpServerRequest.ParsedSearchParams, HttpServerRequest.searchParamsFromURL(url)));
+                const runtime = runtimeCredential(verifyRuntime, request);
+                const authenticated = yield* withPrincipal(credential, verifyToken, backend, Effect.gen(function* () {
+                    const principal = yield* CurrentPrincipal;
+                    const caller = yield* currentCaller;
+                    const visible = entity.actions.filter((action) => action.permissions.every((permission) => isAllowed(permission, principal)) &&
+                        runtimeAllows(caller, { entity: entity.name, action: action.name }));
+                    const suggestions = suggestNames(match[2], visible.map(({ name }) => name));
+                    return toServerResponse(routeNotFound(requestId, suggestions));
+                }), {
+                    session: { request, exchange: exchangeSession },
+                    ...(runtime === undefined ? {} : { runtime }),
+                });
+                return authenticated.status === 404 ? authenticated : bare;
+            });
+            return yield* httpEffect.pipe(Effect.catchIf(HttpServerError.isHttpServerError, (error) => error.reason instanceof HttpServerError.RouteNotFound
+                ? notFound
+                : failureResponse(Cause.fail(error), requestId)), Effect.catchDefect((defect) => failureResponse(Cause.die(defect), requestId)));
+        }), { global: true });
+    }));
+}
+function decorate(response, requestId, hash, durationMs) {
+    const headers = new Headers(response.headers);
+    headers.set(ONTOLOGY_HASH_HEADER, hash);
+    headers.set(REQUEST_ID_HEADER, requestId);
+    headers.append("server-timing", `ontology;dur=${durationMs}`);
+    if (!headers.get("content-type")?.startsWith("text/event-stream")) {
+        headers.set("cache-control", "private, no-store");
+    }
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+/**
+ * The ontology service: the derived HttpApi, the MCP server at `/mcp` and the agent's pairing routes,
+ * wired to the runtime, behind Neon Auth, app-token, API-key and runtime-token authentication.
+ * Every response carries `x-ontology-hash`
+ * and `x-request-id`; failures answer with a JSON error and never a stack or SQL.
+ */
+export function createOntologyService(ontology, config) {
+    const ambient = deploymentFromEnv();
+    const requested = ambient.target === "preview" ? ambient : (config.deployment ?? ambient);
+    const deployment = deploymentFromEnv({
+        SEGMENTSTREAM_DEPLOYMENT_TARGET: requested.target,
+        SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID: requested.deploymentId,
+        SEGMENTSTREAM_PREVIEW_EXPIRES_AT: requested.target === "preview" ? requested.expiresAt : undefined,
+        SEGMENTSTREAM_PREVIEW_HOST: requested.target === "preview" ? requested.host : undefined,
+    });
+    const preview = deployment.target === "preview";
+    config = {
+        ...config,
+        deployment,
+        ...(preview
+            ? {
+                oidc: ontology.signIn.browser ? config.oidc : undefined,
+                runtimeIdentity: undefined,
+                localConnections: undefined,
+                cronSecret: undefined,
+                agentOrigin: undefined,
+                channels: undefined,
+                channelAppProviders: undefined,
+            }
+            : {}),
+    };
+    if (preview && !config.neonAuth && !ontology.signIn.browser?.methods.includes("segmentstream")) {
+        throw new DeploymentAdmissionError("preview_configuration_invalid");
+    }
+    if (preview && config.blobStorage) {
+        validateDeploymentStorage(Redacted.value(config.blobStorage), deployment);
+    }
+    const bundledNavigation = bundledNavigationCatalog();
+    if (bundledNavigation !== undefined &&
+        config.navigation !== undefined &&
+        JSON.stringify(parsePageCatalog(config.navigation)) !== JSON.stringify(bundledNavigation)) {
+        throw new OntologyServiceConfigError({ message: "navigation_catalog_override" });
+    }
+    const navigation = bundledNavigation ?? config.navigation;
+    const telegram = config.channels?.telegram;
+    const testKey = telegram?.miniApp?.testPublicKeyHex;
+    const telegramConnection = ontology.manifest.chat?.telegram?.connection;
+    if (telegram?.miniApp && (!telegramConnection || telegram.connection !== telegramConnection)) {
+        throw new OntologyServiceConfigError({ message: "invalid_channel_connection" });
+    }
+    if (testKey !== undefined && !/^[0-9a-f]{64}$/i.test(testKey)) {
+        throw new OntologyServiceConfigError({ message: "invalid_channel_test_key" });
+    }
+    const channelApps = [
+        ...(config.channelAppProviders ?? []),
+        ...(telegram?.miniApp && telegramConnection
+            ? [telegramAppProvider(telegramConnection, testKey)]
+            : []),
+    ];
+    if (channelApps.some((adapter, i) => !/^[a-z][a-z0-9_-]{0,63}$/.test(adapter.provider) ||
+        channelApps.findIndex((other) => other.provider === adapter.provider) !== i ||
+        adapter.provider === "logout")) {
+        throw new OntologyServiceConfigError({ message: "invalid_channel_provider" });
+    }
+    if (config.mcpStreamMaxDurationMs !== undefined &&
+        (!Number.isInteger(config.mcpStreamMaxDurationMs) ||
+            config.mcpStreamMaxDurationMs <= 0 ||
+            config.mcpStreamMaxDurationMs > 2_147_483_647)) {
+        throw new OntologyServiceConfigError({
+            message: "mcpStreamMaxDurationMs must be a positive integer within the timer range.",
+        });
+    }
+    if (config.blobStorage &&
+        (!config.storageMaintenanceKey || Redacted.value(config.storageMaintenanceKey).length < 32)) {
+        throw new OntologyServiceConfigError({
+            message: "File storage requires a deployment maintenance credential of at least 32 characters.",
+        });
+    }
+    if (config.oauthRefreshReuseGraceMs !== undefined &&
+        (!Number.isFinite(config.oauthRefreshReuseGraceMs) || config.oauthRefreshReuseGraceMs < 0)) {
+        throw new OntologyServiceConfigError({
+            message: "OAuth refresh reuse grace must be nonnegative milliseconds.",
+        });
+    }
+    const browser = ontology.signIn.browser;
+    if (browser) {
+        if (!config.browserRevisionClientId) {
+            throw new OntologyServiceConfigError({ message: "browser_auth_revision_missing" });
+        }
+        const binding = config.browserAuth;
+        const expected = {
+            methods: browser.methods,
+            primary: browser.primary,
+            auto_redirect: browser.autoRedirect,
+            ...(browser.local ? { local: browser.local } : {}),
+        };
+        if (binding?.version !== 1 ||
+            binding.manifest_digest !== ontology.manifest.hash ||
+            JSON.stringify(binding.browser, ["methods", "primary", "auto_redirect", "local", "port"]) !==
+                JSON.stringify(expected, ["methods", "primary", "auto_redirect", "local", "port"])) {
+            throw new OntologyServiceConfigError({ message: "browser_auth_binding_mismatch" });
+        }
+        if (browser.methods.includes("segmentstream") &&
+            config.browserEnvironment !== "local" &&
+            !deployment.deploymentId) {
+            throw new OntologyServiceConfigError({ message: "browser_auth_deployment_missing" });
+        }
+        if (browser.methods.includes("segmentstream") && !config.oidc) {
+            throw new OntologyServiceConfigError({ message: "browser_auth_provider_missing" });
+        }
+    }
+    const runtime = config.runtime ?? sqlServiceRuntime;
+    const plan = planApi(ontology, runtime.generatedActions);
+    const built = buildApi(plan);
+    const hooks = afterCommitHooks(plan, preview ? {} : config.afterCommit);
+    const federationConfig = config.oidc && browser
+        ? {
+            ...config.oidc,
+            environment: config.browserEnvironment ?? deployment.target,
+            deploymentId: config.browserEnvironment === "local" ? undefined : deployment.deploymentId,
+            manifestDigest: ontology.manifest.hash,
+        }
+        : config.oidc;
+    const browserRevision = browser
+        ? {
+            issuer: config.browserRevisionIssuer ??
+                config.oidc?.issuer ??
+                `${new URL(config.segmentstreamUrl).origin}/oidc`,
+            clientId: config.browserRevisionClientId,
+            manifestDigest: ontology.manifest.hash,
+            ...(config.browserEnvironment !== "local" ? { deploymentId: deployment.deploymentId } : {}),
+        }
+        : undefined;
+    const verifyToken = tokenVerifier({
+        ...config,
+        browserRevision,
+        ...(browser ? { browserMethods: browser.methods, oidc: federationConfig } : {}),
+    });
+    const exchangeSession = config.neonAuth === undefined || (browser && !browser.methods.includes("email"))
+        ? undefined
+        : neonAuthSessionExchange(config.neonAuth);
+    const verifyRuntime = config.runtimeIdentity === undefined ? undefined : runtimeTokenVerifier(config.runtimeIdentity);
+    const workflowEngine = deploymentWorkflowEngine(config.workflowEngine ?? vercelWorkflowEngine, deployment);
+    const backend = runtime.connect({
+        deployment,
+        ontology,
+        databaseUrl: config.databaseUrl,
+        ...(config.blobStorage ? { blobStorage: config.blobStorage } : {}),
+        workflowStarter: workflowStarter(ontology, workflowEngine),
+        ...(browser &&
+            !browser.methods.includes("email") &&
+            !preview &&
+            config.browserEnvironment !== "local" &&
+            config.agentOrigin
+            ? {
+                signInLinks: segmentstreamSignInLinks({
+                    segmentstreamUrl: config.segmentstreamUrl,
+                    workspaceId: config.workspaceId,
+                    organizationId: config.organizationId,
+                    identityToken: () => process.env.VERCEL_OIDC_TOKEN,
+                }),
+            }
+            : {}),
+        // Links open the production app, so previews, which have no production origin, send none.
+        ...((!browser || browser.methods.includes("email")) &&
+            config.neonAuth !== undefined &&
+            config.agentOrigin !== undefined &&
+            config.browserEnvironment !== "local" &&
+            !preview
+            ? {
+                signInLinks: neonSignInLinks({
+                    baseUrl: config.neonAuth.baseUrl,
+                    origin: config.agentOrigin,
+                }),
+            }
+            : {}),
+    });
+    const connections = preview
+        ? () => ({
+            request: () => Effect.die(new DeploymentAdmissionError("preview_capability_unavailable", "connections")),
+            stream: () => Effect.die(new DeploymentAdmissionError("preview_capability_unavailable", "connections")),
+        })
+        : (config.connections ??
+            (config.localConnections === undefined
+                ? deployedConnections(config)
+                : localConnections(config.localConnections)));
+    const replicate = deployedReplication(config);
+    const chatDelivery = makeChatDelivery(ontology, connections, config.chatArchive ?? platformDeliveryArchive(config), { settings: config.channels?.telegram, ownOrigins: config.appOrigins });
+    const conversations = config.runtimeIdentity === undefined ? undefined : platformConversations(config);
+    const metricQueries = makeMetricQueries({
+        ontology,
+        transport: platformMetricQueries({ ...config, manifestHash: ontology.manifest.hash }),
+    });
+    const routes = HttpApiBuilder.layer(built.api).pipe(Layer.provide(handlersLayer(built, hooks, connections, replicate, metricQueries, chatDelivery, preview || deployment.deploymentId ? deployment : undefined)), Layer.provide([
+        authenticationLayer(verifyToken, exchangeSession, verifyRuntime),
+        ErrorResponsesLive,
+        storageMaintenanceAuthenticationLayer(config.storageMaintenanceKey),
+    ]));
+    const mcp = config.mcp === false
+        ? Layer.empty
+        : Layer.mergeAll(mcpLayer({
+            built,
+            hooks,
+            connections,
+            verifyToken,
+            verifyRuntime,
+            replicate,
+            metricQueries,
+            chatDelivery,
+            conversations,
+            ...(navigation === undefined ? {} : { navigation }),
+            appOrigins: config.appOrigins,
+            streamMaxDurationMs: config.mcpStreamMaxDurationMs,
+            workspaceId: config.workspaceId,
+            decide: config.decisions,
+        }), preview
+            ? Layer.empty
+            : oauthLayer({ verifyToken, refreshReuseGraceMs: config.oauthRefreshReuseGraceMs }));
+    const agent = preview ? Layer.empty : agentLayer({ verifyToken, verifyRuntime, exchangeSession });
+    const agentTasks = preview
+        ? Layer.empty
+        : agentTasksLayer({
+            verifyToken,
+            verifyRuntime,
+            workspaceId: config.workspaceId,
+            engine: config.workflowEngine ?? vercelWorkflowEngine,
+        });
+    const attachments = preview
+        ? Layer.empty
+        : attachmentsLayer({
+            plan: built.plan,
+            hooks,
+            connections,
+            replicate,
+            verifyToken,
+            verifyRuntime,
+        });
+    const application = Layer.mergeAll(channelApps.length > 0
+        ? Layer.merge(channelSessionLayer(config), channelSignInLayer(channelApps, config, connections))
+        : Layer.empty, federationLayer(federationConfig, verifyToken, { ontology, browserRevision }), routes, preview
+        ? Layer.empty
+        : chatRoutes({
+            built,
+            hooks,
+            connections,
+            replicate,
+            chatDelivery,
+            conversations,
+            verifyToken,
+            verifyRuntime,
+            exchangeSession,
+        }), mcp, agent, agentTasks, attachments, memberFileRoutes({
+        plan: built.plan,
+        hooks,
+        connections,
+        replicate,
+        chatDelivery,
+        verifyToken,
+        exchangeSession,
+    }), preview ? Layer.empty : filesLayer({ plan: built.plan, verifyRuntime }), conversations === undefined
+        ? Layer.empty
+        : conversationRoutes({
+            transport: conversations,
+            verifyToken,
+            verifyRuntime,
+            exchangeSession,
+        }), workflowsLayer({
+        deployment,
+        plan: built.plan,
+        hooks,
+        connections,
+        replicate,
+        chatDelivery,
+        verifyToken,
+        verifyRuntime,
+        exchangeSession,
+        workspaceId: config.workspaceId,
+        cronSecret: config.cronSecret,
+        engine: workflowEngine,
+        agentOrigin: config.agentOrigin,
+        agentTransport: config.agentTaskTransport,
+        webhookSecret: config.webhookSecret,
+        webhookVerifier: config.webhookVerifier ??
+            deployedWebhookVerifier({
+                segmentstreamUrl: config.segmentstreamUrl,
+                workspaceId: config.workspaceId,
+                organizationId: config.organizationId,
+                deploymentId: deployment.deploymentId,
+                ...(preview ? { previewCredential: config.appCredential } : {}),
+            }),
+        webhookTokenVerifier: config.webhookTokenVerifier ??
+            deployedWebhookTokenVerifier({
+                segmentstreamUrl: config.segmentstreamUrl,
+                workspaceId: config.workspaceId,
+                organizationId: config.organizationId,
+                deploymentId: deployment.deploymentId,
+                ...(preview ? { previewCredential: config.appCredential } : {}),
+            }),
+    }), DocsRoute, unmatchedRoutes(plan, verifyToken, exchangeSession, verifyRuntime)).pipe(Layer.provide(Layer.succeed(RuntimeDeployment, deployment)), Layer.provide(backend), Layer.provide(Layer.succeed(WarehouseQueries)(config.warehouseQueries ??
+        platformWarehouseQueries({ ...config, manifestHash: ontology.manifest.hash }))), Layer.provide(HttpServer.layerServices));
+    const web = HttpRouter.toWebHandler(application, { disableLogger: true });
+    const hash = ontology.manifest.hash;
+    // Only names from the deployed plan enter diagnostics; arbitrary path segments may be private.
+    function operationOf(request) {
+        const path = new URL(request.url).pathname;
+        const parts = path.split("/");
+        const entity = plan.entities.find((candidate) => candidate.name === parts[3]);
+        if (parts[1] === "api" && parts[2] === "ontology" && entity !== undefined) {
+            return `/api/ontology/${entity.name}/*`;
+        }
+        if (parts[1] === "api" && parts[2] === "webhooks") {
+            const declared = ontology.workflows.some((workflow) => workflow.triggers.some((trigger) => trigger.kind === "webhook" && trigger.name === parts[3]));
+            // Never the token segment.
+            return declared ? `/api/webhooks/${parts[3]}` : "/api/webhooks/*";
+        }
+        return path === "/mcp" ? "/mcp" : "/api/ontology/*";
+    }
+    return {
+        api: built.api,
+        dispose: web.dispose,
+        async handler(request) {
+            const started = performance.now();
+            const requestId = crypto.randomUUID();
+            const logMcpRequest = observeMcpRequest(request);
+            let response;
+            try {
+                requireDeploymentCapability(deployment);
+                if (preview) {
+                    const path = new URL(request.url).pathname;
+                    const blocked = /^\/api\/ontology\/(?:agent|agents|chat|conversations|attachments|channels)(?:\/|$)/.test(path)
+                        ? "agents"
+                        : undefined;
+                    if (blocked) {
+                        throw new DeploymentAdmissionError("preview_capability_unavailable", blocked);
+                    }
+                    if (/^\/api\/ontology\/(?:oauth|oidc)(?:\/|$)/.test(path) ||
+                        (!browser && /^\/api\/ontology\/federation(?:\/|$)/.test(path)) ||
+                        path.startsWith("/.well-known/oauth")) {
+                        throw new DeploymentAdmissionError("preview_authentication_unavailable");
+                    }
+                }
+                response = await web.handler(request, Context.make(RequestId, requestId));
+            }
+            catch (error) {
+                if (error instanceof DeploymentAdmissionError) {
+                    response = Response.json({
+                        error: error.code,
+                        detail: error.code,
+                        request_id: requestId,
+                        ...(error.capability ? { capability: error.capability } : {}),
+                    }, { status: error.status });
+                }
+                else {
+                    // The runtime could not be built or the router itself failed: log everything, answer little.
+                    captureRuntimeFailure(error, { service: "ontology", boundary: "ontology.request.failed", requestId }, process.env, runtimeFailureValues(config));
+                    const failure = internalError(requestId);
+                    response = Response.json(errorBodyForWire(failure.body), { status: failure.status });
+                }
+            }
+            const durationMs = Math.round((performance.now() - started) * 100) / 100;
+            const timing = {
+                requestId,
+                at: new Date().toISOString(),
+                operation: operationOf(request),
+                method: request.method,
+                status: response.status,
+                durationMs,
+            };
+            console.info(JSON.stringify({ event: "ontology.request", ...timing }));
+            await logMcpRequest?.(response, requestId, durationMs);
+            return decorate(response, requestId, hash, durationMs);
+        },
+    };
+}

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

@@ -0,0 +1,17 @@
+import { Context, Effect } from "effect";
+import type { StoredRecord } from "../runtime.js";
+import { type MetricQueryEnvironment } from "./metric-query-platform.js";
+import { WarehouseReadUnavailable } from "./errors.js";
+import type { WarehouseStatement } from "./warehouse-query.js";
+export type WarehouseReadTransport = (input: {
+    readonly statement: WarehouseStatement;
+    readonly requestId: string;
+    readonly principalId: string;
+}) => Effect.Effect<ReadonlyArray<StoredRecord>, WarehouseReadUnavailable>;
+declare const WarehouseQueries_base: Context.ServiceClass<WarehouseQueries, "@segmentstream/ontology/WarehouseQueries", WarehouseReadTransport>;
+/** One shared deployment budget, used by REST and MCP alike. */
+export declare class WarehouseQueries extends WarehouseQueries_base {
+}
+/** Uses the existing workspace-scoped, byte-limited read-only warehouse query API. */
+export declare function platformWarehouseQueries(environment: MetricQueryEnvironment, fetchImpl?: typeof fetch): WarehouseReadTransport;
+export {};

package/dist/service/warehouse-platform.js

@@ -0,0 +1,122 @@
+import { Context, Effect, Redacted } from "effect";
+import { describeError, securePlatform, } from "./metric-query-platform.js";
+import { WarehouseReadUnavailable } from "./errors.js";
+import { fixedWindowLimiter } from "./rate-limit.js";
+/** One shared deployment budget, used by REST and MCP alike. */
+export class WarehouseQueries extends Context.Service()("@segmentstream/ontology/WarehouseQueries") {
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Uses the existing workspace-scoped, byte-limited read-only warehouse query API. */
+export function platformWarehouseQueries(environment, fetchImpl = fetch) {
+    const limiter = fixedWindowLimiter({ limit: 30, windowMs: 60_000, maxKeys: 10_000 });
+    const credential = environment.appCredential === undefined ? undefined : Redacted.value(environment.appCredential);
+    const configured = credential !== undefined && securePlatform(environment.segmentstreamUrl);
+    const base = `${environment.segmentstreamUrl.replace(/\/$/, "")}/api/v1/workspaces/` +
+        `${encodeURIComponent(environment.workspaceId)}/warehouse/queries`;
+    return (input) => Effect.gen(function* () {
+        if (!configured || credential === undefined) {
+            return yield* new WarehouseReadUnavailable({ reason: "not_configured" });
+        }
+        const retryAfterSeconds = limiter.take(input.principalId);
+        if (retryAfterSeconds !== undefined) {
+            return yield* new WarehouseReadUnavailable({ reason: "limited", retryAfterSeconds });
+        }
+        return yield* Effect.tryPromise({
+            try: async (signal) => {
+                const bounded = AbortSignal.any([signal, AbortSignal.timeout(60_000)]);
+                const pageSize = Math.min(input.statement.maxRows, 1000);
+                const send = async (url, body) => {
+                    const response = await fetchImpl(url, {
+                        method: body === undefined ? "GET" : "POST",
+                        headers: {
+                            authorization: `Bearer ${credential}`,
+                            "content-type": "application/json",
+                            "x-segmentstream-request-id": input.requestId,
+                        },
+                        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                        redirect: "error",
+                        signal: bounded,
+                    });
+                    if (!response.ok) {
+                        const correlation = response.headers.get("x-request-id") ?? "unknown";
+                        throw new Error(`Warehouse query failed: HTTP ${response.status}; request ${correlation}.`);
+                    }
+                    const payload = await response.json();
+                    if (!object(payload) ||
+                        !object(payload.query) ||
+                        !["running", "done"].includes(String(payload.query.state))) {
+                        throw new Error("Invalid warehouse query response.");
+                    }
+                    return payload.query;
+                };
+                let page = await send(base, {
+                    sql: input.statement.sql,
+                    parameters: input.statement.parameters,
+                    pageSize,
+                });
+                const queryId = page.id;
+                const read = (pageToken) => {
+                    if (typeof queryId !== "string" || queryId === "") {
+                        throw new Error("The warehouse query has no continuation id.");
+                    }
+                    const search = new URLSearchParams({ pageSize: String(pageSize) });
+                    if (pageToken !== undefined) {
+                        search.set("pageToken", pageToken);
+                    }
+                    return send(`${base}/${encodeURIComponent(queryId)}?${search}`);
+                };
+                while (page.state === "running") {
+                    await new Promise((resolve, reject) => {
+                        const finish = () => {
+                            bounded.removeEventListener("abort", abort);
+                            resolve();
+                        };
+                        const timer = setTimeout(finish, 250);
+                        const abort = () => {
+                            clearTimeout(timer);
+                            reject(bounded.reason);
+                        };
+                        if (bounded.aborted) {
+                            abort();
+                        }
+                        else {
+                            bounded.addEventListener("abort", abort, { once: true });
+                        }
+                    });
+                    page = await read();
+                }
+                const records = [];
+                const tokens = new Set();
+                for (;;) {
+                    if (!Array.isArray(page.rows) || !page.rows.every(object)) {
+                        throw new Error("Invalid warehouse record rows.");
+                    }
+                    records.push(...page.rows);
+                    if (records.length > input.statement.maxRows) {
+                        throw new Error("The warehouse exceeded the bounded record query.");
+                    }
+                    const token = page.nextPageToken;
+                    if (token === undefined || token === null || token === "") {
+                        return records;
+                    }
+                    if (typeof token !== "string" ||
+                        tokens.has(token) ||
+                        records.length >= input.statement.maxRows) {
+                        throw new Error("Invalid warehouse continuation.");
+                    }
+                    tokens.add(token);
+                    page = await read(token);
+                    if (page.state !== "done") {
+                        throw new Error("A completed warehouse page became pending.");
+                    }
+                }
+            },
+            catch: (cause) => cause,
+        }).pipe(Effect.catch((cause) => Effect.logWarning("ontology.warehouse_records.failed").pipe(Effect.annotateLogs({
+            requestId: input.requestId,
+            cause: describeError(cause, (text) => text.split(credential).join("[redacted]")),
+        }), Effect.andThen(Effect.fail(new WarehouseReadUnavailable({ reason: "upstream", cause }))))));
+    });
+}