qubu 0.6.1 → 0.6.3

package/docs/reference/introspection-support.md

@@ -1,10 +1,10 @@
 # Introspection support
 
-> Look up which catalog facts each adapter reads, which versions it accepts, and which database features remain outside Snapshot v1.
+> Check supported database versions, catalog objects, and snapshot-mapping limits.
 
 The optional `qubu/introspection` entrypoint reads one selected database
 namespace through a user-owned `CatalogConnection`. It returns normalized
-catalog data and can map that data to canonical Snapshot v1 or v2. The
+catalog data and can map that data to canonical Snapshot v1. The
 application owns the driver and connection lifecycle. Snapshot diffing,
 migration planning, and DDL emission are separate Qubu capabilities; see the
 [ownership map](supported-surface.md#ownership-boundary).
@@ -46,7 +46,7 @@ SQL.
 ## PostgreSQL complete catalog surface
 
 The PostgreSQL reader also fills the complete normalized catalog used by
-Snapshot v2. It keeps PostgreSQL OIDs in current-run physical references and
+Snapshot v1. It keeps PostgreSQL OIDs in current-run physical references and
 keeps decompiler output such as `pg_get_viewdef`, `pg_get_triggerdef`, and
 `pg_get_functiondef` as tagged SQL data. It does not evaluate that text.
 
@@ -55,9 +55,9 @@ The query and normalization layout follows the catalog-oriented parts of the
 while Qubu keeps the result as typed data instead of generating TypeScript
 declarations.
 
-Use `mapCatalogToCompleteSnapshot()` for this object set. Use
-`mapCatalogToSnapshot()` when a caller explicitly needs the existing table-only
-Snapshot v1.
+Use `mapCatalogToSnapshot()` or its explicit
+`mapCatalogToCompleteSnapshot()` alias for this object set. Both produce the
+canonical Snapshot v1 shape.
 
 ## SQLite complete catalog surface
 
@@ -67,29 +67,31 @@ table-valued PRAGMAs `database_list`, `table_list`, `table_xinfo`,
 receives bound namespace or object parameters through the caller's
 `CatalogConnection`. The reader does not interpolate a database name into SQL.
 
-SQLite views and triggers become typed complete catalog objects when their
-CREATE SQL has a recoverable definition and target. Their SQL remains tagged
-opaque data with a `sqlite` dialect and a catalog reference. Generated column
-expressions, declared storage types, SQLite affinity, rowid aliases, and
+SQLite views and triggers become typed catalog objects when Qubu can recover
+their definition and target from CREATE SQL. Their SQL remains opaque data,
+tagged with the `sqlite` dialect and a catalog reference.
+
+Generated column expressions, declared storage types, SQLite affinity, rowid aliases, and
 `AUTOINCREMENT` are kept as column or identity dialect extensions. User indexes
-retain ordered column or expression terms and partial predicates. Inline UNIQUE
-constraints are recovered from their internal indexes with deterministic Qubu
+retain ordered column or expression terms and partial predicates.
+
+Inline UNIQUE constraints are recovered from their internal indexes with deterministic Qubu
 names, so SQLite's `sqlite_autoindex_*` names do not become persisted logical
 IDs.
 
 SQLite virtual tables and shadow tables remain typed deferred objects with an
-`unmodeled-object` diagnostic. A selected attached database can expose table
-PRAGMA rows, but its schema SQL is outside the fixed `main` and `temp`
+`unmodeled-object` diagnostic.
+
+A selected attached database can expose table PRAGMA rows, but its schema SQL is outside the fixed `main` and `temp`
 statements. Qubu marks that result as limited and keeps other attached
 databases as opaque boundary records. It never combines attached databases into
 the selected namespace. SQLite does not provide the PostgreSQL object families
 such as routines, materialized views, policies, or ownership, so the reader
 does not fabricate them.
 
-`mapCatalogToCompleteSnapshot()` retains the typed views, triggers, deferred
-objects, opaque boundaries, and dialect extensions in Snapshot v2. The existing
-`mapCatalogToSnapshot()` still maps only tables and preserves Snapshot v1
-behavior.
+`mapCatalogToSnapshot()` delegates to `mapCatalogToCompleteSnapshot()` and
+retains typed views, triggers, deferred objects, opaque boundaries, and dialect
+extensions in Snapshot v1.
 
 The query and normalization seams follow the catalog-reading portions of the
 [Drizzle SQLite introspector](https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-kit/src/introspect-sqlite.ts).
@@ -102,21 +104,28 @@ strict Snapshot v1 result through a separate controlled printer.
 
 The MySQL reader accepts MySQL 8.0.16 and later within the MySQL 8 series. It
 rejects MariaDB and older MySQL versions instead of applying MySQL catalog
-rules to a different product or server version. It reads `INFORMATION_SCHEMA`
-rows for one selected database and retains database-provided SQL as tagged,
+rules to a different product or server version.
+
+It reads `INFORMATION_SCHEMA` rows for one selected database and retains database-provided SQL as tagged,
 unevaluated MySQL data.
 
-MySQL has typed complete records for views, routines and their parameters,
-triggers, partitions, collations used by selected tables or columns, and
-comments. View definitions come from `INFORMATION_SCHEMA.VIEWS`; each view's
+MySQL has typed records for:
+
+- Views.
+- Routines and their parameters.
+- Triggers and partitions.
+- Collations used by selected tables or columns.
+- Comments.
+
+View definitions come from `INFORMATION_SCHEMA.VIEWS`; each view's
 columns are joined back to the matching `COLUMNS` rows by physical table name,
-so the complete Snapshot v2 cross-reference points at the view's own column
+so the complete Snapshot v1 cross-reference points at the view's own column
 IDs. Missing view definitions or unresolved trigger, partition, or other
 object references become deferred records with diagnostics.
 
 Scheduled events are retained as `CatalogOpaqueObject` records. Their event
 metadata and definition remain opaque, and the reader emits an
-`unmodeled-object` warning. Snapshot v2 keeps these records in
+`unmodeled-object` warning. Snapshot v1 keeps these records in
 `opaqueObjects`; they are not treated as typed routines, triggers, or
 migration operations.
 
@@ -132,13 +141,12 @@ The query and normalization layout follows the catalog-reading portions of the
 while Qubu keeps the result as typed data instead of generating TypeScript
 declarations.
 
-Use `mapCatalogToCompleteSnapshot()` to retain these typed MySQL families and
-the opaque or deferred boundaries in Snapshot v2. Use `mapCatalogToSnapshot()`
-when a caller explicitly needs the existing table-only Snapshot v1.
+Use `mapCatalogToSnapshot()` or `mapCatalogToCompleteSnapshot()` to retain these
+typed MySQL families and the opaque or deferred boundaries in Snapshot v1.
 
 ## Snapshot v1 surface
 
-The mapper can emit these facts in canonical Snapshot v1:
+The mapper emits these facts in canonical Snapshot v1:
 
 - one namespace and ordinary tables;
 - exact dialect-native column storage;
@@ -156,20 +164,17 @@ canonical content, not an identity or rename marker.
 
 ## Deferred and limited features
 
-The following remain catalog facts or diagnostics rather than fabricated
-Snapshot v1 objects:
+Supported object families become typed Snapshot v1 records, as described in
+the database sections above. Limits still apply to individual features:
 
-- views and materialized views;
-- sequences, enums, domains, routines, triggers, policies, extensions,
-  collations, comments, and partition metadata;
-- PostgreSQL identity sequence options that have no typed Snapshot v1 field;
+- PostgreSQL identity sequence options that have no typed field;
 - SQLite virtual/shadow tables, attached namespaces, and unrecoverable
   generated or expression definitions;
 - MySQL/MariaDB differences, prefix indexes, invisible indexes, and advanced
   functional, full-text, or spatial index semantics.
 
-Use the complete catalog and Snapshot v2 mapper to retain supported PostgreSQL
-and MySQL families. MySQL scheduled events stay opaque, and MySQL sequences,
+Use the Snapshot v1 mapper to retain supported PostgreSQL and MySQL families.
+MySQL scheduled events stay opaque, and MySQL sequences,
 materialized views, row-level security (RLS) policies, extension objects, and
 ownership stay unsupported or deferred. When a row cannot be normalized safely, the reader
 keeps a typed deferred or opaque record and emits a diagnostic instead of

package/docs/reference/mysql-snapshot.md

@@ -1,8 +1,6 @@
 # MySQL snapshot support
 
-> Use this matrix before selecting `mysqlSnapshotAdapter`; it records the
-> MySQL facts Qubu v1 can encode and the combinations that need a later server
-> version or engine policy.
+> Check which MySQL schema features the Snapshot v1 adapter can save.
 
 Import the adapter from the MySQL snapshot subpath:
 
@@ -21,7 +19,7 @@ to this adapter.
 
 | Schema fact         | MySQL v1 behavior                                                                                                                                                                                                                                   |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Portable storage    | Maps `integer` to `INT`, `numeric` to `DECIMAL`, `text` to `TEXT`, `boolean` to `BOOLEAN`, `date` to `DATE`, `timestamp` to `DATETIME`, `uuid` to `CHAR(36)`, `json` to `JSON`, `bigint` to `BIGINT`, and `binary` to `VARBINARY`.                  |
+| Portable storage    | Uses the mappings below.                                                                                                                                                                                                                            |
 | Native storage      | Preserves a non-empty declaration tagged `mysql` exactly. Native declarations owned by another dialect fail.                                                                                                                                        |
 | Literals            | Encodes `NULL`, finite numbers, strings, booleans, and `bigint` without query parameters. Strings use SQL quote doubling.                                                                                                                           |
 | Defaults            | Canonical literals, branded deterministic expressions, and explicit external behavior are retained. Default expressions cannot reference columns or parameters.                                                                                     |
@@ -34,6 +32,23 @@ to this adapter.
 | Indexes             | Ordered terms, expressions, uniqueness, and candidate-key evidence are retained. Partial predicates, included columns, and `NULLS FIRST/LAST` are diagnosed. Algorithm, locking, access method, parser, and key-block options live under `dialect`. |
 | Names               | Table, column, constraint, and index names are checked against MySQL's 64-character identifier limit. Table names are database-scoped; index names are table-scoped.                                                                                |
 
+## Portable storage types
+
+| Qubu storage | Database declaration |
+| ------------ | -------------------- |
+| `integer`    | `INT`                |
+| `numeric`    | `DECIMAL`            |
+| `text`       | `TEXT`               |
+| `boolean`    | `BOOLEAN`            |
+| `date`       | `DATE`               |
+| `timestamp`  | `DATETIME`           |
+| `uuid`       | `CHAR(36)`           |
+| `json`       | `JSON`               |
+| `bigint`     | `BIGINT`             |
+| `binary`     | `VARBINARY`          |
+
+## Diagnostics
+
 Capability checks run before common traversal. Use the non-throwing form when
 a schema may include a MySQL engine or version-specific feature:
 

package/docs/reference/postgres-snapshot.md

@@ -1,8 +1,6 @@
 # PostgreSQL snapshot support
 
-> Use this matrix before selecting `postgresSnapshotAdapter`; it records the
-> PostgreSQL facts Qubu v1 can encode and the cases that need a later server
-> version policy.
+> Check which PostgreSQL schema features the Snapshot v1 adapter can save.
 
 Import the adapter from the PostgreSQL snapshot subpath:
 
@@ -24,7 +22,7 @@ snapshot metadata and `unsafeSchemaSql()` use `postgresql` consistently.
 
 | Schema fact         | PostgreSQL v1 behavior                                                                                                                                                                                                       |
 | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Portable storage    | Emits PostgreSQL declarations: `INTEGER`, `NUMERIC`, `TEXT`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `UUID`, `JSONB`, `BIGINT`, and `BYTEA`.                                                                                         |
+| Portable storage    | Uses the mappings below.                                                                                                                                                                                                     |
 | Native storage      | Preserves a non-empty declaration tagged `postgresql` exactly. Other dialect tags fail.                                                                                                                                      |
 | Literals            | Encodes finite numbers, strings, booleans, `bigint`, and `NULL` without query parameters.                                                                                                                                    |
 | Defaults            | Canonical literals, branded deterministic expressions, and explicit external behavior are retained. Column references in defaults fail.                                                                                      |
@@ -41,6 +39,21 @@ deterministic data for the `qubu/snapshot` decoder. The package-wide
 [ownership map](supported-surface.md#ownership-boundary) shows the separate
 schema and application boundaries.
 
+## Portable storage types
+
+| Qubu storage | Database declaration |
+| ------------ | -------------------- |
+| `integer`    | `INTEGER`            |
+| `numeric`    | `NUMERIC`            |
+| `text`       | `TEXT`               |
+| `boolean`    | `BOOLEAN`            |
+| `date`       | `DATE`               |
+| `timestamp`  | `TIMESTAMP`          |
+| `uuid`       | `UUID`               |
+| `json`       | `JSONB`              |
+| `bigint`     | `BIGINT`             |
+| `binary`     | `BYTEA`              |
+
 ## Diagnostics
 
 Use the non-throwing form when a schema may contain a server-specific feature:

package/docs/reference/sqlite-snapshot.md

@@ -1,6 +1,6 @@
 # SQLite snapshot support
 
-> Use this matrix to decide which SQLite schema facts Qubu v1 can serialize and which combinations must be diagnosed before a snapshot is written.
+> Check which SQLite schema features the Snapshot v1 adapter can save.
 
 Import the adapter from the SQLite snapshot subpath:
 
@@ -20,7 +20,7 @@ to distinguish it from the query renderer. A dialect-tagged
 
 | Schema fact         | SQLite v1 behavior                                                                                                                                                                                                                            |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Portable storage    | Maps `integer`, `boolean`, and `bigint` to `INTEGER`; `text`, `date`, `timestamp`, `uuid`, and `json` to `TEXT`; `numeric` to `NUMERIC`; and `binary` to `BLOB`. The snapshot also records SQLite's derived affinity.                         |
+| Portable storage    | Uses the mappings below. SQLite affinity is also recorded.                                                                                                                                                                                    |
 | Native storage      | Preserves a non-empty declaration tagged `sqlite` exactly and records its affinity using SQLite's ordered declared-type rules. Other dialect tags fail.                                                                                       |
 | Literals            | Encodes `NULL`, finite numbers, strings, `bigint`, and booleans as parameter-free SQL. Boolean literals use `1` and `0`; strings retain SQL escaping.                                                                                         |
 | Defaults            | Canonical literals, branded deterministic expressions, and explicit external behavior are retained. Default expressions cannot reference columns or parameters.                                                                               |
@@ -32,6 +32,23 @@ to distinguish it from the query renderer. A dialect-tagged
 | Indexes             | Ordered terms, expressions, uniqueness, predicates for partial indexes, and candidate-key evidence are retained. Included columns are diagnosed as unsupported. The typed SQLite index extension is encoded under `dialect`.                  |
 | Namespaces          | An optional unqualified namespace is retained; Qubu does not attach or inspect SQLite databases.                                                                                                                                              |
 
+## Portable storage types
+
+| Qubu storage | Database declaration |
+| ------------ | -------------------- |
+| `integer`    | `INTEGER`            |
+| `numeric`    | `NUMERIC`            |
+| `text`       | `TEXT`               |
+| `boolean`    | `INTEGER`            |
+| `date`       | `TEXT`               |
+| `timestamp`  | `TEXT`               |
+| `uuid`       | `TEXT`               |
+| `json`       | `TEXT`               |
+| `bigint`     | `INTEGER`            |
+| `binary`     | `BLOB`               |
+
+## Diagnostics
+
 Capability checks run before common traversal. Use the non-throwing form when a
 schema may include a feature that depends on a SQLite version or table shape: