@bakery-framework/plugin-db-explorer 2.0.0-alpha.12 → 2.0.0-alpha.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/plugin-db-explorer",
-  "version": "2.0.0-alpha.12",
+  "version": "2.0.0-alpha.13",
   "description": "Bakery database explorer plugin — browse and edit rows — no raw SQL, no DDL.",
   "keywords": [
     "bakery",
@@ -33,8 +33,8 @@
     "!src/tests"
   ],
   "dependencies": {
-    "@bakery-framework/core": "^2.0.0-alpha.12",
-    "@bakery-framework/orm": "^2.0.0-alpha.12"
+    "@bakery-framework/core": "^2.0.0-alpha.13",
+    "@bakery-framework/orm": "^2.0.0-alpha.13"
   },
   "engines": {
     "bun": ">=1.4.0"

package/src/access.ts

@@ -88,9 +88,16 @@ function presentedKey(req: Request): string | null {
   if (SAFE_METHODS.has(req.method)) return presented
 
   // `readCredential` prefers header, then Bearer, then the query — so if
-  // neither header is present, the value it returned came from the URL.
-  const fromHeader =
-    req.headers.has(`x-${DB_KEY}`) || req.headers.has('authorization')
+  // neither header carried a value, what it returned came from the URL.
+  //
+  // **The value, not `has()`.** An empty header is *present*, so
+  // `x-db-key: ''` alongside `?db-key=SECRET` read as "a header was used" and
+  // let a URL credential through on a write — the one case this function
+  // exists to refuse. `readCredential` skips a falsy header and falls to the
+  // query, so the two checks disagreed about which form had been presented.
+  const fromHeader = Boolean(
+    req.headers.get(`x-${DB_KEY}`) || req.headers.get('authorization'),
+  )
   return fromHeader ? presented : null
 }
 
@@ -186,3 +193,32 @@ export function currentAccess(): Access | false {
 export function currentCanWrite(): boolean {
   return canWrite(currentAccess())
 }
+
+/**
+ * Refuse a `users` map that names a level the explorer does not have.
+ *
+ * `access` is typed `Access`, and a JavaScript caller or a value read from the
+ * environment is not bound by that. An unknown level — `'admin'` is the one
+ * that gets written — passed straight through `higher`, reached the client as
+ * the caller's own level in `/api/_db/schema`, and then failed `canWrite`,
+ * which compares against `'write'` exactly. So it failed *closed*, which is
+ * the right direction and an unhelpful way to say "your configuration has a
+ * typo": the operator sees "no access" on a map they believe grants write.
+ *
+ * Thrown at registration rather than logged, because this is a configuration
+ * error in code the application controls, it cannot become correct later, and
+ * the alternative is a server that runs while quietly refusing the people it
+ * was set up to admit.
+ */
+export function assertValidUsers(users: ExplorerUsers | undefined): void {
+  if (!users) return
+  for (const [name, user] of Object.entries(users)) {
+    if (user.access !== 'read' && user.access !== 'write') {
+      throw new Error(
+        `dbExplorerPlugin: users.${name}.access is ${JSON.stringify(
+          user.access,
+        )}; it must be 'read' or 'write'`,
+      )
+    }
+  }
+}

package/src/client/api.ts

@@ -167,6 +167,28 @@ export async function fetchGraph(): Promise<SchemaGraph> {
  * The scalar form is still what the endpoint accepts from anyone else; `toWire`
  * always sends the object form from here.
  */
+/**
+ * What the last counted listing was, and what it counted.
+ *
+ * One slot, so it is bounded by construction (convention 6). The key is
+ * everything that changes which rows a listing covers - table, sort and
+ * filters - and *not* the page number, because paging through one listing is
+ * precisely the case where the total does not change.
+ */
+let lastCounted: { signature: string; total: number } | null = null
+
+function listingSignature(
+  view: ViewState,
+  wire: Record<string, unknown>,
+): string {
+  return JSON.stringify([view.table, view.sortBy ?? '', view.sortOrder, wire])
+}
+
+/** Test seam (convention 9): page 2 of one test must not see page 1 of another. */
+export function __resetPageCount(): void {
+  lastCounted = null
+}
+
 export async function fetchPage(view: ViewState): Promise<Timed<TablePage>> {
   const params: Record<string, string> = {
     tableName: view.table,
@@ -178,11 +200,31 @@ export async function fetchPage(view: ViewState): Promise<Timed<TablePage>> {
   const wire = toWire(view.filters)
   if (Object.keys(wire).length) params.filters = JSON.stringify(wire)
 
+  // The `COUNT(*)` is 97% of what a page costs - 51.3 ms against 1.6 ms for
+  // the rows on a filtered page of a 200,000-row table - and page 2 of a
+  // listing asks exactly what page 1 already answered.
+  //
+  // Sent only when the listing is the same one and this is not its first
+  // page. The server enforces the second condition too, so a total that has
+  // drifted is corrected as soon as the view returns to the start; changing a
+  // filter or a sort changes the signature, which is the other way back.
+  const signature = listingSignature(view, wire)
+  if (view.page > 1 && lastCounted?.signature === signature) {
+    params.knownTotal = String(lastCounted.total)
+  }
+
   const query = `?${new URLSearchParams(params)}`
   const res = await fetch(`/api/_db/table-data${query}`, {
     headers: keyHeaders(),
   })
-  return await unwrapEnvelope<TablePage>(res)
+  const answer = await unwrapEnvelope<TablePage>(res)
+
+  // Remember what came back, whether it was counted or echoed: echoing keeps
+  // the slot on the same listing, and a real count refreshes it.
+  if (typeof answer.data?.totalRows === 'number') {
+    lastCounted = { signature, total: answer.data.totalRows }
+  }
+  return answer
 }
 
 export interface LookupRef {

package/src/client/bulk.ts

@@ -213,7 +213,7 @@ function offerDeleteUndo(
     notify(`${deleted} rows deleted`)
     return
   }
-  const row = rows[0]!
+  const row = restorableRow(rows[0]!, ctx.columns)
   const restore = async () => {
     await run(async () => {
       await insertRows({ table: ctx.table.name, rows: [row] })
@@ -355,3 +355,27 @@ async function run<T>(call: () => Promise<T>): Promise<T | null> {
     return null
   }
 }
+
+/**
+ * A deleted row, reduced to the columns the table actually has.
+ *
+ * `selectedRows()` hands over the row as `getData` returned it, and two of the
+ * three dialects add a key that is not a column: SQLite selects `rowid` and
+ * Postgres `ctid::text AS rowid`, while MySQL selects `*` and so never showed
+ * this. `validateInsertRow` refuses unknown columns by design, so restoring
+ * the row verbatim came back `400 rowid: unknown_column` — the undo offered
+ * after a delete silently did not undo, on two dialects out of three.
+ *
+ * Exported for the test. There is no DOM here and the bug lived in a callback
+ * a click builds, so the only way to pin it is to name the transformation.
+ */
+export function restorableRow(
+  source: Record<string, unknown>,
+  columns: { name: string }[],
+): Record<string, unknown> {
+  const row: Record<string, unknown> = {}
+  for (const column of columns) {
+    if (column.name in source) row[column.name] = source[column.name]
+  }
+  return row
+}

package/src/client/csv-commit.ts

@@ -22,8 +22,28 @@ import {
 import { append, box, button, downloadText, el } from './dom'
 import type { SchemaColumn, SchemaTable } from './meta'
 
-/** One request per chunk. Well under `policy.ts`'s 50,000 row ceiling. */
-const CHUNK = 500
+/**
+ * One request per chunk. Well under `policy.ts`'s 50,000 row ceiling.
+ *
+ * Raised from 500, which made a full-size file 100 requests. Measured end to
+ * end on 20,000 rows through the real endpoint, three rounds against a
+ * CPU-bound control flat at 26-29 ms: **108 ms at 500 against 89 ms at 5,000**,
+ * an 18% saving and 0.53 ms of fixed per-request cost removed 36 times over.
+ *
+ * The reason on record for raising it was that each request re-introspected
+ * the schema, and that is no longer true - `introspect()` is cached against
+ * `schemaFingerprint()` now, so the second request onwards pays 10 us rather
+ * than 8.28 ms. What is left is HTTP, authorisation and a transaction per
+ * request, which is what the 18% is.
+ *
+ * **The cost is cancel granularity**, and it is worth stating plainly.
+ * `cancelled` is checked between chunks, so a chunk in flight always
+ * completes: cancelling used to leave at most 500 further rows inserted and
+ * now leaves at most 5,000. Progress also advances ten times less often. Both
+ * follow from the chunk size rather than from anything that could be tuned
+ * separately, since a chunk is one request and one transaction.
+ */
+const CHUNK = 5000
 
 export interface CommitContext {
   table: SchemaTable

package/src/client/csv-model.ts

@@ -345,10 +345,54 @@ export interface BuildResult {
  * walks over fifty thousand rows is the difference between a responsive dialog
  * and a frozen tab.
  */
+/**
+ * The last build, so a change that cannot alter it does not redo it.
+ *
+ * One slot, so it is bounded by construction (convention 6). Compared by
+ * **reference**, not by value: every update goes through a spread
+ * (`{ ...model, onBadRow }`), so an untouched field keeps its identity and a
+ * touched one does not. Comparing by value would mean walking the whole file
+ * to decide whether to walk the whole file.
+ *
+ * The key is exactly what this function reads - `headers`, `rows`, `assign`,
+ * `emptyToNull` and the columns - and deliberately not `onBadRow`, `ragged`,
+ * `delimiter` or `hasHeader`. Those change what the *import* does, never what
+ * the records are, and the bad-row policy is a dropdown in the same footer
+ * that displays this result. Picking one made the footer coerce every row of
+ * the file to arrive at the count it already had on screen.
+ *
+ * Measured on 50,000 rows of four columns: 153-250 ms per change, on the main
+ * thread, for a number that did not move.
+ */
+let lastBuild: {
+  headers: unknown
+  rows: unknown
+  assign: unknown
+  emptyToNull: unknown
+  columns: unknown
+  result: BuildResult
+} | null = null
+
+/** Test seam (convention 9): one test's file must not answer for another's. */
+export function __resetBuildRecords(): void {
+  lastBuild = null
+}
+
 export function buildRecords(
   model: ImportModel,
   columns: readonly SchemaColumn[],
 ): BuildResult {
+  if (
+    lastBuild !== null &&
+    lastBuild.headers === model.headers &&
+    lastBuild.rows === model.rows &&
+    lastBuild.assign === model.assign &&
+    lastBuild.emptyToNull === model.emptyToNull &&
+    lastBuild.columns === columns
+  ) {
+    return lastBuild.result
+  }
+
   const feeds = feedsOf(model, columns)
   const records: Record<string, unknown>[] = []
   const failures: RowFailure[] = []
@@ -369,7 +413,16 @@ export function buildRecords(
     records.push(record)
   })
 
-  return { records, failures }
+  const result = { records, failures }
+  lastBuild = {
+    headers: model.headers,
+    rows: model.rows,
+    assign: model.assign,
+    emptyToNull: model.emptyToNull,
+    columns,
+    result,
+  }
+  return result
 }
 
 /** RFC 4180 quoting: only when the field needs it, and `"` doubles. */

package/src/endpoints/common.ts

@@ -15,6 +15,7 @@
  * are about the request's own shape rather than about who is asking.
  */
 
+import { errorMsg, pluginLog } from '@bakery-framework/core/logger'
 import { Case, Try } from '@bakery-framework/core/utils'
 import type { JsonResponseData } from '@bakery-framework/core/utils/common'
 import { response } from '@bakery-framework/core/utils/http'
@@ -120,3 +121,21 @@ export async function beginWrite(req: Request): Promise<WriteStart> {
 
   return { ok: true, table, body }
 }
+
+/**
+ * Refuse a request without telling the caller what the database said.
+ *
+ * Every read endpoint used to answer `400` with `error.message` verbatim, so a
+ * malformed `page` came back as SQLite's "datatype mismatch" and a bad lookup
+ * key as a JavaScript `TypeError` naming an internal expression. Postgres is
+ * worse: its parse errors quote the statement. A caller holding only `read`
+ * cannot be handed the query text, and none of it helps a client that has
+ * already been told its request was invalid.
+ *
+ * The message still exists — it goes to the server log with the operation that
+ * produced it, which is where an operator can act on it.
+ */
+export function refuse(op: string, error: unknown, status = 400): Envelope {
+  pluginLog.EXPLORER_QUERY_ERR({ op, error: errorMsg(error) })
+  return response.json.error(status, `${op} failed`)
+}

package/src/endpoints/graph.ts

@@ -15,7 +15,7 @@ import { connection } from '@bakery-framework/orm/connection'
 import { qId } from '@bakery-framework/orm/schema-util'
 import { type Identity, introspect, type TableFacts } from '../identity'
 import { overLimit } from '../policy'
-import { findTable, readBody } from './common'
+import { findTable, readBody, refuse } from './common'
 
 export async function handleGraph(): Promise<JsonResponseData<unknown>> {
   return await Try.return(
@@ -143,6 +143,6 @@ export async function handleLookup(
 
       return response.json.success('success', { rows: results })
     },
-    (error: any) => response.json.error(400, error?.message ?? 'Lookup failed'),
+    error => refuse('lookup', error),
   )
 }

package/src/endpoints/import.ts

@@ -19,7 +19,7 @@ import { DB } from '@bakery-framework/orm/orm'
 import { overLimit } from '../policy'
 import { isRollbackSignal, previewRollback } from '../preview'
 import { type FieldError, validateInsertRow } from '../validate'
-import { beginWrite, invalid } from './common'
+import { beginWrite, invalid, refuse } from './common'
 
 export type OnBadRow = 'stop' | 'skip'
 
@@ -83,7 +83,7 @@ export async function handleImport(
       if (isRollbackSignal(error)) {
         return response.json.success(error.message, error.report, error.status)
       }
-      return response.json.error(400, error?.message ?? 'Import failed')
+      return refuse('import', error)
     },
   )
 }

package/src/endpoints/read.ts

@@ -15,6 +15,7 @@ import { connection } from '@bakery-framework/orm/connection'
 import { currentAccess, currentCanWrite } from '../access'
 import { type Identity, introspect } from '../identity'
 import { parseFilters } from '../shared/filters'
+import { refuse } from './common'
 
 export interface SchemaColumn {
   name: string
@@ -112,6 +113,32 @@ export async function handleSchema(): Promise<JsonResponseData<unknown>> {
   )
 }
 
+/**
+ * A total the client counted on an earlier page, or `undefined`.
+ *
+ * The `COUNT(*)` is 97% of what a page costs - 51.3 ms against 1.6 ms for the
+ * rows on a filtered page of a 200,000-row table - and page 2 of a listing is
+ * asking the same question page 1 already answered.
+ *
+ * **Only from page 2 onwards.** The first page of any listing, and any request
+ * that arrives without a page, counts for real. That is what makes the value
+ * self-correcting: a client whose total has gone stale sees it fixed as soon
+ * as it returns to the first page or changes its filters, because changing
+ * filters restarts at page 1.
+ *
+ * The client asserts it counted with *these* filters; nothing here can check
+ * that, and nothing needs to. The total decides the row readout and the page
+ * count, never which rows are returned, so a wrong one is a stale number on
+ * screen rather than wrong data.
+ */
+function readKnownTotal(url: URL, page: number): number | undefined {
+  if (page <= 1) return undefined
+  const raw = url.searchParams.get('knownTotal')
+  if (raw === null) return undefined
+  const parsed = Number(raw)
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined
+}
+
 /** Table names the way the ORM writes them: identifier characters only. */
 const RX_TABLE_NAME = /^[a-zA-Z0-9_]+$/
 
@@ -161,15 +188,46 @@ export async function handleTableData(
 
   return await Try.return(
     async () => {
+      const page = readBounded(url, 'page', 1, 1, Number.MAX_SAFE_INTEGER)
       const data = await connection.getData(tableName, {
-        page: Number.parseInt(url.searchParams.get('page') || '1', 10),
-        pageSize: Number.parseInt(url.searchParams.get('pageSize') || '50', 10),
+        page,
+        pageSize: readBounded(url, 'pageSize', 50, 1, MAX_PAGE_SIZE),
         sortBy: url.searchParams.get('sortBy'),
         sortOrder: url.searchParams.get('sortOrder') || 'ASC',
         filters: filters.filters,
+        knownTotal: readKnownTotal(url, page),
       })
       return response.json.success('success', data)
     },
-    (error: any) => response.json.error(400, error.message),
+    error => refuse('table-data', error),
   )
 }
+
+/** The largest page the read endpoint will assemble. */
+const MAX_PAGE_SIZE = 500
+
+/**
+ * A positive integer from the query string, clamped.
+ *
+ * The read side was the only unbounded surface left: every write goes through
+ * `policy.ts`, and this took `page` and `pageSize` as whatever
+ * `Number.parseInt` returned. `pageSize=1000000` assembled 50,000 rows and
+ * 5.25 MB in one response, `pageSize=-1` returned the whole table with a
+ * negative `totalPages`, and `page=0` silently served page 1. None needs a
+ * credential beyond `read`.
+ *
+ * `NaN` falls back rather than clamping: `page=abc` is a malformed request,
+ * and answering it with page 1 is friendlier than a 400 for a value that
+ * changes nothing about what the caller may see.
+ */
+function readBounded(
+  url: URL,
+  name: string,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const raw = Number.parseInt(url.searchParams.get(name) || '', 10)
+  if (!Number.isFinite(raw)) return fallback
+  return Math.min(max, Math.max(min, raw))
+}

package/src/endpoints/rows.ts

@@ -32,7 +32,7 @@ import {
   validateKey,
   validatePartial,
 } from '../validate'
-import { beginWrite, type Envelope, invalid } from './common'
+import { beginWrite, type Envelope, invalid, refuse } from './common'
 
 /**
  * A conflict, as the caller sees it: which edit, which row, and what the row
@@ -107,7 +107,10 @@ function fromRollback(error: any): Envelope {
       ? response.json.error(error.status, error.message, error.report)
       : response.json.success(error.message, error.report, error.status)
   }
-  return response.json.error(400, error?.message ?? 'The write failed')
+  // A rollback signal carries a message this plugin wrote, so it is safe to
+  // pass on. Anything else reaching here is the driver's, and the driver's
+  // text is not the caller's business — see `refuse`.
+  return refuse('write', error)
 }
 
 // ---------------------------------------------------------------- POST /rows
@@ -167,7 +170,7 @@ export async function handleInsertRows(
         rows: written,
       })
     },
-    (error: any) => response.json.error(400, error?.message ?? 'Insert failed'),
+    error => refuse('insert', error),
   )
 }
 
@@ -256,6 +259,202 @@ export async function handleUpdateRow(
   )
 }
 
+type PreparedEdit = {
+  key: Record<string, unknown>
+  set: Record<string, unknown>
+  expect: Record<string, unknown>
+}
+
+type CollapsedGroup = {
+  /** The one identity column every member addresses. */
+  column: string
+  set: Record<string, unknown>
+  expect: Record<string, unknown>
+  /**
+   * The original edit index alongside its key value, so a conflict still names
+   * the edit the caller sent rather than a position in a regrouped list.
+   */
+  members: { index: number; value: unknown }[]
+}
+
+/**
+ * Split a bulk edit into runs that can share one statement and those that
+ * cannot.
+ *
+ * A bulk edit issued one `UPDATE` per row, so 1,000 edits were 1,000
+ * statements plus the transaction and the conflict probes on top. The rows
+ * almost always share their `set` and their `expect` - that is what makes it a
+ * *bulk* edit, one action applied to a selection - so grouping on those two
+ * plus the identity column collapses the common case to one statement per
+ * group.
+ *
+ * Three things disqualify a member, and each falls back rather than failing:
+ *
+ *   - a composite identity, because `IN` addresses one column;
+ *   - a `null` key value, because `IN` never matches NULL and `IS NULL` is a
+ *     different clause. The single-row `where` already handles it correctly,
+ *     so falling back is not a compromise;
+ *   - being alone in its group, where one statement is one statement either
+ *     way and the collapsed path would only add a probe.
+ *
+ * Exported as a test seam (convention 9). Two of the three disqualifications -
+ * a composite identity and a `null` key value - are hard to reach through the
+ * endpoint, because a NOT NULL primary key cannot carry a null and validation
+ * refuses it before this runs. The guard still earns its place: identity can
+ * be a unique index over a nullable column, and `IN` would silently match
+ * nothing there. Asserting it directly is the only honest way to pin it.
+ */
+export function groupBulkEdits(prepared: (PreparedEdit | null)[]): {
+  collapsible: CollapsedGroup[]
+  single: number[]
+} {
+  const groups = new Map<string, CollapsedGroup>()
+  const single: number[] = []
+
+  for (let index = 0; index < prepared.length; index++) {
+    const edit = prepared[index]!
+    const columns = Object.keys(edit.key)
+    const column = columns[0]
+    const value = column === undefined ? undefined : edit.key[column]
+
+    if (columns.length !== 1 || column === undefined || value === null) {
+      single.push(index)
+      continue
+    }
+
+    const signature = JSON.stringify([column, edit.set, edit.expect])
+    const group = groups.get(signature)
+    if (group) {
+      group.members.push({ index, value })
+    } else {
+      groups.set(signature, {
+        column,
+        set: edit.set,
+        expect: edit.expect,
+        members: [{ index, value }],
+      })
+    }
+  }
+
+  const collapsible: CollapsedGroup[] = []
+  for (const group of groups.values()) {
+    if (group.members.length > 1) collapsible.push(group)
+    else single.push(group.members[0]!.index)
+  }
+  // The leftovers came out of a Map and have lost their order; they are
+  // applied in sequence below, so put them back in the order they were sent.
+  single.sort((a, b) => a - b)
+
+  return { collapsible, single }
+}
+
+/**
+ * Apply one collapsed group, and report any member that cannot be applied.
+ *
+ * **The probe runs before the write, not after it**, and that ordering is the
+ * whole design. A collapsed `UPDATE` reports a row count, not identities, so a
+ * short count says *some* member did not match without saying which. Finding
+ * out afterwards is not possible: the update has already changed the columns
+ * `expect` refers to, and re-running the members one at a time inside the same
+ * transaction would apply them twice.
+ *
+ * So: ask which keys satisfy identity AND expect, treat the rest as conflicts,
+ * and update only when there are none. That answers the MySQL no-op case for
+ * free - a row that matches the probe but reports zero changed rows is a
+ * no-op, decided exactly as the single-row path decides it, and the probe has
+ * already established the row is there.
+ *
+ * Any conflict rolls the entire bulk edit back, so a group that has one skips
+ * its update rather than writing something about to be discarded.
+ */
+async function applyCollapsedGroup(
+  table: TableFacts,
+  group: CollapsedGroup,
+  conflicts: Conflict[],
+): Promise<number> {
+  let changed = 0
+
+  // One bound parameter per key, plus the `set` and `expect` values, has to
+  // fit inside the dialect's statement limit. `maxQueryParams` is the
+  // adapter's own number; SQLite's 32,766 is the smallest of the three.
+  const fixed = Object.keys(group.set).length + Object.keys(group.expect).length
+  const limit = Math.max(1, getActiveDb().maxQueryParams - fixed - 1)
+
+  for (let start = 0; start < group.members.length; start += limit) {
+    const chunk = group.members.slice(start, start + limit)
+
+    const matched = await selectKeyValues(
+      table,
+      group.column,
+      chunk.map(m => m.value),
+      group.expect,
+    )
+
+    const missing = chunk.filter(m => !matched.has(m.value))
+    if (missing.length) {
+      for (const member of missing) {
+        const key = { [group.column]: member.value }
+        conflicts.push({
+          index: member.index,
+          key,
+          reason: 'the row changed since it was read',
+          row: await selectRow(table, key),
+        })
+      }
+      continue
+    }
+
+    let statement = DB.Update.table(table.name)
+      .set(group.set)
+      .where(group.column, DB.inList(chunk.map(m => m.value)))
+    for (const [column, value] of Object.entries(group.expect)) {
+      // `expect` has already been through `validatePartial`, which is what
+      // decides a value is comparable at all; the builder's parameter type is
+      // narrower than "whatever survived that" and the cast says so once here
+      // rather than loosening the validator.
+      statement = statement.and(column, value as never)
+    }
+
+    const result = await statement.run()
+    changed += Number(result.changes ?? 0)
+  }
+
+  return changed
+}
+
+/**
+ * Which of `values` name a row that also satisfies `expect`.
+ *
+ * A Set of the key values seen, so a key matching more than one row counts
+ * once: the question is whether the edit addresses anything, not how much.
+ */
+async function selectKeyValues(
+  table: TableFacts,
+  column: string,
+  values: unknown[],
+  expect: Record<string, unknown>,
+): Promise<Set<unknown>> {
+  const params: unknown[] = [...values]
+  const clauses = [`${qId(column)} IN (${values.map(() => '?').join(', ')})`]
+
+  for (const [name, value] of Object.entries(expect)) {
+    if (value === null) {
+      clauses.push(`${qId(name)} IS NULL`)
+    } else {
+      params.push(value)
+      clauses.push(`${qId(name)} = ?`)
+    }
+  }
+
+  const rows = (await getActiveDb()
+    .query(
+      `SELECT ${qId(column)} FROM ${qId(table.name)} WHERE ${clauses.join(' AND ')}`,
+    )
+    .all(...params)) as Record<string, unknown>[]
+
+  return new Set(rows.map(row => row[column]))
+}
+
 // ---------------------------------------------------------- POST /rows/bulk
 
 export async function handleBulkEdit(
@@ -313,7 +512,13 @@ export async function handleBulkEdit(
         const conflicts: Conflict[] = []
         let changed = 0
 
-        for (let index = 0; index < prepared.length; index++) {
+        const { collapsible, single } = groupBulkEdits(prepared)
+
+        for (const group of collapsible) {
+          changed += await applyCollapsedGroup(table, group, conflicts)
+        }
+
+        for (const index of single) {
           const edit = prepared[index]!
           const predicate = { ...edit.key, ...edit.expect }
           const result = await chain(

package/src/identity.ts

@@ -311,15 +311,54 @@ export function metaOf(
   }
 }
 
+/**
+ * One entry, held only while the schema it describes is still the live one.
+ *
+ * Convention 6 forbids an unbounded module cache; this is a single slot, so it
+ * is bounded by construction. What made a cache unsafe here was never its size
+ * - the note this replaces said so, and it was right at the time: "the wrong
+ * entry is not a slow response, it is a write addressed by a key the table no
+ * longer has." Staleness, not memory.
+ *
+ * `schemaFingerprint()` closes exactly that. The entry is used only when the
+ * adapter reports the same schema version it was built under, so an entry
+ * describing a dropped column cannot be handed to a write - the version moved
+ * when the column was dropped.
+ *
+ * Keyed on the whole fingerprint string rather than a bare counter, because
+ * the adapter prefixes it with the driver and the file: two SQLite databases
+ * both at version 3 must not share an entry.
+ */
+let cached: {
+  fingerprint: string
+  facts: Map<string, TableFacts>
+} | null = null
+
+/**
+ * Test seam (convention 9). A cache with no way to clear it makes every test
+ * after the first one depend on what the first one did.
+ */
+export function __resetIntrospectCache() {
+  cached = null
+}
+
 /**
  * Every table the connection has, with its identity resolved.
  *
- * Three round trips, taken per request rather than cached. Convention 6 forbids
- * an unbounded module cache, and a bounded one would be worse than none here:
- * the wrong entry is not a slow response, it is a write addressed by a key the
- * table no longer has. Schema introspection is also exactly what the explorer's
- * own `/api/_db/schema` call already costs, so a write pays what a page load
- * pays.
+ * Three round trips, and for a 50-table SQLite database that is **250
+ * statements and 8.28 ms** - paid by every write, every foreign-key hover and
+ * the graph endpoint. On a network dialect the same shape is roughly 52
+ * sequential round trips per write.
+ *
+ * Asking whether it is still valid is 10.4 us, so the cache pays for itself
+ * 795 times over on a hit and costs one extra statement on a miss.
+ *
+ * **Row counts are never cached**, and that is the load-bearing exception.
+ * `schema_version` does not move for an `INSERT` - which is exactly what makes
+ * it a good key for schema, and exactly what makes it a wrong key for a
+ * `COUNT(*)`. A cached count would be silently wrong for as long as nobody
+ * changed the schema. Asking for counts skips the cache in both directions:
+ * it neither reads an entry nor writes one.
  */
 export async function introspect(options?: {
   /**
@@ -329,8 +368,25 @@ export async function introspect(options?: {
    */
   rowCounts?: boolean
 }): Promise<Map<string, TableFacts>> {
+  const wantsCounts = options?.rowCounts === true
+
+  // `null` from an adapter that cannot answer cheaply - Postgres and MySQL
+  // today - and the behaviour is then exactly what it was before this cache
+  // existed. Correctness does not depend on the capability being present.
+  //
+  // Probed rather than called, because this plugin is published against a
+  // *range* of `@bakery-framework/orm` versions and an adapter can come from a
+  // third-party package that predates the method. A `TypeError` here would
+  // turn a missing optimisation into a failed request; the tests' own stub
+  // adapters are the same shape and proved the point immediately.
+  const fingerprint =
+    wantsCounts || typeof connection.schemaFingerprint !== 'function'
+      ? null
+      : await connection.schemaFingerprint()
+  if (fingerprint && cached?.fingerprint === fingerprint) return cached.facts
+
   const [schema, constraints, indexes] = await Promise.all([
-    connection.getSchema({ rowCounts: options?.rowCounts === true }),
+    connection.getSchema({ rowCounts: wantsCounts }),
     connection.getConstraints(),
     connection.getIndexes(),
   ])
@@ -397,5 +453,9 @@ export async function introspect(options?: {
     })
   }
 
+  // Stored after the walk rather than before it, so a walk that throws leaves
+  // no entry claiming to describe a schema nobody successfully read.
+  if (fingerprint) cached = { fingerprint, facts: byTable }
+
   return byTable
 }

package/src/setup.ts

@@ -6,7 +6,7 @@ import type { PluginRouteTable } from '@bakery-framework/core/plugins'
 import { routeTable } from '@bakery-framework/core/plugins'
 import { fs } from '@bakery-framework/core/utils'
 import { response } from '@bakery-framework/core/utils/http'
-import { type AccessConfig, accessStore, resolveAccess } from './access'
+import { accessStore, assertValidUsers, resolveAccess, type AccessConfig } from './access'
 import { handleGraph, handleLookup } from './endpoints/graph'
 import { handleImport } from './endpoints/import'
 import { handleSchema, handleTableData } from './endpoints/read'
@@ -139,6 +139,10 @@ export class DbExplorerHandler extends Handler {
 }
 
 export function setupExplorer(options: AccessConfig = {}) {
+  // Before anything is registered: a bad level cannot become good later, and a
+  // server that boots while refusing the users it was configured with is worse
+  // than one that refuses to boot.
+  assertValidUsers(options.users)
   config = options
   // Above the content handlers, below nothing that matters: the /_db and
   // /api/_db namespaces are reserved for framework routes (convention 10),