qubu 0.5.0 → 0.6.0

package/docs/dialects-and-execution.md

@@ -111,6 +111,40 @@ const adapter: QueryAdapter = {
 }
 ```
 
+### Experimental cloud adapters
+
+The workspace also publishes experimental adapters for HTTP and serverless
+database clients. They are not production-ready and are intentionally outside
+provider-backed CI until funded infrastructure and an external maintainer are
+available.
+
+| Package                                   | Driver boundary                        | Advertised capabilities                                                                              |
+| ----------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `@qubu/adapter-neon`                      | Neon HTTP PostgreSQL query function    | PostgreSQL rendering, object rows, mutation counts, EXPLAIN, and fetch cancellation                  |
+| `@qubu/adapter-planetscale`               | PlanetScale serverless MySQL client    | MySQL rendering, rows, mutation metadata, EXPLAIN, and provider transaction callbacks                |
+| `@qubu/adapter-aws-rds-data-api/postgres` | AWS RDS Data API for Aurora PostgreSQL | PostgreSQL rendering, typed Data API values/results, EXPLAIN, mutation metadata, and transaction IDs |
+| `@qubu/adapter-aws-rds-data-api/mysql`    | AWS RDS Data API for Aurora MySQL      | MySQL rendering, typed Data API values/results, EXPLAIN, mutation metadata, and transaction IDs      |
+
+Neon HTTP and the RDS Data API do not advertise interactive streaming. The
+RDS adapter uses named placeholders (`:p1`, `:p2`, ...), while PlanetScale uses
+the MySQL dialect and the provider's own value formatting. Read each package's
+README for its experimental boundary and required provider setup.
+
+### Official SQLite WASM adapter
+
+`@qubu/adapter-sqlite-wasm` adapts the official SQLite WASM OO1
+`sqlite3.oo1.DB` API for browser and web-worker use. It prepares one statement
+per request, binds Qubu's ordered parameters, copies object rows, and finalizes
+the statement in a `finally` block. SQLite's change count and generated row ID
+are returned as mutation metadata when the request is a mutation.
+
+The package does not create or terminate workers. Initialize the official
+SQLite module inside a dedicated worker, construct the adapter around its
+`sqlite3.oo1.DB`, and close the adapter before terminating that worker. The
+browser build must serve the package's `sqlite3.wasm` asset beside the bundled
+worker module; the combo runner's verified browser scenario demonstrates this
+lifecycle.
+
 ### Decode schema-aware result values
 
 Portable boolean, date, timestamp, and JSON columns retain their logical

package/docs/migrations/index.md

@@ -4,13 +4,13 @@
 
 Qubu migrations are split across explicit ownership boundaries:
 
-| Owner           | Imports                                            | Responsibility                                                                                                               |
-| --------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `qubu`          | `qubu/snapshot`, `qubu/diff`, `qubu/introspection` | Pure schema snapshots, comparison, and catalog mapping                                                                       |
-| `@qubu/migrate` | Focused subpaths listed below                      | Pure planning and compilation plus portable artifacts, journals, execution, status, baselines, and bootstrap                 |
-| `@qubu/cli`     | `@qubu/cli/config`, `@qubu/cli/repository`         | Node.js configuration loading, artifact files, commands, output, and process exit behavior                                   |
-| Adapter package | `@qubu/adapter-*/migration`                        | Pinned driver sessions, parameter binding, transactions, leases, locks, database journal storage, and failure classification |
-| Application     | Its own configuration and deployment code          | Credentials, environment selection, approval policy, custom SQL, rollout timing, and legacy cutover decisions                |
+| Owner           | Imports                                                                                                                     | Responsibility                                                                                                               |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `qubu`          | `qubu/snapshot`, `qubu/snapshot/postgres`, `qubu/snapshot/sqlite`, `qubu/snapshot/mysql`, `qubu/diff`, `qubu/introspection` | Pure schema snapshots, comparison, and catalog mapping                                                                       |
+| `@qubu/migrate` | Focused subpaths listed below                                                                                               | Pure planning and compilation plus portable artifacts, journals, execution, status, baselines, and bootstrap                 |
+| `@qubu/cli`     | `@qubu/cli/config`, `@qubu/cli/repository`                                                                                  | Node.js configuration loading, artifact files, commands, output, and process exit behavior                                   |
+| Adapter package | `@qubu/adapter-*/migration`                                                                                                 | Pinned driver sessions, parameter binding, transactions, leases, locks, database journal storage, and failure classification |
+| Application     | Its own configuration and deployment code                                                                                   | Credentials, environment selection, approval policy, custom SQL, rollout timing, and legacy cutover decisions                |
 
 The pre-alpha `qubu/migration` and `qubu/ddl` entrypoints no longer exist. Use
 the extracted compiler entrypoints:

package/docs/reference/mysql-snapshot.md

@@ -4,13 +4,13 @@
 > MySQL facts Qubu v1 can encode and the combinations that need a later server
 > version or engine policy.
 
-Import the adapter from the optional snapshot entrypoint:
+Import the adapter from the MySQL snapshot subpath:
 
 ```ts
-import { createMysqlSchemaSnapshot, tryCreateMysqlSchemaSnapshot } from "qubu/snapshot"
+import { createSchemaSnapshot, tryCreateSchemaSnapshot } from "qubu/snapshot/mysql"
 
-const snapshot = createMysqlSchemaSnapshot(appSchema)
-const result = tryCreateMysqlSchemaSnapshot(appSchema)
+const snapshot = createSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 ```
 
 The snapshot dialect is named `mysql`, the same name used by Qubu's query
@@ -38,7 +38,7 @@ Capability checks run before common traversal. Use the non-throwing form when
 a schema may include a MySQL engine or version-specific feature:
 
 ```ts
-const result = tryCreateMysqlSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
     console.error(issue.path.join("."), issue.code, issue.message)

package/docs/reference/postgres-snapshot.md

@@ -4,16 +4,16 @@
 > PostgreSQL facts Qubu v1 can encode and the cases that need a later server
 > version policy.
 
-Import the adapter from the optional snapshot entrypoint:
+Import the adapter from the PostgreSQL snapshot subpath:
 
 ```ts
+import { createSchemaSnapshot } from "qubu/snapshot"
 import {
-  createSchemaSnapshot,
-  createPostgresSchemaSnapshot,
+  createSchemaSnapshot as createPostgresSnapshot,
   postgresSnapshotAdapter,
-} from "qubu/snapshot"
+} from "qubu/snapshot/postgres"
 
-const snapshot = createPostgresSchemaSnapshot(appSchema)
+const snapshot = createPostgresSnapshot(appSchema)
 // Equivalent: createSchemaSnapshot(appSchema, { adapter: postgresSnapshotAdapter })
 ```
 
@@ -46,9 +46,9 @@ 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 { tryCreateSchemaSnapshot } from "qubu/snapshot/postgres"
 
-const result = tryCreatePostgresSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
     console.error(issue.path.join("."), issue.code, issue.message)

package/docs/reference/sqlite-snapshot.md

@@ -2,13 +2,13 @@
 
 > Use this matrix to decide which SQLite schema facts Qubu v1 can serialize and which combinations must be diagnosed before a snapshot is written.
 
-Import the adapter from the optional snapshot entrypoint:
+Import the adapter from the SQLite snapshot subpath:
 
 ```ts
-import { createSqliteSchemaSnapshot, tryCreateSqliteSchemaSnapshot } from "qubu/snapshot"
+import { createSchemaSnapshot, tryCreateSchemaSnapshot } from "qubu/snapshot/sqlite"
 
-const snapshot = createSqliteSchemaSnapshot(appSchema)
-const result = tryCreateSqliteSchemaSnapshot(appSchema)
+const snapshot = createSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 ```
 
 The snapshot dialect is `sqlite`, the same name used by Qubu's query dialect.
@@ -36,7 +36,7 @@ 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:
 
 ```ts
-const result = tryCreateSqliteSchemaSnapshot(appSchema)
+const result = tryCreateSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
     console.error(issue.path.join("."), issue.code, issue.message)

package/docs/reference/supported-surface.md

@@ -4,38 +4,46 @@
 
 ## 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/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/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/sqlite`              | Runtime          | The SQLite query dialect policy and native SQLite column factories                                               |
-| `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/migrate/plan`       | Runtime          | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL                     |
-| `@qubu/migrate/ddl`        | Runtime          | DDL preflight and deterministic PostgreSQL, SQLite, or MySQL emission from a migration plan                      |
-| `@qubu/migrate/artifact`   | Runtime          | Versioned programs, strict artifacts and baselines, canonical encoding, and SHA-256 integrity                    |
-| `@qubu/migrate/repository` | Runtime          | Strict full-chain and journal-prefix verification                                                                |
-| `@qubu/migrate/journal`    | Runtime          | Storage-neutral journal records, transitions, validation, and reference storage                                  |
-| `@qubu/migrate/executor`   | Runtime          | Portable execution, structured errors, checkpointing, and explicit reconciliation                                |
-| `@qubu/migrate/baseline`   | Runtime          | Strict live baseline verification and physical managed-schema comparison                                         |
-| `@qubu/migrate/status`     | Runtime          | Pending chain, managed drift, unmanaged objects, interrupted attempts, and incompatible requirements             |
-| `@qubu/migrate/bootstrap`  | Runtime          | Fresh SQLite schema planning through the normal diff, plan, and program compiler                                 |
-| `@qubu/migrate/testing`    | Runtime          | Deterministic fake adapters, fault boundaries, and adapter conformance checks                                    |
-| `@qubu/cli`                | Runtime and CLI  | `@alloc/cmd-ts` commands, typed config, filesystem repositories, stable output, and exit codes                   |
-| `@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                                                        |
+| 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/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/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/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                               |
+| `qubu/sqlite`                             | Runtime          | The SQLite query dialect policy and native SQLite column factories                                               |
+| `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/migrate/plan`                      | Runtime          | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL                     |
+| `@qubu/migrate/ddl`                       | Runtime          | DDL preflight and deterministic PostgreSQL, SQLite, or MySQL emission from a migration plan                      |
+| `@qubu/migrate/artifact`                  | Runtime          | Versioned programs, strict artifacts and baselines, canonical encoding, and SHA-256 integrity                    |
+| `@qubu/migrate/repository`                | Runtime          | Strict full-chain and journal-prefix verification                                                                |
+| `@qubu/migrate/journal`                   | Runtime          | Storage-neutral journal records, transitions, validation, and reference storage                                  |
+| `@qubu/migrate/executor`                  | Runtime          | Portable execution, structured errors, checkpointing, and explicit reconciliation                                |
+| `@qubu/migrate/baseline`                  | Runtime          | Strict live baseline verification and physical managed-schema comparison                                         |
+| `@qubu/migrate/status`                    | Runtime          | Pending chain, managed drift, unmanaged objects, interrupted attempts, and incompatible requirements             |
+| `@qubu/migrate/bootstrap`                 | Runtime          | Fresh SQLite schema planning through the normal diff, plan, and program compiler                                 |
+| `@qubu/migrate/testing`                   | Runtime          | Deterministic fake adapters, fault boundaries, and adapter conformance checks                                    |
+| `@qubu/cli`                               | Runtime and CLI  | `@alloc/cmd-ts` commands, typed config, filesystem repositories, stable output, and exit codes                   |
+| `@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/adapter-neon`                      | Runtime          | Experimental Neon HTTP PostgreSQL `QueryAdapter` behavior                                                        |
+| `@qubu/adapter-planetscale`               | Runtime          | Experimental PlanetScale serverless MySQL `QueryAdapter` and transaction behavior                                |
+| `@qubu/adapter-aws-rds-data-api/postgres` | Runtime          | Experimental Aurora PostgreSQL AWS RDS Data API adapter behavior                                                 |
+| `@qubu/adapter-aws-rds-data-api/mysql`    | Runtime          | Experimental Aurora MySQL AWS RDS Data API adapter behavior                                                      |
+| `@qubu/adapter-sqlite-wasm`               | Runtime          | Official SQLite WASM OO1 `QueryAdapter` for browser and web-worker databases                                     |
+| `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

package/docs/schema/code-generation.md

@@ -49,10 +49,10 @@ baseline for the next catalog read:
 
 ```ts
 import { mapCatalogToSnapshot } from "qubu/introspection"
-import { createSqliteSchemaSnapshot } from "qubu/snapshot"
+import { createSchemaSnapshot } from "qubu/snapshot/sqlite"
 import { mainSchema } from "./schema.generated.ts"
 
-const previousSnapshot = createSqliteSchemaSnapshot(mainSchema)
+const previousSnapshot = createSchemaSnapshot(mainSchema)
 const next = mapCatalogToSnapshot(nextCatalog, {
   namespace: "main",
   previousSnapshot,

package/docs/schema/ddl-emission.md

@@ -9,7 +9,7 @@ plan returns diagnostics and no SQL.
 
 ```ts
 import { emitMigrationPlan } from "@qubu/migrate/ddl"
-import { postgresSchemaDialect } from "qubu/snapshot"
+import { postgresSchemaDialect } from "qubu/snapshot/postgres"
 
 const result = emitMigrationPlan(plan, postgresSchemaDialect)
 if (!result.ok) {

package/docs/schema/snapshots.md

@@ -65,6 +65,18 @@ envelope. A dialect adapter owns physical storage mapping, SQL literal and
 expression encoding, dialect extensions, capability checks, and any dialect
 naming policy. PostgreSQL, SQLite, and MySQL adapters can implement
 `SchemaSnapshotAdapter` without duplicating traversal or decoder rules.
+The neutral API stays at `qubu/snapshot`; built-in dialect adapters have
+dedicated subpaths so importing neutral snapshot utilities does not widen that
+API:
+
+```ts
+import { createSchemaSnapshot } from "qubu/snapshot"
+import { createSchemaSnapshot as createPostgresSnapshot } from "qubu/snapshot/postgres"
+
+const neutral = createSchemaSnapshot(appSchema)
+const postgres = createPostgresSnapshot(appSchema)
+```
+
 The PostgreSQL adapter is documented in the [PostgreSQL snapshot support
 matrix](../reference/postgres-snapshot.md). Its schema dialect extends the
 `postgresql` query dialect, and snapshot metadata uses that same identity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qubu",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/aleclarson/qubu"
@@ -48,6 +48,18 @@
       "types": "./dist/snapshot.d.mts",
       "import": "./dist/snapshot.mjs"
     },
+    "./snapshot/mysql": {
+      "types": "./dist/snapshot/mysql.d.mts",
+      "import": "./dist/snapshot/mysql.mjs"
+    },
+    "./snapshot/postgres": {
+      "types": "./dist/snapshot/postgres.d.mts",
+      "import": "./dist/snapshot/postgres.mjs"
+    },
+    "./snapshot/sqlite": {
+      "types": "./dist/snapshot/sqlite.d.mts",
+      "import": "./dist/snapshot/sqlite.mjs"
+    },
     "./sqlite": {
       "types": "./dist/sqlite.d.mts",
       "import": "./dist/sqlite.mjs"