@bakery-framework/plugin-db-explorer 2.0.0-alpha.9 → 2.0.0-rc.1

package/src/identity.ts

@@ -16,16 +16,22 @@
  *
  * What replaces them is a declared key: a primary key, or failing that a unique
  * index over columns that cannot be null. A table with neither cannot have one
- * of its rows named at all, so it is read-only for everybody — a 409, not a
+ * of its rows named at all, so it is read-only for everybody: a 409, not a
  * best guess.
  *
  * ## The two traps this module exists to absorb
  *
  * `getConstraints()` camel-cases **both** the table key and every column key
  * (`Case.camel`), while `getSchema()` and `getData()` speak raw database names.
- * The bridge between them is here and only here; `Case.snake` is not the
- * inverse of `Case.camel` (`SKU_code` → `sKUCode` → `s_k_u_code`), so raw names
- * are carried through from `getSchema()` rather than reconstructed.
+ * `Case.snake` is not the inverse of `Case.camel` (`SKU_code` → `sKUCode` →
+ * `s_k_u_code`), so raw names cannot be recovered from camel ones. For columns
+ * they are carried through from `getSchema()`; for index columns the adapters
+ * now carry them too (`rawCols` on `getIndexes()` entries), which retired the
+ * camel→raw map this module used to rebuild. That map was first-wins over
+ * collisions (a table holding both `user_id` and `userId` resolved an index
+ * over the second to the first, a predicate over the wrong column), and the
+ * adapter, which had the real names all along, is the only place that cannot
+ * happen.
  *
  * And `getConstraints()` includes **views**, which carry a `_view` key. A view
  * has no rows of its own to address, so it is always `none`.
@@ -80,8 +86,11 @@ export interface TableIntrospection {
   name: string
   /** `getConstraints()[Case.camel(name)]`, camel-keyed, possibly `_view`. */
   constraints: TableConstraints
-  /** This table's `getIndexes()` entries, with camel-cased column names. */
-  indexes: { name: string; type: string; cols: string[] }[]
+  /**
+   * This table's `getIndexes()` entries: `cols` camel-cased, `rawCols` the
+   * database's own spelling, aligned by position.
+   */
+  indexes: { name: string; type: string; cols: string[]; rawCols?: string[] }[]
   /** Raw database column names, in `getSchema()` order. */
   columns: string[]
 }
@@ -89,7 +98,7 @@ export interface TableIntrospection {
 /**
  * Can this identifier survive being written into a statement?
  *
- * `qId` — the single SQL identifier writer (convention 8) — snake-cases before
+ * `qId` (the single SQL identifier writer (convention 8)) snake-cases before
  * quoting, so `qId('Orders')` emits `"orders"`. For every name the ORM created
  * that is a no-op, because it snake-cases on the way in too. For a table some
  * other tool created with a capital in it, it is a statement against a
@@ -104,19 +113,6 @@ export function isAddressable(name: string): boolean {
   return Case.snake(name) === name
 }
 
-/** Build the camel-key → raw-name map `getConstraints()` needs to be read through. */
-function rawByCamel(columns: readonly string[]): Map<string, string> {
-  const map = new Map<string, string>()
-  for (const raw of columns) {
-    const camel = Case.camel(raw)
-    // First wins: two raw columns can camel-case alike (`user_id` and `userId`
-    // in the same table), and a later one must not silently take over the
-    // earlier one's constraints.
-    if (!map.has(camel)) map.set(camel, raw)
-  }
-  return map
-}
-
 /**
  * A column key of `TableConstraints` that is really a column.
  *
@@ -137,7 +133,7 @@ const none = (reason: string): Identity => ({ mode: 'none', cols: [], reason })
 export function describeIdentity(table: TableIntrospection): Identity {
   if (!isAddressable(table.name)) {
     return none(
-      `the table name ${table.name} is not addressable — ` +
+      `the table name ${table.name} is not addressable: ` +
         'identifiers are snake-cased before they are quoted',
     )
   }
@@ -147,11 +143,10 @@ export function describeIdentity(table: TableIntrospection): Identity {
     return none('a view has no rows of its own to address')
   }
 
-  const raw = rawByCamel(table.columns)
   const column = (camel: string): ColumnConstraint | undefined =>
     isColumnKey(camel) ? (constraints[camel] as ColumnConstraint) : undefined
 
-  // 1. Primary key. Composite is the normal case, not an exception — walked in
+  // 1. Primary key. Composite is the normal case, not an exception: walked in
   //    `getSchema()` column order so a composite key has a stable spelling
   //    rather than whatever order the introspection query returned.
   const primary = table.columns.filter(
@@ -175,19 +170,27 @@ export function describeIdentity(table: TableIntrospection): Identity {
     .filter(index => index.type === 'unique')
     .map(index => ({
       name: index.name,
-      cols: index.cols.map(camel => raw.get(camel)),
+      // The adapter's own raw spelling, aligned with `cols` by position: the
+      // camel spelling is kept alongside because the *constraints* are keyed by
+      // it. An entry with no `rawCols` (a TS-declared index reaching here
+      // through some future path) yields `undefined` cells and is filtered out
+      // below rather than guessed at.
+      cols: index.cols.map((camel, i) => ({
+        camel,
+        raw: index.rawCols?.[i],
+      })),
     }))
     .filter(
-      (index): index is { name: string; cols: string[] } =>
+      (index): index is { name: string; cols: { camel: string; raw: string }[] } =>
         index.cols.length > 0 &&
         index.cols.every(
           col =>
-            typeof col === 'string' &&
-            isAddressable(col) &&
+            typeof col.raw === 'string' &&
+            isAddressable(col.raw) &&
             // `nullable === false` explicitly, never `!nullable`. An adapter
             // that reported nothing for a column would otherwise read as NOT
             // NULL, which is the fail-open direction (convention 2).
-            column(Case.camel(col))?.nullable === false,
+            column(col.camel)?.nullable === false,
         ),
     )
     // Narrowest first; ties broken by index name so two equally narrow keys
@@ -197,16 +200,16 @@ export function describeIdentity(table: TableIntrospection): Identity {
     )
 
   const chosen = candidates[0]
-  if (chosen) return { mode: 'unique', cols: chosen.cols }
+  if (chosen) return { mode: 'unique', cols: chosen.cols.map(c => c.raw) }
 
   return none(
-    'no primary key and no unique index over NOT NULL columns — ' +
+    'no primary key and no unique index over NOT NULL columns: ' +
       'there is no way to name one row of this table',
   )
 }
 
 export interface ColumnFacts {
-  /** The raw database column name — what goes into a statement. */
+  /** The raw database column name: what goes into a statement. */
   name: string
   /** The key `getConstraints()` filed it under. */
   camel: string
@@ -227,7 +230,8 @@ export interface TableFacts {
   name: string
   camel: string
   isView: boolean
-  rowCount: number
+  /** `null` unless `introspect({ rowCounts: true })` was asked. See below. */
+  rowCount: number | null
   columns: ColumnFacts[]
   /** By raw column name. */
   byName: Map<string, ColumnFacts>
@@ -235,13 +239,13 @@ export interface TableFacts {
   /**
    * Declared indexes.
    *
-   * Computed here already — `describeIdentity` walks them to find a usable
-   * unique key — and now carried out rather than discarded, because the
+   * Computed here already (`describeIdentity` walks them to find a usable
+   * unique key), and now carried out rather than discarded, because the
    * Structure view shows them and there is no second endpoint that knows them.
    */
   indexes: IndexFacts[]
   /**
-   * The first text column that is not part of the identity — what a foreign-key
+   * The first text column that is not part of the identity: what a foreign-key
    * reference shows instead of a bare id. `null` when the table has none.
    */
   label: string | null
@@ -256,7 +260,7 @@ const RX_DATE_TYPE = /^(date|datetime|timestamp)/i
  * `getConstraints()` is the authority, with one exception it cannot express:
  * `ColumnType` has no date member, so every adapter maps a real `DATE` or
  * `TIMESTAMP` to `string` (MySQL explicitly, Postgres by falling through). The
- * raw SQL type is the only place that distinction survives, and it matters —
+ * raw SQL type is the only place that distinction survives, and it matters:
  * `''` into a text column is an empty string and into a timestamp is an error.
  */
 function kindOf(declared: string | undefined, sqlType: string): ColumnKind {
@@ -286,7 +290,7 @@ export function metaOf(
     nullable: constraint?.nullable ?? !schemaColumn.notnull,
     length: constraint?.length,
     enum: constraint?._enum,
-    // **Not `'default' in constraint`.** That reads as the careful choice —
+    // **Not `'default' in constraint`.** That reads as the careful choice:
     // `DEFAULT NULL` is a real default and is filed as `default: null`, so the
     // key's presence looks like the honest test. It is not: `parseConstraints`
     // writes the key on **every** column, defaulted or not, so `in` answered
@@ -294,7 +298,7 @@ export function metaOf(
     //
     // That is not cosmetic. `omittableOnInsert` is
     // `autoIncrement || hasDefault || nullable`, so an always-true `hasDefault`
-    // makes every column omittable — and the insert dialog would happily leave
+    // makes every column omittable, and the insert dialog would happily leave
     // out a NOT NULL column with no default, to be refused by the database
     // rather than by the form that knew.
     //
@@ -307,19 +311,82 @@ 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(): Promise<Map<string, TableFacts>> {
+export async function introspect(options?: {
+  /**
+   * Take the per-table `COUNT(*)`. The schema listing displays it; nothing
+   * else does, and every write introspects to resolve row identity, so the
+   * default skips a full scan of every table per write.
+   */
+  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 behavior 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 optimization 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(),
+    connection.getSchema({ rowCounts: wantsCounts }),
     connection.getConstraints(),
     connection.getIndexes(),
   ])
@@ -336,6 +403,7 @@ export async function introspect(): Promise<Map<string, TableFacts>> {
         name,
         type: index.type,
         cols: index.cols,
+        rawCols: index.rawCols,
       }))
 
     const identity = describeIdentity({
@@ -363,15 +431,13 @@ export async function introspect(): Promise<Map<string, TableFacts>> {
       columns.find(c => c.meta.kind === 'string' && !identityCols.has(c.name))
         ?.name ?? null
 
-    // `getIndexes()` camel-cases its column names like `getConstraints()` does.
-    // Translating back through the same map `describeIdentity` uses keeps one
-    // spelling on screen; an unresolvable name is shown as it came rather than
-    // dropped, so a mismatch is visible instead of silently missing a column.
-    const rawColumns = rawByCamel(table.columns.map(c => c.name))
+    // The adapter's raw spelling where it exists, the camel one where it does
+    // not: shown as it came rather than dropped, so a mismatch is visible
+    // instead of silently missing a column.
     const tableIndexFacts = tableIndexes.map(index => ({
       name: index.name,
       type: index.type,
-      cols: index.cols.map(col => rawColumns.get(col) ?? col),
+      cols: index.cols.map((col, i) => index.rawCols?.[i] ?? col),
     }))
 
     byTable.set(table.name, {
@@ -387,5 +453,9 @@ export async function introspect(): Promise<Map<string, TableFacts>> {
     })
   }
 
+  // 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/index.ts

@@ -42,7 +42,7 @@ export interface DbExplorerPluginOptions extends AccessConfig {
  * })
  * ```
  *
- * Either door admits and the higher level wins — a session admin presenting a
+ * Either door admits and the higher level wins, a session admin presenting a
  * read-only key is still an admin. With neither configured the explorer admits
  * nobody, which is the same default it had when it was read-only, and the
  * reason there is no `writes: true` flag to leave set by accident.

package/src/policy.ts

@@ -1,7 +1,7 @@
 /**
  * How much one request may do.
  *
- * These are not rate limits and not tuning knobs — they are the size at which a
+ * These are not rate limits and not tuning knobs: they are the size at which a
  * request stops being an edit and starts being a migration. The explorer has no
  * raw-SQL endpoint precisely so that nothing it exposes can rewrite a table in
  * one call; a `rows` array with no ceiling would put that back, one row at a
@@ -12,7 +12,7 @@
  * way to know which 1,000, and the retry duplicates them.
  *
  * The numbers are deliberately round rather than derived. The one real
- * constraint — the ~32,766 bound parameters a statement may carry — is already
+ * constraint (the ~32,766 bound parameters a statement may carry) is already
  * handled below this layer, by `DB.Insert`'s batching.
  */
 
@@ -23,7 +23,7 @@ export const LIMITS = {
   bulkEdits: 1000,
   /** Keys in one `DELETE /api/_db/rows`. */
   deleteKeys: 1000,
-  /** Rows in one `POST /api/_db/import` — a spreadsheet, not an edit. */
+  /** Rows in one `POST /api/_db/import`: a spreadsheet, not an edit. */
   csvRows: 50_000,
   /** Foreign-key targets resolved in one `POST /api/_db/lookup`. */
   lookupRefs: 200,
@@ -35,7 +35,7 @@ export type LimitName = keyof typeof LIMITS
  * The 413 message for a request that is too big, or `null` if it fits.
  *
  * Returns the rejection rather than throwing, and returns it for an
- * indeterminate count as well (a `keys` that is not an array reads as `NaN`) —
+ * indeterminate count as well (a `keys` that is not an array reads as `NaN`):
  * convention 2's shape, applied to a bound rather than to an identity.
  */
 export function overLimit(limit: LimitName, count: number): string | null {

package/src/preview.ts

@@ -3,14 +3,14 @@
  *
  * **This is a workaround for a gap in the ORM, and it should be read as one.**
  * `SQLAdapter.transaction()` commits when the callback returns and rolls back
- * when it throws — there is no third outcome, so there is no way to say "undo
+ * when it throws: there is no third outcome, so there is no way to say "undo
  * this, and here is what it would have done". A dry run needs exactly that: the
  * statements have to actually execute (otherwise the report is a guess about
  * constraints the database has not been asked about), and then not stick.
  *
  * So the report rides out on the exception. The transaction rolls back because
  * the callback threw, `Try.return` catches the signal outside and turns it into
- * an ordinary response, and anything that is **not** this class is rethrown —
+ * an ordinary response, and anything that is **not** this class is rethrown,
  * which is the part that has to stay right. A `catch` that swallowed a real
  * error here would report a failed write as a successful preview.
  *
@@ -24,7 +24,7 @@
  *
  * `status` because two different outcomes need the same mechanism: a dry run
  * answers 200 with what *would* have happened, and a bulk edit that hit an
- * optimistic-concurrency conflict answers 409 with what did — and both have to
+ * optimiztic-concurrency conflict answers 409 with what did, and both have to
  * leave the database untouched, so both have to leave through a throw.
  */
 export class RollbackSignal<T = unknown> extends Error {
@@ -40,12 +40,12 @@ export class RollbackSignal<T = unknown> extends Error {
 
 /** A dry run: nothing kept, 200 with the report. */
 export function previewRollback<T>(report: T): never {
-  throw new RollbackSignal(report, 200, 'dry run — rolled back')
+  throw new RollbackSignal(report, 200, 'dry run: rolled back')
 }
 
 /** A conflict: nothing kept, 409 with the report. */
 export function conflictRollback<T>(report: T): never {
-  throw new RollbackSignal(report, 409, 'conflict — rolled back')
+  throw new RollbackSignal(report, 409, 'conflict, rolled back')
 }
 
 export function isRollbackSignal(error: unknown): error is RollbackSignal {

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'
@@ -19,7 +19,7 @@ import {
 import { SHELL } from './shell'
 
 /**
- * Where this plugin's own files live — each package that ships files anchors
+ * Where this plugin's own files live: each package that ships files anchors
  * to its own location, never to core's (see the dashboard's `paths.ts` for
  * the 404s that lesson cost).
  */
@@ -63,23 +63,23 @@ async function handleClientJs() {
 }
 
 /**
- * The whole request surface, and **the key spellings are the CSRF policy** —
+ * The whole request surface, and **the key spellings are the CSRF policy**,
  * `guardFor` in `plugins/routes.ts` reads them, so getting one wrong here
  * silently loosens a guard rather than failing anywhere visible.
  *
  * - **Bare keys are the reads.** A bare key matches every method and gets
  *   `checkSameOrigin` on *all* of them, which is the stricter of the two: no
  *   cross-site page reaches these, whatever verb it uses.
- * - **Every write key names its method.** That pins the verb — a `GET
- *   /api/_db/rows` no longer resolves at all — and applies `checkCsrf`.
+ * - **Every write key names its method.** That pins the verb (a `GET
+ *   /api/_db/rows` no longer resolves at all), and applies `checkCsrf`.
  *
  * This comment used to say the table needed no CSRF middleware because nothing
  * here could mutate anything. That was true when the plugin was read-only and
  * is now false: rows are inserted, edited and deleted below. What is still
  * true, and is the claim that survives, is **structural**: there is no
  * raw-SQL endpoint and nothing that creates, drops or alters a table. The write
- * surface is bounded and enumerable — it is exactly the five method-qualified
- * keys below — rather
+ * surface is bounded and enumerable (it is exactly the five method-qualified
+ * keys below), rather
  * than gated behind a flag the way the dashboard's is.
  *
  * `/api/_db/graph` and `/api/_db/lookup` are reads despite one of them taking a
@@ -104,6 +104,8 @@ export const explorerRoutes = {
 const dispatchExplorerRoute = routeTable(explorerRoutes)
 
 export class DbExplorerHandler extends Handler {
+  static override namespace = '/_db'
+
   static canHandle(path: string) {
     return (
       path === '/_db' ||
@@ -115,7 +117,7 @@ export class DbExplorerHandler extends Handler {
 
   static async handle(path: string, req: Request) {
     // Styling and script are not secrets, and letting them through keeps an
-    // unauthorised response from rendering unstyled — same split as the
+    // unauthorized response from rendering unstyled: same split as the
     // dashboard. Everything else fails closed.
     const access = await resolveAccess(req, config)
     if (!/\.(css|js)$/.test(path) && !access) {
@@ -124,11 +126,11 @@ export class DbExplorerHandler extends Handler {
         : response.error('Not Found', 404)
     }
 
-    // The level travels with the request rather than in a module variable —
+    // The level travels with the request rather than in a module variable.
     // see `accessStore`. `read` is the floor for the asset paths admitted
     // above, which never consult it but must not run outside a store.
     return await accessStore.run(access || 'read', async () => {
-      // Dispatch keys on `url.pathname` from the request itself — the `path`
+      // Dispatch keys on `url.pathname` from the request itself: the `path`
       // argument only steers the auth split above.
       const result = await dispatchExplorerRoute(req)
       return result ?? response.error('Not Found', 404)
@@ -137,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),

package/src/shared/coerce.ts

@@ -1,15 +1,15 @@
 /**
  * Wire value → column value, and the validation that goes with it.
  *
- * **Pure.** No `Bun.*`, no node builtins, no DOM — convention 5's rule applied
+ * **Pure.** No `Bun.*`, no node builtins, no DOM: convention 5's rule applied
  * inside the plugin, because this module is imported by the endpoints *and*
  * compiled into the browser bundle, so the grid can tell a user their input is
  * wrong before a request is made and get the same answer the server would give.
  * One implementation is the only way those two answers stay equal.
  *
  * **Pure also means importing nothing from `@bakery-framework/*`, including
- * `utils/isomorphic`.** That reads like the one safe exception — it is the
- * framework's own pure layer — and it is not, for a mechanical reason:
+ * `utils/isomorphic`.** That reads like the one safe exception (it is the
+ * framework's own pure layer), and it is not, for a mechanical reason:
  * `bundleModule` marks every *installed package* external
  * (`compiler.ts:316`), so a framework import survives into the emitted bundle
  * as a bare specifier, the browser tries to fetch
@@ -27,9 +27,9 @@
  * express "leave this alone", an empty text field cleared to `NULL`, and `""`
  * into a numeric column silently became `0`. Here:
  *
- *   - **key absent** — leave the column unchanged. Never reaches this function.
- *   - **`null`** — SQL NULL. Refused on a NOT NULL column rather than coerced.
- *   - **`""`** — the empty string. On a text column that is a value; on any
+ *   - **key absent**. Leave the column unchanged. Never reaches this function.
+ *   - **`null`**, SQL NULL. Refused on a NOT NULL column rather than coerced.
+ *   - **`""`**: the empty string. On a text column that is a value; on any
  *     other kind it is an error, never zero and never NULL.
  *
  * And `"007"` is a string in a text column and the number 7 in an integer one,
@@ -41,8 +41,8 @@
  * What kind of value a column holds.
  *
  * The ORM's own `ColumnType` plus `date`. That extra member is not reachable
- * from `getConstraints()` — the ORM stores timestamps as integer seconds, so it
- * reports `integer` — and exists for a column some other tool created as a real
+ * from `getConstraints()` (the ORM stores timestamps as integer seconds, so it
+ * reports `integer`), and exists for a column some other tool created as a real
  * `DATE`/`TIMESTAMP`, which the raw SQL type from `getSchema()` reveals. A
  * genuine date column binds a `Date`, and an integer timestamp binds a number;
  * conflating them is how a timestamp ends up written as the year 1970.
@@ -101,9 +101,8 @@ const ok = (value: unknown): CoerceResult => ({ ok: true, value })
  *
  * `json` and `buffer` cannot, portably: MySQL compares JSON structurally,
  * Postgres refuses `=` on `json` outright (only `jsonb` has it), and a blob
- * comparison depends on how the driver bound the parameter. An optimistic
- * `expect` on one of these would be a predicate that silently never matched —
- * every edit a 409 — so it is refused instead.
+ * comparison depends on how the driver bound the parameter. An optimiztic
+ * `expect` on one of these would be a predicate that silently never matched ( * every edit a 409), so it is refused instead.
  */
 export function comparableKind(kind: ColumnKind): boolean {
   return kind !== 'json' && kind !== 'buffer'
@@ -133,7 +132,7 @@ function coerceInteger(raw: unknown, meta: ColumnMeta): CoerceResult {
     // Narrowed back to a number when it fits, so the common case binds the
     // type every driver has always taken. A value outside the safe range stays
     // a bigint, because turning it into a `number` is the precision loss this
-    // branch exists to avoid — `bigint` is the ORM's own column kind for it.
+    // branch exists to avoid: `bigint` is the ORM's own column kind for it.
     const inSafeRange =
       n <= BigInt(Number.MAX_SAFE_INTEGER) &&
       n >= BigInt(Number.MIN_SAFE_INTEGER)
@@ -187,7 +186,7 @@ function coerceBoolean(raw: unknown): CoerceResult {
 /**
  * A real date/time column, bound as a `Date`.
  *
- * Accepts an ISO-8601 string or a number of **milliseconds** since the epoch —
+ * Accepts an ISO-8601 string or a number of **milliseconds** since the epoch:
  * milliseconds because that is what `Date.now()` and `JSON.stringify(new Date)`
  * produce on the client, and a value that is ambiguous between the two units
  * does not exist: an integer timestamp column reports kind `integer` and never
@@ -215,9 +214,9 @@ function coerceDate(raw: unknown): CoerceResult {
 /**
  * A JSON column, stored as text.
  *
- * The ORM serialises nothing — `Field.Json` declares the column type and the
- * application decides what goes in it — so the explorer stores text and refuses
- * text that is not JSON. An object or array on the wire is serialised here
+ * The ORM serializes nothing: `Field.Json` declares the column type and the
+ * application decides what goes in it, so the explorer stores text and refuses
+ * text that is not JSON. An object or array on the wire is serialized here
  * rather than at the call site, so the grid can send either spelling.
  */
 function coerceJson(raw: unknown): CoerceResult {
@@ -237,7 +236,7 @@ function coerceJson(raw: unknown): CoerceResult {
       return ok(JSON.stringify(raw))
     } catch {
       // A cycle, or a BigInt. Same reasoning as above.
-      return fail('bad_json', 'value cannot be serialised as JSON')
+      return fail('bad_json', 'value cannot be serialized as JSON')
     }
   }
   return fail('type', `expected JSON, got ${typeName(raw)}`)
@@ -312,7 +311,7 @@ export function coerceValue(raw: unknown, meta: ColumnMeta): CoerceResult {
   if (raw === '' && meta.kind !== 'string') {
     // The whole reason this function returns a result rather than a value.
     // `Number('')` is 0, `Boolean('')` is false and `new Date('')` is Invalid
-    // Date — three different wrong answers for the same input, which is what
+    // Date: three different wrong answers for the same input, which is what
     // the dashboard's editor shipped.
     return fail(
       'empty_string',
@@ -351,16 +350,16 @@ export function omittableOnInsert(meta: ColumnMeta): boolean {
 }
 
 /**
- * "Did the user actually change this?" — deliberately loose.
+ * "Did the user actually change this?", deliberately loose.
  *
  * The two operands come from different worlds: the left is a value the database
  * returned, the right is whatever JSON the browser sent, and a driver that
  * hands back `1` for a boolean or a string for a `BIGINT` is not a difference
  * the user made. Strict equality here would send a `set` full of columns nobody
- * touched, which is how an optimistic-concurrency check turns into a conflict
+ * touched, which is how an optimiztic-concurrency check turns into a conflict
  * for every concurrent editor of any column.
  *
- * This is used to *shrink* a statement, never to decide correctness — the
+ * This is used to *shrink* a statement, never to decide correctness: the
  * server's own conflict check is a SQL predicate, not this.
  */
 export function sameValue(a: unknown, b: unknown): boolean {
@@ -379,7 +378,7 @@ export function sameValue(a: unknown, b: unknown): boolean {
   }
   if (typeof a === 'object' || typeof b === 'object') {
     // A cyclic object throws in `JSON.stringify`, and "could not be compared"
-    // has to mean "not equal" — the conservative direction, because it keeps
+    // has to mean "not equal": the conservative direction, because it keeps
     // the column in the statement rather than dropping an edit the user made.
     //
     // A bare try/catch rather than core's `Try`, and that is a constraint of