opa-py-wasm 1.2.1__py3-none-any.whl

opa_py_wasm-1.2.1.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: opa-py-wasm
+Version: 1.2.1
+Summary: In-process, thread-safe Python SDK for evaluating OPA policies compiled to WebAssembly, built on wasmtime.py
+Keywords: opa,open-policy-agent,wasm,webassembly,policy,authorization
+Author: Sanjana Goel, Ravi Chauhan
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: wasmtime>=46.0.0,<47.0.0
+Requires-Dist: pyyaml>=6.0 ; extra == 'yaml'
+Requires-Python: >=3.10, <4.0
+Project-URL: Homepage, https://github.com/intuit/opa-py-wasm
+Project-URL: Repository, https://github.com/intuit/opa-py-wasm
+Project-URL: Issues, https://github.com/intuit/opa-py-wasm/issues
+Project-URL: Changelog, https://github.com/intuit/opa-py-wasm/blob/main/CHANGELOG.md
+Provides-Extra: yaml
+Description-Content-Type: text/markdown
+
+# opa-py-wasm
+
+![Supported Python versions](https://shields.io/badge/python-3.10_|_3.11_|_3.12_|_3.13_|_3.14-green?logo=python)
+[![CI](https://github.com/intuit/opa-py-wasm/actions/workflows/ci.yml/badge.svg)](https://github.com/intuit/opa-py-wasm/actions/workflows/ci.yml)
+![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)
+[![PyPI](https://img.shields.io/pypi/v/opa-py-wasm.svg)](https://pypi.org/project/opa-py-wasm/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/intuit/opa-py-wasm/blob/main/LICENSE)
+
+`opa-py-wasm` is an in-process, thread-safe Python SDK for evaluating
+[Open Policy Agent](https://www.openpolicyagent.org/) policies compiled to
+WebAssembly, built on [`wasmtime.py`](https://github.com/bytecodealliance/wasmtime-py).
+It requires no OPA server, no OPA binary, no subprocess, and no network at
+runtime. It is functionally comparable to StyraOSS `opa-java-wasm`, with a
+Pythonic API and explicit thread-safety guarantees.
+
+> **Import name:** the package installs as `opa-py-wasm` and is imported as
+> `opapywasm`.
+
+## Installation
+
+```shell
+pip install opa-py-wasm
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```shell
+uv add opa-py-wasm
+```
+
+Requires Python 3.10 or newer. The only runtime dependency is
+[`wasmtime`](https://pypi.org/project/wasmtime/).
+
+## Usage
+
+```python
+from opapywasm import UNDEFINED, OpaWasmPolicy, PolicyConfig
+
+policy = OpaWasmPolicy.from_wasm_file(
+    "policy.wasm",
+    config=PolicyConfig(
+        pool_size=8,
+        default_entrypoint="authz/allow",
+        eval_timeout_seconds=30.0,   # per-eval deadline (epoch interruption)
+        max_memory_pages=4096,       # per-instance linear-memory cap (256 MiB)
+    ),
+)
+
+policy.set_data({"roles": {"alice": "admin", "bob": "viewer"}})
+
+decision = policy.evaluate({"user": "alice", "action": "delete"})   # simplified decision
+raw = policy.evaluate_raw({"user": "alice", "action": "delete"})    # full OPA result set
+
+# `evaluate` distinguishes an undefined decision from a defined JSON null:
+if decision is UNDEFINED:
+    ...          # policy produced no result
+elif decision is None:
+    ...          # policy result was JSON null
+
+# Custom host builtins (receive decoded Python args, return JSON-compatible values):
+policy.register_builtin("my.custom", lambda x: {"ok": True})
+```
+
+`OpaWasmPolicy` is a bounded, thread-safe pool — construct it once and call
+`evaluate` from many threads. Runnable scripts are in [`examples/`](https://github.com/intuit/opa-py-wasm/tree/main/examples):
+`basic_authz.py`, `pooled_eval.py`, `custom_builtin.py`, `yaml_builtin.py`.
+
+For the YAML default builtins, install the optional extra:
+
+```shell
+uv add "opa-py-wasm[yaml]"
+```
+
+Start with the [**user guide**](https://github.com/intuit/opa-py-wasm/blob/main/docs/guide.md) — an end-to-end walkthrough
+covering compiling a policy, result semantics, concurrency, data updates, memory
+behaviour, host builtins, and a production adoption checklist.
+
+See [`docs/`](https://github.com/intuit/opa-py-wasm/tree/main/docs) for the focused references: architecture, thread-safety,
+the OPA Wasm ABI, the `opa-java-wasm` parity table, and
+[capacity-planning guidance](https://github.com/intuit/opa-py-wasm/blob/main/docs/capacity_planning.md) for sizing pool size
+and concurrency.
+
+### Test fixtures (dev only)
+
+Compiled `.wasm` fixtures are committed under `tests/fixtures/wasm`, so the test
+suite needs no OPA CLI. To regenerate them from the Rego sources in
+`tests/fixtures/rego`, install the [OPA CLI](https://www.openpolicyagent.org/docs/latest/#running-opa)
+and run:
+
+```shell
+python scripts/build_fixtures.py           # all fixtures
+python scripts/build_fixtures.py allow_true # a single fixture
+```
+
+## Local Development
+
+### uv
+
+This library uses [uv to manage Python dependencies](https://docs.astral.sh/uv/getting-started/features/#projects).  
+`brew` is The easiest way to install on macOS:
+
+```shell
+brew install uv
+```
+
+For additional installation options (e.g. setting the PATH, installing a specific version, etc),
+see the installation docs:  
+https://docs.astral.sh/uv/getting-started/installation/
+
+## Python Versions Supported
+
+Python 3.10 through 3.14 are supported and tested in CI.
+
+To change which versions are supported and tested:
+- Update "envlist" in "tox" section of [tox.ini](/tox.ini)
+- Update "Supported Python versions" badge in [README.md](/README.md)
+- Update "project.requires-python" in [pyproject.toml](/pyproject.toml) (if needed)
+- Update "tool.black.target-version" in [pyproject.toml](/pyproject.toml) (optional)
+- Update the matrix in [.github/workflows/ci.yml](/.github/workflows/ci.yml)
+
+### Virtual Environment
+
+Create by running:
+
+```shell
+uv sync --all-extras
+```
+
+Run a command from the virtual environment, like code formatting:
+
+```shell
+uv run black .
+```
+
+To activate the virtual environment:
+
+```shell
+source .venv/bin/activate
+```
+
+For more information, refer to [uv's documentation](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment).
+
+### Type checking (mypy)
+
+This library supports Python type [annotation](https://peps.python.org/pep-0484/).
+Types will be checked as part of the test suite (see below).
+For more information, see the [mypy documentation](https://mypy.readthedocs.io/en/stable/getting_started.html#dynamic-vs-static-typing).
+
+### Testing
+
+To run the test suite locally:
+```shell
+uv run tox
+```
+
+Coverage is enforced on every CI run by `fail_under = 90` in
+[`tool.coverage.report`](https://github.com/intuit/opa-py-wasm/blob/main/pyproject.toml); the suite currently sits at 99%. The
+coverage badge at the top of this file is static — if you change coverage
+materially, update the percentage in that badge along with your change.
+
+## Releasing
+
+Releases are cut by maintainers by pushing a `vX.Y.Z` tag, which triggers an
+automated build and publish to PyPI. See [`RELEASING.md`](https://github.com/intuit/opa-py-wasm/blob/main/RELEASING.md) for
+the process and the versioning policy. Published versions are listed on
+[PyPI](https://pypi.org/project/opa-py-wasm/), and each release's changes are in
+[`CHANGELOG.md`](https://github.com/intuit/opa-py-wasm/blob/main/CHANGELOG.md).
+
+## Contributing
+
+Contributions are welcome — see the [Contribution Guidelines](https://github.com/intuit/opa-py-wasm/blob/main/CONTRIBUTING.md)
+and our [Code of Conduct](https://github.com/intuit/opa-py-wasm/blob/main/CODE_OF_CONDUCT.md).
+
+## Support
+
+Please open a [GitHub issue](https://github.com/intuit/opa-py-wasm/issues) for
+bugs and feature requests, or start a
+[discussion](https://github.com/intuit/opa-py-wasm/discussions) for questions.
+
+## License
+
+Released under the [MIT License](https://github.com/intuit/opa-py-wasm/blob/main/LICENSE).

opa_py_wasm-1.2.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+opapywasm/__init__.py,sha256=0_HGf8tIjuz_dR73SLlwKt73NkhhWD25ZvjNzyRJ7j8,2261
+opapywasm/abi.py,sha256=akDrpD0MEsS56vbSGNhVYMpWPW4qXg0nD5LpWgLries,12895
+opapywasm/builtins.py,sha256=9OgV8CM1dN_FPevoGQL3aNk3-XRkrw5vupLusK8SXnk,8864
+opapywasm/data.py,sha256=39220B2rLwIj8LCvzN9KgWBmh47tikSusd1mH9CAkVg,4346
+opapywasm/errors.py,sha256=ss4coJlseVXmA2Ug5xfo0KG4QwokF5d9uX6_Qmr3Ux8,3056
+opapywasm/evaluator.py,sha256=jjEsIpczOVbpysWbkXaI1loEmzfrRqiagNfUCunNmU4,9472
+opapywasm/instance.py,sha256=3a6tJegvSf5UNo7gDncyrv-XMO_4gSnXU6HIEuv3GcA,10442
+opapywasm/memory.py,sha256=GlL6SWGTcq5OfxhDUtN0jZbHsJgamPaXDzj6SdFLKtQ,12291
+opapywasm/policy.py,sha256=929nhb3nr7Eq18q4cR4wWC-c9G5N2nTqoYZ6E2JOEwc,17005
+opapywasm/pool.py,sha256=OCSVmnx1Z_M0cv1WleALuUQ40bSgFqEbLtml4TWlOJw,13070
+opapywasm/py.typed,sha256=Y2bzeO4tHJlTrLnOh4twETUGyy3X-dO-n04VWA8tkiw,164
+opapywasm/runtime.py,sha256=er2U1xe8qiyavku1lLTn32YkIQdEmgJVDnhdZyY2VXY,21562
+opapywasm/types.py,sha256=MTaE1fgueSesl5zYQ-Q0CsNFvv_thqzHeEyVLTuOrSc,7245
+opa_py_wasm-1.2.1.dist-info/licenses/LICENSE,sha256=DUwW94JMWqhk1evJO7mh7Vfetx0QPyOq20_Q4IwqzAU,1068
+opa_py_wasm-1.2.1.dist-info/WHEEL,sha256=_d8F1e7SqtoW6CDj4Gi8lFC26a_7I17R7zPLCKTp4Fg,81
+opa_py_wasm-1.2.1.dist-info/METADATA,sha256=g6dwqqQ89wMAQvIe8j45aafc4Ek3CETvEV6Tg8gGNOg,8133
+opa_py_wasm-1.2.1.dist-info/RECORD,,

opa_py_wasm-1.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.15
+Root-Is-Purelib: true
+Tag: py3-none-any

opa_py_wasm-1.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intuit Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opapywasm/__init__.py

@@ -0,0 +1,74 @@
+"""opapywasm — in-process, thread-safe Python SDK for evaluating OPA policies
+compiled to WebAssembly, built on ``wasmtime.py``.
+
+Public API (see :class:`~opapywasm.policy.OpaWasmPolicy`)::
+
+    from opapywasm import OpaWasmPolicy, PolicyConfig
+
+    policy = OpaWasmPolicy.from_wasm_file("policy.wasm")
+    policy.set_data({"roles": {"alice": "admin"}})
+    decision = policy.evaluate({"user": "alice", "action": "delete"})
+
+The ``OpaWasmPolicy`` facade owns a bounded, thread-safe pool of single-use
+Wasm instances; application threads own request-level concurrency.
+"""
+
+from __future__ import annotations
+
+from .builtins import BuiltinRegistry
+from .errors import (
+    OpaAbiError,
+    OpaAbortError,
+    OpaBuiltinError,
+    OpaDataError,
+    OpaEntrypointError,
+    OpaEvaluationError,
+    OpaInvalidInputError,
+    OpaInvalidPolicyError,
+    OpaMemoryError,
+    OpaPolicyClosedError,
+    OpaPoolTimeoutError,
+    OpaWasmError,
+)
+from .policy import OpaWasmPolicy
+from .types import UNDEFINED, BuiltinCallable, JSONInput, JSONValue, PolicyConfig, Undefined
+
+__all__ = [
+    # Facade — a bounded, thread-safe pool of policy instances.
+    "OpaWasmPolicy",
+    "BuiltinRegistry",
+    # Configuration & types
+    "PolicyConfig",
+    "JSONValue",
+    "JSONInput",
+    "BuiltinCallable",
+    "Undefined",
+    "UNDEFINED",
+    # Errors
+    "OpaWasmError",
+    "OpaInvalidPolicyError",
+    "OpaAbiError",
+    "OpaAbortError",
+    "OpaEvaluationError",
+    "OpaBuiltinError",
+    "OpaMemoryError",
+    "OpaPoolTimeoutError",
+    "OpaPolicyClosedError",
+    "OpaInvalidInputError",
+    "OpaEntrypointError",
+    "OpaDataError",
+]
+
+# Sourced from installed package metadata so it can never drift from
+# pyproject.toml. Falls back to "0.0.0+unknown" when running from a source tree
+# that was never installed (e.g. some editable/CI layouts).
+try:
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _pkg_version
+
+    try:
+        __version__ = _pkg_version("opa-py-wasm")
+    except PackageNotFoundError:  # pragma: no cover - only in an uninstalled tree
+        __version__ = "0.0.0+unknown"
+except ImportError:  # pragma: no cover - importlib.metadata always present on 3.10+
+    __version__ = "0.0.0+unknown"

opapywasm/abi.py

@@ -0,0 +1,331 @@
+"""OPA Wasm ABI adapter (milestone C2).
+
+Two layers:
+
+``OpaAbiSpec``
+    Immutable, shareable knowledge about the OPA Wasm ABI: required export
+    names, version-support policy, and capability rules. Safe to share across
+    instances.
+
+``OpaAbi``
+    A per-instance adapter *bound* to one :class:`~opapywasm.runtime.WasmtimeRuntime`
+    (its ``Store`` / ``Instance`` / ``Memory`` / exports). Never shared across
+    instances — OPA value addresses and heap state are instance-local.
+
+ABI facts (names, signatures, version semantics) come from the OPA Wasm ABI
+documentation; see docs/opa_abi.md. Where the module varies by ABI version we
+inspect exports and fail with :class:`OpaAbiError` rather than guessing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import wasmtime
+
+from .errors import OpaAbiError
+
+if TYPE_CHECKING:
+    from .runtime import WasmtimeRuntime
+
+__all__ = ["OpaAbiSpec", "OpaAbi"]
+
+# ABI version globals exported by every OPA policy module.
+_ABI_VERSION_GLOBAL = "opa_wasm_abi_version"
+_ABI_MINOR_GLOBAL = "opa_wasm_abi_minor_version"
+
+# Exports required of every supported OPA policy, independent of ABI minor.
+_REQUIRED_EXPORTS: tuple[str, ...] = (
+    "opa_malloc",
+    "opa_free",
+    "opa_json_parse",
+    "opa_json_dump",
+    "opa_heap_ptr_get",
+    "opa_heap_ptr_set",
+    "entrypoints",
+    "builtins",
+)
+
+# Capability-gating exports. Presence of these toggles the corresponding flag.
+_OPA_EVAL_EXPORT = "opa_eval"
+_EVAL_CTX_EXPORTS: tuple[str, ...] = (
+    "opa_eval_ctx_new",
+    "opa_eval_ctx_set_input",
+    "opa_eval_ctx_set_data",
+    "opa_eval_ctx_set_entrypoint",
+    "eval",
+    "opa_eval_ctx_get_result",
+)
+_HEAP_STASH_EXPORTS: tuple[str, ...] = (
+    "opa_heap_blocks_stash",
+    "opa_heap_blocks_restore",
+    "opa_heap_stash_clear",
+)
+_VALUE_FREE_EXPORT = "opa_value_free"
+
+# Expected Wasm signatures of the exports we actually call, as
+# ``(param_valtypes, result_valtypes)`` in ``i32`` terms. Validated at
+# construction so a mistyped export fails fast with a clear error rather than
+# trapping mid-evaluation. OPA emits everything as i32 (memory offsets / sizes).
+_I32 = "i32"
+_EXPECTED_SIGNATURES: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = {
+    "opa_malloc": ((_I32,), (_I32,)),
+    "opa_free": ((_I32,), ()),
+    "opa_json_parse": ((_I32, _I32), (_I32,)),
+    "opa_json_dump": ((_I32,), (_I32,)),
+    "opa_heap_ptr_get": ((), (_I32,)),
+    "opa_heap_ptr_set": ((_I32,), ()),
+    "entrypoints": ((), (_I32,)),
+    "builtins": ((), (_I32,)),
+    # opa_eval(reserved, entrypoint, data, input, input_len, heap_ptr, format)
+    "opa_eval": ((_I32,) * 7, (_I32,)),
+}
+
+
+@dataclass(frozen=True)
+class OpaAbiSpec:
+    """Immutable, shareable ABI policy for a compiled OPA module.
+
+    Encodes which ABI versions this SDK supports and which exports are required.
+    Holds no per-instance state, so a single spec is shared by every instance of
+    a policy.
+
+    Attributes:
+        min_major / max_major: supported ABI major-version range (inclusive).
+        min_minor_for_eval: the ABI minor version at which the one-shot
+            ``opa_eval`` fast path becomes available. MVP requires ABI >= 1.2.
+        required_exports: exports every supported policy must provide.
+    """
+
+    min_major: int = 1
+    max_major: int = 1
+    min_minor_for_eval: int = 2
+    required_exports: tuple[str, ...] = field(default=_REQUIRED_EXPORTS)
+
+    def check_version(self, major: int, minor: int) -> None:
+        """Validate a detected (major, minor) ABI version against this spec.
+
+        Raises:
+            OpaAbiError: if the major version is outside the supported range.
+        """
+        if not (self.min_major <= major <= self.max_major):
+            raise OpaAbiError(
+                f"unsupported OPA Wasm ABI major version {major}.{minor}; " f"this SDK supports {self.min_major}.x"
+            )
+
+    def requires_eval_fast_path(self, minor: int) -> bool:
+        """Whether the detected ABI minor version implies the ``opa_eval`` path."""
+        return minor >= self.min_minor_for_eval
+
+
+class OpaAbi:
+    """Per-instance adapter binding an OPA module's ABI to one runtime.
+
+    On construction it reads the ABI version globals, validates them against the
+    :class:`OpaAbiSpec`, verifies required exports are present, and computes
+    capability flags. It then offers typed wrappers around the OPA exports.
+
+    Not thread-safe; bound to exactly one instance.
+    """
+
+    def __init__(self, runtime: WasmtimeRuntime, spec: OpaAbiSpec | None = None) -> None:
+        self._rt = runtime
+        self._spec = spec or OpaAbiSpec()
+
+        self._abi_major, self._abi_minor = self._read_version()
+        self._spec.check_version(self._abi_major, self._abi_minor)
+        self._validate_required_exports()
+
+        # Capability flags — derived once from the exports present.
+        self._supports_opa_eval = runtime.has_export(_OPA_EVAL_EXPORT) and self._spec.requires_eval_fast_path(
+            self._abi_minor
+        )
+        self._supports_eval_context = all(runtime.has_export(name) for name in _EVAL_CTX_EXPORTS)
+        self._supports_heap_stash = all(runtime.has_export(name) for name in _HEAP_STASH_EXPORTS)
+        self._supports_value_free = runtime.has_export(_VALUE_FREE_EXPORT)
+
+        # This SDK evaluates exclusively via the opa_eval fast path (ABI >= 1.2).
+        # The eval-context fallback is deliberately not implemented, so we fail
+        # fast at construction if it is unavailable rather than letting a
+        # context-only module construct and then error on first evaluate().
+        if not self._supports_opa_eval:
+            raise OpaAbiError(
+                f"policy ABI {self._abi_major}.{self._abi_minor} does not expose the opa_eval "
+                "fast path (requires ABI >= 1.2 with an 'opa_eval' export); this SDK does not "
+                "implement the eval-context fallback"
+            )
+
+        # Validate the signatures of the exports we call, so a mistyped export is
+        # a clear construction-time error, not a mid-eval trap.
+        self._validate_export_signatures()
+
+    # -- version & capabilities ---------------------------------------------
+
+    @property
+    def abi_version(self) -> tuple[int, int]:
+        """Detected ``(major, minor)`` ABI version."""
+        return (self._abi_major, self._abi_minor)
+
+    @property
+    def supports_opa_eval(self) -> bool:
+        return self._supports_opa_eval
+
+    @property
+    def supports_eval_context(self) -> bool:
+        return self._supports_eval_context
+
+    @property
+    def supports_heap_stash(self) -> bool:
+        return self._supports_heap_stash
+
+    @property
+    def supports_value_free(self) -> bool:
+        return self._supports_value_free
+
+    # -- raw memory access (for the per-instance MemoryCodec) ----------------
+
+    def memory_write(self, addr: int, data: bytes) -> None:
+        """Write ``data`` into this instance's Wasm memory at ``addr``."""
+        self._rt.memory.write(self._rt.store, data, addr)
+
+    def memory_read(self, start: int, stop: int) -> bytearray:
+        """Read this instance's Wasm memory over ``[start, stop)``."""
+        data: bytearray = self._rt.memory.read(self._rt.store, start, stop)
+        return data
+
+    def memory_len(self) -> int:
+        """Current size of this instance's Wasm memory, in bytes."""
+        return int(self._rt.memory.data_len(self._rt.store))
+
+    def set_epoch_deadline(self, ticks: int) -> None:
+        """Arm this instance's per-evaluation epoch deadline (see runtime)."""
+        self._rt.set_epoch_deadline(ticks)
+
+    def clear_epoch_deadline(self) -> None:
+        """Clear the per-evaluation deadline after a successful eval (see runtime)."""
+        self._rt.clear_epoch_deadline()
+
+    def _read_version(self) -> tuple[int, int]:
+        """Read the ABI version globals.
+
+        The minor global was added in ABI 1.1; if it is absent the minor version
+        is treated as 0.
+
+        Raises:
+            OpaAbiError: if the mandatory major-version global is missing or not
+                an integer global.
+        """
+        major_global = self._rt.exports().get(_ABI_VERSION_GLOBAL)
+        if not isinstance(major_global, wasmtime.Global):
+            raise OpaAbiError(f"policy is missing the {_ABI_VERSION_GLOBAL!r} ABI global; not an OPA policy")
+        major = major_global.value(self._rt.store)
+
+        minor_global = self._rt.exports().get(_ABI_MINOR_GLOBAL)
+        minor = minor_global.value(self._rt.store) if isinstance(minor_global, wasmtime.Global) else 0
+
+        if not isinstance(major, int) or not isinstance(minor, int):
+            raise OpaAbiError("OPA ABI version globals are not integers")
+        return major, minor
+
+    def _validate_required_exports(self) -> None:
+        missing = [name for name in self._spec.required_exports if not self._rt.has_export(name)]
+        if missing:
+            raise OpaAbiError(
+                f"policy is missing required OPA ABI export(s): {', '.join(sorted(missing))} "
+                f"(ABI {self._abi_major}.{self._abi_minor})"
+            )
+
+    def _validate_export_signatures(self) -> None:
+        """Check that every export we call has the expected ``i32`` signature.
+
+        A signature mismatch means the module is not the OPA ABI we target;
+        surfacing it here (rather than as an opaque trap during evaluation) makes
+        the failure actionable.
+        """
+        for name, (want_params, want_results) in _EXPECTED_SIGNATURES.items():
+            if not self._rt.has_export(name):
+                # opa_eval presence is already enforced; other names are in the
+                # required-export set. Anything genuinely absent was caught above.
+                continue
+            func = self._rt.get_func(name)
+            func_type = func.type(self._rt.store)
+            got_params = tuple(str(v) for v in func_type.params)
+            got_results = tuple(str(v) for v in func_type.results)
+            if got_params != want_params or got_results != want_results:
+                raise OpaAbiError(
+                    f"OPA export {name!r} has unexpected signature "
+                    f"{got_params}->{got_results}; expected {want_params}->{want_results}"
+                )
+
+    # -- typed export wrappers ----------------------------------------------
+    #
+    # Each wrapper calls the corresponding OPA export with the instance's store.
+    # Addresses are opaque i32 handles into this instance's Wasm memory; callers
+    # (MemoryCodec, DataManager, Evaluator) must never share them across
+    # instances.
+
+    def _call(self, name: str, *args: int) -> int:
+        func = self._rt.get_func(name)
+        return int(func(self._rt.store, *args))
+
+    def opa_malloc(self, size: int) -> int:
+        """Allocate ``size`` bytes in the instance heap; return the address."""
+        return self._call("opa_malloc", size)
+
+    def opa_free(self, addr: int) -> None:
+        self._rt.get_func("opa_free")(self._rt.store, addr)
+
+    def opa_json_parse(self, addr: int, length: int) -> int:
+        """Parse JSON bytes at ``addr`` into an OPA value; return its address."""
+        return self._call("opa_json_parse", addr, length)
+
+    def opa_json_dump(self, value_addr: int) -> int:
+        """Dump an OPA value to a NUL-terminated JSON string; return its address."""
+        return self._call("opa_json_dump", value_addr)
+
+    def opa_heap_ptr_get(self) -> int:
+        return self._call("opa_heap_ptr_get")
+
+    def opa_heap_ptr_set(self, addr: int) -> None:
+        self._rt.get_func("opa_heap_ptr_set")(self._rt.store, addr)
+
+    def entrypoints(self) -> int:
+        """Return the address of the OPA value describing entrypoints (name->id)."""
+        return self._call("entrypoints")
+
+    def builtins(self) -> int:
+        """Return the address of the OPA value describing builtins (name->id)."""
+        return self._call("builtins")
+
+    def opa_eval(
+        self,
+        entrypoint_id: int,
+        data_addr: int,
+        input_addr: int,
+        input_len: int,
+        heap_ptr: int,
+        *,
+        reserved: int = 0,
+        result_format: int = 0,
+    ) -> int:
+        """One-shot evaluation (ABI 1.2+ fast path).
+
+        Signature (per the OPA Wasm ABI):
+        ``opa_eval(reserved, entrypoint_id, data, input, input_len, heap_ptr, format)``
+        returning the address of a NUL-terminated JSON result string.
+
+        The ``opa_eval`` fast path is guaranteed present: :class:`OpaAbi`
+        construction rejects any module lacking it, so no runtime guard is
+        needed here.
+        """
+        return self._call(
+            _OPA_EVAL_EXPORT,
+            reserved,
+            entrypoint_id,
+            data_addr,
+            input_addr,
+            input_len,
+            heap_ptr,
+            result_format,
+        )