graphddb-runtime 0.1.0__py3-none-any.whl

graphddb_runtime/runtime.py

@@ -0,0 +1,1674 @@
+"""GraphDDBRuntime — the DynamoDB executor (issues #44 single-op, #45 relations).
+
+Loads the ``manifest.json`` / ``operations.json`` produced by ``graphddb
+generate python`` and executes the validated access patterns via boto3.
+
+The single-operation core (#44) executes one ``OperationSpec``. Relation queries
+(#45) are expressed as **multiple** operations wired by ``resultPath`` /
+``{result.<sourceField>}`` templates; this runtime executes them in order,
+resolving prior-result-dependent keys, assembling the result tree, and
+collapsing ``belongsTo`` / ``hasOne`` resolution into a single ``BatchGetItem``
+(dedup + chunk + ``UnprocessedKeys`` retry) so N+1 ``GetItem`` does not occur.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, List, Mapping, Optional
+
+from boto3.dynamodb.types import TypeDeserializer, TypeSerializer
+
+from .batch import BatchGetExecutor, BatchWriteExecutor, serialize_key
+from .concurrency import RELATION_TRAVERSAL_CONCURRENCY, map_with_concurrency
+from .cursor import decode_cursor, encode_cursor
+from .errors import (
+    CommandNotFoundError,
+    ContractArityError,
+    ContractNotFoundError,
+    GraphDDBError,
+    LimitExceededError,
+    OperationExecutionError,
+    QueryNotFoundError,
+    TransactionNotFoundError,
+)
+from .filters import compile_filter
+from .hydration import hydrate_item
+from .limits import RuntimeLimits
+from .per_key_cursor import (
+    decode_per_key_cursor,
+    encode_per_key_cursor,
+    serialize_contract_key,
+)
+from .relations import RelationAssembler
+from .templates import (
+    resolve_template,
+    validate_params,
+)
+from .transactions import MAX_TRANSACT_ITEMS, TransactionExpander
+
+try:  # pragma: no cover - exercised indirectly
+    from botocore.exceptions import BotoCoreError, ClientError
+
+    _BOTO_ERRORS: tuple = (ClientError, BotoCoreError)
+except Exception:  # pragma: no cover
+    _BOTO_ERRORS = ()
+
+_PLACEHOLDER_RE = re.compile(r"\{[^{}]+\}")
+
+
+def _normalize_template(template: Optional[str]) -> Optional[str]:
+    """Collapse every ``{placeholder}`` to a wildcard for structural matching."""
+    if template is None:
+        return None
+    return _PLACEHOLDER_RE.sub("\x00", template)
+
+
+def _present(records: Any) -> List[Dict[str, Any]]:
+    """The present (non-``None``, dict) parent records from a result collection.
+
+    A keyed-batch map carries explicit ``None`` for misses, and a point read may
+    yield ``None``; only present records can carry a composed child (#63).
+    """
+    return [r for r in records if isinstance(r, dict)]
+
+
+def _read_from_path(record: Mapping[str, Any], path: str) -> Any:
+    """Read a declarative ``from`` path (``$.field`` / ``$.a.b``) off a parent.
+
+    ``$`` is the record root; each dotted segment descends one field. Returns
+    ``None`` when any segment is missing (treated as an absent child key →
+    explicit ``None`` child). Mirrors the TS ``readFromPath``.
+    """
+    if path == "$":
+        return record
+    current: Any = record
+    for segment in path[2:].split("."):
+        if not isinstance(current, Mapping):
+            return None
+        current = current.get(segment)
+    return current
+
+
+class GraphDDBRuntime:
+    """Executes generated single- and multi-operation queries / commands."""
+
+    def __init__(
+        self,
+        dynamodb_client: Any,
+        manifest_path: str,
+        operations_path: str,
+        table_mapping: Optional[Mapping[str, str]] = None,
+        limits: Optional[RuntimeLimits] = None,
+    ) -> None:
+        self._client = dynamodb_client
+        self._table_mapping = dict(table_mapping or {})
+        self._limits = limits or RuntimeLimits()
+        self._serializer = TypeSerializer()
+        self._deserializer = TypeDeserializer()
+
+        with open(manifest_path, "r", encoding="utf-8") as fh:
+            self._manifest: Dict[str, Any] = json.load(fh)
+        with open(operations_path, "r", encoding="utf-8") as fh:
+            self._operations: Dict[str, Any] = json.load(fh)
+
+        self._queries: Dict[str, Any] = self._operations.get("queries", {})
+        self._commands: Dict[str, Any] = self._operations.get("commands", {})
+        self._transactions: Dict[str, Any] = self._operations.get("transactions", {})
+        # CQRS Contract layer (#59 SSoT → #62 runtime): contract name →
+        # ContractSpec, layered on top of `queries`. Absent in pre-#59 documents.
+        self._contracts: Dict[str, Any] = self._operations.get("contracts", {})
+        self._entities: Dict[str, Any] = self._manifest.get("entities", {})
+
+    # ── public API ────────────────────────────────────────────────────────────
+
+    def execute_query(
+        self,
+        query_id: str,
+        params: Mapping[str, Any],
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> Optional[dict]:
+        spec = self._queries.get(query_id)
+        if spec is None:
+            raise QueryNotFoundError(f"unknown query '{query_id}'")
+
+        validate_params(params, spec.get("params", {}), operation_id=query_id)
+
+        operations: List[Dict[str, Any]] = list(spec.get("operations", []))
+        self._enforce_operation_limits(query_id, operations)
+
+        root_op = operations[0]
+        cardinality = spec.get("cardinality")
+
+        root = self._run_root(query_id, root_op, params, options or {}, cardinality)
+        if root is None:
+            return None
+
+        assembler = RelationAssembler(
+            run_query=lambda op, sv: self._run_relation_query(query_id, op, sv),
+            run_batch_get=lambda op, svs: self._run_relation_batch_get(
+                query_id, op, svs
+            ),
+            key_for=self._relation_key_marker,
+        )
+        self._assemble_relations(spec, operations, root, assembler)
+        return root
+
+    def _assemble_relations(
+        self,
+        spec: Mapping[str, Any],
+        operations: List[Dict[str, Any]],
+        root: Any,
+        assembler: RelationAssembler,
+    ) -> None:
+        """Apply the relation operations onto ``root``, HONORING the execution plan.
+
+        The SSoT execution plan (issue #70a) partitions ``operations`` into ordered
+        *stages*: the operations within a stage are mutually independent (none reads
+        a ``{result.*}`` value another produces — e.g. sibling relations sharing a
+        parent path), so this runtime issues them **concurrently** under the
+        declared in-flight bound (``executionPlan.concurrency``), while the stages
+        run in order because a later stage depends on an earlier one's results
+        (issue #70b). Each op in a stage writes a **disjoint** slot of the result
+        tree (its own parent records' property), so completion order does not affect
+        the merged output.
+
+        Backward compatibility: a spec **without** an ``executionPlan`` (a pre-#70a
+        document, or a single-operation read) falls back to one-operation-per-stage
+        **sequential** assembly — byte-for-byte the pre-#70b behavior. The ``concurrency``
+        helper also runs a single-member stage inline (no thread), so a plan whose
+        stages each hold one op is identical to sequential too.
+        """
+        stages = self._relation_stages(spec, operations)
+        for stage in stages:
+            stage_ops = [operations[i] for i in stage]
+            # Independent ops of one stage → bounded-concurrent apply. The helper
+            # preserves order and runs a single-op stage inline (sequential).
+            map_with_concurrency(
+                stage_ops,
+                self._plan_concurrency(spec),
+                lambda op, _i: assembler.apply(root, op),
+            )
+
+    @staticmethod
+    def _relation_stages(
+        spec: Mapping[str, Any], operations: List[Dict[str, Any]]
+    ) -> List[List[int]]:
+        """The ordered relation stages (indices into ``operations``), excluding the
+        root (index 0).
+
+        Reads ``executionPlan.groups`` (issue #70a) when present, dropping the root
+        index from each group; an empty group is skipped. When the plan is **absent**
+        (backward compatibility), falls back to one stage per relation op in emission
+        order — the pre-#70 sequential ordering, where each op is its own stage.
+        """
+        plan = spec.get("executionPlan")
+        if plan and isinstance(plan.get("groups"), list):
+            stages: List[List[int]] = []
+            for group in plan["groups"]:
+                relation_indices = [i for i in group if i != 0]
+                if relation_indices:
+                    stages.append(relation_indices)
+            return stages
+        # No plan → each relation op is its own (sequential) stage.
+        return [[i] for i in range(1, len(operations))]
+
+    @staticmethod
+    def _plan_concurrency(spec: Mapping[str, Any]) -> int:
+        """The declared in-flight bound from the execution plan, or the default.
+
+        A spec without an ``executionPlan`` (or one omitting ``concurrency``) uses
+        the shared default :data:`RELATION_TRAVERSAL_CONCURRENCY` (16) — but a
+        plan-less spec only ever produces single-op stages, which run inline, so the
+        bound is moot in that case (backward compatibility).
+        """
+        plan = spec.get("executionPlan") or {}
+        concurrency = plan.get("concurrency")
+        if isinstance(concurrency, int) and concurrency > 0:
+            return concurrency
+        return RELATION_TRAVERSAL_CONCURRENCY
+
+    # ── contract method execution (issue #62, single-service Runtime) ───────────
+
+    def execute_query_method(
+        self,
+        contract_name: str,
+        method_name: str,
+        key_or_keys: Any,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        """Execute one CQRS **query**-contract method for a single key OR an array
+        of keys (issue #62; proposal "Query Method — Common Interface" +
+        "Cardinality matrix").
+
+        The result shape follows the proposal's cardinality matrix, decided by the
+        method's serialized ``resolution`` and the input cardinality (the runtime
+        **honors** the decided facts — it never re-derives them):
+
+        - ``point`` + single key  → ``Item | None``                  (key1 : result1)
+        - ``point`` + ``list[key]`` → ``dict[keyId, Item | None]``    (keyN : resultN)
+        - ``range`` + single key  → ``{"items", "cursor"}`` connection (key1 : resultM)
+
+        ``range`` + ``list[key]`` (``keyN : resultN×M``) is **unreachable for a
+        single contract**: a ``range`` method's ``inputArity`` is ``'single'`` (the
+        N+1 rule), so an array fed into one is rejected with
+        :class:`ContractArityError` rather than fanned out. (A keyed map of
+        connections only arises under cross-contract composition, #63 — out of
+        scope here.)
+
+        The keyed map (``keyN : resultN``) is keyed by the canonical
+        :func:`serialize_contract_key` identity; every input key is present, a
+        missing item carried as an explicit ``None`` (BatchGet neither preserves
+        order nor returns absent keys). The ``range`` connection's ``cursor`` is a
+        **per-key envelope** that carries the key it paginates.
+
+        :param contract_name: A contract in the ``contracts`` SSoT map.
+        :param method_name: A query method on that contract.
+        :param key_or_keys: A single key mapping, or a list of key mappings.
+        :param params: Retrieval options (``consistentRead`` / ``limit`` /
+            ``after`` / ``order``). The ``after`` cursor is a per-key envelope.
+        """
+        method = self._resolve_contract_query_method(contract_name, method_name)
+        resolution = method["resolution"]
+        input_arity = method.get("inputArity")
+        op_spec = self._contract_query_op(contract_name, method_name, method)
+        compose = list(method.get("compose") or [])
+        composition_plan = method.get("compositionPlan")
+        opts = dict(params or {})
+
+        is_array = isinstance(key_or_keys, (list, tuple))
+        if is_array:
+            # Only a method whose ``inputArity`` is ``'either'`` coalesces a key
+            # array into one batched call. A ``'single'`` method must reject an
+            # array — that covers BOTH a ``range`` method (one partition Query per
+            # key) AND a unique-GSI ``point`` method (one GSI Query per key;
+            # BatchGetItem cannot read a GSI, issue #71). Either is an N+1 fan-out,
+            # already rejected at build time (#60/#71 checker); this is the
+            # execution backstop, identical to the TS runtime.
+            # `inputArity` is always serialized for a query method; fall back to
+            # `resolution == 'range'` so a spec that somehow omits it still rejects
+            # a range array (defense-in-depth — `resolution` is structurally always
+            # present, mirroring the pre-#71 guard).
+            if input_arity == "single" or (input_arity is None and resolution == "range"):
+                kind = "range" if resolution == "range" else "unique-GSI point"
+                per_key = "partition" if resolution == "range" else "GSI"
+                raise ContractArityError(
+                    f"{contract_name}.{method_name}: {kind} method called with an "
+                    f"array of keys, but its inputArity is 'single'. A {kind} "
+                    f"resolution is one {per_key} Query per key, so an array would "
+                    f"be an N+1 fan-out — forbidden by the contract's N+1 rule. "
+                    f"Loop in application code for N independent reads."
+                )
+            keyed = self._execute_point_batch(
+                contract_name, method_name, op_spec, list(key_or_keys)
+            )
+            # Compose every present parent record in the keyed map (#63): the
+            # child is resolved ONCE, batched, across all parent records (no N+1).
+            self._resolve_compositions(
+                contract_name,
+                method_name,
+                compose,
+                _present(keyed.values()),
+                composition_plan,
+            )
+            return keyed
+
+        key = key_or_keys
+        if resolution == "point":
+            item = self._execute_point_single(
+                contract_name, method_name, op_spec, key, opts
+            )
+            if item is not None:
+                self._resolve_compositions(
+                    contract_name, method_name, compose, [item], composition_plan
+                )
+            return item
+        connection = self._execute_range_single(
+            contract_name, method_name, op_spec, key, opts
+        )
+        # A range parent yields N records (the connection items); compose them
+        # with a single batched child read across all items.
+        self._resolve_compositions(
+            contract_name,
+            method_name,
+            compose,
+            _present(connection["items"]),
+            composition_plan,
+        )
+        return connection
+
+    def _resolve_contract_query_method(
+        self, contract_name: str, method_name: str
+    ) -> Mapping[str, Any]:
+        contract = self._contracts.get(contract_name)
+        if contract is None:
+            available = ", ".join(sorted(self._contracts.keys())) or "(none)"
+            raise ContractNotFoundError(
+                f"unknown contract '{contract_name}'. Available: {available}"
+            )
+        if contract.get("kind") != "query":
+            raise ContractNotFoundError(
+                f"contract '{contract_name}' is a '{contract.get('kind')}' contract; "
+                f"execute_query_method only runs query contracts (commands are #64)."
+            )
+        methods = contract.get("methods", {})
+        method = methods.get(method_name)
+        if method is None:
+            available = ", ".join(sorted(methods.keys())) or "(none)"
+            raise ContractNotFoundError(
+                f"contract '{contract_name}' has no query method '{method_name}'. "
+                f"Available: {available}"
+            )
+        return method
+
+    def _contract_query_op(
+        self, contract_name: str, method_name: str, method: Mapping[str, Any]
+    ) -> Mapping[str, Any]:
+        """The single referenced read op spec for a contract query method.
+
+        A contract method resolves to exactly one declarative read op (#58). Any
+        External Query compositions (#63) it declares are carried separately on
+        the method spec (``compose``) and resolved by :meth:`_resolve_compositions`
+        after the parent step — they do **not** add operations to this op spec.
+        """
+        op_name = method["operation"]
+        spec = self._queries.get(op_name)
+        if spec is None:
+            raise ContractNotFoundError(
+                f"{contract_name}.{method_name}: referenced operation '{op_name}' is "
+                f"not present in `queries`."
+            )
+        operations = spec.get("operations", [])
+        if len(operations) != 1:
+            raise GraphDDBError(
+                f"{contract_name}.{method_name}: a single-contract query method must "
+                f"resolve to exactly one read operation, found {len(operations)}."
+            )
+        return spec
+
+    def _execute_point_single(
+        self,
+        contract_name: str,
+        method_name: str,
+        spec: Mapping[str, Any],
+        key: Mapping[str, Any],
+        opts: Mapping[str, Any],
+    ) -> Optional[dict]:
+        """point + single key → Item | None (GetItem / unique Query).
+
+        Delegates to the proven single-op executor via the referenced op spec.
+        Pagination / ordering retrieval options do not apply to a point read (at
+        most one item per key), so none are consumed here — mirroring the TS
+        runtime's ``executePointSingle``. The ``consistentRead`` retrieval option,
+        however, **does** apply to a point read on the **base table** (issue #65):
+        it is forwarded so the runtime issues a strongly-consistent ``GetItem`` /
+        base-table ``Query`` with the **identical** request the TS runtime issues
+        (``executeQuery`` → ``executeGetItem`` with ``ConsistentRead``). This closes
+        the parity gap #62's audit surfaced (Python previously ignored it).
+
+        Boundary (NOT full parity on a GSI): DynamoDB forbids a consistent read on
+        a secondary index. The TS planner (``src/planner/planner.ts``) *rejects*
+        ``consistentRead: true`` on a GSI-keyed read with a hard error; this runtime
+        instead silently drops the flag on a GSI-keyed Query (the ``not
+        op.get("indexName")`` guard in :meth:`_run_query`). The two therefore differ
+        on the *invalid* GSI+consistentRead combination (TS throws, Python no-ops) —
+        a pre-existing #71 GSI-surface divergence, out of scope for #65. Every
+        reachable point contract in the SSoT is a base-table read, where the two are
+        request-identical; a GSI-keyed consistent point read is not expressible
+        through these contracts.
+        """
+        op = spec["operations"][0]
+        validate_params(key, spec.get("params", {}), operation_id=f"{contract_name}.{method_name}")
+        select = self._select_from_projection(op)
+        entity_meta = self._resolve_entity(op)
+        consistent_read = bool(opts.get("consistentRead"))
+        op_type = op["type"]
+        if op_type == "GetItem":
+            return self._run_get_item(
+                f"{contract_name}.{method_name}",
+                op,
+                key,
+                select,
+                entity_meta,
+                consistent_read=consistent_read,
+            )
+        if op_type == "Query":
+            # A unique-key Query (point) — take the first matched item. Forward
+            # ``consistentRead`` via the run options (honored only for a base-table
+            # query, matching the TS planner).
+            connection = self._run_query(
+                f"{contract_name}.{method_name}",
+                op,
+                key,
+                select,
+                entity_meta,
+                {"consistentRead": consistent_read},
+            )
+            items = connection["items"]
+            return items[0] if items else None
+        raise GraphDDBError(
+            f"{contract_name}.{method_name}: unsupported point read operation "
+            f"'{op_type}'"
+        )
+
+    def _execute_range_single(
+        self,
+        contract_name: str,
+        method_name: str,
+        spec: Mapping[str, Any],
+        key: Mapping[str, Any],
+        opts: Mapping[str, Any],
+    ) -> Dict[str, Any]:
+        """range + single key → connection, with a per-key cursor envelope."""
+        op = spec["operations"][0]
+        validate_params(key, spec.get("params", {}), operation_id=f"{contract_name}.{method_name}")
+        select = self._select_from_projection(op)
+        entity_meta = self._resolve_entity(op)
+
+        # Decode + verify a supplied `after` envelope against this key, then hand
+        # the inner page cursor to the underlying Query (its `options.cursor`).
+        run_options: Dict[str, Any] = {}
+        if opts.get("after") is not None:
+            run_options["cursor"] = decode_per_key_cursor(opts["after"], key)
+
+        # Per-call overrides (limit / order) layer onto the static op spec.
+        op = dict(op)
+        if opts.get("limit") is not None:
+            op["limit"] = opts["limit"]
+
+        connection = self._run_query(
+            f"{contract_name}.{method_name}", op, key, select, entity_meta, run_options
+        )
+        return {
+            "items": connection["items"],
+            "cursor": encode_per_key_cursor(key, connection["cursor"]),
+        }
+
+    def _execute_point_batch(
+        self,
+        contract_name: str,
+        method_name: str,
+        spec: Mapping[str, Any],
+        keys: List[Mapping[str, Any]],
+    ) -> Dict[str, Optional[dict]]:
+        """point + array → keyed dict[keyId, Item | None] via chunked BatchGetItem.
+
+        Reuses :class:`BatchGetExecutor` (chunk ≤100, dedup, UnprocessedKeys
+        retry). BatchGet neither preserves order nor returns absent keys, so each
+        returned item is matched back to its input key by the resolved base-table
+        ``PK`` / ``SK`` and misses are filled with an explicit ``None``. Every
+        input key is present in the result (a duplicate input key maps once).
+        """
+        op = spec["operations"][0]
+        if op["type"] != "GetItem":
+            raise GraphDDBError(
+                f"{contract_name}.{method_name}: a batched point read requires a "
+                f"GetItem op (a key array coalesces to BatchGetItem), found "
+                f"'{op['type']}'."
+            )
+        select = self._select_from_projection(op)
+        entity_meta = self._resolve_entity(op)
+        params_spec = spec.get("params", {})
+        kc = op["keyCondition"]
+        key_attrs = list(kc.keys())
+
+        # Resolve each input key to its base-table dynamo key once; record the
+        # canonical identity ↔ storage marker correspondence (dedup by marker).
+        resolved = []
+        unique_by_marker: Dict[str, Dict[str, Any]] = {}
+        for key in keys:
+            validate_params(
+                key, params_spec, operation_id=f"{contract_name}.{method_name}"
+            )
+            plain_key = {attr: resolve_template(tmpl, key) for attr, tmpl in kc.items()}
+            marker = serialize_key(plain_key)
+            resolved.append((serialize_contract_key(key), plain_key, marker))
+            if marker not in unique_by_marker:
+                unique_by_marker[marker] = plain_key
+
+        if len(unique_by_marker) > self._limits.max_items:
+            raise LimitExceededError(
+                f"{contract_name}.{method_name}: BatchGet needs "
+                f"{len(unique_by_marker)} keys, exceeds max_items "
+                f"{self._limits.max_items}"
+            )
+
+        raw_by_marker: Dict[str, Dict[str, Any]] = {}
+        if unique_by_marker:
+            serialized_keys = [
+                {attr: self._serializer.serialize(v) for attr, v in plain.items()}
+                for plain in unique_by_marker.values()
+            ]
+            executor = BatchGetExecutor(
+                self._client,
+                boto_errors=_BOTO_ERRORS,
+                max_batch_get_items=self._limits.max_batch_get_items,
+            )
+            request_extra = self._projection_request(op, select)
+            raw_items = executor.get(
+                self._physical_table(op["tableName"]), serialized_keys, request_extra
+            )
+            for raw in raw_items:
+                item = self._deserialize(raw)
+                marker = serialize_key({attr: item.get(attr) for attr in key_attrs})
+                raw_by_marker[marker] = item
+
+        out: Dict[str, Optional[dict]] = {}
+        for key_id, _plain_key, marker in resolved:
+            if key_id in out:
+                continue  # a duplicate input key — already mapped.
+            raw = raw_by_marker.get(marker)
+            out[key_id] = (
+                hydrate_item(raw, select, entity_meta) if raw is not None else None
+            )
+        return out
+
+    # ── External Query composition (issue #63) ──────────────────────────────────
+
+    def _resolve_compositions(
+        self,
+        contract_name: str,
+        method_name: str,
+        compose: List[Mapping[str, Any]],
+        parents: List[Dict[str, Any]],
+        composition_plan: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        """Resolve every External Query composition (#63) on a method against the
+        already-resolved parent records, **mutating each in place** to attach the
+        composed value at the edge's ``as`` property, HONORING the composition plan
+        (issue #70b).
+
+        This is the DataLoader pattern across contracts: for each compose edge the
+        bound child key is collected from **all** parent records (via the
+        declarative ``from`` paths), then the referenced child contract method is
+        resolved **once, batched** — N parents collapse to **one**
+        ``BatchGetItem`` (the child is ``point``, enforced by the #60 N+1
+        checker), so there is no N+1 fan-out. Each parent then receives its child
+        (or an explicit ``None`` when the child key is absent / the item missing).
+
+        The ``compositionPlan`` (issue #70a) declares which compositions are
+        independent (a stage of ``compose[]`` indices) and the in-flight bound.
+        Independent compositions write **disjoint** ``as`` properties and each
+        issues its own batched child read, so this runtime resolves the
+        compositions of a stage **concurrently** under the declared bound (#70b).
+        With **no** plan (backward compatibility), the compositions are resolved
+        sequentially in declared order — the pre-#70b behavior.
+        """
+        if not compose or not parents:
+            return
+        stages = self._composition_stages(composition_plan, len(compose))
+        concurrency = self._composition_concurrency(composition_plan)
+        for stage in stages:
+            stage_edges = [compose[i] for i in stage]
+            # Independent compositions of one stage → bounded-concurrent resolve.
+            # The helper preserves order and runs a single-edge stage inline.
+            map_with_concurrency(
+                stage_edges,
+                concurrency,
+                lambda edge, _i: self._resolve_composition(
+                    contract_name, method_name, edge, parents
+                ),
+            )
+
+    @staticmethod
+    def _composition_stages(
+        composition_plan: Optional[Mapping[str, Any]], compose_count: int
+    ) -> List[List[int]]:
+        """The ordered composition stages (indices into ``compose[]``).
+
+        Reads ``compositionPlan.stages`` (issue #70a) when present, skipping empty
+        stages and dropping any out-of-range index defensively. Falls back to one
+        stage holding **all** compositions in declared order when the plan is absent
+        — note the pre-#70b runtime resolved them sequentially, but a single
+        all-in-one stage with a ``concurrency`` of 1 (the plan-less default below)
+        is the same sequential resolution; with a real plan the same stage runs
+        concurrently. To preserve exact pre-#70b behavior when no plan is present,
+        the caller's concurrency falls back to 1 (see
+        :meth:`_composition_concurrency`).
+        """
+        if composition_plan and isinstance(composition_plan.get("stages"), list):
+            stages: List[List[int]] = []
+            for stage in composition_plan["stages"]:
+                indices = [i for i in stage if 0 <= i < compose_count]
+                if indices:
+                    stages.append(indices)
+            if stages:
+                return stages
+        # No plan → one stage with all compositions, resolved sequentially (the
+        # plan-less concurrency is 1, so this matches the pre-#70b in-order loop).
+        return [list(range(compose_count))]
+
+    @staticmethod
+    def _composition_concurrency(
+        composition_plan: Optional[Mapping[str, Any]]
+    ) -> int:
+        """The declared in-flight bound for composition stages.
+
+        With a plan, the serialized ``concurrency`` (16). **Without** a plan, ``1``
+        — so the fallback single all-in-one stage resolves sequentially, preserving
+        the exact pre-#70b behavior for a plan-less spec (backward compatibility).
+        """
+        plan = composition_plan or {}
+        concurrency = plan.get("concurrency")
+        if isinstance(concurrency, int) and concurrency > 0:
+            return concurrency
+        return 1
+
+    def _resolve_composition(
+        self,
+        contract_name: str,
+        method_name: str,
+        edge: Mapping[str, Any],
+        parents: List[Dict[str, Any]],
+    ) -> None:
+        """Resolve one compose edge across all parents (one batched child read)."""
+        as_prop = edge["as"]
+        if edge.get("resolution") != "point":
+            # The #60 N+1 checker rejects a `range` child at build; runtime
+            # backstop so the executor never silently fans out.
+            raise GraphDDBError(
+                f"{contract_name}.{method_name}: composed child '{as_prop}' resolves "
+                f"to a 'range' method, but an External Query child must be 'point' so "
+                f"it coalesces to one BatchGetItem across all parent records."
+            )
+        child_contract = edge["contract"]
+        child_method_name = edge["method"]
+        child_method = self._resolve_contract_query_method(
+            child_contract, child_method_name
+        )
+        child_op_spec = self._contract_query_op(
+            child_contract, child_method_name, child_method
+        )
+        bind: Mapping[str, str] = edge.get("bind", {})
+
+        # Collect the bound child key from each parent record. A parent whose
+        # bound path is absent / None cannot resolve a child → explicit None.
+        bound: List[tuple] = []  # (parent, child_key, key_id)
+        child_keys: List[Dict[str, Any]] = []
+        for parent in parents:
+            child_key: Dict[str, Any] = {}
+            complete = True
+            for field, path in bind.items():
+                value = _read_from_path(parent, path)
+                if value is None:
+                    complete = False
+                    break
+                child_key[field] = value
+            if not complete:
+                parent[as_prop] = None
+                continue
+            bound.append((parent, child_key, serialize_contract_key(child_key)))
+            child_keys.append(child_key)
+
+        if not child_keys:
+            return
+
+        # ONE batched child read across every parent's bound key (point →
+        # BatchGetItem, reusing the keyed-batch path). N parents → 1 request.
+        child_results = self._execute_point_batch(
+            child_contract, child_method_name, child_op_spec, child_keys
+        )
+
+        for parent, _child_key, key_id in bound:
+            parent[as_prop] = child_results.get(key_id)
+
+    def execute_command(
+        self,
+        command_id: str,
+        params: Mapping[str, Any],
+        options: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        spec = self._commands.get(command_id)
+        if spec is None:
+            raise CommandNotFoundError(f"unknown command '{command_id}'")
+
+        validate_params(params, spec.get("params", {}), operation_id=command_id)
+
+        op_type = spec["type"]
+        if op_type == "PutItem":
+            self._run_put_item(command_id, spec, params)
+        elif op_type == "UpdateItem":
+            self._run_update_item(command_id, spec, params)
+        elif op_type == "DeleteItem":
+            self._run_delete_item(command_id, spec, params)
+        else:  # pragma: no cover - schema only allows the three above
+            raise GraphDDBError(f"{command_id}: unknown command type '{op_type}'")
+
+    def execute_transaction(
+        self,
+        transaction_id: str,
+        params: Mapping[str, Any],
+    ) -> None:
+        """Execute a declarative transaction (issue #46).
+
+        Validates params (including array ``forEach`` sources), expands the spec
+        into a ``TransactWriteItems`` request (≤25 after expansion), and runs it
+        via boto3 ``transact_write_items``. A failed transaction
+        (``TransactionCanceledException``) is wrapped in
+        :class:`OperationExecutionError`. A transaction that expands to zero items
+        is a no-op.
+        """
+        spec = self._transactions.get(transaction_id)
+        if spec is None:
+            raise TransactionNotFoundError(f"unknown transaction '{transaction_id}'")
+
+        validate_params(params, spec.get("params", {}), operation_id=transaction_id)
+
+        expander = TransactionExpander(self)
+        transact_items = expander.expand(spec, params)
+
+        if len(transact_items) > MAX_TRANSACT_ITEMS:
+            raise LimitExceededError(
+                f"{transaction_id}: transaction expanded to {len(transact_items)} "
+                f"items, exceeds the DynamoDB TransactWriteItems limit of "
+                f"{MAX_TRANSACT_ITEMS}"
+            )
+        if not transact_items:
+            return
+
+        self._call(
+            transaction_id,
+            self._client.transact_write_items,
+            {"TransactItems": transact_items},
+        )
+
+    # ── command-contract execution (issue #64) ──────────────────────────────
+
+    def execute_command_method(
+        self,
+        contract_name: str,
+        method_name: str,
+        key_or_keys: Any,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> Optional[dict]:
+        """Execute one CQRS **command**-contract method (issue #64; proposal
+        "Command Contract" + "Command Definition").
+
+        A command method maps a **single key** to one write op (``put`` /
+        ``update`` / ``delete``) and an **array of keys** to a batched write per
+        the method's declared mode:
+
+        - ``single`` key  → the one referenced write op in ``commands``;
+        - ``keys[]`` + ``transact``   → one ``TransactWriteItems`` (the synthesized
+          per-key ``forEach`` transaction; **atomic**, ≤25, condition-capable). An
+          array of **>25 keys is rejected** — an atomic transaction cannot be split.
+        - ``keys[]`` + ``batchWrite`` → a ``BatchWriteItem`` (**non-atomic**, **no
+          conditions**), chunked ≤25 per request with ``UnprocessedItems`` retry.
+
+        ``params`` are the mutation values shared across every key (the body's
+        ``params`` argument). For each key the runtime merges ``{**key, **params}``
+        to drive the underlying single write op, exactly as the TS runtime does, so
+        the two produce **identical effects** for the same SSoT.
+
+        :raises ContractNotFoundError: unknown contract / method, or a query
+            contract was addressed.
+        :raises ContractArityError: a key array fed to a method with no batched
+            form.
+        :raises LimitExceededError: a >25-key ``transact`` batch.
+        """
+        method = self._resolve_contract_command_method(contract_name, method_name)
+        shared = dict(params or {})
+
+        if isinstance(key_or_keys, list):
+            self._execute_command_batch(
+                contract_name, method_name, method, key_or_keys, shared
+            )
+            return None
+
+        # Single key → the referenced write surface, driven by key + params.
+        single = method["single"]
+        merged = {**dict(key_or_keys), **shared}
+        mode = single.get("mode", "op")
+        if mode == "transaction":
+            # #90: a MULTI-fragment mutation composes 2+ write fragments into ONE
+            # atomic `TransactWriteItems`. The serializer emits a no-`forEach`
+            # transaction (a fixed composed write set) whose item templates are the
+            # same shared-param `{param}` bindings a single-op write uses — the
+            # cross-fragment data dependencies were resolved at compile time into
+            # shared-param references. Execute it atomically; a condition failure on
+            # any fragment rolls back the WHOLE transaction (DynamoDB atomicity),
+            # identically to the TS runtime's `executeTransactWrites`.
+            self.execute_transaction(single["transaction"], merged)
+        else:
+            command_id = single["operation"]
+            self.execute_command(command_id, merged)
+
+        # #83: a `mutation`-derived method that declares a return projection
+        # resolves its result as a CONSISTENT read-back of the written entity. After
+        # the write commits, GetItem the written entity's primary key with
+        # ConsistentRead and project the declared `returnSelection` via the EXISTING
+        # read-projection machinery — the UNIFORM return mechanism for both a single
+        # op and the future #90 transaction (a TransactWriteItems returns no item
+        # image), so TS and Python return an IDENTICAL projected item.
+        return_selection = method.get("returnSelection")
+        if return_selection:
+            return self._read_back_projection(
+                contract_name, method_name, merged
+            )
+        return None
+
+    def _read_back_projection(
+        self,
+        contract_name: str,
+        method_name: str,
+        params: Mapping[str, Any],
+    ) -> Optional[dict]:
+        """Run the synthesized consistent read-back query for a command method.
+
+        The serializer (#83) emits a base-table ``GetItem`` query named
+        ``<Contract>__<method>__readback`` projecting the return-selection fields;
+        its ``keyCondition`` templates reference the written entity's primary-key
+        fields (``{field}``), which are present in the merged ``params`` (the key +
+        shared input). Resolve it with ``ConsistentRead`` through the proven
+        ``_run_get_item`` path so the projection is request-identical to the TS
+        runtime's ``executeQuery`` read-back.
+        """
+        readback_id = f"{contract_name}__{method_name}__readback"
+        spec = self._queries.get(readback_id)
+        if spec is None:
+            raise GraphDDBError(
+                f"{contract_name}.{method_name}: declares a return projection but the "
+                f"read-back query '{readback_id}' is not present in `queries`."
+            )
+        op = spec["operations"][0]
+        if op["type"] != "GetItem":
+            raise GraphDDBError(
+                f"{contract_name}.{method_name}: the read-back op '{readback_id}' must "
+                f"be a base-table GetItem, found '{op['type']}'."
+            )
+        select = self._select_from_projection(op)
+        entity_meta = self._resolve_entity(op)
+        return self._run_get_item(
+            f"{contract_name}.{method_name}__readback",
+            op,
+            params,
+            select,
+            entity_meta,
+            consistent_read=True,
+        )
+
+    def _execute_command_batch(
+        self,
+        contract_name: str,
+        method_name: str,
+        method: Mapping[str, Any],
+        keys: List[Mapping[str, Any]],
+        shared: Mapping[str, Any],
+    ) -> None:
+        """Apply a command method's array form per its declared batch target."""
+        batch = method.get("batch")
+        label = f"{contract_name}.{method_name}"
+        if batch is None:
+            raise ContractArityError(
+                f"command method '{label}' was called with an array of keys, but it "
+                f"declares no batched-write form. Declare a 'transact' or 'batchWrite' "
+                f"batch on the method, or call it with a single key."
+            )
+        mode = batch.get("mode")
+        if mode == "transaction":
+            # The synthesized transaction expands one item per key (≤25, atomic). The
+            # element shape is the contract Key fields; the shared params are scalars.
+            self.execute_transaction(
+                batch["transaction"], {**dict(shared), "keys": [dict(k) for k in keys]}
+            )
+            return
+        if mode == "batchWrite":
+            self._execute_batch_write(label, batch["operation"], keys, shared)
+            return
+        raise GraphDDBError(  # pragma: no cover - serializer only emits the two above
+            f"{label}: unknown batch resolution mode '{mode}'"
+        )
+
+    def _execute_batch_write(
+        self,
+        label: str,
+        command_id: str,
+        keys: List[Mapping[str, Any]],
+        shared: Mapping[str, Any],
+    ) -> None:
+        """Apply a ``BatchWriteItem`` over the per-key write op (no conditions).
+
+        Reuses :class:`BatchWriteExecutor` (chunk ≤25, ``UnprocessedItems`` retry).
+        DynamoDB's ``BatchWriteItem`` supports only ``PutRequest`` / ``DeleteRequest``
+        — a command whose single-key op is an ``UpdateItem`` cannot resolve its
+        array form to a ``BatchWriteItem`` (it must declare ``transact``).
+        """
+        spec = self._commands.get(command_id)
+        if spec is None:
+            raise ContractNotFoundError(
+                f"{label}: referenced write op '{command_id}' is not present in "
+                f"`commands`."
+            )
+        op_type = spec["type"]
+        if op_type == "UpdateItem":
+            raise GraphDDBError(
+                f"{label}: 'batchWrite' only supports put / delete (DynamoDB's "
+                f"BatchWriteItem has no Update request). Declare a 'transact' batch "
+                f"for a batched update."
+            )
+        requests: List[Dict[str, Any]] = []
+        for key in keys:
+            params = {**dict(key), **dict(shared)}
+            validate_params(params, spec.get("params", {}), operation_id=command_id)
+            if op_type == "PutItem":
+                item = {
+                    field: self._serializer.serialize(resolve_template(tmpl, params))
+                    for field, tmpl in spec.get("item", {}).items()
+                }
+                self._add_key_attributes(spec["entity"], item, params)
+                requests.append({"PutRequest": {"Item": item}})
+            else:  # DeleteItem
+                dynamo_key = {
+                    attr: self._serializer.serialize(resolve_template(tmpl, params))
+                    for attr, tmpl in spec["keyCondition"].items()
+                }
+                requests.append({"DeleteRequest": {"Key": dynamo_key}})
+
+        executor = BatchWriteExecutor(self._client, boto_errors=_BOTO_ERRORS)
+        executor.write(self._physical_table(spec["tableName"]), requests)
+
+    def _resolve_contract_command_method(
+        self, contract_name: str, method_name: str
+    ) -> Mapping[str, Any]:
+        contract = self._contracts.get(contract_name)
+        if contract is None:
+            available = ", ".join(sorted(self._contracts.keys())) or "(none)"
+            raise ContractNotFoundError(
+                f"unknown contract '{contract_name}'. Available: {available}"
+            )
+        if contract.get("kind") != "command":
+            raise ContractNotFoundError(
+                f"contract '{contract_name}' is a '{contract.get('kind')}' contract; "
+                f"execute_command_method only runs command contracts (queries use "
+                f"execute_query_method)."
+            )
+        methods = contract.get("methods", {})
+        method = methods.get(method_name)
+        if method is None:
+            available = ", ".join(sorted(methods.keys())) or "(none)"
+            raise ContractNotFoundError(
+                f"contract '{contract_name}' has no command method '{method_name}'. "
+                f"Available: {available}"
+            )
+        return method
+
+    def explain(self, query_id: str, params: Mapping[str, Any]) -> dict:
+        """Return the resolved operation list for a query without touching DynamoDB.
+
+        Templates are resolved with the supplied ``params`` (``{result.*}``
+        placeholders are left intact — they are bound from prior results only at
+        execution time). The shape mirrors the operations spec so callers can see
+        exactly which physical operations a query would issue.
+        """
+        spec = self._queries.get(query_id)
+        if spec is None:
+            raise QueryNotFoundError(f"unknown query '{query_id}'")
+        validate_params(params, spec.get("params", {}), operation_id=query_id)
+
+        resolved_ops: List[Dict[str, Any]] = []
+        for op in spec.get("operations", []):
+            resolved: Dict[str, Any] = {
+                "type": op["type"],
+                "tableName": self._physical_table(op["tableName"]),
+                "keyCondition": {
+                    attr: self._resolve_partial(tmpl, params)
+                    for attr, tmpl in op.get("keyCondition", {}).items()
+                },
+                "projection": list(op.get("projection", [])),
+                "resultPath": op.get("resultPath", "$"),
+            }
+            if op.get("indexName"):
+                resolved["indexName"] = op["indexName"]
+            if op.get("rangeCondition"):
+                rc = op["rangeCondition"]
+                resolved["rangeCondition"] = {
+                    "operator": rc["operator"],
+                    "key": rc["key"],
+                    "value": self._resolve_partial(rc["value"], params),
+                }
+            if op.get("limit") is not None:
+                resolved["limit"] = op["limit"]
+            if op.get("filter"):
+                resolved["filter"] = op["filter"]
+            if op.get("sourceField"):
+                resolved["sourceField"] = op["sourceField"]
+            resolved_ops.append(resolved)
+
+        return {
+            "queryId": query_id,
+            "cardinality": spec.get("cardinality"),
+            "operations": resolved_ops,
+        }
+
+    # ── limits ──────────────────────────────────────────────────────────────────
+
+    def _enforce_operation_limits(
+        self, query_id: str, operations: List[Dict[str, Any]]
+    ) -> None:
+        if not operations:
+            raise GraphDDBError(f"{query_id}: query has no operations")
+        if len(operations) > self._limits.max_operations:
+            raise LimitExceededError(
+                f"{query_id}: query needs {len(operations)} operations, exceeds "
+                f"max_operations {self._limits.max_operations}"
+            )
+        depth = self._max_relation_depth(operations)
+        if depth > self._limits.max_depth:
+            raise LimitExceededError(
+                f"{query_id}: relation traversal depth {depth} exceeds max_depth "
+                f"{self._limits.max_depth}"
+            )
+
+    @staticmethod
+    def _max_relation_depth(operations: List[Dict[str, Any]]) -> int:
+        """Deepest relation nesting, counting each ``.items``/single-value hop.
+
+        The root op (``$``) is depth 0; ``$.groups.items`` is depth 1;
+        ``$.groups.items.group`` is depth 2; ``$.groups.items.group.permissions.items``
+        is depth 3 — matching the TS ``validateDepth`` currentDepth counting where
+        each relation level increments depth.
+        """
+        max_depth = 0
+        for op in operations[1:]:
+            path = op.get("resultPath", "$")
+            if path in ("$", ""):
+                continue
+            tokens = path[2:].split(".")
+            # Each non-`items` token is one relation hop.
+            depth = sum(1 for t in tokens if t != "items")
+            max_depth = max(max_depth, depth)
+        return max_depth
+
+    # ── root operation ──────────────────────────────────────────────────────────
+
+    def _run_root(
+        self,
+        query_id: str,
+        op: Mapping[str, Any],
+        params: Mapping[str, Any],
+        options: Mapping[str, Any],
+        cardinality: Optional[str],
+    ) -> Optional[dict]:
+        select = self._select_from_projection(op)
+        entity_meta = self._resolve_entity(op)
+        op_type = op["type"]
+
+        if op_type == "GetItem":
+            return self._run_get_item(query_id, op, params, select, entity_meta)
+
+        if op_type == "Query":
+            connection = self._run_query(
+                query_id, op, params, select, entity_meta, options
+            )
+            # A `defineQuery` root with declared cardinality 'one' is a single
+            # entity object regardless of whether relations are assembled onto it:
+            # take the first matched item (None if absent). This matches the
+            # generated flat result type and the TS live executor, which returns
+            # a single object for a cardinality-one Query. A 'many' root (or an
+            # absent cardinality, which defaults to 'many') keeps the connection
+            # shape `{items, cursor}`.
+            wants_single = cardinality == "one"
+            if wants_single:
+                items = connection["items"]
+                return items[0] if items else None
+            return connection
+
+        raise GraphDDBError(
+            f"{query_id}: unsupported root read operation '{op_type}'"
+        )
+
+    # ── relation operations ───────────────────────────────────────────────────────
+
+    def _run_relation_query(
+        self,
+        query_id: str,
+        op: Mapping[str, Any],
+        source_values: Mapping[str, Any],
+    ) -> Dict[str, Any]:
+        select = self._select_from_projection(op)
+        entity_meta = self._resolve_entity(op)
+        ctx = self._result_context(source_values)
+        return self._run_query(
+            query_id, op, ctx, select, entity_meta, options={}, is_relation=True
+        )
+
+    def _run_relation_batch_get(
+        self,
+        query_id: str,
+        op: Mapping[str, Any],
+        source_values: List[Mapping[str, Any]],
+    ) -> Dict[str, str]:
+        select = self._select_from_projection(op)
+        entity_meta = self._resolve_entity(op)
+
+        # Build (deduped) plain keys + their serialized markers.
+        plain_keys: List[Dict[str, Any]] = []
+        seen: set = set()
+        for sv in source_values:
+            ctx = self._result_context(sv)
+            plain_key = {
+                attr: resolve_template(tmpl, ctx)
+                for attr, tmpl in op["keyCondition"].items()
+            }
+            marker = serialize_key(plain_key)
+            if marker in seen:
+                continue
+            seen.add(marker)
+            plain_keys.append(plain_key)
+
+        # The executor chunks at max_batch_get_items; a hard ceiling on the total
+        # deduped key count also fails a runaway fan-out fast rather than issuing
+        # an unbounded number of chunks.
+        if len(plain_keys) > self._limits.max_items:
+            raise LimitExceededError(
+                f"{query_id}: BatchGet needs {len(plain_keys)} keys, exceeds "
+                f"max_items {self._limits.max_items}"
+            )
+
+        serialized_keys = [
+            {attr: self._serializer.serialize(v) for attr, v in key.items()}
+            for key in plain_keys
+        ]
+
+        executor = BatchGetExecutor(
+            self._client,
+            boto_errors=_BOTO_ERRORS,
+            max_batch_get_items=self._limits.max_batch_get_items,
+        )
+        request_extra = self._projection_request(op, select)
+        raw_items = executor.get(
+            self._physical_table(op["tableName"]), serialized_keys, request_extra
+        )
+
+        key_attrs = list(op["keyCondition"].keys())
+        key_to_item: Dict[str, str] = {}
+        for raw in raw_items:
+            item = self._deserialize(raw)
+            marker = serialize_key({attr: item.get(attr) for attr in key_attrs})
+            key_to_item[marker] = hydrate_item(item, select, entity_meta)
+        return key_to_item
+
+    def _relation_key_marker(
+        self, op: Mapping[str, Any], source_values: Mapping[str, Any]
+    ) -> str:
+        ctx = self._result_context(source_values)
+        plain_key = {
+            attr: resolve_template(tmpl, ctx)
+            for attr, tmpl in op["keyCondition"].items()
+        }
+        return serialize_key(plain_key)
+
+    @staticmethod
+    def _result_context(source_values: Mapping[str, Any]) -> Dict[str, Any]:
+        """Map ``{source_field: value}`` to the ``result.<field>`` template names."""
+        return {f"result.{field}": value for field, value in source_values.items()}
+
+    # ── helpers: planning / resolution ──────────────────────────────────────────
+
+    def _physical_table(self, logical: str) -> str:
+        return self._table_mapping.get(logical, logical)
+
+    def _select_from_projection(self, op: Mapping[str, Any]) -> Dict[str, Any]:
+        return {field: True for field in op.get("projection", [])}
+
+    def _resolve_partial(self, template: str, params: Mapping[str, Any]) -> str:
+        """Resolve ``{param}`` placeholders, leaving ``{result.*}`` intact (explain)."""
+
+        def repl(match: "re.Match[str]") -> str:
+            name = match.group(0)[1:-1]
+            if name.startswith("result."):
+                return match.group(0)
+            return str(params.get(name, match.group(0)))
+
+        return _PLACEHOLDER_RE.sub(repl, template)
+
+    def _resolve_entity(self, op: Mapping[str, Any]) -> Dict[str, Any]:
+        """Find the manifest entity a read operation targets, for hydration.
+
+        Strict, insertion-order independent matching (issue #45 follow-up). A
+        candidate entity must:
+
+        1. live on the operation's logical table;
+        2. have a key/GSI whose placeholder-normalized PK template matches the
+           operation's PK template;
+        3. agree on the sort-key predicate:
+           - explicit SK in the keyCondition → equal to the entity's SK template;
+           - ``begins_with`` range on the SK → the entity's SK template must start
+             with the range value's literal prefix;
+           - no SK predicate (a base-table partition Query) → the entity must
+             carry **all** projected fields, which disambiguates same-prefix
+             entities sharing a partition (e.g. Group vs GroupMembership vs
+             Permission under ``GROUP#``). Among several such candidates a unique
+             superset match wins; otherwise the match is rejected so hydration
+             never silently picks the wrong entity (and drops datetime formats).
+
+        Returns an empty meta (no formats) only when nothing matches.
+        """
+        table = op["tableName"]
+        index_name = op.get("indexName")
+        kc = op.get("keyCondition", {})
+        projection = set(op.get("projection", []))
+
+        candidates: List[Dict[str, Any]] = []
+        for entity_meta in self._entities.values():
+            if entity_meta.get("table") != table:
+                continue
+            if index_name is None:
+                key = entity_meta.get("key")
+                if not key:
+                    continue
+                # The segment key model (#51) makes pkTemplate self-contained
+                # (it carries the entity discriminator), so the entity prefix is
+                # no longer prepended.
+                pk_tmpl = key.get("pkTemplate") or ""
+                sk_tmpl = key.get("skTemplate")
+                match = self._key_match_kind(kc, op, "PK", pk_tmpl, "SK", sk_tmpl)
+            else:
+                match = None
+                for gsi in entity_meta.get("gsis", []):
+                    if gsi.get("indexName") != index_name:
+                        continue
+                    pk_attr = f"{index_name}PK"
+                    sk_attr = f"{index_name}SK"
+                    match = self._key_match_kind(
+                        kc,
+                        op,
+                        pk_attr,
+                        gsi.get("pkTemplate"),
+                        sk_attr,
+                        gsi.get("skTemplate"),
+                    )
+                    if match:
+                        break
+            if not match:
+                continue
+            candidates.append((match, entity_meta))
+
+        if not candidates:
+            return {"fields": {}}
+
+        # Prefer an exact sort-key predicate match (explicit SK or begins_with);
+        # these are unambiguous.
+        exact = [meta for (kind, meta) in candidates if kind == "exact"]
+        if len(exact) == 1:
+            return exact[0]
+        if len(exact) > 1:
+            exact = self._disambiguate_by_projection(exact, projection)
+            if len(exact) == 1:
+                return exact[0]
+
+        # No SK predicate (partition Query): disambiguate by projection coverage.
+        partition = [meta for (kind, meta) in candidates if kind == "partition"]
+        pool = exact or partition or [meta for (_k, meta) in candidates]
+        narrowed = self._disambiguate_by_projection(pool, projection)
+        if len(narrowed) == 1:
+            return narrowed[0]
+        # Ambiguous: refuse to guess so datetime restoration is not silently
+        # taken from the wrong entity.
+        return {"fields": {}}
+
+    @staticmethod
+    def _disambiguate_by_projection(
+        candidates: List[Dict[str, Any]], projection: set
+    ) -> List[Dict[str, Any]]:
+        if not projection:
+            return candidates
+        covering = [
+            meta
+            for meta in candidates
+            if projection.issubset(set(meta.get("fields", {}).keys()))
+        ]
+        return covering or candidates
+
+    def _key_match_kind(
+        self,
+        kc: Mapping[str, Any],
+        op: Mapping[str, Any],
+        pk_attr: str,
+        pk_tmpl: Optional[str],
+        sk_attr: str,
+        sk_tmpl: Optional[str],
+    ) -> Optional[str]:
+        """Return 'exact' / 'partition' if the entity key matches, else None.
+
+        'exact'     — the PK matches and the SK predicate (equality or
+                      begins_with) aligns with the entity's SK template.
+        'partition' — the PK matches and the op has no SK predicate (so the SK is
+                      undetermined; the caller disambiguates by projection).
+        """
+        if _normalize_template(kc.get(pk_attr)) != _normalize_template(pk_tmpl):
+            return None
+
+        op_sk = kc.get(sk_attr)
+        if op_sk is not None:
+            return (
+                "exact"
+                if _normalize_template(op_sk) == _normalize_template(sk_tmpl)
+                else None
+            )
+
+        rng = op.get("rangeCondition")
+        if rng is not None and rng.get("key") == sk_attr:
+            if sk_tmpl is None:
+                return None
+            # begins_with: the entity SK template must start with the range's
+            # literal prefix (everything up to the first placeholder).
+            literal_prefix = _PLACEHOLDER_RE.split(rng.get("value", ""))[0]
+            if literal_prefix and not sk_tmpl.startswith(literal_prefix):
+                return None
+            return "exact"
+
+        # No SK predicate at all.
+        return "partition"
+
+    # ── helpers: read execution ────────────────────────────────────────────────
+
+    def _projection_request(
+        self, op: Mapping[str, Any], select: Mapping[str, Any]
+    ) -> Dict[str, Any]:
+        """Build ProjectionExpression / names for a BatchGet, including key attrs.
+
+        Key attributes (PK/SK or GSI keys) are added so items can be matched back
+        to parents, mirroring ``planBatchGetForQueryKeys`` which adds the key
+        fields to the projection.
+        """
+        fields = [f for f, v in select.items() if v is True]
+        # Always project the key attributes used for matching.
+        for attr in op.get("keyCondition", {}).keys():
+            if attr not in fields:
+                fields.append(attr)
+        if not fields:
+            return {}
+        names = {f"#p{i}": f for i, f in enumerate(fields)}
+        return {
+            "ProjectionExpression": ", ".join(names.keys()),
+            "ExpressionAttributeNames": names,
+        }
+
+    def _run_get_item(
+        self,
+        query_id: str,
+        op: Mapping[str, Any],
+        params: Mapping[str, Any],
+        select: Mapping[str, Any],
+        entity_meta: Mapping[str, Any],
+        consistent_read: bool = False,
+    ) -> Optional[dict]:
+        key = {
+            attr: self._serializer.serialize(resolve_template(tmpl, params))
+            for attr, tmpl in op["keyCondition"].items()
+        }
+        request: Dict[str, Any] = {
+            "TableName": self._physical_table(op["tableName"]),
+            "Key": key,
+        }
+        # Strongly-consistent point read on the base table (issue #65). The TS
+        # runtime sets ``ConsistentRead`` on a base-table GetItem when the contract
+        # method's ``consistentRead`` retrieval option is truthy
+        # (``src/executor/executor.ts`` ``executeGetItem``); wire it here so the two
+        # runtimes issue the **identical** GetItem request — closing the parity gap
+        # surfaced by #62's audit (Python previously ignored ``consistentRead``).
+        if consistent_read:
+            request["ConsistentRead"] = True
+        resp = self._call(query_id, self._client.get_item, request)
+        raw = resp.get("Item")
+        if raw is None:
+            return None
+        item = self._deserialize(raw)
+        return hydrate_item(item, select, entity_meta)
+
+    def _run_query(
+        self,
+        query_id: str,
+        op: Mapping[str, Any],
+        params: Mapping[str, Any],
+        select: Mapping[str, Any],
+        entity_meta: Mapping[str, Any],
+        options: Mapping[str, Any],
+        is_relation: bool = False,
+    ) -> Dict[str, Any]:
+        names: Dict[str, str] = {}
+        values: Dict[str, Any] = {}
+        clauses: List[str] = []
+        kc = op["keyCondition"]
+
+        for i, (attr, tmpl) in enumerate(kc.items()):
+            n = f"#k{i}"
+            v = f":k{i}"
+            names[n] = attr
+            values[v] = self._serializer.serialize(resolve_template(tmpl, params))
+            clauses.append(f"{n} = {v}")
+
+        rng = op.get("rangeCondition")
+        if rng is not None:
+            n = "#kr"
+            v = ":kr"
+            names[n] = rng["key"]
+            values[v] = self._serializer.serialize(
+                resolve_template(rng["value"], params)
+            )
+            if rng["operator"] == "begins_with":
+                clauses.append(f"begins_with({n}, {v})")
+            else:  # pragma: no cover - only begins_with is specified
+                raise GraphDDBError(f"unsupported range operator '{rng['operator']}'")
+
+        request: Dict[str, Any] = {
+            "TableName": self._physical_table(op["tableName"]),
+            "KeyConditionExpression": " AND ".join(clauses),
+            "ExpressionAttributeNames": names,
+            "ExpressionAttributeValues": values,
+        }
+        if op.get("indexName"):
+            request["IndexName"] = op["indexName"]
+
+        # Strongly-consistent read on a base-table Query (issue #65). The TS
+        # planner (``src/planner/planner.ts``) sets ``ConsistentRead`` only for a
+        # primary-key (base-table) query, so we mirror that for the valid case:
+        # honor ``consistentRead`` only when the op targets no secondary index. On a
+        # GSI-keyed read DynamoDB forbids a consistent read; TS *rejects* the
+        # combination with a hard error while this runtime drops the flag (a
+        # pre-existing #71 GSI-surface divergence, out of #65 scope). Every
+        # reachable base-table point Query is request-identical to TS.
+        if options.get("consistentRead") and not op.get("indexName"):
+            request["ConsistentRead"] = True
+
+        limit = op.get("limit")
+        if limit is not None:
+            if limit > self._limits.max_items:
+                raise LimitExceededError(
+                    f"{query_id}: limit {limit} exceeds max_items {self._limits.max_items}"
+                )
+            request["Limit"] = limit
+
+        filter_spec = op.get("filter")
+        if filter_spec and filter_spec.get("declarative"):
+            compiled = compile_filter(filter_spec["declarative"], self._serializer)
+            if compiled:
+                request["FilterExpression"] = compiled["FilterExpression"]
+                names.update(compiled["ExpressionAttributeNames"])
+                values.update(compiled["ExpressionAttributeValues"])
+
+        cursor = options.get("cursor")
+        if cursor:
+            request["ExclusiveStartKey"] = self._serialize_key(decode_cursor(cursor))
+
+        resp = self._call(query_id, self._client.query, request)
+        raw_items = resp.get("Items", [])
+        items = [
+            hydrate_item(self._deserialize(raw), select, entity_meta)
+            for raw in raw_items
+        ]
+        if len(items) > self._limits.max_items:
+            raise LimitExceededError(
+                f"{query_id}: returned {len(items)} items, exceeds max_items "
+                f"{self._limits.max_items}"
+            )
+
+        next_cursor: Optional[str] = None
+        lek = resp.get("LastEvaluatedKey")
+        if lek:
+            next_cursor = encode_cursor(self._deserialize(lek))
+
+        return {"items": items, "cursor": next_cursor}
+
+    # ── helpers: write execution ─────────────────────────────────────────────────
+
+    def _run_put_item(
+        self, command_id: str, spec: Mapping[str, Any], params: Mapping[str, Any]
+    ) -> None:
+        item_tmpl = spec.get("item", {})
+        item = {
+            field: self._serializer.serialize(resolve_template(tmpl, params))
+            for field, tmpl in item_tmpl.items()
+        }
+        self._add_key_attributes(spec["entity"], item, params)
+
+        request: Dict[str, Any] = {
+            "TableName": self._physical_table(spec["tableName"]),
+            "Item": item,
+        }
+        self._apply_condition(spec, request, params)
+        self._call(command_id, self._client.put_item, request)
+
+    def _run_update_item(
+        self, command_id: str, spec: Mapping[str, Any], params: Mapping[str, Any]
+    ) -> None:
+        key = {
+            attr: self._serializer.serialize(resolve_template(tmpl, params))
+            for attr, tmpl in spec["keyCondition"].items()
+        }
+        names: Dict[str, str] = {}
+        values: Dict[str, Any] = {}
+        sets: List[str] = []
+        for i, (field, tmpl) in enumerate(spec.get("changes", {}).items()):
+            n = f"#c{i}"
+            v = f":c{i}"
+            names[n] = field
+            values[v] = self._serializer.serialize(resolve_template(tmpl, params))
+            sets.append(f"{n} = {v}")
+
+        request: Dict[str, Any] = {
+            "TableName": self._physical_table(spec["tableName"]),
+            "Key": key,
+        }
+        if sets:
+            request["UpdateExpression"] = "SET " + ", ".join(sets)
+            request["ExpressionAttributeNames"] = names
+            request["ExpressionAttributeValues"] = values
+        self._apply_condition(spec, request, params)
+        self._call(command_id, self._client.update_item, request)
+
+    def _run_delete_item(
+        self, command_id: str, spec: Mapping[str, Any], params: Mapping[str, Any]
+    ) -> None:
+        key = {
+            attr: self._serializer.serialize(resolve_template(tmpl, params))
+            for attr, tmpl in spec["keyCondition"].items()
+        }
+        request: Dict[str, Any] = {
+            "TableName": self._physical_table(spec["tableName"]),
+            "Key": key,
+        }
+        self._apply_condition(spec, request, params)
+        self._call(command_id, self._client.delete_item, request)
+
+    def _apply_condition(
+        self,
+        spec: Mapping[str, Any],
+        request: Dict[str, Any],
+        params: Mapping[str, Any],
+    ) -> None:
+        condition = spec.get("condition")
+        if not condition:
+            return
+        names = request.setdefault("ExpressionAttributeNames", {})
+        kind = condition["kind"]
+        if kind == "notExists":
+            names["#pk"] = "PK"
+            request["ConditionExpression"] = "attribute_not_exists(#pk)"
+        elif kind in ("attributeExists", "attributeNotExists"):
+            # attribute_(not_)exists on any field (incl. PK/SK), issue #81. Routed
+            # through a "#ce" placeholder so reserved words / key attributes are
+            # always legal.
+            fn = (
+                "attribute_exists"
+                if kind == "attributeExists"
+                else "attribute_not_exists"
+            )
+            names["#ce"] = condition["field"]
+            request["ConditionExpression"] = f"{fn}(#ce)"
+        elif kind == "equals":
+            values = request.setdefault("ExpressionAttributeValues", {})
+            clauses = []
+            for i, (field, tmpl) in enumerate(condition["fields"].items()):
+                n = f"#e{i}"
+                v = f":e{i}"
+                names[n] = field
+                # Resolve `{param}` templates against the caller params before
+                # building the ConditionExpression value (issue #46: this was the
+                # #44 latent bug — the raw template was serialized verbatim, so a
+                # condition like `{version}` compared against the literal string
+                # "{version}" rather than the bound value).
+                resolved = resolve_template(tmpl, params)
+                values[v] = self._serializer.serialize(resolved)
+                clauses.append(f"{n} = {v}")
+            request["ConditionExpression"] = " AND ".join(clauses)
+
+    def _add_key_attributes(
+        self, entity_name: str, item: Dict[str, Any], params: Mapping[str, Any]
+    ) -> None:
+        entity_meta = self._entities.get(entity_name, {})
+        plain = {
+            field: self._deserializer.deserialize(av) for field, av in item.items()
+        }
+        key = entity_meta.get("key")
+        if key:
+            # pkTemplate is self-contained (segment key model #51); no prefix.
+            pk = self._fill(key.get("pkTemplate") or "", plain)
+            item["PK"] = self._serializer.serialize(pk)
+            sk_tmpl = key.get("skTemplate")
+            if sk_tmpl is not None:
+                item["SK"] = self._serializer.serialize(self._fill(sk_tmpl, plain))
+
+        for gsi in entity_meta.get("gsis", []):
+            index = gsi["indexName"]
+            pk_tmpl = gsi.get("pkTemplate")
+            sk_tmpl = gsi.get("skTemplate")
+            if pk_tmpl is not None and self._fillable(pk_tmpl, plain):
+                item[f"{index}PK"] = self._serializer.serialize(
+                    self._fill(pk_tmpl, plain)
+                )
+            if sk_tmpl is not None and self._fillable(sk_tmpl, plain):
+                item[f"{index}SK"] = self._serializer.serialize(
+                    self._fill(sk_tmpl, plain)
+                )
+
+    @staticmethod
+    def _fillable(template: str, values: Mapping[str, Any]) -> bool:
+        return all(
+            m.group(0)[1:-1] in values for m in _PLACEHOLDER_RE.finditer(template)
+        )
+
+    @staticmethod
+    def _fill(template: str, values: Mapping[str, Any]) -> str:
+        def repl(match: "re.Match[str]") -> str:
+            name = match.group(0)[1:-1]
+            return str(values.get(name, ""))
+
+        return _PLACEHOLDER_RE.sub(repl, template)
+
+    # ── helpers: boto3 plumbing ──────────────────────────────────────────────────
+
+    def _serialize_key(self, key: Mapping[str, Any]) -> Dict[str, Any]:
+        return {k: self._serializer.serialize(v) for k, v in key.items()}
+
+    def _deserialize(self, item: Mapping[str, Any]) -> Dict[str, Any]:
+        return {k: self._deserializer.deserialize(v) for k, v in item.items()}
+
+    def _call(self, operation_id: str, fn: Any, request: Dict[str, Any]) -> Any:
+        try:
+            return fn(**request)
+        except _BOTO_ERRORS as exc:  # type: ignore[misc]
+            raise OperationExecutionError(
+                f"{operation_id}: DynamoDB operation failed: {exc}", original=exc
+            ) from exc