openframe-core 3.0.1__tar.gz → 3.2.0__tar.gz

{openframe_core-3.0.1 → openframe_core-3.2.0}/.github/CHANGELOG.md

@@ -18,12 +18,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   as the default starting point and frame the other two as explicit alternatives
   with stated conditions. Tracked in the roadmap.
 
-- **`contracts/` five-module depth** — the `capability → context → health →
-  identity → lifecycle → port` chain is clean today. The risk is a sixth or
-  seventh module that doesn't stay within the single-concept-per-file rule or
-  that imports from non-adjacent layers. Consolidate before expanding if either
-  signal appears.
-
 ### Added
 
 - **`openframe.core.telemetry.shutdown_telemetry()`** — flushes and shuts
@@ -64,6 +58,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## 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.contracts → openframe.core.ports
+
+The openframe.core.contracts module has been merged into
+openframe.core.ports and no longer exists. All names previously
+importable from openframe.core.contracts are now importable from
+openframe.core.ports:
+
+```python
+# Before (< v3.1.0)
+from openframe.core.contracts import BasePort, Capability, PluginHealth
+
+# After (v3.1.0+)
+from openframe.core.ports import BasePort, Capability, PluginHealth
+```
+
+No compatibility shim is provided at the old path.
+
+`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.
+
+#### BaseRepository, BaseProducer, BaseConsumer moved to ports/outbound/
+
+The three capability-specific outbound port protocols have moved
+into the ports/outbound/ sub-module to mirror the existing
+inbound/ sub-module on the driven side of the hexagon.
+The public API is unchanged — import from openframe.core.ports
+as before:
+
+```python
+from openframe.core.ports import BaseRepository  # unchanged
+```
+
+The explicit sub-module path is now:
+
+```python
+from openframe.core.ports.outbound import BaseRepository
+```
+
+Future outbound capability protocols (BaseSecretsProvider,
+BaseObjectStore, BaseFeatureFlagProvider from openframe-infra)
+will be added to openframe/core/ports/outbound/ as the
+ecosystem grows.
+
+---
+
 ## [3.0.0] — 2026-07-07
 
 ### Architecture scorecard

{openframe_core-3.0.1 → openframe_core-3.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: openframe-core
-Version: 3.0.1
-Summary: OpenFrame Microservice Suite - platform kernel. Contracts, testing utilities, plugin registry, and composition root.
+Version: 3.2.0
+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/
 Project-URL: Repository, https://github.com/Furious-Meteors/openframe-core
@@ -73,24 +73,15 @@ 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. 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.contracts` | `BasePort` · `Identity` · `Lifecycle` · `Capability` · `PluginStatus` · `PluginHealth` · `PluginContext` · `PrincipalContext` · `TenantContext` |
+| `openframe.core.ports` | `BasePort` · `Identity` · `Lifecycle` · `Capability` · `PluginStatus` · `PluginHealth` · `PluginContext` · `PrincipalContext` · `TenantContext` · `BaseRepository[T]` · `BaseProducer[T]` · `BaseConsumer[T]` |
 | `openframe.core.exceptions` | `OpenFrameError` (root) · `ErrorCode` · `Severity` · `AdapterError` (+5) · `PluginError` (+4, incl. `AmbiguousCapabilityError`) |
 | `openframe.core.config` | `BaseAdapterSettings` — Pydantic `BaseSettings` subclass all adapters inherit |
-| `openframe.core.ports` | `BaseRepository[T]` · `BaseProducer[T]` · `BaseConsumer[T]` — `BasePort` + domain methods (outbound side) |
 | `openframe.core.inbound` | `UseCase[TIn, TOut]` · `CommandHandler[TIn]` · `QueryHandler[TIn, TOut]` · `RequestContext` (driving side) |
 | `openframe.core.plugins` | `PluginRegistry` — explicit registration, ordered init, LIFO shutdown, capability lookup |
 | `openframe.core.runtime` | `ApplicationBootstrap` — optional composition-root base class |
@@ -169,8 +160,7 @@ settings = PostgresSettings()
 Every port is a `BasePort`: `Identity` (`name`/`version`/`capability`) + `Lifecycle` (`initialize`/`shutdown`/`health`) plus its own domain methods. Adapters satisfy it structurally — no inheritance required.
 
 ```python
-from openframe.core.contracts import Capability, PluginContext, PluginHealth, PluginStatus
-from openframe.core.ports import BaseRepository
+from openframe.core.ports import Capability, PluginContext, PluginHealth, PluginStatus, BaseRepository
 
 class PostgresItemRepository:
     # Identity
@@ -200,7 +190,7 @@ assert isinstance(PostgresItemRepository(), BaseRepository)   # True
 A "plugin" is just a registered `BasePort`. The registry initializes in order, shuts down LIFO, and looks up by the typed `Capability` enum:
 
 ```python
-from openframe.core.contracts import Capability
+from openframe.core.ports import Capability
 from openframe.core.plugins import PluginRegistry
 
 registry = PluginRegistry()
@@ -218,7 +208,7 @@ await registry.shutdown_all()                 # reverse order; never raises
 ### Runtime — optional composition root
 
 ```python
-from openframe.core.contracts import Capability
+from openframe.core.ports import Capability
 from openframe.core.runtime import ApplicationBootstrap
 
 class MyServiceBootstrap(ApplicationBootstrap):
@@ -356,11 +346,11 @@ pip install -e ".[dev]"
 pytest tests/ -v
 ```
 
-284 tests. All run in under 1 second — no network calls, no external services.
+301 tests. All run in under 1 second — no network calls, no external services.
 
 ```bash
 # Smoke test
-python -c "from openframe.core.contracts import BasePort; print('openframe-core OK')"
+python -c "from openframe.core.ports import BasePort; print('openframe-core OK')"
 ```
 
 ---

{openframe_core-3.0.1 → openframe_core-3.2.0}/README.md

@@ -17,24 +17,15 @@
   <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. 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.contracts` | `BasePort` · `Identity` · `Lifecycle` · `Capability` · `PluginStatus` · `PluginHealth` · `PluginContext` · `PrincipalContext` · `TenantContext` |
+| `openframe.core.ports` | `BasePort` · `Identity` · `Lifecycle` · `Capability` · `PluginStatus` · `PluginHealth` · `PluginContext` · `PrincipalContext` · `TenantContext` · `BaseRepository[T]` · `BaseProducer[T]` · `BaseConsumer[T]` |
 | `openframe.core.exceptions` | `OpenFrameError` (root) · `ErrorCode` · `Severity` · `AdapterError` (+5) · `PluginError` (+4, incl. `AmbiguousCapabilityError`) |
 | `openframe.core.config` | `BaseAdapterSettings` — Pydantic `BaseSettings` subclass all adapters inherit |
-| `openframe.core.ports` | `BaseRepository[T]` · `BaseProducer[T]` · `BaseConsumer[T]` — `BasePort` + domain methods (outbound side) |
 | `openframe.core.inbound` | `UseCase[TIn, TOut]` · `CommandHandler[TIn]` · `QueryHandler[TIn, TOut]` · `RequestContext` (driving side) |
 | `openframe.core.plugins` | `PluginRegistry` — explicit registration, ordered init, LIFO shutdown, capability lookup |
 | `openframe.core.runtime` | `ApplicationBootstrap` — optional composition-root base class |
@@ -113,8 +104,7 @@ settings = PostgresSettings()
 Every port is a `BasePort`: `Identity` (`name`/`version`/`capability`) + `Lifecycle` (`initialize`/`shutdown`/`health`) plus its own domain methods. Adapters satisfy it structurally — no inheritance required.
 
 ```python
-from openframe.core.contracts import Capability, PluginContext, PluginHealth, PluginStatus
-from openframe.core.ports import BaseRepository
+from openframe.core.ports import Capability, PluginContext, PluginHealth, PluginStatus, BaseRepository
 
 class PostgresItemRepository:
     # Identity
@@ -144,7 +134,7 @@ assert isinstance(PostgresItemRepository(), BaseRepository)   # True
 A "plugin" is just a registered `BasePort`. The registry initializes in order, shuts down LIFO, and looks up by the typed `Capability` enum:
 
 ```python
-from openframe.core.contracts import Capability
+from openframe.core.ports import Capability
 from openframe.core.plugins import PluginRegistry
 
 registry = PluginRegistry()
@@ -162,7 +152,7 @@ await registry.shutdown_all()                 # reverse order; never raises
 ### Runtime — optional composition root
 
 ```python
-from openframe.core.contracts import Capability
+from openframe.core.ports import Capability
 from openframe.core.runtime import ApplicationBootstrap
 
 class MyServiceBootstrap(ApplicationBootstrap):
@@ -300,11 +290,11 @@ pip install -e ".[dev]"
 pytest tests/ -v
 ```
 
-284 tests. All run in under 1 second — no network calls, no external services.
+301 tests. All run in under 1 second — no network calls, no external services.
 
 ```bash
 # Smoke test
-python -c "from openframe.core.contracts import BasePort; print('openframe-core OK')"
+python -c "from openframe.core.ports import BasePort; print('openframe-core OK')"
 ```
 
 ---

{openframe_core-3.0.1 → openframe_core-3.2.0}/docs/code/getting-started/index.md

@@ -23,8 +23,10 @@ pip install openframe-core
 
 ```bash
 python -c "
-from openframe.core.contracts import BasePort, Capability, PluginHealth, PluginStatus
-from openframe.core.ports import BaseRepository, BaseProducer, BaseConsumer
+from openframe.core.ports import (
+    BasePort, Capability, PluginHealth, PluginStatus,
+    BaseRepository, BaseProducer, BaseConsumer,
+)
 from openframe.core.exceptions import OpenFrameError, AdapterError
 from openframe.core.inbound import UseCase, RequestContext
 from openframe.core.plugins import PluginRegistry
@@ -67,7 +69,7 @@ export OPENFRAME_ENV="dev"
 ```python
 from contextlib import asynccontextmanager
 from fastapi import FastAPI
-from openframe.core.contracts import Capability
+from openframe.core.ports import Capability
 from openframe.core.plugins import PluginRegistry
 from openframe.core.telemetry import setup_telemetry, record_lifecycle_event
 from openframe.core.middleware import TelemetryMiddleware

openframe_core-3.2.0/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.0.1 → openframe_core-3.2.0}/docs/code/modules/index.md

@@ -1,13 +1,12 @@
 # Modules
 
-`openframe-core` v3.0.0 contains eleven modules, organised into three tiers: foundation, contract layer, and application modules. Each page documents every public class, method, and function with parameters, return types, and what it raises.
+`openframe-core` v3.1.0 contains ten modules, organised into three tiers: foundation, contract layer, and application modules. Each page documents every public class, method, and function with parameters, return types, and what it raises.
 
 | Module | Import path | What it provides |
 |---|---|---|
 | [exceptions](exceptions.md) | `openframe.core.exceptions` | `OpenFrameError` (root) · `ErrorCode` · `Severity` · `AdapterError` (+5) · `PluginError` (+4, incl. `AmbiguousCapabilityError`) |
 | [config](config.md) | `openframe.core.config` | `BaseAdapterSettings` |
-| [contracts](contracts.md) | `openframe.core.contracts` | `Identity` · `Lifecycle` · `BasePort` · `Capability` · `PluginStatus` · `PluginHealth` · `PluginContext` · `PrincipalContext` · `TenantContext` |
-| [ports](ports.md) | `openframe.core.ports` | `BaseRepository[T]` · `BaseProducer[T]` · `BaseConsumer[T]` — `BasePort` + domain methods |
+| [ports](ports.md) | `openframe.core.ports` | `Identity` · `Lifecycle` · `BasePort` · `Capability` · `PluginStatus` · `PluginHealth` · `PluginContext` · `PrincipalContext` · `TenantContext` · `BaseRepository[T]` · `BaseProducer[T]` · `BaseConsumer[T]` |
 | [inbound](inbound.md) | `openframe.core.inbound` | `UseCase[TIn, TOut]` · `CommandHandler[TIn]` · `QueryHandler[TIn, TOut]` · `RequestContext` |
 | [telemetry](telemetry.md) | `openframe.core.telemetry` | `setup_telemetry` · `get_tracer` · `get_meter` · `record_lifecycle_event` · `record_error` |
 | [tracing](tracing.md) | `openframe.core.tracing` | `TracingProxy` |
@@ -16,5 +15,5 @@
 | [runtime](runtime.md) | `openframe.core.runtime` | `ApplicationBootstrap` |
 | [testing](testing.md) | `openframe.core.testing` | `InMemoryRepository` · `FakeProducer` · `FakeConsumer` · contract test base classes |
 
-!!! note "health module removed in v3.0.0"
-    The `openframe.core.health` module and `HealthCheck` protocol were removed in v3.0.0. Health is now part of the unified `Lifecycle` contract in `openframe.core.contracts` (`Lifecycle.health() -> PluginHealth`). See the [contracts module](contracts.md) and [ADR-006](../../technical/architecture/adrs/adr-006-unified-port-lifecycle.md).
+!!! note "health module removed in v3.0.0; contracts merged into ports in v3.1.0"
+    The `openframe.core.health` module and `HealthCheck` protocol were removed in v3.0.0. Health is now part of the unified `Lifecycle` contract in `openframe.core.ports` (`Lifecycle.health() -> PluginHealth`). In v3.1.0, `openframe.core.contracts` was merged into `openframe.core.ports`, and the outbound protocols (`BaseRepository`, `BaseProducer`, `BaseConsumer`) moved into an internal `ports/outbound/` sub-module mirroring `openframe.core.inbound` on the driving side — the public import path (`from openframe.core.ports import ...`) is unaffected. No compatibility shim exists at the old `openframe.core.contracts` path. See the [ports module](ports.md) and [ADR-006](../../technical/architecture/adrs/adr-006-unified-port-lifecycle.md).

{openframe_core-3.0.1 → openframe_core-3.2.0}/docs/code/modules/plugins.md

@@ -10,7 +10,7 @@
 
 ```python
 from openframe.core.plugins import PluginRegistry
-from openframe.core.contracts import Capability
+from openframe.core.ports import Capability
 ```
 
 ---
@@ -119,7 +119,7 @@ Return all registered ports for the given `Capability`. Returns an empty list wh
 
 ```python
 from openframe.core.plugins import PluginRegistry
-from openframe.core.contracts import Capability
+from openframe.core.ports import Capability
 
 registry = PluginRegistry()
 
@@ -154,7 +154,7 @@ primary, replica = registry.get_all(Capability.PERSISTENCE)
 
 ```python
 from openframe.core.runtime import ApplicationBootstrap
-from openframe.core.contracts import Capability
+from openframe.core.ports import Capability
 
 class MyApp(ApplicationBootstrap):
     def configure(self) -> None: