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

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

@@ -9,17 +9,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Watch items (architectural)
+---
 
-- **Three application wiring options** — `deps.py` + `lru_cache`,
-  `PluginRegistry` direct, and `ApplicationBootstrap` now coexist without a
-  documented hierarchy. The ambiguity is better-named than before but still
-  unresolved. The next documentation pass must establish `ApplicationBootstrap`
-  as the default starting point and frame the other two as explicit alternatives
-  with stated conditions. Tracked in the roadmap.
+## v3.4.0 — 2026-09-28
 
 ### Added
 
+- **`openframe.core.resilience.CircuitBreakerProxy`** (new module,
+  experimental) — zero-code async circuit breaker. Wraps any object and
+  short-circuits its async methods after `failure_threshold` consecutive
+  failures, raising `AdapterConnectionError` ("circuit open", retryable)
+  immediately instead of letting every caller block until
+  `operation_timeout` on every single call during a sustained outage.
+  Standard closed → open → half-open → closed/open state machine.
+  Mirrors `TracingProxy`'s exact wrapping mechanism (`__getattr__`
+  interception, fresh `getattr` resolution of the wrapped method on every
+  call, sync methods pass through unwrapped) so the two proxies compose
+  predictably — see the module docstring for the recommended composition
+  order (`CircuitBreakerProxy(TracingProxy(repo, ...), ...)`, not the
+  reverse, so a short-circuited call never produces a misleading adapter
+  span). Addresses a real gap: none of the four `openframe-adapters`
+  packages (or anything else in the ecosystem) previously had any
+  resilience pattern beyond "block until timeout, then raise."
+
+### Changed
+
+- **Graduated `PluginRegistry` and `ApplicationBootstrap` from `experimental`
+  to `stable`** (`openframe.core.plugins.registry`, `openframe.core.runtime.bootstrap`,
+  and their respective package `__init__.py` re-exports). Graduation
+  criteria: (1) all 7 `openframe-local-validation-framework` services
+  already depend on both in production-shaped code across multiple
+  releases with no breaking change required of them; (2) v3.3.0's
+  `ApplicationBootstrap.compose()`/`get_all()`/`registry` additions landed
+  as pure additive extensions on top of the existing contract — no
+  breaking change was needed to add meaningful new functionality, which is
+  itself evidence the contract shape is right. This is the first module in
+  `openframe-core` to graduate via an explicit, written criteria set
+  (documented in each module's own docstring) rather than an unstated
+  judgment call — future modules going through the same
+  experimental→stable path should record their own criteria the same way.
+
+---
+
+## v3.3.0 — 2026-09-28
+
+### Added
+
+- **`ApplicationBootstrap.compose(*ports)`, `.get_all()`, `.registry`** —
+  resolves the long-standing "three wiring options" ambiguity (previously
+  tracked here as an architectural watch item and in the roadmap) by
+  consolidating to one recommended class at three levels of ceremony
+  instead of three competing patterns:
+  - `compose(*ports)` (new classmethod) — zero-subclass entry point for a
+    service with one or a few ports and no per-port `config`/`init_timeout`.
+    Registers each port immediately at construction; `configure()` stays
+    the default no-op.
+  - `get_all(capability)` (new method) — mirrors `PluginRegistry.get_all()`,
+    closing the one real gap that previously forced a multi-port-per-capability
+    setup (e.g. primary + replica) off `ApplicationBootstrap` and onto
+    `PluginRegistry` directly.
+  - `registry` (new read-only property) — exposes the underlying
+    `PluginRegistry` for customization neither of the above covers (e.g.
+    `list_plugins()`), without standing up a second, parallel registry.
+
+  `PluginRegistry` direct construction and `deps.py` + `lru_cache` are no
+  longer documented as peer alternatives to `ApplicationBootstrap` — see
+  `docs/technical/architecture/design-decisions.md` and
+  `docs/developer-guide/how-it-works.md`'s new "Choosing a Wiring Pattern"
+  section for the full resolution.
+
+- **`PluginRegistry`/`ApplicationBootstrap` per-port init timeout** —
+  `PluginRegistry(default_init_timeout=...)` and
+  `PluginRegistry.register(..., init_timeout=...)` (mirrored on
+  `ApplicationBootstrap`'s constructor and `register()`) bound how long
+  `initialize_all()` waits for a single port's `initialize()` before
+  giving up. Both default to `None` (no timeout), preserving prior
+  behaviour exactly for callers who don't opt in. Addresses a real
+  production risk: previously, one adapter's `initialize()` hanging
+  (e.g. a TCP connection that completes the handshake but never
+  responds) would block application startup indefinitely with no way
+  to bound it. A timeout surfaces as a plain `TimeoutError` and is
+  handled identically to any other `initialize()` failure — already-
+  initialized ports are rolled back (LIFO) before it propagates.
+
 - **`openframe.core.telemetry.shutdown_telemetry()`** — flushes and shuts
   down the OTel SDK, ensuring the `BatchSpanProcessor` exports all buffered
   spans before process exit. Idempotent, never raises, resets `_INITIALISED`
@@ -37,6 +109,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+#### Code
+
+- `TracingProxy` (`tracing/proxy.py`) — replaced the deprecated
+  `asyncio.iscoroutinefunction()` sync/async probe with
+  `inspect.iscoroutinefunction()`. `asyncio.iscoroutinefunction` is
+  slated for removal in Python 3.16; this was the only deprecation
+  warning in the test suite.
+- `AmbiguousCapabilityError` (`exceptions/plugin.py`) — its `capability`
+  and `matches` constructor arguments are now also mirrored into
+  `self.context`, matching the pattern every other `AdapterError`/
+  `PluginError` subclass already follows (e.g. `AdapterError` mirrors
+  `adapter`/`operation` into `context`). Previously these two fields
+  were set as plain attributes but silently absent from `context`.
+
+#### Documentation
+
+- Corrected `PluginStatus` across `docs/technical/overview/glossary.md`,
+  `docs/code/modules/ports.md`, `docs/code/modules/health.md`, and four
+  operational runbooks — several described a `READY`/`DEGRADED`/
+  `UNAVAILABLE` enum that has never existed in source. The actual enum
+  (`ports/health.py`) is `DISCOVERED`/`REGISTERED`/`CONFIGURED`/
+  `INITIALIZED`/`READY`/`STOPPING`/`STOPPED`/`FAILED`; a failed health
+  check reports `FAILED`, with finer detail carried in
+  `PluginHealth.message`/`.details`, not a dedicated status value.
+- Corrected the `PluginContext`, `PrincipalContext`, and `TenantContext`
+  examples in `docs/code/modules/ports.md` — the shown `PluginContext`
+  was missing the required `plugin_name` field entirely and typed
+  `config` as `dict` instead of `Mapping`; `PrincipalContext`/
+  `TenantContext` showed fields (`attributes`, `roles: frozenset[str]`)
+  that don't exist on the real dataclasses (`claims`,
+  `roles: tuple[str, ...]`, `name: str`).
+- Added [ADR-007](../docs/technical/architecture/adrs/adr-007-schema-contracts.md)
+  documenting the `openframe.core.schemas` `@contract` marker shipped in
+  v3.2.1 — the module's own docstring already cited "ADR-007" before
+  this record existed.
+- Corrected `docs/code/modules/plugins.md` and `docs/code/modules/runtime.md`,
+  both stale independently of the init-timeout addition above:
+  `initialize_all()` was documented as taking `principal`/`tenant`
+  parameters directly (they're actually set separately via
+  `PluginRegistry.set_context()`, undocumented until now); `ApplicationBootstrap`
+  was documented as having a `get_all()` method that did not exist on
+  that class at the time (only on `PluginRegistry` itself) — since
+  resolved by actually adding `get_all()` to `ApplicationBootstrap`, see
+  the wiring-consolidation entry above; `ApplicationBootstrap.health()`
+  — a real method — was undocumented entirely; and `start()`/`initialize_all()`
+  were both documented as raising a wrapped `PluginInitializationError`,
+  when in fact the registry re-raises whatever `initialize()` raised
+  (or a plain `TimeoutError`) completely unwrapped.
+- Corrected `docs/developer-guide/debugging.md`'s "PluginRegistry Failures"
+  section, which repeated the same `PluginInitializationError` inaccuracy
+  above, and additionally claimed `get()` raises `PluginNotFoundError` for
+  a missing capability — it actually raises a plain `KeyError`.
+  `PluginNotFoundError` and `PluginInitializationError` both exist in the
+  public exception hierarchy (`openframe.core.exceptions`) but neither is
+  currently raised anywhere in `openframe-core`'s own source — flagged as
+  a roadmap item (dead-code exception classes), not fixed here, since
+  making them actually get raised would be a behavioral change.
+
 #### CI/CD
 
 - Upgraded all GitHub Actions to Node.js 24-compatible versions, resolving
@@ -295,6 +425,11 @@ Dev dependencies: `pytest>=8.0`, `pytest-asyncio>=0.23`, `httpx>=0.27`.
 
 ---
 
-[Unreleased]: https://github.com/openframe-org/openframe-core/compare/v3.0.0...HEAD
+[Unreleased]: https://github.com/openframe-org/openframe-core/compare/v3.4.0...HEAD
+[3.4.0]: https://github.com/openframe-org/openframe-core/compare/v3.3.0...v3.4.0
+[3.3.0]: https://github.com/openframe-org/openframe-core/compare/v3.2.1...v3.3.0
+[3.2.1]: https://github.com/openframe-org/openframe-core/compare/v3.2.0...v3.2.1
+[3.2.0]: https://github.com/openframe-org/openframe-core/compare/v3.1.0...v3.2.0
+[3.1.0]: https://github.com/openframe-org/openframe-core/compare/v3.0.0...v3.1.0
 [3.0.0]: https://github.com/openframe-org/openframe-core/compare/v1.0.0...v3.0.0
 [1.0.0]: https://github.com/openframe-org/openframe-core/releases/tag/v1.0.0

{openframe_core-3.2.1 → openframe_core-3.4.0}/.gitignore

@@ -219,3 +219,4 @@ __marimo__/
 
 # Miscellaneous Files
 .DS_Store
+.claude/

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: openframe-core
-Version: 3.2.1
+Version: 3.4.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/

{openframe_core-3.2.1 → openframe_core-3.4.0}/docs/code/modules/health.md

@@ -11,7 +11,7 @@ async def health(self) -> PluginHealth:
         return PluginHealth(status=PluginStatus.READY)
     except Exception as exc:
         return PluginHealth(
-            status=PluginStatus.UNAVAILABLE,
+            status=PluginStatus.FAILED,
             message=str(exc),
         )
 ```
@@ -28,9 +28,10 @@ PluginHealth(
     details={"ping_ms": 2.1, "schema_ok": True},
 )
 
-# Degraded
+# Degraded but still serving — no separate status exists; encode the
+# nuance in message/details while status stays READY
 PluginHealth(
-    status=PluginStatus.DEGRADED,
+    status=PluginStatus.READY,
     message="replica lag 5s",
     details={"lag_s": 5},
 )

{openframe_core-3.2.1 → openframe_core-3.4.0}/docs/code/modules/plugins.md

@@ -21,18 +21,25 @@ from openframe.core.ports import Capability
 
 ```python
 class PluginRegistry:
+    def __init__(self, *, default_init_timeout: float | None = None) -> None: ...
+
     def register(
         self,
-        port: BasePort,
-        config: dict[str, Any] | None = None,
+        plugin: BasePort,
+        *,
+        config: Mapping[str, Any] | None = None,
+        init_timeout: float | None = None,
     ) -> None: ...
 
-    async def initialize_all(
+    def set_context(
         self,
+        *,
         principal: PrincipalContext | None = None,
         tenant: TenantContext | None = None,
     ) -> None: ...
 
+    async def initialize_all(self) -> None: ...
+
     async def shutdown_all(self) -> None: ...
 
     def get(self, capability: Capability) -> BasePort: ...
@@ -42,33 +49,40 @@ class PluginRegistry:
 
 ---
 
-#### `register(port, config)`
+#### `register(plugin, config, init_timeout)`
 
-Register a `BasePort` with optional config. The config dict is passed into `PluginContext.config` when `initialize_all()` is called.
+Register a `BasePort` with optional config and an optional per-port init timeout. The config mapping is passed into `PluginContext.config` when `initialize_all()` is called.
 
 **Parameters:**
 
 | Name | Type | Default | Description |
 |---|---|---|---|
-| `port` | `BasePort` | — | Any `BasePort` instance (including `BaseRepository`, `BaseProducer`, `BaseConsumer`) |
-| `config` | `dict[str, Any] \| None` | `None` | Port-specific configuration dict, e.g. `{"dsn": "postgres://..."}` |
+| `plugin` | `BasePort` | — | Any `BasePort` instance (including `BaseRepository`, `BaseProducer`, `BaseConsumer`) |
+| `config` | `Mapping[str, Any] \| None` | `None` | Port-specific configuration, e.g. `{"dsn": "postgres://..."}` |
+| `init_timeout` | `float \| None` | `None` | Seconds to wait for this port's `initialize()` in `initialize_all()`, overriding the registry's `default_init_timeout` for this port only. `None` falls back to that default (which is itself `None` — no timeout — unless set on the constructor) |
 
-**Raises:** `DuplicatePluginError` — if the same port instance is registered more than once.
+**Raises:** `TypeError` (object doesn't satisfy `BasePort`) · `DuplicatePluginError` — if a port with this name is already registered.
 
 ---
 
-#### `initialize_all(principal, tenant)`
+#### `set_context(principal, tenant)`
 
-Call `port.initialize(PluginContext)` on every registered port in registration order. Rolls back (shuts down already-initialised ports) if any port raises.
+Set the `principal`/`tenant` threaded through every port's `PluginContext` in `initialize_all()`. Call before `initialize_all()`, typically right after all `register()` calls.
 
 **Parameters:**
 
 | Name | Type | Default | Description |
 |---|---|---|---|
-| `principal` | `PrincipalContext \| None` | `None` | Optional caller identity threaded into `PluginContext` |
-| `tenant` | `TenantContext \| None` | `None` | Optional tenant identity threaded into `PluginContext` |
+| `principal` | `PrincipalContext \| None` | `None` | Optional caller identity threaded into every port's `PluginContext` |
+| `tenant` | `TenantContext \| None` | `None` | Optional tenant identity threaded into every port's `PluginContext` |
+
+---
+
+#### `initialize_all()`
+
+Call `port.initialize(PluginContext)` on every registered port in registration order. Each port's config comes from its own `register()` call; `principal`/`tenant` come from `set_context()` (both default to `None` if never set). Each call is bounded by that port's `init_timeout` (or the registry's `default_init_timeout` if the port didn't specify one) — unbounded by default. Rolls back (shuts down already-initialised ports, in reverse order) if any port raises or times out, then re-raises.
 
-**Raises:** `PluginInitializationError` — wrapping the original exception from `port.initialize()`, after rolling back.
+**Raises:** The exception raised by the failing port's `initialize()` — or a plain `TimeoutError` if its timeout elapsed first. Neither is wrapped into a `PluginError` subclass; the registry re-raises whatever `initialize()` raised (or `TimeoutError`) unchanged, after rollback.
 
 ---
 

{openframe_core-3.2.1 → openframe_core-3.4.0}/docs/code/modules/ports.md

@@ -79,7 +79,7 @@ Called by `PluginRegistry.shutdown_all()` in LIFO order. Should flush, close con
 
 #### `health()`
 
-Return a liveness/readiness snapshot. Must never raise — return `PluginHealth(status=PluginStatus.UNAVAILABLE, message=...)` on any failure.
+Return a liveness/readiness snapshot. Must never raise — return `PluginHealth(status=PluginStatus.FAILED, message=...)` on any failure.
 
 **Returns:** `PluginHealth`
 
@@ -144,12 +144,19 @@ See [capability-taxonomy.md](../../technical/architecture/capability-taxonomy.md
 ### `PluginStatus`
 
 ```python
-class PluginStatus(str, Enum):
-    READY       = "ready"
-    DEGRADED    = "degraded"
-    UNAVAILABLE = "unavailable"
+class PluginStatus(Enum):
+    DISCOVERED  = auto()
+    REGISTERED  = auto()
+    CONFIGURED  = auto()
+    INITIALIZED = auto()
+    READY       = auto()
+    STOPPING    = auto()
+    STOPPED     = auto()
+    FAILED      = auto()
 ```
 
+Lifecycle status values a port/plugin transitions through during application startup and shutdown; the registry tracks the last known state. There is no separate "degraded" or "unavailable" member — a health check that cannot confirm full health reports `FAILED` and encodes the nuance in `PluginHealth.message`/`.details`.
+
 ---
 
 ### `PluginHealth`
@@ -158,11 +165,11 @@ class PluginStatus(str, Enum):
 @dataclass(frozen=True)
 class PluginHealth:
     status: PluginStatus
-    message: str | None = None
+    message: str = ""
     details: dict[str, Any] = field(default_factory=dict)
 ```
 
-Returned by `Lifecycle.health()`. Carries a status, an optional human-readable message, and optional structured detail (e.g. latency, schema checks).
+Returned by `Lifecycle.health()`. Carries a status, a human-readable message (empty string by default, not `None`), and optional structured detail (e.g. latency, schema checks). Frozen — safe to cache and pass across coroutines.
 
 ```python
 # Minimal
@@ -174,12 +181,16 @@ PluginHealth(
     details={"ping_ms": 2.1, "schema_ok": True},
 )
 
-# Degraded
+# Degraded but still serving — no separate status exists; encode the
+# nuance in message/details while status stays READY
 PluginHealth(
-    status=PluginStatus.DEGRADED,
+    status=PluginStatus.READY,
     message="replica lag 5s",
     details={"lag_s": 5},
 )
+
+# Failed
+PluginHealth(status=PluginStatus.FAILED, message=str(exc))
 ```
 
 ---
@@ -189,12 +200,13 @@ PluginHealth(
 ```python
 @dataclass(frozen=True)
 class PluginContext:
-    config: dict[str, Any] = field(default_factory=dict)
+    config: Mapping[str, Any]
+    plugin_name: str
     principal: PrincipalContext | None = None
     tenant: TenantContext | None = None
 ```
 
-Passed to `Lifecycle.initialize()` by `PluginRegistry.initialize_all()`. Carries the port's config dict plus optional identity/tenancy context.
+Passed to `Lifecycle.initialize()` by `PluginRegistry.initialize_all()`. Carries the port's own validated config (a read-only mapping — an empty one when no config was registered for this port), the port's registered `name`, and optional identity/tenancy context. Intentionally narrow on cross-port dependencies — a port cannot look up other ports from this context; the registry must order registrations so dependency ports initialize first.
 
 ---
 
@@ -204,11 +216,11 @@ Passed to `Lifecycle.initialize()` by `PluginRegistry.initialize_all()`. Carries
 @dataclass(frozen=True)
 class PrincipalContext:
     principal_id: str
-    roles: frozenset[str] = field(default_factory=frozenset)
-    attributes: dict[str, Any] = field(default_factory=dict)
+    roles: tuple[str, ...] = ()
+    claims: dict[str, object] = field(default_factory=dict)
 ```
 
-Frozen dataclass carrying caller identity. Threaded through both `PluginContext` (outbound init) and `RequestContext` (inbound requests).
+Frozen dataclass carrying caller identity (user, service account, API key). `roles` is empty when the caller has no roles or role information is unavailable; `claims` carries additional verified claims from the auth token/session (e.g. `{"email": "...", "org": "..."}`). Threaded through both `PluginContext` (outbound init) and `RequestContext` (inbound requests).
 
 ---
 
@@ -218,10 +230,10 @@ Frozen dataclass carrying caller identity. Threaded through both `PluginContext`
 @dataclass(frozen=True)
 class TenantContext:
     tenant_id: str
-    attributes: dict[str, Any] = field(default_factory=dict)
+    name: str = ""
 ```
 
-Frozen dataclass carrying tenant identity. Threaded through both `PluginContext` and `RequestContext`.
+Frozen dataclass carrying tenant identity — `name` is empty when only the identifier is known. Threaded through both `PluginContext` and `RequestContext`.
 
 ---
 
@@ -415,7 +427,7 @@ class PostgresItemRepository:
             await self._pool.fetchval("SELECT 1")
             return PluginHealth(status=PluginStatus.READY)
         except Exception as exc:
-            return PluginHealth(status=PluginStatus.UNAVAILABLE, message=str(exc))
+            return PluginHealth(status=PluginStatus.FAILED, message=str(exc))
 
     # Domain methods
     async def get(self, entity_id: str) -> Item | None: ...

openframe_core-3.4.0/docs/code/modules/runtime.md

@@ -0,0 +1,170 @@
+# runtime
+
+`openframe/core/runtime/` · The recommended composition root, at three levels of ceremony.
+
+---
+
+## Overview
+
+`ApplicationBootstrap` is the single recommended composition root for application code — not one of several competing wiring patterns. It manages `PluginRegistry` registration and lifecycle for you, as an async context manager: `__aenter__` calls `start()` (which calls `configure()` then `initialize_all()`), and `__aexit__` calls `stop()` (which calls `shutdown_all()` then `shutdown_telemetry()`).
+
+It's used at three levels of ceremony, not three separate patterns — see [Choosing a Wiring Pattern](../../developer-guide/how-it-works.md#choosing-a-wiring-pattern) for the full guide:
+
+1. `ApplicationBootstrap.compose(*ports)` — no subclass, for one or a few ports.
+2. Subclass + `configure()` — for per-port `config`/`init_timeout` or conditional registration.
+3. `bootstrap.registry` — the escape hatch to the underlying `PluginRegistry` for what tiers 1-2 don't cover.
+
+```python
+from openframe.core.runtime import ApplicationBootstrap
+```
+
+---
+
+## Classes
+
+### `ApplicationBootstrap`
+
+```python
+class ApplicationBootstrap:
+    def __init__(self, *, default_init_timeout: float | None = None) -> None: ...
+    def configure(self) -> None: ...
+    def register(
+        self,
+        plugin: BasePort,
+        *,
+        config: Mapping[str, Any] | None = None,
+        init_timeout: float | None = None,
+    ) -> None: ...
+    def get(self, capability: Capability) -> BasePort: ...
+    def get_all(self, capability: Capability) -> list[BasePort]: ...
+    @property
+    def registry(self) -> PluginRegistry: ...
+    @classmethod
+    def compose(cls, *ports: BasePort) -> "ApplicationBootstrap": ...
+    async def start(self) -> None: ...
+    async def stop(self) -> None: ...
+    async def health(self) -> dict[str, PluginHealth]: ...
+
+    async def __aenter__(self) -> "ApplicationBootstrap": ...
+    async def __aexit__(self, *args: object) -> None: ...
+```
+
+---
+
+#### `compose(*ports)` — classmethod
+
+The zero-ceremony entry point. Builds an `ApplicationBootstrap` and registers each given port, in order, with no subclass. Covers the common case: settings are usually supplied at a port's own construction (e.g. `PostgresRepository(settings)`), not threaded through `PluginContext.config` — none of the four real `openframe-adapters` packages (Postgres, Mongo, Redis, Kafka) actually read `PluginContext.config` at all. Use a subclass with `configure()` instead once a port needs `config=`, `init_timeout=`, or registration order that depends on a runtime condition.
+
+```python
+async with ApplicationBootstrap.compose(PostgresRepository(settings)) as app:
+    repo = app.get(Capability.PERSISTENCE)
+```
+
+---
+
+#### `configure()`
+
+Override this method to register ports. Called by `start()` before `initialize_all()`. The default implementation is a no-op — `compose()` never overrides it; it registers ports immediately at construction instead.
+
+```python
+class MyApp(ApplicationBootstrap):
+    def configure(self) -> None:
+        self.register(PostgresItemRepository(), config={"dsn": "postgres://..."})
+        self.register(RedisCache(), config={"url": "redis://..."})
+```
+
+---
+
+#### `start()`
+
+Call `configure()` then `registry.initialize_all()`. If any port's `initialize()` raises (or its `init_timeout` elapses first), that exception propagates **unwrapped** after already-initialized ports are rolled back — `start()` does not wrap it into a `PluginInitializationError` (that class is currently unused anywhere in `openframe-core`).
+
+---
+
+#### `stop()`
+
+Call `registry.shutdown_all()`, then flush and shut down the OTel SDK via `shutdown_telemetry()`. Never raises — port and telemetry errors are both logged and shutdown continues.
+
+---
+
+#### `register(plugin, config, init_timeout)`
+
+Delegate to `registry.register()`. Raises `TypeError` if the object doesn't satisfy `BasePort`, or `DuplicatePluginError` if a port with this name is already registered. `init_timeout` overrides the bootstrap's own `default_init_timeout` (set on `__init__`) for this one port; `None` (the default) falls back to it.
+
+---
+
+#### `get(capability)`
+
+Delegate to `registry.get()` — strict, raises `AmbiguousCapabilityError` on >1 match. Only valid after `start()` has completed.
+
+---
+
+#### `get_all(capability)`
+
+Delegate to `registry.get_all()` — the escape hatch for the deliberate multi-port-per-capability case (e.g. primary + replica) that `get()`'s strictness rejects. Returns an empty list, never raises, when nothing matches.
+
+---
+
+#### `registry` — property
+
+The underlying `PluginRegistry` instance. For customization neither `compose()` nor a `configure()` subclass covers (e.g. `list_plugins()`), without standing up a second, parallel registry outside `ApplicationBootstrap`.
+
+---
+
+#### `health()`
+
+Delegate to `registry.health_all()` — a live health snapshot (dict of port name → `PluginHealth`) for every registered port.
+
+---
+
+## Usage Patterns
+
+### Zero-ceremony — one or a few ports
+
+```python
+from openframe.core.runtime import ApplicationBootstrap
+from openframe.core.ports import Capability
+
+async with ApplicationBootstrap.compose(PostgresItemRepository()) as bootstrap:
+    repo = bootstrap.get(Capability.PERSISTENCE)
+    await serve(ItemService(repo))
+```
+
+### Subclass — per-port config, or conditional registration
+
+```python
+class MyServiceBootstrap(ApplicationBootstrap):
+    def configure(self) -> None:
+        self.register(PostgresItemRepository(), config={"dsn": "..."})
+
+async with MyServiceBootstrap() as bootstrap:
+    repo = bootstrap.get(Capability.PERSISTENCE)
+    await serve(ItemService(repo))
+    # shutdown_all() then shutdown_telemetry() called automatically on __aexit__
+```
+
+### As a FastAPI lifespan
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+bootstrap = ApplicationBootstrap.compose(PostgresItemRepository())
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    setup_telemetry()
+    await bootstrap.start()
+    yield
+    await bootstrap.stop()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+### The registry escape hatch — multi-port-per-capability
+
+```python
+async with ApplicationBootstrap.compose(PrimaryPostgres(), ReplicaPostgres()) as bootstrap:
+    primary, replica = bootstrap.get_all(Capability.PERSISTENCE)
+    # or, equivalently: bootstrap.registry.get_all(Capability.PERSISTENCE)
+```

{openframe_core-3.2.1 → openframe_core-3.4.0}/docs/developer-guide/debugging.md

@@ -45,22 +45,25 @@ except OpenFrameError:
 
 ---
 
-## PluginRegistry Failures
+## PluginRegistry / ApplicationBootstrap Failures
 
-**`PluginNotFoundError`** — no port registered for the requested `Capability`. Verify `registry.register(port)` was called before `registry.get(Capability.X)`.
+These apply identically whether you're using `PluginRegistry` directly or through `ApplicationBootstrap` (`app.get(...)`, `app.start()`) — the bootstrap delegates straight through.
 
-**`AmbiguousCapabilityError`** — more than one port registered for the capability passed to `get()`. Use `registry.get_all(Capability.X)` if multiple same-capability ports is intentional.
+**`KeyError`** — no port registered for the requested `Capability`. Verify `register(port)` was called before `get(Capability.X)`. (Note: despite the exception hierarchy also defining a `PluginNotFoundError`, `get()` actually raises a plain `KeyError` — not that class.)
 
-**`PluginInitializationError`** — a port's `initialize()` raised. The registry rolls back already-initialised ports before re-raising. Check the `cause` for the original error.
+**`AmbiguousCapabilityError`** — more than one port registered for the capability passed to `get()`. Use `get_all(Capability.X)` if multiple same-capability ports is intentional (`ApplicationBootstrap.get_all()` or `registry.get_all()`).
+
+**Whatever `initialize()` raised** — `initialize_all()` does **not** wrap a failing port's exception into a `PluginInitializationError` (that class exists in the exception hierarchy but nothing in `openframe-core` currently raises it). It rolls back already-initialised ports (LIFO) and then re-raises the original exception from `initialize()` completely unchanged — catch whatever your adapter actually raises, or `OpenFrameError` for the ecosystem-wide catch point if your adapters follow that convention:
 
 ```python
-from openframe.core.exceptions import PluginInitializationError
+from openframe.core.exceptions import OpenFrameError
 
 try:
-    await registry.initialize_all()
-except PluginInitializationError as exc:
-    print(exc.plugin_name)   # which port failed
-    print(exc.cause)         # original exception from initialize()
+    await app.start()   # or: await registry.initialize_all()
+except OpenFrameError as exc:
+    print(exc.code, exc.retryable)   # whatever the failing port's initialize() raised
+except TimeoutError:
+    print("a port's init_timeout elapsed — see PluginRegistry(default_init_timeout=...)")
 ```
 
 ---

{openframe_core-3.2.1 → openframe_core-3.4.0}/docs/developer-guide/explore.md

@@ -90,6 +90,8 @@ print(isinstance(exc, OpenFrameError))   # True — single catch point for the e
 
 ## Explore PluginRegistry
 
+`PluginRegistry` is the underlying mechanism — useful to poke at directly here to see how it works. In application code, use `ApplicationBootstrap` instead (`ApplicationBootstrap.compose(*ports)` for the common case) — see [How It Works § Choosing a Wiring Pattern](how-it-works.md#choosing-a-wiring-pattern).
+
 ```python
 import asyncio
 from openframe.core.ports import Capability