graphddb-runtime 0.7.8__tar.gz → 0.7.9__tar.gz

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.9}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.7.8
+Version: 0.7.9
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: boto3>=1.26
+Requires-Dist: behavior-contracts==0.1.2
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.9}/graphddb_runtime/per_key_cursor.py

@@ -29,9 +29,10 @@ envelope shape does not branch on arity).
 
 from __future__ import annotations
 
-import json
 from typing import Any, Mapping, Optional
 
+from behavior_contracts import canonical_value as _canonical_value
+
 from .cursor import decode_cursor, encode_cursor
 
 
@@ -39,12 +40,23 @@ def serialize_contract_key(key: Mapping[str, Any]) -> str:
     """Canonical, cross-runtime-stable string identity of a contract key.
 
     Object fields are sorted by name so ``{a, b}`` and ``{b, a}`` serialize
-    identically; values are emitted via ``json.dumps`` with compact separators.
-    Matches the TS ``serializeContractKey`` (``JSON.stringify`` over a
-    field-sorted object), e.g. ``{"categoryId":"tech"}``.
+    identically; values are emitted as compact JSON. Matches the TS
+    ``serializeContractKey`` (``JSON.stringify`` over a field-sorted object),
+    e.g. ``{"categoryId":"tech"}``.
+
+    **WS4 adapter (behavior-contracts)**: this is the shared COMMON
+    ``canonicalValue`` primitive (runtime-boundary.md §2.1 →
+    canonical-serialization.md §2: key identity = top-level key sort + compact
+    JSON). graphddb now delegates to the extracted shared library instead of
+    re-implementing the field-sorted ``json.dumps``. Verified byte-for-byte
+    identical for every value shape a contract key carries (string / int / bool /
+    null / non-ASCII / nested-dict-insertion-order / array); both the shared and
+    the former graphddb impl reject non-JSON-scalar leaves such as ``Decimal``,
+    so the boundary is exact.
     """
-    ordered = {field: key[field] for field in sorted(key.keys())}
-    return json.dumps(ordered, separators=(",", ":"), ensure_ascii=False)
+    # ``canonical_value`` performs the top-level key sort + compact JSON itself,
+    # so pass the key mapping (as a plain dict) straight through.
+    return _canonical_value(dict(key))
 
 
 def encode_per_key_cursor(

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.9}/graphddb_runtime/runtime.py

@@ -19,6 +19,9 @@ from typing import Any, Dict, List, Mapping, Optional, Tuple
 
 from boto3.dynamodb.types import TypeDeserializer, TypeSerializer
 
+from behavior_contracts import EnvelopeFailure as _EnvelopeFailure
+from behavior_contracts import validate_envelope as _validate_envelope
+
 from .batch import BatchGetExecutor, BatchWriteExecutor, serialize_key
 from .concurrency import RELATION_TRAVERSAL_CONCURRENCY, map_with_concurrency
 from .cursor import decode_cursor, encode_cursor
@@ -83,26 +86,40 @@ def _validate_spec_version(document: Mapping[str, Any], label: str) -> None:
       (forward-rejected);
     - a missing / malformed version is rejected (an unversioned document
       cannot be trusted to match any vocabulary).
+
+    **WS4 adapter (behavior-contracts)**: the ``<major>.<minor>`` fail-closed
+    comparison mechanism is the shared COMMON ``validate_envelope`` primitive
+    (runtime-boundary.md §2.1 — ``validateEnvelope``: DynamoDB-agnostic version
+    check). graphddb now delegates the parse + major-equal / minor-<= rule to the
+    shared library (which reads the ``version`` field here) and re-raises the
+    shared ``EnvelopeFailure`` as graphddb's public ``GraphDDBError`` with the
+    same actionable wording (test contract preserved).
     """
-    version = document.get("version")
-    if not isinstance(version, str) or not re.fullmatch(r"\d+\.\d+", version):
-        raise GraphDDBError(
-            f"{label}: missing or malformed spec version {version!r} — expected "
-            f"'<major>.<minor>' (this runtime supports {SPEC_VERSION_SUPPORTED}). "
-            f"Regenerate the document with a matching graphddb generator."
+    try:
+        _validate_envelope(
+            document,
+            SPEC_VERSION_SUPPORTED,
+            field="version",
+            label=label,
+        )
+    except _EnvelopeFailure as exc:
+        version = document.get("version") if isinstance(document, Mapping) else None
+        if exc.code in ("MISSING_VERSION", "MALFORMED_VERSION"):
+            raise GraphDDBError(
+                f"{label}: missing or malformed spec version {version!r} — expected "
+                f"'<major>.<minor>' (this runtime supports {SPEC_VERSION_SUPPORTED}). "
+                f"Regenerate the document with a matching graphddb generator."
+            ) from exc
+        supported_major, supported_minor = (
+            int(part) for part in SPEC_VERSION_SUPPORTED.split(".")
         )
-    major, minor = (int(part) for part in version.split("."))
-    supported_major, supported_minor = (
-        int(part) for part in SPEC_VERSION_SUPPORTED.split(".")
-    )
-    if major != supported_major or minor > supported_minor:
         raise GraphDDBError(
             f"{label}: document spec version '{version}' is not supported by this "
             f"runtime (supports major {supported_major}, minor <= {supported_minor}). "
             f"A newer document may carry binding forms this runtime would silently "
             f"mis-execute; upgrade graphddb_runtime or regenerate the document with "
             f"a matching generator version."
-        )
+        ) from exc
 
 try:  # pragma: no cover - exercised indirectly
     from botocore.exceptions import BotoCoreError, ClientError

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.9}/graphddb_runtime/templates.py

@@ -16,12 +16,31 @@ from __future__ import annotations
 import re
 from typing import Any, Mapping
 
+from behavior_contracts import TemplateFailure as _TemplateFailure
+from behavior_contracts import render_template as _render_template
+
 from .errors import ParameterValidationError
 
 # A placeholder is `{` + name (no dot) + `}`. `{result.*}` is matched but flagged
 # separately by the executor so it can raise the multi-op error.
 _PLACEHOLDER = re.compile(r"\{([^{}]+)\}")
 
+# Names resolved by a *different* layer than the core `{param}` primitive:
+# `{result.*}` (relation-chain binding, resolved by the runPlan/relation layer)
+# and `{item.*}` (Map/forEach expansion). See runtime-boundary.md §4.1: the
+# shared `render_template` deliberately rejects these scopes (RESULT_SCOPE_IN_CORE)
+# because they belong to graphddb's relation execution, not to the DSL-agnostic
+# core. graphddb's `resolve_template` is overloaded to serve BOTH `{param}` key
+# rendering AND `{result.*}` binding, so the adapter only delegates the former.
+_NON_CORE_SCOPES = ("result.", "item.")
+
+
+def _has_non_core_scope(template: str) -> bool:
+    return any(
+        m.group(1).startswith(_NON_CORE_SCOPES)
+        for m in _PLACEHOLDER.finditer(template)
+    )
+
 
 def validate_params(
     params: Mapping[str, Any],
@@ -118,14 +137,45 @@ def resolve_template(template: str, params: Mapping[str, Any]) -> str:
     the single-table layout). Missing params should have been caught by
     :func:`validate_params`; a stray placeholder here raises
     :class:`ParameterValidationError`.
+
+    **WS4 adapter (behavior-contracts)** — this function is *overloaded* in
+    graphddb: it renders both the DSL-agnostic ``{param}`` primitive AND the
+    graphddb-specific ``{result.*}`` relation-chain binding (the relation layer
+    passes ``{"result.<field>": value}`` params with ``{result.<field>}``
+    templates, see ``runtime.py`` ``_relation_key_marker`` / belongsTo fan-out).
+    Per runtime-boundary.md §4.1 only the ``{param}`` case is COMMON, so:
+
+    - **pure ``{param}`` templates** → delegate to the shared COMMON
+      ``render_template`` (single source of truth for the `{param}` grammar,
+      strict missing-key, and Python-parity stringify). The shared
+      ``TemplateFailure(UNBOUND_PARAM)`` is translated to graphddb's
+      ``ParameterValidationError`` to preserve graphddb's public error contract.
+    - **templates carrying ``{result.*}`` / ``{item.*}``** → keep graphddb's own
+      substitution (the shared core deliberately rejects these scopes; they are
+      resolved by graphddb's relation execution layer, not by the DSL core).
+
+    This is the WS4 boundary correction: graphddb's ``resolve_template`` does
+    *more* than the shared ``render_template``, so it cannot be swapped wholesale
+    — the shared core is wired in for the primitive it genuinely owns.
     """
+    if _has_non_core_scope(template):
+        # CONSUMER-SPECIFIC relation-layer binding: substitute every `{name}`
+        # (including `{result.*}` / `{item.*}`) with its param value. This is the
+        # part the shared core does not own (runtime-boundary.md §4.1).
+        def repl(match: "re.Match[str]") -> str:
+            name = match.group(1)
+            if name not in params or params[name] is None:
+                raise ParameterValidationError(
+                    f"template '{template}' references unbound parameter '{name}'"
+                )
+            return str(params[name])
 
-    def repl(match: "re.Match[str]") -> str:
-        name = match.group(1)
-        if name not in params or params[name] is None:
-            raise ParameterValidationError(
-                f"template '{template}' references unbound parameter '{name}'"
-            )
-        return str(params[name])
+        return _PLACEHOLDER.sub(repl, template)
 
-    return _PLACEHOLDER.sub(repl, template)
+    # COMMON `{param}` primitive → shared behavior-contracts.
+    try:
+        return _render_template(template, params)
+    except _TemplateFailure as exc:
+        # Preserve graphddb's public error contract (ParameterValidationError)
+        # while routing the mechanism through the shared library.
+        raise ParameterValidationError(str(exc)) from exc

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.9}/graphddb_runtime.egg-info/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.7.8
+Version: 0.7.9
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: boto3>=1.26
+Requires-Dist: behavior-contracts==0.1.2
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.9}/graphddb_runtime.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ tests/test_description.py
 tests/test_description_followups.py
 tests/test_description_jsdoc.py
 tests/test_integration.py
+tests/test_integration_binding_contract.py
 tests/test_integration_command.py
 tests/test_integration_compose.py
 tests/test_integration_contract.py

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.9}/graphddb_runtime.egg-info/requires.txt

@@ -1,4 +1,5 @@
 boto3>=1.26
+behavior-contracts==0.1.2
 
 [test]
 pytest>=7.0

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.9}/pyproject.toml

@@ -4,12 +4,17 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphddb-runtime"
-version = "0.7.8"
+version = "0.7.9"
 description = "Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44)."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
-dependencies = ["boto3>=1.26"]
+# behavior-contracts (formerly dsl-contracts) epic (WS8): the COMMON runtime
+# primitives (spec-version validation, {param} template rendering, contract-key
+# canonicalisation) are delegated to the extracted shared package
+# ``behavior-contracts`` (import name ``behavior_contracts``). The runtime
+# imports it unconditionally, so it is a HARD dependency.
+dependencies = ["boto3>=1.26", "behavior-contracts==0.1.2"]
 
 [project.optional-dependencies]
 test = ["pytest>=7.0"]

graphddb_runtime-0.7.9/tests/test_integration_binding_contract.py

@@ -0,0 +1,425 @@
+"""Integration tests for the CONTRACT-typed Python bindings (issue #250 step 5).
+
+`test_integration_contract.py` proves the raw contract entry point
+(``execute_query_method`` / ``execute_command_method``) executes the serialized
+cardinality matrix correctly. THIS suite proves the #250 GENERATED layer on top:
+the contract-derived typed repository methods (``group_by_id__get``,
+``members_by_group__list``, ``member_access__get``, ``user_commands__set_tier``,
+…) call those entry points with the right key/params split and return results
+IDENTICAL to a raw entry-point call — for every #250 conformance dimension:
+
+  - point read           (``GroupById.get``  → ``Item | None``, miss → ``None``)
+  - unique-GSI point read (``UserByEmail.get`` → GSI Query, ``inputArity 'single'``)
+  - range read            (``MembersByGroup.list`` → ``{items, cursor}`` connection)
+  - range read WITH a live cursor (a >1MB partition page-breaks with NO retrieval
+    opts — v1 typed bindings expose none, #250 defers limit/after/order — so the
+    connection's ``cursor`` is genuinely non-None through the typed method)
+  - External Query composition (``MemberAccess.get`` → composed ``group`` via the
+    ``GroupById`` contract; absent parent composes ``None``)
+  - non-promoted single writes (``UserCommands.setTier`` update and
+    ``MembershipCommands.add`` create: ``single.mode == 'op'`` in the serialized
+    contract — a plain UpdateItem/PutItem, no transaction promotion)
+
+Cross-language note: the Go / Rust / PHP bindings-IT suites
+(``go/graphddb_bindings_it/contract_integration_test.go``,
+``rust/graphddb_bindings_it/tests/contract_integration.rs``,
+``php/tests/Integration/ContractBindingsIntegrationTest.php``) seed the SAME
+data (group ``g1``/Engineering, members alice=admin / bob=member, joinedAt
+2021-01-01/-02) and assert the SAME expected values, so the four runtimes are
+pinned to identical observable results for the typed contract surface.
+
+Requires DynamoDB Local on port 8000:
+    docker compose -f docker-compose.test.yml up -d
+
+Marked ``integration`` so it is skipped by ``-m "not integration"``.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+
+import boto3
+import pytest
+from botocore.config import Config
+
+import conftest
+from graphddb_runtime import GraphDDBRuntime
+
+pytestmark = pytest.mark.integration
+
+ENDPOINT = os.environ.get("DDB_LOCAL_ENDPOINT", "http://localhost:8000")
+TABLE = "UserPermissions"
+
+# ── the cross-language shared seed (mirrored in the Go / Rust / PHP suites) ────
+GROUP_ID = "g1"
+GROUP_NAME = "Engineering"
+GROUP_DESCRIPTION = "seeded"
+GROUP_CREATED_AT = "2020-01-01T00:00:00.000Z"
+MEMBERS = [
+    ("alice", "admin", "2021-01-01T00:00:00.000Z"),
+    ("bob", "member", "2021-01-02T00:00:00.000Z"),
+]
+USERS = [
+    ("alice", "alice@example.com", "Alice"),
+    ("bob", "bob@example.com", "Bob"),
+]
+
+
+def _load_generated_package():
+    """Import the generated bridge dir as the ``generated_bridge`` package."""
+    gen_dir = conftest.FIXTURES_DIR
+    pkg_name = "generated_bridge"
+    if pkg_name in sys.modules:
+        return sys.modules[pkg_name]
+    init = os.path.join(gen_dir, "__init__.py")
+    spec = importlib.util.spec_from_file_location(
+        pkg_name, init, submodule_search_locations=[gen_dir]
+    )
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[pkg_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.fixture(scope="module")
+def client():
+    cfg = Config(retries={"max_attempts": 2}, connect_timeout=2, read_timeout=10)
+    c = boto3.client(
+        "dynamodb",
+        endpoint_url=ENDPOINT,
+        region_name="local",
+        aws_access_key_id="fake",
+        aws_secret_access_key="fake",
+        config=cfg,
+    )
+    try:
+        c.list_tables()
+    except Exception as exc:  # pragma: no cover
+        pytest.skip(f"DynamoDB Local not reachable at {ENDPOINT}: {exc}")
+    yield c
+
+
+@pytest.fixture(scope="module")
+def table(client):
+    try:
+        client.delete_table(TableName=TABLE)
+        client.get_waiter("table_not_exists").wait(TableName=TABLE)
+    except Exception:
+        pass
+    client.create_table(
+        TableName=TABLE,
+        KeySchema=[
+            {"AttributeName": "PK", "KeyType": "HASH"},
+            {"AttributeName": "SK", "KeyType": "RANGE"},
+        ],
+        AttributeDefinitions=[
+            {"AttributeName": "PK", "AttributeType": "S"},
+            {"AttributeName": "SK", "AttributeType": "S"},
+            {"AttributeName": "GSI1PK", "AttributeType": "S"},
+            {"AttributeName": "GSI1SK", "AttributeType": "S"},
+        ],
+        GlobalSecondaryIndexes=[
+            {
+                "IndexName": "GSI1",
+                "KeySchema": [
+                    {"AttributeName": "GSI1PK", "KeyType": "HASH"},
+                    {"AttributeName": "GSI1SK", "KeyType": "RANGE"},
+                ],
+                "Projection": {"ProjectionType": "ALL"},
+            }
+        ],
+        BillingMode="PAY_PER_REQUEST",
+    )
+    client.get_waiter("table_exists").wait(TableName=TABLE)
+    yield TABLE
+    client.delete_table(TableName=TABLE)
+
+
+@pytest.fixture(scope="module")
+def env(client, table):
+    """Runtime + typed repositories over the shared cross-language seed."""
+    bridge = _load_generated_package()
+    runtime = GraphDDBRuntime(
+        dynamodb_client=client,
+        manifest_path=conftest.MANIFEST_PATH,
+        operations_path=conftest.OPERATIONS_PATH,
+    )
+    group_repo = bridge.GroupRepository(runtime)
+    membership_repo = bridge.GroupMembershipRepository(runtime)
+    user_repo = bridge.UserRepository(runtime)
+
+    # Group META row (the GroupById.get point target / MemberAccess compose child).
+    client.put_item(
+        TableName=TABLE,
+        Item={
+            "PK": {"S": f"GROUP#{GROUP_ID}"},
+            "SK": {"S": "META"},
+            "groupId": {"S": GROUP_ID},
+            "name": {"S": GROUP_NAME},
+            "description": {"S": GROUP_DESCRIPTION},
+            "createdAt": {"S": GROUP_CREATED_AT},
+        },
+    )
+    # User PROFILE rows with the unique-GSI email projection (UserByEmail.get).
+    for uid, email, name in USERS:
+        client.put_item(
+            TableName=TABLE,
+            Item={
+                "PK": {"S": f"USER#{uid}"},
+                "SK": {"S": "PROFILE"},
+                "GSI1PK": {"S": f"EMAIL#{email}"},
+                "GSI1SK": {"S": "PROFILE"},
+                "userId": {"S": uid},
+                "name": {"S": name},
+                "email": {"S": email},
+                "status": {"S": "active"},
+                "createdAt": {"S": GROUP_CREATED_AT},
+            },
+        )
+    # Memberships written THROUGH the typed contract command (a non-promoted
+    # parallel-mode single create — `single.mode == 'op'`, one plain PutItem).
+    for uid, role, joined_at in MEMBERS:
+        membership_repo.membership_commands__add(
+            group_id=GROUP_ID, user_id=uid, role=role, joined_at=joined_at
+        )
+    return {
+        "runtime": runtime,
+        "group": group_repo,
+        "membership": membership_repo,
+        "user": user_repo,
+        "client": client,
+    }
+
+
+# ── point read (GroupById.get → Item | None) ───────────────────────────────────
+
+
+def test_typed_point_read_matches_raw_entry_point(env):
+    typed = env["group"].group_by_id__get(group_id=GROUP_ID)
+    raw = env["runtime"].execute_query_method("GroupById", "get", {"groupId": GROUP_ID})
+    assert typed is not None
+    assert typed == raw
+    assert typed["groupId"] == GROUP_ID
+    assert typed["name"] == GROUP_NAME
+    assert typed["description"] == GROUP_DESCRIPTION
+
+
+def test_typed_point_read_miss_returns_none(env):
+    assert env["group"].group_by_id__get(group_id="does-not-exist") is None
+    assert (
+        env["runtime"].execute_query_method("GroupById", "get", {"groupId": "does-not-exist"})
+        is None
+    )
+
+
+def test_typed_unique_gsi_point_read_matches_raw_entry_point(env):
+    typed = env["user"].user_by_email__get(email="alice@example.com")
+    raw = env["runtime"].execute_query_method(
+        "UserByEmail", "get", {"email": "alice@example.com"}
+    )
+    assert typed is not None
+    assert typed == raw
+    assert typed["userId"] == "alice"
+    assert typed["email"] == "alice@example.com"
+    assert typed["status"] == "active"
+
+
+# ── range read (MembersByGroup.list → {items, cursor} connection) ──────────────
+
+
+def test_typed_range_read_matches_raw_entry_point(env):
+    typed = env["membership"].members_by_group__list(group_id=GROUP_ID)
+    raw = env["runtime"].execute_query_method(
+        "MembersByGroup", "list", {"groupId": GROUP_ID}
+    )
+    assert typed == raw
+    # Single page → the connection cursor is None.
+    assert typed["cursor"] is None
+    by_user = {m["userId"]: m for m in typed["items"]}
+    assert set(by_user) == {"alice", "bob"}
+    assert by_user["alice"]["role"] == "admin"
+    assert by_user["bob"]["role"] == "member"
+    assert all(m["groupId"] == GROUP_ID for m in typed["items"])
+
+
+def test_typed_range_read_carries_live_cursor_on_page_break(env):
+    """The v1 typed range method exposes NO retrieval opts (#250 defers
+    limit/after/order), so a non-None cursor must come from a REAL page break:
+    4 members whose role is ~380KB each overflow the 1MB Query page, and the
+    typed connection surfaces the per-key cursor. The raw entry point (which
+    DOES take opts) continues from that cursor to the remaining rows."""
+    client = env["client"]
+    big_group = "gbig"
+    big_role = "x" * 380_000
+    member_ids = [f"m{i}" for i in range(1, 5)]
+    for uid in member_ids:
+        client.put_item(
+            TableName=TABLE,
+            Item={
+                "PK": {"S": f"GROUP#{big_group}"},
+                "SK": {"S": f"USER#{uid}"},
+                "groupId": {"S": big_group},
+                "userId": {"S": uid},
+                "role": {"S": big_role},
+                "joinedAt": {"S": "2021-01-01T00:00:00.000Z"},
+            },
+        )
+
+    typed = env["membership"].members_by_group__list(group_id=big_group)
+    raw = env["runtime"].execute_query_method(
+        "MembersByGroup", "list", {"groupId": big_group}
+    )
+    assert typed == raw
+    # The 1MB page break yields a genuine cursor through the TYPED method.
+    assert typed["cursor"] is not None
+    first_page = [m["userId"] for m in typed["items"]]
+    assert 0 < len(first_page) < len(member_ids)
+
+    # The typed cursor is the SAME per-key envelope the raw entry point resumes
+    # from: the continuation yields exactly the remaining members, no overlap.
+    rest = env["runtime"].execute_query_method(
+        "MembersByGroup", "list", {"groupId": big_group}, {"after": typed["cursor"]}
+    )
+    rest_ids = [m["userId"] for m in rest["items"]]
+    assert set(first_page).isdisjoint(rest_ids)
+    assert sorted(first_page + rest_ids) == member_ids
+
+    # Cleanup: keep the module-scoped seed minimal for the other tests.
+    for uid in member_ids:
+        client.delete_item(
+            TableName=TABLE,
+            Key={"PK": {"S": f"GROUP#{big_group}"}, "SK": {"S": f"USER#{uid}"}},
+        )
+
+
+# ── External Query composition (MemberAccess.get → composed group) ─────────────
+
+
+def test_typed_compose_matches_raw_entry_point(env):
+    typed = env["membership"].member_access__get(group_id=GROUP_ID, user_id="alice")
+    raw = env["runtime"].execute_query_method(
+        "MemberAccess", "get", {"groupId": GROUP_ID, "userId": "alice"}
+    )
+    assert typed is not None
+    assert typed == raw
+    assert typed["role"] == "admin"
+    # The composed parent group (via the GroupById contract), fully projected.
+    assert typed["group"] is not None
+    assert typed["group"]["groupId"] == GROUP_ID
+    assert typed["group"]["name"] == GROUP_NAME
+    assert typed["group"]["description"] == GROUP_DESCRIPTION
+
+
+def test_typed_compose_absent_parent_is_none(env):
+    client = env["client"]
+    # A membership whose group META does not exist → the composition is None.
+    client.put_item(
+        TableName=TABLE,
+        Item={
+            "PK": {"S": "GROUP#ghost"},
+            "SK": {"S": "USER#alice"},
+            "groupId": {"S": "ghost"},
+            "userId": {"S": "alice"},
+            "role": {"S": "member"},
+            "joinedAt": {"S": "2021-01-01T00:00:00.000Z"},
+        },
+    )
+    typed = env["membership"].member_access__get(group_id="ghost", user_id="alice")
+    raw = env["runtime"].execute_query_method(
+        "MemberAccess", "get", {"groupId": "ghost", "userId": "alice"}
+    )
+    assert typed is not None
+    assert typed == raw
+    assert typed["group"] is None
+    client.delete_item(
+        TableName=TABLE,
+        Key={"PK": {"S": "GROUP#ghost"}, "SK": {"S": "USER#alice"}},
+    )
+
+
+# ── non-promoted single writes (single.mode == 'op') ───────────────────────────
+
+
+def test_fixture_writes_are_serialized_non_promoted():
+    """Document the 'non-promoted' fact this suite covers: both write methods'
+    single-key resolution target is a PLAIN op (`mode: 'op'` → one
+    UpdateItem/PutItem from operations.commands), not a promoted transaction."""
+    with open(conftest.OPERATIONS_PATH, encoding="utf-8") as fh:
+        operations = json.load(fh)
+    set_tier = operations["contracts"]["UserCommands"]["methods"]["setTier"]
+    add = operations["contracts"]["MembershipCommands"]["methods"]["add"]
+    assert set_tier["single"] == {"mode": "op", "operation": "UserCommands__setTier"}
+    assert add["single"] == {"mode": "op", "operation": "MembershipCommands__add"}
+
+
+def test_typed_nonpromoted_update_matches_raw_write(env):
+    """`user_commands__set_tier` (typed, alice) and the raw entry point (bob)
+    must persist IDENTICAL rows (modulo the identity fields)."""
+    client = env["client"]
+    env["user"].user_commands__set_tier(user_id="alice", tier="pro")
+    env["runtime"].execute_command_method(
+        "UserCommands", "setTier", {"userId": "bob"}, {"tier": "pro"}
+    )
+
+    def row(uid):
+        item = client.get_item(
+            TableName=TABLE,
+            Key={"PK": {"S": f"USER#{uid}"}, "SK": {"S": "PROFILE"}},
+            ConsistentRead=True,
+        )["Item"]
+        # Strip the per-user identity attributes; everything else must match.
+        for k in ("PK", "GSI1PK", "userId", "name", "email"):
+            item.pop(k, None)
+        return item
+
+    alice, bob = row("alice"), row("bob")
+    assert alice["tier"] == {"S": "pro"}
+    assert alice == bob
+
+
+def test_typed_nonpromoted_create_matches_raw_write(env):
+    """`membership_commands__add` (typed) and the raw entry point must persist
+    IDENTICAL membership rows (modulo the member id)."""
+    client = env["client"]
+    env["membership"].membership_commands__add(
+        group_id=GROUP_ID, user_id="typed-w", role="viewer", joined_at="2022-03-04T05:06:07.000Z"
+    )
+    env["runtime"].execute_command_method(
+        "MembershipCommands",
+        "add",
+        {"groupId": GROUP_ID, "userId": "raw-w"},
+        {"role": "viewer", "joinedAt": "2022-03-04T05:06:07.000Z"},
+    )
+
+    def row(uid):
+        item = client.get_item(
+            TableName=TABLE,
+            Key={"PK": {"S": f"GROUP#{GROUP_ID}"}, "SK": {"S": f"USER#{uid}"}},
+            ConsistentRead=True,
+        )["Item"]
+        # Strip the per-member identity attributes (the SK and the user-side
+        # GSI1 projection both embed the userId); everything else must match.
+        for k in ("SK", "GSI1PK", "userId"):
+            item.pop(k, None)
+        return item
+
+    typed_row, raw_row = row("typed-w"), row("raw-w")
+    assert typed_row["role"] == {"S": "viewer"}
+    assert typed_row == raw_row
+
+    # …and the typed range read sees both rows exactly as the raw read does.
+    typed = env["membership"].members_by_group__list(group_id=GROUP_ID)
+    raw = env["runtime"].execute_query_method(
+        "MembersByGroup", "list", {"groupId": GROUP_ID}
+    )
+    assert typed == raw
+    assert {"typed-w", "raw-w"} <= {m["userId"] for m in typed["items"]}
+
+    for uid in ("typed-w", "raw-w"):
+        client.delete_item(
+            TableName=TABLE,
+            Key={"PK": {"S": f"GROUP#{GROUP_ID}"}, "SK": {"S": f"USER#{uid}"}},
+        )