@onreza/sqlx-js 0.5.0 → 0.7.0

package/README.md

@@ -43,9 +43,11 @@ const rows = await sql(
 - **Shadow database validation** via `migrate dev` / `migrate verify`: auto-create a disposable shadow DB, apply migrations, validate SQL, and drop it afterwards.
 - **Safe identifier quoting** via `sql.id(...)`, backed by the committed schema snapshot whitelist.
 - **Single runtime adapter**: Postgres.js backs the runtime on Node/Bun-compatible environments — no Bun.SQL-specific adapter to choose.
-- **Watch mode**: debounced re-prepare with a warm `PgClient` + `SchemaCache` on source/SQL changes and scanner/config graph updates.
+- **Incremental watch mode**: debounced re-prepare with a warm `PgClient` + `SchemaCache`; source/SQL edits only rescan affected files and re-describe changed fingerprints, while config/tsconfig/schema changes trigger a full rebuild.
 - **Cache pruning** removes orphaned entries automatically (toggleable with `--no-prune`).
 - **Environment doctor** checks runtime versions, config loading, `.env`, database connectivity/permissions, cache metadata, tsconfig inclusion, and pgschema availability.
+- **Strict inference gate** promotes degraded nullability analysis and generated `unknown` query types to CI errors.
+- **GitHub/editor diagnostics adapter** converts versioned prepare JSON into workflow annotations or Unix problem-matcher output.
 
 ## Install
 
@@ -57,7 +59,7 @@ bun add @onreza/sqlx-js
 
 Node.js 24 or newer is required. Bun users need Bun 1.3 or newer.
 
-The package installs a `sqlx-js` binary. The CLI examples below use `npx @onreza/sqlx-js`; `bunx @onreza/sqlx-js ...` works the same if your project uses Bun.
+The package installs `sqlx-js` and `sqlx-js-diagnostics` binaries. The CLI examples below use `npx @onreza/sqlx-js`; `bunx @onreza/sqlx-js ...` works the same if your project uses Bun.
 
 ## Setup
 
@@ -67,7 +69,7 @@ The package installs a `sqlx-js` binary. The CLI examples below use `npx @onreza
 npx @onreza/sqlx-js init
 ```
 
-Creates `sqlx-js.config.ts`, a `migrations/` directory, and `.env.example` if they don't already exist (it never overwrites existing files), then prints the next steps. Skip it if you prefer to wire things up manually.
+Creates `sqlx-js.config.ts`, `sqlx-js-env.d.ts`, a `migrations/` directory, and `.env.example` if they don't already exist. For strict-JSON files it adds missing `sqlx:*` scripts to `package.json` and appends the declaration to an existing `files` or `include` array in `tsconfig.json`, without replacing existing values; JSONC files are left unchanged with a manual-update hint. Skip it if you prefer to wire things up manually.
 
 For declarative PostgreSQL schema management, scaffold the pgschema workflow instead:
 
@@ -144,7 +146,7 @@ const users = await sql(
 npx @onreza/sqlx-js prepare
 ```
 
-This generates `sqlx-js-env.d.ts` next to your code. Add it to your `tsconfig.json` `include` if it isn't picked up automatically. Use `--dts <path>` to override the destination.
+This generates `sqlx-js-env.d.ts` next to your code. Add it to your `tsconfig.json` `include` if it isn't picked up automatically. Use `--dts <path>` to override the destination relative to `--root`.
 
 ### 5. Dev loop with watch
 
@@ -322,6 +324,25 @@ import { createClient, setClient } from "@onreza/sqlx-js";
 setClient(createClient(process.env.DATABASE_URL));
 ```
 
+For dependency injection, read replicas, tests, or several independent pools in one process, create a scoped runtime instead of replacing the global client:
+
+```ts
+import { createSqlClient } from "@onreza/sqlx-js";
+import type { SqlxJsGeneratedRegistry } from "./sqlx-js-env";
+
+const primary = createSqlClient<SqlxJsGeneratedRegistry>(process.env.DATABASE_URL);
+const replica = createSqlClient<SqlxJsGeneratedRegistry>(process.env.REPLICA_DATABASE_URL);
+
+await primary.sql(`INSERT INTO audit_log (message) VALUES ($1)`, "created");
+const rows = await replica.sql(`SELECT id, message FROM audit_log ORDER BY id DESC`);
+
+await Promise.all([primary.close(), replica.close()]);
+```
+
+Each generated `sqlx-js-env.d.ts` exports its own `SqlxJsGeneratedRegistry`. Passing it to `createSqlClient<...>()` keeps a scoped client on that project's query contract even when a monorepo TypeScript program includes declarations for several databases. The global `sql` export remains available for the single-client convenience path.
+
+The scanner recognizes clients assigned directly from an imported `createSqlClient(...)` (including aliased and namespace imports), so `client.sql(...)`, its cardinality helpers, file queries, and transactions participate in `prepare` exactly like the global `sql` surface.
+
 `createClient(url, options)` accepts every Postgres.js option plus sqlx-js runtime options:
 
 ```ts
@@ -331,6 +352,9 @@ setClient(createClient(process.env.DATABASE_URL, {
   statementTimeoutMs: 5000,
   // Base directory for root-relative sql.file(...) calls.
   fileRoot: import.meta.dirname,
+  // Development-only: re-stat sql.file() files on every call. The default
+  // immutable cache avoids synchronous filesystem work in the query hot path.
+  reloadSqlFiles: true,
   // Honored for every unsafe call. Set false for PgBouncer transaction mode
   // unless protocol-level prepared statements are configured there.
   prepare: false,
@@ -339,14 +363,15 @@ setClient(createClient(process.env.DATABASE_URL, {
     if (error) logger.error({ query, error });        // database errors are PgError
     else if (durationMs > 200) logger.warn({ slow: query, durationMs, rowCount });
   },
+  onQueryHookError: (error) => logger.error({ error }, "query observer failed"),
 }));
 ```
 
-The `onQuery` hook is the integration point for metrics, tracing, and slow-query logging — sqlx-js does not log queries itself. The event carries the raw `params`, which may contain personal or sensitive data — don't log them blindly; redact or omit `params` in shared sinks. Database errors are normalized to `PgError`; transport and non-database errors pass through unchanged.
+The `onQuery` hook is the integration point for metrics, tracing, and slow-query logging — sqlx-js does not log queries itself. It is a non-blocking observer: synchronous throws and asynchronous rejections preserve the database result/error and are passed to `onQueryHookError` when configured. The event carries the raw `params`, which may contain personal or sensitive data — don't log them blindly; redact or omit `params` in shared sinks. Database errors are normalized to `PgError`; transport and non-database errors pass through unchanged.
 
 ### `clearSqlFileCache()`
 
-Drops the in-memory cache used by `sql.file(...)`. The cache invalidates automatically on file mtime change, so this is rarely needed manually.
+Drops the in-memory cache used by `sql.file(...)`. Files are immutable after their first read by default, avoiding a synchronous `stat` call for every query. Call this after a development-time file change or set `reloadSqlFiles: true` on the client to restore mtime-based reloading.
 
 ### Typed errors
 
@@ -385,43 +410,48 @@ In addition to `import { sql } from "@onreza/sqlx-js"`, the scanner recognises `
 
 ```
 sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]
-sqlx-js doctor [--root <dir>] [--json]
-sqlx-js db install | check | plan | apply [--root <dir>] [-- <pgschema args>]
-sqlx-js prepare [--check | --verify | --watch] [--json] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
-sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | verify [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] [--pg-dump <path>] [--lock-timeout <ms>] | archive list | archive restore <name> [--force]
-sqlx-js schema dump | check [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
+sqlx-js doctor [--root <dir>] [--dts <path>] [--json]
+sqlx-js db install | check [--root <dir>]
+sqlx-js db plan | apply [--root <dir>] [-- <pgschema args>]
+sqlx-js prepare [--check | --offline | --verify | --watch] [--json | --jsonl] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
+sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | verify [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] [--pg-dump <path>] [--lock-timeout <ms>] | archive list | archive restore <name> [--force]
+sqlx-js schema dump [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
+sqlx-js schema check [--schema <path>] [--shadow-url <url>]
 sqlx-js --version | --help
 ```
 
-Regular `prepare` describes queries across a small connection pool (default 8, override with `SQLX_JS_PREPARE_CONCURRENCY`) for faster cold runs on large projects. Watch mode keeps one session warm and reuses it between debounced changes.
+Regular `prepare` describes queries across a small connection pool (default 8, override with `SQLX_JS_PREPARE_CONCURRENCY`) for faster cold runs on large projects. Watch mode keeps one session warm, rescans only affected source files, and reuses cached metadata for unchanged fingerprints. Config, tsconfig, and applied shadow-migration changes invalidate the incremental state and perform a full prepare.
 
 | Flag                  | Meaning                                                                              |
 |-----------------------|--------------------------------------------------------------------------------------|
-| `--check`             | Offline: verify every scanned query is present in cache, no database required.       |
+| `--check`             | Read-only offline verification of the active query cache, function catalog, and generated declaration. |
+| `--offline`           | Regenerate `sqlx-js-env.d.ts` from committed cache without a database.                |
 | `--verify`            | Prepare against the live/shadow schema and compare generated artifacts without writing. |
 | `--watch`             | Persistent connection, re-prepare on file change.                                    |
 | `--root <dir>`        | Source/cache/migrations root (default: cwd).                                         |
-| `--dts <path>`        | Declarations output (default: `<root>/sqlx-js-env.d.ts`).                           |
-| `--no-prune`          | Keep orphaned cache entries instead of removing them.                                |
-| `--migrations <dir>`  | Migrations directory (default: `<root>/migrations`).                                 |
+| `--dts <path>`        | Root-relative declarations output (default: `<root>/sqlx-js-env.d.ts`).             |
+| `--no-prune`          | Keep orphaned cache entries; they do not invalidate a later `--check`.                |
+| `--migrations <dir>`  | Root-relative migrations directory (default: `<root>/migrations`).                   |
 | `--dry-run`           | For `migrate run` / `migrate revert`: validate without applying to the target DB.   |
 | `--json`              | Machine-readable prepare diagnostics, doctor output, migration inspection and dry-runs. |
+| `--jsonl`             | Versioned streaming events for `prepare --watch`.                                     |
+| `--strict-inference`  | Fail prepare/dev/verify when nullability degrades or a generated query type contains `unknown`. |
 | `--force`             | For `migrate archive restore`: allow overwriting existing migration files.           |
 | `--lock-timeout <ms>` | Advisory-lock acquisition timeout for `migrate run` / `revert` / `dev` / `verify` / `squash`. |
 | `--shadow-url <url>`  | Use an existing disposable shadow DB instead of auto-creating one.                   |
 | `--shadow-admin-url <url>` | Admin/maintenance DB URL used to auto-create shadow DBs.                       |
 | `--replace`           | For `migrate squash`: archive replaced migration files after writing the baseline.   |
 | `--pg-dump <path>`    | For `migrate squash`: `pg_dump` executable path (default: `pg_dump`).                |
-| `--schema <path>`     | Schema snapshot path (default: `<root>/.sqlx-js/schema/schema.json`).               |
-| `--manifest <path>`   | LLM schema manifest path (default: `<root>/.sqlx-js/schema/schema.md`).             |
+| `--schema <path>`     | Root-relative schema snapshot path (default: `<root>/.sqlx-js/schema/schema.json`). |
+| `--manifest <path>`   | Root-relative LLM schema manifest path (default: `<root>/.sqlx-js/schema/schema.md`). |
 | `--no-manifest`       | Skip writing the LLM schema manifest during `schema dump`.                           |
 | `--schema-provider <name>` | For `init`: `builtin` (default) or `pgschema`.                                |
 
 Flags that take a value accept both `--flag value` and `--flag=value` forms.
 
-Prepare and doctor JSON use `formatVersion: 1`. Prepare diagnostics include a stable phase plus root-relative file, 1-based line/column, PostgreSQL code/position/hint when available, and the query text. This is intended for CI annotations and editor integrations; stdout contains one JSON document and human progress is suppressed.
+Prepare and doctor JSON use `formatVersion: 1`. Prepare diagnostics include a stable phase plus root-relative file, 1-based line/column, PostgreSQL code/position/hint when available, and the query text. Degraded inference and generated `unknown` types appear as warnings by default; `--strict-inference` promotes them to errors. This is intended for CI annotations and editor integrations; stdout contains one JSON document and human progress is suppressed. `prepare --watch --jsonl` emits one `start`, `diagnostic`, `prepared`, `error`, `watching`, or `stopping` event per line so an editor can consume diagnostics without waiting for the watch process to exit. Fatal `error` events include the same structured `diagnostic` object as CLI preflight failures, preserving the prepare phase and source location when available.
 
-`DATABASE_URL` must be set for any command that touches the application database or auto-creates a shadow database. `SHADOW_ADMIN_DATABASE_URL` can point at a maintenance/admin database when the application user cannot `CREATE DATABASE`; `SHADOW_DATABASE_URL` can point at a pre-created disposable shadow database. The internal wire client understands `sslmode`, `sslrootcert`, `sslcert`, `sslkey`, `application_name`, `connect_timeout` (seconds), and `statement_timeout` (milliseconds).
+`DATABASE_URL` must be set for any command that touches the application database or auto-creates a shadow database. `SHADOW_ADMIN_DATABASE_URL` can point at a maintenance/admin database when the application user cannot `CREATE DATABASE`; `SHADOW_DATABASE_URL` can point at a pre-created disposable shadow database. The internal wire client understands `sslmode`, `sslrootcert`, `sslcert`, `sslkey`, `application_name`, `options` (PostgreSQL startup options such as `-c search_path=app,public`), `connect_timeout` (seconds), and `statement_timeout` (milliseconds). Unqualified relations are resolved using the prepare session's real `search_path`; they are not assumed to live in `public`.
 
 ### Development and deployment flows
 
@@ -454,7 +484,7 @@ The built-in `migrate` workflow is kept for simple projects and embedded applica
 Use `migrate verify` in PR/CI before merge:
 
 ```bash
-sqlx-js migrate verify
+sqlx-js migrate verify --strict-inference
 sqlx-js prepare --check
 sqlx-js doctor --json
 tsc --noEmit
@@ -514,6 +544,39 @@ When `prepare` fails, every diagnostic points back to the originating call site:
 
 Phases reported separately: `describe failed`, `analyze failed`, `paramMap failed`. PostgreSQL `position`, `code`, and `hint` are surfaced when present.
 
+### GitHub and editor diagnostics
+
+`sqlx-js-diagnostics` converts the versioned prepare JSON document into GitHub workflow commands or a standard Unix problem-matcher stream:
+
+```bash
+set -o pipefail
+sqlx-js prepare --verify --json | sqlx-js-diagnostics github
+sqlx-js prepare --check --json | sqlx-js-diagnostics unix
+```
+
+The `github` format creates inline workflow annotations. The `unix` format emits `file:line:column: severity: [phase] message`, which can be consumed by VS Code tasks and other editors without a dedicated extension. A minimal VS Code task uses a custom problem matcher:
+
+```json
+{
+  "label": "sqlx-js: check",
+  "type": "shell",
+  "command": "sqlx-js prepare --check --json | sqlx-js-diagnostics unix",
+  "problemMatcher": {
+    "owner": "sqlx-js",
+    "fileLocation": ["relative", "${workspaceFolder}"],
+    "pattern": {
+      "regexp": "^(.+):(\\d+):(\\d+): (error|warning): \\[([^\\]]+)\\] (.*)$",
+      "file": 1,
+      "line": 2,
+      "column": 3,
+      "severity": 4,
+      "code": 5,
+      "message": 6
+    }
+  }
+}
+```
+
 ## Configuration
 
 `sqlx-js.config.ts` at the project root is optional.
@@ -527,6 +590,7 @@ export default defineConfig({
   scan: {
     include: ["apps/*/src/**/*", "packages/*/src/**/*"],
     exclude: ["**/*.generated.ts"],
+    modules: ["@onreza/sqlx-js", "@app/database"],
   },
   schema: {
     provider: "pgschema",
@@ -541,7 +605,7 @@ export default defineConfig({
 });
 ```
 
-By default the scanner uses the root `tsconfig.json` file list and follows TypeScript project references, so a referenced monorepo is scanned without walking unrelated folders. `scan.include` replaces that source-file universe with TypeScript glob patterns; `scan.exclude` is added to the built-in dependency/build exclusions. If there is no root `tsconfig.json`, the fallback is a recursive TypeScript scan.
+By default the scanner uses the root `tsconfig.json` file list and follows TypeScript project references, so a referenced monorepo is scanned without walking unrelated folders. `scan.include` replaces that source-file universe with TypeScript glob patterns; `scan.exclude` is added to the built-in dependency/build exclusions. `scan.modules` replaces the default `@onreza/sqlx-js` import source list, which lets an application re-export `sql` through a shared database module without requiring arbitrary re-export graph analysis. Include `@onreza/sqlx-js` explicitly when direct imports and application-module imports are both used. If there is no root `tsconfig.json`, the fallback is a recursive TypeScript scan.
 
 The `schema` block is optional. Use `provider: "pgschema"` when sqlx-js should delegate schema planning/apply commands to pgschema. `command` can override the managed binary lookup and point at another executable. With the pinned pgschema 1.12.0 CLI, `schemas` must contain exactly one schema name.
 
@@ -620,12 +684,12 @@ Commit the generated `sqlx-js-env.d.ts` and the `.sqlx-js/` cache directory to y
 
 ```yaml
 - run: bun install
-- run: sqlx-js migrate verify    # built-in migration workflow
+- run: sqlx-js migrate verify --strict-inference # built-in migration workflow
 # or, when schema.provider is "pgschema":
 - run: sqlx-js db install
 - run: sqlx-js db plan -- --output-json plan.json
-- run: sqlx-js prepare --verify  # live/shadow comparison of every generated artifact
-- run: sqlx-js prepare --check   # offline cache/version/config consistency
+- run: sqlx-js prepare --verify --strict-inference # live/shadow comparison with complete inference
+- run: sqlx-js prepare --check   # read-only offline cache/declaration consistency
 - run: sqlx-js doctor --json     # runtime/config/DB/cache/tsconfig preflight
 - run: sqlx-js schema check      # fails if the committed schema snapshot is stale
 - run: tsc --noEmit               # fails if types are stale
@@ -633,7 +697,7 @@ Commit the generated `sqlx-js-env.d.ts` and the `.sqlx-js/` cache directory to y
 - run: bun run build              # emits publishable JS + declarations under dist/
 ```
 
-The `migrate verify` step needs `DATABASE_URL` credentials that can either create a temporary database or use `--shadow-admin-url` / `--shadow-url`. It does not write `.sqlx-js/` or `sqlx-js-env.d.ts`. For pgschema projects, `sqlx-js db plan` checks the desired `schema.sql` against the target database and leaves application query typing to `prepare`. The `prepare --check` step then runs without a database; your committed offline cache is the source of truth. Add `prepare --verify` when CI has a canonical database/shadow schema and must prove byte-for-byte artifact freshness. `schema check` intentionally uses a live database because it verifies the committed schema contract against PostgreSQL.
+The `migrate verify` step needs `DATABASE_URL` credentials that can either create a temporary database or use `--shadow-admin-url` / `--shadow-url`. It does not write `.sqlx-js/` or `sqlx-js-env.d.ts`. For pgschema projects, `sqlx-js db plan` checks the desired `schema.sql` against the target database and leaves application query typing to `prepare`. `prepare --check` is read-only and fails when either the committed cache or declaration is stale. Use `prepare --offline` when a developer intentionally needs to restore the declaration from a valid committed cache. Add `prepare --verify` when CI has a canonical database/shadow schema and must prove byte-for-byte artifact freshness. `schema check` intentionally uses a live database because it verifies the committed schema contract against PostgreSQL.
 
 The managed pgschema binary is installed under `node_modules/.cache/sqlx-js/pgschema/`, not `.sqlx-js/`, so it is not part of the committed offline cache.
 
@@ -646,20 +710,21 @@ bun install                  # installs lefthook + wires git hooks
 cargo install cocogitto      # or: brew install cocogitto
 ```
 
-Releases are automated via `release-please`: pushes to `main` accumulate into a release PR that bumps `package.json`, writes `CHANGELOG.md`, and on merge tags the commit. The tag push fires the npm publish workflow, which builds `dist/`, smoke-tests the package entrypoints, checks the tarball contents, and publishes to npm.
+Releases are automated via `release-please`: pushes to `main` accumulate into a release PR that bumps `package.json` and writes `CHANGELOG.md`. Merging that PR creates the tag and release, then the same workflow builds `dist/`, smoke-tests the package entrypoints, checks the tarball contents, and publishes to npm through Trusted Publishing.
 
 ## Limitations
 
 `sqlx-js` is a young library. Known gaps:
 
 - PostgreSQL only (no MySQL or SQLite).
-- The scanner only follows direct named imports and namespace imports from `@onreza/sqlx-js`; it does not follow re-exports, dynamic aliases, or tagged-template calls.
+- The scanner only follows direct named imports and namespace imports from configured `scan.modules` (default: `@onreza/sqlx-js`); it does not discover re-export graphs, dynamic aliases, or tagged-template calls automatically.
 - `SELECT *` falls back to conservative nullability.
 - Plain `sql(...)` keeps returning rows, so statements without `RETURNING` produce an empty typed array. Use `sql.execute(...)` when affected-row count and command metadata matter.
 - Nested CTE references (CTE-`b` referencing CTE-`a` in the same `WITH`) and `WITH RECURSIVE` are not analysed transitively — at worst this produces extra `T | null`. Use `AS "id!"` overrides if needed.
 - Column names whose **real** name (not an alias) ends with `!` or `?` are not supported — the runtime strips those suffixes assuming an override. Use `AS "alias"` if you have such a column.
+- Result columns must have unique names because Postgres.js returns object rows. Alias join projections such as `users.id AS user_id, posts.id AS post_id`; `prepare` rejects duplicate output names before generating declarations.
 - Migrations run inside `BEGIN/COMMIT`. DDL that disallows transactions (`CREATE INDEX CONCURRENTLY`, `VACUUM`, `REINDEX CONCURRENTLY`, …) will fail; split such operations into separate migrations executed outside the runner.
-- The **internal** wire client (used by `migrate run`, `prepare`, and the runtime `migrate()` helper) reads `sslmode`, `sslrootcert`/`sslcert`/`sslkey`, `application_name`, `connect_timeout`, and `statement_timeout` from `DATABASE_URL`. The default runtime `sql()` path delegates connection handling to Postgres.js; configure TLS, pooling, and timeouts through the `DATABASE_URL` and `createClient(...)` options it understands (`statementTimeoutMs` is a convenience that maps to a per-connection `statement_timeout`).
+- The **internal** wire client (used by `migrate run`, `prepare`, and the runtime `migrate()` helper) reads `sslmode`, `sslrootcert`/`sslcert`/`sslkey`, `application_name`, `options`, `connect_timeout`, and `statement_timeout` from `DATABASE_URL`. The default runtime `sql()` path delegates connection handling to Postgres.js; configure TLS, pooling, and timeouts through the `DATABASE_URL` and `createClient(...)` options it understands (`statementTimeoutMs` is a convenience that maps to a per-connection `statement_timeout`).
 - `connect_timeout` bounds the entire internal-client connect, including the TLS handshake and SCRAM authentication.
 - Runtime `sql.file(path)` resolves against `fileRoot` while prepare resolves against `--root`. They are both root-relative, but applications started outside the project root must set `fileRoot` explicitly.
 
@@ -667,7 +732,7 @@ See [ROADMAP.md](./ROADMAP.md) for what's planned.
 
 ## Upgrading
 
-### Cache and parameter contract change (pre-1.0)
+### Cache, codegen, and parameter contract changes (pre-1.0)
 
 Generated cache now includes `.sqlx-js/cache-manifest.json` with an explicit cache format, generator revision, and hash of `jsonbTypes` / `customTypes`. Cache without this manifest is rejected. Delete `.sqlx-js/` and re-run `sqlx-js prepare` against your database — there is no data loss because the cache is generated.
 
@@ -675,6 +740,10 @@ Generated JSON and PostgreSQL array parameters now require `sql.json(...)` and `
 
 CI (`prepare --check`) will also fail loudly until the cache is regenerated; this is intentional so a stale schema can't silently emit incorrect `.d.ts`.
 
+Generator revision 4 changes the declaration layout so it exports `SqlxJsGeneratedRegistry` for scoped clients while continuing to augment the global `KnownQueries` convenience API. Re-run live `sqlx-js prepare` after upgrading. `prepare --check` is now strictly read-only; use `prepare --offline` when deliberate cache-to-declaration regeneration is required.
+
+Runtime observers and SQL-file caching are also stricter production boundaries. An exception from `onQuery` no longer replaces a successful query result; handle it through `onQueryHookError`. `sql.file()` no longer performs an mtime check on every call—use `reloadSqlFiles: true` during development or call `clearSqlFileCache()` explicitly after changing a file.
+
 ## License
 
 MIT.

package/ROADMAP.md

@@ -6,12 +6,12 @@ Items already shipped live in the [README](./README.md) feature list; this file
 
 | Feature | ROI | Notes |
 |---------|-----|-------|
-| pgschema integration hardening | 8 | Basic `init --schema-provider pgschema` plus managed `sqlx-js db install/check/plan/apply` exists. Continue with better docs, CI examples, schema snapshot handoff, and migration guidance for projects that outgrow built-in migrations. |
+| pgschema integration hardening | 6 | Managed install/check/plan/apply now has a real pinned-binary PostgreSQL E2E in CI. Continue with schema snapshot handoff and migration guidance for projects that outgrow built-in migrations. |
 | Built-in migration lifecycle maintenance | 5 | Keep `migrate run/dev/verify/revert/squash/archive` stable for simple projects and application startup, but avoid expanding it into a full PostgreSQL schema-as-code system. |
 | Prisma migration assistant | 7 | Import Prisma Migrate SQL history and Prisma TypedSQL/raw SQL into `sqlx-js`; classify Prisma Client CRUD/nested-write sites as assisted/manual instead of promising a fully automatic ORM rewrite. |
 | Self-join precision (unqualified ColumnRef) | 4 | `SELECT name FROM users u1 JOIN users u2 ON ...` with unqualified `name` can't be attributed to a specific alias. PG would reject ambiguous unqualified refs anyway, but explicit aliasing currently has no narrowing benefit in self-joins. |
 | Tagged-template literal API (`` sql`SELECT ${x}` ``) | 8 | Restoring sqlx's inline-SQL aesthetic requires either a TS compiler plugin (`ts-patch`) or a Bun preload-time AST rewriter. TS itself hardcodes the first tag argument as `TemplateStringsArray` and refuses to narrow to literal tuples. Significant effort, large UX win. |
-| LSP server | 6 | Realtime diagnostics, hover with column types, autocomplete on schema names. Versioned `prepare --json` diagnostics now provide the cheaper CI/editor integration foundation; a full server still needs separate VS Code / Neovim clients. |
+| LSP server | 5 | Realtime hover and schema autocomplete. Versioned batch JSON, incremental `prepare --watch --jsonl`, and `sqlx-js-diagnostics` already provide the transport for editor problems; a full server still needs separate VS Code / Neovim clients. |
 | Schema-aware `jsonb` runtime validation | 5 | Optional opt-in: pass a Zod / Valibot / ArkType schema, validate rows on read. Currently we are compile-time-only by design. |
 | MySQL backend | 5 | Some runtime clients support it, but MySQL has no `Describe Statement` equivalent. Would need a real SQL parser pass + `INFORMATION_SCHEMA` introspection. |
 | SQLite backend | 4 | SQLite's column types are dynamic. Would require running `EXPLAIN` and a heuristic mapper, or schema-driven inference per-statement. |

package/dist/bin/sqlx-js-diagnostics.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/sqlx-js-diagnostics.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function optionalString(value, name) {
+    if (value !== undefined && typeof value !== "string")
+        throw new Error(`${name} must be a string`);
+}
+function optionalPosition(value, name) {
+    if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+}
+function parsePayload(value) {
+    if (!isRecord(value) || value.formatVersion !== 1 || typeof value.ok !== "boolean" || !Array.isArray(value.diagnostics)) {
+        throw new Error("expected sqlx-js diagnostic formatVersion 1");
+    }
+    const diagnostics = value.diagnostics.map((item, index) => {
+        if (!isRecord(item))
+            throw new Error(`diagnostics[${index}] must be an object`);
+        if (item.severity !== "error" && item.severity !== "warning") {
+            throw new Error(`diagnostics[${index}].severity must be error or warning`);
+        }
+        if (typeof item.phase !== "string")
+            throw new Error(`diagnostics[${index}].phase must be a string`);
+        if (typeof item.message !== "string")
+            throw new Error(`diagnostics[${index}].message must be a string`);
+        optionalString(item.file, `diagnostics[${index}].file`);
+        optionalString(item.code, `diagnostics[${index}].code`);
+        optionalPosition(item.line, `diagnostics[${index}].line`);
+        optionalPosition(item.column, `diagnostics[${index}].column`);
+        return {
+            severity: item.severity,
+            phase: item.phase,
+            message: item.message,
+            ...(item.file !== undefined ? { file: item.file } : {}),
+            ...(item.line !== undefined ? { line: item.line } : {}),
+            ...(item.column !== undefined ? { column: item.column } : {}),
+            ...(item.code !== undefined ? { code: item.code } : {}),
+        };
+    });
+    return { formatVersion: 1, ok: value.ok, diagnostics };
+}
+function githubData(value) {
+    return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+function githubProperty(value) {
+    return githubData(value).replaceAll(":", "%3A").replaceAll(",", "%2C");
+}
+function renderGithub(diagnostic) {
+    const properties = [];
+    if (diagnostic.file)
+        properties.push(`file=${githubProperty(diagnostic.file)}`);
+    if (diagnostic.line !== undefined)
+        properties.push(`line=${diagnostic.line}`);
+    if (diagnostic.column !== undefined)
+        properties.push(`col=${diagnostic.column}`);
+    const propertyText = properties.length > 0 ? ` ${properties.join(",")}` : "";
+    const code = diagnostic.code ? ` ${diagnostic.code}` : "";
+    return `::${diagnostic.severity}${propertyText}::${githubData(`[${diagnostic.phase}${code}] ${diagnostic.message}`)}`;
+}
+function renderUnix(diagnostic) {
+    const clean = (value) => value.replace(/[\r\n]+/g, " ");
+    const file = clean(diagnostic.file ?? "<project>");
+    const line = diagnostic.line ?? 1;
+    const column = diagnostic.column ?? 1;
+    const code = diagnostic.code ? ` ${clean(diagnostic.code)}` : "";
+    return `${file}:${line}:${column}: ${diagnostic.severity}: [${clean(diagnostic.phase)}${code}] ${clean(diagnostic.message)}`;
+}
+function usage() {
+    console.log("usage: sqlx-js-diagnostics github|unix < prepare-diagnostics.json");
+    process.exit(0);
+}
+const format = process.argv[2];
+if (format === "--help" || format === "-h")
+    usage();
+if (format !== "github" && format !== "unix") {
+    console.error("sqlx-js-diagnostics: expected output format github or unix");
+    process.exit(2);
+}
+let input = "";
+for await (const chunk of process.stdin)
+    input += chunk;
+let payload;
+try {
+    payload = parsePayload(JSON.parse(input));
+}
+catch (error) {
+    console.error(`sqlx-js-diagnostics: ${error.message}`);
+    process.exit(2);
+}
+for (const diagnostic of payload.diagnostics) {
+    console.log(format === "github" ? renderGithub(diagnostic) : renderUnix(diagnostic));
+}
+process.exit(payload.ok ? 0 : 1);
+export {};