qubu 0.3.5 → 0.4.1

package/docs/guides/sql-templates.md

@@ -9,11 +9,11 @@ substitution as a parameter. This includes strings, numbers, objects, arrays,
 and `null`:
 
 ```ts
-import { integer, render, sql, table, text } from 'qubu'
+import { integer, render, sql, table, text } from "qubu"
 
-const users = table('users', { name: text() })
-const posts = table('posts', { id: integer() })
-const search = 'Ada%'
+const users = table("users", { name: text() })
+const posts = table("posts", { id: integer() })
+const search = "Ada%"
 const predicate = sql`${users.name} LIKE ${search}`
 
 render(predicate)
@@ -33,16 +33,12 @@ statement. Parameters keep one placeholder sequence across nested templates
 and queries:
 
 ```ts
-import { eq, from, render, select, sql, where } from 'qubu'
-import { postgresDialect } from 'qubu/postgres'
+import { eq, from, render, select, sql, where } from "qubu"
+import { postgresDialect } from "qubu/postgres"
 
-const selectedNames = select(
-  { displayName: users.name },
-  from(users),
-  where(eq(users.name, 'Ada'))
-)
+const selectedNames = select({ displayName: users.name }, from(users), where(eq(users.name, "Ada")))
 
-const exists = sql`EXISTS (${selectedNames}) AND ${users.name} <> ${'root'}`
+const exists = sql`EXISTS (${selectedNames}) AND ${users.name} <> ${"root"}`
 
 render(exists, postgresDialect())
 // {
@@ -62,8 +58,8 @@ An unannotated template has application output `unknown` and SQL domain
 named projection:
 
 ```ts
-import { from, select, sql } from 'qubu'
-import type { SqlText } from 'qubu'
+import { from, select, sql } from "qubu"
+import type { SqlText } from "qubu"
 
 const normalizedName = sql.type<string, SqlText>()`LOWER(${users.name})`
 
@@ -98,11 +94,11 @@ Do not use a dotted string as an identifier. Pass each part to
 syntax that cannot use a fixed template segment:
 
 ```ts
-import { sql } from 'qubu'
-import { identifier, unsafeExpression } from 'qubu/core'
+import { sql } from "qubu"
+import { identifier, unsafeExpression } from "qubu/core"
 
-const sortColumn = 'display_name'
-const direction = 'DESC' as const
+const sortColumn = "display_name"
+const direction = "DESC" as const
 
 const ordering = sql`ORDER BY ${identifier(sortColumn)} ${unsafeExpression(direction)}`
 ```
@@ -120,8 +116,8 @@ those facts from unchecked template text.
 Use a built-in expression as the substitution when its semantics matter:
 
 ```ts
-import { count, sql } from 'qubu'
-import type { SqlInteger } from 'qubu'
+import { count, sql } from "qubu"
+import type { SqlInteger } from "qubu"
 
 const postCount = sql.type<number, SqlInteger>()`${count(posts.id)}`
 ```
@@ -140,13 +136,13 @@ Declare a capability when the template text itself uses dialect-specific
 syntax:
 
 ```ts
-import { sql } from 'qubu'
-import { withDialectCapability } from 'qubu/core'
-import type { SqlBoolean } from 'qubu'
+import { sql } from "qubu"
+import { withDialectCapability } from "qubu/core"
+import type { SqlBoolean } from "qubu"
 
 const postgresMatch = withDialectCapability(
   sql.type<boolean, SqlBoolean>()`${users.name} ILIKE ${search}`,
-  'ilike'
+  "ilike",
 )
 ```
 

package/docs/guides/vite-plugin.md

@@ -11,8 +11,8 @@ Add the plugin to Vite and add the matching ambient declarations to TypeScript:
 
 ```ts
 // vite.config.ts
-import { defineConfig } from 'vite'
-import { qubu } from 'qubu/vite'
+import { defineConfig } from "vite"
+import { qubu } from "qubu/vite"
 
 export default defineConfig({
   plugins: [qubu()],
@@ -36,24 +36,20 @@ ambient value and type declarations for the TypeScript compiler.
 Put the directive in the module's initial directive prologue:
 
 ```ts
-'use qubu'
+"use qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
 
-const query = select(
-  { id: users.id, name: users.name },
-  from(users),
-  where(eq(users.id, 42))
-)
+const query = select({ id: users.id, name: users.name }, from(users), where(eq(users.id, 42)))
 ```
 
 Conceptually, the transform adds the imports that this module references:
 
 ```ts
-import { eq, from, integer, select, table, text, where } from 'qubu'
+import { eq, from, integer, select, table, text, where } from "qubu"
 ```
 
 Existing imports remain valid. The transform does not rewrite member properties,
@@ -63,10 +59,10 @@ strings, comments, or names outside the public Qubu global catalog.
 
 ```ts
 qubu({
-  module: 'qubu',
-  include: id => id.includes('/src/'),
+  module: "qubu",
+  include: (id) => id.includes("/src/"),
   exclude: /\.stories\./,
-  globals: ['select', 'from', 'where', 'eq', 'table'],
+  globals: ["select", "from", "where", "eq", "table"],
 })
 ```
 

package/docs/index.md

@@ -29,6 +29,8 @@ define a table, build a `SELECT`, and inspect its SQL and parameters.
   `DELETE` statements.
 - [Use Qubu tables with Drizzle](guides/drizzle.md) while moving query call
   sites without duplicating schema declarations.
+- [Use Qubu with Better Auth](guides/better-auth.md) with plugin-aware schema
+  derivation and a native transactional database adapter.
 - [Extend Qubu](guides/extensions/overview.md) with a custom source, clause,
   dialect policy, or typed expression.
 - [Read JSON scalars](guides/json.md) from structured JSON paths.
@@ -82,18 +84,14 @@ needs to preserve a fact across composition:
 ## A small example
 
 ```ts
-import { eq, from, integer, render, select, table, text, where } from 'qubu'
+import { eq, from, integer, render, select, table, text, where } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
 
-const query = select(
-  { id: users.id, name: users.name },
-  from(users),
-  where(eq(users.id, 7))
-)
+const query = select({ id: users.id, name: users.name }, from(users), where(eq(users.id, 7)))
 
 render(query)
 // {

package/docs/query-model/fragments.md

@@ -54,20 +54,9 @@ Parameter values are not fragment metadata. A renderer calls
 `context.parameter(value)`, and `render()` collects values in placeholder order:
 
 ```ts
-import {
-  and,
-  eq,
-  from,
-  integer,
-  like,
-  render,
-  select,
-  table,
-  text,
-  where,
-} from 'qubu'
-
-const users = table('users', {
+import { and, eq, from, integer, like, render, select, table, text, where } from "qubu"
+
+const users = table("users", {
   id: integer(),
   name: text(),
 })
@@ -75,7 +64,7 @@ const users = table('users', {
 const query = select(
   { id: users.id },
   from(users),
-  where(and(eq(users.id, 7), like(users.name, '%Ada%')))
+  where(and(eq(users.id, 7), like(users.name, "%Ada%"))),
 )
 
 render(query)

package/docs/query-model/result-shapes.md

@@ -7,9 +7,9 @@
 An object projection uses its keys as result names:
 
 ```ts
-import { from, integer, select, table, text, upper } from 'qubu'
+import { from, integer, select, table, text, upper } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
@@ -19,7 +19,7 @@ const query = select(
     id: users.id,
     displayName: upper(users.name),
   },
-  from(users)
+  from(users),
 )
 
 type Row = typeof query.row
@@ -31,12 +31,9 @@ shaped result. Reserve `all(source)` for a whole-source result contract. It
 expands to named columns, so the SQL columns and inferred row keys stay aligned:
 
 ```ts
-import { all, from, select, upper } from 'qubu'
+import { all, from, select, upper } from "qubu"
 
-const query = select(
-  { ...all(users), normalizedName: upper(users.name) },
-  from(users)
-)
+const query = select({ ...all(users), normalizedName: upper(users.name) }, from(users))
 ```
 
 When a query becomes a CTE or derived table, its row shape becomes the columns
@@ -53,13 +50,13 @@ source widens with `null`, while an expression with its own non-null result
 contract can stay non-null:
 
 ```ts
-import { count, eq, from, integer, leftJoin, select, table, text } from 'qubu'
+import { count, eq, from, integer, leftJoin, select, table, text } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
-const posts = table('posts', {
+const posts = table("posts", {
   id: integer(),
   authorId: integer(),
   title: text(),
@@ -72,7 +69,7 @@ const query = select(
     postCount: count(posts.id),
   },
   from(users),
-  leftJoin(posts, eq(users.id, posts.authorId))
+  leftJoin(posts, eq(users.id, posts.authorId)),
 )
 
 type Row = typeof query.row
@@ -89,9 +86,9 @@ expression with non-null branches can return a non-null result.
 result includes `null` when the query may return no rows:
 
 ```ts
-import { fetchFirst, from, scalar, select, table, value } from 'qubu'
+import { fetchFirst, from, scalar, select, table, value } from "qubu"
 
-const users = table('users', { id: integer() })
+const users = table("users", { id: integer() })
 const firstUser = select({ id: users.id }, from(users), fetchFirst(1))
 
 const firstId = scalar(firstUser)

package/docs/query-model/source-scope.md

@@ -13,12 +13,12 @@ Qubu reports a missing source when a query selects a column from a table that
 does not appear in the query:
 
 ```ts
-import { from, integer, select, table, text } from 'qubu'
+import { from, integer, select, table, text } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
 })
-const posts = table('posts', {
+const posts = table("posts", {
   id: integer(),
   title: text(),
 })
@@ -31,12 +31,12 @@ Add the source that owns the column, or join it with a condition that refers to
 both sources:
 
 ```ts
-import { eq, from, innerJoin, integer, select, table } from 'qubu'
+import { eq, from, innerJoin, integer, select, table } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
 })
-const posts = table('posts', {
+const posts = table("posts", {
   id: integer(),
   authorId: integer(),
 })
@@ -44,7 +44,7 @@ const posts = table('posts', {
 const query = select(
   { userId: users.id, postId: posts.id },
   from(users),
-  innerJoin(posts, eq(users.id, posts.authorId))
+  innerJoin(posts, eq(users.id, posts.authorId)),
 )
 ```
 
@@ -54,14 +54,14 @@ Aliases, CTEs, derived queries, and custom sources expose new source identities.
 Use their columns after wrapping the original source:
 
 ```ts
-import { alias, from, integer, select, table, text } from 'qubu'
+import { alias, from, integer, select, table, text } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
 
-const author = alias(users, 'author')
+const author = alias(users, "author")
 const query = select({ name: author.name }, from(author))
 ```
 
@@ -72,10 +72,10 @@ The same rule applies to a CTE or derived query. A query's selected row becomes
 the set of columns exposed by its new source:
 
 ```ts
-import { alias, from, lower, select } from 'qubu'
+import { alias, from, lower, select } from "qubu"
 
 const names = select({ name: lower(users.name) }, from(users))
-const namesSource = alias(names, 'names')
+const namesSource = alias(names, "names")
 
 const query = select({ name: namesSource.name }, from(namesSource))
 ```
@@ -90,35 +90,31 @@ Use `customSource()` for a table-valued function or another relation that
 definitions, and complete relation renderer:
 
 ```ts
-import { eq, from, integer, select, text, where } from 'qubu'
-import { identifier } from 'qubu/core'
-import { customSource } from 'qubu/schema'
+import { eq, from, integer, select, text, where } from "qubu"
+import { identifier } from "qubu/core"
+import { customSource } from "qubu/schema"
 
 const entries = customSource({
   identity: {
-    sourceKind: 'table-function',
-    name: 'json_each',
-    alias: 'entry',
+    sourceKind: "table-function",
+    name: "json_each",
+    alias: "entry",
   },
-  sourceKind: 'table-function',
-  reference: identifier('entry'),
+  sourceKind: "table-function",
+  reference: identifier("entry"),
   columns: {
     key: integer(),
     value: text({ nullable: true }),
   },
   render(context) {
-    context.append('json_each(')
+    context.append("json_each(")
     context.parameter('{"a":1}')
-    context.append(') AS ')
-    context.render(identifier('entry'))
+    context.append(") AS ")
+    context.render(identifier("entry"))
   },
 })
 
-const query = select(
-  { value: entries.value },
-  from(entries),
-  where(eq(entries.key, 7))
-)
+const query = select({ value: entries.value }, from(entries), where(eq(entries.key, 7)))
 ```
 
 `identity` is the type-level source key. `reference` is the SQL qualifier used
@@ -135,20 +131,10 @@ Use `correlate()` when an inner query intentionally reads a source from its
 enclosing query. The provision changes type checking but emits no SQL:
 
 ```ts
-import {
-  correlate,
-  crossJoin,
-  eq,
-  from,
-  integer,
-  lateral,
-  select,
-  table,
-  where,
-} from 'qubu'
-
-const users = table('users', { id: integer() })
-const posts = table('posts', {
+import { correlate, crossJoin, eq, from, integer, lateral, select, table, where } from "qubu"
+
+const users = table("users", { id: integer() })
+const posts = table("posts", {
   id: integer(),
   authorId: integer(),
 })
@@ -157,15 +143,11 @@ const recentPost = select(
   { id: posts.id },
   from(posts),
   correlate(users),
-  where(eq(posts.authorId, users.id))
+  where(eq(posts.authorId, users.id)),
 )
 
-const recent = lateral(recentPost, 'recent_post')
-const query = select(
-  { userId: users.id, postId: recent.id },
-  from(users),
-  crossJoin(recent)
-)
+const recent = lateral(recentPost, "recent_post")
+const query = select({ userId: users.id, postId: recent.id }, from(users), crossJoin(recent))
 ```
 
 The inner query consumes `posts` locally. The enclosing `users` source satisfies

package/docs/reference/mysql-snapshot.md

@@ -7,10 +7,7 @@
 Import the adapter from the optional snapshot entrypoint:
 
 ```ts
-import {
-  createMysqlSchemaSnapshot,
-  tryCreateMysqlSchemaSnapshot,
-} from 'qubu/snapshot'
+import { createMysqlSchemaSnapshot, tryCreateMysqlSchemaSnapshot } from "qubu/snapshot"
 
 const snapshot = createMysqlSchemaSnapshot(appSchema)
 const result = tryCreateMysqlSchemaSnapshot(appSchema)
@@ -44,7 +41,7 @@ a schema may include a MySQL engine or version-specific feature:
 const result = tryCreateMysqlSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
-    console.error(issue.path.join('.'), issue.code, issue.message)
+    console.error(issue.path.join("."), issue.code, issue.message)
   }
 }
 ```

package/docs/reference/postgres-snapshot.md

@@ -11,7 +11,7 @@ import {
   createSchemaSnapshot,
   createPostgresSchemaSnapshot,
   postgresSnapshotAdapter,
-} from 'qubu/snapshot'
+} from "qubu/snapshot"
 
 const snapshot = createPostgresSchemaSnapshot(appSchema)
 // Equivalent: createSchemaSnapshot(appSchema, { adapter: postgresSnapshotAdapter })
@@ -46,12 +46,12 @@ schema and application boundaries.
 Use the non-throwing form when a schema may contain a server-specific feature:
 
 ```ts
-import { tryCreatePostgresSchemaSnapshot } from 'qubu/snapshot'
+import { tryCreatePostgresSchemaSnapshot } from "qubu/snapshot"
 
 const result = tryCreatePostgresSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
-    console.error(issue.path.join('.'), issue.code, issue.message)
+    console.error(issue.path.join("."), issue.code, issue.message)
   }
 }
 ```

package/docs/reference/sqlite-snapshot.md

@@ -5,10 +5,7 @@
 Import the adapter from the optional snapshot entrypoint:
 
 ```ts
-import {
-  createSqliteSchemaSnapshot,
-  tryCreateSqliteSchemaSnapshot,
-} from 'qubu/snapshot'
+import { createSqliteSchemaSnapshot, tryCreateSqliteSchemaSnapshot } from "qubu/snapshot"
 
 const snapshot = createSqliteSchemaSnapshot(appSchema)
 const result = tryCreateSqliteSchemaSnapshot(appSchema)
@@ -42,7 +39,7 @@ schema may include a feature that depends on a SQLite version or table shape:
 const result = tryCreateSqliteSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
-    console.error(issue.path.join('.'), issue.code, issue.message)
+    console.error(issue.path.join("."), issue.code, issue.message)
   }
 }
 ```

package/docs/reference/supported-surface.md

@@ -4,32 +4,32 @@
 
 ## Package entrypoints
 
-| Import                  | Kind             | Use it for                                                                                                       |
-| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `qubu`                  | Runtime          | Ordinary query and schema definitions, reads, writes, SQL templates, rendering, EXPLAIN, and execution contracts |
-| `qubu/core`             | Runtime          | Fragment and rendering primitives, dialect construction, SQL types, and extension constructors                   |
-| `qubu/codegen`          | Runtime          | Deterministic machine-owned TypeScript schemas from complete, non-lossy introspection                            |
-| `qubu/ddl`              | Runtime          | DDL preflight and deterministic PostgreSQL, SQLite, or MySQL emission from a migration plan                      |
-| `qubu/diff`             | Runtime          | Canonical Snapshot v1 or v2 comparison, rename hints, suggestions, and safety diagnostics                        |
-| `qubu/drizzle`          | Runtime          | Shared Drizzle conversion errors and dialect types                                                               |
-| `qubu/introspection`    | Runtime          | Catalog readers, normalized catalogs, and mapping to Snapshot v1 or v2                                           |
-| `qubu/migration`        | Runtime          | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL                     |
-| `qubu/mysql`            | Runtime          | The MySQL query dialect policy                                                                                   |
-| `qubu/postgres`         | Runtime          | PostgreSQL query dialect helpers such as `postgresDialect()` and `ilike()`                                       |
-| `qubu/schema`           | Runtime          | Advanced schema metadata, storage and constraint models, source models, and schema-expression extensions         |
-| `qubu/snapshot`         | Runtime          | Canonical Snapshot v1 and v2 traversal, encoding, decoding, diagnostics, and digests                             |
-| `qubu/sqlite`           | Runtime          | The SQLite query dialect policy                                                                                  |
-| `qubu/vite`             | Runtime          | The optional `qubu()` Vite compiler hint                                                                         |
-| `qubu/package.json`     | JSON             | The published package manifest                                                                                   |
-| `qubu/drizzle/mysql`    | Runtime          | Runtime conversion from Qubu schemas to MySQL Drizzle tables                                                     |
-| `qubu/drizzle/postgres` | Runtime          | Runtime conversion from Qubu schemas to PostgreSQL Drizzle tables                                                |
-| `qubu/drizzle/sqlite`   | Runtime          | Runtime conversion from Qubu schemas to SQLite Drizzle tables                                                    |
-| `qubu/globals`          | TypeScript types | Opt-in ambient declarations for directive-bearing modules                                                        |
-
-The package validator confirms 17 runtime entrypoints, 18 type entrypoints,
-`qubu/package.json` as JSON, and `qubu/globals` as type-only. Concrete dialect
-constructors live on their database subpaths. The root renderer uses Qubu's
-standard SQL policy by default.
+| Import                   | Kind             | Use it for                                                                                                       |
+| ------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `qubu`                   | Runtime          | Ordinary query and schema definitions, reads, writes, SQL templates, rendering, EXPLAIN, and execution contracts |
+| `qubu/core`              | Runtime          | Fragment and rendering primitives, dialect construction, SQL types, and extension constructors                   |
+| `qubu/codegen`           | Runtime          | Deterministic machine-owned TypeScript schemas from complete, non-lossy introspection                            |
+| `qubu/ddl`               | Runtime          | DDL preflight and deterministic PostgreSQL, SQLite, or MySQL emission from a migration plan                      |
+| `qubu/diff`              | Runtime          | Canonical Snapshot v1 or v2 comparison, rename hints, suggestions, and safety diagnostics                        |
+| `qubu/introspection`     | Runtime          | Catalog readers, normalized catalogs, and mapping to Snapshot v1 or v2                                           |
+| `qubu/migration`         | Runtime          | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL                     |
+| `qubu/mysql`             | Runtime          | The MySQL query dialect policy                                                                                   |
+| `qubu/postgres`          | Runtime          | PostgreSQL query dialect helpers such as `postgresDialect()` and `ilike()`                                       |
+| `qubu/schema`            | Runtime          | Advanced schema metadata, storage and constraint models, source models, and schema-expression extensions         |
+| `qubu/snapshot`          | Runtime          | Canonical Snapshot v1 and v2 traversal, encoding, decoding, diagnostics, and digests                             |
+| `qubu/sqlite`            | Runtime          | The SQLite query dialect policy                                                                                  |
+| `qubu/vite`              | Runtime          | The optional `qubu()` Vite compiler hint                                                                         |
+| `qubu/package.json`      | JSON             | The published package manifest                                                                                   |
+| `@qubu/drizzle`          | Runtime          | Shared Drizzle conversion errors and dialect types                                                               |
+| `@qubu/drizzle/mysql`    | Runtime          | Runtime conversion from Qubu schemas to MySQL Drizzle tables                                                     |
+| `@qubu/drizzle/postgres` | Runtime          | Runtime conversion from Qubu schemas to PostgreSQL Drizzle tables                                                |
+| `@qubu/drizzle/sqlite`   | Runtime          | Runtime conversion from Qubu schemas to SQLite Drizzle tables                                                    |
+| `@qubu/better-auth`      | Runtime          | Better Auth schema derivation and native PostgreSQL, MySQL, and SQLite adapter behavior                          |
+| `qubu/globals`           | TypeScript types | Opt-in ambient declarations for directive-bearing modules                                                        |
+
+The package validator checks every declared entrypoint in each packed workspace
+package. Concrete dialect constructors live on their database subpaths. The
+root renderer uses Qubu's standard SQL policy by default.
 
 Snapshot dialect behavior is documented in the [PostgreSQL](postgres-snapshot.md),
 [SQLite](sqlite-snapshot.md), and [MySQL](mysql-snapshot.md) support matrices.
@@ -70,13 +70,13 @@ Snapshot creation, diffing, migration planning, and DDL emission are pure.
 interfaces the application provides. Qubu can emit DDL, but it never applies
 that DDL to a database.
 
-| Boundary                 | Qubu side                                                                                                                                                                                                                                                                                                                         | Application side                                                                                                                                                                                                                                                                |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Query rendering          | Builds a typed query and renders SQL text with ordered raw parameter values                                                                                                                                                                                                                                                       | Keeps the runtime database schema aligned with query definitions and validates any dynamic syntax passed to an unsafe helper                                                                                                                                                    |
-| Query execution          | Binds an adapter with `qubu()` when requested; renders and passes statements to `QueryAdapter`, `ExplainableQueryAdapter`, or a read-only `StreamingQueryAdapter`; scopes `db.transaction()` callbacks through `TransactionalQueryAdapter`; returns `ExecutionResult`, `ExplainResult`, rows, or an adapter-owned `AsyncIterable` | Owns the adapter, driver, connections, pools, cursors, stream cleanup, transaction begin/commit/rollback, savepoints, retries, parameter encoding, application-row and plan-row decoding, backpressure, cancellation behavior, driver error translation, and database lifecycle |
-| Catalog introspection    | Selects fixed parameterized catalog queries, normalizes rows, and maps catalog data to snapshots                                                                                                                                                                                                                                  | Supplies `CatalogConnection`, credentials, already-decoded catalog rows, logging, and connection lifecycle                                                                                                                                                                      |
-| Schema source generation | Prints deterministic TypeScript from complete, non-lossy Snapshot v1 introspection without writing files                                                                                                                                                                                                                          | Owns generated-file writes, replacement policy, hand-edit merging, and CLI integration                                                                                                                                                                                          |
-| Schema changes           | Creates snapshots, compares them, builds deterministic migration plans, and emits DDL from approved plans with preflight diagnostics                                                                                                                                                                                              | Reviews decisions, executes or rolls back statements, acquires locks, manages transactions and migration journals, and owns database lifecycle                                                                                                                                  |
+| Boundary                 | Qubu side                                                                                                                                                                                                                                                                      | Application side                                                                                                                                                                                                                                                             |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Query rendering          | Builds a typed query and renders SQL text with ordered raw parameter values                                                                                                                                                                                                    | Keeps the runtime database schema aligned with query definitions and validates any dynamic syntax passed to an unsafe helper                                                                                                                                                 |
+| Query execution          | Binds an adapter with `qubu()` when requested; passes rendered statements and result shapes to execution adapters; applies registered logical field decoders to buffered or streamed object rows; scopes transaction callbacks; returns typed results, plans, rows, or streams | Owns the adapter, driver, connections, pools, cursors, stream cleanup, transactions, savepoints, retries, parameter encoding, proprietary row normalization, decoder policy, plan-row decoding, backpressure, cancellation, driver error translation, and database lifecycle |
+| Catalog introspection    | Selects fixed parameterized catalog queries, normalizes rows, and maps catalog data to snapshots                                                                                                                                                                               | Supplies `CatalogConnection`, credentials, already-decoded catalog rows, logging, and connection lifecycle                                                                                                                                                                   |
+| Schema source generation | Prints deterministic TypeScript from complete, non-lossy Snapshot v1 introspection without writing files                                                                                                                                                                       | Owns generated-file writes, replacement policy, hand-edit merging, and CLI integration                                                                                                                                                                                       |
+| Schema changes           | Creates snapshots, compares them, builds deterministic migration plans, and emits DDL from approved plans with preflight diagnostics                                                                                                                                           | Reviews decisions, executes or rolls back statements, acquires locks, manages transactions and migration journals, and owns database lifecycle                                                                                                                               |
 
 Start with [Dialects and execution](../dialects-and-execution.md) for the query
 adapter contract. The schema path is documented in [Canonical schema

package/docs/schema/catalog-model.md

@@ -12,7 +12,7 @@ families and an immutable materializer:
 import {
   createCompleteIntrospectionCatalog,
   mapCatalogToCompleteSnapshot,
-} from 'qubu/introspection'
+} from "qubu/introspection"
 
 const completeCatalog = createCompleteIntrospectionCatalog(catalog)
 const result = mapCatalogToCompleteSnapshot(completeCatalog)
@@ -36,10 +36,7 @@ references and are not used as logical IDs.
 `qubu/snapshot` provides the strict complete format as a separate API:
 
 ```ts
-import {
-  decodeCompleteSchemaSnapshot,
-  encodeCompleteSchemaSnapshot,
-} from 'qubu/snapshot'
+import { decodeCompleteSchemaSnapshot, encodeCompleteSchemaSnapshot } from "qubu/snapshot"
 
 const encoded = encodeCompleteSchemaSnapshot(snapshotV2)
 const decoded = decodeCompleteSchemaSnapshot(encoded)