@fabrika/app 0.4.8 → 0.5.0

package/skill/references/tests.md

@@ -284,6 +284,15 @@ if (postgres !== null) {
 - `kit.runJob('<job>')` runs a cron job once and answers `{ status: 'succeeded', attempts }`. A job's `ctx.links`
   reaches the kit's stand-in IAM under the job's own key, so a job that declares `issues` issues and revokes links in a
   plain `testKit` and under `fabrika app dev`, as IAM allows it: for its declared mount only.
+- A form or a mutation that declares `then` starts its job in the background of the call. `kit.drain()` waits for
+  those runs, and `kit.runJob` first waits for them; every generated access case drains before it answers. The kicked
+  run may start at once, so arm a fault before the call, never between the call and the run.
+- `kit.mail` is the stand-in for every job's mail transport (`MemoryEmailSender` of `@fabrika/app/testing`), so a test
+  needs no mail variable. `kit.mail.accepted` is what reached the inbox, once per key, and `kit.mail.handoffs` every
+  send with its `answer`. `refuse(code?)`, `unavailable()`, `unreachable()`, `loseAnswers(n)` and `during(hook)`
+  inject a failure until `heal()`. A message carries the key the transport got, `transportMailKey(kit.mailKeyScope,
+  key)`. Model a transport that does not deduplicate with `testKit(app, { mail: new MemoryEmailSender({ capabilities:
+  { idempotent: false, confirmation: 'queued' } }) })`. The test e-mail in `references/public-intake.md` is an example.
 - An application with files passes `files: new MemoryFileObjects()` (`@fabrika/platform/testing`) to `testKit`;
   without it the application does not boot. With `scan: true`, an upload stays `quarantined` until
   `kit.runJob(FILE_SCAN_JOB)` (`@fabrika/app/implement`) runs with a `scanner` passed to `testKit`: a `FileScanner`
@@ -294,7 +303,7 @@ if (postgres !== null) {
   a stand-in of your own receives the check (`hostname`, `action`) a passing answer must confirm as its second argument.
 - `testKit` takes no `deps`, and a test may not start a server (`Bun.serve` is `forbidden-global`). Stand in for an
   outbound dependency through its variables: `env` points it at a test URL, and `spyOn(globalThis, 'fetch')` answers
-  that URL only and passes every other request on (`src/__tests__/mail-stand-in.ts` in `references/public-intake.md`).
+  that URL only and passes every other request on to the real `fetch`.
 - `defineDeps(build)` runs at every boot, the generated tests' too, which set no application variable: read a variable
   where it is used, not in `build` (`references/public-intake.md`). A handler that calls an outbound dependency fails its
   generated cases with 500, so an endpoint they cover writes an outbox row a job sends (`references/endpoint.md`).

package/src/bun.ts

@@ -8,6 +8,8 @@
 import { HttpIamMembership } from '@fabrika/auth'
 import type { Database, PostgresOptions } from '@fabrika/db'
 import { isScopedDatabase } from '@fabrika/db/framework'
+import type { EmailProviderRegistry } from '@fabrika/email'
+import { directoryEmailProvider } from '@fabrika/email/directory'
 import { parseJwks } from '@fabrika/jwks'
 import type { FileObjectStore } from '@fabrika/platform'
 import { applicationRuntimeUrl, S3BlobStore } from '@fabrika/platform-node'
@@ -27,6 +29,9 @@ export { clamscanArguments, type ClamscanOptions, clamscanScanner } from './file
 
 export { markProductionProcess } from '@fabrika/db/production'
 
+/** The local stack's capture: boot honours it only under a loopback issuer, and the stack names it with `FABRIKA_EMAIL_PROVIDER`. */
+const LOCAL_EMAIL_PROVIDERS = { directory: directoryEmailProvider } satisfies EmailProviderRegistry
+
 export interface ManagedBunHandlerOptions {
 	/** Required sink for rejected background tasks. Do not log raw errors or secret-bearing values. */
 	onBackgroundError(error: unknown): void
@@ -125,6 +130,23 @@ async function loadDataLayer(): Promise<DataLayerOpeners> {
 	return { postgres: Database.postgres, applicationSchema }
 }
 
+/** How long a stopping process waits for the work its requests left running; a kicked run aborts at once. */
+const SHUTDOWN_DRAIN_MS = 10_000
+
+/** Waits for `drain`, at most `ms`; a drain the bound cuts short is logged. */
+async function drainWithin(drain: Promise<void>, ms: number): Promise<void> {
+	const expired = Promise.withResolvers<void>()
+	const timer = setTimeout(() => {
+		console.error(`fabrika: the shutdown drain ended after ${ms / 1000} s with background work still running`)
+		expired.resolve()
+	}, ms)
+	try {
+		await Promise.race([drain, expired.promise])
+	} finally {
+		clearTimeout(timer)
+	}
+}
+
 /** The provisioning credential the platform writes; only the launcher reads it, and the application's process never holds it. */
 const PROVISIONING_DATABASE_URL = 'FABRIKA_APP_DATABASE_URL'
 /** The runtime role's credential, which the launcher derives and hands the application's process in its place. */
@@ -371,9 +393,10 @@ async function startContractServer(
 		membership,
 		workloadTokens,
 		requireProxySecret: true,
+		localEmailProviders: LOCAL_EMAIL_PROVIDERS,
 		...(operationsFetch === undefined ? {} : { operationsFetch }),
 	})
-	// The work a request leaves running (a failure's report, a job a form kicked) is drained before the database closes.
+	// The work a request leaves running (a failure's report, a kicked run) is drained, within a bound, before the database closes.
 	const handler = createBunHandler({ fetch: (request, _env: undefined, exec) => served.fetch(request, exec) }, undefined, {
 		onBackgroundError: () => console.error('fabrika: a background task of a request failed'),
 	})
@@ -386,8 +409,9 @@ async function startContractServer(
 	}
 	const stop = async (): Promise<void> => {
 		clearInterval(checks)
+		served.stopKicks()
 		await server.stop(false)
-		await handler.drain()
+		await drainWithin(handler.drain(), SHUTDOWN_DRAIN_MS)
 		await database?.close()
 	}
 	process.once('SIGTERM', () => void stop().then(() => process.exit(0)))
@@ -439,6 +463,7 @@ export async function runContractJob(
 			membership,
 			workloadTokens,
 			requireProxySecret: true,
+			localEmailProviders: LOCAL_EMAIL_PROVIDERS,
 			// ClamAV on PATH, as the provider's build installs it for a `scan: true` collection; missing, the scan fails closed.
 			scanner: clamscanScanner(),
 		})

package/src/contract/artifact-schema.ts

@@ -8,6 +8,7 @@ import {
 	type ContractArtifact,
 	displayNameProblem,
 	type EndpointRow,
+	JOB_MAILERS,
 	LOCALES,
 	mailTemplateProblems,
 	type MessageKind,
@@ -294,6 +295,8 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
 		unscoped: record(z.enum(['read', 'write'])),
 		connect: names,
 		issues: nullableName,
+		then: name.optional(),
+		mailer: z.enum(JOB_MAILERS).optional(),
 	})).optional(),
 	directories: record(z.strictObject({ dimension: name, lists: z.boolean() })).optional(),
 	locale: z.enum(LOCALES).optional(),

package/src/contract/build.ts

@@ -29,8 +29,10 @@ import {
 	type ImportArtifact,
 	isLocale,
 	isMessageKind,
+	JOB_MAILERS,
 	JOB_SITE_PREFIX,
 	type JobArtifact,
+	type JobMailer,
 	type Locale,
 	LOCALES,
 	type MailTemplate,
@@ -113,7 +115,8 @@ const AUDIENCE = 'any consumer user'
 const IMPORT_FIELDS = ['app', 'export', 'version', 'digest', 'procedures', 'usedBy', 'timeoutMs']
 /** Tables the framework keeps in the application's schema; no site reaches them unscoped. */
 const FRAMEWORK_TABLE_PREFIX = 'fabrika_'
-const DECLARED_ALLOWED = "sql: 'read' | 'write', unscoped: { <table>: 'read' | 'write' }, connect: ['<import>'], issues: '<link mount>'"
+const DECLARED_ALLOWED =
+	"sql: 'read' | 'write', unscoped: { <table>: 'read' | 'write' }, connect: ['<import>'], issues: '<link mount>', then: '<cron job>', mailer: 'installation' | 'own'"
 const CSP_FIELDS = ['connectSrc', 'imgSrc', 'frameAncestors', 'scriptSrc', 'frameSrc', 'styleSrc', 'fontSrc']
 /** An environment variable an application reads; a form's challenge names its secret by one. */
 const APPLICATION_VARIABLE = /^[A-Z][A-Z0-9_]*$/
@@ -530,7 +533,7 @@ class ArtifactBuilder {
 					path: mount.path,
 					appendTo: mount.appendTo,
 					...this.#formAdmission(name, where, mount),
-					...(mount.then === undefined ? {} : { then: this.#formJob(where, mount.then) }),
+					...(mount.then === undefined ? {} : { then: this.#kickedJob(where, mount.then) }),
 				}
 			case 'webhook': {
 				this.#prefix(where, mount.path)
@@ -555,8 +558,8 @@ class ArtifactBuilder {
 		}
 	}
 
-	/** The job a form kicks: a cron job of this contract. */
-	#formJob(where: string, then: string): string {
+	/** The job a form or a mutation kicks: a cron job of this contract. */
+	#kickedJob(where: string, then: string): string {
 		const jobs = this.#contract.jobs
 		const job: { readonly kind: string } | undefined = Object.hasOwn(jobs, then) ? jobs[then] : undefined
 		if (job === undefined) {
@@ -1467,6 +1470,8 @@ class ArtifactBuilder {
 				this.#problem(where, `'${key}' is not a declared field (allowed: ${DECLARED_ALLOWED})`)
 			}
 		}
+		const then = this.#then(where, value['then'], place)
+		const mailer = this.#mailer(where, value['mailer'], place)
 		const reach: DeclaredReach = {
 			sql: this.#sqlMode(where, value['sql'], place.readOnly),
 			unscoped: this.#unscoped(where, value['unscoped'], place.readOnly),
@@ -1476,6 +1481,8 @@ class ArtifactBuilder {
 				: place.kind === 'job'
 				? this.#jobIssues(where, value['issues'], place.actions)
 				: null,
+			...(then === undefined ? {} : { then }),
+			...(mailer === undefined ? {} : { mailer }),
 		}
 		if (place.kind !== 'rpc') {
 			this.#rpcOnly(where, 'connect', value['connect'])
@@ -1483,7 +1490,10 @@ class ArtifactBuilder {
 		if (place.kind !== 'rpc' && place.kind !== 'job' && value['issues'] !== undefined) {
 			this.#problem(where, 'declares issues, which only an endpoint of an RPC mount or a cron job declares')
 		}
-		if (reach.sql !== null || Object.keys(reach.unscoped).length > 0 || reach.connect.length > 0 || reach.issues !== null) {
+		if (
+			reach.sql !== null || Object.keys(reach.unscoped).length > 0 || reach.connect.length > 0 || reach.issues !== null || reach.then !== undefined
+			|| reach.mailer !== undefined
+		) {
 			this.#declared[site] = reach
 		}
 	}
@@ -1611,6 +1621,42 @@ class ArtifactBuilder {
 		return name
 	}
 
+	/** The cron job a mutation kicks once its transaction committed; `undefined` when it declares none or after a problem. */
+	#then(where: string, value: unknown, place: DeclaringSite): string | undefined {
+		if (value === undefined) {
+			return undefined
+		}
+		if (place.kind !== 'rpc' && place.kind !== 'link') {
+			this.#problem(where, 'declares then, which only a mutation of an RPC or link mount declares')
+			return undefined
+		}
+		if (place.readOnly) {
+			this.#problem(where, 'declares then, and it runs read-only (allowed: then on a mutation)')
+			return undefined
+		}
+		if (typeof value !== 'string') {
+			this.#problem(where, "then is not a job's name (allowed: then: '<cron job>')")
+			return undefined
+		}
+		return this.#kickedJob(where, value)
+	}
+
+	/** The mail transport a cron job reaches; `undefined` when it declares none or after a problem. */
+	#mailer(where: string, value: unknown, place: DeclaringSite): JobMailer | undefined {
+		if (value === undefined) {
+			return undefined
+		}
+		if (place.kind !== 'job') {
+			this.#problem(where, 'declares mailer, which only a cron job declares')
+			return undefined
+		}
+		const mailer = JOB_MAILERS.find((transport) => transport === value)
+		if (mailer === undefined) {
+			this.#problem(where, `mailer ${JSON.stringify(value)} is not a transport (allowed: mailer: 'installation' or 'own')`)
+		}
+		return mailer
+	}
+
 	/** `connect` calls another application on behalf of a person, so only an RPC endpoint declares it. */
 	#rpcOnly(where: string, field: 'connect', value: unknown): void {
 		if (value !== undefined) {

package/src/contract/context.ts

@@ -2,7 +2,7 @@
 // is typed by the kit (vocabulary, `DbIndex`, imports) and the site's own declaration, never by the contract value,
 // so a group in any module types itself without importing `fabrika.contract.ts`.
 
-import type { RpcCaller } from '@fabrika/auth-core'
+import type { JobMailer, RpcCaller } from '@fabrika/auth-core'
 import type {
 	AnyDbIndex,
 	ApplicationTables,
@@ -24,7 +24,7 @@ import type { ApplicationDirectory, LinkIssuing, MemberDirectory, MemberLookup,
 import type { AppPrincipal, PrincipalOf, ServicePrincipal } from '../implement/principal'
 import type { ConnectCall, RequestContext } from '../implement/types'
 import type { WebhookDelivery, WebhookPrincipal } from '../implement/webhook'
-import type { JobContext } from '../jobs/types'
+import type { AppMail, JobContext } from '../jobs/types'
 import type { ConnectSnapshot } from './connect'
 import type { MemberAccess, Schema } from './define'
 import type { App } from './kit'
@@ -86,15 +86,17 @@ export type SqlMode = 'read' | 'write'
  * The off-road reach a site declares: part of the contract, read by Control, a review signal for the approver. A
  * field the site does not declare is absent.
  */
-export interface Declared<S extends SqlMode, U, Cn extends readonly string[], Is extends string> {
+export interface Declared<S extends SqlMode, U, Cn extends readonly string[], Is extends string, M extends JobMailer = never> {
 	readonly sql?: S
 	readonly unscoped?: U
 	readonly connect?: Cn
 	readonly issues?: Is
+	readonly mailer?: M
 }
 
 /** One declared field, `never` when the site leaves it out. */
-type Of<D, F extends keyof Declared<SqlMode, unknown, readonly string[], string>> = D extends { readonly [P in F]?: infer V } ? Exclude<V, undefined>
+type Of<D, F extends keyof Declared<SqlMode, unknown, readonly string[], string, JobMailer>> = D extends { readonly [P in F]?: infer V }
+	? Exclude<V, undefined>
 	: never
 
 export type SqlValue = string | number | boolean | bigint | Date | null | readonly (string | number)[]
@@ -347,6 +349,7 @@ export type EndpointContext<
 	& SqlContext<Of<D, 'sql'>, K['index']>
 	& FilesContext<K['index'], Kind>
 	& { readonly db: DataOf<K['index'], EndpointData<K['index'], Kind, Acc, Of<D, 'unscoped'>>> }
+	& NoMail
 
 /** A link procedure acts on the one object its key is bound to. */
 export type LinkContext<
@@ -363,6 +366,7 @@ export type LinkContext<
 	& {
 		readonly db: DataOf<K['index'], EndpointData<K['index'], Kind, { readonly action: A; readonly on: LD; readonly from: string }, Of<D, 'unscoped'>>>
 	}
+	& NoMail
 
 /** An export procedure runs read-only, for a consumer application: its capability and data, nothing that writes. */
 export type ExportContext<K extends KitTypes, Acc, D extends Declared<'read', unknown, never, never>> =
@@ -370,6 +374,7 @@ export type ExportContext<K extends KitTypes, Acc, D extends Declared<'read', un
 	& CapabilityContext<Acc>
 	& SqlContext<Of<D, 'sql'>, K['index']>
 	& { readonly db: DataOf<K['index'], EndpointData<K['index'], 'query', Acc, Of<D, 'unscoped'>>> }
+	& NoMail
 
 /**
  * A capability a job or webhook minted or received, of one of its declared actions `Acts`, bound to the same handles
@@ -387,7 +392,7 @@ type SiteData<Ix extends AnyDbIndex, Kind extends DataKind, Acts extends string,
 	& UnscopedData<Ix, U, Kind>
 
 /** The fenced transaction of a job attempt: writes and `tx.sql` commit only while the attempt holds its lease. */
-export type JobTransaction<K extends KitTypes, A extends string, D extends Declared<SqlMode, unknown, never, string>> =
+export type JobTransaction<K extends KitTypes, A extends string, D extends Declared<SqlMode, unknown, never, string, JobMailer>> =
 	& { readonly db: SiteData<K['index'], 'mutation', A, Of<D, 'unscoped'>> }
 	& SqlContext<Of<D, 'sql'>, K['index']>
 	& FilesContext<K['index'], 'mutation'>
@@ -400,13 +405,22 @@ type JobLinksContext<Dim extends string, A extends string, Is extends string> =
 	? { readonly links: Unavailable<"declare issues: '<link mount>' on this job to issue its share links"> }
 	: { readonly links: LinkIssuing<Dim, A, Is> }
 
+/** `ctx.mail` of a cron job that declares the transport it sends through (`mailer: 'installation' | 'own'`). */
+type JobMailContext<M extends JobMailer> = [M] extends [never]
+	? { readonly mail: Unavailable<"declare mailer: 'installation' or 'own' on this job to send mail"> }
+	: { readonly mail: AppMail }
+
+/** A send is external I/O that never rolls back, so only a job sends, from the outbox row an endpoint wrote. */
+type NoMail = { readonly mail: Unavailable<"an endpoint sends no mail: write an outbox row and kick a job that declares mailer (then: '<job>')"> }
+
 /** What a cron job's handler receives. Its reads run outside the transaction; every write runs in `ctx.transaction`. */
-export type JobKitContext<K extends KitTypes, A extends string, D extends Declared<SqlMode, unknown, never, string>> =
+export type JobKitContext<K extends KitTypes, A extends string, D extends Declared<SqlMode, unknown, never, string, JobMailer>> =
 	& JobContext<A, K['dimension']>
 	& { readonly db: SiteData<K['index'], 'job', A, Of<D, 'unscoped'>> }
 	& { readonly sql: Unavailable<'a job runs ctx.sql inside ctx.transaction((tx) => …), as tx.sql'> }
 	& FilesContext<K['index'], 'job'>
 	& JobLinksContext<K['dimension'], A, Of<D, 'issues'>>
+	& JobMailContext<Of<D, 'mailer'>>
 	& { transaction<R>(work: (tx: JobTransaction<K, A, D>) => Promise<R>): Promise<R> }
 
 /** What a webhook delivery's handler receives: one transaction per delivery, idempotent by `ctx.delivery.key`. */
@@ -415,6 +429,7 @@ export type WebhookKitContext<K extends KitTypes, B extends string, Acts extends
 	& { readonly refs: { readonly [A in Acts]: Ref<B, A> }; readonly delivery: WebhookDelivery }
 	& SqlContext<Of<D, 'sql'>, K['index']>
 	& { readonly db: SiteData<K['index'], 'mutation', Acts, Of<D, 'unscoped'>> }
+	& NoMail
 
 type IndexOf<A> = A extends App<infer K> ? K['index'] : never
 

package/src/contract/declaration.ts

@@ -69,7 +69,7 @@ export function unknownOptions(options: object, builder: Builder): string[] {
  * The off-road fields a site of the staged kit declares beside its builder's options. The kit copies them into
  * `declared`; `buildArtifact` checks which of them the site may carry.
  */
-export const DECLARED_FIELDS = ['sql', 'unscoped', 'connect', 'issues'] as const
+export const DECLARED_FIELDS = ['sql', 'unscoped', 'connect', 'issues', 'then', 'mailer'] as const
 
 /** The keys of a kit site's `options` that are neither `builder`'s option fields nor a declared field. */
 export function kitUnknownOptions(options: object, builder: Builder): string[] {
@@ -77,7 +77,7 @@ export function kitUnknownOptions(options: object, builder: Builder): string[] {
 }
 
 /**
- * The reach a site of the staged kit declares, as written (`sql`, `unscoped`, `connect`, `issues`): only the fields
+ * The reach a site of the staged kit declares, as written (`sql`, `unscoped`, `connect`, `issues`, `then`, `mailer`): only the fields
  * its options carry. Unchecked here: the static reader copies what the source holds, and `buildArtifact` parses it.
  */
 export interface DeclaredDeclaration {
@@ -85,6 +85,8 @@ export interface DeclaredDeclaration {
 	readonly unscoped?: unknown
 	readonly connect?: unknown
 	readonly issues?: unknown
+	readonly then?: unknown
+	readonly mailer?: unknown
 }
 
 /** The declared fields of a kit site's options, each one only when the options carry it. */
@@ -94,6 +96,8 @@ export function declaredOf(options: DeclaredDeclaration): DeclaredDeclaration {
 		...(options.unscoped === undefined ? {} : { unscoped: options.unscoped }),
 		...(options.connect === undefined ? {} : { connect: options.connect }),
 		...(options.issues === undefined ? {} : { issues: options.issues }),
+		...(options.then === undefined ? {} : { then: options.then }),
+		...(options.mailer === undefined ? {} : { mailer: options.mailer }),
 	}
 }
 

package/src/contract/group.ts

@@ -55,6 +55,22 @@ type OneLiteral<Is> = string extends Is ? Unavailable<"issues names one link mou
 	: true extends IsUnion<Is> ? Unavailable<"issues names one link mount, as a literal: issues: 'shared'">
 	: unknown
 
+/** `then` names one cron job, as a literal. */
+type OneJob<Th> = string extends Th ? Unavailable<"then names one cron job, as a literal: then: 'mailing'">
+	: true extends IsUnion<Th> ? Unavailable<"then names one cron job, as a literal: then: 'mailing'">
+	: unknown
+
+/** A mutation's `then`, inferred from its optional field and then required, like a declared field. */
+type KickField<Th> =
+	& {
+		/** The cron job this mutation kicks once its transaction committed; the schedule stays its recovery. */
+		readonly then?: Th
+	}
+	& ([Th] extends [never] ? unknown : { readonly then: Th & NoInfer<OneJob<Th>> })
+
+/** A query writes nothing, so it has nothing to kick a job for. */
+type NoKick = { readonly then?: Unavailable<'a query kicks no job: declare then on a mutation'> }
+
 type IsUnion<T, All = T> = T extends unknown ? ([All] extends [T] ? false : true) : never
 
 /** An endpoint's declaration: its schemas, its access form and the reach it declares. */
@@ -147,7 +163,7 @@ export interface GroupKit<K extends KitTypes, Caller extends RpcCaller> {
 		const Cn extends readonly ImportOf<K>[] = never,
 		const Is extends string = never,
 	>(
-		def: EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']>,
+		def: EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']> & NoKick,
 	): EndpointBuilder<
 		'query',
 		I,
@@ -164,8 +180,9 @@ export interface GroupKit<K extends KitTypes, Caller extends RpcCaller> {
 		const U extends UnscopedDeclaration<K['tables'], UnscopedMode> = never,
 		const Cn extends readonly ImportOf<K>[] = never,
 		const Is extends string = never,
+		const Th extends string = never,
 	>(
-		def: EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']>,
+		def: EndpointDef<I, O, Acc, S, U, Cn, Is, K['index']> & KickField<Th>,
 	): EndpointBuilder<
 		'mutation',
 		I,
@@ -226,7 +243,7 @@ export interface LinkGroupKit<K extends KitTypes, LD extends string, G extends s
 		const S extends 'read' = never,
 		const U extends UnscopedDeclaration<K['tables'], 'read'> = never,
 	>(
-		def: EndpointDef<I, O, Acc, S, U, never, never, K['index']>,
+		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>>>
 	mutation<
 		const Acc extends LinkAccess<G>,
@@ -234,8 +251,9 @@ export interface LinkGroupKit<K extends KitTypes, LD extends string, G extends s
 		I extends InputSchema | null = null,
 		const S extends SqlMode = never,
 		const U extends UnscopedDeclaration<K['tables'], UnscopedMode> = never,
+		const Th extends string = never,
 	>(
-		def: EndpointDef<I, O, Acc, S, U, never, never, K['index']>,
+		def: EndpointDef<I, O, Acc, S, U, never, never, K['index']> & KickField<Th>,
 	): EndpointBuilder<'mutation', I, O, Acc, Declared<S, U, never, never>, LinkContext<K, 'mutation', LD, Acc['action'], Declared<S, U, never, never>>>
 }
 

package/src/contract/kit.ts

@@ -3,7 +3,7 @@
 // handlers beside their endpoints, in any module, type-check without a cycle. Browser-safe: it builds plain data and
 // holds each handler beside its site (`handled.ts`), never calling one.
 
-import type { RpcCaller } from '@fabrika/auth-core'
+import type { JobMailer, RpcCaller } 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, KitImports, KitTypes, NoTablesIndex, SqlMode, WebhookKitContext } from './context'
@@ -73,10 +73,19 @@ export type KitOf<V, Ix, Imp extends KitImports> = V extends AppVocabulary<infer
 	}
 	: never
 
-export type CronOptions<Acts, Sc, S, U, Is, Ix extends AnyDbIndex> =
+export type CronOptions<Acts, Sc, S, U, Is, Ix extends AnyDbIndex, M = never> =
 	& Owned<'kind' | 'schedule'>
 	& { readonly actions: Acts; readonly scope: Sc; readonly timeout?: string; readonly retries?: number }
 	& DeclaredFields<S, U, never, Is, Ix>
+	& MailerField<M>
+
+/** 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, Sc extends string, D> extends CronJob<Acts, Sc> {
@@ -84,7 +93,12 @@ export interface KitCronJob<Acts extends string, Sc extends string, D> extends C
 }
 
 /** A cron job before `.handle`: the contract's `jobs` refuses it. */
-export interface CronBuilder<K extends KitTypes, Acts extends string, Sc extends string, D extends Declared<SqlMode, unknown, never, string>> {
+export interface CronBuilder<
+	K extends KitTypes,
+	Acts extends string,
+	Sc extends string,
+	D extends Declared<SqlMode, unknown, never, string, JobMailer>,
+> {
 	handle(handler: (args: { readonly ctx: JobKitContext<K, Acts, D> }) => void | Promise<void>): KitCronJob<Acts, Sc, D>
 }
 
@@ -234,7 +248,8 @@ export interface App<K extends KitTypes> {
 		const S extends SqlMode = never,
 		const U extends UnscopedDeclaration<K['tables'], UnscopedMode> = never,
 		const Is extends string = never,
-	>(schedule: string, options: CronOptions<Acts, Sc, S, U, Is, K['index']>): CronBuilder<K, Acts[number], Sc, Declared<S, U, never, Is>>
+		const M extends JobMailer = never,
+	>(schedule: string, options: CronOptions<Acts, Sc, S, U, Is, K['index'], M>): CronBuilder<K, Acts[number], Sc, Declared<S, U, never, Is, M>>
 	/** A GitHub webhook bound per value of `boundTo`; the contract mounts it by name. */
 	webhook<
 		const B extends K['dimension'],

package/src/implement/boot.ts

@@ -18,6 +18,7 @@ import {
 	FABRIKA_PROXY_SECRET,
 	type FormMountArtifact,
 	type IamMembershipRpc,
+	isLoopbackHost,
 	type Jwks,
 	parseAppEnvironmentId,
 } from '@fabrika/auth-core'
@@ -33,6 +34,8 @@ import {
 	type WebhookTables,
 } from '@fabrika/db/framework'
 import type { DataKind } from '@fabrika/db/tables'
+import type { EmailProviderRegistry } from '@fabrika/email'
+import { builtinEmailProviders } from '@fabrika/email/providers'
 import { TokenVerifier } from '@fabrika/jwks'
 import type { FileObjectStore } from '@fabrika/platform'
 import { compileContract } from '../contract/compile'
@@ -44,6 +47,7 @@ import { kitOriginOf } from '../contract/handled'
 import type { RequestExecutionContext } from '../fetch'
 import { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE, FILE_SWEEP_TIMEOUT_MS, fileCollections } from '../files/collections'
 import { FILE_SCAN_JOB, FILE_SCAN_SCHEDULE, type FileScanner, SCAN_LIMITS } from '../files/scan'
+import { type MailStandIn, resolveMailTransports } from '../jobs/mail'
 import { logReporter, type OperationsReporter, operationsReporter, operationsSettings, type ReportSource } from '../jobs/report'
 import { bindJobs, type ContractJobs, type HandlerErrorSink } from '../jobs/runner'
 import { environmentScrubber } from '../jobs/scrub'
@@ -127,6 +131,18 @@ export interface BootOptions {
 	 * application withholds because it may carry a credential.
 	 */
 	readonly revealHandlerErrors?: HandlerErrorSink
+	/** The providers `FABRIKA_EMAIL_PROVIDER` may name for the jobs that declare `mailer: 'installation'`; the built-in ones by default. */
+	readonly emailProviders?: EmailProviderRegistry
+	/**
+	 * Providers added to `emailProviders` only in a local composition (a loopback `FABRIKA_IAM_ISSUER`); anywhere else
+	 * `FABRIKA_EMAIL_PROVIDER` naming one is refused like any unknown provider. On a name both hold, `emailProviders` wins.
+	 */
+	readonly localEmailProviders?: EmailProviderRegistry
+	/**
+	 * The test kit's stand-in for every mailer job, or `'none'` for an installation without mail; boot then reads neither
+	 * `FABRIKA_EMAIL_*` nor `serve`'s `mail`.
+	 */
+	readonly mailStandIn?: MailStandIn
 }
 
 export interface ContractApp {
@@ -134,6 +150,8 @@ export interface ContractApp {
 	fetch(request: Request, exec?: RequestExecutionContext): Promise<Response>
 	/** The contract's `c.cron` jobs; `fabrika job run <name>` runs one. */
 	readonly jobs: ContractJobs
+	/** Aborts every kicked run in flight; a later kick starts none; the schedule recovers their work. */
+	stopKicks(): void
 }
 
 /** Everything that stops a contract application from starting, with where it is and what to do. */
@@ -628,6 +646,19 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 		dsn: operations === null ? null : (options.environment.framework['FABRIKA_OPERATIONS_DSN'] ?? '').trim(),
 		release: options.environment.framework['FABRIKA_RELEASE']?.trim() || null,
 	}, problems)
+	// A token of a deployed IAM never carries a loopback issuer, so a deployed application is never local.
+	const local = variables.issuer !== '' && isLoopbackHost(new URL(variables.issuer).hostname)
+	const providers = options.emailProviders ?? builtinEmailProviders
+	const mail = resolveMailTransports({
+		artifact,
+		framework: options.environment.framework,
+		application: options.environment.application,
+		own: app.mail,
+		standIn: options.mailStandIn,
+		registry: local ? { ...options.localEmailProviders, ...providers } : providers,
+		keyScope: { issuer: variables.issuer, appId: variables.iamAppId },
+		local,
+	}, problems)
 	if (problems.length > 0) {
 		throw new BootError(problems)
 	}
@@ -682,6 +713,7 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 						facilities: siteFacilities(facilitiesOf(artifact, row), bound.declaration),
 						connect: siteConnect(connect.get(id), bound.declaration),
 						site: servedSite(procedure.type, bound),
+						...(bound.declaration?.then == null ? {} : { then: bound.declaration.then }),
 					})
 				}
 			}
@@ -746,6 +778,7 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 		capabilities: issuer.authority,
 		containers,
 		...(options.revealHandlerErrors === undefined ? {} : { revealHandlerErrors: options.revealHandlerErrors }),
+		mail,
 	}, problems)
 	for (const id of jobs.declared) {
 		declared.add(id)
@@ -822,5 +855,9 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 		kick: jobs.kick,
 		actions: Object.freeze(Object.keys(artifact.actions).sort()),
 	})
-	return Object.freeze({ fetch: (request: Request, exec?: RequestExecutionContext) => runtime.fetch(request, exec), jobs: jobs.jobs })
+	return Object.freeze({
+		fetch: (request: Request, exec?: RequestExecutionContext) => runtime.fetch(request, exec),
+		jobs: jobs.jobs,
+		stopKicks: jobs.stopKicks,
+	})
 }

package/src/implement/dispatch.ts

@@ -120,6 +120,8 @@ export type ServedEndpoint =
 		readonly connect?: readonly ImportWire[]
 		/** A staged-kit site, which gets `ctx.db`; a handler `implement` bound has none. */
 		readonly site?: ServedSite
+		/** The cron job this mutation kicks once its transaction committed; absent without `then`. */
+		readonly then?: string
 	}
 	/** What an export's consumer vendors, behind the export's own callers. */
 	| { readonly kind: 'description'; readonly row: CredentialedEndpoint; readonly description: ExportDescription }
@@ -302,7 +304,7 @@ export class ContractRuntime {
 					}
 					return await withBootstrap(await this.#asset(served, request), served.prefix)
 				case 'procedure':
-					return await this.#procedure(served, request)
+					return await this.#procedure(served, request, exec)
 				case 'file':
 					return await this.#file(served, request, plan.params)
 				case 'form':
@@ -438,9 +440,14 @@ export class ContractRuntime {
 	/**
 	 * A staged-kit site runs in one transaction: its statements commit after the handler returned, the output passed
 	 * validation and an attachment was encoded, and roll back on a throw, a refused output, a file over its limit or a
-	 * cancelled request. So an audited export keeps its log row only when its file goes out.
+	 * cancelled request. So an audited export keeps its log row only when its file goes out. Only after that commit does
+	 * `then` kick its job, which the answer neither waits for nor depends on.
 	 */
-	async #procedure(served: Extract<ServedEndpoint, { kind: 'procedure' }>, request: Request): Promise<Response> {
+	async #procedure(
+		served: Extract<ServedEndpoint, { kind: 'procedure' }>,
+		request: Request,
+		exec: RequestExecutionContext | undefined,
+	): Promise<Response> {
 		const caller = await this.#authorize(served.row, request)
 		const input = await readInput(served, request)
 		const frame = new RequestFrame(crypto.randomUUID(), { readOnly: served.readOnly === true, endpoint: served.row.id })
@@ -476,6 +483,11 @@ export class ContractRuntime {
 			}
 			const answer = this.#answerOf(served, result)
 			await invocation?.commit(signal)
+			if (served.then !== undefined) {
+				// Without an execution context the kick runs detached; it never rejects.
+				const kicked = this.#parts.kick(served.then)
+				exec?.waitUntil(kicked)
+			}
 			return answer
 		} finally {
 			await invocation?.rollback()

package/src/implement/implement.ts

@@ -4,6 +4,7 @@
 import type { TablePolicyArtifact } from '@fabrika/auth-core'
 import type { DataLayer } from '@fabrika/db'
 import type { CapabilityAuthority } from '@fabrika/db/capability'
+import type { EmailSender } from '@fabrika/email'
 import type { ConnectSnapshot } from '../contract/connect'
 import type { AnyContract } from '../contract/define'
 import type { ConnectSnapshots, ExactHandlers, HandlersOf } from './types'
@@ -41,6 +42,8 @@ export interface ContractImplementation<C extends AnyContract = AnyContract> {
 	readonly connect?: Readonly<Record<string, ConnectSnapshot>>
 	/** Runs `deps`, then `handlers` over its result. The tree is checked by the types of `implement`, and again by `boot`. */
 	readonly handlers: (env: ApplicationEnvironment, runtime: DepsRuntime) => unknown
+	/** The application's own transport, built once at boot from its own variables; `null` when they configure none. */
+	readonly mail?: (env: ApplicationEnvironment) => EmailSender | null
 }
 
 /**