From b80a10bb5cc773485166bd5b157631c2c0a222b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Contreras=20Guill=C3=A9n?=
 <ancongui@Andress-MacBook-Pro.local>
Date: Sun, 31 May 2026 19:34:06 +0200
Subject: [PATCH] fix: framework-wide hardening pass (v26.05.06)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A deep audit surfaced a class of silent wiring gaps and correctness bugs —
features that existed but were never connected to the runtime path, so the
suite passed while behaviour was broken. This fixes them. 3146 tests pass;
ruff / ruff-format / mypy --strict all green. See CHANGELOG.md for the full list.

Admin dashboard
- traces are recorded (TraceCollectorFilter now joins the filter chain)
- SSE streams instead of buffering (fixed all Server-Sent Events framework-wide)
- server info resolves lazily (was "unknown")

Dependency injection & AOP
- same-type @bean methods no longer collapse; list[T] returns every bean
- AOP woven regardless of registration order (two-pass post-processing)
- weaving/scheduling/wiring scans no longer trigger @property getters at startup
- RequestContextFilter wired by default (REQUEST scope + @pre/@post_authorize)

Web
- RequestLoggingFilter no longer crashes without structlog (pyfly.logging.get_logger)
- FastAPI adapter: correct OpenAPI generation + @controller_advice handlers
- /actuator health rescan now runs; /actuator/prometheus returns text format

Transactional engine
- workflow @compensation_step executes on failure (reverse-order rollback)
- REST controllers (orchestration/dlq/workflow) are mounted
- saga compensator records outcomes; recovery TypeError fixed
- workflow @wait_for_all/@wait_for_any timeouts honoured; child correlation id

CQRS / EDA / messaging / scheduling
- query cache + domain-event publishing wired
- EDA circuit breaker no longer stuck OPEN
- Kafka/RabbitMQ subscribe-after-start; scheduler fixed_delay survives errors

Data / config / eventsourcing / notifications / callbacks
- derived-query stub detection; mongo LIKE wildcards
- Config.bind() placeholders + nested dataclasses; ConfigServer save/fetch
- projection cursor no longer skips failed events; SMTP BCC; HMAC canonical JSON

Docs: CHANGELOG v26.05.06, new docs/modules/logging.md + config-server.md.
Version synced (pyfly.__version__ was stale).

🤖 Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  96 +++++++
 docs/modules/README.md                        |   2 +
 docs/modules/config-server.md                 | 105 ++++++++
 docs/modules/logging.md                       | 106 ++++++++
 pyproject.toml                                |   2 +-
 src/pyfly/__init__.py                         |   2 +-
 src/pyfly/actuator/adapters/starlette.py      |  19 +-
 src/pyfly/admin/auto_configuration.py         |   9 +-
 src/pyfly/admin/providers/server_provider.py  |  31 ++-
 src/pyfly/aop/weaver.py                       |   8 +
 src/pyfly/callbacks/dispatcher.py             |   9 +-
 .../cli/templates/cli/hello_command.py.j2     |   4 +-
 src/pyfly/config_server/backend.py            |  34 ++-
 src/pyfly/container/container.py              |  35 ++-
 src/pyfly/context/application_context.py      | 101 +++----
 src/pyfly/core/config.py                      |  61 +++--
 src/pyfly/cqrs/config/auto_configuration.py   |  33 ++-
 src/pyfly/cqrs/event/publisher.py             |  30 ++-
 .../data/document/mongodb/query_compiler.py   |  15 +-
 src/pyfly/data/post_processor.py              |   8 +
 src/pyfly/eda/adapters/kafka.py               |  11 +-
 src/pyfly/eda/adapters/postgres.py            |  23 +-
 src/pyfly/eda/adapters/redis.py               |  26 +-
 src/pyfly/eda/auto_configuration.py           |   4 +-
 src/pyfly/eda/circuit_breaker.py              |   5 +
 src/pyfly/eventsourcing/projection.py         |   6 +
 src/pyfly/logging/__init__.py                 |  28 +-
 src/pyfly/messaging/adapters/kafka.py         |  44 ++--
 src/pyfly/messaging/adapters/rabbitmq.py      |  49 ++--
 src/pyfly/notifications/providers/smtp.py     |   5 +
 src/pyfly/observability/correlation.py        |  20 +-
 src/pyfly/scheduling/task_scheduler.py        |  14 +-
 src/pyfly/transactional/rest/controllers.py   | 100 +++++--
 .../transactional/saga/engine/compensator.py  |  10 +-
 .../transactional/saga/engine/saga_engine.py  |   6 +-
 .../shared/persistence/memory.py              |  21 +-
 .../workflow/child_workflow_service.py        |  12 +-
 .../transactional/workflow/definition.py      |   2 +
 src/pyfly/transactional/workflow/engine.py    |  14 +
 src/pyfly/transactional/workflow/executor.py  |  91 ++++++-
 src/pyfly/transactional/workflow/registry.py  |   2 +
 src/pyfly/web/adapters/fastapi/app.py         | 112 +++++---
 src/pyfly/web/adapters/fastapi/controller.py  |  54 +++-
 src/pyfly/web/adapters/starlette/app.py       |  90 ++++---
 .../web/adapters/starlette/filter_chain.py    |  54 +++-
 .../adapters/starlette/filters/__init__.py    |   2 +
 .../filters/request_logging_filter.py         |   9 +-
 .../web/adapters/starlette/request_logger.py  |   8 +-
 src/pyfly/web/adapters/starlette/resolver.py  |  23 +-
 src/pyfly/web/mappings.py                     |  14 +-
 tests/actuator/test_health_rescan.py          |  55 ++++
 tests/admin/test_admin_create_app_wiring.py   | 103 ++++++++
 tests/aop/test_property_and_ordering.py       |  94 +++++++
 tests/callbacks/test_callbacks.py             |  19 +-
 tests/config/test_bind_placeholders_nested.py |  70 +++++
 tests/config_server/test_config_server.py     |  20 ++
 tests/container/test_same_type_beans.py       |  74 ++++++
 tests/cqrs/test_auto_configuration_wiring.py  |  37 +++
 tests/cqrs/test_event_publishing_wiring.py    | 199 ++++++++++++++
 tests/eda/test_auto_configuration.py          |  48 ++--
 tests/eda/test_circuit_breaker.py             |  61 +++++
 tests/eda/test_postgres_event_bus.py          |  10 +-
 tests/logging/test_get_logger.py              |  52 ++++
 tests/observability/test_correlation.py       |  17 +-
 tests/transactional/saga/test_recovery.py     |  24 ++
 .../test_rest_controllers_mounting.py         | 121 +++++++++
 .../workflow/test_compensation.py             | 247 ++++++++++++++++++
 tests/transactional/workflow/test_engine.py   |  28 ++
 tests/transactional/workflow/test_registry.py |  22 ++
 tests/web/test_fastapi_adapter.py             |  78 +++++-
 tests/web/test_filter_chain.py                |  90 +++++++
 uv.lock                                       |   2 +-
 72 files changed, 2683 insertions(+), 357 deletions(-)
 create mode 100644 docs/modules/config-server.md
 create mode 100644 docs/modules/logging.md
 create mode 100644 tests/actuator/test_health_rescan.py
 create mode 100644 tests/admin/test_admin_create_app_wiring.py
 create mode 100644 tests/aop/test_property_and_ordering.py
 create mode 100644 tests/config/test_bind_placeholders_nested.py
 create mode 100644 tests/container/test_same_type_beans.py
 create mode 100644 tests/cqrs/test_auto_configuration_wiring.py
 create mode 100644 tests/cqrs/test_event_publishing_wiring.py
 create mode 100644 tests/eda/test_circuit_breaker.py
 create mode 100644 tests/logging/test_get_logger.py
 create mode 100644 tests/transactional/test_rest_controllers_mounting.py
 create mode 100644 tests/transactional/workflow/test_compensation.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ad6d239..935d97d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,102 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## v26.05.06 (2026-05-31)
+
+### Hardening pass — framework-wide bug fixes
+
+A deep audit of the whole framework surfaced a class of *silent wiring gaps*
+and correctness bugs — features that existed but were never connected to the
+runtime path, so the test suite passed while the behaviour was broken. This
+release fixes them. The full test suite passes and CI (`ruff`, `ruff format`,
+`mypy --strict`) is green.
+
+#### Admin dashboard
+
+- **HTTP traces are now recorded.** The `TraceCollectorFilter` was resolved
+  from the DI container at `create_app()` time — before beans are instantiated —
+  so it was always `None` and never joined the request filter chain. It is now
+  created and owned by `create_app` and wired into the chain; `/admin/api/traces`
+  and the SSE trace stream show real traffic.
+- **Live updates (SSE) now stream.** `WebFilterChainMiddleware` buffered the
+  *entire* response body before returning, which hung every infinite SSE stream
+  (this broke **all** Server-Sent Events framework-wide, not just admin). The
+  filter chain now forwards streaming responses incrementally.
+- **Server info** resolves lazily instead of showing `unknown`.
+
+#### Dependency injection & AOP
+
+- **Same-type beans no longer collapse.** Two `@bean` methods returning the same
+  concrete type overwrote each other in the type-keyed registry and vanished
+  from `list[T]` resolution. All registrations are now tracked and
+  `resolve_all`/`list[T]` returns every bean.
+- **AOP advice is woven regardless of registration order.** Bean post-processing
+  is now two-pass (all `before_init`, then `post_construct`+`after_init`), so a
+  target initialised before its `@aspect` is still advised.
+- **A side-effecting `@property` no longer aborts startup.** Weaving, scheduled-
+  task discovery and every context wiring/lifecycle scan now look attributes up
+  statically (`inspect.getattr_static`) instead of triggering property getters.
+- **`RequestContextFilter` is wired by default**, so `REQUEST`-scoped beans and
+  `@pre_authorize`/`@post_authorize` work out of the box.
+
+#### Web
+
+- `RequestLoggingFilter`/middleware no longer crash on every request when
+  `structlog` is not installed (new `pyfly.logging.get_logger` shim).
+- The FastAPI adapter now generates a correct OpenAPI document for controller
+  routes and honours `@controller_advice` global exception handlers.
+- The health-indicator rescan hook now actually runs after startup, so
+  `/actuator/health` reflects `DOWN` subsystems instead of always reporting `UP`.
+- `/actuator/prometheus` returns the Prometheus text exposition format (was JSON).
+
+#### Transactional engine
+
+- **Workflow `@compensation_step` now executes on failure** — completed
+  compensatable steps are rolled back in reverse order.
+- **Transactional REST controllers** (`/api/orchestration`, `/dlq`, `/workflow`)
+  are now mounted as HTTP routes.
+- The saga compensator records compensation outcomes, so
+  `SagaResult.compensated`/`compensation_result` are populated.
+- Saga stale-recovery no longer raises `TypeError` (`started_at` is persisted as
+  a `datetime`; `get_stale` tolerates ISO strings).
+- Workflow `@wait_for_all`/`@wait_for_any` timeouts are honoured (no unbounded waits).
+- Fire-and-forget child workflows return the real child correlation id.
+
+#### CQRS
+
+- The query cache adapter now receives the `CacheAdapter`, so `@cacheable`
+  queries are actually cached.
+- Domain-event publishing is wired when an EDA/messaging producer bean is
+  present (was a permanent no-op).
+
+#### EDA, messaging & scheduling
+
+- The EDA circuit breaker no longer gets permanently stuck `OPEN`.
+- Kafka/RabbitMQ message-broker adapters handle `@message_listener` subscriptions
+  that arrive after `start()` (they previously never consumed).
+- A scheduled `fixed_delay` task that raises no longer kills its loop.
+
+#### Data, config, event sourcing, notifications, callbacks
+
+- Derived-query stub detection no longer misclassifies documented repository
+  methods as real implementations (SQLAlchemy + MongoDB).
+- MongoDB derived-query `LIKE` wildcards (`%`, `_`) are now translated to regex.
+- `Config.bind()` resolves `${...}` placeholders and binds nested dataclass fields.
+- `ConfigServer` filesystem backend writes back the file `fetch()` reads, so
+  saves are no longer silently shadowed by a stale `.yaml`.
+- The event-sourcing `ProjectionRunner` no longer advances its cursor past a
+  failed event (at-least-once, in-order; was silent data loss).
+- The SMTP notification provider no longer drops BCC recipients.
+- Outbound callback/webhook HMAC signatures are computed over canonical JSON
+  (were computed over `str(dict)` — unverifiable).
+
+#### Internal
+
+- `pyfly.__version__` is back in sync with the packaged version (it was stale).
+- Lint/format/type fixes across the EDA adapters and correlation surface.
+
+---
+
 ## v26.05.05 (2026-05-19)
 
 ### Fixed — `PostgresEventBus` is multi-worker safe
diff --git a/docs/modules/README.md b/docs/modules/README.md
index b3c789a..4536f03 100644
--- a/docs/modules/README.md
+++ b/docs/modules/README.md
@@ -29,6 +29,7 @@ The building blocks that every PyFly application relies on.
 | [Core & Lifecycle](core.md) | Application bootstrap with `@pyfly_application`, startup/shutdown sequence, configuration loading, profile overlays, banner rendering |
 | [Dependency Injection](dependency-injection.md) | `@service`, `@repository`, `@controller`, `@component` stereotypes, constructor injection, `Autowired()`, scopes (singleton, transient, request), `@bean` factories, `@primary`, `Qualifier`, conditional beans, lifecycle hooks |
 | [Configuration](configuration.md) | YAML/TOML config files, `Config` class, profile-specific overlays, `@config_properties` binding, environment variable overrides |
+| [Config Server](config-server.md) | Centralized config server (`ConfigServer`, `ConfigClient`), `ConfigBackend` SPI, in-memory & filesystem backends, Spring-Cloud-Config-compatible responses |
 | [Error Handling](error-handling.md) | 25+ exception types, `ErrorResponse`, `ErrorCategory`, `ErrorSeverity`, HTTP status mapping, structured error responses, `@exception_handler` |
 
 ---
@@ -152,6 +153,7 @@ Monitor, schedule, and observe your applications in production.
 | Guide | What You'll Learn |
 |-------|-------------------|
 | [Observability](observability.md) | `@timed`, `@counted`, `@span`, `MetricsRegistry`, `HealthChecker`, Prometheus metrics export, OpenTelemetry tracing, structured logging with correlation IDs |
+| [Logging](logging.md) | `get_logger`, `LoggingPort`, structlog & stdlib adapters, structured `event + key=value` logging, runtime level control |
 | [Scheduling](scheduling.md) | `@scheduled`, `@async_method`, `CronExpression`, `TaskScheduler`, fixed-rate tasks, fixed-delay tasks, asyncio and thread pool executors |
 
 ---
diff --git a/docs/modules/config-server.md b/docs/modules/config-server.md
new file mode 100644
index 0000000..65356c2
--- /dev/null
+++ b/docs/modules/config-server.md
@@ -0,0 +1,105 @@
+# Config Server Guide
+
+A lightweight, Spring-Cloud-Config-style **centralized configuration server**:
+serve versioned config bundles (keyed by application + profile + label) to many
+client services over HTTP.
+
+---
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [ConfigSource](#configsource)
+3. [Backends](#backends)
+4. [ConfigServer](#configserver)
+5. [ConfigClient](#configclient)
+
+---
+
+## Introduction
+
+The module has three parts:
+
+- **`ConfigBackend`** — the storage SPI (a `Protocol`): `fetch`, `save`, `list`.
+- **`ConfigServer`** — a framework-agnostic controller exposing config bundles
+  over HTTP (`base_path = "/config"`).
+- **`ConfigClient`** — fetches a bundle from a remote `ConfigServer` on startup.
+
+---
+
+## ConfigSource
+
+A bundle is identified by `application` + `profile` + `label`:
+
+```python
+from pyfly.config_server import ConfigSource
+
+ConfigSource(
+    application="orders",
+    profile="prod",
+    label="main",                 # defaults to "main"
+    properties={"db.url": "..."},
+)
+```
+
+---
+
+## Backends
+
+Two backends ship out of the box:
+
+```python
+from pyfly.config_server import InMemoryConfigBackend, FilesystemConfigBackend
+
+backend = InMemoryConfigBackend()                 # great for tests
+backend = FilesystemConfigBackend("/etc/pyfly")   # reads/writes files
+```
+
+**`FilesystemConfigBackend`** stores each bundle as
+`<root>/<label>/<application>-<profile>.{yaml,yml,json}`. `fetch()` resolves the
+first matching file (preferring YAML); `save()` writes back to **the same file
+`fetch()` reads** (in its own format) and removes stale duplicate-format files,
+so a save can never be silently shadowed by a pre-existing `.yaml`.
+
+Implement `ConfigBackend` to back the server with a database, S3, Git, etc.:
+
+```python
+@runtime_checkable
+class ConfigBackend(Protocol):
+    async def fetch(self, application: str, profile: str, label: str = "main") -> ConfigSource | None: ...
+    async def save(self, source: ConfigSource) -> None: ...
+    async def list(self) -> list[ConfigSource]: ...
+```
+
+---
+
+## ConfigServer
+
+```python
+from pyfly.config_server import ConfigServer, FilesystemConfigBackend
+
+server = ConfigServer(FilesystemConfigBackend("/etc/pyfly"))
+
+bundle = await server.fetch("orders", "prod")     # Spring-Cloud-Config shaped dict
+await server.save("orders", "prod", {"db.url": "postgres://..."})
+all_sources = await server.list()
+```
+
+`fetch()` returns a Spring-Cloud-Config-compatible document
+(`{name, profiles, label, propertySources: [...]}`), so existing Spring clients
+can consume it. Mount the controller on your HTTP layer at `base_path` (`/config`).
+
+---
+
+## ConfigClient
+
+A client service fetches its bundle from a remote server at startup:
+
+```python
+from pyfly.config_server import ConfigClient
+
+client = ConfigClient(server_url="http://config:8888", application="orders", profile="prod")
+properties = await client.fetch()
+```
+
+Merge the returned properties into your local `Config` before the context starts.
diff --git a/docs/modules/logging.md b/docs/modules/logging.md
new file mode 100644
index 0000000..04d177b
--- /dev/null
+++ b/docs/modules/logging.md
@@ -0,0 +1,106 @@
+# Logging Guide
+
+PyFly uses **structured logging** — every log call is an event name plus
+key/value fields, rendered either by [`structlog`](https://www.structlog.org/)
+(when installed) or a zero-dependency stdlib fallback.
+
+---
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Getting a logger](#getting-a-logger)
+3. [The LoggingPort](#the-loggingport)
+4. [Adapters](#adapters)
+5. [Configuration](#configuration)
+
+---
+
+## Introduction
+
+The logging module is a hexagonal port (`LoggingPort`) with two adapters:
+
+- **`StructlogAdapter`** — used when the `observability` extra (which ships
+  `structlog`) is installed. Produces rich, processor-based structured output.
+- **`StdlibLoggingAdapter`** — a zero-dependency fallback built on the standard
+  library `logging` module. Renders structured fields as `event | key=value`.
+
+Both accept the same **structlog-style call signature**: an event string
+followed by arbitrary keyword fields.
+
+```python
+logger.info("http_request", method="GET", path="/orders", status_code=200)
+```
+
+---
+
+## Getting a logger
+
+Use `get_logger` — it returns a structured logger backed by `structlog` when
+available, and the stdlib shim otherwise, so your call sites are identical
+regardless of which extras are installed:
+
+```python
+from pyfly.logging import get_logger
+
+logger = get_logger(__name__)
+
+logger.info("order_placed", order_id="o-123", total=49.90)
+logger.warning("retrying", attempt=2)
+logger.error("payment_failed", error="declined", order_id="o-123")
+```
+
+> **Why not the stdlib logger directly?** A raw `logging.Logger` rejects
+> arbitrary keyword arguments (`logger.info("event", method="GET")` raises
+> `TypeError`). `get_logger` guarantees the structured signature works even
+> without `structlog` installed.
+
+---
+
+## The LoggingPort
+
+```python
+from typing import Any, Protocol, runtime_checkable
+from pyfly.core.config import Config
+
+@runtime_checkable
+class LoggingPort(Protocol):
+    def configure(self, config: Config) -> None: ...
+    def get_logger(self, name: str) -> Any: ...
+    def set_level(self, name: str, level: str) -> None: ...
+```
+
+The active adapter is selected automatically at startup and configured from the
+`pyfly.logging.*` section.
+
+---
+
+## Adapters
+
+| Adapter | When | Output |
+|---|---|---|
+| `StructlogAdapter` | `structlog` installed | structured (console or JSON) via structlog processors |
+| `StdlibLoggingAdapter` | fallback | `event | key=value` via stdlib `logging` |
+
+The stdlib shim (`_StructuredLogger`) wraps a `logging.Logger` and accepts
+`debug/info/warning/error/critical/exception(event, **kwargs)`.
+
+---
+
+## Configuration
+
+```yaml
+pyfly:
+  logging:
+    level:
+      root: INFO
+      "pyfly.web": DEBUG     # per-logger overrides
+    format: console          # or "json"
+```
+
+- `level.root` — root log level.
+- `level.<logger>` — per-logger level overrides.
+- `format` — `console` (human-readable) or `json` (one JSON object per line).
+
+The admin dashboard's **Loggers** view and the `/actuator/loggers` endpoint let
+you inspect and change levels at runtime.
diff --git a/pyproject.toml b/pyproject.toml
index 65fe893..4548348 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@ name = "pyfly"
 # CalVer YY.MM.PATCH — package metadata uses PEP 440 normalized form (26.5.4);
 # git tag, GitHub release and human-readable display use leading-zero form
 # (v26.05.04) to match the Java/.NET/Go siblings.
-version = "26.5.5"
+version = "26.5.6"
 description = "The official Python implementation of the Firefly Framework — DI, CQRS, EDA, hexagonal architecture, and more."
 readme = "README.md"
 license = "Apache-2.0"
diff --git a/src/pyfly/__init__.py b/src/pyfly/__init__.py
index 498687e..15a42a2 100644
--- a/src/pyfly/__init__.py
+++ b/src/pyfly/__init__.py
@@ -13,4 +13,4 @@
 # limitations under the License.
 """PyFly — Enterprise Python Framework."""
 
-__version__ = "26.05.04"
+__version__ = "26.05.06"
diff --git a/src/pyfly/actuator/adapters/starlette.py b/src/pyfly/actuator/adapters/starlette.py
index 658b250..fca8256 100644
--- a/src/pyfly/actuator/adapters/starlette.py
+++ b/src/pyfly/actuator/adapters/starlette.py
@@ -18,11 +18,12 @@
 import json
 
 from starlette.requests import Request
-from starlette.responses import JSONResponse
+from starlette.responses import JSONResponse, PlainTextResponse, Response
 from starlette.routing import Route
 
 from pyfly.actuator.endpoints.health_endpoint import HealthEndpoint
 from pyfly.actuator.endpoints.loggers_endpoint import LoggersEndpoint
+from pyfly.actuator.endpoints.prometheus_endpoint import PrometheusEndpoint
 from pyfly.actuator.registry import ActuatorRegistry
 
 
@@ -50,12 +51,28 @@ async def index_endpoint(request: Request) -> JSONResponse:
             routes.extend(_make_health_routes(ep))
         elif isinstance(ep, LoggersEndpoint):
             routes.extend(_make_loggers_routes(ep))
+        elif isinstance(ep, PrometheusEndpoint):
+            routes.append(_make_prometheus_route(ep))
         else:
             routes.append(_make_generic_route(eid, ep))
 
     return routes
 
 
+def _make_prometheus_route(ep: PrometheusEndpoint) -> Route:
+    """Prometheus scrape endpoint — must serve the raw text exposition format
+    (``text/plain; version=0.0.4``), not a JSON wrapper."""
+
+    async def handler(request: Request) -> Response:
+        data = await ep.handle()
+        return PlainTextResponse(
+            data.get("body", ""),
+            media_type=data.get("content_type") or "text/plain; version=0.0.4; charset=utf-8",
+        )
+
+    return Route("/actuator/prometheus", handler, methods=["GET"])
+
+
 def _make_health_routes(ep: HealthEndpoint) -> list[Route]:
     """Health endpoint returns dynamic status codes (200/503)."""
 
diff --git a/src/pyfly/admin/auto_configuration.py b/src/pyfly/admin/auto_configuration.py
index f7e7bdd..2c91387 100644
--- a/src/pyfly/admin/auto_configuration.py
+++ b/src/pyfly/admin/auto_configuration.py
@@ -17,7 +17,6 @@
 
 from pyfly.admin.config import AdminClientProperties, AdminProperties
 from pyfly.admin.log_handler import AdminLogHandler
-from pyfly.admin.middleware.trace_collector import TraceCollectorFilter
 from pyfly.admin.providers.runtime_provider import RuntimeProvider
 from pyfly.admin.registry import AdminViewRegistry
 from pyfly.admin.server.client_registration import AdminClientRegistration
@@ -48,9 +47,11 @@ def admin_view_registry(self) -> AdminViewRegistry:
     def runtime_provider(self) -> RuntimeProvider:
         return RuntimeProvider()
 
-    @bean
-    def admin_trace_collector(self) -> TraceCollectorFilter:
-        return TraceCollectorFilter()
+    # NOTE: the HTTP trace collector (TraceCollectorFilter) is created and wired
+    # into the WebFilter chain directly by ``create_app`` — it must join the
+    # chain while the ASGI middleware is assembled, which happens before this
+    # auto-configuration's beans are instantiated. Registering it here as a bean
+    # would never reach the request path, so it is intentionally not a bean.
 
     @bean
     def admin_log_handler(self) -> AdminLogHandler:
diff --git a/src/pyfly/admin/providers/server_provider.py b/src/pyfly/admin/providers/server_provider.py
index 831d067..1b18d3e 100644
--- a/src/pyfly/admin/providers/server_provider.py
+++ b/src/pyfly/admin/providers/server_provider.py
@@ -22,13 +22,36 @@
 
 
 class ServerProvider:
-    """Provides ASGI server runtime info for the admin dashboard."""
+    """Provides ASGI server runtime info for the admin dashboard.
 
-    def __init__(self, server: Any) -> None:
+    The server adapter (``ApplicationServerPort``) is instantiated during
+    ``ApplicationContext.start()`` — after the web app is assembled — so it is
+    resolved lazily from the context on each request rather than captured at
+    construction time. An explicit ``server`` argument still takes precedence
+    when supplied (e.g. in tests).
+    """
+
+    def __init__(self, server: Any = None, context: Any = None) -> None:
         self._server = server
+        self._context = context
+
+    def _resolve_server(self) -> Any:
+        if self._server is not None:
+            return self._server
+        if self._context is None:
+            return None
+        try:
+            from pyfly.server.ports.outbound import ApplicationServerPort
+        except ImportError:
+            return None
+        for _cls, reg in self._context.container._registrations.items():
+            if reg.instance is not None and isinstance(reg.instance, ApplicationServerPort):
+                return reg.instance
+        return None
 
     async def get_server_info(self) -> dict[str, Any]:
-        if self._server is None:
+        server = self._resolve_server()
+        if server is None:
             return {
                 "name": "unknown",
                 "version": "unknown",
@@ -39,7 +62,7 @@ async def get_server_info(self) -> dict[str, Any]:
                 "port": 0,
             }
 
-        info = self._server.server_info
+        info = server.server_info
         return {
             "name": info.name,
             "version": info.version,
diff --git a/src/pyfly/aop/weaver.py b/src/pyfly/aop/weaver.py
index 5211f95..f5b8731 100644
--- a/src/pyfly/aop/weaver.py
+++ b/src/pyfly/aop/weaver.py
@@ -39,6 +39,14 @@ def weave_bean(bean: Any, qualified_prefix: str, registry: AspectRegistry) -> No
         if attr_name.startswith("_"):
             continue
 
+        # Look the attribute up statically on the class FIRST so we never trigger
+        # descriptor ``__get__`` side effects. A plain ``getattr`` here would
+        # evaluate @property / cached_property getters during weaving — a
+        # side-effecting or raising property would then abort application startup.
+        static_attr = inspect.getattr_static(bean, attr_name, None)
+        if isinstance(static_attr, (property, functools.cached_property)):
+            continue
+
         attr = getattr(bean, attr_name, None)
         if attr is None or not callable(attr):
             continue
diff --git a/src/pyfly/callbacks/dispatcher.py b/src/pyfly/callbacks/dispatcher.py
index 9fa1afb..d1cd4ec 100644
--- a/src/pyfly/callbacks/dispatcher.py
+++ b/src/pyfly/callbacks/dispatcher.py
@@ -7,6 +7,7 @@
 import asyncio
 import hashlib
 import hmac
+import json
 import logging
 from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
@@ -78,9 +79,15 @@ async def _deliver(
 
         headers = dict(sub.headers)
         if config.secret:
+            # Sign the canonical JSON serialization of the payload — NOT
+            # ``str(payload)`` (Python dict repr with single quotes / ``True`` /
+            # ``None``), which is invalid JSON and unverifiable by any receiver.
+            # Receivers verify with HmacSignatureValidator over this same compact,
+            # key-sorted JSON body (see pyfly.webhooks.signature).
+            canonical_body = json.dumps(payload, separators=(",", ":"), sort_keys=True)
             sig = hmac.new(
                 config.secret.encode("utf-8"),
-                str(payload).encode("utf-8"),
+                canonical_body.encode("utf-8"),
                 hashlib.sha256,
             ).hexdigest()
             headers["X-Pyfly-Signature"] = f"sha256={sig}"
diff --git a/src/pyfly/cli/templates/cli/hello_command.py.j2 b/src/pyfly/cli/templates/cli/hello_command.py.j2
index 36adcb5..2cb08d5 100644
--- a/src/pyfly/cli/templates/cli/hello_command.py.j2
+++ b/src/pyfly/cli/templates/cli/hello_command.py.j2
@@ -12,12 +12,12 @@ class HelloCommand:
     def __init__(self, greeting_service: GreetingService) -> None:
         self._greeting_service = greeting_service
 
-    @shell_method(description="Say hello")
+    @shell_method(help="Say hello")
     def hello(self, name: str = "World") -> str:
         """Greet someone by name."""
         return self._greeting_service.greet(name)
 
-    @shell_method(description="Say goodbye")
+    @shell_method(help="Say goodbye")
     def goodbye(self, name: str = "World") -> str:
         """Say goodbye to someone."""
         return f"Goodbye, {name}!"
diff --git a/src/pyfly/config_server/backend.py b/src/pyfly/config_server/backend.py
index 897f568..d585c43 100644
--- a/src/pyfly/config_server/backend.py
+++ b/src/pyfly/config_server/backend.py
@@ -9,6 +9,8 @@
 from dataclasses import dataclass, field
 from typing import Any, Protocol, runtime_checkable
 
+import yaml  # type: ignore[import-untyped]
+
 
 @dataclass
 class ConfigSource:
@@ -82,10 +84,33 @@ async def fetch(self, application: str, profile: str, label: str = "main") -> Co
     async def save(self, source: ConfigSource) -> None:
         import json
 
-        target = self._root / source.label if source.label else self._root
-        target.mkdir(parents=True, exist_ok=True)
-        path = target / f"{source.application}-{source.profile}.json"
-        await asyncio.get_event_loop().run_in_executor(None, path.write_text, json.dumps(source.properties, indent=2))
+        candidates = self._path_candidates(source.application, source.profile, source.label)
+        existing = [c for c in candidates if c.exists()]
+
+        # Write back to the SAME file fetch() would read (highest-priority
+        # existing candidate), preserving its format — otherwise a save that
+        # wrote a fresh .json would be silently shadowed by a pre-existing
+        # higher-priority .yaml. If none exists yet, create a .json.
+        if existing:
+            path = existing[0]
+        else:
+            target = self._root / source.label if source.label else self._root
+            target.mkdir(parents=True, exist_ok=True)
+            path = target / f"{source.application}-{source.profile}.json"
+
+        if path.suffix.lstrip(".") in {"yaml", "yml"}:
+            text = yaml.safe_dump(source.properties, sort_keys=False)
+        else:
+            text = json.dumps(source.properties, indent=2)
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        await asyncio.get_event_loop().run_in_executor(None, path.write_text, text)
+
+        # Guarantee exactly one file backs this (application, profile, label) so
+        # future fetches/saves can't diverge across stale duplicate formats.
+        for other in existing:
+            if other != path:
+                other.unlink(missing_ok=True)
 
     async def list(self) -> list[ConfigSource]:
         results: list[ConfigSource] = []
@@ -112,7 +137,6 @@ def _parse_text(text: str, fmt: str) -> dict[str, Any]:
 
         result: dict[str, Any] = json.loads(text)
         return result
-    import yaml  # type: ignore[import-untyped]
 
     parsed: dict[str, Any] | None = yaml.safe_load(text)
     return parsed or {}
diff --git a/src/pyfly/container/container.py b/src/pyfly/container/container.py
index cdc42b5..4ac6c05 100644
--- a/src/pyfly/container/container.py
+++ b/src/pyfly/container/container.py
@@ -54,6 +54,12 @@ def __init__(self) -> None:
         self._bindings: dict[type, list[type]] = {}
         self._resolving: dict[type, None] = {}  # insertion-ordered, O(1) lookup
         self._metrics: dict[type, BeanMetrics] = {}
+        # Every registration keyed by (impl_type, name), preserving insertion
+        # order. ``_registrations`` keeps only the last registration per type, so
+        # this is the source of truth for ``resolve_all``/``list[T]`` — without it,
+        # two @bean methods returning the same concrete type would collapse and
+        # one bean would silently vanish from type/list resolution.
+        self._all: dict[tuple[type, str], Registration] = {}
         self._lock = threading.RLock()
 
     def register(
@@ -73,6 +79,7 @@ def register(
             name=bean_name,
         )
         self._registrations[cls] = reg
+        self._all[(cls, bean_name)] = reg
         if bean_name:
             self._named[bean_name] = reg
 
@@ -119,9 +126,31 @@ def resolve_by_name(self, name: str) -> Any:
         return self._resolve_registration(self._named[name])
 
     def resolve_all(self, cls: type[T]) -> list[T]:
-        """Resolve all implementations bound to an interface."""
-        impls = self._bindings.get(cls, [])
-        return [self._resolve_registration(self._registrations[impl]) for impl in impls]
+        """Resolve every bean assignable to *cls*.
+
+        Includes both implementations bound to an interface AND beans whose own
+        concrete type is *cls* (so multiple @bean methods returning the same
+        concrete type are all returned). Deduplicated by resolved-instance
+        identity so the synthetic interface registration does not double-count
+        an already-bound implementation.
+        """
+        results: list[T] = []
+        seen: set[int] = set()
+
+        def _add(reg: Registration) -> None:
+            instance = self._resolve_registration(reg)
+            if id(instance) not in seen:
+                seen.add(id(instance))
+                results.append(cast(T, instance))
+
+        for impl in self._bindings.get(cls, []):
+            reg = self._registrations.get(impl)
+            if reg is not None:
+                _add(reg)
+        for reg in self._all.values():
+            if reg.impl_type is cls:
+                _add(reg)
+        return results
 
     def contains(self, name: str) -> bool:
         """Check if a named bean exists."""
diff --git a/src/pyfly/context/application_context.py b/src/pyfly/context/application_context.py
index 7d754c5..84ad99e 100644
--- a/src/pyfly/context/application_context.py
+++ b/src/pyfly/context/application_context.py
@@ -197,22 +197,30 @@ async def _do_start(self) -> None:
                 except BeanCreationException as exc:
                     logger.debug("deferred_bean_resolution", extra={"bean": cls.__name__, "reason": str(exc)})
 
-        # 5. Run post-processors and lifecycle hooks
+        # 5. Run post-processors and lifecycle hooks.
+        #
+        # Two passes (not one per-bean loop): every BeanPostProcessor.before_init
+        # runs across ALL beans before any after_init. Otherwise weaving is
+        # registration-order dependent — a target bean initialized before its
+        # @aspect bean would have its advice silently skipped, because the aspect
+        # is only collected during the aspect's own before_init. Snapshotting the
+        # registrations also avoids "dict changed size during iteration" if a hook
+        # lazily creates another bean.
         sorted_pps = sorted(self._post_processors, key=lambda pp: get_order(type(pp)))
-        for reg in self._container._registrations.values():
-            if reg.instance is not None:
-                bean_name = reg.name or reg.impl_type.__name__
+        live_regs = [reg for reg in self._container._registrations.values() if reg.instance is not None]
 
-                # BeanPostProcessor.before_init
-                for pp in sorted_pps:
-                    reg.instance = pp.before_init(reg.instance, bean_name)
+        # Pass 1: before_init for every bean (collects all @aspect beans, etc.)
+        for reg in live_regs:
+            bean_name = reg.name or reg.impl_type.__name__
+            for pp in sorted_pps:
+                reg.instance = pp.before_init(reg.instance, bean_name)
 
-                # @post_construct
-                await self._call_post_construct(reg.instance)
-
-                # BeanPostProcessor.after_init
-                for pp in sorted_pps:
-                    reg.instance = pp.after_init(reg.instance, bean_name)
+        # Pass 2: @post_construct then after_init (weaving now sees every aspect)
+        for reg in live_regs:
+            bean_name = reg.name or reg.impl_type.__name__
+            await self._call_post_construct(reg.instance)
+            for pp in sorted_pps:
+                reg.instance = pp.after_init(reg.instance, bean_name)
 
         # 6. Wire decorator-based beans to their targets
         self._wire_app_event_listeners()
@@ -545,19 +553,38 @@ def _discover_post_processors(self) -> None:
         if count:
             logger.debug("Discovered %d BeanPostProcessor(s)", count)
 
+    @staticmethod
+    def _safe_members(instance: Any, *, skip_private: bool = True) -> list[tuple[str, Any]]:
+        """Return ``(name, member)`` for an instance's attributes, skipping
+        ``@property`` / ``cached_property``.
+
+        Bean wiring and lifecycle scans iterate ``dir(instance)`` to find
+        decorator-marked methods. A plain ``getattr`` would evaluate property
+        getters — a side-effecting or *raising* property would then corrupt or
+        abort startup. Looking the attribute up statically on the class first
+        avoids triggering any descriptor ``__get__``.
+        """
+        members: list[tuple[str, Any]] = []
+        for attr_name in dir(instance):
+            if skip_private and attr_name.startswith("_"):
+                continue
+            static_attr = inspect.getattr_static(instance, attr_name, None)
+            if isinstance(static_attr, (property, functools.cached_property)):
+                continue
+            try:
+                member = getattr(instance, attr_name)
+            except Exception:
+                continue
+            members.append((attr_name, member))
+        return members
+
     def _wire_app_event_listeners(self) -> None:
         """Scan singleton beans for @app_event_listener methods and subscribe to event bus."""
         count = 0
         for reg in self._container._registrations.values():
             if reg.instance is None:
                 continue
-            for attr_name in dir(reg.instance):
-                if attr_name.startswith("_"):
-                    continue
-                try:
-                    method = getattr(reg.instance, attr_name)
-                except Exception:
-                    continue
+            for _attr_name, method in self._safe_members(reg.instance):
                 if not getattr(method, "__pyfly_app_event_listener__", False):
                     continue
                 # Infer event type from the method's type hints
@@ -582,13 +609,7 @@ def _wire_message_listeners(self) -> None:
         for reg in self._container._registrations.values():
             if reg.instance is None:
                 continue
-            for attr_name in dir(reg.instance):
-                if attr_name.startswith("_"):
-                    continue
-                try:
-                    method = getattr(reg.instance, attr_name)
-                except Exception:
-                    continue
+            for _attr_name, method in self._safe_members(reg.instance):
                 if not getattr(method, "__pyfly_message_listener__", False):
                     continue
                 # Lazy-resolve broker on first hit
@@ -673,13 +694,7 @@ def _wire_async_methods(self) -> None:
         for reg in self._container._registrations.values():
             if reg.instance is None:
                 continue
-            for attr_name in dir(reg.instance):
-                if attr_name.startswith("_"):
-                    continue
-                try:
-                    method = getattr(reg.instance, attr_name)
-                except Exception:
-                    continue
+            for attr_name, method in self._safe_members(reg.instance):
                 if not getattr(method, "__pyfly_async__", False):
                     continue
 
@@ -718,13 +733,7 @@ def _wire_shell_commands(self) -> None:
                     logger.debug("No ShellRunnerPort registered; skipping @shell_method wiring")
                     self._wiring_counts["shell_commands"] = 0
                     return
-            for attr_name in dir(reg.instance):
-                if attr_name.startswith("_"):
-                    continue
-                try:
-                    method = getattr(reg.instance, attr_name)
-                except Exception:
-                    continue
+            for attr_name, method in self._safe_members(reg.instance):
                 if not getattr(method, "__pyfly_shell_method__", False):
                     continue
 
@@ -816,9 +825,8 @@ def get_bean_counts_by_stereotype(self) -> dict[str, int]:
 
     async def _call_post_construct(self, instance: Any) -> None:
         """Call all @post_construct methods on an instance."""
-        for attr_name in dir(instance):
-            method = getattr(instance, attr_name, None)
-            if method is not None and getattr(method, "__pyfly_post_construct__", False):
+        for attr_name, method in self._safe_members(instance, skip_private=False):
+            if getattr(method, "__pyfly_post_construct__", False):
                 try:
                     result = method()
                     if inspect.isawaitable(result):
@@ -832,9 +840,8 @@ async def _call_post_construct(self, instance: Any) -> None:
 
     async def _call_pre_destroy(self, instance: Any) -> None:
         """Call all @pre_destroy methods on an instance."""
-        for attr_name in dir(instance):
-            method = getattr(instance, attr_name, None)
-            if method is not None and getattr(method, "__pyfly_pre_destroy__", False):
+        for attr_name, method in self._safe_members(instance, skip_private=False):
+            if getattr(method, "__pyfly_pre_destroy__", False):
                 try:
                     result = method()
                     if inspect.isawaitable(result):
diff --git a/src/pyfly/core/config.py b/src/pyfly/core/config.py
index ceb12e1..8e55bdb 100644
--- a/src/pyfly/core/config.py
+++ b/src/pyfly/core/config.py
@@ -20,9 +20,10 @@
 import os
 import re
 import tomllib
+import types
 from collections.abc import Callable
 from pathlib import Path
-from typing import Any, TypeVar, cast, get_type_hints
+from typing import Any, TypeVar, Union, cast, get_args, get_origin, get_type_hints
 
 import yaml  # type: ignore[import-untyped]
 
@@ -320,7 +321,10 @@ def bind(self, config_cls: type[T]) -> T:
         if prefix is None:
             raise ValueError(f"{config_cls.__name__} is not decorated with @config_properties")
 
-        section = self.get_section(prefix)
+        # Resolve ``${...}`` placeholders across the whole section before binding.
+        # ``_resolve_tree`` builds a fresh structure, so ``self._data`` stays raw
+        # (single-value ``get()`` continues to resolve lazily).
+        section = self._resolve_tree(self.get_section(prefix))
 
         # Pydantic BaseModel path — fail-fast with ValidationError
         try:
@@ -336,19 +340,46 @@ def bind(self, config_cls: type[T]) -> T:
         except ImportError:
             pass
 
-        # Existing dataclass path (unchanged)
+        # Dataclass path (recurses into nested dataclass fields).
+        return cast(T, self._bind_dataclass(config_cls, section))
+
+    def _resolve_tree(self, value: Any, _depth: int = 0) -> Any:
+        """Recursively resolve ``${...}`` placeholders inside nested structures,
+        returning a new structure without mutating the underlying config data."""
+        if isinstance(value, str):
+            return self._resolve_placeholders(value, _depth) if "${" in value else value
+        if isinstance(value, dict):
+            return {k: self._resolve_tree(v, _depth) for k, v in value.items()}
+        if isinstance(value, list):
+            return [self._resolve_tree(v, _depth) for v in value]
+        return value
+
+    def _bind_dataclass(self, config_cls: Any, section: dict[str, Any]) -> Any:
+        """Bind a (possibly nested) dataclass from an already placeholder-resolved dict."""
         hints = get_type_hints(config_cls)
         kwargs: dict[str, Any] = {}
-        for field in dataclasses.fields(config_cls):  # type: ignore[arg-type]
-            if field.name in section:
-                value = section[field.name]
-                expected_type = hints.get(field.name)
-                if expected_type is int and isinstance(value, str):
-                    value = int(value)
-                elif expected_type is float and isinstance(value, str):
-                    value = float(value)
-                elif expected_type is bool and isinstance(value, str):
-                    value = value.lower() in ("true", "1", "yes")
-                kwargs[field.name] = value
-
+        for field in dataclasses.fields(config_cls):
+            if field.name not in section:
+                continue
+            kwargs[field.name] = self._coerce_value(hints.get(field.name), section[field.name])
         return config_cls(**kwargs)
+
+    def _coerce_value(self, expected_type: Any, value: Any) -> Any:
+        """Coerce a raw config value to the field's declared type, recursing into
+        nested dataclasses (so e.g. ``ServerProperties.granian`` becomes a
+        ``GranianProperties`` rather than a raw dict)."""
+        # Unwrap Optional[T] / T | None to the underlying type.
+        if get_origin(expected_type) is Union or isinstance(expected_type, types.UnionType):
+            non_none = [a for a in get_args(expected_type) if a is not type(None)]
+            if non_none:
+                expected_type = non_none[0]
+
+        if dataclasses.is_dataclass(expected_type) and isinstance(value, dict):
+            return self._bind_dataclass(expected_type, value)
+        if expected_type is int and isinstance(value, str):
+            return int(value)
+        if expected_type is float and isinstance(value, str):
+            return float(value)
+        if expected_type is bool and isinstance(value, str):
+            return value.lower() in ("true", "1", "yes")
+        return value
diff --git a/src/pyfly/cqrs/config/auto_configuration.py b/src/pyfly/cqrs/config/auto_configuration.py
index 7b57e5a..56de2b1 100644
--- a/src/pyfly/cqrs/config/auto_configuration.py
+++ b/src/pyfly/cqrs/config/auto_configuration.py
@@ -20,6 +20,7 @@
 
 import logging
 
+from pyfly.cache.ports.outbound import CacheAdapter
 from pyfly.container.bean import bean
 from pyfly.context.conditions import auto_configuration, conditional_on_property
 from pyfly.core.config import Config
@@ -30,10 +31,15 @@
 from pyfly.cqrs.command.registry import HandlerRegistry
 from pyfly.cqrs.command.validation import CommandValidationService
 from pyfly.cqrs.config.properties import CqrsProperties
-from pyfly.cqrs.event.publisher import NoOpEventPublisher
+from pyfly.cqrs.event.publisher import (
+    CommandEventPublisher,
+    EdaCommandEventPublisher,
+    NoOpEventPublisher,
+)
 from pyfly.cqrs.query.bus import DefaultQueryBus
 from pyfly.cqrs.tracing.correlation import CorrelationContext
 from pyfly.cqrs.validation.processor import AutoValidationProcessor
+from pyfly.eda.ports.outbound import EventPublisher
 
 _logger = logging.getLogger(__name__)
 
@@ -52,6 +58,9 @@ class CqrsAutoConfiguration:
     * :class:`CqrsMetricsService`
     * :class:`AuthorizationService` (conditional on ``authorization.enabled``)
     * :class:`HandlerRegistry`
+    * :class:`CommandEventPublisher` (``EdaCommandEventPublisher`` when an EDA
+      :class:`~pyfly.eda.ports.outbound.EventPublisher` bean is present, else
+      :class:`NoOpEventPublisher`)
     * :class:`DefaultCommandBus`
     * :class:`QueryCacheAdapter` (conditional on cache availability)
     * :class:`DefaultQueryBus`
@@ -86,6 +95,17 @@ def authorization_service(self, props: CqrsProperties) -> AuthorizationService:
     def handler_registry(self) -> HandlerRegistry:
         return HandlerRegistry()
 
+    @bean
+    def command_event_publisher(self, producer: EventPublisher | None = None) -> CommandEventPublisher:
+        # Optional injection: the container supplies the EDA ``EventPublisher``
+        # bean when the EDA subsystem is active, otherwise ``producer`` stays
+        # ``None`` (see ApplicationContext._call_bean_method default handling).
+        # When a real producer exists, domain events emitted by command handlers
+        # are forwarded to it; otherwise publishing degrades to a silent no-op.
+        if producer is not None:
+            return EdaCommandEventPublisher(producer)
+        return NoOpEventPublisher()
+
     @bean
     def command_bus(
         self,
@@ -93,19 +113,22 @@ def command_bus(
         validation: CommandValidationService,
         authorization: AuthorizationService,
         metrics: CqrsMetricsService,
+        event_publisher: CommandEventPublisher,
     ) -> DefaultCommandBus:
         return DefaultCommandBus(
             registry=registry,
             validation=validation,
             authorization=authorization,
             metrics=metrics,
-            event_publisher=NoOpEventPublisher(),
+            event_publisher=event_publisher,
         )
 
     @bean
-    def query_cache_adapter(self) -> QueryCacheAdapter:
-        # When pyfly.cache is available, the CacheAdapter will be injected
-        return QueryCacheAdapter()
+    def query_cache_adapter(self, cache: CacheAdapter | None = None) -> QueryCacheAdapter:
+        # Inject the pyfly.cache CacheAdapter bean when the cache subsystem is
+        # active; otherwise the adapter degrades to a silent no-op. Previously no
+        # CacheAdapter was ever passed, so @cacheable queries were never cached.
+        return QueryCacheAdapter(cache=cache)
 
     @bean
     def query_bus(
diff --git a/src/pyfly/cqrs/event/publisher.py b/src/pyfly/cqrs/event/publisher.py
index ab7ac6f..1d20890 100644
--- a/src/pyfly/cqrs/event/publisher.py
+++ b/src/pyfly/cqrs/event/publisher.py
@@ -19,7 +19,11 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, Protocol, runtime_checkable
+from dataclasses import asdict, is_dataclass
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from pyfly.eda.ports.outbound import EventPublisher
 
 _logger = logging.getLogger(__name__)
 
@@ -39,20 +43,32 @@ async def publish(self, event: Any, *, destination: str | None = None) -> None:
 
 
 class EdaCommandEventPublisher:
-    """Event publisher backed by pyfly's EDA messaging subsystem.
+    """Event publisher backed by pyfly's EDA :class:`EventPublisher`.
+
+    Delegates to the EDA :class:`~pyfly.eda.ports.outbound.EventPublisher`
+    port, adapting each domain event to that port's
+    ``publish(destination, event_type, payload, headers)`` contract:
 
-    Delegates to the messaging ``Producer`` from ``pyfly.messaging``.
+    * ``event_type`` is taken from the event's ``event_type`` attribute when
+      present, otherwise the event class name.
+    * ``payload`` is the event serialised to a ``dict`` — via
+      :func:`dataclasses.asdict` for dataclasses, else ``__dict__``.
     """
 
-    def __init__(self, producer: Any, default_destination: str = "cqrs.events") -> None:
+    def __init__(self, producer: EventPublisher, default_destination: str = "cqrs.events") -> None:
         self._producer = producer
         self._default_destination = default_destination
 
     async def publish(self, event: Any, *, destination: str | None = None) -> None:
         target = destination or self._default_destination
+        event_type = str(getattr(event, "event_type", None) or type(event).__name__)
+        if is_dataclass(event) and not isinstance(event, type):
+            payload: dict[str, Any] = asdict(event)
+        else:
+            payload = dict(getattr(event, "__dict__", {}))
         try:
-            await self._producer.send(target, event)
-            _logger.debug("Published event %s to %s", type(event).__name__, target)
+            await self._producer.publish(target, event_type, payload)
+            _logger.debug("Published event %s to %s", event_type, target)
         except Exception as exc:
-            _logger.error("Failed to publish event %s to %s: %s", type(event).__name__, target, exc)
+            _logger.error("Failed to publish event %s to %s: %s", event_type, target, exc)
             raise
diff --git a/src/pyfly/data/document/mongodb/query_compiler.py b/src/pyfly/data/document/mongodb/query_compiler.py
index 3745637..2268d20 100644
--- a/src/pyfly/data/document/mongodb/query_compiler.py
+++ b/src/pyfly/data/document/mongodb/query_compiler.py
@@ -188,8 +188,19 @@ def _build_clause(
         if op == "lte":
             return {field_name: {"$lte": args[arg_idx]}}, arg_idx + 1
         if op == "like":
-            pattern = re.escape(str(args[arg_idx])).replace(r"\%", ".*").replace(r"\_", ".")
-            return {field_name: {"$regex": pattern}}, arg_idx + 1
+            # Translate SQL LIKE wildcards per-character: ``%`` -> ``.*`` and
+            # ``_`` -> ``.``; every other character is regex-escaped. (Note:
+            # ``re.escape`` does NOT escape ``%``/``_``, so the previous
+            # ``.replace(r"\%", ...)`` calls were dead code and never matched.)
+            parts: list[str] = []
+            for char in str(args[arg_idx]):
+                if char == "%":
+                    parts.append(".*")
+                elif char == "_":
+                    parts.append(".")
+                else:
+                    parts.append(re.escape(char))
+            return {field_name: {"$regex": "".join(parts)}}, arg_idx + 1
         if op == "containing":
             escaped = re.escape(str(args[arg_idx]))
             return {field_name: {"$regex": f".*{escaped}.*", "$options": "i"}}, arg_idx + 1
diff --git a/src/pyfly/data/post_processor.py b/src/pyfly/data/post_processor.py
index f21a33d..10041b4 100644
--- a/src/pyfly/data/post_processor.py
+++ b/src/pyfly/data/post_processor.py
@@ -138,6 +138,14 @@ def _is_stub(method: Any) -> bool:
         consts.discard(None)
         consts.discard(Ellipsis)
 
+        # A docstring is stored as a code constant; on its own it does not make
+        # the method a real implementation, so a documented ``...``/``pass`` body
+        # must still count as a stub (otherwise documented derived-query methods
+        # are silently left as no-ops instead of getting a generated query).
+        doc = getattr(func, "__doc__", None)
+        if doc is not None:
+            consts.discard(doc)
+
         # If nothing meaningful remains in the constants and there is
         # very little bytecode, treat as a stub.
         return len(consts) == 0 and code.co_code is not None
diff --git a/src/pyfly/eda/adapters/kafka.py b/src/pyfly/eda/adapters/kafka.py
index 7536f11..7ffcec5 100644
--- a/src/pyfly/eda/adapters/kafka.py
+++ b/src/pyfly/eda/adapters/kafka.py
@@ -26,6 +26,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import fnmatch
 import logging
 from typing import Any
@@ -132,10 +133,8 @@ async def stop(self) -> None:
         self._started = False
         if self._consume_task is not None:
             self._consume_task.cancel()
-            try:
+            with contextlib.suppress(asyncio.CancelledError):
                 await self._consume_task
-            except asyncio.CancelledError:
-                pass
             self._consume_task = None
         if self._consumer is not None:
             await self._consumer.stop()
@@ -152,7 +151,8 @@ async def _consume_loop(self) -> None:
                 except Exception:
                     logger.exception(
                         "Failed to deserialize record from topic=%s offset=%s",
-                        record.topic, record.offset,
+                        record.topic,
+                        record.offset,
                     )
                     continue
                 for pattern, handler in self._handlers:
@@ -162,7 +162,8 @@ async def _consume_loop(self) -> None:
                         except Exception:
                             logger.exception(
                                 "Handler for pattern=%s raised on event_type=%s",
-                                pattern, envelope.event_type,
+                                pattern,
+                                envelope.event_type,
                             )
         except asyncio.CancelledError:
             pass
diff --git a/src/pyfly/eda/adapters/postgres.py b/src/pyfly/eda/adapters/postgres.py
index c63279d..3520540 100644
--- a/src/pyfly/eda/adapters/postgres.py
+++ b/src/pyfly/eda/adapters/postgres.py
@@ -53,6 +53,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import fnmatch
 import hashlib
 import json
@@ -98,7 +99,7 @@ def _normalise_dsn(dsn: str) -> str:
     """Strip SQLAlchemy dialect markers so asyncpg can parse the URL."""
     for marker in ("postgresql+asyncpg://", "postgresql+psycopg://", "postgres+asyncpg://"):
         if dsn.startswith(marker):
-            return "postgresql://" + dsn[len(marker):]
+            return "postgresql://" + dsn[len(marker) :]
     return dsn
 
 
@@ -219,7 +220,9 @@ async def start(self) -> None:
         self._started = True
         logger.info(
             "PostgresEventBus started: channel=%s destinations=%s group=%s",
-            self._channel, self._destinations, self._group,
+            self._channel,
+            self._destinations,
+            self._group,
         )
 
     async def stop(self) -> None:
@@ -228,10 +231,8 @@ async def stop(self) -> None:
         self._wake.set()  # wake the loop so it can observe _closed
         if self._consume_task is not None:
             self._consume_task.cancel()
-            try:
+            with contextlib.suppress(asyncio.CancelledError):
                 await self._consume_task
-            except asyncio.CancelledError:
-                pass
             self._consume_task = None
         if self._listen_conn is not None:
             try:
@@ -270,10 +271,8 @@ async def _consume_loop(self) -> None:
                         await asyncio.sleep(0.5)
                 if self._closed:
                     return
-                try:
+                with contextlib.suppress(asyncio.TimeoutError):
                     await asyncio.wait_for(self._wake.wait(), timeout=self._poll_interval_s)
-                except asyncio.TimeoutError:
-                    pass
                 self._wake.clear()
         except asyncio.CancelledError:
             pass
@@ -292,18 +291,14 @@ async def _drain(self) -> None:
         # the lock.
         lock_key = _group_lock_key(self._group)
         async with self._pool.acquire() as lock_conn:
-            got_lock = await lock_conn.fetchval(
-                "SELECT pg_try_advisory_lock($1)", lock_key
-            )
+            got_lock = await lock_conn.fetchval("SELECT pg_try_advisory_lock($1)", lock_key)
             if not got_lock:
                 return
             try:
                 await self._drain_with_lock()
             finally:
                 try:
-                    await lock_conn.fetchval(
-                        "SELECT pg_advisory_unlock($1)", lock_key
-                    )
+                    await lock_conn.fetchval("SELECT pg_advisory_unlock($1)", lock_key)
                 except Exception:
                     logger.debug(
                         "pg_advisory_unlock raised; lock will release on conn close",
diff --git a/src/pyfly/eda/adapters/redis.py b/src/pyfly/eda/adapters/redis.py
index 8a16362..e910364 100644
--- a/src/pyfly/eda/adapters/redis.py
+++ b/src/pyfly/eda/adapters/redis.py
@@ -25,6 +25,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import fnmatch
 import logging
 import socket
@@ -68,7 +69,7 @@ def __init__(
         block_ms: int = 5000,
         serializer: EventSerializer | None = None,
     ) -> None:
-        from redis import asyncio as redis_asyncio  # type: ignore[import-not-found]
+        from redis import asyncio as redis_asyncio
 
         self._url = url
         self._streams = list(streams) if streams else ["pyfly.events"]
@@ -129,15 +130,13 @@ async def stop(self) -> None:
         self._started = False
         if self._consume_task is not None:
             self._consume_task.cancel()
-            try:
+            with contextlib.suppress(asyncio.CancelledError):
                 await self._consume_task
-            except asyncio.CancelledError:
-                pass
             self._consume_task = None
         await self._client.close()
 
     async def _consume_loop(self) -> None:
-        streams = {s: ">" for s in self._streams}
+        streams: dict[Any, Any] = {s: ">" for s in self._streams}
         try:
             while not self._closed:
                 try:
@@ -171,7 +170,8 @@ async def _dispatch_and_ack(
         if raw is None:
             logger.warning(
                 "Stream entry %s/%s missing 'envelope' field; acking and skipping",
-                stream_name, entry_id,
+                stream_name,
+                entry_id,
             )
             await self._client.xack(stream_name, self._group, entry_id)
             return
@@ -180,7 +180,8 @@ async def _dispatch_and_ack(
         except Exception:
             logger.exception(
                 "Failed to deserialize envelope for %s/%s; acking to prevent redelivery",
-                stream_name, entry_id,
+                stream_name,
+                entry_id,
             )
             await self._client.xack(stream_name, self._group, entry_id)
             return
@@ -192,14 +193,17 @@ async def _dispatch_and_ack(
                     await handler(envelope)
                 except Exception:
                     logger.exception(
-                        "Handler for pattern=%s raised on event_type=%s; "
-                        "leaving entry %s unacked for re-delivery",
-                        pattern, envelope.event_type, entry_id,
+                        "Handler for pattern=%s raised on event_type=%s; leaving entry %s unacked for re-delivery",
+                        pattern,
+                        envelope.event_type,
+                        entry_id,
                     )
                     return
         if not delivered:
             # No handler matched; ack so we don't redeliver forever.
             logger.debug(
-                "No handler matched event_type=%s on %s; acking", envelope.event_type, stream_name,
+                "No handler matched event_type=%s on %s; acking",
+                envelope.event_type,
+                stream_name,
             )
         await self._client.xack(stream_name, self._group, entry_id)
diff --git a/src/pyfly/eda/auto_configuration.py b/src/pyfly/eda/auto_configuration.py
index 1697980..aebc59d 100644
--- a/src/pyfly/eda/auto_configuration.py
+++ b/src/pyfly/eda/auto_configuration.py
@@ -134,7 +134,5 @@ class EdaHealthAutoConfiguration:
     """
 
     @bean(name="eda_health")
-    def eda_health_indicator(
-        self, event_publisher: EventPublisher
-    ) -> EventPublisherHealthIndicator:
+    def eda_health_indicator(self, event_publisher: EventPublisher) -> EventPublisherHealthIndicator:
         return EventPublisherHealthIndicator(event_publisher)
diff --git a/src/pyfly/eda/circuit_breaker.py b/src/pyfly/eda/circuit_breaker.py
index e508343..0945053 100644
--- a/src/pyfly/eda/circuit_breaker.py
+++ b/src/pyfly/eda/circuit_breaker.py
@@ -64,3 +64,8 @@ async def _on_failure(self) -> None:
             self._failures += 1
             if self._failures >= self._config.failure_threshold:
                 self._opened_at = time.monotonic()
+                # Reset the half-open trial budget so the NEXT recovery window
+                # gets a fresh quota. Without this the counter accumulates across
+                # re-opens and the breaker becomes permanently stuck OPEN once
+                # half_open_max_calls total trials have failed over its lifetime.
+                self._half_open_calls = 0
diff --git a/src/pyfly/eventsourcing/projection.py b/src/pyfly/eventsourcing/projection.py
index 542a8e0..ae1a1c3 100644
--- a/src/pyfly/eventsourcing/projection.py
+++ b/src/pyfly/eventsourcing/projection.py
@@ -82,6 +82,12 @@ async def _loop(self) -> None:
                             evt.event_id,
                             exc,
                         )
+                        # Do NOT advance past a failed event: stop the batch
+                        # here so the cursor stays put and this event is retried
+                        # on the next poll (at-least-once, in-order). Continuing
+                        # would let the next success move the cursor past the
+                        # failed event, silently dropping it.
+                        break
             except Exception as exc:  # noqa: BLE001
                 _logger.error("projection runner error: %s", exc)
             try:
diff --git a/src/pyfly/logging/__init__.py b/src/pyfly/logging/__init__.py
index ceffd45..d79a636 100644
--- a/src/pyfly/logging/__init__.py
+++ b/src/pyfly/logging/__init__.py
@@ -13,10 +13,36 @@
 # limitations under the License.
 """PyFly Logging — hexagonal logging port and adapters."""
 
+from __future__ import annotations
+
+import logging
+from typing import Any
+
 from pyfly.logging.port import LoggingPort
 from pyfly.logging.stdlib_adapter import StdlibLoggingAdapter
 
-__all__ = ["LoggingPort", "StdlibLoggingAdapter"]
+__all__ = ["LoggingPort", "StdlibLoggingAdapter", "get_logger"]
+
+
+def get_logger(name: str) -> Any:
+    """Return a structured logger that accepts ``logger.info(event, **kwargs)``.
+
+    Uses ``structlog`` when installed, otherwise a stdlib-backed shim that
+    renders ``event | key=value`` output. This keeps every call site
+    structlog-style and safe even when the ``observability`` extra (which
+    ships ``structlog``) is not installed — passing keyword fields to a raw
+    stdlib :class:`logging.Logger` would otherwise raise ``TypeError`` on
+    every call.
+    """
+    try:
+        import structlog
+
+        return structlog.get_logger(name)
+    except ImportError:
+        from pyfly.logging.stdlib_adapter import _StructuredLogger
+
+        return _StructuredLogger(logging.getLogger(name))
+
 
 try:
     from pyfly.logging.structlog_adapter import StructlogAdapter
diff --git a/src/pyfly/messaging/adapters/kafka.py b/src/pyfly/messaging/adapters/kafka.py
index b40fd83..c10792f 100644
--- a/src/pyfly/messaging/adapters/kafka.py
+++ b/src/pyfly/messaging/adapters/kafka.py
@@ -34,6 +34,7 @@ def __init__(self, bootstrap_servers: str = "localhost:9092") -> None:
         self._consumers: list[Any] = []
         self._handlers: list[tuple[str, MessageHandler, str | None]] = []
         self._consumer_tasks: list[asyncio.Task[None]] = []
+        self._started = False
 
     async def publish(
         self,
@@ -53,31 +54,42 @@ async def subscribe(
         group: str | None = None,
     ) -> None:
         self._handlers.append((topic, handler, group))
+        # PyFly's ApplicationContext auto-starts adapter beans BEFORE @message_listener
+        # wiring calls subscribe(), so a subscription that arrives after start() must
+        # spin up its own consumer immediately — otherwise the handler never consumes.
+        if self._started:
+            await self._start_consumer(topic, [handler], group)
 
     async def start(self) -> None:
-        from aiokafka import AIOKafkaConsumer, AIOKafkaProducer  # type: ignore[import-untyped]
+        from aiokafka import AIOKafkaProducer  # type: ignore[import-untyped]
 
         self._producer = AIOKafkaProducer(bootstrap_servers=self._bootstrap_servers)
         await self._producer.start()
 
-        grouped: dict[tuple[str, str | None], list[tuple[str, MessageHandler]]] = {}
+        grouped: dict[tuple[str, str | None], list[MessageHandler]] = {}
         for topic, handler, group in self._handlers:
-            key = (topic, group)
-            grouped.setdefault(key, []).append((topic, handler))
-
-        for (topic, group), entries in grouped.items():
-            consumer = AIOKafkaConsumer(
-                topic,
-                bootstrap_servers=self._bootstrap_servers,
-                group_id=group,
-            )
-            await consumer.start()
-            self._consumers.append(consumer)
-            handlers_for_consumer = [h for _, h in entries]
-            task = asyncio.create_task(self._consume_loop(consumer, handlers_for_consumer))
-            self._consumer_tasks.append(task)
+            grouped.setdefault((topic, group), []).append(handler)
+
+        for (topic, group), handlers in grouped.items():
+            await self._start_consumer(topic, handlers, group)
+
+        self._started = True
+
+    async def _start_consumer(self, topic: str, handlers: list[MessageHandler], group: str | None) -> None:
+        from aiokafka import AIOKafkaConsumer
+
+        consumer = AIOKafkaConsumer(
+            topic,
+            bootstrap_servers=self._bootstrap_servers,
+            group_id=group,
+        )
+        await consumer.start()
+        self._consumers.append(consumer)
+        task = asyncio.create_task(self._consume_loop(consumer, list(handlers)))
+        self._consumer_tasks.append(task)
 
     async def stop(self) -> None:
+        self._started = False
         for task in self._consumer_tasks:
             task.cancel()
         if self._consumer_tasks:
diff --git a/src/pyfly/messaging/adapters/rabbitmq.py b/src/pyfly/messaging/adapters/rabbitmq.py
index 33d6ec6..c06d820 100644
--- a/src/pyfly/messaging/adapters/rabbitmq.py
+++ b/src/pyfly/messaging/adapters/rabbitmq.py
@@ -39,6 +39,7 @@ def __init__(
         self._channel: Any = None
         self._exchange: Any = None
         self._handlers: list[tuple[str, MessageHandler, str | None]] = []
+        self._started = False
 
     async def publish(
         self,
@@ -60,6 +61,10 @@ async def subscribe(
         group: str | None = None,
     ) -> None:
         self._handlers.append((topic, handler, group))
+        # The ApplicationContext starts adapter beans before @message_listener
+        # wiring subscribes, so a late subscription must bind its own queue now.
+        if self._started:
+            await self._start_consumer(topic, handler, group)
 
     async def start(self) -> None:
         import aio_pika
@@ -71,25 +76,33 @@ async def start(self) -> None:
         )
 
         for topic, handler, group in self._handlers:
-            queue_name = group or f"pyfly.{topic}"
-            queue = await self._channel.declare_queue(queue_name, durable=True)
-            await queue.bind(self._exchange, routing_key=topic)
-
-            async def on_message(
-                message: aio_pika.IncomingMessage,
-                _handler: MessageHandler = handler,
-                _topic: str = topic,
-            ) -> None:
-                async with message.process():
-                    msg = Message(
-                        topic=_topic,
-                        value=message.body,
-                        headers={k: str(v) for k, v in (message.headers or {}).items()},
-                    )
-                    await _handler(msg)
-
-            await queue.consume(on_message)
+            await self._start_consumer(topic, handler, group)
+
+        self._started = True
+
+    async def _start_consumer(self, topic: str, handler: MessageHandler, group: str | None) -> None:
+        import aio_pika
+
+        queue_name = group or f"pyfly.{topic}"
+        queue = await self._channel.declare_queue(queue_name, durable=True)
+        await queue.bind(self._exchange, routing_key=topic)
+
+        async def on_message(
+            message: aio_pika.IncomingMessage,
+            _handler: MessageHandler = handler,
+            _topic: str = topic,
+        ) -> None:
+            async with message.process():
+                msg = Message(
+                    topic=_topic,
+                    value=message.body,
+                    headers={k: str(v) for k, v in (message.headers or {}).items()},
+                )
+                await _handler(msg)
+
+        await queue.consume(on_message)
 
     async def stop(self) -> None:
+        self._started = False
         if self._connection is not None:
             await self._connection.close()
diff --git a/src/pyfly/notifications/providers/smtp.py b/src/pyfly/notifications/providers/smtp.py
index f3ab5f7..6f1bd57 100644
--- a/src/pyfly/notifications/providers/smtp.py
+++ b/src/pyfly/notifications/providers/smtp.py
@@ -39,6 +39,11 @@ def _send_blocking(self, message: EmailMessage) -> NotificationResult:
         msg["To"] = ", ".join(message.to)
         if message.cc:
             msg["Cc"] = ", ".join(message.cc)
+        # ``send_message`` reads recipients from the To/Cc/Bcc headers and
+        # strips the Bcc header before transmission, so BCC recipients are
+        # delivered without being exposed to other recipients.
+        if message.bcc:
+            msg["Bcc"] = ", ".join(message.bcc)
         msg["Subject"] = message.subject
         if message.body_text:
             msg.set_content(message.body_text)
diff --git a/src/pyfly/observability/correlation.py b/src/pyfly/observability/correlation.py
index 63a8fde..b3a59b8 100644
--- a/src/pyfly/observability/correlation.py
+++ b/src/pyfly/observability/correlation.py
@@ -47,21 +47,11 @@
 TRACEPARENT_HEADER = "traceparent"
 TRACESTATE_HEADER = "tracestate"
 
-_correlation_id: ContextVar[str | None] = ContextVar(
-    "pyfly_correlation_id", default=None
-)
-_request_id: ContextVar[str | None] = ContextVar(
-    "pyfly_request_id", default=None
-)
-_tenant_id: ContextVar[str | None] = ContextVar(
-    "pyfly_tenant_id", default=None
-)
-_traceparent: ContextVar[str | None] = ContextVar(
-    "pyfly_traceparent", default=None
-)
-_tracestate: ContextVar[str | None] = ContextVar(
-    "pyfly_tracestate", default=None
-)
+_correlation_id: ContextVar[str | None] = ContextVar("pyfly_correlation_id", default=None)
+_request_id: ContextVar[str | None] = ContextVar("pyfly_request_id", default=None)
+_tenant_id: ContextVar[str | None] = ContextVar("pyfly_tenant_id", default=None)
+_traceparent: ContextVar[str | None] = ContextVar("pyfly_traceparent", default=None)
+_tracestate: ContextVar[str | None] = ContextVar("pyfly_tracestate", default=None)
 
 
 def set_correlation_id(value: str | None) -> Token[str | None]:
diff --git a/src/pyfly/scheduling/task_scheduler.py b/src/pyfly/scheduling/task_scheduler.py
index 02834e9..87f5e0e 100644
--- a/src/pyfly/scheduling/task_scheduler.py
+++ b/src/pyfly/scheduling/task_scheduler.py
@@ -16,6 +16,7 @@
 from __future__ import annotations
 
 import asyncio
+import functools
 import inspect
 import logging
 from collections.abc import Callable
@@ -71,6 +72,12 @@ def discover(self, beans: list[Any]) -> int:
             for name in dir(bean):
                 if name.startswith("_"):
                     continue
+                # Look up statically first so @property / cached_property getters
+                # are never evaluated during discovery — a side-effecting or
+                # raising property must not break scheduled-task scanning.
+                static_attr = inspect.getattr_static(bean, name, None)
+                if isinstance(static_attr, (property, functools.cached_property)):
+                    continue
                 try:
                     attr = getattr(bean, name)
                 except Exception:  # noqa: BLE001
@@ -183,7 +190,12 @@ async def _run_fixed_delay_loop(
             await asyncio.sleep(initial_delay.total_seconds())
         while self._running:
             task = await self._executor.submit(self._invoke(bean, method))
-            await task  # Wait for completion
+            try:
+                await task  # Wait for completion
+            except Exception:
+                # A failing iteration must not permanently kill the loop —
+                # match the fault tolerance of cron/fixed_rate scheduling.
+                logger.exception("scheduled fixed_delay task failed; continuing")
             if not self._running:
                 break
             await asyncio.sleep(delay.total_seconds())
diff --git a/src/pyfly/transactional/rest/controllers.py b/src/pyfly/transactional/rest/controllers.py
index 50c5e7c..4e7ec54 100644
--- a/src/pyfly/transactional/rest/controllers.py
+++ b/src/pyfly/transactional/rest/controllers.py
@@ -13,16 +13,22 @@
 # limitations under the License.
 """Framework-agnostic controller classes — bind into Starlette/FastAPI elsewhere.
 
-Each controller is a *plain class* with async methods that return
-JSON-serializable dicts.  The pyfly web auto-configuration takes care of
-mapping HTTP verbs / paths to those methods, but the controllers themselves
-have no hard dependency on Starlette so they remain easy to unit-test.
+Each controller is a ``@rest_controller`` bean with async methods that return
+JSON-serializable dicts.  Routing is declared with pure-metadata decorators
+(``@request_mapping`` / ``@get_mapping`` / ``@post_mapping`` / ``@delete_mapping``)
+and parameter binders (``PathVar`` / ``QueryParam`` / ``Body`` / ``Valid``).
+Those decorators add no runtime dependency on Starlette, so the transactional
+module stays decoupled from any concrete web adapter while still being
+discovered and mounted by the ``ControllerRegistrar``.
 """
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
+from pydantic import BaseModel
+
+from pyfly.container import rest_controller
 from pyfly.transactional.core.dlq import DeadLetterEntry, DeadLetterService
 from pyfly.transactional.core.model import ExecutionStatus
 from pyfly.transactional.core.persistence import (
@@ -30,6 +36,31 @@
     ExecutionState,
 )
 from pyfly.transactional.workflow.engine import WorkflowEngine
+from pyfly.web import (
+    Body,
+    PathVar,
+    QueryParam,
+    Valid,
+    delete_mapping,
+    get_mapping,
+    post_mapping,
+    request_mapping,
+)
+
+
+class StartRequest(BaseModel):
+    """Request body for :meth:`WorkflowController.start`."""
+
+    workflow_id: str
+    input: Any = None
+
+
+class SignalRequest(BaseModel):
+    """Request body for :meth:`WorkflowController.signal`."""
+
+    correlation_id: str
+    signal: str
+    payload: Any = None
 
 
 def _state_to_dict(state: ExecutionState) -> dict[str, Any]:
@@ -57,6 +88,8 @@ def _dlq_to_dict(entry: DeadLetterEntry) -> dict[str, Any]:
     }
 
 
+@rest_controller
+@request_mapping("/api/orchestration")
 class OrchestrationController:
     """``GET /api/orchestration/executions`` — surface persisted runs."""
 
@@ -65,16 +98,22 @@ class OrchestrationController:
     def __init__(self, persistence: ExecutionPersistenceProvider) -> None:
         self._persistence = persistence
 
-    async def list_executions(self, status: str | None = None) -> list[dict[str, Any]]:
-        status_enum = ExecutionStatus(status) if status else None
+    @get_mapping("/executions")
+    async def list_executions(self, status: QueryParam[str]) -> list[dict[str, Any]]:
+        status_str = cast("str | None", status)
+        status_enum = ExecutionStatus(status_str) if status_str else None
         states = await self._persistence.find_all(status=status_enum)
         return [_state_to_dict(s) for s in states]
 
-    async def get_execution(self, correlation_id: str) -> dict[str, Any] | None:
-        state = await self._persistence.find(correlation_id)
+    @get_mapping("/executions/{correlation_id}")
+    async def get_execution(self, correlation_id: PathVar[str]) -> dict[str, Any] | None:
+        cid = cast(str, correlation_id)
+        state = await self._persistence.find(cid)
         return _state_to_dict(state) if state is not None else None
 
 
+@rest_controller
+@request_mapping("/api/orchestration/dlq")
 class DeadLetterController:
     """``/api/orchestration/dlq`` — list, retry and delete dead-lettered runs."""
 
@@ -83,23 +122,38 @@ class DeadLetterController:
     def __init__(self, dlq: DeadLetterService) -> None:
         self._dlq = dlq
 
-    async def list(self, execution_name: str | None = None, correlation_id: str | None = None) -> list[dict[str, Any]]:
-        entries = await self._dlq.list(execution_name=execution_name, correlation_id=correlation_id)
+    @get_mapping("")
+    async def list(
+        self,
+        execution_name: QueryParam[str],
+        correlation_id: QueryParam[str],
+    ) -> list[dict[str, Any]]:
+        name = cast("str | None", execution_name)
+        cid = cast("str | None", correlation_id)
+        entries = await self._dlq.list(execution_name=name, correlation_id=cid)
         return [_dlq_to_dict(e) for e in entries]
 
-    async def get(self, entry_id: str) -> dict[str, Any] | None:
-        entry = await self._dlq.get(entry_id)
+    @get_mapping("/{entry_id}")
+    async def get(self, entry_id: PathVar[str]) -> dict[str, Any] | None:
+        eid = cast(str, entry_id)
+        entry = await self._dlq.get(eid)
         return _dlq_to_dict(entry) if entry is not None else None
 
-    async def retry(self, entry_id: str) -> dict[str, Any]:
-        ok = await self._dlq.mark_retried(entry_id)
+    @post_mapping("/{entry_id}/retry")
+    async def retry(self, entry_id: PathVar[str]) -> dict[str, Any]:
+        eid = cast(str, entry_id)
+        ok = await self._dlq.mark_retried(eid)
         return {"retried": ok}
 
-    async def delete(self, entry_id: str) -> dict[str, Any]:
-        ok = await self._dlq.delete(entry_id)
+    @delete_mapping("/{entry_id}")
+    async def delete(self, entry_id: PathVar[str]) -> dict[str, Any]:
+        eid = cast(str, entry_id)
+        ok = await self._dlq.delete(eid)
         return {"deleted": ok}
 
 
+@rest_controller
+@request_mapping("/api/orchestration/workflow")
 class WorkflowController:
     """``/api/orchestration/workflow`` — start workflows / deliver signals."""
 
@@ -108,8 +162,10 @@ class WorkflowController:
     def __init__(self, engine: WorkflowEngine) -> None:
         self._engine = engine
 
-    async def start(self, workflow_id: str, input: Any = None) -> dict[str, Any]:
-        result = await self._engine.start(workflow_id, input)
+    @post_mapping("/start")
+    async def start(self, body: Valid[Body[StartRequest]]) -> dict[str, Any]:
+        req = cast(StartRequest, body)
+        result = await self._engine.start(req.workflow_id, req.input)
         return {
             "workflow_id": result.workflow_id,
             "correlation_id": result.correlation_id,
@@ -121,8 +177,10 @@ async def start(self, workflow_id: str, input: Any = None) -> dict[str, Any]:
             "error": result.error,
         }
 
-    async def signal(self, correlation_id: str, signal: str, payload: Any = None) -> dict[str, Any]:
-        ok = await self._engine.deliver_signal(correlation_id, signal, payload)
+    @post_mapping("/signal")
+    async def signal(self, body: Valid[Body[SignalRequest]]) -> dict[str, Any]:
+        req = cast(SignalRequest, body)
+        ok = await self._engine.deliver_signal(req.correlation_id, req.signal, req.payload)
         return {"delivered": ok}
 
     async def query(self, correlation_id: str, query: str, **kwargs: Any) -> Any:
diff --git a/src/pyfly/transactional/saga/engine/compensator.py b/src/pyfly/transactional/saga/engine/compensator.py
index 916b271..ba79b32 100644
--- a/src/pyfly/transactional/saga/engine/compensator.py
+++ b/src/pyfly/transactional/saga/engine/compensator.py
@@ -28,7 +28,7 @@
 import logging
 from typing import TYPE_CHECKING
 
-from pyfly.transactional.shared.types import CompensationPolicy
+from pyfly.transactional.shared.types import CompensationPolicy, StepStatus
 
 if TYPE_CHECKING:
     from pyfly.transactional.saga.core.context import SagaContext
@@ -242,11 +242,13 @@ async def _best_effort_parallel(
 
         async def _compensate_one(sd: StepDefinition) -> Exception | None:
             try:
-                await self._step_invoker.invoke_compensation(
+                result = await self._step_invoker.invoke_compensation(
                     sd,
                     saga_def.bean,
                     ctx,
                 )
+                ctx.compensation_results[sd.id] = result
+                ctx.set_step_status(sd.id, StepStatus.COMPENSATED)
                 await self._emit_compensated(saga_name, sd.id, ctx, error=None)
                 return None
             except Exception as exc:  # noqa: BLE001
@@ -290,11 +292,13 @@ async def _invoke_one(
     ) -> None:
         """Invoke a single compensation, emit events, and optionally handle errors."""
         try:
-            await self._step_invoker.invoke_compensation(
+            result = await self._step_invoker.invoke_compensation(
                 step_def,
                 saga_def.bean,
                 ctx,
             )
+            ctx.compensation_results[step_def.id] = result
+            ctx.set_step_status(step_def.id, StepStatus.COMPENSATED)
             await self._emit_compensated(saga_name, step_def.id, ctx, error=None)
         except Exception as exc:
             await self._emit_compensated(saga_name, step_def.id, ctx, error=exc)
diff --git a/src/pyfly/transactional/saga/engine/saga_engine.py b/src/pyfly/transactional/saga/engine/saga_engine.py
index 9b2e132..9f22bdc 100644
--- a/src/pyfly/transactional/saga/engine/saga_engine.py
+++ b/src/pyfly/transactional/saga/engine/saga_engine.py
@@ -109,7 +109,11 @@ async def execute(
                     "saga_name": saga_name,
                     "correlation_id": ctx.correlation_id,
                     "headers": ctx.headers,
-                    "started_at": started_at.isoformat(),
+                    # Store the datetime itself (not an ISO string) so the
+                    # persistence port's get_stale() can compare it against a
+                    # datetime cutoff — passing a string raised TypeError during
+                    # stale-saga recovery.
+                    "started_at": started_at,
                 }
             )
 
diff --git a/src/pyfly/transactional/shared/persistence/memory.py b/src/pyfly/transactional/shared/persistence/memory.py
index 196d6d2..487f440 100644
--- a/src/pyfly/transactional/shared/persistence/memory.py
+++ b/src/pyfly/transactional/shared/persistence/memory.py
@@ -99,9 +99,26 @@ async def get_in_flight(self) -> list[dict[str, Any]]:
             return [s for s in self._store.values() if s.get("status") == "IN_FLIGHT"]
 
     async def get_stale(self, before: datetime) -> list[dict[str, Any]]:
-        """Return transactions whose ``started_at`` is older than *before*."""
+        """Return transactions whose ``started_at`` is older than *before*.
+
+        Tolerates ``started_at`` stored as either a ``datetime`` or an ISO-8601
+        string so a comparison never raises ``TypeError`` regardless of how the
+        caller persisted it.
+        """
         async with self._lock:
-            return [s for s in self._store.values() if s.get("started_at") is not None and s["started_at"] < before]
+            stale: list[dict[str, Any]] = []
+            for s in self._store.values():
+                started = s.get("started_at")
+                if started is None:
+                    continue
+                if isinstance(started, str):
+                    try:
+                        started = datetime.fromisoformat(started)
+                    except ValueError:
+                        continue
+                if started < before:
+                    stale.append(s)
+            return stale
 
     # -- maintenance --------------------------------------------------------
 
diff --git a/src/pyfly/transactional/workflow/child_workflow_service.py b/src/pyfly/transactional/workflow/child_workflow_service.py
index eb28f60..ab78e6e 100644
--- a/src/pyfly/transactional/workflow/child_workflow_service.py
+++ b/src/pyfly/transactional/workflow/child_workflow_service.py
@@ -59,10 +59,8 @@ async def start(
             if timeout_ms > 0:
                 return await asyncio.wait_for(coro, timeout=timeout_ms / 1000.0)
             return await coro
-        # Fire and forget: schedule and return placeholder correlation id.
-        task = asyncio.create_task(self._engine.start(workflow_id, input))
-        # Allow the new task to begin so it can populate its correlation id;
-        # we then return the (possibly synthetic) id.  In practice the engine
-        # generates the id eagerly and stores it, so we can reach in.
-        await asyncio.sleep(0)
-        return getattr(task, "get_name", lambda: "unknown")()
+        # Fire and forget: the engine eagerly creates the child's ExecutionContext
+        # and schedules the run in the background, returning the real child
+        # correlation id (previously this returned the asyncio Task name).
+        result = await self._engine.start_async(workflow_id, input)
+        return result.correlation_id
diff --git a/src/pyfly/transactional/workflow/definition.py b/src/pyfly/transactional/workflow/definition.py
index b5a2fa1..3a432e4 100644
--- a/src/pyfly/transactional/workflow/definition.py
+++ b/src/pyfly/transactional/workflow/definition.py
@@ -42,7 +42,9 @@ class WorkflowStepDefinition:
     wait_for_signal_timeout_ms: int = 0
     wait_for_timer_ms: int = 0
     wait_for_all: tuple[str, ...] = ()
+    wait_for_all_timeout_ms: int = 0
     wait_for_any: tuple[str, ...] = ()
+    wait_for_any_timeout_ms: int = 0
     child_workflow_id: str | None = None
     child_wait_for_completion: bool = True
     child_timeout_ms: int = 0
diff --git a/src/pyfly/transactional/workflow/engine.py b/src/pyfly/transactional/workflow/engine.py
index edffc44..e7adbf4 100644
--- a/src/pyfly/transactional/workflow/engine.py
+++ b/src/pyfly/transactional/workflow/engine.py
@@ -98,6 +98,20 @@ async def start(self, workflow_id: str, input: Any = None) -> WorkflowResult:
 
         return await self._run(definition, input)
 
+    async def start_async(self, workflow_id: str, input: Any = None) -> WorkflowResult:
+        """Start a workflow fire-and-forget.
+
+        Returns immediately with a :class:`WorkflowResult` carrying the child's
+        real ``correlation_id`` (status PENDING); the run continues in the
+        background. Use this instead of scheduling :meth:`start` as a bare task
+        when you need the correlation id up front (e.g. child workflows).
+        """
+        definition = self._registry.get(workflow_id)
+        if definition is None:
+            msg = f"unknown workflow '{workflow_id}'"
+            raise OrchestrationError(msg)
+        return await self._start_async(definition, input)
+
     async def deliver_signal(self, correlation_id: str, signal: str, payload: Any = None) -> bool:
         return await self._signals.deliver(correlation_id, signal, payload)
 
diff --git a/src/pyfly/transactional/workflow/executor.py b/src/pyfly/transactional/workflow/executor.py
index 194839e..d7ea196 100644
--- a/src/pyfly/transactional/workflow/executor.py
+++ b/src/pyfly/transactional/workflow/executor.py
@@ -21,6 +21,8 @@
 from __future__ import annotations
 
 import asyncio
+import inspect
+import logging
 import time
 from typing import Any
 
@@ -42,6 +44,8 @@
 from pyfly.transactional.workflow.signal_service import SignalService
 from pyfly.transactional.workflow.timer_service import TimerService
 
+_logger = logging.getLogger(__name__)
+
 
 class WorkflowExecutor:
     """Layer-by-layer execution engine for a single workflow run."""
@@ -57,6 +61,11 @@ def __init__(
         backpressure: BackpressureStrategy | None = None,
     ) -> None:
         self._invoker = step_invoker or StepInvoker(ArgumentResolver())
+        # Dedicated resolver for compensation calls (mirrors the invoker's own
+        # resolver). Compensation methods are invoked directly — without retry,
+        # timeout, or step-record mutation — so they cannot clobber the
+        # already-recorded success of the step they roll back.
+        self._compensation_resolver = ArgumentResolver()
         self._signals = signal_service or SignalService()
         self._timers = timer_service or TimerService()
         self._children = child_service or ChildWorkflowService()
@@ -64,11 +73,82 @@ def __init__(
         self._backpressure = backpressure or AdaptiveBackpressureStrategy()
 
     async def execute(self, definition: WorkflowDefinition, ctx: ExecutionContext) -> None:
-        """Run all steps respecting their dependency graph."""
+        """Run all steps respecting their dependency graph.
+
+        On any step failure, already-completed *compensatable* steps are rolled
+        back (in reverse execution order) before the original error propagates.
+        """
         layers = TopologyBuilder.build_layers(definition.graph())
+        try:
+            for layer in layers:
+                steps = [definition.steps[sid] for sid in layer]
+                await self._execute_layer(definition, ctx, steps)
+        except BaseException as exc:
+            await self._compensate(definition, ctx, layers, exc)
+            raise
+
+    async def _compensate(
+        self,
+        definition: WorkflowDefinition,
+        ctx: ExecutionContext,
+        layers: list[list[str]],
+        error: BaseException,
+    ) -> None:
+        """Roll back completed compensatable steps in reverse execution order.
+
+        The set of completed steps is derived from the context (a step may have
+        succeeded concurrently with the one that failed), and ordered using the
+        topology layers so compensation runs newest-first. Compensation errors
+        are recorded and surfaced via events but never mask the original
+        failure that triggered the rollback.
+        """
+        completed_ids: list[str] = []
         for layer in layers:
-            steps = [definition.steps[sid] for sid in layer]
-            await self._execute_layer(definition, ctx, steps)
+            for step_id in layer:
+                step = definition.steps.get(step_id)
+                if step is None or not step.compensatable or step.compensation_method is None:
+                    continue
+                if ctx.is_step_done(step_id):
+                    completed_ids.append(step_id)
+
+        if not completed_ids:
+            return
+
+        await self._events.on_compensation_started(name=definition.id, correlation_id=ctx.correlation_id)
+
+        for step_id in reversed(completed_ids):
+            step = definition.steps[step_id]
+            method = step.compensation_method
+            assert method is not None  # filtered above
+            comp_error: BaseException | None = None
+            comp_result: Any = None
+            try:
+                kwargs = self._compensation_resolver.resolve(
+                    method,
+                    ctx,
+                    compensation_error=error,
+                    skip_first=definition.bean is not None,
+                )
+                call = method(definition.bean, **kwargs)
+                if inspect.isawaitable(call):
+                    comp_result = await call
+                else:
+                    comp_result = call
+            except Exception as exc:  # noqa: BLE001
+                comp_error = exc
+                _logger.warning(
+                    "compensation for %s.%s failed: %s",
+                    definition.id,
+                    step_id,
+                    exc,
+                )
+            await ctx.record_step_compensated(step_id, comp_result, comp_error)
+            await self._events.on_step_compensated(
+                name=definition.id,
+                correlation_id=ctx.correlation_id,
+                step_id=step_id,
+                error=comp_error,
+            )
 
     async def _execute_layer(
         self,
@@ -111,12 +191,11 @@ async def _run_step(
 
         if step.wait_for_all:
             for sig in step.wait_for_all:
-                await ctx.wait_for_signal(sig, step.wait_for_signal_timeout_ms)
+                await ctx.wait_for_signal(sig, step.wait_for_all_timeout_ms)
 
         if step.wait_for_any:
             tasks = [
-                asyncio.create_task(ctx.wait_for_signal(sig, step.wait_for_signal_timeout_ms))
-                for sig in step.wait_for_any
+                asyncio.create_task(ctx.wait_for_signal(sig, step.wait_for_any_timeout_ms)) for sig in step.wait_for_any
             ]
             done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
             for t in pending:
diff --git a/src/pyfly/transactional/workflow/registry.py b/src/pyfly/transactional/workflow/registry.py
index 87f418d..a9f049c 100644
--- a/src/pyfly/transactional/workflow/registry.py
+++ b/src/pyfly/transactional/workflow/registry.py
@@ -83,9 +83,11 @@ def register_from_bean(self, bean: Any) -> WorkflowDefinition:
                 wait_all = getattr(attr, "__pyfly_workflow_wait_all__", None)
                 if wait_all is not None:
                     step.wait_for_all = wait_all.signals
+                    step.wait_for_all_timeout_ms = wait_all.timeout_ms
                 wait_any = getattr(attr, "__pyfly_workflow_wait_any__", None)
                 if wait_any is not None:
                     step.wait_for_any = wait_any.signals
+                    step.wait_for_any_timeout_ms = wait_any.timeout_ms
                 child = getattr(attr, "__pyfly_workflow_child__", None)
                 if child is not None:
                     step.child_workflow_id = child.workflow_id
diff --git a/src/pyfly/web/adapters/fastapi/app.py b/src/pyfly/web/adapters/fastapi/app.py
index 8943728..9f36a75 100644
--- a/src/pyfly/web/adapters/fastapi/app.py
+++ b/src/pyfly/web/adapters/fastapi/app.py
@@ -16,6 +16,7 @@
 from __future__ import annotations
 
 import contextlib
+from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING
 
 from fastapi import FastAPI
@@ -28,10 +29,12 @@
 from pyfly.web.adapters.starlette.filter_chain import WebFilterChainMiddleware
 from pyfly.web.adapters.starlette.filters import (
     CorrelationFilter,
+    RequestContextFilter,
     RequestLoggingFilter,
     SecurityHeadersFilter,
     TransactionIdFilter,
 )
+from pyfly.web.openapi import OpenAPIGenerator
 from pyfly.web.ports.filter import WebFilter
 
 if TYPE_CHECKING:
@@ -57,8 +60,12 @@ def create_app(
     and mounts their routes.  Also auto-discovers user ``WebFilter``,
     ``ActuatorEndpoint``, ``@websocket_mapping``, and ``@sse_mapping`` beans.
 
-    FastAPI provides built-in OpenAPI docs (Swagger UI at ``/docs``, ReDoc at
-    ``/redoc``), so no custom OpenAPI generator is needed.
+    FastAPI's own introspection cannot read the PyFly parameter-binding metadata
+    on controller handlers, so controller routes are registered with
+    ``include_in_schema=False`` and the OpenAPI document is generated with the
+    same :class:`pyfly.web.openapi.OpenAPIGenerator` machinery used by the
+    Starlette adapter. FastAPI's built-in ``/docs`` and ``/redoc`` pages still
+    render, but read from this generated spec.
 
     Includes:
     - WebFilter chain (transaction ID, request logging, security headers, + user filters)
@@ -70,13 +77,31 @@ def create_app(
     - WebSocket routes (auto-discovered from @websocket_mapping)
     - SSE routes (auto-discovered from @sse_mapping)
     """
+    # Detect the admin dashboard early so its HTTP trace collector can join the
+    # filter chain here (before ApplicationContext.start() instantiates beans).
+    # See the Starlette adapter for the full rationale.
+    admin_enabled = False
+    if context is not None:
+        admin_enabled = str(context.config.get("pyfly.admin.enabled", "false")).lower() in ("true", "1", "yes")
+
+    admin_trace_collector = None
+    if admin_enabled:
+        from pyfly.admin.middleware.trace_collector import TraceCollectorFilter
+
+        admin_trace_collector = TraceCollectorFilter()
+
     # --- Build the WebFilter chain ---
+    # RequestContextFilter runs first (HIGHEST_PRECEDENCE) so REQUEST-scoped beans
+    # and @pre_authorize/@post_authorize have a live RequestContext to read.
     filters: list[WebFilter] = [
+        RequestContextFilter(),
         CorrelationFilter(),
         TransactionIdFilter(),
         RequestLoggingFilter(),
         SecurityHeadersFilter(),
     ]
+    if admin_trace_collector is not None:
+        filters.append(admin_trace_collector)
 
     # Auto-discover user WebFilter beans from context
     if context is not None:
@@ -86,7 +111,13 @@ def create_app(
                 and isinstance(reg.instance, WebFilter)
                 and not isinstance(
                     reg.instance,
-                    (CorrelationFilter, TransactionIdFilter, RequestLoggingFilter, SecurityHeadersFilter),
+                    (
+                        RequestContextFilter,
+                        CorrelationFilter,
+                        TransactionIdFilter,
+                        RequestLoggingFilter,
+                        SecurityHeadersFilter,
+                    ),
                 )
             ):
                 filters.append(reg.instance)
@@ -130,9 +161,11 @@ def create_app(
         lifespan=lifespan,  # type: ignore[arg-type]
     )
 
-    # Auto-discover and register controller routes from ApplicationContext
+    # Auto-discover and register controller routes from ApplicationContext.
+    # Routes are registered with include_in_schema=False; the OpenAPI document
+    # is built below from collected route metadata instead.
+    registrar = FastAPIControllerRegistrar()
     if context is not None:
-        registrar = FastAPIControllerRegistrar()
         registrar.register_controllers(app, context)
 
     # Auto-discover WebSocket routes from ApplicationContext
@@ -196,6 +229,21 @@ def _install_indicators() -> None:
         _install_indicators()
         app.state.pyfly_install_health_indicators = _install_indicators
 
+        # Beans (incl. health indicators) are instantiated by the lifespan's
+        # startup, after this factory returns. Wrap the app's lifespan context
+        # so the indicator rescan runs once startup completes — otherwise
+        # /actuator/health reports UP even when a subsystem is DOWN.
+        if lifespan is not None:
+            _inner_lifespan_ctx = app.router.lifespan_context
+
+            @contextlib.asynccontextmanager
+            async def _lifespan_with_indicator_rescan(app_: FastAPI) -> AsyncIterator[None]:
+                async with _inner_lifespan_ctx(app_):
+                    _install_indicators()
+                    yield
+
+            app.router.lifespan_context = _lifespan_with_indicator_rescan
+
         config = context.config if context is not None else None
         registry = ActuatorRegistry(config=config)
 
@@ -214,19 +262,10 @@ def _install_indicators() -> None:
 
         app.routes.extend(make_starlette_actuator_routes(registry))
 
-    # Mount admin dashboard when enabled
-    admin_enabled = False
-    if context is not None:
-        admin_enabled = str(context.config.get("pyfly.admin.enabled", "false")).lower() in (
-            "true",
-            "1",
-            "yes",
-        )
-
+    # Mount admin dashboard when enabled (admin_enabled computed above)
     if admin_enabled and context is not None:
         from pyfly.admin.adapters.starlette import AdminRouteBuilder
         from pyfly.admin.config import AdminProperties
-        from pyfly.admin.middleware.trace_collector import TraceCollectorFilter
         from pyfly.admin.providers.beans_provider import BeansProvider
         from pyfly.admin.providers.cache_provider import CacheProvider
         from pyfly.admin.providers.config_provider import ConfigProvider
@@ -249,12 +288,8 @@ def _install_indicators() -> None:
         with contextlib.suppress(Exception):
             admin_props = context.config.bind(AdminProperties)
 
-        # Find trace collector from context (registered by auto-config)
-        trace_collector = None
-        for _cls, reg in context.container._registrations.items():
-            if reg.instance is not None and isinstance(reg.instance, TraceCollectorFilter):
-                trace_collector = reg.instance
-                break
+        # Use the trace collector created above and wired into the filter chain.
+        trace_collector = admin_trace_collector
 
         # Find view registry from context
         view_registry = AdminViewRegistry()
@@ -275,18 +310,6 @@ def _install_indicators() -> None:
                     indicator_name = reg.name or cls.__name__
                     health_agg.add_indicator(indicator_name, reg.instance)
 
-        # Find server adapter from context for admin dashboard
-        server_adapter = None
-        try:
-            from pyfly.server.ports.outbound import ApplicationServerPort
-
-            for _cls, reg in context.container._registrations.items():
-                if reg.instance is not None and isinstance(reg.instance, ApplicationServerPort):
-                    server_adapter = reg.instance
-                    break
-        except ImportError:
-            pass
-
         admin_builder = AdminRouteBuilder(
             properties=admin_props,
             overview=OverviewProvider(context, health_agg),
@@ -306,14 +329,35 @@ def _install_indicators() -> None:
             trace_collector=trace_collector,
             logfile=LogfileProvider(context),
             runtime=RuntimeProvider(),
-            server=ServerProvider(server_adapter),
+            server=ServerProvider(context=context),
         )
         app.routes.extend(admin_builder.build_routes())
 
     # Register global exception handler
     register_exception_handlers(app)
 
+    # Collect route metadata (used for OpenAPI generation and startup logging)
+    route_metadata = registrar.collect_route_metadata(context) if context is not None else []
+
+    # Generate the OpenAPI spec ourselves. FastAPI's built-in introspection
+    # cannot read PyFly's parameter-binding metadata (controller routes are
+    # registered with include_in_schema=False), so we override ``app.openapi``
+    # to serve the spec produced by ``OpenAPIGenerator`` from the collected
+    # route metadata. FastAPI's ``/openapi.json``, ``/docs``, and ``/redoc``
+    # routes then render from this spec — all guarded by ``docs_enabled`` via
+    # the ``openapi_url``/``docs_url``/``redoc_url`` set on the constructor.
+    if docs_enabled:
+        generator = OpenAPIGenerator(title=title, version=version, description=description)
+        spec = generator.generate(route_metadata or None)
+
+        def _custom_openapi() -> dict[str, object]:
+            app.openapi_schema = spec
+            return spec
+
+        app.openapi = _custom_openapi  # type: ignore[method-assign]
+
     # Store metadata for startup logging
+    app.state.pyfly_route_metadata = route_metadata
     app.state.pyfly_docs_enabled = docs_enabled
 
     return app
diff --git a/src/pyfly/web/adapters/fastapi/controller.py b/src/pyfly/web/adapters/fastapi/controller.py
index 1f92921..3be1ea9 100644
--- a/src/pyfly/web/adapters/fastapi/controller.py
+++ b/src/pyfly/web/adapters/fastapi/controller.py
@@ -21,6 +21,7 @@
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
 
+from pyfly.web.adapters.starlette.controller import ControllerRegistrar, RouteMetadata
 from pyfly.web.adapters.starlette.resolver import ParameterResolver
 from pyfly.web.adapters.starlette.response import handle_return_value
 
@@ -43,16 +44,27 @@ class FastAPIControllerRegistrar:
 
     Reuses the Starlette :class:`ParameterResolver` and :func:`handle_return_value`
     since FastAPI extends Starlette.
+
+    Also collects ``@controller_advice`` beans for global exception handling.
     """
 
     _CONTROLLER_STEREOTYPES = ("rest_controller", "controller")
 
+    def __init__(self) -> None:
+        self._global_exception_handlers: dict[type[Exception], Any] | None = None
+
     def register_controllers(self, app: Any, ctx: Any) -> None:
         """Discover all ``@rest_controller`` and ``@controller`` beans and register routes.
 
         Bean resolution is deferred until the first HTTP request hits each
         controller, avoiding eager resolution of the full dependency tree
         during ``create_app()`` (before auto-configurations have run).
+
+        Routes are registered with ``include_in_schema=False`` because FastAPI's
+        own introspection cannot read the PyFly parameter-binding metadata and
+        would emit an empty/useless schema. The real OpenAPI document is built by
+        the application factory using :class:`pyfly.web.openapi.OpenAPIGenerator`
+        together with :meth:`collect_route_metadata`.
         """
         for cls, _reg in ctx.container._registrations.items():
             if getattr(cls, "__pyfly_stereotype__", "") not in self._CONTROLLER_STEREOTYPES:
@@ -79,9 +91,19 @@ def register_controllers(self, app: Any, ctx: Any) -> None:
                     handler,
                     methods=[http_method],
                     status_code=status_code,
-                    include_in_schema=True,
+                    include_in_schema=False,
                 )
 
+    def collect_route_metadata(self, ctx: Any) -> list[RouteMetadata]:
+        """Collect route metadata from ``@rest_controller`` and ``@controller`` classes.
+
+        Delegates to the Starlette :class:`ControllerRegistrar`. The metadata is
+        derived purely from class-level type hints, mappings, and docstrings (no
+        bean resolution), so it is adapter-agnostic and reused as-is to feed the
+        :class:`pyfly.web.openapi.OpenAPIGenerator`.
+        """
+        return ControllerRegistrar().collect_route_metadata(ctx)
+
     def _collect_exception_handlers(self, instance: Any) -> dict[type[Exception], Any]:
         """Collect all @exception_handler methods from a controller instance.
 
@@ -98,6 +120,28 @@ def _collect_exception_handlers(self, instance: Any) -> dict[type[Exception], An
                 handlers[exc_type] = method
         return dict(sorted(handlers.items(), key=lambda item: len(item[0].__mro__), reverse=True))
 
+    def _collect_global_advice_handlers(self, ctx: Any) -> dict[type[Exception], Any]:
+        """Collect @exception_handler methods from all @controller_advice beans.
+
+        Handlers are sorted by MRO depth (most specific first). Controller-local
+        handlers always take priority over global advice.
+        """
+        handlers: dict[type[Exception], Any] = {}
+        for cls, reg in ctx.container._registrations.items():
+            if getattr(cls, "__pyfly_stereotype__", "") != "controller_advice":
+                continue
+            instance = reg.instance
+            if instance is None:
+                instance = ctx.get_bean(cls)
+            handlers.update(self._collect_exception_handlers(instance))
+        return dict(sorted(handlers.items(), key=lambda item: len(item[0].__mro__), reverse=True))
+
+    def _get_global_advice_handlers(self, ctx: Any) -> dict[type[Exception], Any]:
+        """Return cached global advice handlers, collecting on first call."""
+        if self._global_exception_handlers is None:
+            self._global_exception_handlers = self._collect_global_advice_handlers(ctx)
+        return self._global_exception_handlers
+
     def _make_lazy_handler(
         self,
         ctx: Any,
@@ -120,12 +164,20 @@ async def lazy_endpoint(request: Request) -> Response:
                 result = await _maybe_await(_cache["method"](**kwargs))
                 return handle_return_value(result, status_code)
             except Exception as exc:
+                # 1. Check controller-local exception handlers
                 for exc_type, handler in _cache["exc_handlers"].items():
                     if isinstance(exc, exc_type):
                         result = await _maybe_await(handler(exc))
                         if isinstance(result, tuple) and len(result) == 2:
                             return JSONResponse(result[1], status_code=result[0])
                         return handle_return_value(result)
+                # 2. Check global @controller_advice exception handlers
+                for exc_type, handler in self._get_global_advice_handlers(ctx).items():
+                    if isinstance(exc, exc_type):
+                        result = await _maybe_await(handler(exc))
+                        if isinstance(result, tuple) and len(result) == 2:
+                            return JSONResponse(result[1], status_code=result[0])
+                        return handle_return_value(result)
                 raise
 
         return lazy_endpoint
diff --git a/src/pyfly/web/adapters/starlette/app.py b/src/pyfly/web/adapters/starlette/app.py
index 5b7bbf0..9267b61 100644
--- a/src/pyfly/web/adapters/starlette/app.py
+++ b/src/pyfly/web/adapters/starlette/app.py
@@ -16,6 +16,7 @@
 from __future__ import annotations
 
 import contextlib
+from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING
 
 from starlette.applications import Starlette
@@ -33,6 +34,7 @@
 from pyfly.web.adapters.starlette.filter_chain import WebFilterChainMiddleware
 from pyfly.web.adapters.starlette.filters import (
     CorrelationFilter,
+    RequestContextFilter,
     RequestLoggingFilter,
     SecurityHeadersFilter,
     TransactionIdFilter,
@@ -73,13 +75,34 @@ def create_app(
     - WebSocket routes (auto-discovered from @websocket_mapping)
     - SSE routes (auto-discovered from @sse_mapping)
     """
+    # Detect the admin dashboard early. Its HTTP trace collector is a WebFilter
+    # that must join the chain *here*, while the ASGI middleware is being
+    # assembled — which happens before ``ApplicationContext.start()`` runs. The
+    # auto-configuration bean for it is therefore not yet instantiated, so we
+    # create and own the instance directly and hand the same object to the
+    # admin route providers below.
+    admin_enabled = False
+    if context is not None:
+        admin_enabled = str(context.config.get("pyfly.admin.enabled", "false")).lower() in ("true", "1", "yes")
+
+    admin_trace_collector = None
+    if admin_enabled:
+        from pyfly.admin.middleware.trace_collector import TraceCollectorFilter
+
+        admin_trace_collector = TraceCollectorFilter()
+
     # --- Build the WebFilter chain ---
+    # RequestContextFilter runs first (HIGHEST_PRECEDENCE) so REQUEST-scoped beans
+    # and @pre_authorize/@post_authorize have a live RequestContext to read.
     filters: list[WebFilter] = [
+        RequestContextFilter(),
         CorrelationFilter(),
         TransactionIdFilter(),
         RequestLoggingFilter(),
         SecurityHeadersFilter(),
     ]
+    if admin_trace_collector is not None:
+        filters.append(admin_trace_collector)
 
     # Auto-discover user WebFilter beans from context
     if context is not None:
@@ -89,7 +112,13 @@ def create_app(
                 and isinstance(reg.instance, WebFilter)
                 and not isinstance(
                     reg.instance,
-                    (CorrelationFilter, TransactionIdFilter, RequestLoggingFilter, SecurityHeadersFilter),
+                    (
+                        RequestContextFilter,
+                        CorrelationFilter,
+                        TransactionIdFilter,
+                        RequestLoggingFilter,
+                        SecurityHeadersFilter,
+                    ),
                 )
             ):
                 filters.append(reg.instance)
@@ -207,15 +236,10 @@ def _install_indicators() -> None:
 
         routes.extend(make_starlette_actuator_routes(registry))
 
-    # Mount admin dashboard when enabled
-    admin_enabled = False
-    if context is not None:
-        admin_enabled = str(context.config.get("pyfly.admin.enabled", "false")).lower() in ("true", "1", "yes")
-
+    # Mount admin dashboard when enabled (admin_enabled computed above)
     if admin_enabled and context is not None:
         from pyfly.admin.adapters.starlette import AdminRouteBuilder
         from pyfly.admin.config import AdminProperties
-        from pyfly.admin.middleware.trace_collector import TraceCollectorFilter
         from pyfly.admin.providers.beans_provider import BeansProvider
         from pyfly.admin.providers.cache_provider import CacheProvider
         from pyfly.admin.providers.config_provider import ConfigProvider
@@ -238,12 +262,9 @@ def _install_indicators() -> None:
         with contextlib.suppress(Exception):
             admin_props = context.config.bind(AdminProperties)
 
-        # Find trace collector from context (registered by auto-config)
-        trace_collector = None
-        for _cls, reg in context.container._registrations.items():
-            if reg.instance is not None and isinstance(reg.instance, TraceCollectorFilter):
-                trace_collector = reg.instance
-                break
+        # Use the trace collector that was created above and wired into the
+        # filter chain — it is the live instance recording HTTP traffic.
+        trace_collector = admin_trace_collector
 
         # Find view registry from context
         view_registry = AdminViewRegistry()
@@ -264,18 +285,6 @@ def _install_indicators() -> None:
                     indicator_name = reg.name or cls.__name__
                     health_agg.add_indicator(indicator_name, reg.instance)
 
-        # Find server adapter from context for admin dashboard
-        server_adapter = None
-        try:
-            from pyfly.server.ports.outbound import ApplicationServerPort
-
-            for _cls, reg in context.container._registrations.items():
-                if reg.instance is not None and isinstance(reg.instance, ApplicationServerPort):
-                    server_adapter = reg.instance
-                    break
-        except ImportError:
-            pass
-
         admin_builder = AdminRouteBuilder(
             properties=admin_props,
             overview=OverviewProvider(context, health_agg),
@@ -295,7 +304,7 @@ def _install_indicators() -> None:
             trace_collector=trace_collector,
             logfile=LogfileProvider(context),
             runtime=RuntimeProvider(),
-            server=ServerProvider(server_adapter),
+            server=ServerProvider(context=context),
         )
         routes.extend(admin_builder.build_routes())  # type: ignore[arg-type]
 
@@ -315,24 +324,39 @@ def _install_indicators() -> None:
             ]
         )
 
+    # Health indicators (and other late beans) are only instantiated by
+    # ``ApplicationContext.start()``, which runs inside the provided lifespan —
+    # AFTER this factory returns. So wrap the caller's lifespan to rerun the
+    # indicator scan immediately after startup. Without this, /actuator/health
+    # and the admin health view see an empty indicator set and report UP even
+    # when a subsystem is DOWN. (When no lifespan is supplied — e.g. tests pass
+    # an already-started context — the eager scan above already caught them.)
+    effective_lifespan = lifespan
+    if actuator_enabled and lifespan is not None:
+        _user_lifespan = lifespan
+
+        @contextlib.asynccontextmanager
+        async def _lifespan_with_indicator_rescan(app_: Starlette) -> AsyncIterator[None]:
+            async with _user_lifespan(app_):  # type: ignore[operator]
+                _install_indicators()  # beans are now instantiated
+                yield
+
+        effective_lifespan = _lifespan_with_indicator_rescan
+
     app = Starlette(
         debug=debug,
         middleware=middleware,
         routes=routes,
-        lifespan=lifespan,  # type: ignore[arg-type]
+        lifespan=effective_lifespan,  # type: ignore[arg-type]
     )
 
     # Store metadata for startup logging
     app.state.pyfly_route_metadata = route_metadata
     app.state.pyfly_docs_enabled = docs_enabled
 
-    # Expose the indicator rescan so the downstream lifespan can rerun
-    # it AFTER ``ApplicationContext.start()`` has instantiated every
-    # bean. The eager call above only catches indicators that already
-    # had ``.instance`` set at create_app time (rare — most live as
-    # @bean methods on @auto_configuration classes).
+    # Also expose the rescan for callers that manage their own lifespan.
     if actuator_enabled:
-        app.state.pyfly_install_health_indicators = _install_indicators  # type: ignore[name-defined]
+        app.state.pyfly_install_health_indicators = _install_indicators
 
     # Register global exception handler
     app.add_exception_handler(Exception, global_exception_handler)
diff --git a/src/pyfly/web/adapters/starlette/filter_chain.py b/src/pyfly/web/adapters/starlette/filter_chain.py
index 3c04548..4e9fe24 100644
--- a/src/pyfly/web/adapters/starlette/filter_chain.py
+++ b/src/pyfly/web/adapters/starlette/filter_chain.py
@@ -27,6 +27,23 @@
 MAX_RESPONSE_BODY_SIZE = 100 * 1024 * 1024  # 100 MB
 
 
+class _AlreadySentResponse(Response):
+    """Sentinel returned by the terminal when a streaming response has already
+    been forwarded to the client. Sending it again is a no-op.
+
+    Filters that post-process the response (e.g. add headers) operate on this
+    object harmlessly — for streaming responses the headers were already
+    flushed, so mutations are silently ignored, matching the behaviour of any
+    pass-through ASGI middleware.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(b"", status_code=200)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:  # noqa: D401
+        return
+
+
 class WebFilterChainMiddleware:
     """Pure ASGI middleware that executes a sorted chain of :class:`WebFilter` instances.
 
@@ -54,18 +71,43 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         request = Request(scope, receive, send)
 
         async def _call_app(req: Any) -> Response:
-            """Terminal: run downstream ASGI app and capture its response."""
+            """Terminal: run the downstream ASGI app and adapt its response.
+
+            Single-shot responses are buffered into a :class:`Response` so filters
+            can inspect/modify them. Streaming responses (SSE, chunked downloads —
+            anything that emits a body frame with ``more_body=True``) are detected
+            on their first chunk and forwarded to the client **live**, so they are
+            never buffered in memory and reach the client incrementally.
+            """
             status_code = 200
             raw_headers: list[tuple[bytes, bytes]] = []
             body_parts: list[bytes] = []
+            state = {"streaming": False}
 
             async def _intercept(message: Any) -> None:
                 nonlocal status_code, raw_headers
-                if message["type"] == "http.response.start":
+                msg_type = message["type"]
+                if msg_type == "http.response.start":
                     status_code = message["status"]
                     raw_headers = list(message.get("headers", []))
-                elif message["type"] == "http.response.body":
+                elif msg_type == "http.response.body":
                     body = message.get("body", b"")
+                    more_body = message.get("more_body", False)
+                    # Detect streaming on the first body frame that signals more to
+                    # come. Once detected, flush the captured start line and forward
+                    # every frame (including this one) straight to the client.
+                    if not state["streaming"] and more_body:
+                        state["streaming"] = True
+                        await send(
+                            {
+                                "type": "http.response.start",
+                                "status": status_code,
+                                "headers": raw_headers,
+                            }
+                        )
+                    if state["streaming"]:
+                        await send({"type": "http.response.body", "body": body, "more_body": more_body})
+                        return
                     if body:
                         body_parts.append(body)
                         if sum(len(p) for p in body_parts) > MAX_RESPONSE_BODY_SIZE:
@@ -73,7 +115,7 @@ async def _intercept(message: Any) -> None:
                                 f"Response body exceeds {MAX_RESPONSE_BODY_SIZE} bytes. "
                                 "Consider excluding this route from the filter chain."
                             )
-                elif message["type"] == "http.response.pathsend":
+                elif msg_type == "http.response.pathsend":
                     # ASGI pathsend extension (Granian zero-copy file serving).
                     # Stream the file in chunks to avoid OOM on large files.
                     from pathlib import Path
@@ -91,6 +133,10 @@ async def _intercept(message: Any) -> None:
 
             await self.app(scope, receive, _intercept)
 
+            if state["streaming"]:
+                # Body already forwarded live; nothing left to send.
+                return _AlreadySentResponse()
+
             response = Response(content=b"".join(body_parts), status_code=status_code)
             response.raw_headers[:] = raw_headers
             return response
diff --git a/src/pyfly/web/adapters/starlette/filters/__init__.py b/src/pyfly/web/adapters/starlette/filters/__init__.py
index 6b80a6c..ce7896a 100644
--- a/src/pyfly/web/adapters/starlette/filters/__init__.py
+++ b/src/pyfly/web/adapters/starlette/filters/__init__.py
@@ -15,6 +15,7 @@
 
 from pyfly.web.adapters.starlette.filters.correlation_filter import CorrelationFilter
 from pyfly.web.adapters.starlette.filters.http_security_filter import HttpSecurityFilter
+from pyfly.web.adapters.starlette.filters.request_context_filter import RequestContextFilter
 from pyfly.web.adapters.starlette.filters.request_logging_filter import RequestLoggingFilter
 from pyfly.web.adapters.starlette.filters.security_headers_filter import SecurityHeadersFilter
 from pyfly.web.adapters.starlette.filters.transaction_id_filter import TransactionIdFilter
@@ -22,6 +23,7 @@
 __all__ = [
     "CorrelationFilter",
     "HttpSecurityFilter",
+    "RequestContextFilter",
     "RequestLoggingFilter",
     "SecurityHeadersFilter",
     "TransactionIdFilter",
diff --git a/src/pyfly/web/adapters/starlette/filters/request_logging_filter.py b/src/pyfly/web/adapters/starlette/filters/request_logging_filter.py
index 139178d..933f3e0 100644
--- a/src/pyfly/web/adapters/starlette/filters/request_logging_filter.py
+++ b/src/pyfly/web/adapters/starlette/filters/request_logging_filter.py
@@ -15,7 +15,6 @@
 
 from __future__ import annotations
 
-import logging
 import time
 from typing import cast
 
@@ -23,15 +22,11 @@
 from starlette.responses import Response
 
 from pyfly.container.ordering import HIGHEST_PRECEDENCE, order
+from pyfly.logging import get_logger
 from pyfly.web.filters import OncePerRequestFilter
 from pyfly.web.ports.filter import CallNext
 
-try:
-    import structlog
-
-    logger = structlog.get_logger("pyfly.web")
-except ImportError:
-    logger = logging.getLogger("pyfly.web")
+logger = get_logger("pyfly.web")
 
 
 @order(HIGHEST_PRECEDENCE + 200)
diff --git a/src/pyfly/web/adapters/starlette/request_logger.py b/src/pyfly/web/adapters/starlette/request_logger.py
index f0ebe3a..263b66c 100644
--- a/src/pyfly/web/adapters/starlette/request_logger.py
+++ b/src/pyfly/web/adapters/starlette/request_logger.py
@@ -15,19 +15,15 @@
 
 from __future__ import annotations
 
-import logging
 import time
 from typing import Any
 
 from starlette.requests import Request
 from starlette.types import ASGIApp, Receive, Scope, Send
 
-try:
-    import structlog
+from pyfly.logging import get_logger
 
-    logger = structlog.get_logger("pyfly.web")
-except ImportError:
-    logger = logging.getLogger("pyfly.web")
+logger = get_logger("pyfly.web")
 
 
 class RequestLoggingMiddleware:
diff --git a/src/pyfly/web/adapters/starlette/resolver.py b/src/pyfly/web/adapters/starlette/resolver.py
index c15d598..0a443b9 100644
--- a/src/pyfly/web/adapters/starlette/resolver.py
+++ b/src/pyfly/web/adapters/starlette/resolver.py
@@ -16,9 +16,10 @@
 from __future__ import annotations
 
 import inspect
+import types
 import typing
 from dataclasses import dataclass
-from typing import Any, get_args, get_origin
+from typing import Any, Union, get_args, get_origin
 
 from pydantic import BaseModel
 from starlette.requests import Request
@@ -213,16 +214,28 @@ def _run_validation(self, value: Any, param: ResolvedParam) -> Any:
         return value
 
     def _coerce(self, value: str, target_type: type) -> Any:
-        """Coerce a string value to the target type."""
-        if target_type is str:
+        """Coerce a string value to the target type.
+
+        Handles ``Optional[T]`` / ``T | None`` union types by unwrapping to the
+        first non-NoneType argument before coercion.
+        """
+        # Unwrap Optional[T] (typing.Union[T, None]) or T | None (types.UnionType)
+        actual_type = target_type
+        origin = get_origin(target_type)
+        if origin is Union or isinstance(target_type, types.UnionType):
+            non_none = [a for a in get_args(target_type) if a is not type(None)]
+            actual_type = non_none[0] if non_none else str
+
+        if actual_type is str:
             return value
         try:
-            return target_type(value)
+            return actual_type(value)
         except (ValueError, TypeError) as exc:
+            type_name = getattr(actual_type, "__name__", repr(actual_type))
             from pyfly.kernel.exceptions import InvalidRequestException
 
             raise InvalidRequestException(
-                f"Cannot convert '{value}' to {target_type.__name__}",
+                f"Cannot convert '{value}' to {type_name}",
                 code="TYPE_CONVERSION_ERROR",
             ) from exc
 
diff --git a/src/pyfly/web/mappings.py b/src/pyfly/web/mappings.py
index c6b4b11..c1b70b3 100644
--- a/src/pyfly/web/mappings.py
+++ b/src/pyfly/web/mappings.py
@@ -19,12 +19,22 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import Any, TypeVar
+from typing import Any, Protocol, TypeVar
 
 T = TypeVar("T", bound=type)
 F = TypeVar("F", bound=Callable[..., Any])
 
 
+class MethodMapping(Protocol):
+    """Typed signature of an HTTP method mapping decorator factory.
+
+    Calling it (e.g. ``get_mapping("/path")``) returns a decorator that
+    attaches routing metadata to the handler method.
+    """
+
+    def __call__(self, path: str = ..., *, status_code: int = ...) -> Callable[[F], F]: ...
+
+
 def request_mapping(path: str) -> Callable[[T], T]:
     """Class-level decorator that sets the base path for all handler methods."""
 
@@ -35,7 +45,7 @@ def decorator(cls: T) -> T:
     return decorator
 
 
-def _make_method_mapping(method: str) -> Callable[..., Any]:
+def _make_method_mapping(method: str) -> MethodMapping:
     """Factory that creates an HTTP method mapping decorator."""
 
     def mapping(path: str = "", *, status_code: int = 200) -> Callable[[F], F]:
diff --git a/tests/actuator/test_health_rescan.py b/tests/actuator/test_health_rescan.py
new file mode 100644
index 0000000..40fba8f
--- /dev/null
+++ b/tests/actuator/test_health_rescan.py
@@ -0,0 +1,55 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Regression: health indicators instantiated during the ASGI lifespan startup
+must be reflected by /actuator/health (the rescan hook must actually run)."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+
+from starlette.testclient import TestClient
+
+from pyfly.actuator.health import HealthStatus
+from pyfly.container.stereotypes import component
+from pyfly.context.application_context import ApplicationContext
+from pyfly.core.config import Config
+from pyfly.web.adapters.starlette.app import create_app
+
+
+@component
+class _DownIndicator:
+    async def health(self) -> HealthStatus:
+        return HealthStatus(status="DOWN", details={"reason": "dependency offline"})
+
+
+def test_actuator_health_reflects_indicator_registered_at_startup():
+    ctx = ApplicationContext(Config({}))
+    ctx.register_bean(_DownIndicator)
+
+    # The context is started INSIDE the lifespan — i.e. after create_app returns,
+    # exactly like the generated main.py. The eager scan at create_app time
+    # therefore cannot see _DownIndicator; only the post-startup rescan can.
+    @asynccontextmanager
+    async def lifespan(app):
+        await ctx.start()
+        yield
+
+    app = create_app(context=ctx, actuator_enabled=True, docs_enabled=False, lifespan=lifespan)
+
+    with TestClient(app) as client:  # entering the client triggers the lifespan
+        resp = client.get("/actuator/health")
+        assert resp.status_code == 503
+        body = resp.json()
+        assert body["status"] == "DOWN"
+        assert any(c.get("status") == "DOWN" for c in body.get("components", {}).values())
diff --git a/tests/admin/test_admin_create_app_wiring.py b/tests/admin/test_admin_create_app_wiring.py
new file mode 100644
index 0000000..cc71ba1
--- /dev/null
+++ b/tests/admin/test_admin_create_app_wiring.py
@@ -0,0 +1,103 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Regression tests for admin dashboard wiring inside ``create_app``.
+
+These cover the integration seam that unit tests of the route builder miss:
+the HTTP trace collector must be created *and* inserted into the live
+WebFilter chain so that real traffic is recorded, and the server provider
+must resolve its adapter lazily (the adapter bean is instantiated by
+``ApplicationContext.start()`` which runs after the app is assembled).
+"""
+
+from __future__ import annotations
+
+import pytest
+from starlette.testclient import TestClient
+
+from pyfly.context.application_context import ApplicationContext
+from pyfly.core.config import Config
+from pyfly.web.adapters.starlette.app import create_app
+
+
+async def _admin_context() -> ApplicationContext:
+    ctx = ApplicationContext(Config({"pyfly": {"admin": {"enabled": True}}}))
+    await ctx.start()
+    return ctx
+
+
+class TestAdminTraceCollectorWiring:
+    @pytest.mark.asyncio
+    async def test_traces_recorded_for_real_traffic(self):
+        """A request through the app must show up in /admin/api/traces."""
+        ctx = await _admin_context()
+        app = create_app(context=ctx, docs_enabled=False)
+        client = TestClient(app)
+
+        # Generate some non-admin traffic (admin/actuator paths are excluded).
+        for _ in range(3):
+            client.get("/some/business/path", follow_redirects=False)
+
+        resp = client.get("/admin/api/traces")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["total"] >= 3, f"expected recorded traces, got {data}"
+        paths = {t["path"] for t in data["traces"]}
+        assert "/some/business/path" in paths
+
+    @pytest.mark.asyncio
+    async def test_admin_and_actuator_paths_excluded_from_traces(self):
+        ctx = await _admin_context()
+        app = create_app(context=ctx, docs_enabled=False)
+        client = TestClient(app)
+
+        client.get("/admin/api/overview")
+        client.get("/admin/api/traces")
+
+        resp = client.get("/admin/api/traces")
+        data = resp.json()
+        admin_paths = [t for t in data["traces"] if t["path"].startswith("/admin")]
+        assert admin_paths == [], "admin paths must not be traced"
+
+    @pytest.mark.asyncio
+    async def test_server_info_endpoint_does_not_error(self):
+        ctx = await _admin_context()
+        app = create_app(context=ctx, docs_enabled=False)
+        client = TestClient(app)
+
+        resp = client.get("/admin/api/server")
+        assert resp.status_code == 200
+        # Without a running ApplicationServerPort the provider returns the
+        # graceful "unknown" shape rather than raising.
+        assert "name" in resp.json()
+
+
+class TestAdminSseStreams:
+    """SSE streaming through the filter chain is covered deterministically at the
+    ASGI level by tests/web/test_filter_chain.py::TestFilterChainStreaming. Here we
+    only assert the admin SSE generator emits an initial event immediately (no
+    buffering), driving the generator directly to avoid an unbounded TestClient
+    stream that would never terminate."""
+
+    @pytest.mark.asyncio
+    async def test_health_stream_emits_initial_event(self):
+        from pyfly.actuator.health import HealthAggregator
+        from pyfly.admin.api.sse import health_stream
+        from pyfly.admin.providers.health_provider import HealthProvider
+
+        provider = HealthProvider(HealthAggregator())
+        gen = health_stream(provider, interval=0.01)
+        first = await gen.__anext__()
+        await gen.aclose()
+        assert first.startswith("event: health")
+        assert "data:" in first and "status" in first
diff --git a/tests/aop/test_property_and_ordering.py b/tests/aop/test_property_and_ordering.py
new file mode 100644
index 0000000..1066dc6
--- /dev/null
+++ b/tests/aop/test_property_and_ordering.py
@@ -0,0 +1,94 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Regressions for AOP weaving: @property getters must not be evaluated during
+weaving, and advice must be woven regardless of target/aspect registration order."""
+
+from __future__ import annotations
+
+import pytest
+
+from pyfly.aop.decorators import aspect, before
+from pyfly.aop.post_processor import AspectBeanPostProcessor
+from pyfly.aop.types import JoinPoint
+from pyfly.container.stereotypes import service
+from pyfly.context.application_context import ApplicationContext
+from pyfly.core.config import Config
+
+
+class TestWeavingDoesNotTriggerProperties:
+    @pytest.mark.asyncio
+    async def test_side_effecting_property_not_evaluated_during_weaving(self) -> None:
+        calls: list[str] = []
+
+        @service
+        class ServiceWithProperty:
+            def __init__(self) -> None:
+                self.property_reads = 0
+
+            @property
+            def dangerous(self) -> str:
+                # A property that raises would previously abort startup because
+                # weaving did getattr() over every public attribute.
+                self.property_reads += 1
+                raise RuntimeError("property must not be evaluated during weaving")
+
+            async def do_work(self) -> str:
+                return "done"
+
+        @aspect
+        class WorkAspect:
+            @before("service.ServiceWithProperty.*")
+            def on_before(self, jp: JoinPoint) -> None:
+                calls.append("before")
+
+        ctx = ApplicationContext(Config())
+        ctx.register_bean(WorkAspect)
+        ctx.register_bean(ServiceWithProperty)
+        ctx.register_post_processor(AspectBeanPostProcessor())
+        await ctx.start()  # must not raise
+
+        svc = ctx.get_bean(ServiceWithProperty)
+        assert svc.property_reads == 0  # weaving never touched the property
+        assert await svc.do_work() == "done"
+        assert calls == ["before"]  # the real method was still woven
+
+
+class TestWeavingIsOrderIndependent:
+    @pytest.mark.asyncio
+    async def test_target_registered_before_aspect_is_still_woven(self) -> None:
+        calls: list[str] = []
+
+        @service
+        class OrderTarget:
+            async def execute(self) -> str:
+                return "ran"
+
+        @aspect
+        class OrderAspect:
+            @before("service.OrderTarget.*")
+            def on_before(self, jp: JoinPoint) -> None:
+                calls.append("before")
+
+        ctx = ApplicationContext(Config())
+        # Register the TARGET *before* the ASPECT — previously this left the
+        # target unwoven because its after_init ran before the aspect was
+        # collected.
+        ctx.register_bean(OrderTarget)
+        ctx.register_bean(OrderAspect)
+        ctx.register_post_processor(AspectBeanPostProcessor())
+        await ctx.start()
+
+        target = ctx.get_bean(OrderTarget)
+        assert await target.execute() == "ran"
+        assert calls == ["before"]
diff --git a/tests/callbacks/test_callbacks.py b/tests/callbacks/test_callbacks.py
index 9db19c3..c83e450 100644
--- a/tests/callbacks/test_callbacks.py
+++ b/tests/callbacks/test_callbacks.py
@@ -52,8 +52,11 @@ async def test_dispatcher_signs_with_secret() -> None:
     executions = InMemoryCallbackExecutionRepository()
     captured_headers: list[dict[str, str]] = []
 
+    captured_payloads: list[dict[str, Any]] = []
+
     async def fake_post(url: str, payload: dict[str, Any], headers: dict[str, str]) -> int:
         captured_headers.append(headers)
+        captured_payloads.append(payload)
         return 200
 
     config = CallbackConfig(
@@ -66,8 +69,20 @@ async def fake_post(url: str, payload: dict[str, Any], headers: dict[str, str])
     )
     await configs.save(config)
     dispatcher = CallbackDispatcher(configs, executions, http=fake_post)
-    await dispatcher.dispatch("t", "X", {"a": 1})
-    assert "X-Pyfly-Signature" in captured_headers[0]
+    await dispatcher.dispatch("t", "X", {"a": 1, "b": 2})
+
+    sig_header = captured_headers[0]["X-Pyfly-Signature"]
+    assert sig_header.startswith("sha256=")
+
+    # The signature must be a valid, reproducible HMAC over the canonical JSON
+    # body (not Python's str(dict)), verifiable by the inbound validator.
+    import json
+
+    from pyfly.webhooks.signature import HmacSignatureValidator
+
+    canonical = json.dumps(captured_payloads[0], separators=(",", ":"), sort_keys=True).encode("utf-8")
+    validator = HmacSignatureValidator(secret="topsecret")
+    assert validator.is_valid(body=canonical, signature=sig_header.removeprefix("sha256="))
 
 
 @pytest.mark.asyncio
diff --git a/tests/config/test_bind_placeholders_nested.py b/tests/config/test_bind_placeholders_nested.py
new file mode 100644
index 0000000..a3f9dc3
--- /dev/null
+++ b/tests/config/test_bind_placeholders_nested.py
@@ -0,0 +1,70 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Regression: Config.bind() resolves ${...} placeholders and binds nested dataclasses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pyfly.core.config import Config, config_properties
+
+
+@dataclass
+class _Granian:
+    workers: int = 1
+    threads: int = 2
+
+
+@config_properties("server")
+@dataclass
+class _Server:
+    type: str = "auto"
+    granian: _Granian = field(default_factory=_Granian)
+
+
+@config_properties("svc")
+@dataclass
+class _Svc:
+    url: str = ""
+    port: int = 0
+
+
+def test_bind_resolves_placeholders(monkeypatch):
+    monkeypatch.setenv("MY_PORT", "9000")
+    cfg = Config({"svc": {"url": "http://host:${MY_PORT}/x", "port": "${MY_PORT}"}})
+    svc = cfg.bind(_Svc)
+    assert svc.url == "http://host:9000/x"
+    assert svc.port == 9000  # placeholder resolved, then coerced to int
+
+
+def test_bind_uses_placeholder_default():
+    cfg = Config({"svc": {"url": "http://host:${MISSING_PORT:8080}"}})
+    svc = cfg.bind(_Svc)
+    assert svc.url == "http://host:8080"
+
+
+def test_bind_binds_nested_dataclass():
+    cfg = Config({"server": {"type": "uvicorn", "granian": {"workers": 4, "threads": 8}}})
+    server = cfg.bind(_Server)
+    assert server.type == "uvicorn"
+    assert isinstance(server.granian, _Granian)
+    assert server.granian.workers == 4
+    assert server.granian.threads == 8
+
+
+def test_bind_nested_dataclass_default_when_absent():
+    cfg = Config({"server": {"type": "uvicorn"}})
+    server = cfg.bind(_Server)
+    assert isinstance(server.granian, _Granian)
+    assert server.granian.workers == 1
diff --git a/tests/config_server/test_config_server.py b/tests/config_server/test_config_server.py
index 83e441e..24a10b7 100644
--- a/tests/config_server/test_config_server.py
+++ b/tests/config_server/test_config_server.py
@@ -25,6 +25,26 @@ async def test_in_memory_round_trip() -> None:
     assert fetched.properties == {"x": 1}
 
 
+@pytest.mark.asyncio
+async def test_filesystem_save_updates_existing_yaml(tmp_path: pathlib.Path) -> None:
+    """Regression: save() must update the file fetch() reads (a pre-existing
+    .yaml), not write a shadowed .json that fetch ignores."""
+    import yaml
+
+    yaml_file = tmp_path / "main" / "orders-prod.yaml"
+    yaml_file.parent.mkdir(parents=True, exist_ok=True)
+    yaml_file.write_text(yaml.safe_dump({"v": "old"}))
+
+    backend = FilesystemConfigBackend(tmp_path)
+    await backend.save(ConfigSource(application="orders", profile="prod", label="main", properties={"v": "new"}))
+
+    fetched = await backend.fetch("orders", "prod", "main")
+    assert fetched is not None
+    assert fetched.properties == {"v": "new"}  # not the stale "old"
+    # And no shadow .json was created alongside the .yaml.
+    assert not (tmp_path / "main" / "orders-prod.json").exists()
+
+
 @pytest.mark.asyncio
 async def test_filesystem_round_trip(tmp_path: pathlib.Path) -> None:
     backend = FilesystemConfigBackend(tmp_path)
diff --git a/tests/container/test_same_type_beans.py b/tests/container/test_same_type_beans.py
new file mode 100644
index 0000000..6b82a11
--- /dev/null
+++ b/tests/container/test_same_type_beans.py
@@ -0,0 +1,74 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Regression: two @bean methods returning the SAME concrete type must both
+survive — previously the second overwrote the first in the type-keyed registry
+and `list[T]` resolution returned nothing (silent data loss)."""
+
+from __future__ import annotations
+
+import pytest
+
+from pyfly.container.bean import bean
+from pyfly.container.stereotypes import configuration, service
+from pyfly.context.application_context import ApplicationContext
+from pyfly.core.config import Config
+
+
+class Widget:
+    def __init__(self, label: str) -> None:
+        self.label = label
+
+
+@configuration
+class TwoWidgetsConfig:
+    @bean
+    def widget_one(self) -> Widget:
+        return Widget("one")
+
+    @bean
+    def widget_two(self) -> Widget:
+        return Widget("two")
+
+
+@service
+class WidgetConsumer:
+    def __init__(self, widgets: list[Widget]) -> None:
+        self.widgets = widgets
+
+
+class TestSameTypeBeans:
+    @pytest.mark.asyncio
+    async def test_both_named_beans_resolvable(self):
+        ctx = ApplicationContext(Config({}))
+        ctx.register_bean(TwoWidgetsConfig)
+        await ctx.start()
+        assert ctx.get_bean_by_name("widget_one").label == "one"
+        assert ctx.get_bean_by_name("widget_two").label == "two"
+
+    @pytest.mark.asyncio
+    async def test_resolve_all_returns_every_same_type_bean(self):
+        ctx = ApplicationContext(Config({}))
+        ctx.register_bean(TwoWidgetsConfig)
+        await ctx.start()
+        labels = sorted(w.label for w in ctx.container.resolve_all(Widget))
+        assert labels == ["one", "two"]
+
+    @pytest.mark.asyncio
+    async def test_list_injection_receives_all_same_type_beans(self):
+        ctx = ApplicationContext(Config({}))
+        ctx.register_bean(TwoWidgetsConfig)
+        ctx.register_bean(WidgetConsumer)
+        await ctx.start()
+        consumer = ctx.get_bean(WidgetConsumer)
+        assert sorted(w.label for w in consumer.widgets) == ["one", "two"]
diff --git a/tests/cqrs/test_auto_configuration_wiring.py b/tests/cqrs/test_auto_configuration_wiring.py
new file mode 100644
index 0000000..69af5e3
--- /dev/null
+++ b/tests/cqrs/test_auto_configuration_wiring.py
@@ -0,0 +1,37 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Wiring regressions for CqrsAutoConfiguration."""
+
+from __future__ import annotations
+
+from pyfly.cqrs.config.auto_configuration import CqrsAutoConfiguration
+
+
+class _FakeCache:
+    async def get(self, key): ...
+    async def put(self, key, value, ttl=None): ...
+    async def evict(self, key): ...
+
+
+def test_query_cache_adapter_uses_injected_cache():
+    cfg = CqrsAutoConfiguration()
+    fake = _FakeCache()
+    adapter = cfg.query_cache_adapter(cache=fake)
+    assert adapter._cache is fake
+
+
+def test_query_cache_adapter_no_cache_is_noop():
+    cfg = CqrsAutoConfiguration()
+    adapter = cfg.query_cache_adapter()
+    assert adapter._cache is None
diff --git a/tests/cqrs/test_event_publishing_wiring.py b/tests/cqrs/test_event_publishing_wiring.py
new file mode 100644
index 0000000..3d7f001
--- /dev/null
+++ b/tests/cqrs/test_event_publishing_wiring.py
@@ -0,0 +1,199 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Regression tests for CQRS domain-event publishing wiring.
+
+Guards against the historical bug where ``command_bus`` hardcoded
+``event_publisher=NoOpEventPublisher()``, so events emitted by command
+handlers were *never* published even when an EDA producer was available.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from pyfly.cqrs.command.bus import DefaultCommandBus
+from pyfly.cqrs.command.handler import CommandHandler
+from pyfly.cqrs.command.registry import HandlerRegistry
+from pyfly.cqrs.config.auto_configuration import CqrsAutoConfiguration
+from pyfly.cqrs.config.properties import CqrsProperties
+from pyfly.cqrs.event.publisher import (
+    EdaCommandEventPublisher,
+    NoOpEventPublisher,
+)
+from pyfly.cqrs.tracing.correlation import CorrelationContext
+from pyfly.cqrs.types import Command
+from pyfly.eda.ports.outbound import EventHandler, EventPublisher
+
+# -- Fakes ------------------------------------------------------------------
+
+
+class FakeEventPublisher:
+    """In-memory EDA ``EventPublisher`` that records every publish call.
+
+    Implements the real ``pyfly.eda.ports.outbound.EventPublisher`` protocol
+    so the wiring is exercised against the genuine port contract.
+    """
+
+    def __init__(self) -> None:
+        self.published: list[tuple[str, str, dict[str, Any], dict[str, str] | None]] = []
+        self.started = False
+        self.stopped = False
+
+    def subscribe(self, event_type_pattern: str, handler: EventHandler) -> None:  # pragma: no cover - unused
+        raise NotImplementedError
+
+    async def publish(
+        self,
+        destination: str,
+        event_type: str,
+        payload: dict[str, Any],
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.published.append((destination, event_type, payload, headers))
+
+    async def start(self) -> None:  # pragma: no cover - unused
+        self.started = True
+
+    async def stop(self) -> None:  # pragma: no cover - unused
+        self.stopped = True
+
+
+@dataclass(frozen=True)
+class OrderCreated:
+    """A simple domain event emitted by the test handler."""
+
+    order_id: str
+    amount: float
+
+    @property
+    def event_type(self) -> str:
+        return "OrderCreated"
+
+
+@dataclass
+class CreateOrderCommand(Command[str]):
+    customer_id: str = ""
+    amount: float = 0.0
+    domain_events: list[Any] = field(default_factory=list)
+
+
+class CreateOrderHandler(CommandHandler[CreateOrderCommand, str]):
+    async def do_handle(self, command: CreateOrderCommand) -> str:
+        order_id = f"order-{command.customer_id}"
+        command.domain_events.append(OrderCreated(order_id=order_id, amount=command.amount))
+        return order_id
+
+
+# -- Bean wiring ------------------------------------------------------------
+
+
+def test_command_event_publisher_uses_eda_producer_when_present() -> None:
+    cfg = CqrsAutoConfiguration()
+    producer = FakeEventPublisher()
+    publisher = cfg.command_event_publisher(producer=producer)
+    assert isinstance(publisher, EdaCommandEventPublisher)
+    assert publisher._producer is producer
+
+
+def test_command_event_publisher_falls_back_to_noop_without_producer() -> None:
+    cfg = CqrsAutoConfiguration()
+    publisher = cfg.command_event_publisher()
+    assert isinstance(publisher, NoOpEventPublisher)
+
+
+def test_command_bus_injects_the_publisher_bean() -> None:
+    cfg = CqrsAutoConfiguration()
+    producer = FakeEventPublisher()
+    publisher = cfg.command_event_publisher(producer=producer)
+    bus = cfg.command_bus(
+        registry=HandlerRegistry(),
+        validation=cfg.command_validation_service(cfg.auto_validation_processor()),
+        authorization=cfg.authorization_service(CqrsProperties()),
+        metrics=cfg.cqrs_metrics_service(),
+        event_publisher=publisher,
+    )
+    assert bus._event_publisher is publisher
+
+
+# -- End-to-end through the command bus -------------------------------------
+
+
+async def test_emitted_event_reaches_producer() -> None:
+    CorrelationContext.clear()
+    producer = FakeEventPublisher()
+    publisher = EdaCommandEventPublisher(producer)
+
+    registry = HandlerRegistry()
+    registry.register_command_handler(CreateOrderHandler())
+    bus = DefaultCommandBus(registry=registry, event_publisher=publisher)
+
+    result = await bus.send(CreateOrderCommand(customer_id="cust-1", amount=42.0))
+
+    assert result == "order-cust-1"
+    assert len(producer.published) == 1
+    destination, event_type, payload, headers = producer.published[0]
+    assert destination == "cqrs.events"
+    assert event_type == "OrderCreated"
+    assert payload == {"order_id": "order-cust-1", "amount": 42.0}
+    assert headers is None
+
+
+async def test_no_producer_stays_a_silent_noop() -> None:
+    CorrelationContext.clear()
+    publisher = NoOpEventPublisher()
+
+    registry = HandlerRegistry()
+    registry.register_command_handler(CreateOrderHandler())
+    bus = DefaultCommandBus(registry=registry, event_publisher=publisher)
+
+    # Must process cleanly even though the emitted event goes nowhere.
+    result = await bus.send(CreateOrderCommand(customer_id="cust-2", amount=7.0))
+    assert result == "order-cust-2"
+
+
+# -- DI container optional-injection (the mechanism the bug fix relies on) ---
+
+
+def test_container_injects_eda_publisher_into_command_event_publisher_bean() -> None:
+    """When an ``EventPublisher`` bean exists, the optional param is injected."""
+    from pyfly.container.container import Container
+    from pyfly.context.application_context import ApplicationContext
+    from pyfly.core.config import Config
+
+    ctx = ApplicationContext(Config({}))
+    container: Container = ctx._container
+
+    producer = FakeEventPublisher()
+    container.register(FakeEventPublisher)
+    container._registrations[FakeEventPublisher].instance = producer
+    container.bind(EventPublisher, FakeEventPublisher)
+
+    cfg = CqrsAutoConfiguration()
+    publisher = ctx._call_bean_method(cfg, cfg.command_event_publisher)
+
+    assert isinstance(publisher, EdaCommandEventPublisher)
+    assert publisher._producer is producer
+
+
+def test_container_falls_back_to_noop_when_no_eda_publisher_bean() -> None:
+    """With no ``EventPublisher`` bean, optional injection yields ``None`` -> NoOp."""
+    from pyfly.context.application_context import ApplicationContext
+    from pyfly.core.config import Config
+
+    ctx = ApplicationContext(Config({}))
+    cfg = CqrsAutoConfiguration()
+    publisher = ctx._call_bean_method(cfg, cfg.command_event_publisher)
+
+    assert isinstance(publisher, NoOpEventPublisher)
diff --git a/tests/eda/test_auto_configuration.py b/tests/eda/test_auto_configuration.py
index 07660a8..2f70978 100644
--- a/tests/eda/test_auto_configuration.py
+++ b/tests/eda/test_auto_configuration.py
@@ -18,20 +18,20 @@ def _config(values: dict[str, object]) -> object:
 
 class TestEdaAutoConfiguration:
     def test_memory_provider(self) -> None:
-        bus = EdaAutoConfiguration().event_publisher(
-            _config({"pyfly.eda.provider": "memory"})
-        )
+        bus = EdaAutoConfiguration().event_publisher(_config({"pyfly.eda.provider": "memory"}))
         assert isinstance(bus, InMemoryEventBus)
 
     def test_kafka_provider(self) -> None:
         from pyfly.eda.adapters.kafka import KafkaEventBus
 
         bus = EdaAutoConfiguration().event_publisher(
-            _config({
-                "pyfly.eda.provider": "kafka",
-                "pyfly.eda.destinations": "flydesk.idp.jobs",
-                "pyfly.eda.kafka.bootstrap-servers": "kafka:9092",
-            })
+            _config(
+                {
+                    "pyfly.eda.provider": "kafka",
+                    "pyfly.eda.destinations": "flydesk.idp.jobs",
+                    "pyfly.eda.kafka.bootstrap-servers": "kafka:9092",
+                }
+            )
         )
         assert isinstance(bus, KafkaEventBus)
         assert bus._bootstrap_servers == "kafka:9092"
@@ -42,12 +42,14 @@ def test_redis_provider(self) -> None:
             from pyfly.eda.adapters.redis import RedisStreamsEventBus
 
             bus = EdaAutoConfiguration().event_publisher(
-                _config({
-                    "pyfly.eda.provider": "redis",
-                    "pyfly.eda.redis.url": "redis://r:6379/1",
-                    "pyfly.eda.destinations": "a, b",
-                    "pyfly.eda.group": "flydesk-idp",
-                })
+                _config(
+                    {
+                        "pyfly.eda.provider": "redis",
+                        "pyfly.eda.redis.url": "redis://r:6379/1",
+                        "pyfly.eda.destinations": "a, b",
+                        "pyfly.eda.group": "flydesk-idp",
+                    }
+                )
             )
             assert isinstance(bus, RedisStreamsEventBus)
             assert bus._streams == ["a", "b"]
@@ -57,12 +59,14 @@ def test_postgres_provider(self) -> None:
         from pyfly.eda.adapters.postgres import PostgresEventBus
 
         bus = EdaAutoConfiguration().event_publisher(
-            _config({
-                "pyfly.eda.provider": "postgres",
-                "pyfly.eda.postgres.dsn": "postgresql://x/y",
-                "pyfly.eda.destinations": "flydesk.idp.jobs",
-                "pyfly.eda.postgres.channel": "flydesk_eda",
-            })
+            _config(
+                {
+                    "pyfly.eda.provider": "postgres",
+                    "pyfly.eda.postgres.dsn": "postgresql://x/y",
+                    "pyfly.eda.destinations": "flydesk.idp.jobs",
+                    "pyfly.eda.postgres.channel": "flydesk_eda",
+                }
+            )
         )
         assert isinstance(bus, PostgresEventBus)
         assert bus._destinations == ["flydesk.idp.jobs"]
@@ -72,9 +76,7 @@ def test_postgres_provider_requires_dsn(self) -> None:
         import pytest
 
         with pytest.raises(ValueError, match="postgres.dsn is required"):
-            EdaAutoConfiguration().event_publisher(
-                _config({"pyfly.eda.provider": "postgres"})
-            )
+            EdaAutoConfiguration().event_publisher(_config({"pyfly.eda.provider": "postgres"}))
 
     def test_auto_provider_picks_kafka_when_available(self) -> None:
         with patch("pyfly.config.auto.AutoConfiguration.is_available") as is_avail:
diff --git a/tests/eda/test_circuit_breaker.py b/tests/eda/test_circuit_breaker.py
new file mode 100644
index 0000000..5ae79ad
--- /dev/null
+++ b/tests/eda/test_circuit_breaker.py
@@ -0,0 +1,61 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for EventCircuitBreaker — open/half-open/closed transitions."""
+
+from __future__ import annotations
+
+import pytest
+
+from pyfly.eda.circuit_breaker import CircuitBreakerConfig, CircuitOpenError, EventCircuitBreaker
+
+
+async def _fail() -> None:
+    raise RuntimeError("boom")
+
+
+async def _ok() -> str:
+    return "ok"
+
+
+class TestEventCircuitBreaker:
+    @pytest.mark.asyncio
+    async def test_opens_after_threshold(self):
+        cb = EventCircuitBreaker(CircuitBreakerConfig(failure_threshold=3, recovery_timeout_ms=10_000))
+        for _ in range(3):
+            with pytest.raises(RuntimeError):
+                await cb.execute(_fail)
+        # Now OPEN: further calls fast-fail without invoking the handler.
+        with pytest.raises(CircuitOpenError):
+            await cb.execute(_ok)
+
+    @pytest.mark.asyncio
+    async def test_recovers_after_repeated_reopen(self):
+        """Regression: the breaker must not get permanently stuck OPEN.
+
+        With recovery_timeout_ms=0 every call is eligible for a half-open trial.
+        Before the fix, the half-open counter accumulated across re-opens and the
+        breaker raised 'half-open quota exhausted' forever once half_open_max_calls
+        total trials had failed.
+        """
+        cb = EventCircuitBreaker(
+            CircuitBreakerConfig(failure_threshold=1, recovery_timeout_ms=0, half_open_max_calls=2)
+        )
+        # Trip and re-trip many more times than half_open_max_calls.
+        for _ in range(10):
+            with pytest.raises(RuntimeError):
+                await cb.execute(_fail)
+        # After all those failures a successful call must still be able to close it.
+        assert await cb.execute(_ok) == "ok"
+        # And the breaker is fully closed again.
+        assert await cb.execute(_ok) == "ok"
diff --git a/tests/eda/test_postgres_event_bus.py b/tests/eda/test_postgres_event_bus.py
index 8422a45..a3e7af0 100644
--- a/tests/eda/test_postgres_event_bus.py
+++ b/tests/eda/test_postgres_event_bus.py
@@ -50,14 +50,8 @@ def test_destinations_filter_preserved(self) -> None:
         ]
 
     def test_normalise_dsn_strips_dialect_markers(self) -> None:
-        assert (
-            _normalise_dsn("postgresql+asyncpg://u:p@h:5432/db")
-            == "postgresql://u:p@h:5432/db"
-        )
-        assert (
-            _normalise_dsn("postgresql+psycopg://u:p@h/db")
-            == "postgresql://u:p@h/db"
-        )
+        assert _normalise_dsn("postgresql+asyncpg://u:p@h:5432/db") == "postgresql://u:p@h:5432/db"
+        assert _normalise_dsn("postgresql+psycopg://u:p@h/db") == "postgresql://u:p@h/db"
         assert _normalise_dsn("postgresql://u:p@h/db") == "postgresql://u:p@h/db"
 
     def test_normalise_dsn_applied_in_constructor(self) -> None:
diff --git a/tests/logging/test_get_logger.py b/tests/logging/test_get_logger.py
new file mode 100644
index 0000000..ffb0408
--- /dev/null
+++ b/tests/logging/test_get_logger.py
@@ -0,0 +1,52 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for the structlog-or-stdlib ``get_logger`` factory."""
+
+from __future__ import annotations
+
+import builtins
+import importlib
+
+
+def test_get_logger_accepts_structured_kwargs():
+    from pyfly.logging import get_logger
+
+    log = get_logger("pyfly.test")
+    # Must not raise regardless of which backend is active.
+    log.info("an_event", method="GET", path="/x", status_code=200)
+    log.error("an_error", error="boom")
+
+
+def test_get_logger_falls_back_when_structlog_missing(monkeypatch):
+    """When structlog is not importable, get_logger must still return a logger
+    that accepts ``event, **kwargs`` (stdlib loggers would raise TypeError)."""
+    real_import = builtins.__import__
+
+    def _no_structlog(name, *args, **kwargs):
+        if name == "structlog" or name.startswith("structlog."):
+            raise ImportError("structlog disabled for test")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", _no_structlog)
+
+    import pyfly.logging as logging_mod
+
+    importlib.reload(logging_mod)
+    log = logging_mod.get_logger("pyfly.test.fallback")
+    # The stdlib-backed shim accepts structlog-style calls without raising.
+    log.info("http_request", method="GET", path="/widgets", status_code=200)
+
+    # Restore the module to its structlog-enabled state for other tests.
+    monkeypatch.undo()
+    importlib.reload(logging_mod)
diff --git a/tests/observability/test_correlation.py b/tests/observability/test_correlation.py
index 0f59ef9..3e0bf30 100644
--- a/tests/observability/test_correlation.py
+++ b/tests/observability/test_correlation.py
@@ -32,7 +32,6 @@
 from pyfly.web.adapters.starlette.filter_chain import WebFilterChainMiddleware
 from pyfly.web.adapters.starlette.filters.correlation_filter import CorrelationFilter
 
-
 # ---------------------------------------------------------------------------
 # correlation context vars
 # ---------------------------------------------------------------------------
@@ -107,13 +106,15 @@ async def reader() -> str:
 
 def _build_app() -> Starlette:
     async def endpoint(request):
-        return JSONResponse({
-            "correlation_id": get_correlation_id(),
-            "request_id": get_request_id(),
-            "tenant_id": get_tenant_id(),
-            "traceparent": get_traceparent(),
-            "tracestate": get_tracestate(),
-        })
+        return JSONResponse(
+            {
+                "correlation_id": get_correlation_id(),
+                "request_id": get_request_id(),
+                "tenant_id": get_tenant_id(),
+                "traceparent": get_traceparent(),
+                "tracestate": get_tracestate(),
+            }
+        )
 
     middleware = [Middleware(WebFilterChainMiddleware, filters=[CorrelationFilter()])]
     return Starlette(routes=[Route("/echo", endpoint)], middleware=middleware)
diff --git a/tests/transactional/saga/test_recovery.py b/tests/transactional/saga/test_recovery.py
index 33bee2c..89455af 100644
--- a/tests/transactional/saga/test_recovery.py
+++ b/tests/transactional/saga/test_recovery.py
@@ -467,3 +467,27 @@ def test_creates_with_none_optional_parameters(
             events_port=None,
         )
         assert service is not None
+
+
+class TestRecoveryWithStringTimestamp:
+    """Regression: the engine historically persisted ``started_at`` as an ISO
+    string, which made ``recover_stale`` raise ``TypeError`` (str < datetime)."""
+
+    async def test_recover_stale_tolerates_isoformat_started_at(
+        self,
+        adapter: InMemoryPersistenceAdapter,
+        recovery_service: SagaRecoveryService,
+    ) -> None:
+        await adapter.persist_state(
+            {
+                "correlation_id": "saga-iso",
+                "saga_name": "order-saga",
+                "status": "IN_FLIGHT",
+                "started_at": (datetime.now(UTC) - timedelta(hours=1)).isoformat(),
+            }
+        )
+        recovered = await recovery_service.recover_stale(stale_threshold_seconds=60)
+        assert recovered == 1
+        state = await adapter.get_state("saga-iso")
+        assert state is not None
+        assert state["status"] != "IN_FLIGHT"
diff --git a/tests/transactional/test_rest_controllers_mounting.py b/tests/transactional/test_rest_controllers_mounting.py
new file mode 100644
index 0000000..29ff197
--- /dev/null
+++ b/tests/transactional/test_rest_controllers_mounting.py
@@ -0,0 +1,121 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Integration tests: transactional REST controllers are mounted as HTTP routes.
+
+Regression for the bug where ``OrchestrationController`` / ``DeadLetterController`` /
+``WorkflowController`` were registered as beans but never mounted because the
+classes lacked web stereotype/mapping decorators, so the ``ControllerRegistrar``
+skipped them.
+"""
+
+from __future__ import annotations
+
+import pytest
+from starlette.routing import Route
+from starlette.testclient import TestClient
+
+from pyfly.context.application_context import ApplicationContext
+from pyfly.core.config import Config
+from pyfly.web.adapters.starlette.app import create_app
+
+
+def _transactional_context() -> ApplicationContext:
+    """Build a context with the full transactional stack enabled."""
+    return ApplicationContext(Config({"pyfly": {"transactional": {"enabled": "true"}}}))
+
+
+class TestTransactionalControllerMounting:
+    """The three REST controllers are discovered and mounted by create_app()."""
+
+    @pytest.mark.asyncio
+    async def test_routes_are_mounted(self) -> None:
+        ctx = _transactional_context()
+        await ctx.start()
+
+        app = create_app(context=ctx)
+
+        paths = {route.path for route in app.routes if isinstance(route, Route)}
+        assert "/api/orchestration/executions" in paths
+        assert "/api/orchestration/executions/{correlation_id}" in paths
+        assert "/api/orchestration/dlq" in paths
+        assert "/api/orchestration/dlq/{entry_id}" in paths
+        assert "/api/orchestration/dlq/{entry_id}/retry" in paths
+        assert "/api/orchestration/workflow/start" in paths
+        assert "/api/orchestration/workflow/signal" in paths
+
+    @pytest.mark.asyncio
+    async def test_list_executions_returns_200(self) -> None:
+        ctx = _transactional_context()
+        await ctx.start()
+
+        app = create_app(context=ctx)
+        client = TestClient(app)
+
+        response = client.get("/api/orchestration/executions")
+        assert response.status_code == 200
+        assert response.json() == []
+
+    @pytest.mark.asyncio
+    async def test_list_dlq_returns_200(self) -> None:
+        ctx = _transactional_context()
+        await ctx.start()
+
+        app = create_app(context=ctx)
+        client = TestClient(app)
+
+        response = client.get("/api/orchestration/dlq")
+        assert response.status_code == 200
+        assert response.json() == []
+
+    @pytest.mark.asyncio
+    async def test_get_unknown_execution_returns_no_content(self) -> None:
+        ctx = _transactional_context()
+        await ctx.start()
+
+        app = create_app(context=ctx)
+        client = TestClient(app)
+
+        # The handler returns ``None`` for an unknown id; the framework maps a
+        # ``None`` return value to ``204 No Content``.
+        response = client.get("/api/orchestration/executions/does-not-exist")
+        assert response.status_code == 204
+
+    @pytest.mark.asyncio
+    async def test_dlq_delete_unknown_returns_200(self) -> None:
+        ctx = _transactional_context()
+        await ctx.start()
+
+        app = create_app(context=ctx)
+        client = TestClient(app)
+
+        response = client.delete("/api/orchestration/dlq/missing")
+        assert response.status_code == 200
+        assert response.json() == {"deleted": False}
+
+    @pytest.mark.asyncio
+    async def test_workflow_signal_binds_json_body(self) -> None:
+        ctx = _transactional_context()
+        await ctx.start()
+
+        app = create_app(context=ctx)
+        client = TestClient(app)
+
+        # Body[SignalRequest] is validated and bound; an unknown correlation id
+        # is simply not delivered (no error raised).
+        response = client.post(
+            "/api/orchestration/workflow/signal",
+            json={"correlation_id": "unknown", "signal": "approve", "payload": {"ok": True}},
+        )
+        assert response.status_code == 200
+        assert response.json() == {"delivered": False}
diff --git a/tests/transactional/workflow/test_compensation.py b/tests/transactional/workflow/test_compensation.py
new file mode 100644
index 0000000..29012fe
--- /dev/null
+++ b/tests/transactional/workflow/test_compensation.py
@@ -0,0 +1,247 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Integration tests for workflow step compensation on failure."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import pytest
+
+from pyfly.transactional.core.argument import CompensationError, FromStep
+from pyfly.transactional.core.events import LoggerOrchestrationEvents
+from pyfly.transactional.core.model import ExecutionStatus, StepStatus
+from pyfly.transactional.core.persistence import InMemoryPersistenceProvider
+from pyfly.transactional.workflow.annotations import (
+    compensation_step,
+    workflow,
+    workflow_step,
+)
+from pyfly.transactional.workflow.engine import WorkflowEngine
+from pyfly.transactional.workflow.executor import WorkflowExecutor
+from pyfly.transactional.workflow.registry import WorkflowRegistry
+
+
+def _make_engine() -> tuple[WorkflowEngine, WorkflowRegistry]:
+    registry = WorkflowRegistry()
+    engine = WorkflowEngine(
+        registry=registry,
+        executor=WorkflowExecutor(events=LoggerOrchestrationEvents()),
+        persistence=InMemoryPersistenceProvider(),
+    )
+    return engine, registry
+
+
+class TestWorkflowCompensation:
+    @pytest.mark.asyncio
+    async def test_completed_compensatable_step_is_rolled_back_on_later_failure(self) -> None:
+        """An early compensatable step must be compensated when a later step fails."""
+        side_effects: list[str] = []
+
+        @workflow(id="comp-basic")
+        class CompBasic:
+            @workflow_step(id="reserve", compensatable=True, compensation_method="release")
+            async def reserve(self) -> str:
+                side_effects.append("reserve")
+                return "reserved"
+
+            @workflow_step(id="charge", depends_on=["reserve"])
+            async def charge(self) -> None:
+                side_effects.append("charge")
+                msg = "payment declined"
+                raise RuntimeError(msg)
+
+            @compensation_step(for_step="reserve")
+            async def release(self) -> None:
+                side_effects.append("release")
+
+        engine, registry = _make_engine()
+        registry.register_from_bean(CompBasic())
+
+        result = await engine.start("comp-basic")
+
+        assert result.status == ExecutionStatus.FAILED
+        assert not result.successful
+        # The compensation method ran after the failure.
+        assert side_effects == ["reserve", "charge", "release"]
+
+    @pytest.mark.asyncio
+    async def test_multiple_compensations_run_in_reverse_order(self) -> None:
+        """Completed compensatable steps roll back newest-first."""
+        order: list[str] = []
+
+        @workflow(id="comp-order")
+        class CompOrder:
+            @workflow_step(id="a", compensatable=True, compensation_method="undo_a")
+            async def a(self) -> str:
+                return "a"
+
+            @workflow_step(id="b", depends_on=["a"], compensatable=True, compensation_method="undo_b")
+            async def b(self) -> str:
+                return "b"
+
+            @workflow_step(id="c", depends_on=["b"])
+            async def c(self) -> None:
+                msg = "boom"
+                raise RuntimeError(msg)
+
+            @compensation_step(for_step="a")
+            async def undo_a(self) -> None:
+                order.append("undo_a")
+
+            @compensation_step(for_step="b")
+            async def undo_b(self) -> None:
+                order.append("undo_b")
+
+        engine, registry = _make_engine()
+        registry.register_from_bean(CompOrder())
+
+        result = await engine.start("comp-order")
+
+        assert result.status == ExecutionStatus.FAILED
+        # b completed after a, so its compensation runs first (reverse order).
+        assert order == ["undo_b", "undo_a"]
+
+    @pytest.mark.asyncio
+    async def test_non_compensatable_step_is_not_compensated(self) -> None:
+        """A completed step without ``compensatable=True`` must be left untouched."""
+        side_effects: list[str] = []
+
+        @workflow(id="comp-skip")
+        class CompSkip:
+            @workflow_step(id="plain")
+            async def plain(self) -> str:
+                return "plain"
+
+            @workflow_step(id="fail", depends_on=["plain"])
+            async def fail(self) -> None:
+                msg = "boom"
+                raise RuntimeError(msg)
+
+            @compensation_step(for_step="plain")
+            async def undo_plain(self) -> None:
+                side_effects.append("undo_plain")
+
+        engine, registry = _make_engine()
+        registry.register_from_bean(CompSkip())
+
+        result = await engine.start("comp-skip")
+
+        assert result.status == ExecutionStatus.FAILED
+        # 'plain' is not marked compensatable -> its handler must not run.
+        assert side_effects == []
+
+    @pytest.mark.asyncio
+    async def test_compensation_receives_triggering_error_and_step_result(self) -> None:
+        """Compensation methods can inject the original step result and the error."""
+        captured: dict[str, object] = {}
+
+        @workflow(id="comp-args")
+        class CompArgs:
+            @workflow_step(id="reserve", compensatable=True, compensation_method="release")
+            async def reserve(self) -> dict[str, str]:
+                return {"reservation_id": "R-1"}
+
+            @workflow_step(id="charge", depends_on=["reserve"])
+            async def charge(self) -> None:
+                msg = "declined"
+                raise RuntimeError(msg)
+
+            @compensation_step(for_step="reserve")
+            async def release(
+                self,
+                reservation: Annotated[dict, FromStep("reserve")],
+                error: Annotated[BaseException, CompensationError()],
+            ) -> None:
+                captured["reservation"] = reservation
+                captured["error"] = error
+
+        engine, registry = _make_engine()
+        registry.register_from_bean(CompArgs())
+
+        result = await engine.start("comp-args")
+
+        assert result.status == ExecutionStatus.FAILED
+        assert captured["reservation"] == {"reservation_id": "R-1"}
+        assert isinstance(captured["error"], BaseException)
+
+    @pytest.mark.asyncio
+    async def test_no_compensation_when_workflow_succeeds(self) -> None:
+        """Compensation must not run on the happy path."""
+        side_effects: list[str] = []
+
+        @workflow(id="comp-happy")
+        class CompHappy:
+            @workflow_step(id="reserve", compensatable=True, compensation_method="release")
+            async def reserve(self) -> str:
+                return "reserved"
+
+            @workflow_step(id="charge", depends_on=["reserve"])
+            async def charge(self) -> str:
+                return "charged"
+
+            @compensation_step(for_step="reserve")
+            async def release(self) -> None:
+                side_effects.append("release")
+
+        engine, registry = _make_engine()
+        registry.register_from_bean(CompHappy())
+
+        result = await engine.start("comp-happy")
+
+        assert result.status == ExecutionStatus.COMPLETED
+        assert side_effects == []
+
+    @pytest.mark.asyncio
+    async def test_compensation_records_step_status_in_context(self) -> None:
+        """A rolled-back step is marked COMPENSATED on the execution context."""
+        recorded: dict[str, StepStatus] = {}
+
+        @workflow(id="comp-status")
+        class CompStatus:
+            @workflow_step(id="reserve", compensatable=True, compensation_method="release")
+            async def reserve(self) -> str:
+                return "reserved"
+
+            @workflow_step(id="charge", depends_on=["reserve"])
+            async def charge(self) -> None:
+                msg = "boom"
+                raise RuntimeError(msg)
+
+            @compensation_step(for_step="reserve")
+            async def release(self) -> None: ...
+
+            @workflow_step(id="probe", depends_on=["charge"])
+            async def probe(self) -> None: ...  # never reached
+
+        engine, registry = _make_engine()
+        registry.register_from_bean(CompStatus())
+
+        # Drive directly through the executor to inspect the context.
+        from pyfly.transactional.core.context import ExecutionContext
+        from pyfly.transactional.core.exceptions import StepFailedError
+        from pyfly.transactional.core.model import ExecutionPattern
+
+        definition = registry.get("comp-status")
+        assert definition is not None
+        ctx = ExecutionContext(name="comp-status", pattern=ExecutionPattern.WORKFLOW)
+        executor = WorkflowExecutor(events=LoggerOrchestrationEvents())
+
+        with pytest.raises(StepFailedError):
+            await executor.execute(definition, ctx)
+
+        reserve_rec = ctx.get_step("reserve")
+        assert reserve_rec is not None
+        recorded["reserve"] = reserve_rec.status
+        assert recorded["reserve"] == StepStatus.COMPENSATED
diff --git a/tests/transactional/workflow/test_engine.py b/tests/transactional/workflow/test_engine.py
index fb9c9d1..0c8d82a 100644
--- a/tests/transactional/workflow/test_engine.py
+++ b/tests/transactional/workflow/test_engine.py
@@ -77,6 +77,34 @@ async def x(self) -> None:
         assert not result.successful
 
 
+class TestChildWorkflowFireAndForget:
+    @pytest.mark.asyncio
+    async def test_fire_and_forget_returns_real_correlation_id(self) -> None:
+        """Regression: fire-and-forget child start must return the child's real
+        correlation id (and persist it), not the asyncio Task name."""
+        from pyfly.transactional.workflow.child_workflow_service import ChildWorkflowService
+
+        @workflow(id="child-wf")
+        class ChildWf:
+            @workflow_step(id="only")
+            async def only(self) -> str:
+                return "ok"
+
+        engine, registry = _make_engine()
+        registry.register_from_bean(ChildWf())
+
+        svc = ChildWorkflowService()
+        svc.bind(engine)
+        correlation_id = await svc.start("child-wf", wait_for_completion=False)
+
+        assert isinstance(correlation_id, str)
+        assert not correlation_id.startswith("Task-")
+        # The engine persisted the execution under this id before returning.
+        state = await engine.get_execution(correlation_id)
+        assert state is not None
+        assert state.correlation_id == correlation_id
+
+
 class TestSignalDriven:
     @pytest.mark.asyncio
     async def test_wait_for_signal_resumes_workflow(self) -> None:
diff --git a/tests/transactional/workflow/test_registry.py b/tests/transactional/workflow/test_registry.py
index 186790f..656c499 100644
--- a/tests/transactional/workflow/test_registry.py
+++ b/tests/transactional/workflow/test_registry.py
@@ -29,6 +29,28 @@ async def s1(self) -> None: ...
     assert reg.get("a") is definition
 
 
+def test_wait_for_all_any_timeouts_propagated() -> None:
+    """Regression: @wait_for_all/@wait_for_any timeout_ms must reach the step
+    definition (previously dropped, causing unbounded waits)."""
+    from pyfly.transactional.workflow.annotations import wait_for_all, wait_for_any
+
+    @workflow(id="waits")
+    class W:
+        @workflow_step(id="all")
+        @wait_for_all("a", "b", timeout_ms=1500)
+        async def all_step(self) -> None: ...
+
+        @workflow_step(id="any")
+        @wait_for_any("x", "y", timeout_ms=2500)
+        async def any_step(self) -> None: ...
+
+    definition = WorkflowRegistry().register_from_bean(W())
+    assert definition.steps["all"].wait_for_all == ("a", "b")
+    assert definition.steps["all"].wait_for_all_timeout_ms == 1500
+    assert definition.steps["any"].wait_for_any == ("x", "y")
+    assert definition.steps["any"].wait_for_any_timeout_ms == 2500
+
+
 def test_unregistered_class_raises() -> None:
     class NotADecorated: ...
 
diff --git a/tests/web/test_fastapi_adapter.py b/tests/web/test_fastapi_adapter.py
index 8a086ad..367bad9 100644
--- a/tests/web/test_fastapi_adapter.py
+++ b/tests/web/test_fastapi_adapter.py
@@ -18,7 +18,7 @@
 import pytest
 from pydantic import BaseModel
 
-from pyfly.container.stereotypes import rest_controller, service
+from pyfly.container.stereotypes import controller_advice, rest_controller, service
 from pyfly.web.exception_handler import exception_handler
 from pyfly.web.mappings import delete_mapping, get_mapping, post_mapping, request_mapping
 from pyfly.web.params import Body, PathVar, QueryParam
@@ -39,6 +39,17 @@ class ItemNotFoundError(Exception):
     pass
 
 
+class ItemConflictError(Exception):
+    """Raised by the controller but handled by a global @controller_advice bean."""
+
+
+@controller_advice
+class GlobalErrorAdvice:
+    @exception_handler(ItemConflictError)
+    async def handle_conflict(self, exc: ItemConflictError):
+        return 409, {"error": str(exc), "scope": "global"}
+
+
 @service
 class ItemService:
     def find(self, item_id: str) -> dict:
@@ -75,6 +86,10 @@ async def create_item(self, body: Body[CreateItemRequest]) -> dict:
     async def delete_item(self, item_id: PathVar[str]) -> None:
         pass
 
+    @get_mapping("/{item_id}/conflict")
+    async def conflicting_item(self, item_id: PathVar[str]) -> dict:
+        raise ItemConflictError(f"Item {item_id} already exists")
+
     @exception_handler(ItemNotFoundError)
     async def handle_not_found(self, exc: ItemNotFoundError):
         return 404, {"error": str(exc)}
@@ -201,3 +216,64 @@ async def test_exception_handler_on_controller(self):
         response = client.get("/api/items/not-found")
         assert response.status_code == 404
         assert "not found" in response.json()["error"]
+
+    @pytest.mark.asyncio
+    async def test_global_controller_advice_handler(self):
+        """A @controller_advice global handler converts a controller exception."""
+        from starlette.testclient import TestClient
+
+        from pyfly.context.application_context import ApplicationContext
+        from pyfly.core.config import Config
+        from pyfly.web.adapters.fastapi.adapter import FastAPIWebAdapter
+
+        ctx = ApplicationContext(Config({}))
+        ctx.register_bean(ItemService)
+        ctx.register_bean(ItemController)
+        ctx.register_bean(GlobalErrorAdvice)
+        await ctx.start()
+
+        adapter = FastAPIWebAdapter()
+        app = adapter.create_app(context=ctx, docs_enabled=False)
+        client = TestClient(app, raise_server_exceptions=False)
+
+        response = client.get("/api/items/abc/conflict")
+        assert response.status_code == 409
+        body = response.json()
+        assert body["scope"] == "global"
+        assert "already exists" in body["error"]
+
+
+class TestFastAPIOpenAPIGeneration:
+    @pytest.mark.asyncio
+    async def test_openapi_json_includes_controller_route(self):
+        """The generated /openapi.json includes auto-discovered controller paths."""
+        from starlette.testclient import TestClient
+
+        from pyfly.context.application_context import ApplicationContext
+        from pyfly.core.config import Config
+        from pyfly.web.adapters.fastapi.adapter import FastAPIWebAdapter
+
+        ctx = ApplicationContext(Config({}))
+        ctx.register_bean(ItemService)
+        ctx.register_bean(ItemController)
+        await ctx.start()
+
+        adapter = FastAPIWebAdapter()
+        app = adapter.create_app(context=ctx, docs_enabled=True)
+        client = TestClient(app)
+
+        response = client.get("/openapi.json")
+        assert response.status_code == 200
+        spec = response.json()
+        assert spec["openapi"] == "3.1.0"
+        # Controller routes appear in the generated spec even though FastAPI's
+        # own introspection registers them with include_in_schema=False.
+        assert "/api/items/{item_id}" in spec["paths"]
+        get_op = spec["paths"]["/api/items/{item_id}"]["get"]
+        # These fields come from PyFly's OpenAPIGenerator reading the handler's
+        # binding metadata — FastAPI's native introspection of a `PathVar[str]`
+        # handler cannot produce them (it mangles operationId and omits the path
+        # parameter), so this asserts the generated spec is actually in use.
+        assert get_op["operationId"] == "get_item"
+        path_params = [p for p in get_op.get("parameters", []) if p.get("in") == "path"]
+        assert any(p["name"] == "item_id" for p in path_params)
diff --git a/tests/web/test_filter_chain.py b/tests/web/test_filter_chain.py
index 3b88831..810d725 100644
--- a/tests/web/test_filter_chain.py
+++ b/tests/web/test_filter_chain.py
@@ -15,6 +15,8 @@
 
 from __future__ import annotations
 
+import asyncio
+
 import pytest
 from starlette.applications import Starlette
 from starlette.middleware import Middleware
@@ -194,6 +196,94 @@ async def receive():
         assert headers[b"x-filter-a"] == b"applied"
 
 
+class TestFilterChainStreaming:
+    """Streaming responses (SSE, large downloads) must pass through incrementally,
+    not be buffered until the generator completes."""
+
+    @pytest.mark.asyncio
+    async def test_streaming_response_forwarded_incrementally(self):
+        """First chunk must reach the client BEFORE the generator produces the last one."""
+        release = asyncio.Event()
+        chunk1_seen = asyncio.Event()
+
+        async def streaming_app(scope, receive, send):
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 200,
+                    "headers": [(b"content-type", b"text/event-stream")],
+                }
+            )
+            await send({"type": "http.response.body", "body": b"chunk1", "more_body": True})
+            await release.wait()  # block until the test confirms chunk1 was delivered
+            await send({"type": "http.response.body", "body": b"chunk2", "more_body": False})
+
+        mw = WebFilterChainMiddleware(app=streaming_app, filters=[HeaderFilter()])
+
+        sent: list[dict] = []
+
+        async def capture_send(message):
+            sent.append(message)
+            if message.get("type") == "http.response.body" and message.get("body") == b"chunk1":
+                chunk1_seen.set()
+
+        scope = {"type": "http", "method": "GET", "path": "/sse", "query_string": b"", "headers": []}
+
+        async def receive():
+            return {"type": "http.request", "body": b""}
+
+        task = asyncio.create_task(mw(scope, receive, capture_send))
+
+        # If the middleware buffers the whole response, this times out (the second
+        # chunk is gated behind ``release`` which we have not set yet).
+        await asyncio.wait_for(chunk1_seen.wait(), timeout=2.0)
+
+        start_msgs = [m for m in sent if m["type"] == "http.response.start"]
+        assert start_msgs, "start message must be flushed before the body streams"
+        body_msgs = [m for m in sent if m["type"] == "http.response.body"]
+        assert body_msgs[0]["body"] == b"chunk1"
+        assert body_msgs[0]["more_body"] is True
+
+        release.set()
+        await asyncio.wait_for(task, timeout=2.0)
+
+        assert sent[-1]["body"] == b"chunk2"
+        assert sent[-1]["more_body"] is False
+
+    @pytest.mark.asyncio
+    async def test_non_streaming_response_still_buffered_and_filtered(self):
+        """Single-shot responses keep working and filters can still mutate headers."""
+
+        async def json_app(scope, receive, send):
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 200,
+                    "headers": [(b"content-type", b"application/json")],
+                }
+            )
+            await send({"type": "http.response.body", "body": b'{"ok":true}', "more_body": False})
+
+        mw = WebFilterChainMiddleware(app=json_app, filters=[HeaderFilter()])
+        sent: list[dict] = []
+
+        async def capture_send(message):
+            sent.append(message)
+
+        scope = {"type": "http", "method": "GET", "path": "/data", "query_string": b"", "headers": []}
+
+        async def receive():
+            return {"type": "http.request", "body": b""}
+
+        await mw(scope, receive, capture_send)
+
+        start = sent[0]
+        assert start["type"] == "http.response.start"
+        assert dict(start["headers"])[b"x-filter-a"] == b"applied"
+        body = b"".join(m.get("body", b"") for m in sent if m["type"] == "http.response.body")
+        assert body == b'{"ok":true}'
+
+
 class TestFilterChainCustomDiscovery:
     @pytest.mark.asyncio
     async def test_custom_filter_auto_discovered_in_create_app(self):
diff --git a/uv.lock b/uv.lock
index be7f8b7..6552274 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1589,7 +1589,7 @@ wheels = [
 
 [[package]]
 name = "pyfly"
-version = "26.5.4"
+version = "26.5.6"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },