ferro-orm 0.21.0__tar.gz → 0.21.2__tar.gz

{ferro_orm-0.21.0 → ferro_orm-0.21.2}/.github/workflows/ci.yml

@@ -127,7 +127,7 @@ jobs:
 
       - name: Static type gate (ty, scoped)
         run: |
-          uv run ty check src/ferro/query tests/test_query_typing.py tests/test_static_contracts.py
+          uv run ty check src/ferro/query tests/test_query_typing.py tests/test_static_contracts.py tests/test_alembic_typing.py
 
       - name: Run IR vector contract harness
         run: |

{ferro_orm-0.21.0 → ferro_orm-0.21.2}/AGENTS.md

@@ -181,6 +181,51 @@ For a single model, every emitter must agree on:
     connect-time warnings remain the only word on them. See ADR-0019
     (rebuild the bodies ferro writes, report the bodies you write; flags are
     one-way) and PRD #406.
+17. **Enum type provenance** — the decision of which declared native enum
+    types a generated revision *introduces* (every column declaring the
+    type is one the revision adds: a created table's column or an
+    `add_column`), how an introduced type comes into being (`Inline`: a
+    `create_table` of the revision carries it and SQLAlchemy creates it
+    with the table; `Statement`: every column of it is an `add_column`, so
+    the revision must execute the `CREATE TYPE` itself, #439), and which
+    types it merely *reuses* (an added column declares it, but so does a
+    column the downgrade leaves standing or puts back), together with the
+    rendered `CREATE TYPE` and `DROP TYPE`, are decided by ONE trio of
+    functions: `ferro_ddl_lowering::enum_type_provenance` (one
+    `Introduced { creation } | Reused` verdict per touched type) /
+    `render_pg_enum_create_type` (the runtime create pass's guarded
+    statement; never a second renderer) / `render_pg_enum_drop_type`.
+    SQLAlchemy creates the type inline with `create_table`, unconditionally,
+    and nowhere else, and Alembic has no op for it, so the rendered
+    `downgrade()` never dropped it (#438), a `create_table` reusing a live
+    type re-issued `CREATE TYPE` and failed with `DuplicateObject` (#443),
+    and an `add_column` of a new type failed with `UndefinedObject` (#439).
+    The Alembic autogenerate comparator (`FerroEnumTypeIntroducedOp` /
+    `FerroEnumTypeDropOp` in `src/ferro/migrations/alembic.py`) consumes
+    the verdicts over FFI (`_core._plan_enum_type_provenance`, which carries
+    `create_statement` and `drop_statement`): an introduced type keeps its
+    inline creation, or gets the byte-identical guarded `CREATE TYPE`
+    ahead of every table op when only `add_column`s carry it, and gets the
+    byte-identical `DROP TYPE` on downgrade, after the last `drop_table` /
+    `drop_column`; a reused type gets neither and every `create_table`
+    column of it rewritten to
+    `postgresql.ENUM(..., create_type=False)` (`add_column` never creates a
+    type, so it is left alone). SQLAlchemy's `repr` omits that flag, so it
+    is rendered by the bridge's `render_item` hook
+    (`ferro.migrations.render_item`, wired in `env.py`); a revision that
+    needs it in a context that lacks it is refused at autogenerate with the
+    line to add, never written with an upgrade that fails later. The
+    decision is made from the revision alone, never from the live catalog,
+    so the file means the same thing on every database it runs against.
+    Pinned by `tests/test_alembic_enum_type_drop.py`,
+    `test_enum_type_provenance_parity_pin` and the ferro-ddl-lowering unit
+    pins. Postgres-only (SQLite enums store as text); Alembic-only by
+    construction (auto-migrate has no downgrade door, and its create pass
+    executes the same guarded `CREATE TYPE` itself), so the single-source
+    rule applies and the create statement is the one artifact with a
+    runtime twin to pin against. Ownership is by provenance (ADR-0020);
+    the upgrade side mirrors it (ADR-0021) and completes it for the
+    `add_column`-only shape (ADR-0022).
 
 ### Why this invariant exists
 
@@ -477,14 +522,29 @@ ops `extend` the list while it still has no table ops (#423).
 After-tables families (`ADD CONSTRAINT` over a new column, `CREATE POLICY`
 on a new table) register at `priority=LAST`. Before-tables families (enum
 label addition) register at `priority=FIRST` and insert at the front of the
-ops list. Default `MEDIUM` is an I-12 violation for ferro schema
-comparators. Alembic's own table comparator may remain `MEDIUM`. A
-same-revision pin is required for every after-tables family.
+ops list. The enum type provenance family (#438, #439) is before-tables on
+upgrade (the `CREATE TYPE` for a type only `add_column`s carry must precede
+those `add_column`s) and after-tables on downgrade (`DROP TYPE` is only
+legal after every `drop_table` / `drop_column`); it reads the revision's
+`create_table` and `add_column` ops to decide, so it registers at
+`priority=LAST`, but inserts at the front of the ops list, and the one
+placement serves both sides: `UpgradeOps.reverse()` reverses order, so an
+op ahead of every `create_table` lands behind every `drop_table` in the
+downgrade. The priority says when a comparator runs; the insertion point
+says where its op renders. Default `MEDIUM` is an I-12 violation for
+ferro schema comparators. Alembic's own table comparator may remain
+`MEDIUM`. A same-revision pin is required for every after-tables family
+and for the before-tables upgrade statement.
 
 Pinned by the row-security comparator's LAST registration and
 `test_new_declaration_on_a_brand_new_table_lands_after_create_table`, and
 by `test_autogenerate_adds_a_column_before_the_check_that_references_it`
-(#423). Architecture review: I-19 in #427. See PRD #429 and
+(#423), for the downgrade-after-tables slot by
+`test_a_type_shared_by_two_new_tables_drops_once_after_both_tables`
+(#438), and for the before-tables type creation by
+`test_a_type_introduced_by_add_column_alone_is_created_and_dropped` and
+`test_a_type_created_by_statement_lands_before_tables_beside_label_additions`
+(#439). Architecture review: I-19 in #427. See PRD #429 and
 `docs/solutions/patterns/alembic-comparator-slot.md`.
 
 ---

{ferro_orm-0.21.0 → ferro_orm-0.21.2}/CHANGELOG.md

@@ -1,6 +1,48 @@
 # CHANGELOG
 
 
+## v0.21.2 (2026-09-29)
+
+### Bug Fixes
+
+- **alembic**: Create add_column-only enum types, type render_item, close the label-addition block
+  ([#448](https://github.com/syn54x/ferro-orm/pull/448),
+  [`dc49156`](https://github.com/syn54x/ferro-orm/commit/dc49156be6b8c998fd726230bc5a1ffb5fce15c4))
+
+
+## v0.21.1 (2026-09-28)
+
+### Bug Fixes
+
+- **alembic**: Drop enum types in the downgrade of the create_table that made them
+  ([#441](https://github.com/syn54x/ferro-orm/pull/441),
+  [`5c86b7f`](https://github.com/syn54x/ferro-orm/commit/5c86b7fef03828443fd61852caa3705849e3150f))
+
+- **alembic**: Render create_type=False for enum types a revision reuses
+  ([#445](https://github.com/syn54x/ferro-orm/pull/445),
+  [`6776d0b`](https://github.com/syn54x/ferro-orm/commit/6776d0b7b13499d85666280a623f91fbf2df6387))
+
+- **checks**: Compare associative OR/AND chains flat in the drift normalizer
+  ([#442](https://github.com/syn54x/ferro-orm/pull/442),
+  [`4df72a2`](https://github.com/syn54x/ferro-orm/commit/4df72a2d37b456d79ba1fc9cfa6b5ba2a0c6f194))
+
+### Documentation
+
+- Replace Pinch RLS examples and humanize guide prose
+  ([#433](https://github.com/syn54x/ferro-orm/pull/433),
+  [`4471d75`](https://github.com/syn54x/ferro-orm/commit/4471d7510f7bf6b642f13e5f768ac723bbdb2288))
+
+- Unpack dense Why Ferro, query, and RLS prose
+  ([#434](https://github.com/syn54x/ferro-orm/pull/434),
+  [`1af08af`](https://github.com/syn54x/ferro-orm/commit/1af08af1288d670139fa5f0beab19bf7b19d8c8c))
+
+### Refactoring
+
+- **alembic**: Enum type drop cleanups from the #441 review panel
+  ([#444](https://github.com/syn54x/ferro-orm/pull/444),
+  [`ae6b6d3`](https://github.com/syn54x/ferro-orm/commit/ae6b6d387d40727a79cb0f8a96c5151daffa1dbb))
+
+
 ## v0.21.0 (2026-09-17)
 
 ### Bug Fixes

{ferro_orm-0.21.0 → ferro_orm-0.21.2}/CONTEXT.md

@@ -149,7 +149,7 @@ The `migrate_updates` step that alters existing schema objects — tables and fe
 _Avoid_: Update pass, schema sync, drift repair
 
 **Ferro-owned artifact**:
-A schema object ferro may reconcile to match the declared model. Indexes and constraints are ferro-owned by naming (`idx_`, `uq_`, `fk_`, `ck_`); native enum types are ferro-owned by derivation — the type's name matches the name ferro derives from the model. Artifacts owned neither way belong to the user and are never altered or dropped.
+A schema object ferro may reconcile to match the declared model. Indexes and constraints are ferro-owned by naming (`idx_`, `uq_`, `fk_`, `ck_`); native enum types are ferro-owned by derivation — the type's name matches the name ferro derives from the model. A generated revision owns an enum type a third way, by provenance: it introduces every column of the type, so its downgrade drops the type (see *Type drop*); a type it adds a column of but does not introduce is one it reuses, never creates (see *Type reuse*). Artifacts owned none of these ways belong to the user and are never altered or dropped.
 _Avoid_: Managed index, system constraint, internal index
 
 **Enum label**:
@@ -160,6 +160,18 @@ _Avoid_: Enum value, variant, choice
 The reconciliation-pass operation appending model-declared labels missing from a live ferro-owned enum type. Append-only and metadata-only: rows are never touched, and labels the database has but the model lacks are warned about loudly and never removed — removal and rename are reviewed-migration territory.
 _Avoid_: Enum sync, label reconciliation, enum evolution
 
+**Type drop**:
+The reverse of a generated revision's creation of a native enum type — inline with `create_table`, or by *Type creation* when only `add_column`s carry it: the `DROP TYPE` the revision's `downgrade()` emits, after its last `drop_table` and `drop_column`, for each native enum type the revision introduces — every column declaring it is one the revision adds, and none is one the downgrade puts back. Decided from the revision alone, never from the live catalog; the type is the revision's by provenance, not derivation (ADR-0020). Alembic core has no operation for either direction; ferro's bridge supplies the drop, and the creation for the `add_column`-only shape, so a downgrade leaves no type behind and an upgrade finds every type it needs.
+_Avoid_: Enum cleanup, type teardown, cascade drop
+
+**Type creation**:
+The `CREATE TYPE` a generated revision's `upgrade()` executes, ahead of its table operations, for a native enum type it introduces (see *Type drop*) that no `create_table` of the revision carries — every column of it is an `add_column`, and SQLAlchemy creates a named enum type inline with `create_table` only. It is the runtime create pass's guarded statement, rendered by the same function, so both migration doors run the same SQL for the same model; a type a `create_table` carries is created inline by SQLAlchemy and gets no statement. The second axis of the one type-provenance decision (ADR-0022).
+_Avoid_: Explicit enum create, add_column type fix, pre-create
+
+**Type reuse**:
+A generated revision's use of a native enum type it does not introduce — a column the revision adds declares it, but so does a column the downgrade leaves standing or puts back — so the type already lives on every database the revision can run against. The revision's `create_table` columns of that type render as `postgresql.ENUM(..., create_type=False)` (through the bridge's `render_item` hook, since SQLAlchemy's `repr` omits the flag) and no `DROP TYPE` is emitted. The other verdict of the one type-provenance decision that also decides the type drop, made from the revision alone (ADR-0021).
+_Avoid_: Shared type, existing type, live-type exclusion
+
 **Constraint rebuild**:
 Drop-and-recreate of a ferro-owned constraint whose live definition no longer matches the declared model — a foreign key's `on_delete`, its target, its columns, or a table check's predicate. Metadata-only: rows are never touched. On a backend that cannot alter constraints, ferro warns loudly and skips; it never diverges silently.
 _Avoid_: Constraint alter, FK patch, in-place constraint update

{ferro_orm-0.21.0 → ferro_orm-0.21.2}/Cargo.lock

@@ -46,9 +46,9 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
 [[package]]
 name = "bigdecimal"
-version = "0.4.10"
+version = "0.4.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4d6867f1565b3aad85681f1015055b087fcfd840d6aeee6eee7f2da317603695"
+checksum = "8fa3f3d8cbf4dffcfe4991de61d012bef509a409ecbe9dd41049bfe32b4d4653"
 dependencies = [
  "autocfg",
  "libm",
@@ -95,9 +95,9 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "cc"
-version = "1.4.6"
+version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a3eb0f42d6c360dc3f8a821f6bf2fdea7f72bfd36b3076eb0e6d1e9e0752fff4"
+checksum = "f360145194ee8e21db5ee7f3fcd4fe52210864c75c985dae33218202c8bbe040"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -317,7 +317,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.21.0"
+version = "0.21.2"
 dependencies = [
  "chrono",
  "dashmap",
@@ -365,9 +365,9 @@ dependencies = [
 
 [[package]]
 name = "find-msvc-tools"
-version = "0.1.12"
+version = "0.1.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3e0f1c7c3a72c66fd80abe965175f7523475c0489a87d3ff9d6e8c87d87a9d2d"
+checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484"
 
 [[package]]
 name = "flume"
@@ -781,9 +781,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "js-sys"
-version = "0.3.105"
+version = "0.3.106"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce57d20d1ea864ce2ac172ab472d409214f4fd359f0b2a2775abdf522e2af99e"
+checksum = "7883d941dae510fb2d978fc3fe018c71c9e2892fd38854de3e8b92c2e5ad9cc5"
 dependencies = [
  "cfg-if",
  "futures-util",
@@ -813,9 +813,9 @@ checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
 
 [[package]]
 name = "libredox"
-version = "0.1.24"
+version = "0.1.25"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6480ccc157a1389bb2e4891b24751b0f798ba640d22386f23143fbcc89da195a"
+checksum = "61ff90caf6077a803a240f62fdbe88645a890bbca49ef8174c3cb0404362171d"
 dependencies = [
  "bitflags",
  "libc",
@@ -1427,9 +1427,9 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "smallvec"
-version = "1.16.1"
+version = "1.16.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ba467056f1b547ed52077911161fc86985becbc60e8e1857c8a144dab0def891"
+checksum = "f9395f0f0eee849a9b707b2f06bb92a6a422090e2123bb2ef8e87a0e61892a8e"
 dependencies = [
  "serde",
 ]
@@ -1729,18 +1729,18 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "thiserror"
-version = "2.0.20"
+version = "2.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
+checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e"
 dependencies = [
  "thiserror-impl",
 ]
 
 [[package]]
 name = "thiserror-impl"
-version = "2.0.20"
+version = "2.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
+checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1848,9 +1848,9 @@ checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5"
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.25"
+version = "1.0.26"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ab72a15cf68d77cb0987d3684aa8a45c5ef827e8cb49ee2f30bfd7ba2feb519f"
+checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
 
 [[package]]
 name = "unicode-normalization"
@@ -1934,9 +1934,9 @@ checksum = "b8dad83b4f25e74f184f64c43b150b91efe7647395b42289f38e50566d82855b"
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.128"
+version = "0.2.129"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aecb87a33d3b0c5e3b7aa46336eaf486cffafbd281b195e4c8b80d50df2351bf"
+checksum = "9bb54f33acc68fd454578d9820b0bde1a1a3d17aa17bb7b6595806d02886d409"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -1947,9 +1947,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.128"
+version = "0.2.129"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a690d511e3c1a8b3a55e33511e3c2c00c78415cd23650f32b808627f5696b9ed"
+checksum = "2e29d0c35b16e224a7eeb5cd2d25e3e1968fbd65604117b44d3b789d00ee8535"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -1957,9 +1957,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.128"
+version = "0.2.129"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "411e4887f0071ef2d2164a9d5fdf2d20efbef78fccd3a78b0c10a1dc5295e48a"
+checksum = "6f501a8bc3719dba86ef8ae4728879c08001bea749eb1333ac5b91e040e2a6b7"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -1970,9 +1970,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.128"
+version = "0.2.129"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "81941cd78d0c92026c33e5e01312845a4cb1e9af3407f9134b100dd03144103e"
+checksum = "23f0c9c52aa7cd7d77769a4cfe2a9adb1b331f489a41d912ce14513d5ab995c6"
 dependencies = [
  "unicode-ident",
 ]
@@ -2243,18 +2243,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.57"
+version = "0.8.59"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d35102a9f36d089ccae9e4c6802bc118be4487b80aaffc0ab4e0cf5ce92d2873"
+checksum = "6df92bf3d9227be3d53173901ddbffac2babc27ae50f397776ffd6dc33f800cb"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.57"
+version = "0.8.59"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "146c01f5ab44258da43cf276c74a2763db2ff3969c9c652c3f2de07041d0b2bc"
+checksum = "ac4f328cf2f05d084e496c3e9c3f33ed0a183656a16e1fcec4d464d8373aec82"
 dependencies = [
  "proc-macro2",
  "quote",

{ferro_orm-0.21.0 → ferro_orm-0.21.2}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferro-schema-ir", "crates/ferro-ddl-lowering", "crates/ferro-
 
 [package]
 name = "ferro"
-version = "0.21.0"
+version = "0.21.2"
 edition = "2024"
 readme = "README.md"
 

{ferro_orm-0.21.0 → ferro_orm-0.21.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.21.0
+Version: 0.21.2
 Requires-Dist: pydantic>=2.0
 Requires-Dist: alembic>=1.18.1 ; extra == 'alembic'
 Requires-Dist: sqlalchemy>=2.0.46 ; extra == 'alembic'