@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/connection.d.ts

@@ -0,0 +1,213 @@
+import { Context, Effect, Layer, Schema, Stream, type Scope } from "effect";
+export declare const ConnectionTypeId: unique symbol;
+/** A connection key, as `connections/connections.py` declares it. */
+export declare const CONNECTION_KEY: RegExp;
+export declare const CONNECTION_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+export type ConnectionMethod = (typeof CONNECTION_METHODS)[number];
+/** The largest request body. */
+export declare const MAXIMUM_CONNECTION_BODY_BYTES: number;
+/**
+ * The largest response body `get`, `post` and `request` collect. A larger response fails with
+ * `invalid_response`; `stream` reads a response of any size.
+ */
+export declare const MAXIMUM_CONNECTION_RESPONSE_BYTES: number;
+/**
+ * Why a connection call failed, as {@link ConnectionError} carries it:
+ *
+ * - `authorization_required`: the connection is declared but not configured or authorized yet;
+ * - `not_deployed`: the workspace's connection declarations are not deployed;
+ * - `not_granted`: the platform refused this service the connection, a platform fault;
+ * - `unavailable`: the proxy or the provider could not be reached; retrying may succeed;
+ * - `refused`: the provider refused the request in a way retrying will not fix;
+ * - `timeout`: the call exceeded its deadline;
+ * - `invalid_request`: the proxy refused the request itself, such as a forbidden header or path;
+ * - `invalid_response`: the response did not match the schema given to `json`.
+ */
+export declare const CONNECTION_ERROR_REASONS: readonly ["authorization_required", "not_deployed", "not_granted", "unavailable", "refused", "timeout", "invalid_request", "invalid_response"];
+export type ConnectionErrorReason = (typeof CONNECTION_ERROR_REASONS)[number];
+declare const ConnectionError_base: Schema.Class<ConnectionError, Schema.TaggedStruct<"ConnectionError", {
+    /** The connection key. */
+    readonly connection: Schema.String;
+    readonly reason: Schema.Literals<readonly ["authorization_required", "not_deployed", "not_granted", "unavailable", "refused", "timeout", "invalid_request", "invalid_response"]>;
+    readonly message: Schema.String;
+    readonly retryable: Schema.Boolean;
+    /** The request id SegmentStream answered with, for correlating its logs. */
+    readonly requestId: Schema.optionalKey<Schema.String>;
+    /** Original internal failure, retained for operator diagnostics only. */
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A connection call failed. A provider's non-2xx status is a response, not this error. `prepare` may
+ * catch it; if it escapes, the action responds with the matching status and writes nothing.
+ */
+export declare class ConnectionError extends ConnectionError_base {
+}
+/** One HTTP request through the connection proxy, before it is bound to a connection key. */
+export interface ConnectionCall {
+    /** One of the connection's declared APIs; the connection's `default_api` when omitted. */
+    readonly api?: string;
+    readonly method: ConnectionMethod;
+    /** The path and query, relative to the API's base URL, such as `/people/match?reveal=true`. */
+    readonly path: string;
+    readonly headers: ReadonlyArray<readonly [string, string]>;
+    readonly body: Uint8Array;
+}
+/** What the proxy answered: the provider's status, headers and buffered body. */
+export interface ConnectionReply {
+    readonly status: number;
+    readonly headers: ReadonlyArray<readonly [string, string]>;
+    readonly body: Uint8Array;
+}
+/** A provider response whose body is consumed within the caller's scope. */
+export interface ConnectionStreamReply {
+    readonly status: number;
+    readonly headers: ReadonlyArray<readonly [string, string]>;
+    readonly body: Stream.Stream<Uint8Array, ConnectionError>;
+}
+export interface ConnectionStreamResponse extends ConnectionStreamReply {
+    readonly ok: boolean;
+    header(name: string): string | undefined;
+}
+declare const ConnectionTransport_base: Context.ServiceClass<ConnectionTransport, "@segmentstream/ontology/ConnectionTransport", {
+    readonly request: (call: ConnectionCall & {
+        readonly connection: string;
+    }) => Effect.Effect<ConnectionReply, ConnectionError>;
+    /** Optional for transports written before response streaming was introduced. */
+    readonly stream?: (call: ConnectionCall & {
+        readonly connection: string;
+    }) => Effect.Effect<ConnectionStreamReply, ConnectionError, Scope.Scope>;
+}>;
+/**
+ * Sends connection calls: to backend-next from a deployed service, to the local route with a CLI
+ * grant in development, or to stubs in tests. The ontology service provides it to actions; tests
+ * provide {@link Connections.test}.
+ */
+export declare class ConnectionTransport extends ConnectionTransport_base {
+}
+/** A buffered provider response. */
+export interface ConnectionResponse {
+    readonly status: number;
+    /** `true` for a 2xx status. */
+    readonly ok: boolean;
+    readonly headers: ReadonlyArray<readonly [string, string]>;
+    readonly body: Uint8Array;
+    /** The body as UTF-8 text. */
+    readonly text: string;
+    /** The first value of a header, by case-insensitive name. */
+    header(name: string): string | undefined;
+    /** Parses the body as JSON and decodes it; `invalid_response` when either fails. */
+    json<S extends Schema.Top>(schema: S): Effect.Effect<S["Type"], ConnectionError, S["DecodingServices"]>;
+}
+/**
+ * The requirement of a connection handle's calls. `prepare` has exactly the connections its action
+ * declares, so calling an undeclared one does not type-check.
+ */
+export interface Connection<Key extends string> {
+    readonly "~connection": Key;
+}
+/** The service behind {@link Connection}: the transport, bound to one connection key. */
+export interface ConnectionClient {
+    readonly request: (call: ConnectionCall) => Effect.Effect<ConnectionReply, ConnectionError>;
+    readonly stream?: (call: ConnectionCall) => Effect.Effect<ConnectionStreamReply, ConnectionError, Scope.Scope>;
+}
+export type ConnectionHeaders = Readonly<Record<string, string>> | ReadonlyArray<readonly [string, string]>;
+export type QueryValue = string | number | boolean | ReadonlyArray<string | number | boolean>;
+/** The options of `request` and the method helpers. */
+export interface ConnectionRequestOptions {
+    /** One of the connection's declared APIs; the connection's `default_api` when omitted. */
+    readonly api?: string;
+    /** Appended to the path as a query string. `undefined` values are skipped. */
+    readonly query?: Readonly<Record<string, QueryValue | undefined>>;
+    readonly headers?: ConnectionHeaders;
+    /** A JSON body, sent with `content-type: application/json`. */
+    readonly json?: unknown;
+    /** A form body, sent with `content-type: application/x-www-form-urlencoded`. */
+    readonly form?: Readonly<Record<string, string>>;
+    /** A raw body. Set at most one of `json`, `form` and `body`. */
+    readonly body?: string | Uint8Array;
+}
+export interface ConnectionRequest extends ConnectionRequestOptions {
+    readonly method: ConnectionMethod;
+    readonly path: string;
+}
+type Call<Key extends string> = Effect.Effect<ConnectionResponse, ConnectionError, Connection<Key>>;
+/**
+ * A workspace connection an action may call, declared once in `ontology/` with
+ * `connection(key, { description })` and listed in the actions that use it. Calls go through
+ * SegmentStream's connection proxy, so the provider's credentials never reach the deployment.
+ */
+export interface ConnectionHandle<Key extends string = string> {
+    readonly [ConnectionTypeId]: typeof ConnectionTypeId;
+    /** The connection's key in `connections/connections.py`. */
+    readonly key: Key;
+    /** What the ontology uses the connection for, shown in the catalog. */
+    readonly description: string;
+    /** Whether the ontology sends data out through this connection, such as conversions or messages. */
+    readonly delivers: boolean;
+    /** The context key of this connection's client. */
+    readonly service: Context.Service<Connection<Key>, ConnectionClient>;
+    request(request: ConnectionRequest): Call<Key>;
+    /** Keeps the provider response open until consumption or scope closure. Requests remain bounded. */
+    stream(request: ConnectionRequest): Effect.Effect<ConnectionStreamResponse, ConnectionError, Connection<Key> | Scope.Scope>;
+    get(path: string, options?: ConnectionRequestOptions): Call<Key>;
+    post(path: string, options?: ConnectionRequestOptions): Call<Key>;
+    put(path: string, options?: ConnectionRequestOptions): Call<Key>;
+    patch(path: string, options?: ConnectionRequestOptions): Call<Key>;
+    delete(path: string, options?: ConnectionRequestOptions): Call<Key>;
+}
+/** Any connection handle. Its context key is invariant in the key, so the key is `any` here. */
+export type AnyConnectionHandle = ConnectionHandle<any>;
+/** The requirements of the handles in a list: `Connection<"apollo"> | Connection<"stripe">`. */
+export type ConnectionsOf<C extends ReadonlyArray<AnyConnectionHandle>> = C[number] extends infer H ? H extends ConnectionHandle<infer Key> ? Connection<Key> : never : never;
+export interface ConnectionOptions {
+    /** What the ontology uses the connection for: "Apollo people search. Enriches new leads." */
+    readonly description: string;
+    /**
+     * The ontology sends data out through this connection: offline conversions, a message, an
+     * email. The manifest marks it so Cloud can list it as a destination. Default false.
+     */
+    readonly delivers?: boolean;
+}
+/** The call a request describes: query appended, body encoded and its content type set. */
+export declare function connectionCall(key: string, request: ConnectionRequest): ConnectionCall;
+/** A buffered response over what the proxy answered. */
+export declare function connectionResponse(key: string, reply: ConnectionReply): ConnectionResponse;
+/**
+ * Declares a connection the ontology's actions may call. `key` names a connection in the
+ * workspace's `connections/connections.py`. List the handle once in `defineOntology({ connections })`
+ * and in the `connections` of each action that calls it.
+ */
+export declare function connection<const Key extends string>(key: Key, options: ConnectionOptions): ConnectionHandle<Key>;
+export declare function isConnection(value: unknown): value is AnyConnectionHandle;
+export declare function bufferedStream(reply: ConnectionReply): ConnectionStreamReply;
+/**
+ * The clients of the given handles over one transport: what `prepare` runs with. Only these
+ * connections can be called; the transport is never exposed to the action.
+ */
+export declare function connectionContext<const C extends ReadonlyArray<AnyConnectionHandle>>(handles: C, transport: ConnectionTransport["Service"], options?: {
+    readonly readOnly?: boolean;
+}): Context.Context<ConnectionsOf<C>>;
+/** A stubbed response for {@link Connections.test}. */
+export interface StubResponse {
+    readonly status?: number;
+    readonly headers?: ConnectionHeaders;
+    /** A JSON body. */
+    readonly json?: unknown;
+    /** A text body. */
+    readonly text?: string;
+}
+/** A call as a stub receives it. */
+export interface StubRequest extends ConnectionCall {
+    readonly connection: string;
+    /** The request body as UTF-8 text. */
+    readonly text: string;
+}
+export type ConnectionStub = (request: StubRequest) => Effect.Effect<StubResponse | ConnectionReply, ConnectionError>;
+export declare const Connections: {
+    /**
+     * A transport that answers with stubs by connection key, for runtime tests of actions that
+     * declare connections. A call to a connection without a stub fails the test.
+     */
+    test: (stubs: Readonly<Record<string, ConnectionStub>>) => Layer.Layer<ConnectionTransport>;
+};
+export {};

package/dist/connection.js

@@ -0,0 +1,289 @@
+import { Context, Effect, Layer, Schema, Stream } from "effect";
+export const ConnectionTypeId = Symbol.for("@segmentstream/ontology/Connection");
+/** A connection key, as `connections/connections.py` declares it. */
+export const CONNECTION_KEY = /^(?=.{1,64}$)[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+export const CONNECTION_METHODS = [
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+];
+/** The largest request body. */
+export const MAXIMUM_CONNECTION_BODY_BYTES = 2 * 1024 * 1024;
+/**
+ * The largest response body `get`, `post` and `request` collect. A larger response fails with
+ * `invalid_response`; `stream` reads a response of any size.
+ */
+export const MAXIMUM_CONNECTION_RESPONSE_BYTES = 64 * 1024 * 1024;
+/**
+ * Why a connection call failed, as {@link ConnectionError} carries it:
+ *
+ * - `authorization_required`: the connection is declared but not configured or authorized yet;
+ * - `not_deployed`: the workspace's connection declarations are not deployed;
+ * - `not_granted`: the platform refused this service the connection, a platform fault;
+ * - `unavailable`: the proxy or the provider could not be reached; retrying may succeed;
+ * - `refused`: the provider refused the request in a way retrying will not fix;
+ * - `timeout`: the call exceeded its deadline;
+ * - `invalid_request`: the proxy refused the request itself, such as a forbidden header or path;
+ * - `invalid_response`: the response did not match the schema given to `json`.
+ */
+export const CONNECTION_ERROR_REASONS = [
+    "authorization_required",
+    "not_deployed",
+    "not_granted",
+    "unavailable",
+    "refused",
+    "timeout",
+    "invalid_request",
+    "invalid_response",
+];
+/**
+ * A connection call failed. A provider's non-2xx status is a response, not this error. `prepare` may
+ * catch it; if it escapes, the action responds with the matching status and writes nothing.
+ */
+export class ConnectionError extends Schema.TaggedError()("ConnectionError", {
+    /** The connection key. */
+    connection: Schema.String,
+    reason: Schema.Literals(CONNECTION_ERROR_REASONS),
+    message: Schema.String,
+    retryable: Schema.Boolean,
+    /** The request id SegmentStream answered with, for correlating its logs. */
+    requestId: Schema.optionalKey(Schema.String),
+    /** Original internal failure, retained for operator diagnostics only. */
+    cause: Schema.optionalKey(Schema.Unknown),
+}) {
+}
+/**
+ * Sends connection calls: to backend-next from a deployed service, to the local route with a CLI
+ * grant in development, or to stubs in tests. The ontology service provides it to actions; tests
+ * provide {@link Connections.test}.
+ */
+export class ConnectionTransport extends Context.Service()("@segmentstream/ontology/ConnectionTransport") {
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function connectionFailure(connection, reason, message, cause) {
+    return new ConnectionError({
+        connection,
+        reason,
+        message,
+        retryable: reason === "unavailable" || reason === "timeout",
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+function headerPairs(headers) {
+    if (headers === undefined) {
+        return [];
+    }
+    return Array.isArray(headers)
+        ? [...headers]
+        : Object.entries(headers);
+}
+function withQuery(path, query) {
+    if (query === undefined) {
+        return path;
+    }
+    const parameters = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+        if (value === undefined) {
+            continue;
+        }
+        for (const item of Array.isArray(value) ? value : [value]) {
+            parameters.append(name, String(item));
+        }
+    }
+    const search = parameters.toString();
+    if (search === "") {
+        return path;
+    }
+    return `${path}${path.includes("?") ? "&" : "?"}${search}`;
+}
+function hasHeader(headers, name) {
+    return headers.some(([candidate]) => candidate.toLowerCase() === name);
+}
+/** The call a request describes: query appended, body encoded and its content type set. */
+export function connectionCall(key, request) {
+    const bodies = [request.json, request.form, request.body].filter((body) => body !== undefined);
+    if (bodies.length > 1) {
+        throw connectionFailure(key, "invalid_request", "Set at most one of json, form and body.");
+    }
+    const headers = headerPairs(request.headers);
+    let body = new Uint8Array();
+    let contentType;
+    if (request.json !== undefined) {
+        body = encoder.encode(JSON.stringify(request.json));
+        contentType = "application/json";
+    }
+    else if (request.form !== undefined) {
+        body = encoder.encode(new URLSearchParams(Object.entries(request.form)).toString());
+        contentType = "application/x-www-form-urlencoded";
+    }
+    else if (typeof request.body === "string") {
+        body = encoder.encode(request.body);
+    }
+    else if (request.body !== undefined) {
+        body = request.body;
+    }
+    if (contentType !== undefined && !hasHeader(headers, "content-type")) {
+        headers.push(["content-type", contentType]);
+    }
+    if (body.byteLength > MAXIMUM_CONNECTION_BODY_BYTES) {
+        throw connectionFailure(key, "invalid_request", "The request body exceeds 2 MiB.");
+    }
+    return {
+        ...(request.api === undefined ? {} : { api: request.api }),
+        method: request.method,
+        path: withQuery(request.path, request.query),
+        headers,
+        body,
+    };
+}
+/** A buffered response over what the proxy answered. */
+export function connectionResponse(key, reply) {
+    let text;
+    const readText = () => (text ??= decoder.decode(reply.body));
+    return {
+        status: reply.status,
+        ok: reply.status >= 200 && reply.status < 300,
+        headers: reply.headers,
+        body: reply.body,
+        get text() {
+            return readText();
+        },
+        header: (name) => reply.headers.find(([candidate]) => candidate.toLowerCase() === name.toLowerCase())?.[1],
+        json: (schema) => Effect.try({
+            try: () => JSON.parse(readText()),
+            catch: () => connectionFailure(key, "invalid_response", "The response body is not JSON."),
+        }).pipe(Effect.flatMap((value) => Schema.decodeUnknownEffect(schema)(value)), Effect.mapError((error) => error instanceof ConnectionError
+            ? error
+            : connectionFailure(key, "invalid_response", `The response does not match the expected schema: ${error.message}`))),
+    };
+}
+/**
+ * Declares a connection the ontology's actions may call. `key` names a connection in the
+ * workspace's `connections/connections.py`. List the handle once in `defineOntology({ connections })`
+ * and in the `connections` of each action that calls it.
+ */
+export function connection(key, options) {
+    const service = Context.Service(`@segmentstream/ontology/Connection/${key}`);
+    const request = (input) => Effect.gen(function* () {
+        const client = yield* service;
+        const call = yield* Effect.try({
+            try: () => connectionCall(key, input),
+            catch: (error) => error instanceof ConnectionError
+                ? error
+                : connectionFailure(key, "invalid_request", String(error)),
+        });
+        const reply = yield* client.request(call);
+        return connectionResponse(key, reply);
+    });
+    const method = (verb) => (path, options = {}) => request({ ...options, method: verb, path });
+    return {
+        [ConnectionTypeId]: ConnectionTypeId,
+        key,
+        description: options?.description,
+        delivers: options?.delivers === true,
+        service,
+        request,
+        stream: (input) => Effect.gen(function* () {
+            const client = yield* service;
+            const call = yield* Effect.try({
+                try: () => connectionCall(key, input),
+                catch: (cause) => cause instanceof ConnectionError
+                    ? cause
+                    : connectionFailure(key, "invalid_request", "invalid_request", cause),
+            });
+            const reply = client.stream
+                ? yield* client.stream(call)
+                : bufferedStream(yield* client.request(call));
+            return {
+                ...reply,
+                ok: reply.status >= 200 && reply.status < 300,
+                header: (name) => reply.headers.find(([candidate]) => candidate.toLowerCase() === name.toLowerCase())?.[1],
+            };
+        }),
+        get: method("GET"),
+        post: method("POST"),
+        put: method("PUT"),
+        patch: method("PATCH"),
+        delete: method("DELETE"),
+    };
+}
+export function isConnection(value) {
+    return typeof value === "object" && value !== null && ConnectionTypeId in value;
+}
+export function bufferedStream(reply) {
+    return { ...reply, body: Stream.fromIterable([reply.body]) };
+}
+/**
+ * The clients of the given handles over one transport: what `prepare` runs with. Only these
+ * connections can be called; the transport is never exposed to the action.
+ */
+export function connectionContext(handles, transport, options = {}) {
+    let context = Context.empty();
+    for (const handle of handles) {
+        const admit = (call) => {
+            if (options.readOnly !== true) {
+                return Effect.void;
+            }
+            return Effect.try({
+                try: () => new URL(call.path, "https://connection.invalid"),
+                catch: (cause) => connectionFailure(handle.key, "invalid_request", "The connection path is invalid.", cause),
+            }).pipe(Effect.flatMap((url) => {
+                // Match the proxy's policy, including attempts to tunnel writes through GET.
+                if (!["GET", "HEAD", "OPTIONS"].includes(call.method) ||
+                    call.body.byteLength > 0 ||
+                    call.headers.some(([name]) => name.toLowerCase().includes("method")) ||
+                    [...url.searchParams.keys()].some((name) => ["method", "_method"].includes(name.toLowerCase()))) {
+                    return Effect.fail(connectionFailure(handle.key, "invalid_request", "This action's connections are read-only."));
+                }
+                return Effect.void;
+            }));
+        };
+        context = Context.add(context, handle.service, {
+            request: (call) => admit(call).pipe(Effect.andThen(() => transport.request({ ...call, connection: handle.key }))),
+            stream: (call) => admit(call).pipe(Effect.andThen(() => transport.stream
+                ? transport.stream({ ...call, connection: handle.key })
+                : transport
+                    .request({ ...call, connection: handle.key })
+                    .pipe(Effect.map(bufferedStream)))),
+        });
+    }
+    return context;
+}
+function stubReply(response) {
+    if ("body" in response && response.body instanceof Uint8Array) {
+        return response;
+    }
+    const stub = response;
+    const headers = headerPairs(stub.headers);
+    let body = new Uint8Array();
+    if (stub.json !== undefined) {
+        body = encoder.encode(JSON.stringify(stub.json));
+        if (!hasHeader(headers, "content-type")) {
+            headers.push(["content-type", "application/json"]);
+        }
+    }
+    else if (stub.text !== undefined) {
+        body = encoder.encode(stub.text);
+    }
+    return { status: stub.status ?? 200, headers, body };
+}
+export const Connections = {
+    /**
+     * A transport that answers with stubs by connection key, for runtime tests of actions that
+     * declare connections. A call to a connection without a stub fails the test.
+     */
+    test: (stubs) => Layer.succeed(ConnectionTransport, {
+        request: (call) => {
+            const stub = stubs[call.connection];
+            if (stub === undefined) {
+                return Effect.die(new Error(`Connections.test has no stub for the connection ${call.connection}.`));
+            }
+            return stub({ ...call, text: decoder.decode(call.body) }).pipe(Effect.map(stubReply));
+        },
+    }),
+};

package/dist/deployment.d.ts

@@ -0,0 +1,35 @@
+/** Runtime observations; authorization of the machine credential remains platform-owned. */
+export interface DeploymentCapabilities {
+    readonly warehouseRead: boolean;
+    readonly pipelineRuns: boolean;
+    readonly connections: boolean;
+    readonly agents: boolean;
+    readonly workflows: boolean;
+}
+export type DeploymentObservation = {
+    readonly target: "production";
+    readonly deploymentId?: string;
+    readonly capabilities: DeploymentCapabilities;
+} | {
+    readonly target: "preview";
+    readonly deploymentId: string;
+    readonly expiresAt: string;
+    /**
+     * `local` when the preview runs on a developer's machine (`segmentstream dev`), where the
+     * Workflow SDK's local world records runs; absent on a hosted preview.
+     */
+    readonly host?: "local";
+    readonly capabilities: DeploymentCapabilities;
+};
+export type DeploymentAdmissionCode = "preview_configuration_invalid" | "preview_expired" | "preview_capability_unavailable" | "preview_authentication_unavailable" | "preview_storage_binding_invalid";
+/** Stable codes only: workspace code owns explanations and presentation. */
+export declare class DeploymentAdmissionError extends Error {
+    readonly code: DeploymentAdmissionCode;
+    readonly capability?: keyof DeploymentCapabilities | undefined;
+    readonly _tag = "DeploymentAdmissionError";
+    constructor(code: DeploymentAdmissionCode, capability?: keyof DeploymentCapabilities | undefined);
+    get status(): number;
+}
+export declare function deploymentFromEnv(environment?: Readonly<Record<string, string | undefined>>): DeploymentObservation;
+/** Recheck the deadline on every admission, including a warm process and cached sessions. */
+export declare function requireDeploymentCapability(deployment: DeploymentObservation, capability?: keyof DeploymentCapabilities, now?: number): void;

package/dist/deployment.js

@@ -0,0 +1,76 @@
+/** Stable codes only: workspace code owns explanations and presentation. */
+export class DeploymentAdmissionError extends Error {
+    code;
+    capability;
+    _tag = "DeploymentAdmissionError";
+    constructor(code, capability) {
+        super(code);
+        this.code = code;
+        this.capability = capability;
+        this.name = "DeploymentAdmissionError";
+    }
+    get status() {
+        return this.code === "preview_expired"
+            ? 410
+            : this.code === "preview_configuration_invalid" ||
+                this.code === "preview_storage_binding_invalid"
+                ? 503
+                : 403;
+    }
+}
+export function deploymentFromEnv(environment = process.env) {
+    const target = environment.SEGMENTSTREAM_DEPLOYMENT_TARGET?.trim() || "production";
+    const deploymentId = environment.SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID?.trim();
+    if (target === "production") {
+        return Object.freeze({
+            target,
+            ...(deploymentId ? { deploymentId } : {}),
+            capabilities: Object.freeze({
+                warehouseRead: true,
+                pipelineRuns: true,
+                connections: true,
+                agents: true,
+                workflows: true,
+            }),
+        });
+    }
+    const expiresAt = environment.SEGMENTSTREAM_PREVIEW_EXPIRES_AT?.trim();
+    const host = environment.SEGMENTSTREAM_PREVIEW_HOST?.trim() || undefined;
+    if (target !== "preview" ||
+        (host !== undefined && host !== "local") ||
+        !deploymentId ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(deploymentId) ||
+        !expiresAt ||
+        !/^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(expiresAt) ||
+        !Number.isFinite(Date.parse(expiresAt))) {
+        throw new DeploymentAdmissionError("preview_configuration_invalid");
+    }
+    return Object.freeze({
+        target,
+        deploymentId,
+        expiresAt,
+        ...(host === undefined ? {} : { host }),
+        capabilities: Object.freeze({
+            warehouseRead: true,
+            pipelineRuns: false,
+            connections: false,
+            agents: false,
+            workflows: true,
+        }),
+    });
+}
+/** Recheck the deadline on every admission, including a warm process and cached sessions. */
+export function requireDeploymentCapability(deployment, capability, now = Date.now()) {
+    if (deployment.target !== "preview") {
+        return;
+    }
+    if (!Number.isFinite(now) ||
+        !Number.isFinite(Date.parse(deployment.expiresAt)) ||
+        now >= Date.parse(deployment.expiresAt)) {
+        throw new DeploymentAdmissionError("preview_expired");
+    }
+    // The preview profile is fixed; supplied flags cannot enable managed integrations.
+    if (capability !== undefined && capability !== "warehouseRead" && capability !== "workflows") {
+        throw new DeploymentAdmissionError("preview_capability_unavailable", capability);
+    }
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,27 @@
+import { Schema } from "effect";
+export declare const DIAGNOSTIC_CODES: readonly ["invalid-source", "missing-column", "invalid-column", "invalid-scope", "invalid-scope-path", "scope-reads-all", "scope-unused", "scope-member-overlap", "source-with-actions", "source-with-index", "invalid-metric", "unknown-metric", "circular-metric", "invalid-join", "missing-join", "invalid-entity", "invalid-property", "invalid-relationship", "invalid-actions", "invalid-action", "invalid-action-input", "invalid-role", "invalid-name", "reserved-name", "duplicate-name", "invalid-entity-id", "duplicate-entity-id", "missing-label", "missing-description", "invalid-title", "invalid-options", "invalid-default", "invalid-constraint", "unknown-relationship-target", "inverse-collision", "invalid-on-delete", "invalid-phrase", "invalid-index", "unknown-reference", "invalid-renamed-from", "earlier-name", "invalid-guide", "invalid-writes", "generated-update-empty", "managed-without-effect", "missing-permissions", "invalid-permission", "unknown-permission", "removed-allow", "unreachable-action", "wildcard-permission", "invalid-sign-in", "invalid-connection", "invalid-feedback", "invalid-discovery", "invalid-email", "feedback-unanswerable", "unknown-connection", "unused-connection", "invalid-prepare", "invalid-tool-name", "invalid-alignment", "single-entity-model-metric", "invalid-workflow", "workflow_role_unknown", "workflow_role_is_member", "workflow_role_grants_nothing", "workflow_role_wildcard", "workflow_role_scoped", "workflow_cron_never_fires", "workflow_input_invalid", "workflow_cron_invalid", "workflow_run_missing", "invalid-trigger", "trigger_action_unknown", "trigger_function_async", "workflow_trigger_limit_exceeded", "workflow_webhook_duplicate", "workflow_webhook_input_invalid", "workflow_webhook_mixed_triggers", "workflow_webhook_signature_invalid", "workflow_webhook_verification_invalid", "workflow_webhook_headers_invalid", "workflow_webhook_limit_exceeded"];
+export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
+/** A problem `check` found in an ontology definition. */
+export declare const Diagnostic: Schema.Struct<{
+    readonly severity: Schema.Literals<readonly ["error", "warning", "info"]>;
+    readonly code: Schema.Literals<readonly ["invalid-source", "missing-column", "invalid-column", "invalid-scope", "invalid-scope-path", "scope-reads-all", "scope-unused", "scope-member-overlap", "source-with-actions", "source-with-index", "invalid-metric", "unknown-metric", "circular-metric", "invalid-join", "missing-join", "invalid-entity", "invalid-property", "invalid-relationship", "invalid-actions", "invalid-action", "invalid-action-input", "invalid-role", "invalid-name", "reserved-name", "duplicate-name", "invalid-entity-id", "duplicate-entity-id", "missing-label", "missing-description", "invalid-title", "invalid-options", "invalid-default", "invalid-constraint", "unknown-relationship-target", "inverse-collision", "invalid-on-delete", "invalid-phrase", "invalid-index", "unknown-reference", "invalid-renamed-from", "earlier-name", "invalid-guide", "invalid-writes", "generated-update-empty", "managed-without-effect", "missing-permissions", "invalid-permission", "unknown-permission", "removed-allow", "unreachable-action", "wildcard-permission", "invalid-sign-in", "invalid-connection", "invalid-feedback", "invalid-discovery", "invalid-email", "feedback-unanswerable", "unknown-connection", "unused-connection", "invalid-prepare", "invalid-tool-name", "invalid-alignment", "single-entity-model-metric", "invalid-workflow", "workflow_role_unknown", "workflow_role_is_member", "workflow_role_grants_nothing", "workflow_role_wildcard", "workflow_role_scoped", "workflow_cron_never_fires", "workflow_input_invalid", "workflow_cron_invalid", "workflow_run_missing", "invalid-trigger", "trigger_action_unknown", "trigger_function_async", "workflow_trigger_limit_exceeded", "workflow_webhook_duplicate", "workflow_webhook_input_invalid", "workflow_webhook_mixed_triggers", "workflow_webhook_signature_invalid", "workflow_webhook_verification_invalid", "workflow_webhook_headers_invalid", "workflow_webhook_limit_exceeded"]>;
+    /** Where the problem is, for example `lead.properties.status.options[1]`. */
+    readonly path: Schema.String;
+    readonly message: Schema.String;
+}>;
+export type Diagnostic = typeof Diagnostic.Type;
+declare const InvalidOntology_base: Schema.Class<InvalidOntology, Schema.TaggedStruct<"InvalidOntology", {
+    readonly message: Schema.String;
+    readonly diagnostics: Schema.$Array<Schema.Struct<{
+        readonly severity: Schema.Literals<readonly ["error", "warning", "info"]>;
+        readonly code: Schema.Literals<readonly ["invalid-source", "missing-column", "invalid-column", "invalid-scope", "invalid-scope-path", "scope-reads-all", "scope-unused", "scope-member-overlap", "source-with-actions", "source-with-index", "invalid-metric", "unknown-metric", "circular-metric", "invalid-join", "missing-join", "invalid-entity", "invalid-property", "invalid-relationship", "invalid-actions", "invalid-action", "invalid-action-input", "invalid-role", "invalid-name", "reserved-name", "duplicate-name", "invalid-entity-id", "duplicate-entity-id", "missing-label", "missing-description", "invalid-title", "invalid-options", "invalid-default", "invalid-constraint", "unknown-relationship-target", "inverse-collision", "invalid-on-delete", "invalid-phrase", "invalid-index", "unknown-reference", "invalid-renamed-from", "earlier-name", "invalid-guide", "invalid-writes", "generated-update-empty", "managed-without-effect", "missing-permissions", "invalid-permission", "unknown-permission", "removed-allow", "unreachable-action", "wildcard-permission", "invalid-sign-in", "invalid-connection", "invalid-feedback", "invalid-discovery", "invalid-email", "feedback-unanswerable", "unknown-connection", "unused-connection", "invalid-prepare", "invalid-tool-name", "invalid-alignment", "single-entity-model-metric", "invalid-workflow", "workflow_role_unknown", "workflow_role_is_member", "workflow_role_grants_nothing", "workflow_role_wildcard", "workflow_role_scoped", "workflow_cron_never_fires", "workflow_input_invalid", "workflow_cron_invalid", "workflow_run_missing", "invalid-trigger", "trigger_action_unknown", "trigger_function_async", "workflow_trigger_limit_exceeded", "workflow_webhook_duplicate", "workflow_webhook_input_invalid", "workflow_webhook_mixed_triggers", "workflow_webhook_signature_invalid", "workflow_webhook_verification_invalid", "workflow_webhook_headers_invalid", "workflow_webhook_limit_exceeded"]>;
+        /** Where the problem is, for example `lead.properties.status.options[1]`. */
+        readonly path: Schema.String;
+        readonly message: Schema.String;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/** `defineOntology` found errors. Every diagnostic, including warnings, is attached. */
+export declare class InvalidOntology extends InvalidOntology_base {
+}
+export declare function formatDiagnostics(diagnostics: ReadonlyArray<Diagnostic>): string;
+export {};