loom-kernel 2.19.0__tar.gz → 2.20.1__tar.gz

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/CHANGELOG.md

@@ -375,6 +375,34 @@
 
 ### core
 
+- **core:** on a model with a composite primary key, the SQLAlchemy
+  repository's `get_by_id`, `exists`, `update` and `delete` take the key as a
+  tuple of every key value in declaration order (`repo.get_by_id((account_id,
+  entry_id))`) and raise `ValueError` for anything else, a scalar included,
+  instead of matching the first key column. A `Load` step and a cached
+  repository's `get_by_id`, `update` and `delete` pass the id unchanged, so a
+  scalar id raises there too; a cached `@cache_query(scope="entity")` read
+  takes the tuple as its first argument and raises `TypeError` for anything
+  else. A cursor token issued for such a model before this release is refused with
+  `UnsupportedQuery`, `400 unsupported_query`; clients restart from the first
+  page. `decode_cursor` takes `id_count`, the number of key columns, and
+  `get_id_attributes` returns every key column name.
+
+- **core:** `compile_all` raises `ValueError` for a model with a composite
+  primary key that declares a relation or a projection whose loader runs
+  `load_many`, naming the model, its key and those fields. The backend loads
+  them by the first key column only, so a many-to-one relation attached
+  another owner's row and a one-to-many relation grouped children by that
+  column; load them by hand until they are matched by the full key.
+
+- **core:** the `RepositoryMongo`, `RepositoryDynamoDB` and
+  `loom.testing.InMemoryRepository` constructors raise `ConfigError` for a
+  model with a composite primary key, naming the model and its key. Each
+  keys an item by one field (Mongo's `_id` and the DynamoDB partition key by
+  the first key column, the in-memory store by its `id_field`), so a second
+  row sharing that field's value raised `Conflict` on Mongo and DynamoDB and
+  replaced the first row in memory.
+
 - **core:** the miss path of a cached `@cache_query`/`@cache_call` read,
   `McpHandle.call` and `CacheGateway.get_value`/`multi_get_values` now raise
   `BoundaryValidationError` — a `ValueError` — on a stale or malformed cached
@@ -457,6 +485,10 @@
 
 ### rest
 
+- **rest:** auto-CRUD mounts no `/{id}` route (get, update, delete) for a
+  model with a composite primary key, since one path segment cannot carry the
+  key; naming one of them in `include` raises `ValueError` when the routes are
+  built. Those routes matched the first key column only.
 - **rest:** a JSON object body that fails `Command` validation now answers
   `422 boundary_validation` with a `violations` list (`{field, message}`
   pairs, `field` being the wire name the client sent, the same shape
@@ -570,6 +602,36 @@
 
 ### core
 
+- **core:** the relation steps and the `load_many` projection steps of a read
+  profile run one after another on the request's session. They ran with
+  `asyncio.gather` on that one session: when one step failed while another was
+  still waiting, on Postgres with asyncpg the caller got `InterfaceError:
+  cannot perform operation: another operation is in progress` instead of the
+  step's error, and the pooled connection was left in a manually started
+  transaction, so the next request on it failed until `engine.dispose()`. The
+  number of statements is unchanged, at most one per step.
+
+- **core:** cursor pagination and the by-id operations of the SQLAlchemy
+  repository use the full primary key of a model whose key is composite, such
+  as a `RowScoped` model keyed by its boundary column and its own id. They
+  used only the first key column: a cursor walk ordered and compared on it
+  alone and skipped the rows sharing that column's value with the last row of
+  each page, and `get_by_id`, `exists`, `update` and `delete` matched that
+  column only. The cursor now orders and compares on
+  every key column after the sort keys and carries every key value in the
+  token; offset pages and `list_paginated` order by every key column too.
+  Tokens of single-column keys are unchanged. A cached repository over such a
+  model keyed its entries by the first key column too, so a warm
+  `list_paginated` or first cursor page served the rows sharing a first key
+  value as copies of one of them; it now caches and reloads every row by its
+  full key, one `get_by_id` per missing row.
+
+- **core:** a `MANY_TO_MANY` relation joins the target table on the column
+  the secondary table's foreign key references. It joined on the target
+  model's first key column, so a target with a composite key, or whose link
+  references a unique non-key column, loaded the rows whose first key column
+  held the linked value instead of the linked rows.
+
 - **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

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/PKG-INFO

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

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/src/loom/core/backend/core_model.py

@@ -21,7 +21,6 @@ The ORM class (``ProductSA``) is kept exclusively for writes and Alembic.
 
 from __future__ import annotations
 
-import asyncio
 from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
@@ -61,7 +60,8 @@ class CoreRelationStep:
 
     * ``MANY_TO_MANY``:
       ``fk_col`` = owner FK column in the secondary table.
-      ``pk_col`` = PK column on the *target* table.
+      ``pk_col`` = target column the secondary table's FK references (a key
+      or unique column).
       ``secondary_table`` / ``secondary_target_fk`` required.
     """
 
@@ -201,8 +201,9 @@ class CoreModel:
     ) -> list[Any]:
         """Execute ``stmt``, batch-load relations, run projections, return ``list[Struct]``.
 
-        Relations declared in the profile are fetched in parallel via
-        ``asyncio.gather``.  Projection steps run after relation loading.
+        Relations declared in the profile are loaded one after another on
+        ``session``, with at most one statement each.  Projection steps run
+        after relation loading.
 
         Args:
             session: Active async SQLAlchemy session.
@@ -277,10 +278,7 @@ async def _load_relations(
     steps: tuple[CoreRelationStep, ...],
     rows: list[Any],
 ) -> dict[str, dict[Any, Any]]:
-    if not steps:
-        return {}
-    results = await asyncio.gather(*(_fetch_relation_batch(session, step, rows) for step in steps))
-    return {step.attr: data for step, data in zip(steps, results, strict=False)}
+    return {step.attr: await _fetch_relation_batch(session, step, rows) for step in steps}
 
 
 def _make_adapter(

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/src/loom/core/backend/sqlalchemy.py

@@ -13,6 +13,7 @@ from sqlalchemy import (
     BigInteger,
     Boolean,
     CheckConstraint,
+    Column,
     Constraint,
     DateTime,
     Float,
@@ -57,6 +58,7 @@ from loom.core.model.introspection import (
     extract_model_from_hint,
     get_column_fields,
     get_id_attribute,
+    get_id_attributes,
     get_projections,
     get_relations,
     get_table_name,
@@ -879,6 +881,7 @@ def _compile_core_model(struct_cls: type, comp: _Compilation) -> None:
     profile_plans = _build_profile_plans(
         profiles, all_columns, id_attr, relations, relation_steps, projections, struct_cls
     )
+    _refuse_composite_key_loads(struct_cls, profile_plans)
 
     core_model = CoreModel(struct_cls, table, id_attr, profile_plans)
     for name, col in zip(column_fields, all_columns, strict=False):
@@ -887,6 +890,37 @@ def _compile_core_model(struct_cls: type, comp: _Compilation) -> None:
     comp.core[struct_cls] = core_model
 
 
+def _refuse_composite_key_loads(struct_cls: type, plans: dict[str, CoreProfilePlan]) -> None:
+    """Refuse relations and backend projections on a model with a composite primary key.
+
+    The core loaders match loaded rows to their owner by ``CoreProfilePlan.id_attr``,
+    the first primary-key column, so on a composite key they attach rows to the
+    wrong owner.
+    """
+    key = get_id_attributes(struct_cls)
+    if len(key) == 1:
+        return
+    loads = _fields_loaded_by_key(plans)
+    if loads:
+        raise ValueError(
+            f"{struct_cls.__name__} has the composite primary key ({', '.join(key)}); the "
+            f"backend loads {', '.join(loads)} by its first key column only, so drop "
+            "them from the model and load them by hand"
+        )
+
+
+def _fields_loaded_by_key(plans: dict[str, CoreProfilePlan]) -> list[str]:
+    relations = {step.attr for plan in plans.values() for step in plan.relation_steps}
+    projections = {
+        step.name
+        for plan in plans.values()
+        for level in plan.projection_plan.levels
+        for step in level
+        if not step.prefer_memory
+    }
+    return sorted(relations | projections)
+
+
 def _collect_profiles(
     relations: dict[str, Any],
     projections: dict[str, Any],
@@ -1167,12 +1201,12 @@ def _compile_many_to_many_step(
     if secondary_table is None:
         return None
     owner_table_name = get_table_name(struct_cls)
-    secondary_owner_fk, secondary_target_fk, target_table_name = _inspect_secondary(
+    secondary_owner_fk, secondary_target_fk, target_ref = _inspect_secondary(
         secondary_table, owner_table_name
     )
-    if secondary_owner_fk is None or secondary_target_fk is None or target_table_name is None:
+    if secondary_owner_fk is None or secondary_target_fk is None or target_ref is None:
         return None
-    target_sa = _find_target_sa_class(target_table_name, comp)
+    target_sa = _find_target_sa_class(target_ref.table.name, comp)
     if target_sa is None:
         return None
     related_struct = getattr(target_sa, "__struct_cls__", None)
@@ -1188,7 +1222,7 @@ def _compile_many_to_many_step(
         related_struct=related_struct,
         owner_pk_col=get_id_attribute(struct_cls),
         fk_col=secondary_owner_fk,
-        pk_col=get_id_attribute(related_struct),
+        pk_col=target_ref.name,
         secondary_table=secondary_table,
         secondary_target_fk=secondary_target_fk,
     )
@@ -1197,18 +1231,19 @@ def _compile_many_to_many_step(
 def _inspect_secondary(
     secondary_table: Any,
     owner_table_name: str,
-) -> tuple[str | None, str | None, str | None]:
+) -> tuple[str | None, str | None, Column[Any] | None]:
+    """Return the owner FK column, the target FK column and the target column it references."""
     owner_fk: str | None = None
     target_fk: str | None = None
-    target_table_name: str | None = None
+    target_ref: Column[Any] | None = None
     for col in secondary_table.columns:
         for fk in col.foreign_keys:
             if fk.column.table.name == owner_table_name:
                 owner_fk = col.name
             else:
                 target_fk = col.name
-                target_table_name = fk.column.table.name
-    return owner_fk, target_fk, target_table_name
+                target_ref = fk.column
+    return owner_fk, target_fk, target_ref
 
 
 def _target_cols(related_struct: type, target_table: Any) -> tuple[Any, ...]:

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/src/loom/core/cache/repository.py

@@ -7,6 +7,7 @@ import warnings
 from collections.abc import Awaitable, Callable, Mapping, Sequence
 from dataclasses import dataclass
 from functools import partial, wraps
+from types import GenericAlias
 from typing import Any, Generic, NamedTuple, TypeVar, cast
 
 import msgspec
@@ -30,7 +31,7 @@ from loom.core.model import BoundaryValidationError, LoomType, is_pydantic_model
 from loom.core.model.convert import to_struct
 from loom.core.model.enums import Cardinality
 from loom.core.model.introspection import (
-    get_id_attribute,
+    get_id_attributes,
     get_projections,
     get_relations,
     list_element_type,
@@ -127,37 +128,42 @@ class _DependencySpec:
 class _PrimaryKey(NamedTuple):
     """Primary key of the cached model as the wrapper reads it.
 
+    A single-column key is its value; a composite key is the tuple of every
+    key value in declaration order, the form the SQLAlchemy repository's
+    ``get_by_id`` takes.
+
     Attributes:
-        attribute: Name of the primary-key attribute; ``id`` when the wrapped
-            repository declares no model or the model declares no primary key.
-        python_type: Type of the key, or ``None`` when it is unresolvable or
-            not a plain class (``int | None``, for instance).
+        attributes: Names of the primary-key attributes in declaration order;
+            ``("id",)`` when the wrapped repository declares no model or the
+            model declares no primary key.
+        python_types: Type of each key attribute, ``None`` where it is
+            unresolvable or not a plain class (``int | None``, for instance).
     """
 
-    attribute: str
-    python_type: type | None
+    attributes: tuple[str, ...]
+    python_types: tuple[type | None, ...]
 
 
-_FALLBACK_PRIMARY_KEY = _PrimaryKey(attribute="id", python_type=None)
+_FALLBACK_PRIMARY_KEY = _PrimaryKey(attributes=("id",), python_types=(None,))
 
 
 def _resolve_primary_key(repository: Repository[Any, Any, Any, Any]) -> _PrimaryKey:
     """Resolve the primary key of the wrapped repository's model.
 
     Falls back to the attribute ``id`` with no type for a repository without a
-    model or whose model declares no primary key; the type alone is ``None``
-    when the key's annotation is not a plain class.  The cached index is then
-    used as it was decoded.
+    model or whose model declares no primary key; the type of one attribute
+    alone is ``None`` when its annotation is not a plain class.
     """
     model = getattr(repository, "model", None)
     if model is None:
         return _FALLBACK_PRIMARY_KEY
     try:
-        attribute = get_id_attribute(model)
+        attributes = get_id_attributes(model)
     except (TypeError, ValueError):
         return _FALLBACK_PRIMARY_KEY
-    hint = resolve_type_hints(model).get(attribute)
-    return _PrimaryKey(attribute, hint if isinstance(hint, type) else None)
+    hints = resolve_type_hints(model)
+    types = tuple(hint if isinstance(hint, type) else None for hint in map(hints.get, attributes))
+    return _PrimaryKey(attributes, types)
 
 
 class CachedRepository(
@@ -174,9 +180,11 @@ class CachedRepository(
     single ``<primary key> IN (...)`` query, so the wrapped repository should
     support :attr:`~loom.core.repository.abc.query.FilterOp.IN` on the primary
     key; a repository whose ``allowed_filter_fields`` excludes the primary key
-    is detected and served with per-id reads instead.  The key is read by the
-    attribute name the model declares (``id`` when there is no model or the
-    model declares no primary key).
+    is detected and served with per-id reads instead, and so is a model with a
+    composite primary key, which a filter on one field cannot match.  The key
+    is read by the attribute names the model declares (``id`` when there is no
+    model or the model declares no primary key); a composite key is the tuple
+    of its values in declaration order.
 
     Concurrent misses of the same key on the entity read and on a
     ``@cache_query`` read are coalesced inside the process: the first caller
@@ -699,12 +707,15 @@ class CachedRepository(
         return max(1, round(ttl + self._rng.uniform(-spread, spread)))
 
     def _extract_entity_id(self, item: Any) -> object | None:
-        """Read the primary key of *item* by the attribute the model declares.
+        """Read the primary key of *item* by the attributes the model declares.
 
-        The same attribute names the refill filter, which queries the missing
-        entities with ``FilterSpec(field=<primary key>, ...)``.
+        Returns the value of a single-column key and the tuple of every value
+        of a composite one, or ``None`` when a key value is missing.
         """
-        return getattr(item, self._primary_key.attribute, None)
+        values = tuple(getattr(item, name, None) for name in self._primary_key.attributes)
+        if None in values:
+            return None
+        return values[0] if len(values) == 1 else values
 
     async def _create_many(self, data: Sequence[msgspec.Struct]) -> tuple[OutputT, ...]:
         if not data:
@@ -842,11 +853,12 @@ class CachedRepository(
         """Return the primary key a ``scope="entity"`` read is keyed by, or raise.
 
         The key must be the first positional argument (a keyword does not
-        count) and must not be ``None``.  When the model's primary-key type
-        resolved to a plain class, the argument must be of that exact type:
-        a ``datetime`` for a ``date`` key or a ``bool`` for an ``int`` key
+        count) and must not be ``None``; a composite key must be a tuple of
+        one value per key attribute.  Where a key attribute's type resolved
+        to a plain class, its value must be of that exact type: a
+        ``datetime`` for a ``date`` key or a ``bool`` for an ``int`` key
         would render a tag no mutation event ever bumps, so both are
-        rejected even though ``isinstance`` would accept them.  A key
+        rejected even though ``isinstance`` would accept them.  An attribute
         declared ``int | None`` resolves no class and gets no type check.
         Only this entry point is guarded: ``get_by_id``, ``update`` and
         ``delete`` are typed ``IdT`` and stay unchecked.
@@ -859,11 +871,18 @@ class CachedRepository(
                 f"{method_name}: @cache_query(scope='entity') needs the primary key"
                 " as first positional argument"
             )
-        expected = self._primary_key.python_type
-        if expected is not None and type(args[0]) is not expected:
+        types = self._primary_key.python_types
+        composite = len(types) > 1
+        values = args[0] if composite and isinstance(args[0], tuple) else (args[0],)
+        if len(values) != len(types) or any(
+            expected is not None and type(value) is not expected
+            for value, expected in zip(values, types, strict=True)
+        ):
+            names = ", ".join("Any" if t is None else t.__name__ for t in types)
             raise TypeError(
                 f"{method_name}: @cache_query(scope='entity') received a"
-                f" {type(args[0]).__name__} as primary key, expected {expected.__name__}"
+                f" {type(args[0]).__name__} as primary key,"
+                f" expected {f'tuple[{names}]' if composite else names}"
             )
         return args[0]
 
@@ -930,10 +949,12 @@ class CachedRepository(
         A repository may restrict the filterable fields (``allowed_filter_fields``).
         When the primary-key attribute is not among them the batched refill would
         be rejected, so the wrapper degrades to per-id reads rather than failing
-        the page; the repository's declared policy is left untouched.
+        the page; the repository's declared policy is left untouched.  A
+        composite key is always read per id, since a filter names one field.
         """
+        attributes = self._primary_key.attributes
         allowed = getattr(self._repository, "allowed_filter_fields", None)
-        return not allowed or self._primary_key.attribute in allowed
+        return len(attributes) == 1 and (not allowed or attributes[0] in allowed)
 
     async def _fetch_missing_one_by_one(
         self,
@@ -966,7 +987,9 @@ class CachedRepository(
     def _id_in_query(self, ids: Sequence[IdT]) -> QuerySpec:
         return QuerySpec(
             filters=FilterGroup(
-                filters=(FilterSpec(field=self._primary_key.attribute, op=FilterOp.IN, value=ids),)
+                filters=(
+                    FilterSpec(field=self._primary_key.attributes[0], op=FilterOp.IN, value=ids),
+                )
             ),
             limit=len(ids),
         )
@@ -1029,16 +1052,21 @@ class CachedRepository(
         """Restore the ids of a cached index to the model's primary-key type.
 
         The index round-trips through msgpack, which renders a ``datetime``, a
-        ``date`` or a ``UUID`` as a string, while the repository binds the
-        declared type: SQLAlchemy returns no rows for a ``datetime`` column
-        filtered with strings.  Converting here keeps every later use of the id
-        — cache key, filter value, identity match — in the declared type.
+        ``date`` or a ``UUID`` as a string and a tuple as a list, while the
+        repository binds the declared type: SQLAlchemy returns no rows for a
+        ``datetime`` column filtered with strings, and the SQLAlchemy
+        repository takes a composite key only as a tuple.  Converting here
+        keeps every later use of the id — cache key, filter value, identity
+        match — in the declared type.
 
         Returns:
             The converted ids, or ``None`` when they do not fit the current
             primary-key type, which makes the index unusable.
         """
-        id_type = self._primary_key.python_type
+        types = self._primary_key.python_types
+        id_type: Any = types[0]
+        if len(types) > 1:
+            id_type = GenericAlias(tuple, tuple(Any if t is None else t for t in types))
         if id_type is None:
             return cast(list[IdT], raw_ids)
         try:

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/src/loom/core/model/__init__.py

@@ -22,6 +22,7 @@ from loom.core.model.introspection import (
     declared_unique,
     get_column_fields,
     get_id_attribute,
+    get_id_attributes,
     get_projections,
     get_relations,
     get_table_name,
@@ -107,6 +108,7 @@ __all__ = [
     "UnsupportedBoundaryType",
     "get_column_fields",
     "get_id_attribute",
+    "get_id_attributes",
     "get_projections",
     "get_relations",
     "get_table_name",

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/src/loom/core/model/introspection.py

@@ -145,12 +145,21 @@ def get_projections(cls: type) -> dict[str, Projection]:
     return _collect_inherited_dict_metadata(cls, "__loom_projections__")
 
 
+def get_id_attributes(cls: type) -> tuple[str, ...]:
+    """Return the names of the primary-key fields, in declaration order.
+
+    Raises:
+        ValueError: If the model declares no primary-key field.
+    """
+    names = tuple(name for name, info in get_column_fields(cls).items() if info.field.primary_key)
+    if not names:
+        raise ValueError(f"No primary key field found on {cls.__name__}")
+    return names
+
+
 def get_id_attribute(cls: type) -> str:
-    """Return the name of the primary key field."""
-    for name, info in get_column_fields(cls).items():
-        if info.field.primary_key:
-            return name
-    raise ValueError(f"No primary key field found on {cls.__name__}")
+    """Return the name of the first primary-key field."""
+    return get_id_attributes(cls)[0]
 
 
 def get_table_name(cls: type) -> str:

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/src/loom/core/projection/runtime.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import asyncio
 import inspect
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
@@ -231,18 +230,12 @@ async def _execute_backend_steps(
     parent_ids: Sequence[object],
     values_by_index: dict[int, dict[str, Any]],
 ) -> None:
-    if not steps:
-        return
-
-    backend_results = await asyncio.gather(
-        *(step.loader.load_many(backend_context, parent_ids) for step in steps)
-    )
-    for step, rows in zip(steps, backend_results, strict=False):
+    for step in steps:
         _merge_rows(
             values_by_index=values_by_index,
             parent_ids=parent_ids,
             field_name=step.name,
-            rows=rows,
+            rows=await step.loader.load_many(backend_context, parent_ids),
             default=step.projection.default,
         )
 

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/src/loom/core/repository/abc/cursor.py

@@ -1,7 +1,9 @@
 """Backend-neutral cursor tokens for keyset pagination.
 
 A token is the base64url form of a msgspec-encoded record
-``{"b": backend, "k": [sort key values...], "id": tie-breaker}``.  Every
+``{"b": backend, "k": [sort key values...], "id": tie-breaker}``, where the
+tie-breaker is the primary-key value, or the list of its values when the key
+is composite.  Every
 backend issues and consumes the same shape, so a token from another backend
 or in a legacy format is rejected at decode time with
 :class:`~loom.core.repository.abc.errors.UnsupportedQuery`.
@@ -28,7 +30,8 @@ class Cursor(LoomFrozenStruct, frozen=True):
     Args:
         backend: Name of the backend that issued the token.
         keys: Sort key values of the last row on the previous page, in sort order.
-        tie_breaker: Primary key of that row.
+        tie_breaker: Primary key of that row; a tuple in key order when the
+            key is composite.
     """
 
     backend: str
@@ -58,7 +61,7 @@ _Key = int | float | str | bool | None | _DateTimeKey | _DateKey | _UuidKey | _D
 class _Token(msgspec.Struct):
     b: str
     k: list[_Key]
-    id: _Key
+    id: _Key | list[_Key]
 
 
 def _wrap(value: object) -> _Key:
@@ -89,7 +92,8 @@ def encode_cursor(backend: str, keys: Sequence[object], tie_breaker: object) ->
     Args:
         backend: Name of the issuing backend.
         keys: Sort key values of the last row on the page, in sort order.
-        tie_breaker: Primary key of that row.
+        tie_breaker: Primary key of that row; a tuple in key order when the
+            key is composite.
 
     Returns:
         base64url token that :func:`decode_cursor` accepts for ``backend``.
@@ -97,11 +101,18 @@ def encode_cursor(backend: str, keys: Sequence[object], tie_breaker: object) ->
     Raises:
         TypeError: If a key has a type the token format cannot carry.
     """
-    token = _Token(b=backend, k=[_wrap(key) for key in keys], id=_wrap(tie_breaker))
+    tie: _Key | list[_Key]
+    if isinstance(tie_breaker, tuple):
+        tie = [_wrap(value) for value in tie_breaker]
+    else:
+        tie = _wrap(tie_breaker)
+    token = _Token(b=backend, k=[_wrap(key) for key in keys], id=tie)
     return base64.urlsafe_b64encode(msgspec.json.encode(token)).decode()
 
 
-def decode_cursor(token: str, backend: str, model: str, *, key_count: int | None = None) -> Cursor:
+def decode_cursor(
+    token: str, backend: str, model: str, *, key_count: int | None = None, id_count: int = 1
+) -> Cursor:
     """Decode a token issued by :func:`encode_cursor` for ``backend``.
 
     Args:
@@ -110,13 +121,17 @@ def decode_cursor(token: str, backend: str, model: str, *, key_count: int | None
         model: Qualified model name, used in the error.
         key_count: Number of sort keys the query orders by; when given, a
             token carrying a different number is rejected.
+        id_count: Number of primary-key columns. A single-column key is
+            carried as a scalar and a composite key as a list of that many
+            values; any other token is rejected.
 
     Returns:
         The decoded :class:`Cursor`.
 
     Raises:
         UnsupportedQuery: If the token is undecodable, in a legacy format,
-            was issued by another backend or does not match the sort.
+            was issued by another backend or does not match the sort or the
+            primary key.
     """
     try:
         record = msgspec.json.decode(base64.urlsafe_b64decode(token.encode()), type=_Token)
@@ -126,8 +141,17 @@ def decode_cursor(token: str, backend: str, model: str, *, key_count: int | None
         raise UnsupportedQuery(backend, model, "cursor token was issued by another backend")
     if key_count is not None and len(record.k) != key_count:
         raise UnsupportedQuery(backend, model, "cursor token does not match the sort")
+    tie_breaker: object
+    if isinstance(record.id, list):
+        carried: int | None = len(record.id)
+        tie_breaker = tuple(_unwrap(key) for key in record.id)
+    else:
+        carried = None
+        tie_breaker = _unwrap(record.id)
+    if carried != (id_count if id_count > 1 else None):
+        raise UnsupportedQuery(backend, model, "cursor token does not match the primary key")
     return Cursor(
         backend=record.b,
         keys=tuple(_unwrap(key) for key in record.k),
-        tie_breaker=_unwrap(record.id),
+        tie_breaker=tie_breaker,
     )

{loom_kernel-2.19.0 → loom_kernel-2.20.1}/src/loom/core/repository/dynamodb/repository.py

@@ -23,10 +23,11 @@ from typing import Any, ClassVar, Generic, cast
 
 import msgspec
 
+from loom.core.config import ConfigError
 from loom.core.errors import Conflict
 from loom.core.logger import get_logger
 from loom.core.model.convert import to_struct
-from loom.core.model.introspection import get_column_fields, get_id_attribute, get_table_name
+from loom.core.model.introspection import get_column_fields, get_id_attributes, get_table_name
 from loom.core.repository.abc import (
     Creatable,
     Deletable,
@@ -70,6 +71,9 @@ class RepositoryDynamoDB(
         table_name: Name of the DynamoDB table backing this repository.
         model: The Loom struct model this repository is bound to. Its
             ``primary_key`` field becomes the DynamoDB partition key.
+
+    Raises:
+        ConfigError: If the model's primary key is composite.
     """
 
     backend_name: ClassVar[str] = "dynamodb"
@@ -86,7 +90,7 @@ class RepositoryDynamoDB(
         self._client = client
         self._table_name = table_name
         self._model = model
-        self._id_attr = get_id_attribute(model)
+        self._id_attr = _single_id_attribute(model)
         self._column_fields = frozenset(get_column_fields(model).keys())
         self._serializer = TypeSerializer()
         self._deserializer = TypeDeserializer()
@@ -260,6 +264,17 @@ class RepositoryDynamoDB(
         return {self._id_attr: self._encode_value(obj_id)}
 
 
+def _single_id_attribute(model: type) -> str:
+    key = get_id_attributes(model)
+    if len(key) == 1:
+        return key[0]
+    raise ConfigError(
+        f"{model.__qualname__} has the composite primary key ({', '.join(key)}); "
+        "the repository keys each item by one partition key, so declare a single "
+        "primary key"
+    )
+
+
 def _is_conditional_check_failure(exc: Exception) -> bool:
     """Return whether *exc* is a DynamoDB conditional-check failure."""
     response = getattr(exc, "response", None)