@fabrika/app 0.9.0-dev.1 → 0.9.0-dev.2

package/types/src/implement/types.d.ts

@@ -0,0 +1,243 @@
+import type { z } from 'zod/v4';
+import type { ConnectSnapshot } from '../contract/connect';
+import type { SurfaceSection } from '../contract/declaration';
+import type { Export, InputOf, InputSchema, LinkMount, MemberAccess, Procedure, RoleOf, RpcMount, Schema, WebhookMount } from '../contract/define';
+import type { JobHandlersOf } from '../jobs/types';
+import type { AppCapability, Ref, Within } from './capability';
+import type { ConnectResult } from './connect';
+import type { LinkIssuing, MemberDirectory, MemberLookup, MemberManagement } from './membership';
+import type { AppPrincipal, LinkHolder, PrincipalOf, ServicePrincipal } from './principal';
+import type { AppUrl } from './urls';
+import type { WebhookDelivery, WebhookPrincipal } from './webhook';
+/** What every handler gets: who called, this request's id, the client the proxy saw, and the signal that ends it. */
+export interface RequestContext<P> {
+    readonly principal: P;
+    readonly requestId: string;
+    /**
+     * Aborts when the client leaves or the request outlives its time limit (`limits.timeoutMs`, `REQUEST_BUDGET_MS` by
+     * default); its transaction then rolls back. Pass it to every outbound call, so the call stops with the request.
+     */
+    readonly signal: AbortSignal;
+    /** The client the proxy saw. Information to record, never a check. */
+    readonly client: RequestClient;
+    /** An absolute link to a procedure of this application: `ctx.url('api.mail.unsubscribe', { query: { t } })`. */
+    readonly url: AppUrl;
+}
+/**
+ * The client of a request: its address as the proxy saw it, `null` where the platform cannot vouch for it (behind a
+ * balancer whose range it does not trust); its `User-Agent`, cut to `MAX_USER_AGENT_LENGTH`, `null` when it sends none.
+ */
+export interface RequestClient {
+    readonly ip: string | null;
+    readonly userAgent: string | null;
+}
+/** The capability an access form hands. `{ member: true }` hands none. */
+export type AccessContext<Acc> = Acc extends MemberAccess ? unknown : Acc extends {
+    readonly action: infer A extends string;
+    readonly over: infer D extends string;
+} ? {
+    readonly within: Within<D, A>;
+} : Acc extends {
+    readonly action: infer A extends string;
+    readonly in: infer D extends string;
+} ? {
+    readonly target: Ref<D, A>;
+} : Acc extends {
+    readonly action: infer A extends string;
+    readonly on: infer D extends string;
+} ? {
+    readonly target: Ref<D, A>;
+} : Acc extends {
+    readonly action: infer A extends string;
+    readonly creates: infer D extends string;
+} ? {
+    readonly created: Ref<D, A>;
+} : Acc extends {
+    readonly action: infer A extends string;
+    readonly app: true;
+} ? {
+    readonly app: AppCapability<A>;
+} : Acc extends {
+    readonly capabilities: infer C;
+} ? {
+    readonly capabilities: {
+        readonly [N in keyof C]: CapabilityOf<C[N]>;
+    };
+} : never;
+/** The capability one of several hands: a `Within` for `over`, a `Ref` for `on` and `in`. */
+export type CapabilityOf<F> = F extends {
+    readonly action: infer A extends string;
+    readonly over: infer D extends string;
+} ? Within<D, A> : F extends {
+    readonly action: infer A extends string;
+    readonly in: infer D extends string;
+} ? Ref<D, A> : F extends {
+    readonly action: infer A extends string;
+    readonly on: infer D extends string;
+} ? Ref<D, A> : never;
+type DimensionsOf<C> = C extends {
+    readonly dimensions: infer Dims;
+} ? Dims : never;
+/** The dimension and action of an access form that hands a `Ref` of an existing object. */
+type TargetOf<Acc> = Acc extends {
+    readonly action: infer A extends string;
+    readonly in: infer D extends string;
+} ? readonly [D, A] : Acc extends {
+    readonly action: infer A extends string;
+    readonly on: infer D extends string;
+} ? readonly [D, A] : never;
+/** The nearest dimension, `D` or one containing it, that declares members; `never` when none does. */
+type DirectoryOf<C, D extends string> = D extends keyof DimensionsOf<C> ? DimensionsOf<C>[D] extends {
+    readonly members: object;
+} ? D : DimensionsOf<C>[D] extends {
+    readonly in: infer P extends string;
+} ? DirectoryOf<C, P> : never : never;
+/**
+ * `ctx.members` (ADR-0012 §6): management where the action is the dimension's `members.manage`; otherwise the directory
+ * of the nearest dimension that declares members, which lists them only for its `members.list`.
+ */
+type MembersContext<C, Acc> = TargetOf<Acc> extends readonly [infer D extends string, infer A extends string] ? DimensionsOf<C>[D & keyof DimensionsOf<C>] extends {
+    readonly members: {
+        readonly manage: A;
+    };
+} ? {
+    readonly members: MemberManagement<D, A, RoleOf<C>>;
+} : [DirectoryOf<C, D>] extends [never] ? unknown : DimensionsOf<C>[DirectoryOf<C, D>] extends {
+    readonly members: {
+        readonly list: A;
+    };
+} ? {
+    readonly members: MemberDirectory;
+} : {
+    readonly members: MemberLookup;
+} : unknown;
+/** The link mounts whose dimension and issuing action are `D` and `A`. */
+type IssuingMounts<C, D extends string, A extends string> = {
+    [M in keyof SurfaceOf<C>]: SurfaceOf<C>[M] extends {
+        readonly kind: 'link';
+        readonly dimension: D;
+        readonly issuedBy: A;
+    } ? M : never;
+}[keyof SurfaceOf<C>] & string;
+/** `ctx.links`, only where the `Ref` carries a link mount's issuing action for its dimension. */
+type LinksContext<C, Acc> = TargetOf<Acc> extends readonly [infer D extends string, infer A extends string] ? [IssuingMounts<C, D, A>] extends [never] ? unknown : {
+    readonly links: LinkIssuing<D, A, IssuingMounts<C, D, A>>;
+} : unknown;
+/** What a procedure's context carries for its access form in this contract. */
+export type ContractContext<C, Acc> = AccessContext<Acc> & MembersContext<C, Acc> & LinksContext<C, Acc>;
+/** The input without the `from` field: the only copy of that id a handler has is the checked capability. */
+export type HandlerInput<I, Acc> = Acc extends {
+    readonly from: infer F extends string;
+} ? {
+    readonly [K in keyof InputOf<I> as K extends F ? never : K]: InputOf<I>[K];
+} : InputOf<I>;
+export type Handler<In, Ctx, O extends Schema> = (args: {
+    readonly input: In;
+    readonly ctx: Ctx;
+}) => z.input<O> | Promise<z.input<O>>;
+type ImportsOf<C> = SurfaceOf<C> extends {
+    readonly imports: infer I;
+} ? I : Record<never, never>;
+/** What `implement({ connect })` takes: the vendored snapshot of each import, by the import's name. */
+export type ConnectSnapshots<C> = {
+    readonly [K in keyof ImportsOf<C>]: ConnectSnapshot;
+};
+type ImportsUsedBy<C, Id extends string> = {
+    [K in keyof ImportsOf<C>]: ImportsOf<C>[K] extends {
+        readonly usedBy: readonly (infer U)[];
+    } ? Id extends U ? K : never : never;
+}[keyof ImportsOf<C>];
+type ImportedProcedures<C, K> = K extends keyof ImportsOf<C> ? ImportsOf<C>[K] extends {
+    readonly procedures: readonly (infer P extends string)[];
+} ? P : never : never;
+/** A connector call never throws for the owner's answer: it resolves to a typed outcome. */
+export type ConnectCall<I, O extends Schema> = [I] extends [InputSchema] ? (input: z.input<I>) => Promise<ConnectResult<z.output<O>>> : (input?: Record<never, never>) => Promise<ConnectResult<z.output<O>>>;
+type ConnectorOf<S, P extends string> = {
+    readonly [Path in P]: S extends {
+        readonly procedures: {
+            readonly [Q in Path]: {
+                readonly input: infer I;
+                readonly output: infer O extends Schema;
+            };
+        };
+    } ? ConnectCall<I, O> : never;
+};
+/** `ctx.connect` with the imports whose `usedBy` names endpoint `Id`; nothing for any other endpoint. */
+export type ConnectContext<C, Snap, Id extends string> = [ImportsUsedBy<C, Id>] extends [never] ? unknown : {
+    readonly connect: {
+        readonly [K in ImportsUsedBy<C, Id> & keyof Snap]: ConnectorOf<Snap[K], ImportedProcedures<C, K>>;
+    };
+};
+type RpcHandlers<C, P, T, Snap, Prefix extends string> = {
+    readonly [K in keyof T]: T[K] extends Procedure<'query' | 'mutation', infer I, infer O, infer Acc> ? Handler<HandlerInput<I, Acc>, RequestContext<P> & ContractContext<C, Acc> & ConnectContext<C, Snap, `${Prefix}${K & string}`>, O> : RpcHandlers<C, P, T[K], Snap, `${Prefix}${K & string}.`>;
+};
+/** An export handler runs read-only: its context carries its capability and nothing that writes. */
+type ExportHandlers<T> = {
+    readonly [K in keyof T]: T[K] extends Procedure<'query', infer I, infer O, infer Acc> ? Handler<HandlerInput<I, Acc>, RequestContext<ServicePrincipal | AppPrincipal> & AccessContext<Acc>, O> : ExportHandlers<T[K]>;
+};
+type ExportsOf<C> = SurfaceOf<C> extends {
+    readonly exports: infer E;
+} ? E : Record<never, never>;
+type ExportHandlersOf<C> = [keyof ExportsOf<C>] extends [never] ? unknown : {
+    readonly exports: {
+        readonly [E in keyof ExportsOf<C>]: ExportsOf<C>[E] extends Export<infer T> ? ExportHandlers<T> : never;
+    };
+};
+/** A link procedure acts on the object its key is bound to. */
+type LinkHandlers<D extends string, T> = {
+    readonly [K in keyof T]: T[K] extends Procedure<'query' | 'mutation', infer I, infer O, {
+        readonly action: infer A extends string;
+    }> ? Handler<InputOf<I>, RequestContext<LinkHolder> & {
+        readonly target: Ref<D, A>;
+    }, O> : LinkHandlers<D, T[K]>;
+};
+/**
+ * A delivery's handler: the declared input, a `Ref` of the bound value for each declared action, and the delivery's
+ * stable key. It runs at least once per delivery: a failed run is run again on GitHub's redelivery.
+ */
+export type WebhookHandler<B extends string, Acts extends string, I> = (args: {
+    readonly input: z.output<I>;
+    readonly ctx: RequestContext<WebhookPrincipal> & {
+        readonly refs: {
+            readonly [A in Acts]: Ref<B, A>;
+        };
+        readonly delivery: WebhookDelivery;
+    };
+}) => void | Promise<void>;
+type MountHandlers<C, M, Name extends string, Snap> = M extends RpcMount<infer Callers, infer T> ? RpcHandlers<C, PrincipalOf<Callers[number]>, T, Snap, `${Name}.`> : M extends LinkMount<infer D, string, string, infer T> ? LinkHandlers<D, T> : M extends WebhookMount<infer B, infer Acts, infer I> ? WebhookHandler<B, Acts, I> : never;
+type ServedMount<M> = M extends {
+    readonly kind: 'rpc' | 'link' | 'webhook';
+} ? true : false;
+type SurfaceOf<C> = C extends {
+    readonly surface: infer S;
+} ? S : never;
+/**
+ * One handler tree per procedure mount and one handler per webhook, keyed like the contract, one per job under `jobs`,
+ * and the export handlers under `exports`.
+ */
+export type HandlersOf<C, Snap = unknown> = {
+    readonly [M in keyof SurfaceOf<C> as M extends SurfaceSection ? never : ServedMount<SurfaceOf<C>[M]> extends true ? M : never]: MountHandlers<C, SurfaceOf<C>[M], M & string, Snap>;
+} & JobHandlersOf<C> & ExportHandlersOf<C>;
+/** An `any` comes from an error elsewhere in the handler; reporting it here too would only add noise. */
+export type IsAny<T> = 0 extends 1 & T ? true : false;
+/** Fields of `R` that the output `O` does not declare. When `O` is a union, a value that fits one branch has none. */
+export type ExtraKeys<R, O> = IsAny<R> extends true ? never : true extends (O extends unknown ? ([ExtraKeysOf<R, O>] extends [never] ? true : false) : never) ? never : ExtraKeysOf<R, O>;
+type ExtraKeysOf<R, O> = R extends readonly (infer RE)[] ? (O extends readonly (infer OE)[] ? ExtraKeys<RE, OE> : never) : R extends object ? O extends object ? Exclude<keyof R, keyof O> | {
+    [Q in keyof R & keyof O]: ExtraKeys<R[Q], O[Q]>;
+}[keyof R & keyof O] : never : never;
+type Returned<F> = F extends (args: never) => infer R ? Awaited<R> : never;
+type Undeclared<F, Expected> = ExtraKeys<Returned<F>, Returned<Expected>>;
+/** No undeclared field, or a field whose type is an error reported where it arose. */
+type NoneOrError<U> = [U] extends [never] ? true : IsAny<U>;
+type ExactTree<H, E, Path extends string> = {
+    readonly [K in keyof H]: K extends keyof E ? E[K] extends (args: never) => unknown ? NoneOrError<Undeclared<H[K], E[K]>> extends true ? H[K] : {
+        readonly [_ in `handler '${Path}${K & string}' returns fields the contract output does not declare. Return only declared fields`]: Undeclared<H[K], E[K]>;
+    } : ExactTree<H[K], E[K], `${Path}${K & string}.`> : `'${Path}${K & string}' is not in the contract. Declare the endpoint in fabrika.contract.ts first.`;
+};
+type KindOf<M> = M extends {
+    readonly kind: infer K extends string;
+} ? K : 'section';
+export type ExactHandlers<H, C> = {
+    readonly [M in keyof H]: M extends keyof HandlersOf<C> ? HandlersOf<C>[M] extends (args: never) => unknown ? H[M] : ExactTree<H[M], HandlersOf<C>[M], `${M & string}.`> : M extends keyof SurfaceOf<C> ? `'${M & string}' is a ${KindOf<SurfaceOf<C>[M]>} mount; it takes no handler. Remove it from handlers.` : `'${M & string}' is not in the contract. Declare the mount in fabrika.contract.ts first.`;
+};
+export {};

package/types/src/implement/urls.d.ts

@@ -0,0 +1,15 @@
+import { type ContractArtifact } from '@fabrika/auth-core';
+/** A value a URL parameter carries; an absent one is left out. */
+export type UrlValue = string | number | boolean | null | undefined;
+export interface UrlParameters {
+    /** A `GET` procedure's input, each field a parameter. */
+    readonly input?: Readonly<Record<string, UrlValue>>;
+    /** A `POST` procedure's `http.query`. */
+    readonly query?: Readonly<Record<string, UrlValue>>;
+}
+/** `ctx.url`: the absolute URL of a procedure of this contract, with the parameters its HTTP shape reads from the URL. */
+export type AppUrl = (endpoint: string, parameters?: UrlParameters) => string;
+/** The environment's canonical origin, or `null` where the deploy wrote none; a malformed one is a boot problem. */
+export declare function readAppOrigin(framework: Readonly<Record<string, string>>, problems: string[]): string | null;
+/** `ctx.url` over the approved artifact's procedure rows. */
+export declare function appUrl(artifact: ContractArtifact, origin: string | null): AppUrl;

package/types/src/implement/verifiers.d.ts

@@ -0,0 +1,19 @@
+import { type WebhookScheme } from '@fabrika/auth-core';
+/** How far a signed timestamp may be from now: the window in which a captured delivery could be replayed. */
+export declare const WEBHOOK_TIMESTAMP_TOLERANCE_MS: number;
+/** What a verifier reads of a delivery. */
+export interface SignedDelivery {
+    readonly headers: Headers;
+    readonly body: Uint8Array<ArrayBuffer>;
+    /**
+     * The URL the provider posted to: `FABRIKA_APP_ORIGIN` and the request's path and query, which Twilio signs. `null`
+     * where the environment has no public origin.
+     */
+    readonly url: string | null;
+}
+/** Whether the delivery proves it holds `secret` under `scheme`. `now` is the clock a signed timestamp is checked against. */
+export declare function verifyDelivery(scheme: WebhookScheme, delivery: SignedDelivery, secret: string, now: number): Promise<boolean>;
+/** A Standard Webhooks secret is `whsec_` and the key in base64; `null` when it is not. */
+export declare function standardKey(secret: string): Uint8Array<ArrayBuffer> | null;
+/** The GitHub account a payload names, as a binding records it: `installation:<id>` or `repository:<id>`. */
+export declare function githubAccounts(payload: unknown): readonly string[];

package/types/src/implement/webhook.d.ts

@@ -0,0 +1,55 @@
+import { type ScopeBinding, type WebhookScheme } from '@fabrika/auth-core';
+import { type CapabilityAuthority } from '@fabrika/db/capability';
+import type { Session, WebhookTables } from '@fabrika/db/framework';
+import type { WebhookBindings } from '../contract/webhook-binding';
+/** The workload a delivery runs as: no person, only the binding. It creates no scope and manages no member. */
+export interface WebhookPrincipal {
+    readonly kind: 'webhook';
+    readonly bindingId: string;
+}
+/** The principal id a delivery's capabilities are granted to. */
+export declare function webhookSubject(bindingId: string): string;
+/**
+ * A delivery key is kept this long per binding. GitHub signs no timestamp, so a body replayed after the window
+ * runs again; GitHub itself redelivers for three days.
+ */
+export declare const WEBHOOK_REPLAY_RETENTION_MS: number;
+/**
+ * How long a delivery's claim outlasts its handler's time limit: a copy that arrives later finds the claim held and is
+ * answered as received; once the lease passed without a completion (a crash, a lost connection), the redelivery runs.
+ */
+export declare const WEBHOOK_CLAIM_GRACE_MS = 30000;
+/**
+ * `sha256:<hex>` of the binding id and the signed body: what replay protection and an idempotent handler key on.
+ * A redelivery of one event has the same key, whatever its `X-GitHub-Delivery` says.
+ */
+export declare function deliveryKey(bindingId: string, body: Uint8Array<ArrayBuffer>): Promise<string>;
+/** What a handler knows of its delivery. Handlers run at least once: write idempotently, keyed on `key`. */
+export interface WebhookDelivery {
+    readonly key: string;
+}
+/** The scope a binding of a webhook bound to `'app'` records: the application, which has no value. */
+export declare const APP_BINDING_SCOPE: Readonly<{
+    type: "app";
+    value: "";
+}>;
+/** What a procedure that binds needs of its webhook: where deliveries arrive, how they are signed, what they reach. */
+export interface BindableWebhook {
+    readonly name: string;
+    readonly path: string;
+    readonly scheme: WebhookScheme;
+    readonly boundTo: ScopeBinding;
+}
+/** Where `ctx.webhooks` runs: the procedure's transaction, bound to its request like every handle. */
+export interface BindingSite {
+    readonly site: string;
+    readonly webhook: BindableWebhook;
+    readonly tables: () => WebhookTables;
+    readonly authority: CapabilityAuthority;
+    readonly session: () => Promise<Session>;
+    readonly check: () => void;
+    /** Who binds: the caller's subject, recorded with the binding. */
+    readonly principal: string;
+}
+/** `ctx.webhooks` of a procedure that declares `binds`: only its declared webhook, only on the value its capability names. */
+export declare function webhookBindings(site: BindingSite): (name: string) => WebhookBindings;

package/types/src/implement/workload.d.ts

@@ -0,0 +1,56 @@
+import { type ContractArtifact, type MintFromKeyResult, type OwnWorkloadKind, type PermissionEntry } from '@fabrika/auth-core';
+import type { TokenVerifier } from '@fabrika/jwks';
+export type WorkloadKindOf = OwnWorkloadKind;
+/** Where a workload exchanges its key for a token: IAM's public `WORKLOAD_TOKEN_PATH`, or a stand-in in a test. */
+export interface WorkloadTokenSource {
+    exchange(input: {
+        readonly app: string;
+        readonly key: string;
+    }): Promise<MintFromKeyResult>;
+}
+/** IAM's token exchange at its public origin. An answer that is not IAM's decided outcome throws: "IAM could not be asked". */
+export declare function issuerWorkloadTokens(issuer: string, fetcher?: (request: Request) => Promise<Response>): WorkloadTokenSource;
+/** What the workload may do now, or why it may do nothing. */
+export type WorkloadAuthority = 
+/** `token` is the bearer IAM signed: what a job that issues links presents to IAM. */
+{
+    readonly ok: true;
+    readonly perms: readonly PermissionEntry[];
+    readonly token: string;
+}
+/** IAM refused the key, or signed a token that is not this workload's: a decided negative. */
+ | {
+    readonly ok: false;
+    readonly reason: 'refused';
+}
+/** IAM or its keys could not be reached. */
+ | {
+    readonly ok: false;
+    readonly reason: 'unavailable';
+};
+export interface WorkloadCredentialOptions {
+    readonly kind: WorkloadKindOf;
+    readonly name: string;
+    readonly key: string;
+    /** This application's IAM id, `<app>@<env>`: the token's audience. */
+    readonly audience: string;
+    readonly source: WorkloadTokenSource;
+    readonly verifier: TokenVerifier;
+}
+/** One workload's key, exchanged for a token when none is cached or the cached one is about to expire. */
+export declare class WorkloadCredential {
+    #private;
+    constructor(options: WorkloadCredentialOptions);
+    authority(): Promise<WorkloadAuthority>;
+}
+/** The key a workload's credential is found under: `job:<name>`, `webhook:<name>`, `public:<endpoint id>`. */
+export declare function workloadSite(kind: WorkloadKindOf, name: string): string;
+export interface WorkloadCredentialsInput {
+    readonly artifact: ContractArtifact;
+    readonly framework: Readonly<Record<string, string>>;
+    readonly audience: string;
+    readonly source: WorkloadTokenSource | undefined;
+    readonly verifier: TokenVerifier;
+}
+/** `workloadSite(kind, name)` → the workload's credential, or why one cannot start to `problems`. */
+export declare function workloadCredentials(input: WorkloadCredentialsInput, problems: string[]): ReadonlyMap<string, WorkloadCredential>;

package/types/src/implement/xlsx.d.ts

@@ -0,0 +1,6 @@
+import type { AttachmentShape } from '@fabrika/auth-core';
+/**
+ * The XLSX of `rows`, each read through `rowOf` only when its turn comes, after the row count was checked. Each cell
+ * is counted against `maxBytes`, with every other part and header of the file, before the next one is read.
+ */
+export declare function encodeXlsx(endpoint: string, shape: AttachmentShape, rows: unknown, rowOf: (row: unknown) => unknown): Uint8Array<ArrayBuffer>;

package/types/src/index.d.ts

@@ -0,0 +1,12 @@
+export { initRpc } from './rpc/builder.js';
+export type { InferRpcClient, InferRpcContractClient, RpcProcedureContract, RpcRouterFor } from './rpc/contract.js';
+export type { InferRouter, InferRouterClient } from './rpc/types.js';
+export type { StandardSchemaV1 } from './standard-schema.js';
+export type { FetchService, RequestExecutionContext } from './fetch.js';
+export { BadRequestError, ConflictError, defaultOnError, ForbiddenError, HttpError, isStructuralError, NotFoundError, type StructuralError, toErrorResponse, UnauthorizedError, } from './errors.js';
+export { fromPage, fromRow, type RowInput } from './from-row.js';
+export { honeypot } from './honeypot.js';
+export type { AuthContext, Scope } from '@fabrika/auth';
+export { createRpcClient } from './client/rpc.js';
+export type { RpcClientOptions } from './client/rpc.js';
+export { RpcError, type RpcFetch } from './client/transport.js';

package/types/src/jobs/exception.d.ts

@@ -0,0 +1,40 @@
+import type { Scrubber } from './scrub';
+/** A message is cut to this many characters. */
+export declare const MAX_MESSAGE_LENGTH = 2048;
+/** A file or function name is cut to this many characters. */
+export declare const MAX_FRAME_FIELD_LENGTH = 512;
+/** The frames nearest the throw are kept. */
+export declare const MAX_FRAMES = 50;
+/** The thrown value and at most this many minus one causes. */
+export declare const MAX_CAUSE_DEPTH = 5;
+/** The encoded exception values stay within this; Operations refuses an ingest message above 120 KiB. */
+export declare const MAX_EXCEPTION_BYTES: number;
+/** One stack frame in Sentry's shape. */
+export interface ReportedFrame {
+    readonly filename: string;
+    readonly function?: string;
+    readonly lineno?: number;
+    readonly colno?: number;
+    /** `false` for a dependency's or the runtime's own frame. */
+    readonly in_app: boolean;
+}
+/** One exception value in Sentry's shape. */
+export interface ReportedException {
+    readonly type: string;
+    readonly value: string;
+    readonly stacktrace?: {
+        readonly frames: readonly ReportedFrame[];
+    };
+}
+/**
+ * The frames of a V8 (Cloudflare Workers) or JavaScriptCore (Bun) `stack`, oldest call first as Sentry orders them,
+ * the `MAX_FRAMES` nearest the throw kept. The message lines before the first frame are not read.
+ */
+export declare function parseStack(stack: string, scrubber: Scrubber): ReportedFrame[];
+/**
+ * `error` and its causes, at most `MAX_CAUSE_DEPTH`, the deepest cause first and `error` last, as Sentry orders a
+ * chain. Every text is scrubbed and cut; the chain is then fitted within `MAX_EXCEPTION_BYTES`.
+ */
+export declare function exceptionChain(error: unknown, scrubber: Scrubber): ReportedException[];
+/** Drops the deepest causes, then halves the frames of what is left, until `values` encodes within `maxBytes`. */
+export declare function fitWithin(values: readonly ReportedException[], maxBytes: number): ReportedException[];

package/types/src/jobs/mail.d.ts

@@ -0,0 +1,67 @@
+import { type ContractArtifact } from '@fabrika/auth-core';
+import { type EmailProviderRegistry, type EmailSender } from '@fabrika/email';
+import type { OpenedFile } from '../files/handle';
+import type { ApplicationEnvironment } from '../implement/implement';
+import type { AppMail } from './types';
+export declare const MAX_APP_MAIL_KEY_LENGTH = 200;
+/** Whose keys a prefix separates: the installation, by IAM's public origin, and the application environment in it. */
+export interface MailKeyScope {
+    /** `FABRIKA_IAM_ISSUER` as an origin: it tells installations, and the local stack, apart. */
+    readonly issuer: string;
+    /** `FABRIKA_IAM_APP_ID`, `<app>@<env>`. */
+    readonly appId: string;
+}
+/**
+ * `fabrika:<the first 32 hex of sha256('<issuer>\n<app>@<env>')>:` — 41 characters, whatever the names hold. Renaming
+ * IAM's domain changes every key once, so a message in flight across the rename may be sent again.
+ */
+export declare function mailKeyPrefix(scope: MailKeyScope): string;
+/** The key the transport receives for the application's `key`. */
+export declare function transportMailKey(scope: MailKeyScope, key: string): string;
+/** A mailer job's transport: one that sends, or the stated absence of one, whose every send fails `mail_not_configured`. */
+export interface JobMailTransport {
+    readonly sender: EmailSender;
+    readonly available: boolean;
+}
+/** The transports of a contract's mailer jobs, resolved once by `boot`; `null` where no job declares that mailer. */
+export interface MailTransports {
+    readonly installation: JobMailTransport | null;
+    readonly own: JobMailTransport | null;
+    readonly keyPrefix: string;
+}
+/** The test kit's transport for every mailer job: a stand-in sender, or `'none'` for an installation without mail. */
+export type MailStandIn = EmailSender | 'none';
+/** The application's own transport, built once at boot from its own variables; `null` when they configure none. */
+export type OwnMailTransport = (env: ApplicationEnvironment) => EmailSender | null;
+export interface JobMailInput {
+    readonly transport: JobMailTransport;
+    readonly keyPrefix: string;
+    /** The attempt's `ctx.signal`: it aborts every send of the attempt. */
+    readonly signal: AbortSignal;
+    /** Throws once the attempt has ended. */
+    readonly assertLive: () => void;
+    /** `ctx.files.open` of the attempt: the bytes of a live file whose reference it holds, at most `maxBytes`. */
+    readonly open: (file: unknown, options: {
+        readonly maxBytes: number;
+    }) => Promise<OpenedFile>;
+}
+export declare function jobMail(input: JobMailInput): AppMail;
+export interface MailTransportInput {
+    readonly artifact: ContractArtifact;
+    /** The framework's variables, whose `FABRIKA_EMAIL_*` configure the installation's transport. */
+    readonly framework: Readonly<Record<string, string>>;
+    readonly application: ApplicationEnvironment;
+    /** `serve(contract, { mail })`. */
+    readonly own: OwnMailTransport | undefined;
+    /** The test kit's transport for every mailer job; the variables and `own` are then not read. */
+    readonly standIn: MailStandIn | undefined;
+    readonly registry: EmailProviderRegistry;
+    /** Whose keys the prefix separates. */
+    readonly keyScope: MailKeyScope;
+    /** A local composition: a missing transport is no mail, as `FABRIKA_EMAIL_PROVIDER=none` is, instead of a refused boot. */
+    readonly local: boolean;
+}
+/** The transports of the contract's mailer jobs, or why one of them cannot send, added to `problems`. */
+export declare function resolveMailTransports(input: MailTransportInput, problems: string[]): MailTransports;
+/** Where the installation has no transport: every send fails `not_sent`, and the boot does not. */
+export declare const NO_MAIL: JobMailTransport;

package/types/src/jobs/report.d.ts

@@ -0,0 +1,56 @@
+import type { Scrubber } from './scrub';
+export interface OperationsReport {
+    /** Grouping in Operations: one issue per kind of problem and job or endpoint. */
+    readonly fingerprint: readonly string[];
+    /** The exception type Operations shows, e.g. `JobFailed`. */
+    readonly type: string;
+    /** Framework-authored text only: fixed codes and declared names. What was thrown travels as `error`. */
+    readonly message: string;
+    readonly tags: Readonly<Record<string, string>>;
+    /** What was thrown, when something was: sent scrubbed as the cause chain of the framework's exception. */
+    readonly error?: unknown;
+}
+export interface OperationsReporter {
+    /** Never throws: a report that cannot be delivered is one log line. */
+    report(report: OperationsReport): Promise<void>;
+}
+export interface OperationsTarget {
+    readonly envelopeUrl: string;
+    readonly publicKey: string;
+}
+/** The envelope endpoint and key of a DSN `https://<key>@<host>/<project>`, or `null` when it is not one. */
+export declare function operationsTarget(dsn: string): OperationsTarget | null;
+/** The envelope's `logger`: which part of the framework reported. */
+export type ReportSource = 'fabrika.jobs' | 'fabrika.requests' | 'fabrika.process';
+export interface OperationsReporterOptions {
+    readonly target: OperationsTarget;
+    readonly release: string | null;
+    readonly environment: string | null;
+    readonly source: ReportSource;
+    /** What every text of a thrown value passes before it leaves the process. */
+    readonly scrubber: Scrubber;
+    readonly fetch?: (request: Request) => Promise<Response>;
+}
+/** Where the reports of one application environment go: the ingest of its DSN, its release and its environment. */
+export type OperationsSettings = Omit<OperationsReporterOptions, 'source' | 'scrubber' | 'fetch'>;
+/**
+ * The settings of `FABRIKA_OPERATIONS_DSN`, `FABRIKA_RELEASE` and `FABRIKA_ENVIRONMENT`; `null` without a DSN. A DSN
+ * that is not an ingest DSN adds a problem, because every report would reach no one.
+ */
+export declare function operationsSettings(variables: Readonly<Record<string, string>>, problems: string[]): OperationsSettings | null;
+type EnvelopeOptions = Pick<OperationsReporterOptions, 'release' | 'environment' | 'source' | 'scrubber'>;
+/** A framework report: its own exception last, so the issue keeps the framework's title, after what was thrown. */
+export declare function reportEnvelope(report: OperationsReport, options: EnvelopeOptions, now: Date): string;
+/** How a process failed outside any request or job run. */
+export type CrashKind = 'uncaught_exception' | 'unhandled_rejection' | 'boot_failed';
+/** A crash: what was thrown is the issue itself, grouped by Operations from its type and in-app frames. */
+export declare function crashEnvelope(kind: CrashKind, error: unknown, options: EnvelopeOptions, now: Date): string;
+export declare function operationsReporter(options: OperationsReporterOptions): OperationsReporter;
+export interface CrashReporter {
+    /** Never throws: a report that cannot be delivered is one log line. */
+    report(kind: CrashKind, error: unknown): Promise<void>;
+}
+export declare function crashReporter(options: Omit<OperationsReporterOptions, 'source'>): CrashReporter;
+/** Reports go to the server log only: the application has no Operations DSN. */
+export declare const logReporter: OperationsReporter;
+export {};