qubu 0.0.0 → 0.3.4

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

@@ -0,0 +1,182 @@
+# Source scope
+
+> Keep each column tied to the table, alias, CTE, or derived source that provides it; use this page to fix scope errors and intentional correlations.
+
+A column carries the identity of the source that provides it. Qubu checks that
+identity when you assemble a query. The source must appear in `FROM` or a join
+before its columns can appear in the projection, a predicate, or another
+clause.
+
+## Add the source that owns a column
+
+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'
+
+const users = table('users', {
+  id: integer(),
+})
+const posts = table('posts', {
+  id: integer(),
+  title: text(),
+})
+
+select({ id: users.id }, from(posts))
+// Type error: users is not available in this query scope
+```
+
+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'
+
+const users = table('users', {
+  id: integer(),
+})
+const posts = table('posts', {
+  id: integer(),
+  authorId: integer(),
+})
+
+const query = select(
+  { userId: users.id, postId: posts.id },
+  from(users),
+  innerJoin(posts, eq(users.id, posts.authorId))
+)
+```
+
+## Use the source identity you introduced
+
+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'
+
+const users = table('users', {
+  id: integer(),
+  name: text(),
+})
+
+const author = alias(users, 'author')
+const query = select({ name: author.name }, from(author))
+```
+
+`author.name` belongs to the `author` source. `users.name` is a different source
+identity after aliasing, even though both columns refer to the same table.
+
+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'
+
+const names = select({ name: lower(users.name) }, from(users))
+const namesSource = alias(names, 'names')
+
+const query = select({ name: namesSource.name }, from(namesSource))
+```
+
+Use [Compose queries](../guides/compose-queries.md) for the full CTE,
+derived-table, scalar-subquery, and set-operation workflow.
+
+## Produce a custom FROM source
+
+Use `customSource()` for a table-valued function or another relation that
+`table()` cannot describe. The producer supplies the source identity, column
+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'
+
+const entries = customSource({
+  identity: {
+    sourceKind: 'table-function',
+    name: 'json_each',
+    alias: 'entry',
+  },
+  sourceKind: 'table-function',
+  reference: identifier('entry'),
+  columns: {
+    key: integer(),
+    value: text({ nullable: true }),
+  },
+  render(context) {
+    context.append('json_each(')
+    context.parameter('{"a":1}')
+    context.append(') AS ')
+    context.render(identifier('entry'))
+  },
+})
+
+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
+by the generated columns. The nullable `value` column stays nullable, and a
+`leftJoin()` adds outer-join nullability to every selected column from
+`entries`.
+
+Bind function arguments with `context.parameter()`. The normal renderer then
+keeps those values in placeholder order.
+
+## Correlate an inner query
+
+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', {
+  id: integer(),
+  authorId: integer(),
+})
+
+const recentPost = select(
+  { id: posts.id },
+  from(posts),
+  correlate(users),
+  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)
+)
+```
+
+The inner query consumes `posts` locally. The enclosing `users` source satisfies
+its outer requirement. The same requirement flows through `scalar()`,
+`exists()`, and `inQuery()`.
+
+## Read next
+
+- [Result shapes and cardinality](result-shapes.md) explains projection names,
+  outer-join nullability, and scalar subqueries.
+- [Fragments and metadata](fragments.md) explains the type facts that carry
+  source requirements through custom expressions and clauses.
+- [Extend Qubu](../guides/extensions/overview.md) shows how to publish a custom
+  source or clause.

package/docs/reference/introspection-support.md

@@ -0,0 +1,196 @@
+# Introspection support
+
+> Look up which catalog facts each adapter reads, which versions it accepts, and which database features remain outside Snapshot v1.
+
+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
+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).
+
+## Version and namespace baseline
+
+| Adapter    | Baseline | Selected namespace            | Product policy                      |
+| ---------- | -------- | ----------------------------- | ----------------------------------- |
+| PostgreSQL | 12+      | one PostgreSQL schema         | PostgreSQL only                     |
+| SQLite     | 3.37+    | one database, normally `main` | attached databases are not combined |
+| MySQL      | 8.0.16+  | one MySQL database            | MariaDB requires a separate adapter |
+
+Version and product failures are structured diagnostics. The adapters do not
+silently downgrade to a different product's catalog rules.
+
+## Catalog facts
+
+| Fact                        | PostgreSQL                                                                                                                                          | SQLite                                                                                   | MySQL                                                                                                                               |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Tables and visible columns  | `pg_class`, `pg_attribute`                                                                                                                          | `sqlite_schema`, `table_xinfo`                                                           | `TABLES`, `COLUMNS`                                                                                                                 |
+| Native storage              | `format_type`                                                                                                                                       | declared type                                                                            | `COLUMN_TYPE`                                                                                                                       |
+| Defaults                    | `pg_get_expr`                                                                                                                                       | `dflt_value`                                                                             | `COLUMN_DEFAULT`                                                                                                                    |
+| Generated columns           | stored expressions                                                                                                                                  | stored/virtual when CREATE SQL is recoverable                                            | stored/virtual and `GENERATION_EXPRESSION`                                                                                          |
+| Identity behavior           | `attidentity`                                                                                                                                       | `INTEGER PRIMARY KEY`, `AUTOINCREMENT`                                                   | `AUTO_INCREMENT`                                                                                                                    |
+| Keys and foreign keys       | `pg_constraint`                                                                                                                                     | table metadata and `foreign_key_list`                                                    | `TABLE_CONSTRAINTS`, `KEY_COLUMN_USAGE`, `REFERENTIAL_CONSTRAINTS`                                                                  |
+| Checks                      | `pg_constraint` and decompiled definition                                                                                                           | CREATE SQL                                                                               | `CHECK_CONSTRAINTS`                                                                                                                 |
+| Indexes                     | `pg_index`, access method, decompiled terms                                                                                                         | `index_list`, `index_xinfo`, schema SQL                                                  | `STATISTICS`                                                                                                                        |
+| Complete PostgreSQL objects | views/materialized views, sequences, enums/domains, collations, triggers, routines, partitions, row-level policies, comments/owners, and extensions | N/A                                                                                      | N/A                                                                                                                                 |
+| Complete SQLite objects     | N/A                                                                                                                                                 | views and triggers when CREATE SQL is recoverable; table/view columns from `table_xinfo` | N/A                                                                                                                                 |
+| Complete MySQL objects      | N/A                                                                                                                                                 | N/A                                                                                      | typed views and view columns, routines and parameters, triggers, partitions, used collations, comments, and opaque scheduled events |
+| Unsupported MySQL families  | N/A                                                                                                                                                 | N/A                                                                                      | sequences, materialized views, row-level security (RLS) policies, extensions, and ownership                                         |
+| Deferred or opaque objects  | foreign tables and relation kinds without a safe typed mapping                                                                                      | virtual/shadow tables, attached-database boundaries, and unrecoverable definitions       | scheduled events are opaque; unknown or other non-base table rows are deferred                                                      |
+
+The readers preserve physical names and use database catalog identifiers only
+as current-run join keys. The normalized catalog keeps opaque SQL and its
+source, whether it came from a catalog value, a database decompiler, or CREATE
+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
+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.
+
+The query and normalization layout follows the catalog-oriented parts of the
+[Drizzle PostgreSQL introspector](https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-kit/src/introspect-pg.ts),
+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.
+
+## SQLite complete catalog surface
+
+The SQLite reader uses fixed statements over `sqlite_schema` and the
+table-valued PRAGMAs `database_list`, `table_list`, `table_xinfo`,
+`index_list`, `index_xinfo`, and `foreign_key_list`. Each table-valued PRAGMA
+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
+`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
+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`
+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.
+
+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).
+Drizzle's module generates source declarations; Qubu keeps the same SQLite
+metadata sources as normalized data and never evaluates database-provided SQL.
+The optional [source generator](../schema/code-generation.md) consumes the
+strict Snapshot v1 result through a separate controlled printer.
+
+## MySQL 8 complete catalog surface
+
+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,
+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
+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
+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
+`opaqueObjects`; they are not treated as typed routines, triggers, or
+migration operations.
+
+The MySQL reader does not expose typed sequences or materialized views. A
+sequence-like or other non-base table row is retained as a deferred object
+when the catalog reports one. MySQL row-level security (RLS) policies,
+extension objects, and ownership are unsupported complete families. Definers on
+views, routines, triggers, and events remain dialect metadata; they do not
+become ownership records. The corresponding capability flags are false.
+
+The query and normalization layout follows the catalog-reading portions of the
+[Drizzle MySQL introspector](https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-kit/src/introspect-mysql.ts),
+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.
+
+## Snapshot v1 surface
+
+The mapper can emit these facts in canonical Snapshot v1:
+
+- one namespace and ordinary tables;
+- exact dialect-native column storage;
+- nullability and unambiguous literal or opaque SQL defaults;
+- generated columns with stored or virtual mode;
+- identities kept separate from defaults and generated columns;
+- primary, unique, nullable-unique, foreign-key, and check constraints;
+- ordered column or expression index terms, predicates, included columns, and
+  representable dialect extensions;
+- stable logical IDs with physical names preserved separately.
+
+Strict mode returns no snapshot when a supported table fact cannot be mapped
+soundly. Lossy mode is explicit and marks warnings in the result. A digest is
+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:
+
+- 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;
+- 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,
+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
+dropping it.
+
+## Upstream references
+
+The dialect reader structure follows useful patterns from Drizzle Kit while
+keeping Qubu's output data-only:
+
+- [Drizzle PostgreSQL introspector](https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-kit/src/introspect-pg.ts)
+- [Drizzle SQLite introspector](https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-kit/src/introspect-sqlite.ts)
+- [Drizzle MySQL introspector](https://github.com/drizzle-team/drizzle-orm/blob/main/drizzle-kit/src/introspect-mysql.ts)
+
+Those modules generate TypeScript declarations as part of their workflows.
+Qubu keeps catalog normalization, Snapshot v1 mapping, and optional source
+generation as separate pure boundaries, so diffing and planning do not depend
+on source generation.
+
+See [Database introspection](../schema/introspection.md) for the connection
+adapter example, identity rules, diagnostics, and the later diff/planning
+boundary. See the [PostgreSQL](postgres-snapshot.md),
+[SQLite](sqlite-snapshot.md), and [MySQL](mysql-snapshot.md) snapshot pages for
+the pure serialization adapters.

package/docs/reference/mysql-snapshot.md

@@ -0,0 +1,55 @@
+# 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.
+
+Import the adapter from the optional snapshot entrypoint:
+
+```ts
+import {
+  createMysqlSchemaSnapshot,
+  tryCreateMysqlSchemaSnapshot,
+} from 'qubu/snapshot'
+
+const snapshot = createMysqlSchemaSnapshot(appSchema)
+const result = tryCreateMysqlSchemaSnapshot(appSchema)
+```
+
+The snapshot dialect is named `mysql`, the same name used by Qubu's query
+renderer. A dialect-tagged `unsafeSchemaSql('mysql', sql)` expression belongs
+to this adapter.
+
+## Support matrix
+
+| 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`.                  |
+| 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.                                                                                     |
+| `ON UPDATE`         | A branded, parameter-free column expression is retained as `onUpdate`. PostgreSQL and SQLite adapters diagnose this MySQL-only fact.                                                                                                                |
+| AUTO_INCREMENT      | `identityColumn(..., { dialect: { dialect: 'mysql', autoIncrement: true } })` is retained as a column-level identity extension. The column must be non-nullable, integer-family storage, and the first term of a key.                               |
+| Generated columns   | Both `stored` and `virtual` modes are retained. Generated columns cannot also use `ON UPDATE` or `AUTO_INCREMENT`.                                                                                                                                  |
+| Keys and checks     | Primary keys, strict unique keys, ordinary unique constraints, foreign keys, and checks retain logical and physical names, actions, and typed MySQL extension data.                                                                                 |
+| Foreign keys        | `MATCH SIMPLE` and standard actions except `SET DEFAULT` are supported. `MATCH FULL`, `MATCH PARTIAL`, deferrability, and `SET DEFAULT` are diagnosed.                                                                                              |
+| Nullable uniqueness | `nulls: 'distinct'` is supported. `nulls: 'not-distinct'` is diagnosed because ordinary MySQL `UNIQUE` constraints allow multiple `NULL` values.                                                                                                    |
+| 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.                                                                                |
+
+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)
+if (!result.ok) {
+  for (const issue of result.diagnostics) {
+    console.error(issue.path.join('.'), issue.code, issue.message)
+  }
+}
+```
+
+The adapter does not connect to MySQL, inspect `information_schema`, or emit
+DDL. It produces deterministic data for the strict `qubu/snapshot` decoder.
+The package-wide [ownership map](supported-surface.md#ownership-boundary)
+shows the separate schema and application boundaries.

package/docs/reference/postgres-snapshot.md

@@ -0,0 +1,61 @@
+# 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.
+
+Import the adapter from the optional snapshot entrypoint:
+
+```ts
+import {
+  createSchemaSnapshot,
+  createPostgresSchemaSnapshot,
+  postgresSnapshotAdapter,
+} from 'qubu/snapshot'
+
+const snapshot = createPostgresSchemaSnapshot(appSchema)
+// Equivalent: createSchemaSnapshot(appSchema, { adapter: postgresSnapshotAdapter })
+```
+
+The schema dialect extends Qubu's existing `postgresql` query dialect, so both
+snapshot metadata and `unsafeSchemaSql()` use `postgresql` consistently.
+
+## Support matrix
+
+| Schema fact         | PostgreSQL v1 behavior                                                                                                                                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Portable storage    | Emits PostgreSQL declarations: `INTEGER`, `NUMERIC`, `TEXT`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `UUID`, `JSONB`, `BIGINT`, and `BYTEA`.                                                                                         |
+| 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.                                                                                      |
+| Identity            | `always` and `by-default` identity metadata stays separate from generated expressions.                                                                                                                                       |
+| Generated columns   | Stored expressions are supported. Virtual generated columns fail with a capability diagnostic.                                                                                                                               |
+| Keys and checks     | Primary keys, strict unique keys, ordinary unique constraints, foreign keys, and checks retain names, timing, actions, and expressions. Checks cannot be deferrable.                                                         |
+| Foreign-key match   | `simple` and `full` are retained. `partial` fails because PostgreSQL does not implement it.                                                                                                                                  |
+| Nullable uniqueness | `nulls: 'distinct'` is portable. `nulls: 'not-distinct'` needs a PostgreSQL 15-or-newer policy and is rejected by v1.                                                                                                        |
+| Indexes             | Ordered terms, expressions, predicates, included columns, uniqueness, and candidate-key evidence are retained. PostgreSQL method, concurrency, operator class, and storage-parameter extensions are encoded under `dialect`. |
+| Names               | Table, column, constraint, and index names are checked against PostgreSQL's 63-byte identifier limit. Relation names are checked for collisions across tables and indexes.                                                   |
+
+The adapter does not connect to PostgreSQL or emit DDL. It produces
+deterministic data for the `qubu/snapshot` decoder. The package-wide
+[ownership map](supported-surface.md#ownership-boundary) shows the separate
+schema and application boundaries.
+
+## Diagnostics
+
+Use the non-throwing form when a schema may contain a server-specific feature:
+
+```ts
+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)
+  }
+}
+```
+
+Capability checks run before common traversal. The common serializer still
+owns ordering, cross-reference checks, canonical encoding, and strict snapshot
+validation.

package/docs/reference/sqlite-snapshot.md

@@ -0,0 +1,53 @@
+# 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.
+
+Import the adapter from the optional snapshot entrypoint:
+
+```ts
+import {
+  createSqliteSchemaSnapshot,
+  tryCreateSqliteSchemaSnapshot,
+} from 'qubu/snapshot'
+
+const snapshot = createSqliteSchemaSnapshot(appSchema)
+const result = tryCreateSqliteSchemaSnapshot(appSchema)
+```
+
+The snapshot dialect is `sqlite`, the same name used by Qubu's query dialect.
+This shared name is intentional: SQLite does not need a second metadata identity
+to distinguish it from the query renderer. A dialect-tagged
+`unsafeSchemaSql('sqlite', sql)` expression belongs to this adapter.
+
+## Support matrix
+
+| 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.                         |
+| 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.                                                                               |
+| Generated columns   | Both `stored` and `virtual` modes are retained. Generated columns cannot be used in a SQLite `PRIMARY KEY`; expressions still pass through the shared deterministic schema-expression boundary.                                               |
+| Identity and rowids | Identity columns require INTEGER affinity and a single-column `PRIMARY KEY`. Set `identityColumn(..., { dialect: { dialect: 'sqlite', autoIncrement: true } })` only with an exact `INTEGER` declaration to represent SQLite `AUTOINCREMENT`. |
+| Keys and checks     | Primary keys, strict unique keys, ordinary unique constraints, foreign keys, and checks retain logical and physical names. Constraint `DEFERRABLE` timing is diagnosed except on foreign keys.                                                |
+| Foreign keys        | Standard update/delete actions and `MATCH SIMPLE` are retained. `MATCH FULL` and `MATCH PARTIAL` are diagnosed because the v1 adapter does not claim SQLite support for them.                                                                 |
+| Nullable uniqueness | `nulls: 'distinct'` is supported. `nulls: 'not-distinct'` is diagnosed because SQLite's ordinary UNIQUE semantics distinguish NULLs.                                                                                                          |
+| 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.                                                                                                                                              |
+
+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)
+if (!result.ok) {
+  for (const issue of result.diagnostics) {
+    console.error(issue.path.join('.'), issue.code, issue.message)
+  }
+}
+```
+
+The adapter does not connect to SQLite, inspect `sqlite_master`, or emit DDL.
+It produces deterministic data for the strict `qubu/snapshot` decoder. The
+package-wide [ownership map](supported-surface.md#ownership-boundary) shows
+the separate schema and application boundaries.