qubu 0.6.0 → 0.6.2

package/docs/schema/introspection.md

@@ -1,6 +1,6 @@
 # Database introspection
 
-> Read one existing database namespace into explainable catalog data and an optional canonical Snapshot v1 or complete Snapshot v2 without giving Qubu ownership of the connection.
+> Read one existing database namespace into explainable catalog data and a canonical Snapshot v1 without giving Qubu ownership of the connection.
 
 Database introspection is an optional capability exported from
 `qubu/introspection`. It discovers database facts; it does not recreate the
@@ -59,9 +59,10 @@ catalog can later support inspection, source generation, or another snapshot
 format:
 
 ```ts
-import { mapCatalogToSnapshot, readSqliteCatalog } from "qubu/introspection"
+import { mapCatalogToSnapshot } from "qubu/introspection"
+import { readCatalog } from "qubu/introspection/sqlite"
 
-const catalog = await readSqliteCatalog(connection, { namespace: "main" })
+const catalog = await readCatalog(connection, { namespace: "main" })
 const result = mapCatalogToSnapshot(catalog, {
   namespace: "main",
   mode: "strict",
@@ -84,8 +85,8 @@ catalog. Use `createCompleteIntrospectionCatalog()` to materialize and freeze
 all optional collections, then `mapCatalogToCompleteSnapshot()` when an
 adapter-supported family such as views, routines, triggers, partitions,
 collations, comments, or retained opaque and deferred objects must cross the
-strict Snapshot v2 boundary. Snapshot v1 is still selected explicitly by
-`mapCatalogToSnapshot()` and remains table-shaped.
+strict Snapshot v1 boundary. `mapCatalogToSnapshot()` delegates to the complete
+mapper, so the canonical result is always Snapshot v1.
 
 The result is successful only when Snapshot v1 validation succeeds. A failed
 result may retain the partial catalog and structured diagnostics, but it has no
@@ -107,9 +108,9 @@ rename. Pass the previous snapshot or an identity hint when a later diff must
 preserve identity across a rename. See [snapshot diffing](diff.md) for the
 comparison and hint boundary.
 
-The first version selects one namespace: a PostgreSQL schema, MySQL database,
-or SQLite database such as `main`. It does not combine attached databases or
-multiple PostgreSQL schemas into one Snapshot v1 value.
+Each Snapshot v1 result selects one namespace: a PostgreSQL schema, MySQL
+database, or SQLite database such as `main`. It does not combine attached
+databases or multiple PostgreSQL schemas into one value.
 
 ## Strict and lossy output
 
@@ -126,12 +127,20 @@ generated expressions, checks, predicates, and expression index terms remain
 dialect-tagged SQL. Falsy values such as `0`, `false`, `NULL`, and empty
 strings are preserved.
 
+References to nested columns, constraints, and indexes include their owning
+table, view, or domain in the complete Snapshot v1 output. References to
+top-level objects remain unscoped, and table-local backing relationships must
+resolve within the table that contains them. Dialect provenance, extensions,
+native storage, and typed expressions are checked against the selected
+snapshot dialect; arbitrary catalog `data` and `configuration` JSON remains
+opaque.
+
 PostgreSQL readers expose views, materialized views, sequences, enums, domains,
 collations, routines, triggers, policies, partitions, extensions, comments,
 and ownership as typed complete catalog records. `mapCatalogToCompleteSnapshot`
-retains those records in Snapshot v2. The existing `mapCatalogToSnapshot`
-mapper still emits the table-only Snapshot v1 and does not fabricate these
-objects into tables. If a PostgreSQL catalog row lacks the evidence needed for
+retains those records in Snapshot v1. `mapCatalogToSnapshot()` uses the same
+complete mapping and does not fabricate these objects into tables. If a
+PostgreSQL catalog row lacks the evidence needed for
 safe normalization, the reader retains a deferred or opaque record and emits a
 diagnostic.
 
@@ -154,13 +163,13 @@ collations used by the selected tables or columns, and comments.
 
 View definitions come from `INFORMATION_SCHEMA.VIEWS`. The reader cross-
 references each view with its `INFORMATION_SCHEMA.COLUMNS` rows by physical
-table name, so view columns remain attached to the view and Snapshot v2 can
+table name, so view columns remain attached to the view and Snapshot v1 can
 validate their own column IDs. A missing definition or an unresolved
 cross-object reference becomes a deferred record with a diagnostic.
 
 MySQL scheduled events are kept as `CatalogOpaqueObject` records with their
 metadata and definition tagged as opaque SQL. The reader emits an
-`unmodeled-object` warning, and Snapshot v2 retains the record in
+`unmodeled-object` warning, and Snapshot v1 retains the record in
 `opaqueObjects` without treating it as a typed routine, trigger, or migration
 operation.
 
@@ -177,9 +186,8 @@ The reader keeps that metadata as normalized typed data and never evaluates
 database-provided SQL. Optional source generation remains a later, pure step
 with a controlled literal printer.
 
-Use `mapCatalogToCompleteSnapshot()` for the typed MySQL families and its
-opaque or deferred boundaries. Use `mapCatalogToSnapshot()` when the caller
-needs the table-only Snapshot v1.
+Use `mapCatalogToSnapshot()` or `mapCatalogToCompleteSnapshot()` for the typed
+MySQL families and their opaque or deferred boundaries.
 
 ## Diagnostics and safety
 

package/docs/schema/snapshots.md

@@ -14,10 +14,11 @@ const snapshot = createSchemaSnapshot(appSchema)
 const json = encodeSchemaSnapshot(snapshot)
 ```
 
-The v1 envelope contains a format version, an independently versioned dialect
-extension, a versioned naming-policy description, an optional namespace, and
-arrays of tables. Tables, columns, constraints, and indexes are sorted by
-stable logical ID. Physical names are values in the snapshot, not identities:
+The Snapshot v1 envelope contains a format version, an independently versioned
+dialect extension, a versioned naming-policy description, a namespace,
+capability facts, and arrays for every supported object family. Tables,
+columns, constraints, and indexes are sorted by stable logical ID. Physical
+names are values in the snapshot, not identities:
 changing a physical name does not change the TypeScript field or metadata key.
 
 Snapshot data is deliberately not executable Qubu state. Expressions are
@@ -45,6 +46,15 @@ dialect metadata, and broken foreign-key or column references as structured
 diagnostics. It does not call `process.exit()` and has no runtime validation
 library dependency.
 
+References to nested columns, constraints, and indexes carry an explicit
+`owner: { kind, id }` scope. Table columns, constraints, and indexes are owned
+by their table; view columns are owned by their view; and domain constraints
+are owned by their domain. References to top-level objects remain ownerless,
+and the decoder validates each nested scope independently. Dialect metadata is
+checked only in typed snapshot fields. Extension `data`, `configuration`, and
+other opaque JSON payloads are retained as data and are not interpreted as
+typed metadata.
+
 `schemaSnapshotFingerprint()` computes a deterministic content fingerprint from canonical
 JSON. The fingerprint is useful for cache keys and fixture assertions only. It is not
 an entity identity, a rename marker, or migration lineage.
@@ -91,15 +101,15 @@ Snapshot serialization remains separate from database introspection,
 comparison, rename resolution, migration planning, and DDL emission. The
 optional `qubu/introspection` entrypoint can produce the same canonical
 Snapshot v1 data from a user-owned catalog connection. The complete normalized
-catalog can also be encoded as strict Snapshot v2 with the dedicated
-complete-snapshot APIs described in [the catalog model](catalog-model.md).
+catalog can also be encoded with the explicit complete-snapshot APIs described
+in [the catalog model](catalog-model.md).
 Readers and connection lifecycle do not belong to this pure serialization
-layer. Diffing can compare either snapshot version. Resolved diffs feed
+layer. Diffing consumes Snapshot v1. Resolved diffs feed
 migration plans, and approved plans feed DDL emission. The package-wide
 [ownership map](../reference/supported-surface.md#ownership-boundary) keeps
 those pure steps separate from application-owned database execution.
 
 The optional [schema source generator](code-generation.md) consumes a complete,
 non-lossy introspection result and makes its generated schema the next identity
-baseline. It does not replace snapshot serialization or generate Snapshot v2
+baseline. It does not replace snapshot serialization or populate non-table
 object families.

package/docs/schema/storage-and-schema-sql.md

@@ -36,14 +36,19 @@ declaration:
 import { nativeColumn, nativeStorage, table } from "qubu"
 
 const accounts = table("accounts", {
-  handle: nativeColumn(nativeStorage("postgresql", 'citext COLLATE "C"')),
+  handle: nativeColumn(nativeStorage("postgresql", 'citext COLLATE "C"'), {
+    sqlType: "postgres.citext",
+  }),
 })
 ```
 
 `nativeStorage()` preserves the declaration text and freezes the descriptor. The
 `ColumnStorageOf`, `ColumnStorageTypeOf`, `ColumnStorageDialectOf`, and
 `ColumnStorageDeclarationOf` helpers read its metadata. Native storage is
-descriptive. It does not change selection, mutation, or query rendering.
+descriptive. The optional `sqlType` field is the runtime semantic domain passed
+to adapters; provide it for custom domains because the compile-time SQL type is
+not available at runtime. It does not change selection, mutation, or query
+rendering.
 
 ## Render deterministic schema expressions
 

package/docs/sql-semantic-types.md

@@ -89,6 +89,14 @@ operation. This contextual typing does not relabel an expression: comparing a
 `SqlUuid` expression with a `SqlText` expression is still rejected. Cast when
 the database operation intentionally changes domains:
 
+Scalar text functions bind primitive operands automatically, and `coalesce()`
+uses its first expression to type primitive fallbacks:
+
+```ts
+upper("Ada") // UPPER(?)
+coalesce(metrics.label, "Anonymous") // COALESCE("metrics"."label", ?)
+```
+
 ```ts
 import { cast, like, text } from "qubu"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qubu",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/aleclarson/qubu"
@@ -32,6 +32,18 @@
       "types": "./dist/introspection.d.mts",
       "import": "./dist/introspection.mjs"
     },
+    "./introspection/mysql": {
+      "types": "./dist/introspection/mysql.d.mts",
+      "import": "./dist/introspection/mysql.mjs"
+    },
+    "./introspection/postgres": {
+      "types": "./dist/introspection/postgres.d.mts",
+      "import": "./dist/introspection/postgres.mjs"
+    },
+    "./introspection/sqlite": {
+      "types": "./dist/introspection/sqlite.d.mts",
+      "import": "./dist/introspection/sqlite.mjs"
+    },
     "./mysql": {
       "types": "./dist/mysql.d.mts",
       "import": "./dist/mysql.mjs"
@@ -112,6 +124,7 @@
     "test:type-performance": "node ./scripts/test-type-performance.mjs",
     "diff-check": "vitest --run test/diff.test.ts && pnpm --filter @qubu/migrate test -- plan.test.ts",
     "test:bun": "node ./scripts/test-package.mjs --runtime=bun",
+    "test:bun-sql": "bun test adapters/bun-sql/test/bun-sql.test.ts",
     "test:package": "node ./scripts/test-package.mjs",
     "test:workspace-children": "pnpm run build:workspace-packages && node ./scripts/test-workspace-packages.mjs",
     "test:workspace-packages": "pnpm run test:package && pnpm run test:workspace-children",