@fabrika/db 0.5.4 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/db",
-	"version": "0.5.4",
+	"version": "0.6.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -61,8 +61,8 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/auth-core": "0.5.4",
-		"@fabrika/platform-node": "0.5.4",
+		"@fabrika/auth-core": "0.6.0",
+		"@fabrika/platform-node": "0.6.0",
 		"kysely": "0.29.6",
 		"kysely-postgres-js": "5.0.1",
 		"zod": "^3.25.76"

package/src/file-tables.ts

@@ -53,6 +53,18 @@ export interface PendingFile {
 	readonly createdAt: Date
 }
 
+/** A file whose object was written before it had an owner (a form's): `adopt` gives it one. */
+export interface AdoptedFile {
+	readonly id: string
+	readonly objectKey: string
+	readonly size: number
+	readonly sha256: string
+	readonly contentType: string
+	readonly originalName: string | null
+	/** When its object was received. */
+	readonly createdAt: Date
+}
+
 /** A file whose upload completed: served when `live`, `409` while `quarantined`, gone when `rejected`. */
 export type HeldStatus = Exclude<FileStatus, 'pending'>
 
@@ -112,8 +124,16 @@ export interface FileCollectionTable {
 	complete(owner: unknown, id: string, written: { readonly size: number; readonly sha256: string }, status: 'live' | 'quarantined'): Promise<void>
 	/** Deletes the caller's own pending row once its object is gone. */
 	abandon(id: string): Promise<void>
+	/**
+	 * Locks the owner where `owner` (a `Ref` for the write action) says it lies and inserts a held row for a file whose
+	 * object already exists, in `using`: `quarantined` in a scanning collection, so the scan job decides about it, else
+	 * `live`. The owner's held files are counted under that lock, so two adoptions never both pass `maxPerOwner`
+	 * (`null`: no limit); `limit`, with nothing inserted, when the owner holds that many. `NotFoundError` when the owner
+	 * is not there.
+	 */
+	adopt(owner: unknown, file: AdoptedFile, using: Session, maxPerOwner: number | null): Promise<'adopted' | 'limit'>
 	/** The owner's files that hold a place in its quota: live, quarantined and rejected, until removed. */
-	countHeld(owner: unknown): Promise<number>
+	countHeld(owner: unknown, using?: Session): Promise<number>
 	/** Marks a held file of `owner` removed. */
 	retract(owner: unknown, id: string, at: Date): Promise<void>
 	/**
@@ -381,14 +401,39 @@ function collectionTable(models: TableModels, runtime: () => DataLayerRuntime, s
 			await session().run(deleteNode(table, where, 'id'), guard('DeleteQueryNode', table, scope))
 		},
 
-		async countHeld(capability: unknown): Promise<number> {
+		async adopt(capability: unknown, file: AdoptedFile, transaction: Session, maxPerOwner: number | null): Promise<'adopted' | 'limit'> {
+			const grant = grantOf(capability, owner.dimension, spec.actions.write)
+			const values = new Map<string, string | number | Date | null>([['id', file.id]])
+			for (const { link, value } of linkValues(table, fileOwnerLinks, grant)) {
+				values.set(link.column, value)
+			}
+			values.set('status', spec.scan ? 'quarantined' : 'live')
+			values.set('object_key', file.objectKey)
+			values.set('size', file.size)
+			values.set('content_type', file.contentType)
+			values.set('sha256', file.sha256)
+			values.set('original_name', file.originalName)
+			values.set('created_by', grant.principal)
+			values.set('created_at', file.createdAt)
+			if (spec.scan) {
+				values.set('scan_after', new Date())
+			}
+			await lockOwner(transaction, grant)
+			if (maxPerOwner !== null && (await this.countHeld(capability, transaction)) >= maxPerOwner) {
+				return 'limit'
+			}
+			await transaction.run(insertNode(table, values, acknowledgement(table, 'id', undefined)), guard('InsertQueryNode', table, undefined))
+			return 'adopted'
+		},
+
+		async countHeld(capability: unknown, using?: Session): Promise<number> {
 			const grant = grantOf(capability, owner.dimension, spec.actions.write)
 			const scope = linksPredicate(table, linkValues(table, fileOwnerLinks, grant))
 			const count = SelectionNode.create(
 				AliasNode.create(AggregateFunctionNode.create('count', [SelectAllNode.create()]), IdentifierNode.create('count')),
 			)
 			const conditions = allOf([isHeld(), isNull(table, 'deleted_at', false)])
-			const [row] = await session().run<Readonly<Record<string, unknown>>>(
+			const [row] = await (using ?? session()).run<Readonly<Record<string, unknown>>>(
 				selectNode(table, [count], conditions, scope),
 				guard('SelectQueryNode', table, scope),
 			)

package/src/form-admissions.ts

@@ -6,7 +6,7 @@
 
 import { runFixedStatement, type Session, sessionOf } from './database'
 import { QueryRefusedError } from './errors'
-import { FORM_ADMISSIONS_TABLE, FORM_CHALLENGES_TABLE } from './migrations'
+import { FORM_ADMISSIONS_TABLE, FORM_BYTES_TABLE, FORM_CHALLENGES_TABLE } from './migrations'
 import type { DataLayerRuntime } from './store'
 
 /** The bucket of `fabrika_form_admissions` an inbox append takes from, in the append's own transaction. */
@@ -26,6 +26,13 @@ export interface FormAdmissions {
 	 * recorded and has not expired, which makes the token's second use a replay.
 	 */
 	recordChallenge(form: string, tokenDigest: string, retainMs: number): Promise<boolean>
+	/**
+	 * Reserves `bytes` of `form`'s hourly byte budget `limit`, in the database's current hour; `false`, with nothing
+	 * taken, when they no longer fit. The check and the counter are one statement.
+	 */
+	reserveBytes(form: string, bytes: number, limit: number): Promise<boolean>
+	/** Gives back `bytes` of a reservation of the current hour that a written file did not need. */
+	releaseBytes(form: string, bytes: number): Promise<void>
 }
 
 const A = FORM_ADMISSIONS_TABLE
@@ -46,6 +53,21 @@ insert into ${A} (form, bucket, window_start, count) values ($1, $2, date_trunc(
 on conflict (form, bucket, window_start) do update set count = ${A}.count + 1 where ${A}.count < $3::int
 returning count`
 
+const B = FORM_BYTES_TABLE
+
+const SQL_RESERVE_BYTES = `with pruned as (
+	delete from ${B} where (form, window_start) in (
+		select form, window_start from ${B} where window_start < date_trunc('hour', now())
+		limit ${PRUNE_BATCH} for update skip locked
+	)
+)
+insert into ${B} (form, window_start, bytes) select $1, date_trunc('hour', now()), $2::bigint where $2::bigint <= $3::bigint
+on conflict (form, window_start) do update set bytes = ${B}.bytes + excluded.bytes where ${B}.bytes + excluded.bytes <= $3::bigint
+returning bytes`
+
+const SQL_RELEASE_BYTES = `update ${B} set bytes = greatest(bytes - $2::bigint, 0)
+where form = $1 and window_start = date_trunc('hour', now()) returning bytes`
+
 const SQL_RECORD_CHALLENGE = `with pruned as (
 	delete from ${C} where (form, token_digest) in (
 		select form, token_digest from ${C} where expires_at <= now() and (form, token_digest) <> ($1, $2)
@@ -78,5 +100,20 @@ export function formAdmissions(runtime: () => DataLayerRuntime): FormAdmissions
 			const rows = await runFixedStatement(session(), SQL_RECORD_CHALLENGE, [form, tokenDigest, positiveInteger(retainMs, 'a retention')])
 			return rows.length > 0
 		},
+
+		async reserveBytes(form: string, bytes: number, limit: number): Promise<boolean> {
+			const rows = await runFixedStatement(session(), SQL_RESERVE_BYTES, [
+				form,
+				positiveInteger(bytes, 'a reservation'),
+				positiveInteger(limit, 'a byte budget'),
+			])
+			return rows.length > 0
+		},
+
+		async releaseBytes(form: string, bytes: number): Promise<void> {
+			if (bytes > 0) {
+				await runFixedStatement(session(), SQL_RELEASE_BYTES, [form, positiveInteger(bytes, 'a release')])
+			}
+		},
 	})
 }

package/src/form-files.ts

@@ -0,0 +1,226 @@
+// The framework's side of `fabrika_form_files` (`@fabrika/db/migrations`): the files a form received with a submission,
+// before anything owns them. A row is written `pending` before its object, so it is the intent to clean that object up;
+// the submission's inbox append makes it `held` in the inbox row's own transaction (`holdFormFiles`), and the job that
+// drains the inbox claims it in the transaction that writes its owner, where `@fabrika/app` moves it into the
+// collection's own table. Nothing serves a row of this table. Each operation is one fixed statement on the database's
+// clock, reached only through `frameworkTablesOf`.
+
+import { type FixedParameter, runFixedStatement, type Session, sessionOf } from './database'
+import { QueryRefusedError } from './errors'
+import { FORM_FILES_TABLE } from './migrations'
+import type { DataLayerRuntime } from './store'
+
+const F = FORM_FILES_TABLE
+
+/** A file a form is about to write: its row comes first, then the object under `objectKey`. */
+export interface StagedFormFile {
+	readonly id: string
+	readonly form: string
+	readonly collection: string
+	readonly objectKey: string
+	readonly contentType: string
+	readonly originalName: string | null
+}
+
+/** What writing a staged file's object recorded: its size and the SHA-256 of its bytes. */
+export interface WrittenFormFile {
+	readonly id: string
+	readonly size: number
+	readonly sha256: string
+}
+
+/** The files a submission holds once its inbox row commits, and how long they wait for their owner. */
+export interface HeldFormFiles {
+	readonly files: readonly WrittenFormFile[]
+	readonly holdMs: number
+}
+
+/** A held file a claim took out of the table: what the collection's own row records of it. */
+export interface ClaimedFormFile {
+	readonly id: string
+	readonly objectKey: string
+	readonly size: number
+	readonly sha256: string
+	readonly contentType: string
+	readonly originalName: string | null
+	readonly createdAt: Date
+}
+
+export interface RemovableFormFile {
+	readonly id: string
+	readonly objectKey: string
+}
+
+export interface FormFiles {
+	/** Inserts the `pending` row of a file whose object is written next: the intent to clean that object up. */
+	stage(file: StagedFormFile): Promise<void>
+	/** Deletes a `pending` row once its object is gone; a held row stays. */
+	abandon(id: string): Promise<void>
+	/**
+	 * Takes the held file `id` of `collection` out of the table, in `using` (the transaction that writes its owner), and
+	 * answers it; `null` when there is none: never received, of another collection, already claimed, or its hold ended.
+	 */
+	claim(collection: string, id: string, using: Session): Promise<ClaimedFormFile | null>
+	/** At most `limit` rows whose objects may go: held past their hold, or pending for longer than `pendingGraceMs`. */
+	removable(limit: number, pendingGraceMs: number): Promise<readonly RemovableFormFile[]>
+	/** Deletes a removable row once its object is gone; a row that is held or recently pending is never deleted. */
+	purge(id: string, pendingGraceMs: number): Promise<void>
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+/**
+ * Removable: held for an hour past its hold, or pending for longer than the grace in parameter `$<grace>`. The hour
+ * keeps the sweep off a file a job's transaction, which started before the hold ended, may still claim.
+ */
+const removable = (grace: number): string =>
+	`(status = 'pending' and created_at < now() - $${grace}::bigint * interval '1 millisecond')
+	or (status = 'held' and held_until <= now() - interval '1 hour')`
+
+const SQL_STAGE = `insert into ${F} (id, form, collection, status, object_key, content_type, original_name, created_at)
+values ($1::uuid, $2, $3, 'pending', $4, $5, $6, now()) returning id`
+
+const SQL_ABANDON = `delete from ${F} where id = $1::uuid and status = 'pending' returning id`
+
+/** Every file of a submission at once: ids, sizes and digests as comma-separated lists, in the same order. */
+const SQL_HOLD = `update ${F} as f set status = 'held', size = v.size, sha256 = v.sha256,
+	held_until = now() + $4::bigint * interval '1 millisecond'
+from unnest(string_to_array($1, ',')::uuid[], string_to_array($2, ',')::bigint[], string_to_array($3, ',')) as v (id, size, sha256)
+where f.id = v.id and f.status = 'pending' returning f.id`
+
+// The clock of the statement, not of the transaction: a job's transaction may have started before the hold ended.
+const SQL_CLAIM = `delete from ${F} where id = $1::uuid and collection = $2 and status = 'held' and held_until > clock_timestamp()
+returning id::text as id, object_key, size, sha256, content_type, original_name, created_at`
+
+const SQL_REMOVABLE = `select id::text as id, object_key from ${F} where ${removable(1)} order by created_at limit $2::int`
+
+const SQL_PURGE = `delete from ${F} where id = $1::uuid and (${removable(2)}) returning id`
+
+function positive(value: number, what: string): number {
+	if (!Number.isSafeInteger(value) || value < 1) {
+		throw new QueryRefusedError('invalid_argument', `${what} must be a whole number of at least 1`)
+	}
+	return value
+}
+
+function nonNegative(value: number, what: string): number {
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw new QueryRefusedError('invalid_argument', `${what} must be a whole number`)
+	}
+	return value
+}
+
+function sha256(value: string): string {
+	if (!/^[0-9a-f]{64}$/.test(value)) {
+		throw new QueryRefusedError('invalid_argument', 'a form file is recorded with the hex SHA-256 of its bytes')
+	}
+	return value
+}
+
+function uuid(value: string): string {
+	if (!UUID.test(value)) {
+		throw new QueryRefusedError('invalid_argument', 'a form file is named by its UUID')
+	}
+	return value
+}
+
+function record(row: unknown): Readonly<Record<string, unknown>> {
+	if (typeof row !== 'object' || row === null) {
+		throw new QueryRefusedError('unexpected_row', `${F} answered a row that is not an object`)
+	}
+	return Object.fromEntries(Object.entries(row))
+}
+
+function text(row: Readonly<Record<string, unknown>>, column: string): string {
+	const value = row[column]
+	if (typeof value !== 'string') {
+		throw new QueryRefusedError('unexpected_row', `${F}.${column} came back as ${typeof value}`)
+	}
+	return value
+}
+
+/** BIGINT comes back as a string. */
+function size(row: Readonly<Record<string, unknown>>): number {
+	const value = Number(row['size'])
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw new QueryRefusedError('unexpected_row', `${F}.size is not a non-negative integer`)
+	}
+	return value
+}
+
+/**
+ * Makes every file of a submission `held`, in `session`: the transaction that appends its inbox row, so a row that does
+ * not commit leaves its files pending for the form to clean up. A file that is no longer pending fails the transaction.
+ */
+export async function holdFormFiles(session: Session, held: HeldFormFiles): Promise<void> {
+	if (held.files.length === 0) {
+		return
+	}
+	const parameters: FixedParameter[] = [
+		held.files.map((file) => uuid(file.id)).join(','),
+		held.files.map((file) => nonNegative(file.size, 'a form file size')).join(','),
+		held.files.map((file) => sha256(file.sha256)).join(','),
+		positive(held.holdMs, 'a form file hold'),
+	]
+	const rows = await runFixedStatement(session, SQL_HOLD, parameters)
+	if (rows.length !== held.files.length) {
+		throw new QueryRefusedError('unexpected_row', 'a form file is no longer pending; the submission writes nothing')
+	}
+}
+
+export function formFiles(runtime: () => DataLayerRuntime): FormFiles {
+	const session = () => sessionOf(runtime())
+	return Object.freeze({
+		async stage(file: StagedFormFile): Promise<void> {
+			await runFixedStatement(session(), SQL_STAGE, [
+				uuid(file.id),
+				file.form,
+				file.collection,
+				file.objectKey,
+				file.contentType,
+				file.originalName,
+			])
+		},
+
+		async abandon(id: string): Promise<void> {
+			await runFixedStatement(session(), SQL_ABANDON, [uuid(id)])
+		},
+
+		async claim(collection: string, id: string, using: Session): Promise<ClaimedFormFile | null> {
+			if (!UUID.test(id)) {
+				return null
+			}
+			const [found] = await runFixedStatement(using, SQL_CLAIM, [id, collection])
+			if (found === undefined) {
+				return null
+			}
+			const row = record(found)
+			const createdAt = row['created_at']
+			if (!(createdAt instanceof Date)) {
+				throw new QueryRefusedError('unexpected_row', `${F}.created_at came back as ${typeof createdAt}`)
+			}
+			const name = row['original_name']
+			return Object.freeze({
+				id: text(row, 'id'),
+				objectKey: text(row, 'object_key'),
+				size: size(row),
+				sha256: text(row, 'sha256'),
+				contentType: text(row, 'content_type'),
+				originalName: typeof name === 'string' ? name : null,
+				createdAt,
+			})
+		},
+
+		async removable(limit: number, pendingGraceMs: number): Promise<readonly RemovableFormFile[]> {
+			const rows = await runFixedStatement(session(), SQL_REMOVABLE, [positive(pendingGraceMs, 'a pending grace'), positive(limit, 'a batch')])
+			return rows.map((found) => {
+				const row = record(found)
+				return Object.freeze({ id: text(row, 'id'), objectKey: text(row, 'object_key') })
+			})
+		},
+
+		async purge(id: string, pendingGraceMs: number): Promise<void> {
+			await runFixedStatement(session(), SQL_PURGE, [uuid(id), positive(pendingGraceMs, 'a pending grace')])
+		},
+	})
+}

package/src/framework.ts

@@ -20,6 +20,7 @@ export {
 } from './errors'
 export { fileTableName } from './file-table-sql'
 export type {
+	AdoptedFile,
 	FileCollectionSpec,
 	FileCollectionTable,
 	FilePage,
@@ -32,6 +33,7 @@ export type {
 	StoredFile,
 } from './file-tables'
 export type { FormAdmissions, InboxQuota } from './form-admissions'
+export type { ClaimedFormFile, FormFiles, HeldFormFiles, RemovableFormFile, StagedFormFile, WrittenFormFile } from './form-files'
 export type { NewWebhookBinding, WebhookBinding, WebhookTables } from './framework-tables'
 export type { JobLeases, JobLeaseState, JobOutcome, OverdueClaim } from './job-leases'
 export type { DataAccess, DataHandles, DataSite } from './orm'

package/src/migrations.ts

@@ -11,6 +11,8 @@ export const JOB_LEASES_TABLE = 'fabrika_job_leases'
 export const JOB_KICKS_TABLE = 'fabrika_job_kicks'
 export const FORM_ADMISSIONS_TABLE = 'fabrika_form_admissions'
 export const FORM_CHALLENGES_TABLE = 'fabrika_form_challenges'
+export const FORM_FILES_TABLE = 'fabrika_form_files'
+export const FORM_BYTES_TABLE = 'fabrika_form_bytes'
 
 export interface FrameworkMigration {
 	/** Ordered by name; an applied one is immutable, like an application's. */
@@ -92,6 +94,40 @@ CREATE TABLE ${JOB_KICKS_TABLE} (
 	job TEXT PRIMARY KEY,
 	pending BOOLEAN NOT NULL
 );
+`,
+	}),
+	Object.freeze({
+		name: '0005_form_files.sql',
+		sql: `-- A file a form received with a submission, owned by nobody and served by no endpoint. It is 'pending' from before
+-- its object (<collection>/<id>) is written until the submission's inbox row commits, then 'held' until held_until:
+-- the job that drains the inbox attaches it to its owner, which moves it into the collection's own table, or the
+-- sweep deletes its object and the row once the hold ended (a pending row once it is an hour old).
+CREATE TABLE ${FORM_FILES_TABLE} (
+	id UUID PRIMARY KEY,
+	form TEXT NOT NULL,
+	collection TEXT NOT NULL,
+	status TEXT NOT NULL CONSTRAINT ${FORM_FILES_TABLE}_status CHECK (status IN ('pending', 'held')),
+	object_key TEXT NOT NULL UNIQUE,
+	size BIGINT,
+	sha256 TEXT,
+	content_type TEXT NOT NULL,
+	original_name TEXT,
+	created_at TIMESTAMPTZ NOT NULL,
+	held_until TIMESTAMPTZ
+);
+CREATE INDEX ${FORM_FILES_TABLE}_created_at ON ${FORM_FILES_TABLE} (created_at);
+`,
+	}),
+	Object.freeze({
+		name: '0006_form_bytes.sql',
+		sql: `-- The bytes a form's files may write per hour, shared by every instance: one row per form and hour, which the next
+-- reservation of a later hour prunes. A file reserves its collection's maxBytes before its object is written.
+CREATE TABLE ${FORM_BYTES_TABLE} (
+	form TEXT NOT NULL,
+	window_start TIMESTAMPTZ NOT NULL,
+	bytes BIGINT NOT NULL,
+	PRIMARY KEY (form, window_start)
+);
 `,
 	}),
 ])

package/src/registry.ts

@@ -2,15 +2,20 @@
 // `store.ts`, which registers and builds the framework's stores, `framework.ts`, which `@fabrika/app` alone imports, and `testing.ts`, which only test
 // files may import.
 
+import type { Session } from './database'
 import type { FileTables } from './file-tables'
 import type { FormAdmissions, InboxQuota } from './form-admissions'
+import type { FormFiles, HeldFormFiles } from './form-files'
 import type { WebhookTables } from './framework-tables'
 import type { JobLeases } from './job-leases'
 import type { DataAccess } from './orm'
 import type { DataLayerRuntime, TableContext, TableProbe } from './store'
 
-/** Answers what the framework's access check reads from the database: an object's containers, by dimension. */
-export type Locator = (dimension: string, id: string) => Promise<ReadonlyMap<string, string> | null>
+/**
+ * Answers what the framework's access check reads from the database: an object's containers, by dimension. `using` is
+ * the session to read in (a job's transaction, which sees the object it just wrote); a statement of its own otherwise.
+ */
+export type Locator = (dimension: string, id: string, using?: Session) => Promise<ReadonlyMap<string, string> | null>
 
 /** What the framework writes itself: a form's inbox row and its own `fabrika_*` tables. Usable once bound. */
 export interface FrameworkTables {
@@ -18,13 +23,16 @@ export interface FrameworkTables {
 	inboxProblems(form: string, fields: readonly string[]): readonly string[]
 	/**
 	 * Appends one row of `values` (column → value) to the inbox table of `form`, taking one from `quota` in the same
-	 * transaction; `false`, with nothing written, when the bucket is full.
+	 * transaction, and makes the submission's `held` files held in it too; `false`, with nothing written, when the
+	 * bucket is full.
 	 */
-	appendToInbox(form: string, values: Readonly<Record<string, unknown>>, quota: InboxQuota): Promise<boolean>
+	appendToInbox(form: string, values: Readonly<Record<string, unknown>>, quota: InboxQuota, held?: HeldFormFiles): Promise<boolean>
 	readonly webhooks: WebhookTables
 	readonly jobs: JobLeases
 	/** A form's admission counters and the challenge tokens it accepted. */
 	readonly forms: FormAdmissions
+	/** The files forms received, until the job that drains each inbox attaches them to their owner. */
+	readonly formFiles: FormFiles
 }
 
 export interface FrameworkSide {

package/src/store.ts

@@ -44,6 +44,7 @@ import {
 import { CapabilityError, ConflictError, NotFoundError, PolicyError, QueryRefusedError } from './errors'
 import { fileTables } from './file-tables'
 import { formAdmissions, type InboxQuota, takeFromBucket } from './form-admissions'
+import { formFiles, type HeldFormFiles, holdFormFiles } from './form-files'
 import { webhookTables } from './framework-tables'
 import type { ForeignKeyPair, GuardContext, RootKind } from './guard'
 import { fencedTransaction, jobLeases } from './job-leases'
@@ -1551,16 +1552,17 @@ export function scoped<DB, P>(tables: Tables<DB, P>): ScopedDatabase<DB, P> {
 			}
 			const bound: DataLayerRuntime = freeze({ database: runtime.database, capabilities: runtime.capabilities, readOnly: runtime.readOnly })
 			connection.runtime = bound
-			return async (dimension, id) => locateObject(models, bound, dimension, id)
+			return async (dimension, id, using) => locateObject(models, bound, dimension, id, using)
 		},
 		files: fileTables(models, () => runtimeOf(connection)),
 		framework: freeze({
 			inboxProblems: (form: string, fields: readonly string[]) => inboxProblems(models, form, fields),
-			appendToInbox: (form: string, values: Readonly<Record<string, unknown>>, quota: InboxQuota) =>
-				appendToInbox(models, runtimeOf(connection), form, values, quota),
+			appendToInbox: (form: string, values: Readonly<Record<string, unknown>>, quota: InboxQuota, held?: HeldFormFiles) =>
+				appendToInbox(models, runtimeOf(connection), form, values, quota, held),
 			webhooks: webhookTables(() => runtimeOf(connection)),
 			jobs: jobLeases(() => runtimeOf(connection)),
 			forms: formAdmissions(() => runtimeOf(connection)),
+			formFiles: formFiles(() => runtimeOf(connection)),
 		}),
 		data: dataAccess({
 			models,
@@ -1639,8 +1641,9 @@ function inboxProblems(models: TableModels, form: string, fields: readonly strin
 
 /**
  * One row of the form's declared fields, taken from the form's `quota` bucket in the same transaction: a row that
- * fails to insert gives its place back. `false`, with nothing written, when the bucket is full. An inbox answers
- * nothing, so the form reads nothing back.
+ * fails to insert gives its place back. The submission's files become held in that transaction too, so a row that does
+ * not commit holds none. `false`, with nothing written, when the bucket is full. An inbox answers nothing, so the form
+ * reads nothing back.
  */
 async function appendToInbox(
 	models: TableModels,
@@ -1648,6 +1651,7 @@ async function appendToInbox(
 	form: string,
 	values: Readonly<Record<string, unknown>>,
 	quota: InboxQuota,
+	held: HeldFormFiles | undefined,
 ): Promise<boolean> {
 	const inbox = inboxOf(models, form)
 	if (inbox === undefined) {
@@ -1664,6 +1668,9 @@ async function appendToInbox(
 			joins: {},
 			scope: undefined,
 		})
+		if (held !== undefined) {
+			await holdFormFiles(transaction, held)
+		}
 		return true
 	})
 }
@@ -1695,6 +1702,7 @@ async function locateObject(
 	runtime: DataLayerRuntime,
 	dimension: string,
 	id: string,
+	using: Session | undefined,
 ): Promise<ReadonlyMap<string, string> | null> {
 	const owner = locatedOwner(models, dimension)
 	if (typeof id !== 'string' || id.length === 0) {
@@ -1707,7 +1715,7 @@ async function locateObject(
 		columns[columns.length] = owner.chain[index]?.column ?? ''
 	}
 	const context: GuardContext = { root: 'SelectQueryNode', table: owner.name, joins: {}, scope }
-	const [row] = await sessionOf(runtime).run<Readonly<Record<string, unknown>>>(locateNode(owner.name, columns, scope), context)
+	const [row] = await (using ?? sessionOf(runtime)).run<Readonly<Record<string, unknown>>>(locateNode(owner.name, columns, scope), context)
 	if (row === undefined) {
 		return null
 	}