graphddb-runtime 0.9.0__tar.gz → 0.9.1__tar.gz

{graphddb_runtime-0.9.0 → graphddb_runtime-0.9.1}/PKG-INFO

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

{graphddb_runtime-0.9.0 → graphddb_runtime-0.9.1}/graphddb_runtime/runtime.py

@@ -151,6 +151,44 @@ except Exception:  # pragma: no cover
 _PLACEHOLDER_RE = re.compile(r"\{[^{}]+\}")
 
 
+def _is_conditional_check_failure(err: BaseException) -> bool:
+    """Whether ``err`` is a DynamoDB ``ConditionalCheckFailedException`` — the
+    #301 two-stage fallback trigger.
+
+    The runtime wraps every DynamoDB error in an ``OperationExecutionError`` whose
+    ``original`` is the boto ``ClientError`` (its ``response.Error.Code`` is
+    ``ConditionalCheckFailedException``). A fake test client may raise a plain
+    exception standing in for the boto error; matched by the exception name / its
+    string carrying ``ConditionalCheckFailed`` (mirroring the TS runtime's
+    name-based match). Unwraps ``__cause__`` / ``original`` so a wrapped error is
+    detected identically."""
+    seen: set = set()
+    stack: List[BaseException] = [err]
+    while stack:
+        e = stack.pop()
+        if id(e) in seen:
+            continue
+        seen.add(id(e))
+        # boto ClientError carries a structured error code.
+        response = getattr(e, "response", None)
+        if isinstance(response, Mapping):
+            code = response.get("Error", {}).get("Code")
+            if code == "ConditionalCheckFailedException":
+                return True
+        # Name / message match (fake clients, wrapped strings).
+        if "ConditionalCheckFailed" in type(e).__name__:
+            return True
+        if "ConditionalCheckFailed" in str(e):
+            return True
+        original = getattr(e, "original", None)
+        if isinstance(original, BaseException):
+            stack.append(original)
+        cause = getattr(e, "__cause__", None)
+        if isinstance(cause, BaseException):
+            stack.append(cause)
+    return False
+
+
 def _normalize_template(template: Optional[str]) -> Optional[str]:
     """Collapse every ``{placeholder}`` to a wildcard for structural matching."""
     if template is None:
@@ -1243,8 +1281,24 @@ class GraphDDBRuntime:
         else:  # pragma: no cover - schema only allows the three above
             raise GraphDDBError(f"{command_id}: unknown command type '{op_type}'")
 
+        # #301: an atomic-ADD update (`add` present) coexisting with a `condition`
+        # cannot apply the ADD when the condition fails (DynamoDB rejects the WHOLE
+        # UpdateItem on a ConditionExpression miss), yet the ADD (the mark's
+        # `version++`) MUST always happen. So the send is TWO-STAGE: primary
+        # `ADD + SET` under the condition (the common path, 1 write); on
+        # `ConditionalCheckFailedException`, a fallback `ADD`-only write (no SET, no
+        # condition). Without a condition the single ADD+SET is already
+        # unconditional (no fallback). read=0, retry=0.
+        two_stage = (
+            op_type == "UpdateItem"
+            and bool(spec.get("add"))
+            and spec.get("condition") is not None
+        )
+
         if not mw.active:
-            self._send_write_item(command_id, item, force_old_image=False)
+            self._send_update_two_stage(
+                command_id, spec, params, item, force_old_image=False, two_stage=two_stage
+            )
             return None
 
         kind = self._TYPE_TO_KIND.get(op_type)
@@ -1259,8 +1313,14 @@ class GraphDDBRuntime:
         persist_ctx = mw.persist_ctx([item], origin)
         mw.run_persist(
             persist_ctx,
-            lambda items: self._send_write_item(
-                command_id, items[0], force_old_image=force_old_image, cap=cap
+            lambda items: self._send_update_two_stage(
+                command_id,
+                spec,
+                params,
+                items[0],
+                force_old_image=force_old_image,
+                two_stage=two_stage,
+                cap=cap,
             ),
         )
         if not force_old_image:
@@ -1356,6 +1416,47 @@ class GraphDDBRuntime:
         attrs = resp.get("Attributes") if isinstance(resp, Mapping) else None
         return self._deserialize(attrs) if attrs else None
 
+    def _send_update_two_stage(
+        self,
+        command_id: str,
+        spec: Mapping[str, Any],
+        params: Mapping[str, Any],
+        item: Mapping[str, Any],
+        force_old_image: bool = False,
+        two_stage: bool = False,
+        cap: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Send one composed write, applying the #301 atomic-ADD TWO-STAGE fallback.
+
+        When ``two_stage`` is set (an UpdateItem carrying both ``add`` and a write
+        condition), the primary ``ADD + SET`` send is attempted under the condition;
+        on ``ConditionalCheckFailedException`` a fallback ``ADD``-only UpdateItem is
+        re-issued (no SET, no condition — the counter still increments). For every
+        other write this is a plain :meth:`_send_write_item`."""
+        if not two_stage:
+            return self._send_write_item(
+                command_id, item, force_old_image=force_old_image, cap=cap
+            )
+        try:
+            return self._send_write_item(
+                command_id, item, force_old_image=force_old_image, cap=cap
+            )
+        except Exception as err:  # noqa: BLE001 — re-raised unless it is a CCF
+            if not _is_conditional_check_failure(err):
+                raise
+            # Fallback: ADD-only. Rebuild the UpdateItem with `add_only=True` (drops
+            # the SET changes, the GSI re-derive AND the condition); the ADD (the
+            # version bump) still applies. Its own `_send_write_item` may still
+            # capture an ALL_OLD image for a W2 hook.
+            fallback_item = {
+                "Update": self._build_update_request(
+                    command_id, spec, params, add_only=True
+                )
+            }
+            return self._send_write_item(
+                command_id, fallback_item, force_old_image=force_old_image, cap=cap
+            )
+
     def execute_transaction(
         self,
         transaction_id: str,
@@ -2175,9 +2276,20 @@ class GraphDDBRuntime:
         self._call(command_id, self._client.put_item, self._build_put_request(spec, params))
 
     def _build_update_request(
-        self, command_id: str, spec: Mapping[str, Any], params: Mapping[str, Any]
+        self,
+        command_id: str,
+        spec: Mapping[str, Any],
+        params: Mapping[str, Any],
+        add_only: bool = False,
     ) -> Dict[str, Any]:
-        """Compose the boto3 ``update_item`` request body (no send)."""
+        """Compose the boto3 ``update_item`` request body (no send).
+
+        #301: the atomic-``ADD`` clauses (``ADD #a :d``) ride the SAME
+        UpdateExpression as the SET changes but are a distinct DynamoDB action.
+        When ``add_only`` is set (the two-stage fallback), the SET changes, the GSI
+        re-derive and the write condition are ALL dropped — only the unconditional
+        ``ADD`` survives (the counter still increments after a condition miss).
+        """
         key = {
             attr: self._serializer.serialize(resolve_template(tmpl, params))
             for attr, tmpl in spec["keyCondition"].items()
@@ -2185,34 +2297,59 @@ class GraphDDBRuntime:
         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}"
+        if not add_only:
+            for i, (field, tmpl) in enumerate(spec.get("changes", {}).items()):
+                n = f"#c{i}"
+                v = f":c{i}"
+                names[n] = field
+                # Typed value-position resolution (issue #295) — see _build_put_request.
+                values[v] = self._serializer.serialize(
+                    resolve_value_template(tmpl, params)
+                )
+                sets.append(f"{n} = {v}")
+
+            # GSI key re-derivation (issue #115): an UpdateItem that changes a GSI's
+            # composing field MUST re-derive its `<index>PK`/`<index>SK` or the index
+            # silently rots — exactly as the TS `buildUpdateInput` does. The available
+            # values are the caller `params` (key fields ∪ change fields); a GSI is
+            # affected when at least one of its template placeholders is a changed
+            # field. An affected GSI whose composing fields are not all available
+            # throws (mirroring the base-table partial-key throw).
+            self._append_gsi_rederive_sets(
+                command_id, spec, params, names, values, sets
+            )
+
+        # #301: atomic-`ADD` clauses (`ADD #a :d`, a caller `param.number()` delta).
+        # Built AFTER the SET so an ADD-only expression (`add_only`, or an update
+        # whose SET change set is empty) is legal — DynamoDB's `SET … ADD …` is one
+        # expression, and `ADD …` alone is a valid UpdateExpression. The delta rides
+        # value-position (numeric N), resolved with the SAME typed resolution the SET
+        # values use, so a `param.number()` delta lands as `N`.
+        add_clauses: List[str] = []
+        add_index = len(sets)
+        for field, tmpl in spec.get("add", {}).items():
+            n = f"#a{add_index}"
+            v = f":a{add_index}"
             names[n] = field
-            # Typed value-position resolution (issue #295) — see _build_put_request.
             values[v] = self._serializer.serialize(resolve_value_template(tmpl, params))
-            sets.append(f"{n} = {v}")
-
-        # GSI key re-derivation (issue #115): an UpdateItem that changes a GSI's
-        # composing field MUST re-derive its `<index>PK`/`<index>SK` or the index
-        # silently rots — exactly as the TS `buildUpdateInput` does. The available
-        # values are the caller `params` (key fields ∪ change fields); a GSI is
-        # affected when at least one of its template placeholders is a changed
-        # field. An affected GSI whose composing fields are not all available
-        # throws (mirroring the base-table partial-key throw).
-        self._append_gsi_rederive_sets(
-            command_id, spec, params, names, values, sets
-        )
+            add_clauses.append(f"{n} {v}")
+            add_index += 1
 
         request: Dict[str, Any] = {
             "TableName": self._physical_table(spec["tableName"]),
             "Key": key,
         }
+        expr_parts: List[str] = []
         if sets:
-            request["UpdateExpression"] = "SET " + ", ".join(sets)
+            expr_parts.append("SET " + ", ".join(sets))
+        if add_clauses:
+            expr_parts.append("ADD " + ", ".join(add_clauses))
+        if expr_parts:
+            request["UpdateExpression"] = " ".join(expr_parts)
             request["ExpressionAttributeNames"] = names
             request["ExpressionAttributeValues"] = values
-        self._apply_condition(spec, request, params)
+        if not add_only:
+            self._apply_condition(spec, request, params)
         return request
 
     def _run_update_item(

{graphddb_runtime-0.9.0 → graphddb_runtime-0.9.1}/graphddb_runtime/templates.py

@@ -161,15 +161,19 @@ def resolve_value_template(template: Any, params: Mapping[str, Any]) -> Any:
     STRING param resolves to the same string either way, so pre-#295 outputs are
     byte-identical.
     """
-    if isinstance(template, str):
-        m = _WHOLE_TOKEN.fullmatch(template)
-        if m is not None:
-            name = m.group(1)
-            if name in params and params[name] is not None:
-                return params[name]
-            raise ParameterValidationError(
-                f"template '{template}' references unbound parameter '{name}'"
-            )
+    if not isinstance(template, str):
+        # A TYPED literal (a `number` / `boolean` carried verbatim by the emitter,
+        # issue #299) is not a template — return it as-is so it marshals to `N` /
+        # `BOOL`. Only strings carry `{param}` placeholders.
+        return template
+    m = _WHOLE_TOKEN.fullmatch(template)
+    if m is not None:
+        name = m.group(1)
+        if name in params and params[name] is not None:
+            return params[name]
+        raise ParameterValidationError(
+            f"template '{template}' references unbound parameter '{name}'"
+        )
     return resolve_template(template, params)
 
 

{graphddb_runtime-0.9.0 → graphddb_runtime-0.9.1}/graphddb_runtime.egg-info/PKG-INFO

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

{graphddb_runtime-0.9.0 → graphddb_runtime-0.9.1}/graphddb_runtime.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ graphddb_runtime.egg-info/SOURCES.txt
 graphddb_runtime.egg-info/dependency_links.txt
 graphddb_runtime.egg-info/requires.txt
 graphddb_runtime.egg-info/top_level.txt
+tests/test_atomic_add_command.py
 tests/test_concurrency.py
 tests/test_contract_runtime.py
 tests/test_crosslang_python_cells.py

{graphddb_runtime-0.9.0 → graphddb_runtime-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphddb-runtime"
-version = "0.9.0"
+version = "0.9.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.9.1/tests/test_atomic_add_command.py

@@ -0,0 +1,184 @@
+"""Atomic-ADD standalone update command — two-stage fallback (issue #301).
+
+Mirrors the TS ``__tests__/runtime/atomic-add-command.test.ts`` fake-executor
+test against a recording-fake DynamoDB client (no Docker). The ``StatsTreeCmd.mark``
+command carries ``add: { computeVersion }`` (an atomic `ADD`) coexisting with a
+CONDITIONAL SET of ``minPendingAt``/``computedAt``. The correctness guarantee is
+that the ADD is ALWAYS applied while the SET is conditional; because DynamoDB
+discards the WHOLE UpdateItem on a ConditionExpression miss, the runtime performs
+a transparent TWO-STAGE:
+
+  1. primary: ``ADD + SET`` under the condition (the common path, 1 write);
+  2. on ConditionalCheckFailedException: fallback ``ADD``-only (no SET, no
+     condition) — the counter still increments.
+
+The two cases below pin BOTH branches on the fake client:
+
+  * common path (condition holds → single UpdateItem, ADD+SET together);
+  * fallback path (first UpdateItem throws CCF → a SECOND UpdateItem that is
+    ADD-only: no SET-#c aliases, no ConditionExpression).
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from graphddb_runtime import GraphDDBRuntime
+
+import conftest
+
+
+def _mark_runtime(client) -> GraphDDBRuntime:
+    return GraphDDBRuntime(
+        dynamodb_client=client,
+        manifest_path=conftest.MANIFEST_PATH,
+        operations_path=conftest.OPERATIONS_PATH,
+    )
+
+
+class _ConditionalCheckFailed(Exception):
+    """A stand-in for the boto ConditionalCheckFailedException the runtime maps to
+    the two-stage fallback (matched by name, mirroring the TS name-based match)."""
+
+
+class _ProvisionedThroughputExceeded(Exception):
+    """A stand-in for a NON-CCF boto ``ClientError`` (a throttling error). It carries
+    a boto-style ``response.Error.Code`` that is NOT ``ConditionalCheckFailedException``,
+    so the runtime's two-stage matcher rejects it and re-raises (no ADD-only fallback)."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.response = {
+            "Error": {
+                "Code": "ProvisionedThroughputExceededException",
+                "Message": message,
+            }
+        }
+
+
+class _MarkClient:
+    """Records every update_item request; optionally throws a ConditionalCheckFailed
+    on the FIRST update_item to drive the two-stage fallback."""
+
+    def __init__(self, fail_first: bool):
+        self.updates: list[dict] = []
+        self._fail_first = fail_first
+
+    def update_item(self, **kwargs):
+        self.updates.append(kwargs)
+        if self._fail_first and len(self.updates) == 1:
+            raise _ConditionalCheckFailed(
+                "An error occurred (ConditionalCheckFailedException) when calling "
+                "the UpdateItem operation: The conditional request failed"
+            )
+        return {}
+
+
+class _NonCCFMarkClient:
+    """Records every update_item request; the FIRST update_item raises a NON-CCF error
+    (a throttling ``ProvisionedThroughputExceededException``) to prove that a non-CCF
+    failure propagates and does NOT trigger the ADD-only two-stage fallback."""
+
+    def __init__(self):
+        self.updates: list[dict] = []
+
+    def update_item(self, **kwargs):
+        self.updates.append(kwargs)
+        if len(self.updates) == 1:
+            raise _ProvisionedThroughputExceeded(
+                "An error occurred (ProvisionedThroughputExceededException) when "
+                "calling the UpdateItem operation: rate exceeded"
+            )
+        return {}
+
+    def put_item(self, **kwargs):  # pragma: no cover - defensive
+        raise AssertionError("mark must not put_item")
+
+    def delete_item(self, **kwargs):  # pragma: no cover - defensive
+        raise AssertionError("mark must not delete_item")
+
+    # The mark command never issues these, but the runtime probes for them.
+    def put_item(self, **kwargs):  # pragma: no cover - defensive
+        raise AssertionError("mark must not put_item")
+
+    def delete_item(self, **kwargs):  # pragma: no cover - defensive
+        raise AssertionError("mark must not delete_item")
+
+
+_MARK_PARAMS = {
+    "part": "n1",
+    "child": "leaf",
+    "computeVersion": 1,
+    "minPendingAt": 1700000000000,
+    "computedAt": 1700000001000,
+}
+
+
+def _has_add_clause(expr: str) -> bool:
+    return "ADD " in expr
+
+
+def _has_set_clause(expr: str) -> bool:
+    return "SET " in expr
+
+
+def test_mark_common_path_single_write_add_and_set():
+    """Condition holds → ONE UpdateItem carrying ADD + SET together, under the
+    ConditionExpression. No fallback."""
+    client = _MarkClient(fail_first=False)
+    rt = _mark_runtime(client)
+
+    rt.execute_command("StatsTreeCmd__mark", _MARK_PARAMS)
+
+    assert len(client.updates) == 1, "common path must be a SINGLE UpdateItem"
+    req = client.updates[0]
+    expr = req["UpdateExpression"]
+    assert _has_add_clause(expr), f"primary must carry ADD: {expr!r}"
+    assert _has_set_clause(expr), f"primary must carry SET: {expr!r}"
+    assert "ConditionExpression" in req, "primary is CONDITIONAL"
+    # The ADD delta rides as a numeric N value.
+    vals = req["ExpressionAttributeValues"]
+    assert any(v == {"N": "1"} for v in vals.values()), vals
+
+
+def test_mark_fallback_add_only_on_condition_fail():
+    """First UpdateItem throws ConditionalCheckFailed → a SECOND UpdateItem that is
+    ADD-only: it carries the ADD clause, NO SET clause, and NO ConditionExpression —
+    the computeVersion++ still applies while the SET is dropped."""
+    client = _MarkClient(fail_first=True)
+    rt = _mark_runtime(client)
+
+    rt.execute_command("StatsTreeCmd__mark", _MARK_PARAMS)
+
+    assert len(client.updates) == 2, "condition miss must trigger EXACTLY one retry"
+    primary, fallback = client.updates
+    # Primary: ADD + SET under the condition.
+    assert _has_add_clause(primary["UpdateExpression"])
+    assert _has_set_clause(primary["UpdateExpression"])
+    assert "ConditionExpression" in primary
+    # Fallback: ADD-only — no SET, no condition.
+    fexpr = fallback["UpdateExpression"]
+    assert _has_add_clause(fexpr), f"fallback must carry ADD: {fexpr!r}"
+    assert not _has_set_clause(fexpr), f"fallback must NOT carry SET: {fexpr!r}"
+    assert "ConditionExpression" not in fallback, "fallback must be UNCONDITIONAL"
+    # The ADD delta still rides in the fallback as the same numeric N.
+    fvals = fallback["ExpressionAttributeValues"]
+    assert any(v == {"N": "1"} for v in fvals.values()), fvals
+
+
+def test_mark_non_ccf_error_propagates():
+    """A NON-condition error on the primary must NOT be swallowed by the two-stage —
+    it propagates and no ADD-only fallback fires. Parity with the Rust
+    ``mark_non_ccf_error_propagates`` and the Go ``TestMarkNonCCFErrorPropagates``."""
+    client = _NonCCFMarkClient()
+    rt = _mark_runtime(client)
+
+    with pytest.raises(Exception) as excinfo:
+        rt.execute_command("StatsTreeCmd__mark", _MARK_PARAMS)
+
+    # The original throttling error must surface (never rewritten to a CCF path).
+    assert "ProvisionedThroughputExceeded" in str(excinfo.value), excinfo.value
+    # Exactly ONE UpdateItem: a non-CCF error must NOT trigger the ADD-only retry.
+    assert len(client.updates) == 1, "a non-CCF error must NOT trigger a second write"