graphddb-runtime 0.7.8__tar.gz → 0.7.10__tar.gz

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.10}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.7.8
+Version: 0.7.10
 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.3
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.10}/graphddb_runtime/per_key_cursor.py

@@ -29,9 +29,10 @@ envelope shape does not branch on arity).
 
 from __future__ import annotations
 
-import json
 from typing import Any, Mapping, Optional
 
+from behavior_contracts import canonical_value as _canonical_value
+
 from .cursor import decode_cursor, encode_cursor
 
 
@@ -39,12 +40,23 @@ def serialize_contract_key(key: Mapping[str, Any]) -> str:
     """Canonical, cross-runtime-stable string identity of a contract key.
 
     Object fields are sorted by name so ``{a, b}`` and ``{b, a}`` serialize
-    identically; values are emitted via ``json.dumps`` with compact separators.
-    Matches the TS ``serializeContractKey`` (``JSON.stringify`` over a
-    field-sorted object), e.g. ``{"categoryId":"tech"}``.
+    identically; values are emitted as compact JSON. Matches the TS
+    ``serializeContractKey`` (``JSON.stringify`` over a field-sorted object),
+    e.g. ``{"categoryId":"tech"}``.
+
+    **WS4 adapter (behavior-contracts)**: this is the shared COMMON
+    ``canonicalValue`` primitive (runtime-boundary.md §2.1 →
+    canonical-serialization.md §2: key identity = top-level key sort + compact
+    JSON). graphddb now delegates to the extracted shared library instead of
+    re-implementing the field-sorted ``json.dumps``. Verified byte-for-byte
+    identical for every value shape a contract key carries (string / int / bool /
+    null / non-ASCII / nested-dict-insertion-order / array); both the shared and
+    the former graphddb impl reject non-JSON-scalar leaves such as ``Decimal``,
+    so the boundary is exact.
     """
-    ordered = {field: key[field] for field in sorted(key.keys())}
-    return json.dumps(ordered, separators=(",", ":"), ensure_ascii=False)
+    # ``canonical_value`` performs the top-level key sort + compact JSON itself,
+    # so pass the key mapping (as a plain dict) straight through.
+    return _canonical_value(dict(key))
 
 
 def encode_per_key_cursor(

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.10}/graphddb_runtime/runtime.py

@@ -19,6 +19,9 @@ from typing import Any, Dict, List, Mapping, Optional, Tuple
 
 from boto3.dynamodb.types import TypeDeserializer, TypeSerializer
 
+from behavior_contracts import EnvelopeFailure as _EnvelopeFailure
+from behavior_contracts import validate_envelope as _validate_envelope
+
 from .batch import BatchGetExecutor, BatchWriteExecutor, serialize_key
 from .concurrency import RELATION_TRAVERSAL_CONCURRENCY, map_with_concurrency
 from .cursor import decode_cursor, encode_cursor
@@ -54,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:
@@ -83,26 +94,40 @@ def _validate_spec_version(document: Mapping[str, Any], label: str) -> None:
       (forward-rejected);
     - a missing / malformed version is rejected (an unversioned document
       cannot be trusted to match any vocabulary).
+
+    **WS4 adapter (behavior-contracts)**: the ``<major>.<minor>`` fail-closed
+    comparison mechanism is the shared COMMON ``validate_envelope`` primitive
+    (runtime-boundary.md §2.1 — ``validateEnvelope``: DynamoDB-agnostic version
+    check). graphddb now delegates the parse + major-equal / minor-<= rule to the
+    shared library (which reads the ``version`` field here) and re-raises the
+    shared ``EnvelopeFailure`` as graphddb's public ``GraphDDBError`` with the
+    same actionable wording (test contract preserved).
     """
-    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."
+    try:
+        _validate_envelope(
+            document,
+            SPEC_VERSION_SUPPORTED,
+            field="version",
+            label=label,
+        )
+    except _EnvelopeFailure as exc:
+        version = document.get("version") if isinstance(document, Mapping) else None
+        if exc.code in ("MISSING_VERSION", "MALFORMED_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."
+            ) from exc
+        supported_major, supported_minor = (
+            int(part) for part in SPEC_VERSION_SUPPORTED.split(".")
         )
-    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."
-        )
+        ) from exc
 
 try:  # pragma: no cover - exercised indirectly
     from botocore.exceptions import BotoCoreError, ClientError
@@ -1392,6 +1417,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):
@@ -1399,6 +1427,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)
@@ -1406,6 +1436,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.8 → graphddb_runtime-0.7.10}/graphddb_runtime/templates.py

@@ -16,12 +16,31 @@ from __future__ import annotations
 import re
 from typing import Any, Mapping
 
+from behavior_contracts import TemplateFailure as _TemplateFailure
+from behavior_contracts import render_template as _render_template
+
 from .errors import ParameterValidationError
 
 # A placeholder is `{` + name (no dot) + `}`. `{result.*}` is matched but flagged
 # separately by the executor so it can raise the multi-op error.
 _PLACEHOLDER = re.compile(r"\{([^{}]+)\}")
 
+# Names resolved by a *different* layer than the core `{param}` primitive:
+# `{result.*}` (relation-chain binding, resolved by the runPlan/relation layer)
+# and `{item.*}` (Map/forEach expansion). See runtime-boundary.md §4.1: the
+# shared `render_template` deliberately rejects these scopes (RESULT_SCOPE_IN_CORE)
+# because they belong to graphddb's relation execution, not to the DSL-agnostic
+# core. graphddb's `resolve_template` is overloaded to serve BOTH `{param}` key
+# rendering AND `{result.*}` binding, so the adapter only delegates the former.
+_NON_CORE_SCOPES = ("result.", "item.")
+
+
+def _has_non_core_scope(template: str) -> bool:
+    return any(
+        m.group(1).startswith(_NON_CORE_SCOPES)
+        for m in _PLACEHOLDER.finditer(template)
+    )
+
 
 def validate_params(
     params: Mapping[str, Any],
@@ -118,14 +137,45 @@ def resolve_template(template: str, params: Mapping[str, Any]) -> str:
     the single-table layout). Missing params should have been caught by
     :func:`validate_params`; a stray placeholder here raises
     :class:`ParameterValidationError`.
+
+    **WS4 adapter (behavior-contracts)** — this function is *overloaded* in
+    graphddb: it renders both the DSL-agnostic ``{param}`` primitive AND the
+    graphddb-specific ``{result.*}`` relation-chain binding (the relation layer
+    passes ``{"result.<field>": value}`` params with ``{result.<field>}``
+    templates, see ``runtime.py`` ``_relation_key_marker`` / belongsTo fan-out).
+    Per runtime-boundary.md §4.1 only the ``{param}`` case is COMMON, so:
+
+    - **pure ``{param}`` templates** → delegate to the shared COMMON
+      ``render_template`` (single source of truth for the `{param}` grammar,
+      strict missing-key, and Python-parity stringify). The shared
+      ``TemplateFailure(UNBOUND_PARAM)`` is translated to graphddb's
+      ``ParameterValidationError`` to preserve graphddb's public error contract.
+    - **templates carrying ``{result.*}`` / ``{item.*}``** → keep graphddb's own
+      substitution (the shared core deliberately rejects these scopes; they are
+      resolved by graphddb's relation execution layer, not by the DSL core).
+
+    This is the WS4 boundary correction: graphddb's ``resolve_template`` does
+    *more* than the shared ``render_template``, so it cannot be swapped wholesale
+    — the shared core is wired in for the primitive it genuinely owns.
     """
+    if _has_non_core_scope(template):
+        # CONSUMER-SPECIFIC relation-layer binding: substitute every `{name}`
+        # (including `{result.*}` / `{item.*}`) with its param value. This is the
+        # part the shared core does not own (runtime-boundary.md §4.1).
+        def repl(match: "re.Match[str]") -> str:
+            name = match.group(1)
+            if name not in params or params[name] is None:
+                raise ParameterValidationError(
+                    f"template '{template}' references unbound parameter '{name}'"
+                )
+            return str(params[name])
 
-    def repl(match: "re.Match[str]") -> str:
-        name = match.group(1)
-        if name not in params or params[name] is None:
-            raise ParameterValidationError(
-                f"template '{template}' references unbound parameter '{name}'"
-            )
-        return str(params[name])
+        return _PLACEHOLDER.sub(repl, template)
 
-    return _PLACEHOLDER.sub(repl, template)
+    # COMMON `{param}` primitive → shared behavior-contracts.
+    try:
+        return _render_template(template, params)
+    except _TemplateFailure as exc:
+        # Preserve graphddb's public error contract (ParameterValidationError)
+        # while routing the mechanism through the shared library.
+        raise ParameterValidationError(str(exc)) from exc

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.10}/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.8 → graphddb_runtime-0.7.10}/graphddb_runtime.egg-info/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: graphddb-runtime
-Version: 0.7.8
+Version: 0.7.10
 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.3
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.10}/graphddb_runtime.egg-info/SOURCES.txt

@@ -26,7 +26,9 @@ 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
 tests/test_integration_compose.py
 tests/test_integration_contract.py

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.10}/graphddb_runtime.egg-info/requires.txt

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

{graphddb_runtime-0.7.8 → graphddb_runtime-0.7.10}/pyproject.toml

@@ -4,12 +4,17 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphddb-runtime"
-version = "0.7.8"
+version = "0.7.10"
 description = "Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44)."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
-dependencies = ["boto3>=1.26"]
+# behavior-contracts (formerly dsl-contracts) epic (WS8): the COMMON runtime
+# primitives (spec-version validation, {param} template rendering, contract-key
+# 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.3"]
 
 [project.optional-dependencies]
 test = ["pytest>=7.0"]

graphddb_runtime-0.7.10/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