@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/runtime-contract.d.ts

@@ -0,0 +1,508 @@
+import type { ActionRuntime } from "../runtime-source.js";
+import type { ConfirmationStore } from "../runtime/confirmations.js";
+import { Context, Schema, type Effect, type Layer, type Redacted } from "effect";
+import type { AttachmentRuntime } from "../storage/attachments.js";
+import type { BlobRuntime } from "../storage/sessions.js";
+import type { BlobStorageBinding } from "../storage/provider.js";
+import type { AnyAction } from "../action.js";
+import type { ResolvedEntity } from "../analyze.js";
+import type { ConnectionError, ConnectionTransport } from "../connection.js";
+import type { ActionError, DeploymentInterrupted, NotFound } from "../errors.js";
+import type { Ontology } from "../ontology.js";
+import type { Query, QueryResult } from "../query.js";
+import type { AgentTaskStore } from "../runtime/agent-tasks.js";
+import type { InvalidQuery, TriggerInputInvalid, WorkflowRecoveryUnavailable } from "../runtime/errors.js";
+import type { InvalidStartsCursor, SweepResult, WorkflowStarter, WorkflowStartsPage } from "../runtime/workflow-starts.js";
+import type { HistoryEntry } from "../runtime/history.js";
+import type { ActionOutcome, CommittedAction } from "../runtime/pipeline.js";
+import type { Principal, StoredRecord } from "../runtime.js";
+import type { SignInCheck } from "../sign-in.js";
+/**
+ * What the HTTP service needs from the SQL runtime in `src/runtime`, bound to one ontology and one
+ * database. `src/runtime/service-binding.ts` implements it; the service only calls it, and tests
+ * substitute it.
+ */
+export interface RunActionInput {
+    readonly runtime?: ActionRuntime;
+    readonly entity: string;
+    readonly action: string;
+    /** The input as the caller sent it. `runAction` validates it against the action's input schema. */
+    readonly input: unknown;
+    readonly principal: Principal;
+    readonly options: {
+        readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
+        /** Describe the action's confirmation in this chat language instead of running it. */
+        readonly confirm?: {
+            readonly locale: string;
+        };
+    };
+    /**
+     * Runs once the action has committed, outside its transaction, before `runAction` returns. It
+     * reports its own failures: the action stays committed whatever it does.
+     */
+    readonly afterCommit?: (committed: CommittedAction) => Effect.Effect<void>;
+    /** The request id, which `prepare` and the handler receive for logs. */
+    readonly requestId?: string;
+    /** Sends the calls of the action's `prepare` to its declared connections, bound to this request. */
+    readonly connections?: ConnectionTransport["Service"];
+}
+/**
+ * `generatedActions(entity, ontology)`: `create`, `update`, `delete`, `upsert_by_<property>`, `link`
+ * and `unlink`, as `src/runtime/generated-actions.ts` derives them.
+ */
+export type GeneratedActionsProvider = (entity: ResolvedEntity, ontology: Ontology) => Readonly<Record<string, AnyAction>>;
+/**
+ * Who verified a member's token: the workspace's Neon Auth, or SegmentStream, whose app tokens stay
+ * accepted while workspaces move to Neon Auth.
+ */
+export type IdentityProvider = "neon-auth" | "segmentstream";
+/** A member verified by their token. */
+export interface SignInIdentity {
+    readonly provider: IdentityProvider;
+    readonly oidcIdentity?: {
+        readonly issuer: string;
+        readonly subject: string;
+    };
+    /** The token's subject: the member's Neon Auth user id, or their WorkOS user id. */
+    readonly subject: string;
+    /** An address the provider verified; sign-in links the member invited with it. */
+    readonly email?: string;
+    readonly name?: string;
+}
+declare const NotInvited_base: Schema.Class<NotInvited, Schema.TaggedStruct<"NotInvited", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The sign-in policy is `invited` and nobody invited this person: no user has their identity or
+ * their email. Unlike other rejections the caller is told, so that the app can say what to do.
+ */
+export declare class NotInvited extends NotInvited_base {
+}
+/** How a client proves itself at the token endpoint; `none` for a public client, with PKCE only. */
+export type OAuthClientAuthMethod = "none" | "client_secret_post" | "client_secret_basic";
+/** A client that registered itself to connect an agent (RFC 7591 dynamic registration). */
+export interface OAuthClient {
+    readonly id: string;
+    readonly name: string;
+    readonly redirectUris: ReadonlyArray<string>;
+    readonly authMethod: OAuthClientAuthMethod;
+    /** SHA-256 of a confidential client's secret; null for a public client. */
+    readonly secretHash: string | null;
+    readonly clientUri: string | null;
+}
+/** An authorization request waiting, for a few minutes, for a member's consent. */
+export interface OAuthRequest {
+    readonly id: string;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    readonly state: string | null;
+    /** The PKCE S256 challenge the token request must answer. */
+    readonly codeChallenge: string;
+    readonly scope: string;
+    /** The MCP server the tokens are for (RFC 8707). */
+    readonly resource: string;
+    readonly expiresAt: Date;
+}
+/** RFC 8628 authorization. Both codes are stored as hashes. */
+export interface OAuthDevice {
+    readonly hash: string;
+    readonly userCodeHash: string;
+    readonly clientId: string;
+    readonly scope: string;
+    readonly resource: string;
+    readonly expiresAt: Date;
+    readonly interval: number;
+    readonly status: "pending" | "approved" | "denied" | "consumed";
+    readonly userId: string | null;
+}
+export type DevicePoll = {
+    readonly status: "approved";
+    readonly device: OAuthDevice;
+} | {
+    readonly status: "authorization_pending" | "slow_down" | "access_denied" | "expired_token" | "invalid_grant";
+};
+/** What a member allowed a client to do. Its tokens stop working once it is revoked. */
+export interface OAuthGrant {
+    readonly id: string;
+    readonly clientId: string;
+    readonly userId: string;
+    readonly scope: string;
+    readonly resource: string;
+    /** Present on access-token lookup, for absolute session expiry. */
+    readonly expiresAt?: Date;
+    /** Verified live identity binding, never client-supplied provenance. */
+    readonly identityProvider?: string;
+}
+export type OAuthTokenKind = "code" | "access" | "refresh";
+/** A code or token of a grant, stored only as the SHA-256 of its value. */
+export interface OAuthToken {
+    readonly hash: string;
+    readonly grantId: string;
+    readonly kind: OAuthTokenKind;
+    readonly expiresAt: Date;
+    /** For a code: the redirect URI it was sent to, which the token request must repeat. */
+    readonly redirectUri?: string;
+    /** For a code: the PKCE challenge the token request's verifier must answer. */
+    readonly codeChallenge?: string;
+}
+/**
+ * A consumed code or refresh token. An unused immediate successor can be recovered; consumption
+ * of that successor proves reuse of an older generation.
+ */
+export type UsedOAuthToken = {
+    readonly status: "valid";
+    readonly token: OAuthToken;
+    readonly grant: OAuthGrant;
+} | {
+    readonly status: "reused";
+    readonly grant: OAuthGrant;
+    /** True only with evidence of a consumed successor; missing recovery state is inconclusive. */
+    readonly successorUsed?: boolean;
+} | {
+    readonly status: "invalid";
+};
+/**
+ * Where the MCP server's authorization server keeps clients, pending requests, grants and tokens:
+ * the runtime's OAuth tables in the workspace database. Expiry is checked against the database's
+ * clock; failures are defects.
+ */
+export interface OAuthStore {
+    /** Locks a token row and commits consuming it, saving successors and replay together. */
+    readonly withTokenLock: <A>(hash: string, effect: Effect.Effect<A>) => Effect.Effect<A>;
+    /** Recovers an unexpired predecessor's unused successor, locking it until the transaction ends. */
+    readonly refreshReplay: (hash: string, graceMs: number) => Effect.Effect<string | undefined>;
+    readonly saveRefreshReplay: (hash: string, encrypted: string, successorHash: string) => Effect.Effect<void>;
+    readonly saveDevice: (device: OAuthDevice) => Effect.Effect<boolean>;
+    /** The device for a user code, whatever its status or expiry, until cleanup removes it. */
+    readonly findDevice: (userCodeHash: string) => Effect.Effect<OAuthDevice | undefined>;
+    /** Durable per-member verification budget, including invalid codes. */
+    readonly deviceAttempt: (memberId: string) => Effect.Effect<boolean>;
+    readonly decideDevice: (userCodeHash: string, userId: string, scope: string | undefined, decision: "approve" | "deny") => Effect.Effect<boolean>;
+    /** Serializes interval checks, backoff and single-use consumption. */
+    readonly pollDevice: (hash: string, clientId: string, resource: string | undefined) => Effect.Effect<DevicePoll>;
+    readonly saveClient: (client: OAuthClient) => Effect.Effect<void>;
+    /** Read on every access-token authentication; only ID/name become caller provenance. */
+    readonly findClient: (id: string) => Effect.Effect<OAuthClient | undefined>;
+    /** Stores a request, and forgets the expired ones. */
+    readonly saveRequest: (request: OAuthRequest) => Effect.Effect<void>;
+    /** A request that has not expired. */
+    readonly findRequest: (id: string) => Effect.Effect<OAuthRequest | undefined>;
+    /** Removes a request that has not expired and returns it: a request is decided once. */
+    readonly takeRequest: (id: string) => Effect.Effect<OAuthRequest | undefined>;
+    /** Records a grant, with its PKCE code when using browser authorization. */
+    readonly saveGrant: (grant: OAuthGrant, code?: OAuthToken) => Effect.Effect<void>;
+    /** Uses a code or refresh token, once, before it expires and while its grant stands. */
+    readonly useToken: (hash: string, kind: "code" | "refresh") => Effect.Effect<UsedOAuthToken>;
+    /** Stores new tokens, and forgets the expired ones. */
+    readonly saveTokens: (tokens: ReadonlyArray<OAuthToken>) => Effect.Effect<void>;
+    /** The grant of an access token that has not expired, unless the grant was revoked. */
+    readonly findAccess: (hash: string) => Effect.Effect<OAuthGrant | undefined>;
+    /** The grant of a token of any kind, revoked or not. */
+    readonly findGrantOfToken: (hash: string) => Effect.Effect<OAuthGrant | undefined>;
+    readonly revokeGrant: (id: string) => Effect.Effect<void>;
+    /** The member a grant acts for, with the roles they hold now; undefined once they may not sign in. */
+    readonly memberPrincipal: (userId: string) => Effect.Effect<Principal | undefined>;
+}
+/** A channel account waiting, for ten minutes, for a member to claim it with its pairing code. */
+export interface AgentPairing {
+    readonly id: string;
+    /** The channel, such as `telegram`. */
+    readonly provider: string;
+    /** The account's id on the channel. */
+    readonly externalId: string;
+    /** How the channel names the account, shown on the connect page. */
+    readonly display: string | null;
+    readonly expiresAt: Date;
+}
+/** A channel account paired with a member: the app's agent acts as the member for its messages. */
+export interface AgentIdentity {
+    readonly id: string;
+    readonly provider: string;
+    readonly externalId: string;
+    readonly userId: string;
+    readonly display: string | null;
+    readonly username?: string;
+    readonly createdAt: Date;
+    /** When the identity stopped working; null while it is live. */
+    readonly revokedAt: Date | null;
+    readonly origin: "paired" | "provisioned";
+    readonly noticedAt: Date | null;
+    readonly noticeSha256: string | null;
+    readonly noticeVersion: string | null;
+}
+/** A member as the agent names them: their user's name and the roles they hold now. */
+export interface AgentMember {
+    readonly name: string;
+    readonly principal: Principal;
+}
+/** Limits supplied only by the trusted runtime; fixed windows use the database clock. */
+export interface AgentLimits {
+    readonly perSender: {
+        readonly turnsPerMinute: number;
+        readonly turnsPerDay: number;
+    };
+    readonly newUsersPerHour: number;
+    readonly workspaceTurnsPerDay: number;
+}
+export type AgentLimitScope = "turnsPerMinute" | "turnsPerDay" | "newUsersPerHour" | "workspaceTurnsPerDay";
+export interface ResolveIdentityInput {
+    readonly provider: string;
+    readonly externalId: string;
+    readonly chat: "private" | "group";
+    readonly turn: boolean;
+    readonly display?: string | null;
+    readonly username?: string;
+    readonly noticeVersion?: string;
+    readonly noticeSha256?: string;
+    readonly limits?: {
+        readonly perSender?: Partial<AgentLimits["perSender"]>;
+        readonly newUsersPerHour?: number;
+        readonly workspaceTurnsPerDay?: number;
+    };
+}
+/** Verified provider facts only; channel-app callers cannot submit policy or bot-turn fields. */
+export type ChannelSignInInput = Pick<ResolveIdentityInput, "provider" | "externalId" | "display" | "username">;
+/** Admission runs before the issuer transaction, including shared limits and onNewUser. */
+export interface ChannelSessionStore {
+    readonly create: (input: ChannelSignInInput & {
+        readonly resource: string;
+    }) => Effect.Effect<AgentResolution | {
+        readonly status: "signed_in";
+        readonly token: string;
+        readonly expiresAt: Date;
+    }>;
+}
+export type AgentResolution = {
+    readonly status: "existing" | "created";
+    readonly member: AgentMember;
+    readonly provisioned: boolean;
+    readonly noticeDue: boolean;
+    readonly onNewUserPending: boolean;
+} | {
+    readonly status: "pairing_required";
+} | {
+    readonly status: "refused";
+    readonly reason: "blocked" | "inactive";
+} | {
+    readonly status: "limited";
+    readonly scope: AgentLimitScope;
+    readonly retryAfterSeconds: number;
+    readonly notify: boolean;
+    readonly notificationId?: string;
+};
+declare const IdentityInUse_base: Schema.Class<IdentityInUse, Schema.TaggedStruct<"IdentityInUse", {}>, import("effect/Cause").YieldableError>;
+/** An account already belongs to another member; approval must roll back without consuming the code. */
+export declare class IdentityInUse extends IdentityInUse_base {
+}
+/** A group chat the agent saw, as `POST /api/ontology/agent/chats/seen` answers. */
+export interface SeenChat {
+    readonly id: string;
+    readonly title: string;
+    readonly purpose: string | null;
+    readonly whenToUse: string | null;
+}
+/**
+ * Where the app's agent keeps pairing codes and the identities they create: the runtime's agent
+ * tables in the workspace database. Codes are stored only as SHA-256 hashes. Expiry is checked
+ * against the database's clock; failures are defects.
+ */
+export interface AgentStore {
+    readonly confirmations?: ConfirmationStore;
+    /** Stores a pairing under its code's hash and forgets expired ones; false when the hash is taken. */
+    readonly savePairing: (pairing: AgentPairing & {
+        readonly codeHash: string;
+    }) => Effect.Effect<boolean>;
+    /** A pairing that has neither expired nor been approved. */
+    readonly findPairing: (codeHash: string) => Effect.Effect<AgentPairing | undefined>;
+    /**
+     * Consumes a live pairing once. The same account on the same member is idempotent; another
+     * member's live account fails without consuming the code. Replaces the member's own previous
+     * account on that provider. `undefined` when the pairing expired or was already approved.
+     */
+    readonly approvePairing: (input: {
+        readonly codeHash: string;
+        readonly userId: string;
+        readonly identityId: string;
+    }) => Effect.Effect<AgentIdentity | undefined, IdentityInUse>;
+    /** Finds an active identity, or provisions a private sender when the channel admits strangers. */
+    readonly resolveIdentity: (input: ResolveIdentityInput) => Effect.Effect<AgentResolution>;
+    /** Complete the leased limit-reply claim only after delivery, or release it after failure. */
+    readonly completeLimitNotice: (input: {
+        readonly notificationId: string;
+        readonly delivered: boolean;
+    }) => Effect.Effect<boolean>;
+    /** Trusted member management; false for an unknown member id. Revokes sessions when blocking. */
+    readonly setMemberBlocked: (input: {
+        readonly id: string;
+        readonly blocked: boolean;
+    }) => Effect.Effect<boolean>;
+    /** Acknowledges first-contact notice delivery on a live provisioned identity. */
+    readonly recordNotice: (input: {
+        readonly provider: string;
+        readonly externalId: string;
+        readonly sha256: string;
+        readonly version?: string;
+    }) => Effect.Effect<boolean>;
+    /** The account's live identity, else its latest revoked one, else `undefined`. */
+    readonly findIdentity: (input: {
+        readonly provider: string;
+        readonly externalId: string;
+    }) => Effect.Effect<AgentIdentity | undefined>;
+    /** The member's live identities, oldest first. */
+    readonly listIdentities: (userId: string) => Effect.Effect<ReadonlyArray<AgentIdentity>>;
+    /** Revokes one of the member's live identities; false when they have no such identity. */
+    readonly revokeIdentity: (input: {
+        readonly id: string;
+        readonly userId: string;
+    }) => Effect.Effect<boolean>;
+    /** An active member by user id; `undefined` for an unknown user, a service or an inactive member. */
+    readonly member: (userId: string) => Effect.Effect<AgentMember | undefined>;
+    /** The member a runtime caller acts for: active, and with a live identity. */
+    readonly actingMember: (userId: string, provider?: string) => Effect.Effect<Principal | undefined>;
+    /**
+     * Records a message the agent saw in a group chat: creates the `agent_chat` or keeps its title
+     * current, records when the chat last had a message (at most every 15 minutes, so that history
+     * keeps it without a row per message), links the writer to its members when they are an active
+     * member, and unlinks `leftMemberId`, a member who left, when linked. With `agentLeft`, the agent
+     * itself left the chat: every member is unlinked, and the chat stays. With `migratedFrom`, the
+     * chat had that id before it became a supergroup: its record moves to `externalId`, or, when both
+     * ids have one, the new record takes the old one's members, and its purpose and when to use where
+     * it has none. Concurrent calls for one chat leave one record.
+     */
+    readonly seeChat: (input: {
+        readonly provider: string;
+        readonly externalId: string;
+        readonly title: string;
+        readonly memberId?: string;
+        readonly leftMemberId?: string;
+        readonly agentLeft?: true;
+        readonly migratedFrom?: string;
+    }) => Effect.Effect<SeenChat>;
+}
+declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream/ontology/OntologyBackend", {
+    readonly workflowAdmissions?: {
+        readonly ensureRecovery: (commitBy: number) => Effect.Effect<number, WorkflowRecoveryUnavailable>;
+        readonly reserve: (start: import("../runtime/workflow-admission.js").AdmittedWorkflowStart) => Effect.Effect<import("../runtime/workflow-admission.js").AdmittedWorkflowStart, import("../errors.js").DeploymentSwitching | DeploymentInterrupted | WorkflowRecoveryUnavailable>;
+        readonly submitted: (start: import("../runtime/workflow-admission.js").AdmittedWorkflowStart) => Effect.Effect<void>;
+    };
+    readonly blobs?: BlobRuntime;
+    /** The agent's temporary attachments, on deployments with file storage. */
+    readonly attachments?: AttachmentRuntime;
+    readonly maintainBlobs?: Effect.Effect<{
+        readonly removed: number;
+    }, unknown>;
+    readonly runAction: (input: RunActionInput) => Effect.Effect<ActionOutcome, ActionError | ConnectionError | TriggerInputInvalid | WorkflowRecoveryUnavailable>;
+    /**
+     * The starts action triggers decided, in `_workflow_starts`: the sweep that starts the pending
+     * ones, and a workflow's listing. Absent on a backend without the table's runtime.
+     */
+    readonly workflowStarts?: {
+        readonly sweep: (input: {
+            /** Also retry the rows the automatic sweep gave up on. */
+            readonly retryAbandoned: boolean;
+            readonly requestId: string;
+            /** The recovery run's horizon: count as waiting only the rows created before it. */
+            readonly before?: string | undefined;
+        }) => Effect.Effect<SweepResult>;
+        readonly list: (input: {
+            /** The workflow's wire name. */
+            readonly workflow: string;
+            /** Only the pending, or only the started, starts; all when absent. */
+            readonly pending?: boolean | undefined;
+            readonly limit: number;
+            readonly after?: string | undefined;
+        }) => Effect.Effect<WorkflowStartsPage, InvalidStartsCursor>;
+    };
+    /** The tasks workflows hand the app's agent, in `_agent_tasks`. */
+    readonly agentTasks?: AgentTaskStore;
+    /**
+     * One record. With a `reader` holding scoped permissions, a record outside its read scope is
+     * NotFound; the reads, gets and histories of `find` and `history` honour the reader the same way.
+     */
+    readonly get: (input: {
+        readonly entity: string;
+        readonly id: string;
+        readonly reader?: Principal;
+    }) => Effect.Effect<StoredRecord, NotFound>;
+    /** A page of records; `InvalidQuery` for a query the entity cannot answer, such as a stale cursor. */
+    readonly find: (input: {
+        readonly entity: string;
+        readonly query: Query;
+        readonly reader?: Principal;
+    }) => Effect.Effect<QueryResult<StoredRecord>, InvalidQuery>;
+    /**
+     * A page of a record's history, newest first. A deleted record keeps its history, which a reader
+     * with a read scope of the entity no longer reads: they read the history of a record they can
+     * read now.
+     */
+    readonly history: (input: {
+        readonly entity: string;
+        readonly id: string;
+        readonly after?: string;
+        readonly limit?: number;
+        readonly reader?: Principal;
+    }) => Effect.Effect<QueryResult<HistoryEntry>, NotFound | InvalidQuery>;
+    /**
+     * The workspace's keyless pipeline worker, for a verified workload token whose subject is
+     * `pipeline-workers:<workspace id>`. `undefined` when it may not act.
+     */
+    readonly resolveHookService?: (heldRole: string) => Effect.Effect<Principal | undefined>;
+    readonly resolvePipelineWorker?: (execution: import("../runtime/workload.js").WorkloadExecution) => Effect.Effect<Principal | undefined>;
+    /**
+     * A workflow's keyless service user, `workflows:<workspace id>:<workflow name>`, which the
+     * workflow's runs act as in this process. `undefined` for a workflow the ontology does not
+     * declare and for an inactive user. No token resolves it.
+     */
+    readonly resolveWorkflowUser?: (input: {
+        readonly workspaceId: string;
+        readonly workflow: string;
+    }) => Effect.Effect<Principal | undefined>;
+    /**
+     * Finds, links or creates the member's user. `undefined` when the user may not sign in, and
+     * {@link NotInvited} when the sign-in policy turns away a person nobody invited.
+     */
+    readonly resolvePrincipal: (identity: SignInIdentity) => Effect.Effect<Principal | undefined, NotInvited>;
+    /**
+     * Whether a person may sign in with this address, and how, read before the app emails them.
+     * It changes nothing, and unlike `resolvePrincipal` it needs no token.
+     */
+    readonly checkSignIn: (email: string) => Effect.Effect<SignInCheck>;
+    /** The user holding an `ssk_` key, or `undefined` for an unknown or revoked key. */
+    readonly resolveApiKey: (key: Redacted.Redacted<string>) => Effect.Effect<Principal | undefined>;
+    /** The manifest hash recorded in the `_ontology` catalog table, or `undefined` before the first. */
+    readonly appliedHash: Effect.Effect<string | undefined>;
+    readonly replicationEnabled?: Effect.Effect<boolean>;
+    /** The OAuth tables, for members who connect agents; without it, agents use API keys. */
+    readonly oauth?: OAuthStore;
+    readonly channelSessions?: ChannelSessionStore;
+    readonly federation?: import("../runtime/federation.js").FederationStore;
+    /** The agent tables, which pair channel accounts with members for the app's own agent. */
+    readonly agents?: AgentStore;
+}>;
+/**
+ * The runtime as the HTTP service sees it, with its database and ontology already bound. Failures
+ * outside the declared errors are defects and become a sanitized 500.
+ */
+export declare class OntologyBackend extends OntologyBackend_base {
+}
+/**
+ * The runtime binding `createOntologyService` runs against: the generated actions, and a layer that
+ * connects the runtime to the workspace database as `ontology_app`. `sqlServiceRuntime` is the
+ * default.
+ */
+export interface OntologyServiceRuntime {
+    readonly generatedActions: GeneratedActionsProvider;
+    readonly connect: (input: {
+        readonly deployment?: import("../deployment.js").DeploymentObservation;
+        readonly ontology: Ontology;
+        readonly databaseUrl: Redacted.Redacted<string>;
+        readonly blobStorage?: Redacted.Redacted<BlobStorageBinding>;
+        /** Starts the runs action triggers decide, after each action's commit and in the sweep. */
+        readonly workflowStarter?: WorkflowStarter["Service"];
+        /** Requests the sign-in links actions queue, after each action's commit. */
+        readonly signInLinks?: import("../runtime/sign-in-links.js").SignInLinks["Service"];
+    }) => Layer.Layer<OntologyBackend, unknown>;
+}
+export {};

package/dist/service/runtime-contract.js

@@ -0,0 +1,18 @@
+import { Context, Schema } from "effect";
+/**
+ * The sign-in policy is `invited` and nobody invited this person: no user has their identity or
+ * their email. Unlike other rejections the caller is told, so that the app can say what to do.
+ */
+export class NotInvited extends Schema.TaggedError()("NotInvited", {
+    message: Schema.String,
+}) {
+}
+/** An account already belongs to another member; approval must roll back without consuming the code. */
+export class IdentityInUse extends Schema.TaggedError()("IdentityInUse", {}) {
+}
+/**
+ * The runtime as the HTTP service sees it, with its database and ontology already bound. Failures
+ * outside the declared errors are defects and become a sanitized 500.
+ */
+export class OntologyBackend extends Context.Service()("@segmentstream/ontology/OntologyBackend") {
+}

package/dist/service/runtime-identity.d.ts

@@ -0,0 +1,71 @@
+import { Effect, Redacted } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { type JWTVerifyGetKey } from "jose";
+/**
+ * The header in which a runtime caller names the member it acts for: the member's user id. The
+ * service honours it only with a verified runtime token, so nobody else can claim a member with it.
+ */
+export declare const ACT_AS_HEADER = "x-segmentstream-act-as";
+/**
+ * The header in which the app's agent, running a task a workflow handed it, presents the task's
+ * secret instead of naming a member. With a verified runtime token it authenticates as the task's
+ * workflow user, on `/mcp` and the task routes only; every other route refuses it.
+ */
+export declare const AGENT_TASK_HEADER = "x-segmentstream-agent-task";
+/**
+ * Whom the service trusts as its runtime caller: Vercel OIDC tokens of the functions of this
+ * deployment's own project. The app's agent is a service of the same Vercel project as the ontology
+ * service, so `VERCEL_PROJECT_ID` pins exactly the deployment's own functions.
+ */
+export interface RuntimeIdentityConfig {
+    /** The team's issuer: `https://oidc.vercel.com/<team slug>` in team issuer mode. */
+    readonly issuer: string;
+    /** The audience Vercel issues function tokens for: `https://vercel.com/<team slug>`. */
+    readonly audience: string;
+    /** The project the token must name, from `VERCEL_PROJECT_ID`. */
+    readonly projectId: string;
+}
+export type RuntimeVerification = {
+    readonly status: "valid";
+}
+/** The token claims the runtime issuer but fails verification; `reason` names what failed. */
+ | {
+    readonly status: "invalid";
+    readonly reason: string;
+} | {
+    readonly status: "unavailable";
+}
+/** The token does not claim the runtime issuer: it is some other credential. */
+ | {
+    readonly status: "other";
+};
+/** Verifies a bearer token as the deployment's own runtime token. */
+export type RuntimeTokenVerifier = (token: string) => Promise<RuntimeVerification>;
+/** The issuer's key set, at `<issuer>/.well-known/jwks` as Vercel publishes it. */
+export declare function runtimeKeySet(issuer: string): JWTVerifyGetKey;
+/**
+ * Verifies the Vercel OIDC token of a function of this deployment's project, as backend-next
+ * verifies the ontology service's own: RS256 from the team's issuer, for the team's audience,
+ * unexpired, with `project_id` equal to the configured project and `environment` `production`.
+ * The issuer and the audience name the team, so no further owner check is needed. A token that
+ * claims another issuer is `other`, without a key-set fetch.
+ */
+export declare function makeRuntimeTokenVerifier(config: RuntimeIdentityConfig, keySet: JWTVerifyGetKey): RuntimeTokenVerifier;
+/** The runtime verifier on the issuer's remote key set, which jose caches between requests. */
+export declare function runtimeTokenVerifier(config: RuntimeIdentityConfig): RuntimeTokenVerifier;
+/** A runtime token that failed verification: the reason is logged, the token never. */
+export declare function logRuntimeRejection(reason: string): Effect.Effect<void>;
+/** How a request may authenticate as the runtime: the verifier and the member it names, if any. */
+export declare const ACT_AS_PROVIDER_HEADER = "x-segmentstream-identity-provider";
+export interface RuntimeCredential {
+    readonly verify: RuntimeTokenVerifier;
+    /** The user id in `X-SegmentStream-Act-As`; `undefined` without the header. */
+    readonly actAs: string | undefined;
+    readonly provider?: string;
+    /** The task secret in `X-SegmentStream-Agent-Task`; `undefined` without the header. */
+    readonly agentTask?: Redacted.Redacted<string>;
+}
+/** The task secret a request presents; `undefined` without the header. */
+export declare function agentTaskSecret(request: HttpServerRequest.HttpServerRequest): Redacted.Redacted<string> | undefined;
+/** The request's runtime credential, or `undefined` while runtime authentication is disabled. */
+export declare function runtimeCredential(verify: RuntimeTokenVerifier | undefined, request: HttpServerRequest.HttpServerRequest): RuntimeCredential | undefined;