@fabrika/app 0.8.2 → 0.9.0-cloudflare.1

package/types/src/bun.d.ts

@@ -0,0 +1,66 @@
+import type { FileObjectStore } from '@fabrika/platform';
+import type { FetchService, RequestExecutionContext } from './fetch.js';
+import { type IamKeySource } from './implement/boot.js';
+import { type CrashEvents } from './implement/crashes.js';
+import { type ContractImplementation } from './implement/implement.js';
+import { type JobRunOptions, type JobRunResult } from './jobs/runner.js';
+export { diskAssets } from './disk-assets.js';
+export { clamscanArguments, type ClamscanOptions, clamscanScanner } from './files/clamscan.js';
+export { markProductionProcess } from '@fabrika/db/production';
+export interface ManagedBunHandlerOptions {
+    /** Required sink for rejected background tasks. Do not log raw errors or secret-bearing values. */
+    onBackgroundError(error: unknown): void;
+    executionContext?: never;
+}
+export interface ExternalBunHandlerOptions {
+    /** Existing supervised process context. Its owner remains responsible for draining it. */
+    executionContext: RequestExecutionContext;
+    onBackgroundError?: never;
+}
+export type BunHandlerOptions = ManagedBunHandlerOptions | ExternalBunHandlerOptions;
+export interface BunHandler {
+    fetch(request: Request): Promise<Response>;
+    /** Wait until every task registered through `waitUntil()` has settled. */
+    drain(): Promise<void>;
+}
+export declare function createBunHandler<Env>(app: FetchService<Env>, env: Env, options: BunHandlerOptions): BunHandler;
+/** IAM's public key set at the issuer's `/.well-known/jwks.json`, for a process with no IAM binding. */
+export declare function issuerJwks(issuer: unknown): IamKeySource;
+export interface ContractServer {
+    /** The port the server listens on; `PORT=0` picks a free one. */
+    readonly port: number;
+    /** Stops accepting requests and waits for the ones in flight. */
+    stop(): Promise<void>;
+}
+/**
+ * The stored files' object storage (Zerops object storage, path-style), when the platform wrote its variables;
+ * a partial set stops the boot. The credentials are never quoted in a message.
+ */
+export declare function openFileStorage(framework: Readonly<Record<string, string>>): FileObjectStore | undefined;
+/** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
+export type ImplementationLoader = () => Promise<{
+    readonly default: ContractImplementation;
+}>;
+export interface ContractServerOptions {
+    /** Where the process hears of an uncaught exception or an unhandled rejection; `process` by default. */
+    readonly crashes?: CrashEvents;
+    /** What posts a report to Operations' ingest; `fetch` by default. */
+    readonly operationsFetch?: (request: Request) => Promise<Response>;
+}
+/**
+ * Captures the framework's variables and scrubs them from the process, then imports the application, boots it and
+ * serves it on `PORT` (default 3000), on every interface: the project's private network is how the proxy reaches
+ * it. Called only by the generated entrypoint, with `process.env`. SIGTERM drains. Given the provisioning credential,
+ * it is the launcher instead: it never loads the application and re-runs the entrypoint as the runtime role.
+ * With an Operations DSN, a startup that throws is reported before it is rethrown, and so is a crash once it serves.
+ */
+export declare function serveContract(load: ImplementationLoader, env: Readonly<Record<string, string | undefined>>, options?: ContractServerOptions): Promise<ContractServer>;
+/** The application module at `path`, imported when the loader runs; its default export must be what `serve` returned. */
+export declare function implementationAt(path: string): ImplementationLoader;
+/**
+ * One run of the job `name` (`fabrika job run <name>`, the crontab's command): the framework's variables are captured
+ * and scrubbed before the application loads, exactly as `serveContract` does, then `boot` binds the job and the run
+ * takes its lease. The connection closes when the run ends. Given the provisioning credential, it re-runs the command
+ * as the runtime role, as `serveContract` does.
+ */
+export declare function runContractJob(load: ImplementationLoader, env: Readonly<Record<string, string | undefined>>, name: string, options?: JobRunOptions): Promise<JobRunResult>;

package/types/src/client/caller.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod/v4';
+declare const PageCallerSchema: z.ZodObject<{
+    label: z.ZodString;
+    email: z.ZodString;
+    actions: z.ZodObject<{
+        /** The actions held as a global grant, so in every value. */
+        app: z.ZodArray<z.ZodString>;
+        /** Each scope value the person holds something in, with those actions; sorted by dimension, then value. */
+        scopes: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            value: z.ZodString;
+            actions: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PageCaller = z.infer<typeof PageCallerSchema>;
+/** The caller document as the framework answers it; throws on any other value. */
+export declare function parsePageCaller(value: unknown): PageCaller;
+export {};

package/types/src/client/contract.d.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod/v4';
+import { type AttachmentBrand } from '../contract/attachment';
+import { type ProcedureType } from '../contract/declaration';
+import type { AnyContract, InputSchema, Procedure, Schema } from '../contract/define';
+import { type ClientInput, type FileBrand } from '../contract/file';
+import { type BounceOption, type RpcFetch } from './transport';
+type SurfaceOf<C> = C extends {
+    readonly surface: infer S;
+} ? S : never;
+/** The mounts a client calls: RPC mounts and link mounts. */
+export type ClientMount<C> = {
+    [M in keyof SurfaceOf<C>]: SurfaceOf<C>[M] extends {
+        readonly kind: 'rpc' | 'link';
+    } ? M : never;
+}[keyof SurfaceOf<C>] & string;
+/**
+ * One procedure: its input as the caller writes it (defaults optional), its output as parsed, and the output schema
+ * it parses with (`@fabrika/app/react` reads a cached answer back through it).
+ */
+export type ProcedureCall<I, O extends Schema> = ([I] extends [InputSchema] ? (input: ClientInput<z.input<I>>) => Promise<z.output<O>> : (input?: Record<never, never>) => Promise<z.output<O>>) & {
+    readonly output: O;
+};
+export type ClientTree<T> = {
+    readonly [K in keyof T]: T[K] extends Procedure<'query' | 'mutation', infer I, infer O, unknown> ? O extends AttachmentBrand ? AttachmentProcedure<I> : O extends FileBrand<string> ? FileProcedure<I> : ProcedureCall<I, O> : ClientTree<T[K]>;
+};
+type MountOf<C, M> = SurfaceOf<C>[M & keyof SurfaceOf<C>];
+/** One function per procedure, and an `AttachmentProcedure` or `FileProcedure` per procedure that answers a file. */
+export type ContractClient<C, M> = MountOf<C, M> extends {
+    readonly procedures: infer T;
+} ? ClientTree<T> : never;
+/** The answer of a client procedure: `ResultOf<typeof api.tasks.get>`; a procedure that answers a file, a `DownloadedFile`. */
+export type ResultOf<F> = F extends (...args: never[]) => Promise<infer R> ? R : F extends AttachmentProcedure<unknown> | FileProcedure<unknown> ? DownloadedFile : never;
+/** The input of a client procedure as the caller writes it: `InputOf<typeof api.tasks.create>`. */
+export type InputOf<F> = F extends (...args: infer A) => Promise<unknown> ? A[0] : F extends AttachmentProcedure<infer I> | FileProcedure<infer I> ? DownloadInput<I>[0] : never;
+export interface ClientOptions {
+    /** The application's origin; procedure paths are joined to it. Defaults to the page's own origin. */
+    readonly baseUrl?: string;
+    /** Override `fetch` (tests, a script). Defaults to the global `fetch`. */
+    readonly fetch?: RpcFetch;
+    /**
+     * A `px_` key, sent as `Authorization: Bearer`. A request with a key carries no cookie. In a browser the key goes
+     * only to the page's own origin.
+     */
+    readonly key?: string;
+    /** On a 401 that carries a login URL, send the browser to sign in instead of throwing. */
+    readonly bounceOnAuth?: BounceOption;
+}
+/** A link mount's caller is the holder of its share key, which every request presents. */
+export interface LinkClientOptions extends ClientOptions {
+    readonly key: string;
+}
+type OptionsFor<C, M> = SurfaceOf<C>[M & keyof SurfaceOf<C>] extends {
+    readonly kind: 'link';
+} ? [options: LinkClientOptions] : [options?: ClientOptions];
+/**
+ * What a value of a client tree is, kept beside it so the value stays a plain function or record: a procedure's
+ * `<mount>.<path>`, its type and input schema, or a group's prefix. `@fabrika/app/react` keys its cache by it.
+ */
+export interface ClientNode {
+    readonly mount: string;
+    /** The dotted path below the mount; `''` for the client itself. */
+    readonly path: string;
+    readonly procedure: {
+        readonly type: ProcedureType;
+        readonly input: Schema | null;
+    } | null;
+}
+/** The node a value of a client tree is, or `null` for any other value. */
+export declare function clientNodeOf(value: unknown): ClientNode | null;
+/**
+ * The URL a page's ALTCHA widget fetches the challenge of `procedure` from (`GET /__fabrika/challenge/<action>`), on the
+ * client's `baseUrl`. Throws for a procedure whose `admission.challenge` is not `provider: 'altcha'`.
+ */
+export declare function challengeUrl(procedure: object): string;
+declare const attachmentInput: unique symbol;
+/**
+ * An attachment procedure of a client: not a function, because its answer is a file. `download(api.<procedure>,
+ * input)` fetches and saves it.
+ */
+export interface AttachmentProcedure<I> {
+    /** `<mount>.<path>` */
+    readonly id: string;
+    /** The file name the contract declares. */
+    readonly filename: string;
+    /** Carries the input schema for `download`; never present at runtime. */
+    readonly [attachmentInput]?: I;
+}
+/**
+ * A procedure whose output is a file (`file('<kind>')`): not a function, because its answer is a file.
+ * `download(api.<procedure>, input)` fetches it with the caller's credential, and a GET one's `url(input)` is where a
+ * same-origin page links to it (`<img src>`, `<a download>`).
+ */
+export interface FileProcedure<I> {
+    /** `<mount>.<path>` */
+    readonly id: string;
+    /**
+     * The URL of the file a GET procedure answers, for a page signed in on the same origin. A client with a key has none:
+     * a key never goes into a URL, so it downloads instead.
+     */
+    url(...input: DownloadInput<I>): string;
+    /** Carries the input schema for `download`; never present at runtime. */
+    readonly [attachmentInput]?: I;
+}
+/** A downloaded file: a `File`, and the page's offer to save it. */
+export declare class DownloadedFile extends File {
+    /** The file as a `Blob`. */
+    blob(): Blob;
+    /** Offers the file as a download under its name; nothing where there is no page. */
+    save(): void;
+}
+/** The mount and path of an attachment procedure of a client, or `null` for any other value. */
+export declare function attachmentAt(value: unknown): {
+    readonly mount: string;
+    readonly path: string;
+} | null;
+/** The input `download` takes: the procedure's, or none. */
+export type DownloadInput<I> = [I] extends [InputSchema] ? [input: z.input<I>] : [input?: Record<never, never>];
+/**
+ * Calls a procedure that answers a file (an attachment, or a `file('<kind>')` output) with the caller's credential, and
+ * answers the file: `blob()`, `stream()`, `save()`. An attachment is also offered as a download in a browser, under the
+ * declared name. A refusal is an `RpcError`.
+ */
+export declare function download<I>(procedure: AttachmentProcedure<I> | FileProcedure<I>, ...input: DownloadInput<I>): Promise<DownloadedFile>;
+/** `download` of any file procedure of a client, its input unchecked: the provider's `useDownload` runs it. */
+export declare function downloadFile(procedure: object, input: unknown): Promise<DownloadedFile>;
+/**
+ * The client of mount `mount` of `contract`: one function per declared procedure. A link mount's client sends its
+ * share key as a bearer, so `options.key` is required there.
+ */
+export declare function createClient<const C extends AnyContract, const M extends ClientMount<C>>(contract: C, mount: M, ...rest: OptionsFor<C, M>): ContractClient<C, M>;
+export {};

package/types/src/client/error-reporting.d.ts

@@ -0,0 +1,66 @@
+import type { RpcFetch } from './transport';
+/** One stack frame in Sentry's shape, the file a script URL. */
+export interface BrowserFrame {
+    readonly filename: string;
+    readonly function?: string;
+    readonly lineno: number;
+    readonly colno: number;
+    /** A frame of a script of the page's own origin. */
+    readonly in_app: boolean;
+}
+/** Where the page reports, read from its browser config. */
+export interface ReportingTarget {
+    /** The ingest's envelope endpoint, authenticated by the DSN's public key in its query, as the Sentry SDK sends it. */
+    readonly envelopeUrl: string;
+    readonly release: string | null;
+    readonly environment: string | null;
+}
+/** What the reporter listens on and reads the page's address from: `window` in a page. */
+export interface ReportingPage {
+    addEventListener(type: 'error' | 'unhandledrejection', listener: (event: Event) => void): void;
+    removeEventListener(type: 'error' | 'unhandledrejection', listener: (event: Event) => void): void;
+    readonly location: {
+        readonly origin: string;
+        readonly pathname: string;
+    };
+}
+/** A page that keeps failing stops reporting here; Operations rate-limits the whole source, not one page. */
+export declare const MAX_REPORTS_PER_PAGE = 20;
+/**
+ * The envelope endpoint of an ingest DSN `https://<key>@<host>/<project>`, or `null` for any other value. The server's
+ * reporter parses the same DSN (`jobs/report.ts`); it is server code, so a page does not import it.
+ */
+export declare function envelopeUrlOf(dsn: string): string | null;
+/** The reporting target the browser config names, or `null` when it names no usable DSN. */
+export declare function reportingTargetOf(config: unknown): ReportingTarget | null;
+/**
+ * The frames of a V8, SpiderMonkey or JavaScriptCore `stack`, oldest call first as Sentry orders them, the
+ * `MAX_FRAMES` nearest the throw kept. A frame whose file is no URL (an `eval`, a native function) is left out.
+ */
+export declare function parseBrowserStack(stack: string, origin: string): BrowserFrame[];
+type Mechanism = 'onerror' | 'onunhandledrejection';
+interface ReportedException {
+    readonly type: string;
+    readonly value: string;
+    readonly mechanism: {
+        readonly type: Mechanism;
+        readonly handled: false;
+    };
+    readonly stacktrace?: {
+        readonly frames: readonly BrowserFrame[];
+    };
+}
+/** The envelope of one error event. The page's address goes without its query and fragment, which may carry a key. */
+export declare function browserEnvelope(exception: ReportedException, target: ReportingTarget, page: ReportingPage['location'], now: Date): string;
+/**
+ * Listen for the page's uncaught errors and unhandled rejections and send each to `target`; answers the uninstall.
+ * An error equal to the one just sent is not sent again, and the page sends at most `MAX_REPORTS_PER_PAGE`. A failed
+ * delivery is dropped: reporting never throws into the page.
+ */
+export declare function installErrorReporting(page: ReportingPage, target: ReportingTarget, send: RpcFetch): () => void;
+/**
+ * Read the browser config at `configUrl` and install reporting when it names a DSN; answers the uninstall, or `null`
+ * when nothing was installed. A missing, refused or unreadable config (local development, a test) installs nothing.
+ */
+export declare function startErrorReporting(configUrl: string, fetch: RpcFetch, page: ReportingPage): Promise<(() => void) | null>;
+export {};

package/types/src/client/index.d.ts

@@ -0,0 +1,4 @@
+export { type PageCaller, parsePageCaller } from './caller';
+export { type AttachmentProcedure, challengeUrl, type ClientMount, type ClientOptions, type ClientTree, type ContractClient, createClient, download, DownloadedFile, type DownloadInput, type FileProcedure, type InputOf, type LinkClientOptions, type ProcedureCall, type ResultOf, } from './contract';
+export { shareKey } from './share';
+export { type BounceOption, RpcError, type RpcFetch } from './transport';

package/types/src/client/rpc.d.ts

@@ -0,0 +1,14 @@
+import type { InferRpcClient } from '../rpc/contract.js';
+import { type BounceOption, type RpcFetch } from './transport.js';
+export interface RpcClientOptions {
+    /** Endpoint the RPC proxy POSTs to (e.g. `/rpc`). */
+    readonly baseUrl: string;
+    /**
+     * Auto-redirect to SSO on a sign-in 401 (`type: 'auth'` + `loginUrl`) instead of throwing.
+     * `true` uses sane defaults; pass `{ sessionKey, windowMs }` to tune the re-entry guard.
+     */
+    readonly bounceOnAuth?: BounceOption;
+    /** Override `fetch` (tests / non-browser). Defaults to the global `fetch`. */
+    readonly fetch?: RpcFetch;
+}
+export declare function createRpcClient<TApi>(opts: RpcClientOptions): InferRpcClient<TApi>;

package/types/src/client/share.d.ts

@@ -0,0 +1,2 @@
+/** The key the share link carried, or `null` outside a share SPA or when the link had none. */
+export declare function shareKey(): string | null;

package/types/src/client/transport.d.ts

@@ -0,0 +1,42 @@
+export declare class RpcError extends Error {
+    readonly type: string;
+    readonly issues?: unknown;
+    readonly loginUrl?: string;
+    readonly httpStatus?: number;
+    constructor(payload: {
+        type: string;
+        message: string;
+        issues?: unknown;
+        loginUrl?: string;
+        httpStatus?: number;
+    });
+}
+/** Minimal Fetch API surface required by the RPC client. */
+export type RpcFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Auto-redirect to SSO on a sign-in 401 (`type: 'auth'` + `loginUrl`) instead of throwing.
+ * `true` uses sane defaults; pass `{ sessionKey, windowMs }` to tune the re-entry guard.
+ */
+export type BounceOption = boolean | {
+    sessionKey?: string;
+    windowMs?: number;
+};
+export interface BounceConfig {
+    readonly sessionKey: string;
+    readonly windowMs: number;
+}
+export declare function resolveBounce(scope: string, opt: BounceOption | undefined): BounceConfig | null;
+/**
+ * Sends one request and answers the envelope's `result`; every failure is an `RpcError`, and so is every answer that is
+ * not 2xx, whatever its body holds. `init` builds the request inside the guard, so an input that does not serialize
+ * rejects like a failed request instead of throwing.
+ */
+export declare function exchange(doFetch: RpcFetch, url: string, init: () => RequestInit, bounce: BounceConfig | null): Promise<unknown>;
+/**
+ * Sends one request whose success is a file and answers its bytes and its `Content-Disposition`; a failure is read from
+ * its `{ error }` envelope.
+ */
+export declare function exchangeFile(doFetch: RpcFetch, url: string, init: () => RequestInit, bounce: BounceConfig | null): Promise<{
+    readonly body: Blob;
+    readonly disposition: string | null;
+}>;

package/types/src/cloudflare/application.d.ts

@@ -0,0 +1,42 @@
+import { type SqliteStorage } from '@fabrika/db/sqlite';
+import { type CrashEvents } from '../implement/crashes.js';
+import type { ContractImplementation } from '../implement/implement.js';
+import { type OpsStorage } from './ops.js';
+/** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
+export type ImplementationLoader = () => Promise<{
+    readonly default: ContractImplementation;
+}>;
+/** One of the application's SQLite migrations, as `fabrika app build` bundles them from `db/migrations`. */
+export interface ApplicationMigration {
+    readonly name: string;
+    readonly sql: string;
+}
+export interface ContractWorkerOptions {
+    /** The application's own SQLite migrations, applied as the bundle `app` after the framework's `fabrika`. */
+    readonly migrations?: readonly ApplicationMigration[];
+    /** Where the isolate hears of an unhandled rejection; the global `unhandledrejection` event by default. */
+    readonly rejections?: CrashEvents;
+    /** What posts a report to Operations' ingest; `fetch` by default. */
+    readonly operationsFetch?: (request: Request) => Promise<Response>;
+}
+/**
+ * Marks the Worker's minute tick, with its `scheduledTime`. The Worker's `fetch` removes it from every request it
+ * forwards, so only its own `scheduled` handler reaches the tick.
+ */
+export declare const TICK_HEADER = "X-Fabrika-Tick";
+/** What the object needs of its `ctx.storage`; a Durable Object's `DurableObjectStorage` fits it. */
+export type ApplicationStorage = SqliteStorage & OpsStorage;
+/** What the object needs of its `DurableObjectState`. */
+export interface ApplicationState {
+    readonly storage: ApplicationStorage;
+    blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+    waitUntil(promise: Promise<unknown>): void;
+}
+/** What the object classes of this isolate boot: the generated entrypoint's `createContractWorker` registers it. */
+export declare function registerApplication(load: ImplementationLoader, options: ContractWorkerOptions): void;
+/** The application environment's one object. The Worker's generated entrypoint exports it as `FabrikaApplication`. */
+export declare class FabrikaApplication {
+    #private;
+    constructor(state: ApplicationState, env: Readonly<Record<string, unknown>>);
+    fetch(request: Request): Promise<Response>;
+}

package/types/src/cloudflare/bindings.d.ts

@@ -0,0 +1,27 @@
+import type { IamMembershipRpc, IamTerminalRpc } from '@fabrika/auth-core';
+import type { IamKeySource } from '../implement/boot.js';
+import { type ConnectFetch } from '../implement/connect.js';
+import type { SpaAssets } from '../implement/dispatch.js';
+import type { WorkloadTokenSource } from '../implement/workload.js';
+/** The method `name` of a binding, bound to it, or `null` when it has none. */
+export declare function method(target: unknown, name: string): ((...args: unknown[]) => unknown) | null;
+export declare function bindingKeySource(binding: unknown): IamKeySource;
+/**
+ * IAM's membership operations on the `IAM` binding (`PropustkaApplication`), every answer decoded like the HTTP
+ * transport's. A binding without them is no membership transport, and `boot` refuses a contract that needs one.
+ */
+export declare function bindingMembership(binding: unknown): IamMembershipRpc | undefined;
+/** The identifications at a terminal over the IAM binding, when its entrypoint serves them (ADR-0067). */
+export declare function bindingTerminals(binding: unknown): IamTerminalRpc | undefined;
+/**
+ * IAM's token exchange on the `IAM` binding (`mintFromKey`), for the keys of the jobs, webhooks and public procedures.
+ * An answer that is not IAM's decided outcome throws: "IAM could not be asked".
+ */
+export declare function bindingWorkloadTokens(binding: unknown): WorkloadTokenSource | undefined;
+export declare function bindingAssets(binding: unknown): SpaAssets | undefined;
+/**
+ * The service bindings to owners' proxy Workers (`FABRIKA_CONNECT_<IMPORT>`), which `captureEnvironment` keeps from
+ * the application because no `FABRIKA_*` value reaches it. A binding routes by itself: the URL it is called with
+ * carries the owner's host, which the proxy Worker selects the application by.
+ */
+export declare function connectBindings(env: Readonly<Record<string, unknown>>): Record<string, ConnectFetch>;

package/types/src/cloudflare/names.d.ts

@@ -0,0 +1,6 @@
+/** The Durable Object class the Cloudflare entry exports: one object per application environment runs it (ADR-0065). */
+export declare const CLOUDFLARE_APPLICATION_CLASS = "FabrikaApplication";
+/** The binding through which the application's Worker reaches its object. */
+export declare const CLOUDFLARE_APPLICATION_BINDING = "FABRIKA_APPLICATION";
+/** The R2 bucket binding of the environment's stored files. */
+export declare const CLOUDFLARE_FILES_BINDING = "FABRIKA_FILES";

package/types/src/cloudflare/ops.d.ts

@@ -0,0 +1,46 @@
+import { type ApplicationObjects, type OpsBootFailureContent, type OpsOperation } from '@fabrika/auth-core';
+import type { SqliteCursor, SqliteValue } from '@fabrika/db/sqlite';
+/** What the view reads of the object's storage; workerd's `DurableObjectStorage` has both optional members. */
+export interface OpsStorage {
+    readonly sql: {
+        exec(query: string, ...bindings: SqliteValue[]): SqliteCursor;
+        /** The bun:sqlite test double has no size. */
+        readonly databaseSize?: number;
+    };
+    /** The bun:sqlite test double has no alarm. */
+    getAlarm?(): Promise<number | null>;
+}
+/** `X-Fabrika-Endpoint` of the composed ops row, the only value an ops request may carry (ADR-0022 rule 3). */
+export declare const OPS_ENDPOINT: string;
+/** What the platform wrote for the ops channel: the key digests and the objects a request may name. */
+export interface OpsAccess {
+    readonly digests: readonly Uint8Array[];
+    readonly objects: ApplicationObjects;
+}
+/** The environment's ops access, or `null` (an older deploy, or a malformed value), which refuses every ops request. */
+export declare function opsAccess(env: Readonly<Record<string, unknown>>): OpsAccess | null;
+/** What an ops request reads of the object it reached. */
+export interface OpsTarget {
+    readonly storage: OpsStorage;
+    /**
+     * The instance's last failed boot, the application's error text included. Asked only after authentication: it
+     * waits for a boot under way and never starts one.
+     */
+    bootFailure(): Promise<OpsBootFailureContent | null>;
+}
+/**
+ * Answers an ops request the Worker forwarded with the proxy secret, which the object checked before. Authentication
+ * runs first; an unknown operation, a malformed body and an object name the list lacks are refused after it.
+ */
+export declare function serveOps(request: Request, access: OpsAccess | null, target: OpsTarget): Promise<Response>;
+/** The object an ops request names, read with its operation's strict parser; `null` for a body that does not parse. */
+export declare function objectNamed(operation: OpsOperation, body: unknown): string | null;
+/** The request's body as JSON, or `undefined` when it is none: every parser refuses `undefined`. */
+export declare function jsonBody(request: {
+    text(): Promise<string>;
+}): Promise<unknown>;
+/**
+ * Control's credentials on an ops request: the row's method, its endpoint header, and a key whose digest is one the
+ * platform wrote, compared in constant time. The Worker and the object both run it; it reads nothing the body names.
+ */
+export declare function opsAuthenticated(request: Request, access: OpsAccess): boolean;

package/types/src/cloudflare/r2-files.d.ts

@@ -0,0 +1,9 @@
+import { type FileObjectStore } from '@fabrika/platform';
+/**
+ * R2 stores a stream only when its length is known up front, which an upload's is not. A body up to this size is
+ * buffered and written in one conditional put; a longer one goes up in parts of this size, so an object holds at most
+ * one part in memory. R2 takes parts of at least 5 MiB, all but the last of one size.
+ */
+export declare const R2_PART_BYTES: number;
+/** `bucket` (an R2 binding) as the files' object store, or `undefined` when the environment binds none. */
+export declare function r2FileObjectStore(bucket: unknown): FileObjectStore | undefined;

package/types/src/cloudflare.d.ts

@@ -0,0 +1,42 @@
+import { type ContractWorkerOptions, type ImplementationLoader } from './cloudflare/application.js';
+import type { FetchService, RequestExecutionContext } from './fetch.js';
+export { markProductionProcess } from '@fabrika/db/production';
+export { type ApplicationMigration, type ApplicationState, type ApplicationStorage, type ContractWorkerOptions, FabrikaApplication, type ImplementationLoader, } from './cloudflare/application.js';
+/** Minimal structural view of a Workers `ExecutionContext`. */
+export interface CloudflareExecutionContext extends RequestExecutionContext {
+    passThroughOnException(): void;
+}
+/** Minimal structural view of a Workers cron `ScheduledController`. */
+export interface CloudflareScheduledController {
+    readonly scheduledTime: number;
+    readonly cron: string;
+    noRetry(): void;
+}
+/** Minimal structural view of a Workers queue `MessageBatch`. */
+export interface CloudflareMessageBatch {
+    readonly queue: string;
+    readonly messages: ReadonlyArray<unknown>;
+}
+export interface CloudflareWorkerOptions<Env> {
+    scheduled?: (controller: CloudflareScheduledController, env: Env, exec: CloudflareExecutionContext) => Promise<void>;
+    queue?: (batch: CloudflareMessageBatch, env: Env, exec: CloudflareExecutionContext) => Promise<void>;
+}
+export interface CloudflareWorker<Env> {
+    fetch(request: Request, env: Env, exec: CloudflareExecutionContext): Promise<Response>;
+    scheduled?(controller: CloudflareScheduledController, env: Env, exec: CloudflareExecutionContext): Promise<void>;
+    queue?(batch: CloudflareMessageBatch, env: Env, exec: CloudflareExecutionContext): Promise<void>;
+}
+/** Adapt a runtime-neutral `{ fetch }` service to a Workers module export. */
+export declare function createCloudflareWorker<Env>(app: FetchService<Env>, options?: CloudflareWorkerOptions<Env>): CloudflareWorker<Env>;
+export interface ContractWorker {
+    fetch(request: Request, env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<Response>;
+    scheduled(controller: CloudflareScheduledController, env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<void>;
+}
+/**
+ * The Worker module of a contract application, called only by the generated entrypoint, which also exports
+ * `FabrikaApplication`. The application runs in the environment's Durable Object (ADR-0065): `fetch` forwards every
+ * request to it with the proxy secret, the proxy's own headers unchanged, and `scheduled` forwards the minute tick.
+ * An ops request goes to the object its body names instead (ADR-0069). The object captures the environment, imports
+ * the application and boots it.
+ */
+export declare function createContractWorker(load: ImplementationLoader, options?: ContractWorkerOptions): ContractWorker;

package/types/src/contract/app-id.d.ts

@@ -0,0 +1,2 @@
+/** The contract's application id rule; an id that holds to it reaches a generated script unquoted. */
+export declare const CONTRACT_APP_ID_PATTERN: RegExp;

package/types/src/contract/artifact-schema.d.ts

@@ -0,0 +1,8 @@
+import { type ContractArtifact, type OutputShape, type SchemaShape } from '@fabrika/auth-core';
+import { z } from 'zod/v4';
+/** A `SchemaShape` read back as JSON. */
+export declare const schemaShapeSchema: z.ZodType<SchemaShape>;
+export declare const outputShapeSchema: z.ZodType<OutputShape>;
+export declare const contractArtifactSchema: z.ZodType<ContractArtifact>;
+/** Parses JSON that should be a contract artifact; throws a `ZodError` naming every mismatch. */
+export declare function parseContractArtifact(value: unknown): ContractArtifact;

package/types/src/contract/attachment.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod/v4';
+import { type AttachmentDeclaration } from './declaration';
+import type { InputSchema, NotLoose, Schema } from './define';
+declare const ATTACHMENT: unique symbol;
+/** What `attachment()` adds to the rows' array schema: its declaration and its row schema. */
+export interface AttachmentMark {
+    readonly declaration: AttachmentDeclaration;
+    readonly row: InputSchema;
+}
+/** An attachment output of rows `R`: the handler returns `z.input<R>[]`, and the caller receives a file. */
+export type Attachment<R extends InputSchema> = z.ZodArray<R> & AttachmentBrand;
+/** What tells an attachment output from a JSON one in the types. */
+export interface AttachmentBrand {
+    readonly [ATTACHMENT]: AttachmentMark;
+}
+export interface AttachmentOptions<R> {
+    /**
+     * `'csv'`: RFC 4180, UTF-8 with a byte order mark, a header line of the row's field names. `'xlsx'`: one sheet, the
+     * header row of the field names, then a number, boolean or text cell per value, and a date cell for a string whose
+     * schema is `z.iso.date()` or `z.iso.datetime()`.
+     */
+    readonly format: 'csv' | 'xlsx';
+    /** The file name the browser saves: `[A-Za-z0-9._-]`, ending in `.csv` or `.xlsx`, as the format. */
+    readonly filename: string;
+    /** The row schema: a strict object of scalar fields, in the file's column order. */
+    readonly row: R;
+    /** The encoded file's limit; an encoding over it fails the invocation and sends no body. */
+    readonly maxBytes: number;
+    /** At most this many rows; 10 000 when left out. */
+    readonly maxRows?: number;
+}
+/**
+ * The output of a procedure that answers a file of `row`s. Like every builder it validates nothing: `compileContract`
+ * and the checker refuse a format, a name, a limit or a column outside what an attachment may be.
+ */
+export declare function attachment<R extends InputSchema>(options: AttachmentOptions<R & NotLoose<R>>): Attachment<R>;
+/** The rows' array schema marked with `declaration`; the static reader builds the evaluated value with it. */
+export declare function attachmentOutput<R extends InputSchema>(row: R, declaration: AttachmentDeclaration): Attachment<R>;
+/** The mark of an `attachment()` output, or `null` for any other schema. */
+export declare function attachmentOf(schema: Schema): AttachmentMark | null;
+export {};

package/types/src/contract/build.d.ts

@@ -0,0 +1,12 @@
+import { type ContractArtifact, type FileShape, type SchemaShape, type TablePolicyArtifact } from '@fabrika/auth-core';
+import { type ContractDeclaration } from './declaration';
+/** Turnstile's `action`: the procedure's endpoint id, which the verification expects back. */
+/** Validates a described contract against its table policies and normalizes it; throws `ContractError` with every problem. */
+export declare function buildArtifact(contract: ContractDeclaration<SchemaShape>, tables: Readonly<Record<string, TablePolicyArtifact>>): ContractArtifact;
+/** Whether a schema holds a file anywhere. */
+export declare function containsFile(shape: SchemaShape): boolean;
+/** The file fields of an input, by name: the parts a multipart body carries beside its JSON. */
+export declare function fileFieldsOf(input: SchemaShape | null): ReadonlyMap<string, FileShape & {
+    readonly many: boolean;
+    readonly max: number;
+}>;

package/types/src/contract/compile.d.ts

@@ -0,0 +1,11 @@
+import type { ContractArtifact, SchemaShape, TablePolicyArtifact } from '@fabrika/auth-core';
+import { type Tables } from '@fabrika/db/tables';
+import { type ContractDeclaration } from './declaration';
+import type { AnyContract } from './define';
+/**
+ * The normalized artifact of a contract and its table policies: what `defineTables` returned (`src/db/tables.ts`),
+ * or the artifact form of each policy.
+ */
+export declare function compileContract<DB, P>(contract: AnyContract, tables: Tables<DB, P> | Readonly<Record<string, TablePolicyArtifact>>): ContractArtifact;
+/** The contract with its schemas read as shapes; throws `ContractError` for a schema outside the subset. */
+export declare function describeContract(contract: AnyContract): ContractDeclaration<SchemaShape>;