ferrum-orm 0.1.17__tar.gz → 0.1.19__tar.gz

{ferrum_orm-0.1.17 → ferrum_orm-0.1.19}/Cargo.lock

@@ -25,9 +25,9 @@ checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
 
 [[package]]
 name = "anyhow"
-version = "1.0.102"
+version = "1.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
 
 [[package]]
 name = "autocfg"
@@ -223,7 +223,7 @@ checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "ferrum-core"
-version = "0.1.17"
+version = "0.1.19"
 dependencies = [
  "criterion",
  "proptest",
@@ -234,7 +234,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-migrate"
-version = "0.1.17"
+version = "0.1.19"
 dependencies = [
  "ferrum-core",
  "serde",
@@ -243,7 +243,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-pyo3"
-version = "0.1.17"
+version = "0.1.19"
 dependencies = [
  "ferrum-core",
  "ferrum-sql",
@@ -255,7 +255,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-sql"
-version = "0.1.17"
+version = "0.1.19"
 dependencies = [
  "criterion",
  "ferrum-core",

{ferrum_orm-0.1.17 → ferrum_orm-0.1.19}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferrum-core", "crates/ferrum-sql", "crates/ferrum-pyo3"]
 resolver = "2"
 
 [workspace.package]
-version = "0.1.17"
+version = "0.1.19"
 edition = "2021"
 authors = ["Ferrum Contributors"]
 license = "Apache-2.0"

{ferrum_orm-0.1.17 → ferrum_orm-0.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferrum-orm
-Version: 0.1.17
+Version: 0.1.19
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -25,7 +25,7 @@ Requires-Dist: ferrum-orm[cli] ; extra == 'all'
 Requires-Dist: ferrum-orm[dotenv] ; extra == 'all'
 Requires-Dist: typer>=0.12 ; extra == 'cli'
 Requires-Dist: rich>=13 ; extra == 'cli'
-Requires-Dist: ferrum-orm[pg,cli,dotenv] ; extra == 'dev'
+Requires-Dist: ferrum-orm[pg,mysql,sqlite,mssql,cli,dotenv] ; extra == 'dev'
 Requires-Dist: maturin>=1.7,<2 ; extra == 'dev'
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
@@ -96,12 +96,25 @@ Ferrum aims to provide all four.
 - Pydantic-first models
 - Django-inspired ORM experience
 - Rust-powered query engine
-- PostgreSQL-first architecture (MySQL, SQLite, and SQL Server via optional extras)
+- PostgreSQL-first architecture. MySQL, SQLite, and SQL Server extras are best-effort thin parity — not production-supported and not production-readiness release gates
 - Type-safe query construction
 - Automatic migrations
 - High-performance result hydration
 - Production-ready observability
 
+### Production-readiness execution
+
+Ferrum is still alpha. The remaining production work for Ticket Analyzer and an
+async-refactored Org AI Platform is tracked in
+[the production-readiness plan](.cursor/plans/ferrum-production-readiness_6b5f422d.plan.md).
+Execution is wave-based and supports parallel agents through disjoint file ownership,
+per-workstream state, immutable evidence logs, and an independent verification gate.
+
+Every task follows `Specify → Plan → Tasks → Implement`; every executor run follows
+`Load → Execute → Validate executor output → Verify independently → Update state`.
+See [.agent-work/production-readiness/](.agent-work/production-readiness/) for the durable
+execution contract and current aggregate state.
+
 ---
 
 ## Quick Example
@@ -285,7 +298,9 @@ This allows Ferrum to maintain a Pythonic API without sacrificing performance.
 ### Cross-Driver Full-Text Search
 
 Native full-text search across PostgreSQL, MySQL, SQLite FTS5, and SQL Server — one
-QuerySet API, dialect-specific SQL emit and migration DDL.
+QuerySet API, dialect-specific SQL emit and migration DDL. Cross-dialect FTS on
+MySQL / SQLite / SQL Server is a **thin-extra** capability, not a P0
+production-readiness release gate. PostgreSQL FTS is the production-readiness target.
 
 **Query modes** (filter lookups and ranking):
 
@@ -366,7 +381,7 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 - [x] Migrations (schema diff, apply, revert, CLI)
 - [x] Relationships (ForeignKey, OneToOne, ManyToMany)
 - [x] pgvector KNN search and HNSW/IVFFLAT index DDL
-- [x] Full-text search (cross-dialect: PostgreSQL, MySQL, SQLite FTS5, SQL Server)
+- [x] Full-text search (PostgreSQL is the P0 gate; MySQL/SQLite/SQL Server FTS is thin-extra)
 - [x] Observability hooks (Tier A/B/C)
 - [x] CLI (`makemigrations`, `migrate`, `revert`, `showmigrations`, `inspectdb`, `resetdb`)
 
@@ -397,7 +412,11 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 
 Ferrum is currently in active development.
 
-The API is not yet stable and breaking changes should be expected until the first public release.
+The API is not yet stable. **0.x has no compatibility guarantee**: SemVer MINOR and PATCH
+may both break. After 1.0, public API and migration-ops breaks require a deprecation
+window of at least one minor release and 90 days, whichever is longer. Generated SQL is
+never a compatibility surface. Compatibility policy: `AGENTS.md` §5a. Thin extras:
+`AGENTS.md` §2.6. See also `CHANGELOG.md`.
 
 ## Installation
 
@@ -430,10 +449,45 @@ pip install ferrum-orm
 Bare `ferrum-orm` installs Pydantic and the Rust core only. Choose a driver extra
 (`pg`, `mysql`, `sqlite`, or `mssql`) before calling `ferrum.connect()`.
 
-MySQL, SQLite, and SQL Server are **thin-parity** backends: they support core CRUD
-and migrations but not transactions, upsert, `bulk_update`, RLS, or pgvector
-(PostgreSQL only). SQL Server connects via `aioodbc`/`pyodbc` and requires a system
-ODBC driver such as `msodbcsql18`; DSNs use the `mssql://` or `sqlserver://` scheme.
+MySQL, SQLite, and SQL Server are **best-effort thin-parity** backends: they are **not
+production-supported** and are **not production-readiness release gates**. Core CRUD is
+exercised across all four drivers; advanced behavior is capability-gated rather than
+emulated with incompatible SQL. The integration-suite registry
+(`tests/python/integration/backends.py`) is the coverage matrix — what is tested,
+not a stability or production-support claim. PostgreSQL claims every capability.
+MySQL and SQL Server claim full-text search and composite primary keys only.
+SQLite claims `RETURNING`, full-text search, and composite primary keys.
+
+| Capability | PostgreSQL | MySQL | SQLite | SQL Server |
+| ---------- | :--------: | :---: | :----: | :--------: |
+| Transactions | ✅ | — | — | — |
+| Savepoints | ✅ | — | — | — |
+| Cursor streaming | ✅ | — | — | — |
+| Bulk update | ✅ | — | — | — |
+| Aggregates / grouping | ✅ | — | — | — |
+| Upsert | ✅ | — | — | — |
+| Returning rows | ✅ | — | ✅ | — |
+| Row-level security helpers | ✅ | — | — | — |
+| pgvector | ✅ | — | — | — |
+| Full-text search | ✅ | ✅ | ✅ | ✅ |
+| JSON operators | ✅ | — | — | — |
+| Case-insensitive `ILIKE` | ✅ | — | — | — |
+| Array columns | ✅ | — | — | — |
+| Alter column | ✅ | — | — | — |
+| Composite primary keys | ✅ | ✅ | ✅ | ✅ |
+| Stored-function calls | ✅ | — | — | — |
+
+Unsupported capabilities fail with a typed Ferrum error before backend SQL is
+executed. Transactions, savepoints, aggregates, upsert, alter-column, and
+stored-function calls are PostgreSQL-only in this matrix; thin extras raise at
+the Python/compiler boundary rather than sending Postgres SQL. Pull requests
+exercise PostgreSQL and SQLite, while the nightly integration matrix runs
+PostgreSQL, MySQL, SQLite, and SQL Server independently. SQLite on PRs is CI
+coverage, not a production-readiness gate. Cross-dialect FTS in the matrix is
+thin-extra coverage, not a P0 release gate.
+
+SQL Server connects via `aioodbc`/`pyodbc` and requires a system ODBC driver such
+as `msodbcsql18`; DSNs use the `mssql://` or `sqlserver://` scheme.
 
 ### Wire format (advanced)
 

{ferrum_orm-0.1.17 → ferrum_orm-0.1.19}/README.md

@@ -24,12 +24,25 @@ Ferrum aims to provide all four.
 - Pydantic-first models
 - Django-inspired ORM experience
 - Rust-powered query engine
-- PostgreSQL-first architecture (MySQL, SQLite, and SQL Server via optional extras)
+- PostgreSQL-first architecture. MySQL, SQLite, and SQL Server extras are best-effort thin parity — not production-supported and not production-readiness release gates
 - Type-safe query construction
 - Automatic migrations
 - High-performance result hydration
 - Production-ready observability
 
+### Production-readiness execution
+
+Ferrum is still alpha. The remaining production work for Ticket Analyzer and an
+async-refactored Org AI Platform is tracked in
+[the production-readiness plan](.cursor/plans/ferrum-production-readiness_6b5f422d.plan.md).
+Execution is wave-based and supports parallel agents through disjoint file ownership,
+per-workstream state, immutable evidence logs, and an independent verification gate.
+
+Every task follows `Specify → Plan → Tasks → Implement`; every executor run follows
+`Load → Execute → Validate executor output → Verify independently → Update state`.
+See [.agent-work/production-readiness/](.agent-work/production-readiness/) for the durable
+execution contract and current aggregate state.
+
 ---
 
 ## Quick Example
@@ -213,7 +226,9 @@ This allows Ferrum to maintain a Pythonic API without sacrificing performance.
 ### Cross-Driver Full-Text Search
 
 Native full-text search across PostgreSQL, MySQL, SQLite FTS5, and SQL Server — one
-QuerySet API, dialect-specific SQL emit and migration DDL.
+QuerySet API, dialect-specific SQL emit and migration DDL. Cross-dialect FTS on
+MySQL / SQLite / SQL Server is a **thin-extra** capability, not a P0
+production-readiness release gate. PostgreSQL FTS is the production-readiness target.
 
 **Query modes** (filter lookups and ranking):
 
@@ -294,7 +309,7 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 - [x] Migrations (schema diff, apply, revert, CLI)
 - [x] Relationships (ForeignKey, OneToOne, ManyToMany)
 - [x] pgvector KNN search and HNSW/IVFFLAT index DDL
-- [x] Full-text search (cross-dialect: PostgreSQL, MySQL, SQLite FTS5, SQL Server)
+- [x] Full-text search (PostgreSQL is the P0 gate; MySQL/SQLite/SQL Server FTS is thin-extra)
 - [x] Observability hooks (Tier A/B/C)
 - [x] CLI (`makemigrations`, `migrate`, `revert`, `showmigrations`, `inspectdb`, `resetdb`)
 
@@ -325,7 +340,11 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 
 Ferrum is currently in active development.
 
-The API is not yet stable and breaking changes should be expected until the first public release.
+The API is not yet stable. **0.x has no compatibility guarantee**: SemVer MINOR and PATCH
+may both break. After 1.0, public API and migration-ops breaks require a deprecation
+window of at least one minor release and 90 days, whichever is longer. Generated SQL is
+never a compatibility surface. Compatibility policy: `AGENTS.md` §5a. Thin extras:
+`AGENTS.md` §2.6. See also `CHANGELOG.md`.
 
 ## Installation
 
@@ -358,10 +377,45 @@ pip install ferrum-orm
 Bare `ferrum-orm` installs Pydantic and the Rust core only. Choose a driver extra
 (`pg`, `mysql`, `sqlite`, or `mssql`) before calling `ferrum.connect()`.
 
-MySQL, SQLite, and SQL Server are **thin-parity** backends: they support core CRUD
-and migrations but not transactions, upsert, `bulk_update`, RLS, or pgvector
-(PostgreSQL only). SQL Server connects via `aioodbc`/`pyodbc` and requires a system
-ODBC driver such as `msodbcsql18`; DSNs use the `mssql://` or `sqlserver://` scheme.
+MySQL, SQLite, and SQL Server are **best-effort thin-parity** backends: they are **not
+production-supported** and are **not production-readiness release gates**. Core CRUD is
+exercised across all four drivers; advanced behavior is capability-gated rather than
+emulated with incompatible SQL. The integration-suite registry
+(`tests/python/integration/backends.py`) is the coverage matrix — what is tested,
+not a stability or production-support claim. PostgreSQL claims every capability.
+MySQL and SQL Server claim full-text search and composite primary keys only.
+SQLite claims `RETURNING`, full-text search, and composite primary keys.
+
+| Capability | PostgreSQL | MySQL | SQLite | SQL Server |
+| ---------- | :--------: | :---: | :----: | :--------: |
+| Transactions | ✅ | — | — | — |
+| Savepoints | ✅ | — | — | — |
+| Cursor streaming | ✅ | — | — | — |
+| Bulk update | ✅ | — | — | — |
+| Aggregates / grouping | ✅ | — | — | — |
+| Upsert | ✅ | — | — | — |
+| Returning rows | ✅ | — | ✅ | — |
+| Row-level security helpers | ✅ | — | — | — |
+| pgvector | ✅ | — | — | — |
+| Full-text search | ✅ | ✅ | ✅ | ✅ |
+| JSON operators | ✅ | — | — | — |
+| Case-insensitive `ILIKE` | ✅ | — | — | — |
+| Array columns | ✅ | — | — | — |
+| Alter column | ✅ | — | — | — |
+| Composite primary keys | ✅ | ✅ | ✅ | ✅ |
+| Stored-function calls | ✅ | — | — | — |
+
+Unsupported capabilities fail with a typed Ferrum error before backend SQL is
+executed. Transactions, savepoints, aggregates, upsert, alter-column, and
+stored-function calls are PostgreSQL-only in this matrix; thin extras raise at
+the Python/compiler boundary rather than sending Postgres SQL. Pull requests
+exercise PostgreSQL and SQLite, while the nightly integration matrix runs
+PostgreSQL, MySQL, SQLite, and SQL Server independently. SQLite on PRs is CI
+coverage, not a production-readiness gate. Cross-dialect FTS in the matrix is
+thin-extra coverage, not a P0 release gate.
+
+SQL Server connects via `aioodbc`/`pyodbc` and requires a system ODBC driver such
+as `msodbcsql18`; DSNs use the `mssql://` or `sqlserver://` scheme.
 
 ### Wire format (advanced)
 

ferrum_orm-0.1.19/crates/ferrum-core/benches/hydrate.rs

@@ -0,0 +1,384 @@
+//! Criterion benchmarks for row hydration at 1 / 10 / 100 / 1000 rows.
+//!
+//! Budget (ARCHITECTURE.md §14 / benches/README.md): `hydrate_rows` p99 < 5 ms @ 100 rows.
+//!
+//! Coverage added in W4-B:
+//! - `hydrate_rows` across 1 / 10 / 100 / 1000 rows (original).
+//! - `hydrate_rows_wide` — 20-column row to measure per-field validation cost
+//!   scaling with column count.
+//! - `hydrate_rows_jsonb` — JSONB + array + vector field types to cover the
+//!   type mix used by ticket-analyzer workloads.
+//! - `json_boundary_encode` / `json_boundary_decode` — the throwaway
+//!   serde_json copy the PyO3 bridge makes for Rust structural validation
+//!   (AGENTS.md: `_RowEncoder` serializes a copy for validation only). This
+//!   isolates the JSON wire-format boundary cost from hydration itself.
+//! - `validation_copy` — the `validate_row` walk over non-nullable fields,
+//!   measured by hydrating the same rows with all-non-nullable vs
+//!   all-nullable metadata so the delta is the validation walk.
+
+// Bench-harness files are test infrastructure, not shipped code. Keep
+// `clippy::all` enforced; suppress the pedantic group (doc backticks,
+// cast-precision on bench indices) to keep data construction readable.
+#![allow(clippy::pedantic)]
+
+use criterion::{black_box, criterion_group, criterion_main, BatchSize, BenchmarkId, Criterion};
+use ferrum_core::hydrate::hydrate_rows;
+use ferrum_core::hydrate::RowPayload;
+use ferrum_core::ir::metadata::{FieldMeta, FieldType, ModelMetadata};
+use serde_json::json;
+
+// ---------------------------------------------------------------------------
+// Metadata builders
+// ---------------------------------------------------------------------------
+
+fn bench_metadata() -> ModelMetadata {
+    ModelMetadata {
+        model_name: "Post".into(),
+        table_name: "posts".into(),
+        fields: vec![
+            FieldMeta {
+                name: "id".into(),
+                column_name: "id".into(),
+                field_type: FieldType::Int,
+                allowed_operators: vec!["eq".into()],
+                nullable: false,
+                vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
+            },
+            FieldMeta {
+                name: "title".into(),
+                column_name: "title".into(),
+                field_type: FieldType::Text,
+                allowed_operators: vec!["eq".into(), "icontains".into()],
+                nullable: false,
+                vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
+            },
+            FieldMeta {
+                name: "body".into(),
+                column_name: "body".into(),
+                field_type: FieldType::Text,
+                allowed_operators: vec!["eq".into()],
+                nullable: true,
+                vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
+            },
+            FieldMeta {
+                name: "published".into(),
+                column_name: "published".into(),
+                field_type: FieldType::Bool,
+                allowed_operators: vec!["eq".into()],
+                nullable: false,
+                vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
+            },
+        ],
+        pk_index: 0,
+        pk_fields: vec![0],
+        full_text_indexes: vec![],
+    }
+}
+
+/// 20-column wide model — measures validation cost scaling with column count.
+fn wide_metadata(nullable: bool) -> ModelMetadata {
+    let fields = (0..20)
+        .map(|i| FieldMeta {
+            name: format!("col{i}"),
+            column_name: format!("col{i}"),
+            field_type: if i % 5 == 0 {
+                FieldType::Int
+            } else if i % 5 == 1 {
+                FieldType::Text
+            } else if i % 5 == 2 {
+                FieldType::Bool
+            } else if i % 5 == 3 {
+                FieldType::Float
+            } else {
+                FieldType::Json
+            },
+            allowed_operators: vec!["eq".into()],
+            nullable,
+            vector_dimensions: None,
+            fts_config: None,
+            fts_source_columns: None,
+        })
+        .collect();
+    ModelMetadata {
+        model_name: "Wide".into(),
+        table_name: "wide".into(),
+        fields,
+        pk_index: 0,
+        pk_fields: vec![0],
+        full_text_indexes: vec![],
+    }
+}
+
+/// JSONB + array + vector field mix — ticket-analyzer workload shape.
+fn jsonb_metadata() -> ModelMetadata {
+    ModelMetadata {
+        model_name: "Doc".into(),
+        table_name: "docs".into(),
+        fields: vec![
+            FieldMeta {
+                name: "id".into(),
+                column_name: "id".into(),
+                field_type: FieldType::Uuid,
+                allowed_operators: vec!["eq".into()],
+                nullable: false,
+                vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
+            },
+            FieldMeta {
+                name: "tags".into(),
+                column_name: "tags".into(),
+                field_type: FieldType::ArrayText,
+                allowed_operators: vec!["eq".into(), "contains".into()],
+                nullable: true,
+                vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
+            },
+            FieldMeta {
+                name: "meta".into(),
+                column_name: "meta".into(),
+                field_type: FieldType::Json,
+                allowed_operators: vec!["eq".into(), "contains".into(), "has_key".into()],
+                nullable: true,
+                vector_dimensions: None,
+                fts_config: None,
+                fts_source_columns: None,
+            },
+            FieldMeta {
+                name: "embedding".into(),
+                column_name: "embedding".into(),
+                field_type: FieldType::Vector,
+                allowed_operators: vec!["eq".into()],
+                nullable: true,
+                vector_dimensions: Some(8),
+                fts_config: None,
+                fts_source_columns: None,
+            },
+        ],
+        pk_index: 0,
+        pk_fields: vec![0],
+        full_text_indexes: vec![],
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Row builders
+// ---------------------------------------------------------------------------
+
+fn make_rows(count: usize) -> Vec<RowPayload> {
+    (0..count)
+        .map(|i| {
+            serde_json::from_value(json!({
+                "id": i64::try_from(i).expect("bench row index") + 1,
+                "title": format!("Post title {i}"),
+                "body": if i % 3 == 0 { serde_json::Value::Null } else { json!(format!("Body {i}")) },
+                "published": i % 2 == 0,
+            }))
+            .expect("valid row payload")
+        })
+        .collect()
+}
+
+fn make_wide_rows(count: usize) -> Vec<RowPayload> {
+    (0..count)
+        .map(|i| {
+            let mut obj = serde_json::Map::new();
+            for j in 0..20_u32 {
+                let key = format!("col{j}");
+                let val = match j % 5 {
+                    0 => json!((i as i64) + j as i64),
+                    1 => json!(format!("text-{i}-{j}")),
+                    2 => json!(j % 2 == 0),
+                    3 => json!(i as f64 + 0.5 * j as f64),
+                    _ => json!({"k": i, "j": j}),
+                };
+                obj.insert(key, val);
+            }
+            obj
+        })
+        .collect()
+}
+
+fn make_jsonb_rows(count: usize) -> Vec<RowPayload> {
+    (0..count)
+        .map(|i| {
+            serde_json::from_value(json!({
+                "id": format!("00000000-0000-0000-0000-{:012x}", i),
+                "tags": ["alpha", "beta", format!("tag{i}")],
+                "meta": {"category": "doc", "weight": i, "nested": {"flag": true}},
+                "embedding": [0.1_f64 * i as f64, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8],
+            }))
+            .expect("valid jsonb row payload")
+        })
+        .collect()
+}
+
+// ---------------------------------------------------------------------------
+// Benchmarks
+// ---------------------------------------------------------------------------
+
+fn hydrate_rows_bench(c: &mut Criterion) {
+    let metadata = bench_metadata();
+    let row_counts = [1_usize, 10, 100, 1000];
+
+    let mut group = c.benchmark_group("hydrate_rows");
+    group.sample_size(50);
+    group.warm_up_time(std::time::Duration::from_millis(300));
+    group.measurement_time(std::time::Duration::from_secs(3));
+
+    for count in row_counts {
+        let rows = make_rows(count);
+        group.bench_with_input(BenchmarkId::new("rows", count), &rows, |b, batch| {
+            b.iter_batched(
+                || batch.clone(),
+                |rows| hydrate_rows(black_box(&metadata), black_box(rows)).unwrap(),
+                BatchSize::SmallInput,
+            );
+        });
+    }
+
+    group.finish();
+}
+
+fn hydrate_rows_wide_bench(c: &mut Criterion) {
+    // All-non-nullable: every column triggers the validation lookup.
+    let metadata = wide_metadata(false);
+    let rows100 = make_wide_rows(100);
+
+    let mut group = c.benchmark_group("hydrate_rows_wide");
+    group.sample_size(50);
+    group.warm_up_time(std::time::Duration::from_millis(300));
+    group.measurement_time(std::time::Duration::from_secs(3));
+
+    group.bench_with_input(BenchmarkId::new("cols20", 100), &rows100, |b, batch| {
+        b.iter_batched(
+            || batch.clone(),
+            |rows| hydrate_rows(black_box(&metadata), black_box(rows)).unwrap(),
+            BatchSize::SmallInput,
+        );
+    });
+
+    group.finish();
+}
+
+fn hydrate_rows_jsonb_bench(c: &mut Criterion) {
+    let metadata = jsonb_metadata();
+    let row_counts = [1_usize, 100];
+
+    let mut group = c.benchmark_group("hydrate_rows_jsonb");
+    group.sample_size(50);
+    group.warm_up_time(std::time::Duration::from_millis(300));
+    group.measurement_time(std::time::Duration::from_secs(3));
+
+    for count in row_counts {
+        let rows = make_jsonb_rows(count);
+        group.bench_with_input(BenchmarkId::new("rows", count), &rows, |b, batch| {
+            b.iter_batched(
+                || batch.clone(),
+                |rows| hydrate_rows(black_box(&metadata), black_box(rows)).unwrap(),
+                BatchSize::SmallInput,
+            );
+        });
+    }
+
+    group.finish();
+}
+
+/// Validation-copy isolation: hydrate the same wide rows under all-nullable
+/// metadata (validation walk still iterates but skips the null checks) vs
+/// all-non-nullable (full validation). The delta is the validation copy cost.
+fn validation_copy_bench(c: &mut Criterion) {
+    let meta_nullable = wide_metadata(true);
+    let meta_strict = wide_metadata(false);
+    let rows = make_wide_rows(100);
+
+    let mut group = c.benchmark_group("validation_copy");
+    group.sample_size(50);
+    group.warm_up_time(std::time::Duration::from_millis(300));
+    group.measurement_time(std::time::Duration::from_secs(3));
+
+    group.bench_with_input(BenchmarkId::new("nullable_meta", 100), &rows, |b, batch| {
+        b.iter_batched(
+            || batch.clone(),
+            |rows| hydrate_rows(black_box(&meta_nullable), black_box(rows)).unwrap(),
+            BatchSize::SmallInput,
+        );
+    });
+
+    group.bench_with_input(BenchmarkId::new("strict_meta", 100), &rows, |b, batch| {
+        b.iter_batched(
+            || batch.clone(),
+            |rows| hydrate_rows(black_box(&meta_strict), black_box(rows)).unwrap(),
+            BatchSize::SmallInput,
+        );
+    });
+
+    group.finish();
+}
+
+/// JSON wire-format boundary cost: the throwaway serde_json round-trip the
+/// PyO3 bridge performs for Rust structural validation (AGENTS.md: `_RowEncoder`
+/// serializes a copy; `model_construct` receives native driver types). This
+/// isolates serialization from hydration by encoding rows to JSON bytes and
+/// decoding them back, without invoking `hydrate_rows`.
+fn json_boundary_bench(c: &mut Criterion) {
+    let row_counts = [1_usize, 100, 1000];
+
+    let mut group = c.benchmark_group("json_boundary");
+    group.sample_size(50);
+    group.warm_up_time(std::time::Duration::from_millis(300));
+    group.measurement_time(std::time::Duration::from_secs(3));
+
+    for count in row_counts {
+        let rows = make_rows(count);
+
+        group.bench_with_input(BenchmarkId::new("encode", count), &rows, |b, batch| {
+            b.iter_batched(
+                || serde_json::to_vec(batch).expect("encode"),
+                |bytes| {
+                    black_box(bytes);
+                },
+                BatchSize::SmallInput,
+            );
+        });
+
+        let encoded: Vec<Vec<u8>> = rows
+            .iter()
+            .map(|r| serde_json::to_vec(r).expect("encode"))
+            .collect();
+        group.bench_with_input(BenchmarkId::new("decode", count), &encoded, |b, batch| {
+            b.iter_batched(
+                || batch.clone(),
+                |bytes_vec| {
+                    let decoded: Vec<RowPayload> = bytes_vec
+                        .iter()
+                        .map(|b| serde_json::from_slice(b).expect("decode"))
+                        .collect();
+                    black_box(decoded);
+                },
+                BatchSize::SmallInput,
+            );
+        });
+    }
+
+    group.finish();
+}
+
+criterion_group!(
+    benches,
+    hydrate_rows_bench,
+    hydrate_rows_wide_bench,
+    hydrate_rows_jsonb_bench,
+    validation_copy_bench,
+    json_boundary_bench,
+);
+criterion_main!(benches);