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

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

@@ -46,10 +46,58 @@ For a single model, every emitter must agree on:
    `docs/solutions/patterns/derived-type-and-naming-decision-table.md`.
 7. **Primary key constraint names** — when explicitly named.
 8. **Check constraint names** — `ck_<table>_<col>` for the single-column
-   `db_check=True` constraint; generated by `_ck_constraint_name` (Python)
-   and `db_check_constraint_name` (Rust).
+   `db_check=True` constraint; `ck_<table>_<suffix>` for table checks declared
+   in `__ferro_checks__`. Column checks use `_ddl_check_constraint_name`
+   (Python) and `db_check_constraint_name` (Rust); table checks use
+   `_ddl_table_check_constraint_name` (Python) and
+   `table_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).
+12. **Check additions** — the missing-check decision (which declared `ck_*`
+    names — table checks, then column checks — a live table does not carry)
+    and the rendered ADD are decided by ONE pair of functions:
+    `ferro_ddl_lowering::missing_check_names` / `render_check_addition`.
+    The auto-migrate reconciliation pass consumes them through
+    `ferro_migrate::plan_missing_checks`; the Alembic autogenerate
+    comparator consumes them over FFI (`_core._plan_check_addition`) and
+    executes the byte-identical statements. Pinned by
+    `tests/test_table_check_reconcile.py`. See ADR-0013 (add on
+    `migrate_updates`; name-only comparison) and ADR-0014 (SQLite warn-skip).
+13. **Check rebuilds** — the same-name body-drift decision (which declared
+    `ck_*` names exist live **and** whose catalog definition normalizes
+    unequal to the canonical rendering) and the rendered DROP + bare ADD
+    are decided by ONE pair of functions:
+    `ferro_ddl_lowering::drifted_check_names` / `render_check_rebuild`
+    (one normalizer: `normalize_check_definition`). The auto-migrate
+    reconciliation pass consumes them through
+    `ferro_migrate::plan_check_rebuilds`; the Alembic autogenerate
+    comparator consumes them over FFI (`_core._plan_check_rebuild`) and
+    executes the byte-identical statements. Pinned by
+    `tests/test_table_check_rebuild.py`. See ADR-0015 (canonical render vs
+    catalog, both through one normalizer) and ADR-0014 (SQLite warn-skip).
+14. **Check leftovers / drops** — the leftover-name decision (which live
+    ferro-owned `ck_*` names a table carries that the model no longer
+    declares) and the rendered DROP are decided by ONE trio of functions:
+    `ferro_ddl_lowering::extra_check_names` /
+    `extra_check_names_warning` / `render_check_drop`. The auto-migrate
+    reconciliation pass consumes them through
+    `ferro_migrate::plan_check_drops` (ops only under
+    `migrate_destructive`; the warning always fires on `migrate_updates`).
+    The Alembic autogenerate comparator consumes them over FFI
+    (`_core._plan_check_drop`) with **no** destructive gate and executes
+    the byte-identical statements. Pinned by
+    `tests/test_table_check_orphans.py`. See ADR-0013 (leftover warning +
+    destructive ladder) and ADR-0014 (SQLite warn-skip).
 
 ### Why this invariant exists
 

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

@@ -1,6 +1,52 @@
 # CHANGELOG
 
 
+## v0.19.0 (2026-08-18)
+
+### Bug Fixes
+
+- Classify PG18 RESTRICT (23001) as ForeignKeyViolationError
+  ([#338](https://github.com/syn54x/ferro-orm/pull/338),
+  [`4fa1153`](https://github.com/syn54x/ferro-orm/commit/4fa1153477802de8207c7987748db962b35c2f0f))
+
+### Features
+
+- Named table-level CHECK constraints ([#356](https://github.com/syn54x/ferro-orm/pull/356),
+  [`ba179e7`](https://github.com/syn54x/ferro-orm/commit/ba179e71e9bce4ab77a6fdbc1831661485de6799))
+
+
+## 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.19.0}/CONTEXT.md

@@ -129,13 +129,33 @@ 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.
+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
+
+**Column check**:
+A single-column CHECK that restricts a closed-domain field to its declared labels (`Field(db_check=True)` → `col IN (...)`). Named `ck_<table>_<col>`; not a table check.
+_Avoid_: enum check, db_check constraint, value check
+
+**Table check**:
+A named boolean invariant over one row of one table, declared on the model as a lambda and enforced by the database as a CHECK constraint. The live name is `ck_<table>_<suffix>`; the suffix is what the model declares.
+_Avoid_: table-level check, multi-column check, composite check, row check
+
+**Check predicate**:
+The lambda body of a table check — a ferro predicate over that model's own columns (or a forward-FK null test on the relation or its shadow `*_id`), with literal values only. Relation traversal, existence tests, and aggregates are not check predicates.
+_Avoid_: check SQL, constraint expression, check body