openframe-core 3.1.0__tar.gz → 3.2.1__tar.gz

{openframe_core-3.1.0 → openframe_core-3.2.1}/.github/CHANGELOG.md

@@ -58,6 +58,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v3.2.1
+
+### Added
+
+- `openframe.core.schemas` — new experimental module providing
+  the `@contract(name, version)` decorator, `ContractMeta` dataclass,
+  and `get_contract_meta()` helper. Marks Pydantic models as
+  published cross-service contracts. The schema export, registry,
+  breaking-change diff, and codegen machinery lives in the
+  separate `openframe-schemas` package (openframe-tooling repo).
+
+---
+
+## v3.2.0
+
+### Added
+
+- `openframe.core.testing.fakes.inbound` — three in-memory test
+  doubles for the inbound contracts: `EchoUseCase`,
+  `SpyCommandHandler`, `SpyQueryHandler`. Mirror of the outbound
+  fakes (`InMemoryRepository`, `FakeProducer`, `FakeConsumer`).
+- `openframe.core.testing.contracts.inbound` — three inheritable
+  pytest base classes: `UseCaseContractTests`,
+  `CommandHandlerContractTests`, `QueryHandlerContractTests`.
+  Any application service or validation-framework service
+  implementing these protocols can prove conformance by inheriting
+  the relevant class.
+- All six new names exported from `openframe.core.testing`
+  top-level for consistent import ergonomics.
+
+---
+
 ## v3.1.0
 
 ### Breaking changes

{openframe_core-3.1.0 → openframe_core-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openframe-core
-Version: 3.1.0
+Version: 3.2.1
 Summary: OpenFrame Microservice Suite - platform kernel. Port contracts, testing utilities, plugin registry, and composition root.
 Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-core
 Project-URL: Documentation, https://furious-meteors.github.io/openframe-core/
@@ -73,16 +73,8 @@ Description-Content-Type: text/markdown
   <a href="https://github.com/Furious-Meteors/openframe-core/blob/production/.github/CHANGELOG.md">Changelog</a>
 </p>
 
----
-
 `openframe-core` is the foundation package of the OpenFrame Microservice Development Suite. It defines the structural contracts, telemetry primitives, and shared utilities that every other package in the ecosystem depends on.
 
-Every package in the OpenFrame ecosystem pins `openframe-core>=3.0,<4`. The major version is the stability contract for the entire ecosystem.
-
-> **v3.0.0 is a breaking redesign.** The old hardcoded, lifecycle-free ports, the standalone `HealthCheck` protocol, and the separate `OpenFramePlugin` protocol are gone. They are replaced by a single unified contract layer built on `BasePort` (`Identity` + `Lifecycle`), and the error hierarchy is consolidated under a single `OpenFrameError` root. **v3.1.0 merges `openframe.core.contracts` into `openframe.core.ports`, and moves `BaseRepository`/`BaseProducer`/`BaseConsumer` into an internal `ports/outbound/` sub-module** (mirroring `openframe.core.inbound`) — no compatibility shim at the old path, and no change to the public `from openframe.core.ports import ...` surface. See [ADR-006](https://furious-meteors.github.io/openframe-core/technical/architecture/adrs/adr-006-unified-port-lifecycle/) and the [Changelog](.github/CHANGELOG.md) for the full migration guide.
-
----
-
 ## What's inside
 
 | Module | Exports |

{openframe_core-3.1.0 → openframe_core-3.2.1}/README.md

@@ -17,16 +17,8 @@
   <a href="https://github.com/Furious-Meteors/openframe-core/blob/production/.github/CHANGELOG.md">Changelog</a>
 </p>
 
----
-
 `openframe-core` is the foundation package of the OpenFrame Microservice Development Suite. It defines the structural contracts, telemetry primitives, and shared utilities that every other package in the ecosystem depends on.
 
-Every package in the OpenFrame ecosystem pins `openframe-core>=3.0,<4`. The major version is the stability contract for the entire ecosystem.
-
-> **v3.0.0 is a breaking redesign.** The old hardcoded, lifecycle-free ports, the standalone `HealthCheck` protocol, and the separate `OpenFramePlugin` protocol are gone. They are replaced by a single unified contract layer built on `BasePort` (`Identity` + `Lifecycle`), and the error hierarchy is consolidated under a single `OpenFrameError` root. **v3.1.0 merges `openframe.core.contracts` into `openframe.core.ports`, and moves `BaseRepository`/`BaseProducer`/`BaseConsumer` into an internal `ports/outbound/` sub-module** (mirroring `openframe.core.inbound`) — no compatibility shim at the old path, and no change to the public `from openframe.core.ports import ...` surface. See [ADR-006](https://furious-meteors.github.io/openframe-core/technical/architecture/adrs/adr-006-unified-port-lifecycle/) and the [Changelog](.github/CHANGELOG.md) for the full migration guide.
-
----
-
 ## What's inside
 
 | Module | Exports |

openframe_core-3.2.1/docs/code/modules/health.md

@@ -0,0 +1,46 @@
+# Health
+
+Health is part of the unified `Lifecycle` contract in `openframe.core.ports`. Every `BasePort` implements a single `health()` method that returns a rich `PluginHealth` snapshot — there is no separate health protocol.
+
+```python
+from openframe.core.ports import Lifecycle, PluginHealth, PluginStatus
+
+async def health(self) -> PluginHealth:
+    try:
+        await self._pool.fetchval("SELECT 1")
+        return PluginHealth(status=PluginStatus.READY)
+    except Exception as exc:
+        return PluginHealth(
+            status=PluginStatus.UNAVAILABLE,
+            message=str(exc),
+        )
+```
+
+`Lifecycle.health()` is the single canonical health primitive. Liveness vs. readiness granularity — or any other reporting distinction an adapter needs — is expressed through `PluginStatus` and `PluginHealth.details`, not through separate methods:
+
+```python
+# Minimal
+PluginHealth(status=PluginStatus.READY)
+
+# With detail
+PluginHealth(
+    status=PluginStatus.READY,
+    details={"ping_ms": 2.1, "schema_ok": True},
+)
+
+# Degraded
+PluginHealth(
+    status=PluginStatus.DEGRADED,
+    message="replica lag 5s",
+    details={"lag_s": 5},
+)
+```
+
+`PluginRegistry` calls `health()` on every registered port to build a live snapshot — see [`PluginRegistry.health_all()`](plugins.md).
+
+---
+
+## See Also
+
+- [ports module](ports.md) — `Lifecycle`, `PluginHealth`, `PluginStatus`, `BasePort`
+- [ADR-006](../../technical/architecture/adrs/adr-006-unified-port-lifecycle.md) — full design rationale

{openframe_core-3.1.0 → openframe_core-3.2.1}/docs/index.md

@@ -2,7 +2,7 @@
 
 The foundation package of the OpenFrame Microservice Development Suite — the unified port + lifecycle contract layer, structured exceptions, telemetry, and ASGI middleware for any hexagonal architecture Python service. Every ecosystem package pins `openframe-core>=3.0,<4`.
 
-> **v3.0.0 is a breaking redesign.** The old lifecycle-free ports, standalone `HealthCheck`, and separate `OpenFramePlugin` protocol are replaced by a single unified contract layer (`BasePort` = `Identity` + `Lifecycle`). The error hierarchy is consolidated under `OpenFrameError`. **v3.1.0 merges `openframe.core.contracts` into `openframe.core.ports`** and moves the outbound protocols into an internal `ports/outbound/` sub-module — no compatibility shim, no public API change. See [ADR-006](technical/architecture/adrs/adr-006-unified-port-lifecycle.md) for the full rationale.
+`openframe-core` is built around a single unified contract layer: `BasePort` (`Identity` + `Lifecycle`) is the one base every outbound port and every registrable plugin extends — there is no separate health protocol and no separate plugin protocol. The error hierarchy is consolidated under a single `OpenFrameError` root. The full contract layer, including the capability-specific outbound protocols (`BaseRepository`, `BaseProducer`, `BaseConsumer`), lives in `openframe.core.ports`. See [ADR-006](technical/architecture/adrs/adr-006-unified-port-lifecycle.md) for the full design rationale.
 
 ---
 

{openframe_core-3.1.0 → openframe_core-3.2.1}/docs/technical/overview/roadmap.md

@@ -40,7 +40,7 @@ Lower-priority items:
 
 ## v3.1.0 — contracts/ Merged into ports/, outbound/ Sub-module Introduced (breaking)
 
-> Ecosystem packages pin `openframe-core>=3.0,<4`.
+> Ecosystem packages pinned `openframe-core>=3.0,<4`; `openframe-adapters` has migrated its imports to `openframe.core.ports`.
 
 - `openframe.core.contracts` renamed to `openframe.core.ports`. All names previously importable from `openframe.core.contracts` are now importable from `openframe.core.ports`. No compatibility shim — update all imports.
 - `openframe.core.ports` now exports both the port primitives (`BasePort`, `Capability`, `Identity`, `Lifecycle`, `PluginStatus`, `PluginHealth`, `PluginContext`, `PrincipalContext`, `TenantContext`) and the outbound protocols (`BaseRepository`, `BaseProducer`, `BaseConsumer`) from a single unified module.
@@ -50,7 +50,7 @@ Lower-priority items:
 
 ## v3.0.0 — Unified Port + Lifecycle Contract (breaking)
 
-> Full migration guide: [ADR-006](../architecture/adrs/adr-006-unified-port-lifecycle.md). Ecosystem packages pin `openframe-core>=3.0,<4`.
+> Migration guide: [ADR-006](../architecture/adrs/adr-006-unified-port-lifecycle.md). Ecosystem packages pinned `openframe-core>=3.0,<4`; all packages have since migrated.
 
 **Removed:**
 

openframe_core-3.2.1/openframe/core/schemas/__init__.py

@@ -0,0 +1,128 @@
+"""
+openframe.core.schemas
+========================
+Cross-service data shape governance (ADR-007).
+
+The @contract decorator marks a Pydantic model as a published
+cross-service contract — a shape that crosses a service boundary
+(via REST, Kafka, gRPC, or any other transport) and must be
+governed for breaking changes.
+
+This module owns only the *marker*. The machinery that acts on
+the marker — schema export, version registry, breaking-change diff,
+codegen — lives in the separate openframe-schemas package, which
+has its own dependencies and release cadence.
+
+Dependency order:
+    core/schemas → stdlib only (no pydantic, no openframe imports)
+
+Usage::
+
+    from openframe.core.schemas import contract
+
+    @contract(name="item", version="1.0")
+    class Item(BaseModel):
+        id: str
+        name: str
+        description: str | None = None
+        status: str = "active"
+
+The @contract decorator does not change the class in any way that
+affects Pydantic validation, serialization, or runtime behaviour.
+It attaches __contract__ as a class attribute that openframe-schemas
+reads at schema-export time.
+
+.. stability: experimental
+   Experimental — the decorator signature (name, version) is stable;
+   the ContractMeta attributes may gain additional fields in future
+   minor versions.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["ContractMeta", "contract", "get_contract_meta"]
+
+__stability__ = "experimental"
+
+
+@dataclass
+class ContractMeta:
+    """
+    Metadata attached to a @contract-decorated model.
+
+    .. stability: experimental
+
+    Attributes:
+        name:    The contract's stable name (e.g. ``"item"``). Identifies
+                 the contract independently of the Python class name.
+        version: The contract's version string (e.g. ``"1.0"``). Governed
+                 by openframe-schemas' breaking-change diff tooling.
+    """
+
+    name: str
+    version: str
+
+    __stability__ = "experimental"
+
+
+def contract(name: str, version: str):
+    """
+    Mark a class as a published cross-service contract.
+
+    Attaches a :class:`ContractMeta` instance to the decorated class as
+    ``cls.__contract__``. Returns the class unchanged — pure decoration,
+    no wrapping — so Pydantic validation, serialization, and any other
+    runtime behaviour are unaffected.
+
+    Works with any class, not just Pydantic ``BaseModel`` subclasses, but
+    the intended use is always Pydantic models.
+
+    .. stability: experimental
+
+    Args:
+        name:    The contract's stable name.
+        version: The contract's version string.
+
+    Returns:
+        A decorator that attaches ``__contract__`` to the class and
+        returns it unchanged.
+
+    Usage::
+
+        @contract(name="item", version="1.0")
+        class Item(BaseModel):
+            id: str
+            name: str
+    """
+
+    def _decorate(cls: type) -> type:
+        cls.__contract__ = ContractMeta(name=name, version=version)
+        return cls
+
+    return _decorate
+
+
+contract.__stability__ = "experimental"
+
+
+def get_contract_meta(cls: type) -> ContractMeta | None:
+    """
+    Return the ContractMeta attached to a class, if any.
+
+    Safe on any class — undecorated classes simply return ``None``
+    rather than raising.
+
+    .. stability: experimental
+
+    Args:
+        cls: The class to inspect.
+
+    Returns:
+        The :class:`ContractMeta` attached via :func:`contract`, or
+        ``None`` if the class is not @contract-decorated.
+    """
+    return getattr(cls, "__contract__", None)
+
+
+get_contract_meta.__stability__ = "experimental"

{openframe_core-3.1.0 → openframe_core-3.2.1}/openframe/core/testing/__init__.py

@@ -4,10 +4,12 @@ openframe.core.testing
 Reusable testing infrastructure for the OpenFrame ecosystem (ADR-006).
 
 Provides in-memory test doubles (fakes) and reusable pytest base classes
-(contract tests) that every ``openframe-adapters-*`` package uses.
+(contract tests) for both the outbound (driven) side — every
+``openframe-adapters-*`` package uses these — and the inbound (driving)
+side of the hexagon.
 
 Zero external dependencies — fakes import only from
-``openframe.core.ports``, ``openframe.core.ports``, and
+``openframe.core.ports``, ``openframe.core.inbound``, and
 ``openframe.core.exceptions``.  Contract test classes do not import pytest
 at the module level; they are only useful when pytest is installed.
 
@@ -21,15 +23,31 @@ Quick reference::
 
     repo = InMemoryRepository()
     assert isinstance(repo, BaseRepository)  # BasePort + repository methods
+
+    from openframe.core.testing import EchoUseCase, SpyCommandHandler, SpyQueryHandler
+    from openframe.core.testing import UseCaseContractTests
+
+    use_case = EchoUseCase(response={"id": "1"})
+    assert isinstance(use_case, UseCase)
 """
 from __future__ import annotations
 
 from openframe.core.testing.contracts.consumer import ConsumerContractTests
+from openframe.core.testing.contracts.inbound import (
+    CommandHandlerContractTests,
+    QueryHandlerContractTests,
+    UseCaseContractTests,
+)
 from openframe.core.testing.contracts.lifecycle import LifecycleContractTests
 from openframe.core.testing.contracts.port import PortContractTests
 from openframe.core.testing.contracts.producer import ProducerContractTests
 from openframe.core.testing.contracts.repository import RepositoryContractTests
 from openframe.core.testing.fakes.consumer import FakeConsumer
+from openframe.core.testing.fakes.inbound import (
+    EchoUseCase,
+    SpyCommandHandler,
+    SpyQueryHandler,
+)
 from openframe.core.testing.fakes.producer import FakeProducer
 from openframe.core.testing.fakes.repository import InMemoryRepository
 
@@ -37,9 +55,15 @@ __all__ = [
     "InMemoryRepository",
     "FakeProducer",
     "FakeConsumer",
+    "EchoUseCase",
+    "SpyCommandHandler",
+    "SpyQueryHandler",
     "LifecycleContractTests",
     "PortContractTests",
     "RepositoryContractTests",
     "ProducerContractTests",
     "ConsumerContractTests",
+    "UseCaseContractTests",
+    "CommandHandlerContractTests",
+    "QueryHandlerContractTests",
 ]

openframe_core-3.2.1/openframe/core/testing/contracts/__init__.py

@@ -0,0 +1,44 @@
+"""
+openframe.core.testing.contracts
+==================================
+Reusable pytest base classes for port and inbound contract tests (ADR-006).
+
+Outbound: ``PortContractTests``/``LifecycleContractTests`` cover the
+shared ``BasePort`` identity/lifecycle suite; ``RepositoryContractTests``,
+``ProducerContractTests``, ``ConsumerContractTests`` build on
+``PortContractTests`` with domain-specific assertions.
+
+Inbound: ``UseCaseContractTests``, ``CommandHandlerContractTests``,
+``QueryHandlerContractTests`` mirror the outbound contract classes for
+the driving side of the hexagon. They do not build on any shared base
+class — ``UseCase``/``CommandHandler``/``QueryHandler`` do not extend
+``BasePort``.
+
+No top-level pytest import — all modules here can be imported without
+pytest installed.
+
+.. stability: beta
+"""
+from __future__ import annotations
+
+from openframe.core.testing.contracts.consumer import ConsumerContractTests
+from openframe.core.testing.contracts.inbound import (
+    CommandHandlerContractTests,
+    QueryHandlerContractTests,
+    UseCaseContractTests,
+)
+from openframe.core.testing.contracts.lifecycle import LifecycleContractTests
+from openframe.core.testing.contracts.port import PortContractTests
+from openframe.core.testing.contracts.producer import ProducerContractTests
+from openframe.core.testing.contracts.repository import RepositoryContractTests
+
+__all__ = [
+    "LifecycleContractTests",
+    "PortContractTests",
+    "RepositoryContractTests",
+    "ProducerContractTests",
+    "ConsumerContractTests",
+    "UseCaseContractTests",
+    "CommandHandlerContractTests",
+    "QueryHandlerContractTests",
+]

openframe_core-3.2.1/openframe/core/testing/contracts/inbound.py

@@ -0,0 +1,221 @@
+"""
+openframe/core/testing/contracts/inbound.py
+==============================================
+UseCaseContractTests, CommandHandlerContractTests, QueryHandlerContractTests
+— reusable pytest base classes for the inbound (driving) side of the
+hexagon (ADR-006).
+
+Any application service or validation-framework service implementing
+:class:`~openframe.core.inbound.usecase.UseCase`,
+:class:`~openframe.core.inbound.command.CommandHandler`, or
+:class:`~openframe.core.inbound.query.QueryHandler` can prove protocol
+conformance by inheriting the matching class here and providing its
+required fixture.
+
+Unlike :class:`~openframe.core.testing.contracts.repository.RepositoryContractTests`
+(which builds on :class:`~openframe.core.testing.contracts.port.PortContractTests`
+for the shared ``BasePort`` identity/lifecycle suite), there is no base
+class above these three. ``UseCase``/``CommandHandler``/``QueryHandler``
+do not extend ``BasePort`` — they are inbound (driving) contracts, not
+outbound ports — so each class stands alone.
+
+No top-level pytest import — this module can be imported without pytest
+installed. The test methods use pytest's fixture injection mechanism
+through parameter names; pytest is discovered at collection time.
+
+.. stability: beta
+   Beta — API may change in minor versions with a deprecation notice.
+
+Dependency order:
+    testing/contracts/inbound → inbound
+
+Subclass usage::
+
+    class TestMyUseCase(UseCaseContractTests):
+        @pytest.fixture
+        def use_case(self) -> MyUseCase:
+            return MyUseCase()
+
+    class TestMyCommandHandler(CommandHandlerContractTests):
+        @pytest.fixture
+        def command_handler(self) -> MyCommandHandler:
+            return MyCommandHandler()
+
+    class TestMyQueryHandler(QueryHandlerContractTests):
+        @pytest.fixture
+        def query_handler(self) -> MyQueryHandler:
+            return MyQueryHandler()
+
+        @pytest.fixture
+        def make_query(self):
+            def _make() -> str:
+                return "item-1"
+            return _make
+"""
+from __future__ import annotations
+
+from openframe.core.inbound.context import RequestContext
+
+__all__ = [
+    "UseCaseContractTests",
+    "CommandHandlerContractTests",
+    "QueryHandlerContractTests",
+]
+
+
+class UseCaseContractTests:
+    """
+    Reusable pytest base class for :class:`~openframe.core.inbound.usecase.UseCase`
+    contract tests.
+
+    Subclasses must provide one pytest fixture:
+
+    ``use_case``
+        A fresh instance satisfying
+        :class:`~openframe.core.inbound.usecase.UseCase`.
+
+    Subclasses may optionally override the ``make_command`` method to
+    supply a custom command payload; the default is a dict ``{"id": "test"}``.
+    Not a pytest fixture — a plain overridable method, following the same
+    convention as :meth:`~openframe.core.testing.contracts.lifecycle.LifecycleContractTests._make_context`,
+    so this module never needs a top-level pytest import.
+
+    .. stability: beta
+    """
+
+    def make_command(self):
+        """Build a default command payload — a plain dict. Override to customise."""
+        return {"id": "test"}
+
+    async def test_satisfies_use_case_protocol(self, use_case) -> None:
+        """use_case satisfies UseCase via structural subtyping."""
+        from openframe.core.inbound import UseCase
+
+        assert isinstance(use_case, UseCase), (
+            f"{type(use_case).__name__} does not satisfy UseCase. "
+            "Ensure it has a matching async 'execute' method."
+        )
+
+    async def test_execute_without_context_returns_result(self, use_case) -> None:
+        """execute(command) completes without raising, given no context."""
+        command = self.make_command()
+        await use_case.execute(command)
+
+    async def test_execute_with_context_threads_correlation_id(self, use_case) -> None:
+        """execute(command, context) accepts a RequestContext without raising."""
+        command = self.make_command()
+        context = RequestContext(correlation_id="test-corr-1")
+        await use_case.execute(command, context)
+
+    async def test_execute_with_none_context_is_accepted(self, use_case) -> None:
+        """execute(command, None) is accepted — context is optional."""
+        command = self.make_command()
+        await use_case.execute(command, None)
+
+
+class CommandHandlerContractTests:
+    """
+    Reusable pytest base class for
+    :class:`~openframe.core.inbound.command.CommandHandler` contract tests.
+
+    Subclasses must provide one pytest fixture:
+
+    ``command_handler``
+        A fresh instance satisfying
+        :class:`~openframe.core.inbound.command.CommandHandler`.
+
+    Subclasses may optionally override the ``make_command`` method to
+    supply a custom command payload; the default is a dict ``{"id": "test"}``.
+    Not a pytest fixture — a plain overridable method, following the same
+    convention as :meth:`~openframe.core.testing.contracts.lifecycle.LifecycleContractTests._make_context`,
+    so this module never needs a top-level pytest import.
+
+    .. stability: beta
+    """
+
+    def make_command(self):
+        """Build a default command payload — a plain dict. Override to customise."""
+        return {"id": "test"}
+
+    async def test_satisfies_command_handler_protocol(self, command_handler) -> None:
+        """command_handler satisfies CommandHandler via structural subtyping."""
+        from openframe.core.inbound import CommandHandler
+
+        assert isinstance(command_handler, CommandHandler), (
+            f"{type(command_handler).__name__} does not satisfy CommandHandler. "
+            "Ensure it has a matching async 'execute' method."
+        )
+
+    async def test_execute_returns_none(self, command_handler) -> None:
+        """execute(command) returns None on success — the defining CommandHandler property."""
+        command = self.make_command()
+        result = await command_handler.execute(command)
+        assert result is None
+
+    async def test_execute_with_context_returns_none(self, command_handler) -> None:
+        """execute(command, context) returns None — context does not change the return type."""
+        command = self.make_command()
+        context = RequestContext(correlation_id="test-corr-1")
+        result = await command_handler.execute(command, context)
+        assert result is None
+
+    async def test_execute_with_none_context_is_accepted(self, command_handler) -> None:
+        """execute(command, None) completes without raising and returns None."""
+        command = self.make_command()
+        result = await command_handler.execute(command, None)
+        assert result is None
+
+
+class QueryHandlerContractTests:
+    """
+    Reusable pytest base class for
+    :class:`~openframe.core.inbound.query.QueryHandler` contract tests.
+
+    Subclasses must provide one pytest fixture:
+
+    ``query_handler``
+        A fresh instance satisfying
+        :class:`~openframe.core.inbound.query.QueryHandler`, configured
+        to return a non-``None`` result.
+
+    Subclasses may optionally override the ``make_query`` method to
+    supply a custom query payload; the default is the string
+    ``"test-query"``. Not a pytest fixture — a plain overridable method,
+    following the same convention as
+    :meth:`~openframe.core.testing.contracts.lifecycle.LifecycleContractTests._make_context`,
+    so this module never needs a top-level pytest import.
+
+    .. stability: beta
+    """
+
+    def make_query(self):
+        """Build a default query payload — a plain string. Override to customise."""
+        return "test-query"
+
+    async def test_satisfies_query_handler_protocol(self, query_handler) -> None:
+        """query_handler satisfies QueryHandler via structural subtyping."""
+        from openframe.core.inbound import QueryHandler
+
+        assert isinstance(query_handler, QueryHandler), (
+            f"{type(query_handler).__name__} does not satisfy QueryHandler. "
+            "Ensure it has a matching async 'execute' method."
+        )
+
+    async def test_execute_returns_a_result(self, query_handler) -> None:
+        """execute(query) returns a non-None result — distinguishes QueryHandler from CommandHandler."""
+        query = self.make_query()
+        result = await query_handler.execute(query)
+        assert result is not None
+
+    async def test_execute_with_context_returns_result(self, query_handler) -> None:
+        """execute(query, context) returns a non-None result — context does not change the return type."""
+        query = self.make_query()
+        context = RequestContext(correlation_id="test-corr-1")
+        result = await query_handler.execute(query, context)
+        assert result is not None
+
+    async def test_execute_with_none_context_is_accepted(self, query_handler) -> None:
+        """execute(query, None) returns a non-None result — context is optional."""
+        query = self.make_query()
+        result = await query_handler.execute(query, None)
+        assert result is not None

openframe_core-3.2.1/openframe/core/testing/fakes/__init__.py

@@ -0,0 +1,36 @@
+"""
+openframe.core.testing.fakes
+==============================
+In-memory test doubles for OpenFrame ports and inbound contracts (ADR-006).
+
+Outbound fakes (``InMemoryRepository``, ``FakeProducer``, ``FakeConsumer``)
+have zero external dependencies and satisfy their respective
+``BasePort``-based port protocols via structural subtyping — including the
+identity/lifecycle members every port now carries.
+
+Inbound fakes (``EchoUseCase``, ``SpyCommandHandler``, ``SpyQueryHandler``)
+mirror the outbound fakes for the driving side of the hexagon — they
+satisfy ``UseCase``/``CommandHandler``/``QueryHandler`` structurally and
+record every call for spy-style assertions.
+
+.. stability: beta
+"""
+from __future__ import annotations
+
+from openframe.core.testing.fakes.consumer import FakeConsumer
+from openframe.core.testing.fakes.inbound import (
+    EchoUseCase,
+    SpyCommandHandler,
+    SpyQueryHandler,
+)
+from openframe.core.testing.fakes.producer import FakeProducer
+from openframe.core.testing.fakes.repository import InMemoryRepository
+
+__all__ = [
+    "InMemoryRepository",
+    "FakeProducer",
+    "FakeConsumer",
+    "EchoUseCase",
+    "SpyCommandHandler",
+    "SpyQueryHandler",
+]