@fabrika/control-contract 0.8.1 → 0.9.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/control-contract",
-	"version": "0.8.1",
+	"version": "0.9.0-dev.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -11,12 +11,13 @@
 		"access": "public"
 	},
 	"files": [
-		"src"
+		"src",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		}
 	},
@@ -25,8 +26,8 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "0.8.1",
-		"@fabrika/app": "0.8.1",
-		"@fabrika/provider-contract": "0.8.1"
+		"@fabrika/auth-core": "0.9.0-dev.2",
+		"@fabrika/app": "0.9.0-dev.2",
+		"@fabrika/provider-contract": "0.9.0-dev.2"
 	}
 }

package/src/index.ts

@@ -207,9 +207,18 @@ export interface UpdateAppRequest extends AppOptionalFields {
 	repoUrl?: string
 }
 
+/**
+ * `dev` follows the workspace bound to it through its launcher, without a run (ADR-0049); at most one per application,
+ * never protected and never production. Every other environment is `standard`.
+ */
+export const APP_ENV_KINDS = ['standard', 'dev'] as const
+
+export type AppEnvKind = (typeof APP_ENV_KINDS)[number]
+
 export interface AppEnvDto {
 	appId: string
 	env: string
+	kind: AppEnvKind
 	domain: string | null
 	publicOrigin: string | null
 	/** The exact origins whose pages may call this environment's cross-origin endpoints (ADR-0022); empty lists none. */
@@ -272,6 +281,8 @@ export interface PutAppEnvRequest {
 	triggerRef?: string | null
 	/** Omitted keeps the stored value. Only a Zerops environment of an app with a GitHub connection qualifies. */
 	authoring?: boolean
+	/** Set when the environment is created, `standard` when omitted; it never changes afterwards. */
+	kind?: AppEnvKind
 	namespaceId?: string | null
 	target: ProviderEnvelopeDto
 	artifact: ProviderEnvelopeDto

package/types/src/access.d.ts

@@ -0,0 +1,56 @@
+/** IAM vocabulary shared by the Control runtime, its Access schema and the console. */
+/** Durable IAM application id of the console — a deployed identity, not configuration branding (ADR-0024). */
+export declare const CONTROL_APP_ID = "vozka";
+/**
+ * The actions Control authorizes against. AWS-IAM-style dotted strings; IAM's `permits` matches
+ * them (incl. `*` / `prefix.*` wildcards in granted roles).
+ */
+export declare const CONTROL_ACTIONS: Readonly<{
+    /** Trigger a deploy run (the manual "Deploy" button / triggerDeploy RPC). Scoped by app/environment. */
+    DEPLOY_TRIGGER: "deploy.trigger";
+    /** Read deploy runs + their logs (run history API). Scoped by app/environment. */
+    DEPLOY_READ: "deploy.read";
+    /** Manage the app registry (apps + app_envs CRUD, onboarding). Scoped by app (global to create). */
+    APP_MANAGE: "app.manage";
+    /** Manage provider-owned deployment namespaces and their lifecycle. Global because namespaces may span apps. */
+    NAMESPACE_MANAGE: "namespace.manage";
+    /**
+     * Manage SECRET VALUES + their references. Gates the app_secrets reference CRUD (scoped by app) AND
+     * writing/rotating/deleting the encrypted per-app/app-env VALUES in the vault. The value is
+     * write-only over the API; it is never returned. (Platform creds — the CF token, IAM
+     * provisioning creds — are fabrika's own Worker secrets, not managed through this action.)
+     */
+    SECRET_MANAGE: "secret.manage";
+    /** Manage the platform GitHub source connection. Global because it changes control-wide credentials. */
+    SOURCE_CONNECTION_MANAGE: "source.connection.manage";
+    /** Read the files of one's own Git workspaces on an authoring target (ADR-0049). Scoped by app/environment. */
+    SOURCE_WORKSPACE_READ: "source.workspace.read";
+    /** Create Git workspaces and commit to them on an authoring target. Scoped by app/environment. */
+    SOURCE_WORKSPACE_WRITE: "source.workspace.write";
+    /** Open a pull request from one's own workspace to the default branch. Scoped by app/environment. */
+    SOURCE_PULL_REQUEST_CREATE: "source.pull-request.create";
+    /**
+     * Approve a widening of an environment's access and change its `protected` flag (ADR-0050). Outside `deploy.*`, so
+     * the operator role does not hold it; only a human user principal in the console may use it. Scoped by app/environment.
+     */
+    ACCESS_APPROVE: "access.approve";
+    /**
+     * List relayed mail and read its metadata. Scoped by app/environment for an application's messages; an installation
+     * sender's messages need a global grant.
+     */
+    MAIL_READ: "mail.read";
+    /** Read a relayed message's recipient, subject and bodies. Global. */
+    MAIL_CONTENT_READ: "mail.content.read";
+    /** Release or drop a held message, requeue a final one, and change the gate's rules. Global. */
+    MAIL_MANAGE: "mail.manage";
+}>;
+/**
+ * The scope dimensions Control authorizes within (flat + independent IAM semantics):
+ *  - `app`         — scoped to one registered app (its `id`), across every environment.
+ *  - `environment` — scoped to one environment name (e.g. only `stage`), across apps.
+ * A grant with neither scope is global.
+ */
+export declare const CONTROL_SCOPES: Readonly<{
+    APP: "app";
+    ENVIRONMENT: "environment";
+}>;

package/types/src/builder-bootstrap.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+export declare const BUILDER_APPROVAL_STORAGE_KEY = "fabrika.builder.approval.v1";
+export declare const BUILDER_AUTHORIZE_PATH = "/builder/authorize";
+export interface BuilderApprovalState {
+    readonly attemptId: string;
+    readonly approvalVerifier: string;
+    readonly expiresAt: number;
+}
+export interface BuilderInstallationDiscoveryDto {
+    readonly version: 1;
+    readonly controlOrigin: string;
+    readonly iamIssuer: string;
+    readonly provider: string;
+}
+/** Self-contained so the public capture page can embed this exact validator without external assets. */
+export declare function parseBuilderApprovalState(value: unknown, nowSeconds?: number): BuilderApprovalState | null;
+/** Accept only a credential-free installation origin, never a redirect or a repository-selected path. */
+export declare function parseBuilderPublicOrigin(value: unknown): string | null;
+export declare function parseBuilderInstallationDiscovery(value: unknown): BuilderInstallationDiscoveryDto | null;
+export declare const builderPublicOriginSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const builderInstallationDiscoverySchema: z.ZodEffects<z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    controlOrigin: z.ZodEffects<z.ZodString, string, string>;
+    iamIssuer: z.ZodEffects<z.ZodString, string, string>;
+    provider: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    version: 1;
+    controlOrigin: string;
+    iamIssuer: string;
+    provider: string;
+}, {
+    version: 1;
+    controlOrigin: string;
+    iamIssuer: string;
+    provider: string;
+}>, {
+    version: 1;
+    controlOrigin: string;
+    iamIssuer: string;
+    provider: string;
+}, unknown>;

package/types/src/builder-connections.d.ts

@@ -0,0 +1,223 @@
+import { z } from 'zod';
+import type { AppDto } from './index.js';
+export declare const BUILDER_CONNECTION_ATTEMPT_ID: RegExp;
+export declare const BUILDER_APPROVAL_VERIFIER: RegExp;
+export declare const BUILDER_CONNECTION_IDENTIFIER: RegExp;
+export interface BuilderConnectionEnvironmentDto {
+    readonly env: string;
+    readonly namespaceId: string | null;
+    readonly domain: string | null;
+    readonly publicOrigin: string | null;
+    readonly triggerRef: string | null;
+}
+export interface BuilderConnectionReceiptDto {
+    readonly version: 1;
+    readonly attemptId: string;
+    readonly provider: string;
+    readonly app: AppDto;
+    readonly environment: BuilderConnectionEnvironmentDto;
+    readonly createdAt: number;
+}
+export interface CreateBuilderConnectionReceiptRequest {
+    readonly attemptId: string;
+    readonly approvalVerifier: string;
+    readonly appId: string;
+    readonly environment: BuilderConnectionEnvironmentDto;
+}
+export interface GetBuilderConnectionReceiptRequest {
+    readonly attemptId: string;
+}
+/** Decode the persisted/wire snapshot without accepting provider envelopes or credential fields. */
+export declare function parseBuilderConnectionReceipt(value: unknown): BuilderConnectionReceiptDto;
+export declare const builderConnectionAppSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    repoUrl: z.ZodString;
+    defaultBranch: z.ZodString;
+    workerDir: z.ZodNullable<z.ZodString>;
+    buildCmd: z.ZodNullable<z.ZodString>;
+    configPath: z.ZodNullable<z.ZodString>;
+    githubConnectionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    githubInstallationId: z.ZodNullable<z.ZodNumber>;
+    createdAt: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    repoUrl: string;
+    defaultBranch: string;
+    workerDir: string | null;
+    buildCmd: string | null;
+    configPath: string | null;
+    githubInstallationId: number | null;
+    createdAt: number;
+    githubConnectionId?: string | null | undefined;
+}, {
+    id: string;
+    repoUrl: string;
+    defaultBranch: string;
+    workerDir: string | null;
+    buildCmd: string | null;
+    configPath: string | null;
+    githubInstallationId: number | null;
+    createdAt: number;
+    githubConnectionId?: string | null | undefined;
+}>, {
+    githubInstallationId: number | null;
+    createdAt: number;
+    githubConnectionId?: string | null | undefined;
+    id: string;
+    repoUrl: string;
+    defaultBranch: string;
+    workerDir: string | null;
+    buildCmd: string | null;
+    configPath: string | null;
+}, {
+    id: string;
+    repoUrl: string;
+    defaultBranch: string;
+    workerDir: string | null;
+    buildCmd: string | null;
+    configPath: string | null;
+    githubInstallationId: number | null;
+    createdAt: number;
+    githubConnectionId?: string | null | undefined;
+}>;
+export declare const builderConnectionEnvironmentSchema: z.ZodObject<{
+    env: z.ZodString;
+    namespaceId: z.ZodNullable<z.ZodString>;
+    domain: z.ZodNullable<z.ZodString>;
+    publicOrigin: z.ZodNullable<z.ZodString>;
+    triggerRef: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    env: string;
+    domain: string | null;
+    publicOrigin: string | null;
+    triggerRef: string | null;
+    namespaceId: string | null;
+}, {
+    env: string;
+    domain: string | null;
+    publicOrigin: string | null;
+    triggerRef: string | null;
+    namespaceId: string | null;
+}>;
+export declare const builderConnectionReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    attemptId: z.ZodString;
+    provider: z.ZodString;
+    app: z.ZodEffects<z.ZodObject<{
+        id: z.ZodString;
+        repoUrl: z.ZodString;
+        defaultBranch: z.ZodString;
+        workerDir: z.ZodNullable<z.ZodString>;
+        buildCmd: z.ZodNullable<z.ZodString>;
+        configPath: z.ZodNullable<z.ZodString>;
+        githubConnectionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        githubInstallationId: z.ZodNullable<z.ZodNumber>;
+        createdAt: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        repoUrl: string;
+        defaultBranch: string;
+        workerDir: string | null;
+        buildCmd: string | null;
+        configPath: string | null;
+        githubInstallationId: number | null;
+        createdAt: number;
+        githubConnectionId?: string | null | undefined;
+    }, {
+        id: string;
+        repoUrl: string;
+        defaultBranch: string;
+        workerDir: string | null;
+        buildCmd: string | null;
+        configPath: string | null;
+        githubInstallationId: number | null;
+        createdAt: number;
+        githubConnectionId?: string | null | undefined;
+    }>, {
+        githubInstallationId: number | null;
+        createdAt: number;
+        githubConnectionId?: string | null | undefined;
+        id: string;
+        repoUrl: string;
+        defaultBranch: string;
+        workerDir: string | null;
+        buildCmd: string | null;
+        configPath: string | null;
+    }, {
+        id: string;
+        repoUrl: string;
+        defaultBranch: string;
+        workerDir: string | null;
+        buildCmd: string | null;
+        configPath: string | null;
+        githubInstallationId: number | null;
+        createdAt: number;
+        githubConnectionId?: string | null | undefined;
+    }>;
+    environment: z.ZodObject<{
+        env: z.ZodString;
+        namespaceId: z.ZodNullable<z.ZodString>;
+        domain: z.ZodNullable<z.ZodString>;
+        publicOrigin: z.ZodNullable<z.ZodString>;
+        triggerRef: z.ZodNullable<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        env: string;
+        domain: string | null;
+        publicOrigin: string | null;
+        triggerRef: string | null;
+        namespaceId: string | null;
+    }, {
+        env: string;
+        domain: string | null;
+        publicOrigin: string | null;
+        triggerRef: string | null;
+        namespaceId: string | null;
+    }>;
+    createdAt: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    app: {
+        githubInstallationId: number | null;
+        createdAt: number;
+        githubConnectionId?: string | null | undefined;
+        id: string;
+        repoUrl: string;
+        defaultBranch: string;
+        workerDir: string | null;
+        buildCmd: string | null;
+        configPath: string | null;
+    };
+    environment: {
+        env: string;
+        domain: string | null;
+        publicOrigin: string | null;
+        triggerRef: string | null;
+        namespaceId: string | null;
+    };
+    attemptId: string;
+    version: 1;
+    provider: string;
+    createdAt: number;
+}, {
+    app: {
+        id: string;
+        repoUrl: string;
+        defaultBranch: string;
+        workerDir: string | null;
+        buildCmd: string | null;
+        configPath: string | null;
+        githubInstallationId: number | null;
+        createdAt: number;
+        githubConnectionId?: string | null | undefined;
+    };
+    environment: {
+        env: string;
+        domain: string | null;
+        publicOrigin: string | null;
+        triggerRef: string | null;
+        namespaceId: string | null;
+    };
+    attemptId: string;
+    version: 1;
+    provider: string;
+    createdAt: number;
+}>;

package/types/src/builder-pairing.d.ts

@@ -0,0 +1,12 @@
+export type { ApproveDeviceAuthorizationResult, DenyDeviceAuthorizationResult, DeviceAuthorizationFailure, DeviceAuthorizationReceipt, DeviceAuthorizationRequest, InspectDeviceAuthorizationResult, ListOwnDeviceAuthorizationsResult, RevokeKeyResult, } from '@fabrika/auth-core';
+export interface BuilderPairingProofRequest {
+    readonly attemptId: string;
+    readonly approvalVerifier: string;
+}
+export interface ListOwnBuilderPairingsRequest {
+    readonly before?: string;
+    readonly limit?: number;
+}
+export interface RevokeBuilderPairingRequest {
+    readonly credentialId: string;
+}

package/types/src/index.d.ts

@@ -0,0 +1,500 @@
+import type { EndpointKind, EndpointMethod } from '@fabrika/auth-core';
+import type { JsonValue, ProviderEnvelope } from '@fabrika/provider-contract';
+import { z } from 'zod';
+export * from './access.js';
+export * from './builder-bootstrap.js';
+export * from './builder-connections.js';
+export * from './builder-pairing.js';
+export * from './mail.js';
+export type { JsonValue };
+/** A plain list response. */
+export interface ListResponse<T> {
+    items: T[];
+}
+/** A keyset-paginated list. */
+export interface CursorList<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+export type ProviderEnvelopeDto = ProviderEnvelope;
+/** What the console needs to know about the installation it runs in. */
+export interface InstallationDto {
+    /** The id of the one provider bundle this installation composes (ADR-0011). */
+    readonly provider: string;
+}
+/**
+ * The console actions the caller's verified token holds, in the shape of an application's caller document. The
+ * console shows and hides by it; it decides nothing, because every procedure checks its own action.
+ */
+export interface ConsoleAccessDto {
+    /** Null for a credential bound to no principal. */
+    readonly principal: {
+        readonly id: string;
+        readonly label: string;
+    } | null;
+    /** The actions held as a global grant, so in every scope value. */
+    readonly global: readonly string[];
+    /** Each scope value the caller holds an action in, with those actions; sorted by dimension, then value. */
+    readonly scopes: readonly ConsoleScopedActionsDto[];
+}
+export interface ConsoleScopedActionsDto {
+    readonly type: string;
+    readonly value: string;
+    readonly actions: readonly string[];
+}
+export interface GitHubSourceRepositoryDto {
+    readonly owner: string;
+    readonly name: string;
+}
+export interface GitHubSourceConnectionAppDto {
+    readonly id: number;
+    readonly slug: string;
+    readonly htmlUrl: string;
+    readonly public: boolean;
+    readonly owner: {
+        readonly login: string;
+        readonly type: 'Organization';
+    };
+    readonly permissions: {
+        readonly contents: 'read';
+    };
+    readonly events: readonly ['push'];
+}
+export interface GitHubSourceConnectionInstallationDto {
+    readonly id: number;
+    readonly accountLogin: string;
+    readonly repositorySelection: 'all' | 'selected';
+    readonly verifiedRepositories: readonly GitHubSourceRepositoryDto[];
+}
+interface GitHubSourceConnectionBaseDto {
+    readonly provider: string;
+    readonly kind: 'github-app';
+}
+export interface GitHubSourceConnectionAnonymousDto extends GitHubSourceConnectionBaseDto {
+    readonly state: 'anonymous';
+}
+export interface GitHubSourceConnectionUnavailableDto extends GitHubSourceConnectionBaseDto {
+    readonly state: 'unavailable';
+}
+export interface GitHubSourceConnectionSetupPendingDto extends GitHubSourceConnectionBaseDto {
+    readonly state: 'setup-pending';
+    readonly connectionId: string;
+    readonly phase: 'starting' | 'awaiting-manifest-callback' | 'persisting' | 'activating';
+    /** Present only while the same-origin manifest handoff can be resumed. */
+    readonly continuePath?: string;
+}
+export interface GitHubSourceConnectionInstallationRequiredDto extends GitHubSourceConnectionBaseDto {
+    readonly state: 'installation-required';
+    readonly connectionId: string;
+    readonly app: GitHubSourceConnectionAppDto;
+    readonly installationUrl: string;
+}
+/**
+ * The query parameter Control's GitHub setup URL adds when it sends the browser to the console's source page. It reports
+ * what that one return from GitHub found; the page still reads the connection state from the API.
+ */
+export declare const GITHUB_SETUP_OUTCOME_PARAM = "github-setup";
+export type GitHubSetupOutcome = 'connected' | 'approval-requested' | 'unverified';
+export interface GitHubSourceConnectionConnectedDto extends GitHubSourceConnectionBaseDto {
+    readonly state: 'connected';
+    readonly connectionId: string;
+    readonly app: GitHubSourceConnectionAppDto;
+    readonly installation: GitHubSourceConnectionInstallationDto;
+}
+export type GitHubSourceConnectionWorkflowDto = Exclude<GitHubSourceConnectionStatusDto, GitHubSourceConnectionConnectedDto>;
+export * from './source-connection-list.js';
+export interface GitHubSourceConnectionListInput {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface GitHubSourceConnectionListResponse {
+    readonly items: readonly GitHubSourceConnectionConnectedDto[];
+    readonly nextCursor: string | null;
+    /** The one global non-connected workflow state, when present. */
+    readonly workflow: GitHubSourceConnectionWorkflowDto | null;
+}
+export interface GitHubSourceConnectionRepairRequiredDto extends GitHubSourceConnectionBaseDto {
+    readonly state: 'repair-required';
+    readonly connectionId: string;
+    readonly reason: 'interrupted-setup' | 'credential-activation' | 'installation-verification';
+    readonly app?: GitHubSourceConnectionAppDto;
+}
+/** Browser-safe setup state. It never carries a private key, webhook secret, token, or source RPC key. */
+export type GitHubSourceConnectionStatusDto = GitHubSourceConnectionAnonymousDto | GitHubSourceConnectionUnavailableDto | GitHubSourceConnectionSetupPendingDto | GitHubSourceConnectionInstallationRequiredDto | GitHubSourceConnectionConnectedDto | GitHubSourceConnectionRepairRequiredDto;
+export interface StartGitHubSourceConnectionRequest {
+    readonly organization: string;
+    readonly appName: string;
+    readonly visibility: 'private' | 'public';
+    readonly repositories: readonly GitHubSourceRepositoryDto[];
+}
+export interface StartGitHubSourceConnectionResponse {
+    readonly connectionId: string;
+    /** Same-origin path that starts the GitHub manifest handoff. */
+    readonly continuePath: string;
+}
+/** One redacted line of deploy output: the runner's NDJSON log line and the control API's view of it. */
+export declare const runLogLineSchema: z.ZodObject<{
+    ts: z.ZodNumber;
+    stream: z.ZodEnum<["stdout", "stderr", "meta"]>;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    ts: number;
+    stream: "stdout" | "stderr" | "meta";
+}, {
+    text: string;
+    ts: number;
+    stream: "stdout" | "stderr" | "meta";
+}>;
+export type RunLogLine = z.infer<typeof runLogLineSchema>;
+/** Backward-compatible short name for browser consumers. */
+export type LogLine = RunLogLine;
+export interface SetSecretValueRequest {
+    value: string;
+    env?: string | null;
+}
+export interface AppDto {
+    id: string;
+    repoUrl: string;
+    defaultBranch: string;
+    workerDir: string | null;
+    buildCmd: string | null;
+    configPath: string | null;
+    githubConnectionId?: string | null;
+    githubInstallationId: number | null;
+    createdAt: number;
+}
+export interface AppOptionalFields {
+    defaultBranch?: string;
+    workerDir?: string | null;
+    buildCmd?: string | null;
+    configPath?: string | null;
+    /** Must equal the installation of the repository owner's GitHub connection. */
+    githubInstallationId?: number | null;
+    /** Bind the app to the repository owner's GitHub connection (one per owner). */
+    resolveInstallationId?: boolean;
+}
+export interface UpdateAppRequest extends AppOptionalFields {
+    repoUrl?: string;
+}
+/**
+ * `dev` follows the workspace bound to it through its launcher, without a run (ADR-0049); at most one per application,
+ * never protected and never production. Every other environment is `standard`.
+ */
+export declare const APP_ENV_KINDS: readonly ["standard", "dev"];
+export type AppEnvKind = (typeof APP_ENV_KINDS)[number];
+export interface AppEnvDto {
+    appId: string;
+    env: string;
+    kind: AppEnvKind;
+    domain: string | null;
+    publicOrigin: string | null;
+    /** The exact origins whose pages may call this environment's cross-origin endpoints (ADR-0022); empty lists none. */
+    crossOrigins: string[];
+    triggerRef: string | null;
+    /** An MCP authoring target (ADR-0049): users with `source.workspace.*` grants may edit and deploy it. */
+    authoring: boolean;
+    /** A widening of access waits for a human's approval here (ADR-0050); `prod` is protected by default. */
+    protected: boolean;
+    /** The run whose snapshot is this environment's active access; null until a run publishes one. */
+    publishedRunId: string | null;
+    /**
+     * The published snapshot's steps off the paved road, grouped by the site or migration that takes them: the reach its
+     * sites declare and the database code its migrations declare. Listed whether or not the environment is protected.
+     */
+    deviationSubjects: DeviationSubjectDto[];
+    /** The published snapshot's endpoints as the outside reaches them, most exposed first; empty until a run publishes one. */
+    surface: SurfaceEndpointDto[];
+    namespaceId: string | null;
+    provider: string;
+    target: ProviderEnvelopeDto;
+    artifact: ProviderEnvelopeDto;
+    createdAt: number;
+}
+/** One endpoint, job or migration of a published snapshot and its steps off the paved road. */
+export interface DeviationSubjectDto {
+    /** `Endpoint \`id\``, `Job \`name\`` or `Migration \`file\``. */
+    subject: string;
+    /** Each step, phrased to follow the subject: `declares raw SQL (\`read\`)`. */
+    steps: string[];
+}
+/** Who reaches an endpoint, most exposed first. */
+export declare const SURFACE_REACHES: readonly ["anyone", "link", "app", "machine", "human"];
+/** An endpoint is listed under its most exposed caller: `anyone` for an anonymous kind, `app` for an `app:<id>` caller. */
+export type SurfaceReach = (typeof SURFACE_REACHES)[number];
+/** One endpoint of a published snapshot, in the approval's words. */
+export interface SurfaceEndpointDto {
+    id: string;
+    method: EndpointMethod;
+    path: string;
+    kind: EndpointKind;
+    reach: SurfaceReach;
+    /** Every caller kind the endpoint admits; empty for an anonymous kind. */
+    callers: string[];
+    /** What a caller must hold: `who are members` or `` with `notes.read` (on `note`) ``; null for an anonymous kind. */
+    requirement: string | null;
+    /** What else opens the endpoint: another origin, a file it answers, a body limit, a form's protection, a signature. */
+    notes: string[];
+}
+export interface PutAppEnvRequest {
+    domain?: string | null;
+    publicOrigin?: string | null;
+    /** Replaces the stored list; omitted keeps it, and an empty list clears it. */
+    crossOrigins?: string[];
+    triggerRef?: string | null;
+    /** Omitted keeps the stored value. Only a Zerops environment of an app with a GitHub connection qualifies. */
+    authoring?: boolean;
+    /** Set when the environment is created, `standard` when omitted; it never changes afterwards. */
+    kind?: AppEnvKind;
+    namespaceId?: string | null;
+    target: ProviderEnvelopeDto;
+    artifact: ProviderEnvelopeDto;
+}
+export type DeploymentNamespaceState = 'pending' | 'provisioning' | 'ready' | 'failed';
+export interface DeploymentNamespaceDto {
+    id: string;
+    env: string;
+    provider: string;
+    exclusiveAppId: string | null;
+    target: ProviderEnvelopeDto;
+    state: DeploymentNamespaceState;
+    /**
+     * The last lifecycle failure, redacted and bounded, with its class in `lastErrorCode`: a stable
+     * identifier — a provider error code such as `insufficientPermissions`, or `internal` when the cause
+     * was not a typed provider failure — so a console can tell two failures apart without matching prose.
+     * A row written before the codes existed carries a message and no code.
+     */
+    lastError: string | null;
+    lastErrorCode: string | null;
+    /**
+     * Present only while a `namespaces.update` is unconfirmed (`lastErrorCode` `namespaceUpdateUnconfirmed`):
+     * the target that update was moving to. Retrying `namespaces.update` with it finishes the update.
+     */
+    unconfirmedTarget?: ProviderEnvelopeDto;
+    createdAt: number;
+}
+export interface DeploymentNamespaceDetailDto extends DeploymentNamespaceDto {
+    presentation: DeploymentNamespacePresentationDto | null;
+    /**
+     * The public hosts this namespace serves, with the environment that already claimed each one. Absent
+     * where the provider names none — a placement whose domains are bound out of band, or one whose entry
+     * point is not published yet.
+     */
+    readonly hosts?: readonly DeploymentNamespaceHostDto[];
+}
+/** One host a namespace serves, and the application environment whose domain already takes it. */
+export interface DeploymentNamespaceHostDto {
+    readonly host: string;
+    readonly port: number;
+    readonly takenBy?: {
+        readonly appId: string;
+        readonly environment: string;
+    };
+}
+export interface CreateDeploymentNamespaceRequest {
+    id: string;
+    env: string;
+    exclusiveAppId?: string | null;
+    target: ProviderEnvelopeDto;
+}
+export interface AdoptDeploymentNamespaceRequest {
+    env: string;
+    exclusiveAppId?: string | null;
+    target: ProviderEnvelopeDto;
+}
+/**
+ * A namespace's new provider target. Its payload may name only what changes; the provider merges it over
+ * the stored one. Only what the provider can change in place is accepted — on Zerops the PostgreSQL
+ * profile. A field the target does not have is a 400; any other change is a 409 that names the supported
+ * path, a new namespace under a new id.
+ */
+export interface UpdateDeploymentNamespaceRequest {
+    target: ProviderEnvelopeDto;
+}
+export interface DeploymentNamespaceFactDto {
+    readonly label: string;
+    readonly value: string;
+    /** Set when the value names a LIVE provider resource that outlives the namespace row (see removal). */
+    readonly resource?: boolean;
+}
+export interface DeploymentNamespacePresentationDto {
+    readonly preset: string;
+    readonly title: string;
+    readonly facts: readonly DeploymentNamespaceFactDto[];
+    readonly instructions: readonly string[];
+}
+export interface DeploymentNamespacePresetDto {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly requiresExclusiveApp: boolean;
+}
+export interface DeploymentNamespaceOperatorDto {
+    readonly presets: readonly DeploymentNamespacePresetDto[];
+}
+export interface DeploymentNamespaceListResponse {
+    items: DeploymentNamespaceDto[];
+    operator: DeploymentNamespaceOperatorDto | null;
+}
+/**
+ * What removal leaves behind. Fabrika deletes no provider resource: it holds OWNER on the projects it
+ * creates ([ADR-0034](../../../docs/decisions/0034-the-control-plane-creates-the-projects-it-owns.md)),
+ * so deleting one is a destructive act on live state that stays with the operator. The removed row is
+ * returned whole — its provider target and presentation name what is now unowned.
+ */
+export interface RemoveDeploymentNamespaceResponse {
+    readonly removed: DeploymentNamespaceDetailDto;
+}
+export interface PlanDeploymentNamespaceRequest {
+    id: string;
+    env: string;
+    preset: string;
+    exclusiveAppId?: string;
+    options?: JsonValue;
+}
+export interface PlannedDeploymentNamespaceDto {
+    readonly id: string;
+    readonly env: string;
+    readonly exclusiveAppId?: string;
+    readonly target: ProviderEnvelopeDto;
+}
+export interface PlanDeploymentNamespaceResponse {
+    readonly namespace: PlannedDeploymentNamespaceDto;
+    readonly presentation: DeploymentNamespacePresentationDto;
+}
+/**
+ * Where an app secret's value is kept: `vault` (control's vault), `provider` (the provider's own storage),
+ * or `legacy` — a row from before secrets were vault-only, which no deploy resolves until it is set again.
+ */
+export type AppSecretStorage = 'vault' | 'provider' | 'legacy';
+export interface AppSecretDto {
+    appId: string;
+    env: string | null;
+    name: string;
+    storage: AppSecretStorage;
+    /** The `vault:` ref; null for any other storage, whose stored ref control cannot vouch for. */
+    valueRef: string | null;
+    createdAt: number;
+}
+/** The plaintext is write-only: control seals it and stores only the resulting ref. */
+export interface PutAppSecretRequest {
+    name: string;
+    value: string;
+    env?: string | null;
+}
+export interface AppVarDto {
+    appId: string;
+    env: string | null;
+    name: string;
+    value: string;
+    createdAt: number;
+}
+export interface PutAppVarRequest {
+    name: string;
+    value: string;
+    env?: string | null;
+}
+export interface RegisterAppRequest extends AppOptionalFields {
+    id: string;
+    repoUrl: string;
+    env: string;
+    domain?: string | null;
+    publicOrigin?: string | null;
+    /** The environment's cross-origin list (ADR-0022); omitted lists none. */
+    crossOrigins?: string[];
+    triggerRef?: string | null;
+    namespaceId?: string | null;
+    target: ProviderEnvelopeDto;
+    artifact: ProviderEnvelopeDto;
+}
+export interface RegisterAppResponse {
+    app: AppDto;
+    env: AppEnvDto;
+}
+export type RunTrigger = 'webhook' | 'manual' | 'poll';
+/** `awaiting_approval`: the run widens access on a protected environment and waits for a human (ADR-0050). */
+export type RunStatus = 'pending' | 'running' | 'awaiting_approval' | 'succeeded' | 'failed';
+export interface RunDto {
+    id: string;
+    appId: string;
+    env: string;
+    ref: string;
+    commitSha: string | null;
+    trigger: RunTrigger;
+    /** Who created the run: `user:<id>`, `service:<id>`, `oauth:<id>` (an MCP client acting for a user), `webhook:<connection>` or `poll`. */
+    actor: string | null;
+    status: RunStatus;
+    exitCode: number | null;
+    externalRunId: string | null;
+    logKey: string | null;
+    createdAt: number;
+    startedAt: number | null;
+    finishedAt: number | null;
+}
+/**
+ * One plain-language line of an access change. `effect` is `widens` when it can grant access the baseline did not,
+ * `narrows` when it can only take access away, and `neutral` when it admits no one new and takes nothing away.
+ * `review: 'closer'` marks a step off the paved road (declared reach, database code) or a change the diff cannot classify.
+ */
+export interface AccessChangeDto {
+    effect: 'widens' | 'narrows' | 'neutral';
+    line: string;
+    review?: 'closer';
+    /** The line opens an endpoint to the pages on the origins the environment lists; `ApprovalDto.crossOrigins` names them. */
+    environmentOrigins?: true;
+}
+/** A run's access change against its environment's active snapshot (ADR-0050 §3). */
+export interface ApprovalDto {
+    run: RunDto;
+    /** `none`: no line. `no-widening`: lines that narrow or leave access unchanged; it publishes at once. */
+    outcome: 'none' | 'no-widening' | 'widening';
+    changes: AccessChangeDto[];
+    /** The digest of the run's snapshot and of the active one it was compared with: an approval is bound to both. */
+    candidateDigest: string;
+    baselineDigest: string;
+    /** The published run the change was compared with; null when nothing was published. */
+    baselineRunId: string | null;
+    protected: boolean;
+    /**
+     * The environment's cross-origin list as it stands now: the pages an endpoint the contract opens to the environment's
+     * list answers. It is set on the environment, takes effect at once, and no approval covers it (ADR-0050). Only on one
+     * approval read while the run waits for a decision, its environment exists and a line has `environmentOrigins`;
+     * empty when the environment lists none.
+     */
+    crossOrigins?: string[];
+    /** The human who approved it, once one did. */
+    approval: {
+        principalId: string;
+        label: string;
+        approvedAt: number;
+    } | null;
+}
+/** Approve or refuse one parked run. The digests are the ones the approver read; a reclassified run refuses them. */
+export interface CompleteApprovalRequest {
+    runId: string;
+    decision: 'approve' | 'reject';
+    candidateDigest: string;
+    baselineDigest: string;
+}
+/** Change whether a widening waits for approval on one environment (ADR-0050 §4). */
+export interface SetEnvironmentProtectionRequest {
+    appId: string;
+    env: string;
+    protected: boolean;
+}
+export interface TriggerDeployRequest {
+    appId: string;
+    env: string;
+    ref?: string;
+}
+export interface RunTailResponse {
+    lines: RunLogLine[];
+    cursor: number;
+    done: boolean;
+    status: RunStatus;
+}
+export interface RunLogResponse {
+    lines: RunLogLine[];
+    status?: RunStatus;
+}
+export type { AdoptNamespaceInput, AppEnvironmentInput, AppIdInput, AppNamedValueInput, ControlRpcContract, CreateAppRequest, DescribeConnectorRequest, GitHubSourceConnectionInput, GitHubSourceConnectionRpcContract, NamespaceIdInput, OkResponse, PutAppEnvironmentInput, PutAppSecretInput, PutAppVarInput, RotateTokenKeyResponse, RunIdInput, RunListInput, SecretValueInput, SecretValueResponse, TailRunInput, UpdateNamespaceInput, } from './rpc.js';

package/types/src/mail.d.ts

@@ -0,0 +1,88 @@
+/** The mail relay as the console reads and steers it. */
+/**
+ * `held` waits for a person, `queued` for the dispatcher, `sending` is one attempt a dispatcher claimed. `sent`,
+ * `failed` (not sent), `unknown` (may have left) and `dropped` are final.
+ */
+export type MailMessageState = 'held' | 'queued' | 'sending' | 'sent' | 'failed' | 'unknown' | 'dropped';
+export type MailRuleAction = 'pass' | 'hold' | 'drop';
+/** A relayed message's metadata, behind `mail.read`. It carries no recipient, subject or body. */
+export interface MailMessageDto {
+    readonly id: string;
+    /** `<app>@<env>`, or `installation:<service>` for an installation sender. */
+    readonly sender: string;
+    readonly recipientDomain: string;
+    readonly state: MailMessageState;
+    /** The rule that decided the message at acceptance; null when none did. */
+    readonly ruleId: string | null;
+    /** Who released or dropped it, or requeued it once it was final. */
+    readonly decidedBy: string | null;
+    readonly attempts: number;
+    readonly nextAttemptAt: number | null;
+    readonly providerMessageId: string | null;
+    /**
+     * The `EmailDeliveryErrorCode` of the last failed attempt, or `dispatch_interrupted`: the dispatcher stopped after it
+     * claimed the attempt, before it recorded an outcome.
+     */
+    readonly errorCode: string | null;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/** One attachment as the console shows it: its name, type and size, never its bytes. */
+export interface MailAttachmentDto {
+    readonly filename: string;
+    readonly contentType: string;
+    readonly bytes: number;
+}
+/** What the recipient sees, behind `mail.content.read`. */
+export interface MailMessageContentDto {
+    readonly to: string;
+    readonly subject: string;
+    readonly text: string;
+    readonly html?: string;
+    readonly replyTo?: string;
+    readonly fromName?: string;
+    readonly unsubscribeUrl?: string;
+    readonly attachments: readonly MailAttachmentDto[];
+}
+/** `withheld`: the caller does not hold `mail.content.read`. `purged`: the relay no longer keeps it. */
+export type MailContentDto = {
+    readonly kind: 'withheld';
+} | {
+    readonly kind: 'purged';
+} | {
+    readonly kind: 'present';
+    readonly message: MailMessageContentDto;
+};
+export interface MailMessageDetailDto extends MailMessageDto {
+    readonly content: MailContentDto;
+    /** Whether a requeue would send it again now: `failed`, or `unknown` over an idempotent transport, with its content kept. */
+    readonly requeueable: boolean;
+}
+export interface MailMessageListInput {
+    readonly state?: MailMessageState;
+    /** One sender: `<app>@<env>` or `installation:<service>`. */
+    readonly scope?: string;
+    readonly cursor?: string;
+}
+export interface MailMessageIdInput {
+    readonly id: string;
+}
+export interface MailRuleDto {
+    readonly id: string;
+    /** `*` or `<app>@<env>`. */
+    readonly scope: string;
+    /** `*` or a lowercase recipient domain. */
+    readonly domain: string;
+    readonly action: MailRuleAction;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/** Sets the action of the rule of `scope` and `domain`, creating it when there is none. */
+export interface SetMailRuleInput {
+    readonly scope: string;
+    readonly domain: string;
+    readonly action: MailRuleAction;
+}
+export interface MailRuleIdInput {
+    readonly id: string;
+}

package/types/src/rpc.d.ts

@@ -0,0 +1,193 @@
+import type { RpcProcedureContract } from '@fabrika/app';
+import type { ExportDescription } from '@fabrika/auth-core';
+import type { BuilderConnectionReceiptDto, CreateBuilderConnectionReceiptRequest, GetBuilderConnectionReceiptRequest } from './builder-connections.js';
+import type { ApproveDeviceAuthorizationResult, BuilderPairingProofRequest, DenyDeviceAuthorizationResult, InspectDeviceAuthorizationResult, ListOwnBuilderPairingsRequest, ListOwnDeviceAuthorizationsResult, RevokeBuilderPairingRequest, RevokeKeyResult } from './builder-pairing.js';
+import type { AdoptDeploymentNamespaceRequest, AppDto, AppEnvDto, ApprovalDto, AppSecretDto, AppVarDto, CompleteApprovalRequest, ConsoleAccessDto, CreateDeploymentNamespaceRequest, CursorList, DeploymentNamespaceDetailDto, DeploymentNamespaceListResponse, GitHubSourceConnectionListInput, GitHubSourceConnectionListResponse, GitHubSourceConnectionStatusDto, InstallationDto, ListResponse, PlanDeploymentNamespaceRequest, PlanDeploymentNamespaceResponse, PutAppEnvRequest, PutAppSecretRequest, PutAppVarRequest, RegisterAppRequest, RegisterAppResponse, RemoveDeploymentNamespaceResponse, RunDto, RunLogResponse, RunTailResponse, SetEnvironmentProtectionRequest, StartGitHubSourceConnectionRequest, StartGitHubSourceConnectionResponse, TriggerDeployRequest, UpdateAppRequest, UpdateDeploymentNamespaceRequest } from './index.js';
+import type { MailMessageDetailDto, MailMessageDto, MailMessageIdInput, MailMessageListInput, MailRuleDto, MailRuleIdInput, SetMailRuleInput } from './mail.js';
+type RpcProcedure<TInput, TOutput> = RpcProcedureContract<TInput, TOutput>;
+export interface AppIdInput {
+    readonly appId: string;
+}
+/** Whether a rotation was recorded: `false` while the environment holds no token key. */
+export interface RotateTokenKeyResponse {
+    readonly requested: boolean;
+}
+export interface AppEnvironmentInput extends AppIdInput {
+    readonly env: string;
+}
+export interface AppNamedValueInput extends AppIdInput {
+    readonly name: string;
+    readonly env?: string | null;
+}
+export interface CreateAppRequest extends UpdateAppRequest {
+    readonly id: string;
+    readonly repoUrl: string;
+}
+export interface PutAppEnvironmentInput extends AppEnvironmentInput {
+    readonly environment: PutAppEnvRequest;
+}
+export interface PutAppSecretInput extends AppIdInput {
+    readonly secret: PutAppSecretRequest;
+}
+export interface PutAppVarInput extends AppIdInput {
+    readonly variable: PutAppVarRequest;
+}
+export interface SecretValueInput extends AppNamedValueInput {
+    readonly value: string;
+}
+export interface SecretValueResponse {
+    readonly ok: boolean;
+    readonly valueRef?: string;
+}
+export interface OkResponse {
+    readonly ok: boolean;
+}
+export interface NamespaceIdInput {
+    readonly namespaceId: string;
+}
+export interface AdoptNamespaceInput extends NamespaceIdInput {
+    readonly namespace: AdoptDeploymentNamespaceRequest;
+}
+export interface UpdateNamespaceInput extends NamespaceIdInput {
+    readonly namespace: UpdateDeploymentNamespaceRequest;
+}
+export interface RunListInput {
+    readonly appId?: string;
+    readonly env?: string;
+    readonly before?: string;
+    readonly limit?: number;
+}
+export interface RunIdInput {
+    readonly runId: string;
+}
+export interface TailRunInput extends RunIdInput {
+    readonly after?: number;
+}
+export interface GitHubSourceConnectionInput {
+    readonly connectionId: string;
+}
+/** Provider-neutral admin seam. A statically composed provider implements these GitHub operations. */
+export interface GitHubSourceConnectionRpcContract {
+    list: RpcProcedure<GitHubSourceConnectionListInput, GitHubSourceConnectionListResponse>;
+    start: RpcProcedure<StartGitHubSourceConnectionRequest, StartGitHubSourceConnectionResponse>;
+    verifyInstallation: RpcProcedure<GitHubSourceConnectionInput, GitHubSourceConnectionStatusDto>;
+    repair: RpcProcedure<GitHubSourceConnectionInput, GitHubSourceConnectionStatusDto>;
+    reconcile: RpcProcedure<GitHubSourceConnectionInput, GitHubSourceConnectionStatusDto>;
+}
+/** Portable Delivery control API shared by browser and machine callers. */
+export interface ControlRpcContract {
+    installation: RpcProcedure<void, InstallationDto>;
+    consoleAccess: RpcProcedure<void, ConsoleAccessDto>;
+    builderPairing: {
+        inspect: RpcProcedure<BuilderPairingProofRequest, InspectDeviceAuthorizationResult>;
+        approve: RpcProcedure<BuilderPairingProofRequest, ApproveDeviceAuthorizationResult>;
+        deny: RpcProcedure<BuilderPairingProofRequest, DenyDeviceAuthorizationResult>;
+        listOwn: RpcProcedure<ListOwnBuilderPairingsRequest, ListOwnDeviceAuthorizationsResult>;
+        revoke: RpcProcedure<RevokeBuilderPairingRequest, RevokeKeyResult>;
+    };
+    builderConnections: {
+        createReceipt: RpcProcedure<CreateBuilderConnectionReceiptRequest, BuilderConnectionReceiptDto>;
+        getReceipt: RpcProcedure<GetBuilderConnectionReceiptRequest, BuilderConnectionReceiptDto>;
+    };
+    sourceConnection: GitHubSourceConnectionRpcContract;
+    apps: {
+        list: RpcProcedure<void, ListResponse<AppDto>>;
+        get: RpcProcedure<AppIdInput, AppDto>;
+        create: RpcProcedure<CreateAppRequest, AppDto>;
+        update: RpcProcedure<AppIdInput & {
+            app: UpdateAppRequest;
+        }, AppDto>;
+        delete: RpcProcedure<AppIdInput, OkResponse>;
+        environments: {
+            list: RpcProcedure<AppIdInput, ListResponse<AppEnvDto>>;
+            put: RpcProcedure<PutAppEnvironmentInput, AppEnvDto>;
+            delete: RpcProcedure<AppEnvironmentInput, OkResponse>;
+            /** Human user principals with `access.approve` only, from the console (ADR-0050 §4). */
+            protect: RpcProcedure<SetEnvironmentProtectionRequest, AppEnvDto>;
+            /** The environment's next deploy retires the key its signed tokens are signed with and signs with a new one. */
+            rotateTokenKey: RpcProcedure<AppEnvironmentInput, RotateTokenKeyResponse>;
+        };
+        secrets: {
+            list: RpcProcedure<AppIdInput, ListResponse<AppSecretDto>>;
+            put: RpcProcedure<PutAppSecretInput, AppSecretDto>;
+            /** Removes the value where it is stored (vault or provider), then the row; a failed value delete keeps the row. */
+            delete: RpcProcedure<AppNamedValueInput, OkResponse>;
+        };
+        variables: {
+            list: RpcProcedure<AppIdInput, ListResponse<AppVarDto>>;
+            put: RpcProcedure<PutAppVarInput, AppVarDto>;
+            delete: RpcProcedure<AppNamedValueInput, OkResponse>;
+        };
+    };
+    vault: {
+        set: RpcProcedure<SecretValueInput, SecretValueResponse>;
+        rotate: RpcProcedure<SecretValueInput, OkResponse>;
+        /** The same operation as `apps.secrets.delete`. */
+        delete: RpcProcedure<AppNamedValueInput, OkResponse>;
+    };
+    namespaces: {
+        list: RpcProcedure<void, DeploymentNamespaceListResponse>;
+        get: RpcProcedure<NamespaceIdInput, DeploymentNamespaceDetailDto>;
+        plan: RpcProcedure<PlanDeploymentNamespaceRequest, PlanDeploymentNamespaceResponse>;
+        create: RpcProcedure<CreateDeploymentNamespaceRequest, DeploymentNamespaceDetailDto>;
+        adopt: RpcProcedure<AdoptNamespaceInput, DeploymentNamespaceDetailDto>;
+        reconcile: RpcProcedure<NamespaceIdInput, DeploymentNamespaceDetailDto>;
+        /** Change a ready namespace in place, synchronously (backlog 79); also the retry after an unconfirmed update. */
+        update: RpcProcedure<UpdateNamespaceInput, DeploymentNamespaceDetailDto>;
+        /** Free a namespace id. Refused while any app environment is registered in it (backlog 73). */
+        remove: RpcProcedure<NamespaceIdInput, RemoveDeploymentNamespaceResponse>;
+    };
+    runs: {
+        list: RpcProcedure<RunListInput, CursorList<RunDto>>;
+        /** Per app environment, its newest finished run when that run failed: a later finished run supersedes a failure. */
+        latestFailures: RpcProcedure<void, ListResponse<RunDto>>;
+        get: RpcProcedure<RunIdInput, RunDto>;
+        log: RpcProcedure<RunIdInput, RunLogResponse>;
+        tail: RpcProcedure<TailRunInput, RunTailResponse>;
+        cancel: RpcProcedure<RunIdInput, RunDto>;
+    };
+    /** Runs whose access change waits for a human (ADR-0050 §5), behind `access.approve`. */
+    approvals: {
+        list: RpcProcedure<void, ListResponse<ApprovalDto>>;
+        get: RpcProcedure<RunIdInput, ApprovalDto>;
+        /** A human user principal, from the console's own origin; no key, service or OAuth token completes one. */
+        complete: RpcProcedure<CompleteApprovalRequest, ApprovalDto>;
+    };
+    deploy: RpcProcedure<TriggerDeployRequest, RunDto>;
+    register: RpcProcedure<RegisterAppRequest, RegisterAppResponse>;
+    /** What a consumer vendors (`fabrika connect add`): the export its owner's environment approved for it. */
+    connectors: {
+        describe: RpcProcedure<DescribeConnectorRequest, ExportDescription>;
+    };
+    /** The mail relay: `mail.read`, `mail.content.read` and `mail.manage`. */
+    mail: {
+        messages: {
+            list: RpcProcedure<MailMessageListInput, CursorList<MailMessageDto>>;
+            /** The content only with `mail.content.read`. */
+            get: RpcProcedure<MailMessageIdInput, MailMessageDetailDto>;
+            /** A held message only. */
+            release: RpcProcedure<MailMessageIdInput, MailMessageDto>;
+            /** A held message only. */
+            drop: RpcProcedure<MailMessageIdInput, MailMessageDto>;
+            /** A `failed` message, or an `unknown` one over an idempotent transport, whose content is kept. */
+            requeue: RpcProcedure<MailMessageIdInput, MailMessageDto>;
+        };
+        rules: {
+            list: RpcProcedure<void, ListResponse<MailRuleDto>>;
+            set: RpcProcedure<SetMailRuleInput, MailRuleDto>;
+            remove: RpcProcedure<MailRuleIdInput, OkResponse>;
+        };
+    };
+}
+/**
+ * One export version of `app` as the environment `env` approved it, read for its consumer `consumer`. Unknown, not
+ * approved, or not exported to that consumer: 404 alike.
+ */
+export interface DescribeConnectorRequest {
+    readonly consumer: string;
+    readonly env: string;
+    readonly app: string;
+    readonly export: string;
+    readonly version: number;
+}
+export {};

package/types/src/source-connection-list.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const GITHUB_SOURCE_CONNECTION_DEFAULT_PAGE_SIZE = 50;
+export declare const GITHUB_SOURCE_CONNECTION_MAX_PAGE_SIZE = 100;
+export declare const GITHUB_SOURCE_CONNECTION_PAGE_CURSOR_MAX_LENGTH = 512;
+export declare const githubSourceConnectionListInputSchema: z.ZodEffects<z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+}, {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+}>, {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+}, {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+}>;