openframe-protocol-base 0.3.0__py3-none-any.whl

openframe/protocol/base/__init__.py

@@ -0,0 +1,44 @@
+"""
+openframe.protocol.base
+==========================
+Shared, transport-neutral mechanics every `openframe-protocol-*` binding
+builds on: error categorisation (`errors.py`), `RequestContext`
+construction (`context.py`), and the inbound conformance suite
+(`testing.py`). No transport dependencies — a binding package depends on
+this one, never the reverse.
+
+.. stability: experimental
+"""
+from __future__ import annotations
+
+from openframe.protocol.base.context import build_request_context
+from openframe.protocol.base.errors import (
+    ErrorCategory,
+    ErrorEnvelope,
+    build_envelope,
+    categorize,
+    raise_for_envelope,
+)
+from openframe.protocol.base.testing import (
+    UNEXPECTED_ERROR_SECRET,
+    DriverResult,
+    RemoteClientConformanceTests,
+    RemoteClientDriver,
+    TransportConformanceTests,
+    TransportDriver,
+)
+
+__all__ = [
+    "ErrorCategory",
+    "ErrorEnvelope",
+    "categorize",
+    "build_envelope",
+    "raise_for_envelope",
+    "build_request_context",
+    "DriverResult",
+    "TransportDriver",
+    "TransportConformanceTests",
+    "UNEXPECTED_ERROR_SECRET",
+    "RemoteClientDriver",
+    "RemoteClientConformanceTests",
+]

openframe/protocol/base/context.py

@@ -0,0 +1,96 @@
+"""
+openframe/protocol/base/context.py
+=====================================
+Builds `openframe.core.inbound.RequestContext` for an inbound transport
+binding — the one place that decides what `correlation_id` actually is,
+so every transport does it the same way instead of each reinventing it.
+
+`RequestContext` itself is a frozen dataclass in core with no factory
+function (confirmed empty — nothing in core constructs one outside its
+own tests). `principal`/`tenant` stay `None` here; wiring real auth
+through is deferred to `openframe-infra`/security, per draft 8 section 7's
+"reserve the hook, don't implement it yet" rule — `context_enricher`
+below is that hook.
+
+Dependency order:
+    protocol/base/context → openframe.core.inbound, opentelemetry (trace API)
+"""
+from __future__ import annotations
+
+import uuid
+from typing import Callable, Mapping
+
+from opentelemetry import propagate, trace
+
+from openframe.core.inbound import RequestContext
+
+__all__ = ["build_request_context"]
+
+ContextEnricher = Callable[[RequestContext], RequestContext]
+
+
+def build_request_context(
+    headers: Mapping[str, str],
+    *,
+    correlation_header: str = "x-correlation-id",
+    context_enricher: ContextEnricher | None = None,
+) -> RequestContext:
+    """
+    Build a `RequestContext` for one inbound request.
+
+    `correlation_id` resolution order (first match wins):
+
+    1. The trace id from an incoming W3C `traceparent` header, extracted
+       directly from *this request's own headers* — not from whatever
+       OTel span happens to be ambiently active. This distinction is
+       the fix for a real bug found while building this: `TelemetryMiddleware`
+       starts a span for *every* request regardless of whether one
+       actually propagated in from a caller, so checking
+       `trace.get_current_span()` (ambient state) can never tell "a
+       trace genuinely arrived" apart from "a fresh local span with no
+       upstream caller" — it would always win, making step 2 below
+       unreachable in practice. Extracting straight from `headers`
+       avoids that: no incoming `traceparent` means no trace id here,
+       full stop, regardless of what span is locally active.
+    2. The `correlation_header` request header (default
+       `X-Correlation-ID`), for a caller that sends its own id without
+       a trace context.
+    3. A freshly generated `uuid4`, so `correlation_id` is never empty.
+
+    Args:
+        headers:            The inbound request's headers. Lookup is
+                            case-insensitive — pass whatever mapping the
+                            transport already has; most ASGI frameworks'
+                            header mappings already are.
+        correlation_header: Header name checked in step 2. Override only
+                            if a deployment uses a non-default header.
+        context_enricher:   Optional hook called with the built context
+                            before it's returned, so a caller can attach
+                            `principal`/`tenant` once real auth exists.
+                            `None` (the default) leaves both unset — this
+                            is the reserved-but-unimplemented auth seam
+                            draft 8 asks for, not a finished feature.
+
+    Returns:
+        A `RequestContext` with a non-empty `correlation_id`.
+    """
+    extracted = propagate.extract(headers)
+    span_context = trace.get_current_span(extracted).get_span_context()
+    if span_context.is_valid:
+        correlation_id = f"{span_context.trace_id:032x}"
+    else:
+        correlation_id = _get_header(headers, correlation_header) or str(uuid.uuid4())
+
+    context = RequestContext(correlation_id=correlation_id)
+    if context_enricher is not None:
+        context = context_enricher(context)
+    return context
+
+
+def _get_header(headers: Mapping[str, str], name: str) -> str | None:
+    """Case-insensitive header lookup — ASGI header mappings vary on casing."""
+    lowered = name.lower()
+    for key, value in headers.items():
+        if key.lower() == lowered:
+            return value
+    return None

openframe/protocol/base/errors.py

@@ -0,0 +1,244 @@
+"""
+openframe/protocol/base/errors.py
+====================================
+Transport-neutral error categorisation — the single source of truth every
+`openframe-protocol-*` binding maps through, instead of each transport
+hand-writing its own isinstance ladder over `OpenFrameError` subclasses.
+
+`categorize()` is keyed on `exc.code` (a plain string, e.g.
+"adapter.not_found"), not on `isinstance` checks against concrete classes —
+this means a *new* `AdapterError` subclass from any downstream package,
+with a code this module has never seen, still gets a sane `INTERNAL`
+fallback instead of silently escaping unmapped. `ErrorCategory` itself is
+NOT added to `openframe-core` — draft 8's own rule-of-three discipline
+applies here exactly as it did to `Capability`/`Communication`: promote to
+core only once at least two transports (HTTP + gRPC) show real
+isinstance-ladder pain from re-deriving this table themselves.
+
+Dependency order:
+    protocol/base/errors → openframe.core.exceptions (read-only; never
+    raises or re-exports core exception classes itself)
+"""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+
+from openframe.core.exceptions import (
+    AdapterConnectionError,
+    AdapterNotFoundError,
+    AdapterQueryError,
+    AdapterTimeoutError,
+    OpenFrameError,
+)
+
+__all__ = [
+    "ErrorCategory",
+    "ErrorEnvelope",
+    "categorize",
+    "build_envelope",
+    "raise_for_envelope",
+]
+
+
+class ErrorCategory(Enum):
+    """
+    Closed, transport-neutral bucket an error falls into.
+
+    Every `openframe-protocol-*` binding maps exactly these five values to
+    its own wire representation (HTTP status, gRPC status code, an MCP
+    tool-error shape, ...) — see draft 8 section 5.2's table. Adding a
+    sixth value here is a decision with the same weight as adding a
+    `Capability` member: don't, until a real transport needs a
+    distinction none of these five already draw.
+    """
+
+    NOT_FOUND = "not_found"
+    INVALID = "invalid"
+    TIMEOUT = "timeout"
+    UNAVAILABLE = "unavailable"
+    INTERNAL = "internal"
+
+
+# Code → category. Keyed on the plain `domain.kind` string `OpenFrameError.code`
+# carries as data (see openframe.core.exceptions.codes.ErrorCode's own docstring)
+# rather than on the exception *class*, so a downstream package's own
+# `"ai.rate_limited"`-style code can be added here later without this module
+# needing to import that package's exception classes at all.
+_CODE_TO_CATEGORY: dict[str, ErrorCategory] = {
+    "adapter.not_found": ErrorCategory.NOT_FOUND,
+    "adapter.timeout": ErrorCategory.TIMEOUT,
+    "adapter.connection": ErrorCategory.UNAVAILABLE,
+    "plugin.not_found": ErrorCategory.NOT_FOUND,
+}
+
+# Retryability fallback for codes this module doesn't recognise at all
+# (a non-OpenFrameError, or an OpenFrameError whose code isn't in the table
+# above) — checked by exception *type* only as a last resort, since an
+# unrecognised code has no `retryable` semantics to trust.
+_RETRYABLE_TYPES = (AdapterConnectionError, AdapterTimeoutError)
+_NOT_FOUND_TYPES = (AdapterNotFoundError,)
+
+
+def categorize(exc: BaseException) -> ErrorCategory:
+    """
+    Map any exception to its transport-neutral category.
+
+    Args:
+        exc: The exception a binding caught — an `OpenFrameError` subclass,
+             a `pydantic.ValidationError`, or anything else (a bare bug).
+
+    Returns:
+        The matching `ErrorCategory`. Falls back to `INTERNAL` for
+        anything this module has no specific mapping for — including a
+        brand-new `AdapterError` subclass from a package this module has
+        never heard of. Never raises.
+    """
+    # pydantic's ValidationError (and FastAPI's RequestValidationError,
+    # which wraps one) is the one validation-error source core itself has
+    # none of — checked by class name string, not an isinstance import, so
+    # this module has zero pydantic/FastAPI dependency of its own.
+    if type(exc).__name__ in ("ValidationError", "RequestValidationError"):
+        return ErrorCategory.INVALID
+
+    if isinstance(exc, OpenFrameError):
+        category = _CODE_TO_CATEGORY.get(exc.code)
+        if category is not None:
+            return category
+        # Unrecognised OpenFrameError code — fall back to the exception's
+        # own `retryable` flag/type rather than guessing blindly.
+        if isinstance(exc, _NOT_FOUND_TYPES):
+            return ErrorCategory.NOT_FOUND
+        if isinstance(exc, _RETRYABLE_TYPES) or exc.retryable:
+            return ErrorCategory.UNAVAILABLE
+        return ErrorCategory.INTERNAL
+
+    return ErrorCategory.INTERNAL
+
+
+@dataclass(frozen=True)
+class ErrorEnvelope:
+    """
+    The wire-level error body shape every transport serialises, in its own
+    format, from the same four fields — see draft 8 section 5.2.
+
+    Attributes:
+        code:           `OpenFrameError.code` if the source was one,
+                        else a generic `"internal.error"`.
+        message:        Safe to show the caller. Never the raw `str(exc)`
+                        for an `INTERNAL`-category error — see
+                        `build_envelope`'s own docstring for why.
+        retryable:      Drives `Retry-After` (HTTP) and equivalent retry
+                        hints on other transports.
+        correlation_id: Threaded through so a caller can quote it back
+                        when reporting an issue.
+    """
+
+    code: str
+    message: str
+    retryable: bool
+    correlation_id: str
+
+
+def build_envelope(exc: BaseException, *, correlation_id: str | None = None) -> ErrorEnvelope:
+    """
+    Build the wire-safe error envelope for *exc*.
+
+    Deliberately does **not** leak internals in the message for an
+    `INTERNAL`-category error (draft 8's own stated rule) — the real
+    `str(exc)` goes to logs and the current span via
+    `openframe.core.telemetry.record_error`, never into the response body,
+    since an `AdapterError.__str__` includes the driver cause and a stray
+    driver error message is exactly the kind of internal detail a 500
+    body should never carry.
+
+    Args:
+        exc:             The exception a binding caught.
+        correlation_id:  The active request's correlation id. A fresh
+                         `uuid4` is generated if the caller has none yet
+                         (should not normally happen — bindings build
+                         `RequestContext` before the handler can raise).
+
+    Returns:
+        An `ErrorEnvelope` ready for the calling transport to serialise.
+    """
+    category = categorize(exc)
+    cid = correlation_id or str(uuid.uuid4())
+
+    if isinstance(exc, OpenFrameError):
+        code = exc.code
+        retryable = exc.retryable
+    else:
+        code = "internal.error"
+        retryable = False
+
+    if category is ErrorCategory.INTERNAL:
+        message = "An internal error occurred."
+    elif isinstance(exc, OpenFrameError):
+        message = exc.message
+    else:
+        message = str(exc)
+
+    return ErrorEnvelope(code=code, message=message, retryable=retryable, correlation_id=cid)
+
+
+# ---------------------------------------------------------------------------
+# Client side: reconstruct an exception from a received envelope
+# ---------------------------------------------------------------------------
+
+_CATEGORY_TO_EXCEPTION_CLASS: dict[ErrorCategory, type[OpenFrameError]] = {
+    ErrorCategory.NOT_FOUND: AdapterNotFoundError,
+    ErrorCategory.TIMEOUT: AdapterTimeoutError,
+    ErrorCategory.UNAVAILABLE: AdapterConnectionError,
+    # INVALID and INTERNAL both reconstruct as AdapterQueryError — core's
+    # AdapterError family has no dedicated "the request itself was
+    # malformed" subclass (the server side used pydantic's ValidationError
+    # directly, which only exists on the server; there is nothing to
+    # reconstruct symmetrically on the client). AdapterQueryError is the
+    # closest existing fit for both: a failed operation, not retryable by
+    # default — documented here as a deliberate choice, not an oversight.
+    ErrorCategory.INVALID: AdapterQueryError,
+    ErrorCategory.INTERNAL: AdapterQueryError,
+}
+
+
+def raise_for_envelope(category: ErrorCategory, envelope: ErrorEnvelope, *, remote_name: str) -> None:
+    """
+    Reconstruct and raise the `AdapterError` subclass matching a remote
+    call's error envelope — the client-side mirror of `build_envelope`.
+
+    A remote service call is, from the calling code's perspective,
+    exactly as fallible as a database call, and should surface through
+    the same `AdapterError` family so callers don't need a separate
+    catch clause for "this dependency happens to be another service"
+    versus "this dependency happens to be a database" — see
+    `openframe.core.remote`'s own docstring for the same reasoning
+    applied to the port contract itself.
+
+    Args:
+        category:    The category the response's status (or whatever the
+                     calling transport uses to signal failure) mapped to.
+        envelope:    The decoded error envelope from the response body.
+        remote_name: Identifies which remote call this was, in the raised
+                     exception's own `adapter`/`operation` context — e.g.
+                     `"http:GET /items/{item_id}"`. Not the envelope's own
+                     `code`, which identifies the *server's* error, not
+                     which call on the client side failed.
+
+    Raises:
+        Always raises — this function never returns normally. The
+        specific `AdapterError` subclass is chosen by `category`;
+        `retryable` on the raised instance reflects the envelope's own
+        `retryable` flag, which may differ from the subclass's default
+        (e.g. a `503` the server marked non-retryable for some reason).
+    """
+    exc_class = _CATEGORY_TO_EXCEPTION_CLASS[category]
+    # AdapterError subclasses' own __init__ only forwards (message,
+    # adapter, operation, cause) — confirmed directly, not assumed:
+    # retryable/correlation_id are NOT constructor kwargs despite being
+    # real OpenFrameError attributes, so they're set after construction.
+    exc = exc_class(envelope.message, adapter=remote_name, operation="call")
+    exc.retryable = envelope.retryable
+    exc.correlation_id = envelope.correlation_id
+    raise exc

openframe/protocol/base/testing.py

@@ -0,0 +1,332 @@
+"""
+openframe/protocol/base/testing.py
+=====================================
+`TransportDriver` + `TransportConformanceTests` — the one conformance
+suite every inbound `openframe-protocol-*` binding proves itself against.
+
+Incubating here, not in `openframe-core`, per draft 8 section 4's own
+rule: core's existing suites (`core.testing.contracts.inbound`) are
+shape-only (does `execute()` have the right signature) — they know
+nothing about transports, error mapping, or correlation ids. This suite
+is promoted to `openframe.core.testing` only after HTTP *and* gRPC both
+pass it for real (the same rule-of-three discipline already applied to
+`SessionHandler`).
+
+Design choice: every assertion goes through `DriverResult`, a normalised
+shape every transport's own driver translates its real response into —
+an HTTP status code and a gRPC status code mean nothing to each other,
+but `ErrorCategory.NOT_FOUND` means the same thing regardless of which
+wire format produced it. This is what actually keeps the suite
+transport-agnostic rather than secretly HTTP-shaped.
+
+No top-level pytest import — importable without pytest installed,
+matching every `openframe.core.testing` contract module's own convention.
+
+Dependency order:
+    protocol/base/testing → protocol/base/errors
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Protocol, runtime_checkable
+
+from openframe.protocol.base.errors import ErrorCategory
+
+__all__ = [
+    "DriverResult",
+    "TransportDriver",
+    "TransportConformanceTests",
+    "UNEXPECTED_ERROR_SECRET",
+    "RemoteClientDriver",
+    "RemoteClientConformanceTests",
+]
+
+# Shared between this module's own assertions and every driver
+# implementation's `call_unexpected_error()` — the driver rigs its
+# handler to raise an exception carrying this exact string, and the
+# conformance test asserts it is absent from the caller-visible body.
+# A real driver-cause string, not a placeholder — if this ever shows up
+# in a response body, the leak is real, not a test artefact.
+UNEXPECTED_ERROR_SECRET = "driver-internal-cause-must-never-reach-a-caller"
+
+
+@dataclass(frozen=True)
+class DriverResult:
+    """
+    One call's outcome, normalised to a shape every transport can produce.
+
+    Attributes:
+        category:       `None` on success. An `ErrorCategory` member on
+                        failure — the caller-facing classification, not
+                        a transport-specific status code.
+        body:           The decoded response body (a dict) on success,
+                        or the decoded error envelope on failure.
+        correlation_id: Extracted from wherever the transport carries it
+                        (an HTTP response header, a gRPC trailer, ...).
+                        `None` only if the driver genuinely couldn't find
+                        one — a real conformance failure if assertions
+                        don't later catch it, not an expected state.
+        retryable:      Only meaningful when `category` is not `None`.
+    """
+
+    category: ErrorCategory | None
+    body: Mapping[str, Any]
+    correlation_id: str | None
+    retryable: bool | None = None
+
+
+@runtime_checkable
+class TransportDriver(Protocol):
+    """
+    What a transport's own test module implements to run this suite.
+
+    Each `call_*` method exercises one bound handler scenario end-to-end
+    (through the real binder, not by calling a handler method directly)
+    and returns the outcome as a `DriverResult`. How a driver rigs its
+    handler to produce each scenario (which fake, which `raises=`) is the
+    driver's own business — `SpyCommandHandler(raises=...)`/
+    `SpyQueryHandler(raises=...)` from `openframe.core.testing` cover
+    every case below.
+    """
+
+    async def call_create(self) -> DriverResult:
+        """A command that succeeds — e.g. creating an entity."""
+        ...
+
+    async def call_get_existing(self) -> DriverResult:
+        """A query that finds its target and returns a non-empty result."""
+        ...
+
+    async def call_get_missing(self) -> DriverResult:
+        """A query whose target doesn't exist — must categorise NOT_FOUND."""
+        ...
+
+    async def call_list(self) -> DriverResult:
+        """A query returning a collection — proves the binder isn't single-entity-only."""
+        ...
+
+    async def call_invalid_input(self) -> DriverResult:
+        """A request whose payload fails input validation — must categorise INVALID."""
+        ...
+
+    async def call_timeout(self) -> DriverResult:
+        """The handler raises `AdapterTimeoutError` — must categorise TIMEOUT, retryable."""
+        ...
+
+    async def call_connection_error(self) -> DriverResult:
+        """The handler raises `AdapterConnectionError` — must categorise UNAVAILABLE, retryable."""
+        ...
+
+    async def call_unexpected_error(self) -> DriverResult:
+        """
+        The handler raises a bare, non-`OpenFrameError` exception carrying
+        `UNEXPECTED_ERROR_SECRET` in its message — must categorise
+        INTERNAL, and the secret must not appear in `body`.
+        """
+        ...
+
+    async def call_with_traceparent(self, traceparent: str) -> DriverResult:
+        """A successful call carrying a real W3C `traceparent` header."""
+        ...
+
+    async def call_with_correlation_header(self, value: str) -> DriverResult:
+        """A successful call carrying a correlation-id header, no traceparent."""
+        ...
+
+    async def call_with_no_trace_context(self) -> DriverResult:
+        """A successful call with neither header — correlation_id must still be generated."""
+        ...
+
+
+class TransportConformanceTests:
+    """
+    Reusable pytest base class. Subclasses provide one fixture:
+
+    ``driver``
+        A fresh instance satisfying `TransportDriver`, wired to a real
+        bound handler over the transport under test (e.g. `httpx` against
+        an in-process ASGI app for HTTP).
+
+    .. stability: experimental
+       New alongside `openframe-protocol-base` itself. Promotion to
+       `openframe.core.testing` is gated on two transports passing this
+       suite for real, per draft 8's rule-of-three discipline.
+    """
+
+    async def test_create_succeeds(self, driver: TransportDriver) -> None:
+        result = await driver.call_create()
+        assert result.category is None
+
+    async def test_get_existing_succeeds(self, driver: TransportDriver) -> None:
+        result = await driver.call_get_existing()
+        assert result.category is None
+        assert result.body
+
+    async def test_get_missing_is_not_found(self, driver: TransportDriver) -> None:
+        result = await driver.call_get_missing()
+        assert result.category is ErrorCategory.NOT_FOUND
+
+    async def test_list_succeeds(self, driver: TransportDriver) -> None:
+        result = await driver.call_list()
+        assert result.category is None
+
+    async def test_invalid_input_is_invalid(self, driver: TransportDriver) -> None:
+        result = await driver.call_invalid_input()
+        assert result.category is ErrorCategory.INVALID
+
+    async def test_timeout_is_timeout_and_retryable(self, driver: TransportDriver) -> None:
+        result = await driver.call_timeout()
+        assert result.category is ErrorCategory.TIMEOUT
+        assert result.retryable is True
+
+    async def test_connection_error_is_unavailable_and_retryable(
+        self, driver: TransportDriver
+    ) -> None:
+        result = await driver.call_connection_error()
+        assert result.category is ErrorCategory.UNAVAILABLE
+        assert result.retryable is True
+
+    async def test_unexpected_error_is_internal_and_does_not_leak(
+        self, driver: TransportDriver
+    ) -> None:
+        result = await driver.call_unexpected_error()
+        assert result.category is ErrorCategory.INTERNAL
+        body_text = str(result.body)
+        assert UNEXPECTED_ERROR_SECRET not in body_text, (
+            "Driver-internal cause leaked into a caller-visible response body — "
+            "an INTERNAL-category error must never expose the real exception message."
+        )
+
+    async def test_correlation_id_from_traceparent(self, driver: TransportDriver) -> None:
+        traceparent = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"
+        result = await driver.call_with_traceparent(traceparent)
+        assert result.correlation_id is not None
+        assert result.correlation_id != ""
+
+    async def test_correlation_id_from_header(self, driver: TransportDriver) -> None:
+        result = await driver.call_with_correlation_header("test-corr-abc123")
+        assert result.correlation_id == "test-corr-abc123"
+
+    async def test_correlation_id_generated_when_absent(self, driver: TransportDriver) -> None:
+        result = await driver.call_with_no_trace_context()
+        assert result.correlation_id is not None
+        assert result.correlation_id != ""
+
+
+# ---------------------------------------------------------------------------
+# Client-side conformance — the outbound counterpart, added for M1b
+# ---------------------------------------------------------------------------
+#
+# Deliberately NOT built on DriverResult's normalise-into-data pattern. A
+# remote client's execute() doesn't return a category-tagged result on
+# failure — it raises a real AdapterError subclass directly (that's the
+# whole point of raise_for_envelope: the caller doesn't need to know this
+# dependency happens to be a remote service rather than a database). So
+# the conformance test for the CLIENT side just calls the driver and
+# asserts the real exception type, rather than introducing a second
+# normalised-result type that would only exist to immediately throw an
+# exception anyway.
+
+
+@runtime_checkable
+class RemoteClientDriver(Protocol):
+    """
+    What a remote-client implementation's own test module provides to
+    run `RemoteClientConformanceTests`. Each `call_*` method exercises
+    one real client call end to end (through the real client class, not
+    by calling a lower-level method directly) against a real bound
+    server on the other end — same rigor as `TransportDriver`, just for
+    the opposite direction.
+    """
+
+    async def call_success(self) -> Any:
+        """A call that succeeds — returns the decoded result."""
+        ...
+
+    async def call_not_found(self) -> Any:
+        """A call whose target doesn't exist server-side. Must raise, not return."""
+        ...
+
+    async def call_timeout(self) -> Any:
+        """The server raises `AdapterTimeoutError`. Must raise the same type client-side."""
+        ...
+
+    async def call_connection_refused(self) -> Any:
+        """A genuine network-level connection failure — not a simulated server error."""
+        ...
+
+    async def call_unexpected_error(self) -> Any:
+        """
+        The server raises a bare, non-`OpenFrameError` exception carrying
+        `UNEXPECTED_ERROR_SECRET`. Must raise `AdapterQueryError`
+        client-side, with the secret absent from the exception's message.
+        """
+        ...
+
+
+class RemoteClientConformanceTests:
+    """
+    Reusable pytest base class. Subclasses provide one fixture:
+
+    ``driver``
+        A fresh instance satisfying `RemoteClientDriver`, wired to a real
+        client calling a real bound server over the transport under test.
+
+    .. stability: experimental
+       New alongside `openframe-protocol-http`'s `HttpRemoteQueryClient`/
+       `HttpRemoteCommandClient`. Promotion to `openframe.core.testing` is
+       gated on two transports (HTTP, gRPC) passing this suite for real,
+       same rule as `TransportConformanceTests`.
+    """
+
+    async def test_call_success_returns_a_value(self, driver: "RemoteClientDriver") -> None:
+        result = await driver.call_success()
+        assert result is not None
+
+    async def test_call_not_found_raises_adapter_not_found_error(
+        self, driver: "RemoteClientDriver"
+    ) -> None:
+        from openframe.core.exceptions import AdapterNotFoundError
+
+        try:
+            await driver.call_not_found()
+        except AdapterNotFoundError:
+            pass
+        else:
+            raise AssertionError("expected AdapterNotFoundError to be raised")
+
+    async def test_call_timeout_raises_adapter_timeout_error(
+        self, driver: "RemoteClientDriver"
+    ) -> None:
+        from openframe.core.exceptions import AdapterTimeoutError
+
+        try:
+            await driver.call_timeout()
+        except AdapterTimeoutError as exc:
+            assert exc.retryable is True
+        else:
+            raise AssertionError("expected AdapterTimeoutError to be raised")
+
+    async def test_call_connection_refused_raises_adapter_connection_error(
+        self, driver: "RemoteClientDriver"
+    ) -> None:
+        from openframe.core.exceptions import AdapterConnectionError
+
+        try:
+            await driver.call_connection_refused()
+        except AdapterConnectionError:
+            pass
+        else:
+            raise AssertionError("expected AdapterConnectionError to be raised")
+
+    async def test_call_unexpected_error_raises_adapter_query_error_and_does_not_leak(
+        self, driver: "RemoteClientDriver"
+    ) -> None:
+        from openframe.core.exceptions import AdapterQueryError
+
+        try:
+            await driver.call_unexpected_error()
+        except AdapterQueryError as exc:
+            assert UNEXPECTED_ERROR_SECRET not in exc.message
+        else:
+            raise AssertionError("expected AdapterQueryError to be raised")

openframe_protocol_base-0.3.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: openframe-protocol-base
+Version: 0.3.0
+Summary: OpenFrame Microservice Suite - shared transport-neutral protocol mechanics (error mapping, RequestContext construction, inbound conformance suite).
+Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-protocol
+Project-URL: Documentation, https://furious-meteors.github.io/openframe-protocol/
+Project-URL: Repository, https://github.com/Furious-Meteors/openframe-protocol
+Project-URL: Changelog, https://github.com/Furious-Meteors/openframe-protocol/blob/production/.github/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/Furious-Meteors/openframe-protocol/issues
+Author-email: Furious Meteors Engineering <engineering@furiousmeteors.dev>
+Maintainer-email: Furious Meteors Engineering <engineering@furiousmeteors.dev>
+License: MIT
+Keywords: hexagonal,microservice,openframe,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: openframe-core<4,>=3.2.1
+Requires-Dist: opentelemetry-api>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openframe-protocol-base
+
+Shared, transport-neutral mechanics every `openframe-protocol-*` binding
+package builds on. No transport dependencies of its own.
+
+- `errors.py` — `categorize(exc) -> ErrorCategory` and `build_envelope(exc)`,
+  the one place every transport maps `OpenFrameError` (and anything else)
+  to a caller-safe error shape.
+- `context.py` — `build_request_context(headers)`, building
+  `openframe.core.inbound.RequestContext` consistently across transports
+  (trace id, then a correlation header, then a generated uuid4).
+- `testing.py` — `TransportConformanceTests` + `TransportDriver`, the
+  suite every binding proves itself against.
+
+## Wiring example
+
+```python
+from openframe.protocol.base import build_envelope, build_request_context
+
+context = build_request_context(request.headers)
+try:
+    result = await handler.execute(command, context)
+except Exception as exc:
+    envelope = build_envelope(exc, correlation_id=context.correlation_id)
+    # serialise envelope in whatever shape this transport uses
+```
+
+## Status
+
+Experimental — incubating the inbound conformance suite here until two
+transports (HTTP, gRPC) both pass it for real, per the project's own
+rule-of-three discipline for promoting shared infrastructure into
+`openframe-core`.

openframe_protocol_base-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+openframe/protocol/base/__init__.py,sha256=ZDRoe87Ge04hGohxAtt1mEWy02kPPYenu5JcxUR2iVY,1164
+openframe/protocol/base/context.py,sha256=EkixS6VYZg_Kk54hDP8O6_qjWfc9jqh6eEW6l5Ir6Zc,4119
+openframe/protocol/base/errors.py,sha256=VFQACZwAL_AsXRlVnS6fq0zDKxIxzgOcjIP4u0C0G_w,10337
+openframe/protocol/base/testing.py,sha256=vZ4Q0FKKaDfG0fn_eEn0k5qqf10z1EeNQCo1aJLur68,13525
+openframe_protocol_base-0.3.0.dist-info/METADATA,sha256=TuKLyjlxYM-bVe5-yKg6SApzYoDqgA1R39G4w2gymfM,2956
+openframe_protocol_base-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+openframe_protocol_base-0.3.0.dist-info/RECORD,,

openframe_protocol_base-0.3.0.dist-info/WHEEL

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