python-neva 4.0.0__tar.gz → 5.0.0__tar.gz

{python_neva-4.0.0 → python_neva-5.0.0}/.gitlab-ci.yml

@@ -48,6 +48,15 @@ pyrefly:
   script:
     - uv run --frozen pyrefly check
 
+# The fragments shipped in the wheel cite the tests that prove their claims.
+# Every cited path must still resolve, so a behaviour change that leaves the
+# guidance behind fails here rather than reaching an agent as a wrong answer.
+guidelines:
+  extends: [.uv_base, .default_rules]
+  stage: code_qa
+  script:
+    - uv run --frozen neva-boost check neva/guidelines/fragments
+
 ##### Test #####
 pytest:
   extends: [.uv_base, .default_rules]

{python_neva-4.0.0 → python_neva-5.0.0}/CHANGELOG.md

@@ -1,3 +1,33 @@
+## 5.0.0 (2026-09-01)
+
+### 💥 Boom
+
+- **obs**: drop OpenTelemetry and pyinstrument from the core
+
+### ✨ Features
+
+- **obs**: resolve logging through named channels
+- **deps**: offer neva-boost through the boost extra
+
+### 💚👷 CI & Build
+
+- **guidelines**: fail when a fragment cites a test that is gone
+
+### 📝💡 Documentation
+
+- **guidelines**: rule out resolving from the container in register()
+- **guidelines**: cover logging channels, and where OTel now lives
+
+## 4.1.0 (2026-08-31)
+
+### ✅🤡🧪 Tests
+
+- **support**: add tests for results and options
+
+### 📝💡 Documentation
+
+- **guidelines**: ship agent guidelines in the wheel
+
 ## 4.0.0 (2026-08-28)
 
 ### 💥 Boom

{python_neva-4.0.0 → python_neva-5.0.0}/CLAUDE.md

@@ -138,4 +138,15 @@ rendered changelog. See `README.md` for the full flow and the plugin list.
 
 ## Documentation
 
-- Architecture guides: `wiki/architecture/`
+Agent guidelines live in `neva/guidelines/fragments/` and ship inside the wheel, so a
+consuming project gets the guidance for the version it actually installed. They are
+discovered by `neva-boost` through the `neva.boost` entry point (`neva/guidelines/manifest.py`).
+
+- One fragment per topic, with frontmatter: `id`, `title`, `requires` (a version
+  specifier), `triggers`, `priority`, `verified_by`.
+- **`verified_by` lists the tests that prove the fragment's claims.** Every path must
+  resolve. When you change behaviour, update the fragment in the same commit as the code
+  and the test — that pairing is what keeps the guidance honest.
+- Terse and rule-shaped, not narrative: this text is loaded into an agent's context.
+- Nothing here may describe another package. `neva-fastapi` and friends ship their own
+  fragments; a cross-package claim made here cannot be verified or maintained.

{python_neva-4.0.0 → python_neva-5.0.0}/PKG-INFO

@@ -1,21 +1,21 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 4.0.0
+Version: 5.0.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: asyncpg>=0.30.0
 Requires-Dist: cryptography>=46.0.3
 Requires-Dist: dishka>=1.10.0
-Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.62b0
 Requires-Dist: pwdlib[argon2,bcrypt]>=0.3.0
 Requires-Dist: pydantic>=2.7
-Requires-Dist: pyinstrument>=5.1.1
 Requires-Dist: sqlalchemy[asyncio]>=2.0.0
 Requires-Dist: structlog>=25.5.0
 Requires-Dist: typing-extensions>=4.13
 Provides-Extra: asgi
 Requires-Dist: neva-asgi>=0.1.1; extra == 'asgi'
+Provides-Extra: boost
+Requires-Dist: neva-boost>=0.2.1; extra == 'boost'
 Provides-Extra: fastapi
 Requires-Dist: neva-fastapi>=1.1.1; extra == 'fastapi'
 Provides-Extra: faststream
@@ -47,17 +47,59 @@ independent repo, independently versioned and published.
 
 | Package           | Repo / directory   | Role                                                                                  | Status                          |
 | ----------------- | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------- |
-| `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, observability, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
+| `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, structured logging, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
 | `neva-fastapi`    | `neva-fastapi/`    | FastAPI integration — `App` extends `FastAPI` and wires dishka into routes. Pulled in via the `python-neva[fastapi]` extra. | published ([PyPI](https://pypi.org/project/neva-fastapi/)) |
 | `neva-asgi`       | `neva-asgi/`       | **ASGI middleware** — correlation IDs and per-request profiling. Pure ASGI, so both the HTTP and messaging integrations can consume it. Pulled in via the `python-neva[asgi]` extra. | published ([PyPI](https://pypi.org/project/neva-asgi/)) |
 | `neva-faststream` | `neva-faststream/` | FastStream (messaging) integration.                                                   | scaffolded, early placeholder   |
 | `neva-auth`       | `neva-auth/`       | Authentication & identity toolkit — token-issuance engine, OAuth2 grants, guards, pluggable formats/backends. | core complete, OAuth-server slice in progress |
+| `neva-otel`       | `neva-otel/`       | **OpenTelemetry** — SDK wiring, tracer and meter providers, exporters, samplers and instrumentors. Kept out of the core so nothing is committed to an observability backend. | planned |
+| `neva-boost`      | `neva-boost/`      | **Agent guidelines** — composes each installed package's versioned guideline fragments into a project's agent configuration (Claude Code skills or `AGENTS.md`). Dev-time tooling; pulled in via the `python-neva[boost]` extra. | published ([PyPI](https://pypi.org/project/neva-boost/)) |
 | `neva-example`    | `neva-example/`    | Reference application consuming `python-neva[fastapi]`. Not published; demonstration + integration test bed. | unpublished                     |
 
 > When working across packages locally, each repo can be cloned as a sibling
 > directory; integration packages depend on `python-neva` from PyPI (or an
 > editable local path during development).
 
+## Logging
+
+Logging is a set of named channels, each with its own driver, level and output —
+Laravel's `Log`, configured from one `config/obs.py` namespace.
+
+```python
+config = {
+    "logging": {
+        "default": "stdout",
+        "channels": {
+            "stdout": {"driver": "console", "level": "DEBUG"},
+            "json":   {"driver": "json", "stream": "stderr", "level": "INFO"},
+            "audit":  {"driver": "file", "path": "var/audit.log"},
+            "both":   {"driver": "stack", "channels": ["json", "audit"]},
+        },
+    },
+}
+```
+
+```python
+from neva.support.facade import Log
+
+Log.info("order placed", order_id=42)                    # default channel
+Log.channel("audit").warning("role granted", actor="root")
+Log.bind(tenant="acme")                                  # every channel, this context
+```
+
+Drivers are `console`, `json`, `file`, `stack` and `null`. With no `config/obs.py`
+at all, logging still works: a console channel on stdout at `DEBUG`.
+
+Each channel carries its own structlog processor chain rather than going through
+the process-global `structlog.configure()`, so one application's renderer cannot
+leak into another in the same interpreter. `LogManager.processor(fn)` lets a
+plugin add a processor to every chain — the seam `neva-otel` uses to put the
+current span's ids on every record.
+
+**Tracing and metrics are deliberately not here.** They live in `neva-otel`, so
+the core carries no OpenTelemetry dependency and commits no application to an
+observability backend.
+
 ## Develop
 
 ```bash
@@ -103,10 +145,9 @@ rewrite the new tag with the rendered changelog as its annotation.
 ## Feature ideas
 
 - Feature-parity FastStream integration (now scaffolded as `neva-faststream`)
-- Finish cleaning up the core package (moving any remaining ASGI-dependent code into the appropriate integration packages)
 - Improved router registration (auto-discovery OR provider-based? both?)
 - Improved security tooling (performance improvements, better defaults, etc.)
-- Better OpenTelemetry integration
+- OpenTelemetry as a plugin (`neva-otel`) — the core keeps logging and takes no OTel dependency
 - Improved factory module (based on Polyfactory)
 - Queue/Jobs system
 - CLI integration

{python_neva-4.0.0 → python_neva-5.0.0}/README.md

@@ -18,17 +18,59 @@ independent repo, independently versioned and published.
 
 | Package           | Repo / directory   | Role                                                                                  | Status                          |
 | ----------------- | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------- |
-| `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, observability, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
+| `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, structured logging, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
 | `neva-fastapi`    | `neva-fastapi/`    | FastAPI integration — `App` extends `FastAPI` and wires dishka into routes. Pulled in via the `python-neva[fastapi]` extra. | published ([PyPI](https://pypi.org/project/neva-fastapi/)) |
 | `neva-asgi`       | `neva-asgi/`       | **ASGI middleware** — correlation IDs and per-request profiling. Pure ASGI, so both the HTTP and messaging integrations can consume it. Pulled in via the `python-neva[asgi]` extra. | published ([PyPI](https://pypi.org/project/neva-asgi/)) |
 | `neva-faststream` | `neva-faststream/` | FastStream (messaging) integration.                                                   | scaffolded, early placeholder   |
 | `neva-auth`       | `neva-auth/`       | Authentication & identity toolkit — token-issuance engine, OAuth2 grants, guards, pluggable formats/backends. | core complete, OAuth-server slice in progress |
+| `neva-otel`       | `neva-otel/`       | **OpenTelemetry** — SDK wiring, tracer and meter providers, exporters, samplers and instrumentors. Kept out of the core so nothing is committed to an observability backend. | planned |
+| `neva-boost`      | `neva-boost/`      | **Agent guidelines** — composes each installed package's versioned guideline fragments into a project's agent configuration (Claude Code skills or `AGENTS.md`). Dev-time tooling; pulled in via the `python-neva[boost]` extra. | published ([PyPI](https://pypi.org/project/neva-boost/)) |
 | `neva-example`    | `neva-example/`    | Reference application consuming `python-neva[fastapi]`. Not published; demonstration + integration test bed. | unpublished                     |
 
 > When working across packages locally, each repo can be cloned as a sibling
 > directory; integration packages depend on `python-neva` from PyPI (or an
 > editable local path during development).
 
+## Logging
+
+Logging is a set of named channels, each with its own driver, level and output —
+Laravel's `Log`, configured from one `config/obs.py` namespace.
+
+```python
+config = {
+    "logging": {
+        "default": "stdout",
+        "channels": {
+            "stdout": {"driver": "console", "level": "DEBUG"},
+            "json":   {"driver": "json", "stream": "stderr", "level": "INFO"},
+            "audit":  {"driver": "file", "path": "var/audit.log"},
+            "both":   {"driver": "stack", "channels": ["json", "audit"]},
+        },
+    },
+}
+```
+
+```python
+from neva.support.facade import Log
+
+Log.info("order placed", order_id=42)                    # default channel
+Log.channel("audit").warning("role granted", actor="root")
+Log.bind(tenant="acme")                                  # every channel, this context
+```
+
+Drivers are `console`, `json`, `file`, `stack` and `null`. With no `config/obs.py`
+at all, logging still works: a console channel on stdout at `DEBUG`.
+
+Each channel carries its own structlog processor chain rather than going through
+the process-global `structlog.configure()`, so one application's renderer cannot
+leak into another in the same interpreter. `LogManager.processor(fn)` lets a
+plugin add a processor to every chain — the seam `neva-otel` uses to put the
+current span's ids on every record.
+
+**Tracing and metrics are deliberately not here.** They live in `neva-otel`, so
+the core carries no OpenTelemetry dependency and commits no application to an
+observability backend.
+
 ## Develop
 
 ```bash
@@ -74,10 +116,9 @@ rewrite the new tag with the rendered changelog as its annotation.
 ## Feature ideas
 
 - Feature-parity FastStream integration (now scaffolded as `neva-faststream`)
-- Finish cleaning up the core package (moving any remaining ASGI-dependent code into the appropriate integration packages)
 - Improved router registration (auto-discovery OR provider-based? both?)
 - Improved security tooling (performance improvements, better defaults, etc.)
-- Better OpenTelemetry integration
+- OpenTelemetry as a plugin (`neva-otel`) — the core keeps logging and takes no OTel dependency
 - Improved factory module (based on Polyfactory)
 - Queue/Jobs system
 - CLI integration

{python_neva-4.0.0 → python_neva-5.0.0}/neva/database/manager.py

@@ -10,7 +10,6 @@ from neva.database.config import ConnectionConfig
 from neva.database.connection import ConnectionManager, TransactionContext
 from neva.database.transaction import BoundTransaction
 from neva.obs import LogManager
-from neva.obs.instrumentation.sqlalchemy import instrument
 from neva.support import Nothing, Option, Some, from_optional
 
 
@@ -36,7 +35,6 @@ class DatabaseManager:
             name: The connection name.
             engine: The async engine.
         """
-        instrument(engine)
         self._connections[name] = ConnectionManager(
             name,
             self._tx_context,

python_neva-5.0.0/neva/guidelines/__init__.py

@@ -0,0 +1,6 @@
+"""Guideline fragments and the manifest `neva-boost` reads to find them."""
+
+from neva.guidelines.manifest import MANIFEST
+
+
+__all__ = ["MANIFEST"]

python_neva-5.0.0/neva/guidelines/fragments/configuration.md

@@ -0,0 +1,108 @@
+---
+id: configuration
+title: Configuration
+requires: python-neva>=4.0
+triggers: [reading a config value, adding a config file, Config.get, config namespace, environment settings, providers list]
+priority: 50
+verified_by: [tests/config/test_repository.py, tests/config/test_loader.py, tests/config/test_config_path_resolution.py, tests/arch/test_config_shapes.py]
+---
+
+# Configuration
+
+A flat directory of `.py` files, each exporting a module-level `config = {...}` dict. **The
+filename is the namespace.** Values are read by dot-notation and come back as `Result`.
+
+```
+src/config/app.py       → "app"
+src/config/database.py  → "database"
+src/config/providers.py → "providers"
+```
+
+Config files are real modules executed at boot, so they may compute values and import helpers.
+Keep them pure — no I/O, no connections.
+
+## Where the directory comes from
+
+`config_path` argument, else `$NEVA_CONFIG_PATH`, else `./config` relative to the working
+directory. Deliberately a dedicated subdirectory, never the project root: every `.py` in it is
+imported to read its `config` dict, so a folder of ordinary modules would be executed.
+
+The loader globs `*.py` except `__init__.py`, imports each file, and takes its `config`
+attribute **only if it is a dict**. A file with no `config`, or a non-dict `config`, is skipped
+silently — check that first when a namespace seems missing. A missing directory, a
+`SyntaxError`, or any import-time exception aborts boot with `RuntimeError`.
+
+There is no CLI, no generator, and no `ConfigServiceProvider`: loading is wired directly into
+`Application.__init__`.
+
+## Namespaces that drive boot
+
+| Key | Meaning |
+| --- | ------- |
+| `providers.providers` | Providers to register. |
+| `app.providers` | Further providers, appended after those. |
+
+## Typed shapes
+
+Each package declares a `TypedDict` for the keys **it** reads, so a shape never advertises keys
+its own package ignores. Annotate your file to have a type checker catch typos before boot.
+
+```python
+from neva.arch import AppConfig
+config: AppConfig = {"key": "...", "providers": [ActorServiceProvider]}
+```
+
+`AppConfig` (`neva.arch`) covers `app.key`, `app.previous_keys`, `app.providers`, all optional.
+`ProviderConfig` (`neva.arch`) covers `providers.providers`. `DatabaseConfig`
+(`neva.database`) covers the `database` namespace, and its `connections` key is **required**.
+The `app` namespace is shared — an integration package declares the keys it adds.
+
+## Reading
+
+Inject `ConfigRepository` inside services you unit-test; use the `Config` facade for
+cross-cutting reads. Both resolve the same instance.
+
+```python
+Config.get("app.title").unwrap_or("Untitled")
+Config.get("app.debug", type_=bool).unwrap_or(False)
+```
+
+`get(key, type_=None) -> Result[T, str]`. It never raises and has **no default parameter** — the
+`Result` is the default mechanism.
+
+**`type_` is a cast, not validation.** Nothing is coerced or checked:
+`Config.get("app.debug", type_=bool)` over `debug = 0` returns the integer `0`, merely *typed*
+as `bool`. Parse or validate separately, and wrap consumed config in a typed object.
+
+`has(key) -> bool` is `get(key).is_ok`. `all() -> dict` returns a deep copy; mutating it never
+reaches the repository, frozen or not.
+
+## Writing
+
+Mutable until frozen. This is the extension seam — a package registers defaults, an application
+overrides leaves — and the seam tests use.
+
+`set(key, value)` sets one dot-notation path, creating intermediate dicts, and errors if an
+intermediate segment holds a non-dict.
+
+**`merge(key, items)` is a recursive deep merge.** Nested dictionaries are combined rather than
+replaced, so a leaf can be overridden without restating its siblings; only non-dict values are
+replaced outright. Overriding one nested key needs nothing special:
+
+```python
+Config.merge("hashing", {"argon": {"time_cost": 2, "memory_cost": 1024}})
+Config.merge("hashing", {"argon": {"time_cost": 4}})
+# → argon == {"time_cost": 4, "memory_cost": 1024}
+```
+
+Boot uses exactly this: each loaded `{namespace: dict}` is merged in.
+
+`freeze()` makes every later `set`/`merge` return `Err`. **The framework never calls it.** Config
+stays writable at runtime, which is what keeps the extension seam and test overrides working.
+Call it yourself if you want hard immutability after startup.
+
+## In tests
+
+`TestCase.create_config(tmp_path)` returns the directory the application is built from. Override
+it as a **classmethod** — see the testing fragment. Because the repository is unfrozen you can
+also adjust values mid-test with `Config.set` / `Config.merge`, or fake the facade.

python_neva-5.0.0/neva/guidelines/fragments/database-transactions.md

@@ -0,0 +1,125 @@
+---
+id: database-transactions
+title: Database and transactions
+requires: python-neva>=4.0
+triggers: [database query, opening a transaction, DB.begin, session, savepoint, on_commit, rollback, SQLAlchemy]
+priority: 40
+verified_by: [tests/database/test_transaction.py, tests/database/test_transaction_callbacks.py, tests/database/test_transaction_context.py, tests/database/test_transaction_registry.py, tests/database/test_connection_manager.py, tests/database/test_database_manager.py, tests/database/test_multi_connection.py, tests/database/test_sqlalchemy_integration.py]
+---
+
+# Database and transactions
+
+A transaction-first wrapper over SQLAlchemy async. Never build an engine or session, never call
+`session.commit()`. Open a unit of work, work through `tx.session`, and the block commits on
+clean exit or rolls back on error.
+
+```python
+async with DB.begin() as tx:
+    tx.session.add(actor)
+    await tx.session.flush()
+```
+
+## Configuring
+
+One `database` namespace, mapping connection name to `ConnectionConfig`. `url` is required and
+must use an **async** driver; `pool_size`, `max_overflow`, `pool_recycle`, `pool_pre_ping` and
+`echo` are optional and pass straight to `create_async_engine`.
+
+```python
+config: DatabaseConfig = {
+    "connections": {"default": {"url": "postgresql+asyncpg://…", "echo": True}}
+}
+```
+
+`DatabaseServiceProvider` binds `TransactionContext` and `DatabaseManager`, then registers each
+configured connection during `lifespan()` and disposes the engines on shutdown. Session
+factories use `expire_on_commit=False`, so ORM objects stay readable after commit.
+
+**A missing or malformed `database` namespace does not fail boot.** The provider logs the error
+and continues with zero connections; the failure then surfaces much later as
+`RuntimeError: No connection registered with name default` from the first `DB.begin()`. If you
+see that error, check the config namespace first.
+
+## DatabaseManager
+
+| Call | Returns | Purpose |
+| ---- | ------- | ------- |
+| `begin(name="default")` | ctx mgr of `BoundTransaction` | Open a unit of work. `RuntimeError` if the name is unregistered. |
+| `session(connection=None)` | `Option[AsyncSession]` | Current session, only if this task may use it. |
+| `current(connection=None)` | `Option[BoundTransaction]` | Innermost transaction (top of stack), or the one for a named connection. |
+| `outermost()` | `Option[BoundTransaction]` | The transaction that commits **last**. What deferred events attach to. |
+| `connection(name)` | `Option[ConnectionManager]` | The connection manager. |
+| `register_connection(name, cfg)` | `None` | Build an engine from config. The normal path. |
+| `register_engine(name, engine)` | `None` | Adopt an engine the caller built. For a schema on an in-memory database, where a second engine would be a second, empty database. |
+| `close()` | `None` | Dispose every engine. |
+
+Inject `DatabaseManager` in services you unit-test; use the `DB` facade for ambient access.
+
+## The caller owns the transaction
+
+An inner service reads the current session rather than opening its own:
+
+```python
+class CreateActor:
+    def __init__(self, db: DatabaseManager) -> None:
+        self._db = db
+
+    async def __call__(self, cmd: CreateActorCommand) -> Actor:
+        session = self._db.session().expect("CreateActor must run inside DB.begin()")
+        ...
+```
+
+`session()` returns `Nothing` when no transaction is open **or** when the open one belongs to a
+different asyncio task. Handle the `Option`; it is usually a wiring mistake.
+
+## BoundTransaction
+
+`session` (non-null inside the block), `on_commit(cb)`, `on_rollback(cb)`, `rollback()`,
+`share()`, `is_root`, `is_active`, `parent`.
+
+`await tx.rollback()` **marks** the transaction; the block then exits normally and nothing is
+raised. Only an exception propagating out of the block rolls back *and* re-raises.
+
+## Nesting is a savepoint
+
+A second `begin()` on the same connection, from a task that can reach the parent, reuses the
+parent session and opens a `SAVEPOINT`. An inner rollback undoes only the savepoint; the outer
+transaction continues. Independent code paths can each wrap their work without knowing whether
+they are outermost.
+
+## Commit and rollback callbacks
+
+```python
+tx.on_commit(lambda: send_confirmation_email(order.id))
+tx.on_rollback(release_reserved_stock)
+```
+
+- **Sync or async, and `None` is a valid return.** The contract is
+  `Callable[[], Result[None, str] | None | Awaitable[...]]`. A bare side-effecting lambda is
+  fine; returning `None` is read as `Ok(None)`.
+- **They bubble to the root** and fire only when the root settles — commit callbacks on commit,
+  rollback callbacks on rollback.
+- **A raising callback is captured as `Err` and logged.** It never breaks the settle path or the
+  other callbacks, and it cannot abort a commit that already happened.
+- **They run with no ambient transaction.** By the time one runs, the session is committed and
+  the transaction is off the registry, so `DB.current()` and `DB.session()` return `Nothing`.
+  This is what makes a callback the right place for an SMTP send or an HTTP call — none of it
+  pins the pooled connection or holds a lock. A callback needing the database opens its own
+  `DB.begin()`.
+
+This is the machinery behind `DEFERRED` events.
+
+## Task-bound sessions
+
+A `BoundTransaction` records the asyncio task that opened it, and `AsyncSession` is not
+concurrent-safe, so another task gets `Nothing` from `session()` and opens a fresh transaction
+instead of reusing it. `tx.share()` lifts that for controlled **sequential** access only — its
+canonical use is `RefreshDatabase`.
+
+## Pitfalls
+
+- Never call `session.commit()` / `session.rollback()`. The block owns settling.
+- Never construct `AsyncEngine` / `AsyncSession` by hand.
+- A nested rollback undoes the savepoint, not the transaction.
+- `session()` and `current()` return `Option`. Handle `Nothing`.
+- Use an async driver end to end.

python_neva-5.0.0/neva/guidelines/fragments/events.md

@@ -0,0 +1,150 @@
+---
+id: events
+title: Events and handling policies
+requires: python-neva>=4.0
+triggers: [dispatching an event, writing a listener, DEFERRED vs IMMEDIATE, reacting to something that happened, side effect after commit]
+priority: 30
+verified_by: [tests/events/test_deferred.py, tests/events/test_immediate.py, tests/events/test_dispatch.py, tests/events/test_listen_on_parent_class.py, tests/events/test_function_listener.py, tests/events/test_before_dispatch.py, tests/events/test_listener_wiring.py]
+---
+
+# Events and handling policies
+
+A producer announces what happened; unrelated listeners react. The defining feature is
+transaction awareness: a `DEFERRED` listener runs only after the surrounding database
+transaction commits.
+
+```python
+from neva.support.facade import Event
+_ = await Event.dispatch(ActorCreated(actor_id=actor.id))
+```
+
+## Defining an event
+
+Subclass `Event[T]`, where `T` types the `event_id`. The base supplies `event_id: T` and
+`timestamp: datetime` (defaulted to `neva.support.time.utcnow`). Events are Pydantic models, so
+they validate on construction and serialise.
+
+```python
+class ActorCreated(Event[uuid.UUID]):
+    actor_id: uuid.UUID
+```
+
+Most applications define one project base event that fixes the id strategy
+(`event_id: uuid.UUID = pydantic.Field(default_factory=uuid.uuid4)`) and let component events
+declare payload only.
+
+Naming: events are **past tense**.
+
+## Writing a listener
+
+```python
+class SendWelcomeEmail(EventListener[ActorCreated]):
+    policy = HandlingPolicy.DEFERRED          # default is IMMEDIATE
+
+    def __init__(self, mailer: Mailer) -> None:
+        self._mailer = mailer
+
+    async def handle(self, event: ActorCreated) -> Result[None, str]:
+        await self._mailer.send_welcome(event.actor_id)
+        return Ok(None)
+```
+
+Or, with no dependencies, decorate a handler — `@listener` synthesises a class named
+`<Pascal>Listener` (`log_actor_created` → `LogActorCreatedListener`):
+
+```python
+@listener(policy=HandlingPolicy.DEFERRED)     # bare @listener() is IMMEDIATE
+async def log_actor_created(event: ActorCreated) -> Result[None, str]:
+    Log.info("actor created", actor_id=str(event.actor_id))
+    return Ok(None)
+```
+
+Naming: class listeners are imperative (`SendWelcomeEmail`), function handlers snake_case.
+
+**Always define `handle`.** The base class body is `...` and is not abstract, so an omitted
+`handle` silently returns `None` where the contract promises `Result[None, str]`.
+
+**Return `Err`, never raise.** A raised exception is captured as `Err(f"Listener raised: {e}")`
+and never reaches the producer or the other listeners.
+
+## Policy × transaction
+
+| Policy | Inside an open transaction | Outside any transaction |
+| ------ | -------------------------- | ----------------------- |
+| `IMMEDIATE` | runs during `dispatch()` | runs during `dispatch()` |
+| `DEFERRED` | runs after the transaction commits | runs during `dispatch()` |
+
+`DEFERRED` is for effects that must not happen unless the data persisted — mail, indexing,
+webhooks, outbound calls. On rollback they never fire. With no transaction open, `DEFERRED`
+degrades to immediate: same call site, different timing by context.
+
+## What dispatch does
+
+1. Runs `before_dispatch` hooks.
+2. Resolves listeners, walking the event's **MRO** — a listener registered against a base event
+   also fires for subclasses. A listener reached through several registries fires **once**;
+   repeated registrations against the *same* event are honoured and fire repeatedly.
+3. Splits by policy.
+4. Branches on `DatabaseManager.outermost()` — the transaction that commits **last**, not
+   `current()`. Deferred listeners attach to it via `on_commit`, so they never run for work an
+   enclosing transaction may still roll back. With no transaction, deferred listeners join the
+   immediate list.
+5. Runs immediate listeners, resolving each from the container and awaiting `handle`.
+6. Returns one `Result` per **immediate** listener.
+
+The returned list therefore says nothing about deferred work. Never use it to confirm a
+deferred listener ran.
+
+## Resolution
+
+`_resolve_listener` asks the container, then falls back to no-argument instantiation. A listener
+with constructor dependencies **must** be bound — the `listen` ClassVar does that for you.
+
+## Registering
+
+Declarative, and preferred:
+
+```python
+class ActorServiceProvider(ServiceProvider):
+    listen = {ActorCreated: [SendWelcomeEmail, IndexActorForSearch]}
+```
+
+Listener classes are bound at `Scope.APP` onto the application's root provider during
+registration, then wired onto the dispatcher during `lifespan()`. If `listen` mappings exist and
+the dispatcher cannot be resolved, boot **raises `RuntimeError`** naming the count and the fix
+rather than leaving every listener silently unwired.
+
+Imperative registration also works. Note the type stubs currently declare only the single-class
+form, so a list argument type-checks as an error even though the dispatcher accepts it:
+
+```python
+Event.listen(ActorCreated, SendWelcomeEmail)
+```
+
+`EventServiceProvider` is a base provider — always registered, never added by hand.
+
+## before_dispatch hooks
+
+Run once per dispatch, before any listener. The **hook** may be sync or async; the
+**registration call is always awaited**, because `before_dispatch` is itself a coroutine
+function. Forgetting the `await` registers nothing.
+
+```python
+await Event.before_dispatch(persist_to_event_store)
+await Event.before_dispatch(lambda e: metrics.incr(type(e).__name__))
+```
+
+## Testing
+
+`Event.fake()` installs an `EventFake` that records events and fires **no** listeners — neither
+immediate nor deferred — and whose `dispatch` always returns `[]`.
+
+```python
+fake = Event.fake()
+fake.assert_dispatched(ActorCreated, times=1, match=lambda e: e.actor_id == expected)
+fake.assert_not_dispatched(ActorDeleted)
+events = fake.dispatched(ActorCreated)
+```
+
+`with Event.faking() as fake:` scopes it. `TestCase` restores facades after every test. To test
+what a listener *does*, exercise the listener directly — the fake suppresses it.