ferro-orm 0.12.3__tar.gz → 0.14.0__tar.gz

{ferro_orm-0.12.3 → ferro_orm-0.14.0}/.github/workflows/ci.yml

@@ -3,9 +3,8 @@ name: CI
 on:
   workflow_call:
   pull_request:
-    branches: [main, feat/ir-first]
   push:
-    branches: [main, feat/ir-first]
+    branches: [main]
   workflow_dispatch:
 
 concurrency:
@@ -153,6 +152,10 @@ jobs:
         run: |
           uv run maturin develop
 
+      - name: Static type gate (ty, scoped)
+        run: |
+          uv run ty check src/ferro/query tests/test_query_typing.py tests/test_static_contracts.py
+
       - name: Run IR vector contract harness
         run: |
           uv run pytest -v tests/test_ir_vectors_contract.py

{ferro_orm-0.12.3 → ferro_orm-0.14.0}/AGENTS.md

@@ -27,18 +27,23 @@ For a single model, every emitter must agree on:
 
 1. **Table name** — already handled by `model_name.lower()`.
 2. **Column names** — including shadow `*_id` columns from `ForeignKey`.
-3. **Column types** — pydantic JSON schema → SQL type mapping must be one
-   function (or two functions whose outputs are tested for parity). This
-   includes the canonical `db_type` vocabulary (`text`, `varchar(N)`,
-   `smallint`, `int`, `bigint`, `uuid`, `timestamp`, `timestamptz`, `date`,
-   `time`) — duplicated in `_db_type_to_sa_type` (Python) and
-   `db_type_token_to_canonical` (Rust), pinned by
-   `tests/test_db_type_cross_emitter_parity.py`.
+3. **Column types** — decided by ONE function:
+   `ferro_ddl_lowering::resolve_column_storage` (explicit `db_type` token →
+   native-enum resolution → the `canonical_from_parts` cascade). The Alembic
+   bridge consumes it mechanically over FFI (`_core._resolve_storage_type`)
+   and `_db_type_to_sa_type` is only the SA *rendering* of the shared token
+   vocabulary — never a second decision table. Pinned exhaustively by
+   `tests/test_db_type_cross_emitter_parity.py` (every token and every
+   derived annotation × both dialects). See
+   `docs/solutions/patterns/derived-type-and-naming-decision-table.md`.
 4. **Index names** — `idx_<table>_<col>` for single-column indexes,
    `idx_<table>_<col1>_<col2>...` for composite indexes.
 5. **Unique constraint names** — `uq_<table>_<col>` for single-column,
    `uq_<table>_<col1>_<col2>...` for composite.
-6. **Foreign key constraint names** — when explicitly named.
+6. **Foreign key constraint names** — `fk_<table>_<col>_<to_table>`, always
+   emitted (both emitters render `SchemaForeignKey.name`; single-sourced in
+   `ferro_ddl_lowering::fk_name`). See
+   `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)
@@ -91,7 +96,7 @@ If you add a new schema feature (e.g. partial indexes, exclusion constraints):
 2. Implement it in **both** the Alembic and Rust paths in the same PR.
 3. Add a parity test that asserts the names match.
 4. Do not edit `CHANGELOG.md` manually — release tooling records entries at
-   release time (see I-11).
+   release time (see I-10).
 
 ---
 
@@ -151,17 +156,7 @@ See `docs/solutions/README.md` for the frontmatter conventions.
 
 ---
 
-## I-6: No AI attribution in commits or PRs
-
-Never sign commits or pull requests with AI/agent attribution. No
-`Co-Authored-By: Claude ...` trailers, no "Generated with Claude Code"
-footers, no robot emoji bylines — in commit messages, PR titles, or PR
-bodies. This applies even when an agent's default behavior is to add them:
-this rule overrides those defaults for this repository.
-
----
-
-## I-7: No stop-gap solutions
+## I-6: No stop-gap solutions
 
 Every feature, bug fix, and improvement must be designed as the best,
 well-thought-out solution for the project with the library's future in
@@ -194,7 +189,7 @@ agent default that biases toward minimal or expedient changes.
 
 ---
 
-## I-8: Docs examples show both field-declaration styles
+## I-7: Docs examples show both field-declaration styles
 
 Ferro supports two equivalent ways to declare model fields: assignment
 (`name: str = Field(unique=True)`) and `Annotated` metadata
@@ -232,18 +227,20 @@ preferred declaration style.
 
 ---
 
-## I-9: Lambda predicates are the official query style
+## I-8: Lambda predicates are the official query style
 
 Documentation and examples use the lambda predicate style for all queries:
 
 ```python
-adults = await User.where(lambda t: t.age >= 18).all()
+adults = await User.where(lambda user: user.age >= 18).all()
 ```
 
 Rules:
 
 - **Every query example** in docs, docstring `Examples:` sections, and
   `docs/examples/` scripts uses lambda predicates.
+- Name the lambda parameter after the model in **lowercase singular**
+  (`user` for `User`, `post` for `Post`) so filters read naturally.
 - When the predicate styles themselves are documented, present them in
   order **lambda > `col()` > operator**, with lambda labeled the officially
   recommended style.
@@ -262,7 +259,7 @@ else uses lambda without restating the trade-offs.
 
 ---
 
-## I-10: PRs must close scoped issues explicitly
+## I-9: PRs must close scoped issues explicitly
 
 Issue closure is part of feature completion, not optional cleanup.
 
@@ -280,7 +277,7 @@ Rules:
 
 ---
 
-## I-11: Do not edit CHANGELOG.md manually
+## I-10: Do not edit CHANGELOG.md manually
 
 `CHANGELOG.md` is updated automatically by the release workflow (semantic
 release / release tooling). Agents and contributors must **not** add,
@@ -295,3 +292,29 @@ What to do instead:
 If release tooling fails to capture a change, fix the release configuration or
 commit message conventions — do not patch `CHANGELOG.md` by hand in ordinary
 PRs.
+
+---
+
+## I-11: Explain technical concepts in plain language, example-first
+
+When explaining a concept, design, trade-off, or change to the maintainer, lead
+with plain language and a concrete, user-facing example — not internal function
+names and call graphs.
+
+Rules:
+
+- **Anchor on what the user sees.** Show a real model definition and the SQL (or
+  behavior) it produces, then explain the internal mechanics against that
+  anchor. "A `datetime` field becomes `timestamptz` — here's the `CREATE TABLE`"
+  beats "`canonical_from_parts` maps the logical type."
+- **Introduce jargon only after the plain version.** Function and type names are
+  precise back-references once the idea is clear — not the primary explanation.
+- **Use analogies for architecture.** "Two translation dictionaries that must
+  agree by hand" communicates a duplication smell faster than a module diagram.
+- **Show, don't just tell.** Prefer before/after diffs, rendered SQL, and
+  concrete values over abstract prose (complements the show-don't-tell habit
+  used in issue/PR explanations).
+
+This applies to brainstorming, design discussions, PR descriptions, issue
+comments, and any explanation directed at the maintainer. It governs how work is
+communicated, not what gets built.

{ferro_orm-0.12.3 → ferro_orm-0.14.0}/CHANGELOG.md

@@ -1,6 +1,193 @@
 # CHANGELOG
 
 
+## v0.14.0 (2026-07-07)
+
+### Bug Fixes
+
+- **ff-g**: Make Postgres db_check ADD CONSTRAINT idempotent (G6, #176)
+  ([#181](https://github.com/syn54x/ferro-orm/pull/181),
+  [`2c0e4cf`](https://github.com/syn54x/ferro-orm/commit/2c0e4cf6c922a73454198f6aa0aa75b30eb1f0c8))
+
+### Chores
+
+- **benchmarks**: Pinned async benchmark suite over the rich-type hot path
+  ([#196](https://github.com/syn54x/ferro-orm/pull/196),
+  [`d9a656b`](https://github.com/syn54x/ferro-orm/commit/d9a656b320bd7fb6b613f4408a796161e9badc41))
+
+### Documentation
+
+- Consolidate migration guides into one evergreen upgrade guide
+  ([#234](https://github.com/syn54x/ferro-orm/pull/234),
+  [`15c83db`](https://github.com/syn54x/ferro-orm/commit/15c83dbc6b1c057a78dfc425d70441e50c359f5d))
+
+- Fixes roadmap
+  ([`5718d02`](https://github.com/syn54x/ferro-orm/commit/5718d02630b6c84d3ced6f8a3080adf4e7fe2383))
+
+- **fable-fixes**: Fold #176 into Epic FF-G as sub-task G6
+  ([`b966e65`](https://github.com/syn54x/ferro-orm/commit/b966e65739d7c33ed666a7fd14086a27688516dd))
+
+- **ff-a**: A5 — docs & migration guide for the mutation-surface changes
+  ([#180](https://github.com/syn54x/ferro-orm/pull/180),
+  [`ffc5476`](https://github.com/syn54x/ferro-orm/commit/ffc5476f9ba72f03a35048f283b11390f813856b))
+
+- **ff-b**: Tick FF-B sub-task and exit-gate boxes in the fable-fixes roadmap
+  ([`29f9172`](https://github.com/syn54x/ferro-orm/commit/29f91724e2b6886f8299bbb42940c804c8e88141))
+
+### Features
+
+- **ff-a**: Create() is a real INSERT; save() distinguishes INSERT from UPDATE (A3+A4)
+  ([#179](https://github.com/syn54x/ferro-orm/pull/179),
+  [`de3ec30`](https://github.com/syn54x/ferro-orm/commit/de3ec30196202ee14c42afc5b02f163f82a68451))
+
+- **ff-a**: Reject limit/offset on mutating queries
+  ([#178](https://github.com/syn54x/ferro-orm/pull/178),
+  [`67faf42`](https://github.com/syn54x/ferro-orm/commit/67faf421d49984c5be16d2163982f13ab86cc5e4))
+
+- **ff-a**: Typed DBAPI-shaped exception hierarchy mapped from sqlx errors
+  ([#177](https://github.com/syn54x/ferro-orm/pull/177),
+  [`9c306c5`](https://github.com/syn54x/ferro-orm/commit/9c306c549e716dd4a5158d655265aa7890e63c0b))
+
+- **ff-b**: B1 canonical derived-type & naming decision table + refusal-rail scaffolding
+  ([`8c879f7`](https://github.com/syn54x/ferro-orm/commit/8c879f77833a7e5a983d53012efc8332cca5b852))
+
+- **ff-b**: B2+B6 one derived-type decision table; native PG enums + timestamptz/time parity; delete
+  bridge mirrors
+  ([`bfdc1fd`](https://github.com/syn54x/ferro-orm/commit/bfdc1fda1eceebe70ae711e38b785af88b46e11e))
+
+- **ff-b**: B3+B4 single-source artifact naming; both emitters emit named fk_/uq_ artifacts
+  ([`6b771f3`](https://github.com/syn54x/ferro-orm/commit/6b771f38933c72e8f848013a5ae93708fabf5c7a))
+
+- **ff-c**: C1 — per-model ColumnCodec plan; delete codec.rs schema sniffing (F5)
+  ([#197](https://github.com/syn54x/ferro-orm/pull/197),
+  [`0e8e572`](https://github.com/syn54x/ferro-orm/commit/0e8e57252f4cca2d2bc9fffd06d9155338056cf3))
+
+- **ff-c**: C2 — schema-epoch catalog cache; zero catalog queries on steady-state CRUD
+  ([#200](https://github.com/syn54x/ferro-orm/pull/200),
+  [`8c6d6ed`](https://github.com/syn54x/ferro-orm/commit/8c6d6edf578cf55ed7ada0d49359a7e09528da1e))
+
+- **ff-c**: C3+C4 — native typed Postgres decode; plan-driven enum hydration replaces _fix_types
+  ([#198](https://github.com/syn54x/ferro-orm/pull/198),
+  [`05a008c`](https://github.com/syn54x/ferro-orm/commit/05a008cb73f6c4dc8b2478a441c99282d07bd41d))
+
+- **ff-d**: Session-scoped weak identity map with refresh-on-load; single-handle routing
+  ([#201](https://github.com/syn54x/ferro-orm/pull/201),
+  [`a328cfc`](https://github.com/syn54x/ferro-orm/commit/a328cfcd107e2cac998ddc8af50845857ec669a5))
+
+- **ff-e**: Registry & model identity — qualified keys, configurable tables, O(N) import
+  ([#209](https://github.com/syn54x/ferro-orm/pull/209),
+  [`6391805`](https://github.com/syn54x/ferro-orm/commit/6391805c1b4ee46c0590513ac6684237c18f7430))
+
+- **ff-f**: Query builder 1.0 shape — immutable chaining, build-time column validation, lambda-only
+  predicates, QueryIR-only Rust ([#223](https://github.com/syn54x/ferro-orm/pull/223),
+  [`eb7fece`](https://github.com/syn54x/ferro-orm/commit/eb7fece8fbc2231220ecf9111616f803f2f987eb))
+
+- **ff-g-a**: Hardening — hydration ABI guard, transactional PG migrate, correctness edges,
+  decode-path caching ([#232](https://github.com/syn54x/ferro-orm/pull/232),
+  [`22617e1`](https://github.com/syn54x/ferro-orm/commit/22617e1cfe5e2bc9d0a3d7a1fed5acf4d8589cef))
+
+### Refactoring
+
+- **ff-g-b**: Operations.rs dedup — ModelMeta + Executor (G2)
+  ([#233](https://github.com/syn54x/ferro-orm/pull/233),
+  [`09c2c62`](https://github.com/syn54x/ferro-orm/commit/09c2c6214af9e2f9510d39d037935c53bd2e796d))
+
+### Testing
+
+- **ff-b**: B5 I-1 sentinel on the full backend matrix with a full-type fixture, zero filters
+  ([`1141eb4`](https://github.com/syn54x/ferro-orm/commit/1141eb437b4843303e01556a5b24ddee9d0e0279))
+
+- **ff-b**: Force psycopg v3 driver in the Postgres sentinel regardless of URL scheme
+  ([`64f9845`](https://github.com/syn54x/ferro-orm/commit/64f98454bdb5e090a41bd214de06b7670974f4eb))
+
+
+## v0.13.0 (2026-07-02)
+
+### Bug Fixes
+
+- **ir-p8.6**: Datetime/timestamptz coarseness — stop silent Postgres column reinterpretation (#154)
+  ([#167](https://github.com/syn54x/ferro-orm/pull/167),
+  [`7182a57`](https://github.com/syn54x/ferro-orm/commit/7182a5744900abe7ed50915edbca7d5184b2c535))
+
+- **ir-p8.6**: Stop false-positive BLOB drift warning on SQLite (#165)
+  ([#168](https://github.com/syn54x/ferro-orm/pull/168),
+  [`d554ac4`](https://github.com/syn54x/ferro-orm/commit/d554ac4558286106bcb0908baec9fa3d49a2781d))
+
+- **ir-p8.6**: Surface real PEP 649 deferred-annotation error (#155)
+  ([#163](https://github.com/syn54x/ferro-orm/pull/163),
+  [`00976e7`](https://github.com/syn54x/ferro-orm/commit/00976e748d86246b8be47230229d19516d8bb3c0))
+
+### Documentation
+
+- Use model-named lambda predicates in examples
+  ([#132](https://github.com/syn54x/ferro-orm/pull/132),
+  [`420ca6e`](https://github.com/syn54x/ferro-orm/commit/420ca6e1cb4a90d1acc556a83373c9da99b22bb3))
+
+- **agents**: Add I-11 — explain concepts plainly, example-first
+  ([`efc7ef5`](https://github.com/syn54x/ferro-orm/commit/efc7ef5678e2f6efacaa3a6e84c0575b0cdef51c))
+
+- **ir-first**: Add Phase 8.6 post-8.5 cleanup backlog (epic #145)
+  ([#147](https://github.com/syn54x/ferro-orm/pull/147),
+  [`e57b74b`](https://github.com/syn54x/ferro-orm/commit/e57b74b397bd51ebc4809f25d57536896540b9de))
+
+- **ir-first**: Expand #144 scope — auto-migrate index/unique reconciliation
+  ([#150](https://github.com/syn54x/ferro-orm/pull/150),
+  [`fdbac40`](https://github.com/syn54x/ferro-orm/commit/fdbac4003e9bd25fdc3f3cb0012c5dd9d562ee68))
+
+- **ir-first**: Lowering-consolidation audit + Phase 8.5
+  ([#138](https://github.com/syn54x/ferro-orm/pull/138),
+  [`c6ce53c`](https://github.com/syn54x/ferro-orm/commit/c6ce53c2409a1fd20a40c1de58d42e1e3d2e1344))
+
+- **ir-p8.6**: Add #153 create-path IR unification spec
+  ([`be4bb99`](https://github.com/syn54x/ferro-orm/commit/be4bb99b90e6d02a6e01bfc5807a7cb178055862))
+
+- **ir-p8.6**: Add #153 create-path unification implementation plan
+  ([`de3c427`](https://github.com/syn54x/ferro-orm/commit/de3c42794de821d8e47eb5ca94b582f8199992df))
+
+- **ir-p8.6**: Sync roadmap — #153 merged, file #158 (db_check check-renderer)
+  ([`62c80fa`](https://github.com/syn54x/ferro-orm/commit/62c80fa3fe7ac456169d280f3ee8795feac32a8c))
+
+- **ir-p8.6**: Sync roadmap — #154 merged (datetime/timestamptz warn-and-skip); #145 now 6/7
+  ([`31dbbb6`](https://github.com/syn54x/ferro-orm/commit/31dbbb6c0f1d3afa0ed452ed9ae34441df69c501))
+
+- **ir-p8.6**: Sync roadmap — #162 merged (typed save/update bind), file #165
+  ([`5ca76a1`](https://github.com/syn54x/ferro-orm/commit/5ca76a1e177f4847ded4fb19402841a9988b62d1))
+
+- **ir-p8.6**: Sync roadmap — #165 merged (BLOB introspection); #145 complete 7/7, Phase 8.6 wrapped
+  ([`1dbb278`](https://github.com/syn54x/ferro-orm/commit/1dbb27864881d77a68d5026ab5a9bb07f142c3c5))
+
+- **rust**: Add detailed docstrings for all public APIs
+  ([#130](https://github.com/syn54x/ferro-orm/pull/130),
+  [`8d5a951`](https://github.com/syn54x/ferro-orm/commit/8d5a95162568eef215ba03524a31b657df87e8c6))
+
+### Features
+
+- Ir cutover ([#137](https://github.com/syn54x/ferro-orm/pull/137),
+  [`0509c2a`](https://github.com/syn54x/ferro-orm/commit/0509c2a35b0f0200492143a52563146359550129))
+
+- **ir-p8.6**: Route save/update/bulk value bind through the typed codec path (#162)
+  ([#166](https://github.com/syn54x/ferro-orm/pull/166),
+  [`486e68c`](https://github.com/syn54x/ferro-orm/commit/486e68c110c03356fa579051849b44e8f4eae751))
+
+### Refactoring
+
+- Lowering consolidation & single-source-of-truth closeout (#139)
+  ([#156](https://github.com/syn54x/ferro-orm/pull/156),
+  [`f76bec9`](https://github.com/syn54x/ferro-orm/commit/f76bec93651bc9741bea85171da927ddb8864a1a))
+
+- Unify the CREATE TABLE path onto the Python SchemaIR (#153)
+  ([#157](https://github.com/syn54x/ferro-orm/pull/157),
+  [`c9ce7b0`](https://github.com/syn54x/ferro-orm/commit/c9ce7b093fde350da8a1653cf7c42f522e0523b2))
+
+- Unify the three dialect enums into one shared Dialect (#146)
+  ([#159](https://github.com/syn54x/ferro-orm/pull/159),
+  [`4b0dfe6`](https://github.com/syn54x/ferro-orm/commit/4b0dfe6b9eca1a2a63631a54504c629f42f7c5e1))
+
+- **ir-p8.6**: Single check-renderer for db_check (#158)
+  ([#161](https://github.com/syn54x/ferro-orm/pull/161),
+  [`c04df1c`](https://github.com/syn54x/ferro-orm/commit/c04df1ce5aa4505f737864944855ff4170a4d350))
+
+
 ## v0.12.3 (2026-06-24)
 
 ### Bug Fixes