@bakery-framework/orm 1.2.3 → 2.0.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/orm",
-  "version": "1.2.3",
+  "version": "2.0.0-alpha.11",
   "description": "Bakery database layer: adapters, query builder, schema sync and backup.",
   "keywords": [
     "bakery",
@@ -51,9 +51,9 @@
     "!src/tests"
   ],
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   },
   "dependencies": {
-    "@bakery-framework/core": "^1.0.0"
+    "@bakery-framework/core": "^2.0.0-alpha.11"
   }
 }

package/src/adapters/base.ts

@@ -35,10 +35,21 @@ export namespace SQLAdapter {
   }
   export interface TableDetails {
     name: string
-    rowCount: number
+    /**
+     * `null` unless the caller asked for counts. A `COUNT(*)` is a full scan
+     * on SQLite and Postgres, and `getSchema()` is on the write path — every
+     * explorer write introspects to resolve row identity — so the scan is paid
+     * only where a number is actually displayed. `null`, not `0`: a count that
+     * was never taken must not read as an empty table.
+     */
+    rowCount: number | null
     columns: TableColumnInfo[]
     indexes: TableIndexInfo[]
   }
+  export interface SchemaOptions {
+    /** Take the per-table `COUNT(*)`. Off by default — see `rowCount`. */
+    rowCounts?: boolean
+  }
   export interface TableDataResult {
     rows: any[]
     totalRows: number
@@ -534,7 +545,9 @@ export abstract class SQLAdapter {
     ).run()
   }
 
-  abstract getSchema(): Promise<SQLAdapter.TableDetails[]>
+  abstract getSchema(
+    options?: SQLAdapter.SchemaOptions,
+  ): Promise<SQLAdapter.TableDetails[]>
 
   /**
    * Foreign keys as the database has them, keyed by the tuple that identifies
@@ -768,14 +781,6 @@ export abstract class SQLAdapter {
     })
   }
 
-  /**
-   * A `CHECK (col IN (…))` clause restricting a column to a set of values.
-   *
-   * Takes the column name because a CHECK has to name it, which is why
-   * `colDef` grew an optional `column` argument. Values bind nowhere — this is
-   * DDL — so they are quoted the same way `formatDefault` quotes a string
-   * default, by doubling the single quote.
-   */
   /**
    * The declared width of a **sized** text column, or `undefined`.
    *
@@ -804,6 +809,13 @@ export abstract class SQLAdapter {
     return Number.isInteger(n) && n > 0 ? n : undefined
   }
 
+  /**
+   * A `CHECK (col IN (…))` clause restricting a column to a set of values.
+   *
+   * Takes the column name because a CHECK has to name it. Values bind nowhere —
+   * this is DDL — so they are quoted the same way `formatDefault` quotes a
+   * string default, by doubling the single quote.
+   */
   protected enumClause(column: string, values: string[]): string {
     const list = values
       .map(v => `'${String(v).replaceAll("'", "''")}'`)
@@ -850,20 +862,68 @@ export abstract class SQLAdapter {
     return new DatabaseStatement(this, sqlText)
   }
 
+  /**
+   * The `LIKE` escape character — `!`, and deliberately **not** a backslash.
+   *
+   * A backslash is the obvious choice and is still the wrong one. MySQL
+   * processes backslash escapes inside string literals where SQLite and
+   * Postgres do not, so `ESCAPE '\'` would need a per-dialect spelling — and
+   * the whole point of one escape character is one clause for all three.
+   *
+   * The Postgres normalizer used to make this worse: it applied MySQL's rule
+   * to every dialect, so `'\'` swallowed its own closing quote and the driver
+   * reported a syntax error several tokens later. That defect is fixed — the
+   * scanner now has no opinion about backslashes, matching the server — and
+   * `a backslash in a literal is a character, not an escape` pins it. `!` stays
+   * regardless, because MySQL's literal-level escaping is the server's real
+   * behaviour, not a scanner bug, and a character with no meaning to any of the
+   * three parsers needs no capability getter.
+   */
+  protected readonly likeEscape = '!'
+
+  get likeEscapeClause(): string {
+    return ` ESCAPE '${this.likeEscape}'`
+  }
+
+  /**
+   * Make a value match literally under `LIKE`.
+   *
+   * Without this a search for `50%` matches every row and one for `a_b` matches
+   * `axb` — `%` and `_` are the wildcards, and the filter passed user input
+   * through untouched. The escape character itself goes first, or escaping it
+   * afterwards would double the ones this method just added.
+   */
+  protected escapeLike(value: string): string {
+    const e = this.likeEscape
+    return value
+      .split(e)
+      .join(e + e)
+      .replace(/[%_]/g, m => `${e}${m}`)
+  }
+
+  /**
+   * `WHERE` and `ORDER BY` for a browsable table listing.
+   *
+   * A filter is either a **bare scalar**, which means `contains` and is what
+   * every caller sent before operators existed, or **`{op, value}`**. Keeping
+   * the scalar form meaningful is not politeness: `getData` is public and the
+   * dashboard still calls it that way.
+   *
+   * Columns are intersected with the real column set by the caller, so an
+   * unknown column disappears rather than reaching SQL. Values always bind.
+   */
   protected buildFilterSort(
     options: SQLAdapter.FilterSortOptions,
     validCols: Set<string>,
   ) {
     const whereParams: unknown[] = []
-    const whereClauses = Object.entries(options.filters || {})
-      .filter(
-        ([col, val]) =>
-          validCols.has(col) && val !== undefined && val !== null && val !== '',
-      )
-      .map(([col, val]) => {
-        whereParams.push(`%${val}%`)
-        return `${this.quote(col)} LIKE ?`
-      })
+    const whereClauses: string[] = []
+
+    for (const [col, raw] of Object.entries(options.filters || {})) {
+      if (!validCols.has(col)) continue
+      const clause = this.filterClause(col, raw, whereParams)
+      if (clause) whereClauses.push(clause)
+    }
 
     const whereSql = whereClauses.length
       ? ` WHERE ${whereClauses.join(' AND ')}`
@@ -881,6 +941,67 @@ export abstract class SQLAdapter {
     return { whereSql, orderSql, whereParams }
   }
 
+  /**
+   * One filter, as SQL. Returns `null` when the filter says nothing.
+   *
+   * `params` is appended to rather than returned, because an operator may bind
+   * one value, two, or none at all — `IS NULL` has nothing to bind, and
+   * pretending otherwise is how a placeholder count drifts from its arguments.
+   */
+  private filterClause(
+    col: string,
+    raw: unknown,
+    params: unknown[],
+  ): string | null {
+    const quoted = this.quote(col)
+
+    // The pre-operator form. An empty string means "no filter" here, which is
+    // what a cleared text box sends and what every caller has relied on.
+    if (raw === null || raw === undefined || typeof raw !== 'object') {
+      if (raw === undefined || raw === null || raw === '') return null
+      params.push(`%${this.escapeLike(String(raw))}%`)
+      return `${quoted} LIKE ?${this.likeEscapeClause}`
+    }
+
+    const { op, value } = raw as { op?: string; value?: unknown }
+
+    // No value to bind, and none expected — these two are the whole reason a
+    // filter cannot be modelled as a plain column/value pair.
+    if (op === 'null') return `${quoted} IS NULL`
+    if (op === 'notnull') return `${quoted} IS NOT NULL`
+
+    if (value === undefined || value === null) return null
+
+    const comparison: Record<string, string> = {
+      eq: '=',
+      ne: '<>',
+      gt: '>',
+      gte: '>=',
+      lt: '<',
+      lte: '<=',
+    }
+    if (op && comparison[op]) {
+      params.push(value)
+      return `${quoted} ${comparison[op]} ?`
+    }
+
+    const pattern: Record<string, (v: string) => string> = {
+      contains: v => `%${v}%`,
+      starts: v => `${v}%`,
+      ends: v => `%${v}`,
+    }
+    const shape = op ? pattern[op] : undefined
+    if (shape) {
+      params.push(shape(this.escapeLike(String(value))))
+      return `${quoted} LIKE ?${this.likeEscapeClause}`
+    }
+
+    // An operator this dialect does not know is dropped rather than guessed
+    // at. Guessing would mean answering a question nobody asked, and the
+    // caller validates the vocabulary before it gets here.
+    return null
+  }
+
   protected formatDefault(
     def: unknown,
     boolTrue: string,

package/src/adapters/mysql.ts

@@ -270,7 +270,9 @@ export class MySQLAdapter extends SQLAdapter {
     return new MySQLAdapter(sql as SQL)
   }
 
-  async getSchema(): Promise<SQLAdapter.TableDetails[]> {
+  async getSchema(
+    options?: SQLAdapter.SchemaOptions,
+  ): Promise<SQLAdapter.TableDetails[]> {
     const res = (await this.query(
       'SELECT table_name AS name' +
         ' FROM information_schema.tables' +
@@ -280,7 +282,11 @@ export class MySQLAdapter extends SQLAdapter {
     const tablesWithDetails: SQLAdapter.TableDetails[] = []
     for (const t of res) {
       const [countRes, cols, idxs] = (await Promise.all([
-        this.query(`SELECT COUNT(*) as count FROM ${this.quote(t.name)}`).get(),
+        options?.rowCounts
+          ? this.query(
+              `SELECT COUNT(*) as count FROM ${this.quote(t.name)}`,
+            ).get()
+          : null,
         this.query(
           'SELECT column_name AS name, data_type AS type,' +
             ' is_nullable AS is_nullable, column_key AS column_key' +
@@ -293,13 +299,13 @@ export class MySQLAdapter extends SQLAdapter {
             ' FROM information_schema.statistics' +
             ' WHERE table_name = ? AND table_schema = DATABASE()',
         ).all(t.name),
-      ])) as [SQLAdapter.CountRow, any[], any[]]
+      ])) as [SQLAdapter.CountRow | null, any[], any[]]
       const uniqueIdxs = Array.from(
         new Map(idxs.map(i => [i.name, i.non_unique === 0])).entries(),
       ).map(([name, unique]) => ({ name, unique }))
       tablesWithDetails.push({
         name: t.name,
-        rowCount: countRes?.count || 0,
+        rowCount: options?.rowCounts ? countRes?.count || 0 : null,
         columns: cols.map(c => ({
           name: c.name,
           type: c.type,
@@ -505,6 +511,7 @@ export class MySQLAdapter extends SQLAdapter {
           type: info.non_unique === 0 ? 'unique' : 'index',
           table: Case.camel(info.table),
           cols: info.cols.map(Case.camel),
+          rawCols: info.cols,
         },
       ]),
     )

package/src/adapters/pgsql.ts

@@ -60,13 +60,16 @@ export class PGAdapter extends SQLAdapter {
     nextChar: string | undefined,
     state: PGSQLParserState,
   ): string | null {
-    if (char === '\\') {
-      if ((state.inSingleQuote || state.inDoubleQuote) && nextChar) {
-        state.skipNext = true
-        return `\\${nextChar}`
-      }
-      return char
-    }
+    // No backslash branch, deliberately. Postgres with
+    // `standard_conforming_strings` — the server default since 9.1, and what
+    // every connection here runs under — treats a backslash inside a `'…'`
+    // literal as an ordinary character. This scanner used to apply MySQL's
+    // rule instead: `\` consumed the next character, so the `'` closing a
+    // `'\'` literal was eaten, the scanner stayed "inside" a literal the
+    // server had already closed, and every `?` after it was left unrewritten —
+    // which is how `ESCAPE '\'` produced a syntax error several tokens
+    // downstream. The server's parse is the only one that matters; the scanner
+    // now agrees with it by having no opinion about backslashes at all.
     if (char === '`') {
       return !state.inSingleQuote && !state.inDoubleQuote ? '"' : char
     }
@@ -246,57 +249,73 @@ export class PGAdapter extends SQLAdapter {
     return new PGAdapter(sql as SQL)
   }
 
-  async getSchema(): Promise<SQLAdapter.TableDetails[]> {
+  async getSchema(
+    options?: SQLAdapter.SchemaOptions,
+  ): Promise<SQLAdapter.TableDetails[]> {
     const res = (await this.query(
       'SELECT table_name AS name, table_type AS type' +
         ' FROM information_schema.tables' +
         " WHERE table_schema NOT IN ('pg_catalog', 'information_schema')" +
         ' ORDER BY table_name',
     ).all()) as any[]
-    const tablesWithDetails: SQLAdapter.TableDetails[] = []
-
-    for (const t of res) {
-      const qName = this.quote(t.name)
-      const [countRes, cols, pkCols, idxs] = (await Promise.all([
-        this.query(`SELECT COUNT(*)::int as count FROM ${qName}`).get(),
-        this.query(
-          'SELECT column_name AS name, data_type AS type,' +
-            ' is_nullable AS is_nullable' +
-            ' FROM information_schema.columns' +
-            ' WHERE table_name = ?' +
-            " AND table_schema NOT IN ('pg_catalog', 'information_schema')" +
-            ' ORDER BY ordinal_position',
-        ).all(t.name),
-        this.query(
-          'SELECT a.attname AS name' +
-            ' FROM pg_index i' +
-            ' JOIN pg_attribute a ON a.attrelid = i.indrelid' +
-            ' AND a.attnum = ANY(i.indkey)' +
-            ` WHERE i.indisprimary AND i.indrelid = ${qName}::regclass`,
-        ).all(),
-        this.query(
-          'SELECT indexname AS name, indexdef AS def' +
-            ' FROM pg_indexes' +
-            " WHERE schemaname NOT IN ('pg_catalog', 'information_schema')" +
-            ' AND tablename = ?',
-        ).all(t.name),
-      ])) as [SQLAdapter.CountRow, any[], any[], any[]]
-      tablesWithDetails.push({
-        name: t.name,
-        rowCount: countRes?.count || 0,
-        columns: cols.map(c => ({
-          name: c.name,
-          type: c.type,
-          notnull: c.is_nullable === 'NO',
-          pk: pkCols.some(pk => pk.name === c.name),
-        })),
-        indexes: idxs.map(i => ({
-          name: i.name,
-          unique: /UNIQUE/i.test(i.def),
-        })),
-      })
-    }
-    return tablesWithDetails
+    // One wave rather than N. The four queries per table were already
+    // concurrent; the loop around them awaited each table in turn, so a
+    // 20-table schema cost 20 sequential round-trip waves. See the note in
+    // sqlite.ts about the COUNT(*), which is a full scan here too.
+    return await Promise.all(
+      res.map(async t => {
+        const qName = this.quote(t.name)
+        const [countRes, cols, pkCols, idxs] = (await Promise.all([
+          options?.rowCounts
+            ? this.query(`SELECT COUNT(*)::int as count FROM ${qName}`).get()
+            : null,
+          this.query(
+            'SELECT column_name AS name, data_type AS type,' +
+              ' is_nullable AS is_nullable' +
+              ' FROM information_schema.columns' +
+              ' WHERE table_name = ?' +
+              " AND table_schema NOT IN ('pg_catalog', 'information_schema')" +
+              ' ORDER BY ordinal_position',
+          ).all(t.name),
+          // `::regclass` casts a **string**, so the table name binds as a
+          // parameter. It used to interpolate `qName` — a double-quoted
+          // *identifier* — which Postgres reads as a column reference, so this
+          // threw `column "<table>" does not exist` for every table and took the
+          // whole of `getSchema()` down with it on this dialect.
+          //
+          // The quiet case was worse than the loud one: a table with a column of
+          // the same name resolved, casting that column's *value* to a regclass
+          // and reporting some other table's primary key as this one's.
+          this.query(
+            'SELECT a.attname AS name' +
+              ' FROM pg_index i' +
+              ' JOIN pg_attribute a ON a.attrelid = i.indrelid' +
+              ' AND a.attnum = ANY(i.indkey)' +
+              ' WHERE i.indisprimary AND i.indrelid = ?::regclass',
+          ).all(t.name),
+          this.query(
+            'SELECT indexname AS name, indexdef AS def' +
+              ' FROM pg_indexes' +
+              " WHERE schemaname NOT IN ('pg_catalog', 'information_schema')" +
+              ' AND tablename = ?',
+          ).all(t.name),
+        ])) as [SQLAdapter.CountRow | null, any[], any[], any[]]
+        return {
+          name: t.name,
+          rowCount: options?.rowCounts ? countRes?.count || 0 : null,
+          columns: cols.map(c => ({
+            name: c.name,
+            type: c.type,
+            notnull: c.is_nullable === 'NO',
+            pk: pkCols.some(pk => pk.name === c.name),
+          })),
+          indexes: idxs.map(i => ({
+            name: i.name,
+            unique: /UNIQUE/i.test(i.def),
+          })),
+        }
+      }),
+    )
   }
 
   async getData(
@@ -461,14 +480,14 @@ export class PGAdapter extends SQLAdapter {
       )
         continue
       const m = r.indexdef.match(/\(([^)]+)\)/)
+      const raw: string[] = m
+        ? m[1].split(',').map((c: string) => c.trim().replace(/"/g, ''))
+        : []
       dbIndexes[Case.camel(r.indexname)] = {
         type: /UNIQUE/i.test(r.indexdef) ? 'unique' : 'index',
         table: Case.camel(r.tablename),
-        cols: m
-          ? m[1]
-              .split(',')
-              .map((c: string) => Case.camel(c.trim().replace(/"/g, '')))
-          : [],
+        cols: raw.map(Case.camel),
+        rawCols: raw,
       }
     }
     return dbIndexes

package/src/adapters/sqlite.ts

@@ -282,34 +282,58 @@ export class SQLiteAdapter extends SQLAdapter {
     return new SQLiteAdapter(this.filename, sql as SQL)
   }
 
-  async getSchema(): Promise<SQLAdapter.TableDetails[]> {
+  async getSchema(
+    options?: SQLAdapter.SchemaOptions,
+  ): Promise<SQLAdapter.TableDetails[]> {
     const res = (await this.query(
       'SELECT name FROM sqlite_master' +
         " WHERE type='table' AND name NOT LIKE 'sqlite_%'",
     ).all()) as SQLAdapter.NameRow[]
-    const tablesWithDetails: SQLAdapter.TableDetails[] = []
-    for (const t of res) {
-      const tableName = this.quote(t.name)
-
-      const [countRes, cols, idxs] = (await Promise.all([
-        this.query(`SELECT COUNT(*) as count FROM ${tableName}`).get(),
-        this.query(`PRAGMA table_info(${tableName})`).all(),
-        this.query(`PRAGMA index_list(${tableName})`).all(),
-      ])) as [SQLAdapter.CountRow, any[], any[]]
-
-      tablesWithDetails.push({
-        name: t.name,
-        rowCount: countRes?.count || 0,
-        columns: cols.map(c => ({
-          name: c.name,
-          type: c.type,
-          notnull: c.notnull === 1,
-          pk: c.pk === 1,
-        })),
-        indexes: idxs.map(i => ({ name: i.name, unique: i.unique === 1 })),
-      })
-    }
-    return tablesWithDetails
+    // Per table rather than per wave: the three queries below were already
+    // concurrent, but the loop around them awaited each table in turn, so a
+    // 20-table schema cost 20 sequential round-trip waves. They share nothing,
+    // so the whole fan-out is one wave now.
+    //
+    // The `COUNT(*)` is a full scan on this dialect and on Postgres, so it is
+    // opt-in: only a schema *listing* displays the number, and `getSchema()`
+    // also sits on the explorer's write path, where a count nobody shows cost
+    // a scan of every table per write.
+    return await Promise.all(
+      res.map(async t => {
+        const tableName = this.quote(t.name)
+
+        const [countRes, cols, idxs] = (await Promise.all([
+          options?.rowCounts
+            ? this.query(`SELECT COUNT(*) as count FROM ${tableName}`).get()
+            : null,
+          this.query(`PRAGMA table_info(${tableName})`).all(),
+          this.query(`PRAGMA index_list(${tableName})`).all(),
+        ])) as [SQLAdapter.CountRow | null, any[], any[]]
+
+        return {
+          name: t.name,
+          rowCount: options?.rowCounts ? countRes?.count || 0 : null,
+          columns: cols.map(c => ({
+            name: c.name,
+            type: c.type,
+            notnull: c.notnull === 1,
+            // `pk` is the column's **1-based position within the primary key**,
+            // not a boolean — `PRAGMA table_info` reports 0 for "not part of the
+            // key", 1 for the first key column, 2 for the second. So `=== 1`
+            // reported a composite `PRIMARY KEY (a, b)` as a single-column key on
+            // `a`, silently, and only on SQLite: MySQL reads `column_key = 'PRI'`
+            // and Postgres reads `pg_index.indisprimary`, both of which are set on
+            // every member.
+            //
+            // `parseConstraints` a few hundred lines down already had this right
+            // (`col.pk > 0`), which is why `getConstraints()` disagreed with
+            // `getSchema()` about the same table.
+            pk: c.pk > 0,
+          })),
+          indexes: idxs.map(i => ({ name: i.name, unique: i.unique === 1 })),
+        }
+      }),
+    )
   }
 
   async getData(
@@ -484,18 +508,22 @@ export class SQLiteAdapter extends SQLAdapter {
     ).all()) as any[]
     return Object.fromEntries(
       await Promise.all(
-        indexes.map(async idx => [
-          Case.camel(idx.name),
-          {
-            type: idx.sql.toUpperCase().includes('UNIQUE') ? 'unique' : 'index',
-            table: Case.camel(idx.tbl_name),
-            cols: (
-              (await this.query(
-                `PRAGMA index_info('${idx.name}')`,
-              ).all()) as any[]
-            ).map(c => Case.camel(c.name)),
-          },
-        ]),
+        indexes.map(async idx => {
+          const raw = (
+            (await this.query(`PRAGMA index_info('${idx.name}')`).all()) as any[]
+          ).map(c => String(c.name))
+          return [
+            Case.camel(idx.name),
+            {
+              type: idx.sql.toUpperCase().includes('UNIQUE')
+                ? 'unique'
+                : 'index',
+              table: Case.camel(idx.tbl_name),
+              cols: raw.map(Case.camel),
+              rawCols: raw,
+            },
+          ]
+        }),
       ),
     )
   }

package/src/orm/index.ts

@@ -12,9 +12,8 @@
  * `TypeError: undefined is not an object (evaluating 'Mutation.Insert')`.
  *
  * Biome's `organizeImports` sorts these alphabetically and puts `./mutation`
- * first. That happened during the 2026-08-09 sweep and cost 12 tests; the
- * compiler cannot see it, because the types are fine either way. Hence the
- * suppression.
+ * first. The compiler cannot see the breakage, because the types are fine
+ * either way. Hence the suppression.
  */
 // biome-ignore-all assist/source/organizeImports: cycle — see above
 import { DB } from './query'

package/src/orm/query.ts

@@ -1072,6 +1072,16 @@ export namespace DB {
     if (op === 'IS NULL' || op === 'IS NOT NULL') {
       return `${left} ${op}`
     }
+    // A bound NULL can never satisfy `=` or `<>` — three-valued logic makes
+    // both comparisons UNKNOWN for every row, so `where(col, null)` silently
+    // matched nothing while cheerfully reporting success. The caller who
+    // passes an explicit null means the SQL spelling of it. Only literal
+    // values: a column reference on the right is a different comparison and
+    // is left alone.
+    if (rightArg === null && !isRightColumn) {
+      if (op === '=') return `${left} IS NULL`
+      if (op === '!=' || op === '<>') return `${left} IS NOT NULL`
+    }
     if (op === 'BETWEEN' && Array.isArray(rightArg)) {
       const min = evalOperands(rightArg[0], params, false)
       const max = evalOperands(rightArg[1], params, false)

package/src/schema-registry.ts

@@ -36,18 +36,15 @@ import type { MapOf } from '@bakery-framework/core/types'
 
 // Augmented by the app; empty until then.
 //
-// **It has to be an `interface`, and the empty body is the point.** Biome's
 // **`interface`, not `type`, and the empty body is the point.** A type alias
 // cannot be declaration-merged, so rewriting this to `type X = {}` turns every
 // app's `declare module '@bakery-framework/orm/schema-registry'` into
 // `TS2300: Duplicate identifier` and the whole schema registry stops working.
 //
-// Biome's `noBannedTypes` proposed exactly that rewrite and called it a safe
-// fix; the 2026-08-09 sweep applied it and `bun run typecheck` was the only
-// thing that caught it. That rule is off repo-wide now — it had no true
-// positives here — but `noEmptyInterface` reaches the same construct and
-// offers the same fix, so the suppression stays. The compiler is the real
-// guard: change this line and `apps/starter` fails to typecheck.
+// Biome's `noBannedTypes` proposes exactly that rewrite and calls it a safe
+// fix. That rule is off repo-wide now, but `noEmptyInterface` reaches the same
+// construct and offers the same fix, so the suppression stays. The compiler is
+// the real guard: change this line and `apps/starter` fails to typecheck.
 // biome-ignore lint/suspicious/noEmptyInterface: must stay mergeable — above
 export interface SchemaRegistry {}
 

package/src/sync/builder.ts

@@ -503,21 +503,6 @@ ${body}`
     return `${result}  } as const;\n`
   }
 
-  /**
-   * The `orm/` folder layout's `schema.ts`: `table()` values and nothing else.
-   *
-   * The generator only ever emitted the `DBInfo` namespace, and for a folder
-   * project the write target is `orm/schema.ts` — which `orm/index.ts`
-   * re-exports. So a regeneration replaced every `table()` with a namespace
-   * *and* added a second `declare module '@bakery-framework/orm/schema-registry'` block
-   * colliding with the one in `index.ts`. It fired on `--choose=db` and, less
-   * visibly, after any sync involving `old()` wrappers.
-   *
-   * Tables only, deliberately: `index.ts` owns the re-exports and the schema
-   * registration, `indexes.ts` owns the index and unique declarations, and
-   * neither is the generator's to rewrite. That separation is the reason the
-   * folder layout exists (see `load.ts`).
-   */
   /**
    * The constraints key a `_references.table` names, or `undefined`.
    *
@@ -604,6 +589,16 @@ ${body}`
       : `Field.Foreign(${target})`
   }
 
+  /**
+   * The `orm/` folder layout's `schema.ts`: `table()` values and nothing else.
+   *
+   * Tables only, deliberately: `index.ts` owns the re-exports and the schema
+   * registration, `indexes.ts` owns the index and unique declarations, and
+   * neither is the generator's to rewrite. Emitting the single-file `DBInfo`
+   * namespace here instead would clobber both and leave two colliding
+   * `declare module '@bakery-framework/orm/schema-registry'` blocks. That
+   * separation is the reason the folder layout exists (see `load.ts`).
+   */
   private static buildTableModule(
     constraints: Record<string, any>,
     adapter: SQLAdapter,