qubu 0.6.1 → 0.6.2

package/docs/reference/supported-surface.md

@@ -9,15 +9,15 @@
 | `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/diff`                               | Runtime          | Canonical Snapshot v1 or v2 comparison, rename hints, suggestions, and safety diagnostics                        |
-| `qubu/introspection`                      | Runtime          | Shared catalog contracts, normalized catalog models, diagnostics, and mapping to Snapshot v1 or v2               |
+| `qubu/diff`                               | Runtime          | Canonical Snapshot v1 comparison, rename hints, suggestions, and safety diagnostics                              |
+| `qubu/introspection`                      | Runtime          | Shared catalog contracts, normalized catalog models, diagnostics, and mapping to Snapshot v1                     |
 | `qubu/introspection/postgres`             | Runtime          | PostgreSQL catalog reader and catalog queries for one selected namespace                                         |
 | `qubu/introspection/sqlite`               | Runtime          | SQLite catalog reader and catalog queries for one selected namespace                                             |
 | `qubu/introspection/mysql`                | Runtime          | MySQL catalog reader and catalog queries for one selected namespace                                              |
 | `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 fingerprints                        |
+| `qubu/snapshot`                           | Runtime          | Canonical Snapshot v1 traversal, encoding, decoding, diagnostics, and fingerprints                               |
 | `qubu/snapshot/mysql`                     | Runtime          | MySQL snapshot adapter, schema dialect, and convenience creators                                                 |
 | `qubu/snapshot/postgres`                  | Runtime          | PostgreSQL snapshot adapter, schema dialect, and convenience creators                                            |
 | `qubu/snapshot/sqlite`                    | Runtime          | SQLite snapshot adapter, schema dialect, affinity helper, and convenience creators                               |
@@ -25,6 +25,7 @@
 | `qubu/vite`                               | Runtime          | The optional `qubu()` Vite compiler hint                                                                         |
 | `qubu/package.json`                       | JSON             | The published package manifest                                                                                   |
 | `@qubu/migrate`                           | Runtime          | Migration compiler format identity and shared plan types                                                         |
+| `@qubu/pgvector`                          | Runtime          | PostgreSQL pgvector columns, dense-vector codecs, distance expressions, and HNSW/IVFFlat index metadata          |
 | `@qubu/migrate/plan`                      | Runtime          | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL                     |
 | `@qubu/migrate/ddl`                       | Runtime          | DDL preflight and generic emission from a migration plan and supplied schema dialect                             |
 | `@qubu/migrate/ddl/postgres`              | Runtime          | PostgreSQL DDL emission from an approved migration plan                                                          |
@@ -78,14 +79,14 @@ entrypoint table.
 | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Schema values        | `table`, immutable `schema` registries with namespaces, portable and dialect-native column storage descriptors, canonical default and generated-column metadata, identity descriptors, named primary, candidate-key, nullable unique, foreign-key, and check constraints, physical object names, included-column indexes, typed dialect extensions, and typed column helpers             |
 | Read queries         | Named projections, spreadable source columns, aliases, joins, typed custom and LATERAL `FROM` sources, correlated subqueries, `WHERE`, grouping with declared-key proofs, `HAVING`, ordering, window expressions, distinctness, pagination, row locking, ordinary and recursive CTEs, subqueries, and set operations                                                                     |
-| Expressions          | Comparison, boolean, arithmetic, null, range, membership, aggregate, window, string, JSON scalar reads, definition-backed and raw casts, cases, parameterized SQL templates, custom expressions, and branded deterministic schema expressions                                                                                                                                            |
+| Expressions          | Comparison, boolean, arithmetic, null, range, membership, aggregate, window, string, JSON scalar reads and typed nested JSON query results, definition-backed and raw casts, cases, parameterized SQL templates, custom expressions, and branded deterministic schema expressions                                                                                                        |
 | SQL type metadata    | Portable domains and capabilities, physical column storage descriptors, `SqlTypeOf`, projected SQL type maps, `SourceLike` and `TableLike` field constraints, contextual literals, typed extension values, calls, and casts, plus a permissive `SqlUnknown` fallback                                                                                                                     |
-| Write queries        | `INSERT` values, defaults, and selects; typed `UPDATE`, PostgreSQL `UPDATE ... FROM`, and `DELETE`; typed assignments; `RETURNING`; and explicit unrestricted-write opt-in                                                                                                                                                                                                               |
+| Write queries        | `INSERT` values, defaults, and selects; typed `UPDATE`, PostgreSQL `UPDATE ... FROM`, and `DELETE`; typed assignments; PostgreSQL/SQLite conflict clauses; MySQL duplicate-key updates and incoming rows; `RETURNING` on supporting dialects; and explicit unrestricted-write opt-in                                                                                                     |
 | Rendering            | Standard, PostgreSQL, SQLite, MySQL, and user-created policies for identifiers, placeholders, pagination, row locking, JSON, logical cast targets, schema literals, and EXPLAIN options                                                                                                                                                                                                  |
 | Execution boundary   | `QueryAdapter`, opt-in `ExplainableQueryAdapter`, `StreamingQueryAdapter`, and `TransactionalQueryAdapter` capabilities, bound clients from `qubu()`, structured results from `execute()` or `db.execute()`, row-only results from `executeRows()` or `db.rows()`, typed read streams from `stream()` or `db.stream()`, and adapter-decoded plan rows from `explain()` or `db.explain()` |
-| Snapshots            | Pure Snapshot v1 and v2 creation, canonical encoding and strict decoding, immutable data, diagnostics, and FNV change-detection fingerprints                                                                                                                                                                                                                                             |
+| Snapshots            | Pure Snapshot v1 creation, canonical encoding and strict decoding, immutable data, diagnostics, and FNV change-detection fingerprints                                                                                                                                                                                                                                                    |
 | Introspection        | PostgreSQL, SQLite, and MySQL catalog readers for one selected namespace, normalized catalog data, structured diagnostics, and strict or explicit lossy snapshot mapping                                                                                                                                                                                                                 |
-| Snapshot diffing     | Pure Snapshot v1 and v2 comparison, explicit rename evidence, non-authoritative suggestions, and safety diagnostics                                                                                                                                                                                                                                                                      |
+| Snapshot diffing     | Pure Snapshot v1 comparison, explicit rename evidence, non-authoritative suggestions, and safety diagnostics                                                                                                                                                                                                                                                                             |
 | Migration planning   | Pure, dialect-neutral plans with stable ordering, dependency edges, preconditions, explicit review decisions, and tagged custom SQL                                                                                                                                                                                                                                                      |
 | DDL emission         | Preflight plus deterministic PostgreSQL, SQLite, and MySQL statements from an approved `MigrationPlan` and matching `SchemaDialect`                                                                                                                                                                                                                                                      |
 | Migration operations | Strict artifacts and baselines, authoritative programs, repository and journal validation, adapter capability preflight, execution, status/drift, reconciliation, SQLite bootstrap, and complete PostgreSQL bootstrap with standalone enum ordering                                                                                                                                      |

package/docs/schema/catalog-model.md

@@ -31,25 +31,38 @@ IDs are evidence selected by the adapter's identity policy. PostgreSQL OIDs,
 SQLite implementation names, and similar catalog keys stay in current-run
 references and are not used as logical IDs.
 
-## Snapshot v2
+## Snapshot v1
 
 `qubu/snapshot` provides the strict complete format as a separate API:
 
 ```ts
 import { decodeCompleteSchemaSnapshot, encodeCompleteSchemaSnapshot } from "qubu/snapshot"
 
-const encoded = encodeCompleteSchemaSnapshot(snapshotV2)
+const encoded = encodeCompleteSchemaSnapshot(snapshotV1)
 const decoded = decodeCompleteSchemaSnapshot(encoded)
 ```
 
-Snapshot v2 uses the same `qubu-schema` envelope with `version: 2`. Its
+Snapshot v1 uses the same `qubu-schema` envelope with `version: 1`. Its
 namespace, capability facts, object-family arrays, cross-object references,
 provenance, typed dialect extensions, and deferred/opaque boundaries are
 strictly validated. Arrays are ordered by logical ID (with ordinal sequences
 and index terms ordered by their semantic position), and the fingerprint is computed
 from the deterministic encoding.
 
-Snapshot v1 remains a separate strict format. `decodeSchemaSnapshot` still
-accepts only v1 and continues to reject unknown fields and future versions;
-v2 callers must select `decodeCompleteSchemaSnapshot` explicitly. Neither
-snapshot format evaluates database-provided SQL.
+Normalized references to nested catalog objects retain their owner scope. A
+table-local index or constraint reference is mapped with
+`owner: { kind: "table", id }`; view columns use the view kind and ID; domain
+constraints use the domain kind and ID. The legacy `tableId` shorthand on
+catalog entity references is converted to that owner form at the Snapshot v1
+boundary. Top-level references have no owner. This scope prevents equal child
+IDs from different tables or object families from overwriting one another.
+
+Catalog extension payloads and configuration records are opaque JSON. Their
+keys and values are preserved through normalization and canonical encoding;
+objects inside those payloads are not treated as Snapshot expressions or
+native storage declarations.
+
+Snapshot v1 is the only strict schema snapshot format. `decodeSchemaSnapshot`
+and `decodeCompleteSchemaSnapshot` both validate the same version-1 envelope,
+reject unknown fields and future versions, and never evaluate database-provided
+SQL.

package/docs/schema/code-generation.md

@@ -135,6 +135,6 @@ module does not look complete by omission.
 
 The entrypoint does not provide a CLI, filesystem ownership, live driver
 integration, multiple namespaces, runtime schema materialization, migrations,
-DDL, Snapshot v2 object generation, or hand-edit merging. Use
+DDL, non-table object generation, or hand-edit merging. Use
 [Database introspection](introspection.md) for the catalog boundary and
 [Canonical schema snapshots](snapshots.md) for the identity artifact.

package/docs/schema/diff.md

@@ -1,6 +1,6 @@
 # Snapshot diffing
 
-> Compare canonical Snapshot v1 or v2 values and review identity changes before a later planning step.
+> Compare canonical Snapshot v1 values and review identity changes before a later planning step.
 
 The optional `qubu/diff` entrypoint compares immutable snapshot data. It does
 not open a connection, render SQL, execute a change, or infer migration history.
@@ -57,7 +57,7 @@ an `ambiguous` diagnostic and leaves both operations visible for review.
 
 Removing an object is marked `destructive`. Narrowing nullability, changing
 storage, removing a value, or changing a constraint can also receive that
-classification. Opaque and deferred Snapshot v2 records remain visible as
+classification. Opaque and deferred Snapshot v1 records remain visible as
 `add` or `remove` data and produce `lossy` or `unsupported` diagnostics. They
 cannot be silently promoted to a rename.
 

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
@@ -85,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
@@ -108,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
 
@@ -127,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.
 
@@ -155,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.
 
@@ -178,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qubu",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/aleclarson/qubu"
@@ -124,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",