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

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

@@ -152,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.13.0 → 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)

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

@@ -1,6 +1,106 @@
 # 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

{ferro_orm-0.13.0 → ferro_orm-0.14.0}/Cargo.lock

@@ -8,6 +8,15 @@ version = "0.2.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
 
+[[package]]
+name = "android_system_properties"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "atoi"
 version = "2.0.0"
@@ -35,6 +44,19 @@ version = "1.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
+[[package]]
+name = "bigdecimal"
+version = "0.4.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4d6867f1565b3aad85681f1015055b087fcfd840d6aeee6eee7f2da317603695"
+dependencies = [
+ "autocfg",
+ "libm",
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+]
+
 [[package]]
 name = "bitflags"
 version = "2.13.0"
@@ -73,9 +95,9 @@ checksum = "8ae3f5d315924270530207e2a68396c3cc547f6dca3fbdca317cfb1a51edb593"
 
 [[package]]
 name = "cc"
-version = "1.2.65"
+version = "1.2.66"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e228eec9be7c17ccb640b59b36a5cd805ea2a564a4c5e162c2f659fea30d3b96"
+checksum = "f5d6cac793997bd970000024b2934968efe83b382de4fdcf4fcb46b6ee4ad996"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -87,6 +109,17 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "num-traits",
+ "windows-link",
+]
+
 [[package]]
 name = "concurrent-queue"
 version = "2.5.0"
@@ -102,6 +135,12 @@ version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
 [[package]]
 name = "cpufeatures"
 version = "0.2.17"
@@ -128,18 +167,18 @@ checksum = "217698eaf96b4a3f0bc4f3662aaa55bdf913cd54d7204591faa790070c6d0853"
 
 [[package]]
 name = "crossbeam-queue"
-version = "0.3.12"
+version = "0.3.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0f58bbc28f91df819d0aa2a2c00cd19754769c2fad90579b3592b1c9ba7a3115"
+checksum = "803d13fb3b09d88be9f4dbc29062c66b19bf7170867ceb746d2a8689bf6c7a26"
 dependencies = [
  "crossbeam-utils",
 ]
 
 [[package]]
 name = "crossbeam-utils"
-version = "0.8.21"
+version = "0.8.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
 
 [[package]]
 name = "crypto-common"
@@ -288,8 +327,9 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.13.0"
+version = "0.14.0"
 dependencies = [
+ "chrono",
  "dashmap",
  "ferro-ddl-lowering",
  "ferro-migrate",
@@ -578,6 +618,30 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "icu_collections"
 version = "2.2.0"
@@ -835,6 +899,16 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "num-bigint"
+version = "0.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
 [[package]]
 name = "num-bigint-dig"
 version = "0.8.6"
@@ -1210,9 +1284,9 @@ dependencies = [
 
 [[package]]
 name = "rustversion"
-version = "1.0.22"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
 [[package]]
 name = "ryu"
@@ -1418,7 +1492,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ee6798b1838b6a0f69c007c133b8df5866302197e404e8b6ee8ed3e3a5e68dc6"
 dependencies = [
  "base64",
+ "bigdecimal",
  "bytes",
+ "chrono",
  "crc",
  "crossbeam-queue",
  "either",
@@ -1494,9 +1570,11 @@ checksum = "aa003f0038df784eb8fecbbac13affe3da23b45194bd57dba231c8f48199c526"
 dependencies = [
  "atoi",
  "base64",
+ "bigdecimal",
  "bitflags",
  "byteorder",
  "bytes",
+ "chrono",
  "crc",
  "digest",
  "dotenvy",
@@ -1537,8 +1615,10 @@ checksum = "db58fcd5a53cf07c184b154801ff91347e4c30d17a3562a635ff028ad5deda46"
 dependencies = [
  "atoi",
  "base64",
+ "bigdecimal",
  "bitflags",
  "byteorder",
+ "chrono",
  "crc",
  "dotenvy",
  "etcetera",
@@ -1553,6 +1633,7 @@ dependencies = [
  "log",
  "md-5",
  "memchr",
+ "num-bigint",
  "once_cell",
  "rand",
  "serde",
@@ -1574,6 +1655,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2d12fe70b2c1b4401038055f90f151b78208de1f9f89a7dbfd41587a10c3eea"
 dependencies = [
  "atoi",
+ "chrono",
  "flume",
  "futures-channel",
  "futures-core",
@@ -1930,12 +2012,65 @@ dependencies = [
  "wasite",
 ]
 
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "windows-link"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.48.0"
@@ -2115,18 +2250,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.52"
+version = "0.8.53"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f"
+checksum = "75726053136156d419e285b9b7eddaaea9e3fea6ce32eed44a89901f0bd98de1"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.52"
+version = "0.8.53"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
+checksum = "4714fd92cf900833d49538023a9b3915155210801d1c1169eba513b2addefd71"
 dependencies = [
  "proc-macro2",
  "quote",

{ferro_orm-0.13.0 → ferro_orm-0.14.0}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferro-schema-ir", "crates/ferro-ddl-lowering", "crates/ferro-
 
 [package]
 name = "ferro"
-version = "0.13.0"
+version = "0.14.0"
 edition = "2024"
 readme = "README.md"
 
@@ -30,11 +30,18 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 once_cell = "1.21"
 dashmap = "6.1"
-sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite", "postgres", "any", "tls-rustls-ring-webpki", "uuid"]}
+# chrono/bigdecimal/json enable native typed decode of Postgres temporal,
+# numeric, and json wire values (FF-C C3). bigdecimal (not rust_decimal)
+# because PG `numeric` is arbitrary-precision: rust_decimal caps at 28
+# significant digits and would silently corrupt wider values.
+sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite", "postgres", "any", "tls-rustls-ring-webpki", "uuid", "chrono", "bigdecimal", "json"]}
 sea-query = { version = "0.32", features = ["with-uuid"] }
 tokio = { version = "1.49", features = ["full"] }
 pyo3-async-runtimes = { version = "0.27", features = ["tokio-runtime"] }
 uuid = { version = "1.11", features = ["v4"] }
+# Same crate sqlx re-exports; direct dep only for formatting helpers
+# (SecondsFormat) sqlx does not re-export.
+chrono = { version = "0.4", default-features = false, features = ["std"] }
 ferro-schema-ir = { path = "crates/ferro-schema-ir" }
 ferro-ddl-lowering = { path = "crates/ferro-ddl-lowering" }
 ferro-migrate = { path = "crates/ferro-migrate" }

{ferro_orm-0.13.0 → ferro_orm-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.13.0
+Version: 0.14.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: alembic>=1.18.1 ; extra == 'alembic'
 Requires-Dist: sqlalchemy>=2.0.46 ; extra == 'alembic'
@@ -54,7 +54,7 @@ pip install ferro-orm
 pip install "ferro-orm[alembic]"
 ```
 
-Ferro currently supports SQLite and PostgreSQL. Register multiple named connections with `connect(..., name="...")` when a process needs more than one database — see the [connections guide](https://syn54x.github.io/ferro-orm/guide/connections/).
+Ferro currently supports SQLite and PostgreSQL. Register multiple named connections with `connect(..., name="...")` when a process needs more than one database — see the [connections guide](https://ferro-orm.x54.sh/guide/connections/).
 
 ## Quick Start
 

{ferro_orm-0.13.0 → ferro_orm-0.14.0}/README.md

@@ -41,7 +41,7 @@ pip install ferro-orm
 pip install "ferro-orm[alembic]"
 ```
 
-Ferro currently supports SQLite and PostgreSQL. Register multiple named connections with `connect(..., name="...")` when a process needs more than one database — see the [connections guide](https://syn54x.github.io/ferro-orm/guide/connections/).
+Ferro currently supports SQLite and PostgreSQL. Register multiple named connections with `connect(..., name="...")` when a process needs more than one database — see the [connections guide](https://ferro-orm.x54.sh/guide/connections/).
 
 ## Quick Start
 

ferro_orm-0.14.0/benchmarks/README.md

@@ -0,0 +1,133 @@
+# Ferro hot-path benchmarks
+
+A small, pinned, repeatable suite that measures Ferro's Python-facing async hot
+path — **single save**, **bulk save**, and a **filtered fetch of ~10k rows** — on
+both backends, over a rich-type fixture model. It exists so the before/after of
+Epic **FF-C** (per-model codec plans, catalog cache, native Postgres decode, enum
+hydration) is quantifiable and future hot-path regressions are visible.
+
+It is **purely additive**: it imports the public Ferro API and changes no
+production code. It is **not** part of `just test`, so it never slows the
+functional matrix.
+
+## What it measures
+
+Four cases per backend, over `BenchRecord` (see `model.py`):
+
+| benchmark                 | operation                                             | rows |
+| ------------------------- | ----------------------------------------------------- | ---- |
+| `single_save`             | `record.save()` — one INSERT                          | 1    |
+| `bulk_save`               | `BenchRecord.bulk_create([...])` — one bulk INSERT    | 10k  |
+| `fetch_10k_identity_on`   | `BenchRecord.where(...).all()`, identity map **on**   | 10k  |
+| `fetch_10k_identity_off`  | `BenchRecord.where(...).all()`, identity map **off**  | 10k  |
+
+Only **wall-clock** is recorded (median / min / mean / stdev / p95, in ms).
+
+### Why the rich-type fixture is load-bearing
+
+A plain `int`/`str` model would show *nothing* from FF-C. Every `BenchRecord`
+field maps to a concrete cost C1–C4 removes, so the suite makes that work
+visible:
+
+- `created_at: datetime` (`db_type="timestamptz"`) → **C3** native typed decode
+  (today a `CAST(... AS text)` projection on Postgres — finding **F8**).
+- `balance: Decimal` → **C1/F5** per-value codec (the `pattern_looks_decimal`
+  heuristic C1 deletes).
+- `external_id: uuid.UUID` (`db_type="uuid"`) → **C3** typed decode / UUID casing.
+- `status: Status` (`str, Enum`, no `db_type`) → native Postgres enum, **C4**
+  enum hydration (removes the `_fix_types` Python post-pass).
+- `attributes: dict[str, str]` → JSON codec.
+- `name`, `score` → the plain-typed baseline columns.
+
+Catalog round-trips (**F4**) are incurred by all of the above during
+save/fetch/migrate, so they are exercised implicitly.
+
+## Running
+
+```bash
+just bench                 # SQLite always; Postgres if FERRO_POSTGRES_URL is set
+# or directly:
+uv run python -m benchmarks.run
+```
+
+Postgres is included automatically when a URL is configured (via
+`FERRO_POSTGRES_URL` or a repo-root `.env`, reusing `tests/db_backends.py`); it is
+skipped with a printed note otherwise.
+
+Useful flags: `--rows N`, `--iters N`, `--warmup N`, `--seed N`,
+`--backends sqlite,postgres`, `--out DIR`.
+
+Each run writes `baselines/<backend>.json` (per-backend, keyed by benchmark name)
+and prints a summary table.
+
+## Capturing a before/after around a change
+
+```bash
+# 1. Baseline the current code into a scratch dir
+uv run python -m benchmarks.run --out /tmp/before
+
+# 2. Make your hot-path change, rebuild the Rust core
+uv run maturin develop
+
+# 3. Re-run into a second dir
+uv run python -m benchmarks.run --out /tmp/after
+
+# 4. Diff the medians (per backend)
+uv run python -m benchmarks.compare /tmp/before/sqlite.json /tmp/after/sqlite.json
+uv run python -m benchmarks.compare /tmp/before/postgres.json /tmp/after/postgres.json
+```
+
+`compare` prints each benchmark's `old → new` median with **Δms** and **Δ%**.
+Negative % is a speed-up (green); positive is a regression (red).
+
+## Reading the deltas
+
+- Compare **same backend, same machine** only. Absolute numbers vary wildly by
+  backend and hardware; the deliverable is a stable *per-backend delta*, never a
+  SQLite-vs-Postgres comparison.
+- The checked-in `baselines/*.json` were captured on a developer machine and are
+  a reference point, not a CI gate. Re-capture your own baseline before measuring
+  a change so both sides come from the same box.
+- Watch the **median** for the headline and **stdev/p95** for noise. If stdev is
+  a large fraction of the median, raise `--warmup`/`--iters` until it settles
+  before trusting a delta.
+
+## Stability knobs
+
+Fixed row counts, deterministic seed data (`random.Random(seed)`), discarded
+warmup iterations, a fresh database per case (temp SQLite file / dropped-and-
+recreated PG schema), a pinned pool (`max_connections=5`), and a single
+persistent event loop across all cases. The fetch cases are measured with the
+identity map both on and off because that bookkeeping is real hot-path cost the
+FF-C rewrite interacts with.
+
+## FF-C epic results (recorded 2026-07-02)
+
+Full before/after of Epic FF-C — **before** is the pre-C1 baseline capture
+(`d9a656b`), **after** is post-C2 (catalog cache; C1 codec plan, C3 native
+decode, and C4 enum hydration included). Same machine, release-profile `.so`
+(sha-verified), medians in ms.
+
+**Postgres**
+
+| benchmark                | pre-C1 | post-C2 | Δ %    | C2-only Δ % (vs post-C3) |
+| ------------------------ | ------ | ------- | ------ | ------------------------ |
+| single_save              | 1.708  | 0.399   | −76.6% | −66.9%                   |
+| bulk_save                | 389.5  | 92.1    | −76.4% | −11.8%                   |
+| fetch_10000_identity_on  | 189.5  | 16.1    | −91.5% | −16.9%                   |
+| fetch_10000_identity_off | 285.9  | 67.3    | −76.5% | +0.0%                    |
+
+**SQLite**
+
+| benchmark                | pre-C1 | post-C2 | Δ %    | C2-only Δ % (vs post-C3) |
+| ------------------------ | ------ | ------- | ------ | ------------------------ |
+| single_save              | 0.352  | 0.277   | −21.2% | −9.8%                    |
+| bulk_save                | 221.5  | 54.6    | −75.4% | −0.1%                    |
+| fetch_10000_identity_on  | 175.5  | 34.5    | −80.4% | +1.0%                    |
+| fetch_10000_identity_off | 271.2  | 80.9    | −70.2% | +0.4%                    |
+
+The C2 column isolates the catalog cache: on Postgres the save path drops
+sharply (3 catalog round-trips per op eliminated — F4; single_save
+1.21 → 0.40 ms), while SQLite deltas are noise, as required (the cache is a
+no-op off Postgres). The checked-in `baselines/*.json` are the post-C2
+capture.

ferro_orm-0.14.0/benchmarks/__init__.py

@@ -0,0 +1,11 @@
+"""Ferro hot-path benchmark suite (Epic FF-C, sub-task C5).
+
+A small, pinned, repeatable suite measuring the Python-facing async hot path —
+single save, bulk save, and a filtered fetch of ~10k rows — on both backends
+(SQLite always; Postgres when ``FERRO_POSTGRES_URL`` is configured), over a
+rich-type fixture model that exercises the type-decision path FF-C's C1–C4
+rewrite touches.
+
+The suite is purely additive: it imports the public Ferro API and never changes
+production code. Run it with ``just bench`` (see ``benchmarks/README.md``).
+"""

ferro_orm-0.14.0/benchmarks/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m benchmarks`` → run the suite (alias for ``benchmarks.run``)."""
+
+from __future__ import annotations
+
+import sys
+
+from benchmarks.run import main
+
+if __name__ == "__main__":
+    sys.exit(main())