@vibeorm/migrate 1.3.1 → 2.0.0-alpha.10

package/README.md

@@ -1,95 +1,62 @@
 # @vibeorm/migrate
 
-Migration, introspection, and schema diff toolkit for VibeORM. Handles DDL generation, database introspection, schema comparison, migration tracking, and `.prisma` schema printing.
+> Part of **[VibeORM](https://github.com/vibeorm/vibeorm)** — a type-safe TypeScript ORM for Bun and Node. Prisma-schema or TypeScript-DSL input, a canonical schema IR, a generated client, and a dialect-aware SQL layer over PostgreSQL, PGlite, SQLite and MySQL.
 
-## Installation
+The migration engine: it diffs two schema IRs into dialect-neutral steps, renders those steps as per-dialect DDL, applies them with bookkeeping, and introspects a live database back into IR. It is its own package so that the CLI and tests can run schema changes without pulling in the query runtime, and so every SQL-text decision stays in one reviewable place.
 
 ```bash
-bun add @vibeorm/migrate
+bun add @vibeorm/migrate@alpha
 ```
 
-## Features
+> **Pre-release.** `2.0.0-alpha.x`, published under the `alpha` dist-tag. `npm i vibeorm` still resolves to the stable v1 line.
 
-- **DDL generation** — schema IR to PostgreSQL DDL (enums, tables, constraints, indexes, foreign keys, M:N join tables)
-- **Introspection** — reverse-engineer a live PostgreSQL database into schema IR
-- **Schema diffing** — compute migration operations between two schema versions
-- **Migration runner** — track and apply migrations via a `_vibeorm_migrations` table
-- **Snapshot management** — serialize/deserialize schema IR as JSON for diffing
-- **Schema printing** — convert schema IR back to `.prisma` format
+Most users never install this directly — it ships as a dependency of [`vibeorm`](https://www.npmjs.com/package/vibeorm) and of the generated client. Reach for it when you are writing an adapter or tooling against the runtime.
 
-## API
+## What it does
 
-### DDL
+Three stages, each usable on its own.
 
-```ts
-import { buildDDL } from "@vibeorm/migrate";
+**Diff.** `diffSchemas({ from, to, dialect })` returns ordered `MigrationStep` values — `createTable`, `addColumn`, `alterColumn`, `createIndex`, `addForeignKey`, `createJoinTable`, `dropView` and the rest. Steps carry IR fragments, never SQL text, and are emitted in dependency-safe order. Both sides normalize before comparison, so `diffSchemas({ from: introspect(push(X)), to: X })` is empty: pushing twice is a no-op. There is no rename detection — a renamed table diffs as drop plus create.
 
-const { sql, statements } = buildDDL({ schema });
-// sql: full DDL wrapped in BEGIN/COMMIT
-// statements: individual DDL statements
-```
+**Render.** `renderSteps({ steps, dialect, from, to })` produces the SQL strings for postgres, sqlite (including the table-rebuild recipe for ALTERs sqlite cannot express) or mysql. `describeStep({ step })` gives the one-line human description used in CLI output and refusal messages.
 
-### Introspection
+**Run.** `applyMigrations` executes `MigrationFile`s in order under an advisory lock, recording each in the `_vibe_migrations` bookkeeping table with a sha256 checksum over its statements. Re-applying a migration whose SQL changed is a `VIBE_MIGRATION` error, not a silent divergence. On postgres and sqlite each migration runs inside one transaction with its bookkeeping row; on mysql, where DDL auto-commits, progress is recorded per statement and a re-run resumes from where it stopped. `migrationStatus` reports applied, pending, mismatched and mid-rollback migrations, `rollbackMigration` runs a migration's `downSql`, and `resolveMigration` repairs the bookkeeping table without running SQL.
 
-```ts
-import { introspect } from "@vibeorm/migrate";
+**Introspect.** `introspectPostgres`, `introspectSqlite` and `introspectMysql` read a live database back into `SchemaIR`; `pull` picks the right one for a dialect.
 
-const schema = await introspect({ executor });
-// Returns a Schema IR from a live database
-```
+## push vs migrate
 
-### Schema Diffing
+`push` goes straight from the live database to your schema — introspect, diff, render, apply — with no files kept. It suits prototyping and disposable databases. `generateMigration` plus `applyMigrations` keeps named, checksummed SQL files you can review and replay, which is what shared and production databases need. Details in [docs/migrations.md](https://github.com/vibeorm/vibeorm/blob/master/docs/migrations.md).
 
-```ts
-import { diffSchemas } from "@vibeorm/migrate";
+## Destructive steps
 
-const operations = diffSchemas({ previous: oldSchema, current: newSchema });
-// Returns DiffOperation[] with isDestructive flags
-```
+Every step carries a `destructive` flag: drops of tables, columns, enums and join tables, plus narrowing type changes. `push` refuses to run when any step is destructive unless you pass `acceptDataLoss: true`, and the thrown `VibeError` (`VIBE_MIGRATION`) lists each offending step by description. `generateMigration` surfaces the same information as `MigrationFile.destructive` so callers can require confirmation before applying. Constructs a dialect cannot express — scalar lists on sqlite and mysql, partial indexes on mysql, removing a value from a surviving enum — throw `VIBE_UNSUPPORTED_CAPABILITY` instead of degrading.
 
-### Migration Runner
+## Usage
 
 ```ts
-import {
-  ensureMigrationTable,
-  getAppliedMigrations,
-  applyMigration,
-  removeMigrationRecord,
-  markMigrationApplied,
-} from "@vibeorm/migrate";
-
-await ensureMigrationTable({ executor });
-const applied = await getAppliedMigrations({ executor });
-await applyMigration({ executor, migrationName: "20260101_init", sql, checksum });
-```
-
-### Snapshots
+import { applyMigrations, generateMigration, push, pull } from "@vibeorm/migrate";
+import { toSqlExecutor } from "@vibeorm/runtime";
 
-```ts
-import {
-  saveSnapshot,
-  loadLatestSnapshot,
-  loadSnapshot,
-  saveJournal,
-  loadJournal,
-  generateTimestamp,
-  computeChecksum,
-} from "@vibeorm/migrate";
-```
+const executor = toSqlExecutor({ adapter });
 
-### Schema Printing
+// Prototyping: make the database match the schema.
+const result = await push({ executor, schema, acceptDataLoss: false });
+console.log(result.steps, result.applied);
 
-```ts
-import { printSchema } from "@vibeorm/migrate";
+// Versioned: render a named migration from a diff, then apply it.
+const migration = generateMigration({ from: previous, to: schema, name: "add_posts", dialect: "postgres" });
+await applyMigrations({ executor, migrations: [migration], dialect: "postgres" });
 
-const prismaText = printSchema({ schema });
-// Returns .prisma formatted schema text
+// Introspect the live database back into IR.
+const live = await pull({ executor, dialect: "postgres" });
 ```
 
-### Diff Operation Types
-
-18 operation types: `createEnum`, `addEnumValue`, `removeEnumValue`, `dropEnum`, `createTable`, `dropTable`, `addColumn`, `dropColumn`, `alterColumnType`, `alterColumnNullability`, `alterColumnDefault`, `addUnique`, `dropUnique`, `addIndex`, `dropIndex`, `addForeignKey`, `dropForeignKey`, `createJoinTable`, `dropJoinTable`.
+`SqlExecutor` calls must all reach the same database session — the engine issues `BEGIN`/`COMMIT`, `PRAGMA` and advisory-lock statements through it. Pool-backed executors must pin one connection for the whole operation.
 
-## License
+## Links
 
-[MIT](../../LICENSE)
+- [Documentation](https://github.com/vibeorm/vibeorm/tree/master/docs)
+- [Query API](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md)
+- [Repository and issues](https://github.com/vibeorm/vibeorm)
+- MIT licensed

package/dist/ddl/drop-order.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Topological ordering for DROP TABLE statements — children (referencing
+ * tables) first.
+ *
+ * postgres never needs this: `DROP TABLE … CASCADE` takes inbound FK
+ * constraints with it. sqlite and mysql have no working cascade for inbound
+ * foreign keys — mysql refuses outright (errno 3730
+ * `ER_FK_CANNOT_DROP_PARENT`, observed live on 8.4 when a fixture switch
+ * dropped `Project` while the also-being-dropped `ProjectMember` still
+ * referenced it). ONE shared implementation, consumed by both renderers —
+ * the LEARNINGS rule: a structural rule is never re-implemented per consumer.
+ */
+import type { NormalizedSchema } from "../normalize.ts";
+/**
+ * Order the tables in `names` so that no table is dropped while another
+ * to-be-dropped table still references it. Tables unknown to `fromNorm` (or a
+ * missing `fromNorm`, or a reference cycle) fall back to the given order —
+ * rendering proceeds and the server reports what it cannot do (dialect
+ * honesty beats silently dropping statements).
+ */
+export declare function orderDropsChildrenFirst(params: {
+    names: readonly string[];
+    fromNorm: NormalizedSchema | undefined;
+}): string[];
+//# sourceMappingURL=drop-order.d.ts.map

package/dist/ddl/drop-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drop-order.d.ts","sourceRoot":"","sources":["../../src/ddl/drop-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACxC,GAAG,MAAM,EAAE,CAwCX"}

package/dist/ddl/mysql.d.ts

@@ -0,0 +1,46 @@
+/**
+ * MySQL DDL renderer: migration steps → SQL statements.
+ *
+ * Every identifier is backtick-quoted through `mysqlDialect.quoteIdent` — the
+ * ONE quoting decision point. Pinned choices:
+ *
+ * - String → varchar(191): utf8mb4 × 4 bytes keeps indexed String columns
+ *   inside the 767-byte legacy InnoDB index-key limit (`@db.Text` opts out —
+ *   TEXT columns are never indexed by us; indexing one would need a prefix
+ *   length we do not emit).
+ * - autoincrement renders `AUTO_INCREMENT` (the column must be a key — the
+ *   PRIMARY KEY clause in the same CREATE TABLE satisfies that; ALTERing one
+ *   onto an existing column is refused, pg parity).
+ * - Enums are inline `ENUM('A', 'B')` column types; the standalone enum steps
+ *   (createEnum/dropEnum/addEnumValue) render NOTHING — value changes arrive
+ *   as alterColumn steps (value-based type keys) and render as MODIFY COLUMN
+ *   with the widened list.
+ * - alterColumn type/nullability → one `MODIFY COLUMN` with the full target
+ *   definition (mysql redefines the column wholesale); default-only changes
+ *   use `ALTER COLUMN … SET/DROP DEFAULT`.
+ * - No partial indexes on mysql → VIBE_UNSUPPORTED_CAPABILITY naming the
+ *   index. Index kinds other than btree are refused the same way.
+ * - `DROP INDEX … ON table` needs the table — the differ's dropIndex steps
+ *   carry it; a step without one is a VIBE_MIGRATION error.
+ * - `DROP TABLE` has no cascade (mysql parses `CASCADE` and ignores it), and
+ *   dropping a parent still referenced by another to-be-dropped table fails
+ *   with errno 3730 `ER_FK_CANNOT_DROP_PARENT` (observed live on 8.4). FK
+ *   drops on SURVIVING tables come from the differ's bucket order; drops of
+ *   whole dependent groups are topologically reordered children-first here
+ *   (the shared `orderDropsChildrenFirst`, same rule as sqlite).
+ */
+import type { SchemaIR } from "@vibeorm/schema";
+import type { MigrationStep } from "../types.ts";
+/**
+ * Render migration steps to mysql SQL. `to` (the target schema) is required
+ * whenever an enum column is rendered — the inline `ENUM(…)` type needs the
+ * enum's values, which live on the schema, not the step. `from` enables the
+ * topological drop order (children before referenced parents); without it,
+ * drops render in step order.
+ */
+export declare function renderMysqlSteps(params: {
+    steps: readonly MigrationStep[];
+    from?: SchemaIR;
+    to?: SchemaIR;
+}): string[];
+//# sourceMappingURL=mysql.d.ts.map

package/dist/ddl/mysql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.d.ts","sourceRoot":"","sources":["../../src/ddl/mysql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAmB,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAMjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,EAAE,CAAC,EAAE,QAAQ,CAAC;CACf,GAAG,MAAM,EAAE,CAyBX"}

package/dist/ddl/postgres.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Postgres DDL renderer: migration steps → SQL statements.
+ *
+ * Every identifier is quoted through `postgresDialect.quoteIdent` — the ONE
+ * quoting decision point (@vibeorm/sql). Choices, each pinned by a renderer
+ * test:
+ *
+ * - autoincrement renders as `GENERATED BY DEFAULT AS IDENTITY` (SQL-standard,
+ *   no sequence-name coupling; postgres ≥10 and pglite both support it) — not
+ *   SERIAL. The introspector maps identity columns back to autoincrement.
+ * - `DROP TABLE ... CASCADE`: inbound FK constraints drop with the table.
+ * - scalar→array type changes carry the LEARNINGS `USING CASE WHEN col IS NULL
+ *   THEN NULL ELSE ARRAY[col] END` repair clause (postgres cannot implicit-cast).
+ * - `ALTER TYPE ... ADD VALUE IF NOT EXISTS` appends at the end of the enum
+ *   (no BEFORE/AFTER positioning); fine inside a transaction on postgres ≥12.
+ * - Unsupported columns render their `nativeType` verbatim and migrate like
+ *   any other column.
+ */
+import type { MigrationStep } from "../types.ts";
+/** Render migration steps to postgres SQL (one string per statement, in order). */
+export declare function renderPostgresSteps(params: {
+    steps: readonly MigrationStep[];
+}): string[];
+//# sourceMappingURL=postgres.d.ts.map

package/dist/ddl/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/ddl/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAYH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,GAAG,MAAM,EAAE,CAGzF"}

package/dist/ddl/render.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Dialect dispatcher for DDL rendering — the ONE public entry point. Routes to
+ * the per-dialect renderers (ddl/postgres.ts, ddl/sqlite.ts, ddl/mysql.ts) so
+ * every SQL-text decision stays in exactly one dialect module.
+ */
+import type { Dialect, SchemaIR } from "@vibeorm/schema";
+import type { MigrationStep } from "../types.ts";
+/**
+ * Render migration steps to SQL statements (one string per statement, in
+ * order) for a dialect.
+ *
+ * `from`/`to` — the schemas the steps were diffed from — are OPTIONAL for
+ * postgres (ignored) but needed by sqlite whenever a step compiles to the
+ * table-rebuild recipe (the target table shape lives on the schema, not the
+ * step) and by sqlite/mysql for enum columns (CHECK / inline ENUM values).
+ * `generateMigration` and `push` always pass them; direct callers rendering
+ * rebuild-free, enum-free steps may omit them.
+ */
+export declare function renderSteps(params: {
+    steps: readonly MigrationStep[];
+    dialect: Dialect;
+    from?: SchemaIR;
+    to?: SchemaIR;
+}): string[];
+//# sourceMappingURL=render.d.ts.map

package/dist/ddl/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/ddl/render.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAIzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAClC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,EAAE,CAAC,EAAE,QAAQ,CAAC;CACf,GAAG,MAAM,EAAE,CAsBX"}

package/dist/ddl/rls.d.ts

@@ -0,0 +1,40 @@
+import type { Dialect, ModelIR, SchemaIR } from "@vibeorm/schema";
+import type { MigrationStep } from "../types.ts";
+/** Whether a model requires ENABLE + FORCE and a managed policy. */
+export declare function isRlsProtected(params: {
+    model: ModelIR;
+}): boolean;
+/** Parent policies before through children; callers validate acyclic IR first. */
+export declare function orderedRlsModels(params: {
+    schema: SchemaIR;
+}): ModelIR[];
+/** RLS declarations refuse on unsupported dialects even when the physical diff is empty. */
+export declare function assertRlsDialect(params: {
+    schema: SchemaIR;
+    dialect: Dialect;
+}): void;
+/** Compose child-first policy drops, physical DDL, parent-first installations, then explicit removals. */
+export declare function withRlsSteps(params: {
+    from: SchemaIR;
+    to: SchemaIR;
+    steps: readonly MigrationStep[];
+}): MigrationStep[];
+/** Structural step discriminator shared by all three migration renderers. */
+export declare function isRlsStep(params: {
+    step: MigrationStep;
+}): boolean;
+/** Dispatch only: absence of a SQL-layer migration renderer is a loud refusal, never synthesized SQL. */
+export declare function renderRlsStep(params: {
+    step: MigrationStep;
+    dialect: Dialect;
+}): string[];
+/** Human preview of security changes, deliberately separate from destructive data steps. */
+export declare function securityChangesOf(params: {
+    steps: readonly MigrationStep[];
+}): string[];
+/** Shared push/apply/rollback refusal. Data-loss flags are intentionally not accepted here. */
+export declare function assertSecurityAcknowledgement(params: {
+    securityChanges: readonly string[];
+    acceptSecurityChanges?: boolean;
+}): void;
+//# sourceMappingURL=rls.d.ts.map

package/dist/ddl/rls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rls.d.ts","sourceRoot":"","sources":["../../src/ddl/rls.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAElE;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GAAG,OAAO,EAAE,CAgBxE;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAMrF;AAED,0GAA0G;AAC1G,wBAAgB,YAAY,CAAC,MAAM,EAAE;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,QAAQ,CAAC;IACb,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CACjC,GAAG,aAAa,EAAE,CAuDlB;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GAAG,OAAO,CAElE;AAED,yGAAyG;AACzG,wBAAgB,aAAa,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,CAmBzF;AAED,4FAA4F;AAC5F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,GAAG,MAAM,EAAE,CAEvF;AAED,+FAA+F;AAC/F,wBAAgB,6BAA6B,CAAC,MAAM,EAAE;IAAE,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAOnI"}

package/dist/ddl/sqlite.d.ts

@@ -0,0 +1,79 @@
+/**
+ * SQLite DDL renderer: migration steps → SQL statements, including THE TABLE
+ * REBUILD — sqlite has no ALTER COLUMN, cannot add/drop constraints, and its
+ * DROP COLUMN is heavily restricted, so any such step compiles to the
+ * documented 12-step recipe (https://sqlite.org/lang_altertable.html §7),
+ * emitted as an ordered, self-contained statement block:
+ *
+ *   PRAGMA foreign_keys=OFF;
+ *   BEGIN;
+ *   CREATE TABLE "T_new" (…target shape: columns, PK, FKs, enum CHECKs…);
+ *   INSERT INTO "T_new" (common cols) SELECT common cols FROM "T";
+ *   DROP TABLE "T";
+ *   ALTER TABLE "T_new" RENAME TO "T";
+ *   CREATE …INDEX… (every index of the target table);
+ *   PRAGMA foreign_key_check;
+ *   COMMIT;
+ *   PRAGMA foreign_keys=ON;
+ *
+ * Because the block manages its own transaction (PRAGMA foreign_keys is a
+ * no-op inside one), callers must NOT wrap scripts containing it — push and
+ * the runner detect this via `usesSelfManagedTransactions` (execute.ts).
+ * Rebuild blocks are emitted AFTER all other statements so a rebuilt table's
+ * new FKs can reference tables created earlier in the same script — EXCEPT a
+ * rebuild that removes an FK to a table this migration drops, which is hoisted
+ * ahead of the drops: sqlite's DROP TABLE cascades into surviving child rows
+ * while the FK is still installed (F27).
+ *
+ * Cheap paths are preferred wherever sqlite's plain ALTER suffices:
+ * `ADD COLUMN` (unless the column is required without a literal default, or
+ * defaults to CURRENT_TIMESTAMP / an expression — both forbidden in ADD
+ * COLUMN) and `DROP COLUMN` (unless the column is in the PK, any index or
+ * partial-index predicate, an FK on either side, or carries an enum CHECK).
+ *
+ * Column-value transfer on rebuild: dropped columns are omitted, added
+ * columns take their default (or NULL), type-changed columns are a PLAIN COPY
+ * — sqlite's flexible typing keeps the stored values as-is, so e.g. non-numeric
+ * TEXT survives verbatim inside an INTEGER column (documented lossy-ness:
+ * nothing is coerced, nothing is validated beyond the new CHECK constraints).
+ *
+ * Other pinned choices:
+ * - autoincrement renders `INTEGER PRIMARY KEY AUTOINCREMENT` (monotonic ids,
+ *   Prisma parity) — plain `INTEGER PRIMARY KEY` would reuse rowids after
+ *   deletes. The `PRIMARY KEY AUTOINCREMENT` text is also the introspection
+ *   marker. Costs the `sqlite_sequence` bookkeeping table (skipped on pull).
+ * - Composite / non-autoincrement PKs render as an unnamed table-level
+ *   `PRIMARY KEY (…)` (sqlite keeps constraint names only as noise).
+ * - Enums render TEXT + a NAMED column-level CHECK (see sqlite-types.ts) —
+ *   the name (`<table>_<column>_enum_<Enum>`) is how pull recovers the enum.
+ * - `DROP TABLE` has no CASCADE on sqlite; table drops are topologically
+ *   ordered (referencing tables first) using the `from` schema.
+ * - Index kinds other than btree/unique throw VIBE_UNSUPPORTED_CAPABILITY.
+ */
+import type { SchemaIR } from "@vibeorm/schema";
+import type { MigrationStep } from "../types.ts";
+/**
+ * Render migration steps to sqlite SQL. `from`/`to` (the schemas that produced
+ * the steps) are required whenever a step triggers a table rebuild or renders
+ * an enum column — `generateMigration` and `push` always pass them.
+ */
+export declare function renderSqliteSteps(params: {
+    steps: readonly MigrationStep[];
+    from?: SchemaIR;
+    to?: SchemaIR;
+}): string[];
+/**
+ * Tables whose sqlite DDL will DROP and re-create them (the rebuild recipe) or
+ * drop them outright — i.e. every table that loses its attached objects.
+ * SQLite's `DROP TABLE` takes the table's triggers with it, and the rebuild
+ * restores only the core indexes, so callers holding extension artifacts (FTS
+ * synchronization triggers) must re-create theirs afterwards (F31).
+ */
+export declare function sqliteInvalidatedTables(params: {
+    steps: readonly MigrationStep[];
+    from?: SchemaIR;
+}): {
+    rebuilt: Set<string>;
+    dropped: Set<string>;
+};
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/ddl/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/ddl/sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAGH,OAAO,KAAK,EAAmB,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAajE,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,aAAa,CAAC;AAK9D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,EAAE,CAAC,EAAE,QAAQ,CAAC;CACf,GAAG,MAAM,EAAE,CA0NX;AAgED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB,GAAG;IAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CAUjD"}

package/dist/differ.d.ts

@@ -0,0 +1,41 @@
+/**
+ * IR-vs-IR schema differ → dialect-neutral migration steps.
+ *
+ * The contract that matters most: `diffSchemas({ from: introspect(push(X)),
+ * to: X })` is EMPTY — both sides normalize through normalize.ts before
+ * comparison, so representation differences (implicit list sides vs explicit
+ * M2M fields, `@unique` vs `@@unique`, app-level defaults, cascade-action
+ * defaults) never produce phantom steps and `db push` twice is a no-op.
+ *
+ * No rename detection (v1 parity): a renamed table/column diffs as drop +
+ * create. Removing a value from a surviving enum throws
+ * VIBE_UNSUPPORTED_CAPABILITY — postgres cannot drop enum values without a
+ * manual type rebuild, and silence would be dialect dishonesty.
+ */
+import type { Dialect, SchemaIR } from "@vibeorm/schema";
+import type { RenameIntent } from "./renames.ts";
+import type { MigrationStep } from "./types.ts";
+/**
+ * Diff two Schema IRs into an ordered list of dialect-neutral migration steps
+ * that transform the `from` database shape into the `to` shape.
+ *
+ * `dialect` (default postgres) selects the comparison rules: sqlite/mysql
+ * compare columns by physical type (see normalize.ts), refuse scalar-list
+ * columns up front (no array types — VIBE_UNSUPPORTED_CAPABILITY naming the
+ * model.field), skip standalone enum steps (their enums are inline: TEXT +
+ * CHECK on sqlite, `ENUM(…)` on mysql — value changes flow through
+ * `alterColumn`), and refuse enum-value REMOVAL at the column level.
+ */
+export declare function diffSchemas(params: {
+    from: SchemaIR;
+    to: SchemaIR;
+    dialect?: Dialect;
+    /**
+     * EXPLICIT physical renames, written down by whoever wants them (renames.ts).
+     * Applied to the source schema before the diff runs, so a renamed table or
+     * column produces a rename step instead of the drop/create pair the differ
+     * would otherwise — correctly — derive. Nothing here is ever inferred.
+     */
+    renames?: readonly RenameIntent[];
+}): MigrationStep[];
+//# sourceMappingURL=differ.d.ts.map

package/dist/differ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../src/differ.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAU,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAOjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAqB,aAAa,EAAE,MAAM,YAAY,CAAC;AAoCnE;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,QAAQ,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CACnC,GAAG,aAAa,EAAE,CAmElB"}

package/dist/down.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Down-migration generation: the REVERSE diff of an up migration, with v1's
+ * two rollback rules baked in (LEARNINGS / issue #15):
+ *
+ * 1. RE-ADDED COLUMNS COME BACK NULLABLE. The reverse of `dropColumn` is
+ *    `addColumn`, but the dropped column's data is gone — re-adding it
+ *    NOT NULL would fail on any populated table. Every `addColumn` step in a
+ *    down migration is therefore forced optional (its default, when present,
+ *    is kept). Whole-table re-creates (`createTable`) keep their NOT NULLs:
+ *    the re-created table is empty.
+ * 2. IRREVERSIBLE UP-STEPS ARE SKIPPED, NOT THROWN. An up migration that
+ *    added an enum value has no reverse — postgres cannot drop enum values,
+ *    and sqlite/mysql refuse narrowing an inline enum whose rows may hold the
+ *    value. The rollback target keeps those values and the skip is reported
+ *    in `skipped`, so "undo the last migration" still works (v1's
+ *    `isReversible: false` behavior).
+ *
+ * Extension artifacts: object artifacts the up migration created (columns,
+ * indexes, shadow tables, triggers) are dropped by the down migration via
+ * their own `drop` SQL. `CREATE EXTENSION`-class artifacts are never dropped
+ * — other database objects may depend on the extension — and are reported in
+ * `skipped` instead.
+ */
+import type { Dialect, SchemaIR, VibeExtension } from "@vibeorm/schema";
+/** A generated down migration: reverse SQL plus what could NOT be reversed. */
+export type DownMigrationFile = {
+    readonly name: string;
+    /** One SQL string per statement, in execution order. */
+    readonly sql: readonly string[];
+    /** True when any reverse step can lose data (e.g. dropping an up-added column). */
+    readonly destructive: boolean;
+    /** Separate review category: never covered by acceptDataLoss. */
+    readonly securityChanges?: readonly string[];
+    /**
+     * Human descriptions of up-changes this down migration cannot reverse
+     * (added enum values, installed postgres extensions). Empty = full reverse.
+     */
+    readonly skipped: readonly string[];
+};
+/**
+ * Generate the DOWN migration for an up migration described by the same
+ * `from`/`to` pair handed to `generateMigration`: `from` is the current
+ * database shape, `to` the schema the up migration moves to. The down
+ * migration transforms `to` back into `from` (modulo the skipped
+ * irreversibles), so callers write it alongside the up file and apply it
+ * newest-first to roll back.
+ */
+export declare function generateDownMigration(params: {
+    from: SchemaIR;
+    to: SchemaIR;
+    name: string;
+    /** Rendering dialect; postgres if omitted. */
+    dialect?: Dialect;
+    /** Configured extension instances — their up-created artifacts are dropped. */
+    extensions?: readonly VibeExtension[];
+}): DownMigrationFile;
+//# sourceMappingURL=down.d.ts.map

package/dist/down.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"down.d.ts","sourceRoot":"","sources":["../src/down.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAU,QAAQ,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAahF,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAyDF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,QAAQ,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACvC,GAAG,iBAAiB,CAwDpB"}

package/dist/enum-values.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Enum-value resolution shared by the sqlite/mysql type mappers.
+ *
+ * On dialects without named enum types (sqlite: TEXT + CHECK, mysql: inline
+ * `ENUM(...)`) the enum's NAME does not survive in the database — only its
+ * VALUES do. Column comparison keys and DDL rendering therefore resolve a
+ * field's enum reference to its value list; the name is presentation only.
+ */
+import type { Dialect, EnumIR, FieldIR } from "@vibeorm/schema";
+/**
+ * Resolve an enum name to its values. The map is keyed by db name
+ * (`dbName ?? name`, the normalize.ts convention); a schema-side reference by
+ * IR name falls back to a scan so both key styles resolve.
+ */
+export declare function resolveEnumValues(params: {
+    name: string;
+    enums: ReadonlyMap<string, EnumIR>;
+}): readonly string[] | undefined;
+/** Storage transitions are detected on physical fields, after normalization. */
+export declare function isEnumStringTransition(params: {
+    from: FieldIR;
+    to: FieldIR;
+}): boolean;
+/** Shared differ/renderer backstop for storage casts that are not yet lossless. */
+export declare function assertEnumStringTransition(params: {
+    from: FieldIR;
+    to: FieldIR;
+    dialect: Dialect;
+    table: string;
+    column: string;
+}): void;
+//# sourceMappingURL=enum-values.d.ts.map

package/dist/enum-values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum-values.d.ts","sourceRoot":"","sources":["../src/enum-values.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAQhC;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAGtF;AAED,mFAAmF;AACnF,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAaxI"}