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

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

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

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

@@ -84,6 +84,10 @@ _Avoid_: Select list, projection spec, hydration mode flag
 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
@@ -100,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.2 → 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.2"
+version = "0.16.3"
 dependencies = [
  "chrono",
  "dashmap",
@@ -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",

{ferro_orm-0.16.2 → 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.2"
+version = "0.16.3"
 edition = "2024"
 readme = "README.md"
 

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

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

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

{ferro_orm-0.16.2 → 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.2 → 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.2 → 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

{ferro_orm-0.16.2 → ferro_orm-0.16.3}/src/ferro/ir/compiler.py

@@ -10,7 +10,6 @@ from __future__ import annotations
 from collections.abc import Sequence
 from typing import Any
 
-from .. import state as ferro_state
 from .._core import (
     _ddl_check_constraint_name,
     _ddl_composite_index_name,
@@ -19,14 +18,15 @@ from .._core import (
     _ddl_single_index_name,
     _ddl_single_unique_name,
 )
-from ..columns import ColumnSpec, build_column_specs, build_relation_specs
+from ..columns import (
+    ColumnSpec,
+    build_column_specs,
+    build_relation_specs,
+    primary_key_field_name,
+)
 from ..composite_indexes import drop_overlap_with_uniques, normalized_composite_indexes
 from ..composite_uniques import normalized_composite_uniques
-from ..state import (
-    _JOIN_TABLE_REGISTRY,
-    _MODEL_REGISTRY_PY,
-    _SCHEMA_IR_BY_MODEL,
-)
+from ..registry import REGISTRY, ir_fingerprint
 
 _IR_VERSION = 1
 
@@ -214,11 +214,11 @@ def compile_schema_ir_payload(
 def _persist_schema_ir_envelope(model_name: str, envelope: dict[str, Any]) -> None:
     """Store one model's compiled SchemaIR envelope and fingerprint.
 
-    Routes through the single ``ferro.state`` envelope-write entrypoint so every
-    per-model store mutation lives at the store-owning layer (#243); the
-    fingerprint is derived from the envelope inside that entrypoint.
+    Routes through the Registry's envelope-write entrypoint so every per-model
+    store mutation lives at the store-owning layer (#243); the fingerprint is
+    derived from the envelope inside that entrypoint.
     """
-    ferro_state.persist_model_envelope(model_name, envelope)
+    REGISTRY.persist_envelope(model_name, envelope)
 
 
 def _compile_and_persist_model_envelope(
@@ -300,6 +300,10 @@ def compile_model_schema_ir(
     """
     if specs is None:
         specs = build_column_specs(model_cls)
+    # Derive the PK fact (and run the at-most-one guard) before compile +
+    # persist: a multi-PK model raises here, at class definition time, and
+    # never persists an envelope or publishes specs.
+    pk_field = primary_key_field_name(model_name, specs)
     column_names = frozenset(specs)
     uniques = normalized_composite_uniques(model_cls, column_names)
     indexes = drop_overlap_with_uniques(
@@ -318,6 +322,9 @@ def compile_model_schema_ir(
     # "``__ferro_columns__`` can never go stale relative to the envelope"
     # invariant, made atomic.
     model_cls.__ferro_columns__ = specs
+    # Same choke point caches the PK fact: every ``__ferro_columns__`` refresh
+    # re-derives ``__ferro_pk__``, so it can never go stale relative to specs.
+    model_cls.__ferro_pk__ = pk_field
     # Same choke point compiles relation-traversal facts (#268): every
     # ``__ferro_columns__`` refresh (provisional class-body registration and
     # the resolved second pass) refreshes ``__ferro_relation_specs__`` too, so
@@ -329,12 +336,12 @@ def compile_model_schema_ir(
 def _model_payload_from_envelope(name: str) -> dict[str, Any]:
     """Return one model's SchemaIR payload object from the envelope cache.
 
-    The returned dict is a live reference into ``_SCHEMA_IR_BY_MODEL`` — the
-    assembled modelset shares these payload objects. Treat them as read-only;
-    in-place mutation corrupts the per-model cache and survives clean-path
-    re-assembles indefinitely (#245).
+    The returned dict is a live reference into the Registry's envelope cache —
+    the assembled modelset shares these payload objects. Treat them as
+    read-only; in-place mutation corrupts the per-model cache and survives
+    clean-path re-assembles indefinitely (#245).
     """
-    envelope = _SCHEMA_IR_BY_MODEL.get(name)
+    envelope = REGISTRY.envelope(name)
     if envelope is None:
         raise RuntimeError(
             f"Missing SchemaIR envelope for '{name}'. "
@@ -347,11 +354,11 @@ def _model_payload_from_envelope(name: str) -> dict[str, Any]:
 def _assemble_modelset_envelope() -> dict[str, Any]:
     """Stitch per-model envelopes into one sorted modelset envelope."""
     models: list[dict[str, Any]] = []
-    for model_name, _model_cls in sorted(_MODEL_REGISTRY_PY.items(), key=lambda item: item[0]):
+    for model_name in sorted(REGISTRY.models()):
         models.append(_model_payload_from_envelope(model_name))
 
     for table_name, bundle in sorted(
-        _JOIN_TABLE_REGISTRY.items(), key=lambda item: item[0]
+        REGISTRY.join_tables().items(), key=lambda item: item[0]
     ):
         if not isinstance(bundle, dict):
             continue
@@ -366,22 +373,10 @@ def _assemble_modelset_envelope() -> dict[str, Any]:
         },
     }
 
-    ferro_state._SCHEMA_IR_MODELSET = envelope
-    ferro_state._SCHEMA_IR_MODELSET_FINGERPRINT = ferro_state.ir_fingerprint(envelope)
+    REGISTRY.set_modelset(envelope)
     return envelope
 
 
-def _missing_registry_envelope_names() -> list[str]:
-    missing: list[str] = []
-    for name in _MODEL_REGISTRY_PY:
-        if name not in _SCHEMA_IR_BY_MODEL:
-            missing.append(name)
-    for table_name, bundle in _JOIN_TABLE_REGISTRY.items():
-        if isinstance(bundle, dict) and table_name not in _SCHEMA_IR_BY_MODEL:
-            missing.append(table_name)
-    return missing
-
-
 def _register_join_table_bundle(table_name: str, bundle: dict[str, Any]) -> None:
     register_model_with_ir(
         table_name,
@@ -393,12 +388,12 @@ def _register_join_table_bundle(table_name: str, bundle: dict[str, Any]) -> None
 
 
 def _recompile_missing_registry_envelopes() -> None:
-    for model_name in _missing_registry_envelope_names():
-        model_cls = _MODEL_REGISTRY_PY.get(model_name)
+    for model_name in REGISTRY.missing_envelope_names():
+        model_cls = REGISTRY.models().get(model_name)
         if model_cls is not None:
             compile_model_schema_ir(model_name, model_cls)
             continue
-        bundle = _JOIN_TABLE_REGISTRY.get(model_name)
+        bundle = REGISTRY.join_tables().get(model_name)
         if isinstance(bundle, dict):
             _register_join_table_bundle(model_name, bundle)
 
@@ -411,10 +406,10 @@ def _recompile_all_registered_envelopes() -> None:
     Alembic-adjacent tooling) historically relied on compile-not-assemble here.
     The connect/reconnect clean path never hits this (#245).
     """
-    for model_name, model_cls in sorted(_MODEL_REGISTRY_PY.items(), key=lambda item: item[0]):
+    for model_name, model_cls in sorted(REGISTRY.models().items()):
         compile_model_schema_ir(model_name, model_cls)
     for table_name, bundle in sorted(
-        _JOIN_TABLE_REGISTRY.items(), key=lambda item: item[0]
+        REGISTRY.join_tables().items(), key=lambda item: item[0]
     ):
         if isinstance(bundle, dict):
             _register_join_table_bundle(table_name, bundle)
@@ -423,8 +418,8 @@ def _recompile_all_registered_envelopes() -> None:
 def compile_registry_schema_ir() -> dict[str, Any]:
     """Assemble and persist a deterministic SchemaIR envelope for all models.
 
-    Stitches already-compiled per-model envelopes from ``_SCHEMA_IR_BY_MODEL``
-    for every entry in ``_MODEL_REGISTRY_PY`` and ``_JOIN_TABLE_REGISTRY``.
+    Stitches already-compiled per-model envelopes from the Registry's envelope
+    cache for every registered model and join table.
     On a dirty registry, recompiles envelopes first so direct callers that
     bypass ``resolve_relationships()`` still observe current registry state.
     After ``ensure_resolved_modelset()`` on the clean path, this is
@@ -433,7 +428,7 @@ def compile_registry_schema_ir() -> dict[str, Any]:
     Returns:
         The assembled model-set SchemaIR envelope, sorted by model name.
     """
-    if ferro_state.is_modelset_dirty():
+    if REGISTRY.is_dirty():
         _recompile_all_registered_envelopes()
     else:
         _recompile_missing_registry_envelopes()
@@ -442,4 +437,4 @@ def compile_registry_schema_ir() -> dict[str, Any]:
 
 def schema_ir_fingerprint(ir_envelope: dict[str, Any]) -> str:
     """Return a deterministic SHA-256 fingerprint for a SchemaIR envelope."""
-    return ferro_state.ir_fingerprint(ir_envelope)
+    return ir_fingerprint(ir_envelope)

{ferro_orm-0.16.2 → ferro_orm-0.16.3}/src/ferro/metaclass.py

@@ -23,8 +23,8 @@ from .base import FerroField, ForeignKey, ManyToManyRelation
 from .fields import FERRO_FIELD_EXTRA_KEY
 from .ir import compile_model_schema_ir
 from .query import Relation
+from .registry import REGISTRY
 from .relations.descriptors import ForwardDescriptor
-from .state import _MODEL_REGISTRY_PY, _PENDING_RELATIONS, register_model
 
 _TABLE_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*\Z")
 
@@ -79,7 +79,7 @@ class ModelMetaclass(type(BaseModel)):
         cls.__ferro_identity__ = f"{cls.__module__}.{cls.__qualname__}"
         cls.__ferro_table__ = mcs._resolve_table_name(name, namespace)
         for field_name, metadata in pending_relations:
-            _PENDING_RELATIONS.append((cls.__ferro_identity__, field_name, metadata))
+            REGISTRY.defer_relation(cls.__ferro_identity__, field_name, metadata)
 
         mcs._register_model(cls, cls.__ferro_identity__, local_relations)
         ferro_fields = mcs._parse_ferro_field_metadata(cls)
@@ -278,8 +278,9 @@ class ModelMetaclass(type(BaseModel)):
         Returns:
             (local_relations, fields_to_remove, pending_relations): Relationship
             metadata, fields to hide from Pydantic, and ``(field_name, metadata)``
-            entries deferred to ``_PENDING_RELATIONS`` (flushed under the model's
-            resolved ``__ferro_identity__`` after the class object exists).
+            entries deferred to the Registry's pending-relation queue (flushed
+            under the model's resolved ``__ferro_identity__`` after the class
+            object exists).
         """
         local_relations = {}
         fields_to_remove = []
@@ -405,7 +406,7 @@ class ModelMetaclass(type(BaseModel)):
                 qualified identity is idempotent.
         """
         table_name = cls.__ferro_table__
-        for key, other in _MODEL_REGISTRY_PY.items():
+        for key, other in REGISTRY.models().items():
             if key == identity:
                 continue
             if getattr(other, "__ferro_table__", None) == table_name:
@@ -415,7 +416,7 @@ class ModelMetaclass(type(BaseModel)):
                     "models cannot share a table. Set __ferro_table__ on one of "
                     "them to give it a distinct table name."
                 )
-        register_model(cls)
+        REGISTRY.register(cls)
         cls.ferro_relations = local_relations
 
     @staticmethod

{ferro_orm-0.16.2 → ferro_orm-0.16.3}/src/ferro/models.py

@@ -126,9 +126,9 @@ def evict_instance(
     directly with their already-resolved route instead of going through this
     wrapper, so a route is never resolved twice for one operation.
     """
-    from .state import resolve_model_reference
+    from .registry import REGISTRY
 
-    model_cls = resolve_model_reference(model) if isinstance(model, str) else model
+    model_cls = REGISTRY.resolve_reference(model) if isinstance(model, str) else model
     route = resolve_operation_scope(using=using, session=session)
     _core_evict_instance(model_cls.__ferro_identity__, pk, route)
 
@@ -211,6 +211,9 @@ class Model(BaseModel, metaclass=ModelMetaclass):
     __ferro_composite_uniques__: ClassVar[tuple[tuple[str, ...], ...]] = ()
     __ferro_composite_indexes__: ClassVar[tuple[tuple[str, ...], ...]] = ()
     __ferro_columns__: ClassVar[dict[str, "ColumnSpec"]] = {}
+    #: The single PK field name, derived once at the compile choke point
+    #: alongside ``__ferro_columns__``; ``None`` for a PK-less model.
+    __ferro_pk__: ClassVar[str | None] = None
     __ferro_relation_specs__: ClassVar[dict[str, "RelationSpec"]] = {}
     _enum_fields: ClassVar[dict[str, type[Enum]]] = {}
 
@@ -247,9 +250,17 @@ class Model(BaseModel, metaclass=ModelMetaclass):
                 if isinstance(val, Model):
                     # Read the *target* model's PK (FF-D D5) — the source
                     # model's PK name is irrelevant to the related instance.
-                    pk_field = val.__class__._primary_key_field_name() or "id"
-                    id_val = getattr(val, pk_field, None)
-                    data[f"{field_name}_id"] = id_val
+                    pk_field = val.__class__.__ferro_pk__
+                    if pk_field is None:
+                        raise ValueError(
+                            f"Cannot assign a {val.__class__.__name__} instance "
+                            f"to relationship field {field_name!r}: "
+                            f"{val.__class__.__name__} declares no primary-key "
+                            "column, so there is no value to store in "
+                            f"{field_name!r}_id. Pass the scalar value directly "
+                            "or declare a primary_key=True column."
+                        )
+                    data[f"{field_name}_id"] = getattr(val, pk_field, None)
                 else:
                     # It's already an ID or something else
                     data[f"{field_name}_id"] = val
@@ -323,7 +334,7 @@ class Model(BaseModel, metaclass=ModelMetaclass):
                 mode="upsert",
             )
         elif _is_persisted(self):
-            pk_field_name = self.__class__._primary_key_field_name()
+            pk_field_name = self.__class__.__ferro_pk__
             pk_val = getattr(self, pk_field_name) if pk_field_name is not None else None
             if pk_val is None:
                 raise ValueError(
@@ -346,16 +357,17 @@ class Model(BaseModel, metaclass=ModelMetaclass):
             )
 
         pk_val = None
-        pk_field_name = None
-
-        for field_name, spec in self.__class__.__ferro_columns__.items():
-            if not spec.primary_key:
-                continue
-            pk_field_name = field_name
-            if spec.autoincrement and getattr(self, field_name) is None and new_id is not None:
-                setattr(self, field_name, new_id)
-            pk_val = getattr(self, field_name)
-            break
+        pk_field_name = self.__class__.__ferro_pk__
+
+        if pk_field_name is not None:
+            spec = self.__class__.__ferro_columns__[pk_field_name]
+            if (
+                spec.autoincrement
+                and getattr(self, pk_field_name) is None
+                and new_id is not None
+            ):
+                setattr(self, pk_field_name, new_id)
+            pk_val = getattr(self, pk_field_name)
 
         if pk_val is not None:
             register_instance(
@@ -380,7 +392,7 @@ class Model(BaseModel, metaclass=ModelMetaclass):
             >>> if user:
             ...     await user.delete()
         """
-        pk_field_name = self.__class__._primary_key_field_name()
+        pk_field_name = self.__class__.__ferro_pk__
         pk_val = getattr(self, pk_field_name) if pk_field_name is not None else None
         route, _identity_using = await _instance_transaction_route(self, using, session)
 
@@ -394,13 +406,6 @@ class Model(BaseModel, metaclass=ModelMetaclass):
             # The instance is transient again: a later save() re-INSERTs.
             _set_persisted(self, False)
 
-    @classmethod
-    def _primary_key_field_name(cls) -> str | None:
-        for field_name, spec in cls.__ferro_columns__.items():
-            if spec.primary_key:
-                return field_name
-        return None
-
     @classmethod
     async def all(
         cls, *, using: str | None = None, session: "Session | None" = None
@@ -454,7 +459,7 @@ class Model(BaseModel, metaclass=ModelMetaclass):
         Returns:
             The matching model instance, or None when no record exists.
         """
-        pk_field_name = cls._primary_key_field_name()
+        pk_field_name = cls.__ferro_pk__
         if pk_field_name is None:
             raise RuntimeError(f"Model {cls.__name__} does not define a primary key")
 
@@ -475,7 +480,7 @@ class Model(BaseModel, metaclass=ModelMetaclass):
             >>> user = await User.get(1)
             >>> await user.refresh()
         """
-        pk_field_name = self.__class__._primary_key_field_name()
+        pk_field_name = self.__class__.__ferro_pk__
         pk_val = getattr(self, pk_field_name) if pk_field_name is not None else None
 
         if pk_val is None:
@@ -772,7 +777,7 @@ class ModelConnection[M: Model]:
         return instance
 
     async def get_or_none(self, pk: Any) -> M | None:
-        pk_field_name = self.model_cls._primary_key_field_name()
+        pk_field_name = self.model_cls.__ferro_pk__
         if pk_field_name is None:
             raise RuntimeError(
                 f"Model {self.model_cls.__name__} does not define a primary key"