graphddb-runtime 0.6.0__tar.gz → 0.7.1__tar.gz

{graphddb_runtime-0.6.0 → graphddb_runtime-0.7.1}/PKG-INFO

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

{graphddb_runtime-0.6.0 → graphddb_runtime-0.7.1}/graphddb_runtime/__init__.py

@@ -41,10 +41,11 @@ from .middleware import (
     WriteCtx,
     WriteRuntime,
 )
-from .runtime import GraphDDBRuntime
+from .runtime import SPEC_VERSION_SUPPORTED, GraphDDBRuntime
 
 __all__ = [
     "GraphDDBRuntime",
+    "SPEC_VERSION_SUPPORTED",
     "AsyncGraphDDBRuntime",
     "RuntimeLimits",
     # middleware / hooks (issue #50 / #140 — Python parity)

{graphddb_runtime-0.6.0 → graphddb_runtime-0.7.1}/graphddb_runtime/relations.py

@@ -132,7 +132,12 @@ class RelationAssembler:
             return
 
         if op["type"] == "BatchGetItem":
-            self._apply_batch_get(parents, op, write_key)
+            if op.get("sourceList"):
+                # The list fan-out binding form (issue #208, B案): a `refs`
+                # relation resolved from an inline parent-row id-list.
+                self._apply_refs(parents, op, write_key)
+            else:
+                self._apply_batch_get(parents, op, write_key)
         else:  # Query (hasMany)
             self._apply_query(parents, op, write_key)
 
@@ -167,6 +172,80 @@ class RelationAssembler:
                 continue
             parent[write_key] = key_to_item.get(self._key_for(op, sv))
 
+    # ── refs: an inline parent-row id-list → ONE deduped BatchGetItem ───────────
+
+    def _apply_refs(
+        self,
+        parents: List[Dict[str, Any]],
+        op: Dict[str, Any],
+        write_key: str,
+    ) -> None:
+        """Resolve a ``refs`` fan-out op (issue #208 B案; #197 read side).
+
+        The op's ``sourceList`` names the parent LIST attribute (``from``) whose
+        elements each carry the reference key (``key`` — always equal to the op's
+        ``sourceField``, the ``{result.<sourceField>}`` token). Semantics mirror
+        the TS in-process ``fetchRefsList`` byte-for-byte:
+
+        - an object element binds ``element[key]``; a bare scalar element binds
+          itself; a null/missing ref is skipped;
+        - ALL parents' element keys fan into ONE deduped BatchGet (the injected
+          ``run_batch_get`` already chunks at 100 and retries UnprocessedKeys);
+        - each parent receives a ``{"items": [...], "cursor": None}`` connection —
+          the resolved child bodies in **first-seen element order**, deduped,
+          with missing bodies dropped (a dangling ref cannot be hydrated);
+        - a parent whose list is absent / not a list resolves to an empty
+          connection.
+        """
+        source_field = op["sourceField"]
+        from_attr = op["sourceList"]["from"]
+        element_key = op["sourceList"].get("key", source_field)
+
+        def element_values(parent: Dict[str, Any]) -> List[Any]:
+            raw = parent.get(from_attr)
+            elements = raw if isinstance(raw, list) else []
+            values: List[Any] = []
+            for element in elements:
+                value = (
+                    element.get(element_key)
+                    if isinstance(element, dict)
+                    else element
+                )
+                if value is None:
+                    continue
+                values.append(value)
+            return values
+
+        # One deduped BatchGet across ALL parents' element keys.
+        source_values: List[Dict[str, Any]] = []
+        seen: set = set()
+        for parent in parents:
+            for value in element_values(parent):
+                sv = {source_field: value}
+                marker = self._key_for(op, sv)
+                if marker in seen:
+                    continue
+                seen.add(marker)
+                source_values.append(sv)
+
+        key_to_item = (
+            self._run_batch_get(op, source_values) if source_values else {}
+        )
+
+        for parent in parents:
+            items: List[Any] = []
+            seen_local: set = set()
+            for value in element_values(parent):
+                sv = {source_field: value}
+                marker = self._key_for(op, sv)
+                if marker in seen_local:
+                    continue
+                seen_local.add(marker)
+                item = key_to_item.get(marker)
+                if item is not None:
+                    items.append(item)
+            parent[write_key] = {"items": items, "cursor": None}
+
     # ── hasMany: a per-parent Query ─────────────────────────────────────────────
 
     def _apply_query(

{graphddb_runtime-0.6.0 → graphddb_runtime-0.7.1}/graphddb_runtime/runtime.py

@@ -48,7 +48,7 @@ from .per_key_cursor import (
     encode_per_key_cursor,
     serialize_contract_key,
 )
-from .relations import RelationAssembler
+from .relations import RelationAssembler, collect_parents, parse_result_path
 from .templates import (
     resolve_template,
     validate_params,
@@ -56,6 +56,54 @@ from .templates import (
 from .transactions import MAX_TRANSACT_ITEMS, TransactionExpander
 from .transactions import _when_holds as _tx_when_holds
 
+#: The operation-IR (spec) version this runtime implements — the newest
+#: ``manifest.json`` / ``operations.json`` document version whose vocabulary it
+#: fully understands. See :func:`_validate_spec_version` for the compatibility
+#: rule.
+SPEC_VERSION_SUPPORTED = "1.1"
+
+
+def _validate_spec_version(document: Mapping[str, Any], label: str) -> None:
+    """Loudly reject a document this runtime cannot faithfully execute (#208).
+
+    The IR is a **stable execution contract**: its op vocabulary is closed over
+    the physical DynamoDB API, but the *binding grammar* grows occasionally
+    (e.g. the 1.1 ``sourceList`` list fan-out, #208 B案). A runtime handed a
+    document NEWER than it understands could silently mis-execute the unknown
+    binding forms (a pre-1.1 runtime resolves a ``refs`` fan-out to ``None``
+    without any error), so version skew must fail loudly, never silently.
+
+    Compatibility rule (``<major>.<minor>`` vs :data:`SPEC_VERSION_SUPPORTED`):
+
+    - **major** must equal the supported major — a major bump means the
+      existing vocabulary itself changed shape;
+    - **minor** must be **<=** the supported minor — minors are additive, so
+      every OLDER document is fully understood (backward compatible), while a
+      NEWER one may carry vocabulary this runtime does not implement
+      (forward-rejected);
+    - a missing / malformed version is rejected (an unversioned document
+      cannot be trusted to match any vocabulary).
+    """
+    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."
+        )
+    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."
+        )
+
 try:  # pragma: no cover - exercised indirectly
     from botocore.exceptions import BotoCoreError, ClientError
 
@@ -168,6 +216,12 @@ class GraphDDBRuntime:
         with open(operations_path, "r", encoding="utf-8") as fh:
             self._operations: Dict[str, Any] = json.load(fh)
 
+        # The IR is a stable execution contract (#208): refuse a document whose
+        # version this runtime does not fully implement, LOUDLY at construction
+        # (never a silent per-operation mis-execution).
+        _validate_spec_version(self._manifest, "manifest.json")
+        _validate_spec_version(self._operations, "operations.json")
+
         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", {})
@@ -360,8 +414,33 @@ class GraphDDBRuntime:
             key_for=self._relation_key_marker,
         )
         self._assemble_relations(spec, operations, root, assembler)
+        self._strip_implicit_sources(operations, root)
         return root
 
+    @staticmethod
+    def _strip_implicit_sources(
+        operations: List[Dict[str, Any]], root: Any
+    ) -> None:
+        """Drop parent attributes projected solely to drive a fan-out (#208 B案).
+
+        A ``refs`` fan-out op whose ``sourceList.implicit`` is set reads a parent
+        LIST attribute the query's select did not ask for — the planner projected
+        it onto the parent operation only so the fan-out could bind its keys
+        (mirroring the TS implicit relation-source projection, which the TS
+        hydrator strips from the assembled result). Delete it from every parent
+        node AFTER all relation operations are applied, so the visible result
+        carries exactly the selected fields on both runtimes.
+        """
+        for op in operations:
+            source_list = op.get("sourceList")
+            if not source_list or not source_list.get("implicit"):
+                continue
+            parent_tokens, _write_key, _is_connection = parse_result_path(
+                op["resultPath"]
+            )
+            for parent in collect_parents(root, parent_tokens):
+                parent.pop(source_list["from"], None)
+
     def _assemble_relations(
         self,
         spec: Mapping[str, Any],
@@ -1644,6 +1723,10 @@ class GraphDDBRuntime:
                 resolved["filter"] = op["filter"]
             if op.get("sourceField"):
                 resolved["sourceField"] = op["sourceField"]
+            if op.get("sourceList"):
+                # The list fan-out binding form (issue #208 B案) is resolved from
+                # prior results only at execution time; carry it verbatim.
+                resolved["sourceList"] = dict(op["sourceList"])
             resolved_ops.append(resolved)
 
         return {

{graphddb_runtime-0.6.0 → graphddb_runtime-0.7.1}/graphddb_runtime.egg-info/PKG-INFO

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

{graphddb_runtime-0.6.0 → graphddb_runtime-0.7.1}/graphddb_runtime.egg-info/SOURCES.txt

@@ -40,5 +40,6 @@ tests/test_integration_unique.py
 tests/test_maintain.py
 tests/test_middleware.py
 tests/test_relations.py
+tests/test_spec_version_guard.py
 tests/test_ttl.py
 tests/test_unit.py

{graphddb_runtime-0.6.0 → graphddb_runtime-0.7.1}/pyproject.toml

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

{graphddb_runtime-0.6.0 → graphddb_runtime-0.7.1}/tests/test_integration_relations.py

@@ -177,6 +177,29 @@ def seeded(raw_client):
             "grantedAt": {"S": "2022-01-01T00:00:00.000Z"},
         })
 
+    # #208 (B案) refs fixtures: tag bodies + articles carrying inline id-lists.
+    for tid, label in [("ts", "TypeScript"), ("py", "Python")]:
+        put({
+            "PK": {"S": f"TAG#{tid}"}, "SK": {"S": "META"},
+            "tagId": {"S": tid}, "label": {"S": label},
+        })
+    put({
+        "PK": {"S": "ARTICLE#a1"}, "SK": {"S": "META"},
+        "articleId": {"S": "a1"}, "title": {"S": "Refs!"},
+        # duplicate ref (ts×2) + a dangling ref (ghost) — dedup / drop semantics.
+        "tagRefs": {"L": [
+            {"M": {"tagId": {"S": "py"}}},
+            {"M": {"tagId": {"S": "ts"}}},
+            {"M": {"tagId": {"S": "ts"}}},
+            {"M": {"tagId": {"S": "ghost"}}},
+        ]},
+    })
+    put({
+        "PK": {"S": "ARTICLE#a2"}, "SK": {"S": "META"},
+        "articleId": {"S": "a2"}, "title": {"S": "No tags"},
+        "tagRefs": {"L": []},
+    })
+
     yield client
     client.delete_table(TableName=TABLE)
 
@@ -309,3 +332,45 @@ def test_explain_lists_operations_without_touching_dynamodb(seeded):
     assert plan["operations"][0]["keyCondition"]["GSI1PK"] == "EMAIL#alice@example.com"
     assert plan["operations"][2]["type"] == "BatchGetItem"
     assert spy.counts == {}
+
+
+# ── #208 (B案): refs — the inline id-list fan-out through the generated bridge ──
+
+
+def test_refs_fan_out_resolves_inline_id_list_in_one_batch_get(env):
+    bridge = _load_generated_package()
+    repo = bridge.ArticleRepository(env["runtime"])
+    env["spy"].reset()
+
+    out = repo.get_article_with_tags(article_id="a1")
+    assert out is not None
+    assert out["articleId"] == "a1"
+    assert out["title"] == "Refs!"
+    # First-seen element order, deduped (ts once), dangling ref dropped,
+    # cursor always None — byte-matching the TS in-process refs semantics.
+    assert out["tags"] == {
+        "items": [
+            {"tagId": "py", "label": "Python"},
+            {"tagId": "ts", "label": "TypeScript"},
+        ],
+        "cursor": None,
+    }
+    # The source list attribute was projected ONLY to drive the fan-out
+    # (sourceList.implicit) and must be stripped from the assembled result.
+    assert "tagRefs" not in out
+    # Physical cost: 1 parent GetItem + ONE deduped BatchGet — never per-ref reads.
+    assert env["spy"].counts.get("batch_get_item", 0) == 1
+    assert env["spy"].counts.get("get_item", 0) == 1
+
+
+def test_refs_empty_list_resolves_empty_connection_without_batch_get(env):
+    bridge = _load_generated_package()
+    repo = bridge.ArticleRepository(env["runtime"])
+    env["spy"].reset()
+
+    out = repo.get_article_with_tags(article_id="a2")
+    assert out is not None
+    assert out["tags"] == {"items": [], "cursor": None}
+    assert "tagRefs" not in out
+    # No refs to resolve → no BatchGet issued at all.
+    assert env["spy"].counts.get("batch_get_item", 0) == 0

{graphddb_runtime-0.6.0 → graphddb_runtime-0.7.1}/tests/test_relations.py

@@ -474,3 +474,140 @@ def test_resolve_entity_get_item_uses_sk_predicate():
     # SK 'META' uniquely selects GroupModel (createdAt:datetime).
     assert meta["fields"].get("createdAt", {}).get("format") == "datetime"
     assert "name" in meta["fields"]
+
+
+# ── refs: the list fan-out binding form (issue #208 B案 / #197 read side) ───────
+
+
+def _refs_op(**extra):
+    op = {
+        "type": "BatchGetItem",
+        "keyCondition": {"PK": "TAG#{result.tagId}", "SK": "META"},
+        "resultPath": "$.tags.items",
+        "sourceField": "tagId",
+        "sourceList": {"from": "tagRefs", "key": "tagId"},
+    }
+    op.update(extra)
+    return op
+
+
+def _refs_assembler(store, batches):
+    """An assembler whose BatchGet serves child bodies from ``store`` (tagId → item)."""
+
+    def run_batch_get(op, source_values):
+        batches.append([sv["tagId"] for sv in source_values])
+        out = {}
+        for sv in source_values:
+            item = store.get(sv["tagId"])
+            if item is not None:
+                out[serialize_key({"PK": f"TAG#{sv['tagId']}"})] = item
+        return out
+
+    return RelationAssembler(
+        run_query=lambda op, sv: {"items": [], "cursor": None},
+        run_batch_get=run_batch_get,
+        key_for=lambda op, sv: serialize_key({"PK": f"TAG#{sv['tagId']}"}),
+    )
+
+
+def test_assembler_refs_fans_out_one_deduped_batch_first_seen_order():
+    batches = []
+    store = {
+        "a": {"tagId": "a", "name": "Alpha"},
+        "b": {"tagId": "b", "name": "Beta"},
+    }
+    asm = _refs_assembler(store, batches)
+    root = {
+        "postId": "p1",
+        # duplicate ref + a null ref + a missing body ('ghost') interleaved.
+        "tagRefs": [
+            {"tagId": "b"},
+            {"tagId": "a"},
+            {"tagId": "b"},
+            {"tagId": None},
+            {"tagId": "ghost"},
+        ],
+    }
+    asm.apply(root, _refs_op())
+    # ONE batch, deduped, in first-seen order (null refs skipped).
+    assert batches == [["b", "a", "ghost"]]
+    # Items in first-seen element order, deduped, missing body dropped, cursor None.
+    assert root["tags"] == {
+        "items": [
+            {"tagId": "b", "name": "Beta"},
+            {"tagId": "a", "name": "Alpha"},
+        ],
+        "cursor": None,
+    }
+
+
+def test_assembler_refs_missing_or_non_list_source_resolves_empty_connection():
+    batches = []
+    asm = _refs_assembler({}, batches)
+    root_missing = {"postId": "p1"}
+    asm.apply(root_missing, _refs_op())
+    assert root_missing["tags"] == {"items": [], "cursor": None}
+
+    root_scalar = {"postId": "p2", "tagRefs": "not-a-list"}
+    asm.apply(root_scalar, _refs_op())
+    assert root_scalar["tags"] == {"items": [], "cursor": None}
+
+    # No source values at all → no BatchGet issued.
+    assert batches == []
+
+
+def test_assembler_refs_bare_scalar_elements_bind_themselves():
+    batches = []
+    store = {"x": {"tagId": "x", "name": "X"}}
+    asm = _refs_assembler(store, batches)
+    root = {"postId": "p1", "tagRefs": ["x", None, "x"]}
+    asm.apply(root, _refs_op())
+    assert batches == [["x"]]
+    assert root["tags"]["items"] == [{"tagId": "x", "name": "X"}]
+
+
+def test_assembler_refs_multiple_parents_share_one_batch():
+    batches = []
+    store = {
+        "a": {"tagId": "a", "name": "Alpha"},
+        "b": {"tagId": "b", "name": "Beta"},
+    }
+    asm = _refs_assembler(store, batches)
+    root = {
+        "posts": {
+            "items": [
+                {"postId": "p1", "tagRefs": [{"tagId": "a"}, {"tagId": "b"}]},
+                {"postId": "p2", "tagRefs": [{"tagId": "b"}]},
+                {"postId": "p3", "tagRefs": []},
+            ],
+            "cursor": None,
+        }
+    }
+    asm.apply(root, _refs_op(resultPath="$.posts.items.tags.items"))
+    # The fan-out across ALL parents is one deduped batch.
+    assert batches == [["a", "b"]]
+    items = root["posts"]["items"]
+    assert [t["tagId"] for t in items[0]["tags"]["items"]] == ["a", "b"]
+    assert [t["tagId"] for t in items[1]["tags"]["items"]] == ["b"]
+    assert items[2]["tags"] == {"items": [], "cursor": None}
+
+
+def test_strip_implicit_sources_removes_only_implicit_list_attributes():
+    root = {
+        "postId": "p1",
+        "tagRefs": [{"tagId": "a"}],
+        "tags": {"items": [{"tagId": "a", "name": "Alpha"}], "cursor": None},
+    }
+    ops = [
+        {"type": "GetItem", "resultPath": "$"},
+        _refs_op(sourceList={"from": "tagRefs", "key": "tagId", "implicit": True}),
+    ]
+    GraphDDBRuntime._strip_implicit_sources(ops, root)
+    assert "tagRefs" not in root
+    assert root["tags"]["items"] == [{"tagId": "a", "name": "Alpha"}]
+
+    # A selected (non-implicit) source list stays in the result.
+    root2 = {"postId": "p1", "tagRefs": [{"tagId": "a"}], "tags": {"items": [], "cursor": None}}
+    ops2 = [{"type": "GetItem", "resultPath": "$"}, _refs_op()]
+    GraphDDBRuntime._strip_implicit_sources(ops2, root2)
+    assert root2["tagRefs"] == [{"tagId": "a"}]

graphddb_runtime-0.7.1/tests/test_spec_version_guard.py

@@ -0,0 +1,95 @@
+"""Spec-version guard tests (issue #208 follow-up).
+
+The IR is a stable execution contract: ``GraphDDBRuntime`` must LOUDLY reject a
+``manifest.json`` / ``operations.json`` whose version it does not fully
+implement, instead of silently mis-executing unknown binding forms (a pre-1.1
+runtime would resolve a 1.1 ``refs`` fan-out to ``None`` without any error).
+
+Compatibility rule (pinned here): a ``<major>.<minor>`` document is accepted
+iff its major equals the supported major AND its minor is <= the supported
+minor (minors are additive → older documents are fully understood; newer ones
+are forward-rejected). Missing / malformed versions are rejected.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+import pytest
+
+import conftest
+from graphddb_runtime import GraphDDBError, GraphDDBRuntime, SPEC_VERSION_SUPPORTED
+
+
+def _load(path):
+    with open(path, "r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def _write(tmp_path, name, doc):
+    p = os.path.join(str(tmp_path), name)
+    with open(p, "w", encoding="utf-8") as fh:
+        json.dump(doc, fh)
+    return p
+
+
+def _runtime(manifest_path, operations_path):
+    return GraphDDBRuntime(
+        dynamodb_client=object(),
+        manifest_path=manifest_path,
+        operations_path=operations_path,
+    )
+
+
+def _paths_with_versions(tmp_path, manifest_version, operations_version):
+    manifest = _load(conftest.MANIFEST_PATH)
+    operations = _load(conftest.OPERATIONS_PATH)
+    if manifest_version is None:
+        manifest.pop("version", None)
+    else:
+        manifest["version"] = manifest_version
+    if operations_version is None:
+        operations.pop("version", None)
+    else:
+        operations["version"] = operations_version
+    return (
+        _write(tmp_path, "manifest.json", manifest),
+        _write(tmp_path, "operations.json", operations),
+    )
+
+
+def test_supported_version_constant_matches_generated_fixtures():
+    # The committed generated fixtures are the runtime's own vocabulary.
+    assert _load(conftest.MANIFEST_PATH)["version"] == SPEC_VERSION_SUPPORTED
+    assert _load(conftest.OPERATIONS_PATH)["version"] == SPEC_VERSION_SUPPORTED
+
+
+def test_current_version_documents_are_accepted():
+    rt = _runtime(conftest.MANIFEST_PATH, conftest.OPERATIONS_PATH)
+    assert rt is not None
+
+
+def test_older_minor_is_accepted_backward_compatible(tmp_path):
+    m, o = _paths_with_versions(tmp_path, "1.0", "1.0")
+    assert _runtime(m, o) is not None
+
+
+@pytest.mark.parametrize("version", ["1.2", "1.99", "2.0", "0.9"])
+def test_newer_minor_or_wrong_major_is_a_loud_reject(tmp_path, version):
+    m, o = _paths_with_versions(tmp_path, version, SPEC_VERSION_SUPPORTED)
+    with pytest.raises(GraphDDBError, match="not supported"):
+        _runtime(m, o)
+
+
+def test_operations_version_is_validated_independently(tmp_path):
+    m, o = _paths_with_versions(tmp_path, SPEC_VERSION_SUPPORTED, "1.2")
+    with pytest.raises(GraphDDBError, match="operations.json.*not supported"):
+        _runtime(m, o)
+
+
+@pytest.mark.parametrize("version", [None, "v1", "1", "1.x", 1.1])
+def test_missing_or_malformed_version_is_a_loud_reject(tmp_path, version):
+    m, o = _paths_with_versions(tmp_path, version, SPEC_VERSION_SUPPORTED)
+    with pytest.raises(GraphDDBError, match="missing or malformed"):
+        _runtime(m, o)