@fabrika/db 0.8.2 → 0.9.0-cloudflare.2

package/src/orm.ts

@@ -3,6 +3,7 @@
 // is that invocation, then refuses what the site may not do with the message its types give, then runs the store's
 // own checks of kind, dimension and action against the capability.
 
+import { uuidv7 } from '@fabrika/platform'
 import type { OperationNode } from 'kysely'
 import { BinaryOperationNode, OperatorNode, ValueNode } from 'kysely'
 import { freeze, hasOwn, inSet, isSafeInteger, nameSet, namesOf, ownDescriptor, ownKeys, ownNames, parseList, setOwn } from './builtins'
@@ -41,11 +42,14 @@ import {
 	appListPredicate,
 	appRecordPredicate,
 	appRowPredicate,
+	boundTerms,
+	boundValues,
 	childObjectPredicate,
 	childScope,
 	claimedRowPredicate,
 	claimScope,
 	type DataLayerRuntime,
+	dialectOf,
 	heldAction,
 	insertPrepared,
 	insertRow,
@@ -60,6 +64,7 @@ import {
 	reachPredicate,
 	readValues,
 	removeRow,
+	rowColumnsOf,
 	type Runner,
 	runtimeOf,
 	scopedApplicationRead,
@@ -72,7 +77,7 @@ import {
 	updatingRef,
 	versionArgument,
 } from './store'
-import { answerDays, timestampInput } from './temporal'
+import { answerRows, timestampInput } from './temporal'
 
 /** A list page holds this many rows unless the caller asks for fewer, and never more than `MAX_LIST_LIMIT`. */
 export const DEFAULT_LIST_LIMIT = 50
@@ -331,7 +336,7 @@ function targetRow(
 		const node = lockedSelectNode(context.model.name, visibleFor(context.model, grant.action), scope, context.model.dates)
 		const session = await run.read()
 		const rows = await session.run(node, { root: 'SelectQueryNode', table: context.model.name, joins: {}, scope, lock: 'update' })
-		const [row] = answerDays(context.model.name, context.model.dates, rows)
+		const [row] = answerRows(dialectOf(context), context.model.name, rowColumnsOf(context.model), rows)
 		if (row === undefined) {
 			throw new NotFoundError(`${context.model.name} not found`)
 		}
@@ -590,7 +595,7 @@ function applicationRows(
 			const node = lockedSelectNode(table, visibleFor(model, action), scope, model.dates)
 			const session = await run.read()
 			const rows = await session.run(node, { root: 'SelectQueryNode', table, joins: {}, scope, lock: 'update' })
-			const [row] = answerDays(table, model.dates, rows)
+			const [row] = answerRows(dialectOf(context), table, rowColumnsOf(model), rows)
 			if (row === undefined) {
 				throw new NotFoundError(`${table} not found`)
 			}
@@ -752,10 +757,11 @@ async function claimRows(
 	}
 	const limit = limitOf(options['limit'])
 	const visible = visibleFor(model, grant.action)
-	const conditions = conditionsOf(actionShape(model, visible), options['where'])
+	const conditions = conditionsOf(context, actionShape(model, visible), options['where'])
 	if (scope === undefined) {
 		return []
 	}
+	const dialect = dialectOf(context)
 	const key = keyOf(model)
 	const chain = model.chain.map((link) => link.column)
 	const selected = namesOf(nameSet([...visible, key, version, queue.attempts, ...chain]))
@@ -769,6 +775,7 @@ async function claimRows(
 			{ due: queue.due, attempts: queue.attempts, now, maxAttempts: queue.maxAttempts },
 			scope,
 			model.dates,
+			dialect,
 		)
 		const rows = await session.run<Readonly<Record<string, unknown>>>(node, { root: 'SelectQueryNode', table, joins: {}, scope, lock: 'claim' })
 		const byAttempts = new Map<number, string[]>()
@@ -785,7 +792,7 @@ async function claimRows(
 			const due = new Date(now.getTime() + backoffMs(tickMs, attempts + 1))
 			const changes = new Map<string, Primitive>([[queue.attempts, attempts + 1], [queue.due, due]])
 			const updated = await session.run<Readonly<Record<string, unknown>>>(
-				updateNode(table, changes, version, scopedWhere(inList(table, key, ids), scope), answer(context)),
+				updateNode(table, boundValues(context, changes), version, scopedWhere(inList(table, key, ids), scope), answer(context)),
 				{ root: 'UpdateQueryNode', table, joins: {}, scope },
 			)
 			for (const row of updated) {
@@ -797,7 +804,7 @@ async function claimRows(
 				claimed.set(id, { version: next, attempts: attempts + 1, due })
 			}
 		}
-		return { rows: await answerFiles(model, site.files, session, answerDays(table, model.dates, rows), grant.action), claimed }
+		return { rows: await answerFiles(model, site.files, session, answerRows(dialect, table, rowColumnsOf(model), rows), grant.action), claimed }
 	})
 	return leased.rows.map((row) => {
 		const id = String(row[key])
@@ -957,10 +964,11 @@ function unscopedRows(context: TableContext, site: DataSite, run: Runner, mode:
 		aggregate: bound(site, async <Row>(spec: AggregateSpec<Row>) => aggregateRows(context, run, everything(), context.shape, spec)),
 		get: bound(site, async (id: unknown) => {
 			const scope = everything()
-			const node = selectNode(rowState(table, [], [], 1), visible, scope, byKey(id), model.dates)
+			const dialect = dialectOf(context)
+			const node = selectNode(rowState(table, [], [], 1), visible, scope, byKey(id), model.dates, dialect)
 			const session = await run.read()
 			const rows = await session.run(node, { root: 'SelectQueryNode', table, joins: {}, scope })
-			const [row] = answerDays(table, model.dates, rows)
+			const [row] = answerRows(dialect, table, rowColumnsOf(model), rows)
 			if (row === undefined) {
 				throw new NotFoundError(`${table} not found`)
 			}
@@ -1003,7 +1011,7 @@ async function insertUnscoped(context: TableContext, run: Runner, principal: str
 			)
 		}
 	}
-	row.set(keyOf(model), Bun.randomUUIDv7())
+	row.set(keyOf(model), uuidv7())
 	if (model.version !== undefined) {
 		row.set(model.version, 1)
 	}
@@ -1045,7 +1053,8 @@ function readOptions(options: unknown, allowed: readonly string[], what: string)
 	return read
 }
 
-function conditionsOf(shape: TableShape, where: unknown): (Compare | Contains)[] {
+/** A list's `where`, parsed, with each value as its dialect binds it (`boundTerms`). */
+function conditionsOf(context: TableContext, shape: TableShape, where: unknown): readonly (Compare | Contains)[] {
 	if (where === undefined) {
 		return []
 	}
@@ -1059,7 +1068,7 @@ function conditionsOf(shape: TableShape, where: unknown): (Compare | Contains)[]
 	if (conditions === undefined) {
 		throw new QueryRefusedError('invalid_argument', 'where takes a plain array of [column, operator, value] conditions')
 	}
-	return conditions
+	return boundTerms(context, context.model, conditions)
 }
 
 function orderOf(shape: TableShape, orderBy: unknown, tiebreak: readonly string[]): OrderColumn[] {
@@ -1202,15 +1211,16 @@ async function listRows(
 	const table = context.model.name
 	const options = readOptions(input, ['where', 'orderBy', 'limit', 'after'], 'list')
 	const shape = actionShape(context.model, visible)
-	const conditions = conditionsOf(shape, options['where'])
+	const conditions = conditionsOf(context, shape, options['where'])
 	const order = orderOf(shape, options['orderBy'], tiebreak)
 	const limit = limitOf(options['limit'])
 	const position = options['after'] === undefined ? undefined : keysetAfter(table, order, decodeCursor(options['after'], order))
 	if (scope === undefined) {
 		return { items: [], next: null }
 	}
+	const dialect = dialectOf(context)
 	const node = withCursorColumns(
-		selectNode(rowState(table, conditions, order, limit + 1), visible, scope, position, context.model.dates),
+		selectNode(rowState(table, conditions, order, limit + 1), visible, scope, position, context.model.dates, dialect),
 		table,
 		order.map((term) => term.column),
 	)
@@ -1221,7 +1231,7 @@ async function listRows(
 		joins: {},
 		scope,
 	})
-	const page = answerDays(table, context.model.dates, rows.slice(0, limit))
+	const page = answerRows(dialect, table, rowColumnsOf(context.model), rows.slice(0, limit))
 	const last = page[page.length - 1]
 	const items = page.map((row) => withoutCursor(row, order))
 	return {
@@ -1239,7 +1249,7 @@ async function countRows(
 ): Promise<number> {
 	const table = context.model.name
 	const options = readOptions(input, ['where'], 'count')
-	const conditions = conditionsOf(actionShape(context.model, visible), options['where'])
+	const conditions = conditionsOf(context, actionShape(context.model, visible), options['where'])
 	if (scope === undefined) {
 		return 0
 	}

package/src/policy.ts

@@ -160,6 +160,8 @@ export interface TableColumns<Col extends string = string, Table extends string
 	readonly dates?: readonly Col[]
 	/** The `timestamp` and `timestamptz` columns, which a write takes as a `Date` or strict ISO 8601 text; absent when none. */
 	readonly timestamps?: readonly Col[]
+	/** On SQLite, the columns declared `BOOLEAN`, stored as 0 or 1 and read as a boolean; absent when none. */
+	readonly booleans?: readonly Col[]
 }
 
 /** The columns and foreign keys of every table, generated next to the schema types. */
@@ -221,6 +223,8 @@ export interface TableModel {
 	readonly dates: NameSet
 	/** The `timestamp` and `timestamptz` columns: a write's text must be strict ISO 8601 with an offset. */
 	readonly timestamps: NameSet
+	/** On SQLite, the `BOOLEAN` columns, stored as 0 or 1. */
+	readonly booleans: NameSet
 	/** The table's foreign keys, from the column list; a containment column must be one to its container's key. */
 	readonly foreignKeys: readonly ForeignKey[]
 	/**
@@ -342,7 +346,7 @@ function parseVocabulary(input: unknown): VocabularyModel {
 	return freeze({ dimensions: freeze(containment), actions: nameSet(actions) })
 }
 
-const COLUMN_LIST_FIELDS = nameSet(['columns', 'foreignKeys', 'dates', 'timestamps'])
+const COLUMN_LIST_FIELDS = nameSet(['columns', 'foreignKeys', 'dates', 'timestamps', 'booleans'])
 const FOREIGN_KEY_FIELDS = nameSet(['columns', 'table', 'references'])
 const POLICY_FIELDS = nameSet(['scope', 'actions', 'insert', 'update', 'version', 'createdBy', 'columns', 'queue', 'files'])
 const QUEUE_FIELDS = nameSet(['attempts', 'due', 'maxAttempts'])
@@ -524,6 +528,7 @@ function parseTable(table: string, columnList: unknown, policyInput: unknown, vo
 	}
 	const dates = parseColumnSet(table, ownEntry(entry, 'dates'), column, 'dates')
 	const timestamps = parseColumnSet(table, ownEntry(entry, 'timestamps'), column, 'timestamps')
+	const booleans = parseColumnSet(table, ownEntry(entry, 'booleans'), column, 'booleans')
 	const queue = queueInput === undefined
 		? undefined
 		: parseQueue(table, queueInput, column, { columns, timestamps, version, actions, update, columnWrites })
@@ -551,6 +556,7 @@ function parseTable(table: string, columnList: unknown, policyInput: unknown, vo
 		columnWrites: freeze(columnWrites),
 		dates,
 		timestamps,
+		booleans,
 		foreignKeys,
 	}
 }
@@ -673,7 +679,7 @@ function parseQueue(
 	return freeze({ attempts, due, maxAttempts: maxInput === undefined ? DEFAULT_MAX_ATTEMPTS : maxInput })
 }
 
-/** The column list's `date` (`dates`) or timestamp (`timestamps`) columns, each one of the table's. */
+/** The column list's `date` (`dates`), timestamp (`timestamps`) or boolean (`booleans`) columns, each one of the table's. */
 function parseColumnSet(table: string, input: unknown, column: (name: unknown, field: string) => string, field: string): NameSet {
 	if (input === undefined) {
 		return nameSet([])

package/src/postgres.ts

@@ -0,0 +1,26 @@
+import { SQL } from 'bun'
+import { PostgresJSDialect } from 'kysely-postgres-js'
+import { Database } from './database'
+import { QueryRefusedError } from './errors'
+import { isPlainIdentifier } from './identifier'
+
+export interface PostgresOptions {
+	readonly url: string
+	/** The application's schema (`app_<id>`), set as the connection's `search_path`. */
+	readonly schema: string
+	readonly max?: number
+}
+
+/**
+ * Over `Bun.SQL` with `prepare: false`: Bun otherwise keeps one prepared statement per distinct SQL text per
+ * connection, and `in` lists of different lengths make that grow without bound.
+ */
+export function openPostgres(options: PostgresOptions): Database {
+	if (!isPlainIdentifier(options.schema)) {
+		throw new QueryRefusedError('invalid_name', 'the schema must match ^[a-z_][a-z0-9_]*$')
+	}
+	const pool = new SQL({ url: options.url, adapter: 'postgres', prepare: false, max: options.max ?? 10, connection: { search_path: options.schema } })
+	return Database.fromDialect(new PostgresJSDialect({ postgres: pool }), { schema: options.schema })
+}
+// Application modules load after this one: a replaced opener would receive the database URL.
+Object.freeze(openPostgres)

package/src/registry.ts

@@ -26,9 +26,15 @@ export interface FrameworkTables {
 	readonly files: StoredFiles
 }
 
+/** A connection of the layer and its locator. Only its holder can `release` it, which lets the layer be bound again. */
+export interface ProvisionalBinding {
+	readonly locate: Locator
+	release(): void
+}
+
 export interface FrameworkSide {
-	/** Connects the layer once and answers its locator; a second call throws. */
-	bind(runtime: DataLayerRuntime): Locator
+	/** Connects the layer once and answers its binding; a call while one is connected throws. */
+	bind(runtime: DataLayerRuntime): ProvisionalBinding
 	readonly framework: FrameworkTables
 	/** The untyped handle over one table that `@fabrika/db/testing` hands the isolation tests. */
 	probe(table: string): TableProbe

package/src/sql.ts

@@ -373,17 +373,21 @@ function scopeFragment(terms: ScopeTerms, alias: string): { readonly parts: read
 	const parts: string[] = []
 	const values: SqlValue[] = []
 	let text = '('
-	terms.forEach((group, groupIndex) => {
+	// Index loops, never a method of the terms or of Array.prototype: this is the scope of the statement.
+	for (let groupIndex = 0; groupIndex < terms.length; groupIndex++) {
+		const group = terms[groupIndex] ?? []
 		text += `${groupIndex === 0 ? '' : ' or '}(`
-		group.forEach((test, testIndex) => {
+		for (let testIndex = 0; testIndex < group.length; testIndex++) {
+			const test = group[testIndex]
+			if (test === undefined) continue
 			text += `${testIndex === 0 ? '' : ' and '}${alias}.${test.column} = ${typeof test.value === 'string' ? '' : 'any('}`
-			parts.push(text)
-			values.push(test.value)
+			parts[parts.length] = text
+			values[values.length] = test.value
 			text = typeof test.value === 'string' ? '' : ')'
-		})
+		}
 		text += ')'
-	})
-	parts.push(`${text})`)
+	}
+	parts[parts.length] = `${text})`
 	return { parts, values }
 }
 
@@ -830,6 +834,10 @@ export function sqlTag(site: SqlSite, schema: string | undefined, termsOf: Scope
 				const statement = classifySql(expanded.parts, site.mode, schema ?? '')
 				const parameters = expanded.values.map((value, index) => parameterOf(value, index + 1))
 				const session = await site.session()
+				// ADR-0065: the classifier reads Postgres's grammar, so nothing of it is sent to SQLite.
+				if (session.dialect !== 'postgres') {
+					refuse('sql_dialect', 'raw SQL runs only on Postgres; an application on Cloudflare reads and writes through ctx.db')
+				}
 				if (session.readOnly && site.mode === 'write') {
 					refuse('read_only', 'this invocation is read-only')
 				}

package/src/sqlite-bun.ts

@@ -0,0 +1,122 @@
+// A `bun:sqlite` database shaped like a Durable Object's storage, for the tests and the SQLite test kit. Not a subpath:
+// a Worker never loads it.
+
+import { Database, type SQLQueryBindings } from 'bun:sqlite'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { SqliteCursor, SqliteStorage, SqliteValue } from './sqlite'
+
+export interface BunSqliteStorage extends SqliteStorage {
+	/** Runs `fn` in one transaction of its own, as a Durable Object's `storage.transactionSync` does. */
+	transactionSync<T>(fn: () => T): T
+}
+
+/** workerd's authorizer refuses these in `sql.exec`: a transaction runs through `transaction` or `transactionSync`. */
+const TRANSACTION_CONTROL = /(?:^|;)(?:\s|--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)*(?:begin|commit|end|rollback|savepoint|release)\b/i
+
+function bunBinding(value: SqliteValue): SQLQueryBindings {
+	return value instanceof ArrayBuffer ? new Uint8Array(value) : value
+}
+
+/** A column value as workerd answers it: a BLOB is an `ArrayBuffer`. */
+function storageValue(value: unknown): SqliteValue {
+	if (value === null || typeof value === 'string' || typeof value === 'number') {
+		return value
+	}
+	if (value instanceof Uint8Array) {
+		return value.slice().buffer
+	}
+	throw new Error('bun:sqlite answered a value a Durable Object never does')
+}
+
+function storageRow(row: Record<string, unknown>): Record<string, SqliteValue> {
+	return Object.fromEntries(Object.entries(row).map(([name, value]) => [name, storageValue(value)]))
+}
+
+/** The transaction a `transaction` callback runs in: its savepoint depth, and the queue its own nested ones wait in. */
+interface OpenTransaction {
+	readonly depth: number
+	queue: Promise<void>
+}
+
+/**
+ * `database` (a fresh `:memory:` one by default) with foreign keys enforced, as a Durable Object enforces them. One
+ * `transaction` runs at a time; one started inside a callback nests in a savepoint, as workerd nests it, and its
+ * siblings wait for each other. A statement outside one runs at once. A text of several statements runs whole when its
+ * first statement answers no rows, as a migration's does; otherwise only its first statement runs.
+ */
+export function bunSqliteStorage(database: Database = new Database(':memory:')): BunSqliteStorage {
+	database.run('PRAGMA foreign_keys = ON')
+	const totalChanges = (): number => database.query<{ readonly changes: number }, []>('select total_changes() as changes').get()?.changes ?? 0
+	const root: OpenTransaction = { depth: 0, queue: Promise.resolve() }
+	const open = new AsyncLocalStorage<OpenTransaction>()
+
+	function exec(query: string, ...bindings: SqliteValue[]): SqliteCursor {
+		if (TRANSACTION_CONTROL.test(query)) {
+			throw new Error('sql.exec runs no transaction statement: use storage.transaction() or storage.transactionSync()')
+		}
+		const values = bindings.map(bunBinding)
+		const before = totalChanges()
+		const statement = database.prepare<Record<string, unknown>, SQLQueryBindings[]>(query)
+		let rows: Record<string, SqliteValue>[] = []
+		try {
+			if (statement.columnNames.length > 0) {
+				rows = statement.all(...values).map(storageRow)
+			} else {
+				database.run(query, values)
+			}
+		} finally {
+			statement.finalize()
+		}
+		const rowsWritten = totalChanges() - before
+		return { toArray: () => rows, rowsWritten }
+	}
+
+	return {
+		sql: { exec },
+		async transaction<T>(closure: () => Promise<T>): Promise<T> {
+			const parent = open.getStore() ?? root
+			const previous = parent.queue
+			const done = Promise.withResolvers<void>()
+			parent.queue = previous.then(() => done.promise)
+			await previous
+			const depth = parent.depth + 1
+			const savepoint = `_test_savepoint_${depth}`
+			try {
+				database.run(depth === 1 ? 'BEGIN' : `SAVEPOINT ${savepoint}`)
+				try {
+					const result = await open.run({ depth, queue: Promise.resolve() }, closure)
+					database.run(depth === 1 ? 'COMMIT' : `RELEASE ${savepoint}`)
+					return result
+				} catch (error) {
+					if (depth === 1 && database.inTransaction) {
+						database.run('ROLLBACK')
+					} else if (depth > 1) {
+						database.run(`ROLLBACK TO ${savepoint}`)
+						database.run(`RELEASE ${savepoint}`)
+					}
+					throw error
+				}
+			} finally {
+				done.resolve()
+			}
+		},
+		transactionSync<T>(fn: () => T): T {
+			// Inside an open transaction workerd nests it in a savepoint too.
+			const nested = database.inTransaction
+			database.run(nested ? 'SAVEPOINT _test_sync_savepoint' : 'BEGIN')
+			try {
+				const result = fn()
+				database.run(nested ? 'RELEASE _test_sync_savepoint' : 'COMMIT')
+				return result
+			} catch (error) {
+				if (nested) {
+					database.run('ROLLBACK TO _test_sync_savepoint')
+					database.run('RELEASE _test_sync_savepoint')
+				} else if (database.inTransaction) {
+					database.run('ROLLBACK')
+				}
+				throw error
+			}
+		},
+	}
+}

package/src/sqlite-migrate.ts

@@ -0,0 +1,242 @@
+// @fabrika/db/sqlite-migrate — applies the framework's and the application's migrations to an application's SQLite
+// database when its Durable Object boots (ADR-0065), in a ledger in the same database. The identity and the
+// checksum rule are the Postgres runner's (ADR-0017): `(bundle, name)`, and the SHA-256 of an applied file's text.
+// Every new object instance runs it, so a bundle whose files match the digest recorded for it is not read further.
+// Runs inside a Worker: no Bun import.
+
+/** What the runner needs of the database; a Durable Object's `storage.sql.exec` and `storage.transactionSync` fit it. */
+export interface SqliteMigrationTarget {
+	/** Runs `query`, which may hold several statements, and answers the rows of the last one. */
+	exec(query: string, ...bindings: (string | number | null)[]): { toArray(): Record<string, unknown>[] }
+	/** Runs `fn` in one transaction: commits when it returns, rolls back when it throws. */
+	transactionSync<T>(fn: () => T): T
+}
+
+export interface SqliteMigrationBundle {
+	readonly bundle: string
+	readonly migrations: readonly { readonly name: string; readonly sql: string }[]
+}
+
+export class SqliteMigrationError extends Error {
+	override readonly name = 'SqliteMigrationError'
+}
+
+const LEDGER = 'fabrika_migrations'
+const DIGESTS = 'fabrika_migration_bundles'
+const BUNDLE_NAME = /^[a-z][a-z0-9-]*$/
+const MIGRATION_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*\.sql$/
+
+const LEDGER_DDL = `CREATE TABLE IF NOT EXISTS ${LEDGER} (
+	bundle TEXT NOT NULL,
+	name TEXT NOT NULL,
+	checksum TEXT NOT NULL,
+	applied_at TEXT NOT NULL,
+	PRIMARY KEY (bundle, name)
+) STRICT`
+
+/** A bundle's digest: the SHA-256 of its ordered file names and checksums, written with the last of its files applied. */
+const DIGESTS_DDL = `CREATE TABLE IF NOT EXISTS ${DIGESTS} (
+	bundle TEXT PRIMARY KEY,
+	digest TEXT NOT NULL
+) STRICT`
+
+interface HashedMigration {
+	readonly name: string
+	readonly sql: string
+	readonly checksum: string
+}
+
+interface PlannedMigration extends HashedMigration {
+	readonly bundle: string
+}
+
+interface PlannedBundle {
+	readonly bundle: string
+	readonly digest: string
+	readonly migrations: readonly PlannedMigration[]
+}
+
+interface HashedFiles {
+	readonly digest: string
+	readonly migrations: readonly HashedMigration[]
+}
+
+/** The files an array held when it was hashed, and their hashes: reused while the array still holds the same files. */
+interface HashedEntry {
+	readonly snapshot: readonly { readonly name: string; readonly sql: string }[]
+	readonly files: Promise<HashedFiles>
+}
+
+/** The migration arrays are module values, hashed once per isolate; an array mutated since is hashed again. */
+const hashedFiles = new WeakMap<SqliteMigrationBundle['migrations'], HashedEntry>()
+
+/** The SHA-256 hex of the file's UTF-8 text: the Postgres runner's `migrationChecksum`, so both ledgers agree. */
+async function checksumOf(sql: string): Promise<string> {
+	const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(sql))
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+function compareNames(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0
+}
+
+/** Refuses a malformed bundle before anything is hashed or run. */
+function check(bundles: readonly SqliteMigrationBundle[]): void {
+	const bundleNames = new Set<string>()
+	for (const bundle of bundles) {
+		if (!BUNDLE_NAME.test(bundle.bundle)) throw new SqliteMigrationError(`Invalid SQLite migration bundle name: ${bundle.bundle}`)
+		if (bundleNames.has(bundle.bundle)) throw new SqliteMigrationError(`Duplicate SQLite migration bundle ${bundle.bundle}`)
+		bundleNames.add(bundle.bundle)
+		const names = new Set<string>()
+		for (const migration of bundle.migrations) {
+			const identity = `${bundle.bundle}/${migration.name}`
+			if (!MIGRATION_NAME.test(migration.name)) throw new SqliteMigrationError(`Invalid SQLite migration filename: ${identity}`)
+			if (names.has(migration.name)) throw new SqliteMigrationError(`Duplicate SQLite migration ${identity}`)
+			if (migration.sql.trim() === '') throw new SqliteMigrationError(`SQLite migration ${identity} is empty`)
+			names.add(migration.name)
+		}
+	}
+}
+
+/** A bundle's files in name order with their checksums, and its digest: the SHA-256 of the ordered names and checksums. */
+async function hash(files: SqliteMigrationBundle['migrations']): Promise<HashedFiles> {
+	const migrations: HashedMigration[] = []
+	for (const { name, sql } of [...files].sort((a, b) => compareNames(a.name, b.name))) {
+		migrations.push({ name, sql, checksum: await checksumOf(sql) })
+	}
+	// A filename holds no space or newline, so each line is unambiguous.
+	const digest = await checksumOf(migrations.map((migration) => `${migration.name} ${migration.checksum}\n`).join(''))
+	return { digest, migrations }
+}
+
+function holdsSnapshot(files: SqliteMigrationBundle['migrations'], snapshot: HashedEntry['snapshot']): boolean {
+	return files.length === snapshot.length && files.every((file, index) => file.name === snapshot[index]?.name && file.sql === snapshot[index]?.sql)
+}
+
+/** Each bundle's migrations in name order, the bundles in the order given; refuses a malformed bundle before any SQL runs. */
+async function plan(bundles: readonly SqliteMigrationBundle[]): Promise<readonly PlannedBundle[]> {
+	check(bundles)
+	const planned: PlannedBundle[] = []
+	for (const bundle of bundles) {
+		let entry = hashedFiles.get(bundle.migrations)
+		if (entry === undefined || !holdsSnapshot(bundle.migrations, entry.snapshot)) {
+			entry = { snapshot: bundle.migrations.map(({ name, sql }) => ({ name, sql })), files: hash(bundle.migrations) }
+			hashedFiles.set(bundle.migrations, entry)
+		}
+		const { digest, migrations } = await entry.files
+		planned.push({ bundle: bundle.bundle, digest, migrations: migrations.map((migration) => ({ ...migration, bundle: bundle.bundle })) })
+	}
+	return planned
+}
+
+/** The digest recorded for each bundle that has one; empty while the table does not exist, as before its first run. */
+function readDigests(target: SqliteMigrationTarget, planned: readonly PlannedBundle[]): Map<string, string> {
+	const recorded = new Map<string, string>()
+	if (target.exec(`SELECT 1 AS present FROM sqlite_schema WHERE type = 'table' AND name = ?`, DIGESTS).toArray().length === 0) return recorded
+	for (const { bundle } of planned) {
+		const [row] = target.exec(`SELECT digest FROM ${DIGESTS} WHERE bundle = ?`, bundle).toArray()
+		if (row === undefined) continue
+		const { digest } = row
+		if (typeof digest !== 'string') throw new SqliteMigrationError(`SQLite migration table ${DIGESTS} holds a malformed row`)
+		recorded.set(bundle, digest)
+	}
+	return recorded
+}
+
+function recordDigest(target: SqliteMigrationTarget, bundle: PlannedBundle): void {
+	target.exec(DIGESTS_DDL)
+	target.exec(
+		`INSERT INTO ${DIGESTS} (bundle, digest) VALUES (?, ?) ON CONFLICT (bundle) DO UPDATE SET digest = excluded.digest`,
+		bundle.bundle,
+		bundle.digest,
+	)
+}
+
+/** Recorded checksums by `bundle/name`; empty while the ledger does not exist, so a fresh database is checked first. */
+function readLedger(target: SqliteMigrationTarget): Map<string, string> {
+	const present = target.exec(`SELECT 1 AS present FROM sqlite_schema WHERE type = 'table' AND name = ?`, LEDGER).toArray()
+	const applied = new Map<string, string>()
+	if (present.length === 0) return applied
+	for (const row of target.exec(`SELECT bundle, name, checksum FROM ${LEDGER}`).toArray()) {
+		const { bundle, name, checksum } = row
+		if (typeof bundle !== 'string' || typeof name !== 'string' || typeof checksum !== 'string') {
+			throw new SqliteMigrationError(`SQLite migration ledger ${LEDGER} holds a malformed row`)
+		}
+		applied.set(`${bundle}/${name}`, checksum)
+	}
+	return applied
+}
+
+/**
+ * Refuses, before anything is applied: an applied file whose text changed, and a new file that sorts before the last
+ * applied one of its bundle, which would run after the files it precedes. A ledger row without a file is the database
+ * ahead of the code after a rollback, which is tolerated, as on Postgres.
+ */
+function verify(planned: readonly PlannedBundle[], applied: ReadonlyMap<string, string>): void {
+	for (const { migrations } of planned) {
+		let lastApplied: string | undefined
+		for (const migration of migrations) {
+			const identity = `${migration.bundle}/${migration.name}`
+			const recorded = applied.get(identity)
+			if (recorded === undefined) continue
+			if (recorded !== migration.checksum) {
+				throw new SqliteMigrationError(
+					`SQLite migration ${identity} changed after it was applied; an applied migration is immutable, so write the change as a new migration`,
+				)
+			}
+			lastApplied = migration.name
+		}
+		for (const migration of migrations) {
+			if (lastApplied === undefined || compareNames(migration.name, lastApplied) >= 0) break
+			if (!applied.has(`${migration.bundle}/${migration.name}`)) {
+				throw new SqliteMigrationError(
+					`SQLite migration ${migration.bundle}/${migration.name} sorts before ${migration.bundle}/${lastApplied}, which is already applied; rename it to sort after it`,
+				)
+			}
+		}
+	}
+}
+
+/**
+ * Applies every migration the ledger does not record, each in its own transaction together with its ledger row, so a
+ * failing one leaves nothing of itself and keeps the ones before it. A bundle's digest is recorded in the transaction
+ * of its last file, or alone when nothing of it was pending; while every bundle matches its digest, the ledger is not
+ * read. Answers the identities it applied.
+ */
+export async function migrateSqlite(
+	target: SqliteMigrationTarget,
+	bundles: readonly SqliteMigrationBundle[],
+): Promise<{ readonly applied: readonly string[] }> {
+	const planned = await plan(bundles)
+	const digests = readDigests(target, planned)
+	if (planned.every((bundle) => digests.get(bundle.bundle) === bundle.digest)) return { applied: [] }
+	const recorded = readLedger(target)
+	verify(planned, recorded)
+	target.exec(LEDGER_DDL)
+	const applied: string[] = []
+	for (const bundle of planned) {
+		if (digests.get(bundle.bundle) === bundle.digest) continue
+		const pending = bundle.migrations.filter((migration) => !recorded.has(`${migration.bundle}/${migration.name}`))
+		if (pending.length === 0) target.transactionSync(() => recordDigest(target, bundle))
+		for (const [index, migration] of pending.entries()) {
+			const identity = `${migration.bundle}/${migration.name}`
+			try {
+				target.transactionSync(() => {
+					target.exec(migration.sql)
+					target.exec(
+						`INSERT INTO ${LEDGER} (bundle, name, checksum, applied_at) VALUES (?, ?, ?, ?)`,
+						migration.bundle,
+						migration.name,
+						migration.checksum,
+						new Date().toISOString(),
+					)
+					if (index === pending.length - 1) recordDigest(target, bundle)
+				})
+			} catch (error) {
+				throw new SqliteMigrationError(`SQLite migration ${identity} failed`, { cause: error })
+			}
+			applied.push(identity)
+		}
+	}
+	return { applied }
+}