@fabrika/app 0.5.3 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.5.3",
+	"version": "0.5.5",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -93,14 +93,14 @@
 		"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
 	},
 	"dependencies": {
-		"@fabrika/auth": "0.5.3",
-		"@fabrika/auth-core": "0.5.3",
-		"@fabrika/db": "0.5.3",
-		"@fabrika/email": "0.5.3",
-		"@fabrika/jwks": "0.5.3",
-		"@fabrika/platform": "0.5.3",
-		"@fabrika/platform-node": "0.5.3",
-		"@fabrika/proxy-core": "0.5.3",
+		"@fabrika/auth": "0.5.5",
+		"@fabrika/auth-core": "0.5.5",
+		"@fabrika/db": "0.5.5",
+		"@fabrika/email": "0.5.5",
+		"@fabrika/jwks": "0.5.5",
+		"@fabrika/platform": "0.5.5",
+		"@fabrika/platform-node": "0.5.5",
+		"@fabrika/proxy-core": "0.5.5",
 		"jose": "^5.9.0"
 	},
 	"peerDependencies": {

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabrika-app
-version: 0.5.3
+version: 0.5.5
 description: >
   How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
   slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors
@@ -220,14 +220,15 @@ the access check. `references/spa.md` shows the stack.
 
 ## Off the road: declare it
 
-| What the handler needs         | Declare on the endpoint         | It gets                                            |
-| ------------------------------ | ------------------------------- | -------------------------------------------------- |
-| a join, a report, a bulk write | `sql: 'read'` (or `'write'`)    | `` ctx.sql(Row)`…` ``, scoped with `ctx.sql.scope` |
-| rows outside its capability    | `unscoped: { <table>: 'read' }` | `ctx.db.unscoped.<table>`                          |
-| another application's export   | `connect: ['<import>']`         | `ctx.connect.<import>`                             |
-| a share link                   | `issues: '<link mount>'`        | `ctx.links.issue`                                  |
-| e-mail (a cron job only)       | `mailer: 'installation'`        | `ctx.mail.send`                                    |
-| a trigger, function or view    | its migration                   | —                                                  |
+| What the handler needs         | Declare on the endpoint                        | It gets                                             |
+| ------------------------------ | ---------------------------------------------- | --------------------------------------------------- |
+| a join, a report, a bulk write | `sql: 'read'` (or `'write'`)                   | `` ctx.sql(Row)`…` ``, scoped with `ctx.sql.scope`  |
+| rows outside its capability    | `unscoped: { <table>: 'read' }`                | `ctx.db.unscoped.<table>`                           |
+| another application's export   | `connect: ['<import>']`                        | `ctx.connect.<import>`                              |
+| a share link                   | `issues: '<link mount>'`                       | `ctx.links.issue`                                   |
+| e-mail (a cron job only)       | `mailer: 'installation'`                       | `ctx.mail.send`                                     |
+| a file with a public form      | `files: { photo: { collection } }` on `c.form` | the id in the inbox; the job's `tx.files(…).attach` |
+| a trigger, function or view    | its migration                                  | —                                                   |
 
 Scope every scoped table a raw statement reads with `${ctx.sql.scope(<capability>, '<table>', '<alias>')}`, a conjunct
 of its WHERE or JOIN … ON (`where (<filter>) and ${…}`): `ctx.target` for `on` and `in`, `ctx.within` for `over`, a
@@ -258,7 +259,7 @@ Which promise the types, the checker, boot, the runtime or the approver keeps, a
 - A 401, a 403 or a failing generated test: never loosen the contract, a role, a policy or a test to pass. Tell the
   human which action or role the caller lacks.
 - When the task does not already ask for it, before you add a role, a grant, an action, a declared deviation, an
-  anonymous endpoint (`c.form`, a webhook, a link), an export or an import, or a job, or before you drop or rename a
+  anonymous endpoint (`c.form`, a form's `files`, a webhook, a link), an export or an import, or a job, or before you drop or rename a
   column: say in one sentence what it lets someone do, and wait for a yes. A data repair goes to the operator, not
   into a job.
 - A file refused as protected: stop and ask. Do not move the change elsewhere.

package/skill/references/app-setup.md

@@ -19,20 +19,20 @@ the SPA is added with it.
 		"test": "bun test --isolate"
 	},
 	"dependencies": {
-		"@fabrika/app": "0.5.3",
-		"@fabrika/db": "0.5.3",
-		"@fabrika/provider-zerops": "0.5.3",
-		"@fabrika/proxy-core": "0.5.3",
-		"@fabrika/ui": "0.5.3",
+		"@fabrika/app": "0.5.5",
+		"@fabrika/db": "0.5.5",
+		"@fabrika/provider-zerops": "0.5.5",
+		"@fabrika/proxy-core": "0.5.5",
+		"@fabrika/ui": "0.5.5",
 		"kysely": "0.29.6",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"zod": "^3.25.76"
 	},
 	"devDependencies": {
-		"@fabrika/check": "0.5.3",
-		"@fabrika/cli": "0.5.3",
-		"@fabrika/platform": "0.5.3",
+		"@fabrika/check": "0.5.5",
+		"@fabrika/cli": "0.5.5",
+		"@fabrika/platform": "0.5.5",
 		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/bun": "latest",
 		"@types/react": "^19.0.0",

package/skill/references/files.md

@@ -325,6 +325,29 @@ CREATE INDEX fabrika_files_attachments_scan ON fabrika_files_attachments (scan_a
   for something else (a one-click answer): a mount the list does not name has no file route and need not grant
   the collection's actions. Its holder gets 403 from the proxy, which finds no endpoint for the path.
 
+## A file with a public form
+
+A visitor without an account reaches no collection endpoint. A form takes the file with its submission instead
+(`references/public-intake.md` builds it): `files: { photo: { collection: 'photos' } }` on `c.form`, into a collection
+with `scan: true`, beside a challenge. The file waits owned by nobody, and nothing reads it; its id lands in the inbox
+column of its field (`photo UUID`). The job that drains the inbox creates the record and attaches the file in the same
+transaction, with a `Ref` of the new record for the collection's `write` action, which `tx.ref` locates in that
+transaction:
+
+```text
+const [created] = await tx.sql(Id)`insert into candidates (…) values (…) on conflict (email) do nothing returning id`
+if (created !== undefined && row.photo !== null) {
+	await tx.files('photos').attach(await tx.ref('candidates.attach', 'candidate', created.id), row.photo)
+}
+```
+
+- Only a job's `tx.files` has `attach`; a mutation's has none. `tx.ref` is `ctx.ref` located in the transaction.
+- `attach` answers `false` when no file of the collection waits under the id (none was sent, or its hold of seven days
+  ended) and `true` again for one the same owner attached before; it never moves another owner's file. Past
+  `maxPerOwner` it throws 409, and the transaction rolls back with the file still held.
+- The attached file is `quarantined` until the scan job's clean verdict, like any upload of a scanning collection.
+- A file nobody attached is deleted by the sweep job an hour after its hold of seven days ended.
+
 ## Storage
 
 On Zerops, declare one `object-storage` service in `fabrika.config.ts`; the platform writes `FABRIKA_APP_STORAGE_*`

package/skill/references/public-intake.md

@@ -1,7 +1,7 @@
 # references/public-intake.md — the public intake recipe
 
-A visitor who has no account submits a form on a public page, confirms the e-mail address through a link, attaches
-files, and asks for a new link when the first one is lost. HR reviews the records, an HR lead edits the code lists of
+A visitor who has no account submits a form on a public page, with a photo from the phone's camera if they like,
+confirms the e-mail address through a link, attaches files, and asks for a new link when the first one is lost. HR reviews the records, an HR lead edits the code lists of
 open positions and of the reasons a decision records, HR exports every candidate with an audit row, and an HR person
 checks the mail setup with a test e-mail to their own address. This file is an application of its own (`intake`); its
 `package.json`, `tsconfig.json` and `src/app-kit.ts` are those of `app-setup.md`.
@@ -136,13 +136,15 @@ CREATE TABLE candidate_events (
 );
 CREATE INDEX candidate_events_candidate ON candidate_events (candidate_id);
 
--- The forms' inboxes: a column per input field, of its name, except the honeypot and the challenge token. A form
--- writes its input fields only, so every other column has a default: id names the row for the job, received_at keeps
--- the time of the submission, and a registration counts the job's failed attempts at it.
+-- The forms' inboxes: a column per input field, of its name, except the honeypot and the challenge token, and one per
+-- file field, which receives the id of the file the submission carried (NULL without one). A form writes those
+-- columns only, so every other column has a default: id names the row for the job, received_at keeps the time of the
+-- submission, and a registration counts the job's failed attempts at it.
 CREATE TABLE registrations (
 	id UUID NOT NULL DEFAULT gen_random_uuid(),
 	email TEXT NOT NULL,
 	full_name TEXT NOT NULL,
+	photo UUID,
 	received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
 	attempts INTEGER NOT NULL DEFAULT 0,
 	last_failure TEXT
@@ -214,8 +216,31 @@ CREATE INDEX fabrika_files_attachments_removable ON fabrika_files_attachments (c
 CREATE INDEX fabrika_files_attachments_scan ON fabrika_files_attachments (scan_after) WHERE status = 'quarantined';
 ```
 
-The file table is `fileTableSql('attachments', { table: 'candidates', key: { column: 'id', type: 'uuid' }, chain: [] })`
-(`references/files.md`): a top-level owner has no chain.
+```sql db/migrations/20261013090150_photos.sql
+CREATE TABLE fabrika_files_photos (
+	id UUID PRIMARY KEY,
+	owner_id UUID,
+	status TEXT NOT NULL CONSTRAINT fabrika_files_photos_status CHECK (status IN ('pending', 'live', 'quarantined', 'rejected')),
+	object_key TEXT NOT NULL UNIQUE,
+	size BIGINT,
+	content_type TEXT NOT NULL,
+	sha256 TEXT,
+	original_name TEXT,
+	created_by TEXT NOT NULL,
+	created_at TIMESTAMPTZ NOT NULL,
+	deleted_at TIMESTAMPTZ,
+	object_version TEXT,
+	scan_attempts INTEGER NOT NULL DEFAULT 0,
+	scan_after TIMESTAMPTZ,
+	FOREIGN KEY (owner_id) REFERENCES candidates (id) ON UPDATE CASCADE ON DELETE SET NULL
+);
+CREATE INDEX fabrika_files_photos_owner ON fabrika_files_photos (owner_id) WHERE deleted_at IS NULL;
+CREATE INDEX fabrika_files_photos_removable ON fabrika_files_photos (created_at) WHERE deleted_at IS NOT NULL OR owner_id IS NULL OR status = 'pending';
+CREATE INDEX fabrika_files_photos_scan ON fabrika_files_photos (scan_after) WHERE status = 'quarantined';
+```
+
+The file tables are `fileTableSql('attachments', { table: 'candidates', key: { column: 'id', type: 'uuid' }, chain: [] })`
+and the same for `photos` (`references/files.md`): a top-level owner has no chain.
 
 ```ts src/db/tables.ts
 import { defineTables } from '@fabrika/db/tables'
@@ -359,6 +384,7 @@ export const contract = app.contract((c) => ({
 			secret: 'TURNSTILE_SECRET',
 			siteKey: 'TURNSTILE_SITE_KEY',
 		},
+		files: { photo: { collection: 'photos' } },
 		then: 'intake',
 	}),
 	resend: c.form('/resend', {
@@ -385,6 +411,16 @@ export const contract = app.contract((c) => ({
 			link: true,
 			scan: true,
 		}),
+		photos: c.files({
+			owner: 'candidates',
+			read: 'candidates.read',
+			write: 'candidates.attach',
+			delete: 'candidates.review',
+			maxBytes: 15728640,
+			types: ['image/jpeg', 'image/png', 'image/webp'],
+			maxPerOwner: 1,
+			scan: true,
+		}),
 	},
 	jobs: { intake, testMails },
 	health: c.health('/healthz'),
@@ -421,6 +457,22 @@ export const contract = app.contract((c) => ({
   `styleSrc`, `fontSrc` and `frameAncestors`: exact `https://` origins, at most 16 each. Each new origin is a widening the approver sees.
 - **Scanned files.** A visitor's upload waits `quarantined` until ClamAV answers clean (`references/files.md`): its
   download answers 409 until then. On Zerops the deploy service needs `verticalAutoscaling: { minRam: 2 }`.
+- **A photo with the registration.** `files: { photo: { collection: 'photos' } }` lets the form carry one file beside
+  its input; `required: true` refuses a submission without it. The form becomes `multipart/form-data` (the page's code
+  is below) and must declare a challenge; each field lands in a collection that has `scan: true`, whose `types`,
+  `maxBytes` and `maxPerOwner` bound the file, while the form's `maxBytes` bounds only its input. The inbox has a
+  column named like the field (`photo UUID`), which receives the file's id, or `NULL` when the visitor sent none. Until
+  the job attaches it, the file is owned by nobody and nobody can read it; one the job never attaches (a known address,
+  a registration that stays dead) is deleted seven days after the submission. The approver sees "Form `register` takes
+  a file `photo` from anyone into files `photos`". A file the collection refuses (a type it does not admit, bytes
+  that are not that type, too large) is 415 or 413 after the challenge was spent, so the page checks the type and the
+  size before it submits, and solves the challenge again after a refusal.
+  While no file is `required`, the form still takes the JSON body it took before (every file column `NULL`): deploy the
+  application first, then switch each page to multipart. A form with files accepts 20 submissions a minute unless
+  `rate.perForm` says otherwise, and its files write at most 512 MiB an hour in all (`rate: { bytesPerHour }` to raise
+  it, never below the largest file): each file reserves its collection's `maxBytes` first, so with a 15 MiB photo about
+  34 maximal photos fit in an hour, more of the usual 2–5 MB ones; past it the form answers 429 until the hour ends.
+  Size the budget for the expected peak: a flood that spends it costs that hour's photos, not the storage.
 - **The kick.** `then: 'intake'` makes each accepted submission start a run of the job within seconds, once its row
   committed, under the job's own key. The visitor's answer is the same constant and never waits for the run. Kicks
   coalesce on the job's lease (at most one run and one pending, however many visitors submit), so a flood adds no
@@ -505,6 +557,7 @@ const Queued = z.strictObject({
 	id: z.string(),
 	email: z.string(),
 	fullName: z.string(),
+	photo: z.nullable(z.string()),
 })
 const Ask = z.strictObject({ email: z.string() })
 const Id = z.strictObject({ id: z.string() })
@@ -574,18 +627,27 @@ export const intake = app.cron('* * * * *', {
 				ctx.transaction(async (tx) => {
 					// Claimed where it is consumed: a row other work holds is skipped, not waited for.
 					const [row] = await tx.sql(Queued)`
-						select id, email, full_name from registrations
+						select id, email, full_name, photo from registrations
 						where id = ${id} and attempts < ${MAX_ATTEMPTS}
 						for update skip locked`
 					if (row === undefined) return
 					await tx.sql(Id)`
 						delete from registrations where id = ${row.id} returning id`
-					await tx.sql(Id)`
+					const [created] = await tx.sql(Id)`
 						insert into candidates (id, email, name, created_by, version)
 						values (${crypto.randomUUID()}, ${row.email}, ${row.fullName},
 							${ctx.principal.id}, 1)
 						on conflict (email) do nothing
 						returning id`
+					// The photo becomes the new candidate's in this transaction; a known address gets none.
+					if (created !== undefined && row.photo !== null) {
+						const candidate = await tx.ref(
+							'candidates.attach',
+							'candidate',
+							created.id,
+						)
+						await tx.files('photos').attach(candidate, row.photo)
+					}
 				}), async () => {
 				const [counted] = await ctx.transaction((tx) =>
 					tx.sql(Attempts)`
@@ -922,9 +984,15 @@ export const siteKey = async (): Promise<string | null> => {
 ```
 
 The public page sends the form with a plain `fetch`: a form has no typed client, and its answer never depends on the
-data.
+data. A form that takes files is `multipart/form-data`: the first part is named `input` and holds the input as JSON,
+and each file follows in a part named after its field. Let the browser write the `Content-Type` with its boundary:
+never set it yourself.
 
 ```ts web/site/register.ts
+/** What the `photos` collection admits; the page checks it before it spends the challenge. */
+const PHOTO_TYPES = ['image/jpeg', 'image/png', 'image/webp']
+const PHOTO_MAX_BYTES = 15728640
+
 export const register = async (
 	form: HTMLFormElement,
 	challengeToken: string,
@@ -934,16 +1002,25 @@ export const register = async (
 		const value = data.get(name)
 		return typeof value === 'string' ? value : ''
 	}
-	const response = await fetch('/register', {
-		method: 'POST',
-		headers: { 'Content-Type': 'application/json' },
-		body: JSON.stringify({
+	const body = new FormData()
+	body.append(
+		'input',
+		JSON.stringify({
 			email: field('email'),
 			full_name: field('full_name'),
 			website: field('website'),
 			challengeToken,
 		}),
-	})
+	)
+	// <input type="file" name="photo" accept="image/*" capture="environment">; an empty one sends nothing.
+	const photo = data.get('photo')
+	if (photo instanceof File && photo.size > 0) {
+		if (!PHOTO_TYPES.includes(photo.type) || photo.size > PHOTO_MAX_BYTES) {
+			return false
+		}
+		body.append('photo', photo, photo.name)
+	}
+	const response = await fetch('/register', { method: 'POST', body })
 	return response.ok
 }
 ```
@@ -1525,7 +1602,12 @@ export const testMails = app.cron('* * * * *', {
   job's key, so `kit.runJob('intake')` needs `testKit(app, { membership })` with an `IamMembershipRpc` of your own that
   answers `issueLink` and `revokeLink`. A test of a form passes `env: {
   TURNSTILE_SECRET: '…', TURNSTILE_SITE_KEY: '…' }` and `challengeFetch`, a stand-in for Turnstile's answer, to `testKit`, and a fresh
-  `challengeToken` with each submission: a token is single use. Test each stop of a delivery (a refused e-mail, IAM
+  `challengeToken` with each submission: a token is single use. A form that takes files is sent as the page sends it,
+  a `FormData` with the `input` part first, through `kit.fetch` with the page's `Origin` (`kit.origin`), and needs
+  `files: new MemoryFileObjects()` in `testKit`; `kit.runJob('intake')` then attaches the photo, and the scan job
+  (`FILE_SCAN_JOB`, with a `scanner`) makes it downloadable. Test the refusals beside the success: no or a failed
+  token, a filled honeypot, a file too large or of another type, a part the form does not declare, a page on another
+  origin; each keeps nothing. Test each stop of a delivery (a refused e-mail, IAM
   down, a crash after each step, an answer lost after the provider took the e-mail): the next run must leave exactly
   one live, e-mailed link and the transport one message per key. Test a bad record beside good ones too: a
   registration the insert refuses and a recipient whose e-mail hangs end dead after `MAX_ATTEMPTS` runs, a recipient

package/skill/references/spa.md

@@ -736,9 +736,11 @@ if (postgres !== null) {
 ```
 
 - `web/__tests__/dom.ts` comes first: imports run in order, and React reads `window` when it loads. `installDom` keeps
-  Bun's `fetch`, `AbortController`, `URL`, `Blob`, `File` and `FormData`, because the clients, the kit, a form's
-  challenge and a download run on them, and turns navigation off, so a download's link click leaves the page for the
-  next test. Run the tests with `bun test --isolate`, which gives each file its own globals.
+  Bun's `fetch`, `AbortController`, `URL`, `Blob`, `File`, `FormData` and its `ReadableStream`, `WritableStream` and
+  `TransformStream`, because the clients, the kit, a form's challenge, a form's file and a download run on them, and
+  turns navigation off, so a download's link click leaves the page for the next test. A DOM registration of your own
+  keeps the same classes of Bun, or a form with a file fails in the kit. Run the tests with `bun test --isolate`, which
+  gives each file its own globals.
 - `await type('Title', 'report')` types into the control whose label (or `aria-label`) is `Title` as React reads a
   person typing; a select takes the option's value. `controlByLabel(label)` answers the control, and
   `waitForText(text)` waits until the page shows it.

package/src/contract/artifact-schema.ts

@@ -189,10 +189,11 @@ const mount = z.discriminatedUnion('kind', [
 		kind: z.literal('form'),
 		path: name,
 		appendTo: name,
-		rate: z.strictObject({ perClient: formRate.optional(), perForm: formRate.optional() }).optional(),
+		rate: z.strictObject({ perClient: formRate.optional(), perForm: formRate.optional(), bytesPerHour: z.int().positive().optional() }).optional(),
 		honeypot: name.optional(),
 		challenge: z.strictObject({ provider: z.literal('turnstile'), secret: applicationVariable, siteKey: applicationVariable.optional() }).optional(),
 		then: name.optional(),
+		files: z.record(name, z.strictObject({ collection: name, required: z.boolean() })).optional(),
 	}),
 	z.strictObject({ kind: z.literal('webhook'), path: name, scheme: z.literal('github-sha256'), boundTo: scopeBinding, actions }),
 ])

package/src/contract/build.ts

@@ -25,6 +25,7 @@ import {
 	type ExportArtifact,
 	type FileCollectionArtifact,
 	type FormChallenge,
+	type FormFileArtifact,
 	type FormMountArtifact,
 	type FormRate,
 	type ImportArtifact,
@@ -82,7 +83,10 @@ import {
 	fileCollectionPaths,
 	FILES_PREFIX,
 	FORM_CHALLENGE_FIELD,
+	FORM_FILE_LIMITS,
+	FORM_INPUT_PART,
 	FORM_LIMITS,
+	FORM_MULTIPART_TYPE,
 	joinPath,
 	JSON_ADMISSION,
 	LINK_API_SEGMENT,
@@ -121,6 +125,8 @@ const DECLARED_ALLOWED =
 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_]*$/
+/** A form's file field names the inbox column its file's id lands in. */
+const FORM_FILE_FIELD = /^[a-z_][a-z0-9_]*$/
 /** Turnstile's `action`: the form's name, which the verification expects back. */
 const CHALLENGE_ACTION = /^[A-Za-z0-9_-]{1,32}$/
 
@@ -524,26 +530,29 @@ class ArtifactBuilder {
 				this.#prefix(where, mount.path)
 				this.#anonymous(name, 'health', 'GET', mount.path, null, null)
 				return { kind: 'health', path: mount.path }
-			case 'form':
+			case 'form': {
 				this.#prefix(where, mount.path)
 				this.#objectSchema(`${where} input`, mount.input)
 				this.#nonEmpty(`${where} appendTo`, mount.appendTo)
-				this.#anonymous(
-					name,
-					'form',
-					'POST',
-					mount.path,
-					this.#bodyLimit(where, mount.maxBytes, CONTRACT_DEFAULTS.formMaxBytes),
-					mount.input,
-					this.#crossOrigin(where, mount.crossOrigin, true),
-				)
+				const files = mount.files === undefined ? null : this.#formFiles(where, mount, mount.files)
+				this.#formByteBudget(where, mount, files)
+				const limit = this.#bodyLimit(where, mount.maxBytes, CONTRACT_DEFAULTS.formMaxBytes)
+				// A form that takes files is multipart: `maxBytes` bounds its input part, each collection its file. While no
+				// file is required it also takes the JSON body it took before, so its existing pages keep working.
+				const optional = files !== null && Object.values(files).every((file) => !file.required)
+				const admission: BodyAdmission = files === null
+					? limit
+					: { contentTypes: optional ? ['application/json', FORM_MULTIPART_TYPE] : [FORM_MULTIPART_TYPE], maxBytes: limit.maxBytes }
+				this.#anonymous(name, 'form', 'POST', mount.path, admission, mount.input, this.#crossOrigin(where, mount.crossOrigin, true))
 				return {
 					kind: 'form',
 					path: mount.path,
 					appendTo: mount.appendTo,
 					...this.#formAdmission(name, where, mount),
 					...(mount.then === undefined ? {} : { then: this.#kickedJob(where, mount.then) }),
+					...(files === null ? {} : { files }),
 				}
+			}
 			case 'webhook': {
 				this.#prefix(where, mount.path)
 				this.#objectSchema(`${where} input`, mount.input)
@@ -608,9 +617,92 @@ class ArtifactBuilder {
 		return admission
 	}
 
+	/**
+	 * A form's file fields: at most `FORM_FILE_LIMITS.maxFields`, each a lowercase column name that no input field, the
+	 * honeypot, the challenge token or the input part takes, each landing in a declared collection that scans. An
+	 * anonymous visitor's file reaches the people who read the collection, so the form must declare a challenge too.
+	 */
+	#formFiles(where: string, mount: FormMountDeclaration<SchemaShape>, declared: unknown): Readonly<Record<string, FormFileArtifact>> | null {
+		const example = "files: { photo: { collection: '<a c.files collection with scan: true>' } }"
+		if (typeof declared !== 'object' || declared === null || Array.isArray(declared)) {
+			this.#problem(where, `files is not an object of file fields (allowed: ${example})`)
+			return null
+		}
+		const entries = Object.entries(declared)
+		if (entries.length === 0 || entries.length > FORM_FILE_LIMITS.maxFields) {
+			this.#problem(where, `files declares ${entries.length} file fields (allowed: 1 to ${FORM_FILE_LIMITS.maxFields}, one file each)`)
+		}
+		if (mount.challenge === undefined) {
+			this.#problem(where, "takes files, so it declares a challenge: an anonymous upload needs a solved one (challenge: { provider: 'turnstile', … })")
+		}
+		const fields = mount.input.type === 'object' ? mount.input.fields : {}
+		const files: Record<string, FormFileArtifact> = {}
+		for (const [field, option] of entries) {
+			const at = `${where} file '${field}'`
+			if (!FORM_FILE_FIELD.test(field)) {
+				this.#problem(at, 'is not a column name (allowed: lowercase snake_case, as its inbox column is named)')
+			}
+			if (field === FORM_INPUT_PART || field === FORM_CHALLENGE_FIELD || field === mount.honeypot || Object.hasOwn(fields, field)) {
+				this.#problem(at, `is also the name of the input part, the challenge token, the honeypot or an input field; name the file its own field`)
+			}
+			if (typeof option !== 'object' || option === null || Array.isArray(option)) {
+				this.#problem(at, `is not { collection, required? } (allowed: ${example})`)
+				continue
+			}
+			this.#keys(at, option, ['collection', 'required'])
+			const collection: unknown = Reflect.get(option, 'collection')
+			const required: unknown = Reflect.get(option, 'required')
+			if (required !== undefined && typeof required !== 'boolean') {
+				this.#problem(at, `required ${JSON.stringify(required)} is not true or false`)
+			}
+			const collections = this.#contract.files
+			const target: { readonly kind: string; readonly scan?: boolean } | undefined =
+				typeof collection === 'string' && Object.hasOwn(collections, collection) ? collections[collection] : undefined
+			if (typeof collection !== 'string' || target === undefined || target.kind !== 'files') {
+				const names = Object.keys(collections)
+				this.#problem(
+					at,
+					`collection ${JSON.stringify(collection)} is not a file collection of the contract (collections: ${
+						names.length === 0 ? 'none' : names.join(', ')
+					})`,
+				)
+				continue
+			}
+			if (target.scan !== true) {
+				this.#problem(at, `lands in files '${collection}', which does not scan; an anonymous visitor's file waits for a clean verdict (scan: true)`)
+			}
+			files[field] = { collection, required: required === true }
+		}
+		return files
+	}
+
+	/** `bytesPerHour` belongs to a form with files, and fits at least the largest file one of its fields admits. */
+	#formByteBudget(where: string, mount: FormMountDeclaration<SchemaShape>, files: Readonly<Record<string, FormFileArtifact>> | null): void {
+		const declared: unknown = typeof mount.rate === 'object' && mount.rate !== null ? Reflect.get(mount.rate, 'bytesPerHour') : undefined
+		if (declared === undefined) {
+			return
+		}
+		if (files === null) {
+			this.#problem(where, 'declares rate.bytesPerHour and takes no files (allowed: on a form with files)')
+			return
+		}
+		const largest = Math.max(...Object.values(files).map((file) => this.#contract.files[file.collection]?.maxBytes ?? 0))
+		if (typeof declared === 'number' && declared < largest) {
+			this.#problem(where, `rate.bytesPerHour ${declared} is less than the ${largest} bytes one of its files may hold`)
+		}
+	}
+
 	#formRate(where: string, rate: object): FormRate {
-		this.#keys(where, rate, ['perClient', 'perForm'])
-		const parsed: { perClient?: number; perForm?: number } = {}
+		this.#keys(where, rate, ['perClient', 'perForm', 'bytesPerHour'])
+		const parsed: { perClient?: number; perForm?: number; bytesPerHour?: number } = {}
+		const bytes: unknown = Reflect.get(rate, 'bytesPerHour')
+		if (bytes !== undefined) {
+			if (typeof bytes !== 'number' || !Number.isSafeInteger(bytes) || bytes < 1 || bytes > FORM_FILE_LIMITS.maxBytesPerHour) {
+				this.#problem(where, `bytesPerHour ${String(bytes)} is not a whole number of bytes from 1 to ${FORM_FILE_LIMITS.maxBytesPerHour}`)
+			} else {
+				parsed.bytesPerHour = bytes
+			}
+		}
 		for (const key of ['perClient', 'perForm'] as const) {
 			const value: unknown = Reflect.get(rate, key)
 			if (value === undefined) {
@@ -1782,14 +1874,15 @@ class ArtifactBuilder {
 		if (columns === undefined || mount.input.type !== 'object') {
 			return
 		}
-		for (const field of Object.keys(mount.input.fields)) {
+		const fileFields = typeof mount.files === 'object' && mount.files !== null ? Object.keys(mount.files) : []
+		for (const field of [...Object.keys(mount.input.fields), ...fileFields]) {
 			const exempt = field === mount.honeypot || (mount.challenge !== undefined && field === FORM_CHALLENGE_FIELD)
 			if (!exempt && !columns.includes(field)) {
 				this.#problem(
 					`mount '${name}'`,
-					`the input field '${field}' is not a column of its inbox ${mount.appendTo}${suggestion(field, columns)} (allowed: a field named like a column: ${
-						columns.join(', ')
-					})`,
+					`the ${fileFields.includes(field) ? 'file' : 'input'} field '${field}' is not a column of its inbox ${mount.appendTo}${
+						suggestion(field, columns)
+					} (allowed: a field named like a column: ${columns.join(', ')})`,
 				)
 			}
 		}

package/src/contract/context.ts

@@ -18,7 +18,7 @@ import type {
 	WithinTables,
 } from '@fabrika/db/tables'
 import type { z } from 'zod/v4'
-import type { FileCollectionHandle, FileCollectionReadHandle, FileCollections } from '../files/handle'
+import type { FileCollectionHandle, FileCollectionJobHandle, FileCollectionReadHandle, FileCollections } from '../files/handle'
 import type { AppCapability, Ref, Within } from '../implement/capability'
 import type { ApplicationDirectory, LinkIssuing, MemberDirectory, MemberLookup, MemberManagement } from '../implement/membership'
 import type { AppPrincipal, PrincipalOf, ServicePrincipal } from '../implement/principal'
@@ -135,12 +135,14 @@ type SqlContext<S, Ix extends AnyDbIndex> = {
 }
 
 /** `ctx.files(<collection>)`: removal where the site writes (a mutation, a job's transaction), reading everywhere. */
-type FilesContext<Ix, K extends DataKind> = {
+type FilesContext<Ix, K extends DataKind | 'transaction'> = {
 	readonly files: Ix extends NoTablesIndex ? Unavailable<'this application declares no tables, so it has no file collections'>
-		: FileCollections<K extends 'mutation' ? FileCollectionHandle : FileCollectionReadHandle<RemovesIn<K>>>
+		: FileCollections<
+			K extends 'transaction' ? FileCollectionJobHandle : K extends 'mutation' ? FileCollectionHandle : FileCollectionReadHandle<RemovesIn<K>>
+		>
 }
 
-type RemovesIn<K extends DataKind> = K extends 'job' ? 'a job removes files inside ctx.transaction((tx) => …), as tx.files'
+type RemovesIn<K extends DataKind | 'transaction'> = K extends 'job' ? 'a job removes files inside ctx.transaction((tx) => …), as tx.files'
 	: 'a query reads only; remove files in a mutation'
 
 type UnscopedData<Ix extends AnyDbIndex, U, K extends DataKind> = {
@@ -395,7 +397,14 @@ type SiteData<Ix extends AnyDbIndex, Kind extends DataKind, Acts extends 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'>
+	& FilesContext<K['index'], 'transaction'>
+	& {
+		/**
+		 * `ctx.ref`, located in this transaction: an object it wrote is found before the commit, so the same transaction
+		 * attaches a form's file to the record it just created.
+		 */
+		ref<const Act extends A, const Dim extends K['dimension']>(action: Act, dimension: Dim, id: string): Promise<Ref<Dim, Act>>
+	}
 
 /**
  * `ctx.links` of a cron job that declares the link mount it issues (`issues: '<mount>'`): a link for an object the job

package/src/contract/declaration.ts

@@ -51,7 +51,7 @@ export const BUILDER_FIELDS: Readonly<Record<Builder, BuilderFields>> = {
 	rpc: { options: ['callers'], owned: ['kind', 'prefix', 'procedures'] },
 	link: { options: ['spa', 'dimension', 'grants', 'issuedBy', 'maxDays', 'procedures'], owned: ['kind', 'prefix'] },
 	spa: { options: ['dir', 'access', 'public'], owned: ['kind', 'prefix'] },
-	form: { options: ['input', 'appendTo', 'maxBytes', 'rate', 'honeypot', 'challenge', 'then', 'crossOrigin'], owned: ['kind', 'path'] },
+	form: { options: ['input', 'appendTo', 'maxBytes', 'rate', 'honeypot', 'challenge', 'then', 'crossOrigin', 'files'], owned: ['kind', 'path'] },
 	webhook: { options: ['scheme', 'boundTo', 'actions', 'input', 'maxBytes'], owned: ['kind', 'path'] },
 	files: { options: ['owner', 'read', 'write', 'delete', 'maxBytes', 'types', 'maxPerOwner', 'link', 'scan'], owned: ['kind'] },
 	cron: { options: ['actions', 'scope', 'timeout', 'retries'], owned: ['kind', 'schedule'] },
@@ -228,8 +228,11 @@ export interface FormMountDeclaration<S> extends OptionsRecord {
 	readonly input: S
 	readonly appendTo: string
 	readonly maxBytes?: number
-	/** Submissions per minute from one client and accepted in all; `FORM_LIMITS` holds the defaults. */
-	readonly rate?: { readonly perClient?: number; readonly perForm?: number }
+	/**
+	 * Submissions per minute from one client and accepted in all, and the bytes a form with files writes per hour;
+	 * `FORM_LIMITS` and `FORM_FILE_LIMITS` hold the defaults.
+	 */
+	readonly rate?: { readonly perClient?: number; readonly perForm?: number; readonly bytesPerHour?: number }
 	/** An input field that must stay empty. */
 	readonly honeypot?: string
 	/**
@@ -241,6 +244,8 @@ export interface FormMountDeclaration<S> extends OptionsRecord {
 	readonly then?: string
 	/** `true` (the environment's listed origins) or `'*'` (any origin), as written; `buildArtifact` refuses anything else. */
 	readonly crossOrigin?: unknown
+	/** The file fields, by name: `{ collection, required? }` each, as written; `buildArtifact` checks them. */
+	readonly files?: unknown
 }
 
 export interface WebhookMountDeclaration<S> extends OptionsRecord {