graphddb-runtime 0.1.1__tar.gz → 0.2.1__tar.gz

{graphddb_runtime-0.1.1 → graphddb_runtime-0.2.1}/PKG-INFO

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

{graphddb_runtime-0.1.1 → graphddb_runtime-0.2.1}/graphddb_runtime/batch.py

@@ -152,7 +152,8 @@ class BatchWriteExecutor:
 
     ``BatchWriteItem`` carries **no conditions** (DynamoDB has no per-request
     ``ConditionExpression`` for it) and is **not atomic** — both are properties of
-    the command-contract ``'batchWrite'`` mode (issue #64). The sleep is injected
+    the command-contract ``mode: 'parallel'`` coalesced fan-out (issue #64/#101).
+    The sleep is injected
     so unit tests can observe the backoff schedule without real delays.
     """
 

{graphddb_runtime-0.1.1 → graphddb_runtime-0.2.1}/graphddb_runtime/filters.py

@@ -2,9 +2,11 @@
 
 Port of the TypeScript ``compileFilterExpression``
 (``src/expression/filter-expression.ts``). The declarative tree carried in a
-query spec's ``filter.declarative`` is JSON-safe (the TS bridge guard rejects
-the non-serializable ``cond`` escape hatch), so only the operator/logical forms
-are handled here.
+query spec's ``filter.declarative`` is JSON-safe, so only the operator/logical
+forms are handled here. (A read-side ``cond`` escape hatch is not serialized into
+``filter.declarative``; a *write*-side ``cond`` rides the separate ``raw``
+condition spec — issue #114-B — rendered in ``runtime.py`` / ``transactions.py``,
+not here.)
 
 Names are ``#``-aliased columns (reused per distinct column); values are
 ``:``-aliased parameters — no literal interpolation. The result is returned in

{graphddb_runtime-0.1.1 → graphddb_runtime-0.2.1}/graphddb_runtime/runtime.py

@@ -64,6 +64,53 @@ def _normalize_template(template: Optional[str]) -> Optional[str]:
     return _PLACEHOLDER_RE.sub("\x00", template)
 
 
+def _resolve_condition_leaf(value: Any, params: Mapping[str, Any]) -> Any:
+    """Resolve one declarative-condition operand leaf (issue #114-A).
+
+    A ``{"$param": name}`` marker is replaced by the **typed** caller-param value
+    (so a numeric comparison stays numeric); a native literal is returned as-is.
+    """
+    if isinstance(value, dict) and isinstance(value.get("$param"), str):
+        name = value["$param"]
+        if name not in params or params[name] is None:
+            raise KeyError(f"condition references unbound parameter '{name}'")
+        return params[name]
+    return value
+
+
+def _resolve_condition_tree(node: Any, params: Mapping[str, Any]) -> Any:
+    """Resolve every ``{"$param"}`` marker in a serialized condition tree.
+
+    Walks the JSON-safe operator tree the TS planner emits (field operator
+    objects + ``and`` / ``or`` / ``not`` groups), substituting param markers with
+    typed caller-param values, and returns a tree shaped exactly like a
+    declarative ``filter`` so :func:`compile_filter` compiles it identically.
+    """
+    out: Dict[str, Any] = {}
+    for key, value in node.items():
+        if key in ("and", "or"):
+            out[key] = [_resolve_condition_tree(s, params) for s in value]
+        elif key == "not":
+            out[key] = _resolve_condition_tree(value, params)
+        else:
+            ops: Dict[str, Any] = {}
+            for op, op_val in value.items():
+                if op == "between":
+                    lo, hi = op_val
+                    ops[op] = [
+                        _resolve_condition_leaf(lo, params),
+                        _resolve_condition_leaf(hi, params),
+                    ]
+                elif op == "in":
+                    ops[op] = [_resolve_condition_leaf(v, params) for v in op_val]
+                elif op == "attributeExists":
+                    ops[op] = op_val
+                else:
+                    ops[op] = _resolve_condition_leaf(op_val, params)
+            out[key] = ops
+    return out
+
+
 def _present(records: Any) -> List[Dict[str, Any]]:
     """The present (non-``None``, dict) parent records from a result collection.
 
@@ -789,11 +836,11 @@ class GraphDDBRuntime:
         the method's declared mode:
 
         - ``single`` key  → the one referenced write op in ``commands``;
-        - ``keys[]`` + ``transact``   → one ``TransactWriteItems`` (the synthesized
+        - ``keys[]`` + ``transaction`` → one ``TransactWriteItems`` (the synthesized
           per-key ``forEach`` transaction; **atomic**, ≤25, condition-capable). An
           array of **>25 keys is rejected** — an atomic transaction cannot be split.
-        - ``keys[]`` + ``batchWrite`` → a ``BatchWriteItem`` (**non-atomic**, **no
-          conditions**), chunked ≤25 per request with ``UnprocessedItems`` retry.
+        - ``keys[]`` + ``parallel``    → a non-atomic per-key fan-out with partial
+          success (unconditioned put/delete coalesce into a ``BatchWriteItem``).
 
         ``params`` are the mutation values shared across every key (the body's
         ``params`` argument). For each key the runtime merges ``{**key, **params}``
@@ -810,9 +857,15 @@ class GraphDDBRuntime:
         shared = dict(params or {})
 
         if isinstance(key_or_keys, list):
-            self._execute_command_batch(
+            outcome = self._execute_command_batch(
                 contract_name, method_name, method, key_or_keys, shared
             )
+            # #101 `mode: 'parallel'` returns a partial-success result list; the
+            # atomic / batchWrite forms return None (fire-and-forget). Surface the
+            # parallel outcome to the caller wrapped as `{"results": [...]}`, matching
+            # the TS runtime's `CommandParallelReturn`.
+            if outcome is not None:
+                return {"results": outcome}
             return None
 
         # Single key → the referenced write surface, driven by key + params.
@@ -894,15 +947,19 @@ class GraphDDBRuntime:
         method: Mapping[str, Any],
         keys: List[Mapping[str, Any]],
         shared: Mapping[str, Any],
-    ) -> None:
-        """Apply a command method's array form per its declared batch target."""
+    ) -> Optional[List[Dict[str, Any]]]:
+        """Apply a command method's array form per its declared `mode` target.
+
+        Returns ``None`` for the atomic ``transaction`` form (fire-and-forget), or
+        the per-op partial-success result list for the #101 ``parallel`` form."""
         batch = method.get("batch")
         label = f"{contract_name}.{method_name}"
         if batch is None:
             raise ContractArityError(
                 f"command method '{label}' was called with an array of keys, but it "
-                f"declares no batched-write form. Declare a 'transact' or 'batchWrite' "
-                f"batch on the method, or call it with a single key."
+                f"declares no key-array bulk form. Author the method with "
+                f"`mode: 'transaction'` / `mode: 'parallel'`, or call it with a "
+                f"single key."
             )
         mode = batch.get("mode")
         if mode == "transaction":
@@ -912,13 +969,57 @@ class GraphDDBRuntime:
                 batch["transaction"], {**dict(shared), "keys": [dict(k) for k in keys]}
             )
             return
-        if mode == "batchWrite":
-            self._execute_batch_write(label, batch["operation"], keys, shared)
-            return
+        if mode == "parallel":
+            # #101 — non-atomic per-key fan-out with partial success. This branch
+            # returns a per-op result list; the caller (execute_command_method)
+            # surfaces it.
+            return self._execute_command_parallel(
+                label, batch["operation"], keys, shared
+            )
         raise GraphDDBError(  # pragma: no cover - serializer only emits the two above
             f"{label}: unknown batch resolution mode '{mode}'"
         )
 
+    def _execute_command_parallel(
+        self,
+        label: str,
+        command_id: str,
+        keys: List[Mapping[str, Any]],
+        shared: Mapping[str, Any],
+    ) -> List[Dict[str, Any]]:
+        """#101 ``mode: 'parallel'`` — non-atomic per-key fan-out, partial success.
+
+        Mirrors the TS ``executeParallelWrites``: when the per-key op carries no
+        condition and is put/delete, coalesce into a ``BatchWriteItem`` (chunk ≤25,
+        ``UnprocessedItems`` retry) and report every key ``{"ok": True}``; otherwise
+        issue each conditional write individually, collecting ``{"ok": bool,
+        "error"?}`` per key. A per-op failure NEVER aborts the others. The result
+        list is aligned to the input key order.
+        """
+        if not keys:
+            return []
+        spec = self._commands.get(command_id)
+        if spec is None:
+            raise ContractNotFoundError(
+                f"{label}: referenced write op '{command_id}' is not present in "
+                f"`commands`."
+            )
+        op_type = spec["type"]
+        has_condition = spec.get("condition") is not None
+        coalescible = not has_condition and op_type in ("PutItem", "DeleteItem")
+        if coalescible:
+            self._execute_batch_write(label, command_id, keys, shared)
+            return [{"ok": True} for _ in keys]
+        results: List[Dict[str, Any]] = []
+        for key in keys:
+            params = {**dict(key), **dict(shared)}
+            try:
+                self.execute_command(command_id, params)
+                results.append({"ok": True})
+            except Exception as exc:  # noqa: BLE001 - per-op partial success
+                results.append({"ok": False, "error": str(exc)})
+        return results
+
     def _execute_batch_write(
         self,
         label: str,
@@ -930,8 +1031,9 @@ class GraphDDBRuntime:
 
         Reuses :class:`BatchWriteExecutor` (chunk ≤25, ``UnprocessedItems`` retry).
         DynamoDB's ``BatchWriteItem`` supports only ``PutRequest`` / ``DeleteRequest``
-        — a command whose single-key op is an ``UpdateItem`` cannot resolve its
-        array form to a ``BatchWriteItem`` (it must declare ``transact``).
+        — a command whose single-key op is an ``UpdateItem`` cannot coalesce its
+        ``mode: 'parallel'`` array form into a ``BatchWriteItem`` (it falls back to
+        per-key ``UpdateItem`` calls, or must declare ``mode: 'transaction'``).
         """
         spec = self._commands.get(command_id)
         if spec is None:
@@ -942,8 +1044,8 @@ class GraphDDBRuntime:
         op_type = spec["type"]
         if op_type == "UpdateItem":
             raise GraphDDBError(
-                f"{label}: 'batchWrite' only supports put / delete (DynamoDB's "
-                f"BatchWriteItem has no Update request). Declare a 'transact' batch "
+                f"{label}: BatchWriteItem only supports put / delete (DynamoDB's "
+                f"BatchWriteItem has no Update request). Declare `mode: 'transaction'` "
                 f"for a batched update."
             )
         requests: List[Dict[str, Any]] = []
@@ -1613,6 +1715,35 @@ class GraphDDBRuntime:
                 values[v] = self._serializer.serialize(resolved)
                 clauses.append(f"{n} = {v}")
             request["ConditionExpression"] = " AND ".join(clauses)
+        elif kind == "expr":
+            # The declarative operator tree (issue #114-A): resolve each
+            # ``{"$param": name}`` marker to its typed caller-param value, then
+            # compile the tree to a ConditionExpression with the SAME mechanics as
+            # the read-side filter (``compile_filter``) so TS and Python emit an
+            # identical expression / semantics. ``compile_filter`` allocates
+            # ``#f`` / ``:vf`` aliases that never collide with the update ``#c`` /
+            # ``:c`` namespace, so the compiled names/values merge cleanly.
+            concrete = _resolve_condition_tree(condition["declarative"], params)
+            compiled = compile_filter(concrete, self._serializer)
+            if compiled is None:
+                return
+            names.update(compiled["ExpressionAttributeNames"])
+            values = request.setdefault("ExpressionAttributeValues", {})
+            values.update(compiled["ExpressionAttributeValues"])
+            request["ConditionExpression"] = compiled["FilterExpression"]
+        elif kind == "raw":
+            # A raw ``cond`` write condition (issue #114-B): the expression and
+            # the ``#cr_*`` name aliases are finished; bind each ``:crN`` value to
+            # its literal, or — when it is a ``{"$param": name}`` marker — to the
+            # typed caller-param value, then serialize. ``#cr_*`` / ``:cr*`` never
+            # collide with the update namespace, so they merge cleanly. The
+            # expression mirrors the TS ``serializeRawCondition`` output verbatim.
+            names.update(condition["names"])
+            values = request.setdefault("ExpressionAttributeValues", {})
+            for alias, raw_val in condition["values"].items():
+                resolved = _resolve_condition_leaf(raw_val, params)
+                values[alias] = self._serializer.serialize(resolved)
+            request["ConditionExpression"] = condition["expression"]
 
     def _add_key_attributes(
         self, entity_name: str, item: Dict[str, Any], params: Mapping[str, Any]

{graphddb_runtime-0.1.1 → graphddb_runtime-0.2.1}/graphddb_runtime/transactions.py

@@ -18,6 +18,8 @@ from __future__ import annotations
 import re
 from typing import Any, Dict, List, Mapping, Optional
 
+from .filters import compile_filter
+
 _PLACEHOLDER_RE = re.compile(r"\{[^{}]+\}")
 _WHOLE_PLACEHOLDER_RE = re.compile(r"^\{[^{}]+\}$")
 
@@ -64,6 +66,59 @@ def _resolve_value(
     return _resolve_template(template, params, element)
 
 
+def _resolve_condition_leaf(
+    value: Any,
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+) -> Any:
+    """Resolve one declarative-condition operand leaf in a transaction (#114-A).
+
+    A ``{"$param": name}`` marker binds to the typed param value, or — when the
+    name is ``item.<field>`` — to the current ``forEach`` element's field; a
+    native literal is returned as-is.
+    """
+    if isinstance(value, dict) and isinstance(value.get("$param"), str):
+        return _resolve_value("{" + value["$param"] + "}", params, element)
+    return value
+
+
+def _resolve_condition_tree(
+    node: Any,
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+) -> Any:
+    """Resolve every ``{"$param"}`` marker in a serialized condition tree (#114-A).
+
+    Mirrors the runtime's resolver but element-aware, producing a tree shaped
+    like a declarative ``filter`` for :func:`compile_filter`.
+    """
+    out: Dict[str, Any] = {}
+    for key, value in node.items():
+        if key in ("and", "or"):
+            out[key] = [_resolve_condition_tree(s, params, element) for s in value]
+        elif key == "not":
+            out[key] = _resolve_condition_tree(value, params, element)
+        else:
+            ops: Dict[str, Any] = {}
+            for op, op_val in value.items():
+                if op == "between":
+                    lo, hi = op_val
+                    ops[op] = [
+                        _resolve_condition_leaf(lo, params, element),
+                        _resolve_condition_leaf(hi, params, element),
+                    ]
+                elif op == "in":
+                    ops[op] = [
+                        _resolve_condition_leaf(v, params, element) for v in op_val
+                    ]
+                elif op == "attributeExists":
+                    ops[op] = op_val
+                else:
+                    ops[op] = _resolve_condition_leaf(op_val, params, element)
+            out[key] = ops
+    return out
+
+
 def _resolve_record(
     record: Optional[Mapping[str, str]],
     params: Mapping[str, Any],
@@ -318,6 +373,35 @@ class TransactionExpander:
             target["ConditionExpression"] = f"{fn}(#ce)"
             return
         values = target.setdefault("ExpressionAttributeValues", {})
+        if kind == "expr":
+            # Declarative operator tree (issue #114-A): resolve each
+            # ``{"$param": name}`` marker against the tx params / forEach element
+            # (a ``{item.field}`` name binds from the element), then compile with
+            # the SAME ``compile_filter`` mechanics as the read-side filter. The
+            # compiled ``#f`` / ``:vf`` aliases never collide with the update
+            # ``#u`` namespace, so they merge cleanly.
+            concrete = _resolve_condition_tree(
+                condition["declarative"], params, element
+            )
+            compiled = compile_filter(concrete, self._serializer)
+            if compiled is None:
+                return
+            names.update(compiled["ExpressionAttributeNames"])
+            values.update(compiled["ExpressionAttributeValues"])
+            target["ConditionExpression"] = compiled["FilterExpression"]
+            return
+        if kind == "raw":
+            # A raw ``cond`` write condition (issue #114-B): the expression and
+            # ``#cr_*`` aliases are finished; bind each ``:crN`` value to its
+            # literal or — when a ``{"$param": name}`` marker — against the tx
+            # params / forEach element (a ``{item.field}`` name binds from the
+            # element). ``#cr_*`` / ``:cr*`` never collide with the update aliases.
+            names.update(condition["names"])
+            for alias, raw_val in condition["values"].items():
+                resolved = _resolve_condition_leaf(raw_val, params, element)
+                values[alias] = self._serializer.serialize(resolved)
+            target["ConditionExpression"] = condition["expression"]
+            return
         clauses = []
         for i, (field, tmpl) in enumerate(condition["fields"].items()):
             n = f"#e{i}"

{graphddb_runtime-0.1.1 → graphddb_runtime-0.2.1}/graphddb_runtime.egg-info/PKG-INFO

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

{graphddb_runtime-0.1.1 → graphddb_runtime-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphddb-runtime"
-version = "0.1.1"
+version = "0.2.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.1.1 → graphddb_runtime-0.2.1}/tests/test_integration_command.py

@@ -6,11 +6,11 @@ fixtures (``UserCommands`` / ``MembershipCommands`` in operations.json) and
 asserts the **actual persisted state** after each write:
 
   - single key  → one write op (update / put / delete);
-  - key array + 'transact'   → one atomic TransactWriteItems (with a per-item
-    condition: applies on success, rolls the WHOLE batch back on failure);
-  - key array + 'batchWrite' → a non-atomic BatchWriteItem (put / delete),
-    chunked > 25 with retry;
-  - a >25-key 'transact' array is rejected (an atomic batch cannot be split).
+  - key array + `mode: 'transaction'` → one atomic TransactWriteItems (with a
+    per-item condition: applies on success, rolls the WHOLE batch back on failure);
+  - key array + `mode: 'parallel'`    → a non-atomic per-key fan-out (put / delete
+    coalesce into BatchWriteItem), chunked > 25 with retry;
+  - a >25-key `mode: 'transaction'` array is rejected (an atomic batch cannot be split).
 
 This mirrors the TS suite (__tests__/integration/command-runtime.test.ts) over
 the **same SSoT**, proving the two runtimes produce identical effects.
@@ -147,7 +147,10 @@ def test_single_update_applies(rt, client):
 
 def test_single_put_then_delete(rt, client):
     rt.execute_command_method(
-        "MembershipCommands", "add", {"groupId": "eng", "userId": "solo"}, {"role": "lead"}
+        "MembershipCommands",
+        "add",
+        {"groupId": "eng", "userId": "solo"},
+        {"role": "lead", "joinedAt": "2021-06-01T00:00:00.000Z"},
     )
     row = _membership(client, "eng", "solo")
     assert row is not None and row["role"]["S"] == "lead"
@@ -172,9 +175,21 @@ def test_transact_array_applies_atomically(rt, client):
 
 
 def test_transact_condition_rolls_back_whole_batch_on_failure(rt, client):
-    # Make e 'pending' so its `status = active` condition fails; the atomic batch
-    # must then roll d back too.
-    rt.execute_command_method("UserCommands", "disable", {"userId": "e"}, {"status": "pending"})
+    # Make e 'pending' so its literal `status = active` condition fails; the atomic
+    # batch must then roll d back too. (`disable`'s input is `literal('disabled')`,
+    # so the 'pending' precondition is written with a raw put rather than the command.)
+    client.put_item(
+        TableName=TABLE,
+        Item={
+            "PK": {"S": "USER#e"},
+            "SK": {"S": "PROFILE"},
+            "userId": {"S": "e"},
+            "name": {"S": "User e"},
+            "email": {"S": "e@x.com"},
+            "status": {"S": "pending"},
+            "createdAt": {"S": "2021-01-01T00:00:00.000Z"},
+        },
+    )
     assert _user_status(client, "e") == "pending"
 
     with pytest.raises(OperationExecutionError):
@@ -182,7 +197,7 @@ def test_transact_condition_rolls_back_whole_batch_on_failure(rt, client):
             "UserCommands",
             "disableIfActive",
             [{"userId": "d"}, {"userId": "e"}],
-            {"status": "disabled", "expected": "active"},
+            {"status": "disabled"},
         )
     # d unchanged (rolled back); e unchanged.
     assert _user_status(client, "d") == "active"
@@ -194,7 +209,7 @@ def test_transact_condition_applies_when_all_hold(rt, client):
         "UserCommands",
         "disableIfActive",
         [{"userId": "f"}],
-        {"status": "disabled", "expected": "active"},
+        {"status": "disabled"},
     )
     assert _user_status(client, "f") == "disabled"
 
@@ -205,12 +220,14 @@ def test_transact_rejects_over_25_keys(rt, client):
         rt.execute_command_method("UserCommands", "disable", keys, {"status": "disabled"})
 
 
-# ── array + batchWrite → non-atomic BatchWriteItem (chunked > 25) ────────────
+# ── array + mode:'parallel' → non-atomic BatchWriteItem (chunked > 25) ───────
 
 
 def test_batch_write_puts_and_chunks_over_25(rt, client):
     keys = [{"groupId": "big", "userId": f"m{i}"} for i in range(30)]
-    rt.execute_command_method("MembershipCommands", "add", keys, {"role": "member"})
+    rt.execute_command_method(
+        "MembershipCommands", "add", keys, {"role": "member", "joinedAt": "2021-06-01T00:00:00.000Z"}
+    )
     assert _membership(client, "big", "m0")["role"]["S"] == "member"
     assert _membership(client, "big", "m24")["role"]["S"] == "member"
     assert _membership(client, "big", "m29")["role"]["S"] == "member"
@@ -218,7 +235,9 @@ def test_batch_write_puts_and_chunks_over_25(rt, client):
 
 def test_batch_write_deletes(rt, client):
     keys = [{"groupId": "big", "userId": f"m{i}"} for i in range(30)]
-    rt.execute_command_method("MembershipCommands", "add", keys, {"role": "member"})
+    rt.execute_command_method(
+        "MembershipCommands", "add", keys, {"role": "member", "joinedAt": "2021-06-01T00:00:00.000Z"}
+    )
     rt.execute_command_method("MembershipCommands", "remove", keys)
     assert _membership(client, "big", "m0") is None
     assert _membership(client, "big", "m29") is None

{graphddb_runtime-0.1.1 → graphddb_runtime-0.2.1}/tests/test_unit.py

@@ -342,6 +342,145 @@ def test_conditional_put_emits_attribute_not_exists_on_named_field():
     assert req["ExpressionAttributeNames"]["#ce"] == "PK"
 
 
+def test_conditional_expr_tree_renders_via_compile_filter():
+    """Issue #114-A: a declarative operator tree (`{ kind: expr, declarative }`)
+    resolves its `{$param}` markers (typed) and compiles to a ConditionExpression
+    with the read-side filter mechanics (`#f`/`:vf` aliases).
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["addGroupMember"]["params"] = {
+        **rt._commands["addGroupMember"]["params"],
+        "role_0": {"type": "string", "required": True},
+        "role_1": {"type": "string", "required": True},
+    }
+    rt._commands["addGroupMember"]["condition"] = {
+        "kind": "expr",
+        "declarative": {
+            "and": [
+                {"role": {"in": [{"$param": "role_0"}, {"$param": "role_1"}]}},
+                {"role": {"beginsWith": {"$param": "role"}}},
+            ]
+        },
+    }
+    rt.execute_command(
+        "addGroupMember",
+        {
+            "groupId": "eng",
+            "userId": "alice",
+            "role": "admin",
+            "role_0": "admin",
+            "role_1": "owner",
+        },
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == (
+        "(#f0 IN (:vf0, :vf1) AND begins_with(#f0, :vf2))"
+    )
+    assert req["ExpressionAttributeNames"]["#f0"] == "role"
+    values = plain(req["ExpressionAttributeValues"])
+    assert values[":vf0"] == "admin"
+    assert values[":vf1"] == "owner"
+    assert values[":vf2"] == "admin"
+
+
+def test_conditional_expr_numeric_comparison_keeps_type():
+    """A numeric `{$param}` operand stays numeric (serialized as N), so `gt`
+    compares numerically rather than against a stringified value.
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["disableUser"]["params"] = {
+        **rt._commands["disableUser"]["params"],
+        "minVersion": {"type": "number", "required": True},
+    }
+    rt._commands["disableUser"]["condition"] = {
+        "kind": "expr",
+        "declarative": {"version": {"gt": {"$param": "minVersion"}}},
+    }
+    rt.execute_command(
+        "disableUser", {"userId": "alice", "status": "disabled", "minVersion": 3}
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == "#f0 > :vf0"
+    assert req["ExpressionAttributeValues"][":vf0"] == {"N": "3"}
+
+
+def test_conditional_expr_size_renders_size_function():
+    """Audit fix (issue #114-A): the `size` operator must compile to
+    `size(#f) = :v`, not be silently dropped. The numeric length operand stays
+    N-typed.
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["addGroupMember"]["params"] = {
+        **rt._commands["addGroupMember"]["params"],
+        "role_size": {"type": "number", "required": True},
+    }
+    rt._commands["addGroupMember"]["condition"] = {
+        "kind": "expr",
+        "declarative": {"role": {"size": {"$param": "role_size"}}},
+    }
+    rt.execute_command(
+        "addGroupMember",
+        {"groupId": "eng", "userId": "alice", "role": "admin", "role_size": 5},
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == "size(#f0) = :vf0"
+    assert req["ExpressionAttributeNames"]["#f0"] == "role"
+    assert req["ExpressionAttributeValues"][":vf0"] == {"N": "5"}
+
+
+def test_conditional_raw_cond_literal_renders_verbatim():
+    """Issue #114-B: a raw `cond` write condition (`{ kind: raw }`) attaches its
+    pre-compiled expression + `#cr_*` names verbatim, binding each `:crN` literal
+    value (here 'banned') exactly as the TS `serializeRawCondition` emitted it.
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["addGroupMember"]["condition"] = {
+        "kind": "raw",
+        "expression": "#cr_role <> :cr0 AND attribute_exists(#cr_role)",
+        "names": {"#cr_role": "role"},
+        "values": {":cr0": "banned"},
+    }
+    rt.execute_command(
+        "addGroupMember", {"groupId": "eng", "userId": "alice", "role": "admin"}
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == (
+        "#cr_role <> :cr0 AND attribute_exists(#cr_role)"
+    )
+    assert req["ExpressionAttributeNames"]["#cr_role"] == "role"
+    assert plain(req["ExpressionAttributeValues"])[":cr0"] == "banned"
+
+
+def test_conditional_raw_cond_binds_param_marker():
+    """Issue #114-B: a `{ $param }` value marker in a raw `cond` condition binds
+    from the typed caller param (here `cond_p0`), so TS and Python compare against
+    the same bound value.
+    """
+    client = FakeClient()
+    rt = make_runtime(client)
+    rt._commands["addGroupMember"]["params"] = {
+        **rt._commands["addGroupMember"]["params"],
+        "cond_p0": {"type": "string", "required": True},
+    }
+    rt._commands["addGroupMember"]["condition"] = {
+        "kind": "raw",
+        "expression": "#cr_role = :cr0",
+        "names": {"#cr_role": "role"},
+        "values": {":cr0": {"$param": "cond_p0"}},
+    }
+    rt.execute_command(
+        "addGroupMember",
+        {"groupId": "eng", "userId": "alice", "role": "admin", "cond_p0": "admin"},
+    )
+    _method, req = client.calls[0]
+    assert req["ConditionExpression"] == "#cr_role = :cr0"
+    assert plain(req["ExpressionAttributeValues"])[":cr0"] == "admin"
+
+
 # ── declarative transactions (issue #46) ────────────────────────────────────
 
 
@@ -901,7 +1040,7 @@ def test_command_method_single_update_runs_one_update_item():
 
 
 def test_command_method_transact_array_runs_one_transaction():
-    """A key array + 'transact' → ONE TransactWriteItems (one item per key)."""
+    """A key array + `mode: 'transaction'` → ONE TransactWriteItems (one item per key)."""
     client = FakeClient()
     rt = make_runtime(client)
     rt.execute_command_method(
@@ -920,26 +1059,28 @@ def test_command_method_transact_array_runs_one_transaction():
 
 
 def test_command_method_transact_carries_per_item_condition():
-    """A conditional 'transact' batch attaches the equality condition per item."""
+    """A conditional `mode: 'transaction'` batch attaches the equality condition per item."""
     client = FakeClient()
     rt = make_runtime(client)
     rt.execute_command_method(
         "UserCommands",
         "disableIfActive",
         [{"userId": "a"}, {"userId": "b"}],
-        {"status": "disabled", "expected": "active"},
+        {"status": "disabled"},
     )
     method, req = client.calls[0]
     assert method == "transact_write_items"
     update = req["TransactItems"][0]["Update"]
     assert "ConditionExpression" in update
-    assert "active" in [
-        _DESER.deserialize(v) for v in update["ExpressionAttributeValues"].values()
-    ]
+    # #101 descriptor form: the gate is a concrete-literal equality (status == 'active');
+    # the written value is the 'disabled' status param. Both appear per item.
+    values = [_DESER.deserialize(v) for v in update["ExpressionAttributeValues"].values()]
+    assert "active" in values
+    assert "disabled" in values
 
 
 def test_command_method_transact_rejects_over_25_keys():
-    """A >25-key 'transact' array is rejected — an atomic tx cannot be split."""
+    """A >25-key `mode: 'transaction'` array is rejected — an atomic tx cannot be split."""
     client = FakeClient()
     rt = make_runtime(client)
     keys = [{"userId": f"u{i}"} for i in range(26)]
@@ -949,32 +1090,38 @@ def test_command_method_transact_rejects_over_25_keys():
     assert all(m != "transact_write_items" for m, _ in client.calls)
 
 
-def test_command_method_batch_write_array_runs_batch_write_item():
-    """A key array + 'batchWrite' → a BatchWriteItem of PutRequests (no conditions)."""
+def test_command_method_parallel_guarded_create_runs_individual_conditional_puts():
+    """#101 `mode: 'parallel'` + a guarded create (attribute_not_exists) → INDIVIDUAL
+    conditional PutItem writes (not a condition-less BatchWriteItem), with per-key
+    partial-success results aligned to key order."""
     client = FakeClient()
     rt = make_runtime(client)
-    rt.execute_command_method(
+    out = rt.execute_command_method(
         "MembershipCommands",
         "add",
         [{"groupId": "eng", "userId": "a"}, {"groupId": "eng", "userId": "b"}],
-        {"role": "member"},
+        {"role": "member", "joinedAt": "1970-01-01T00:00:00Z"},
     )
-    assert len(client.calls) == 1
-    method, req = client.calls[0]
-    assert method == "batch_write_item"
-    (table, requests), = req["RequestItems"].items()
-    assert len(requests) == 2
-    item0 = plain(requests[0]["PutRequest"]["Item"])
+    # A guarded create carries a condition, so the parallel path issues one PutItem
+    # per key (concurrently) — never a coalesced BatchWriteItem.
+    methods = [m for m, _ in client.calls]
+    assert methods == ["put_item", "put_item"]
+    first = client.calls[0][1]
+    assert "ConditionExpression" in first
+    item0 = plain(first["Item"])
     assert item0["PK"] == "GROUP#eng"
     assert item0["SK"] == "USER#a"
     assert item0["role"] == "member"
+    # Partial-success result: both keys ok, aligned to input order.
+    assert out == {"results": [{"ok": True}, {"ok": True}]}
 
 
-def test_command_method_batch_write_delete_runs_delete_requests():
-    """A 'batchWrite' delete resolves to DeleteRequests keyed per input key."""
+def test_command_method_parallel_unconditioned_delete_coalesces_batch_write():
+    """#101 `mode: 'parallel'` + an UNconditioned delete coalesces into a
+    BatchWriteItem (DeleteRequests), reporting every key ok."""
     client = FakeClient()
     rt = make_runtime(client)
-    rt.execute_command_method(
+    out = rt.execute_command_method(
         "MembershipCommands",
         "remove",
         [{"groupId": "eng", "userId": "a"}, {"groupId": "eng", "userId": "b"}],
@@ -986,6 +1133,7 @@ def test_command_method_batch_write_delete_runs_delete_requests():
         "PK": "GROUP#eng",
         "SK": "USER#a",
     }
+    assert out == {"results": [{"ok": True}, {"ok": True}]}
 
 
 def test_command_method_unknown_contract_raises():