@fabrika/app 0.5.5 → 0.7.0

package/src/jobs/mail.ts

@@ -1,23 +1,29 @@
-// `ctx.mail` of a job that declares `mailer`, over the transport `boot` resolved: the installation's (`FABRIKA_EMAIL_*`),
-// the application's own (`serve(contract, { mail })`) or the test kit's stand-in. An installation without a transport
-// says so (`FABRIKA_EMAIL_PROVIDER=none`): its jobs get `ctx.mail` that is not available, and each send waits for one.
-// Each key carries the prefix of the installation and the application environment, so senders on one provider account
-// never share a key. Nothing here logs a message or a key.
+// `ctx.mail` of a job that declares `mailer`, over the transport `boot` resolved: the installation's (`FABRIKA_EMAIL_*`,
+// or the platform's relay under `FABRIKA_EMAIL_PROVIDER=platform`), the application's own (`serve(contract, { mail })`)
+// or the test kit's stand-in. An installation without a transport says so (`FABRIKA_EMAIL_PROVIDER=none`): its jobs get
+// `ctx.mail` that is not available, and each send waits for one. Each key carries the prefix of the installation and the
+// application environment, so senders on one provider account never share a key. Nothing here logs a message or a key.
 
-import { type ContractArtifact, JOB_SITE_PREFIX, type JobMailer, sha256Hex } from '@fabrika/auth-core'
+import { type ContractArtifact, JOB_SITE_PREFIX, type JobMailer, platformTransportVariables, sha256Hex } from '@fabrika/auth-core'
 import {
 	EMAIL_PROVIDER_VARIABLE,
+	type EmailAttachment,
 	EmailDeliveryError,
 	type EmailDeliveryResult,
 	type EmailMessage,
 	type EmailProviderRegistry,
 	type EmailSender,
 	emailSenderFromEnv,
+	MAX_EMAIL_ATTACHMENTS,
 	mayRetryDelivery,
 	NO_EMAIL_PROVIDER,
 	pickEmailEnvironment,
 } from '@fabrika/email'
+import { PLATFORM_EMAIL_PROVIDER, PlatformEmailSender } from '@fabrika/email/platform'
 import { z } from 'zod/v4'
+import { HttpError } from '../errors'
+import type { OpenedFile } from '../files/handle'
+import { platformCall } from '../implement/egress'
 import type { ApplicationEnvironment } from '../implement/implement'
 import type { AppMail, AppMailMessage } from './types'
 
@@ -72,10 +78,12 @@ export interface JobMailInput {
 	readonly signal: AbortSignal
 	/** Throws once the attempt has ended. */
 	readonly assertLive: () => void
+	/** `ctx.files.open` of the attempt: the bytes of a live file whose reference it holds, at most `maxBytes`. */
+	readonly open: (file: unknown, options: { readonly maxBytes: number }) => Promise<OpenedFile>
 }
 
 export function jobMail(input: JobMailInput): AppMail {
-	const { transport: { sender, available }, keyPrefix, signal: attempt, assertLive } = input
+	const { transport: { sender, available }, keyPrefix, signal: attempt, assertLive, open } = input
 	return Object.freeze({
 		available,
 		capabilities: sender.capabilities,
@@ -85,6 +93,8 @@ export function jobMail(input: JobMailInput): AppMail {
 			if (typeof key !== 'string' || !APP_MAIL_KEY.test(key)) {
 				throw new EmailDeliveryError(`Email idempotency key is not 1..${MAX_APP_MAIL_KEY_LENGTH} visible ASCII characters`, { code: 'invalid_message' })
 			}
+			// Without a transport the send fails `mail_not_configured` below, and no file is read for it.
+			const attachments = available ? await readAttachments(message.attachments ?? [], sender.capabilities.maxAttachmentBytes, open) : []
 			const transported: EmailMessage = {
 				to: message.to,
 				subject: message.subject,
@@ -93,9 +103,12 @@ export function jobMail(input: JobMailInput): AppMail {
 				idempotencyKey: `${keyPrefix}${key}`,
 				...(message.replyTo === undefined ? {} : { replyTo: message.replyTo }),
 				...(message.fromName === undefined ? {} : { fromName: message.fromName }),
+				...(message.unsubscribe === undefined ? {} : { unsubscribeUrl: message.unsubscribe.url }),
+				...(attachments.length === 0 ? {} : { attachments }),
 			}
 			try {
-				return await sender.send(transported, signal === undefined ? attempt : AbortSignal.any([attempt, signal]))
+				// The transport's request is the platform's, which the job's egress does not cover.
+				return await platformCall(() => sender.send(transported, signal === undefined ? attempt : AbortSignal.any([attempt, signal])))
 			} catch (error) {
 				if (error instanceof EmailDeliveryError) {
 					throw error
@@ -108,6 +121,52 @@ export function jobMail(input: JobMailInput): AppMail {
 	})
 }
 
+/**
+ * The bytes of each file of `files`, read through `ctx.files.open` (which refuses a file that is not live, or whose
+ * reference the attempt does not hold) and bounded together by the transport's limit.
+ */
+async function readAttachments(
+	files: readonly unknown[],
+	maxBytes: number | undefined,
+	open: JobMailInput['open'],
+): Promise<readonly EmailAttachment[]> {
+	if (files.length === 0) {
+		return []
+	}
+	if (maxBytes === undefined) {
+		throw new EmailDeliveryError('This mail transport sends no attachments', { code: 'invalid_message' })
+	}
+	if (files.length > MAX_EMAIL_ATTACHMENTS) {
+		throw new EmailDeliveryError(`Email has more than ${MAX_EMAIL_ATTACHMENTS} attachments`, { code: 'invalid_message' })
+	}
+	const attachments: EmailAttachment[] = []
+	let remaining = maxBytes
+	for (const file of files) {
+		const opened = await open(file, { maxBytes: remaining }).catch((error: unknown) => {
+			if (error instanceof HttpError && error.type === 'too_large') {
+				throw new EmailDeliveryError(`Email attachments have more than the ${maxBytes} bytes this transport sends`, { code: 'invalid_message' })
+			}
+			throw error
+		})
+		remaining -= opened.size
+		attachments.push({ filename: attachmentName(opened), contentType: opened.type, content: opened.bytes })
+	}
+	return attachments
+}
+
+const MAX_ATTACHMENT_NAME_LENGTH = 255
+
+/** The uploader's name with no path separator or quote, which every transport quotes; `attachment` without one. */
+function attachmentName(file: OpenedFile): string {
+	let name = ''
+	for (const character of (file.name ?? '').replace(/[/\\"]/g, '_')) {
+		if (name.length + character.length > MAX_ATTACHMENT_NAME_LENGTH) break
+		name += character
+	}
+	const trimmed = name.trim()
+	return trimmed === '' ? 'attachment' : trimmed
+}
+
 export interface MailTransportInput {
 	readonly artifact: ContractArtifact
 	/** The framework's variables, whose `FABRIKA_EMAIL_*` configure the installation's transport. */
@@ -166,7 +225,7 @@ function installationTransport(names: readonly string[], input: MailTransportInp
 	const env = pickEmailEnvironment(input.framework)
 	let sender: EmailSender | null
 	try {
-		sender = emailSenderFromEnv(env, input.registry)
+		sender = env[EMAIL_PROVIDER_VARIABLE] === PLATFORM_EMAIL_PROVIDER ? platformSender(input.framework) : emailSenderFromEnv(env, input.registry)
 	} catch (error) {
 		if (!(error instanceof EmailDeliveryError)) {
 			throw error
@@ -190,6 +249,29 @@ function installationTransport(names: readonly string[], input: MailTransportInp
 	return null
 }
 
+/** The platform's relay, from its receiver's variables; a refusal names them and never their values. */
+function platformSender(framework: Readonly<Record<string, string>>): EmailSender {
+	const variables = platformTransportVariables('mail')
+	const url = framework[variables.url] ?? ''
+	const key = framework[variables.key] ?? ''
+	const missing = [variables.url, variables.key].filter((name) => (framework[name] ?? '') === '')
+	if (missing.length > 0) {
+		throw new EmailDeliveryError(`Email configuration is invalid: ${missing.map((name) => `${name} is missing`).join('; ')}`, {
+			code: 'invalid_configuration',
+		})
+	}
+	try {
+		return new PlatformEmailSender({ url, key })
+	} catch (error) {
+		if (!(error instanceof EmailDeliveryError)) {
+			throw error
+		}
+		throw new EmailDeliveryError(`Email configuration is invalid: ${variables.url} or ${variables.key} is invalid (${error.message})`, {
+			code: 'invalid_configuration',
+		})
+	}
+}
+
 function ownTransport(names: readonly string[], input: MailTransportInput, problems: string[]): JobMailTransport | null {
 	if (input.own === undefined) {
 		return null
@@ -221,7 +303,13 @@ function ownTransport(names: readonly string[], input: MailTransportInput, probl
 	return null
 }
 
-const SenderCapabilities = z.object({ idempotent: z.boolean(), confirmation: z.enum(['sync', 'queued']), maxBatch: z.int().positive() })
+const SenderCapabilities = z.object({
+	idempotent: z.boolean(),
+	confirmation: z.enum(['sync', 'queued']),
+	maxBatch: z.int().positive(),
+	listUnsubscribe: z.boolean().optional(),
+	maxAttachmentBytes: z.int().positive().optional(),
+})
 
 /** What `serve`'s `mail` returned: a sender, `null` for none, `undefined` for anything else. */
 function parseSender(value: unknown): EmailSender | null | undefined {

package/src/jobs/runner.ts

@@ -1,7 +1,7 @@
 // The job runner (`fabrika job run <name>`): one run of one `c.cron` job. A run takes the job's lease or does not
 // start; each attempt holds one generation of it with a deadline the database enforces, so a write of an attempt
-// that timed out, failed or lost the lease never commits (`@fabrika/db`'s fence). A form's `then` kicks a run in the
-// background without waiting for any lock; a kick that finds the lease held leaves the shared pending flag, and the run
+// that timed out, failed or lost the lease never commits (`@fabrika/db`'s fence). A site's `ctx.kick` sends a run in
+// the background after its commit, without waiting for any lock; a kick that finds the lease held leaves the shared pending flag, and the run
 // holding it runs once more after it succeeded. Failures, crashed runs and a job that stopped succeeding are reported
 // to Operations, each under a fixed failure code.
 
@@ -11,8 +11,17 @@ import type { CapabilityAuthority } from '@fabrika/db/capability'
 import { type DataAccess, type FrameworkTables, type JobLeases, type LeaseFence, LeaseLostError, type Session } from '@fabrika/db/framework'
 import { EmailDeliveryError, type EmailSenderCapabilities, mayRetryDelivery } from '@fabrika/email'
 import { NotFoundError } from '../errors'
-import type { FileCollections } from '../files/collections'
-import { type CapabilityMint, CapabilityRefusedError, type Ref, RequestFrame, runInRequest, type Within } from '../implement/capability'
+import { FileWork, type StoredFileKinds, storedFilesHandle } from '../files/kinds'
+import {
+	type AppCapability,
+	type CapabilityMint,
+	CapabilityRefusedError,
+	type Ref,
+	RequestFrame,
+	runInRequest,
+	type Within,
+} from '../implement/capability'
+import { runAsSite } from '../implement/egress'
 import { failureCode, type FailureReason, failureReason } from '../implement/failures'
 import { ServerFault } from '../implement/faults'
 import type { ContractDatabase } from '../implement/implement'
@@ -24,20 +33,20 @@ import {
 	jobHandles,
 	jobSql,
 	jobSqlOutsideTransaction,
-	noFileCollections,
+	kickRecorder,
 	siteData,
 	type SiteDeclaration,
 	undeclaredSql,
 } from '../implement/invocation'
 import { jobLinkIssuing, type JobLinkMount } from '../implement/membership'
-import type { WorkloadCredential } from '../implement/workload'
+import type { SignedTokens } from '../implement/tokens'
+import { type AppUrl, appUrl } from '../implement/urls'
+import { type WorkloadCredential, workloadSite } from '../implement/workload'
 import { jobMail, type MailTransports } from './mail'
 import type { OperationsReporter } from './report'
 import { type CronSchedule, parseCron, periodAt } from './schedule'
 import type { AppMail, JobContext, JobPrincipal } from './types'
 
-/** An attempt of a job without a `timeout` is cancelled after this long. */
-export const DEFAULT_JOB_TIMEOUT_MS = 15 * 60_000
 /**
  * The lease outlives an attempt's deadline by this much: the runner renews or finishes a timed-out attempt's lease,
  * and no other run takes it over meanwhile. The attempt's writes stop at its deadline regardless.
@@ -47,8 +56,6 @@ export const LEASE_GRACE_MS = 60_000
 export const JOB_CHECK_INTERVAL_MS = 60_000
 const BACKOFF_BASE_MS = 1_000
 const BACKOFF_MAX_MS = 5 * 60_000
-const DURATION = /^([1-9][0-9]*)([smh])$/
-const UNIT_MS: Readonly<Record<string, number>> = { s: 1_000, m: 60_000, h: 3_600_000 }
 
 /**
  * Why a run failed. Fixed codes only: an application error's name and message may carry a secret, so neither is
@@ -167,12 +174,17 @@ interface RunnerContext {
 	readonly reporter: OperationsReporter
 	readonly mint: CapabilityMint
 	readonly data: DataAccess | null
-	readonly files: FileCollections | null
+	readonly fileKinds: StoredFileKinds | null
 	readonly membership: IamMembership | null
 	readonly capabilities: CapabilityAuthority
 	readonly containers: ReadonlyMap<string, readonly string[]>
 	readonly revealHandlerErrors: HandlerErrorSink | null
 	readonly mail: MailTransports
+	/** Kicks a contract job in the background: what a job's own `ctx.kick` sends once its run succeeded. */
+	readonly kick: (name: string) => Promise<void>
+	/** The environment's signed tokens: `ctx.tokens` of a job that declares `signs`. */
+	readonly tokens: SignedTokens | null
+	readonly url: AppUrl
 }
 
 /** Where `fabrika app dev` shows what a handler threw, on the developer's own machine; nothing else sets one. */
@@ -194,9 +206,9 @@ export interface JobBindingInput {
 	readonly mint: CapabilityMint
 	/** The mini-ORM of the bound `scoped(tables)` layer, behind a staged-kit job's `ctx.db`. */
 	readonly data: DataAccess | null
-	/** The contract's file collections, behind a staged-kit job's `ctx.files` and `tx.files`; `null` without any. */
-	readonly files?: FileCollections | null
-	/** The framework's own jobs this contract needs: the scan of its `scan: true` file collections. */
+	/** The contract's file kinds, behind a staged-kit job's `ctx.files.put` and `.open`; `null` without any. */
+	readonly fileKinds?: StoredFileKinds | null
+	/** The framework's own jobs this contract needs: the scan of its `scan: true` file kinds, and the file sweep. */
 	readonly frameworkJobs?: readonly FrameworkJob[]
 	/** IAM's membership operations, which a job that `issues` links asks; `null` when the adapter supplies none. */
 	readonly membership: IamMembership | null
@@ -208,6 +220,10 @@ export interface JobBindingInput {
 	readonly revealHandlerErrors?: HandlerErrorSink
 	/** The transports of the jobs that declare `mailer`, which `boot` resolved. */
 	readonly mail: MailTransports
+	/** The environment's signed tokens, which a job that declares `signs` signs with. */
+	readonly tokens?: SignedTokens
+	/** `ctx.url`: absolute links to the application's own procedures; without it every link is refused. */
+	readonly url?: AppUrl
 }
 
 interface BoundFrameworkJob {
@@ -221,7 +237,7 @@ export interface BoundJobs {
 	/** The handler ids the jobs took (`jobs.<name>`), so `boot` finds no undeclared handler among them. */
 	readonly declared: readonly string[]
 	/**
-	 * Kicks the contract job `name`, as a form's `then` does after its row committed: a run under the job's own key
+	 * Kicks the contract job `name`, as a site's `ctx.kick` does after its commit: a run under the job's own key
 	 * now, or the shared pending flag for the run holding the lease, which then runs once more after it succeeded. It
 	 * waits for no lock, settles when that work has ended and never rejects; the schedule stays the recovery path.
 	 */
@@ -237,15 +253,6 @@ function ownChild(node: unknown, key: string): unknown {
 	return typeof node === 'object' && node !== null && Object.hasOwn(node, key) ? Reflect.get(node, key) : undefined
 }
 
-function durationMs(timeout: string | null): number | null {
-	if (timeout === null) {
-		return DEFAULT_JOB_TIMEOUT_MS
-	}
-	const match = DURATION.exec(timeout)
-	const unit = match?.[2] === undefined ? undefined : UNIT_MS[match[2]]
-	return match?.[1] === undefined || unit === undefined ? null : Number.parseInt(match[1], 10) * unit
-}
-
 /** Binds every declared job to its handler, or adds why it cannot run to `problems`. */
 export function bindJobs(input: JobBindingInput, problems: string[]): BoundJobs {
 	const entries = Object.entries(input.artifact.jobs)
@@ -265,26 +272,22 @@ export function bindJobs(input: JobBindingInput, problems: string[]): BoundJobs
 		if (schedule === null) {
 			problems.push(`${where} has the schedule '${artifact.schedule}', which is not a cron expression (allowed: '0 3 * * *', '*/15 * * * *')`)
 		}
-		const timeoutMs = durationMs(artifact.timeout)
-		if (timeoutMs === null) {
-			problems.push(`${where} has the timeout '${artifact.timeout}', which is not a duration (allowed: '30s', '10m', '1h')`)
-		}
 		const node = ownChild(tree, name)
 		const handler = isSiteHandler(node) ? node.handler : node
 		const site = isSiteHandler(node) ? approvedDeclaration(where, `${JOB_SITE_PREFIX}${name}`, node.declared, 'job', input.artifact, problems) : null
-		const credential = input.credentials.get(`job:${name}`)
+		const credential = input.credentials.get(workloadSite('job', name))
 		const links = jobLinks(where, `${JOB_SITE_PREFIX}${name}`, site, input, problems)
 		const mailer = input.artifact.declared?.[`${JOB_SITE_PREFIX}${name}`]?.mailer ?? null
 		if (typeof handler !== 'function') {
 			problems.push(`${where} has no handler; add it to handlers.jobs`)
 		} else if (site !== null && input.data === null) {
 			problems.push(`${where} reaches data through ctx.db, which runs on @fabrika/db: pass serve(contract, { database: scoped(tables) })`)
-		} else if (schedule !== null && timeoutMs !== null && credential !== undefined) {
+		} else if (schedule !== null && credential !== undefined) {
 			bound.set(name, {
 				name,
 				artifact,
 				schedule,
-				timeoutMs,
+				timeoutMs: artifact.timeoutMs,
 				handler: (args) => Reflect.apply(handler, undefined, [args]),
 				credential,
 				site,
@@ -312,12 +315,16 @@ export function bindJobs(input: JobBindingInput, problems: string[]): BoundJobs
 		reporter: chosen ?? input.reporter,
 		mint: input.mint,
 		data: input.data,
-		files: input.files ?? null,
+		fileKinds: input.fileKinds ?? null,
 		membership: input.membership,
 		capabilities: input.capabilities,
 		containers: input.containers,
 		revealHandlerErrors: input.revealHandlerErrors ?? null,
 		mail: input.mail,
+		tokens: input.tokens ?? null,
+		url: input.url ?? appUrl(input.artifact, null),
+		// A job's kicks run only after the job is bound, so `kick` below is defined by then.
+		kick: (name: string) => kick(name),
 	})
 	const jobs: ContractJobs = Object.freeze({
 		names,
@@ -534,7 +541,9 @@ async function runLeased(
 	await pendingTaken(job, context)
 	const attempts = job.artifact.retries + 1
 	progress.attempts = 1
-	let outcome = await attemptOnce(job, fence, progress.attempts, clock, context, stop)
+	// The jobs the succeeding attempt kicked; a failed attempt's kicks are dropped with its writes.
+	const kicked: string[] = []
+	let outcome = await attemptOnce(job, fence, progress.attempts, clock, context, kicked, stop)
 	while (outcome !== null && outcome.code !== 'stopped' && !outcome.final && progress.attempts < attempts) {
 		console.error(`fabrika: job '${job.name}' attempt ${progress.attempts} of ${attempts} failed: ${describeFailure(outcome)}`)
 		const delay = backoffMs(progress.attempts, clock.random())
@@ -546,10 +555,12 @@ async function runLeased(
 		fence = next
 		await clock.wait(delay, stop ?? new AbortController().signal)
 		progress.attempts++
-		outcome = await attemptOnce(job, fence, progress.attempts, clock, context, stop)
+		outcome = await attemptOnce(job, fence, progress.attempts, clock, context, kicked, stop)
 	}
 	if (outcome === null) {
 		if (await leases.finish(fence, 'succeeded')) {
+			// After the lease is released, so a job that kicks another never waits on its own lease; a kick never rejects.
+			await Promise.all(kicked.map((name) => context.kick(name)))
 			return { status: 'succeeded', attempts: progress.attempts }
 		}
 		return failed(job, progress.attempts, failure('lease_lost'), context.reporter)
@@ -656,8 +667,10 @@ async function attemptOnce(
 	attempt: number,
 	clock: JobClock,
 	context: RunnerContext,
+	kicked: string[],
 	stop?: AbortSignal,
 ): Promise<JobFailure | null> {
+	kicked.length = 0
 	if (isStopped(stop)) {
 		return failure('stopped')
 	}
@@ -673,10 +686,17 @@ async function attemptOnce(
 	const cancel = new AbortController()
 	const timer = new AbortController()
 	const signal = stop === undefined ? cancel.signal : AbortSignal.any([cancel.signal, stop])
-	const ctx = jobContext(job, frame, attempt, signal, context, authority.perms)
+	const kicks = kickRecorder(`job '${job.name}'`, job.site?.kicks ?? [])
+	const ctx = { ...jobContext(job, frame, attempt, signal, context, authority.perms), kick: kicks.kick }
 	try {
 		const ran = runInRequest(frame, async () => {
-			await job.handler({ ctx })
+			const site = job.site
+			if (site === null) {
+				await job.handler({ ctx })
+			} else {
+				await runAsSite(`job '${job.name}'`, site.egress, async () => await job.handler({ ctx }))
+			}
+			kicked.push(...kicks.kicked())
 		}).then(() => null, (error: unknown) => {
 			const failed = failureOf(error, job.mailer === null ? null : (context.mail[job.mailer]?.sender.capabilities ?? null))
 			if (failed.code === 'handler_failed') context.revealHandlerErrors?.(`job '${job.name}' attempt ${attempt}`, error)
@@ -730,7 +750,7 @@ function jobContext(
 	perms: readonly PermissionEntry[],
 ): JobContext<string, string> {
 	const principal: JobPrincipal = Object.freeze({ kind: 'job', id: `job:${job.name}`, job: job.name })
-	const check = (action: string, dimension: string): void => {
+	const checkAction = (action: string): void => {
 		if (frame.ended) {
 			throw new CapabilityRefusedError('ended', `attempt ${frame.id} of job '${job.name}' has ended; it mints no capability`)
 		}
@@ -743,6 +763,9 @@ function jobContext(
 		if (!permits([...perms], action)) {
 			throw new CapabilityRefusedError('undeclared_action', `the token IAM signed for the key of job '${job.name}' does not carry this action`)
 		}
+	}
+	const check = (action: string, dimension: string): void => {
+		checkAction(action)
 		if (!Object.hasOwn(context.artifact.dimensions, dimension)) {
 			throw new CapabilityRefusedError('undeclared_dimension', `job '${job.name}' named a dimension the contract does not declare`)
 		}
@@ -765,14 +788,34 @@ function jobContext(
 		}
 		return context.mint.ref(frame, dimension, action, principal.id, id, chain)
 	}
+	const app = <const Act extends string>(action: Act): AppCapability<Act> => {
+		checkAction(action)
+		return context.mint.app(frame, action, principal.id)
+	}
 	return Object.freeze({
 		principal,
 		runId: frame.id,
 		attempt,
 		signal,
-		...(job.site === null || context.data === null ? {} : kitJobContext(frame, context.data, context.files, job.name, job.site, principal.id, ref)),
+		url: context.url,
+		...(job.site === null || context.data === null
+			? {}
+			: kitJobContext(
+				frame,
+				context.data,
+				context.fileKinds,
+				job.name,
+				job.site,
+				principal.id,
+				ref,
+				app,
+				periodAt(job.schedule, new Date()) ?? undefined,
+			)),
 		...(job.links === null || context.membership === null ? {} : { links: jobLinksOf(job, job.links, context.membership, frame, context) }),
 		...(job.mailer === null ? {} : { mail: jobMailOf(job, job.mailer, frame, signal, context) }),
+		...(job.site === null || job.site.signs.length === 0 || context.tokens === null
+			? {}
+			: { tokens: context.tokens.context(`job '${job.name}'`, job.site.signs) }),
 		within<const Act extends string, const Dim extends string>(action: Act, dimension: Dim): Within<Dim, Act> {
 			check(action, dimension)
 			return context.mint.within(frame, dimension, action, principal.id, 'all')
@@ -780,6 +823,7 @@ function jobContext(
 		ref<const Act extends string, const Dim extends string>(action: Act, dimension: Dim, id: string): Promise<Ref<Dim, Act>> {
 			return ref(action, dimension, id)
 		},
+		app,
 	})
 }
 
@@ -819,16 +863,14 @@ function jobMailOf(job: BoundJob, mailer: JobMailer, frame: RequestFrame, signal
 	if (transport === null) {
 		throw new ServerFault('facility_unbound', `job '${job.name}' declares mailer: '${mailer}', and boot resolved no transport for it`)
 	}
-	return jobMail({
-		transport,
-		keyPrefix: context.mail.keyPrefix,
-		signal,
-		assertLive: () => {
-			if (frame.ended) {
-				throw new CapabilityRefusedError('ended', `attempt ${frame.id} of job '${job.name}' has ended; it sends no mail`)
-			}
-		},
-	})
+	const assertLive = (): void => {
+		if (frame.ended) {
+			throw new CapabilityRefusedError('ended', `attempt ${frame.id} of job '${job.name}' has ended; it sends no mail`)
+		}
+	}
+	// The attempt's holdings belong to its frame, so this work opens what `ctx.files.open` of the attempt opens.
+	const files = storedFilesHandle(context.fileKinds, new FileWork(frame, frame.id), { where: `job '${job.name}'`, check: assertLive, writes: false })
+	return jobMail({ transport, keyPrefix: context.mail.keyPrefix, signal, assertLive, open: files.open })
 }
 
 /**
@@ -838,49 +880,39 @@ function jobMailOf(job: BoundJob, mailer: JobMailer, frame: RequestFrame, signal
 function kitJobContext(
 	frame: RequestFrame,
 	data: DataAccess,
-	files: FileCollections | null,
+	kinds: StoredFileKinds | null,
 	name: string,
 	site: SiteDeclaration,
 	principal: string,
 	ref: (action: string, dimension: string, id: string, using: Session) => Promise<Ref<string, string>>,
+	app: (action: string) => AppCapability<string>,
+	tickMs: number | undefined,
 ): Readonly<Record<string, unknown>> {
-	const reads = jobHandles(frame, data, site, principal, 'job', async () => data.direct(), () => false)
+	// One attempt's files: what it reads, puts and writes, inside its transactions and outside them, belongs to it.
+	const work = new FileWork(frame, frame.id)
+	const binding = kinds?.binding(work)
+	const reads = jobHandles(frame, data, site, principal, 'job', async () => data.direct(), () => false, tickMs, binding)
 	const job = `job '${name}'`
+	const putAndOpen = (check: () => void) => storedFilesHandle(kinds, work, { where: job, check, writes: true })
 	return {
-		db: siteData(reads),
+		db: siteData(reads, (action) => reads.app(app(action))),
 		sql: site.sql === null ? undeclaredSql(job, 'job') : jobSqlOutsideTransaction(job),
-		files: files === null ? noFileCollections(job) : files.site({
-			where: job,
-			frame,
-			check: boundTo(frame, () => false, 'ctx.files'),
-			session: async () => data.direct(),
-			readOnly: 'a job removes files inside ctx.transaction((tx) => …), as tx.files',
-			attaches: false,
-		}),
+		files: putAndOpen(boundTo(frame, () => false, 'ctx.files')),
 		transaction: async <R>(work: (tx: object) => Promise<R>): Promise<R> => {
 			// Outside its attempt there is no lease to fence the transaction with, so it never opens.
 			boundTo(frame, () => false)()
 			return data.transaction(async (session) => {
 				let open = true
-				const writes = jobHandles(frame, data, site, principal, 'mutation', async () => session, () => !open)
+				const writes = jobHandles(frame, data, site, principal, 'mutation', async () => session, () => !open, undefined, binding)
 				try {
 					const sql = site.sql === null ? undeclaredSql(job, 'job', 'tx.sql') : jobSql(frame, data, site.sql, session, () => !open)
-					const removing = files === null
-						? noFileCollections(job)
-						: files.site({
-							where: job,
-							frame,
-							check: boundTo(frame, () => !open, 'tx.files'),
-							session: async () => session,
-							readOnly: null,
-							attaches: true,
-						})
 					// Located in this transaction, so an object it wrote is found before the commit.
 					const located = (action: string, dimension: string, id: string) => {
 						boundTo(frame, () => !open, 'tx.ref')()
 						return ref(action, dimension, id, session)
 					}
-					return await work(Object.freeze({ db: siteData(writes), sql, files: removing, ref: located }))
+					const files = putAndOpen(boundTo(frame, () => !open, 'tx.files'))
+					return await work(Object.freeze({ db: siteData(writes, (action) => writes.app(app(action))), sql, files, ref: located }))
 				} finally {
 					open = false
 				}

package/src/jobs/scrub.ts

@@ -1,7 +1,7 @@
 // What an error report must not carry (ADR-0059): the values of the application's secrets, and anything shaped like a
 // credential — a JWT, an `Authorization` scheme or header, a URL's userinfo, a sensitive query parameter.
 
-import { FABRIKA_CONTRACT_DIGEST, FABRIKA_IAM_APP_ID, FABRIKA_IAM_ISSUER } from '@fabrika/auth-core'
+import { FABRIKA_CONTRACT_DIGEST, FABRIKA_IAM_APP_ID, FABRIKA_IAM_ISSUER, PLATFORM_RECEIVERS, platformTransportVariables } from '@fabrika/auth-core'
 import type { CapturedEnvironment } from '../implement/environment'
 
 export const REDACTED = '[redacted]'
@@ -16,9 +16,12 @@ const PUBLIC_FRAMEWORK_VARIABLES: ReadonlySet<string> = new Set([
 	'FABRIKA_ENVIRONMENT',
 	'FABRIKA_IAM_RPC_URL',
 	'FABRIKA_APP_DATABASE_CONNECTIONS',
+	// `platform` is eight characters, so a secret scrubber would redact the word wherever a message names it.
+	'FABRIKA_EMAIL_PROVIDER',
 	FABRIKA_CONTRACT_DIGEST,
 	FABRIKA_IAM_APP_ID,
 	FABRIKA_IAM_ISSUER,
+	...PLATFORM_RECEIVERS.map((receiver) => platformTransportVariables(receiver).url),
 ])
 
 /**

package/src/jobs/types.ts

@@ -3,7 +3,9 @@
 
 import type { EmailDeliveryResult, EmailSenderCapabilities } from '@fabrika/email'
 import type { CronJob, DimensionOf } from '../contract/define'
-import type { Ref, Within } from '../implement/capability'
+import type { FileRef } from '../contract/file'
+import type { AppCapability, Ref, Within } from '../implement/capability'
+import type { AppUrl } from '../implement/urls'
 
 /** Who a job's writes are stamped with (`createdBy`): the job itself, never a person. */
 export interface JobPrincipal {
@@ -31,6 +33,10 @@ export interface JobContext<A extends string, D extends string> {
 	within<const Act extends A, const Dim extends D>(action: Act, dimension: Dim): Within<Dim, Act>
 	/** One object of `dimension` for a declared action, located now: what a write takes. A missing object is NotFound. */
 	ref<const Act extends A, const Dim extends D>(action: Act, dimension: Dim, id: string): Promise<Ref<Dim, Act>>
+	/** A declared action, application-wide: what `ctx.db.app('<action>')` reads and writes the application tables with. */
+	app<const Act extends A>(action: Act): AppCapability<Act>
+	/** An absolute link to a procedure of this application: `ctx.url('api.mail.unsubscribe', { query: { t } })`. */
+	readonly url: AppUrl
 }
 
 /** One message a job sends. The framework prefixes `idempotencyKey` before the transport sees it. */
@@ -43,6 +49,17 @@ export interface AppMailMessage {
 	readonly idempotencyKey: string
 	readonly replyTo?: string
 	readonly fromName?: string
+	/**
+	 * A one-click unsubscribe (RFC 8058): the transport writes `List-Unsubscribe` and `List-Unsubscribe-Post`. `url` is
+	 * an `https:` link, usually `ctx.url` of a public procedure that verifies a signed token.
+	 */
+	readonly unsubscribe?: { readonly url: string }
+	/**
+	 * Files the message carries: references this attempt holds and may read, as `ctx.files.open` takes them. Only a
+	 * `live` file is sent; the bytes of all of them together stay within the transport's `maxAttachmentBytes`, and a
+	 * transport without it refuses the message. The idempotency key covers the attachments.
+	 */
+	readonly attachments?: readonly FileRef[]
 }
 
 /** `ctx.mail` of a job that declares `mailer`. */
@@ -71,6 +88,6 @@ type JobsOf<C> = C extends { readonly surface: { readonly jobs: infer J } } ? J
 /** `{ jobs: { <name>: handler } }` for a contract that declares jobs, and nothing for one that declares none. */
 export type JobHandlersOf<C> = [JobsOf<C>] extends [never] ? unknown : {
 	readonly jobs: {
-		readonly [K in keyof JobsOf<C>]: JobsOf<C>[K] extends CronJob<infer A, string> ? JobHandler<A, DimensionOf<C>> : never
+		readonly [K in keyof JobsOf<C>]: JobsOf<C>[K] extends CronJob<infer A> ? JobHandler<A, DimensionOf<C>> : never
 	}
 }

package/src/react/hooks.ts

@@ -4,7 +4,7 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
 import { z } from 'zod/v4'
-import type { AttachmentProcedure, DownloadInput } from '../client/contract'
+import type { AttachmentProcedure, DownloadedFile, DownloadInput, FileProcedure } from '../client/contract'
 import type { Schema } from '../contract/define'
 import { type FabrikaError, toFabrikaError } from './errors'
 import { parentOf, prefixOf, useFabrika } from './provider'
@@ -170,7 +170,7 @@ export type DownloadArgument<I> = DownloadInput<I>[0]
  * that hands the provider a client over the kit downloads over the kit. `mutate(input)` saves the file in a browser and
  * answers it as `data`; a refusal is the state's `error`, as for `useMutation`. It refetches nothing.
  */
-export function useDownload<I>(procedure: AttachmentProcedure<I>): MutationState<DownloadArgument<I>, File> {
+export function useDownload<I>(procedure: AttachmentProcedure<I> | FileProcedure<I>): MutationState<DownloadArgument<I>, DownloadedFile> {
 	const fabrika = useFabrika('useDownload')
 	const run = useMemo(() => fabrika.attachment(procedure, 'useDownload'), [fabrika, procedure])
 	return useRun(run, NOTHING_AFTER)