@fabrika/app 0.8.1 → 0.9.0-dev.2

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

@@ -0,0 +1,274 @@
+import type { EndpointCache, RpcCaller } from '@fabrika/auth-core';
+import type { AnyDbIndex, ReadOnlyUnscoped, Unavailable, UnscopedDeclaration, UnscopedMode } from '@fabrika/db/tables';
+import type { z } from 'zod/v4';
+import type { Snake } from '../from-row';
+import type { ExtraKeys, HandlerInput, IsAny } from '../implement/types';
+import type { AttachmentBrand } from './attachment';
+import type { CheckedAccess, Declared, EndpointContext, ExportContext, ImportOf, KickContext, KitTypes, LinkContext, PublicContext, SqlMode, TokensContext, WebhooksContext } from './context';
+import type { ProcedureType } from './declaration';
+import type { AppAccess, CapabilitiesAccess, CapabilityAccess, ChallengeOption, InputOf, InputSchema, LinkAccess, MemberAccess, MutationAccess, NotLoose, Procedure, PublicAccess, QueryAccess, Schema } from './define';
+import type { WithClaims } from './token';
+/** Fields a builder sets itself: a definition that carries one does not type-check. */
+type Owned<K extends string> = {
+    readonly [P in K]?: never;
+};
+/** Unknown keys of an `unscoped` declaration, each refused at its own line. */
+type ExactTables<U, Tables extends string> = [Exclude<keyof U, Tables>] extends [never] ? unknown : {
+    readonly [P in Exclude<keyof U, Tables>]: Unavailable<`${P & string} is not a table of src/db/tables.ts`>;
+};
+/**
+ * The off-road fields a site declares. Each is inferred from its optional field and then required: a handle exists
+ * only for a declaration the object really carries, never for one an annotation merely allows.
+ */
+export type DeclaredFields<S, U, Cn, Is, Ix extends AnyDbIndex> = {
+    /** `ctx.sql`, in this mode; a query declares only `'read'`. */
+    readonly sql?: S;
+    /** `ctx.db.unscoped.<table>`, each in its mode, scope predicate `true`; a query declares only `'read'`. */
+    readonly unscoped?: U;
+    /** `ctx.connect.<connector>`, for the connectors the kit imports. */
+    readonly connect?: Cn;
+    /** `ctx.links.issue` for this link mount, on an endpoint whose action is the mount's `issuedBy`. */
+    readonly issues?: Is;
+} & ([S] extends [never] ? unknown : {
+    readonly sql: S & NoInfer<SqlReach<keyof Ix['tables'] & string>>;
+}) & ([U] extends [never] ? unknown : {
+    readonly unscoped: U & NoInfer<ExactTables<U, keyof Ix['tables'] & string> & ReadOnlyUnscoped<Ix, U>>;
+}) & ([Cn] extends [never] ? unknown : {
+    readonly connect: Cn & NoInfer<LiteralList<Cn>>;
+}) & ([Is] extends [never] ? unknown : {
+    readonly issues: Is & NoInfer<OneLiteral<Is>>;
+});
+/** `ctx.sql` runs on `@fabrika/db`, so a kit without tables declares no `sql`. */
+type SqlReach<Tables extends string> = [Tables] extends [never] ? Unavailable<'ctx.sql runs on @fabrika/db: a kit without tables (defineApp(vocabulary)) declares no sql'> : unknown;
+/** A list typed only by its element (`readonly 'catalog'[]`) may hold none of them; the declaration is a literal tuple. */
+type LiteralList<Cn> = Cn extends readonly unknown[] ? number extends Cn['length'] ? "connect names its connectors as a literal list: connect: ['catalog']" : unknown : unknown;
+/** `issues` names one link mount, as a literal. */
+type OneLiteral<Is> = string extends Is ? Unavailable<"issues names one link mount, as a literal: issues: 'shared'"> : true extends IsUnion<Is> ? Unavailable<"issues names one link mount, as a literal: issues: 'shared'"> : unknown;
+/** A query writes nothing, so it has nothing to kick a job for and no binding to write. */
+type NoKick = {
+    readonly kicks?: Unavailable<'a query kicks no job: declare kicks on a mutation'>;
+    readonly binds?: Unavailable<'a query binds no webhook: declare binds on a mutation'>;
+};
+/** `binds` names one webhook, as a literal. */
+type OneWebhook<Bs> = string extends Bs ? Unavailable<"binds names one webhook, as a literal: binds: 'stripe'"> : true extends IsUnion<Bs> ? Unavailable<"binds names one webhook, as a literal: binds: 'stripe'"> : unknown;
+/** The webhook whose bindings a mutation writes (`ctx.webhooks`), inferred from its optional field and then required. */
+type BindsField<Bs> = {
+    readonly binds?: Bs;
+} & ([Bs] extends [never] ? unknown : {
+    readonly binds: Bs & NoInfer<OneWebhook<Bs>>;
+});
+/** The jobs a mutation may kick (`ctx.kick`), inferred from its optional field and then required, as a literal list. */
+export type KicksField<Ks> = {
+    readonly kicks?: Ks;
+} & ([Ks] extends [never] ? unknown : {
+    readonly kicks: Ks & NoInfer<LiteralList<Ks>>;
+});
+/** The token purposes a site signs (`ctx.tokens.sign`), inferred from its optional field and then required, as a literal list. */
+export type SignsField<Sg, Purposes extends string> = {
+    readonly signs?: Sg;
+} & ([Sg] extends [never] ? unknown : {
+    readonly signs: Sg & NoInfer<KnownPurposes<Sg, Purposes>>;
+});
+/**
+ * The HTTPS origins a site's code calls (`fetch`): each an exact origin, no path or wildcard. A guard on the global
+ * `fetch` refuses any other while the site runs; a public procedure declares none.
+ */
+export interface EgressField {
+    readonly egress?: readonly `https://${string}`[];
+}
+/** Each purpose `signs` names is one of `defineApp`'s `tokens`. */
+type KnownPurposes<Sg, Purposes extends string> = Sg extends readonly (infer P extends string)[] ? [Exclude<P, Purposes>] extends [never] ? LiteralList<Sg> : Unavailable<`signs names ${ListOf<Exclude<P, Purposes>>}, which defineApp's tokens do not declare`> : unknown;
+type IsUnion<T, All = T> = T extends unknown ? ([All] extends [T] ? false : true) : never;
+/** A bucket's calls per minute, or `null` to turn a default bucket off. */
+type Bucket = number | null;
+/**
+ * How a procedure is admitted (`admission`), merged into its kind's default: a public mutation counts 10 calls per
+ * minute per client and 100 for the endpoint; every other procedure counts none unless it declares a bucket.
+ */
+export type AdmissionOption<Acc> = [Acc] extends [PublicAccess] ? {
+    /** `'same-origin'` by default; `'listed'` the environment's listed origins; `'any'` every origin. */
+    readonly origins?: 'same-origin' | 'listed' | 'any';
+    readonly rate?: {
+        readonly perClient?: Bucket;
+        readonly perEndpoint?: Bucket;
+        readonly bytesPerHour?: Bucket;
+    };
+    /** Verified on the server before the handler; the input carries the widget's token in `challengeToken`. */
+    readonly challenge?: ChallengeOption;
+} : {
+    /** `'same-origin'` by default; `'listed'` the environment's listed origins, with a key only (ADR-0022). */
+    readonly origins?: 'same-origin' | 'listed';
+    readonly rate?: {
+        readonly perCaller?: Bucket;
+        readonly perEndpoint?: Bucket;
+    };
+};
+/** A procedure's bounds: its body in bytes (64 KiB by default, at most 1 MiB) and its handler's time (10 s, at most 60 s). */
+export interface LimitsOption {
+    readonly maxBytes?: number;
+    readonly timeoutMs?: number;
+}
+/**
+ * A public procedure's workload actions, which its handler holds and nothing else; no other procedure declares them.
+ * Inferred from the optional field and then required, like a declared field.
+ */
+export type PublicFields<Acc, Acts> = [Acc] extends [PublicAccess] ? {
+    readonly actions: Acts & NoInfer<Acts extends readonly [] ? Unavailable<"a public procedure names what its handler holds: actions: ['<action>']"> : unknown>;
+} : {
+    readonly actions?: Unavailable<'only a public procedure declares actions: its handler runs as its own workload'>;
+};
+/** The handler context of a group's procedure: a public one runs as its own workload, every other as its caller. */
+export type ProcedureContext<K extends KitTypes, Caller extends RpcCaller, Kind extends 'query' | 'mutation', Acc, Acts extends readonly string[], D extends Declared<SqlMode, unknown, readonly string[], string>, Ks = never, Bs = never, Sg = never> = ([Acc] extends [PublicAccess] ? PublicContext<K, Kind, Acts[number]> : EndpointContext<K, Caller, Kind, CheckedAccess<Acc>, D> & WebhooksContext<Bs>) & KickContext<Ks> & TokensContext<K, Sg>;
+/** A group without callers holds public procedures only; any other group may hold both. */
+export type GroupAccess<Caller extends RpcCaller, Acc> = [Caller] extends [never] ? PublicAccess : Acc | PublicAccess;
+/** An endpoint's declaration: its schemas, its access form and the reach it declares. */
+export type EndpointDef<I, O, Acc, S, U, Cn, Is, Ix extends AnyDbIndex> = Owned<'~kind' | 'type'> & {
+    readonly input?: I & NotLoose<I>;
+    readonly output: O & NotLoose<O>;
+    readonly access: Acc;
+    readonly admission?: AdmissionOption<Acc>;
+    readonly limits?: LimitsOption;
+} & DeclaredFields<S, U, Cn, Is, Ix>;
+/**
+ * A group procedure's HTTP shape, its `query` schema inferred: what its handler then reads as `query`. Only a public
+ * procedure has a path of its own.
+ */
+type HttpField<Q, Acc> = {
+    readonly http?: HttpOption<Q & NoInfer<NotLoose<Q>>> & OwnPathOption<Acc>;
+};
+/**
+ * `http.path`: a public procedure served at a literal path of its own instead of `<prefix>/<name>`, so a caller outside
+ * the application keeps its URL. It lies outside every mount's prefix and under no `/__fabrika`.
+ */
+export type OwnPathOption<Acc> = [Acc] extends [PublicAccess] ? {
+    readonly path?: `/${string}`;
+} : unknown;
+type Returned<F> = F extends (args: never) => infer R ? Awaited<R> : never;
+/** The last member of a union, in the order the compiler holds it. */
+type LastOf<U> = (U extends unknown ? (member: () => U) => void : never) extends (member: infer I) => void ? I extends () => infer L ? L : never : never;
+/** `'a' | 'b'` → `'a, b'`, for a message. */
+export type ListOf<U extends string, Listed extends string = ''> = [U] extends [never] ? Listed : ListOf<Exclude<U, LastOf<U>>, Listed extends '' ? LastOf<U> & string : `${LastOf<U> & string}, ${Listed}`>;
+/** The fields, at any depth, that a handler `F` returns and the output `O` does not declare. */
+export type UndeclaredFields<F, O extends Schema> = ExtraKeys<Returned<F>, z.input<O>>;
+/** An object with a camelCase field, which a database row names in snake_case. */
+type HasCamel<V> = {
+    [K in keyof V]: K extends string ? (Snake<K> extends K ? never : K) : never;
+}[keyof V];
+/**
+ * A database row returned where the output declares camelCase fields: its snake_case columns, of any value, at the
+ * depth the output has them. `.handle` admits it so that `ExactReturn` can name `fromRow` in one line.
+ */
+type RowShaped<V> = V extends readonly (infer Item)[] ? readonly RowShaped<Item>[] : V extends object ? [HasCamel<V>] extends [never] ? {
+    readonly [K in keyof V]: RowShaped<V[K]>;
+} : {
+    readonly [K in keyof V as Snake<K & string>]: unknown;
+} : V;
+/**
+ * What a kit handler `F` may return: the output, or — only when `F` returns one — a database row of it, which
+ * `ExactReturn` refuses with the fix, as it refuses anything but rows from an attachment's handler. Any other mistake
+ * keeps the compiler's own message about the output.
+ */
+export type HandlerReturn<F, O extends Schema> = [Returned<F>] extends [z.input<O>] ? z.input<O> : [O] extends [AttachmentBrand] ? unknown : [Returned<F>] extends [RowShaped<z.input<O>>] ? RowShaped<z.input<O>> : z.input<O>;
+/** A kit endpoint's handler, returning `R`; `X` adds what its HTTP shape reads beside the input (`query`). */
+export type KitHandler<In, Ctx, R, X = unknown> = (args: {
+    readonly input: In;
+    readonly ctx: Ctx;
+} & X) => R | Promise<R>;
+/**
+ * What a handler reads beside its input: the URL's `query` of a POST that declares `http.query`, each signed token in it
+ * as the claims of its purpose.
+ */
+export type QueryArgs<Q, T = Record<never, never>> = [Q] extends [never] ? unknown : Q extends InputSchema ? {
+    readonly query: WithClaims<z.output<Q>, T>;
+} : unknown;
+/**
+ * The wire of a procedure: `POST` with a JSON body by default; a query may be `GET`, its input then flat scalar URL
+ * parameters; a POST may read a flat `query` from the URL and take a native form's `urlencoded` body.
+ */
+export interface HttpOption<Q> {
+    readonly method?: 'GET' | 'POST';
+    readonly query?: Q;
+    readonly body?: 'json' | 'urlencoded';
+    /**
+     * A public GET query's successful answers may be reused: `{ maxAgeSeconds }`, or `'immutable'` (a year) when its
+     * input names an immutable value. Every other answer is `no-store`.
+     */
+    readonly cache?: EndpointCache;
+}
+/**
+ * What `.handle` answers: the endpoint, or a message the group refuses at the endpoint's line — when the handler
+ * returns a database row where the output is camelCase, anything but rows for an attachment, or, at any depth, a
+ * field the output does not declare. A field whose type is an error elsewhere in the handler is not reported again here.
+ */
+export type ExactReturn<F, O extends Schema, E> = [Returned<F>] extends [z.input<O>] ? [UndeclaredFields<F, O>] extends [never] ? E : IsAny<UndeclaredFields<F, O>> extends true ? E : Unavailable<`the handler returns ${ListOf<UndeclaredFields<F, O> & string>}, which the output does not declare: return only declared fields`> : [O] extends [AttachmentBrand] ? Unavailable<'an attachment handler returns its rows: an array of its row schema, with nothing around it'> : Unavailable<`the handler returns a database row (${ListOf<UndeclaredFields<F, O> & string>}) where the output is camelCase: map it with fromRow(Schema, row) from @fabrika/app`>;
+/** A declared, handled endpoint: what a group holds. Its type keeps the declaration and drops the handler's. */
+export interface Endpoint<T extends ProcedureType, I extends InputSchema | null, O extends Schema, Acc, D> extends Procedure<T, I, O, Acc> {
+    readonly declared: D;
+}
+/**
+ * An endpoint before `.handle`: a group refuses it. `Tk` are the kit's token purposes: a signed token field of the input
+ * reaches the handler as the claims of its purpose.
+ */
+export interface EndpointBuilder<T extends ProcedureType, I extends InputSchema | null, O extends Schema, Acc, D, Ctx, X = unknown, Tk = Record<never, never>> extends PendingEndpoint {
+    /** The endpoint's handler, typed by its access form and declaration; it may return only the output's fields. */
+    handle<const F extends KitHandler<WithClaims<HandlerInput<I, Acc>, Tk>, Ctx, HandlerReturn<F, O>, X>>(handler: F): ExactReturn<F, O, Endpoint<T, I, O, Acc, D>>;
+}
+/** What every endpoint builder has and no handled endpoint has. */
+export interface PendingEndpoint {
+    handle(handler: never): unknown;
+}
+/**
+ * The builders of a group's callback: they know the group's callers, so a handler knows its principal. A group without
+ * callers (`Caller` is `never`) declares public procedures only.
+ */
+export interface GroupKit<K extends KitTypes, Caller extends RpcCaller> {
+    query<const Acc extends GroupAccess<Caller, QueryAccess<K['action'], K['dimension'], InputOf<I>>>, O extends Schema, I extends InputSchema | null = null, const S extends 'read' = never, const U extends UnscopedDeclaration<K['tables'], 'read'> = never, const Cn extends readonly ImportOf<K>[] = never, const Is extends string = never, const Acts extends readonly K['action'][] = never, Q extends InputSchema = never, const Sg extends readonly string[] = never>(def: EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']> & PublicFields<Acc, Acts> & HttpField<Q, Acc> & NoKick & SignsField<Sg, keyof K['tokens'] & string> & EgressField): EndpointBuilder<'query', I, O, Acc, Declared<S, U, Cn, Is>, ProcedureContext<K, Caller, 'query', Acc, Acts, Declared<S, U, Cn, Is>, never, never, Sg>, QueryArgs<Q, K['tokens']>, K['tokens']>;
+    mutation<const Acc extends GroupAccess<Caller, MutationAccess<K['action'], K['dimension'], K['creatable'], InputOf<I>>>, O extends Schema, I extends InputSchema | null = null, const S extends SqlMode = never, const U extends UnscopedDeclaration<K['tables'], UnscopedMode> = never, const Cn extends readonly ImportOf<K>[] = never, const Is extends string = never, const Acts extends readonly K['action'][] = never, Q extends InputSchema = never, const Ks extends readonly string[] = never, const Bs extends string = never, const Sg extends readonly string[] = never>(def: EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']> & PublicFields<Acc, Acts> & HttpField<Q, Acc> & KicksField<Ks> & BindsField<Bs> & SignsField<Sg, keyof K['tokens'] & string> & EgressField): EndpointBuilder<'mutation', I, O, Acc, Declared<S, U, Cn, Is>, ProcedureContext<K, Caller, 'mutation', Acc, Acts, Declared<S, U, Cn, Is>, Ks, Bs, Sg>, QueryArgs<Q, K['tokens']>, K['tokens']>;
+}
+/** Any handled endpoint. */
+export type AnyEndpoint = Endpoint<ProcedureType, InputSchema | null, Schema, unknown, unknown>;
+/** What a group's callback returns: its endpoints by name. A mount nests groups; a group does not nest. */
+export interface GroupTree {
+    readonly [name: string]: AnyEndpoint;
+}
+/** What a group's callback may return before the group checks that every endpoint took its handler. */
+export interface GroupInput {
+    readonly [name: string]: AnyEndpoint | PendingEndpoint;
+}
+declare const failedBuild: unique symbol;
+/**
+ * The constraint `app.group` infers against. A refused callback falls back to it, and its private symbol keeps the
+ * mount from repeating that error. It is not an annotation: a group typed with it mounts unchecked.
+ */
+export interface GroupBuild extends GroupInput {
+    readonly [failedBuild]?: true;
+}
+/**
+ * A builder without `.handle(…)`. An endpoint typed by the compiler's error type is the consequence of a type error
+ * inside its handler, reported there; every check is wrapped in a tuple, since an unwrapped one answers the error type.
+ */
+type IsPending<E> = [0] extends [1 & E] ? false : [Extract<E, PendingEndpoint>] extends [never] ? false : true;
+/** The endpoints of a group, prefixed by `Path`, that have no `.handle(…)`. */
+export type PendingIn<T, Path extends string> = typeof failedBuild extends keyof T ? never : string extends keyof T ? [IsPending<T[string & keyof T]>] extends [true] ? `${Path}* (its type admits an endpoint without a handler)` : never : {
+    [K in keyof T]: [IsPending<T[K]>] extends [true] ? `${Path}${K & string}` : never;
+}[keyof T];
+/** `app.group(…)`: endpoints for one set of callers (none for a group of public procedures), mounted by the contract. */
+export interface Group<C extends readonly RpcCaller[], T extends GroupInput> {
+    readonly '~kind': 'group';
+    readonly callers: C;
+    readonly endpoints: T;
+}
+/** The builders of a link mount's callback: each procedure acts on the object its key is bound to. */
+export interface LinkGroupKit<K extends KitTypes, LD extends string, G extends string> {
+    query<const Acc extends LinkAccess<G>, O extends Schema, I extends InputSchema | null = null, const S extends 'read' = never, const U extends UnscopedDeclaration<K['tables'], 'read'> = never>(def: EndpointDef<I, O, Acc, S, U, never, never, K['index']> & NoKick): EndpointBuilder<'query', I, O, Acc, Declared<S, U, never, never>, LinkContext<K, 'query', LD, Acc['action'], Declared<S, U, never, never>>, unknown, K['tokens']>;
+    mutation<const Acc extends LinkAccess<G>, O extends Schema, I extends InputSchema | null = null, const S extends SqlMode = never, const U extends UnscopedDeclaration<K['tables'], UnscopedMode> = never, const Ks extends readonly string[] = never>(def: EndpointDef<I, O, Acc, S, U, never, never, K['index']> & KicksField<Ks>): EndpointBuilder<'mutation', I, O, Acc, Declared<S, U, never, never>, LinkContext<K, 'mutation', LD, Acc['action'], Declared<S, U, never, never>> & KickContext<Ks>, unknown, K['tokens']>;
+}
+/** An export procedure names its action and its scope; `{ member: true }` would give the consumer's key nothing to hold. */
+export type ExportAccess<A extends string, D extends string, In> = Exclude<QueryAccess<A, D, In>, MemberAccess | AppAccess<A> | CapabilitiesAccess<{
+    readonly [name: string]: CapabilityAccess<A, D, In>;
+}>>;
+/** The builder of an export's callback: queries only, run read-only. */
+export interface ExportKit<K extends KitTypes> {
+    query<const Acc extends ExportAccess<K['action'], K['dimension'], InputOf<I>>, O extends Schema, I extends InputSchema | null = null, const S extends 'read' = never, const U extends UnscopedDeclaration<K['tables'], 'read'> = never>(def: EndpointDef<I, O, Acc, S, U, never, never, K['index']>): EndpointBuilder<'query', I, O, Acc, Declared<S, U, never, never>, ExportContext<K, CheckedAccess<Acc>, Declared<S, U, never, never>>>;
+}
+export {};

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

@@ -0,0 +1,18 @@
+import type { ConnectSnapshot } from './connect';
+/** `site` with its handler, which only `handlerOf` reads. */
+export declare function withHandler<T extends object>(site: T, handler: unknown): T;
+/** The handler `.handle` attached to a site of the kit, or `undefined` for a site that took none. */
+export declare function handlerOf(site: object): unknown;
+/** `contract` with the snapshots of the kit's imports, by the import's name. */
+export declare function withSnapshots<T extends object>(contract: T, imported: Readonly<Record<string, ConnectSnapshot>>): T;
+/** The snapshots `app.contract` recorded for `contract`; none for a contract the kit did not build. */
+export declare function snapshotsOf(contract: object): Readonly<Record<string, ConnectSnapshot>>;
+/** Which kit built a contract: one with tables, `defineApp(vocabulary, tables)`, or one without, `defineApp(vocabulary)`. */
+export type KitOrigin = 'tables' | 'tableless';
+/** `contract` as `app.contract` built it, with the kind of kit that built it. */
+export declare function withKitOrigin<T extends object>(contract: T, origin: KitOrigin): T;
+/**
+ * The kind of kit that built `contract`, or `undefined` for any other object, a copy of a kit's contract included: a
+ * copy loses what is kept beside the original, so `serve` refuses it.
+ */
+export declare function kitOriginOf(contract: object): KitOrigin | undefined;

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

@@ -0,0 +1,19 @@
+export { contractArtifactSchema, parseContractArtifact, schemaShapeSchema } from './artifact-schema';
+export { type Attachment, attachment, type AttachmentBrand, type AttachmentMark, attachmentOf, type AttachmentOptions, attachmentOutput, } from './attachment';
+export { buildArtifact } from './build';
+export { compileContract, describeContract } from './compile';
+export { type ConnectSnapshot, describeSnapshot, exportDescription, exportDescriptionSchema, incompatibleChanges, incompatibleMountChanges, parseExportDescription, type SnapshotProcedure, } from './connect';
+export type * from './context';
+export * from './declaration';
+export * from './defaults';
+export * from './define';
+export { type ClientInput, file, type FileBrand, type FileMark, fileOf, type FileRef, type FileSchema, type FileStatus } from './file';
+export type * from './group';
+export * from './kit';
+export { schemaFromContract } from './platform';
+export { ContractError } from './problems';
+export { type Redirect, redirect, type RedirectBrand, type RedirectMark, redirectOf, type RedirectOptions } from './redirect';
+export { SNAPSHOT_DIRECTORY, type SnapshotNames, snapshotNames, snapshotSource } from './snapshot-source';
+export { SIGNED_TOKEN_MAX_LENGTH, signedToken, type SignedTokenMark, signedTokenOf, type SignedTokenSchema, token, TOKEN_MAX_DAYS, type TokenOptions, type TokenPurpose, type TokenPurposes, type TokenSigning, type WithClaims, } from './token';
+export * from './vocabulary';
+export { type WebhookBindings, WebhookSecret } from './webhook-binding';

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

@@ -0,0 +1,210 @@
+import type { JobMailer, RpcCaller, WebhookScheme } from '@fabrika/auth-core';
+import type { AnyDbIndex, DbIndex, Tables, Unavailable, UnscopedDeclaration, UnscopedMode } from '@fabrika/db/tables';
+import type { z } from 'zod/v4';
+import type { Declared, JobKitContext, KickContext, KitImports, KitTypes, NoTablesIndex, SqlMode, TokensContext, WebhookKitContext } from './context';
+import { type ExportAccessDeclaration, type ImportDeclaration, type LinkAccessDeclaration, type ProcedureType } from './declaration';
+import { type Contract, type CreatableDimension, type CronJob, type Export, type InputSchema, type JobLimitsOption, type Kit, type LinkMount, type NotLoose, type Path, type ProcedureTree, type RpcMount, type Schema, type Surface, type WebhookMount } from './define';
+import type { DeclaredFields, EgressField, Endpoint, ExportKit, Group, GroupBuild, GroupInput, GroupKit, KicksField, LimitsOption, LinkGroupKit, ListOf, PendingIn, SignsField } from './group';
+import type { TokenPurposes } from './token';
+import type { AnyAppVocabulary, AppVocabulary } from './vocabulary';
+/** Fields a builder sets itself: an options object that carries one does not type-check. */
+type Owned<K extends string> = {
+    readonly [P in K]?: never;
+};
+/** The kit's types, computed once from the vocabulary, the tables' index, the imports and the token purposes. */
+export type KitOf<V, Ix, Imp extends KitImports, Tk extends TokenPurposes = Record<never, never>> = V extends AppVocabulary<infer A, infer D, infer R, infer Dims, infer M> ? {
+    readonly action: A;
+    readonly dimension: D;
+    readonly creatable: CreatableDimension<Dims>;
+    readonly role: R;
+    readonly dimensions: Dims;
+    readonly members: M;
+    readonly index: Ix;
+    readonly tables: Ix extends {
+        readonly tables: infer T;
+    } ? keyof T & string : never;
+    readonly imports: Imp;
+    readonly tokens: Tk;
+} : never;
+export type CronOptions<Acts, S, U, Is, Ix extends AnyDbIndex, M = never, Ks = never, Sg = never, Purposes extends string = never> = Owned<'kind' | 'schedule'> & {
+    readonly actions: Acts;
+    readonly limits?: JobLimitsOption;
+    readonly retries?: number;
+} & DeclaredFields<S, U, never, Is, Ix> & MailerField<M> & KicksField<Ks> & SignsField<Sg, Purposes> & EgressField;
+/** The mail transport a job reaches, inferred from its optional field and then required, like a declared field. */
+type MailerField<M> = {
+    /** `'installation'`: the installation's mail transport; `'own'`: the application's own. */
+    readonly mailer?: M;
+} & ([M] extends [never] ? unknown : {
+    readonly mailer: M;
+});
+/** A cron job of the kit, handled. */
+export interface KitCronJob<Acts extends string, D> extends CronJob<Acts> {
+    readonly declared: D;
+}
+/** A cron job before `.handle`: the contract's `jobs` refuses it. */
+export interface CronBuilder<K extends KitTypes, Acts extends string, D extends Declared<SqlMode, unknown, never, string, JobMailer>, Ks = never, Sg = never> {
+    handle(handler: (args: {
+        readonly ctx: JobKitContext<K, Acts, D> & KickContext<Ks> & TokensContext<K, Sg>;
+    }) => void | Promise<void>): KitCronJob<Acts, D>;
+}
+export type WebhookOptions<B, Acts, I, S, U, Ix extends AnyDbIndex, Ks = never, Sg = never, Purposes extends string = never> = Owned<'kind' | 'path'> & {
+    readonly scheme: WebhookScheme;
+    readonly boundTo: B;
+    readonly actions: Acts;
+    readonly input: I & NotLoose<I>;
+    /** A delivery's body (1 MiB by default and at most) and its handler's time (10 s by default, at most 60 s). */
+    readonly limits?: LimitsOption;
+} & DeclaredFields<S, U, never, never, Ix> & KicksField<Ks> & SignsField<Sg, Purposes> & EgressField;
+/** A webhook of the kit, handled. */
+export interface KitWebhook<B extends string, Acts extends string, I extends Schema, D> extends WebhookMount<B, Acts, I> {
+    readonly declared: D;
+}
+/** A webhook before `.handle`: the contract refuses it as a mount. */
+export interface WebhookBuilder<K extends KitTypes, B extends string, Acts extends string, I extends InputSchema, D extends Declared<SqlMode, unknown, never, never>, Ks = never, Sg = never> {
+    handle(handler: (args: {
+        readonly input: z.output<I>;
+        readonly ctx: WebhookKitContext<K, B, Acts, D> & KickContext<Ks> & TokensContext<K, Sg>;
+    }) => void | Promise<void>): KitWebhook<B, Acts, I, D>;
+}
+/** A link mount's procedures: handled endpoints whose access names one of the mount's granted actions. */
+export interface LinkTree {
+    readonly [name: string]: Endpoint<ProcedureType, InputSchema | null, Schema, LinkAccessDeclaration, unknown>;
+}
+/** An export's procedures: handled queries. */
+export interface ExportTree {
+    readonly [name: string]: Endpoint<'query', InputSchema | null, Schema, ExportAccessDeclaration, unknown>;
+}
+/** What `c.rpc` mounts: one group, or groups by name, nested. */
+export type MountedGroups = Group<readonly RpcCaller[], GroupInput> | {
+    readonly [name: string]: MountedGroups;
+};
+/** The callers each group names; a group of public procedures names none and is left out. */
+type CallersOf<G> = G extends Group<infer C, GroupInput> ? (C extends readonly [] ? never : C) : {
+    [K in keyof G]: CallersOf<G[K]>;
+}[keyof G];
+type EndpointsOf<G> = G extends Group<readonly RpcCaller[], infer T> ? T : {
+    readonly [K in keyof G]: EndpointsOf<G[K]>;
+};
+/** A group that names callers names at least one; a group of public procedures leaves `callers` out. */
+type SomeCallers<C> = C extends readonly [] ? Unavailable<"callers names at least one caller: callers: ['human']; a group of public procedures names none"> : unknown;
+/** The callers of the mount's credentialed procedures, `readonly []` when every group is public. */
+type Callers<G> = [CallersOf<G>] extends [never] ? readonly [] : CallersOf<G> extends infer C extends readonly RpcCaller[] ? C : never;
+type Endpoints<G> = EndpointsOf<G> extends infer T extends ProcedureTree ? T : never;
+type IsUnion<T, All = T> = T extends unknown ? ([All] extends [T] ? false : true) : never;
+type PendingOf<G, Path extends string = ''> = G extends Group<readonly RpcCaller[], infer T> ? PendingIn<T, Path> : {
+    [K in keyof G & string]: PendingOf<G[K], `${Path}${K}.`>;
+}[keyof G & string];
+/**
+ * A mount takes its prefix only when it can serve every group: each endpoint took its `.handle(…)` (a group accepts
+ * one without, because its own callback cannot be checked before it is typed), and every group names the same callers.
+ */
+type MountPrefix<G> = [PendingOf<G>] extends [never] ? true extends IsUnion<CallersOf<G>> ? Unavailable<'every group of one RPC mount that names callers names the same ones, in the same order'> : Path : Unavailable<`add .handle(…) to ${ListOf<PendingOf<G>>}: every endpoint takes its handler beside it`>;
+/** The builders of the contract's callback: the mounts that take no handler, and `rpc`, which mounts groups. */
+export interface ContractKit<K extends KitTypes> extends Pick<Kit<K['action'], K['dimension'], K['creatable']>, 'spa' | 'health' | 'files'> {
+    /**
+     * The groups' endpoints at `POST <prefix>/<group>.<endpoint>`, to the callers the groups name. `compatibility:
+     * 'backward'` promises their callers that a later deploy breaks none of them; Control refuses one that does.
+     */
+    rpc<const G extends MountedGroups>(prefix: MountPrefix<G>, groups: G, options?: RpcMountOptions): RpcMount<Callers<G>, Endpoints<G>>;
+}
+/** The options of `c.rpc`: the promise the mount makes its callers, `'unchecked'` by default. */
+export interface RpcMountOptions {
+    readonly compatibility?: 'backward' | 'unchecked';
+}
+/** The `imports` section the contract carries: the kit's imports, with `usedBy` from the endpoints' `connect`. */
+type ImportsSection<K extends KitTypes> = [keyof K['imports']] extends [never] ? unknown : {
+    readonly imports: {
+        readonly [N in keyof K['imports']]: ImportDeclaration;
+    };
+};
+/** The `tokens` section the contract carries: the kit's token purposes, as `defineApp`'s options declare them. */
+type TokensSection<K extends KitTypes> = [keyof K['tokens']] extends [never] ? unknown : {
+    readonly tokens: K['tokens'];
+};
+/** The contract `app.contract` returns: the same `Contract` the client, the compiler and the test kit read. */
+export type KitContract<K extends KitTypes, S extends Surface> = Contract<K['action'], K['dimension'], K['role'], K['dimensions'], S & ImportsSection<K> & TokensSection<K>>;
+/** The kit of one application: every builder is typed by its vocabulary, its tables and its imports. */
+export interface App<K extends KitTypes> {
+    /**
+     * Endpoints for `callers`, declared and handled together; `fabrika.contract.ts` mounts the group with `c.rpc`. A group
+     * of public procedures only (`access: { public: true }`), which anyone calls, names no callers: `app.group({}, …)`.
+     */
+    group<const C extends readonly RpcCaller[] = readonly [], const T extends GroupBuild = GroupBuild>(options: {
+        readonly callers?: C & NoInfer<SomeCallers<C>>;
+    } & Owned<'kind' | 'endpoints'>, build: (r: GroupKit<K, C[number]>) => T): Group<C, T>;
+    /** A job of the whole application (UTC, five fields) holding `actions`; the contract mounts it under `jobs`. */
+    cron<const Acts extends readonly [K['action'], ...K['action'][]], const S extends SqlMode = never, const U extends UnscopedDeclaration<K['tables'], UnscopedMode> = never, const Is extends string = never, const M extends JobMailer = never, const Ks extends readonly string[] = never, const Sg extends readonly string[] = never>(schedule: string, options: CronOptions<Acts, S, U, Is, K['index'], M, Ks, Sg, keyof K['tokens'] & string>): CronBuilder<K, Acts[number], Declared<S, U, never, Is, M>, Ks, Sg>;
+    /**
+     * A webhook whose deliveries `scheme` verifies, bound per value of `boundTo` or once for the application (`'app'`);
+     * the contract mounts it by name.
+     */
+    webhook<const B extends K['dimension'] | 'app', const Acts extends readonly [K['action'], ...K['action'][]], I extends InputSchema, const S extends SqlMode = never, const U extends UnscopedDeclaration<K['tables'], UnscopedMode> = never, const Ks extends readonly string[] = never, const Sg extends readonly string[] = never>(path: Path, options: WebhookOptions<B, Acts, I, S, U, K['index'], Ks, Sg, keyof K['tokens'] & string>): WebhookBuilder<K, B, Acts[number], I, Declared<S, U, never, never>, Ks, Sg>;
+    /** A share SPA under `prefix` and its procedures under `<prefix>/api`, for an anonymous key bound to one object. */
+    link<const LD extends K['dimension'], const G extends readonly [K['action'], ...K['action'][]], const IB extends K['action'], const T extends LinkTree>(prefix: Path, options: {
+        readonly spa: string;
+        readonly dimension: LD;
+        readonly grants: G;
+        readonly issuedBy: IB;
+        readonly maxDays: number;
+        readonly procedures: (l: LinkGroupKit<K, LD, G[number]>) => T;
+    } & Owned<'kind' | 'prefix'>): LinkMount<LD, G[number], IB, T>;
+    /** Read-only queries another application's connector calls; the contract mounts it under `exports`. */
+    export<const T extends ExportTree>(definition: {
+        readonly version: number;
+        readonly consumers: readonly [string, ...string[]];
+        readonly audience: 'any consumer user';
+        readonly procedures: (e: ExportKit<K>) => T;
+    } & Owned<'kind'>): Export<T>;
+    /**
+     * The contract: mounts by name and the `files`, `jobs`, `exports` and `csp` sections; `imports` and `tokens` come from
+     * the kit.
+     */
+    contract<const S extends Surface & Owned<'imports' | 'tokens'>>(build: (c: ContractKit<K>) => S): KitContract<K, S>;
+}
+/**
+ * The application's kit, built once in `src/app-kit.ts`: `defineApp(vocabulary, tables)`, plus the connectors it
+ * imports (`{ imports: { <name>: { snapshot, procedures, timeoutMs? } } }`). The tables' `DbIndex` is computed here,
+ * once, so each endpoint's `ctx.db` is a lookup.
+ *
+ * This signature is the kit's typed face over `RuntimeApp`, which builds plain declarations. The face answers types
+ * no implementation can return (`.handle`'s `ExactReturn`, `contract`'s `imports` section by the kit's imports), so
+ * the compiler relates the two nowhere else; `kit-runtime.test.ts` holds that each builder returns what its type says.
+ */
+export declare function defineApp<V extends AnyAppVocabulary>(vocabulary: V): App<KitOf<V, NoTablesIndex, Record<never, never>>>;
+export declare function defineApp<V extends AnyAppVocabulary, DB, P>(vocabulary: V, tables: Tables<DB, P>): App<KitOf<V, DbIndex<DB, P, V>, Record<never, never>>>;
+/**
+ * Options that may be absent are no overload, and neither is an option field that may be absent: the contract's type
+ * would promise an imports section, or token purposes, it may not have. Each overload requires the fields it infers.
+ */
+export declare function defineApp<V extends AnyAppVocabulary, DB, P, const Imp extends KitImports, const Tk extends TokenPurposes>(vocabulary: V, tables: Tables<DB, P>, options: {
+    readonly imports: Imp;
+    readonly tokens: Tk;
+}): App<KitOf<V, DbIndex<DB, P, V>, Imp, Tk>>;
+export declare function defineApp<V extends AnyAppVocabulary, DB, P, const Tk extends TokenPurposes>(vocabulary: V, tables: Tables<DB, P>, options: {
+    readonly tokens: Tk;
+}): App<KitOf<V, DbIndex<DB, P, V>, Record<never, never>, Tk>>;
+export declare function defineApp<V extends AnyAppVocabulary, DB, P, const Imp extends KitImports>(vocabulary: V, tables: Tables<DB, P>, options: {
+    readonly imports: Imp;
+}): App<KitOf<V, DbIndex<DB, P, V>, Imp>>;
+/** What `defineApp`'s options carry: the connectors the kit imports, and the purposes of the tokens it signs. */
+export interface KitOptions {
+    readonly imports?: KitImports;
+    /** `{ <purpose>: token(Claims, { maxDays }) }`: each kind of signed token, declared once. */
+    readonly tokens?: TokenPurposes;
+}
+/** One import of the kit as the contract records it: the snapshot's identity, the procedures called, the deadline. */
+export interface KitImportDeclaration {
+    readonly app: string;
+    readonly export: string;
+    readonly version: number;
+    readonly digest: string;
+    readonly procedures: readonly string[];
+    readonly timeoutMs?: number;
+}
+/**
+ * The contract's `imports` section: each import of the kit, used by the RPC endpoints that declare `connect` of it,
+ * in id order. The static reader builds it with this same function, so both read one `usedBy`.
+ */
+export declare function kitImportsSection(imports: Readonly<Record<string, KitImportDeclaration>>, surface: Surface): Record<string, ImportDeclaration>;
+export {};

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

@@ -0,0 +1,9 @@
+import { type AppSchema, type ContractArtifact } from '@fabrika/auth-core';
+/**
+ * The IAM vocabulary of a contract application, marked `contract` so IAM refuses every wildcard written for it: the
+ * dimensions as scopes with their container, creator role and members actions; the actions; the roles, a membership
+ * role with its scope and the roles that may assign it; the link mounts; the delegations; the workloads; and the locale,
+ * display name and e-mail wording IAM names the application with. Every artifact
+ * dimension is a scope, a file collection's `file:<name>` included, because access to a file is checked there.
+ */
+export declare function schemaFromContract(artifact: ContractArtifact): AppSchema;

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

@@ -0,0 +1,14 @@
+/** Every reason a contract does not compile, each with where it is and the allowed form. */
+export declare class ContractError extends Error {
+    readonly name = "ContractError";
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/** Collects problems so that one compile reports all of them, not the first. */
+export declare class Problems {
+    #private;
+    add(where: string, problem: string): void;
+    throwIfAny(): void;
+}
+/** A builder of the staged kit whose signature is fixed and whose runtime a later work unit of the sprint adds. */
+export declare function notImplemented(what: string, unit: string): never;

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

@@ -0,0 +1,25 @@
+import { z } from 'zod/v4';
+import type { Schema } from './define';
+declare const REDIRECT: unique symbol;
+/** What `redirect()` adds to the `{ to }` schema: the origins a target may name besides the application's own. */
+export interface RedirectMark {
+    readonly origins: readonly string[];
+}
+declare const Target: z.ZodObject<{
+    to: z.ZodString;
+}, z.core.$strict>;
+/** A redirect output: the handler returns `{ to }`, and the caller receives a 303 or a 302 there. */
+export type Redirect = typeof Target & RedirectBrand;
+/** What tells a redirect output from a JSON one in the types. */
+export interface RedirectBrand {
+    readonly [REDIRECT]: RedirectMark;
+}
+export interface RedirectOptions {
+    /** Exact `https://` origins a target may name, besides the application's own: `['https://shop.example']`. */
+    readonly origins?: readonly string[];
+}
+/** The output of a procedure that answers a redirect. `compileContract` and the checker refuse an origin it may not list. */
+export declare function redirect(options?: RedirectOptions): Redirect;
+/** The mark of a `redirect()` output, or `null` for any other schema. */
+export declare function redirectOf(schema: Schema): RedirectMark | null;
+export {};

package/types/src/contract/schema-from-shape.d.ts

@@ -0,0 +1,10 @@
+import type { SchemaShape } from '@fabrika/auth-core';
+import { z } from 'zod/v4';
+/** The zod schema that admits what `shape` describes; `describeSchema` reads it back into the same shape. */
+export declare function schemaFromShape(shape: SchemaShape): z.ZodType;
+/**
+ * The path of a validation issue as far as `shape` declares it: field names the schema names, `[]` for an array item,
+ * a tuple position, `{}` for a record value. Record keys and array indexes come from the value, which another
+ * application wrote, so they never reach a message or a log.
+ */
+export declare function declaredPath(shape: SchemaShape, path: readonly PropertyKey[]): string;

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

@@ -0,0 +1,5 @@
+import type { SchemaShape } from '@fabrika/auth-core';
+import { z } from 'zod/v4';
+import type { Problems } from './problems';
+/** A schema's shape, or `null` after recording why it has none. */
+export declare function describeSchema(schema: z.core.$ZodType, where: string, problems: Problems): SchemaShape | null;

package/types/src/contract/snapshot-source.d.ts

@@ -0,0 +1,15 @@
+import type { ExportDescription } from '@fabrika/auth-core';
+/** The directory, relative to the application root, that holds the vendored snapshots. */
+export declare const SNAPSHOT_DIRECTORY = "fabrika/connect";
+export interface SnapshotNames {
+    /** Relative to the application root: `fabrika/connect/catalog.products.v1.ts`. */
+    readonly file: string;
+    /** The snapshot const: `catalogProductsV1`. */
+    readonly snapshot: string;
+    /** The digest const the contract's import names: `catalogProductsV1Digest`. */
+    readonly digest: string;
+}
+/** The file and the identifiers of the snapshot of `app`'s export `name` at `version`. */
+export declare function snapshotNames(app: string, name: string, version: number): SnapshotNames;
+/** The snapshot module of `description`. Throws `ContractError` for a shape no zod source in the subset writes. */
+export declare function snapshotSource(description: ExportDescription): string;