@@ -7,6 +7,36 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed — `dbImport` was demanded from the model, and blocked an upgrade nobody saw fail
+
+`#194` made `dialect` and `dbImport` optional config, then required both from any model
+declaring a `source.rdb`. `dialect` belongs there: every sourced object is lowered to SQL, so a
+wrong default is silently wrong everywhere. **`dbImport` does not.** Only a generator emitting
+`import { db } from …` can read it, and a project whose generated queries take `db` as an
+explicit parameter — the shape the scaffolded `queriesFile()` emits — has no singleton to name.
+Such a project was refused, and told its model "generates database code for: …" that in fact
+imported nothing.
+
+**What that cost, measured on the public reference app.** Its automated dependency PR
+(`0.20.11` → `0.21.6`) had been failing since **15 August**, twelve days, on exactly this:
+
+```
+meta: verify --codegen: regeneration failed: codegen config is missing dbImport —
+  required because this model generates database code for: CouncilTurn, Council.
+##[error]Process completed with exit code 1
+```
+
+The remedy is one config line, which no bot can write — so the app sat four minor lines behind
+with a red PR nobody reads, while every human-facing signal said it was healthy. When the
+upgrade was finally done by hand it took that one line and two generated deltas.
+
+`dbImport` is now demanded at the point of **use**: reading it is what proves a generator emits
+the import, so reading is what asks for it, and the runner's existing `[<generator>]` wrapper
+names which one. A generator that never touches it never demands it. Declaration is *tracked*,
+never inferred by comparing against the default — `meta init` scaffolds a relative path and a
+project may legitimately write the default's own string. Verified against the reference app:
+published `0.24.2` fails, this build emits all 29 files byte-identically.
+
 ### Fixed — `meta verify --codegen` convicted files MetaObjects never wrote
 
 Found by re-running the documented TypeScript quickstart cold against published `0.24.2`, as a
 
@@ -242,32 +242,42 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   }
 
   // #194 — dbImport / dialect are optional config, BUT a model that declares a
-  // source.rdb genuinely needs them. Only a sourced object emits database
+  // source.rdb genuinely needs `dialect`. Only a sourced object emits database
   // artifacts (schema / query / route code), and every generator below gates
   // that emission on hasAnyRdbSource — the #248 R2 source-based predicate — so a
   // sourceless object (a value object, or a sourceless projection) emits zero DB
   // code. Guard BEFORE normalizeConfig fills its inert defaults, so a DB project
-  // that forgot either gets a clear error naming the objects, never
-  // silently-defaulted output (e.g. a Postgres project quietly emitting sqlite).
-  // A model of only value objects and/or sourceless projections reaches
-  // normalizeConfig and gets the harmless placeholders.
+  // that forgot it gets a clear error naming the objects, never
+  // silently-defaulted output (a Postgres project quietly emitting sqlite).
+  //
+  // `dbImport` is NOT part of this check, and the difference is where the answer
+  // is needed. A dialect is a property of the MODEL: every sourced object is
+  // lowered to SQL, and a wrong default is silently wrong everywhere. A dbImport
+  // is a property of a GENERATOR: only one that emits `import { db } from …` can
+  // read it, and a project whose generated queries take `db` as a parameter has
+  // no singleton to name. Demanding it from the model convicted exactly those
+  // projects — the error even told them their model "generates database code"
+  // that in fact imported nothing. It is demanded below at the point of USE, by
+  // the generator that reads it, which the runner names in the thrown message.
   const dbEmittingObjects = safeEntities.filter(
     (e) => !e.isAbstract && hasAnyRdbSource(e),
   );
-  if (dbEmittingObjects.length > 0) {
-    const missing: string[] = [];
-    if (opts.config.dialect === undefined) missing.push("dialect");
-    if (opts.config.dbImport === undefined) missing.push("dbImport");
-    if (missing.length > 0) {
-      const names = dbEmittingObjects.map((e) => e.name).join(", ");
-      throw new Error(
-        `codegen config is missing ${missing.join(" and ")} — required because this model ` +
-          `generates database code for: ${names}. Set ${missing.join(" and ")} in ` +
-          `metaobjects.config.ts. (A model of only value objects and/or sourceless projections may omit them.)`,
-      );
-    }
+  if (dbEmittingObjects.length > 0 && opts.config.dialect === undefined) {
+    const names = dbEmittingObjects.map((e) => e.name).join(", ");
+    throw new Error(
+      `codegen config is missing dialect — required because this model ` +
+        `generates database code for: ${names}. Set dialect in ` +
+        `metaobjects.config.ts. (A model of only value objects and/or sourceless projections may omit it.)`,
+    );
   }
 
+  /** Did the AUTHOR declare a dbImport reachable by this target? Tracked, never
+   *  inferred by comparing against DEFAULT_DB_IMPORT — `meta init` scaffolds a
+   *  relative path and a project may legitimately write the default's own string,
+   *  which a value comparison would then read as absent. */
+  const dbImportUndeclaredFor = (targetName: string): boolean =>
+    (opts.config.targets?.[targetName]?.dbImport ?? opts.config.dbImport) === undefined;
+
   // 2. Resolve targets + entity-module target.
   const config = normalizeConfig(opts.config);
 
@@ -429,6 +439,25 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       warn: (msg) => warnings.push(`[${generator.name}] ${msg}`),
     };
 
+    // The point of USE for an undeclared dbImport (see the guard above). Reading
+    // it is what proves this generator emits a db-singleton import, so reading is
+    // what asks for it; a generator that never touches it never demands it. The
+    // throw travels through the `[${generator.name}]` wrapper below, so the message
+    // names the generator that wants the path. Both surfaces are covered because a
+    // generator may read either.
+    if (dbImportUndeclaredFor(selfTarget.name)) {
+      const demand = (): never => {
+        throw new Error(
+          `codegen config is missing dbImport — this generator emits ` +
+            `\`import { db } from …\` and needs the module to import it from. Set dbImport in ` +
+            `metaobjects.config.ts (or on this generator's target). A project whose generated ` +
+            `queries take \`db\` as a parameter never needs it.`,
+        );
+      };
+      Object.defineProperty(renderContext, "dbImport", { get: demand, configurable: true });
+      Object.defineProperty(ctx.config, "dbImport", { get: demand, configurable: true });
+    }
+
     let files: EmittedFile[];
     try {
       files = await generator.generate(ctx);
 
@@ -2,13 +2,22 @@
 // zero DB code, so requiring them was a dead-but-mandatory tsc obligation). A model
 // that DOES emit DB code must still set them, and omitting them errors clearly rather
 // than silently defaulting (which would e.g. emit sqlite for a Postgres project).
+//
+// The two halves later split on WHERE the answer is needed. `dialect` stays eager:
+// a wrong default silently emits the wrong SQL for every sourced object, so the model
+// alone settles it. `dbImport` is only ever read by a generator that emits
+// `import { db } from …`, and a project whose generated queries take `db` as a
+// parameter never has one — so demanding it from the MODEL convicted projects that
+// could not use it. It is now demanded at the point of USE, by the generator that
+// needs it, naming that generator.
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { MetaDataLoader, InMemoryStringSource } from "@metaobjectsdev/metadata";
 import { runGen } from "../src/runner.js";
 import { entityFile } from "../src/generators/entity-file.js";
+import { routesFile } from "../src/generators/routes-file.js";
 import type { MetaobjectsGenConfig } from "../src/metaobjects-config.js";
 
 let tmp: string;
@@ -82,10 +91,53 @@ describe("#194 item 3 — dbImport/dialect optional for value-object-only and so
       err = e as Error;
     }
     expect(err).toBeDefined();
-    expect(err!.message).toContain("dialect and dbImport");
+    expect(err!.message).toContain("dialect");
     expect(err!.message).toContain("User"); // names the DB-emitting object
   });
 
+  test("a DB entity with dialect but no dbImport generates when nothing emits a db import", async () => {
+    // The shape the eager guard convicted: a real sourced entity, a generator that
+    // takes `db` as a parameter rather than importing a singleton. Nothing can read
+    // dbImport, so nothing may demand it.
+    const root = await load(ENTITY);
+    const cfg = { ...configNoDb(), dialect: "sqlite" as const } as MetaobjectsGenConfig;
+    const result = await runGen({ config: cfg, metadata: root, projectRoot: tmp });
+    expect(result.files.length).toBeGreaterThan(0);
+  });
+
+  test("a generator that DOES emit `import { db }` still demands dbImport, and names itself", async () => {
+    const root = await load(ENTITY);
+    const cfg = {
+      ...configNoDb(),
+      dialect: "sqlite" as const,
+      generators: [routesFile()],
+    } as MetaobjectsGenConfig;
+    let err: Error | undefined;
+    try {
+      await runGen({ config: cfg, metadata: root, projectRoot: tmp });
+    } catch (e) {
+      err = e as Error;
+    }
+    expect(err).toBeDefined();
+    expect(err!.message).toContain("dbImport");
+    expect(err!.message).toContain("routes"); // the runner prefixes [<generator>]
+  });
+
+  test("an explicit dbImport equal to the default is honoured, not read as absent", async () => {
+    // Declaration is tracked, never inferred by comparing against DEFAULT_DB_IMPORT:
+    // `meta init` scaffolds a relative path, and a project is free to write the same
+    // string the default happens to use.
+    const root = await load(ENTITY);
+    const cfg = {
+      ...configNoDb(),
+      dialect: "sqlite" as const,
+      dbImport: "./db",
+      generators: [routesFile()],
+    } as MetaobjectsGenConfig;
+    const result = await runGen({ config: cfg, metadata: root, projectRoot: tmp });
+    expect(result.files.length).toBeGreaterThan(0);
+  });
+
   test("a DB entity WITH dbImport/dialect set generates normally (no regression)", async () => {
     const root = await load(ENTITY);
     const cfg = { ...configNoDb(), dbImport: "./db", dialect: "postgres" as const } as MetaobjectsGenConfig;