@fabrika/db 0.0.0-stage → 0.4.0

package/src/description.ts

@@ -0,0 +1,309 @@
+import { inSet, isSafeInteger, type NameSet, nameSet, namesOf, ownEntry, ownKeys, parseList } from './builtins'
+import { QueryRefusedError } from './errors'
+import { isPlainIdentifier } from './identifier'
+
+export type Primitive = string | number | bigint | boolean | Date
+export type ComparisonOperator = '=' | '<>' | '<' | '<=' | '>' | '>='
+export type PatternOperator = 'like' | 'ilike' | 'not like' | 'not ilike'
+export type ListOperator = 'in' | 'not in'
+export type NullOperator = 'is' | 'is not'
+export type AllowedOperator = ComparisonOperator | PatternOperator | ListOperator | NullOperator
+
+const OPERATOR_LIST: readonly AllowedOperator[] = [
+	'=',
+	'<>',
+	'<',
+	'<=',
+	'>',
+	'>=',
+	'like',
+	'ilike',
+	'not like',
+	'not ilike',
+	'in',
+	'not in',
+	'is',
+	'is not',
+]
+const OPERATORS = nameSet(OPERATOR_LIST)
+
+function isOperator(value: unknown): value is AllowedOperator {
+	return inSet(OPERATORS, value)
+}
+
+export interface Compare {
+	readonly kind: 'compare'
+	readonly column: string
+	readonly operator: AllowedOperator
+	readonly value: Primitive | readonly Primitive[] | null
+}
+
+/** A case-insensitive substring match; the text's `%`, `_` and `\` match literally. */
+export interface Contains {
+	readonly kind: 'contains'
+	readonly column: string
+	readonly text: string
+}
+
+export interface AnyOf {
+	readonly kind: 'any'
+	readonly conditions: readonly (Compare | Contains)[]
+}
+
+export type Condition = Compare | Contains | AnyOf
+
+/** What a select may name: the visible columns of its table and of the children it may join. */
+export interface TableShape {
+	readonly table: string
+	readonly visible: NameSet
+	readonly joinable: Readonly<Record<string, JoinShape>>
+	/** The `date` columns, which a read answers as `YYYY-MM-DD` text. */
+	readonly dates: NameSet
+}
+
+export interface JoinShape {
+	readonly shape: TableShape
+	readonly readAction: string
+	/** The composite foreign key: child column = parent column, for each pair. */
+	readonly on: readonly { readonly childColumn: string; readonly parentColumn: string }[]
+}
+
+export interface JoinState {
+	readonly join: JoinShape
+	readonly select: SelectState
+}
+
+export interface SelectState {
+	/** Identifies the description a callback received, so it cannot return one from elsewhere. */
+	readonly origin: object
+	readonly table: string
+	readonly columns: readonly string[] | undefined
+	readonly conditions: readonly Condition[]
+	readonly orderBy: readonly { readonly column: string; readonly direction: 'asc' | 'desc' }[]
+	readonly limit: number | undefined
+	readonly offset: number | undefined
+	readonly joins: readonly JoinState[]
+}
+
+type Comparable<V> = Exclude<V, null | undefined>
+type Columns<Row> = keyof Row & string
+type StringColumn<Row> = { [K in Columns<Row>]: Comparable<Row[K]> extends string ? K : never }[Columns<Row>]
+type NullableColumn<Row> = { [K in Columns<Row>]: null extends Row[K] ? K : never }[Columns<Row>]
+
+export type ConditionTuple<Row> =
+	| {
+		[K in Columns<Row>]: readonly [K, ComparisonOperator, Comparable<Row[K]>] | readonly [K, ListOperator, readonly Comparable<Row[K]>[]]
+	}[Columns<Row>]
+	| { [K in StringColumn<Row>]: readonly [K, PatternOperator | 'contains', string] }[StringColumn<Row>]
+
+type Prefixed<C extends string, J> = { [K in keyof J & string as `${C}.${K}`]: J[K] }
+export type NoColumns = Record<never, never>
+
+const selectToken: unique symbol = Symbol('scoped-select')
+
+let readState: <Row, Selected, Children>(select: ScopedSelect<Row, Selected, Children>) => SelectState
+let readShape: <Row, Selected, Children>(select: ScopedSelect<Row, Selected, Children>) => TableShape
+
+/**
+ * The only query surface a store callback sees: a frozen description, not a Kysely builder. There is nothing to
+ * execute, no raw SQL entry point, and no way to name a table other than this one and its declared children.
+ */
+export class ScopedSelect<Row, Selected, Children> {
+	readonly #state: SelectState
+	readonly #shape: TableShape
+	readonly #types: { readonly row?: Row; readonly selected?: Selected; readonly children?: Children } = {}
+
+	constructor(token: symbol, state: SelectState, shape: TableShape) {
+		if (token !== selectToken) {
+			throw new QueryRefusedError('invalid_argument', 'a query description is created by the store only')
+		}
+		this.#state = Object.freeze(state)
+		this.#shape = shape
+		Object.freeze(this)
+	}
+
+	static {
+		readState = (select) => select.#state
+		readShape = (select) => select.#shape
+	}
+
+	/** The columns to return; without it, every visible column. */
+	columns<const C extends Columns<Row>>(columns: readonly C[]): ScopedSelect<Row, Pick<Row, C>, Children> {
+		const names = parseList(columns, (name) => this.#column(name))
+		if (names === undefined || names.length === 0) {
+			throw new QueryRefusedError('invalid_argument', 'columns needs a non-empty plain array of column names')
+		}
+		return this.#next({ columns: names })
+	}
+
+	where<C extends Columns<Row>>(column: C, operator: ComparisonOperator, value: Comparable<Row[C]>): ScopedSelect<Row, Selected, Children>
+	where<C extends Columns<Row>>(column: C, operator: ListOperator, values: readonly Comparable<Row[C]>[]): ScopedSelect<Row, Selected, Children>
+	where<C extends StringColumn<Row>>(column: C, operator: PatternOperator, pattern: string): ScopedSelect<Row, Selected, Children>
+	where<C extends NullableColumn<Row>>(column: C, operator: NullOperator, value: null): ScopedSelect<Row, Selected, Children>
+	where(column: string, operator: string, value: unknown): ScopedSelect<Row, Selected, Children> {
+		return this.#withCondition(this.#parseCondition(column, operator, value))
+	}
+
+	/** One OR group of conditions on this table's columns. */
+	whereAny(conditions: readonly ConditionTuple<Row>[]): ScopedSelect<Row, Selected, Children>
+	whereAny(conditions: readonly (readonly unknown[])[]): ScopedSelect<Row, Selected, Children> {
+		const parsed = parseList(conditions, (condition) => {
+			const parts = parseList(condition, (part) => part)
+			if (parts === undefined || parts.length !== 3) {
+				throw new QueryRefusedError('invalid_argument', 'whereAny takes [column, operator, value] conditions, each a plain array')
+			}
+			return this.#parseCondition(parts[0], parts[1], parts[2])
+		})
+		if (parsed === undefined || parsed.length === 0) {
+			throw new QueryRefusedError('invalid_argument', 'whereAny needs a non-empty plain array of [column, operator, value] conditions')
+		}
+		return this.#withCondition({ kind: 'any', conditions: parsed })
+	}
+
+	/** A case-insensitive substring match in which `%` and `_` in the text match themselves. */
+	contains(column: StringColumn<Row>, text: string): ScopedSelect<Row, Selected, Children> {
+		return this.#withCondition(this.#parseCondition(column, 'contains', text))
+	}
+
+	orderBy(column: Columns<Row>, direction: 'asc' | 'desc' = 'asc'): ScopedSelect<Row, Selected, Children> {
+		if (direction !== 'asc' && direction !== 'desc') {
+			throw new QueryRefusedError('list_page', `orderBy direction must be 'asc' or 'desc'`)
+		}
+		return this.#next({ orderBy: [...this.#state.orderBy, { column: this.#column(column), direction }] })
+	}
+
+	limit(limit: number): ScopedSelect<Row, Selected, Children> {
+		return this.#next({ limit: count(limit, 'limit') })
+	}
+
+	offset(offset: number): ScopedSelect<Row, Selected, Children> {
+		return this.#next({ offset: count(offset, 'offset') })
+	}
+
+	/** An inner join to a declared child; its columns come back prefixed (`note_comments.body`). */
+	join<C extends keyof Children & string, J>(
+		child: C,
+		build: (q: ScopedSelect<Children[C], Children[C], NoColumns>) => ScopedSelect<Children[C], J, NoColumns>,
+	): ScopedSelect<Row, Selected & Prefixed<C, J>, Children> {
+		const join = typeof child === 'string' ? ownEntry(this.#shape.joinable, child) : undefined
+		if (join === undefined) {
+			const children = ownKeys(this.#shape.joinable).join(', ') || 'none'
+			throw new QueryRefusedError('unknown_table', `${String(child)} is not a joinable child of ${this.#state.table} (joinable: ${children})`)
+		}
+		const start = startSelect<Children[C], NoColumns>(join.shape)
+		const select = finishSelect(build(start), start)
+		if (select.joins.length > 0 || select.orderBy.length > 0 || select.limit !== undefined || select.offset !== undefined) {
+			throw new QueryRefusedError('invalid_argument', 'a joined child takes columns and where conditions only')
+		}
+		return this.#next({ joins: [...this.#state.joins, { join, select }] })
+	}
+
+	#next<S>(changes: Partial<Omit<SelectState, 'origin' | 'table'>>): ScopedSelect<Row, S, Children> {
+		return new ScopedSelect(selectToken, { ...this.#state, ...changes }, this.#shape)
+	}
+
+	#withCondition(condition: Condition): ScopedSelect<Row, Selected, Children> {
+		return this.#next({ conditions: [...this.#state.conditions, condition] })
+	}
+
+	#column(name: unknown): string {
+		return columnOf(this.#shape, name)
+	}
+
+	#parseCondition(column: unknown, operator: unknown, value: unknown): Compare | Contains {
+		return parseCondition(this.#shape, column, operator, value)
+	}
+}
+Object.freeze(ScopedSelect.prototype)
+Object.freeze(ScopedSelect)
+
+/** A column the shape lets a query name; a hidden one is refused like a missing one. */
+export function columnOf(shape: TableShape, name: unknown): string {
+	const columns = namesOf(shape.visible).join(', ')
+	if (typeof name !== 'string') {
+		throw new QueryRefusedError(
+			'invalid_argument',
+			`a column is named by a string, not by ${typeof name === 'object' ? 'an expression' : typeof name} (columns: ${columns})`,
+		)
+	}
+	if (!isPlainIdentifier(name) || !inSet(shape.visible, name)) {
+		throw new QueryRefusedError('unknown_column', `${name} is not a column of ${shape.table} (columns: ${columns})`)
+	}
+	return name
+}
+
+/** One `[column, operator, value]` condition over a caller's values, checked before anything reads it further. */
+export function parseCondition(shape: TableShape, column: unknown, operator: unknown, value: unknown): Compare | Contains {
+	const name = columnOf(shape, column)
+	if (operator === 'contains') {
+		if (typeof value !== 'string') {
+			throw new QueryRefusedError('invalid_argument', 'contains takes a string')
+		}
+		return { kind: 'contains', column: name, text: value }
+	}
+	if (!isOperator(operator)) {
+		throw new QueryRefusedError('invalid_argument', `operator ${String(operator)} is not allowed (allowed: ${OPERATOR_LIST.join(', ')}, contains)`)
+	}
+	const allowed = operator
+	if (allowed === 'in' || allowed === 'not in') {
+		const list = parseList(value, (item) => {
+			if (!isPrimitive(item)) {
+				throw new QueryRefusedError('invalid_argument', `${allowed} takes plain values only`)
+			}
+			return item
+		})
+		if (list === undefined || list.length === 0) {
+			throw new QueryRefusedError('invalid_argument', `${allowed} needs a non-empty plain array of values`)
+		}
+		return { kind: 'compare', column: name, operator: allowed, value: list }
+	}
+	if (allowed === 'is' || allowed === 'is not') {
+		if (value !== null) {
+			throw new QueryRefusedError('invalid_argument', `${allowed} takes null only`)
+		}
+		return { kind: 'compare', column: name, operator: allowed, value: null }
+	}
+	if (!isPrimitive(value)) {
+		throw new QueryRefusedError('invalid_argument', 'where takes a plain value (string, number, bigint, boolean or Date), not an expression')
+	}
+	return { kind: 'compare', column: name, operator: allowed, value }
+}
+
+export function startSelect<Row, Children>(shape: TableShape): ScopedSelect<Row, Row, Children> {
+	const state: SelectState = {
+		origin: Object.freeze({}),
+		table: shape.table,
+		columns: undefined,
+		conditions: [],
+		orderBy: [],
+		limit: undefined,
+		offset: undefined,
+		joins: [],
+	}
+	return new ScopedSelect(selectToken, state, shape)
+}
+
+/** The description a callback returned; it must derive from the one it received. */
+export function finishSelect<Row, Children>(built: unknown, start: ScopedSelect<Row, Row, Children>): SelectState {
+	if (!(built instanceof ScopedSelect)) {
+		throw new QueryRefusedError('invalid_argument', 'the query callback must return the description it received')
+	}
+	const state = readState(built)
+	const expected = readState(start)
+	if (state.origin !== expected.origin || readShape(built) !== readShape(start)) {
+		throw new QueryRefusedError('invalid_argument', 'the query callback must return the description it received, not one from another query')
+	}
+	return state
+}
+
+export function isPrimitive(value: unknown): value is Primitive {
+	const type = typeof value
+	return type === 'string' || type === 'number' || type === 'bigint' || type === 'boolean' || value instanceof Date
+}
+
+function count(value: unknown, what: string): number {
+	if (typeof value !== 'number' || !isSafeInteger(value) || value < 0) {
+		throw new QueryRefusedError('invalid_argument', `${what} must be a non-negative integer`)
+	}
+	return value
+}

package/src/errors.ts

@@ -0,0 +1,124 @@
+/**
+ * Why the layer refused a capability, as a closed catalog: a server log names the reason and its fixed text, never the
+ * message, which can name a table, a dimension or a value.
+ */
+export const CAPABILITY_ERRORS = Object.freeze({
+	wrong_capability: 'the operation takes another capability than it was given: another kind (a Ref, a Within or an app capability) or dimension',
+	wrong_action: 'the capability holds another action than the table names for the operation',
+	out_of_reach: "the table does not lie in the capability's dimension, or the capability does not reach it",
+	unenforceable: "the table carries no column for a dimension of the capability's chain, so the layer cannot enforce it",
+	undeclared_operation: "the table's policy declares no action for the operation, or handlers do not write the table",
+	table_kind: 'the operation needs another kind of table (a dimension, a child or an application table)',
+	within_size: 'a Within carries more scope values than one statement binds',
+	layer_unbound: 'the data layer was used before the framework connected it at boot, or connected a second time',
+})
+
+export type CapabilityErrorReason = keyof typeof CAPABILITY_ERRORS
+
+/** A capability of the wrong kind, dimension or action for the operation, or the layer used outside its binding. */
+export class CapabilityError extends Error {
+	override name = 'CapabilityError'
+	/** What a log may say; the message is for the author's own run. */
+	readonly reason: CapabilityErrorReason
+
+	constructor(reason: CapabilityErrorReason, message: string) {
+		super(message)
+		this.reason = reason
+	}
+}
+
+/**
+ * Why the layer refused, as a closed catalog: a server log names the reason and its fixed text, never the message,
+ * which can quote a value the request sent.
+ */
+export const QUERY_REFUSALS = {
+	invalid_argument: 'a data-layer call took an argument of another shape than its type declares',
+	invalid_value: 'a value cannot be bound: an invalid or out-of-range date, or a non-finite number',
+	invalid_name: 'a configured name (application, schema, file collection or owner column) breaks its naming rule',
+	unknown_column: 'a column the table does not declare, or one this operation may not set',
+	unknown_table: 'a table src/db/tables.ts does not declare, or one no store, join or locator reaches',
+	framework_table: "a framework table or a catalog name: application data reaches only the application's own tables",
+	row_address: 'a row is addressed otherwise than its table declares (its Ref, its parent Ref and key, or its key)',
+	version_required: 'the table has a version column, so update and remove take expectVersion',
+	read_only: 'a read-only request, query or table was asked to write or lock a row',
+	ended: 'the transaction, invocation or handle has ended or belongs to other work',
+	statement_failed: 'a statement of this transaction failed, so nothing it wrote commits',
+	unexpected_row: 'the database answered a row in another shape than its migration declares',
+	statement_shape: 'the compiled statement has a form the guard does not admit',
+	scope_predicate: 'the scope predicate is missing or is not a top-level conjunct',
+	list_page: 'a list limit, cursor or order outside what a page admits',
+	undeclared_reach: 'the site reaches data it did not declare (sql or unscoped, or their mode)',
+	sql_template: 'ctx.sql was not called as one tagged template whose values are interpolated whole',
+	sql_statement: 'ctx.sql runs one statement of an admitted kind, and none inside another',
+	sql_read_only: "sql: 'read' runs queries only; declare sql: 'write' on a mutation, a job or a webhook",
+	sql_name: 'ctx.sql names a framework, catalog or foreign-schema object, or writes a name in U& form',
+	sql_function: 'ctx.sql calls a function that is not a reviewed built-in',
+	sql_outside_transaction: 'a job runs ctx.sql only inside ctx.transaction((tx) => …), as tx.sql',
+	sql_scope: 'ctx.sql.scope(…) stands alone, joined by AND, in a WHERE or JOIN … ON clause of its own invocation',
+	file_scan: "a scan operation on a file collection without scan: true, or a scan verdict outside the scan job's lease",
+} as const
+
+export type QueryRefusal = keyof typeof QUERY_REFUSALS
+
+/** A query description or an operation tree outside what the layer allows. */
+export class QueryRefusedError extends Error {
+	override name = 'QueryRefusedError'
+	/** What a log may say; the message is for the author's own run and may quote a value. */
+	readonly reason: QueryRefusal
+
+	constructor(reason: QueryRefusal, message: string) {
+		super(message)
+		this.reason = reason
+	}
+}
+
+/** A `ctx.sql` row its row schema refuses: the handler's bug. The message names the column, never its value. */
+export class SqlRowError extends Error {
+	override name = 'SqlRowError'
+}
+
+/** A table policy that cannot be enforced as written. */
+export class PolicyError extends Error {
+	override name = 'PolicyError'
+}
+
+/** The addressed object does not exist in the capability's scope (HTTP 404). */
+export class NotFoundError extends Error {
+	override name = 'NotFoundError'
+}
+
+/** The object exists, but its version is not the one the caller expected (HTTP 409). */
+export class ConflictError extends Error {
+	override name = 'ConflictError'
+}
+
+/** A job attempt wrote after it lost its lease (timed out, taken over or expired); nothing was written. */
+export class LeaseLostError extends Error {
+	override name = 'LeaseLostError'
+}
+
+const SQLSTATE = /^[0-9A-Z]{5}$/
+
+/**
+ * A statement the database refused or could not run, as the layer reports it: its SQLSTATE only. The driver's message,
+ * detail and hint can quote the whole failing row, columns the capability may not read included, so none is kept.
+ */
+export class DatabaseError extends Error {
+	override name = 'DatabaseError'
+	/** The five-character SQLSTATE, or `null` when the statement never reached the database (a lost connection). */
+	readonly sqlState: string | null
+
+	constructor(sqlState: string | null) {
+		super(sqlState === null ? 'the database could not run the statement' : `the database refused the statement (SQLSTATE ${sqlState})`)
+		this.sqlState = sqlState
+	}
+}
+
+/** The driver's failure as a `DatabaseError`; the driver's error object goes no further. */
+export function databaseError(error: unknown): DatabaseError {
+	if (error instanceof DatabaseError) {
+		return error
+	}
+	const state: unknown = typeof error === 'object' && error !== null ? Reflect.get(error, 'errno') : undefined
+	return new DatabaseError(typeof state === 'string' && SQLSTATE.test(state) ? state : null)
+}

package/src/file-table-sql.ts

@@ -0,0 +1,133 @@
+// The names and the DDL of a file collection's table (`fabrika_files_<collection>`). Pure: `@fabrika/db/framework`
+// re-exports `fileTableName` for `boot`, which the Worker adapter imports, and an application's migration uses the DDL.
+
+import {
+	FILE_SCAN_COLUMNS,
+	FILE_STATUSES,
+	FILE_TABLE_PREFIX,
+	fileScanAlter,
+	fileScanIndex,
+	fileStatusCheck,
+	legacyStatusCheckName,
+} from '@fabrika/platform-node/sql'
+import { QueryRefusedError } from './errors'
+import { isPlainIdentifier } from './identifier'
+
+export { FILE_STATUSES, FILE_TABLE_PREFIX, legacyStatusCheckName }
+
+/** `<table>_removable`, the longest name the DDL derives, must stay within Postgres' 63 characters. */
+const MAX_COLLECTION_LENGTH = 63 - FILE_TABLE_PREFIX.length - '_removable'.length
+
+/** The columns every file row has; an owner's containment column may not take one of these names. */
+export const FILE_COLUMNS: readonly string[] = [
+	'id',
+	'owner_id',
+	'status',
+	'object_key',
+	'size',
+	'content_type',
+	'sha256',
+	'original_name',
+	'created_by',
+	'created_at',
+	'deleted_at',
+	'object_version',
+	'scan_attempts',
+	'scan_after',
+]
+
+export type FileStatus = (typeof FILE_STATUSES)[number]
+
+/** The column types whose values `Bun.SQL` decodes as strings, as a capability carries them. */
+export type FileColumnType = 'text' | 'uuid'
+
+export interface FileColumn {
+	readonly column: string
+	readonly type: FileColumnType
+}
+
+export interface FileOwner {
+	readonly table: string
+	readonly key: FileColumn
+	/** The owner's containment columns, as its table policy declares them, nearest container first. */
+	readonly chain: readonly FileColumn[]
+}
+
+/** `fabrika_files_<collection>`, or `null` when the collection's name cannot name a table. */
+export function fileTableName(collection: string): string | null {
+	const table = `${FILE_TABLE_PREFIX}${collection}`
+	return collection.length <= MAX_COLLECTION_LENGTH && isPlainIdentifier(collection) && isPlainIdentifier(table) ? table : null
+}
+
+export function tableOf(collection: string): string {
+	const table = fileTableName(collection)
+	if (table === null) {
+		throw new QueryRefusedError(
+			'invalid_name',
+			`the file collection '${collection}' needs a lowercase snake_case name of at most ${MAX_COLLECTION_LENGTH} characters`,
+		)
+	}
+	return table
+}
+
+function sqlType(column: FileColumn): string {
+	if (!isPlainIdentifier(column.column)) {
+		throw new QueryRefusedError('invalid_name', 'an owner column must match ^[a-z_][a-z0-9_]*$')
+	}
+	if (column.type !== 'text' && column.type !== 'uuid') {
+		throw new QueryRefusedError('invalid_name', "an owner column's type must be 'text' or 'uuid'")
+	}
+	return column.type.toUpperCase()
+}
+
+/**
+ * The migration that creates a collection's table. A row carries its owner's key and the owner's whole containment
+ * chain under the owner's column names, with a composite foreign key: a move of the owner cascades into its files,
+ * so a capability minted before the move matches none of them, and deleting the owner orphans them (every owner
+ * column becomes null) for the sweep. The owner table needs `UNIQUE (<key>, <chain columns>)`, as a child table's
+ * parent does. A row is `pending` from before its object is written until the write completed.
+ */
+export function fileTableSql(collection: string, owner: FileOwner): string {
+	const table = tableOf(collection)
+	if (!isPlainIdentifier(owner.table)) {
+		throw new QueryRefusedError('invalid_name', 'the owner table must match ^[a-z_][a-z0-9_]*$')
+	}
+	const keyType = sqlType(owner.key)
+	const chain = owner.chain.map((link) => ({ column: link.column, type: sqlType(link) }))
+	const taken = chain.find((link) => FILE_COLUMNS.includes(link.column))
+	if (taken !== undefined) {
+		throw new QueryRefusedError('invalid_name', `the owner column ${taken.column} has the name of a file column (${FILE_COLUMNS.join(', ')})`)
+	}
+	const fileColumns = ['owner_id', ...chain.map((link) => link.column)].join(', ')
+	const ownerColumns = [owner.key.column, ...chain.map((link) => link.column)].join(', ')
+	return `CREATE TABLE ${table} (
+	id UUID PRIMARY KEY,
+	owner_id ${keyType},
+${chain.map((link) => `\t${link.column} ${link.type},\n`).join('')}	status TEXT NOT NULL ${fileStatusCheck(table)},
+	object_key TEXT NOT NULL UNIQUE,
+	size BIGINT,
+	content_type TEXT NOT NULL,
+	sha256 TEXT,
+	original_name TEXT,
+	created_by TEXT NOT NULL,
+	created_at TIMESTAMPTZ NOT NULL,
+	deleted_at TIMESTAMPTZ,
+${
+		FILE_SCAN_COLUMNS.map((column) => `\t${column},\n`).join('')
+	}	FOREIGN KEY (${fileColumns}) REFERENCES ${owner.table} (${ownerColumns}) ON UPDATE CASCADE ON DELETE SET NULL
+);
+CREATE INDEX ${table}_owner ON ${table} (owner_id) WHERE deleted_at IS NULL;
+CREATE INDEX ${table}_removable ON ${table} (created_at) WHERE deleted_at IS NOT NULL OR owner_id IS NULL OR status = 'pending';
+${fileScanIndex(table)};
+`
+}
+
+/**
+ * The migration that lets an existing collection turn `scan: true` on: it replaces the status check of a table an
+ * earlier `fileTableSql` created, which admitted only `pending` and `live`, by the check of every state, and adds the
+ * scan job's columns and index. A table `fileTableSql` creates now needs none of it.
+ */
+export function fileScanSql(collection: string): string {
+	const table = tableOf(collection)
+	return `${fileScanAlter(table)};\n${fileScanIndex(table)};\n`
+}