@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/config.d.ts

@@ -0,0 +1,218 @@
+import { type TelegramPreviewSettings } from "../telegram.js";
+import { Redacted, Schema } from "effect";
+import { BlobStorageBinding } from "../storage/provider.js";
+import { type DeploymentObservation } from "../deployment.js";
+import type { DeliveryArchive } from "./chat/archive.js";
+import type { Principal } from "../runtime.js";
+import type { PageCatalogV1 } from "../navigation-catalog.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";
+    readonly segmentstreamUrl: "SEGMENTSTREAM_URL";
+    readonly applicationId: "SEGMENTSTREAM_APPLICATION_ID";
+    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 metric queries to SegmentStream with it; without it, metric
+ * queries are unavailable and everything else works.
+ */
+export declare const APP_CREDENTIAL_VARIABLE = "SEGMENTSTREAM_APP_CREDENTIAL";
+/** The production domain of the deployment's Vercel project, which Vercel sets. */
+export declare const PRODUCTION_URL_VARIABLE = "VERCEL_PROJECT_PRODUCTION_URL";
+/** The Vercel project's cron secret, which the platform sets on the ontology service. */
+export declare const CRON_SECRET_VARIABLE = "CRON_SECRET";
+/**
+ * The workspace's webhook secret, from which each unsigned webhook's URL token is derived. The
+ * platform sets it independently on each target when the ontology declares a webhook trigger.
+ */
+export declare const WEBHOOK_SECRET_VARIABLE = "SEGMENTSTREAM_WEBHOOK_SECRET";
+/**
+ * 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.
+ */
+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. */
+    readonly baseUrl: string;
+    /** The JWKS that verifies the tokens: `<base URL>/.well-known/jwks.json`. */
+    readonly jwksUrl: string;
+}
+/** What the service reads from its environment. */
+export interface OntologyEnvironment {
+    readonly deployment?: DeploymentObservation;
+    /** Destination-channel settings; deployments share the validated agent configuration. */
+    readonly channels?: {
+        readonly telegram?: TelegramPreviewSettings & {
+            /** Explicit Mini App exchange opt-in; omitted means no exchange route. */
+            readonly miniApp?: {
+                readonly testPublicKeyHex?: string;
+            };
+        };
+    };
+    /** Verified own origins; additional aliases belong to the destination channel settings. */
+    readonly appOrigins?: readonly string[];
+    readonly browserRevisionClientId?: string;
+    readonly browserRevisionIssuer?: string;
+    readonly browserAuth?: unknown;
+    readonly browserEnvironment?: "local";
+    readonly oidc?: {
+        readonly issuer: string;
+        readonly clientId: string;
+    };
+    /** The pooled connection string of the `ontology_app` role. */
+    readonly databaseUrl: Redacted.Redacted<string>;
+    readonly blobStorage?: Redacted.Redacted<BlobStorageBinding>;
+    readonly storageMaintenanceKey?: Redacted.Redacted<string>;
+    /** The control plane: it issues app tokens and serves their JWKS. */
+    readonly segmentstreamUrl: string;
+    /** App tokens must be issued for this application: `aud: app:<application id>`. */
+    readonly applicationId: string;
+    readonly workspaceId: string;
+    readonly organizationId: string;
+    /**
+     * The workspace app credential. With it, `/api/ontology/query_metrics` forwards to SegmentStream at
+     * `segmentstreamUrl` for `workspaceId`. App previews receive an independently scoped credential.
+     */
+    readonly appCredential?: Redacted.Redacted<string>;
+    /** Production workload target; preview platform workflow tokens bind to `deployment` instead. */
+    readonly workloadTarget?: {
+        readonly deploymentId: string;
+    };
+    /**
+     * The Vercel project's cron secret, which Vercel sends as a bearer token on each cron
+     * invocation. Without it, the workflow trigger routes refuse every request.
+     */
+    readonly cronSecret?: Redacted.Redacted<string>;
+    /**
+     * The deployment's webhook secret, which derives each unsigned webhook's token:
+     * without it, every webhook path answers 404.
+     */
+    readonly webhookSecret?: 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.
+     */
+    readonly localConnections?: LocalConnectionContext;
+    /**
+     * The deployment's production origin, `https://` and `VERCEL_PROJECT_PRODUCTION_URL`, where
+     * `agentTask` hands the app's agent its tasks and where sign-in links sent from actions open.
+     * Production only: without it, and without `runtimeIdentity`, `agentTask` answers
+     * `agent_unavailable`, and `User.sendSignInLink` marks its emails failed.
+     */
+    readonly agentOrigin?: string;
+}
+/** A committed action, as an after-commit hook receives it. */
+export interface ActionCommitted {
+    readonly entity: string;
+    readonly action: string;
+    readonly principal: Principal;
+    /** The decoded input, using the authored TypeScript schema. */
+    readonly input: unknown;
+    readonly result: unknown;
+    readonly edits: ReadonlyArray<unknown>;
+    readonly requestId: string;
+    /** Provided only when defineOntology declares hooks.role. Runs once as that service role. */
+    readonly run?: (input: {
+        readonly entity: string;
+        readonly action: string;
+        readonly input: unknown;
+        readonly as: "service";
+    }) => Promise<unknown>;
+}
+/**
+ * Runs after an action commits, outside its transaction: start a Vercel Workflow that notifies the
+ * team or calls a webhook. The response waits for the hook, so keep it to starting the work. A failed
+ * hook is logged; the action stays committed and the caller still gets its result.
+ */
+export type AfterCommitHook = (event: ActionCommitted) => void | Promise<void>;
+export interface OntologyServiceConfig extends OntologyEnvironment {
+    /** UI page metadata for standalone services. A bundled deployment catalog cannot be overridden. */
+    readonly navigation?: PageCatalogV1;
+    /** Replace the bounded warehouse query transport in isolated integrations. */
+    readonly warehouseQueries?: import("./warehouse-platform.js").WarehouseReadTransport;
+    /** Explicit adapters for other verified channel apps. */
+    readonly channelAppProviders?: readonly import("./channel/provider.js").ChannelAppProvider[];
+    /** Override the archive transport for isolated integrations; defaults to the authenticated platform archive. */
+    readonly chatArchive?: DeliveryArchive;
+    /**
+     * Reuse the same access token during refresh recovery for this many milliseconds (default 45s).
+     * Afterward, recover the unused refresh successor with fresh access. Zero disables recovery.
+     */
+    readonly oauthRefreshReuseGraceMs?: number;
+    /** The runtime the routes run against: the SQL runtime on the workspace database by default. */
+    readonly runtime?: OntologyServiceRuntime;
+    /** Hooks by `<entity>.<action>`, for example `lead.submitLead`. */
+    readonly afterCommit?: Readonly<Record<string, AfterCommitHook>>;
+    /**
+     * How actions reach their connections. By default: the local grant when `localConnections` is
+     * set, else SegmentStream's proxy with the request's Vercel OIDC token.
+     */
+    readonly connections?: ConnectionTransportFactory;
+    /**
+     * Serve the MCP server at `/mcp`. On by default: its tools reach exactly what the HTTP routes
+     * reach, with the same credentials.
+     */
+    readonly mcp?: boolean;
+    /** Idle MCP GET streams close after this many milliseconds (default 45s). Keep below the host's function limit. */
+    readonly mcpStreamMaxDurationMs?: number;
+    /**
+     * How the workflow routes start runs and read their records: the Vercel Workflow SDK's `start`
+     * and world by default. Tests replace it.
+     */
+    readonly workflowEngine?: import("./workflows.js").WorkflowEngine;
+    /**
+     * How webhook signatures are checked: SegmentStream's backend, which holds the workspace secrets,
+     * called with the request's Vercel OIDC token, by default. Tests replace it.
+     */
+    readonly webhookVerifier?: import("./webhooks.js").WebhookVerifier;
+    /** How registration tokens are compared against backend-held workspace secrets. */
+    readonly webhookTokenVerifier?: import("./webhooks.js").WebhookTokenVerifier;
+    /** How `agentTask` calls the app's agent at `agentOrigin`: `fetch` by default. Tests replace it. */
+    readonly agentTaskTransport?: import("./agent/task-start.js").AgentTransport;
+    /**
+     * How `discover` asks the decision model of `defineOntology({ discovery })`: AI Gateway, with
+     * `AI_GATEWAY_API_KEY` or the request's Vercel OIDC token, by default. Tests replace it.
+     */
+    readonly decisions?: import("./decisions.js").Decide;
+}
+declare const OntologyServiceConfigError_base: Schema.Class<OntologyServiceConfigError, Schema.TaggedStruct<"OntologyServiceConfigError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The service cannot start: its configuration is incomplete or invalid. */
+export declare class OntologyServiceConfigError extends OntologyServiceConfigError_base {
+}
+/**
+ * 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 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 {};

package/dist/service/config.js

@@ -0,0 +1,265 @@
+import { telegramPreviewEnvironment } from "../telegram.js";
+import { Redacted, Schema } from "effect";
+import { BlobStorageBinding } from "../storage/provider.js";
+import { deploymentFromEnv } from "../deployment.js";
+import { LocalConnectionContextError, readLocalConnectionContext, RUNTIME_CONTEXT_FD, } from "./connections.js";
+/** The environment of the workspace deployment's ontology service. */
+export const ENVIRONMENT_VARIABLES = {
+    databaseUrl: "SEGMENTSTREAM_ONTOLOGY_DATABASE_URL",
+    segmentstreamUrl: "SEGMENTSTREAM_URL",
+    applicationId: "SEGMENTSTREAM_APPLICATION_ID",
+    workspaceId: "SEGMENTSTREAM_WORKSPACE_ID",
+    organizationId: "SEGMENTSTREAM_ORGANIZATION_ID",
+};
+/**
+ * The workspace app credential (`ssw_…`), which Vercel injects into every service of a production
+ * deployment. The service forwards metric queries to SegmentStream with it; without it, metric
+ * queries are unavailable and everything else works.
+ */
+export const APP_CREDENTIAL_VARIABLE = "SEGMENTSTREAM_APP_CREDENTIAL";
+/** The production domain of the deployment's Vercel project, which Vercel sets. */
+export const PRODUCTION_URL_VARIABLE = "VERCEL_PROJECT_PRODUCTION_URL";
+/** The Vercel project's cron secret, which the platform sets on the ontology service. */
+export const CRON_SECRET_VARIABLE = "CRON_SECRET";
+/**
+ * The workspace's webhook secret, from which each unsigned webhook's URL token is derived. The
+ * platform sets it independently on each target when the ontology declares a webhook trigger.
+ */
+export const WEBHOOK_SECRET_VARIABLE = "SEGMENTSTREAM_WEBHOOK_SECRET";
+/**
+ * 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.
+ */
+export const NEON_AUTH_ENVIRONMENT_VARIABLES = {
+    baseUrl: "NEON_AUTH_BASE_URL",
+    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 const RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES = {
+    issuer: "SEGMENTSTREAM_RUNTIME_OIDC_ISSUER",
+    audience: "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE",
+    projectId: "VERCEL_PROJECT_ID",
+};
+/** The service cannot start: its configuration is incomplete or invalid. */
+export class OntologyServiceConfigError extends Schema.TaggedError()("OntologyServiceConfigError", { message: Schema.String }) {
+}
+function httpUrl(name, value) {
+    if (!URL.canParse(value)) {
+        throw new OntologyServiceConfigError({ message: `${name} is not a valid URL.` });
+    }
+    const url = new URL(value);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new OntologyServiceConfigError({ message: `${name} must be an http or https URL.` });
+    }
+    return url;
+}
+function normalizeUrl(name, value) {
+    return httpUrl(name, value).origin;
+}
+/**
+ * Both Neon Auth variables or neither. One without the other is a broken deployment, so the service
+ * refuses to start rather than silently ignore the workspace's sign-in.
+ */
+function neonAuthFromEnv(read) {
+    const names = Object.values(NEON_AUTH_ENVIRONMENT_VARIABLES);
+    const missing = names.filter((name) => read(name) === "");
+    if (missing.length === names.length) {
+        return undefined;
+    }
+    if (missing.length > 0) {
+        throw new OntologyServiceConfigError({
+            message: `The ontology service cannot start: ${names.join(" and ")} are set together; ` +
+                `${missing.join(", ")} is not set.`,
+        });
+    }
+    return {
+        baseUrl: httpUrl(NEON_AUTH_ENVIRONMENT_VARIABLES.baseUrl, read(NEON_AUTH_ENVIRONMENT_VARIABLES.baseUrl)).href,
+        jwksUrl: httpUrl(NEON_AUTH_ENVIRONMENT_VARIABLES.jwksUrl, read(NEON_AUTH_ENVIRONMENT_VARIABLES.jwksUrl)).href,
+    };
+}
+/**
+ * The runtime issuer and audience, both or neither, and the project the tokens must name. A partial
+ * configuration is a broken deployment, so the service refuses to start rather than run without the
+ * agent's identity, or trust tokens of every project of the team.
+ */
+function runtimeIdentityFromEnv(read) {
+    const { issuer, audience, projectId } = RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES;
+    const pair = [issuer, audience];
+    const missingPair = pair.filter((name) => read(name) === "");
+    if (missingPair.length === pair.length) {
+        return undefined;
+    }
+    if (missingPair.length > 0) {
+        throw new OntologyServiceConfigError({
+            message: `The ontology service cannot start: ${pair.join(" and ")} are set together; ` +
+                `${missingPair.join(", ")} is not set.`,
+        });
+    }
+    if (read(projectId) === "") {
+        throw new OntologyServiceConfigError({
+            message: `The ontology service cannot start: ${projectId} is not set, which runtime tokens must name.`,
+        });
+    }
+    return {
+        issuer: httpUrl(issuer, read(issuer)).href.replace(/\/+$/, ""),
+        audience: read(audience),
+        projectId: read(projectId),
+    };
+}
+function checkDatabaseUrl(name, value) {
+    // The value is a credential: errors name the variable, never the value.
+    if (!URL.canParse(value)) {
+        throw new OntologyServiceConfigError({ message: `${name} is not a valid connection string.` });
+    }
+    const { protocol } = new URL(value);
+    if (protocol !== "postgres:" && protocol !== "postgresql:") {
+        throw new OntologyServiceConfigError({
+            message: `${name} must be a postgres:// or postgresql:// connection string.`,
+        });
+    }
+    return Redacted.make(value);
+}
+/**
+ * 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 and runtime identity variables are optional, but only as
+ * pairs. The app credential is optional and kept redacted.
+ */
+export function configFromEnv(environment = process.env) {
+    const read = (name) => environment[name]?.trim() ?? "";
+    const deployment = deploymentFromEnv(environment);
+    const missing = Object.values(ENVIRONMENT_VARIABLES).filter((name) => read(name) === "");
+    if (missing.length > 0) {
+        const list = missing.join(", ");
+        const verb = missing.length === 1 ? "is" : "are";
+        throw new OntologyServiceConfigError({
+            message: `The ontology service cannot start: ${list} ${verb} not set.`,
+        });
+    }
+    const deploymentId = read("SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID");
+    if (deploymentId !== "" &&
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(deploymentId)) {
+        throw new OntologyServiceConfigError({
+            message: "SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID must be a UUID.",
+        });
+    }
+    const neonAuth = neonAuthFromEnv(read);
+    const issuer = deployment.target === "preview" && !read("SEGMENTSTREAM_BROWSER_AUTH")
+        ? ""
+        : read("SEGMENTSTREAM_OIDC_ISSUER");
+    const clientId = deployment.target === "preview" && !read("SEGMENTSTREAM_BROWSER_AUTH")
+        ? ""
+        : read("SEGMENTSTREAM_OIDC_CLIENT_ID");
+    const oidcUrl = issuer ? URL.parse(issuer) : null;
+    if ((issuer || clientId) &&
+        (!issuer ||
+            !clientId ||
+            !oidcUrl ||
+            oidcUrl.protocol !== "https:" ||
+            oidcUrl.username ||
+            oidcUrl.password ||
+            oidcUrl.search ||
+            oidcUrl.hash ||
+            issuer.endsWith("/"))) {
+        throw new OntologyServiceConfigError({
+            message: "OIDC requires both a public client ID and an HTTPS issuer.",
+        });
+    }
+    const runtimeIdentity = deployment.target === "preview" ? undefined : runtimeIdentityFromEnv(read);
+    const localConnections = deployment.target === "preview" ? undefined : localConnectionsFromEnv(environment);
+    let blobStorage;
+    if (read("SEGMENTSTREAM_ONTOLOGY_STORAGE")) {
+        try {
+            blobStorage = Redacted.make(Schema.decodeUnknownSync(BlobStorageBinding)(JSON.parse(read("SEGMENTSTREAM_ONTOLOGY_STORAGE"))));
+        }
+        catch {
+            throw new OntologyServiceConfigError({
+                message: "SEGMENTSTREAM_ONTOLOGY_STORAGE is invalid.",
+            });
+        }
+    }
+    const previews = telegramPreviewEnvironment(environment);
+    return {
+        ...previews,
+        deployment,
+        databaseUrl: checkDatabaseUrl(ENVIRONMENT_VARIABLES.databaseUrl, read(ENVIRONMENT_VARIABLES.databaseUrl)),
+        segmentstreamUrl: normalizeUrl(ENVIRONMENT_VARIABLES.segmentstreamUrl, read(ENVIRONMENT_VARIABLES.segmentstreamUrl)),
+        applicationId: read(ENVIRONMENT_VARIABLES.applicationId),
+        workspaceId: read(ENVIRONMENT_VARIABLES.workspaceId),
+        organizationId: read(ENVIRONMENT_VARIABLES.organizationId),
+        ...(blobStorage === undefined ? {} : { blobStorage }),
+        ...(read("SEGMENTSTREAM_ONTOLOGY_STORAGE_MAINTENANCE_KEY")
+            ? {
+                storageMaintenanceKey: Redacted.make(read("SEGMENTSTREAM_ONTOLOGY_STORAGE_MAINTENANCE_KEY")),
+            }
+            : {}),
+        ...(read(CRON_SECRET_VARIABLE)
+            ? { cronSecret: Redacted.make(read(CRON_SECRET_VARIABLE)) }
+            : {}),
+        ...(read(WEBHOOK_SECRET_VARIABLE)
+            ? { webhookSecret: Redacted.make(read(WEBHOOK_SECRET_VARIABLE)) }
+            : {}),
+        ...(read(APP_CREDENTIAL_VARIABLE)
+            ? { appCredential: Redacted.make(read(APP_CREDENTIAL_VARIABLE)) }
+            : {}),
+        ...(deployment.target === "production" &&
+            environment.VERCEL_ENV === "production" &&
+            read("SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID") !== ""
+            ? { workloadTarget: { deploymentId: read("SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID") } }
+            : {}),
+        ...(deployment.target === "production" &&
+            environment.VERCEL_ENV === "production" &&
+            read(PRODUCTION_URL_VARIABLE) !== ""
+            ? {
+                agentOrigin: normalizeUrl(PRODUCTION_URL_VARIABLE, `https://${read(PRODUCTION_URL_VARIABLE)}`),
+            }
+            : {}),
+        ...(neonAuth === undefined ? {} : { neonAuth }),
+        ...(read("SEGMENTSTREAM_BROWSER_AUTH_REVISION_CLIENT_ID")
+            ? { browserRevisionClientId: read("SEGMENTSTREAM_BROWSER_AUTH_REVISION_CLIENT_ID") }
+            : {}),
+        ...(read("SEGMENTSTREAM_BROWSER_AUTH_REVISION_ISSUER")
+            ? { browserRevisionIssuer: read("SEGMENTSTREAM_BROWSER_AUTH_REVISION_ISSUER") }
+            : {}),
+        ...(read("SEGMENTSTREAM_BROWSER_AUTH_ENVIRONMENT") === "local"
+            ? { browserEnvironment: "local" }
+            : {}),
+        ...(read("SEGMENTSTREAM_BROWSER_AUTH")
+            ? { browserAuth: JSON.parse(read("SEGMENTSTREAM_BROWSER_AUTH")) }
+            : {}),
+        ...(issuer && clientId ? { oidc: { issuer, clientId } } : {}),
+        ...(runtimeIdentity === undefined ? {} : { runtimeIdentity }),
+        ...(localConnections === undefined ? {} : { localConnections }),
+    };
+}
+/**
+ * The local grant, read once from the pipe the CLI opened. A deployment never has one: a local
+ * grant on Vercel would mix two ways of calling connections, so the service refuses to start.
+ */
+function localConnectionsFromEnv(environment) {
+    if (environment[RUNTIME_CONTEXT_FD] === undefined) {
+        return undefined;
+    }
+    if ((environment.VERCEL_ENV ?? "") !== "") {
+        throw new OntologyServiceConfigError({
+            message: `The ontology service cannot start: ${RUNTIME_CONTEXT_FD} is set on a Vercel deployment, ` +
+                "which calls connections with its OIDC token.",
+        });
+    }
+    try {
+        return readLocalConnectionContext(environment);
+    }
+    catch (error) {
+        if (error instanceof LocalConnectionContextError) {
+            throw new OntologyServiceConfigError({
+                message: `The ontology service cannot start: ${error.message}`,
+            });
+        }
+        throw error;
+    }
+}

package/dist/service/connection-stream.d.ts

@@ -0,0 +1,10 @@
+import { Effect, type Scope } from "effect";
+import { ConnectionError, type ConnectionReply, type ConnectionStreamReply } from "../connection.js";
+export declare const CONNECTION_STREAM_MEDIA_TYPE = "application/vnd.segmentstream.proxy-stream.v1+ndjson";
+/** Negotiates once; never retries a provider operation to change response formats. */
+export declare function openConnectionStream(input: {
+    readonly connection: string;
+    readonly request: (signal: AbortSignal) => Promise<Response>;
+    readonly legacy: (value: unknown) => ConnectionReply;
+    readonly refusal: (status: number, value: unknown, cause?: unknown) => ConnectionError;
+}): Effect.Effect<ConnectionStreamReply, ConnectionError, Scope.Scope>;