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

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

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

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

@@ -57,13 +57,21 @@ from .templates import (
     validate_params,
 )
 from .transactions import MAX_TRANSACT_ITEMS, TransactionExpander
+from .transactions import _guard_holds as _tx_guard_holds
 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"
+#:
+#: Phase 3 S6 (#266): bumped 1.1 -> 1.2 — the S6 half of the "one release column"
+#: 1.2 bump (TS reached 1.2 in S5). This runtime now EVALUATES the 1.2 SCP
+#: Expression IR ``guard`` vocabulary (see :func:`transactions._guard_holds`), so a
+#: guard-bearing 1.2 bundle is ACCEPTED and executed on py/rust/go (matching TS).
+#: Guard-free bundles remain stamped 1.1 by the generator (the conditional stamper
+#: is unchanged), so an older runtime still runs them.
+SPEC_VERSION_SUPPORTED = "1.2"
 
 
 def _validate_spec_version(document: Mapping[str, Any], label: str) -> None:
@@ -260,15 +268,15 @@ class GraphDDBRuntime:
     def use(self, mw: Any) -> None:
         """Register a host-side middleware (read R1–R5 / write W1–W5 hooks).
 
-        Mirrors the TS ``DDBModel.use``: appended last, so it runs last in the
-        FIFO ``before*`` order and first in the LIFO ``after`` / ``onError``
+        Mirrors the TS ``graphddb.config.use``: appended last, so it runs last in
+        the FIFO ``before*`` order and first in the LIFO ``after`` / ``onError``
         order. The middleware is never serialized.
         """
         self._middleware.use(mw)
 
     def clear_middleware(self) -> None:
         """Remove every registered middleware (teardown / tests). Mirrors the TS
-        ``DDBModel.clearMiddleware``."""
+        ``graphddb.config.clearMiddleware``."""
         self._middleware.clear()
 
     def get_middleware(self) -> Tuple[Any, ...]:
@@ -581,6 +589,33 @@ class GraphDDBRuntime:
         opts = dict(params or {})
 
         is_array = isinstance(key_or_keys, (list, tuple))
+
+        # A **relation-traversal** contract read lowers to >1 operation (the root
+        # read + one leg per resolved relation; e.g. getUserByEmail → 4 ops,
+        # getGroupAccess → 3 ops). The single-op point/range executors below cannot
+        # assemble a multi-op result — that is the job of :meth:`execute_query`,
+        # which walks the whole ``operations`` list and merges the relation legs.
+        # So delegate a multi-op single-key read to the relation-assembly path (the
+        # exact path ``execute_query`` uses), keyed by the method's referenced
+        # operation id. An array of keys against such a method is an N+1 fan-out
+        # (one full traversal per key), forbidden by the same N+1 rule that rejects
+        # a range array — a single-key relation read is the only reachable shape.
+        if len(op_spec.get("operations", [])) > 1:
+            if is_array:
+                raise ContractArityError(
+                    f"{contract_name}.{method_name}: a relation-traversal method "
+                    f"(it lowers to multiple operations) was called with an array of "
+                    f"keys. Each key is a full traversal, so an array would be an N+1 "
+                    f"fan-out — forbidden by the contract's N+1 rule. Loop in "
+                    f"application code for N independent reads."
+                )
+            validate_params(
+                key_or_keys,
+                op_spec.get("params", {}),
+                operation_id=f"{contract_name}.{method_name}",
+            )
+            return self.execute_query(method["operation"], key_or_keys, opts)
+
         if is_array:
             # Only a method whose ``inputArity`` is ``'either'`` coalesces a key
             # array into one batched call. A ``'single'`` method must reject an
@@ -668,12 +703,17 @@ class GraphDDBRuntime:
     def _contract_query_op(
         self, contract_name: str, method_name: str, method: Mapping[str, Any]
     ) -> Mapping[str, Any]:
-        """The single referenced read op spec for a contract query method.
-
-        A contract method resolves to exactly one declarative read op (#58). Any
-        External Query compositions (#63) it declares are carried separately on
-        the method spec (``compose``) and resolved by :meth:`_resolve_compositions`
-        after the parent step — they do **not** add operations to this op spec.
+        """The referenced read op spec for a contract query method.
+
+        A method's referenced operation carries **one or more** read operations: a
+        plain point/range read is a single operation, whereas a relation-traversal
+        read lowers to the root read PLUS one leg per resolved relation (e.g.
+        getUserByEmail → 4 ops). ``execute_query_method`` routes a multi-op spec
+        through the relation-assembly path (:meth:`execute_query`); the single-op
+        point/range executors handle the ``len == 1`` case. Any External Query
+        compositions (#63) a method declares are carried separately on the method
+        spec (``compose``) — they do **not** add operations to this op spec (and a
+        composed child is always a ``point`` read, i.e. a single operation).
         """
         op_name = method["operation"]
         spec = self._queries.get(op_name)
@@ -683,10 +723,10 @@ class GraphDDBRuntime:
                 f"not present in `queries`."
             )
         operations = spec.get("operations", [])
-        if len(operations) != 1:
+        if len(operations) < 1:
             raise GraphDDBError(
-                f"{contract_name}.{method_name}: a single-contract query method must "
-                f"resolve to exactly one read operation, found {len(operations)}."
+                f"{contract_name}.{method_name}: a query method must resolve to at "
+                f"least one read operation, found {len(operations)}."
             )
         return spec
 
@@ -1409,6 +1449,9 @@ class GraphDDBRuntime:
                 continue  # ConditionCheck — not a logical write op.
             for_each = item.get("forEach")
             when = item.get("when")
+            # Issue #266 (Phase 3 S6): a guard-false item is skipped here too, so
+            # W1 does not fire for a write the expander drops (parity with `when`).
+            guard = item.get("guard")
             if for_each:
                 source = params.get(for_each["source"])
                 if not isinstance(source, list):
@@ -1416,6 +1459,8 @@ class GraphDDBRuntime:
                 for element in source:
                     if when and not _tx_when_holds(when, params, element):
                         continue
+                    if guard is not None and not _tx_guard_holds(guard, params, element):
+                        continue
                     op_params = dict(params)
                     op_params.update({f"item.{k}": v for k, v in element.items()})
                     op_params.update(element)
@@ -1423,6 +1468,8 @@ class GraphDDBRuntime:
             else:
                 if when and not _tx_when_holds(when, params, None):
                     continue
+                if guard is not None and not _tx_guard_holds(guard, params, None):
+                    continue
                 yield kind, item, dict(params)
 
     # ── command-contract execution (issue #64) ──────────────────────────────

{graphddb_runtime-0.7.9 → graphddb_runtime-0.8.0}/graphddb_runtime/transactions.py

@@ -18,6 +18,9 @@ from __future__ import annotations
 import re
 from typing import Any, Dict, List, Mapping, Optional
 
+from behavior_contracts import ExprFailure as _ExprFailure
+from behavior_contracts import evaluate_expression as _evaluate_expression
+
 from .filters import compile_filter
 
 _PLACEHOLDER_RE = re.compile(r"\{[^{}]+\}")
@@ -168,6 +171,134 @@ def _when_holds(
     return left == right if when["op"] == "eq" else left != right
 
 
+# ── SCP guard evaluation seam (issue #266, Phase 3 S6) ────────────────────────
+#
+# The branch-for-branch port of the TS ``evaluateGuard`` seam
+# (``src/runtime/guard-eval.ts``, S5 / #265). A ``guard`` on a transaction item is
+# an SCP Expression IR node — a boolean predicate over the transaction ``input``
+# surface and, inside a ``forEach``, the current ``item`` element. S1 loud-rejected
+# every guard-bearing bundle; S6 turns that reject into EVALUATION for the
+# client-side ``input`` / ``item`` class, delegating the normative semantics to the
+# shared ``behavior_contracts`` evaluator (``evaluate_expression``) — the SAME SSoT
+# the TS/Rust/Go runtimes evaluate against, so a guard decides identically in every
+# language: typed ``eq`` (int != string), i64 checked arithmetic, code-point string
+# ordering, truncated-division ``mod`` sign.
+#
+# The two-condition-class rule (identical to TS): a ``guard`` references ONLY
+# ``input`` / ``item`` (known client-side before the write), so guard-false skips
+# the item — the same semantics the legacy ``when`` string-compare guard has, no
+# DynamoDB round-trip. An expression that reads a DynamoDB attribute of the row
+# being written is the ``scpExpr`` write-condition class (out of S6 scope) and must
+# lower to a ``ConditionExpression``; :func:`_assert_guard_scopes` fail-closes a
+# guard whose refs escape ``input`` / ``item`` so a client-side stale check can
+# never happen.
+
+_GUARD_SCOPE_ROOTS = frozenset(("input", "item"))
+
+
+def _assert_guard_scopes(node: Any, context: str) -> None:
+    """Walk an expression IR node; reject any ``ref`` / ``refOpt`` whose ROOT segment
+    is not a client-side guard scope (``input`` / ``item``). Mirrors the TS
+    ``assertGuardScopes`` — a ``prop``-rooted guard is the write-condition class that
+    must lower to a ``ConditionExpression``; evaluating it client-side would be a
+    stale read, so it is loud-rejected (issue #266)."""
+    if not isinstance(node, Mapping):
+        return
+    ref = node.get("ref")
+    if ref is None:
+        ref = node.get("refOpt")
+    if isinstance(ref, list):
+        root = ref[0] if ref else None
+        if isinstance(root, str) and root not in _GUARD_SCOPE_ROOTS:
+            raise ValueError(
+                f"{context}: this guard references '{root}', but a client-side guard "
+                "may only reference the transaction 'input' / fan-out 'item' scopes. "
+                "An expression that reads a DynamoDB attribute must lower to a "
+                "ConditionExpression (write-condition class), not be evaluated "
+                "client-side (issue #266). Refusing to evaluate a stale check."
+            )
+        return
+    # Recurse every nested node (operator args, obj values, arr elements).
+    for value in node.values():
+        if isinstance(value, list):
+            for child in value:
+                _assert_guard_scopes(child, context)
+        elif isinstance(value, Mapping):
+            # ``{obj: {...}}`` construction — its values are nested nodes.
+            for child in value.values():
+                _assert_guard_scopes(child, context)
+
+
+def _to_shared_value(v: Any) -> Any:
+    """Convert a plain graphddb runtime value into the ``behavior_contracts`` value
+    model, classifying by the VALUE's integrality — NOT by its declared numeric
+    subtype. This is the branch-for-branch mirror of the TS ``toSharedValue``
+    (#253): TS maps an integral JS ``number`` (``5`` == ``5.0``) to a ``bigint``
+    (int), so a scope value of ``5.0`` compares equal to an ``{int:"5"}`` literal.
+
+    graphddb's ``@number`` (R7) draws no int/float type distinction, so the only
+    cross-language-consistent rule is to classify by value integrality: an
+    integral-valued ``float`` (``5.0``) becomes a Python ``int`` (an int in the
+    shared model), a fractional ``float`` stays a ``float``. Without this, Python's
+    native ``isinstance(v, float)`` would classify ``5.0`` as float and an
+    ``input.n == {int:"5"}`` guard would TYPE_MISMATCH where TS returns True —
+    a cross-language divergence (S5 audit rule, issue #266)."""
+    if isinstance(v, bool):
+        # bool is an int subclass in Python; keep it a bool in the shared model.
+        return v
+    if isinstance(v, float):
+        # Integral-valued float -> int (matches TS Number.isInteger). NaN/Inf are
+        # non-integral, so they stay float and the shared core loud-rejects them.
+        if v.is_integer():
+            return int(v)
+        return v
+    if isinstance(v, list):
+        return [_to_shared_value(e) for e in v]
+    if isinstance(v, Mapping):
+        return {k: _to_shared_value(field) for k, field in v.items()}
+    return v
+
+
+def _to_shared_params(params: Mapping[str, Any]) -> Dict[str, Any]:
+    return {name: _to_shared_value(value) for name, value in params.items()}
+
+
+def _guard_holds(
+    guard: Mapping[str, Any],
+    params: Mapping[str, Any],
+    element: Optional[Mapping[str, Any]],
+    context: str = "declarative transaction guard",
+) -> bool:
+    """Evaluate a ``guard`` ExpressionSpec against the transaction ``input`` params
+    and the (optional) ``forEach`` element, returning its boolean truth value.
+    Delegates the normative semantics to the shared ``behavior_contracts`` evaluator
+    — the same SSoT every other-language runtime evaluates against (S5/S6/S7).
+
+    Raises ``ValueError`` if the guard escapes the ``input`` / ``item`` scopes
+    (:func:`_assert_guard_scopes`), if the shared evaluator reports a Failure (i64
+    overflow, type mismatch, unknown op, unknown exprVersion, …), or if the guard
+    does not evaluate to a boolean — all fail-closed / loud (issue #266)."""
+    expr = guard["expr"]
+    _assert_guard_scopes(expr, context)
+    scope: Dict[str, Any] = {"input": _to_shared_params(params)}
+    if element is not None:
+        scope["item"] = _to_shared_value(dict(element))
+    try:
+        result = _evaluate_expression(expr, scope)
+    except _ExprFailure as exc:
+        code = getattr(exc, "code", "?")
+        raise ValueError(
+            f"{context}: guard evaluation failed ({code}): {exc}"
+        ) from exc
+    if not isinstance(result, bool):
+        got = "null" if result is None else type(result).__name__
+        raise ValueError(
+            f"{context}: a guard expression must evaluate to a boolean, got {got} "
+            "(issue #266)."
+        )
+    return result
+
+
 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
@@ -477,6 +608,19 @@ class TransactionExpander:
                 values[alias] = self._serializer.serialize(resolved)
             target["ConditionExpression"] = condition["expression"]
             return
+        if kind == "scpExpr":
+            # Issue #266 (Phase 3 S6): the ``scpExpr`` write-condition class refs a
+            # DynamoDB attribute of the row being written, so it must lower to a
+            # ConditionExpression — NOT be evaluated client-side (a stale read is a
+            # #242-type silent drop). That lowering is out of S6 scope, so fail
+            # loudly rather than execute the write with its condition ignored.
+            # (Mirrors the TS ``applyCondition`` scpExpr reject.)
+            raise ValueError(
+                "declarative transaction: this runtime does not evaluate scpExpr "
+                "write conditions yet (spec 1.2 expression vocabulary, issue #261); "
+                "the write-condition class must lower to a ConditionExpression. "
+                "Refusing to execute the write with its condition ignored."
+            )
         clauses = []
         for i, (field, tmpl) in enumerate(condition["fields"].items()):
             n = f"#e{i}"
@@ -667,6 +811,13 @@ class TransactionExpander:
         for item in spec.get("items", []):
             for_each = item.get("forEach")
             when = item.get("when")
+            # Issue #266 (Phase 3 S6): a `guard` (SCP Expression IR over the
+            # `input` / fan-out `item` scopes) is EVALUATED via behavior_contracts
+            # — the normative SSoT every runtime shares. Guard-false skips the item
+            # (matching the legacy string-compare `when`); guard-true keeps it. An
+            # attribute-referencing guard is loud-rejected inside `_guard_holds`
+            # (write-condition class, out of scope). Matches the TS S5 seam.
+            guard = item.get("guard")
             if for_each:
                 source = params.get(for_each["source"])
                 if not isinstance(source, list):
@@ -677,9 +828,13 @@ class TransactionExpander:
                 for element in source:
                     if when and not _when_holds(when, params, element):
                         continue
+                    if guard is not None and not _guard_holds(guard, params, element):
+                        continue
                     expanded.append(self._build_item(item, params, element))
             else:
                 if when and not _when_holds(when, params, None):
                     continue
+                if guard is not None and not _guard_holds(guard, params, None):
+                    continue
                 expanded.append(self._build_item(item, params, None))
         return _collapse_same_key_items(expanded)

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

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

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

@@ -26,6 +26,7 @@ tests/test_crosslang_python_cells.py
 tests/test_description.py
 tests/test_description_followups.py
 tests/test_description_jsdoc.py
+tests/test_guard_eval.py
 tests/test_integration.py
 tests/test_integration_binding_contract.py
 tests/test_integration_command.py

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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphddb-runtime"
-version = "0.7.9"
+version = "0.8.0"
 description = "Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44)."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -14,7 +14,7 @@ license = { text = "MIT" }
 # canonicalisation) are delegated to the extracted shared package
 # ``behavior-contracts`` (import name ``behavior_contracts``). The runtime
 # imports it unconditionally, so it is a HARD dependency.
-dependencies = ["boto3>=1.26", "behavior-contracts==0.1.2"]
+dependencies = ["boto3>=1.26", "behavior-contracts==0.1.3"]
 
 [project.optional-dependencies]
 test = ["pytest>=7.0"]

{graphddb_runtime-0.7.9 → graphddb_runtime-0.8.0}/tests/test_concurrency.py

@@ -166,7 +166,7 @@ def test_independent_relation_stage_runs_concurrently():
 
     # If the two sibling queries did NOT overlap, the barrier (timeout=3) would
     # raise BrokenBarrierError here. Reaching the assertions proves concurrency.
-    out = rt.execute_query("getGroupAccess", {"groupId": "eng"})
+    out = rt.execute_query("GroupAccessMulti__getGroupAccess", {"groupId": "eng"})
 
     assert out["members"]["items"][0]["userId"] == "alice"
     assert out["permissions"]["items"][0]["resource"] == "codebase"
@@ -192,9 +192,9 @@ def test_stage_concurrency_is_bounded_by_the_declared_limit():
     client = _CountingGroupAccessClient()
     rt = GraphDDBRuntime(client, MULTI_MANIFEST, MULTI_OPS)
     # Force the declared bound to 1 on the loaded spec.
-    rt._queries["getGroupAccess"]["executionPlan"]["concurrency"] = 1
+    rt._queries["GroupAccessMulti__getGroupAccess"]["executionPlan"]["concurrency"] = 1
 
-    rt.execute_query("getGroupAccess", {"groupId": "eng"})
+    rt.execute_query("GroupAccessMulti__getGroupAccess", {"groupId": "eng"})
     # Bound 1 → strictly one query at a time.
     assert client.peak_in_flight == 1
     assert client.query_count == 2
@@ -215,9 +215,9 @@ def test_plan_absent_falls_back_to_sequential():
     client.barrier = threading.Barrier(1, timeout=3)  # no overlap expected
     rt = GraphDDBRuntime(client, MULTI_MANIFEST, MULTI_OPS)
     # Strip the plan → exercise the backward-compatible (sequential) fallback.
-    rt._queries["getGroupAccess"].pop("executionPlan", None)
+    rt._queries["GroupAccessMulti__getGroupAccess"].pop("executionPlan", None)
 
-    out = rt.execute_query("getGroupAccess", {"groupId": "eng"})
+    out = rt.execute_query("GroupAccessMulti__getGroupAccess", {"groupId": "eng"})
     assert out["members"]["items"][0]["userId"] == "alice"
     assert out["permissions"]["items"][0]["resource"] == "codebase"
     # Plan-less → each op its own stage → strictly one query in flight at a time.
@@ -227,7 +227,7 @@ def test_plan_absent_falls_back_to_sequential():
 def test_relation_stages_reads_plan_groups():
     """Unit: `_relation_stages` derives stages from the plan (root dropped)."""
     rt = GraphDDBRuntime(_BarrierGroupAccessClient(), MULTI_MANIFEST, MULTI_OPS)
-    spec = rt._queries["getGroupAccess"]
+    spec = rt._queries["GroupAccessMulti__getGroupAccess"]
     operations = spec["operations"]
     # Plan present: [[0],[1,2]] → relation stages [[1, 2]] (root index 0 dropped).
     assert rt._relation_stages(spec, operations) == [[1, 2]]
@@ -243,7 +243,7 @@ def test_relation_stages_reads_plan_groups():
 def test_deep_chain_plan_stages_are_sequential():
     """A result-dependent chain (getUserByEmail) stages into ordered single-op stages."""
     rt = GraphDDBRuntime(_BarrierGroupAccessClient(), MULTI_MANIFEST, MULTI_OPS)
-    spec = rt._queries["getUserByEmail"]
+    spec = rt._queries["UserByEmailMulti__getUserByEmail"]
     # Plan [[0],[1],[2],[3]] → relation stages [[1],[2],[3]] (each depends on prior).
     assert rt._relation_stages(spec, spec["operations"]) == [[1], [2], [3]]
 

{graphddb_runtime-0.7.9 → graphddb_runtime-0.8.0}/tests/test_description.py

@@ -38,7 +38,7 @@ def test_manifest_carries_entity_and_field_description() -> None:
 
 def test_operations_carries_query_param_and_contract_description() -> None:
     ops = _operations()
-    get_group = ops["queries"]["getGroup"]
+    get_group = ops["queries"]["GroupByIdRead__get"]
     assert get_group["description"] == "Fetch a single group by its id."
     assert get_group["params"]["groupId"]["description"] == "The group id to fetch."
     # The contract method description rides the `contracts` map.
@@ -48,7 +48,7 @@ def test_operations_carries_query_param_and_contract_description() -> None:
 
 def test_undescribed_query_has_no_description_key() -> None:
     # `getUser` declares no description — backward compatible.
-    get_user = _operations()["queries"]["getUser"]
+    get_user = _operations()["queries"]["UserByIdRead__get"]
     assert "description" not in get_user
 
 

{graphddb_runtime-0.7.9 → graphddb_runtime-0.8.0}/tests/test_description_jsdoc.py

@@ -63,7 +63,7 @@ def test_manifest_carries_jsdoc_gsi_description() -> None:
 
 
 def test_operations_carry_jsdoc_query_and_param_description() -> None:
-    get_user = _operations()["queries"]["getUserDocumented"]
+    get_user = _operations()["queries"]["UserDocumentedRead__getUserDocumented"]
     assert get_user["description"] == (
         "#165 JSDoc-as-default (query): fetch a single user by id (JSDoc source)."
     )

graphddb_runtime-0.8.0/tests/test_guard_eval.py

@@ -0,0 +1,146 @@
+"""SCP guard evaluation tests (issue #266, Phase 3 S6).
+
+The py runtime evaluates a transaction-item ``guard`` (an SCP Expression IR node
+over the ``input`` / fan-out ``item`` scopes) via the shared ``behavior_contracts``
+evaluator — the SAME normative SSoT the TS S5 seam (``src/runtime/guard-eval.ts``)
+evaluates against, so a guard decides IDENTICALLY across TS/py/rust/go. These
+tests pin the adversarial matrix the S5 audit covered: typed ``eq`` (int != string),
+i64 boundary, code-point string compare, truncated ``mod`` sign, non-bool loud,
+unknown-op loud, scope-escape loud, and — the critical cross-language rule — an
+integral-valued number classifies as int (matching the TS #253 adapter), NOT as
+float -> TYPE_MISMATCH.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import pytest
+
+from graphddb_runtime.transactions import _guard_holds, _to_shared_value
+
+
+def _holds(expr: Any, params: dict, element: Optional[dict] = None) -> bool:
+    return _guard_holds({"exprVersion": 1, "expr": expr}, params, element)
+
+
+# ── the integral-float classification rule (the crux, S5 audit) ───────────────
+
+
+def test_integral_float_param_classifies_as_int():
+    # A param value of 5.0 must compare EQUAL to an {int:"5"} literal — matching
+    # the TS adapter (Number.isInteger(5.0) -> bigint). graphddb @number (R7) has
+    # no int/float distinction, so classification is by VALUE integrality.
+    assert _holds({"eq": [{"ref": ["input", "n"]}, {"int": "5"}]}, {"n": 5.0}) is True
+
+
+def test_integral_int_param_classifies_as_int():
+    assert _holds({"eq": [{"ref": ["input", "n"]}, {"int": "5"}]}, {"n": 5}) is True
+
+
+def test_fractional_float_param_mismatches_int_literal():
+    # 5.5 is genuinely a float; comparing it to an int literal is a TYPE_MISMATCH
+    # (int != float is normative) — matching TS.
+    with pytest.raises(ValueError, match="TYPE_MISMATCH"):
+        _holds({"eq": [{"ref": ["input", "n"]}, {"int": "5"}]}, {"n": 5.5})
+
+
+def test_to_shared_value_classifies_by_integrality():
+    assert _to_shared_value(5.0) == 5 and isinstance(_to_shared_value(5.0), int)
+    assert isinstance(_to_shared_value(5.5), float)
+    # bool is an int subclass in Python but must stay a bool in the shared model.
+    assert _to_shared_value(True) is True
+    # nested integral floats reclassify recursively.
+    assert _to_shared_value({"a": 2.0, "b": [3.0, 4.5]}) == {"a": 2, "b": [3, 4.5]}
+
+
+# ── typed eq (int != string) ──────────────────────────────────────────────────
+
+
+def test_typed_eq_int_never_equals_string():
+    with pytest.raises(ValueError, match="TYPE_MISMATCH"):
+        _holds({"eq": [{"int": "5"}, "5"]}, {})
+
+
+def test_string_eq_string_by_value():
+    assert _holds({"eq": [{"ref": ["input", "role"]}, "admin"]}, {"role": "admin"}) is True
+    assert _holds({"eq": [{"ref": ["input", "role"]}, "admin"]}, {"role": "user"}) is False
+
+
+# ── i64 boundary ──────────────────────────────────────────────────────────────
+
+
+def test_i64_max_boundary_ok():
+    # 2^63-1 is the max i64; adding within range is fine.
+    assert _holds(
+        {"eq": [{"add": [{"int": "9223372036854775806"}, {"int": "1"}]}, {"int": "9223372036854775807"}]},
+        {},
+    ) is True
+
+
+def test_i64_overflow_is_loud():
+    with pytest.raises(ValueError, match="INT_OVERFLOW"):
+        _holds({"lt": [{"add": [{"int": "9223372036854775807"}, {"int": "1"}]}, {"int": "0"}]}, {})
+
+
+# ── code-point string compare ─────────────────────────────────────────────────
+
+
+def test_string_compare_is_code_point_order():
+    # 'Z' (0x5A) < 'a' (0x61) in code-point order.
+    assert _holds({"lt": ["Z", "a"]}, {}) is True
+
+
+# ── truncated mod sign (sign of dividend) ─────────────────────────────────────
+
+
+def test_mod_sign_follows_dividend_negative():
+    # -7 mod 3 == -1 (truncated division; sign follows dividend, NOT Python %).
+    assert _holds({"eq": [{"mod": [{"int": "-7"}, {"int": "3"}]}, {"int": "-1"}]}, {}) is True
+
+
+def test_mod_sign_follows_dividend_positive():
+    assert _holds({"eq": [{"mod": [{"int": "7"}, {"int": "-3"}]}, {"int": "1"}]}, {}) is True
+
+
+# ── non-bool result is loud ───────────────────────────────────────────────────
+
+
+def test_non_bool_guard_is_loud():
+    with pytest.raises(ValueError, match="must evaluate to a boolean"):
+        _holds({"int": "5"}, {})
+
+
+def test_null_guard_result_is_loud():
+    with pytest.raises(ValueError, match="must evaluate to a boolean"):
+        _holds({"refOpt": ["input", "missing"]}, {"missing": None})
+
+
+# ── unknown op / unknown exprVersion is loud (fail-closed) ────────────────────
+
+
+def test_unknown_op_is_loud():
+    with pytest.raises(ValueError, match="UNKNOWN_OP"):
+        _holds({"frobnicate": [1, 2]}, {})
+
+
+# ── scope escape (prop-rooted guard) is loud ──────────────────────────────────
+
+
+def test_prop_rooted_guard_is_rejected():
+    with pytest.raises(ValueError, match="only reference the transaction 'input'"):
+        _holds({"eq": [{"ref": ["prop", "status"]}, "closed"]}, {})
+
+
+def test_nested_prop_ref_is_rejected():
+    with pytest.raises(ValueError, match="only reference the transaction 'input'"):
+        _holds({"and": [True, {"eq": [{"ref": ["prop", "x"]}, "y"]}]}, {})
+
+
+# ── skip / keep semantics ─────────────────────────────────────────────────────
+
+
+def test_guard_true_keeps_guard_false_skips():
+    expr = {"eq": [{"ref": ["input", "active"]}, True]}
+    assert _holds(expr, {"active": True}) is True
+    assert _holds(expr, {"active": False}) is False