@fabrika/db 0.6.0 → 0.7.0

package/src/stored-files.ts

@@ -0,0 +1,402 @@
+// The framework's side of `fabrika_files` (`@fabrika/db/migrations`): every stored file, a value a table's file column
+// references by id. `@fabrika/app` stages a file's row before its object, on a connection of its own; the data layer
+// claims it at its first reference, in the handler's transaction, and reads its metadata beside every row; the sweep
+// deletes a file no column references in three steps. Each operation is a fixed statement on the database's clock,
+// reached only through `@fabrika/db/framework`. A statement that names an application table builds it from the
+// table policies' validated identifiers, never from a caller's value.
+
+import { freeze } from './builtins'
+import { type FixedParameter, runFixedStatement, type Session, sessionOf } from './database'
+import { DatabaseError, QueryRefusedError } from './errors'
+import { isPlainIdentifier } from './identifier'
+import { fencedTransaction } from './job-leases'
+import { FILE_DELETIONS_TABLE, FILES_TABLE } from './migrations'
+import type { DataLayerRuntime } from './store'
+
+const F = FILES_TABLE
+const D = FILE_DELETIONS_TABLE
+
+/** A stored file's states: written, waiting for its first reference, for its scan, served, or refused by the scan. */
+export const STORED_FILE_STATUSES = ['pending', 'quarantined', 'live', 'rejected'] as const
+
+export type StoredFileStatus = (typeof STORED_FILE_STATUSES)[number]
+
+/** What a file reference carries: the file's metadata, never its bytes or its object. */
+export interface StoredFileMeta {
+	readonly id: string
+	readonly kind: string
+	readonly name: string | null
+	readonly type: string
+	readonly size: number
+	readonly status: StoredFileStatus
+}
+
+/** A file about to be written: its row comes first, then the object under `objectKey`. */
+export interface StagedFile {
+	readonly id: string
+	readonly kind: string
+	readonly objectKey: string
+	readonly contentType: string
+	readonly name: string | null
+	/** The request (or job attempt) that writes it: only it may claim the file while it is pending. */
+	readonly request: string
+}
+
+/** A stored file as a byte consumer reads it: only a live one is served, by its scanned version when its kind scans. */
+export interface ServedFile extends StoredFileMeta {
+	readonly objectKey: string
+	readonly objectVersion: string | null
+}
+
+/** What the scan pass needs of a quarantined file. */
+export interface QuarantinedStoredFile {
+	readonly id: string
+	readonly objectKey: string
+	readonly size: number
+	readonly sha256: string
+	readonly contentType: string
+	readonly scanAttempts: number
+	readonly dueSince: Date
+}
+
+/** A file column the sweep looks a file up in: an application table's column, both validated identifiers. */
+export interface FileColumnRef {
+	readonly table: string
+	readonly column: string
+}
+
+/** What a reference write learns of a file it locked. */
+export interface LockedFile {
+	readonly kind: string
+	readonly status: StoredFileStatus
+	readonly request: string | null
+	readonly scope: string | null
+	/** Whether it is still within the pending grace, counted from its creation. */
+	readonly fresh: boolean
+}
+
+export interface StoredFiles {
+	/** Commits the `pending` row of a file whose object is written next, on a connection of its own: the cleanup intent. */
+	stage(file: StagedFile): Promise<void>
+	/** Records the written object's size and digest on its pending row, on a connection of its own. */
+	written(id: string, written: { readonly size: number; readonly sha256: string }): Promise<void>
+	/**
+	 * Deletes a pending row this request wrote and nobody claimed, and records its object for deletion, in one
+	 * statement: the object key, or `null` when the file was claimed (or is gone).
+	 */
+	abandon(id: string, request: string): Promise<string | null>
+	/** A file as a byte consumer reads it, in `using` or on its own; `null` when the sweep deleted it. */
+	find(id: string, using?: Session): Promise<ServedFile | null>
+	/** Quarantines a live file of a scanning kind again when it has no scanned version, so the scan decides once more. */
+	requarantine(id: string, version: string | null): Promise<void>
+	/** Each file's metadata, by id, in `using`: what the data layer answers in a file column. */
+	metadata(using: Session, ids: readonly string[]): Promise<ReadonlyMap<string, StoredFileMeta>>
+	// The scan pass, each verdict fenced by the scan job's lease.
+	quarantined(kinds: readonly string[], limit: number, now: Date): Promise<readonly QuarantinedStoredFile[]>
+	promote(id: string, sha256: string, version: string): Promise<boolean>
+	deferScan(id: string, attempts: number, after: Date): Promise<boolean>
+	reject(id: string): Promise<boolean>
+	// The sweep.
+	/** Objects whose rows a sweep deleted and whose own deletion it did not finish. */
+	unfinishedDeletions(limit: number): Promise<readonly string[]>
+	forgetDeletion(objectKey: string): Promise<void>
+	/** Clears the legacy marker of every migrated file that one of `columns` references: it is an ordinary file now. */
+	adoptReferenced(columns: readonly FileColumnRef[]): Promise<number>
+	/** At most `limit` files past the grace that no column of `columns` references (pending ones included), oldest first. */
+	unreferenced(columns: readonly FileColumnRef[], limit: number, graceMs: number): Promise<readonly string[]>
+	/**
+	 * Deletes the row of an unreferenced file and records its object for deletion, in one transaction; `null` when it
+	 * survived: a reference exists (the foreign key refuses the delete), or it is legacy or within the grace.
+	 */
+	remove(id: string, graceMs: number): Promise<string | null>
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+/** Postgres' code of a foreign key violation: the delete of a file some column still references. */
+const FOREIGN_KEY_VIOLATION = '23503'
+
+const SERVED_COLUMNS = `id::text as id, kind, name, content_type, size, status, object_key, object_version`
+
+const SQL_STAGE = `insert into ${F} (id, kind, status, object_key, content_type, name, request, created_at)
+values ($1::uuid, $2, 'pending', $3, $4, $5, $6, now())`
+
+const SQL_WRITTEN = `update ${F} set size = $2::bigint, sha256 = $3 where id = $1::uuid and status = 'pending' returning id`
+
+const SQL_ABANDON = `with gone as (delete from ${F} where id = $1::uuid and status = 'pending' and request = $2 returning object_key)
+insert into ${D} (object_key, recorded_at) select object_key, now() from gone on conflict (object_key) do nothing returning object_key`
+
+const SQL_FIND = `select ${SERVED_COLUMNS} from ${F} where id = $1::uuid`
+
+const SQL_REQUARANTINE = `update ${F} set status = 'quarantined', object_version = null, scan_attempts = 0, scan_after = now()
+where id = $1::uuid and status = 'live' and object_version is not distinct from $2`
+
+const SQL_METADATA = `select id::text as id, kind, name, content_type, size, status from ${F}
+where id = any(string_to_array($1, ',')::uuid[])`
+
+const SQL_QUARANTINED = `select id::text as id, object_key, size, sha256, content_type, scan_attempts, coalesce(scan_after, created_at) as due_since
+from ${F} where status = 'quarantined' and kind = any(string_to_array($1, ',')) and (scan_after is null or scan_after < $2::timestamptz)
+order by scan_after nulls first, created_at limit $3::int`
+
+const SQL_PROMOTE = `update ${F} set status = 'live', object_version = $3 where id = $1::uuid and status = 'quarantined' and sha256 = $2 returning id`
+
+const SQL_DEFER = `update ${F} set scan_attempts = $2::int, scan_after = $3::timestamptz
+where id = $1::uuid and status = 'quarantined' and scan_attempts = $2::int - 1 returning id`
+
+const SQL_REJECT = `update ${F} set status = 'rejected' where id = $1::uuid and status = 'quarantined' returning id`
+
+const SQL_UNFINISHED = `select object_key from ${D} order by recorded_at limit $1::int`
+
+const SQL_FORGET = `delete from ${D} where object_key = $1`
+
+const SQL_REMOVE = `with gone as (
+	delete from ${F} where id = $1::uuid and legacy is null and created_at < now() - $2::bigint * interval '1 millisecond' returning object_key
+)
+insert into ${D} (object_key, recorded_at) select object_key, now() from gone returning object_key`
+
+/** The lock a reference write takes: a file being deleted cannot gain a reference, and a referenced one is not deleted. */
+const SQL_LOCK = `select kind, status, request, scope, created_at > now() - $2::bigint * interval '1 millisecond' as fresh
+from ${F} where id = $1::uuid for share`
+
+const SQL_CLAIM = `update ${F} set status = $2 where id = $1::uuid and status = 'pending' returning id`
+
+/** The first dimensional reference stamps the scope; one from another top-level scope matches nothing. */
+const SQL_STAMP = `update ${F} set scope = $2 where id = $1::uuid and (scope is null or scope = $2) returning id`
+
+/** `exists (select 1 from <table> where <column> = f.id)`, one per column, over the policies' validated identifiers. */
+function referencedBy(columns: readonly FileColumnRef[]): string {
+	if (columns.length === 0) {
+		return 'false'
+	}
+	return columns.map(({ table, column }) => {
+		if (!isPlainIdentifier(table) || !isPlainIdentifier(column)) {
+			throw new QueryRefusedError('invalid_name', 'a file column is named by plain identifiers')
+		}
+		return `exists (select 1 from ${table} r where r.${column} = f.id)`
+	}).join(' or ')
+}
+
+function uuid(value: string): string {
+	if (!UUID.test(value)) {
+		throw new QueryRefusedError('invalid_argument', 'a stored file is named by its UUID')
+	}
+	return value
+}
+
+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 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
+}
+
+function nullableText(row: Readonly<Record<string, unknown>>, column: string): string | null {
+	const value = row[column]
+	return typeof value === 'string' ? value : null
+}
+
+/** BIGINT and INTEGER come back as strings or numbers; a pending row has no size yet, which reads as 0. */
+function count(row: Readonly<Record<string, unknown>>, column: string): number {
+	const value = row[column] === null ? 0 : Number(row[column])
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw new QueryRefusedError('unexpected_row', `${F}.${column} is not a non-negative integer`)
+	}
+	return value
+}
+
+function status(row: Readonly<Record<string, unknown>>): StoredFileStatus {
+	const value = row['status']
+	const found = STORED_FILE_STATUSES.find((candidate) => candidate === value)
+	if (found === undefined) {
+		throw new QueryRefusedError('unexpected_row', `${F}.status is not a file state`)
+	}
+	return found
+}
+
+function date(row: Readonly<Record<string, unknown>>, column: string): Date {
+	const value = row[column]
+	if (!(value instanceof Date)) {
+		throw new QueryRefusedError('unexpected_row', `${F}.${column} came back as ${typeof value}`)
+	}
+	return value
+}
+
+function metaOf(row: Readonly<Record<string, unknown>>): StoredFileMeta {
+	return freeze({
+		id: text(row, 'id'),
+		kind: text(row, 'kind'),
+		name: nullableText(row, 'name'),
+		type: text(row, 'content_type'),
+		size: count(row, 'size'),
+		status: status(row),
+	})
+}
+
+/** Locks file `id` `for share` in `session`, the transaction that writes a reference to it; `null` when it is gone. */
+export async function lockStoredFile(session: Session, id: string, graceMs: number): Promise<LockedFile | null> {
+	const [found] = await runFixedStatement(session, SQL_LOCK, [uuid(id), positive(graceMs, 'a pending grace')])
+	if (found === undefined) {
+		return null
+	}
+	const row = record(found)
+	return freeze({
+		kind: text(row, 'kind'),
+		status: status(row),
+		request: nullableText(row, 'request'),
+		scope: nullableText(row, 'scope'),
+		fresh: row['fresh'] === true,
+	})
+}
+
+/** Ends the pending state of a file the reference write locked: `quarantined` for a scanning kind, else `live`. */
+export async function claimStoredFile(session: Session, id: string, ended: 'quarantined' | 'live'): Promise<void> {
+	const rows = await runFixedStatement(session, SQL_CLAIM, [uuid(id), ended])
+	if (rows.length !== 1) {
+		throw new QueryRefusedError('unexpected_row', 'a pending file changed under its lock')
+	}
+}
+
+/** Sets the scope of a file's first dimensional reference; `false` when it already holds another. */
+export async function stampStoredFile(session: Session, id: string, scope: string): Promise<boolean> {
+	return (await runFixedStatement(session, SQL_STAMP, [uuid(id), scope])).length === 1
+}
+
+/** Each file's metadata, by id, in `using`: one statement for every file column of a read. */
+export async function storedFilesMetadata(using: Session, ids: readonly string[]): Promise<ReadonlyMap<string, StoredFileMeta>> {
+	const unique = [...new Set(ids)]
+	if (unique.length === 0) {
+		return new Map()
+	}
+	const rows = await runFixedStatement(using, SQL_METADATA, [unique.map(uuid).join(',')])
+	return new Map(rows.map((found) => {
+		const meta = metaOf(record(found))
+		return [meta.id, meta] as const
+	}))
+}
+
+export function storedFiles(runtime: () => DataLayerRuntime): StoredFiles {
+	const session = () => sessionOf(runtime())
+	async function fenced(statement: string, parameters: readonly FixedParameter[]): Promise<boolean> {
+		const current = runtime()
+		const fence = current.capabilities.fence()
+		if (fence === null) {
+			throw new QueryRefusedError('file_scan', "a scan verdict is written only inside the scan job's lease")
+		}
+		const rows = await fencedTransaction(sessionOf(current), fence, (transaction) => runFixedStatement(transaction, statement, parameters))
+		return rows.length > 0
+	}
+	return freeze({
+		async stage(file: StagedFile): Promise<void> {
+			await runFixedStatement(session(), SQL_STAGE, [uuid(file.id), file.kind, file.objectKey, file.contentType, file.name, file.request])
+		},
+
+		async written(id: string, written: { readonly size: number; readonly sha256: string }): Promise<void> {
+			if (!/^[0-9a-f]{64}$/.test(written.sha256) || !Number.isSafeInteger(written.size) || written.size < 0) {
+				throw new QueryRefusedError('invalid_argument', 'a written file records its size and the hex SHA-256 of its bytes')
+			}
+			const rows = await runFixedStatement(session(), SQL_WRITTEN, [uuid(id), String(written.size), written.sha256])
+			if (rows.length !== 1) {
+				throw new QueryRefusedError('unexpected_row', 'a staged file is no longer pending')
+			}
+		},
+
+		async abandon(id: string, request: string): Promise<string | null> {
+			const [found] = await runFixedStatement(session(), SQL_ABANDON, [uuid(id), request])
+			return found === undefined ? null : text(record(found), 'object_key')
+		},
+
+		async find(id: string, using?: Session): Promise<ServedFile | null> {
+			if (!UUID.test(id)) {
+				return null
+			}
+			const [found] = await runFixedStatement(using ?? session(), SQL_FIND, [id])
+			if (found === undefined) {
+				return null
+			}
+			const row = record(found)
+			return freeze({ ...metaOf(row), objectKey: text(row, 'object_key'), objectVersion: nullableText(row, 'object_version') })
+		},
+
+		async requarantine(id: string, version: string | null): Promise<void> {
+			await runFixedStatement(session(), SQL_REQUARANTINE, [uuid(id), version])
+		},
+
+		metadata: storedFilesMetadata,
+
+		async quarantined(kinds: readonly string[], limit: number, now: Date): Promise<readonly QuarantinedStoredFile[]> {
+			if (kinds.length === 0) {
+				return []
+			}
+			const rows = await runFixedStatement(session(), SQL_QUARANTINED, [kinds.join(','), now.toISOString(), positive(limit, 'a scan batch')])
+			return rows.map((found) => {
+				const row = record(found)
+				return freeze({
+					id: text(row, 'id'),
+					objectKey: text(row, 'object_key'),
+					size: count(row, 'size'),
+					sha256: text(row, 'sha256'),
+					contentType: text(row, 'content_type'),
+					scanAttempts: count(row, 'scan_attempts'),
+					dueSince: date(row, 'due_since'),
+				})
+			})
+		},
+
+		promote: (id: string, sha256: string, version: string) => fenced(SQL_PROMOTE, [uuid(id), sha256, version]),
+
+		deferScan: (id: string, attempts: number, after: Date) => fenced(SQL_DEFER, [uuid(id), positive(attempts, 'a scan attempt'), after.toISOString()]),
+
+		reject: (id: string) => fenced(SQL_REJECT, [uuid(id)]),
+
+		async unfinishedDeletions(limit: number): Promise<readonly string[]> {
+			const rows = await runFixedStatement(session(), SQL_UNFINISHED, [positive(limit, 'a sweep batch')])
+			return rows.map((found) => text(record(found), 'object_key'))
+		},
+
+		async forgetDeletion(objectKey: string): Promise<void> {
+			await runFixedStatement(session(), SQL_FORGET, [objectKey])
+		},
+
+		async adoptReferenced(columns: readonly FileColumnRef[]): Promise<number> {
+			if (columns.length === 0) {
+				return 0
+			}
+			const statement = `update ${F} f set legacy = null where f.legacy is not null and (${referencedBy(columns)}) returning id`
+			return (await runFixedStatement(session(), statement, [])).length
+		},
+
+		async unreferenced(columns: readonly FileColumnRef[], limit: number, graceMs: number): Promise<readonly string[]> {
+			const statement = `select f.id::text as id from ${F} f
+where f.legacy is null and f.created_at < now() - $1::bigint * interval '1 millisecond' and not (${referencedBy(columns)})
+order by f.created_at limit $2::int`
+			const rows = await runFixedStatement(session(), statement, [positive(graceMs, 'a pending grace'), positive(limit, 'a sweep batch')])
+			return rows.map((found) => text(record(found), 'id'))
+		},
+
+		async remove(id: string, graceMs: number): Promise<string | null> {
+			try {
+				const [found] = await runFixedStatement(session(), SQL_REMOVE, [uuid(id), positive(graceMs, 'a pending grace')])
+				return found === undefined ? null : text(record(found), 'object_key')
+			} catch (error) {
+				if (error instanceof DatabaseError && error.sqlState === FOREIGN_KEY_VIOLATION) {
+					return null
+				}
+				throw error
+			}
+		},
+	})
+}

package/src/tables.ts

@@ -1,28 +1,38 @@
 // @fabrika/db/tables — the table policies of `src/db/tables.ts` as data. Browser- and Worker-safe: no Bun API and no
 // driver, so `@fabrika/app/contract` and the static contract reader in `@fabrika/check` import it.
 
-import type { ColumnPolicyArtifact, TablePolicyArtifact, TableScope } from '@fabrika/auth-core'
+import type { ColumnPolicyArtifact, TableActionArtifact, TablePolicyArtifact, TableScope } from '@fabrika/auth-core'
 import { freeze, namesOf, ownEntry, ownKeys, setOwn } from './builtins'
+import { PolicyError } from './errors'
 import { modelOf, type ScopeModel, type TableModel, tableModels, type Tables } from './policy'
 
 export { PolicyError } from './errors'
+export type { FileReference } from './file-references'
 export type {
 	AnyDbIndex,
 	ApplicationRows,
 	ApplicationTables,
 	AppRecordRows,
 	ChildRows,
+	ClaimedRow,
+	ClaimedRowHandle,
+	ClaimOptions,
 	ContainedRows,
 	CountOptions,
 	DataKind,
 	DbIndex,
 	FragmentTable,
 	IndexedTable,
+	InsertConflict,
+	InsertMethod,
 	ListOptions,
 	ListPage,
 	NoUnscoped,
 	OrderTerm,
 	OwnerRow,
+	PublicApplicationRows,
+	PublicApplicationTables,
+	PublicInsertMethod,
 	ReadOnlyUnscoped,
 	ReferenceRows,
 	ReferenceTables,
@@ -55,13 +65,14 @@ export {
 	defineTables,
 	type DimensionPolicy,
 	type DimensionScope,
-	type InboxPolicy,
-	type InboxScope,
+	type FilePolicies,
 	isTables,
+	type QueuePolicy,
 	readTables,
 	type RecordActions,
 	type ReferencePolicy,
 	type ReferenceScope,
+	type TableAction,
 	type TableActions,
 	type TableInsert,
 	Tables,
@@ -102,23 +113,6 @@ export function tablePolicies<DB, P>(tables: Tables<DB, P>): TablePolicies {
 	return freeze(artifacts)
 }
 
-/** Each form inbox's columns, by table: the only fields its form writes. The artifact carries no column list. */
-export type InboxColumns = Readonly<Record<string, readonly string[]>>
-
-/** The columns of every inbox table `defineTables` (or `readTables`) checked. */
-export function inboxColumns<DB, P>(tables: Tables<DB, P>): InboxColumns {
-	const models = tableModels(tables)
-	const names = ownKeys(models)
-	const columns: Record<string, readonly string[]> = {}
-	for (let index = 0; index < names.length; index++) {
-		const model = modelOf(models, names[index] ?? '')
-		if (model?.scope.mode === 'inbox') {
-			setOwn(columns, model.name, freeze([...namesOf(model.columns)]))
-		}
-	}
-	return freeze(columns)
-}
-
 function artifactOf(model: TableModel): TablePolicyArtifact {
 	const columns: Record<string, ColumnPolicyArtifact> = {}
 	const declared = [...ownKeys(model.columnReads), ...ownKeys(model.columnWrites)]
@@ -131,10 +125,10 @@ function artifactOf(model: TableModel): TablePolicyArtifact {
 	return {
 		scope: scopeOf(model.scope),
 		actions: {
-			read: model.actions.read,
-			insert: model.actions.insert ?? null,
-			update: model.actions.update ?? null,
-			delete: model.actions.delete ?? null,
+			read: actionArtifact(model.actions.read) ?? noReadAction(model.name),
+			insert: actionArtifact(model.actions.insert),
+			update: actionArtifact(model.actions.update),
+			delete: actionArtifact(model.actions.delete),
 			...(model.actions.appRead.length === 0 ? {} : { appRead: [...model.actions.appRead] }),
 			...(model.actions.appCount.length === 0 ? {} : { appCount: [...model.actions.appCount] }),
 		},
@@ -143,9 +137,23 @@ function artifactOf(model: TableModel): TablePolicyArtifact {
 		version: model.version ?? null,
 		createdBy: model.createdBy ?? null,
 		columns,
+		...(ownKeys(model.files).length === 0 ? {} : { files: { ...model.files } }),
 	}
 }
 
+/** One action as its text, so a single-action policy keeps the artifact and digest it had; several as a list; none as `null`. */
+function actionArtifact(actions: readonly string[]): TableActionArtifact | null {
+	const [first] = actions
+	if (first === undefined) {
+		return null
+	}
+	return actions.length === 1 ? first : [...actions]
+}
+
+function noReadAction(table: string): never {
+	throw new PolicyError(`${table}: the policy needs a read action`)
+}
+
 function scopeOf(scope: ScopeModel): TableScope {
 	switch (scope.mode) {
 		case 'dimension':
@@ -159,8 +167,6 @@ function scopeOf(scope: ScopeModel): TableScope {
 			return { mode: 'child', parent: scope.parent, key: scope.key, column: scope.column, inherit: [...scope.inherit] }
 		case 'reference':
 			return { mode: 'reference', reason: scope.reason }
-		case 'inbox':
-			return { mode: 'inbox', form: scope.form }
 		case 'app':
 			return { mode: 'app', reason: scope.reason, key: scope.key }
 	}

package/src/testing.ts

@@ -20,13 +20,12 @@ import { inSet, namesOf } from './builtins'
 import { type CatalogColumn, introspectSchema } from './codegen'
 import { applicationSchema, Database, openFirstConnection } from './database'
 import type { Primitive } from './description'
-import { FRAMEWORK_MIGRATION_BUNDLE, FRAMEWORK_MIGRATIONS } from './migrations'
+import { FILES_TABLE, FRAMEWORK_MIGRATION_BUNDLE, FRAMEWORK_MIGRATIONS } from './migrations'
 import { type Container, type ForeignKey, modelOf, type TableModel, type TableModels, tableModels, type Tables } from './policy'
 import { refuseInProduction } from './production'
 import { frameworkSideOf } from './registry'
 import type { TableProbe } from './store'
 
-export { withoutInboxes } from './policy'
 export { ChildTable, defineChildStore, defineStore, DimensionTable, type TableProbe } from './store'
 
 const MODULE = '@fabrika/db/testing'
@@ -133,8 +132,13 @@ export interface TestDatabase {
 	 * the markers it holds.
 	 */
 	seedUnder<DB, P>(tables: Tables<DB, P>, table: string, under: WorldRow): Promise<SeededRow>
-	/** Values for the policy's insert columns of `table` that its schema accepts: every required one, sampled. */
+	/** Values for the policy's insert columns of `table` that its schema accepts: every required one, sampled; a file column a seeded file. */
 	sampleInsert<DB, P>(tables: Tables<DB, P>, table: string): Promise<Readonly<Record<string, SampleValue>>>
+	/**
+	 * The object key of every file the fixture seeded into a file column, oldest first. Each stands for an empty object,
+	 * which a test's object store holds when a handler serves or opens the file.
+	 */
+	seededObjects(): readonly string[]
 	/** Closes the connections and drops the schema and its roles. */
 	close(): Promise<void>
 }
@@ -258,6 +262,14 @@ function ownerOf(models: TableModels, dimension: string): TableModel | undefined
 
 /** How many referenced rows deep the fixture follows required foreign keys outside the chain before it gives up. */
 const MAX_REFERENCE_DEPTH = 4
+/** The digest of the empty object a seeded file stands for. */
+const EMPTY_SHA256 = createHash('sha256').digest('hex')
+
+/**
+ * The object version a seeded file was scanned at: whoever stocks its empty object (`seededObjects`) stores it under
+ * this version, so a file of a scanning kind is served as a live one is, by its scanned version.
+ */
+export const SEEDED_OBJECT_VERSION = '"seeded"'
 
 /** A CHECK or foreign key violation of a seeded row, as the generator limit it is; `undefined` for any other failure. */
 function seedLimit(error: unknown, table: string): SeedLimitError | undefined {
@@ -375,6 +387,7 @@ export async function testDatabase(options: TestDatabaseOptions): Promise<TestDa
 	}
 	const { schema, lock, seeder, catalog } = opened
 	let checks: Promise<readonly CheckConstraint[]> | undefined
+	const seededObjects: string[] = []
 
 	/** The CHECK constraints that name `column` of `table`. */
 	async function checksOn(table: string, column: string): Promise<readonly CheckConstraint[]> {
@@ -475,8 +488,21 @@ export async function testDatabase(options: TestDatabaseOptions): Promise<TestDa
 		throw new Error(`${table}.${column} holds a ${dimension} as ${type}; a key or containment column holds its scope value as text or uuid`)
 	}
 
+	/** A live, empty file of `kind`, as the framework's put leaves one once a reference claims it: what a seeded file column holds. */
+	async function seedFile(kind: string): Promise<string> {
+		const id = crypto.randomUUID()
+		const objectKey = `${kind}/${id}`
+		seededObjects.push(objectKey)
+		await seeder.unsafe(
+			`INSERT INTO ${quoted(schema)}.${quoted(FILES_TABLE)} (id, kind, status, object_key, size, sha256, content_type, name, created_at, object_version)
+			VALUES ($1, $2, 'live', $3, 0, $4, 'application/octet-stream', 'seeded', now(), $5)`,
+			[id, kind, objectKey, EMPTY_SHA256, SEEDED_OBJECT_VERSION],
+		)
+		return id
+	}
+
 	/**
-	 * Inserts one row: `assigned` as given, a foreign key outside the chain `null` or referencing a row, a column a CHECK
+	 * Inserts one row: `assigned` as given, a file column a seeded file, a foreign key outside the chain `null` or referencing a row, a column a CHECK
 	 * names its `IN` list's first value or `null`, every other text column a marker and every other required column a
 	 * sample. Answers what the fixture wrote, and the row as stored (its database defaults filled). A CHECK or a foreign
 	 * key the values still fail is a `SeedLimitError` that names the constraint.
@@ -508,8 +534,11 @@ export async function testDatabase(options: TestDatabaseOptions): Promise<TestDa
 				continue
 			}
 			if (column.generated !== 'no') continue
-			const checked = await checkedValue(table, column)
-			if (checked !== undefined) {
+			const kind = model !== undefined && Object.hasOwn(model.files, name) ? model.files[name] : undefined
+			const checked = kind === undefined ? await checkedValue(table, column) : undefined
+			if (kind !== undefined) {
+				row.set(name, await seedFile(kind))
+			} else if (checked !== undefined) {
 				row.set(name, checked)
 			} else if (await holdsMarker(model, table, column)) {
 				const marker = `m${randomHex()}${randomHex()}`
@@ -666,10 +695,13 @@ export async function testDatabase(options: TestDatabaseOptions): Promise<TestDa
 				for (const [name, value] of await referencedKey(models, table, key, open, 0)) values[name] = value
 			}
 			for (const column of required) {
-				if (!(column.column_name in values)) values[column.column_name] = await requiredSample(table, column)
+				const name = column.column_name
+				const kind = Object.hasOwn(model.files, name) ? model.files[name] : undefined
+				if (!(name in values)) values[name] = kind === undefined ? await requiredSample(table, column) : await seedFile(kind)
 			}
 			return values
 		},
+		seededObjects: () => [...seededObjects],
 		// Its own connections end first, so the drop finds a slot even in a database at its limit.
 		close: () => closeTestDatabase(url, opened, (drop) => withConnectionCapacity(drop, { waitMs })),
 	}

package/src/vocabulary-tables.ts

@@ -1,7 +1,7 @@
 // The table policies of the vocabulary form, `defineTables(vocabulary, columns)`: how an application writes them, with
 // containment taken from the vocabulary, and the normalized policies the kit and the handles read. Types only.
 
-import type { ColumnList, ColumnPolicies, InboxPolicy, RecordActions, ReferencePolicy, TableActions, Tables, VersionColumn } from './policy'
+import type { ColumnList, ColumnPolicies, FilePolicies, RecordActions, ReferencePolicy, TableActions, Tables, VersionColumn } from './policy'
 
 declare const databaseType: unique symbol
 
@@ -74,6 +74,8 @@ interface WritableFields<Col extends string, A extends string, Ver extends Col,
 	readonly version?: Ver
 	readonly createdBy?: Col
 	readonly columns?: ColumnPolicies<Col, A>
+	/** The file columns, each with the file kind it holds (`c.files`): a `uuid` foreign key to `fabrika_files`. */
+	readonly files?: FilePolicies<Col>
 }
 
 /**
@@ -131,20 +133,18 @@ type AuthoredApplicationPolicy<Col extends string, A extends string, Ver extends
 
 /**
  * One table's policy as an application writes it under a vocabulary. `S` is its scope as written: its mode picks the
- * one policy form a mistake is reported against, rather than a union of all five. `P` is every policy as written.
+ * one policy form a mistake is reported against, rather than a union of all four. `P` is every policy as written.
  */
 export type VocabularyTablePolicy<Table extends string, Col extends string, A extends string, V, Ver extends Col, S = unknown, P = unknown> =
 	S extends { readonly dimension: unknown } ? AuthoredDimensionPolicy<Col, A, V, Ver, S>
 		: S extends { readonly child: unknown } ? AuthoredChildPolicy<Table, Col, A, Ver, S, P>
 		: S extends { readonly app: unknown } ? AuthoredApplicationPolicy<Col, A, Ver>
 		: S extends { readonly reference: unknown } ? ReferencePolicy<Col, A>
-		: S extends { readonly inbox: unknown } ? InboxPolicy<Col, A>
 		:
 			| AuthoredDimensionPolicy<Col, A, V, Ver, S>
 			| AuthoredChildPolicy<Table, Col, A, Ver, S, P>
 			| AuthoredApplicationPolicy<Col, A, Ver>
 			| ReferencePolicy<Col, A>
-			| InboxPolicy<Col, A>
 
 type StatedScope<P, T> = T extends keyof P ? P[T] extends { readonly scope: infer S } ? S : unknown : unknown