loom-kernel 2.12.0__tar.gz → 2.14.0__tar.gz

{loom_kernel-2.12.0 → loom_kernel-2.14.0}/CHANGELOG.md

@@ -4,6 +4,61 @@
 
 ### core
 
+- **core:** range-partitioned row-scoped tables.
+  `__partition_by__ = ("RANGE", "<column>")` on a `RowScoped` model compiles to
+  `postgresql_partition_by`; the column must be a `DateTime` column of the
+  primary key and every unique key must contain it, LIST and HASH are refused,
+  all at compile time. Partitions are created ahead of time by the migrator
+  through guard revision 2 (`0002.sql`, new functions `create_range_partition`
+  and `detach_partition`, `EXECUTE` for the owner only), which creates,
+  registers and protects each partition with its parent's scopes in the
+  caller's transaction: `op.ensure_range_partitions(table, start, end,
+  interval=...)` in a revision, or
+  `loom.core.repository.sqlalchemy.rls.ensure_range_partitions(url_or_connection,
+  application, model, start, end, interval=...)` at runtime. Partitions are
+  named `<table>_p<YYYYMM>` (`_p<YYYY>`, `_p<YYYYMMDD>` for year and day) with
+  midnight-UTC bounds. Retention uses `op.detach_range_partitions(...,
+  drop=...)` or `detach_range_partitions(...)`, which unprotects, detaches and
+  optionally drops. Dropping a partitioned table in an autogenerated revision
+  drops its partitions first (`op.drop_partitions`). `check` and `verify` count
+  registered partitions with their parent; `verify` reports
+  `partition.registration` for a partition registered unlike its parent.
+  Re-apply the bootstrap to install revision 2; partition calls on an older
+  guard raise `guard revision pending`. `ScopedTable` gains `partition_by`, and
+  `require_guard_revision(_sync)` take an optional `minimum`.
+- **core:** a model declares named checks and partial unique indexes.
+  `__checks__ = {rule: sql_expression}` compiles one `CHECK` constraint per
+  rule, named by the rule; `__partial_unique__ = {rule: (columns, where)}`
+  compiles a unique index `uq_<table>_<rule>` restricted to the rows matching
+  `where`, and on a row-scoped table its columns must contain the boundary
+  (C5, refused at compile time as the guard refuses it with `LG002`). The
+  expression and the predicate are product code with the trust of a
+  hand-written Alembic revision and must be static literals with no runtime
+  input; loom checks only that each is a non-empty string. The static-SQL lint
+  exempts exactly the two calls that compile them and now also watches
+  `CheckConstraint`. Alembic's autogenerate does not compare checks or index
+  predicates, so adding, changing or removing a check on an existing table,
+  or changing a predicate, is a hand-written revision.
+- **core:** `database.schema.naming_convention` hands a SQLAlchemy
+  `naming_convention` (`pk`, `fk`, `uq`, `ck`, `ix`) to the application
+  metadata of the migration path and to the metadata the REST runtime and the
+  Celery worker compile, so all of them name constraints alike; absent,
+  nothing changes. Use
+  `fk_%(table_name)s_%(column_0_N_name)s`: every composite FK of a scoped
+  table starts with the boundary column. Compilation now refuses two
+  constraints or indexes of one table resolving to the same name, and a
+  check, `__indexes__` or `__partial_unique__` name over Postgres's 63 bytes,
+  instead of failing or truncating at DDL time. `reset_registry` takes the
+  convention as `naming_convention=`; called without it, it leaves the
+  convention as it is, and `None` restores SQLAlchemy's default.
+
+- **core:** two column types. `Bytes` (`loom.core.model.Bytes`, also inferred
+  from a `bytes` annotation, which used to fall back to `JSON`) compiles to
+  `LargeBinary`, `bytea` on Postgres; `Postgres.INET` compiles to Postgres
+  `inet`. The SQLAlchemy repository binds `bytes` as they are instead of
+  base64 text, and a network address the driver returns for `inet` reaches a
+  `str` field as its text form (`10.0.0.1`, `2001:db8::1/64`).
+
 - **core:** a memory cache alias can be bounded. `cache: max_size` (entries) and
   the new `cache: max_bytes` (stored payload bytes) serve every
   `aiocache.SimpleMemoryCache` alias through `loom.core.cache.memory.BoundedMemoryCache`,
@@ -85,12 +140,25 @@
 
 ### rest
 
+- **rest:** a single `RuleViolation(field, message)` now answers its `field`.
+  `HttpErrorMapper` dropped it, so two `rule_violation` 422s could only be
+  told apart by their message text. The body adds `field` (`ErrorField.FIELD`,
+  the key each `violations` item of `RuleViolations` already carries) next to
+  the unchanged `code`, `message` and `trace_id`; the status stays `422`. This
+  includes the SQL endpoint's 422s, whose `field` is `sql` or `body`. Every
+  other error body is unchanged.
 - **rest:** a strict `pydantic.BaseModel` result, a `list` of them or an
   envelope holding one now renders directly on a REST route, through
   `MsgspecJSONResponse`'s `enc_hook`, and documents in OpenAPI
   (`_safe_pydantic_schema`) through the same `LoomType` the cache and MCP
   boundaries already use; `LoomRestAdapter`'s Struct projection goes
   through it too.
+- **rest:** `create_app` accepts `modules: Sequence[Callable[[LoomContainer], None]]`,
+  mirroring the Celery `create_app`. Each module is called with the container,
+  in order, before repositories are registered and before use cases are
+  verified, so a use case can inject a port no repository provides (a clock,
+  an identity verifier, a bridge to another bounded context). Without the
+  module, startup still fails with the same `ResolutionError`.
 
 ### prefect
 
@@ -231,6 +299,15 @@
 
 ### core
 
+- **core:** the RLS guard refuses, in the same statement, a drop outside the
+  hatch that breaks its invariants. `DROP POLICY` or `DROP TRIGGER
+  loom_deny_owner_dml` on a scoped table used to commit, because drops are not
+  reported to `ddl_command_end`; the schema then failed the assertion (`LG002`)
+  only at the next DDL. The `sql_drop` trigger now runs the assertion when the
+  drop removes an object of the application schema and the hatch is closed;
+  dropping a plain index still succeeds. Shipped in guard revision 2
+  (`0002.sql`, `CREATE OR REPLACE FUNCTION on_sql_drop`); re-apply the
+  bootstrap to install it.
 - **core:** a model with a relation or projection field imports again on
   Python 3.12.4 and later when its module uses
   `from __future__ import annotations`. It failed with
@@ -293,6 +370,19 @@
   capability does not recover yet; see "A session that died after it opened is
   replaced by the next call" in `docs/ai/mcp.md`.
 
+### rest
+
+- **rest:** an authenticator can report an outage instead of answering `500`.
+  An exception raised inside `AuthenticationMiddleware` never reached
+  Starlette's exception handlers, so a custom authenticator whose identity
+  provider was unreachable answered a bare `500`. An authenticator now raises
+  `loom.rest.auth.AuthenticationUnavailable` and the request answers `503`
+  with the standard error body (`code: service_unavailable`, a fixed message,
+  `trace_id`) and no `WWW-Authenticate` challenge; the exception's message
+  and cause are logged at `WARNING`, never sent. `ErrorCode` gains
+  `SERVICE_UNAVAILABLE`, which `HttpErrorMapper` maps to `503`. Any other
+  exception from the authenticator, and the `401` refusal, are unchanged.
+
 ## ♻️ Refactor
 
 ### etl

{loom_kernel-2.12.0 → loom_kernel-2.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.12.0
+Version: 2.14.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-2.12.0 → loom_kernel-2.14.0}/src/loom/celery/bootstrap.py

@@ -118,6 +118,16 @@ _T = TypeVar("_T")
 # ---------------------------------------------------------------------------
 
 
+class _WorkerSchemaConfig(msgspec.Struct, kw_only=True):
+    """The part of ``database.schema`` the worker compiles models with.
+
+    Attributes:
+        naming_convention: SQLAlchemy naming convention keyed by constraint kind.
+    """
+
+    naming_convention: dict[str, str] | None = None
+
+
 class _WorkerDbConfig(msgspec.Struct, kw_only=True):
     """Database settings for the worker process.
 
@@ -125,11 +135,13 @@ class _WorkerDbConfig(msgspec.Struct, kw_only=True):
         url: Async SQLAlchemy connection URL.
         echo: Log all SQL statements when ``True``.
         pool_pre_ping: Test connections before checkout.
+        schema: Schema settings the models are compiled with.
     """
 
     url: str
     echo: bool = False
     pool_pre_ping: bool = True
+    schema: _WorkerSchemaConfig = msgspec.field(default_factory=_WorkerSchemaConfig)
 
 
 class _DiscoveryModules(msgspec.Struct, kw_only=True):
@@ -621,16 +633,28 @@ def _register_repositories(
     return build_sqlalchemy_repository_registration_module(session_manager, models)
 
 
-def _compile_models(models: Sequence[type[BaseModel]]) -> tuple[type[BaseModel], ...]:
+def _worker_naming_convention(ctx: ConfigContext) -> Mapping[str, str] | None:
+    """The ``database.schema.naming_convention`` the REST runtime and migrations also read."""
+    db_cfg = ctx.section(ConfigKey.DATABASE, _WorkerDbConfig)
+    return db_cfg.schema.naming_convention
+
+
+def _compile_models(
+    models: Sequence[type[BaseModel]], *, naming_convention: Mapping[str, str] | None
+) -> tuple[type[BaseModel], ...]:
     """Compile and normalize discovered models for SQLAlchemy repositories."""
     if not models:
         return ()
     try:
-        from loom.core.backend.sqlalchemy import compile_all, reset_registry
+        from loom.core.backend.sqlalchemy import (
+            compile_all,
+            configured_naming_convention,
+            reset_registry,
+        )
     except ImportError as exc:
         raise _sqlalchemy_extra_error() from exc
     ordered = tuple(dict.fromkeys(models))
-    reset_registry()
+    reset_registry(naming_convention=configured_naming_convention(naming_convention))
     compile_all(*ordered)
     return ordered
 
@@ -656,6 +680,8 @@ def _compile_db_layer(
     session_manager: SessionManager | None,
     models: Sequence[type[BaseModel]],
     user_modules: Sequence[Callable[[LoomContainer], None]],
+    *,
+    naming_convention: Mapping[str, str] | None,
 ) -> tuple[tuple[type[BaseModel], ...], tuple[Callable[[LoomContainer], None], ...]]:
     """Compile models and register repositories; no-op when DB is not configured.
 
@@ -663,6 +689,7 @@ def _compile_db_layer(
         session_manager: Active session manager, or ``None`` for pure jobs.
         models: Model classes discovered or declared for this worker.
         user_modules: Container modules provided by the caller.
+        naming_convention: The configured ``database.schema.naming_convention``.
 
     Returns:
         Tuple of (normalized_models, runtime_modules).  When no DB is
@@ -671,7 +698,7 @@ def _compile_db_layer(
     base = tuple(user_modules)
     if session_manager is None:
         return tuple(models), base
-    normalized = _compile_models(models)
+    normalized = _compile_models(models, naming_convention=naming_convention)
     if not normalized:
         return tuple(models), base
     return normalized, (*base, _register_repositories(session_manager, normalized))
@@ -904,7 +931,10 @@ def bootstrap_worker(
         _apply_job_config_if_present(ctx, job_type)
 
     uow_factory, session_manager = _resolve_uow_factory(ctx)
-    final_models, runtime_modules = _compile_db_layer(session_manager, resolved.models, modules)
+    convention = _worker_naming_convention(ctx) if session_manager is not None else None
+    final_models, runtime_modules = _compile_db_layer(
+        session_manager, resolved.models, modules, naming_convention=convention
+    )
     runtime_modules = (*runtime_modules, cache_module_for(ctx))
 
     resolved = _WorkerResolved(

{loom_kernel-2.12.0 → loom_kernel-2.14.0}/src/loom/core/backend/scoped_ddl.py

@@ -11,13 +11,14 @@ from __future__ import annotations
 
 import json
 import re
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Iterable, Iterator, Mapping
 from typing import Any, Final, get_args
 
 from sqlalchemy import Connection, Table, event, text
 
 from loom.core.config import ConfigError
 from loom.core.model.field import Reach
+from loom.core.model.partition import PartitionRange
 from loom.core.model.privilege import Privilege
 from loom.core.model.scoped import ScopedTable
 from loom.core.schema_names import schema_identifier, sql_identifier
@@ -42,6 +43,21 @@ GRANT_TABLE: Final = (
     "CAST(:readers AS text[]), CAST(:writers AS text[]))"
 )
 ASSERT_SCHEMA: Final = "SELECT assert_scoped_schema()"
+CREATE_RANGE_PARTITION: Final = (
+    "SELECT create_range_partition("
+    "to_regclass(quote_ident(:schema) || '.' || quote_ident(:table)), "
+    "CAST(:partition AS text), CAST(:lower AS text), CAST(:upper AS text))"
+)
+DETACH_PARTITION: Final = (
+    "SELECT detach_partition(to_regclass(quote_ident(:schema) || '.' || quote_ident(:table)), "
+    "CAST(:partition AS text), CAST(:drop AS boolean))"
+)
+PARTITIONS: Final = (
+    "SELECT c.relname FROM pg_inherits i JOIN pg_class c ON c.oid = i.inhrelid "
+    "WHERE i.inhparent = to_regclass(quote_ident(:schema) || '.' || quote_ident(:table)) "
+    "ORDER BY c.relname"
+)
+LANDING: Final = "SELECT current_user, current_schema()"
 GUARD_FIRST: Final = (
     "SELECT set_config('search_path', quote_ident(:guard) || ', pg_catalog, pg_temp', true)"
 )
@@ -62,6 +78,7 @@ MISSING_EVENT_TRIGGERS: Final = (
 
 Parameters = dict[str, Any]
 GuardCall = Callable[[Connection, Parameters], None]
+PartitionCall = tuple[str, Parameters]
 _OPEN_HATCH: Final = text(OPEN_HATCH)
 _PROTECT: Final = text(PROTECT)
 _GRANT_TABLE: Final = text(GRANT_TABLE)
@@ -108,6 +125,45 @@ def grant_parameters(
     }
 
 
+def create_partition_parameters(schema: str, table: str, partition: PartitionRange) -> Parameters:
+    """Bound parameters of :data:`CREATE_RANGE_PARTITION` for one partition of ``schema.table``."""
+    return {
+        **table_parameters(schema, table),
+        "partition": sql_identifier(partition.name),
+        "lower": partition.lower,
+        "upper": partition.upper,
+    }
+
+
+def detach_partition_parameters(
+    schema: str, table: str, partition: str, *, drop: bool
+) -> Parameters:
+    """Bound parameters of :data:`DETACH_PARTITION` for one partition of ``schema.table``."""
+    return {**table_parameters(schema, table), "partition": sql_identifier(partition), "drop": drop}
+
+
+def create_partition_calls(
+    schema: str, table: str, partitions: Iterable[PartitionRange]
+) -> Iterator[PartitionCall]:
+    """Each partition's name and the parameters of :data:`CREATE_RANGE_PARTITION`, in order.
+
+    The guard answers each call with whether it created the partition.
+    """
+    for partition in partitions:
+        yield partition.name, create_partition_parameters(schema, table, partition)
+
+
+def detach_partition_calls(
+    schema: str, table: str, names: Iterable[str], *, drop: bool
+) -> Iterator[PartitionCall]:
+    """Each name and the parameters of :data:`DETACH_PARTITION`, in order.
+
+    The guard answers each call with whether the partition existed.
+    """
+    for name in names:
+        yield name, detach_partition_parameters(schema, table, name, drop=drop)
+
+
 def table_parameters(schema: str, table: str) -> Parameters:
     """The validated schema and table a guard call resolves inside Postgres."""
     return {"schema": schema_identifier(schema), "table": sql_identifier(table)}

{loom_kernel-2.12.0 → loom_kernel-2.14.0}/src/loom/core/backend/sqlalchemy.py

@@ -1,21 +1,26 @@
 from __future__ import annotations
 
 import functools
+from collections import deque
 from collections.abc import Mapping
 from dataclasses import dataclass, field
-from typing import Any
+from enum import Enum
+from typing import Any, Final
 
 import msgspec
 from sqlalchemy import (
     JSON,
     BigInteger,
     Boolean,
+    CheckConstraint,
+    Constraint,
     DateTime,
     Float,
     ForeignKey,
     ForeignKeyConstraint,
     Index,
     Integer,
+    LargeBinary,
     MetaData,
     Numeric,
     String,
@@ -23,21 +28,30 @@ from sqlalchemy import (
     Text,
     UniqueConstraint,
     func,
+    text,
 )
 from sqlalchemy.dialects.postgresql import ARRAY as PG_ARRAY
+from sqlalchemy.dialects.postgresql import INET as PG_INET
 from sqlalchemy.dialects.postgresql import JSONB as PG_JSONB
 from sqlalchemy.dialects.postgresql import TSVECTOR as PG_TSVECTOR
 from sqlalchemy.dialects.postgresql import UUID as PG_UUID
 from sqlalchemy.orm import DeclarativeBase, mapped_column, relationship
 from sqlalchemy.orm import registry as sa_registry
+from sqlalchemy.sql.naming import conv
+from sqlalchemy.sql.schema import DEFAULT_NAMING_CONVENTION
 
 from loom.core.backend.core_model import CoreModel, CoreProfilePlan, CoreRelationStep
 from loom.core.backend.scoped_ddl import SCHEMA_KEY, register_listeners
+from loom.core.config import ConfigError
 from loom.core.model.enums import Cardinality, OnDelete, ServerDefault, ServerOnUpdate
 from loom.core.model.field import ColumnType, Field
 from loom.core.model.introspection import (
     ColumnFieldInfo,
+    PartialUnique,
+    declared_checks,
     declared_indexes,
+    declared_partial_unique,
+    declared_partition,
     declared_privileges,
     declared_unique,
     extract_model_from_hint,
@@ -53,6 +67,7 @@ from loom.core.model.privilege import READ_WRITE, Privilege
 from loom.core.model.relation import Relation
 from loom.core.model.scoped import ScopeColumn, ScopedTable
 from loom.core.projection.runtime import ProjectionStep, build_projection_plan_from_steps
+from loom.core.schema_names import MAX_IDENTIFIER_LENGTH, naming_convention
 
 _SA_TYPE_MAP: dict[str, type] = {
     "String": String,
@@ -62,11 +77,13 @@ _SA_TYPE_MAP: dict[str, type] = {
     "Boolean": Boolean,
     "Text": Text,
     "JSON": JSON,
+    "Bytes": LargeBinary,
     "DateTime": DateTime,
     "Numeric": Numeric,
     "Postgres.JSONB": PG_JSONB,
     "Postgres.UUID": PG_UUID,
     "Postgres.TSVECTOR": PG_TSVECTOR,
+    "Postgres.INET": PG_INET,
 }
 
 _SERVER_DEFAULT_MAP = {
@@ -105,6 +122,16 @@ class _Compilation:
 
 
 _COMPILATION_KEY = "loom.compilation"
+_RULE_KEY = "loom.rule"
+
+
+class _Keep(Enum):
+    """The default of :func:`reset_registry`: leave the naming convention as it is."""
+
+    CONVENTION = "keep"
+
+
+_KEEP_CONVENTION: Final = _Keep.CONVENTION
 
 
 @functools.cache
@@ -211,6 +238,7 @@ def _compile_model(
         struct_cls, column_fields, boundary, models_by_table, comp
     )
     constraints += _declared_constraints(struct_cls, table_name)
+    partition = declared_partition(struct_cls)
 
     attrs: dict[str, Any] = {
         "__tablename__": table_name,
@@ -220,10 +248,15 @@ def _compile_model(
         attrs[name] = _build_mapped_column(
             field_info, inline_foreign_key=name not in composite_columns
         )
-    if constraints:
-        attrs["__table_args__"] = tuple(constraints)
+    table_args: list[Any] = list(constraints)
+    if partition is not None:
+        table_args.append({"postgresql_partition_by": f"RANGE ({partition.column})"})
+    if table_args:
+        attrs["__table_args__"] = tuple(table_args)
 
     sa_cls: Any = type(struct_cls.__name__ + "SA", (comp.base,), attrs)
+    _check_declared_name_lengths(struct_cls, constraints)
+    _check_distinct_names(struct_cls, sa_cls.__table__)
     comp.compiled[struct_cls] = sa_cls
     comp.tables[table_name] = sa_cls
     comp.pending[struct_cls] = get_relations(struct_cls)
@@ -235,6 +268,7 @@ def _compile_model(
             name=table.name,
             scopes=scopes,
             privileges=frozenset(getattr(struct_cls, "__scope_privileges__", READ_WRITE)),
+            partition_by=None if partition is None else partition.column,
         )
         comp.scoped[(table.schema, table.name)] = scoped
     schema = comp.metadata.info.get(SCHEMA_KEY)
@@ -248,15 +282,109 @@ def _compile_model(
     return sa_cls
 
 
-def _declared_constraints(struct_cls: type, table_name: str) -> list[Any]:
-    constraints: list[Any] = [UniqueConstraint(*columns) for columns in declared_unique(struct_cls)]
+def _declared_constraints(struct_cls: type, table_name: str) -> list[Constraint | Index]:
+    """Keys, indexes and checks declared on the model, in declaration order.
+
+    ``__unique__`` constraints are unnamed, so the metadata's naming convention
+    names them. ``__checks__`` are named by their rule, which a ``ck``
+    convention may use as ``%(constraint_name)s``. Indexes carry a name loom
+    builds; :class:`~sqlalchemy.sql.naming.conv` marks it final so no convention
+    renames it, and :func:`_check_declared_name_lengths` refuses one over
+    Postgres's limit.
+
+    Alembic's autogenerate does not compare CHECK constraints and does not
+    compare the ``WHERE`` predicate of an index: adding, changing or removing a
+    check on an existing table, and changing a predicate, are written by hand in
+    a revision, and ``check`` does not report them as drift.
+    """
+    constraints: list[Constraint | Index] = [
+        UniqueConstraint(*columns) for columns in declared_unique(struct_cls)
+    ]
     constraints += [
-        Index(f"ix_{table_name}_{'_'.join(columns)}", *columns)
+        Index(
+            conv(f"ix_{table_name}_{'_'.join(columns)}"),
+            *columns,
+            info={_RULE_KEY: ("__indexes__", ", ".join(columns))},
+        )
         for columns in declared_indexes(struct_cls)
     ]
+    constraints += [
+        _partial_unique_index(table_name, partial)
+        for partial in declared_partial_unique(struct_cls)
+    ]
+    constraints += [
+        _check_constraint(rule, expression)
+        for rule, expression in declared_checks(struct_cls).items()
+    ]
     return constraints
 
 
+def _check_distinct_names(struct_cls: type, table: Table) -> None:
+    """Refuse a table where two constraints or indexes resolve to the same name.
+
+    Postgres would reject the second one at DDL time. Under a naming
+    convention the usual cause is ``fk_%(table_name)s_%(column_0_name)s``: every
+    composite FK of a scoped table starts with the boundary column.
+    """
+    seen: set[str] = set()
+    items: list[Constraint | Index] = [*table.constraints, *table.indexes]
+    for item in items:
+        if item.name is None:
+            continue
+        name = str(item.name)
+        if name in seen:
+            raise ValueError(
+                f"{struct_cls.__name__}: table {table.name} has two constraints named {name!r}; "
+                "name them apart, for FKs with fk_%(table_name)s_%(column_0_N_name)s"
+            )
+        seen.add(name)
+
+
+def _partial_unique_index(table_name: str, partial: PartialUnique) -> Index:
+    """The unique index of one ``__partial_unique__`` rule.
+
+    ``partial.where`` is a DDL fragment the product declared on its model. It
+    must be a static literal with no runtime input; loom checks only that it is
+    a non-empty string.
+    """
+    return Index(
+        conv(f"uq_{table_name}_{partial.rule}"),
+        *partial.columns,
+        unique=True,
+        postgresql_where=text(partial.where),
+        info={_RULE_KEY: ("__partial_unique__", partial.rule)},
+    )
+
+
+def _check_constraint(rule: str, expression: str) -> CheckConstraint:
+    """The CHECK constraint of one ``__checks__`` rule.
+
+    ``expression`` is a DDL fragment the product declared on its model. It must
+    be a static literal with no runtime input; loom checks only that it is a
+    non-empty string.
+    """
+    return CheckConstraint(expression, name=rule, info={_RULE_KEY: ("__checks__", rule)})
+
+
+def _check_declared_name_lengths(struct_cls: type, constraints: list[Constraint | Index]) -> None:
+    """Refuse a declared check or index whose final name Postgres would truncate.
+
+    SQLAlchemy would raise only when emitting DDL for a plain name, and would
+    shorten a final (``conv``) name with a hash; both are refused here instead.
+    """
+    for constraint in constraints:
+        declared = constraint.info.get(_RULE_KEY)
+        if declared is None:
+            continue
+        attr, rule = declared
+        name = str(constraint.name)
+        if len(name.encode()) > MAX_IDENTIFIER_LENGTH:
+            raise ValueError(
+                f"{struct_cls.__name__}: {attr} rule {rule!r} is named {name!r}, longer than "
+                f"the {MAX_IDENTIFIER_LENGTH} bytes Postgres keeps; shorten it"
+            )
+
+
 def _target_model(
     table: str, models_by_table: Mapping[str, type], comp: _Compilation
 ) -> type | None:
@@ -549,29 +677,48 @@ def _topological_sort(
 ) -> list[type]:
     """Kahn's algorithm: return *models* with dependency leaves first.
 
-    If a cycle is detected (remaining nodes after BFS exhaustion), the
-    cyclic models are appended in arbitrary order.  Circular references
-    are valid because ``compile_model`` is idempotent and relationships
-    are resolved after all models are registered.
+    Ties are released in the input order of *models*.  If a cycle is detected
+    (remaining nodes after BFS exhaustion), the cyclic models are appended in
+    their input order.  Circular references are valid because
+    ``compile_model`` is idempotent and relationships are resolved after all
+    models are registered.
     """
-    from collections import deque
+    in_degree, dependents = _dependency_graph(models, deps)
+    result = _release_in_dependency_order(models, in_degree, dependents)
+    processed = set(result)
+    result.extend(m for m in models if m not in processed)
+    return result
 
-    model_set = set(models)
 
-    # in_degree[m] = number of m's deps that are within our compilation set
+def _dependency_graph(
+    models: list[type],
+    deps: dict[type, frozenset[type]],
+) -> tuple[dict[type, int], dict[type, list[type]]]:
+    """Index the dependency edges that stay within *models*.
+
+    Returns:
+        ``in_degree[m]``: how many of ``m``'s deps are in *models*, and
+        ``dependents[dep]``: the models depending on ``dep``, in input order.
+    """
+    model_set = set(models)
     in_degree: dict[type, int] = dict.fromkeys(models, 0)
-    # dependents[dep] = list of models that depend on dep
     dependents: dict[type, list[type]] = {m: [] for m in models}
-
     for m in models:
         for dep in deps.get(m, frozenset()):
             if dep in model_set:
                 in_degree[m] += 1
                 dependents[dep].append(m)
+    return in_degree, dependents
+
 
+def _release_in_dependency_order(
+    models: list[type],
+    in_degree: dict[type, int],
+    dependents: dict[type, list[type]],
+) -> list[type]:
+    """Run Kahn's BFS, consuming *in_degree*; models left in a cycle are omitted."""
     queue: deque[type] = deque(m for m in models if in_degree[m] == 0)
     result: list[type] = []
-
     while queue:
         node = queue.popleft()
         result.append(node)
@@ -579,10 +726,6 @@ def _topological_sort(
             in_degree[dependent] -= 1
             if in_degree[dependent] == 0:
                 queue.append(dependent)
-
-    # Cyclic nodes: append in original order
-    processed = set(result)
-    result.extend(m for m in models if m not in processed)
     return result
 
 
@@ -600,8 +743,6 @@ def _resolve_compile_closure(*roots: type) -> tuple[type, ...]:
     Returns:
         Tuple of all models (roots + transitive deps) in compilation order.
     """
-    from collections import deque
-
     seen: set[type] = set()
     all_deps: dict[type, frozenset[type]] = {}
     queue: deque[type] = deque(roots)
@@ -678,8 +819,29 @@ def get_metadata() -> MetaData:
     return SABase.metadata
 
 
-def reset_registry() -> None:
-    """Clear compiled models — primarily for testing."""
+def configured_naming_convention(value: Mapping[str, str] | None) -> dict[str, str] | None:
+    """Validate the ``database.schema.naming_convention`` setting.
+
+    Raises:
+        ConfigError: Naming the setting and the first unknown kind.
+    """
+    try:
+        return naming_convention(value)
+    except ValueError as exc:
+        raise ConfigError(f"database.schema.naming_convention: {exc}") from exc
+
+
+def reset_registry(
+    *, naming_convention: Mapping[str, str] | None | _Keep = _KEEP_CONVENTION
+) -> None:
+    """Clear compiled models and, when asked, set the shared metadata's naming convention.
+
+    The runtime compiles into the shared metadata after this call, so the
+    convention it receives, the one ``database.schema.naming_convention``
+    declares, names the tables ``create_all`` creates exactly as the
+    application metadata of the migration path does. Without the argument the
+    convention is left as it is; ``None`` restores SQLAlchemy's default.
+    """
     _registry.clear()
     _table_registry.clear()
     _core_registry.clear()
@@ -687,6 +849,11 @@ def reset_registry() -> None:
     _shared().scoped.clear()
     SABase.metadata.clear()
     SABase.registry.dispose()
+    if naming_convention is _KEEP_CONVENTION:
+        return
+    SABase.metadata.naming_convention = (
+        dict(naming_convention) if naming_convention else DEFAULT_NAMING_CONVENTION
+    )
 
 
 # ---------------------------------------------------------------------------