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

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

@@ -1,6 +1,36 @@
 # CHANGELOG
 
 
+## v0.16.3 (2026-07-16)
+
+### Bug Fixes
+
+- Derive the primary-key fact once and reject multi-PK models at class definition
+  ([`ef91fa0`](https://github.com/syn54x/ferro-orm/commit/ef91fa09e09d5e7444e8d659b831921d40bcb365))
+
+### Refactoring
+
+- Compile_query returns one CompiledQuery artifact carrying the hop-class map
+  ([`fc7084c`](https://github.com/syn54x/ferro-orm/commit/fc7084c4ad89b135815f74852263989f23868143))
+
+- Single Registry owner for Python-side registration state
+  ([`1179fcc`](https://github.com/syn54x/ferro-orm/commit/1179fcc07cc9e4305b7e7a8c141b8b29264dcd26))
+
+
+## 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.3}/CONTEXT.md

@@ -80,6 +80,18 @@ _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
+
+**Compiled query**:
+The single artifact `compile_query` returns: the QueryIR payload, its wire JSON, and the plan-scoped hop-class map, all views of one compile. The map is collected from the hop facts the payload itself carries, so wire and hop classes can never disagree; it is `None` unless the materialization plan decodes or hydrates through a hop model's class (mirroring the Rust `needs_hop_classes` guard — a both-sides double-check). No other code assembles hop classes for the FFI.
+_Avoid_: payload + kwargs, hop-class side-channel, wire tuple
+
+**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
@@ -92,6 +104,14 @@ _Avoid_: Nested select, join column, related-field pull
 A user-chosen name for one field of a projected record, given as the key in a dict-returning selector (`select(lambda t: {"account_name": t.account.name})`). Aliases name output fields only — never joins or tables; the relation path remains the sole join identity.
 _Avoid_: Column alias, AS label, join alias
 
+**Primary key fact**:
+The single cached answer to "which column is this model's primary key" — derived once at the compile choke point alongside column specs, stored as `__ferro_pk__` (`None` for a PK-less model). At most one `primary_key=True` column may be declared; a violation raises at class definition time. Operations that need a PK read the cached fact and raise clearly when it is `None` — never guess.
+_Avoid_: PK lookup, PK scan, first primary-key column
+
+**Registry**:
+The single owner of Python-side registration state (`ferro.registry.REGISTRY`): model classes, per-model SchemaIR envelopes + fingerprints, join-table bundles, pending relations, the modelset artifact, and the generation counters. Its stores are private; the agreement invariants (fingerprint pairs its envelope, join-table eviction clears envelopes, one-call test reset) live inside the interface, not in caller convention. Routing/session state is not the Registry — that is `ferro.state`.
+_Avoid_: state module, global dicts, model cache
+
 **Provisional registration**:
 The per-model state installed when a class body finishes executing — enough for runtime codec and PK metadata, but relationships may still be pending and the modelset is not yet authoritative for DDL.
 _Avoid_: Import-time registration, partial registry

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

@@ -59,9 +59,9 @@ dependencies = [
 
 [[package]]
 name = "bitflags"
-version = "2.13.0"
+version = "2.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
 dependencies = [
  "serde_core",
 ]
@@ -327,7 +327,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.16.1"
+version = "0.16.3"
 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",
@@ -1905,9 +1905,9 @@ checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
 [[package]]
 name = "uuid"
-version = "1.23.5"
+version = "1.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ea5fab0d6c3c01ae70085a09cb03d4c7a1d6314e2b3e075392783396d724ca0a"
+checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
 dependencies = [
  "getrandom 0.4.3",
  "js-sys",
@@ -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.3}/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.3"
 edition = "2024"
 readme = "README.md"
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.16.1
+Version: 0.16.3
 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.3}/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.3}/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.3/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.3}/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.3/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.3}/pyproject.toml

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

{ferro_orm-0.16.1 → ferro_orm-0.16.3}/src/ferro/__init__.py

@@ -73,13 +73,13 @@ async def _ensure_rust_registration_synced_for_operation() -> None:
     contention the event loop blocks for one resolve+install per generation; do
     not offload this to a thread pool — that would reintroduce interleaving.
     """
-    from .state import is_modelset_dirty
+    from .registry import REGISTRY
 
-    if not is_modelset_dirty():
+    if not REGISTRY.is_dirty():
         return
 
     with _OPERATION_REGISTRATION_SYNC_LOCK:
-        if is_modelset_dirty():
+        if REGISTRY.is_dirty():
             _ensure_rust_registration_synced()
 
 
@@ -97,25 +97,26 @@ def ensure_resolved_modelset() -> dict[str, Any]:
     path.
     """
     from .ir.compiler import compile_registry_schema_ir
+    from .registry import REGISTRY
     from .relations import resolve_relationships
-    from .state import is_modelset_dirty
 
-    if not is_modelset_dirty():
+    if not REGISTRY.is_dirty():
         return compile_registry_schema_ir()
 
     with _RESOLVED_MODELSET_LOCK:
-        if is_modelset_dirty():
+        if REGISTRY.is_dirty():
             resolve_relationships()
         return compile_registry_schema_ir()
 
 
 def _ensure_rust_registration_synced() -> None:
     """Resolve the modelset if needed, then push it to the Rust runtime."""
-    from . import state as ferro_state
+    from .registry import REGISTRY
 
     envelope = ensure_resolved_modelset()
+    cached = REGISTRY.modelset()
     _push_registration_to_rust(
-        envelope, fingerprint=ferro_state._SCHEMA_IR_MODELSET_FINGERPRINT
+        envelope, fingerprint=cached[1] if cached is not None else None
     )
 
 
@@ -131,24 +132,21 @@ def clear_registry() -> None:
     tolerated by SQLite but rejected by Postgres (``relation ... does not
     exist``). (#153)
 
-    The Python model registry (``_MODEL_REGISTRY_PY``) is intentionally **not**
-    cleared here: clearing the Rust registry while keeping the declared Python
-    models is what allows cold re-hydration after ``reset_engine`` (see
-    ``tests/test_enum_cold_hydration.py``). Callers that want a full Python-side
-    reset clear ``_MODEL_REGISTRY_PY`` / ``_PENDING_RELATIONS`` themselves.
-
-    Each purged join table's compiled SchemaIR envelope is also evicted from the
-    per-model envelope cache (via ``evict_model_envelope`` — envelope-only, so the
-    model registry stays intact per the promise above), keeping the two stores the
-    #153 guard depends on in agreement: a lingering join envelope would let a
-    future assemble step resurrect the stale join table.
+    The Python model registry is intentionally **not** cleared here: clearing
+    the Rust registry while keeping the declared Python models is what allows
+    cold re-hydration after ``reset_engine`` (see
+    ``tests/test_enum_cold_hydration.py``). Callers that want a full
+    Python-side reset use ``REGISTRY.reset_for_test()``.
+
+    Each purged join table's compiled SchemaIR envelope is evicted with it —
+    ``Registry.clear_join_tables`` owns that agreement (#153): a lingering
+    join envelope would let a future assemble step resurrect the stale join
+    table.
     """
     _core_clear_registry()
-    from .state import _JOIN_TABLE_REGISTRY, evict_model_envelope
+    from .registry import REGISTRY
 
-    for join_table in list(_JOIN_TABLE_REGISTRY):
-        evict_model_envelope(join_table)
-    _JOIN_TABLE_REGISTRY.clear()
+    REGISTRY.clear_join_tables()
 
 
 def _push_registration_to_rust(
@@ -172,18 +170,15 @@ def _push_registration_to_rust(
     """
     import json as _json
 
-    from . import state as ferro_state
     from .ir.compiler import compile_registry_schema_ir, schema_ir_fingerprint
+    from .registry import REGISTRY
 
     if envelope is None:
         envelope = compile_registry_schema_ir()
     if fingerprint is None:
-        cached = ferro_state._SCHEMA_IR_MODELSET
-        if (
-            cached is envelope
-            and ferro_state._SCHEMA_IR_MODELSET_FINGERPRINT is not None
-        ):
-            fingerprint = ferro_state._SCHEMA_IR_MODELSET_FINGERPRINT
+        cached = REGISTRY.modelset()
+        if cached is not None and cached[0] is envelope:
+            fingerprint = cached[1]
         else:
             fingerprint = schema_ir_fingerprint(envelope)
     _install_registration(_json.dumps(envelope), fingerprint)

{ferro_orm-0.16.1 → ferro_orm-0.16.3}/src/ferro/_shadow_fk_types.py

@@ -27,13 +27,12 @@ def _scalar_part_of_annotation(ann: Any) -> Any:
 
 def pk_python_type_for_model(target: type[Any]) -> Any | None:
     """Return the PK column's scalar python type from the target's specs."""
-    specs = getattr(target, "__ferro_columns__", None)
-    if not specs:
+    pk_field = getattr(target, "__ferro_pk__", None)
+    if pk_field is None:
         return None
-    for spec in specs.values():
-        if spec.primary_key:
-            return spec.python_type
-    return None
+    specs = getattr(target, "__ferro_columns__", None) or {}
+    spec = specs.get(pk_field)
+    return spec.python_type if spec is not None else None
 
 
 def shadow_annotation_for_pk(pk_ann: Any) -> Any:

{ferro_orm-0.16.1 → ferro_orm-0.16.3}/src/ferro/columns.py

@@ -31,9 +31,37 @@ __all__ = [
     "build_relation_specs",
     "fk_shadow_spec",
     "pk_spec",
+    "primary_key_field_name",
 ]
 
 
+def primary_key_field_name(model_name: str, specs: dict[str, ColumnSpec]) -> str | None:
+    """Derive the model's single PK field name from its column specs.
+
+    The one derivation site for "which column is the primary key" — cached on
+    the class as ``__ferro_pk__`` at the compile choke point, so every
+    consumer (save, descriptors, shadow-FK typing, traversal) reads the cached
+    fact instead of re-looping specs. At most one ``primary_key=True`` column
+    is legal; zero is a valid declaration (``None``) and the operations that
+    need a PK raise their own errors.
+
+    Raises:
+        TypeError: If more than one column declares ``primary_key=True`` —
+            at class definition time, naming the model and offending fields,
+            rather than resolving the ambiguity silently by declaration order
+            (the follow-up ADR-0002 asked for). ``TypeError`` is the
+            declaration-error contract the metaclass surfaces unwrapped
+            (ADR-0003's db_type validation sets the precedent).
+    """
+    pks = [name for name, spec in specs.items() if spec.primary_key]
+    if len(pks) > 1:
+        raise TypeError(
+            f"Model {model_name!r} declares multiple primary-key columns: "
+            f"{sorted(pks)!r}. At most one primary_key=True column is supported."
+        )
+    return pks[0] if pks else None
+
+
 @dataclass(frozen=True, slots=True)
 class ForeignKeyRef:
     to_table: str
@@ -126,13 +154,13 @@ def _property_is_integer(prop: dict[str, Any]) -> bool:
 
 
 def _target_table_name(target: Any) -> str:
-    from .state import resolve_model_reference
+    from .registry import REGISTRY
 
     if isinstance(target, ForwardRef):
         target = target.__forward_arg__
     if isinstance(target, str):
         try:
-            model = resolve_model_reference(target, default=None)
+            model = REGISTRY.resolve_reference(target, default=None)
         except RuntimeError:
             # Ambiguous short ref during first-pass schema build: defer the
             # loud, candidate-listing error to resolve_relationships (the