Every generated client carries a private copy of the runtime, so a second module in one app duplicates it — and in Dart the two cannot be imported together at all

[jryannel]

Each sqlb generate run emits a self-contained client: the row types and operations for that project's tables, preceded by a full private copy of the runtime — Collection, Page, Problem, ProblemDetail, ApiRequest, Transport, the filter-grammar encoder, isProblem/allowedFor.

That is exactly right for one module. A modular monolith has many, all serving one frontend, and the second module is where it breaks.

Measured, on the second module in one app

Two modules in one app (family, then tutor), emitting into the same web/src/api and mobile/lib/api:

	file A	file B	identical leading lines
TypeScript	client.gen.ts 457	tutor.client.gen.ts 587	287
Dart	client.gen.dart 1563	tutor.client.gen.dart 1893	1187

The runtime is byte-identical in both — it is the same generator emitting the same template. A third module makes it three copies.

I had to set TSClientFile / TSQueriesFile / DartFile on the second module, because the defaults (client.gen.ts, queries.gen.ts, client.gen.dart) are per-project constants and the second project silently overwrites the first's files in a shared output directory. Those options exist, so this part has an answer — but the answer is a naming convention the adopter has to invent, and it does not address what follows.

In Dart it is a compile error, not duplication

Dart is nominally typed, so the two Page<T> are two unrelated classes. One file cannot consume both clients:

import 'client.gen.dart';
import 'tutor.client.gen.dart';

Future<void> probe(Transport t) async {
  final Page<Child> kids = await listChildren(t);
  final Page<Session> sessions = await listSessions(t);
}

error - The name 'Transport' is defined in the libraries 'client.gen.dart' and
        'tutor.client.gen.dart'. Try using 'as prefix' for one of the import
        directives, or hiding the name from all but one of the imports. - ambiguous_import
error - The name 'Page' is defined in the libraries ... - ambiguous_import

as prefix makes it compile and does not make it work:

• family.Page<T> and tutor.Page<T> are distinct types, so no shared widget, pager, or error boundary can accept both. An infinite-scroll list widget — the thing the Dart cursor pager exists to make possible — has to be written once per module.
• The hand-written http_transport.dart returns Transport. There are now two Transport typedefs, so the app's single transport (base URL, bearer token, 401 policy, ApiException) has to be duplicated per module, and each copy catches only its own module's Problem.

TypeScript escapes the compile error because it is structurally typed — the duplicate Page/Problem interfaces interoperate. It still ships N copies of the encoder and the runtime to the browser, and still asks the app to wire one Transport per module.

Why a convention cannot fix it

The generated file's own header says it imports nothing, and that is a real design property — no pub package, no bundler assumption. But "imports nothing" and "there are several of these" are only compatible if the runtime is emitted once, separately, and the per-module files import that.

Suggested shape

Emit the runtime as its own file, once per output directory, and have each module's client import it:

web/src/api/runtime.gen.ts        ← Page, Problem, Transport, encodeListQuery, …
web/src/api/family.gen.ts         ← imports './runtime.gen'
web/src/api/tutor.gen.ts          ← imports './runtime.gen'

mobile/lib/api/runtime.gen.dart
mobile/lib/api/family.gen.dart    ← export 'runtime.gen.dart' or import it
mobile/lib/api/tutor.gen.dart

The runtime is derived from nothing module-specific, so a second module writing it is a no-op and codegen.Check stays meaningful. A RuntimeFile/RuntimeImport option would let an adopter point several projects at one shared file without the generator needing to know they are related.

The alternative — one generator invocation over a registry containing every module's tables — is not available to this codebase: the whole point of the per-module registry is that modules do not import each other, so nothing is entitled to hold all of them at once.

Found taking a second module schema-first in the multi-app adoption (the subject-mono of docs/review-adoption-multi-app.md). Related: #20 (Dart emitter).

[jryannel]

Left open deliberately by #126, which closed the other ten from this backlog sweep.

This one is architectural rather than a declaration gap: it affects every emitter at once, the fix is a shared-runtime module rather than a per-emitter change, and in Dart the symptom is a compile error rather than duplication — Page<T> from two generated files are two unrelated types, so one file cannot consume both clients.

That deserves its own decision, likely its own ADR, rather than being folded into a sweep.

[jryannel]

Revisiting this properly — I labelled it "architectural" when I excluded it from #126, and that was wrong on all three counts. Correcting the record before implementing it.

It is a defect in Dart and an optimisation in TypeScript

Those are different things and lumping them together is what produced the wrong label.

TypeScript is an optimisation. Structural typing means the duplicate Page/Problem interoperate. The cost is ~287 duplicated lines per module shipped to the browser, and one Transport to wire per module. Annoying, not broken.

Dart is a defect. Nominal typing means family.Page<T> and tutor.Page<T> are unrelated types, so — as this issue documents — as prefix makes it compile without making it work. No shared pager widget can accept both, and the app's single transport has to be duplicated per module with each copy catching only its own Problem. For a multi-module Flutter app the Dart emitter does not work.

The import-path question is already answered, once, in this repo

This is the part I had not checked. The Go emitter already does exactly what this issue asks for. cli/client/client_gen.go holds Request, Transport, Client, Do, Run, Problem, ItemPath — the runtime — as its own package, and cli_gen.go imports it. That split was made for #97 for a different reason, and it answered the import-path question then: ClientImportPath derives from the nearest go.mod and is overridable when the derivation cannot be right.

TS and Dart are strictly easier, because neither needs a module path — the import is relative, inside the output directory the generator already owns:

import type { Page, Problem } from './runtime.gen';

import 'runtime.gen.dart';

No bundler config, no pub package, and no new option for the single-module case.

Regeneration is handled, and one case gets better

• A column or table added or removed lands in the module's own file. The runtime is derived from nothing module-specific, so it is not touched.
• Two modules, same sqlb version render a byte-identical runtime; the second write is a no-op and both sqlb check runs pass, since Check is a byte comparison per file.
• Two modules, different sqlb versions — the runtime differs, last writer wins, and the other module's check fails out of date. Version skew becomes a gate failure rather than something silently shipped, which is better than today, where each module carries its own stale copy and nothing notices.

New failure mode worth naming: deleting a module leaves an orphaned runtime.gen.* that nothing collects.

On "it imports nothing"

That header promise is real and worth keeping in substance. A relative import of a sibling generated file is not a package dependency, so what changes is the wording. Dart can keep it invisible to existing consumers entirely: the module file exports the runtime library, so import 'client.gen.dart' still sees Page and Transport — and two modules exporting the same library is exactly what removes the ambiguous_import, because the names now resolve to one declaration instead of two.

Implementing it now, as the shape suggested here.

[jryannel]

Implemented for TypeScript in #126 (fa5d9c0). Dart is attempted, reverted, and I think it needs a decision from you — details below.

TypeScript: done, in the shape this issue proposed

web/src/api/runtime.gen.ts   Page, Problem, Transport, the filter encoder
web/src/api/client.gen.ts    imports it, and re-exports it

Invisible to a single-module project, deliberately: client.gen re-exports the runtime, so import type { Page } from './client.gen' keeps compiling. Splitting without that would break every consumer to fix a problem only multi-module consumers have.

The import list is computed from the emitted body rather than written down — tsconfig has noUnusedLocals, so an import the body does not reference is a build failure, and the set varies by schema (a schema with no array column never mentions ArrayCond). The runtime's exports are parsed out of the runtime source and the body scanned for them.

Two things worth recording:

• itemPath was module-local and the client calls it. Before the split every helper was in scope, so this could not happen; after it, the failure arrived as ten Cannot find name errors from tsc rather than from the generator. It is exported now — the same helper Go exports as ItemPath — and a generator-time check reports the next one as a sentence instead.
• The import carries the .ts extension. queries.gen.ts omits it and gets away with it because that file is only typechecked; client.gen.ts runs, under node --test with type stripping, where Node's resolver needs a real path. Extensionless would be a bundler assumption, and no bundler assumption is a property this client claims in its own header.

Dart: the file split does not reach it, and here is why

I implemented it, it did not converge, and the failures were not incidental — they were the same fact three times.

Dart privacy is per library, and the runtime's contract with the generated client is largely private.

• Row declares the protocol every generated row view inherits — _str, _int, _one, _many, ~28 members. A subclass in another library cannot call any of it.
• The client emits cond?._encode(out, 'id'), and _encode is a private method on the public Cond family. It also takes _Query, which is private too.
• Top-level _get, _post, _row, _page, _asInt are called directly by the generated body.

I tried partitioning by public/private, then by an explicit shared list, then by reachability with the privates duplicated into whichever half references them. Each fixed one layer and exposed the next, and --fatal-infos with unused_element means a helper cannot simply be copied into both halves.

So the honest shape of the Dart fix is: make the runtime's protocol public and documented, then split. That is ~15 top-level helpers plus Row's ~28 inherited members becoming public API — and under public_member_api_docs, becoming documented API. It changes what every generated Dart client exposes: get, post, row, asInt would be callable by anyone.

That is a decision about the client's public surface, not a refactor, and I did not want to make it inside a backlog sweep. The alternative shapes I can see:

1. Make the protocol public — Dart matches TS and Go exactly, at the cost of a much larger public API.
2. Share only the response vocabulary — Page, Collection, Problem, Transport, ApiRequest — and leave Row and the Cond family per client. This fixes what the issue actually reports (one pager widget, one transport, one Problem to catch) and leaves the private machinery duplicated, which is invisible because it is private. Smaller, and it does not make Row shareable.
3. Leave Dart as is and document that a multi-module Flutter app needs one generated module.

My read is (2) — it buys the thing the issue is about and costs no public API. But it is your call, so the issue stays open for that.

Reopening scope note: TypeScript's half is closed by #126; this issue now stands for the Dart half only.

[jryannel]

Option 2 implemented in #126 (be43fa7). Both emitters are done; mise run ci passes.

mobile/lib/api/runtime.gen.dart   Page, Collection, Problem, ProblemDetail,
                                  ApiRequest, Transport, CursorPager,
                                  SortTerm, WireValue, and the two exceptions
mobile/lib/api/client.gen.dart    imports it, exports it, and keeps Row and
                                  the Cond family

That is the defect this issue reports, fixed: two clients exporting one library offer one Page, one Transport, one Problem — so a shared pager widget and a single transport are writable again.

Row and the filter conditions stay per client, on the boundary Dart's privacy actually allows. Both keep a private contract with the generated code — Row declares the _str/_int/_one/_many protocol every row view inherits, and the client emits cond?._encode(out, 'id') over a private _Query — so sharing either needs ~40 members entering the public, documented API of every client. Leaving them per client duplicates code nothing can observe, because all of it is private.

The test that matters generates two modules into one directory and asserts the runtime is byte-identical between them, that neither declares its own Page, and that both export the runtime. Byte-identical is what lets the second module write the same path without disturbing the first, and what keeps sqlb check meaningful for both — which is the regeneration question from earlier in this thread, now enforced rather than argued.

Two notes for whoever reads the code:

• The private helpers go wherever they are reached, computed to a fixpoint, and into both halves when both reach them. The walk is seeded with the generated body, because the resource sections are what call _get, _page and _row; seeding from the runtime alone left every one of them behind.
• One parser correction is commented where it lives: a line at column zero begins a new declaration only if it starts with a letter, underscore or annotation. A multi-line signature closes on a ) in column zero, and reading that as a declaration cut the function in half — reported by the analyser as a syntax error three declarations later.

Closing: the TypeScript half landed in fa5d9c0, the Dart half here.

[jryannel]

Closing against #126, which is open for review. Reopen if the branch does not land.