ferro-orm 0.17.1__tar.gz → 0.18.0__tar.gz

{ferro_orm-0.17.1 → ferro_orm-0.18.0}/AGENTS.md

@@ -50,6 +50,16 @@ For a single model, every emitter must agree on:
    and `db_check_constraint_name` (Rust).
 9. **Default values** — server-side defaults must serialize identically.
 10. **Nullability** — must agree.
+11. **Enum label additions** — the label-addition decision (which model-declared
+    labels a live enum type is missing, and which live labels are extra) and
+    the rendered `ALTER TYPE ... ADD VALUE IF NOT EXISTS` statement are decided
+    by ONE pair of functions: `ferro_ddl_lowering::missing_enum_labels` /
+    `extra_enum_labels` + `render_pg_enum_add_value`. The auto-migrate
+    reconciliation pass consumes them directly; the Alembic autogenerate
+    comparator consumes them over FFI (`_core._plan_enum_label_addition`) and
+    executes the byte-identical statements. Pinned by
+    `tests/test_cross_emitter_parity.py` and the ferro-ddl-lowering unit pins.
+    See ADR-0011 (append-only; update-gated; warn-never-act for extras).
 
 ### Why this invariant exists
 

{ferro_orm-0.17.1 → ferro_orm-0.18.0}/CHANGELOG.md

@@ -1,6 +1,38 @@
 # CHANGELOG
 
 
+## v0.18.0 (2026-08-05)
+
+### Documentation
+
+- **adr**: ADR-0011 label addition + glossary terms (enum label, label addition)
+  ([`449616f`](https://github.com/syn54x/ferro-orm/commit/449616f07aefe473fe098f45f6873eb2003cf8e5))
+
+- **migrate**: Label addition — the auto_migrate trap, the migrate_updates contract, the ordering
+  caveat ([#334](https://github.com/syn54x/ferro-orm/pull/334),
+  [`482911b`](https://github.com/syn54x/ferro-orm/commit/482911b441eeeed21b13d3927c9492797bb1eba5))
+
+### Features
+
+- **alembic**: Autogenerate comparator emits label additions from the shared diff
+  ([#333](https://github.com/syn54x/ferro-orm/pull/333),
+  [`1579fc3`](https://github.com/syn54x/ferro-orm/commit/1579fc38a7f0d2b94c4ea51aa7daac652df30abc))
+
+- **migrate**: Label addition tracer — migrate_updates appends missing enum labels
+  ([#330](https://github.com/syn54x/ferro-orm/pull/330),
+  [`e929a6a`](https://github.com/syn54x/ferro-orm/commit/e929a6ae854fd435c6aac3277e476c15b106f73a))
+
+- **migrate**: Warn-never-act for extra enum labels; create pass stays silent
+  ([#331](https://github.com/syn54x/ferro-orm/pull/331),
+  [`a73d142`](https://github.com/syn54x/ferro-orm/commit/a73d142e2ff22ef8e47c2a8b8c34ca92372d0487))
+
+### Testing
+
+- **migrate**: Label addition edges — shared types, default-in-same-run, ordering, idempotence
+  ([#332](https://github.com/syn54x/ferro-orm/pull/332),
+  [`1215f0c`](https://github.com/syn54x/ferro-orm/commit/1215f0c0e52367eafd91411b7b7891220edf318e))
+
+
 ## v0.17.1 (2026-07-19)
 
 ### Bug Fixes

{ferro_orm-0.17.1 → ferro_orm-0.18.0}/CONTEXT.md

@@ -129,13 +129,21 @@ The auto-migrate step that brings missing tables into existence — the table, i
 _Avoid_: Bootstrap, ensure-tables, table sync
 
 **Reconciliation pass**:
-The `migrate_updates` step that alters existing tables to match the registered models — the only authority for DDL against a table that already exists. Within one table, column changes land before the indexes and constraints that reference them.
+The `migrate_updates` step that alters existing schema objects — tables and ferro-owned enum types — to match the registered models; the only authority for DDL against an object that already exists. Within one table, column changes land before the indexes and constraints that reference them; label additions land before any table's changes.
 _Avoid_: Update pass, schema sync, drift repair
 
 **Ferro-owned artifact**:
-An index or constraint whose name follows ferro's canonical naming (`idx_`, `uq_`, `fk_`, `ck_`), marking it as reconcilable: auto-migrate may create, rebuild, or drop it to match the declared model. Artifacts named any other 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. Artifacts owned neither way belong to the user and are never altered or dropped.
 _Avoid_: Managed index, system constraint, internal index
 
+**Enum label**:
+One storable value of a native Postgres enum type, mirrored from a Python `StrEnum` member's value. Members are the Python-side declaration; labels are what the database accepts and stores.
+_Avoid_: Enum value, variant, choice
+
+**Label addition**:
+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
+
 **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. 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.17.1 → ferro_orm-0.18.0}/Cargo.lock

@@ -10,9 +10,9 @@ checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
 
 [[package]]
 name = "android_system_properties"
-version = "0.1.5"
+version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
+checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
 dependencies = [
  "libc",
 ]
@@ -95,9 +95,9 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "cc"
-version = "1.3.0"
+version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c89588d05638b5b4594a3348a2d6c20277e43a7f5c5202b05cc56888475a47b8"
+checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -120,15 +120,6 @@ dependencies = [
  "windows-link",
 ]
 
-[[package]]
-name = "concurrent-queue"
-version = "2.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
-dependencies = [
- "crossbeam-utils",
-]
-
 [[package]]
 name = "const-oid"
 version = "0.9.6"
@@ -263,13 +254,13 @@ dependencies = [
 
 [[package]]
 name = "displaydoc"
-version = "0.2.6"
+version = "0.2.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
+checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn 3.0.3",
 ]
 
 [[package]]
@@ -280,9 +271,9 @@ checksum = "1aaf95b3e5c8f23aa320147307562d361db0ae0d51242340f558153b4eb2439b"
 
 [[package]]
 name = "either"
-version = "1.16.0"
+version = "1.17.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
+checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"
 dependencies = [
  "serde",
 ]
@@ -316,18 +307,17 @@ dependencies = [
 
 [[package]]
 name = "event-listener"
-version = "5.4.1"
+version = "5.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e13b66accf52311f30a0db42147dadea9850cb48cd070028831ae5f5d4b856ab"
+checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2"
 dependencies = [
- "concurrent-queue",
  "parking",
  "pin-project-lite",
 ]
 
 [[package]]
 name = "ferro"
-version = "0.17.1"
+version = "0.18.0"
 dependencies = [
  "chrono",
  "dashmap",
@@ -778,7 +768,7 @@ checksum = "bee2c455ca60511a054699102d40ce7153621cb2429558f9eaa600e4499b5984"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.0",
+ "syn 3.0.3",
 ]
 
 [[package]]
@@ -809,9 +799,9 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.186"
+version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 
 [[package]]
 name = "libm"
@@ -821,14 +811,14 @@ checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
 
 [[package]]
 name = "libredox"
-version = "0.1.18"
+version = "0.1.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c943259e342f1e06ff2da7a83eabdfe7f92ce10262688dbf1895ff0b3e6e4652"
+checksum = "2026a5056764a10b2bf5d56488cba40da507f5493a6a429340e2004d9ed085fa"
 dependencies = [
  "bitflags",
  "libc",
  "plain",
- "redox_syscall 0.9.0",
+ "redox_syscall 0.9.1",
 ]
 
 [[package]]
@@ -1206,9 +1196,9 @@ dependencies = [
 
 [[package]]
 name = "redox_syscall"
-version = "0.9.0"
+version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c5102a6aaa05aa011a238e178e6bca86d2cb56fc9f586d37cb80f5bca6e07759"
+checksum = "07507be7b4a5f9f26eeb41eeaebb1f5a7ff29dfb29739facc21d35bf8b11c21e"
 dependencies = [
  "bitflags",
 ]
@@ -1249,9 +1239,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.42"
+version = "0.23.43"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138"
+checksum = "0283386ce02abc0151e1761d08802dfe86c173b0b494af5cbc086574e453da06"
 dependencies = [
  "once_cell",
  "ring",
@@ -1263,9 +1253,9 @@ dependencies = [
 
 [[package]]
 name = "rustls-pki-types"
-version = "1.15.0"
+version = "1.15.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "764899a24af3980067ee14bc143654f297b22eaebfe3c7b6b211920a5a59b046"
+checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
 dependencies = [
  "zeroize",
 ]
@@ -1351,14 +1341,14 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.0",
+ "syn 3.0.3",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.150"
+version = "1.0.151"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
 dependencies = [
  "itoa",
  "memchr",
@@ -1709,9 +1699,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "3.0.0"
+version = "3.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f2fac314a64dc9a36e61a9eb4261a5e9bbfbc922b27e518af97bc32b926cf967"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1752,7 +1742,7 @@ checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.0",
+ "syn 3.0.3",
 ]
 
 [[package]]
@@ -1782,9 +1772,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.53.0"
+version = "1.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d988bcd52dbe076d3d46903332f58c912b87a2c49b1428419a5845154762ffee"
+checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
 dependencies = [
  "bytes",
  "libc",
@@ -1799,20 +1789,20 @@ dependencies = [
 
 [[package]]
 name = "tokio-macros"
-version = "2.7.1"
+version = "2.7.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6328af13490e73a9b4694030fafd93f8c8c6a9dede33e821c3fc63eddf8042ba"
+checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn 3.0.3",
 ]
 
 [[package]]
 name = "tokio-stream"
-version = "0.1.18"
+version = "0.1.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32da49809aab5c3bc678af03902d4ccddea2a87d028d86392a4b1560c6906c70"
+checksum = "a3d06f0b082ba57c26b79407372e57cf2a1e28124f78e9479fe80322cf53420b"
 dependencies = [
  "futures-core",
  "pin-project-lite",
@@ -2260,18 +2250,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.54"
+version = "0.8.55"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7cbbc0a705a0fd05cc3676525980d2bf5a9bc4adac6d6475209a7887cf59d19"
+checksum = "b5a105cd7b140f6eeec8acff2ea38135d3cab283ada58540f629fe51e46696eb"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.54"
+version = "0.8.55"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5"
+checksum = "0fe976fb70c78cd64cccfe3a6fc142244e8a77b70959b30faf9d0ac37ee228eb"
 dependencies = [
  "proc-macro2",
  "quote",

{ferro_orm-0.17.1 → ferro_orm-0.18.0}/Cargo.toml

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

{ferro_orm-0.17.1 → ferro_orm-0.18.0}/PKG-INFO

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

{ferro_orm-0.17.1 → ferro_orm-0.18.0}/crates/ferro-ddl-lowering/src/lib.rs

@@ -498,6 +498,63 @@ pub fn render_pg_enum_create_type(type_name: &str, labels: &[String]) -> String
     )
 }
 
+/// The label-addition decision (ADR-0011): which model-declared labels a live
+/// ferro-owned enum type is missing, in declared order. This is the single
+/// decision table for enum label drift — the auto-migrate planner and the
+/// Alembic autogenerate comparator both consume it mechanically (AGENTS.md
+/// § I-1); neither side re-derives it. Append-only by construction: labels the
+/// live type has but the model lacks are not this function's concern.
+pub fn missing_enum_labels(declared: &[String], live: &[String]) -> Vec<String> {
+    declared
+        .iter()
+        .filter(|label| !live.contains(label))
+        .cloned()
+        .collect()
+}
+
+/// The warn-never-act half of the label-addition decision (ADR-0011): labels
+/// the live type carries that the model no longer declares, in live (enum
+/// sort) order. Rows may still hold these labels and older code may still be
+/// running against the schema, so callers warn loudly and never remove —
+/// removal and rename are reviewed-migration territory.
+pub fn extra_enum_labels(declared: &[String], live: &[String]) -> Vec<String> {
+    live.iter()
+        .filter(|label| !declared.contains(label))
+        .cloned()
+        .collect()
+}
+
+/// The warn-never-act message for one drifted enum type, or `None` when
+/// nothing is extra. Single-sourced like [`refused_conversion_warning`]:
+/// callers emit it verbatim, never re-derive the wording.
+pub fn extra_enum_labels_warning(type_name: &str, extra: &[String]) -> Option<String> {
+    if extra.is_empty() {
+        return None;
+    }
+    let listed: Vec<String> = extra.iter().map(|l| format!("'{l}'")).collect();
+    Some(format!(
+        "Enum type '{}' has label(s) {} that the model no longer declares. \
+         Label addition is append-only: ferro never removes enum labels \
+         (existing rows may still hold them). Remove or rename labels with \
+         a reviewed Alembic migration.",
+        type_name,
+        listed.join(", ")
+    ))
+}
+
+/// One `ALTER TYPE ... ADD VALUE IF NOT EXISTS` for a label addition.
+/// `IF NOT EXISTS` makes concurrent boots and shared-type replans harmless;
+/// executed outside transactions (autocommit) so the statement is legal on
+/// every supported Postgres version and the label is committed before any
+/// table plan that references it.
+pub fn render_pg_enum_add_value(type_name: &str, label: &str) -> String {
+    format!(
+        "ALTER TYPE {} ADD VALUE IF NOT EXISTS '{}'",
+        quote_ident(type_name),
+        label.replace('\'', "''"),
+    )
+}
+
 /// Detect a refused conversion from a live column to a resolved storage
 /// target. Extends [`refused_scalar_conversion`] with the native-enum case:
 /// a live non-enum (varchar/text) column targeted at a native Postgres enum
@@ -1464,6 +1521,55 @@ mod tests {
         );
     }
 
+    #[test]
+    fn missing_enum_labels_returns_additions_in_declared_order() {
+        let declared = vec!["plaid".to_string(), "mx".to_string(), "teller".to_string()];
+        let live = vec!["plaid".to_string()];
+        assert_eq!(missing_enum_labels(&declared, &live), vec!["mx", "teller"]);
+    }
+
+    #[test]
+    fn missing_enum_labels_empty_when_live_covers_declared() {
+        let declared = vec!["plaid".to_string()];
+        let live = vec!["plaid".to_string(), "legacy".to_string()];
+        assert!(missing_enum_labels(&declared, &live).is_empty());
+    }
+
+    #[test]
+    fn extra_enum_labels_returns_undeclared_live_labels_in_live_order() {
+        let declared = vec!["plaid".to_string()];
+        let live = vec!["legacy".to_string(), "plaid".to_string(), "old".to_string()];
+        assert_eq!(extra_enum_labels(&declared, &live), vec!["legacy", "old"]);
+        assert!(extra_enum_labels(&live, &live).is_empty());
+    }
+
+    #[test]
+    fn extra_enum_labels_warning_is_pinned_and_names_the_exit() {
+        assert_eq!(
+            extra_enum_labels_warning("provider", &["legacy".to_string()]),
+            Some(
+                "Enum type 'provider' has label(s) 'legacy' that the model no longer \
+                 declares. Label addition is append-only: ferro never removes enum \
+                 labels (existing rows may still hold them). Remove or rename labels \
+                 with a reviewed Alembic migration."
+                    .to_string()
+            )
+        );
+        assert_eq!(extra_enum_labels_warning("provider", &[]), None);
+    }
+
+    #[test]
+    fn render_pg_enum_add_value_is_pinned_and_escapes() {
+        assert_eq!(
+            render_pg_enum_add_value("provider", "mx"),
+            "ALTER TYPE \"provider\" ADD VALUE IF NOT EXISTS 'mx'"
+        );
+        assert_eq!(
+            render_pg_enum_add_value("od'd", "it's"),
+            "ALTER TYPE \"od'd\" ADD VALUE IF NOT EXISTS 'it''s'"
+        );
+    }
+
     #[test]
     fn render_pg_enum_create_type_escapes_quotes() {
         let sql = render_pg_enum_create_type("od'd", &["it's".to_string()]);

ferro_orm-0.18.0/docs/adr/0011-label-addition-update-gated-append-only.md

@@ -0,0 +1,65 @@
+# Label addition is update-gated and append-only
+
+A native Postgres enum type that already exists is an existing schema object,
+so evolving its label set belongs to the **reconciliation pass**
+(`migrate_updates`), not the create pass — the same line ADR-0010 drew for
+indexes. The reconciliation pass performs **label addition** (`CONTEXT.md`):
+it appends model-declared labels missing from a live ferro-owned enum type,
+and does nothing else. Labels the database has but the model lacks are warned
+about loudly and never removed — rows may still hold them, and old code may
+still be running against the new schema during a rolling deploy. A type is
+ferro-owned by **derivation**: its name matches the name ferro derives from
+the model (enum types carry no `idx_`/`uq_`-style prefix, so prefix doctrine
+cannot apply). The additive-only scope is what makes derivation-based
+ownership safe: the worst misattribution appends a label; it never drops or
+rewrites anything.
+
+Both migration doors consume one decision: the label diff (model labels +
+live `pg_enum` labels → additions + warnings) lives in the Rust core and is
+consumed mechanically by the auto-migrate planner and by an Alembic
+autogenerate comparator in the bridge — the same one-decision-table seam as
+`resolve_column_storage` (AGENTS.md I-1). Alembic autogenerate has no
+`migrate_updates` gate: running autogenerate is itself the request for a
+diff, so the comparator always reports; parity is in the decision, not the
+gate. `ALTER TYPE ... ADD VALUE` executes outside transactions on both paths
+(an autocommit pre-pass before the per-table transactions in auto-migrate;
+`autocommit_block()` in generated revisions) — Prisma shipped the
+in-transaction version and it is a graveyard (prisma#7251, #5290, #8424).
+
+Decision by owner (2026-08-05), grilling #328.
+
+Rejected alternatives:
+
+- **Ensure semantics under plain `auto_migrate`** ("the type guard already
+  runs in the create pass; label addition is just a stronger ensure"):
+  re-opens the two-owners divergence ADR-0010 closed — an existing object
+  whose shape plain `auto_migrate` sometimes changes. The create pass stays
+  introspection-free and silent about drift of every kind, enums included.
+- **Automatic removal/rename** (full sync, as `alembic-postgresql-enum`
+  does): removal requires a type-replacement dance and human judgment about
+  rows holding the removed label; every implementation that automated it
+  grew a bug tracker around it. Reviewed-migration territory, permanently.
+- **Recommending `alembic-postgresql-enum`** instead of our own comparator:
+  it autogenerates removals, contradicting append-only — the two doors would
+  disagree about what the same model means.
+- **Ownership markers** (`COMMENT ON TYPE` stamped at create time): sound
+  provenance, but every existing deployment's types are unmarked, and the
+  backfill machinery buys nothing additive-only doesn't already guarantee.
+
+## Consequences
+
+- Under plain `auto_migrate=True`, an evolved `StrEnum` still fails at first
+  use with the database's `invalid input value for enum` error — silently at
+  boot, by design. The documented answer to drift, enum drift included, is
+  `migrate_updates=True`. Auto-migrate docs must carry this trap loudly:
+  fresh schemas always get the complete label set, so no app-side test
+  against a throwaway schema can catch it (#328).
+- A new table created under plain `auto_migrate` that references an existing
+  stale type gets the stale label set — the create-pass type guard only
+  fires for missing types. Same flag fixes it.
+- Appended labels land at the end of the Postgres enum ordering regardless of
+  their position in the Python declaration; `ORDER BY` on an enum column
+  follows database order, not declaration order.
+- Live introspection must read `pg_enum` labels (today it records only
+  "is an enum"), and the cross-emitter parity tests extend to pin the label
+  diff across both consumers.

{ferro_orm-0.17.1 → ferro_orm-0.18.0}/docs/pages/guide/migrations.md

@@ -48,6 +48,8 @@ What it covers is capability-relative per backend:
 | Change column type | ⚠️ `UserWarning`, no DDL (SQLite type affinity makes drift mostly cosmetic) | ✅ `ALTER COLUMN ... TYPE ... USING` cast |
 | Change nullability | ⚠️ `UserWarning`, no DDL | ✅ `SET NOT NULL` / `DROP NOT NULL` |
 | Drop orphaned Ferro-named index (`idx_*` / `uq_*`) | ✅ with `migrate_destructive=True` | ✅ with `migrate_destructive=True` |
+| Add a missing enum label (a `StrEnum` grew a member) | ✅ nothing to do — enums store as text | ✅ `ALTER TYPE ... ADD VALUE` *0.18.0+* |
+| Remove or rename an enum label | ✅ nothing to do | ⚠️ `UserWarning`, no DDL — Alembic territory |
 | Inline single-column `UNIQUE` on existing column, index option changes | ❌ never — Alembic territory | ❌ never |
 | Rename column/table, change primary key, drop table | ❌ never — Alembic territory | ❌ never |
 
@@ -59,6 +61,74 @@ Rules worth knowing:
 - **Postgres type changes take an exclusive lock** and fail the connect if existing data does not cast cleanly — fine for a development flag, but worth knowing.
 - **The pool refreshes after any schema change**, so no cached statement or stale identity-mapped instance can observe the pre-migration schema.
 
+### Evolving enums: label addition
+
+*Added in 0.18.0.* On PostgreSQL, `StrEnum` fields create a **native enum type**, and a type that already exists in the database does not learn new members on its own. When a `StrEnum` grows, `migrate_updates=True` performs **label addition**: it compares the model's members against the live type and appends what's missing with `ALTER TYPE ... ADD VALUE IF NOT EXISTS`.
+
+!!! danger "This gap is invisible to your tests"
+    Under plain `auto_migrate=True` (without `migrate_updates`), an existing enum type is **never** updated — like every existing object, it belongs to the update pass. The failure mode is nasty: every test suite that creates its schema fresh gets the complete enum and stays green, while every *existing* database rejects the new member at runtime with `invalid input value for enum`. No app-side test against a throwaway schema can catch this. If your models' enums evolve, run with `migrate_updates=True` (or generate the migration with Alembic — the [autogenerate bridge](#alembic-for-production) sees the same drift).
+
+=== "Assignment"
+
+    ```python
+    from enum import StrEnum
+
+    import ferro
+    from ferro import Model
+
+
+    class Provider(StrEnum):
+        PLAID = "plaid"
+        MX = "mx"  # new member — the live type only has 'plaid'
+
+
+    class Feed(Model):
+        id: int | None = ferro.Field(primary_key=True, default=None)
+        provider: Provider
+
+
+    await ferro.connect("postgres://...", migrate_updates=True)
+    # → ALTER TYPE "provider" ADD VALUE IF NOT EXISTS 'mx'
+
+    feed = await Feed.create(provider=Provider.MX)
+    recent = await Feed.where(lambda feed: feed.provider == Provider.MX).all()
+    ```
+
+=== "Annotated"
+
+    ```python
+    from enum import StrEnum
+    from typing import Annotated
+
+    import ferro
+    from ferro import FerroField, Model
+
+
+    class Provider(StrEnum):
+        PLAID = "plaid"
+        MX = "mx"  # new member — the live type only has 'plaid'
+
+
+    class Feed(Model):
+        id: Annotated[int | None, FerroField(primary_key=True)] = None
+        provider: Provider
+
+
+    await ferro.connect("postgres://...", migrate_updates=True)
+    # → ALTER TYPE "provider" ADD VALUE IF NOT EXISTS 'mx'
+
+    feed = await Feed.create(provider=Provider.MX)
+    recent = await Feed.where(lambda feed: feed.provider == Provider.MX).all()
+    ```
+
+The contract, precisely:
+
+- **Append-only, metadata-only.** Label addition adds labels and does nothing else; rows are never touched. A shared `StrEnum` used by several models is one type and reconciles once.
+- **Removals and renames are never automatic.** A live label the model no longer declares raises a `UserWarning` naming the type and labels — rows may still hold that label, and older code may still be running against the schema mid-deploy — and the label stays. Remove or rename labels in a reviewed Alembic migration.
+- **Labels commit before table changes.** Additions run as their own autocommit statements ahead of the per-table plans, so a new column whose literal default is a brand-new member works in a single deploy, on every supported PostgreSQL version.
+- **Appended labels sort last.** `ADD VALUE` appends: a member inserted mid-enum in Python lands at the end of the database ordering, and `ORDER BY` on an enum column follows *database* order, not declaration order.
+- **SQLite is unaffected.** Enums store as text there; a new member needs no DDL.
+
 ### Destructive drops with `migrate_destructive`
 
 *Added in 0.11.0.* Also **drop** live columns that no longer exist on the model (never whole tables):
@@ -134,6 +204,7 @@ target_metadata = get_metadata()
 - **Composite constraints** (`__ferro_composite_uniques__`, `__ferro_composite_indexes__`) emit matching `UniqueConstraint` / `Index` objects, including the automatic constraints on many-to-many join tables.
 - **One-to-one** relations (`ForeignKey(unique=True)`) emit the same `UNIQUE` on the shadow column that `auto_migrate` creates at runtime.
 - **Enums** map to named `sqlalchemy.Enum` types (class name lowercased, e.g. `UserRole` → `userrole`) so revisions compile on PostgreSQL, which rejects anonymous enum types.
+- **Enum label drift is diffed.** *0.18.0+.* Alembic core is blind to enum value changes; ferro's bridge registers an autogenerate comparator that diffs each named enum type against the live PostgreSQL catalog — the same decision (and the same rendered SQL) the auto-migrate pass uses. A grown `StrEnum` generates `ALTER TYPE ... ADD VALUE IF NOT EXISTS` inside an `autocommit_block()` (placed before table operations, runnable on every supported PostgreSQL version); a live label the model no longer declares generates a comment in the revision telling you removal needs a hand-written step. Models in sync generate nothing.
 
 ### Autogenerate
 

{ferro_orm-0.17.1 → ferro_orm-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ferro-orm"
-version = "0.17.1"
+version = "0.18.0"
 description = "A high-performance, Rust-backed ORM for Python."
 readme = "README.md"
 authors = [