@fabrika/db 0.5.5 → 0.7.0

package/src/store.ts

@@ -1,5 +1,7 @@
 import { BinaryOperationNode, type OperationNode, OperatorNode, type ReturningNode, ValueNode } from 'kysely'
+import { admissions } from './admissions'
 import {
+	defineValue,
 	freeze,
 	hasOwn,
 	inSet,
@@ -42,9 +44,8 @@ import {
 	type TableShape,
 } from './description'
 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 { answerFiles, type FileBinding, fileValue, referenceFiles, rowScope, storedRowScope } from './file-columns'
+import { fileReference } from './file-references'
 import { webhookTables } from './framework-tables'
 import type { ForeignKeyPair, GuardContext, RootKind } from './guard'
 import { fencedTransaction, jobLeases } from './job-leases'
@@ -78,6 +79,7 @@ import {
 	type ContainerOf,
 	type DimensionOf,
 	type DimensionTableName,
+	includes,
 	type InsertValues,
 	type JoinableChildren,
 	type ListDimensionOf,
@@ -99,6 +101,7 @@ import {
 } from './policy'
 import { frameworkSideOf, type Locator, register } from './registry'
 import type { ScopeTerms, ScopeTest, ScopeUse } from './sql'
+import { storedFiles, storedFilesMetadata } from './stored-files'
 import { type TablePolicies, tablePolicies } from './tables'
 import { answerDays, dayInput, timestampInput } from './temporal'
 
@@ -161,25 +164,32 @@ export function listDimension(scope: DimensionScopeModel): string {
 	return scope.container?.dimension ?? scope.dimension
 }
 
-export function requiredAction(context: TableContext, operation: Operation): string {
-	const action = context.model.actions[operation]
-	if (action === undefined) {
+/** The actions that allow `operation` on the table, any one of them; throws when its policy declares none. */
+export function requiredActions(context: TableContext, operation: Operation): readonly string[] {
+	const actions = context.model.actions[operation]
+	if (actions.length === 0) {
 		throw new CapabilityError('undeclared_operation', `${context.model.name} allows no ${operation}; its policy declares no ${operation} action`)
 	}
-	return action
+	return actions
+}
+
+/** Refuses a capability whose action is not one of `operation`'s actions on the table. */
+export function checkAction(context: TableContext, operation: Operation, action: string): void {
+	const actions = requiredActions(context, operation)
+	if (!includes(actions, action)) {
+		throw new CapabilityError('wrong_action', `${operation} on ${context.model.name} requires ${actions.join(' or ')}; the capability holds ${action}`)
+	}
 }
 
 function checkGrant(context: TableContext, grant: RefGrant | WithinGrant, dimension: string, operation: Operation): void {
-	const action = requiredAction(context, operation)
+	requiredActions(context, operation)
 	if (grant.dimension !== dimension) {
 		throw new CapabilityError(
 			'wrong_capability',
 			`${operation} on ${context.model.name} needs a ${grant.kind} of ${dimension}, got a ${grant.kind} of ${grant.dimension}`,
 		)
 	}
-	if (grant.action !== action) {
-		throw new CapabilityError('wrong_action', `${operation} on ${context.model.name} requires ${action}; the capability holds ${grant.action}`)
-	}
+	checkAction(context, operation, grant.action)
 }
 
 function refGrant(context: TableContext, capability: unknown, dimension: string, operation: Operation): RefGrant {
@@ -292,8 +302,8 @@ export function childListPredicate(context: TableContext, capability: unknown, o
 		checkGrant(context, grant, scope.parent.dimension, operation)
 		return parentPredicate(context, grant)
 	}
-	if (grant.kind === 'app') {
-		throw new CapabilityError('wrong_capability', `a list of ${context.model.name} by its parent needs a Ref or a Within, got an app capability`)
+	if (grant.kind === 'app' || grant.kind === 'row') {
+		throw new CapabilityError('wrong_capability', `a list of ${context.model.name} by its parent needs a Ref or a Within, got ${describeGrant(grant)}`)
 	}
 	checkGrant(context, grant, listDimension(scope.parent), operation)
 	return withinPredicate(context.model, scope.parent.container?.column ?? scope.column, grant)
@@ -326,10 +336,7 @@ export function reachPredicate(context: TableContext, capability: unknown): Oper
 	if (grant.kind !== 'within') {
 		throw new CapabilityError('wrong_capability', `a list of ${table} needs a Within, got ${describeGrant(grant)}`)
 	}
-	const action = requiredAction(context, 'read')
-	if (grant.action !== action) {
-		throw new CapabilityError('wrong_action', `read on ${table} requires ${action}; the capability holds ${grant.action}`)
-	}
+	checkAction(context, 'read', grant.action)
 	const column = reachColumn(context.model, grant.dimension)
 	if (column === undefined) {
 		throw new CapabilityError(
@@ -355,21 +362,21 @@ function checkWriteTarget(context: TableContext, grant: CapabilityGrant, use: 'u
 	if (grant.kind !== 'app' && model.scope.mode === 'app') {
 		throw new CapabilityError('table_kind', `a scoped site writes no application table: ${statement} needs the capability of an app endpoint`)
 	}
-	const action = model.actions[use]
-	if (grant.action === action) {
+	const actions = model.actions[use]
+	if (includes(actions, grant.action)) {
 		return
 	}
 	const columnWrites: string[] = []
 	const updates = use === 'update' ? updateActions(model) : []
 	for (let index = 0; index < updates.length; index++) {
 		const write = updates[index]
-		if (write !== undefined && write !== action) columnWrites[columnWrites.length] = write
+		if (write !== undefined && !includes(actions, write)) columnWrites[columnWrites.length] = write
 	}
-	if (action === undefined && columnWrites.length === 0) {
+	if (actions.length === 0 && columnWrites.length === 0) {
 		throw new CapabilityError('undeclared_operation', `${statement}: its policy declares no ${use} action`)
 	}
-	if (!columnWrites.includes(grant.action)) {
-		const needs = action === undefined ? [] : [`its ${use} action ${action}`]
+	if (!includes(columnWrites, grant.action)) {
+		const needs = actions.length === 0 ? [] : [`its ${use} action ${actions.join(' or ')}`]
 		if (columnWrites.length > 0) needs[needs.length] = `a column's own write action (${columnWrites.join(', ')})`
 		throw new CapabilityError('wrong_action', `${statement} needs ${needs.join(' or ')}; the capability holds ${grant.action}`)
 	}
@@ -404,6 +411,9 @@ function checkWriteTarget(context: TableContext, grant: CapabilityGrant, use: 'u
 export function scopeTerms(context: TableContext, capability: unknown, use: ScopeUse, assigned?: readonly string[]): ScopeTerms {
 	const grant = runtimeOf(context.connection).capabilities.resolve(capability)
 	const model = context.model
+	if (grant.kind === 'row') {
+		throw new CapabilityError('wrong_capability', `ctx.sql.scope takes a Ref, a Within or an app capability, got ${describeGrant(grant)}`)
+	}
 	if (use !== 'read') {
 		checkWriteTarget(context, grant, use, assigned)
 	}
@@ -442,10 +452,10 @@ export function scopeTerms(context: TableContext, capability: unknown, use: Scop
 			`a Within of ${grant.dimension} does not reach ${model.name}: its containment chain does not hold ${grant.dimension}`,
 		)
 	}
-	if (use === 'read' && grant.action !== model.actions.read) {
+	if (use === 'read' && !includes(model.actions.read, grant.action)) {
 		throw new CapabilityError(
 			'wrong_action',
-			`a Within of ${grant.action} does not read ${model.name}: it reads with its read action ${model.actions.read}`,
+			`a Within of ${grant.action} does not read ${model.name}: it reads with its read action ${model.actions.read.join(' or ')}`,
 		)
 	}
 	if (grant.values === 'all') {
@@ -510,11 +520,14 @@ export type AppReach = 'rows' | 'counts'
 /** Refuses an `app` capability whose action does not reach `reach` of a dimension or child table. */
 function checkRecordReach(context: TableContext, grant: AppGrant, reach: AppReach): void {
 	const model = context.model
-	const { read, appRead, appCount } = model.actions
-	if (grant.action === read || includesName(appRead, grant.action) || (reach === 'counts' && includesName(appCount, grant.action))) {
+	const { appRead, appCount } = model.actions
+	const read = model.actions.read.join(' or ')
+	if (
+		includes(model.actions.read, grant.action) || includes(appRead, grant.action) || (reach === 'counts' && includes(appCount, grant.action))
+	) {
 		return
 	}
-	if (includesName(appCount, grant.action)) {
+	if (includes(appCount, grant.action)) {
 		throw new CapabilityError(
 			'wrong_action',
 			`an app capability of ${grant.action} only counts ${model.name} (its appCount): it reads no row, so list, aggregate and a scope fragment need its read action ${read}${
@@ -530,15 +543,6 @@ function checkRecordReach(context: TableContext, grant: AppGrant, reach: AppReac
 	)
 }
 
-function includesName(names: readonly string[], name: string): boolean {
-	for (let index = 0; index < names.length; index++) {
-		if (names[index] === name) {
-			return true
-		}
-	}
-	return false
-}
-
 /**
  * Refuses a table `ctx.db.app` does not list for the capability (`applicationTables` in `orm.ts`): it lists an
  * application table under any action the table names, and the rows of a dimension or child table under its read
@@ -609,10 +613,7 @@ function appGrant(context: TableContext, capability: unknown, operation: Operati
 		checkApplicationTable(context, operation)
 	}
 	checkAppReach(context, grant)
-	const action = requiredAction(context, operation)
-	if (grant.action !== action) {
-		throw new CapabilityError('wrong_action', `${operation} on ${table} requires ${action}; the capability holds ${grant.action}`)
-	}
+	checkAction(context, operation, grant.action)
 	return grant
 }
 
@@ -635,11 +636,11 @@ export function scopedApplicationRead(context: TableContext, capability: unknown
 	if (grant.kind === 'app') {
 		throw new CapabilityError('wrong_capability', `a read of ${model.name} from a scoped site needs a Ref or a Within, got ${describeGrant(grant)}`)
 	}
-	const read = requiredAction(context, 'read')
-	if (grant.action !== read) {
+	const read = requiredActions(context, 'read')
+	if (!includes(read, grant.action)) {
 		throw new CapabilityError(
 			'wrong_action',
-			`a scoped site reads ${model.name} with its read action ${read} only; the capability holds ${grant.action}`,
+			`a scoped site reads ${model.name} with its read action ${read.join(' or ')} only; the capability holds ${grant.action}`,
 		)
 	}
 	return everything()
@@ -652,6 +653,62 @@ export function appRowPredicate(context: TableContext, capability: unknown, key:
 	return appKeyPredicate(context.model, key)
 }
 
+/**
+ * What a claim of a queue table leases through `capability`: an application table's every row for an `app` capability,
+ * a dimension or child table's rows a `Within` lists. Either way its action is one of the table's update actions.
+ */
+export function claimScope(
+	context: TableContext,
+	capability: unknown,
+): { readonly grant: AppGrant | WithinGrant; readonly scope: OperationNode | undefined } {
+	const model = context.model
+	const grant = runtimeOf(context.connection).capabilities.resolve(capability)
+	if (model.queue === undefined) {
+		throw new CapabilityError('undeclared_operation', `${model.name} is not a queue table: its policy declares no queue`)
+	}
+	if (grant.kind === 'app') {
+		return { grant: appGrant(context, capability, 'update'), scope: everything() }
+	}
+	if (grant.kind !== 'within') {
+		throw new CapabilityError('wrong_capability', `a claim of ${model.name} needs a Within or an app capability, got ${describeGrant(grant)}`)
+	}
+	if (model.scope.mode === 'app') {
+		throw new CapabilityError('table_kind', `${model.name} is an application table: claim it through ctx.db.app`)
+	}
+	checkAction(context, 'update', grant.action)
+	const column = reachColumn(model, grant.dimension)
+	if (column === undefined) {
+		throw new CapabilityError(
+			'out_of_reach',
+			`a Within of ${grant.dimension} does not reach ${model.name}: its containment chain does not hold ${grant.dimension}`,
+		)
+	}
+	return { grant, scope: withinPredicate(model, column, grant) }
+}
+
+/**
+ * The one row a claim's `row.ref` names, for an action of `operation`: its key and every containment column it had when
+ * it was claimed, so a row moved since is not reached.
+ */
+export function claimedRowPredicate(context: TableContext, capability: unknown, operation: 'update' | 'delete'): OperationNode {
+	const model = context.model
+	const grant = runtimeOf(context.connection).capabilities.resolve(capability)
+	if (grant.kind !== 'row' || grant.table !== model.name) {
+		throw new CapabilityError('wrong_capability', `${operation} of a claimed ${model.name} row needs its row.ref, got ${describeGrant(grant)}`)
+	}
+	checkAction(context, operation, grant.action)
+	const terms: OperationNode[] = [equals(model.name, keyOf(model), grant.id)]
+	for (let index = 0; index < model.chain.length; index++) {
+		const link = model.chain[index]
+		const value = link === undefined ? undefined : grant.chain.get(link.column)
+		if (link === undefined || value === undefined) {
+			throw new CapabilityError('unenforceable', `the row.ref of ${model.name} carries no ${link?.column ?? 'containment'} value`)
+		}
+		terms[terms.length] = equals(model.name, link.column, value)
+	}
+	return allOf(terms)
+}
+
 /** The row of an application table `key` names. */
 export function appKeyPredicate(model: TableModel, key: unknown): OperationNode {
 	if (typeof key !== 'string' || key.length === 0) {
@@ -705,6 +762,8 @@ export interface Runner {
 	read(): Promise<Session>
 	/** Runs `work` in one transaction. */
 	write<T>(work: (transaction: Session) => Promise<T>): Promise<T>
+	/** Where file references are made and checked; a store's own runner has none, and its file columns read as ids. */
+	readonly files?: FileBinding
 }
 
 /**
@@ -717,6 +776,11 @@ export function fencedWork<T>(runtime: DataLayerRuntime, work: (transaction: Ses
 	return fence === null ? session.transaction(work) : fencedTransaction(session, fence, work)
 }
 
+/** The action a capability holds, which its operation's checks already admitted. */
+export function heldAction(context: TableContext, capability: unknown): string {
+	return runtimeOf(context.connection).capabilities.resolve(capability).action
+}
+
 function storeRunner(context: TableContext): Runner {
 	return {
 		read: async () => sessionOf(runtimeOf(context.connection)),
@@ -762,6 +826,10 @@ export function readValues(values: unknown, allowed: NameSet, what: 'insert' | '
 		if (value === undefined) {
 			continue
 		}
+		if (hasOwn(model.files, key)) {
+			copied.set(key, fileValue(model, key, value))
+			continue
+		}
 		if (value !== null && !isPrimitive(value)) {
 			throw new QueryRefusedError('invalid_argument', `${table}.${key} takes a plain value (string, number, bigint, boolean, Date or null)`)
 		}
@@ -817,8 +885,11 @@ async function selectRows<S>(
 	const run = storeRunner(context)
 	for (let index = 0; index < state.joins.length; index++) {
 		const join = state.joins[index]
-		if (join !== undefined && join.join.readAction !== action) {
-			throw new CapabilityError('wrong_action', `joining ${join.join.shape.table} requires ${join.join.readAction}; the capability holds ${action}`)
+		if (join !== undefined && !includes(join.join.readActions, action)) {
+			throw new CapabilityError(
+				'wrong_action',
+				`joining ${join.join.shape.table} requires ${join.join.readActions.join(' or ')}; the capability holds ${action}`,
+			)
 		}
 	}
 	if (scope === undefined) {
@@ -849,19 +920,68 @@ function joinedDays(own: NameSet, state: SelectState): NameSet {
 	return nameSet(names)
 }
 
-/** One row by its scope predicate, with `visible` columns (the table's read action's, unless a capability reads its own). */
-export async function selectOne<O>(context: TableContext, run: Runner, scope: OperationNode, visible = context.model.visible): Promise<O> {
+/**
+ * One row by its scope predicate, with `visible` columns (the table's read action's, unless a capability reads its own).
+ * `action` is what read it: each file column then answers a reference that reads the file only under a read action.
+ */
+export async function selectOne<O>(
+	context: TableContext,
+	run: Runner,
+	scope: OperationNode,
+	visible = context.model.visible,
+	action?: string,
+): Promise<O> {
 	const start = startSelect(context.shape)
 	const state = finishSelect(start, start)
 	const node = selectNode(state, visible, scope, undefined, context.model.dates)
-	const rows = await (await run.read()).run<O>(node, guard(context, 'SelectQueryNode', scope))
+	const session = await run.read()
+	const rows = await session.run<O>(node, guard(context, 'SelectQueryNode', scope))
 	const [row] = answerDays(context.model.name, context.model.dates, rows)
 	if (row === undefined) {
 		throw new NotFoundError(`${context.model.name} not found`)
 	}
+	if (action !== undefined) {
+		await answerFiles(context.model, run.files, session, [row], action)
+	}
 	return row
 }
 
+/** The file references an insert wrote, in its transaction: stamped with the scope of the row's own values. */
+async function referenceInserted(
+	context: TableContext,
+	run: Runner,
+	transaction: Session,
+	values: ReadonlyMap<string, Primitive | null>,
+): Promise<void> {
+	const model = context.model
+	await referenceFiles(model, run.files, transaction, values, async () => {
+		const scope = rowScope(model, values)
+		if (scope === undefined) {
+			throw new QueryRefusedError('unexpected_row', `an insert into ${model.name} carries no value of its top-level scope`)
+		}
+		return scope
+	})
+}
+
+/** The file references an update wrote, in its transaction: stamped with the scope the updated row lies in. */
+async function referenceUpdated(
+	context: TableContext,
+	run: Runner,
+	transaction: Session,
+	changes: ReadonlyMap<string, Primitive | null>,
+	row: unknown,
+): Promise<void> {
+	const model = context.model
+	await referenceFiles(model, run.files, transaction, changes, async () => {
+		const key = keyOf(model)
+		const value: unknown = typeof row === 'object' && row !== null ? ownDescriptor(row, key)?.value : undefined
+		if (typeof value !== 'string') {
+			throw new QueryRefusedError('unexpected_row', `an update of ${model.name} answered no ${key}`)
+		}
+		return storedRowScope(model, transaction, key, value)
+	})
+}
+
 export function answer(context: TableContext): ReturningNode {
 	return acknowledgement(context.model.name, keyOf(context.model), context.model.version)
 }
@@ -919,10 +1039,185 @@ export async function insertRow<O>(
 			throw new QueryRefusedError('unexpected_row', `the insert into ${context.model.name} returned no row`)
 		}
 		checkVersion(context, row)
+		await referenceInserted(context, run, transaction, values)
 		return row
 	})
 }
 
+/**
+ * `insert(values, { onConflict: { columns, do } })`: on a conflict of `columns` (a unique index of the table), `nothing`
+ * writes nothing and `update` sets the columns the table's update action writes, from `updates`.
+ */
+export interface OnConflict {
+	readonly columns: readonly string[]
+	readonly mode: 'nothing' | 'update'
+	/** The values given for the table's update columns: what `update` sets on the conflicting row. */
+	readonly updates: ReadonlyMap<string, Primitive | null>
+}
+
+const CONFLICT_FIELDS = nameSet(['columns', 'do'])
+
+/**
+ * The `onConflict` of an insert's options, read through own data properties; `undefined` without options. `'update'`
+ * also needs the capability's action to be one of the table's update actions.
+ */
+export function onConflictOf(
+	context: TableContext,
+	options: unknown,
+	action: string,
+	given: ReadonlyMap<string, Primitive | null>,
+): OnConflict | undefined {
+	if (options === undefined) {
+		return undefined
+	}
+	const model = context.model
+	const read = plainOptions(options, nameSet(['onConflict']), 'insert')
+	const input = ownEntry(read, 'onConflict')
+	if (input === undefined) {
+		return undefined
+	}
+	const conflict = plainOptions(input, CONFLICT_FIELDS, 'onConflict')
+	const columns = parseList(ownEntry(conflict, 'columns'), (name) => {
+		if (!inSet(model.columns, name)) {
+			throw new QueryRefusedError('on_conflict', `onConflict names ${String(name)}, which is not a column of ${model.name}`)
+		}
+		return name
+	})
+	if (columns === undefined || columns.length === 0) {
+		throw new QueryRefusedError('on_conflict', 'onConflict.columns takes a plain array of the columns of a unique index')
+	}
+	const mode = ownEntry(conflict, 'do')
+	if (mode !== 'nothing' && mode !== 'update') {
+		throw new QueryRefusedError('on_conflict', "onConflict.do takes 'nothing' or 'update'")
+	}
+	const updates = new Map<string, Primitive | null>()
+	if (mode === 'update') {
+		if (!includes(model.actions.update, action)) {
+			throw new CapabilityError(
+				'wrong_action',
+				`an insert of ${model.name} that updates on a conflict also needs its update action ${
+					model.actions.update.join(' or ') || '(none)'
+				}; the capability holds ${action}`,
+			)
+		}
+		const columns = namesOf(model.update)
+		for (let index = 0; index < columns.length; index++) {
+			const name = columns[index] ?? ''
+			const value = given.get(name)
+			if (value !== undefined) {
+				updates.set(name, value)
+			}
+		}
+	}
+	return freeze({ columns: freeze(columns), mode, updates })
+}
+
+/** A plain object's own data properties, each one of `allowed`; the options of an insert or its `onConflict`. */
+function plainOptions(value: unknown, allowed: NameSet, what: string): Readonly<Record<string, unknown>> {
+	if (typeof value !== 'object' || value === null || isArray(value)) {
+		throw new QueryRefusedError('invalid_argument', `${what} takes { ${namesOf(allowed).join(', ')} }`)
+	}
+	const prototype: unknown = prototypeOf(value)
+	if ((prototype !== OBJECT_PROTOTYPE && prototype !== null) || ownSymbols(value).length > 0) {
+		throw new QueryRefusedError('invalid_argument', `${what} takes a plain object literal`)
+	}
+	const copy: Record<string, unknown> = {}
+	const keys = ownNames(value)
+	for (let index = 0; index < keys.length; index++) {
+		const key = keys[index] ?? ''
+		const descriptor = ownDescriptor(value, key)
+		if (!inSet(allowed, key)) {
+			throw new QueryRefusedError('invalid_argument', `${key} is not an option of ${what} (options: ${namesOf(allowed).join(', ')})`)
+		}
+		if (descriptor === undefined || !hasOwn(descriptor, 'value')) {
+			throw new QueryRefusedError('invalid_argument', `${what}.${key} is an accessor; ${what} takes plain values`)
+		}
+		setOwn(copy, key, descriptor.value)
+	}
+	return copy
+}
+
+/**
+ * The rows an insert's conflict may update: those in the containment the insert stamped (its chain, or a top-level
+ * object's own key), or every row of an application table. A conflicting row outside it is never written.
+ */
+function insertedScope(context: TableContext, values: ReadonlyMap<string, Primitive | null>): OperationNode {
+	const model = context.model
+	const columns: string[] = []
+	for (let index = 0; index < model.chain.length; index++) {
+		columns[columns.length] = model.chain[index]?.column ?? ''
+	}
+	if (model.scope.mode === 'dimension' && model.scope.container === undefined) {
+		columns[columns.length] = model.scope.key
+	}
+	const terms: OperationNode[] = []
+	for (let index = 0; index < columns.length; index++) {
+		const name = columns[index] ?? ''
+		const value = values.get(name)
+		if (value === undefined || value === null) {
+			throw new QueryRefusedError('on_conflict', `the insert into ${model.name} carries no ${name}`)
+		}
+		terms[terms.length] = equals(model.name, name, value)
+	}
+	return terms.length === 0 ? everything() : allOf(terms)
+}
+
+/**
+ * `insert … on conflict (columns) do nothing`, and for `update` the conflicting row's update in the same transaction,
+ * within the insert's own containment. A row deleted between the two is inserted on the second try; a conflicting row
+ * the capability does not reach is a 409. Answers `{ id, version?, inserted: true }`, `{ id, version?, inserted:
+ * false }` after an update, and `{ inserted: false }` when `nothing` wrote nothing.
+ */
+async function insertOnConflict(
+	context: TableContext,
+	run: Runner,
+	transaction: Session,
+	values: ReadonlyMap<string, Primitive | null>,
+	conflict: OnConflict,
+): Promise<Readonly<Record<string, unknown>>> {
+	const model = context.model
+	const matches: OperationNode[] = []
+	for (let index = 0; index < conflict.columns.length; index++) {
+		const name = conflict.columns[index] ?? ''
+		const value = values.get(name)
+		if (value === undefined || value === null) {
+			throw new QueryRefusedError('on_conflict', `onConflict names ${name}, which this insert into ${model.name} leaves empty`)
+		}
+		matches[matches.length] = equals(model.name, name, value)
+	}
+	const scope = conflict.mode === 'update' ? insertedScope(context, values) : undefined
+	for (let attempt = 0; attempt < 2; attempt++) {
+		const node = insertNode(model.name, values, answer(context), conflict.columns)
+		const [row] = await transaction.run<Readonly<Record<string, unknown>>>(node, {
+			...guard(context, 'InsertQueryNode', undefined),
+			onConflict: 'nothing',
+		})
+		if (row !== undefined) {
+			checkVersion(context, row)
+			await referenceInserted(context, run, transaction, values)
+			return { ...row, inserted: true }
+		}
+		if (scope === undefined) {
+			return { inserted: false }
+		}
+		const where = scopedWhere(allOf(matches), scope)
+		const unchanged = conflict.updates.size === 0
+		const update = unchanged
+			? acknowledgementNode(model.name, keyOf(model), model.version, where)
+			: updateNode(model.name, conflict.updates, model.version, where, answer(context))
+		const [updated] = await transaction.run<Readonly<Record<string, unknown>>>(
+			update,
+			guard(context, unchanged ? 'SelectQueryNode' : 'UpdateQueryNode', scope),
+		)
+		if (updated !== undefined) {
+			checkVersion(context, updated)
+			await referenceUpdated(context, run, transaction, conflict.updates, updated)
+			return { ...updated, inserted: false }
+		}
+	}
+	throw new ConflictError(`${model.name} holds a row with these ${conflict.columns.join(', ')} that this insert does not reach`)
+}
+
 /**
  * The rows a write addresses: the scope predicate, and the caller's conditions beside it (an unscoped row's key, whose
  * scope predicate is `true`).
@@ -986,6 +1281,7 @@ export async function updateRow<O>(
 		const [row] = await transaction.run<O>(node, guard(context, unchanged ? 'SelectQueryNode' : 'UpdateQueryNode', target.scope))
 		if (row !== undefined) {
 			checkVersion(context, row)
+			await referenceUpdated(context, run, transaction, changes, row)
 			return row
 		}
 		return missingOrChanged(context, transaction, target, expectedVersion)
@@ -1115,42 +1411,87 @@ function aggregateDays(dates: NameSet, columns: AggregateColumns): NameSet {
 	return nameSet(names)
 }
 
-/** `DimensionTable.insert` over a capability nobody type-checked; the table probe of `@fabrika/db/testing` calls it too. */
-export function insertIntoDimension<O>(context: TableContext, run: Runner, target: unknown, values: unknown): Promise<O> {
+/** An insert's row, stamped from its capability, the destination it locks, and what it does on a conflict. */
+export interface PreparedInsert {
+	readonly row: Map<string, Primitive | null>
+	readonly destination: RefGrant | undefined
+	readonly conflict: OnConflict | undefined
+}
+
+/**
+ * A dimension table's insert over a capability nobody type-checked: into a container (a new UUIDv7 key, the chain from
+ * the container's `Ref`), or for a top-level table the object the `Ref` names.
+ */
+export function prepareDimensionInsert(context: TableContext, target: unknown, values: unknown, options?: unknown): PreparedInsert {
 	const scope = dimensionScope(context.model)
 	const grant = refGrant(context, target, listDimension(scope), 'insert')
 	const row = readValues(values, context.model.insert, 'insert', context.model)
+	const conflict = onConflictOf(context, options, grant.action, row)
 	if (scope.container === undefined) {
 		// The object does not exist yet; this only refuses a chain the table has no column for.
 		linkValues(context.model.name, [{ dimension: scope.dimension, column: scope.key }], grant)
 		stampInsert(context, grant, row, scope.key, grant.id)
-		return insertRow(context, run, row, undefined)
+		return { row, destination: undefined, conflict }
 	}
 	stampInsert(context, grant, row, scope.key, Bun.randomUUIDv7())
 	for (const { link, value } of linkValues(context.model.name, context.model.chain, grant)) {
 		row.set(link.column, value)
 	}
-	return insertRow(context, run, row, grant)
+	return { row, destination: grant, conflict }
 }
 
 /** An application table's insert, for an `app` capability of its insert action: a new key, no containment. */
-export function insertIntoApplication<O>(context: TableContext, run: Runner, capability: unknown, values: unknown): Promise<O> {
+export function prepareApplicationInsert(context: TableContext, capability: unknown, values: unknown, options?: unknown): PreparedInsert {
 	const grant = appGrant(context, capability, 'insert')
 	const row = readValues(values, context.model.insert, 'insert', context.model)
+	const conflict = onConflictOf(context, options, grant.action, row)
 	stampInsert(context, grant, row, keyOf(context.model), Bun.randomUUIDv7())
-	return insertRow(context, run, row, undefined)
+	return { row, destination: undefined, conflict }
 }
 
-/** `ChildTable.insert` over a capability nobody type-checked. */
-export function insertIntoChild<O>(context: TableContext, run: Runner, parent: unknown, values: unknown): Promise<O> {
+/** A child table's insert under the parent its `Ref` names, whose chain is checked against the database. */
+export function prepareChildInsert(context: TableContext, parent: unknown, values: unknown, options?: unknown): PreparedInsert {
 	const scope = childScope(context)
 	const grant = refGrant(context, parent, scope.parent.dimension, 'insert')
 	const row = readValues(values, context.model.insert, 'insert', context.model)
+	const conflict = onConflictOf(context, options, grant.action, row)
 	stampInsert(context, grant, row, scope.key, Bun.randomUUIDv7())
 	for (const { link, value } of linkValues(context.model.name, context.model.chain, grant)) {
 		row.set(link.column, value)
 	}
-	return insertRow(context, run, row, grant)
+	return { row, destination: grant, conflict }
+}
+
+/** A prepared insert, with its conflict handling when the caller named one. */
+export function insertPrepared(context: TableContext, run: Runner, prepared: PreparedInsert): Promise<Readonly<Record<string, unknown>>> {
+	const conflict = prepared.conflict
+	if (conflict === undefined) {
+		return insertRow(context, run, prepared.row, prepared.destination)
+	}
+	return run.write(async (transaction) => {
+		if (prepared.destination !== undefined) {
+			await lockDestination(transaction, context, prepared.destination)
+		}
+		return insertOnConflict(context, run, transaction, prepared.row, conflict)
+	})
+}
+
+/** `DimensionTable.insert` over a capability nobody type-checked; the table probe of `@fabrika/db/testing` calls it too. */
+export function insertIntoDimension<O>(context: TableContext, run: Runner, target: unknown, values: unknown): Promise<O> {
+	const prepared = prepareDimensionInsert(context, target, values)
+	return insertRow(context, run, prepared.row, prepared.destination)
+}
+
+/** An application table's insert, for an `app` capability of its insert action. */
+export function insertIntoApplication<O>(context: TableContext, run: Runner, capability: unknown, values: unknown): Promise<O> {
+	const prepared = prepareApplicationInsert(context, capability, values)
+	return insertRow(context, run, prepared.row, prepared.destination)
+}
+
+/** `ChildTable.insert` over a capability nobody type-checked. */
+export function insertIntoChild<O>(context: TableContext, run: Runner, parent: unknown, values: unknown): Promise<O> {
+	const prepared = prepareChildInsert(context, parent, values)
+	return insertRow(context, run, prepared.row, prepared.destination)
 }
 
 type ReadAction<P, T> = ActionOf<P, T, 'read'>
@@ -1176,7 +1517,7 @@ export class DimensionTable<DB, P, T extends string> {
 		const scope = dimensionListPredicate(context, within, 'read')
 		const start = startSelect<Row<DB, P, T>, Joinable<DB, P, T>>(context.shape)
 		const state = finishSelect(build(start), start)
-		return selectRows<S>(context, scope, state, requiredAction(context, 'read'))
+		return selectRows<S>(context, scope, state, heldAction(context, within))
 	}
 
 	async get(ref: Ref<DimensionOf<P, T>, ReadAction<P, T>>): Promise<Row<DB, P, T>> {
@@ -1261,7 +1602,7 @@ export class ChildTable<DB, P, T extends string> {
 		const predicate = childListPredicate(context, scope, 'read')
 		const start = startSelect<Row<DB, P, T>, NoColumns>(context.shape)
 		const state = finishSelect(build(start), start)
-		return selectRows<S>(context, predicate, state, requiredAction(context, 'read'))
+		return selectRows<S>(context, predicate, state, heldAction(context, scope))
 	}
 
 	async get(parent: Ref<ParentDimension<P, T>, ReadAction<P, T>>, key: string): Promise<Row<DB, P, T>> {
@@ -1296,6 +1637,37 @@ export class ChildTable<DB, P, T extends string> {
 }
 Object.freeze(ChildTable.prototype)
 
+/**
+ * The runner of `@fabrika/db/testing`'s probe: a store's own, with a file binding of its own, and `held`, which turns
+ * each stored file's id in a file column of `values` into a reference the probe holds. The probe writes the file the
+ * isolation fixture seeded as a handler writes a reference it read; an id of no stored file stays an id, and is refused.
+ */
+function probeRunner(context: TableContext): { readonly run: Runner; readonly held: (values: unknown) => Promise<unknown> } {
+	const holder = {}
+	const run: Runner = { ...storeRunner(context), files: { holder, request: 'probe', graceMs: 1, scans: () => false } }
+	const held = async (values: unknown): Promise<unknown> => {
+		const columns = ownKeys(context.model.files)
+		if (columns.length === 0 || typeof values !== 'object' || values === null) {
+			return values
+		}
+		const ids = columns.flatMap((column) => {
+			const value: unknown = ownDescriptor(values, column)?.value
+			return typeof value === 'string' ? [value] : []
+		})
+		const metadata = ids.length === 0 ? new Map() : await storedFilesMetadata(await run.read(), ids)
+		const copy = { ...values }
+		for (const column of columns) {
+			const value: unknown = ownDescriptor(values, column)?.value
+			const meta = typeof value === 'string' ? metadata.get(value) : undefined
+			if (meta !== undefined) {
+				defineValue(copy, column, fileReference(meta, holder, true))
+			}
+		}
+		return copy
+	}
+	return { run, held }
+}
+
 /**
  * One table's operations without the store types, for `@fabrika/db/testing` only: the generated isolation tests address
  * a table by name. Every runtime check of a store applies; a child row is addressed by its parent's capability and
@@ -1332,12 +1704,9 @@ function probeOf(context: TableContext): TableProbe {
 		}
 		return child ? childListPredicate(context, capability, 'read') : dimensionListPredicate(context, capability, 'read')
 	}
-	// An `app` capability reads the columns of its own action, as ctx.db.app does; any other the read action's.
-	const visible = (capability: unknown): readonly string[] => {
-		const grant = runtimeOf(context.connection).capabilities.resolve(capability)
-		return visibleFor(context.model, grant.kind === 'app' ? grant.action : requiredAction(context, 'read'))
-	}
-	const run = storeRunner(context)
+	// A capability reads the columns of its own action, as ctx.db does.
+	const visible = (capability: unknown): readonly string[] => visibleFor(context.model, heldAction(context, capability))
+	const { run, held } = probeRunner(context)
 	return freeze({
 		mode: child ? 'child' : 'dimension',
 		get: async (capability: unknown, key?: string) => selectOne<Readonly<Record<string, unknown>>>(context, run, object(capability, key, 'read')),
@@ -1347,7 +1716,7 @@ function probeOf(context: TableContext): TableProbe {
 				context,
 				list(capability, 'rows'),
 				finishSelect(start, start),
-				requiredAction(context, 'read'),
+				heldAction(context, capability),
 				visible(capability),
 			)
 		},
@@ -1371,10 +1740,12 @@ function probeOf(context: TableContext): TableProbe {
 			return typeof count === 'string' ? count : '0'
 		},
 		insert: async (capability: unknown, values: unknown) =>
-			child ? insertIntoChild(context, run, capability, values) : insertIntoDimension(context, run, capability, values),
+			child
+				? insertIntoChild(context, run, capability, await held(values))
+				: insertIntoDimension(context, run, capability, await held(values)),
 		update: async (capability: unknown, key: string | undefined, values: unknown, expectVersion?: number) => {
 			const scope = object(capability, key, 'update')
-			const changes = readValues(values, context.model.update, 'update', context.model)
+			const changes = readValues(await held(values), context.model.update, 'update', context.model)
 			return updateRow(context, run, addressed(scope), changes, versionArgument(context, expectVersion === undefined ? [] : [{ expectVersion }]))
 		},
 		remove: async (capability: unknown, key?: string) => removeRow(context, run, addressed(object(capability, key, 'delete'))),
@@ -1386,7 +1757,7 @@ function probeOf(context: TableContext): TableProbe {
  * also takes a scoped site's `Ref` or `Within` of the table's read action.
  */
 function appProbeOf(context: TableContext): TableProbe {
-	const run = storeRunner(context)
+	const { run, held } = probeRunner(context)
 	// A scoped site reads an application table too: the probe answers both, as ctx.db.app does.
 	const scoped = (capability: unknown): boolean => runtimeOf(context.connection).capabilities.resolve(capability).kind !== 'app'
 	const every = (capability: unknown): OperationNode =>
@@ -1417,7 +1788,7 @@ function appProbeOf(context: TableContext): TableProbe {
 				context,
 				every(capability),
 				finishSelect(start, start),
-				requiredAction(context, 'read'),
+				heldAction(context, capability),
 			)
 		},
 		count,
@@ -1426,10 +1797,10 @@ function appProbeOf(context: TableContext): TableProbe {
 				groupBy: columns,
 				count: true,
 			}),
-		insert: async (capability: unknown, values: unknown) => insertIntoApplication(context, run, capability, values),
+		insert: async (capability: unknown, values: unknown) => insertIntoApplication(context, run, capability, await held(values)),
 		update: async (capability: unknown, key: string | undefined, values: unknown, expectVersion?: number) => {
 			const scope = appRowPredicate(context, capability, key, 'update')
-			const changes = readValues(values, context.model.update, 'update', context.model)
+			const changes = readValues(await held(values), context.model.update, 'update', context.model)
 			return updateRow(context, run, addressed(scope), changes, versionArgument(context, expectVersion === undefined ? [] : [{ expectVersion }]))
 		},
 		remove: async (capability: unknown, key?: string) => removeRow(context, run, addressed(appRowPredicate(context, capability, key, 'delete'))),
@@ -1477,7 +1848,7 @@ function joinShapes(models: TableModels, parent: TableModel): Readonly<Record<st
 				const name = model.scope.inherit[position] ?? ''
 				on[on.length] = { childColumn: name, parentColumn: name }
 			}
-			setOwn(joinable, model.name, freeze({ shape: shapeOf(model, freeze({})), readAction: model.actions.read, on: freeze(on) }))
+			setOwn(joinable, model.name, freeze({ shape: shapeOf(model, freeze({})), readActions: model.actions.read, on: freeze(on) }))
 		}
 	}
 	return freeze(joinable)
@@ -1554,15 +1925,11 @@ export function scoped<DB, P>(tables: Tables<DB, P>): ScopedDatabase<DB, P> {
 			connection.runtime = bound
 			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, 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)),
+			admissions: admissions(() => runtimeOf(connection)),
+			files: storedFiles(() => runtimeOf(connection)),
 		}),
 		data: dataAccess({
 			models,
@@ -1612,69 +1979,6 @@ export function defineChildStore<DB, P, const T extends ChildTableName<P>, S>(
 	return build(new ChildTable(storeContext(database, table, 'child')))
 }
 
-/** The inbox table of `form`: the one table whose scope is `{ inbox: form }`. */
-function inboxOf(models: TableModels, form: string): TableModel | undefined {
-	const names = ownKeys(models)
-	for (let index = 0; index < names.length; index++) {
-		const model = modelOf(models, names[index] ?? '')
-		if (model?.scope.mode === 'inbox' && model.scope.form === form) {
-			return model
-		}
-	}
-	return undefined
-}
-
-function inboxProblems(models: TableModels, form: string, fields: readonly string[]): readonly string[] {
-	const inbox = inboxOf(models, form)
-	if (inbox === undefined) {
-		return [`no table in src/db/tables.ts is the inbox of '${form}' (scope: { inbox: '${form}', read })`]
-	}
-	const problems: string[] = []
-	for (let index = 0; index < fields.length; index++) {
-		const field = fields[index] ?? ''
-		if (!inSet(inbox.columns, field)) {
-			problems[problems.length] = `the input field '${field}' of '${form}' is not a column of its inbox ${inbox.name}`
-		}
-	}
-	return problems
-}
-
-/**
- * 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. 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,
-	runtime: DataLayerRuntime,
-	form: string,
-	values: Readonly<Record<string, unknown>>,
-	quota: InboxQuota,
-	held: HeldFormFiles | undefined,
-): Promise<boolean> {
-	const inbox = inboxOf(models, form)
-	if (inbox === undefined) {
-		throw new QueryRefusedError('unknown_table', `no table is the inbox of ${form}`)
-	}
-	const row = readValues(values, inbox.columns, 'insert', inbox)
-	return await sessionOf(runtime).transaction(async (transaction) => {
-		if (!(await takeFromBucket(transaction, form, quota.bucket, quota.limit))) {
-			return false
-		}
-		await transaction.run(insertNode(inbox.name, row, undefined), {
-			root: 'InsertQueryNode',
-			table: inbox.name,
-			joins: {},
-			scope: undefined,
-		})
-		if (held !== undefined) {
-			await holdFormFiles(transaction, held)
-		}
-		return true
-	})
-}
-
 /** The table that owns `dimension`: the one dimension table scoped by it (`defineTables` refuses a second). */
 export function ownerOf(models: TableModels, dimension: string): TableModel | undefined {
 	const names = ownKeys(models)