@bakery-framework/orm 2.0.0-alpha.9 → 2.0.0-rc.2

package/src/sync/execute.ts

@@ -37,7 +37,7 @@ async function processTableRebuild(
   // Inline, or the rebuild silently drops every foreign key the table had.
   //
   // A constraint is part of the table definition, so recreating the table
-  // without it removes it — and on SQLite there is no `ALTER` to put one back,
+  // without it removes it, and on SQLite there is no `ALTER` to put one back,
   // which is precisely why the planner turns a foreign-key change into a
   // rebuild. Without this, that plan could never *add* a key: the rebuild it
   // scheduled was the thing dropping them.
@@ -209,12 +209,12 @@ async function rebuildTablesPhase(
  * Drop declared views before any table is rebuilt, where the dialect needs it.
  *
  * A rebuild swaps the table out and back, and two of the three dialects refuse
- * to do that while a view still names the table — SQLite at the rename, Postgres
+ * to do that while a view still names the table: SQLite at the rename, Postgres
  * at the drop. `viewsBlockTableRebuild` carries which, and why; MySQL is the one
  * that does not care and skips this entirely.
  *
  * Views hold no data and `syncViewsAndTablesPhase` recreates every declared one
- * a moment later, so dropping them first costs nothing — it is the same "drop
+ * a moment later, so dropping them first costs nothing: it is the same "drop
  * and recreate" the engine already does when a view's body changes.
  *
  * Only when something is actually being rebuilt: a sync with no rebuilds should
@@ -295,7 +295,7 @@ async function addIndexesPhase(
  * Foreign keys on tables that already existed.
  *
  * Only reachable where the dialect can ALTER one in. SQLite cannot, so its
- * missing keys are handled by scheduling a table rebuild in the planner — the
+ * missing keys are handled by scheduling a table rebuild in the planner: the
  * rebuild recreates the table through `createTable`, which emits them inline.
  */
 async function foreignKeysPhase(
@@ -308,7 +308,7 @@ async function foreignKeysPhase(
   for (const fk of fksToDrop.values()) {
     // Called unconditionally, like every other phase. These two were `?.` for
     // as long as `syncMsgs` did not declare them, which read as "this message
-    // is optional" and was really "this message does not exist" — the optional
+    // is optional" and was really "this message does not exist": the optional
     // call is what let the gap survive: it type-checked, and the proxy turned
     // the miss into an error line at run time instead of a build failure.
     MESSAGES.EXEC_DROP_FK({ table: fk.table, name: fk.name ?? '' })
@@ -375,7 +375,7 @@ export function hasOldWrappers(constraints: SyncTypes.DBConstraints) {
     // and a table-level `_transform` (a function), so `Object.values` really
     // does yield a mixed union and `_oldColumn` really is absent from two of
     // its three members. Reading it off the string or the function gives
-    // `undefined`, which is what this check wants — so the narrowing is
+    // `undefined`, which is what this check wants, so the narrowing is
     // deliberate rather than a lie, and the emitted code is unchanged.
     const cols = Object.values(tObj) as (
       | SyncTypes.ColumnConstraint
@@ -385,7 +385,7 @@ export function hasOldWrappers(constraints: SyncTypes.DBConstraints) {
   })
 }
 
-/** The `foreign()` declarations, normalised into the shape the diff uses. */
+/** The `foreign()` declarations, normalized into the shape the diff uses. */
 export function collectForeignKeys(
   tsIndexes: SyncTypes.DBIndexes,
 ): SyncTypes.DBForeignKeys {
@@ -412,7 +412,7 @@ export function collectForeignKeys(
  * Which foreign keys to add and which to drop.
  *
  * Keyed by the tuple, so a constraint the database named itself still matches
- * the declaration that produced it — including on SQLite, which reports no name
+ * the declaration that produced it, including on SQLite, which reports no name
  * at all.
  */
 export function calculateForeignKeyDiff(
@@ -422,7 +422,7 @@ export function calculateForeignKeyDiff(
   /**
    * Tables that already exist, so a key on a table being *created* is left out.
    *
-   * `CREATE TABLE` emits its foreign keys inline — the only spelling SQLite
+   * `CREATE TABLE` emits its foreign keys inline: the only spelling SQLite
    * has. Counting those as "to add" made MySQL and Postgres ALTER in a
    * constraint that already existed, and made SQLite schedule a rebuild of a
    * table that did not exist yet: a fresh `db:sync` announced
@@ -430,7 +430,7 @@ export function calculateForeignKeyDiff(
    *
    * Phrased as "being created" rather than "already exists" deliberately. The
    * inverse defaults to an *empty* set, which reads as "nothing exists" and so
-   * suppressed every key precisely when the database was new — the case that
+   * suppressed every key precisely when the database was new: the case that
    * exposed this in the first place.
    */
   tablesBeingCreated: Set<string> = new Set(),
@@ -439,7 +439,7 @@ export function calculateForeignKeyDiff(
   const fksToDrop = new Map<string, SyncTypes.ForeignKeyInfo>()
 
   // `NO ACTION` on both sides of the comparison, because that is what every
-  // dialect reports for a key declared without one — so an omitted action and
+  // dialect reports for a key declared without one, so an omitted action and
   // an explicit `NO ACTION` must not read as a difference.
   const act = (a?: string) => a ?? 'NO ACTION'
   const sameActions = (
@@ -456,8 +456,8 @@ export function calculateForeignKeyDiff(
 
     const existing = dbFks[id]
     if (existing) {
-      // Same columns, different behaviour. No dialect alters a referential
-      // action in place, so the constraint is replaced — and the drop carries
+      // Same columns, different behavior. No dialect alters a referential
+      // action in place, so the constraint is replaced, and the drop carries
       // the name the *database* gave it, which is not necessarily the one we
       // would generate for it.
       if (!sameActions(existing, fk)) {
@@ -479,14 +479,14 @@ export function calculateForeignKeyDiff(
  * Table names ordered so a parent is always created before its children.
  *
  * Not cosmetic: a foreign key requires the referenced table to exist, so an
- * unordered CREATE fails outright — verified against Postgres, which answers
+ * unordered CREATE fails outright, verified against Postgres, which answers
  * `relation "o_parent" does not exist`. Dropping runs in reverse for the
  * mirror-image reason.
  *
  * A cycle cannot be ordered at all. Rather than loop forever or drop tables,
  * the remainder is appended in declaration order: the foreign key that closes
- * the cycle then fails loudly at the database, which is the honest outcome —
- * breaking it needs a deferred constraint, which no dialect here spells alike.
+ * the cycle then fails loudly at the database, which is the honest outcome.
+ * Breaking it needs a deferred constraint, which no dialect here spells alike.
  */
 export function orderTablesByDependency(
   tables: string[],

package/src/sync/history.ts

@@ -9,8 +9,8 @@ const logger = new Logger('db-history')
 /**
  * What changed between two applied schemas, by name only.
  *
- * Names, not types — the same restraint `shapesMatch` uses and for the same
- * reason: a type comparison here would need dialect normalisation, which is the
+ * Names, not types: the same restraint `shapesMatch` uses and for the same
+ * reason: a type comparison here would need dialect normalization, which is the
  * thing the ledger exists to avoid depending on. A summary that says "column
  * changed" when a Postgres default merely re-rendered itself would be worse
  * than saying nothing.
@@ -63,7 +63,7 @@ export function isEmptyDiff(d: HistoryDiff): boolean {
   )
 }
 
-/** `applied_at` is stored as whole seconds — see `writeLedger`. */
+/** `applied_at` is stored as whole seconds. See `writeLedger`. */
 export function formatWhen(appliedAt: number): string {
   if (!Number.isFinite(appliedAt) || appliedAt <= 0) return 'unknown'
   return new Date(appliedAt * 1000).toISOString().replace('T', ' ').slice(0, 19)
@@ -102,7 +102,7 @@ export function formatEntry(
   // Only worth saying on rows that predate the payload carrying indexes,
   // because those are exactly the rows `db:rollback` will refuse.
   if (entry.indexes === undefined) {
-    lines.push('      (no index record — written before ledger v2)')
+    lines.push('      (no index record: written before ledger v2)')
   }
   return lines
 }
@@ -115,7 +115,7 @@ export class HistoryService {
   }
 
   static printHelp(): void {
-    // Program output, not a log line — the same call the other commands' usage
+    // Program output, not a log line: the same call the other commands' usage
     // text makes, and one of the two documented `console` exceptions.
     console.log(`
 Usage: bun run db:history

package/src/sync/index.ts

@@ -15,7 +15,7 @@ const syncMsgs = {
     'E %rforeign() is declared but not implemented%*: {names}. No adapter emits FOREIGN KEY DDL, so it would be created as a plain index and then re-diffed on every sync. Use index() on the column and enforce the reference in your application.',
   SCHEMA_NOT_FOUND:
     'E %rConfigured schema path not found%*: {path}. %yschema%* in server.config.ts must name a file or an orm/ folder that exists; remove it to auto-detect. Generating one from the database? Create the (empty) file first, or run %ydb:sync --migrate%*.',
-  MIGRATE_SCAFFOLDED: 'I Created %y{dir}%* — the generator owns tables.ts.',
+  MIGRATE_SCAFFOLDED: 'I Created %y{dir}%*: the generator owns tables.ts.',
   MIGRATE_RETIRED:
     'I Converted to the orm/ folder. The previous %yschema.ts%* was moved to %y{to}%*, not deleted.',
 } as const
@@ -23,7 +23,7 @@ const syncMsgs = {
 const MESSAGES = messageLogger(logger, syncMsgs)
 
 /**
- * `orm/index.ts` — the one file in the folder layout nothing else writes.
+ * `orm/index.ts`: the one file in the folder layout nothing else writes.
  *
  * `tables.ts` belongs to the generator, and `views.ts` / `indexes.ts` are seeded
  * by it. This is the re-export barrel plus the type registration, and without
@@ -50,8 +50,8 @@ ${hasViews ? "export * from './views'\n" : ''}${hasIndexes ? "export * from './i
 type Model = ${model}
 
 // Without this block the ORM still runs, untyped: every table and column falls
-// back to \`any\`. The framework never imports this file at runtime — schema
-// values are loaded by path — so this is purely the type registration.
+// back to \`any\`. The framework never imports this file at runtime (schema
+// values are loaded by path), so this is purely the type registration.
 declare module '@bakery-framework/orm/schema-registry' {
   interface SchemaRegistry {
     schema: {
@@ -72,7 +72,7 @@ export class SyncService {
    *
    * Separated from `run()` so the answer is available before anything is
    * opened. It used to be the last check in `run()`, after `initConfig`,
-   * `initDB`, `loadSchema` and both fatal guards — so the one flag whose whole
+   * `initDB`, `loadSchema` and both fatal guards, so the one flag whose whole
    * job is to explain the others exited 1 on an unreachable database or a
    * single `foreign()` declaration, and creating `bakery/server.db` as a side
    * effect of asking for help.
@@ -82,7 +82,7 @@ export class SyncService {
   }
 
   static printHelp(): void {
-    // CLI usage text goes to stdout verbatim — it is program output, not a
+    // CLI usage text goes to stdout verbatim: it is program output, not a
     // log line, so it deliberately bypasses the structured logger.
     console.log(`
 Usage: bun run db:sync [--migrate] [--choose=db|ts] [--dry-run] [--force-sync] [--help]
@@ -141,7 +141,7 @@ Flags:
    *
    * Moved, never deleted: it goes to `bakery/backups/`, beside the copies the
    * generator already keeps there. `loadSchema` prefers `orm/index.ts`, so a
-   * leftover `schema.ts` would be *ignored* rather than used — which is the
+   * leftover `schema.ts` would be *ignored* rather than used, which is the
    * quiet kind of wrong, since it looks like the file still describes the app
    * while nothing reads it.
    */
@@ -178,7 +178,7 @@ Flags:
 
     // A configured path that does not exist is a config error, not an empty
     // project. Continuing would sync against no schema and then generate a new
-    // one at the wrong location — with the app's real model still sitting
+    // one at the wrong location, with the app's real model still sitting
     // where the typo missed it.
     if (loaded.missing) {
       MESSAGES.SCHEMA_NOT_FOUND({ path: loaded.missing })
@@ -193,12 +193,12 @@ Flags:
     }
 
     // `foreign()` used to abort here, because no adapter emitted FOREIGN KEY
-    // DDL and the declaration would have become a plain index — referential
+    // DDL and the declaration would have become a plain index: referential
     // integrity in appearance only. All three adapters now emit and read back
     // real foreign keys, so the guard is gone.
     //
     // `findUnsupportedForeignKeys` is kept and still exported *from
-    // `sync/load`* — it is what a future adapter without support would use to
+    // `sync/load`*: it is what a future adapter without support would use to
     // refuse rather than pretend. It is no longer imported here, which is the
     // distinction: the function has a reason to exist, the dead import did not.
 
@@ -209,14 +209,14 @@ Flags:
     // `--migrate` on a project with no schema at all creates the folder layout
     // rather than a single `schema.ts`. Adoption is exactly the case where the
     // folder earns its keep: the generator owns `tables.ts` and regenerating it
-    // cannot touch the views, indexes and registration beside it — which for an
+    // cannot touch the views, indexes and registration beside it, which for an
     // adopted database is the difference between re-running the command and
     // hand-restoring what it overwrote.
     // `--migrate` always lands on the folder layout, including from an existing
     // single-file `schema.ts`. It used to convert only from *nothing*, which
     // read as an arbitrary distinction: the reason to prefer the folder is that
     // the generator owns `tables.ts` and cannot touch the views, indexes and
-    // registration beside it — and that is worth exactly as much to a project
+    // registration beside it, and that is worth exactly as much to a project
     // that already has a schema as to one that does not.
     const adopting = SyncService.migrateRequested()
     const layout = adopting ? 'folder' : loaded.layout

package/src/sync/ledger.ts

@@ -16,20 +16,20 @@ import type * as SyncTypes from './types'
  * the table on every single sync.
  *
  * Comparing against what we *wrote down* removes that whole class. Two JSON
- * objects, no dialect spellings, no normalisation — and it can carry things
+ * objects, no dialect spellings, no normalization, and it can carry things
  * introspection cannot report reliably, such as a `VARCHAR` width.
  *
  * **Why it is not simply trusted.** Introspection cannot lie about what exists;
  * a ledger can. If someone alters the database outside Bakery, the ledger is
- * stale, and migrating from a stale premise is worse than a spurious rebuild —
+ * stale, and migrating from a stale premise is worse than a spurious rebuild:
  * it can drop a column somebody added. So the ledger is used only when its
  * *shape* still matches the live database, and shape is checked by comparing
- * table and column names, which needs no normalisation and therefore cannot
+ * table and column names, which needs no normalization and therefore cannot
  * suffer the bugs above. Anything else falls back to introspection.
  *
  * One consequence to know: **MySQL commits DDL implicitly**, so the schema
  * change and the ledger write cannot be one atomic unit there. A crash between
- * them leaves the ledger behind, which the shape check then catches — it fails
+ * them leaves the ledger behind, which the shape check then catches: it fails
  * safe, toward introspection.
  */
 export const LEDGER_TABLE = '__bakery_schema'
@@ -58,7 +58,7 @@ export interface LedgerEntry {
   appliedAt: number
   constraints: SyncTypes.DBConstraints
   /**
-   * Absent on rows written before the payload carried indexes — see
+   * Absent on rows written before the payload carried indexes. See
    * {@link parsePayload}. `undefined` means "not recorded", which is not the
    * same as `{}` ("recorded, and there were none"), and `db:rollback` refuses
    * the difference rather than guessing.
@@ -72,11 +72,11 @@ export interface LedgerEntry {
  * v1 rows are a bare `DBConstraints` object; v2 wraps constraints alongside the
  * indexes that were applied with them. The version is detected by the `v` key
  * rather than by a column, so existing rows keep working with no migration of
- * the migration table — which would be a fine joke and a bad idea.
+ * the migration table, which would be a fine joke and a bad idea.
  *
  * Indexes were missing from v1 because the ledger only ever fed the *diff*,
  * which reads constraints. `db:rollback` replays a stored schema as a target,
- * and a target with no indexes means "drop every index" — so the payload had to
+ * and a target with no indexes means "drop every index", so the payload had to
  * grow before rollback could be honest.
  */
 function parsePayload(
@@ -186,7 +186,7 @@ export async function writeLedger(
  * Every spelling of the ledger's name that can appear in a constraints object.
  *
  * `getConstraints()` camelCases table names, so the table created as
- * `__bakery_schema` comes back as `bakerySchema` — matching only the literal
+ * `__bakery_schema` comes back as `bakerySchema`: matching only the literal
  * name silently stripped nothing, and the ledger showed up in its own diff as
  * a table the schema did not declare. Which then made the shape check fail
  * forever and the ledger never get used at all.
@@ -213,28 +213,28 @@ export function stripLedger(
  * live database?
  *
  * **Names only, deliberately.** Comparing types or defaults here would need the
- * same normalisation the ledger exists to avoid, and a disagreement there is
+ * same normalization the ledger exists to avoid, and a disagreement there is
  * exactly what the ledger is more trustworthy about. Names are names in every
  * dialect, so this check cannot itself be wrong in the way the others were.
  *
  * **But a name has two spellings, and the two sides do not use the same one.**
- * The ledger stores the keys of your TypeScript schema — whatever you passed to
- * `table()` / `view()` — while `getConstraints()` camelCases everything it reads
+ * The ledger stores the keys of your TypeScript schema (whatever you passed to
+ * `table()` / `view()`), while `getConstraints()` camelCases everything it reads
  * back. So a table declared `view('published_posts', …)` is `published_posts` in
  * the ledger and `publishedPosts` from introspection, and this check called that
  * a drifted database: *"tables differ (+publishedPosts; -published_posts)"*, on
- * a database nothing had touched. Permanently — the spellings never converge, so
+ * a database nothing had touched. Permanently: the spellings never converge, so
  * every later sync re-reported it and the ledger was never used again. Every app
  * `bun create bakery` generated hit it on the first `db:sync`, because the
  * generated schema declares exactly that view.
  *
  * The damage is quieter than the warning. Falling back to introspection is
- * *safe*, so nothing breaks loudly — it just silently withdraws the thing the
+ * *safe*, so nothing breaks loudly: it just silently withdraws the thing the
  * ledger is for. Enum member changes, for one, only migrate when the diff runs
  * against the ledger (`plan.ledgerSource === 'ledger'`), so on any such app that
  * feature was inert.
  *
- * Comparing camel-normalised names fixes it at the one place the two spellings
+ * Comparing camel-normalized names fixes it at the one place the two spellings
  * meet. `LEDGER_ALIASES` below is the same bug, found earlier and patched for a
  * single known name; this is the general form of it.
  */
@@ -243,7 +243,7 @@ export function shapesMatch(
   live: SyncTypes.DBConstraints,
 ): { ok: true } | { ok: false; reason: string } {
   const meta = (k: string) => k.startsWith('_')
-  // Compare on the normalised spelling, report the declared one — a diff that
+  // Compare on the normalized spelling, report the declared one: a diff that
   // named tables the reader cannot find in either their schema or their database
   // would trade one confusion for another.
   const namesOf = (o: object) => {
@@ -284,13 +284,13 @@ export function shapesMatch(
  * The ledger stores the keys of your TypeScript schema verbatim; every consumer
  * of "current state" downstream looks tables up by `Case.camel(name)`, because
  * that is what `getConstraints()` produces. Handing the raw ledger to the
- * planner therefore made every lookup miss — `diffViews` asked for
+ * planner therefore made every lookup miss: `diffViews` asked for
  * `publishedPosts`, the ledger held `published_posts`, and a miss reads as "the
  * database does not have this view", so the view was recreated on every single
  * sync. Silent and harmless-looking; a view holds no data, so the only symptom
  * is churn in the log.
  *
- * Normalising on read rather than on write is deliberate: it repairs the ledgers
+ * Normalizing on read rather than on write is deliberate: it repairs the ledgers
  * already written by earlier versions, which a write-side fix could not.
  *
  * Meta keys (`_view`, `_references`, …) are values, not identifiers, and are
@@ -319,7 +319,7 @@ function normalizeLedgerKeys(
  * database, introspection otherwise.
  *
  * Returning the *source* as well as the constraints is what lets the caller say
- * out loud which one it used — a sync that quietly changed its mind about where
+ * out loud which one it used: a sync that quietly changed its mind about where
  * truth lives would be very hard to debug later.
  */
 export async function resolveCurrentState(
@@ -333,8 +333,8 @@ export async function resolveCurrentState(
   const live = stripLedger(await adapter.getConstraints())
   // `--no-ledger`, and it exists because the ledger can be *wrong about types*
   // in a way `shapesMatch` cannot see. That check compares names only, on
-  // purpose — comparing types would need the dialect normalisation the ledger
-  // exists to avoid — so a ledger claiming `VARCHAR(64)` where the column is
+  // purpose (comparing types would need the dialect normalization the ledger
+  // exists to avoid), so a ledger claiming `VARCHAR(64)` where the column is
   // really `TEXT` matches its shape and wins the diff. That happens whenever a
   // sync legitimately concluded "no change needed" and the *rule* it used later
   // got stricter, which is exactly what adding width to the diff did.
@@ -369,8 +369,8 @@ export async function resolveCurrentState(
  * Has the database stopped matching what Bakery last applied?
  *
  * The same comparison {@link resolveCurrentState} makes, exposed on its own so
- * a caller can *report* it. Sync already handles drift correctly — it quietly
- * falls back to introspection — but quietly is the problem: a column added by
+ * a caller can *report* it. Sync already handles drift correctly (it quietly
+ * falls back to introspection), but quietly is the problem: a column added by
  * hand in production is indistinguishable, from the outside, from a normal run.
  * This is how you find out.
  *
@@ -378,7 +378,7 @@ export async function resolveCurrentState(
  * synced is not "drifted"), or the shape still matches.
  *
  * Never throws. It runs at boot, and a database that cannot answer must not be
- * the reason a server fails to start — the sync path will raise anything that
+ * the reason a server fails to start: the sync path will raise anything that
  * genuinely matters.
  */
 export async function detectDrift(

package/src/sync/load.ts

@@ -6,14 +6,14 @@
  * `orm/index.ts`. A single `schema.ts` at the root still works, so nothing
  * has to move.
  *
- * The folder is not only tidier — it separates what the generator owns from
+ * The folder is not only tidier: it separates what the generator owns from
  * what a person wrote. `--choose=db` regenerates tables; with everything in
  * one file it has to rewrite indexes and foreign keys too, and anything
  * hand-authored alongside them is collateral.
  *
  * Both of those are *defaults*, probed in that order from the app's cwd. An
- * app that keeps its model somewhere else — `db/`, `src/database/`, a path
- * shared with another tool — sets `schema` in `server.config.ts` and this
+ * app that keeps its model somewhere else (`db/`, `src/database/`, a path
+ * shared with another tool) sets `schema` in `server.config.ts` and this
  * stops guessing:
  *
  * ```ts
@@ -40,7 +40,7 @@ import type * as SyncTypes from './types'
  * `folder` means `table()` values in `<dir>/schema.ts`, with `<dir>/index.ts`
  * owning the re-exports and the schema registration. `file` and `none` mean the
  * single-file `DBInfo` namespace, which carries its own registration block.
- * Emitting the wrong one is not cosmetic — see `SchemaBuilder.generate`.
+ * Emitting the wrong one is not cosmetic. See `SchemaBuilder.generate`.
  */
 export type SchemaLayout = 'folder' | 'file' | 'none'
 
@@ -53,7 +53,7 @@ export interface LoadedSchema {
    *
    * SQL forbids those. MySQL and Postgres refuse the CREATE outright; SQLite
    * accepts the DDL and then fails *every insert* with `foreign key mismatch`,
-   * naming two tables and nothing else — so the caller aborts on this rather
+   * naming two tables and nothing else, so the caller aborts on this rather
    * than letting it surface at runtime.
    */
   unreferenceable?: string[]
@@ -62,7 +62,7 @@ export interface LoadedSchema {
   layout: SchemaLayout
   /**
    * The path a configured `schema` pointed at that does not exist. Set only
-   * for that case — never when nothing is configured, since absence is a
+   * for that case, never when nothing is configured, since absence is a
    * supported state for the defaults. The caller must abort rather than sync.
    */
   missing?: string
@@ -74,8 +74,8 @@ const CONSTRAINT_TYPES = new Set(['index', 'unique', 'foreign'])
  * Foreign keys are declarable but not implemented, and the failure is nasty:
  * no adapter emits FOREIGN KEY DDL, so a declaration is created as an ordinary
  * index. The next diff then compares `foreign` in TypeScript against `index`
- * in the database, decides to drop and re-add it, and — because index drops
- * count as destructive — aborts the sync. The dev server stops starting, with
+ * in the database, decides to drop and re-add it, and (because index drops
+ * count as destructive) aborts the sync. The dev server stops starting, with
  * nothing pointing at the cause.
  *
  * Failing here converts that into one clear message. The alternative would be
@@ -110,7 +110,7 @@ function collectIndexes(module: Record<string, unknown>) {
  *
  * Takes the whole config object rather than the field so the one place that
  * knows the config's shape is here. `unknown` because core's `AppConfig` does
- * not declare `schema` yet — `defaultConfig` in `core/core/config.ts` is
+ * not declare `schema` yet: `defaultConfig` in `core/core/config.ts` is
  * annotated `Required<AppConfig>`, so declaring the field there forces a
  * default value for it, and there is no single path to give: the default is
  * the *probe*, not a location. Core spreads unknown keys from
@@ -182,7 +182,7 @@ type Resolved =
 /**
  * Turn a configured `schema` value into an entry file and a write target.
  *
- * Relative paths resolve against the app's cwd — the framework's own location
+ * Relative paths resolve against the app's cwd: the framework's own location
  * is irrelevant and, once it is an installed package, meaningless.
  *
  * A directory means the folder layout. So does a path ending in `index.ts`,
@@ -193,13 +193,13 @@ type Resolved =
 /**
  * Where the folder layout's table declarations live.
  *
- * `tables.ts`, beside `views.ts` and `indexes.ts` — one file per kind of
+ * `tables.ts`, beside `views.ts` and `indexes.ts`: one file per kind of
  * declaration, which is the separation the folder layout exists for. It was
  * `schema.ts`, which read oddly next to its siblings and collided with the
  * single-file layout's `schema.ts` in conversation.
  *
- * The old name is still honoured when it is the one on disk. Loading never
- * cared — that goes through `index.ts`'s re-exports, so any filename works —
+ * The old name is still honored when it is the one on disk. Loading never
+ * cared: that goes through `index.ts`'s re-exports, so any filename works,
  * but *generation* writes here, and writing `tables.ts` beside someone's
  * existing `schema.ts` would leave two files declaring the same tables.
  */
@@ -280,8 +280,8 @@ export async function loadSchema(
  * cannot do on its own:
  *
  * 1. **Copies the referenced column's type onto the child.** MySQL rejects a
- *    foreign key whose types do not match exactly — an `INT` child against a
- *    `BIGINT` parent is refused — and the two declarations are usually pages
+ *    foreign key whose types do not match exactly (an `INT` child against a
+ *    `BIGINT` parent is refused), and the two declarations are usually pages
  *    apart. Copying makes the mismatch unrepresentable rather than merely
  *    unlikely. `length` comes along for a `Varchar` key, for the same reason.
  * 2. **Emits the key into the index map**, which is where `collectForeignKeys`
@@ -321,7 +321,7 @@ export function resolveColumnForeignKeys(
 
   for (const [tableName, cols] of Object.entries(constraints)) {
     // A view cannot carry a foreign key, and `view(name, sourceTable, body)`
-    // borrows the source table's columns — `_references` included. Without this
+    // borrows the source table's columns: `_references` included. Without this
     // the view gets a key of its own, which no dialect will create, so every
     // sync plans to add it again: an empty printed plan and a run that never
     // reports a perfectly synced database.

package/src/sync/plan.ts

@@ -30,8 +30,7 @@ export async function buildSyncPlan(
     dbConstraintsForDiff: {},
   }
 
-  // The one place sync decides what "currently" means. Prefers the ledger —
-  // what Bakery last applied — and falls back to introspection whenever the
+  // The one place sync decides what "currently" means. Prefers the ledger (  // what Bakery last applied), and falls back to introspection whenever the
   // ledger no longer describes the same tables and columns. See sync/ledger.ts
   // for why that fallback is the whole safety argument.
   const current = await resolveCurrentState(adapter, {

package/src/sync/rename.ts

@@ -125,7 +125,7 @@ export function handleTableRenames(
   )
   // Views are excluded, not merely absent. `initDbTablesMap` skips `_view`
   // entries, so a view is never in `dbTables` and would look like a table that
-  // still needs creating — on every run, forever. `evaluateChanges` counts
+  // still needs creating: on every run, forever. `evaluateChanges` counts
   // `unmappedTsTables`, so a schema with a view could never report a perfectly
   // synced database. The view phase creates them; this set is about tables.
   plan.unmappedTsTables = new Set(

package/src/sync/rollback.ts

@@ -26,7 +26,7 @@ const rollbackMsgs = {
     'W %ySchema #{id} predates the ledger recording indexes%*, so this rollback leaves indexes exactly as they are. Tables and columns roll back; index changes made since then do not.',
   SCHEMA_REWRITTEN: 'I Rewrote %y{path}%* to match the restored schema.',
   SCHEMA_KEPT:
-    'W %y--keep-schema: schema.ts still describes the newer schema.%* The next %ydb:sync%* — including the one a dev boot runs — will apply it again and undo this rollback. Revert the file yourself, or re-run without the flag.',
+    'W %y--keep-schema: schema.ts still describes the newer schema.%* The next %ydb:sync%* (including the one a dev boot runs) will apply it again and undo this rollback. Revert the file yourself, or re-run without the flag.',
   DONE: 'I %gRollback complete%*.',
 } as const
 
@@ -127,7 +127,7 @@ changes, exactly as db:sync does.
     })
 
     // A v1 row recorded no indexes, and replaying it with an empty index set
-    // would read as "drop every index" — a silent, permanent performance
+    // would read as "drop every index": a silent, permanent performance
     // change dressed up as a rollback. Restoring the *live* indexes instead
     // means the plan contains no index work at all, which is the honest
     // degradation: it does less than asked, and says so.
@@ -163,7 +163,7 @@ changes, exactly as db:sync does.
     // The whole point of the ledger: a rollback is just a sync whose target is
     // a schema we already stored. Backups, the destructive-change prompt,
     // `--dry-run`, `--force-sync` and the new ledger row all come from
-    // `SyncEngine.run` unchanged — there is no second migration path to keep
+    // `SyncEngine.run` unchanged: there is no second migration path to keep
     // correct, which is the only reason this file is as short as it is.
     await SyncEngine.run(
       adapter,

package/src/sync/types.ts

@@ -15,7 +15,7 @@ export interface ColumnConstraint {
    * **Now part of the column diff**, so widening a `Varchar` migrates. This
    * used to say the opposite, and the reason was sound at the time: it needed
    * every adapter to report the width back exactly, and any that did not would
-   * rebuild the table on every sync. That is no longer a guess — all three
+   * rebuild the table on every sync. That is no longer a guess: all three
    * were measured against live servers, and the one real trap (MySQL reporting
    * `character_maximum_length = 65535` for an unsized `TEXT`) is handled in
    * `SQLAdapter.sizedTextLength`.
@@ -25,7 +25,7 @@ export interface ColumnConstraint {
    */
   length?: number
   /**
-   * The permitted values of an enum column — `Field.Enum([...])`.
+   * The permitted values of an enum column: `Field.Enum([...])`.
    *
    * Not part of the column diff, for exactly the reason `length` is not:
    * MySQL reports an ENUM's members back in its own spelling, Postgres reports
@@ -55,13 +55,29 @@ export interface IndexConstraint {
   type: 'index' | 'unique' | 'foreign'
   table: string
   cols: string[]
+  /**
+   * The column names exactly as the database reported them, aligned with
+   * `cols` by position. Introspection always fills this; a TS-declared index
+   * (`Field.Unique`, `Field.Index`) has no database spelling to carry, which
+   * is why it is optional.
+   *
+   * It exists because `Case.snake` is not the inverse of `Case.camel`
+   * (`SKU_code` → `sKUCode` → `s_k_u_code`), so a consumer that needs the raw
+   * spelling (a statement, a display) cannot recover it from `cols` and had
+   * to rebuild a camel→raw map from the schema's column list. That rebuild was
+   * first-wins over collisions: a table holding both `user_id` and `userId`
+   * files them under one camel key, and an index over the *second* resolved to
+   * the first, a predicate over the wrong column. The adapter knows the real
+   * names at parse time; carrying them costs an array.
+   */
+  rawCols?: string[]
   /** Set only when `type` is 'foreign'. */
   refTable?: string
   refCols?: string[]
 }
 
 /**
- * Referential actions, normalised to the SQL spelling.
+ * Referential actions, normalized to the SQL spelling.
  *
  * One vocabulary for three dialects: MySQL and SQLite report these words back
  * verbatim, Postgres reports single characters (`c`, `a`, `r`, `n`, `d`) which
@@ -99,7 +115,7 @@ export interface ForeignKeyInfo {
  *
  * It lives here rather than beside `buildSyncPlan` because `sync/rename.ts` and
  * `sync/diff.ts` both mutate a plan and are both imported *by* the planner. A
- * home in `plan.ts` would make that pair of edges circular — type-only, and so
+ * home in `plan.ts` would make that pair of edges circular: type-only, and so
  * erased under `verbatimModuleSyntax`, but this repo has been bitten by import
  * cycles often enough that not creating one is worth more than the adjacency.
  */