tablewalk 0.0.1

package/dist/adapters/sqlite.js

@@ -0,0 +1,781 @@
+/**
+ * SQLite adapter, on Node's built-in `node:sqlite`.
+ *
+ * SQLite comes first because it needs no server, which means the tool has a
+ * demo you can run in one command and a test target that does not depend on
+ * anything being installed. It is also the dialect that proves the model is
+ * general: its catalog is nothing like `information_schema`, so anything that
+ * works for both is unlikely to be accidentally Postgres-shaped.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { ANSI_STYLE, buildWhere, clampLimit, clampOffset, boundStatement, looksWrappable, dedupe, refuseStacked, trimStatement, Refusal, Serial, } from './adapter.js';
+import { compileView, compileViewCount } from '../shared/view.js';
+import { compileBreakdown, compileBreakdownCount } from '../shared/breakdown.js';
+import { vocabularyFromDDL } from '../shared/vocabulary.js';
+import { coerceForColumn, deleteRuleOf, } from '../shared/schema.js';
+/**
+ * Wait rather than fail when someone else holds the file.
+ *
+ * A SQLite database is usually a file another process is also using — the
+ * application whose data this is, a migration, a test — and one writer at a
+ * time is the whole locking model. Without a busy timeout the very next read
+ * during someone else's write comes back "database is locked", which reads
+ * as a broken tool rather than as a lock that would have cleared in
+ * milliseconds. Five seconds is long enough to outlast an ordinary write and
+ * short enough that a genuinely stuck writer still surfaces.
+ */
+function waitForLocks(db) {
+    try {
+        db.exec('PRAGMA busy_timeout = 5000');
+    }
+    catch {
+        /* An old build without the pragma is not a reason to refuse the
+           database; it is a reason to be no worse than before. */
+    }
+}
+export class SqliteAdapter {
+    file;
+    label;
+    dialect = 'sqlite';
+    db;
+    /** Opened lazily, only when an edit is actually applied. */
+    writeDb = null;
+    /* Every write on that handle, one at a time. See `Serial`. */
+    writes = new Serial();
+    constructor(file, label = file) {
+        this.file = file;
+        this.label = label;
+        // Read-only by intent as well as by API: this is a browsing tool, and a
+        // browsing tool that can write is a browsing tool that can destroy.
+        this.db = new DatabaseSync(file, { readOnly: true });
+        waitForLocks(this.db);
+    }
+    async introspect() {
+        const tableRows = this.db
+            .prepare(`SELECT name, type, sql FROM sqlite_master
+          WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%'
+          ORDER BY name`)
+            .all();
+        const tables = [];
+        const foreignKeys = [];
+        /* Approximate rows, the way SQLite can afford them: sqlite_stat1 where
+           ANALYZE has run — free, and as current as the last ANALYZE — and a
+           COUNT(*) otherwise, which on a local file is a b-tree scan the once-
+           per-open introspection can absorb. Views stay uncounted: counting one
+           runs its query, and a view is allowed to be expensive. */
+        const analyzed = new Map();
+        try {
+            const stats = this.db
+                .prepare('SELECT tbl, stat FROM sqlite_stat1 WHERE stat IS NOT NULL')
+                .all();
+            for (const s of stats) {
+                // The first number of `stat` is the row estimate; a partial index
+                // reports fewer, so the largest claim across indexes wins.
+                const n = Number(String(s.stat).split(' ')[0]);
+                if (Number.isFinite(n))
+                    analyzed.set(s.tbl, Math.max(analyzed.get(s.tbl) ?? 0, n));
+            }
+        }
+        catch {
+            /* No sqlite_stat1 means no ANALYZE yet, not an error. */
+        }
+        const approxRowsOf = (name, type) => {
+            if (type !== 'table')
+                return undefined;
+            const known = analyzed.get(name);
+            if (known !== undefined)
+                return known;
+            try {
+                const row = this.db.prepare(`SELECT COUNT(*) AS n FROM ${ANSI_STYLE.quote(name)}`).get();
+                return row.n;
+            }
+            catch {
+                // A table the catalog lists can still refuse a scan (a broken
+                // virtual table, say); no count beats no schema.
+                return undefined;
+            }
+        };
+        for (const t of tableRows) {
+            const cols = this.db
+                .prepare(`PRAGMA table_info(${ANSI_STYLE.quote(t.name)})`)
+                .all();
+            const fks = this.db
+                .prepare(`PRAGMA foreign_key_list(${ANSI_STYLE.quote(t.name)})`)
+                .all();
+            /* PRAGMA returns one row per column of a composite key, grouped by `id`.
+               Collapsing them here means the model never has to know that. */
+            const byId = new Map();
+            for (const fk of fks) {
+                const list = byId.get(fk.id) ?? [];
+                list.push(fk);
+                byId.set(fk.id, list);
+            }
+            for (const [id, group] of byId) {
+                const ordered = [...group].sort((a, b) => a.seq - b.seq);
+                foreignKeys.push({
+                    name: `${t.name}_fk_${id}`,
+                    onDelete: deleteRuleOf(ordered[0].on_delete),
+                    from: { table: t.name, columns: ordered.map((f) => f.from) },
+                    // A null `to` means the FK targets the referenced table's primary
+                    // key implicitly, which SQLite allows and reports as null.
+                    to: {
+                        table: ordered[0].table,
+                        columns: ordered.map((f) => f.to ?? 'rowid'),
+                    },
+                });
+            }
+            const refByColumn = new Map();
+            for (const [, group] of byId) {
+                for (const f of group) {
+                    refByColumn.set(f.from, { table: f.table, column: f.to ?? 'rowid' });
+                }
+            }
+            /* SQLite keeps the `CREATE TABLE` text it was given, checks and all, so
+               the vocabulary is right there in the statement — no second query. */
+            const vocabulary = t.sql
+                ? vocabularyFromDDL(t.sql, cols.map((c) => c.name))
+                : new Map();
+            /* An untyped column of a *table* really does have BLOB affinity —
+               `CREATE TABLE t (a)` is a column SQLite will happily store anything
+               in, and saying BLOB is saying what the database will do with it.
+      
+               A *view* is a different question. `PRAGMA table_info` reports no type
+               for a computed column because there is no declaration to report, not
+               because the values are blobs: `COUNT(*)` came back as BLOB and so did
+               `SUM(total)`, which is a wrong answer to "what does this column hold"
+               rather than an unhelpful one. Left empty instead — `columnKind`
+               already reads that as unknown, exactly as it read BLOB, so nothing
+               renders differently; the tool simply stops claiming a type it was
+               never told. */
+            const untyped = t.type === 'view' ? '' : 'BLOB';
+            const columns = cols.map((c) => ({
+                name: c.name,
+                type: c.type || untyped,
+                nullable: c.notnull === 0,
+                primaryKey: c.pk > 0,
+                references: refByColumn.get(c.name),
+                default: c.dflt_value ?? undefined,
+                allowed: vocabulary.get(c.name),
+            }));
+            tables.push({
+                name: t.name,
+                schema: '',
+                id: t.name,
+                columns,
+                approxRows: approxRowsOf(t.name, t.type),
+                isView: t.type === 'view',
+                indexed: t.type === 'view' ? [] : this.leadingIndexColumns(t.name, columns),
+            });
+        }
+        return {
+            label: this.label,
+            dialect: this.dialect,
+            tables,
+            foreignKeys,
+            readAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * The columns an ORDER BY can lean on.
+     *
+     * `PRAGMA index_list` reports every index including the implicit ones
+     * SQLite creates for UNIQUE and for a non-integer primary key; `index_info`
+     * gives their columns in order and only the first of each is useful for
+     * sorting.
+     *
+     * `INTEGER PRIMARY KEY` is special and has no index at all — it *is* the
+     * rowid, so ordering by it is free — which is exactly the case a naive
+     * index scan would report as unindexed and then refuse to sort by.
+     */
+    leadingIndexColumns(table, columns) {
+        const leading = new Set();
+        const rowidAlias = columns.find((c) => c.primaryKey && /^int(eger)?$/i.test(c.type.trim()));
+        if (rowidAlias && columns.filter((c) => c.primaryKey).length === 1)
+            leading.add(rowidAlias.name);
+        try {
+            const indexes = this.db
+                .prepare(`PRAGMA index_list(${ANSI_STYLE.quote(table)})`)
+                .all();
+            for (const index of indexes) {
+                const info = this.db
+                    .prepare(`PRAGMA index_info(${ANSI_STYLE.quote(index.name)})`)
+                    .all();
+                const first = info.find((c) => c.seqno === 0)?.name;
+                if (first)
+                    leading.add(first);
+            }
+        }
+        catch {
+            /* A virtual table, or one that vanished between listing and reading.
+               Reporting no indexes is the safe answer: it only ever costs a
+               default sort falling back to the key. */
+        }
+        return [...leading];
+    }
+    async query(request) {
+        const table = this.assertTable(request.table);
+        const where = buildWhere(request.filter, ANSI_STYLE);
+        const cols = request.columns?.length
+            ? request.columns.map((c) => ANSI_STYLE.quote(c)).join(', ')
+            : '*';
+        const order = request.orderBy?.length
+            ? ' ORDER BY ' +
+                request.orderBy
+                    .map((o) => `${ANSI_STYLE.quote(o.column)} ${o.direction === 'desc' ? 'DESC' : 'ASC'}`)
+                    .join(', ')
+            : '';
+        /* Every read is bounded. There is no code path that reaches the database
+           without a LIMIT, including one that forgot to ask for one. */
+        const limit = clampLimit(request.limit);
+        const text = `SELECT ${cols} FROM ${ANSI_STYLE.quote(table)}${where.text}${order} LIMIT ? OFFSET ?`;
+        const params = [...where.params, limit, clampOffset(request.offset)];
+        const started = performance.now();
+        const statement = this.db.prepare(text);
+        /* Integers past 2^53 are read as BigInt rather than throwing; valueSafe
+           turns the safe ones back into numbers and keeps the rest as strings. */
+        statement.setReadBigInts(true);
+        const rows = statement.all(...params);
+        const ms = Math.round(performance.now() - started);
+        return {
+            columns: rows.length ? Object.keys(rows[0]) : (request.columns ?? []),
+            rows: rows.map(toJsonSafe),
+            ms,
+            sql: { text, params },
+        };
+    }
+    /**
+     * Run a compiled view.
+     *
+     * Everything hard happened in `compileView`: paths resolved against the
+     * catalog, joins planned with collision-free aliases, values reduced to
+     * bound parameters. What is left here is picking the dialect's style and
+     * handing the statement to the driver — which is the point. An adapter that
+     * built its own joins would be an adapter that could get LEFT wrong on its
+     * own.
+     */
+    async runView(view, offset = 0) {
+        const schema = await this.schema();
+        /* Every read is bounded, views included: `compileView` runs the limit
+           through `clampLimit` and emits LIMIT unconditionally, so there is no
+           shape of ViewDef that reaches the database without one. */
+        const compiled = compileView(schema, view, ANSI_STYLE, offset);
+        const started = performance.now();
+        const viewStmt = this.db.prepare(compiled.text);
+        viewStmt.setReadBigInts(true);
+        const rows = viewStmt.all(...compiled.params);
+        const ms = Math.round(performance.now() - started);
+        return {
+            // From the compiled column list, not the first row: an empty result
+            // still has to render its headers rather than collapsing to nothing.
+            columns: compiled.columns.map((c) => c.name),
+            rows: rows.map(toJsonSafe),
+            ms,
+            sql: { text: compiled.text, params: compiled.params },
+            resolved: compiled.columns,
+            joins: compiled.joins,
+        };
+    }
+    async runBreakdown(breakdown, offset = 0) {
+        const schema = await this.schema();
+        const compiled = compileBreakdown(schema, breakdown, ANSI_STYLE, offset);
+        const started = performance.now();
+        const breakdownStmt = this.db.prepare(compiled.text);
+        breakdownStmt.setReadBigInts(true);
+        const rows = breakdownStmt.all(...compiled.params);
+        return {
+            columns: compiled.columns.map((c) => c.name),
+            rows: rows.map(toJsonSafe),
+            ms: Math.round(performance.now() - started),
+            sql: { text: compiled.text, params: compiled.params },
+            resolved: compiled.columns,
+        };
+    }
+    async countBreakdown(breakdown) {
+        const compiled = compileBreakdownCount(await this.schema(), breakdown, ANSI_STYLE);
+        const row = this.db.prepare(compiled.text).get(...compiled.params);
+        return Number(row?.n ?? 0);
+    }
+    async countView(view) {
+        const compiled = compileViewCount(await this.schema(), view, ANSI_STYLE);
+        const row = this.db.prepare(compiled.text).get(...compiled.params);
+        return Number(row?.n ?? 0);
+    }
+    /**
+     * EXPLAIN QUERY PLAN, indented the way the tree nests.
+     *
+     * Prepared and read, never executed: the rows come from the EXPLAIN
+     * statement itself, so even a write handed here is only ever planned — on
+     * the read-only handle, at that.
+     */
+    async explainSql(request) {
+        const stacked = refuseStacked(request.text);
+        if (stacked)
+            throw new Error(stacked);
+        const started = performance.now();
+        const rows = this.db
+            .prepare(`EXPLAIN QUERY PLAN ${trimStatement(request.text)}`)
+            .all(...(request.params ?? []));
+        /* The driver hands back a flat list with parent pointers; the indentation
+           is the tree, said in text. */
+        const depth = new Map();
+        const plan = rows.map((r) => {
+            const d = (depth.get(r.parent) ?? 0) + 1;
+            depth.set(r.id, d);
+            return `${'  '.repeat(d - 1)}${r.detail}`;
+        });
+        return { plan, ms: Math.round(performance.now() - started) };
+    }
+    /**
+     * SQLite keeps no column statistics worth reading — sqlite_stat1 knows
+     * index selectivity, not null shares — so this looks: one aggregate pass
+     * for counts and edges, then one small GROUP BY per column that provably
+     * repeats. `source` tells the caller what the look cost.
+     *
+     * Above `scanAtMost` rows it stops scanning and samples, because
+     * node:sqlite is synchronous and a full pass over a ten-million-row table
+     * holds the whole process for seconds. Every k-th rowid rather than the
+     * first N: insertion order is not a sample, it is a history, and a min
+     * taken from the first month of data would be presented as the table's.
+     * A view — or a WITHOUT ROWID table, which refuses the arithmetic — falls
+     * back to the first N with the same honest label, because running a view
+     * twice to randomise it would cost what sampling exists to avoid.
+     */
+    async profile(table, limits) {
+        const name = this.assertTable(table);
+        const meta = (await this.schema()).tables.find((t) => t.id === name);
+        if (!meta)
+            throw new Error(`No table or view called "${name}" in this database.`);
+        const q = (c) => ANSI_STYLE.quote(c);
+        const scanAtMost = limits?.scanAtMost ?? 200_000;
+        const sampleSize = limits?.sampleSize ?? 100_000;
+        const started = performance.now();
+        /* COUNT(*) walks an index, not the data pages — cheap enough to decide
+           with, and the number the answer reports either way. */
+        const total = Number(this.db.prepare(`SELECT COUNT(*) AS n FROM ${q(name)}`).get().n ?? 0);
+        let from = q(name);
+        let source = 'scan';
+        if (total > scanAtMost) {
+            source = 'sample';
+            const k = Math.max(2, Math.ceil(total / sampleSize));
+            try {
+                this.db.prepare(`SELECT rowid FROM ${q(name)} LIMIT 1`).get();
+                /* Hashed, not bare `rowid % k`: data is allowed to be periodic —
+                   every tenth row null is a perfectly ordinary import — and a bare
+                   modulo resonates with exactly that, sampling only the pattern.
+                   Knuth's multiplicative constant scatters the rowids first, so the
+                   stride cannot alias with anything the rows themselves repeat. */
+                from = `(SELECT * FROM ${q(name)} WHERE ((rowid * 2654435761) & 0x7fffffff) % ${k} = 0)`;
+            }
+            catch {
+                from = `(SELECT * FROM ${q(name)} LIMIT ${sampleSize})`;
+            }
+        }
+        const aggs = meta.columns.map((c, i) => `COUNT(${q(c.name)}) AS n${i}, COUNT(DISTINCT ${q(c.name)}) AS d${i}, `
+            + `MIN(${q(c.name)}) AS mn${i}, MAX(${q(c.name)}) AS mx${i}`);
+        const profileStmt = this.db
+            .prepare(`SELECT COUNT(*) AS total${aggs.length ? `, ${aggs.join(', ')}` : ''} FROM ${from}`);
+        /* MIN/MAX over a 64-bit id column would throw on read without this;
+           valueSafe normalises what comes back. */
+        profileStmt.setReadBigInts(true);
+        const row = profileStmt.get();
+        /* The denominator the fractions are honest against: the rows actually
+           read, which is the whole table only when nothing was skipped. */
+        const basis = Number(row.total ?? 0);
+        const columns = meta.columns.map((c, i) => {
+            const nonNull = Number(row[`n${i}`] ?? 0);
+            const distinct = Number(row[`d${i}`] ?? 0);
+            const profiled = {
+                column: c.name,
+                type: c.type,
+                nullFrac: basis ? (basis - nonNull) / basis : 0,
+                distinct,
+                min: valueSafe(row[`mn${i}`]) ?? undefined,
+                max: valueSafe(row[`mx${i}`]) ?? undefined,
+            };
+            // Only where a value provably repeats; a unique column's most common
+            // value is noise.
+            if (nonNull > 0 && distinct < nonNull) {
+                const topStmt = this.db.prepare(`SELECT ${q(c.name)} AS v, COUNT(*) AS n FROM ${from} `
+                    + `WHERE ${q(c.name)} IS NOT NULL GROUP BY ${q(c.name)} ORDER BY n DESC, v LIMIT 5`);
+                topStmt.setReadBigInts(true);
+                const top = topStmt.all();
+                profiled.common = top.map((t) => ({ value: valueSafe(t.v), frac: Number(t.n) / basis }));
+            }
+            return profiled;
+        });
+        return {
+            table: name,
+            rows: total,
+            columns,
+            source,
+            ...(source === 'sample' ? { sampled: basis } : {}),
+            ms: Math.round(performance.now() - started),
+        };
+    }
+    /** Introspection is cheap here but not free; the view path re-uses it. */
+    cachedSchema = null;
+    async schema() {
+        if (!this.cachedSchema)
+            this.cachedSchema = await this.introspect();
+        return this.cachedSchema;
+    }
+    async count(table, filter) {
+        const name = this.assertTable(table);
+        const where = buildWhere(filter, ANSI_STYLE);
+        const text = `SELECT COUNT(*) AS n FROM ${ANSI_STYLE.quote(name)}${where.text}`;
+        const row = this.db.prepare(text).get(...where.params);
+        return Number(row?.n ?? 0);
+    }
+    /**
+     * SQLite stores the original statement text, so this is the real thing —
+     * whitespace, comments, check constraints and all — not a reconstruction.
+     * Indexes are appended because they are separate statements in
+     * `sqlite_master` and are usually the first thing you want after the shape.
+     */
+    async ddl(table) {
+        const name = this.assertTable(table);
+        const row = this.db
+            .prepare(`SELECT sql FROM sqlite_master WHERE name = ? AND type IN ('table','view')`)
+            .get(name);
+        if (!row?.sql)
+            return undefined;
+        const indexes = this.db
+            .prepare(`SELECT sql FROM sqlite_master
+          WHERE type = 'index' AND tbl_name = ? AND sql IS NOT NULL
+          ORDER BY name`)
+            .all(name);
+        const parts = [`${row.sql.trim()};`];
+        if (indexes.length)
+            parts.push('', ...indexes.map((i) => `${i.sql.trim()};`));
+        return parts.join('\n');
+    }
+    /**
+     * The write path, on its own handle.
+     *
+     * `this.db` is opened read-only and stays that way for the life of the
+     * process, so browsing can never write no matter what the UI believes. A
+     * second handle is opened the first time an edit is actually applied.
+     */
+    async update(request) {
+        return this.writes.run(() => this.updateNow(request));
+    }
+    async updateNow(request) {
+        const table = this.assertTable(request.table);
+        const meta = this.db.prepare(`PRAGMA table_info(${ANSI_STYLE.quote(table)})`).all();
+        const pk = meta.filter((c) => c.pk > 0).map((c) => c.name);
+        if (!pk.length)
+            throw new Refusal(`${table} has no primary key, so no single row can be identified.`);
+        const keyColumns = Object.keys(request.key);
+        /* The key must be the whole primary key and nothing else. Accepting a
+           partial key would let a two-column key match a whole group of rows,
+           and accepting extra columns would let the caller widen the match. */
+        const same = keyColumns.length === pk.length && pk.every((c) => keyColumns.includes(c));
+        if (!same) {
+            throw new Refusal(`Updating ${table} needs exactly its primary key (${pk.join(', ')}).`);
+        }
+        const entries = Object.entries(request.values ?? {});
+        if (!entries.length)
+            throw new Refusal('Nothing to update.');
+        const applied = {};
+        for (const [column, raw] of entries) {
+            const declared = meta.find((c) => c.name === column);
+            if (!declared)
+                throw new Refusal(`${table} has no column called "${column}".`);
+            if (pk.includes(column)) {
+                // Editing a key in place silently repoints every row that referenced
+                // it, or fails on the constraint. Neither belongs behind an editor.
+                throw new Refusal(`"${column}" is part of the primary key and cannot be edited here.`);
+            }
+            /* Coerced against the declared type, because everything typed into a
+               text box arrives as a string — including "17901" for a REAL column. */
+            applied[column] = coerceForColumn(declared.type || '', raw);
+            if (applied[column] === null && declared.notnull === 1) {
+                throw new Refusal(`"${column}" is NOT NULL and cannot be emptied.`);
+            }
+        }
+        const filter = {
+            groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))],
+        };
+        /* Pre-flight. The count runs on the read-only handle, so the check cannot
+           itself have side effects, and a filter matching anything other than one
+           row stops here rather than at the UPDATE. */
+        const matches = await this.count(table, filter);
+        if (matches !== 1) {
+            throw new Refusal(`Refused: that key matches ${matches} rows, not 1. An update is only allowed when it is certain which row it changes.`);
+        }
+        const where = buildWhere(filter, ANSI_STYLE);
+        const assignments = Object.keys(applied).map((c) => `${ANSI_STYLE.quote(c)} = ?`).join(', ');
+        const text = `UPDATE ${ANSI_STYLE.quote(table)} SET ${assignments}${where.text}`;
+        const params = [...Object.values(applied), ...where.params];
+        const write = this.writeHandle();
+        const result = write.prepare(text).run(...params);
+        return { affected: Number(result.changes), applied, sql: { text, params } };
+    }
+    /**
+     * Add one row.
+     *
+     * The guards are `update`'s where they apply — real columns, coerced
+     * values, a NOT NULL that cannot be handed null — but the key rules
+     * invert: a primary key may be supplied (currency.code is one somebody
+     * types) or left for the database to assign. What is deliberately *not*
+     * pre-checked is completeness: a missing NOT NULL column with no default
+     * is the database's refusal to make, and its message names the column
+     * better than a paraphrase would.
+     *
+     * `RETURNING *` rather than last_insert_rowid plus a re-read: one
+     * statement returns the row as stored — defaults filled, the assigned key
+     * included — with no window for another write to land in between.
+     */
+    async insert(request) {
+        return this.writes.run(() => this.insertNow(request));
+    }
+    async insertNow(request) {
+        const table = this.assertTable(request.table);
+        const meta = this.db.prepare(`PRAGMA table_info(${ANSI_STYLE.quote(table)})`).all();
+        const entries = Object.entries(request.values ?? {});
+        if (!entries.length)
+            throw new Refusal('Nothing to insert. Name at least one column.');
+        const applied = {};
+        for (const [column, raw] of entries) {
+            const declared = meta.find((c) => c.name === column);
+            if (!declared)
+                throw new Refusal(`${table} has no column called "${column}".`);
+            applied[column] = coerceForColumn(declared.type || '', raw);
+            if (applied[column] === null && declared.notnull === 1) {
+                throw new Refusal(`"${column}" is NOT NULL and cannot be null. Leave it out to use its default, if it has one.`);
+            }
+        }
+        const columns = Object.keys(applied);
+        const text = `INSERT INTO ${ANSI_STYLE.quote(table)} (${columns.map((c) => ANSI_STYLE.quote(c)).join(', ')})`
+            + ` VALUES (${columns.map(() => '?').join(', ')}) RETURNING *`;
+        const params = Object.values(applied);
+        const write = this.writeHandle();
+        const inserted = write.prepare(text);
+        /* The RETURNING row can carry a 64-bit id — most often exactly here, on a
+           table whose key is one — so it is read as BigInt rather than throwing,
+           and normalised on the way out like every other read. */
+        inserted.setReadBigInts(true);
+        const row = inserted.get(...params);
+        const safe = toJsonSafe(row);
+        const pk = meta.filter((c) => c.pk > 0).map((c) => c.name);
+        const key = Object.fromEntries(pk.map((c) => [c, safe[c]]));
+        return { key, row: safe, applied, sql: { text, params } };
+    }
+    /**
+     * Run a statement the user wrote.
+     *
+     * The read handle is opened `readOnly: true` at the file level, which SQLite
+     * enforces in the engine — there is no session setting for a statement to
+     * reset, so unlike the other two adapters no transaction wrapper is needed
+     * to make the guarantee real.
+     *
+     * What SQLite does not have is a statement timeout, and `node:sqlite` is
+     * synchronous, so a pathological statement blocks the whole process rather
+     * than one request. The LIMIT wrap covers the ordinary case — a streaming
+     * SELECT stops once it has enough rows — but not an aggregate over a cross
+     * join, which has to finish before it returns anything. That is a real limit
+     * of running SQLite in-process and the interface says so rather than
+     * pretending otherwise.
+     */
+    async runSql(request) {
+        const stacked = refuseStacked(request.text);
+        if (stacked)
+            throw new Error(stacked);
+        const limit = clampLimit(request.limit);
+        const bounded = !request.write && looksWrappable(request.text);
+        const text = bounded ? boundStatement(request.text, limit) : trimStatement(request.text);
+        const db = request.write ? this.writeHandle() : this.db;
+        const started = performance.now();
+        /* The wrap is an optimisation that is allowed to fail. Not every legal
+           statement survives being made a derived table, and rather than enumerate
+           which, a statement that will not compile wrapped is run as written and
+           reported as unbounded. Safe to prepare twice because this handle cannot
+           write. */
+        let wrapped = bounded;
+        let statement;
+        try {
+            statement = db.prepare(text);
+        }
+        catch (err) {
+            if (!bounded)
+                throw err;
+            wrapped = false;
+            statement = db.prepare(trimStatement(request.text));
+        }
+        if (request.write) {
+            const info = statement.run();
+            return {
+                columns: [], rows: [], ms: Math.round(performance.now() - started),
+                truncated: false, bounded: false,
+                affected: Number(info.changes ?? 0),
+                sql: { text, params: [] },
+            };
+        }
+        /* Arrays and a real column list, both from the driver.
+    
+           `columns()` reports every output column including two of the same name,
+           and `setReturnArrays` makes the rows positional so both values survive —
+           an object keyed by name can only hold one of them. Deriving names from
+           the first row's keys, which is what `query()` does, loses the duplicate
+           and returns nothing at all for an empty result. */
+        statement.setReturnArrays(true);
+        /* Same reason as the table reads: a raw `SELECT` can return a 64-bit id,
+           and without this the driver throws on the first one past 2^53. */
+        statement.setReadBigInts(true);
+        const columns = dedupe(statement.columns().map((c) => c.name ?? c.column ?? '?'));
+        const raw = statement.all();
+        /* Capped whether or not the wrap applied. `bounded` says who did the
+           limiting — the database, or us after it had already done the work — and
+           the caller shows that difference. What it never means is that more rows
+           than asked for reach the client. */
+        const truncated = raw.length > limit;
+        const kept = truncated ? raw.slice(0, limit) : raw;
+        return {
+            columns,
+            rows: kept.map((row) => row.map(valueSafe)),
+            ms: Math.round(performance.now() - started),
+            truncated,
+            bounded: wrapped,
+            sql: { text: wrapped ? text : trimStatement(request.text), params: [] },
+        };
+    }
+    /**
+     * Delete one row.
+     *
+     * The guards are `update`'s, for the same reason they are `update`'s: the
+     * danger in an editor is never injection, it is a statement whose WHERE is
+     * broader than the author believed. A delete has the sharper version of that
+     * problem, so nothing here is relaxed.
+     *
+     * Foreign keys are the database's business. `node:sqlite` enables
+     * `foreign_keys` by default — checked, not assumed — so a RESTRICT fires and
+     * a CASCADE cascades exactly as the schema says, and the error the user sees
+     * is SQLite's own.
+     */
+    async remove(request) {
+        return this.writes.run(() => this.removeNow(request));
+    }
+    async removeNow(request) {
+        const table = this.assertTable(request.table);
+        const meta = this.db.prepare(`PRAGMA table_info(${ANSI_STYLE.quote(table)})`).all();
+        const pk = meta.filter((c) => c.pk > 0).map((c) => c.name);
+        if (!pk.length)
+            throw new Refusal(`${table} has no primary key, so no single row can be identified.`);
+        const keyColumns = Object.keys(request.key);
+        const same = keyColumns.length === pk.length && pk.every((c) => keyColumns.includes(c));
+        if (!same) {
+            throw new Refusal(`Deleting from ${table} needs exactly its primary key (${pk.join(', ')}).`);
+        }
+        const filter = {
+            groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))],
+        };
+        /* Pre-flight on the read-only handle, so the check cannot itself have side
+           effects, and a filter matching anything other than one row stops here
+           rather than at the DELETE. */
+        const matches = await this.count(table, filter);
+        if (matches !== 1) {
+            throw new Refusal(`Refused: that key matches ${matches} rows, not 1. A delete is only allowed when it is certain which row it removes.`);
+        }
+        const where = buildWhere(filter, ANSI_STYLE);
+        const text = `DELETE FROM ${ANSI_STYLE.quote(table)}${where.text}`;
+        const write = this.writeHandle();
+        const result = write.prepare(text).run(...where.params);
+        return { affected: Number(result.changes), sql: { text, params: where.params } };
+    }
+    writeHandle() {
+        if (!this.writeDb) {
+            this.writeDb = new DatabaseSync(this.file);
+            waitForLocks(this.writeDb);
+        }
+        return this.writeDb;
+    }
+    /**
+     * Several writes as one, or none of them.
+     *
+     * `BEGIN` / `COMMIT` on the write handle, which is a second connection to
+     * the same file. The read handle is a third, opened read-only — so the
+     * pre-flight counts inside the callback see the file as it was before this
+     * transaction started, which is what a teardown wants and what an insert
+     * does not care about.
+     *
+     * `node:sqlite` is synchronous, so nothing can interleave *within* one
+     * statement; the queue is what stops another request's write interleaving
+     * *between* two of these.
+     */
+    async transaction(run) {
+        return this.writes.run(async () => {
+            const write = this.writeHandle();
+            write.exec('BEGIN');
+            try {
+                const out = await run({
+                    insert: (r) => this.insertNow(r),
+                    remove: (r) => this.removeNow(r),
+                    update: (r) => this.updateNow(r),
+                });
+                write.exec('COMMIT');
+                return out;
+            }
+            catch (err) {
+                try {
+                    write.exec('ROLLBACK');
+                }
+                catch {
+                    /* Already rolled back, or never begun. The original error is the
+                       one worth reporting either way. */
+                }
+                throw err;
+            }
+        });
+    }
+    async close() {
+        this.db.close();
+        this.writeDb?.close();
+        this.writeDb = null;
+    }
+    /**
+     * Table names are the one identifier that cannot be a bound parameter, so
+     * they are checked against the catalog rather than escaped and hoped for.
+     * An unknown name is rejected before it reaches a statement.
+     */
+    assertTable(name) {
+        const exists = this.db
+            .prepare(`SELECT 1 FROM sqlite_master WHERE type IN ('table','view') AND name = ?`)
+            .get(name);
+        if (!exists)
+            throw new Error(`No table or view called "${name}" in this database.`);
+        return name;
+    }
+}
+/**
+ * One value from the database, made safe to send as JSON.
+ *
+ * Two things do not survive `JSON.stringify`, and one of them does not survive
+ * being *read* by default. `node:sqlite` throws on any integer past 2^53
+ * unless the statement is told to read big integers — so the data statements
+ * ask for that (`setReadBigInts`), and everything comes back as `bigint`.
+ *
+ * A bigint inside the safe range is turned back into a plain number, because
+ * the client formats numbers — thousands separators, right alignment — and a
+ * string would lose all of that on the id column of every ordinary table. One
+ * *past* the safe range is kept as a string, because that is the whole point:
+ * a Postgres/Snowflake-style 64-bit id shown as `9007199254740992` when it is
+ * really `...993` looks right and matches nothing when clicked. Passing it
+ * through as a number would be the silent corruption this exists to prevent.
+ *
+ * Blobs become `<n bytes>`: the grid has no use for the bytes and every use
+ * for the size.
+ */
+function valueSafe(v) {
+    if (typeof v === 'bigint') {
+        return v >= -9007199254740991n && v <= 9007199254740991n ? Number(v) : v.toString();
+    }
+    if (v instanceof Uint8Array)
+        return `<${v.byteLength} bytes>`;
+    return v;
+}
+function toJsonSafe(row) {
+    const out = {};
+    for (const [k, v] of Object.entries(row))
+        out[k] = valueSafe(v);
+    return out;
+}