@fabrika/db 0.8.2 → 0.9.0-cloudflare.2

package/src/stored-files.ts

@@ -9,7 +9,7 @@ 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 { type DialectTexts, fencedTransaction, SQLITE_NOW, sqliteNowPlus, sqliteTimestamp } from './job-leases'
 import { FILE_DELETIONS_TABLE, FILES_TABLE } from './migrations'
 import type { DataLayerRuntime } from './store'
 
@@ -112,55 +112,136 @@ export interface StoredFiles {
 }
 
 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. */
+/** Postgres' code of a foreign key violation, which the SQLite engine maps its own to: the delete of a referenced file. */
 const FOREIGN_KEY_VIOLATION = '23503'
 
 const SERVED_COLUMNS = `id::text as id, kind, name, content_type, size, status, object_key, object_version`
+const SQLITE_SERVED_COLUMNS = `id, kind, name, content_type, size, status, object_key, object_version`
+const N = SQLITE_NOW
+
+const SQL_STAGE: DialectTexts = {
+	postgres: `insert into ${F} (id, kind, status, object_key, content_type, name, request, created_at)
+values ($1::uuid, $2, 'pending', $3, $4, $5, $6, now())`,
+	sqlite: `insert into ${F} (id, kind, status, object_key, content_type, name, request, created_at)
+values (?1, ?2, 'pending', ?3, ?4, ?5, ?6, ${N})`,
+}
 
-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_WRITTEN: DialectTexts = {
+	postgres: `update ${F} set size = $2::bigint, sha256 = $3 where id = $1::uuid and status = 'pending' returning id`,
+	sqlite: `update ${F} set size = cast(?2 as integer), sha256 = ?3 where id = ?1 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`
+// SQLite has no data-modifying CTE: the delete and the record of its object are two statements in one transaction.
+const SQLITE_ABANDON = `delete from ${F} where id = ?1 and status = 'pending' and request = ?2 returning object_key`
+const SQLITE_RECORD_ABANDONED =
+	`insert into ${D} (object_key, recorded_at) values (?1, ${N}) on conflict (object_key) do nothing returning object_key`
 
-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_FIND: DialectTexts = {
+	postgres: `select ${SERVED_COLUMNS} from ${F} where id = $1::uuid`,
+	sqlite: `select ${SQLITE_SERVED_COLUMNS} from ${F} where id = ?1`,
+}
 
-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_REQUARANTINE: DialectTexts = {
+	postgres: `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`,
+	sqlite: `update ${F} set status = 'quarantined', object_version = null, scan_attempts = 0, scan_after = ${N}
+where id = ?1 and status = 'live' and object_version is ?2`,
+}
+
+// The ids are one parameter: a comma-separated list on Postgres, a JSON array on SQLite.
+const SQL_METADATA: DialectTexts = {
+	postgres: `select id::text as id, kind, name, content_type, size, status from ${F}
+where id = any(string_to_array($1, ',')::uuid[])`,
+	sqlite: `select id, kind, name, content_type, size, status from ${F}
+where id in (select value from json_each(?1))`,
+}
 
-const SQL_QUARANTINED = `select id::text as id, object_key, size, sha256, content_type, scan_attempts, coalesce(scan_after, created_at) as due_since
+const SQL_QUARANTINED: DialectTexts = {
+	postgres: `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`
+order by scan_after nulls first, created_at limit $3::int`,
+	sqlite: `select id, object_key, size, sha256, content_type, scan_attempts, coalesce(scan_after, created_at) as due_since
+from ${F} where status = 'quarantined' and kind in (select value from json_each(?1)) and (scan_after is null or scan_after < ?2)
+order by scan_after nulls first, created_at limit ?3`,
+}
 
-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_PROMOTE: DialectTexts = {
+	postgres: `update ${F} set status = 'live', object_version = $3 where id = $1::uuid and status = 'quarantined' and sha256 = $2 returning id`,
+	sqlite: `update ${F} set status = 'live', object_version = ?3 where id = ?1 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_DEFER: DialectTexts = {
+	postgres: `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`,
+	sqlite: `update ${F} set scan_attempts = ?2, scan_after = ?3
+where id = ?1 and status = 'quarantined' and scan_attempts = ?2 - 1 returning id`,
+}
 
-const SQL_REJECT = `update ${F} set status = 'rejected' where id = $1::uuid and status = 'quarantined' returning id`
+const SQL_REJECT: DialectTexts = {
+	postgres: `update ${F} set status = 'rejected' where id = $1::uuid and status = 'quarantined' returning id`,
+	sqlite: `update ${F} set status = 'rejected' where id = ?1 and status = 'quarantined' returning id`,
+}
 
-const SQL_UNFINISHED = `select object_key from ${D} order by recorded_at limit $1::int`
+const SQL_UNFINISHED: DialectTexts = {
+	postgres: `select object_key from ${D} order by recorded_at limit $1::int`,
+	sqlite: `select object_key from ${D} order by recorded_at limit ?1`,
+}
 
-const SQL_FORGET = `delete from ${D} where object_key = $1`
+const SQL_FORGET: DialectTexts = {
+	postgres: `delete from ${D} where object_key = $1`,
+	sqlite: `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`
 
+const SQLITE_REMOVE = `delete from ${F} where id = ?1 and legacy is null and created_at < ${sqliteNowPlus('-?2')} returning object_key`
+const SQLITE_RECORD_REMOVED = `insert into ${D} (object_key, recorded_at) values (?1, ${N}) 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_LOCK: DialectTexts = {
+	postgres: `select kind, status, request, scope, created_at > now() - $2::bigint * interval '1 millisecond' as fresh
+from ${F} where id = $1::uuid for share`,
+	// No lock: while the reference write's transaction is open, the Durable Object runs no sweep.
+	sqlite: `select kind, status, request, scope, created_at > ${sqliteNowPlus('-?2')} as fresh
+from ${F} where id = ?1`,
+}
 
-const SQL_CLAIM = `update ${F} set status = $2 where id = $1::uuid and status = 'pending' returning id`
+const SQL_CLAIM: DialectTexts = {
+	postgres: `update ${F} set status = $2 where id = $1::uuid and status = 'pending' returning id`,
+	sqlite: `update ${F} set status = ?2 where id = ?1 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`
+const SQL_STAMP: DialectTexts = {
+	postgres: `update ${F} set scope = $2 where id = $1::uuid and (scope is null or scope = $2) returning id`,
+	sqlite: `update ${F} set scope = ?2 where id = ?1 and (scope is null or scope = ?2) returning id`,
+}
+
+/** Runs the text of `session`'s dialect. */
+function run(session: Session, texts: DialectTexts, parameters: readonly FixedParameter[]): Promise<readonly unknown[]> {
+	return runFixedStatement(session, texts[session.dialect], parameters)
+}
+
+/**
+ * SQLite's form of a delete that records its object for deletion: the delete, then the record, in one transaction.
+ * The record's object key, or `null` when nothing was deleted or recorded.
+ */
+function deleteAndRecord(session: Session, deletion: string, parameters: readonly FixedParameter[], recording: string): Promise<string | null> {
+	return session.transaction(async (transaction) => {
+		const [gone] = await runFixedStatement(transaction, deletion, parameters)
+		if (gone === undefined) {
+			return null
+		}
+		const [recorded] = await runFixedStatement(transaction, recording, [text(record(gone), 'object_key')])
+		return recorded === undefined ? null : text(record(recorded), 'object_key')
+	})
+}
 
 /** `exists (select 1 from <table> where <column> = f.id)`, one per column, over the policies' validated identifiers. */
 function referencedBy(columns: readonly FileColumnRef[]): string {
@@ -227,8 +308,9 @@ function status(row: Readonly<Record<string, unknown>>): StoredFileStatus {
 	return found
 }
 
-function date(row: Readonly<Record<string, unknown>>, column: string): Date {
-	const value = row[column]
+/** A timestamp column: a `Date` from Postgres, a stored ISO text from SQLite. */
+function date(session: Session, row: Readonly<Record<string, unknown>>, column: string): Date {
+	const value = session.dialect === 'sqlite' ? sqliteTimestamp(row[column], `${F}.${column}`) : row[column]
 	if (!(value instanceof Date)) {
 		throw new QueryRefusedError('unexpected_row', `${F}.${column} came back as ${typeof value}`)
 	}
@@ -248,7 +330,7 @@ function metaOf(row: Readonly<Record<string, unknown>>): StoredFileMeta {
 
 /** 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')])
+	const [found] = await run(session, SQL_LOCK, [uuid(id), positive(graceMs, 'a pending grace')])
 	if (found === undefined) {
 		return null
 	}
@@ -258,13 +340,14 @@ export async function lockStoredFile(session: Session, id: string, graceMs: numb
 		status: status(row),
 		request: nullableText(row, 'request'),
 		scope: nullableText(row, 'scope'),
-		fresh: row['fresh'] === true,
+		// SQLite answers a comparison as 1 or 0.
+		fresh: row['fresh'] === (session.dialect === 'sqlite' ? 1 : 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])
+	const rows = await run(session, SQL_CLAIM, [uuid(id), ended])
 	if (rows.length !== 1) {
 		throw new QueryRefusedError('unexpected_row', 'a pending file changed under its lock')
 	}
@@ -272,7 +355,7 @@ export async function claimStoredFile(session: Session, id: string, ended: 'quar
 
 /** 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
+	return (await run(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. */
@@ -281,7 +364,8 @@ export async function storedFilesMetadata(using: Session, ids: readonly string[]
 	if (unique.length === 0) {
 		return new Map()
 	}
-	const rows = await runFixedStatement(using, SQL_METADATA, [unique.map(uuid).join(',')])
+	const checked = unique.map(uuid)
+	const rows = await run(using, SQL_METADATA, [using.dialect === 'sqlite' ? JSON.stringify(checked) : checked.join(',')])
 	return new Map(rows.map((found) => {
 		const meta = metaOf(record(found))
 		return [meta.id, meta] as const
@@ -290,32 +374,36 @@ export async function storedFilesMetadata(using: Session, ids: readonly string[]
 
 export function storedFiles(runtime: () => DataLayerRuntime): StoredFiles {
 	const session = () => sessionOf(runtime())
-	async function fenced(statement: string, parameters: readonly FixedParameter[]): Promise<boolean> {
+	async function fenced(statement: DialectTexts, 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))
+		const rows = await fencedTransaction(sessionOf(current), fence, (transaction) => run(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])
+			await run(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])
+			const rows = await run(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])
+			const current = session()
+			if (current.dialect === 'sqlite') {
+				return deleteAndRecord(current, SQLITE_ABANDON, [uuid(id), request], SQLITE_RECORD_ABANDONED)
+			}
+			const [found] = await runFixedStatement(current, SQL_ABANDON, [uuid(id), request])
 			return found === undefined ? null : text(record(found), 'object_key')
 		},
 
@@ -323,7 +411,7 @@ export function storedFiles(runtime: () => DataLayerRuntime): StoredFiles {
 			if (!UUID.test(id)) {
 				return null
 			}
-			const [found] = await runFixedStatement(using ?? session(), SQL_FIND, [id])
+			const [found] = await run(using ?? session(), SQL_FIND, [id])
 			if (found === undefined) {
 				return null
 			}
@@ -332,7 +420,7 @@ export function storedFiles(runtime: () => DataLayerRuntime): StoredFiles {
 		},
 
 		async requarantine(id: string, version: string | null): Promise<void> {
-			await runFixedStatement(session(), SQL_REQUARANTINE, [uuid(id), version])
+			await run(session(), SQL_REQUARANTINE, [uuid(id), version])
 		},
 
 		metadata: storedFilesMetadata,
@@ -341,7 +429,9 @@ export function storedFiles(runtime: () => DataLayerRuntime): StoredFiles {
 			if (kinds.length === 0) {
 				return []
 			}
-			const rows = await runFixedStatement(session(), SQL_QUARANTINED, [kinds.join(','), now.toISOString(), positive(limit, 'a scan batch')])
+			const current = session()
+			const listed = current.dialect === 'sqlite' ? JSON.stringify(kinds) : kinds.join(',')
+			const rows = await run(current, SQL_QUARANTINED, [listed, now.toISOString(), positive(limit, 'a scan batch')])
 			return rows.map((found) => {
 				const row = record(found)
 				return freeze({
@@ -351,7 +441,7 @@ export function storedFiles(runtime: () => DataLayerRuntime): StoredFiles {
 					sha256: text(row, 'sha256'),
 					contentType: text(row, 'content_type'),
 					scanAttempts: count(row, 'scan_attempts'),
-					dueSince: date(row, 'due_since'),
+					dueSince: date(current, row, 'due_since'),
 				})
 			})
 		},
@@ -363,33 +453,46 @@ export function storedFiles(runtime: () => DataLayerRuntime): StoredFiles {
 		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')])
+			const rows = await run(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])
+			await run(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
+			const current = session()
+			const statement = current.dialect === 'sqlite'
+				? `update ${F} as f set legacy = null where f.legacy is not null and (${referencedBy(columns)}) returning id`
+				: `update ${F} f set legacy = null where f.legacy is not null and (${referencedBy(columns)}) returning id`
+			return (await runFixedStatement(current, 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
+			const current = session()
+			const statement = current.dialect === 'sqlite'
+				? `select f.id as id from ${F} f
+where f.legacy is null and f.created_at < ${sqliteNowPlus('-?1')} and not (${referencedBy(columns)})
+order by f.created_at limit ?2`
+				: `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')])
+			const rows = await runFixedStatement(current, 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')])
+				const current = session()
+				const parameters = [uuid(id), positive(graceMs, 'a pending grace')]
+				if (current.dialect === 'sqlite') {
+					return await deleteAndRecord(current, SQLITE_REMOVE, parameters, SQLITE_RECORD_REMOVED)
+				}
+				const [found] = await runFixedStatement(current, SQL_REMOVE, parameters)
 				return found === undefined ? null : text(record(found), 'object_key')
 			} catch (error) {
 				if (error instanceof DatabaseError && error.sqlState === FOREIGN_KEY_VIOLATION) {

package/src/tables.ts

@@ -2,10 +2,13 @@
 // driver, so `@fabrika/app/contract` and the static contract reader in `@fabrika/check` import it.
 
 import type { ColumnPolicyArtifact, TableActionArtifact, TablePolicyArtifact, TableScope } from '@fabrika/auth-core'
+import { type ApplicationRowsPlan, planApplicationRows } from './application-rows'
 import { freeze, namesOf, ownEntry, ownKeys, setOwn } from './builtins'
 import { PolicyError } from './errors'
 import { modelOf, type ScopeModel, type TableModel, tableModels, type Tables } from './policy'
 
+export { applicationRowRefusalText } from './application-rows'
+export type { ApplicationRowRefusal, ApplicationRowsPlan } from './application-rows'
 export { PolicyError } from './errors'
 export type { FileReference } from './file-references'
 export type {
@@ -96,6 +99,19 @@ export type {
 	VocabularyTablePolicy,
 } from './vocabulary-tables'
 
+/**
+ * The plan of seeding one row of each application table `rows` names (table → column → value), as an endpoint access
+ * case seeds its `appRows`: the order, the foreign keys that link one given row to another, and every refusal.
+ * `@fabrika/check` reports the refusals from source; `@fabrika/db/testing` throws the first, both in the words of
+ * `applicationRowRefusalText`.
+ */
+export function applicationRowsPlan<DB, P>(
+	tables: Tables<DB, P>,
+	rows: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
+): ApplicationRowsPlan {
+	return planApplicationRows(tableModels(tables), rows)
+}
+
 /** Every table's policy in the form the contract artifact carries, by table name. */
 export type TablePolicies = Readonly<Record<string, TablePolicyArtifact>>
 

package/src/temporal.ts

@@ -3,11 +3,14 @@
 // the database's own text (`cast(<column> as text)`, `nodes.ts`), never through the `Date` `Bun.SQL` decodes: outside
 // 0001–9999 that one drifts by the process's offset and can land on a neighbouring valid day. Only an aggregate's
 // `min`/`max` and a store's joined child column still arrive as a `Date`. The generated column list names the `date`
-// columns (`TableColumns.dates`); every read of a table's rows passes through `answerDays`. A write's text for a day or a
+// columns (`TableColumns.dates`); every read of a table's rows passes through `answerRows` (`answerDays` on Postgres). A write's text for a day or a
 // timestamp is checked here before anything is sent: Postgres would also take `now`, `today` or `10/12/2026`, and read
-// a timestamp without an offset in the session's time zone.
+// a timestamp without an offset in the session's time zone. On SQLite (ADR-0065) a timestamp is stored as UTC ISO text
+// and a boolean as 0 or 1: `storedTimestamp` is what a write binds and `answerRows` turns both back into what Postgres's
+// driver answers.
 
 import { defineValue, inSet, type NameSet, ownDescriptor, ownKeys } from './builtins'
+import type { SqlDialect } from './database'
 import { QueryRefusedError } from './errors'
 
 /** The text Postgres prints for a day in 0001–9999 under its default `DateStyle` (ISO). */
@@ -61,7 +64,7 @@ export function answerDays<R>(table: string, days: NameSet, rows: R[]): R[] {
 }
 
 /** An instant in strict ISO 8601: a day, `T`, the time to the minute or finer, and `Z` or an offset. */
-const TIMESTAMP_TEXT = /^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.[0-9]{1,6})?)?(?:Z|[+-]([0-9]{2}):([0-9]{2}))$/
+const TIMESTAMP_TEXT = /^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.([0-9]{1,6}))?)?(?:Z|([+-])([0-9]{2}):([0-9]{2}))$/
 
 /** Whether `year-month-day` is a day of the calendar: no 30 February, no month 13. */
 function isCalendarDay(year: number, month: number, day: number): boolean {
@@ -78,14 +81,117 @@ export function dayInput(value: string, where: string): string {
 	return value
 }
 
-/** A timestamp a write binds as text: strict ISO 8601 with `Z` or an offset, every field in range. */
-export function timestampInput(value: string, where: string): string {
+/** The instant of strict ISO 8601 text, in milliseconds since the epoch (digits past the millisecond dropped), or `undefined`. */
+function instantOf(value: string): number | undefined {
 	const match = TIMESTAMP_TEXT.exec(value)
-	const [, year, month, day, hour, minute, second = '0', offsetHour = '0', offsetMinute = '0'] = match ?? []
-	const valid = match !== null && isCalendarDay(Number(year), Number(month), Number(day)) && Number(hour) < 24 && Number(minute) < 60
-		&& Number(second) < 60 && Number(offsetHour) < 16 && Number(offsetMinute) < 60
+	if (match === null) {
+		return undefined
+	}
+	const [, year, month, day, hour, minute, second = '0', fraction = '', sign = '+', offsetHour = '0', offsetMinute = '0'] = match
+	const valid = isCalendarDay(Number(year), Number(month), Number(day)) && Number(hour) < 24 && Number(minute) < 60 && Number(second) < 60
+		&& Number(offsetHour) < 16 && Number(offsetMinute) < 60
 	if (!valid) {
-		throw new QueryRefusedError('invalid_value', `${where} takes a Date or ISO 8601 text with Z or an offset, such as 2026-10-12T08:30:00.000Z`)
+		return undefined
+	}
+	// setUTCFullYear, unlike Date.UTC, keeps the years 0001–0099.
+	const date = new Date(0)
+	date.setUTCFullYear(Number(year), Number(month) - 1, Number(day))
+	date.setUTCHours(Number(hour), Number(minute), Number(second), Number(fraction.padEnd(3, '0').slice(0, 3)))
+	const offset = (Number(offsetHour) * 60 + Number(offsetMinute)) * 60_000
+	return date.getTime() - (sign === '-' ? -offset : offset)
+}
+
+function timestampRefused(where: string): QueryRefusedError {
+	return new QueryRefusedError('invalid_value', `${where} takes a Date or ISO 8601 text with Z or an offset, such as 2026-10-12T08:30:00.000Z`)
+}
+
+/** A timestamp a write binds as text: strict ISO 8601 with `Z` or an offset, every field in range. */
+export function timestampInput(value: string, where: string): string {
+	if (instantOf(value) === undefined) {
+		throw timestampRefused(where)
 	}
 	return value
 }
+
+/** A timestamp as SQLite stores it: UTC `Date#toISOString()` text, whose text order is time order. */
+const STORED_TIMESTAMP = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$/
+
+/**
+ * What a write or a comparison binds for a timestamp on SQLite: the instant of a `Date`, or of the text `timestampInput`
+ * admits, as stored text. Digits past the millisecond are dropped; an instant outside the years 0000–9999 UTC is
+ * refused, since its text would not sort.
+ */
+export function storedTimestamp(value: string | Date, where: string): string {
+	const time = typeof value === 'string' ? instantOf(value) : value.getTime()
+	if (time === undefined) {
+		throw timestampRefused(where)
+	}
+	const text = Number.isNaN(time) ? '' : new Date(time).toISOString()
+	if (!STORED_TIMESTAMP.test(text)) {
+		throw new QueryRefusedError(
+			'invalid_value',
+			`${where} holds an instant outside the years 0000-9999 UTC, which SQLite cannot store as sortable text`,
+		)
+	}
+	return text
+}
+
+/** The columns of a read's rows the layer answers in a form of its own, by the name each arrives under. */
+export interface RowColumns {
+	/** `date` columns: `YYYY-MM-DD` text. */
+	readonly days: NameSet
+	/** Timestamps: a `Date` (SQLite answers its stored text). */
+	readonly timestamps: NameSet
+	/** Booleans: `true` or `false` (SQLite answers 1 or 0). */
+	readonly booleans: NameSet
+}
+
+function unexpected(where: string, expected: string): QueryRefusedError {
+	return new QueryRefusedError('unexpected_row', `${where} came back as something other than ${expected}`)
+}
+
+/** One SQLite value of `key` as Postgres's driver answers it; a value the migrations' types never store is refused. */
+function sqliteValue(columns: RowColumns, where: string, key: string, value: unknown): unknown {
+	if (value === null) {
+		return value
+	}
+	if (inSet(columns.timestamps, key)) {
+		if (typeof value !== 'string' || !STORED_TIMESTAMP.test(value)) {
+			throw unexpected(where, 'UTC ISO text (YYYY-MM-DDTHH:MM:SS.sssZ), the form a timestamp is stored in on SQLite')
+		}
+		return new Date(value)
+	}
+	if (inSet(columns.booleans, key)) {
+		if (value !== 0 && value !== 1) {
+			throw unexpected(where, '0 or 1, the form a boolean is stored in on SQLite')
+		}
+		return value === 1
+	}
+	return typeof value === 'string' && inSet(columns.days, key) ? dayText(value, where) : value
+}
+
+/**
+ * Every row of a read as the layer answers it, in place: each day as `YYYY-MM-DD` text, and on SQLite each timestamp as
+ * a `Date` and each boolean as `true` or `false`, so a handler reads the same values on both dialects.
+ */
+export function answerRows<R>(dialect: SqlDialect, table: string, columns: RowColumns, rows: R[]): R[] {
+	if (dialect === 'postgres') {
+		return answerDays(table, columns.days, rows)
+	}
+	for (let index = 0; index < rows.length; index++) {
+		const row = rows[index]
+		if (typeof row !== 'object' || row === null) {
+			continue
+		}
+		const keys = ownKeys(row)
+		for (let position = 0; position < keys.length; position++) {
+			const key = keys[position] ?? ''
+			const value: unknown = ownDescriptor(row, key)?.value
+			const answered = sqliteValue(columns, `${table}.${key}`, key, value)
+			if (answered !== value) {
+				defineValue(row, key, answered)
+			}
+		}
+	}
+	return rows
+}