graphddb-runtime 0.2.5__tar.gz → 0.3.0__tar.gz

{graphddb_runtime-0.2.5 → graphddb_runtime-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.2.5
+Version: 0.3.0
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9

{graphddb_runtime-0.2.5 → graphddb_runtime-0.3.0}/graphddb_runtime/middleware.py

@@ -25,14 +25,14 @@ Idiomatic Python differences from the TS reference (behavior is identical):
   {...}}}``) OR a small object with the matching attributes — a ``Middleware``
   is anything :func:`_hook` can read a callable off. This mirrors the TS object
   literal a host registers, and keeps registration as light as ``runtime.use({...})``.
-- Context objects are mutable dataclasses; the mutable fields the proposal marks
+- Context objects are mutable dataclasses; the mutable fields docs/middleware.md marks
   (``params`` in R1, ``operation`` in R2, ``kind`` / ``input`` in W1, ``items``
   in W3) are plain attributes a hook reassigns or mutates in place.
 
 A read or write issued with no ``context`` sees an empty ``{}`` — exactly as the
 TS runtime threads ``context ?? {}``.
 
-@see docs/proposals/read-middleware.md
+@see docs/middleware.md
 """
 
 from __future__ import annotations
@@ -51,7 +51,7 @@ from typing import (
 
 # A registered middleware is any object/mapping carrying the hook groups. The
 # library never validates its shape beyond reading callables off the known
-# paths, mirroring the TS "hooks are unrestricted" stance (proposal appendix A).
+# paths, mirroring the TS "hooks are unrestricted" stance (see docs/middleware.md).
 Middleware = Any
 RequestContext = Dict[str, Any]
 Item = Dict[str, Any]

{graphddb_runtime-0.2.5 → graphddb_runtime-0.3.0}/graphddb_runtime/transactions.py

@@ -152,6 +152,53 @@ def _when_holds(
     return left == right if when["op"] == "eq" else left != right
 
 
+def _apply_maintain_transform(op: str, args: List[Any], value: Any) -> Any:
+    """Apply one maintenance projection transform to a resolved source value (#129,
+    Epic #118) — the branch-for-branch mirror of the TS in-process
+    ``applyProjectionTransform`` (``command-runtime.ts``) and the declarative
+    ``applyMaintainTransform`` (``declarative-transaction.ts``):
+
+    - ``identity`` — copy the source value through unchanged;
+    - ``preview`` — keep the first ``n`` characters of the string form of the source
+      value (``args[0]`` is the positive-integer bound). ``None`` passes through.
+
+    Both runtimes apply this IDENTICALLY so the maintained row is byte-consistent.
+    """
+    if op == "identity":
+        return value
+    if op == "preview":
+        n = args[0] if args else None
+        if not isinstance(n, int) or isinstance(n, bool) or n <= 0:
+            raise ValueError(
+                f"a maintenance `preview` projection has a non-positive-integer length "
+                f"bound ({n!r})."
+            )
+        if value is None:
+            return value
+        return str(value)[:n]
+    raise ValueError(
+        f"unknown maintenance projection op '{op}' (expected 'identity' / 'preview')."
+    )
+
+
+def _build_maintain_projection(
+    maintain: Mapping[str, Any],
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+) -> Dict[str, Any]:
+    """Build the projected record a maintenance write mirrors onto the owner row: each
+    target attribute resolved from its source mutation-input field and run through its
+    transform. Mirrors the TS ``buildMaintainProjection``.
+    """
+    out: Dict[str, Any] = {}
+    for attr, transform in maintain["projection"].items():
+        value = _resolve_value("{" + transform["inputField"] + "}", params, element)
+        out[attr] = _apply_maintain_transform(
+            transform["op"], transform.get("args", []), value
+        )
+    return out
+
+
 def _attr_str(value: Any) -> str:
     """The string form of a serialized DynamoDB attribute value (PK/SK are strings)."""
     if isinstance(value, Mapping):
@@ -472,6 +519,18 @@ class TransactionExpander:
             self._apply_condition(condition, check, params, element)
             return {"ConditionCheck": check}
 
+        # #129 (Epic #118): a relation-side maintenance write — a projected `Update`
+        # on a SEPARATE owner row (a snapshot SET / a bounded-collection list_append),
+        # the branch-for-branch mirror of the TS in-process `renderMaintainWriteItem`
+        # and the declarative `buildMaintainUpdateItem`. The owner key was already
+        # resolved into `key`; the projection transform IR is applied here so the
+        # maintained row is byte-consistent across the runtimes.
+        maintain = spec.get("maintain")
+        if maintain is not None:
+            return self._build_maintain_update(
+                spec, maintain, table, key, params, element
+            )
+
         # Update. Two distinct DynamoDB actions, both supported (issue #85):
         #   - `changes` → `SET #f = :v` (overwrite a named field);
         #   - `add`     → `ADD #f :delta` (atomic numeric increment, concurrency-safe;
@@ -511,6 +570,80 @@ class TransactionExpander:
         self._apply_condition(spec.get("condition"), update, params, element)
         return {"Update": update}
 
+    def _build_maintain_update(
+        self,
+        spec: Mapping[str, Any],
+        maintain: Mapping[str, Any],
+        table: str,
+        key: Dict[str, Any],
+        params: Mapping[str, Any],
+        element: Optional[Mapping[str, Any]],
+    ) -> Dict[str, Any]:
+        """Build a relation-side maintenance ``Update`` (#129/#141, Epic #118): a
+        ``counter`` applies an atomic scalar ``ADD #attr :delta``; a ``snapshot`` SETs
+        each projected attribute onto the owner row; a ``collection`` appends the
+        projected item into the bounded list
+        (``SET #c = list_append(if_not_exists(#c, :empty), :item)``). **Phase 1 is
+        append-only** — ``maxItems`` / ``orderBy`` are not trimmed synchronously
+        (#130). The branch-for-branch mirror of the TS ``renderMaintainWriteItem`` /
+        ``buildMaintainUpdateItem``: the owner key is already resolved (``key``), and
+        the projection transform IR is applied so the maintained row is
+        byte-consistent across the runtimes.
+        """
+        update: Dict[str, Any] = {"TableName": table, "Key": key}
+        kind = maintain["kind"]
+        # #141: a counter is a scalar atomic `ADD #attr :delta` (no projection) — the
+        # SAME `ADD #a0 :a0` shape the self-lifecycle derived counter (#85) builds, so a
+        # same-row counter ADD merges identically across runtimes.
+        if kind == "counter":
+            counter = maintain.get("counter")
+            if counter is None:
+                raise ValueError(
+                    f"a 'counter' maintenance write on '{spec['entity']}' has no "
+                    f"`counter` payload."
+                )
+            delta = counter["delta"]
+            delta = int(delta) if isinstance(delta, str) else delta
+            update["UpdateExpression"] = "ADD #a0 :a0"
+            update["ExpressionAttributeNames"] = {"#a0": counter["attribute"]}
+            update["ExpressionAttributeValues"] = {":a0": self._serializer.serialize(delta)}
+            return {"Update": update}
+        projection = _build_maintain_projection(maintain, params, element)
+        if kind == "collection":
+            collection = maintain.get("collection") or {}
+            field = collection.get("field")
+            if field is None:
+                raise ValueError(
+                    f"a 'collection' maintenance write on '{spec['entity']}' has no "
+                    f"`collection.field`."
+                )
+            update["UpdateExpression"] = (
+                "SET #c = list_append(if_not_exists(#c, :empty), :item)"
+            )
+            update["ExpressionAttributeNames"] = {"#c": field}
+            update["ExpressionAttributeValues"] = {
+                ":empty": self._serializer.serialize([]),
+                ":item": self._serializer.serialize([projection]),
+            }
+        else:
+            names: Dict[str, str] = {}
+            values: Dict[str, Any] = {}
+            sets: List[str] = []
+            for i, (attr, value) in enumerate(projection.items()):
+                names[f"#m{i}"] = attr
+                values[f":m{i}"] = self._serializer.serialize(value)
+                sets.append(f"#m{i} = :m{i}")
+            if not sets:
+                raise ValueError(
+                    f"a 'snapshot' maintenance write on '{spec['entity']}' has an empty "
+                    f"projection."
+                )
+            update["UpdateExpression"] = "SET " + ", ".join(sets)
+            update["ExpressionAttributeNames"] = names
+            update["ExpressionAttributeValues"] = values
+        # A maintenance write carries no DynamoDB write condition (it upserts the row).
+        return {"Update": update}
+
     def expand(
         self, spec: Mapping[str, Any], params: Mapping[str, Any]
     ) -> List[Dict[str, Any]]:

{graphddb_runtime-0.2.5 → graphddb_runtime-0.3.0}/graphddb_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.2.5
+Version: 0.3.0
 Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
 License: MIT
 Requires-Python: >=3.9

{graphddb_runtime-0.2.5 → graphddb_runtime-0.3.0}/graphddb_runtime.egg-info/SOURCES.txt

@@ -29,10 +29,12 @@ tests/test_integration_contract.py
 tests/test_integration_edge_derive.py
 tests/test_integration_edge_write.py
 tests/test_integration_events.py
+tests/test_integration_maintain.py
 tests/test_integration_middleware.py
 tests/test_integration_referential.py
 tests/test_integration_relations.py
 tests/test_integration_unique.py
+tests/test_maintain.py
 tests/test_middleware.py
 tests/test_relations.py
 tests/test_unit.py

{graphddb_runtime-0.2.5 → graphddb_runtime-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphddb-runtime"
-version = "0.2.5"
+version = "0.3.0"
 description = "Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44)."
 readme = "README.md"
 requires-python = ">=3.9"

graphddb_runtime-0.3.0/tests/test_integration_maintain.py

@@ -0,0 +1,337 @@
+"""Integration tests for #129 relation-side MAINTENANCE WRITES against DynamoDB Local.
+
+Exercises ``GraphDDBRuntime.execute_command_method`` on the maintain contracts
+generated from the same SSoT the TS in-process runtime (#127) executes:
+
+  - COLLECTION (embeddedSnapshot / ``@hasMany``): ``ThreadPostCommands.create`` fires
+    ``ThreadPost.created`` → ``ThreadSummary.latestPosts``. The create composes the
+    ThreadPost Put AND a projected ``list_append`` onto the THREADSUMMARY#<threadId>
+    owner row in ONE atomic ``TransactWriteItems`` — the owner row is UPSERTED and the
+    projected item (``postId`` identity, ``textPreview = preview(body, 120)``) appended.
+  - SNAPSHOT (``@belongsTo``): ``ProfileCommands.update`` fires ``Profile.updated`` →
+    ``ProfileCard``. The update composes the Profile Put AND a projected ``SET``
+    (``displayName`` identity, ``bioPreview = preview(bio, 40)``) onto the
+    PROFILECARD#<userId> owner row, atomically.
+
+ACs proven on real DynamoDB (mirroring __tests__/integration/mutation-maintain.test.ts
+over the SAME SSoT, so the two runtimes produce identical effects / identical rollback):
+
+  - 1 atomic tx: after ONE create, BOTH the source row and the maintained append are
+    present; after ONE update, BOTH the source row and the snapshot mirror are present.
+  - append-only (Phase 1): a second create appends a SECOND item (the first preserved).
+  - atomic rollback: re-creating the SAME post fails the create guard and does NOT
+    append a duplicate maintained item (the maintenance write rolled back WITH the
+    source — it is not a separate, independently-applied write).
+  - read-back invariant: the mirrored values match the source payload through the
+    projection transform (identity / preview), byte-for-byte the TS runtime's output.
+
+Marked ``integration`` so it is skipped by ``-m "not integration"``.
+"""
+
+from __future__ import annotations
+
+import os
+
+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"
+
+
+@pytest.fixture(scope="module")
+def client():
+    cfg = Config(retries={"max_attempts": 2}, connect_timeout=2, read_timeout=5)
+    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()
+def rt(client, table):
+    return GraphDDBRuntime(
+        dynamodb_client=client,
+        manifest_path=conftest.MANIFEST_PATH,
+        operations_path=conftest.OPERATIONS_PATH,
+    )
+
+
+def _row(client, pk, sk):
+    res = client.get_item(TableName=TABLE, Key={"PK": {"S": pk}, "SK": {"S": sk}})
+    return res.get("Item")
+
+
+# ── COLLECTION maintainer: ThreadPost.created → ThreadSummary.latestPosts ─────────
+
+
+def test_collection_create_writes_post_and_appends_maintained_item_atomically(rt, client):
+    result = rt.execute_command_method(
+        "ThreadPostCommands",
+        "create",
+        {"threadId": "it1", "postId": "p1"},
+        {
+            "threadId": "it1",
+            "postId": "p1",
+            "body": "hello world",
+            "createdAt": "2026-06-01T00:00:00.000Z",
+        },
+    )
+    # The read-back projection of the source write.
+    assert result == {"threadId": "it1", "postId": "p1", "body": "hello world"}
+
+    # The ThreadPost row persisted (the base write).
+    post = _row(client, "THREAD#it1", "POST#p1")
+    assert post is not None and post["body"]["S"] == "hello world"
+
+    # The ThreadSummary owner row was UPSERTED and the maintained collection item
+    # appended — in the SAME transaction as the post Put.
+    summary = _row(client, "THREADSUMMARY#it1", "SUMMARY")
+    assert summary is not None
+    assert summary["latestPosts"] == {
+        "L": [{"M": {"postId": {"S": "p1"}, "textPreview": {"S": "hello world"}}}]
+    }
+
+    # #141: the SAME ThreadPost.created ALSO incremented the ThreadCounter.postCount
+    # counter (+1, on a DIFFERENT owner row) — upserted from absent in the same tx.
+    counter = _row(client, "THREADCOUNT#it1", "COUNT")
+    assert counter is not None and counter["postCount"]["N"] == "1"
+
+
+def test_collection_second_create_appends_second_projected_item(rt, client):
+    long_body = "x" * 300
+    rt.execute_command_method(
+        "ThreadPostCommands",
+        "create",
+        {"threadId": "it1", "postId": "p2"},
+        {
+            "threadId": "it1",
+            "postId": "p2",
+            "body": long_body,
+            "createdAt": "2026-06-02T00:00:00.000Z",
+        },
+    )
+    summary = _row(client, "THREADSUMMARY#it1", "SUMMARY")
+    items = summary["latestPosts"]["L"]
+    assert len(items) == 2
+    # The first item is preserved (append, not overwrite).
+    assert items[0] == {"M": {"postId": {"S": "p1"}, "textPreview": {"S": "hello world"}}}
+    # The second item's textPreview is preview(body, 120) — exactly 120 chars.
+    assert items[1]["M"]["postId"]["S"] == "p2"
+    assert len(items[1]["M"]["textPreview"]["S"]) == 120
+    assert items[1]["M"]["textPreview"]["S"] == "x" * 120
+
+
+def test_collection_atomic_rollback_no_duplicate_append(rt, client):
+    # Before: latestPosts has 2 items.
+    before = _row(client, "THREADSUMMARY#it1", "SUMMARY")
+    assert len(before["latestPosts"]["L"]) == 2
+
+    # Re-create p1 — the entity Put's attribute_not_exists(PK) guard fails, cancelling
+    # the WHOLE TransactWriteItems (the source Put + the maintenance append).
+    with pytest.raises(Exception):
+        rt.execute_command_method(
+            "ThreadPostCommands",
+            "create",
+            {"threadId": "it1", "postId": "p1"},
+            {
+                "threadId": "it1",
+                "postId": "p1",
+                "body": "duplicate",
+                "createdAt": "2026-06-03T00:00:00.000Z",
+            },
+        )
+    # Proof of atomic rollback: the maintained collection was NOT appended a third time
+    # — still exactly the 2 prior items (the maintenance write rolled back WITH the
+    # failed source write; it is not a separate, independently-applied write).
+    after = _row(client, "THREADSUMMARY#it1", "SUMMARY")
+    assert len(after["latestPosts"]["L"]) == 2
+
+
+# ── SNAPSHOT maintainer: Profile.updated → ProfileCard mirror ─────────────────────
+
+
+def test_snapshot_update_mirrors_projected_row_into_owner_atomically(rt, client):
+    # Seed the Profile so the `update` has a row to write (and the snapshot has a source).
+    client.put_item(
+        TableName=TABLE,
+        Item={
+            "PK": {"S": "PROFILE#u1"},
+            "SK": {"S": "META"},
+            "userId": {"S": "u1"},
+            "displayName": {"S": "old name"},
+            "bio": {"S": "old bio"},
+        },
+    )
+    bio = (
+        "mathematician and the first to recognise that the analytical engine "
+        "had applications beyond pure calculation"
+    )
+    result = rt.execute_command_method(
+        "ProfileCommands",
+        "update",
+        {"userId": "u1"},
+        {"userId": "u1", "displayName": "Ada Lovelace", "bio": bio},
+    )
+    assert result == {"userId": "u1", "displayName": "Ada Lovelace"}
+
+    # The Profile row updated (base write).
+    profile = _row(client, "PROFILE#u1", "META")
+    assert profile["displayName"]["S"] == "Ada Lovelace"
+
+    # The ProfileCard owner row was UPSERTED with the projected snapshot — same tx.
+    card = _row(client, "PROFILECARD#u1", "CARD")
+    assert card is not None
+    assert card["displayName"]["S"] == "Ada Lovelace"
+    # bioPreview = preview(bio, 40) — the first 40 characters.
+    assert card["bioPreview"]["S"] == bio[:40]
+    assert len(card["bioPreview"]["S"]) == 40
+
+
+# ── #141 COUNTER maintainer: ThreadPost.created/removed → ThreadCounter.postCount ──
+
+
+def test_counter_create_increments_postcount_plus_one_atomically(rt, client):
+    """`ThreadPost.created` → ThreadCounter.postCount += 1: the create composes the
+    ThreadPost Put AND an atomic `ADD postCount 1` onto the THREADCOUNT#<threadId> owner
+    row in ONE atomic transact_write_items (upserted from absent)."""
+    rt.execute_command_method(
+        "ThreadPostCommands",
+        "create",
+        {"threadId": "ctC", "postId": "cp1"},
+        {
+            "threadId": "ctC",
+            "postId": "cp1",
+            "body": "first",
+            "createdAt": "2026-06-01T00:00:00.000Z",
+        },
+    )
+    assert _row(client, "THREAD#ctC", "POST#cp1") is not None
+    counter = _row(client, "THREADCOUNT#ctC", "COUNT")
+    assert counter is not None and counter["postCount"]["N"] == "1"
+
+    # A second create increments to 2 (concurrency-safe ADD, no read-modify-write).
+    rt.execute_command_method(
+        "ThreadPostCommands",
+        "create",
+        {"threadId": "ctC", "postId": "cp2"},
+        {
+            "threadId": "ctC",
+            "postId": "cp2",
+            "body": "second",
+            "createdAt": "2026-06-02T00:00:00.000Z",
+        },
+    )
+    counter = _row(client, "THREADCOUNT#ctC", "COUNT")
+    assert counter["postCount"]["N"] == "2"
+
+
+def test_counter_remove_decrements_postcount_minus_one_atomically(rt, client):
+    """`ThreadPost.removed` → ThreadCounter.postCount -= 1: the remove composes the
+    ThreadPost Delete AND an atomic `ADD postCount -1` in ONE atomic tx."""
+    # Seed a counter at 2 and a ThreadPost row to remove.
+    client.put_item(
+        TableName=TABLE,
+        Item={
+            "PK": {"S": "THREADCOUNT#ctR"},
+            "SK": {"S": "COUNT"},
+            "threadId": {"S": "ctR"},
+            "postCount": {"N": "2"},
+        },
+    )
+    client.put_item(
+        TableName=TABLE,
+        Item={
+            "PK": {"S": "THREAD#ctR"},
+            "SK": {"S": "POST#cpR"},
+            "threadId": {"S": "ctR"},
+            "postId": {"S": "cpR"},
+            "body": {"S": "to remove"},
+            "createdAt": {"S": "2026-06-02T00:00:00.000Z"},
+        },
+    )
+    rt.execute_command_method(
+        "ThreadPostCommands",
+        "remove",
+        {"threadId": "ctR", "postId": "cpR"},
+        {"threadId": "ctR", "postId": "cpR"},
+    )
+    # The base post row removed.
+    assert _row(client, "THREAD#ctR", "POST#cpR") is None
+    # The counter decremented (2 → 1) by the atomic ADD(-1) in the same tx.
+    counter = _row(client, "THREADCOUNT#ctR", "COUNT")
+    assert counter["postCount"]["N"] == "1"
+
+
+def test_counter_atomic_rollback_no_double_increment(rt, client):
+    """Re-creating the same post fails the create guard and the WHOLE tx rolls back —
+    the counter is NOT double-incremented (the ADD rode the failed source Put)."""
+    rt.execute_command_method(
+        "ThreadPostCommands",
+        "create",
+        {"threadId": "ctX", "postId": "cpX"},
+        {"threadId": "ctX", "postId": "cpX", "body": "one", "createdAt": "2026-06-01T00:00:00.000Z"},
+    )
+    before = _row(client, "THREADCOUNT#ctX", "COUNT")
+    assert before["postCount"]["N"] == "1"
+
+    with pytest.raises(Exception):
+        rt.execute_command_method(
+            "ThreadPostCommands",
+            "create",
+            {"threadId": "ctX", "postId": "cpX"},
+            {"threadId": "ctX", "postId": "cpX", "body": "dup", "createdAt": "2026-06-02T00:00:00.000Z"},
+        )
+    after = _row(client, "THREADCOUNT#ctX", "COUNT")
+    assert after["postCount"]["N"] == "1"

graphddb_runtime-0.3.0/tests/test_maintain.py

@@ -0,0 +1,280 @@
+"""Unit tests for relation-side MAINTENANCE WRITES (#129, Epic #118).
+
+The Python mirror of the TS in-process `renderMaintainWriteItem`
+(`src/runtime/command-runtime.ts`) and the declarative `buildMaintainUpdateItem`
+(`src/operations/declarative-transaction.ts`). These prove the Python runtime
+realizes the serialized maintenance shape — the projection transform IR
+(`identity` / `preview`) + the bounded-collection append — IDENTICALLY, the same
+way the conformance golden proves it end-to-end against DynamoDB Local.
+
+No network: the maintain command is driven through `execute_command_method`
+against a recording fake client that captures the `transact_write_items` request,
+so the projected `Update` item (the snapshot `SET` / the collection `list_append`)
+is asserted directly.
+"""
+
+from __future__ import annotations
+
+import pytest
+from boto3.dynamodb.types import TypeDeserializer
+
+from graphddb_runtime import GraphDDBRuntime
+from graphddb_runtime.transactions import (
+    _apply_maintain_transform,
+    _build_maintain_projection,
+)
+
+import conftest
+
+_DESER = TypeDeserializer()
+
+
+def make_runtime(client, **kw) -> GraphDDBRuntime:
+    return GraphDDBRuntime(
+        dynamodb_client=client,
+        manifest_path=conftest.MANIFEST_PATH,
+        operations_path=conftest.OPERATIONS_PATH,
+        **kw,
+    )
+
+
+def plain(av_map):
+    return {k: _DESER.deserialize(v) for k, v in av_map.items()}
+
+
+class FakeClient:
+    def __init__(self):
+        self.calls = []
+
+    def transact_write_items(self, **kwargs):
+        self.calls.append(("transact_write_items", kwargs))
+        return {}
+
+    # The maintain commands declare a `result.select`, so a consistent read-back
+    # GetItem follows the write; return an empty item (the read-back parity is
+    # covered by conformance, not this unit test).
+    def get_item(self, **kwargs):
+        self.calls.append(("get_item", kwargs))
+        return {}
+
+
+# ── the transform IR mirror (applyProjectionTransform parity) ────────────────────
+
+
+def test_identity_transform_copies_value_through():
+    assert _apply_maintain_transform("identity", [], "hello") == "hello"
+    assert _apply_maintain_transform("identity", [], 42) == 42
+    assert _apply_maintain_transform("identity", [], None) is None
+
+
+def test_preview_transform_keeps_first_n_chars():
+    # Exactly the TS `applyProjectionTransform('preview', [n], value)` semantics:
+    # the first n characters of the string form; a short value is unchanged.
+    assert _apply_maintain_transform("preview", [5], "hello world") == "hello"
+    assert _apply_maintain_transform("preview", [120], "short") == "short"
+    # A non-string is stringified first (matching `String(value).slice(0, n)`).
+    assert _apply_maintain_transform("preview", [2], 12345) == "12"
+    # None passes through (a missing source value is not previewed).
+    assert _apply_maintain_transform("preview", [10], None) is None
+
+
+def test_preview_transform_rejects_non_positive_bound():
+    for bad in (0, -1, 1.5, "x", None):
+        with pytest.raises(ValueError):
+            _apply_maintain_transform("preview", [bad], "value")
+
+
+def test_unknown_transform_op_rejects_loudly():
+    with pytest.raises(ValueError):
+        _apply_maintain_transform("uppercase", [], "value")
+
+
+def test_build_maintain_projection_applies_each_transform():
+    maintain = {
+        "projection": {
+            "postId": {"op": "identity", "args": [], "inputField": "postId"},
+            "textPreview": {"op": "preview", "args": [5], "inputField": "body"},
+        }
+    }
+    out = _build_maintain_projection(
+        maintain, {"postId": "p1", "body": "hello world"}, None
+    )
+    assert out == {"postId": "p1", "textPreview": "hello"}
+
+
+# ── the collection maintainer (embeddedSnapshot / hasMany) ───────────────────────
+
+
+def test_collection_maintainer_appends_projected_item_via_list_append():
+    """`ThreadPost.created` → ThreadSummary.latestPosts: the create composes the
+    ThreadPost Put AND a `list_append` onto the THREADSUMMARY#<threadId> owner row in
+    ONE atomic transact_write_items — the Python mirror of the TS in-process append."""
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt.execute_command_method(
+        "ThreadPostCommands",
+        "create",
+        {"threadId": "t1", "postId": "p1"},
+        {
+            "threadId": "t1",
+            "postId": "p1",
+            "body": "hello world",
+            "createdAt": "2026-06-01T00:00:00.000Z",
+        },
+    )
+    write_calls = [c for c in client.calls if c[0] == "transact_write_items"]
+    assert len(write_calls) == 1
+    items = write_calls[0][1]["TransactItems"]
+    # The base ThreadPost Put + the collection maintenance Update on the THREADSUMMARY
+    # owner row + (#141) the counter ADD on the THREADCOUNT owner row.
+    puts = [it["Put"] for it in items if "Put" in it]
+    updates = [it["Update"] for it in items if "Update" in it]
+    assert len(puts) == 1
+    assert plain(puts[0]["Item"])["PK"] == "THREAD#t1"
+
+    # Select the collection maintainer by its owner-row key (the counter Update targets
+    # a DIFFERENT row, THREADCOUNT#t1, so the two never collide).
+    upd = next(u for u in updates if plain(u["Key"])["PK"] == "THREADSUMMARY#t1")
+    assert plain(upd["Key"]) == {"PK": "THREADSUMMARY#t1", "SK": "SUMMARY"}
+    # Append-only: list_append(if_not_exists(#c, :empty), :item) onto `latestPosts`.
+    assert (
+        upd["UpdateExpression"]
+        == "SET #c = list_append(if_not_exists(#c, :empty), :item)"
+    )
+    assert upd["ExpressionAttributeNames"] == {"#c": "latestPosts"}
+    vals = upd["ExpressionAttributeValues"]
+    assert _DESER.deserialize(vals[":empty"]) == []
+    # The appended item: postId identity, textPreview = preview(body, 120).
+    appended = _DESER.deserialize(vals[":item"])
+    assert appended == [{"postId": "p1", "textPreview": "hello world"}]
+
+
+def test_collection_maintainer_preview_truncates_long_body_to_120():
+    client = FakeClient()
+    rt = make_runtime(client)
+    long_body = "x" * 300
+    rt.execute_command_method(
+        "ThreadPostCommands",
+        "create",
+        {"threadId": "t2", "postId": "p2"},
+        {
+            "threadId": "t2",
+            "postId": "p2",
+            "body": long_body,
+            "createdAt": "2026-06-02T00:00:00.000Z",
+        },
+    )
+    items = [c for c in client.calls if c[0] == "transact_write_items"][0][1][
+        "TransactItems"
+    ]
+    # Select the collection maintainer (THREADSUMMARY) — the #141 counter Update targets
+    # THREADCOUNT and carries no `:item`.
+    updates = [it["Update"] for it in items if "Update" in it]
+    upd = next(u for u in updates if plain(u["Key"])["PK"] == "THREADSUMMARY#t2")
+    appended = _DESER.deserialize(upd["ExpressionAttributeValues"][":item"])
+    assert len(appended[0]["textPreview"]) == 120
+    assert appended[0]["textPreview"] == "x" * 120
+
+
+# ── the snapshot maintainer (belongsTo) ──────────────────────────────────────────
+
+
+def test_snapshot_maintainer_sets_projected_attributes_onto_owner_row():
+    """`Profile.updated` → ProfileCard snapshot: the update composes the Profile Put
+    AND a `SET` of each projected attribute onto the PROFILECARD#<userId> owner row in
+    ONE atomic transact_write_items — the Python mirror of the TS in-process snapshot."""
+    client = FakeClient()
+    rt = make_runtime(client)
+    bio = (
+        "mathematician and the first to recognise that the analytical engine "
+        "had applications beyond pure calculation"
+    )
+    rt.execute_command_method(
+        "ProfileCommands",
+        "update",
+        {"userId": "u1"},
+        {"userId": "u1", "displayName": "Ada Lovelace", "bio": bio},
+    )
+    items = [c for c in client.calls if c[0] == "transact_write_items"][0][1][
+        "TransactItems"
+    ]
+    updates = [it["Update"] for it in items if "Update" in it]
+    # The base Profile Update (the `update` write) + the maintenance Update on the card.
+    card = next(
+        u for u in updates if plain(u["Key"])["PK"] == "PROFILECARD#u1"
+    )
+    assert plain(card["Key"]) == {"PK": "PROFILECARD#u1", "SK": "CARD"}
+    assert card["UpdateExpression"].startswith("SET ")
+    names = card["ExpressionAttributeNames"]
+    values = {k: _DESER.deserialize(v) for k, v in card["ExpressionAttributeValues"].items()}
+    # Reconstruct attr -> value from the #mN / :mN aliases.
+    projected = {}
+    for name_alias, attr in names.items():
+        value_alias = ":" + name_alias[1:]
+        projected[attr] = values[value_alias]
+    assert projected["displayName"] == "Ada Lovelace"
+    # bioPreview = preview(bio, 40) — exactly the first 40 chars.
+    assert projected["bioPreview"] == bio[:40]
+    assert len(projected["bioPreview"]) == 40
+
+
+# ── the counter maintainer (@aggregate / count(), #141) ──────────────────────────
+
+
+def _counter_update(items):
+    """The THREADCOUNT (counter) Update among a create/remove's transact items."""
+    updates = [it["Update"] for it in items if "Update" in it]
+    return next(u for u in updates if plain(u["Key"])["PK"].startswith("THREADCOUNT#"))
+
+
+def test_counter_maintainer_adds_plus_one_on_create():
+    """`ThreadPost.created` → ThreadCounter.postCount += 1: the create composes the
+    ThreadPost Put AND an atomic `ADD postCount 1` onto the THREADCOUNT#<threadId> owner
+    row in ONE atomic transact_write_items — the Python mirror of the TS in-process
+    counter render. The counter row is a DIFFERENT owner from the collection
+    (THREADSUMMARY), so they never collide."""
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt.execute_command_method(
+        "ThreadPostCommands",
+        "create",
+        {"threadId": "t1", "postId": "p1"},
+        {
+            "threadId": "t1",
+            "postId": "p1",
+            "body": "hello world",
+            "createdAt": "2026-06-01T00:00:00.000Z",
+        },
+    )
+    items = [c for c in client.calls if c[0] == "transact_write_items"][0][1][
+        "TransactItems"
+    ]
+    upd = _counter_update(items)
+    assert plain(upd["Key"]) == {"PK": "THREADCOUNT#t1", "SK": "COUNT"}
+    # An atomic `ADD #a0 :a0` of +1 (concurrency-safe, no prior read).
+    assert upd["UpdateExpression"] == "ADD #a0 :a0"
+    assert upd["ExpressionAttributeNames"] == {"#a0": "postCount"}
+    assert _DESER.deserialize(upd["ExpressionAttributeValues"][":a0"]) == 1
+
+
+def test_counter_maintainer_adds_minus_one_on_remove():
+    """`ThreadPost.removed` → ThreadCounter.postCount -= 1: the remove composes the
+    ThreadPost Delete AND an atomic `ADD postCount -1` onto the THREADCOUNT owner row."""
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt.execute_command_method(
+        "ThreadPostCommands",
+        "remove",
+        {"threadId": "t9", "postId": "p9"},
+        {"threadId": "t9", "postId": "p9"},
+    )
+    items = [c for c in client.calls if c[0] == "transact_write_items"][0][1][
+        "TransactItems"
+    ]
+    # The base ThreadPost Delete + the counter ADD(-1).
+    deletes = [it["Delete"] for it in items if "Delete" in it]
+    assert any(plain(d["Key"])["PK"] == "THREAD#t9" for d in deletes)
+    upd = _counter_update(items)
+    assert upd["UpdateExpression"] == "ADD #a0 :a0"
+    assert upd["ExpressionAttributeNames"] == {"#a0": "postCount"}
+    assert _DESER.deserialize(upd["ExpressionAttributeValues"][":a0"]) == -1