@workerstack/database 0.21.0 → 0.22.1

package/src/migrate/core/pg-server-snapshot.ts

@@ -2,8 +2,9 @@
  * The server's shared catalogs read as committed, in one query: what a bare
  * statement changed, which no transaction counts, and what a second connection committed, which this
  * backend's counts never see (pg-server-writes.ts). The read is the server's, another session's work
- * in it too, so each row carries the names of the objects it is about, and a change is a file's only
- * when one is a name the file spells (namesIn in sql-code.ts). A replay's own rows are left out, but
+ * in it too, so each row carries the names of the objects it is about: a change is a file's when it
+ * is to the replay's own database, or to a name the file spells (namesIn in sql-code.ts) beside a
+ * statement that can run code comb cannot read (pg-replay-hidden.ts). A replay's own rows are left out, but
  * for the fields of its own database's row that keep the cleanup from dropping it, which only that
  * replay changes. Beside the catalogs, the server's replication slots, which no catalog
  * holds.
@@ -142,27 +143,6 @@ function snapshotChanges(before: Snapshot, after: Snapshot, names?: ReadonlySet<
 	return changes
 }
 
-/** What the cleanup drops, by the noun its subject starts with */
-type Strays = { databases: string[]; roles: string[]; slots: string[] }
-
-// lookup-table: the nouns of what a file adds that the cleanup drops, by where it keeps them
-const DROPPED: ReadonlyArray<[keyof Strays, string]> = [
-	["databases", "database "],
-	["roles", "role "],
-	["slots", "replication slot "],
-]
-
-/** The roles, databases and replication slots named in `names` that `after` holds and `before` does not */
-function added(before: Snapshot, after: Snapshot, names: ReadonlySet<string>): Strays {
-	const out: Strays = { databases: [], roles: [], slots: [] }
-	for (const subject of after.keys()) {
-		if (before.has(subject) || !about(subject, { after, before }, names)) continue
-		const [where, noun] = DROPPED.find(([, prefix]) => subject.startsWith(prefix)) ?? []
-		if (where !== undefined) out[where].push(subject.slice(noun?.length))
-	}
-	return out
-}
-
 /** The subscriptions `after` holds in `database` and `before` does not, by subject: its drop takes them */
 const subscriptionsIn = (before: Snapshot, after: Snapshot, database: string): string[] =>
 	[...after]
@@ -171,4 +151,4 @@ const subscriptionsIn = (before: Snapshot, after: Snapshot, database: string): s
 		)
 		.map(([subject]) => subject)
 
-export { added, prepareSnapshot, type Snapshot, snapshot, snapshotChanges, type Strays, subscriptionsIn }
+export { prepareSnapshot, type Snapshot, snapshot, snapshotChanges, subscriptionsIn }

package/src/migrate/core/proof-readers.ts

@@ -0,0 +1,80 @@
+/**
+ * What a file leaves unable to run: SQLite's DROP TABLE and DROP VIEW check no view or trigger that names what they
+ * drop, and SQLite, D1 and libsql resolve those names only when a statement runs. So a file can apply and leave every
+ * read of a view, or every write a trigger fires on, failing. After a file applies to the proof's copy, each view and
+ * trigger that survives it and names an object the file dropped or changed is compiled: a view's read, a trigger's
+ * own write on its table or view (trigger-write.mjs). SQLite resolves a name only by name, and the copy holds every
+ * reader that names a table a file reaches (proof-scope.ts), so this finds every reader the file breaks.
+ */
+import type { LocalDb } from "../drivers/local-db.ts"
+import type { LiveObject } from "./proof-copy.ts"
+import { referencesOf } from "./proof-scope.ts"
+import { asciiFold } from "./sql-code.ts"
+import { quote, triggerEvent, writeOf } from "./trigger-write.mjs"
+
+/** The copy's schema, each object by type and folded name */
+function schemaOf(db: LocalDb): Map<string, LiveObject> {
+	const rows = db.all("SELECT type, name, sql, tbl_name FROM main.sqlite_master WHERE sql IS NOT NULL")
+	return new Map(
+		rows.map((row) => {
+			const object = {
+				name: String(row["name"]),
+				sql: String(row["sql"]),
+				table: String(row["tbl_name"]),
+				type: String(row["type"]),
+			}
+			return [`${object.type} ${asciiFold(object.name)}`, object]
+		}),
+	)
+}
+
+/** SQLite's error compiling `sql`, or undefined */
+function compileError(db: LocalDb, sql: string): string | undefined {
+	try {
+		db.all(`EXPLAIN ${sql}`)
+		return undefined
+	} catch (error) {
+		// reason: what SQLite refuses to compile is the finding
+		return (error as Error).message
+	}
+}
+
+/** Why `reader`, a view or a trigger, fails on `db`, or undefined */
+function brokenRead(db: LocalDb, reader: LiveObject): string | undefined {
+	if (reader.type === "view") {
+		const error = compileError(db, `SELECT * FROM ${quote(reader.name)}`)
+		return error === undefined ? undefined : `view ${reader.name} cannot be read: ${error}`
+	}
+	const event = triggerEvent(reader.sql)
+	const columns = db
+		.all(`PRAGMA main.table_xinfo(${quote(reader.table)})`)
+		.filter((row) => row["hidden"] === 0)
+		.map((row) => String(row["name"]))
+	const error = compileError(db, writeOf(reader.table, event, columns))
+	return error === undefined
+		? undefined
+		: `every ${event} on ${reader.table} fails, as a trigger it fires cannot compile: ${error}`
+}
+
+/**
+ * Throws when a file that turned the copy's schema `before` into `db`'s leaves a view or trigger unable to run,
+ * naming it and SQLite's error: no approval overrides, since every read or write through it would fail
+ */
+function refuseBrokenReaders(db: LocalDb, before: ReadonlyMap<string, LiveObject>): void {
+	const after = schemaOf(db)
+	const touched = new Set(
+		[...before]
+			.filter(([key, object]) => after.get(key)?.sql !== object.sql)
+			.map(([, object]) => asciiFold(object.name)),
+	)
+	if (touched.size === 0) return
+	for (const reader of after.values()) {
+		if (reader.type !== "view" && reader.type !== "trigger") continue
+		if (![...referencesOf(reader)].some((name) => touched.has(name))) continue
+		const broken = brokenRead(db, reader)
+		if (broken !== undefined)
+			throw new Error(`after this file, ${broken}; drop or change it in this file, or keep what it uses`)
+	}
+}
+
+export { refuseBrokenReaders, schemaOf }

package/src/migrate/core/proof-run.ts

@@ -12,7 +12,8 @@
  * Seeded rows cannot meet every predicate a file holds, so what each statement writes is read from
  * SQLite itself as it runs (proof-engine.ts): an update of a column that was there before, a
  * delete, a trigger fired or a temp shadow is unsafe whichever rows it meets, and a backfill of the
- * file's own columns is cautious. A file the copy cannot run is unproven, and unproven is unsafe.
+ * file's own columns is cautious. A file the copy cannot run is unproven, and unproven is unsafe. A
+ * file that leaves a view or trigger unable to run is refused outright (proof-readers.ts).
  */
 import { isMirror, mirrorFindings, mirrorRows } from "./proof-mirror.ts"
 import { type LocalDb, openScratch, type ScratchEngine } from "../drivers/local-db.ts"
@@ -21,6 +22,7 @@ import { notEngineTables } from "./engine-tables.ts"
 import { compare, type Shape } from "./proof-compare.ts"
 import { type Copy, copyOf, buildCopy, creatable, jsonColumns, type LiveObject, liveObjects } from "./proof-copy.ts"
 import { applyToCopy, engineFindings } from "./proof-engine.ts"
+import { refuseBrokenReaders, schemaOf } from "./proof-readers.ts"
 import { quote } from "./proof-seed.ts"
 import { observable } from "./proof-scope.ts"
 import { asciiFold } from "./sql-code.ts"
@@ -174,7 +176,10 @@ function snapshotAfter(db: Copy["db"]): Map<string, Shape> | string {
 	}
 }
 
-/** The proof of a file that applied as `run`, from the copy's tables and mirrored rows before it and its tables after */
+/**
+ * The proof of file `name`, which applied as `run`, from the copy's tables, mirrored rows and schema before it and its
+ * tables after; throws, naming the file, when it leaves a view or trigger unable to run, which no approval overrides
+ */
 function appliedProof(
 	copy: Copy,
 	run: ReturnType<typeof applyToCopy>,
@@ -182,8 +187,17 @@ function appliedProof(
 		after,
 		before,
 		mirrors,
-	}: { after: Map<string, Shape>; before: Map<string, Shape>; mirrors: ReturnType<typeof mirrorRows> },
+		name,
+		schema,
+	}: {
+		after: Map<string, Shape>
+		before: Map<string, Shape>
+		mirrors: ReturnType<typeof mirrorRows>
+		name: string
+		schema: ReturnType<typeof schemaOf>
+	},
 ): Proof {
+	named(name, () => refuseBrokenReaders(copy.db, schema))
 	const found = compare(copy.db, new Map([...before].filter(([table]) => !copy.unproven.has(table))), after)
 	const steps = engineFindings(run.steps, run.start)
 	return {
@@ -228,7 +242,7 @@ async function provePending(
 				proofs.set(name, failedProof(copy, failed))
 				continue
 			}
-			let [before, mirrors] = [snapshot(copy.db), mirrorRows(copy.db)]
+			let [before, mirrors, schema] = [snapshot(copy.db), mirrorRows(copy.db), schemaOf(copy.db)]
 			let run = named(name, () => applyToCopy(copy.db, sql))
 			const retry = run.error === undefined ? undefined : await reseeded(objects, applied, making)
 			if (retry !== undefined) {
@@ -263,7 +277,7 @@ async function provePending(
 				failed = `an earlier pending file, ${name}, left a table SQLite cannot read, so this one is unproven`
 				continue
 			}
-			proofs.set(name, appliedProof(copy, run, { after, before, mirrors }))
+			proofs.set(name, appliedProof(copy, run, { after, before, mirrors, name, schema }))
 		}
 	} finally {
 		copy.db.close()

package/src/migrate/core/proof-scope.ts

@@ -3,15 +3,17 @@
  * can observe, created, and the tables whose rows they can observe, seeded, so the copy refuses what the whole
  * schema would and costs what the files reach.
  *
- * - An object's references are every name its text spells (sql-code's lexer, compared folded, never as a substring)
- *   and, for a virtual table, each string and quoted name among its module's arguments, whole. A table's FK parents
- *   are the other tables it references; a reader is a view, a trigger or a virtual table, and reads what it references.
+ * - An object's references are every name its text spells where SQLite's grammar takes a name (sql-code's lexer,
+ *   compared folded, never as a substring: the `TABLE` of `CREATE TABLE` is no name) and, for a virtual table, each
+ *   word, string and quoted name among its module's arguments, whole. A table's FK parents are the other tables it
+ *   references; a reader is a view, a trigger or a virtual table, and reads what it references.
  * - N: each live object whose name a file spells, and the history table; S is N's tables, which a file creates,
  *   alters, drops, renames or writes.
  * - Rows go to S, each table a reader reached from S references (to a fixpoint), D (their FK descendants: a cascade
  *   reaches them) and A (the FK ancestors of all those: their keys must be met).
  * - The copy creates N, the seeded tables, and each reader that references an S table (SQLite checks views and
- *   triggers on DROP COLUMN and RENAME COLUMN, and a rename rewrites them). Then to a fixpoint each index and trigger
+ *   triggers on DROP COLUMN and RENAME COLUMN, and a rename rewrites them) or a view of N (a file that drops the
+ *   view leaves the reader unable to run, which the proof compiles it to see). Then to a fixpoint each index and trigger
  *   on a created table or view (a view's INSTEAD OF triggers carry out a write through it), each table and view a
  *   created reader references, and each created table's FK ancestors, which a write to it compiles checks against.
  * - Reflection reads the schema itself: a name with SQLite's reserved `sqlite_` prefix (its catalogs, sqlite_sequence,
@@ -66,24 +68,31 @@ const nameOf = ({ kind, text }: Token): string =>
 	asciiFold(kind === "literal" ? text.slice(1, -1).replaceAll("''", "'") : unquote(text))
 
 /**
- * Virtual table `object`'s module, the name after USING however it is written, and each string and quoted name among
- * the module's arguments, which the module may read as a table's name (fts5vocab, content=)
+ * Virtual table `object`'s module, the name after USING however it is written, each string and quoted name among
+ * the module's arguments, which the module may read as a table's name (fts5vocab, content=), and each bare word there
  */
-function virtualOf(object: LiveObject): { args: string[]; module: string } | undefined {
+function virtualOf(object: LiveObject): { args: string[]; module: string; words: string[] } | undefined {
 	if (!isVirtual(object)) return undefined
 	const tokens = tokensOf(object.sql)
 	const at = tokens.findIndex(({ kind, text }) => kind === "code" && /^using$/i.test(text)) + 1
-	const args = tokens[at + 1]?.text === "(" ? tokens.slice(at + 2).filter(({ kind }) => kind !== "code") : []
-	return { args: args.map(nameOf), module: nameOf(tokens[at] as Token) }
+	const inside = tokens[at + 1]?.text === "(" ? tokens.slice(at + 2) : []
+	return {
+		args: inside.filter(({ kind }) => kind !== "code").map(nameOf),
+		module: nameOf(tokens[at] as Token),
+		words: inside.filter(({ kind, text }) => kind === "code" && /^[A-Za-z_\u0080-\uffff]/.test(text)).map(nameOf),
+	}
 }
 
 /** The folded names of the shadow tables virtual table `object`'s module makes */
 const shadowsOf = (object: LiveObject): string[] =>
 	(SHADOWS[virtualOf(object)?.module as string] ?? []).map((suffix) => asciiFold(`${object.name}_${suffix}`))
 
-/** Every name `object` references, folded (see the module's comment) */
+/**
+ * Every name `object` references, folded (see the module's comment). A virtual table's module reads its own arguments,
+ * not SQL, so each bare word among them may name a table, `group` in `content=group` among them
+ */
 const referencesOf = (object: LiveObject): Set<string> =>
-	new Set([...sqliteNames(object.sql), ...(virtualOf(object)?.args ?? [])])
+	new Set([...sqliteNames(object.sql), ...(virtualOf(object)?.args ?? []), ...(virtualOf(object)?.words ?? [])])
 
 /* a name SQLite reserves for its own tables, or a pragma's table-valued function: either reads the schema itself */
 const REFLECTION = /^(?:sqlite_|pragma_)/
@@ -216,9 +225,13 @@ function observable(
 	const statements = files.flatMap(({ sql }) => splitSqlStatements(sql))
 	const checks = objects.filter((object) => object.type === "view" || object.type === "trigger")
 	/* a rename rewrites the text of each view and trigger naming an S table, and D1 then compiles the writes to its
-	   table; a virtual table reading one reads the rows a file writes */
+	   table; a virtual table reading one reads the rows a file writes; a drop of a view of N breaks each reading it */
+	const reached = new Set([
+		...s,
+		...n.filter((object) => object.type === "view").map((object) => asciiFold(object.name)),
+	])
 	const rewritten = objects.filter(
-		(object) => isReader(object) && [...(graph.names.get(object) as Set<string>)].some((name) => s.has(name)),
+		(object) => isReader(object) && [...(graph.names.get(object) as Set<string>)].some((name) => reached.has(name)),
 	)
 	/* a write to a created table compiles its keys' checks, which need each parent table */
 	let made = forward(graph, [...n, ...objectsOf(graph, seeded), ...rewritten])
@@ -240,4 +253,4 @@ function observable(
 	return { objects: kept, seeded }
 }
 
-export { isVirtual, observable, type Scope, shadowsOf, virtualOf }
+export { isVirtual, observable, referencesOf, type Scope, shadowsOf, virtualOf }

package/src/migrate/core/sql-code.ts

@@ -4,7 +4,8 @@
  * an action list splits only at its top-level commas.
  */
 import type { Dialect } from "../types.ts"
-import { bodyText, joined, segments } from "../../sql-lexer.ts"
+import { bodyText, segments } from "../../sql-lexer.ts"
+import { NEVER_NAMES } from "./sqlite-keywords.ts"
 
 /** One name part: double-quoted, backtick or bracket quoted, or bare */
 const IDENT: string = `(?:"(?:[^"]|"")*"|\`[^\`]*\`|\\[[^\\]]*\\]|[A-Za-z_\\u0080-\\uffff][\\w$\\u0080-\\uffff]*)`
@@ -100,13 +101,43 @@ function pragmaOf(code: string): Pragma | undefined {
 const qualifiedKey = (name: string): string =>
 	[...name.matchAll(PARTS)].map((match) => partKey(match[0], "sqlite")).join(".")
 
+/* the words and punctuation of SQLite code: a bare word, or one character that breaks a run of words */
+const CODE_TOKEN = /[A-Za-z_\u0080-\uffff][\w$\u0080-\uffff]*|\S/g
+
 /**
- * Every name SQLite code can spell, as SQLite resolves one: each bare word and each quoted name unquoted, and each
- * word of a string, which SQLite reads as a name where one stands (`FROM 'post'`) and a module as its option's
- * (`content='post'`), folded by asciiFold; never a word of a comment
+ * Every name SQLite code can spell, as SQLite resolves one: each quoted name unquoted, each word of a string, which
+ * SQLite reads as a name where one stands (`FROM 'post'`) and a module as its option's (`content='post'`), and each
+ * bare word that can be one, all folded by asciiFold; never a word of a comment. A bare keyword is no name
+ * where SQLite's grammar takes none: `TABLE`, `CREATE`, `NULL` and the rest of NEVER_NAMES whenever it is bare, and
+ * `KEY` after `PRIMARY` or `FOREIGN`, which no name can follow. So a table named `table` is named by `"table"` and
+ * not by the `CREATE TABLE` of every file. Any other bare word may be a name and is read as one: a name read
+ * where there is none only widens what a proof copies, a name missed would narrow it
  */
 function sqliteNames(sql: string): Set<string> {
-	return new Set([...joined(sql, "sqlite", true).matchAll(PARTS)].map((match) => partKey(match[0], "sqlite")))
+	const names = new Set<string>()
+	const quoted = (text: string) => {
+		for (const match of text.matchAll(PARTS)) names.add(partKey(match[0], "sqlite"))
+	}
+	let before: string | undefined
+	for (const { kind, text } of segments(sql, "sqlite")) {
+		if (kind === "comment") continue
+		if (kind !== "code") {
+			quoted(text)
+			before = undefined
+			continue
+		}
+		for (const [token] of text.matchAll(CODE_TOKEN)) {
+			if (!/^[A-Za-z_\u0080-\uffff]/.test(token)) {
+				before = undefined
+				continue
+			}
+			const word = asciiFold(token)
+			const keyword = NEVER_NAMES.has(word) || (word === "key" && (before === "primary" || before === "foreign"))
+			if (!keyword) names.add(word)
+			before = word
+		}
+	}
+	return names
 }
 
 /* a bare word in Postgres code, which may be a name */

package/src/migrate/core/sql-scan.ts

@@ -67,9 +67,15 @@ function readCode(reading: Reading, text: string): string[] {
 	return done
 }
 
+/* SQLITE_SPACE's whitespace at either end of a statement */
+const SQLITE_EDGE_SPACE = /^[\t\n\f\r ]+|[\t\n\f\r ]+$/g
+
 /** The statement read so far, reset for the next; empty when it held no code */
 function finish(reading: Reading): string {
-	const statement = reading.code.replace(/;/g, "").trim() === "" ? "" : reading.text.trim()
+	const statement =
+		reading.code.replace(/;/g, "").replace(SQLITE_EDGE_SPACE, "") === ""
+			? ""
+			: reading.text.replace(SQLITE_EDGE_SPACE, "")
 	reading.code = ""
 	reading.state = 0
 	reading.text = ""

package/src/migrate/core/sqlite-keywords.ts

@@ -0,0 +1,70 @@
+/**
+ * The words SQLite reads only as keywords when they stand bare in code: no table, column, index, view,
+ * trigger or alias can be named by one unless it is quoted. The other keywords (`key`, `end`, `action`, `left`,
+ * `if`) SQLite takes as a name where its grammar wants one, so a bare one may be a name and is read as one.
+ * The list is the engine's: tests/sqlite-keywords.test.ts holds every word here to SQLite's refusal as each kind of
+ * name, in node:sqlite's SQLite and libsql's. `nothing` and `returning` are left out, as an SQLite before 3.24 and
+ * 3.35 reads them as plain names.
+ */
+
+// lookup-table: the keywords no bare name can be, lower case, by the engine's own refusal
+const NEVER_NAMES: ReadonlySet<string> = /* @__PURE__ */ new Set([
+	"add",
+	"all",
+	"alter",
+	"and",
+	"as",
+	"autoincrement",
+	"between",
+	"case",
+	"check",
+	"collate",
+	"commit",
+	"constraint",
+	"create",
+	"default",
+	"deferrable",
+	"delete",
+	"distinct",
+	"drop",
+	"else",
+	"escape",
+	"except",
+	"exists",
+	"foreign",
+	"from",
+	"group",
+	"having",
+	"in",
+	"index",
+	"insert",
+	"intersect",
+	"into",
+	"is",
+	"isnull",
+	"join",
+	"limit",
+	"not",
+	"notnull",
+	"null",
+	"on",
+	"or",
+	"order",
+	"primary",
+	"references",
+	"select",
+	"set",
+	"table",
+	"then",
+	"to",
+	"transaction",
+	"union",
+	"unique",
+	"update",
+	"using",
+	"values",
+	"when",
+	"where",
+])
+
+export { NEVER_NAMES }

package/src/migrate/core/stopped.ts

@@ -0,0 +1,70 @@
+/**
+ * The one report of a run a signal stopped: which files applied and which did not, as an
+ * object both of a command's outputs render, the human line and the `--json` object. The loop that
+ * applies files holds a step for the length of its work; when a signal comes, the step reads what
+ * committed once the work in flight has ended, prints the line and returns the report, which the
+ * command's own step, held before the loop's and so run after it, reads and prints as JSON. A stop
+ * parks the loop itself (cleanup.ts pastStop), so a run it stopped never throws its own report.
+ */
+import { hold } from "./cleanup.ts"
+import { Refused } from "./refused.ts"
+
+/** The files a stop found applied by the run, and left pending */
+type Found = { applied: string[]; pending: string[] }
+
+/** A run a signal stopped: the signal, and as a Refused the files it applied, left, or may have applied */
+export class Stopped extends Refused {
+	readonly signal: NodeJS.Signals
+
+	constructor(signal: NodeJS.Signals, message: string, files: ConstructorParameters<typeof Refused>[1]) {
+		super(message, files)
+		this.name = "Stopped"
+		this.signal = signal
+	}
+}
+
+const list = (names: readonly string[]) => names.join(", ") || "none"
+
+/**
+ * The report of a run `signal` stopped, whose approved files are `names`: what `read` found, or,
+ * when it cannot read, every one of `names` as unknown, since any of them may have committed
+ */
+async function reportOf(
+	signal: NodeJS.Signals,
+	{ names, read }: { names: readonly string[]; read: () => Promise<Found> },
+): Promise<Stopped> {
+	try {
+		const { applied, pending } = await read()
+		return new Stopped(signal, `Stopped by ${signal}: applied ${list(applied)}; not applied ${list(pending)}`, {
+			applied,
+			pending,
+		})
+	} catch (error) {
+		return new Stopped(
+			signal,
+			`Stopped by ${signal}: comb could not read what was applied: ${(error as Error).message}`,
+			{ pending: [], unknown: names },
+		)
+	}
+}
+
+/**
+ * `work`, with a step held while it runs that, on a signal, says on `print` which of `names` the run
+ * applied and which it did not, as `read` finds them once the work in flight has ended (cleanup.ts
+ * runs a child's own step before this one), and returns the report. The process then ends by the signal.
+ */
+export async function whileStoppable<T>(
+	{ names, print, read }: { names: readonly string[]; print: (line: string) => void; read: () => Promise<Found> },
+	work: () => Promise<T>,
+): Promise<T> {
+	const release = hold(async (signal) => {
+		const stopped = await reportOf(signal, { names, read })
+		print(stopped.message)
+		return stopped
+	})
+	try {
+		return await work()
+	} finally {
+		release()
+	}
+}

package/src/migrate/core/trigger-write.d.mts

@@ -0,0 +1,7 @@
+/** A write a table takes */
+export type Event = "DELETE" | "INSERT" | "UPDATE"
+
+export const EVENTS: readonly ["INSERT", "UPDATE", "DELETE"]
+export function quote(name: string): string
+export function triggerEvent(sql: string): Event
+export function writeOf(table: string, event: Event, columns: readonly string[]): string

package/src/migrate/core/trigger-write.mjs

@@ -0,0 +1,42 @@
+/**
+ * The write that compiles a trigger: SQLite compiles a trigger's body into the program of each statement of its
+ * event on its table or view, so `EXPLAIN` of that statement resolves every name the body uses and every function
+ * it calls. A view takes a write only for an event an INSTEAD OF trigger on it fires on; for any other event SQLite
+ * answers "cannot modify ... because it is a view", and no program exists to fail. Plain JavaScript, shared by the
+ * D1 proof's child (d1-engine-child.mjs), which node runs untransformed, and the SQLite proof (proof-readers.ts).
+ */
+
+/** The writes a table takes, in the order the proofs compile them */
+export const EVENTS = /** @type {const} */ (["INSERT", "UPDATE", "DELETE"])
+
+/** @param {string} name */
+export const quote = (name) => `"${name.replaceAll('"', '""')}"`
+
+/* what in SQL text may spell any word: a comment, a string, a quoted name */
+const HIDDEN = /--[^\n]*|\/\*[\s\S]*?(?:\*\/|$)|'(?:[^']|'')*'|"(?:[^"]|"")*"|`(?:[^`]|``)*`|\[[^\]]*\]/g
+
+/**
+ * The event of trigger text `sql`, as sqlite_master holds it: the first bare INSERT, UPDATE or DELETE outside a
+ * comment, a string and a quoted name. CREATE TRIGGER's grammar puts the event before ON and the body, and no bare
+ * name before it can be one of those keywords
+ * @param {string} sql
+ * @returns {"DELETE" | "INSERT" | "UPDATE"}
+ */
+export function triggerEvent(sql) {
+	const event = /** @type {RegExpExecArray} */ (/\b(DELETE|INSERT|UPDATE)\b/i.exec(sql.replace(HIDDEN, " ")))
+	return /** @type {"DELETE" | "INSERT" | "UPDATE"} */ (/** @type {string} */ (event[1]).toUpperCase())
+}
+
+/**
+ * The statement of `event` on `table` that compiles each trigger it fires and each generated column it computes:
+ * an insert of defaults, an update assigning each of `columns` (the stored and virtual ones, by name) to itself, a
+ * delete
+ * @param {string} table
+ * @param {"DELETE" | "INSERT" | "UPDATE"} event
+ * @param {readonly string[]} columns
+ */
+export function writeOf(table, event, columns) {
+	if (event === "INSERT") return `INSERT INTO ${quote(table)} DEFAULT VALUES`
+	if (event === "DELETE") return `DELETE FROM ${quote(table)}`
+	return `UPDATE ${quote(table)} SET ${columns.map((column) => `${quote(column)} = ${quote(column)}`).join(", ")}`
+}

package/src/pg/columns.ts

@@ -31,6 +31,8 @@ import type {
 	EnumOptions,
 	IntegerConstraints,
 	JsonConstraints,
+	RealConstraints,
+	RefConstraints,
 	TextConstraints,
 	TimestampConstraints,
 } from "../sqlite/constraints.ts"
@@ -100,9 +102,9 @@ export type PgColumns = {
 		_constraints?: JsonConstraints,
 	) => Set$Type<PgJsonbBuilder, z.infer<TSchema>>
 	/** a floating-point number, stored as double precision */
-	real: (name: string, _constraints?: IntegerConstraints) => PgDoublePrecisionBuilder
+	real: (name: string, _constraints?: RealConstraints) => PgDoublePrecisionBuilder
 	/** a text foreign key; chain `.references()` to name the column it points at */
-	ref: (name: string, _constraints?: TextConstraints) => Text
+	ref: (name: string, _constraints?: RefConstraints) => Text
 	/** the auto-incrementing 4-byte `serial` primary key `id`, filled by the database */
 	serialId: () => SetIsPrimaryKey<PgSerialBuilder>
 	/**
@@ -158,11 +160,11 @@ export const c: PgColumns = {
 		withCombColumn(jsonb(name).$type<z.infer<TSchema>>(), { constraints, kind: "json", schema }),
 
 	/* Floating point (double precision) */
-	real: (name: string, constraints?: IntegerConstraints) =>
+	real: (name: string, constraints?: RealConstraints) =>
 		withCombColumn(doublePrecision(name), { constraints, kind: "real" }),
 
 	/* Foreign key reference - use with .references() */
-	ref: (name: string, constraints?: TextConstraints) => withCombColumn(text(name), { constraints, kind: "ref" }),
+	ref: (name: string, constraints?: RefConstraints) => withCombColumn(text(name), { constraints, kind: "ref" }),
 
 	/* Auto-increment integer primary key */
 	serialId: () => withCombColumn(serial("id").primaryKey(), { kind: "serialId" }),

package/src/query/cursor-mint.ts

@@ -3,13 +3,12 @@
  * MAX_CURSOR_LENGTH, a value too long for it carried by reference (cursor-ref.ts) on a table's
  * list, and refused on a derived list, which no row holds to read a reference back from.
  */
-import { CombError } from "../error.ts"
-import { combErrorKeys } from "../types.ts"
 import { cursorBytes, CursorRef, MAX_CURSOR_LENGTH } from "./cursor.ts"
 import { readsApart } from "./cursor-reads.ts"
 import { type CursorOptions, seal, sealedLength } from "./cursor-seal.ts"
 import { roundedKey } from "./rounded-key.ts"
 import type { SortField } from "./types.ts"
+import { UnmintableRow } from "./cursor-refusals.ts"
 
 /**
  * The open's column check a builder hands the mint: the index of the first value, the tiebreak id last,
@@ -37,7 +36,7 @@ function longestFitting(record: Record<string, unknown>, field: string, fits: (r
 }
 
 /** The overflow, as paginate reports it on the page that met it: a 500 naming the field and the cap */
-function tooLong(fields: string, length: number, kind: KeysetKind | "unread"): CombError {
+function tooLong(fields: string, length: number, kind: KeysetKind | "unread"): UnmintableRow {
 	const reasons = {
 		derived: "a derived list reads no row to page by reference, so sort it by a key of bounded length",
 		merged:
@@ -47,11 +46,9 @@ function tooLong(fields: string, length: number, kind: KeysetKind | "unread"): C
 			"its long key is a column not of the anchor table, or an expression over one, so no reference reads its value back; sort by a key of bounded length, or by a column of the anchor table",
 	}
 	const reason = reasons[kind]
-	return new CombError({
-		cause: `a row's ${fields} is too long to page this list by: its cursor would be ${length} characters, past ${MAX_CURSOR_LENGTH}; ${reason}`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	return new UnmintableRow(
+		`a row's ${fields} is too long to page this list by: its cursor would be ${length} characters, past ${MAX_CURSOR_LENGTH}; ${reason}`,
+	)
 }
 
 /**
@@ -159,11 +156,9 @@ function refuseInvalidDate(
 		({ field }) => at.asRead(field) && row[field] instanceof Date && Number.isNaN((row[field] as Date).getTime()),
 	)
 	if (unheld === undefined) return
-	throw new CombError({
-		cause: `the sort by ${unheld.field} reads a date no JS Date holds (a Postgres 'infinity' read in date mode, or a SQLite timestamp holding ±Infinity), which this list has no row to read back by, ${at.derived ? "a derived list having none" : "its key being no column of the anchor table"}; select it in string mode or sort by another column`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	throw new UnmintableRow(
+		`the sort by ${unheld.field} reads a date no JS Date holds (a Postgres 'infinity' read in date mode, or a SQLite timestamp holding ±Infinity), which this list has no row to read back by, ${at.derived ? "a derived list having none" : "its key being no column of the anchor table"}; select it in string mode or sort by another column`,
+	)
 }
 
 /** A 500 naming the first value of `record` its column does not hold (ColumnCheck), the cursor the next page would refuse */
@@ -179,11 +174,9 @@ function refuseUnfit(
 	const index = options.holds(values, (i) => options.carried?.has(sort[i]?.field ?? "") ?? false)
 	if (index === -1) return
 	const named = sort[index] === undefined ? `the tiebreak id ${idField}` : `the sort by ${sort[index].field}`
-	throw new CombError({
-		cause: `${named} reads a value its column's mode does not hold (a JSON-mode key's, or a SQLite column's of another storage class than its mode reads), which no cursor of this list resumes after; sort by another column`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	throw new UnmintableRow(
+		`${named} reads a value its column's mode does not hold (a JSON-mode key's, or a SQLite column's of another storage class than its mode reads), which no cursor of this list resumes after; sort by another column`,
+	)
 }
 
 export { type ColumnCheck, createCursor, fitCursor, fittedCursor, type KeysetKind }