@bakery-framework/orm 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/orm",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Bakery database layer: adapters, query builder, schema sync and backup.",
   "keywords": [
     "bakery",

package/src/sync/builder.ts

@@ -106,7 +106,6 @@ export class SchemaBuilder {
     const nul = cons.nullable ?? false
 
     const hasDefault = def !== undefined && def !== null && def !== 'NULL'
-    const isExplicitNull = def === null || def === 'NULL' || (!isView && nul)
 
     if (hasDefault) {
       const isStr = typeof def === 'string'
@@ -119,7 +118,22 @@ export class SchemaBuilder {
           : String(def)
     }
 
-    if (isExplicitNull) return 'null'
+    // **A null default is only spellable on a nullable column**, and conflating
+    // the two turned every NOT NULL column without a default into a nullable
+    // one. `Field`'s convention — stated in `asFieldCall` below — is that a null
+    // default *means* nullable, so `Field.Int(null)` does not describe
+    // `author_id integer NOT NULL`; it redefines it.
+    //
+    // Introspection is not the problem and reports this correctly: a NOT NULL
+    // column with no default comes back as `{type, default: null}` with no
+    // `nullable` key, and a genuinely nullable one carries `nullable: true`.
+    // This function was reading only the default and ignoring the flag beside
+    // it, so `--choose=db` on a real database produced a schema whose very next
+    // sync proposed rebuilding the table it had just been generated from.
+    if (!isView && nul) return 'null'
+    // A view has no NOT NULL to speak of, so there the null-ish default is all
+    // there is to go on.
+    if (isView && (def === null || def === 'NULL')) return 'null'
     return undefined
   }
 
@@ -163,7 +177,83 @@ export class SchemaBuilder {
     if (n) parts.push('nullable: true')
     if (a) parts.push('autoIncrement: true')
     if (p) parts.push('primary: true')
-    return `${indent}${colName}: { ${parts.join(', ')} },\n`
+    if (cons._references) {
+      const r = cons._references
+      const opts = [`table: '${r.table}'`, `column: '${r.column}'`]
+      if (r.onDelete) opts.push(`onDelete: '${r.onDelete}'`)
+      if (r.onUpdate) opts.push(`onUpdate: '${r.onUpdate}'`)
+      parts.push(`_references: { ${opts.join(', ')} }`)
+    }
+    // `as const`, and without it the folder layout loses these columns' types.
+    //
+    // `table()` takes `C extends ColumnMap`, which is `Record<string, unknown>`
+    // — a constraint that does not preserve literals, so `{ type: 'integer' }`
+    // widens to `{ type: string }` and `InferSchema` has no `'integer'` left to
+    // match. Every column the `Field` vocabulary cannot name — which since
+    // foreign keys round-trip includes *every referencing column* — then infers
+    // as a string.
+    //
+    // Invisible in the single-file layout, where `DBInfo.constraints` is already
+    // `as const`, and that is why it took a real app on the folder layout to
+    // surface: 28 errors of the form `number is not assignable to string` on
+    // inserts into tables whose foreign keys are integers.
+    return `${indent}${colName}: { ${parts.join(', ')} } as const,\n`
+  }
+
+  /**
+   * Copy introspected foreign keys onto the columns that carry them.
+   *
+   * `getConstraints()` describes columns and `getForeignKeys()` describes
+   * references, and the generator only ever read the first — so a database whose
+   * `posts.author_id` references `users.id ON DELETE CASCADE` regenerated as a
+   * plain integer. The constraint stayed in the database, the schema stopped
+   * mentioning it, and the next sync therefore planned to rebuild the table to
+   * *remove* a key nobody asked to remove.
+   *
+   * Single-column keys only. A composite key cannot be a property of one column
+   * — it is declared with `foreign()` alongside the indexes — and inventing a
+   * per-column half of one would be worse than omitting it, so it is counted and
+   * reported rather than silently dropped.
+   */
+  private static attachReferences(
+    constraints: Record<string, any>,
+    fks: SyncTypes.DBForeignKeys,
+  ): { attached: number; composite: number } {
+    let attached = 0
+    let composite = 0
+
+    for (const fk of Object.values(fks)) {
+      if (fk.cols.length !== 1 || fk.refCols.length !== 1) {
+        composite++
+        continue
+      }
+      // Introspection reports SQL identifiers; the constraints map is keyed the
+      // way the schema declares them.
+      const table = Object.keys(constraints).find(
+        t => Case.camel(t) === Case.camel(fk.table),
+      )
+      const cols = table ? constraints[table] : undefined
+      if (!cols) continue
+
+      const col = Object.keys(cols).find(
+        c => Case.camel(c) === Case.camel(fk.cols[0]),
+      )
+      if (!col) continue
+
+      cols[col]._references = {
+        table: fk.refTable,
+        column: fk.refCols[0],
+        ...(fk.onDelete && fk.onDelete !== 'NO ACTION'
+          ? { onDelete: fk.onDelete }
+          : {}),
+        ...(fk.onUpdate && fk.onUpdate !== 'NO ACTION'
+          ? { onUpdate: fk.onUpdate }
+          : {}),
+      }
+      attached++
+    }
+
+    return { attached, composite }
   }
 
   /**
@@ -186,6 +276,13 @@ export class SchemaBuilder {
     nullable: boolean,
   ): string | null {
     if (cons.primary || cons.autoIncrement) return null
+    // A referencing column has no `Field.*` spelling that also carries the
+    // reference — `Field.Foreign` needs the parent table's column *value* in
+    // scope, which the generated file cannot guarantee (introspection order is
+    // not declaration order, and the single-file layout has no table values at
+    // all). Fall through to the object literal, which spells `_references`
+    // exactly as the loader reads it.
+    if (cons._references) return null
     const hasLen = typeof cons.length === 'number'
     // `undefined` from getDefaultValue means "no default", which is a different
     // column from one defaulting to null.
@@ -354,6 +451,39 @@ ${body}`
     return `${result}  } as const;\n`
   }
 
+  /**
+   * `orm/indexes.ts`: one exported declaration per index in the database.
+   *
+   * The folder layout's counterpart to the `indexes` block `DBInfo` carries, and
+   * the reason a regenerated folder schema no longer arms the next sync to drop
+   * every index it just read.
+   */
+  private static buildIndexModule(dbIndexes: Record<string, any>): string {
+    let body = ''
+    for (const [idxName, idx] of Object.entries(dbIndexes)) {
+      const cols =
+        idx.cols.length === 1
+          ? `'${idx.cols[0]}'`
+          : `[${idx.cols.map((c: string) => `'${c}'`).join(', ')}]`
+      const fn = idx.type === 'unique' ? 'Field.Unique' : 'Field.Index'
+      body += `export const ${Case.camel(idxName)} = ${fn}('${idx.table}', ${cols})\n`
+    }
+
+    return `/**
+ * Generated from the database by \`db:sync\`.
+ *
+ * Seeded once and never overwritten — unlike \`tables.ts\`. An index this file
+ * does not declare is dropped by the next TS-wins sync, so add new ones here
+ * rather than only in the database.
+ *
+ * Composite foreign keys belong here too, declared with \`foreign()\`: a
+ * reference on a single column cannot express them.
+ */
+import { Field } from '@bakery-framework/orm'
+
+${body}`
+  }
+
   private static buildIndexesString(dbIndexes: Record<string, any>): string {
     let result = '{\n'
     for (const [idxName, idx] of Object.entries(dbIndexes)) {
@@ -388,12 +518,106 @@ ${body}`
    * 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`.
+   *
+   * Introspection reports SQL identifiers while the constraints map is keyed the
+   * way the schema declares them, so the two are compared through `Case.camel`.
+   */
+  private static tableKeyFor(
+    constraints: Record<string, any>,
+    sqlName: string,
+  ): string | undefined {
+    return Object.keys(constraints).find(
+      k => Case.camel(k) === Case.camel(sqlName),
+    )
+  }
+
+  /**
+   * Table names ordered so every table follows the ones it references.
+   *
+   * A depth-first walk with a visiting set, which is also the cycle break: a
+   * table already on the stack is left where it is, and the column pointing back
+   * at it falls through to the object literal — correct, just not pretty.
+   * Circular references between tables are legal SQL and this must not fail on
+   * them or, worse, emit a forward reference that is `undefined` at module
+   * evaluation.
+   */
+  private static tablesParentsFirst(
+    constraints: Record<string, any>,
+  ): string[] {
+    const order: string[] = []
+    const done = new Set<string>()
+    const visiting = new Set<string>()
+
+    const visit = (name: string) => {
+      if (done.has(name) || visiting.has(name)) return
+      visiting.add(name)
+
+      const cols = constraints[name]
+      if (cols && !cols._view) {
+        for (const cons of Object.values<any>(cols)) {
+          const parent = cons?._references?.table
+          if (!parent) continue
+          const key = SchemaBuilder.tableKeyFor(constraints, parent)
+          if (key && key !== name) visit(key)
+        }
+      }
+
+      visiting.delete(name)
+      done.add(name)
+      order.push(name)
+    }
+
+    for (const name of Object.keys(constraints)) visit(name)
+    return order
+  }
+
+  /**
+   * `Field.Foreign(parent.column, …)` when the parent is already in scope.
+   *
+   * Returns null when it is not — the cycle case above — so the caller falls
+   * back to the literal rather than emitting a reference to a `const` declared
+   * further down the file, which is a TDZ error at import time.
+   */
+  private static asForeignCall(
+    cons: any,
+    constraints: Record<string, any>,
+    declared: Set<string>,
+  ): string | null {
+    const ref = cons?._references
+    if (!ref) return null
+
+    const key = SchemaBuilder.tableKeyFor(constraints, ref.table)
+    if (!key || !declared.has(key)) return null
+
+    const opts: string[] = []
+    // The literal form spells nullability as `nullable: true, default: null`;
+    // `Field.Foreign` takes the one flag and writes both.
+    if (cons.nullable) opts.push('nullable: true')
+    if (ref.onDelete) opts.push(`onDelete: '${ref.onDelete}'`)
+    if (ref.onUpdate) opts.push(`onUpdate: '${ref.onUpdate}'`)
+
+    const target = `${exportNameFor(key)}.${ref.column}`
+    return opts.length
+      ? `Field.Foreign(${target}, { ${opts.join(', ')} })`
+      : `Field.Foreign(${target})`
+  }
+
   private static buildTableModule(
     constraints: Record<string, any>,
     adapter: SQLAdapter,
   ): string {
+    // Parents before children, so a referencing column can name the table value
+    // it points at. `Field.Foreign(sections.id)` is the form a person writes and
+    // the one the scaffolder's own template uses; the alternative is the object
+    // literal below, which states the same thing in four times the width.
+    const order = SchemaBuilder.tablesParentsFirst(constraints)
+    const declared = new Set<string>()
+
     let body = ''
-    for (const [tableName, cols] of Object.entries(constraints)) {
+    for (const tableName of order) {
+      const cols = constraints[tableName]
       // Views are left to `views.ts`, exactly as indexes are left to
       // `indexes.ts`. This file is the only one the generator owns; emitting a
       // view here as well would leave the same declaration in two files after
@@ -404,15 +628,19 @@ ${body}`
       for (const [colName, cons] of Object.entries(
         cols as Record<string, SyncTypes.ColumnConstraint>,
       )) {
-        colsStr += SchemaBuilder.formatColumnConstraint(
-          colName,
-          cons,
-          adapter,
-          // Never a view here — those were skipped above.
-          false,
-          '  ',
-        )
+        const ref = SchemaBuilder.asForeignCall(cons, constraints, declared)
+        colsStr += ref
+          ? `  ${colName}: ${ref},\n`
+          : SchemaBuilder.formatColumnConstraint(
+              colName,
+              cons,
+              adapter,
+              // Never a view here — those were skipped above.
+              false,
+              '  ',
+            )
       }
+      declared.add(tableName)
       body += `export const ${exportNameFor(tableName)} = table('${tableName}', {\n${colsStr}})\n\n`
     }
 
@@ -517,6 +745,16 @@ declare module '@bakery-framework/orm/schema-registry' {
     const { stripLedger } = await import('./ledger')
     const constraints = stripLedger(await adapter.getConstraints())
 
+    // Before nullability is reconciled, so a referencing column is described
+    // completely by the time anything decides how to spell it.
+    const refs = SchemaBuilder.attachReferences(
+      constraints,
+      await adapter.getForeignKeys(),
+    )
+    if (refs.composite) {
+      messages.GEN_COMPOSITE_FK({ count: String(refs.composite) })
+    }
+
     SchemaBuilder.syncNullableConstraints(constraints, existingConstraints)
 
     // The write target and the shape written have to agree. `folder` means
@@ -564,6 +802,25 @@ declare module '@bakery-framework/orm/schema-registry' {
           messages.VIEWS_SEEDED?.({ file: viewsPath })
         }
       }
+
+      // And `indexes.ts`, on the same seed-once terms.
+      //
+      // Nothing wrote this file before, which made the folder layout lossy in a
+      // way the single-file layout is not: `DBInfo` carries an `indexes` block,
+      // so `--choose=db` there round-trips them, while the folder layout left
+      // every index undeclared. A TS-wins sync then drops what the schema does
+      // not mention — so regenerating a folder-layout schema from a database
+      // armed the *next* sync to delete every index in it.
+      const indexes = await adapter.getIndexes()
+      if (Object.keys(indexes).length) {
+        const indexesPath = `${schemaPath.replace(/[^/\\]+$/, '')}indexes.ts`
+        if (await Bun.file(indexesPath).exists()) {
+          messages.INDEXES_KEPT?.({ file: indexesPath })
+        } else {
+          await Bun.write(indexesPath, SchemaBuilder.buildIndexModule(indexes))
+          messages.INDEXES_SEEDED?.({ file: indexesPath })
+        }
+      }
     }
 
     messages.SYNC_SUCCESS()

package/src/sync/engine.ts

@@ -18,6 +18,18 @@ import type * as SyncTypes from './types'
 // prettier-ignore
 export const syncMsgs = {
   GEN_TYPES: 'I Generating types...',
+  // Counted rather than silently dropped: a composite key is not a property of
+  // one column, so the generator cannot spell it — but a reader who is not told
+  // will believe the generated schema is complete.
+  GEN_COMPOSITE_FK:
+    'W %y{count}%* composite foreign key(s) could not be generated as column references — declare them with %yforeign()%* beside the indexes.',
+  INDEXES_SEEDED: 'I Seeded %y{file}%* from the database.',
+  INDEXES_KEPT:
+    'I Left %y{file}%* alone: index declarations are hand-owned once seeded. Delete it and re-run to reseed.',
+  MIGRATE_DONE:
+    'I %gAdopted the existing database%*. No tables were changed; run %ydb:sync%* to confirm nothing is pending.',
+  MIGRATE_NO_LEDGER:
+    'W Schema written, but the ledger could not be recorded — the next sync will diff against live introspection instead.',
   SYNC_SUCCESS: 'I %gschema.ts successfully synced%* to Database!',
   INVALID_SCHEMA: 'W %yschema.ts is invalid or corrupt. Treating as new.%*',
   NO_DBINFO: 'W %yDBInfo namespace not found in schema.ts!%*',
@@ -122,6 +134,28 @@ class SyncSession implements AsyncDisposable {
 export class SyncEngine {
   protected constructor() {}
 
+  /**
+   * Record the adopted database as the schema Bakery last applied.
+   *
+   * Without this, the first sync after an adoption falls back to introspection —
+   * safe, but it withdraws the thing the ledger is for, and enum member changes
+   * only migrate when the diff runs against the ledger.
+   *
+   * Seeded from introspection rather than from the generated file, deliberately:
+   * the ledger's job is to record *what is in the database*, and reading it back
+   * from a file that was itself just derived from the database would add a
+   * lossy hop for no gain.
+   */
+  private static async seedLedger(adapter: SQLAdapter): Promise<void> {
+    const { writeLedger, stripLedger } = await import('./ledger')
+    const wrote = await writeLedger(
+      adapter,
+      stripLedger(await adapter.getConstraints()),
+      await adapter.getIndexes(),
+    )
+    if (!wrote) MESSAGES.MIGRATE_NO_LEDGER()
+  }
+
   private static async checkEmptyConstraints(
     adapter: SQLAdapter,
     constraints: SyncTypes.DBConstraints,
@@ -290,6 +324,30 @@ export class SyncEngine {
   ): Promise<void> {
     const genLocal = (c: any = {}) =>
       SchemaBuilder.generate(adapter, schemaPath, MESSAGES, c, layout)
+
+    // `--migrate` runs before every other branch, and changes no tables.
+    //
+    // It is not `--choose=db` with a nicer name. `--choose=db` sits *after* the
+    // "no changes" early return, so on a database that already matches it does
+    // nothing — which is the common case when adopting one, since the schema
+    // being written is derived from that same database. And it never writes the
+    // ledger, so the first real sync afterwards diffs against introspection
+    // instead: the one place enum changes are invisible.
+    if (process.argv.includes('--migrate')) {
+      // `{}`, not `constraints`: adoption generates from the **database alone**.
+      //
+      // Passing the loaded schema in makes `syncNullableConstraints` reconcile
+      // view column nullability against it, which is right for a regeneration of
+      // a schema you are keeping and wrong for this — the point of `--migrate`
+      // is that the database is the source of truth, and quietly carrying a
+      // detail over from the file being replaced would make the result depend on
+      // what happened to be there.
+      await genLocal({})
+      await SyncEngine.seedLedger(adapter)
+      MESSAGES.MIGRATE_DONE()
+      return
+    }
+
     const isEmpty = await SyncEngine.checkEmptyConstraints(
       adapter,
       constraints,

package/src/sync/index.ts

@@ -14,11 +14,56 @@ const syncMsgs = {
   FOREIGN_UNSUPPORTED:
     '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.',
+    '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_RETIRED:
+    'I Converted to the orm/ folder. The previous %yschema.ts%* was moved to %y{to}%*, not deleted.',
 } as const
 
 const MESSAGES = messageLogger(logger, syncMsgs)
 
+/**
+ * `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
+ * the `declare module` block the ORM runs untyped: every table and column falls
+ * back to `any`.
+ */
+function ormIndexModule(hasViews: boolean, hasIndexes: boolean): string {
+  // Conditional, and it has to be: the generator seeds `views.ts` and
+  // `indexes.ts` only when the database actually has views or indexes, so an
+  // unconditional `export * from './views'` is a module that does not resolve
+  // in every project that has neither.
+  const viewImport = hasViews ? "import * as views from './views'\n" : ''
+  const model = hasViews ? 'typeof tables & typeof views' : 'typeof tables'
+
+  return `import type {
+  InferOptionals,
+  InferSchema,
+  InferViews,
+} from '@bakery-framework/orm'
+import * as tables from './tables'
+${viewImport}
+export * from './tables'
+${hasViews ? "export * from './views'\n" : ''}${hasIndexes ? "export * from './indexes'\n" : ''}
+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.
+declare module '@bakery-framework/orm/schema-registry' {
+  interface SchemaRegistry {
+    schema: {
+      DBSchema: InferSchema<Model>
+      DBOptionals: InferOptionals<Model>
+      Views: InferViews<Model>
+    }
+  }
+}
+`
+}
+
 export class SyncService {
   protected constructor() {}
 
@@ -40,9 +85,13 @@ export class SyncService {
     // 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 [--choose=db|ts] [--dry-run] [--force-sync] [--help]
+Usage: bun run db:sync [--migrate] [--choose=db|ts] [--dry-run] [--force-sync] [--help]
 
 Flags:
+  --migrate       Adopt an existing database: write the schema from what is
+                  already there, creating the orm/ folder if none exists, and
+                  record it so the next sync has nothing to do. Changes no
+                  tables. Use this once, on a database Bakery did not create.
   --choose=db     Generate schema.ts from the database (DB wins)
   --choose=ts     Apply schema.ts to the database (TS wins, default)
   --dry-run       Preview planned changes without applying them
@@ -52,6 +101,66 @@ Flags:
 `)
   }
 
+  /** `--migrate`: adopt what is already in the database. */
+  static migrateRequested(argv: string[] = process.argv.slice(2)): boolean {
+    return argv.includes('--migrate')
+  }
+
+  /**
+   * Write the three files the generator does *not* own, and return the one it
+   * does.
+   *
+   * Only `index.ts`, and that is the whole point of the restraint.
+   *
+   * The first version also wrote empty `views.ts` and `indexes.ts` stubs, which
+   * *broke adoption* in a way that only an end-to-end run showed: the generator
+   * seeds both, but only when the file does not already exist, so the stubs
+   * blocked it. The schema then declared no views and no indexes, and the very
+   * next `db:sync` planned to drop the view and all three indexes it had just
+   * adopted. An adoption path that arms a destructive sync is worse than none.
+   *
+   * `tables.ts` is not written here either: `SchemaBuilder` owns it outright.
+   */
+  static async writeOrmIndex(cwd: string): Promise<void> {
+    const dir = `${cwd}/orm`
+    const indexPath = `${dir}/index.ts`
+    if (await Bun.file(indexPath).exists()) return
+
+    await Bun.write(
+      indexPath,
+      ormIndexModule(
+        await Bun.file(`${dir}/views.ts`).exists(),
+        await Bun.file(`${dir}/indexes.ts`).exists(),
+      ),
+    )
+    MESSAGES.MIGRATE_SCAFFOLDED({ dir: 'orm/' })
+  }
+
+  /**
+   * Move the old single-file `schema.ts` out of the way after a conversion.
+   *
+   * 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
+   * quiet kind of wrong, since it looks like the file still describes the app
+   * while nothing reads it.
+   */
+  static async retireSingleFileSchema(
+    cwd: string,
+    previous: 'folder' | 'file' | 'none',
+  ): Promise<void> {
+    if (previous !== 'file') return
+
+    const from = `${cwd}/schema.ts`
+    const file = Bun.file(from)
+    if (!(await file.exists())) return
+
+    const to = `${cwd}/bakery/backups/schema.pre-migrate.${Date.now()}.ts`
+    await Bun.write(to, await file.text())
+    await file.delete()
+    MESSAGES.MIGRATE_RETIRED({ to: to.slice(cwd.length + 1) })
+  }
+
   static async run() {
     // Before initConfig/initDB/loadSchema: help must not depend on a working
     // connection, a loadable schema, or the absence of a `foreign()`.
@@ -97,12 +206,33 @@ Flags:
       MESSAGES.NO_DBINFO()
     }
 
-    await connection.syncSchema(
-      constraints,
-      tsIndexes,
-      schemaPath,
-      loaded.layout,
-    )
+    // `--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
+    // 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
+    // that already has a schema as to one that does not.
+    const adopting = SyncService.migrateRequested()
+    const layout = adopting ? 'folder' : loaded.layout
+    const targetPath = adopting ? `${process.cwd()}/orm/tables.ts` : schemaPath
+
+    await connection.syncSchema(constraints, tsIndexes, targetPath, layout)
+
+    // After generation, not before: `index.ts` re-exports `views.ts` and
+    // `indexes.ts`, which the generator writes only when the database has views
+    // or indexes to write. Deciding what to import before knowing which files
+    // exist is how the first version produced a barrel pointing at nothing.
+    if (adopting) {
+      await SyncService.writeOrmIndex(process.cwd())
+      await SyncService.retireSingleFileSchema(process.cwd(), loaded.layout)
+    }
+
     await closeDB()
   }
 }