ferro-orm 0.16.1__tar.gz → 0.16.2__tar.gz

{ferro_orm-0.16.1 → ferro_orm-0.16.2}/CHANGELOG.md

@@ -1,6 +1,20 @@
 # CHANGELOG
 
 
+## v0.16.2 (2026-07-15)
+
+### Bug Fixes
+
+- Self-referential FKs no longer evict their component from CREATE TABLE order
+  ([#303](https://github.com/syn54x/ferro-orm/pull/303),
+  [`d1a55f6`](https://github.com/syn54x/ferro-orm/commit/d1a55f6ae241101d98ee659e6651fa33abaf4ec5))
+
+### Refactoring
+
+- Compile QueryIR payloads at a single wire choke point
+  ([`851b3f4`](https://github.com/syn54x/ferro-orm/commit/851b3f4e1f077d70481ebca643ff0ffff81645d8))
+
+
 ## v0.16.1 (2026-07-13)
 
 ### Bug Fixes

{ferro_orm-0.16.1 → ferro_orm-0.16.2}/CONTEXT.md

@@ -80,6 +80,14 @@ _Avoid_: Eager-loaded field, select_related, prefetched attribute, joined attrib
 A query's declaration of what its result columns become: complete root instances (every query today), a projected record of named fields, or — in the future — a populated instance graph. Every query carries exactly one plan; the plan travels with the query rather than being inferred from its column list.
 _Avoid_: Select list, projection spec, hydration mode flag
 
+**QueryIR payload**:
+The single typed wire artifact a query ships to the Rust runtime — model identity, predicates, ordering, paging, joins, and exactly one materialization plan, inside a versioned envelope. Compiled only by `compile_query`; no other code assembles query wire shape.
+_Avoid_: Query dict, query def, payload dict
+
+**Golden vector**:
+A hand-authored JSON fixture pinning one wire shape — the independent authority both the Python emitter and the Rust decoder assert against, never regenerated from either side's output. Updating one by hand is the contract-review moment for a wire change.
+_Avoid_: Snapshot, fixture dump, example payload
+
 **Aggregate projection**:
 A projection containing at least one aggregate field. Each group collapses to exactly one projected record: every non-aggregate field is a group key, so grouping is derived from the projection and never declared separately. With no non-aggregate fields, the whole result collapses to a single record. Grouping collapses rows — bucketing complete instances by a key ("partitioning") is a different, client-side operation and is not grouping.
 _Avoid_: Group-by query, summary query, rollup, partition

{ferro_orm-0.16.1 → ferro_orm-0.16.2}/Cargo.lock

@@ -327,7 +327,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.16.1"
+version = "0.16.2"
 dependencies = [
  "chrono",
  "dashmap",
@@ -890,9 +890,9 @@ dependencies = [
 
 [[package]]
 name = "mio"
-version = "1.2.1"
+version = "1.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
+checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
 dependencies = [
  "libc",
  "wasi",
@@ -1249,9 +1249,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.41"
+version = "0.23.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6b92b125634d9b795e7beca796cc790df15a7fb38323bf3196fda83292d06b1f"
+checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138"
 dependencies = [
  "once_cell",
  "ring",
@@ -1444,9 +1444,9 @@ dependencies = [
 
 [[package]]
 name = "socket2"
-version = "0.6.4"
+version = "0.6.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
 dependencies = [
  "libc",
  "windows-sys 0.61.2",
@@ -1454,9 +1454,9 @@ dependencies = [
 
 [[package]]
 name = "spin"
-version = "0.9.8"
+version = "0.9.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6980e8d7511241f8acf4aebddbb1ff938df5eebe98691418c4468d0b72a96a67"
+checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e"
 dependencies = [
  "lock_api",
 ]
@@ -1698,9 +1698,9 @@ checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
 
 [[package]]
 name = "syn"
-version = "2.0.118"
+version = "2.0.119"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2329,6 +2329,6 @@ dependencies = [
 
 [[package]]
 name = "zmij"
-version = "1.0.22"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bd2f034a4bebf216c9e4b7083603e024cf930873fd67830cfb083c9fa33129d9"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

{ferro_orm-0.16.1 → ferro_orm-0.16.2}/Cargo.toml

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

{ferro_orm-0.16.1 → ferro_orm-0.16.2}/PKG-INFO

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

{ferro_orm-0.16.1 → ferro_orm-0.16.2}/crates/ferro-migrate/src/emit.rs

@@ -255,47 +255,23 @@ fn post_create_artifacts(
 
 /// Order `AddTable` models so each table's FK targets are created before it.
 ///
-/// A FK dependency on a table that is *not* part of this add set (already
-/// exists in the live DB) does not constrain ordering. Cycles fall through in
-/// arbitrary order — the inline FKs are anonymous, so a cyclic create still
-/// runs (SQLite is lenient; Postgres `CREATE TABLE` with a forward inline FK
-/// reference is the pre-existing behavior preserved here).
+/// Delegates to [`crate::order_by_dependencies`] for the dependency
+/// semantics: a self-referential FK and a FK to a table outside this add set
+/// do not constrain ordering, and genuine cross-table cycles fall through in
+/// input order (SQLite tolerates the forward references; Postgres rejects
+/// them — #302 follow-up).
 pub fn order_models_for_create<'a>(models: &[&'a SchemaModel]) -> Vec<&'a SchemaModel> {
-    let mut remaining: Vec<&SchemaModel> = models.to_vec();
-    let mut ordered = Vec::new();
-    let mut created = std::collections::HashSet::new();
-
-    while !remaining.is_empty() {
-        let available: std::collections::HashSet<String> = remaining
-            .iter()
-            .map(|m| m.table_name.clone())
-            .collect();
-        let mut progress = false;
-        let mut index = 0;
-        while index < remaining.len() {
-            let deps: Vec<String> = remaining[index]
+    crate::order_by_dependencies(
+        models.to_vec(),
+        |model| model.table_name.clone(),
+        |model| {
+            model
                 .foreign_keys
                 .iter()
                 .map(|fk| fk.to_table.clone())
-                .collect();
-            if deps
-                .iter()
-                .all(|dep| created.contains(dep) || !available.contains(dep))
-            {
-                let model = remaining.remove(index);
-                created.insert(model.table_name.clone());
-                ordered.push(model);
-                progress = true;
-            } else {
-                index += 1;
-            }
-        }
-        if !progress {
-            ordered.append(&mut remaining);
-            break;
-        }
-    }
-    ordered
+                .collect()
+        },
+    )
 }
 
 fn emit_add_table_passes(

{ferro_orm-0.16.1 → ferro_orm-0.16.2}/crates/ferro-migrate/src/lib.rs

@@ -4,12 +4,14 @@
 //! [`emit_sql_with_ir`] lowers structural ops to executable backend-specific DDL.
 
 mod emit;
+mod order;
 
 use ferro_ddl_lowering::schema_columns_storage_drift;
 use ferro_schema_ir::{IrEnvelope, SchemaIrPayload, SchemaModel};
 use std::collections::{BTreeMap, BTreeSet};
 
 pub use emit::{emit_sql_with_ir, order_models_for_create, render_create_table, CreateTableEmission};
+pub use order::order_by_dependencies;
 pub use ferro_ddl_lowering::Dialect;
 
 /// Executable SQL plus non-fatal warnings from [`emit_sql_with_ir`].

ferro_orm-0.16.2/crates/ferro-migrate/src/order.rs

@@ -0,0 +1,56 @@
+//! Dependency ordering shared by every path that emits or reconciles tables.
+
+use std::collections::HashSet;
+
+/// Order `items` so every FK dependency of an item is emitted before it.
+///
+/// This is the single dependency-order primitive: both the CREATE TABLE
+/// emitter ([`crate::order_models_for_create`]) and the runtime's migrate
+/// reconcile loop funnel through it, so the semantics live in one place:
+///
+/// - A dependency on the item's **own** table (a self-referential FK) is not
+///   an ordering constraint — the inline `REFERENCES` resolves against the
+///   table its own `CREATE TABLE` statement is creating (#302).
+/// - A dependency on a table **outside** `items` (already live in the DB)
+///   does not constrain ordering.
+/// - Genuine cross-table cycles cannot be dependency-ordered; the remaining
+///   items are appended in input order. SQLite tolerates the resulting
+///   forward references; Postgres rejects them at CREATE time (#302
+///   follow-up: defer those FKs to post-create `ALTER TABLE ADD CONSTRAINT`).
+///
+/// Ordering is deterministic: input order is preserved except where a
+/// dependency forces an item later.
+pub fn order_by_dependencies<T>(
+    items: Vec<T>,
+    table_of: impl Fn(&T) -> String,
+    deps_of: impl Fn(&T) -> Vec<String>,
+) -> Vec<T> {
+    let mut remaining = items;
+    let mut ordered = Vec::with_capacity(remaining.len());
+    let mut created: HashSet<String> = HashSet::new();
+
+    while !remaining.is_empty() {
+        let available: HashSet<String> = remaining.iter().map(&table_of).collect();
+        let mut progress = false;
+        let mut index = 0;
+        while index < remaining.len() {
+            let table = table_of(&remaining[index]);
+            let satisfied = deps_of(&remaining[index])
+                .iter()
+                .all(|dep| dep == &table || created.contains(dep) || !available.contains(dep));
+            if satisfied {
+                let item = remaining.remove(index);
+                created.insert(table);
+                ordered.push(item);
+                progress = true;
+            } else {
+                index += 1;
+            }
+        }
+        if !progress {
+            ordered.append(&mut remaining);
+            break;
+        }
+    }
+    ordered
+}

{ferro_orm-0.16.1 → ferro_orm-0.16.2}/crates/ferro-migrate/src/tests.rs

@@ -1459,3 +1459,36 @@ fn emit_sql_with_ir_add_column_db_check_postgres_quoted_and_sqlite_warns() {
         lite.warnings
     );
 }
+
+#[test]
+fn order_models_for_create_self_fk_is_not_an_ordering_constraint() {
+    // #302: `znode` carries a self-referential FK; `areferrer` arrives first
+    // (mirroring the alphabetical incoming order) and requires `znode`. The
+    // self-loop is satisfied by the table's own CREATE, so it must not evict
+    // the component from the dependency order.
+    let znode = SchemaModel {
+        foreign_keys: vec![SchemaForeignKey {
+            column: "parent_id".to_string(),
+            to_table: "znode".to_string(),
+            to_column: "id".to_string(),
+            on_delete: None,
+            name: None,
+        }],
+        ..schema_model("znode", vec![col("id", "uuid", false)])
+    };
+    let areferrer = SchemaModel {
+        foreign_keys: vec![SchemaForeignKey {
+            column: "node_id".to_string(),
+            to_table: "znode".to_string(),
+            to_column: "id".to_string(),
+            on_delete: None,
+            name: None,
+        }],
+        ..schema_model("areferrer", vec![col("id", "uuid", false)])
+    };
+
+    let models = vec![&areferrer, &znode];
+    let ordered = order_models_for_create(&models);
+    let tables: Vec<&str> = ordered.iter().map(|m| m.table_name.as_str()).collect();
+    assert_eq!(tables, vec!["znode", "areferrer"]);
+}

ferro_orm-0.16.2/docs/solutions/issues/self-fk-evicts-component-from-create-order.md

@@ -0,0 +1,59 @@
+---
+title: Self-referential FK evicted its whole component from CREATE TABLE order
+type: issue
+tags: [rust, schema, migrations, gotcha, postgres]
+related_files:
+  - crates/ferro-migrate/src/order.rs
+  - crates/ferro-migrate/src/emit.rs
+  - src/schema.rs
+related_issues: [302]
+captured: 2026-07-15
+---
+
+# Self-referential FK evicted its whole component from CREATE TABLE order
+
+**Problem:** On a fresh Postgres schema, `auto_migrate` created a referrer
+table before its FK target whenever the target carried a self-referential FK —
+the inline `REFERENCES` failed with `relation "..." does not exist`.
+
+**Takeaway:** In a dependency sort, an edge to your own table is already
+satisfied by your own `CREATE TABLE`; treating it as a pending dependency makes
+the table permanently ineligible, stalls everything downstream of it, and drops
+the whole component into the cycle fallback (input/alphabetical order).
+
+## What happened
+
+Both ordering loops (`order_models_for_create` in `ferro-migrate` and
+`order_models_for_migration` in `src/schema.rs`) only scheduled a table once
+every `fk.to_table` was in the `created` set. A self-FK's target can never be
+in `created` before the table itself, so the self-FK table never became
+eligible, its dependents stalled behind it, and the no-progress fallback
+appended the remainder in incoming order. Any referrer sorting before its
+target then failed on Postgres. Existing schemas survived by alphabetical
+luck.
+
+Two things let the bug survive review:
+
+1. The ordering loop existed in **two hand-rolled copies** with the same flaw.
+   Both now delegate to one primitive:
+   `ferro_migrate::order_by_dependencies` (`crates/ferro-migrate/src/order.rs`),
+   where the self-edge rule lives exactly once.
+2. A doc comment claimed cycles were harmless because "Postgres `CREATE TABLE`
+   with a forward inline FK reference is the pre-existing behavior" — false.
+   Postgres rejects forward references at CREATE time; only SQLite tolerates
+   them. Don't trust ordering-doesn't-matter claims without a Postgres test.
+
+Genuine cross-table cycles (A→B→A) still fall through in input order and fail
+on Postgres — a real fix needs post-create `ALTER TABLE ADD CONSTRAINT`
+deferral (follow-up tracked from #302).
+
+## How to recognize
+
+- `relation "X" does not exist` during `auto_migrate` on a fresh Postgres
+  schema, where X *is* among the registered models.
+- The failure appears/disappears when a self-FK is added/removed anywhere in
+  the dependency component, or when table names are renamed across the
+  alphabetical boundary.
+- SQLite passes while Postgres fails: SQLite accepts forward FK references, so
+  ordering bugs are invisible there — regression tests for CREATE order must
+  run on the Postgres matrix.

{ferro_orm-0.16.1 → ferro_orm-0.16.2}/pyproject.toml

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