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

package/src/client/panel.ts

@@ -1,5 +1,5 @@
 /**
- * The row side panel — one row, as a form.
+ * The row side panel: one row, as a form.
  *
  * Promoted from `drawer.ts`, which did the same job with less of it. The grid
  * is the right shape for scanning and the wrong shape for a forty-column row:
@@ -14,11 +14,11 @@
  *    beats a cell for those two.
  *  - **Both directions of the graph.** "References" jumps to the row this one
  *    points at; "Referenced by" lists the rows pointing here.
- *  - **Exact counts.** They used to be labelled approximate and were: the only
+ *  - **Exact counts.** They used to be labeled approximate and were: the only
  *    filter available was a substring `LIKE`, so a row with id `1` counted `11`
  *    and `21` too. With `eq` the number is the number.
  *
- * "Referenced by" is still **lazy** — one request per referencing table, issued
+ * "Referenced by" is still **lazy**: one request per referencing table, issued
  * when the section is opened. Doing that for every visible row would be the
  * per-cell `fetch` that `fk.ts` exists to avoid, in a different costume.
  */
@@ -103,7 +103,7 @@ function fields(ctx: PanelContext, id: string | null): HTMLElement {
 /**
  * One column: its name, its declared type, and an editor or a read-only value.
  *
- * The same `createEditor` the grid opens in a cell — including the null toggle,
+ * The same `createEditor` the grid opens in a cell, including the null toggle,
  * which is the whole reason a 40-column row is editable here at all: several of
  * those columns are nullable, and a form of plain text inputs cannot say so.
  * `multiline` is the one difference, and it is what makes this the place long
@@ -136,7 +136,7 @@ function field(
     current,
     {
       // In the panel there is no cursor to move, so every change stages
-      // immediately. Same buffer, same Save — the difference is only that the
+      // immediately. Same buffer, same Save: the difference is only that the
       // grid needs a commit key to know where to go next and this does not.
       onInput: value => {
         ctx.session.stage(id, ctx.row, column.name, value)
@@ -178,7 +178,7 @@ function footer(
         ctx.session.drop(id)
         ctx.onDirtyChange()
         message.textContent =
-          'reverted — reopen the row to see the stored values'
+          'reverted: reopen the row to see the stored values'
       },
       { class: 'btn' },
     ),
@@ -187,7 +187,7 @@ function footer(
 }
 
 /**
- * The rows *this* row points at — one link per outgoing foreign key.
+ * The rows *this* row points at: one link per outgoing foreign key.
  *
  * Not lazy, because it costs nothing: the key is already in the row, so the
  * link is built from data in hand and only the click spends a request. A key
@@ -235,7 +235,7 @@ function referenceRow(ctx: PanelContext, relation: Relation): HTMLElement {
 /**
  * Tables that point at this row, resolved when the section is opened.
  *
- * The counts are **exact**. They used to be labelled approximate and were —
+ * The counts are **exact**. They used to be labeled approximate and were:
  * the only filter the table-data endpoint offered was `col LIKE '%value%'`, so
  * a row with id `1` matched `11` and `21` too. `eq` removed the caveat along
  * with the reason for it.

package/src/client/relations.ts

@@ -20,7 +20,7 @@ import type { ForeignKeyInfo, SchemaGraph } from './meta'
 import { sameTable } from './meta'
 
 export interface Relation {
-  /** The columns on the near side — this table's, for `outgoing`. */
+  /** The columns on the near side: this table's, for `outgoing`. */
   cols: string[]
   /** The table at the other end. */
   table: string
@@ -43,10 +43,10 @@ export interface Relations {
  * programming: `getForeignKeys()` reports whatever the database calls a table
  * while `getConstraints()` is camel-keyed, and the graph endpoint passes both
  * through untouched. Comparing literally makes every foreign key on a
- * `snake_case` schema invisible — the whole feature silently absent, which is
+ * `snake_case` schema invisible: the whole feature silently absent, which is
  * exactly what `meta.ts`'s own note on `sameTable` records.
  *
- * A self-reference — a `manager_id` pointing at the same table's `id` — appears
+ * A self-reference (a `manager_id` pointing at the same table's `id`) appears
  * in **both** lists, which is correct: it is genuinely a key this table
  * declares and genuinely a key that points here.
  */
@@ -189,7 +189,7 @@ function incomingRow(ctx: RelationsContext, relation: Relation): HTMLElement {
  * The filters that open the rows of `relation.table` pointing at one row.
  *
  * Exported for the row panel, which is where "referenced by *this row*" lives.
- * `eq` per column, so the count and the page are exact — this used to be a
+ * `eq` per column, so the count and the page are exact: this used to be a
  * substring `LIKE` and the panel had to label its counts "approximate".
  */
 export function filtersForIncoming(

package/src/client/save.ts

@@ -43,7 +43,7 @@ function kindLookup(
  *
  * The pre-image goes as `expect`, so the statement is `identity ∧ expect` and a
  * concurrent edit is a 409 rather than a silent overwrite. `force` is sent only
- * when a changed column is `json` or `buffer` — kinds SQL cannot compare, so
+ * when a changed column is `json` or `buffer`: kinds SQL cannot compare, so
  * there is no predicate to guard them with.
  */
 export async function saveRow(
@@ -113,8 +113,8 @@ async function reportFailure(
 /**
  * Keep mine / Take theirs, with the server's copy of the row in hand.
  *
- * The 409 body carries the row as it now stands — that is why the endpoint
- * attaches it — so this is a real choice rather than a prompt to guess.
+ * The 409 body carries the row as it now stands (that is why the endpoint
+ * attaches it), so this is a real choice rather than a prompt to guess.
  */
 function offerResolution(
   table: SchemaTable,
@@ -172,7 +172,7 @@ function offerResolution(
 /**
  * Keep mine: the same `set`, with `expect` taken from *their* row.
  *
- * Not `expect: {}` — that is last-write-wins, which the endpoint refuses to
+ * Not `expect: {}`. That is last-write-wins, which the endpoint refuses to
  * default to for exactly this reason. Rebasing on the row that was just shown
  * means a *third* edit arriving between the 409 and this retry is a 409 again,
  * which is the correct answer rather than an inconvenience.

package/src/client/sidebar.ts

@@ -6,7 +6,7 @@
  * everything else and had no business sharing a module with the grid's chrome.
  *
  * A **single click opens a preview tab** and a **double click makes it
- * permanent** — the two are wired here and defined in `tabs.ts`.
+ * permanent**: the two are wired here and defined in `tabs.ts`.
  */
 
 import { append, box, button, each, el, on } from './dom'
@@ -46,7 +46,7 @@ export function renderSidebar(ctx: SidebarContext): HTMLElement {
  * The system-tables checkbox, present only when there is something to reveal.
  *
  * `__bakery_schema` is the ORM's sync ledger and is not the user's data, so it
- * is hidden by default — but every real client offers the toggle rather than
+ * is hidden by default, but every real client offers the toggle rather than
  * hiding such tables outright, because a ledger row is occasionally exactly
  * what someone needs to see. The count is in the label so the checkbox says
  * what it would do before it is clicked.
@@ -65,7 +65,7 @@ function systemToggle(ctx: SidebarContext): HTMLElement | null {
   const label = el('label', {
     class: 'note system-toggle',
     text: ` show system tables (${hidden})`,
-    title: "the framework's own bookkeeping — the ORM sync ledger",
+    title: "the framework's own bookkeeping: the ORM sync ledger",
   })
   label.prepend(check)
   return label
@@ -76,8 +76,8 @@ function tableButton(ctx: SidebarContext, table: SchemaTable): HTMLElement {
     class: 'table-btn',
   })
   // `dblclick` fires *after* its two `click`s, so the single click has already
-  // opened the preview tab and this only promotes it — which is exactly VS
-  // Code's behaviour and needs no suppression of the first click.
+  // opened the preview tab and this only promotes it, which is exactly VS
+  // Code's behavior and needs no suppression of the first click.
   on(node, 'dblclick', () => ctx.onOpen(table.name))
 
   if (table.name === ctx.activeTable) node.classList.add('active')
@@ -96,7 +96,7 @@ function badgeFor(table: SchemaTable): HTMLElement | null {
     return el('span', {
       class: 'ro',
       text: '⊞',
-      title: 'a view — it has no rows of its own to address',
+      title: 'a view: it has no rows of its own to address',
     })
   }
   if (!table.writable) {

package/src/client/state.ts

@@ -9,7 +9,7 @@
  * The view lives in the **hash** rather than the query string on purpose. The
  * explorer is reached with `?db-key=…` on a first visit, the client scrubs that
  * parameter out of the URL immediately, and a view state sharing the query
- * string would be scrubbed along with it — or worse, would have to be
+ * string would be scrubbed along with it, or worse, would have to be
  * reconstructed by an edit to the same `URLSearchParams` the credential was
  * just removed from. A hash also never reaches the server, which is the right
  * place for "which row am I on".
@@ -34,7 +34,7 @@ export interface ViewState {
   sortBy: string | null
   sortOrder: 'ASC' | 'DESC'
   /**
-   * Column, operator and operand — several, each removable.
+   * Column, operator and operand: several, each removable.
    *
    * A **list** rather than a record, because the builder lets a filter exist
    * before it has a column or a value and a record cannot hold a half-built
@@ -62,7 +62,7 @@ export function defaultView(table = ''): ViewState {
  * omitted rather than written, so the common case is `t=parcels`.
  *
  * There is no `r` any more. It carried a row identity because a filter could
- * not name a row — `id=1` matched `11` under a substring `LIKE` — and with `eq`
+ * not name a row (`id=1` matched `11` under a substring `LIKE`), and with `eq`
  * available a foreign-key jump is just a filter. An old link with `r=` decodes
  * to the same page it always did, minus the highlight.
  */
@@ -159,7 +159,7 @@ export function tableOf(
  *
  * Matched against the **raw** database name, which is what the schema report
  * carries: `introspect()` builds from `getSchema()`, and that speaks raw names.
- * (`getConstraints()` camel-cases, so the same table is `bakerySchema` there —
+ * (`getConstraints()` camel-cases, so the same table is `bakerySchema` there:
  * that spelling never reaches this client, and matching it here would risk
  * hiding a user table that happens to be called `bakerySchema`.)
  */

package/src/client/statusbar.ts

@@ -5,7 +5,7 @@
  * Every database client has one, and it earns its space by answering three
  * questions that otherwise need a round trip through the developer tools: how
  * many rows there really are, how long the server took, and whether this
- * session can write at all. The last one is the reason it exists here — the
+ * session can write at all. The last one is the reason it exists here: the
  * access level used to be a line of sidebar text that scrolled away.
  *
  * `statusParts` is **pure** and is where the wording lives, so the segments are
@@ -30,7 +30,7 @@ export interface StatusFacts {
 /**
  * The segments, in order, already worded.
  *
- * Absent facts are **omitted rather than rendered as a placeholder** — a
+ * Absent facts are **omitted rather than rendered as a placeholder**: a
  * `page 1 / ?` teaches nobody anything, and `getData` genuinely does not always
  * return a total. An empty array is the honest answer for "nothing is open".
  */
@@ -70,7 +70,7 @@ function formatCount(count: number): string {
  * Sub-millisecond timings keep one decimal.
  *
  * `getElapsed` returns a float, and a fast query rounding to `0 ms` reads as
- * "not measured" rather than "fast" — which is the opposite of what it means.
+ * "not measured" rather than "fast", which is the opposite of what it means.
  */
 function formatMs(ms: number): string {
   return ms < 10 ? ms.toFixed(1) : String(Math.round(ms))
@@ -89,7 +89,7 @@ export class StatusBar {
    * The last facts painted.
    *
    * Kept so `bumpDirty` can repaint one segment without the caller having to
-   * reconstruct the row count, the page and the timing — which it cannot,
+   * reconstruct the row count, the page and the timing, which it cannot,
    * since a staged edit does not re-fetch and the alternative would be showing
    * a stale count or none.
    */
@@ -122,8 +122,8 @@ export class StatusBar {
 
   private render(): void {
     this.line.textContent = statusParts(this.facts).join(' · ')
-    // The dirty count is the one segment worth colouring, and it is always
-    // last — so the class goes on the bar rather than on a span nobody can see
+    // The dirty count is the one segment worth coloring, and it is always
+    // last, so the class goes on the bar rather than on a span nobody can see
     // when the bar is empty.
     this.node.classList.toggle('dirty', this.facts.dirtyRows > 0)
   }

package/src/client/structure.ts

@@ -1,13 +1,13 @@
 /**
  * The Structure view: what the table *is*, as opposed to what is in it.
  *
- * Every serious client — DBeaver, DataGrip, Devart — splits a table into Data
+ * Every serious client (DBeaver, DataGrip, Devart) splits a table into Data
  * and its structure, and keeps them apart. This one was the single biggest
  * omission: `GET /api/_db/schema` has always returned the type, nullability,
  * default, enum values, auto-increment flag and resolved row identity of every
  * column, and the client used all of it *only* to pick which editor widget to
  * open. None of it was ever on screen. The reason a table is read-only was the
- * worst of it — it existed, in the server's own words, and appeared nowhere
+ * worst of it: it existed, in the server's own words, and appeared nowhere
  * except a tooltip on a padlock.
  *
  * `structureRows` is **pure** and is the whole derivation, so what each column
@@ -22,7 +22,7 @@ export interface StructureRow {
   name: string
   type: string
   nullable: string
-  /** `AUTO`, a literal `DEFAULT`, or empty — never a guess. */
+  /** `AUTO`, a literal `DEFAULT`, or empty, never a guess. */
   default: string
   /** `PK`, `unique`, or empty. */
   key: string
@@ -40,7 +40,7 @@ export interface StructureRow {
  *
  *  - **`hasDefault` and `autoIncrement` are different facts**, and an
  *    auto-increment column is reported as such rather than as "has a default".
- *    They differ in the one place it matters — `omittableOnInsert` — and
+ *    They differ in the one place it matters (`omittableOnInsert`), and
  *    conflating them on screen would teach the reader the wrong model.
  *  - **`notnull` is not the negation of `nullable` here.** The server sends
  *    both, from two different introspection calls (`getConstraints()` when it
@@ -114,8 +114,8 @@ const INDEX_HEADINGS = ['index', 'type', 'columns'] as const
 /**
  * A scrolling table of plain text cells.
  *
- * Columns and indexes are the same table twice — headings, then a `<tr>` of
- * `<td class="cell">` per row — so they are one builder and two `string[][]`.
+ * Columns and indexes are the same table twice (headings, then a `<tr>` of
+ * `<td class="cell">` per row), so they are one builder and two `string[][]`.
  */
 function dataTable(
   headings: readonly string[],
@@ -150,7 +150,7 @@ export function renderStructure(ctx: StructureContext): HTMLElement {
 }
 
 /**
- * How a row of this table is named — and, when it cannot be, why.
+ * How a row of this table is named, and, when it cannot be, why.
  *
  * First rather than last, and a banner rather than a footnote. "This table is
  * read-only" with no reason is the message that generates support questions;
@@ -165,7 +165,7 @@ function identitySection(ctx: StructureContext): HTMLElement {
     section.appendChild(
       el('p', {
         class: 'banner warn',
-        text: `no row of this table can be named — ${ctx.reason}`,
+        text: `no row of this table can be named: ${ctx.reason}`,
       }),
     )
     return section

package/src/client/tabs.ts

@@ -1,19 +1,19 @@
 /**
  * Open tables as tabs, with VS Code's preview semantics.
  *
- * **Pure — no DOM.** Every transition is a function from a state to a state, so
+ * **Pure, no DOM.** Every transition is a function from a state to a state, so
  * the rules below are asserted in `tabs.test.ts` rather than inferred from a
  * click handler. `tabstrip.ts` is the view over this.
  *
- * The behaviour is Supabase Studio's, which is VS Code's:
+ * The behavior is Supabase Studio's, which is VS Code's:
  *
- *  - A **single click** opens a *preview* tab — rendered italic, and **replaced
+ *  - A **single click** opens a *preview* tab: rendered italic, and **replaced
  *    in place** by the next single click. Browsing twelve tables therefore
  *    leaves one tab open, not twelve, which is the whole point.
  *  - **Double-clicking**, or **editing**, makes it permanent. Investment is what
  *    promotes a tab; merely looking at it is not.
  *  - A table that is already open is *selected* rather than reopened, and its
- *    own view state — page, sort, filters — is left exactly as it was. That is
+ *    own view state (page, sort, filters) is left exactly as it was. That is
  *    the property that makes tabs worth having: switching back restores.
  *
  * There is at most one preview tab, which is what makes "replace the preview"
@@ -58,8 +58,8 @@ function previewIndex(state: TabsState): number {
 /**
  * Single click: open as preview.
  *
- * Three cases in order, and the order is the behaviour. An already-open table
- * wins over everything — reopening it would throw away the page and filters the
+ * Three cases in order, and the order is the behavior. An already-open table
+ * wins over everything: reopening it would throw away the page and filters the
  * user left it on, which is precisely what tabs exist to preserve.
  */
 export function openPreview(state: TabsState, view: ViewState): TabsState {
@@ -109,8 +109,8 @@ export function selectTab(state: TabsState, index: number): TabsState {
 /**
  * Close one tab.
  *
- * Closing the active tab activates whatever slid into its slot — the tab to the
- * right — and the last tab when there is nothing to the right. Closing anything
+ * Closing the active tab activates whatever slid into its slot (the tab to the
+ * right), and the last tab when there is nothing to the right. Closing anything
  * left of the active one shifts the active index down so the *same* tab stays
  * selected, which is the bug the naive version has.
  */
@@ -172,7 +172,7 @@ export function pruneTabs(
 /**
  * The whole strip in a hash.
  *
- * `x` repeats, one per tab, each holding a whole encoded view — `URLSearchParams`
+ * `x` repeats, one per tab, each holding a whole encoded view: `URLSearchParams`
  * escapes the inner `&` on the way in and unescapes it on the way out, so the
  * nesting needs no encoding of its own. `a` is the active index and `w` the
  * preview one; both are indexes rather than flags because there is at most one
@@ -191,7 +191,7 @@ export function decodeTabs(hash: string): TabsState {
   const params = new URLSearchParams(hash.replace(/^#/, ''))
   const encoded = params.getAll('x')
 
-  // A pre-tabs link — `#t=parcels&p=2` — is one permanent tab. Those links are
+  // A pre-tabs link (`#t=parcels&p=2`) is one permanent tab. Those links are
   // in chat logs and bookmarks, and silently rendering nothing for them would
   // be the most visible possible regression.
   if (!encoded.length) {

package/src/client/tabstrip.ts

@@ -1,7 +1,7 @@
 /**
  * The tab strip, and the view switcher under it.
  *
- * Two rows, and **exactly two** — the table tabs, then Data / Structure /
+ * Two rows, and **exactly two**: the table tabs, then Data / Structure /
  * Relations for whichever table is active. Beekeeper sells itself on not having
  * "tabs within tabs", and it is right: one level of nesting is navigable and
  * two is a maze. Nothing below this line gets its own strip.
@@ -19,7 +19,7 @@ export interface TabStripContext {
   /** Double-click on a preview tab: keep it. */
   onPromote: (index: number) => void
   onClose: (index: number) => void
-  /** The `+` button — back to the table picker. */
+  /** The `+` button: back to the table picker. */
   onNew: () => void
 }
 
@@ -50,7 +50,7 @@ function tabNode(ctx: TabStripContext, index: number): HTMLElement {
 
   const label = button(tab.view.table, () => ctx.onSelect(index), {
     class: 'tab-label',
-    title: tab.preview ? `${tab.view.table} — preview` : tab.view.table,
+    title: tab.preview ? `${tab.view.table}: preview` : tab.view.table,
   })
   on(label, 'dblclick', () => ctx.onPromote(index))
   node.appendChild(label)

package/src/client.ts

@@ -1,23 +1,23 @@
 /**
  * The explorer's browser entry: boot, then wiring. Nothing else.
  *
- * This file used to be the whole client — 197 lines, one `renderTable` that
+ * This file used to be the whole client: 197 lines, one `renderTable` that
  * fetched, built a header, built a body and built a pager, and scored **34**
  * against biome's ceiling of 25. Growing that into a data editor would have
  * meant growing that one function, so the shape changed first. The pieces live
- * under `client/`, each obeying two mechanical rules — **no function both
- * fetches and renders**, and **every loop body is a named function** — and what
+ * under `client/`, each obeying two mechanical rules (**no function both
+ * fetches and renders**, and **every loop body is a named function**), and what
  * is left here is the composition: state, routing, and which callback goes
  * where.
  *
  * The layout is the one a database client is expected to have: a table list, a
  * strip of table tabs with VS Code preview semantics, Data / Structure /
- * Relations under it — **one level of nesting and no more** — and a status bar.
+ * Relations under it (**one level of nesting and no more**), and a status bar.
  * Tab state lives in `client/tabs.ts` and is pure; this module owns the hash.
  *
  * What is deliberately *not* here, and is not anywhere: a SQL console, an ER
- * diagram, and grid virtualisation. The first is refused by the plugin's
- * contract — no raw SQL, structurally — and the other two are not what a row
+ * diagram, and grid virtualization. The first is refused by the plugin's
+ * contract (no raw SQL, structurally), and the other two are not what a row
  * editor is for.
  */
 
@@ -119,7 +119,7 @@ function writeHash(): void {
   selfNavigation = true
   location.hash = encodeTabs(tabs)
   // `hashchange` fires as a task, so the flag has to survive at least until
-  // the next one — a microtask would clear it before the listener ran.
+  // the next one: a microtask would clear it before the listener ran.
   setTimeout(() => {
     selfNavigation = false
   }, 0)
@@ -137,7 +137,7 @@ async function confirmDiscard(): Promise<boolean> {
   const ok = await confirmChoice({
     verb: 'discard',
     count: session.dirtyRows(),
-    table: currentTable() || '—',
+    table: currentTable() || '-',
     detail: 'unsaved edits will be thrown away',
   })
   if (ok) session.clear()
@@ -202,8 +202,8 @@ function switchView(view: TableView): void {
  *
  * The slots matter: `renderChrome` repaints the sidebar and the strip in
  * place, and `#main` is not one of them. Rebuilding the whole shell on every
- * tab-strip change would tear down the grid — including any editor open in it
- * and the focus inside that editor — every time a staged edit promoted a
+ * tab-strip change would tear down the grid (including any editor open in it
+ * and the focus inside that editor) every time a staged edit promoted a
  * preview tab, which is precisely when it must not.
  */
 const sideSlot = el('div', { class: 'side-slot' })
@@ -263,7 +263,7 @@ async function renderAll(): Promise<void> {
   await renderMain()
 }
 
-/** Fetch, then render — the two never live in one function. */
+/** Fetch, then render: the two never live in one function. */
 async function renderMain(): Promise<void> {
   const main = mainSlot
   const view = activeView(tabs)
@@ -282,7 +282,7 @@ async function renderMain(): Promise<void> {
   }
 
   // Structure and Relations render from the schema report the client already
-  // holds — no request, so no loading state and no failure path.
+  // holds: no request, so no loading state and no failure path.
   if (view.view !== 'data') {
     page.paintMeta(main, view, table)
     return
@@ -318,7 +318,7 @@ function openRowPanel(
       handle.close()
       save(table, id)
     },
-    // A real edit is what makes a preview tab permanent — VS Code's rule, and
+    // A real edit is what makes a preview tab permanent: VS Code's rule, and
     // the one that matters: nobody wants the tab they just typed into replaced
     // by the next single click in the sidebar.
     onDirtyChange: () => {
@@ -333,14 +333,14 @@ function openRowPanel(
 /**
  * Follow a foreign key.
  *
- * One `eq` filter per referenced column, which *is* the row identity — so the
+ * One `eq` filter per referenced column, which *is* the row identity, so the
  * destination page holds exactly the referenced row. This used to need a
  * second mechanism: `filters` was a substring `LIKE`, `id=1` also matched `11`,
  * so a link carried a separate `focus` identity and the grid highlighted it.
  * `eq` removed the need and `focus` went with it.
  *
  * The current view is pushed first, so Back returns to where the reference was
- * followed from — the breadcrumb, which stays.
+ * followed from: the breadcrumb, which stays.
  */
 async function followFk(
   target: FkTarget,
@@ -370,14 +370,14 @@ async function boot(): Promise<void> {
   adoptUrlKey()
   try {
     // `{access, tables}`: the client has to know its posture *before* it
-    // renders, so it never draws an edit affordance it cannot honour.
+    // renders, so it never draws an edit affordance it cannot honor.
     state.report = await fetchSchema()
   } catch (error) {
     app.replaceChildren(el('p', { class: 'error', text: messageOf(error) }))
     return
   }
 
-  // The graph is decoration — a schema with no declared foreign keys is
+  // The graph is decoration: a schema with no declared foreign keys is
   // ordinary, and a failure here must not cost anyone the grid.
   state.graph = await fetchGraph().catch(() => null)
 

package/src/endpoints/common.ts

@@ -2,11 +2,11 @@
  * The preamble every write endpoint shares, in the order the checks have to
  * happen.
  *
- *   1. **`currentCanWrite()`** — a `read` caller is refused before the body is
+ *   1. **`currentCanWrite()`**: a `read` caller is refused before the body is
  *      even parsed, so nothing about the request can influence the answer.
- *   2. **The body** — JSON, an object, naming a table.
- *   3. **The table** — 404 if it is not there.
- *   4. **The identity** — 409 if the table has none. A table with no primary
+ *   2. **The body**: JSON, an object, naming a table.
+ *   3. **The table**: 404 if it is not there.
+ *   4. **The identity**: 409 if the table has none. A table with no primary
  *      key and no all-NOT-NULL unique index is read-only for everyone,
  *      including a `write` caller, because there is no way to name one of its
  *      rows. See `identity.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'
@@ -37,7 +38,7 @@ export function invalid(errors: FieldError[]): Envelope {
  * The request body as an object, or `null`.
  *
  * `req.json()` rather than core's `processBody`, which answers `{}` for a body
- * it could not parse — indistinguishable from an empty one, so a truncated
+ * it could not parse: indistinguishable from an empty one, so a truncated
  * upload would be reported as a missing `table` field.
  */
 export async function readBody(
@@ -55,7 +56,7 @@ export async function readBody(
 /**
  * Find a table by the name the caller used.
  *
- * Raw database name first — that is what `/api/_db/schema` renders and what the
+ * Raw database name first: that is what `/api/_db/schema` renders and what the
  * grid sends back. The camel spelling is accepted as well, because a script
  * written against a typed schema has `orderItems` where the database has
  * `order_items`, and refusing that would be refusing the ORM's own vocabulary.
@@ -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

@@ -3,7 +3,7 @@
  *
  * `/api/_db/graph` is the map, fetched once: every declared foreign key, every
  * table's identity, and the column worth showing instead of an id.
- * `/api/_db/lookup` resolves actual references — **batched, one query per
+ * `/api/_db/lookup` resolves actual references: **batched, one query per
  * table**, because the shape this replaces is a `fetch` per visible cell, and a
  * fifty-row page with three foreign keys is a hundred and fifty round trips.
  */
@@ -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(
@@ -23,7 +23,7 @@ export async function handleGraph(): Promise<JsonResponseData<unknown>> {
       const [tables, foreignKeys] = await Promise.all([
         introspect(),
         // Composites are already grouped by the adapter, keyed by the tuple
-        // rather than by constraint name — SQLite reports no name at all.
+        // rather than by constraint name: SQLite reports no name at all.
         connection.getForeignKeys(),
       ])
 
@@ -111,7 +111,7 @@ export async function handleLookup(
         for (const index of indexes) {
           const key = parsed[index]!.key
           // A ref whose key does not name exactly the identity is skipped
-          // rather than widened — a partial key is a predicate over more than
+          // rather than widened: a partial key is a predicate over more than
           // one row, which is the bug `validateKey` refuses for a write and
           // there is no reason to accept it for a read.
           if (cols.some(col => !(col in key))) continue
@@ -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),
   )
 }