python-neva 4.1.0__tar.gz → 5.1.0__tar.gz

{python_neva-4.1.0 → python_neva-5.1.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.1.0 → python_neva-5.1.0}/CHANGELOG.md

@@ -1,3 +1,33 @@
+## 5.1.0 (2026-09-02)
+
+### ✨ Features
+
+- **deps**: offer neva-otel through the otel extra
+
+### 📝💡 Documentation
+
+- **guidelines**: add security, facades and factories fragments
+
+## 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

{python_neva-4.1.0 → python_neva-5.1.0}/PKG-INFO

@@ -1,25 +1,27 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 4.1.0
+Version: 5.1.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
 Requires-Dist: faststream>=0.6.6; extra == 'faststream'
+Provides-Extra: otel
+Requires-Dist: neva-otel>=0.2.0; extra == 'otel'
 Provides-Extra: polyfactory
 Requires-Dist: polyfactory>=3.1.0; extra == 'polyfactory'
 Provides-Extra: testing
@@ -47,17 +49,48 @@ 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. Pulled in via the `python-neva[otel]` extra. | published ([PyPI](https://pypi.org/project/neva-otel/)) |
+| `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
+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.
+
+Channel configuration, the driver keys and the failure modes are documented in
+`neva/guidelines/fragments/observability.md`, which CI checks against the tests.
+
 ## Develop
 
 ```bash
@@ -103,10 +136,8 @@ 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
 - Improved factory module (based on Polyfactory)
 - Queue/Jobs system
 - CLI integration

{python_neva-4.1.0 → python_neva-5.1.0}/README.md

@@ -18,17 +18,48 @@ 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. Pulled in via the `python-neva[otel]` extra. | published ([PyPI](https://pypi.org/project/neva-otel/)) |
+| `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
+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.
+
+Channel configuration, the driver keys and the failure modes are documented in
+`neva/guidelines/fragments/observability.md`, which CI checks against the tests.
+
 ## Develop
 
 ```bash
@@ -74,10 +105,8 @@ 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
 - Improved factory module (based on Polyfactory)
 - Queue/Jobs system
 - CLI integration

{python_neva-4.1.0 → python_neva-5.1.0}/neva/database/connection.py

@@ -7,7 +7,6 @@ from dataclasses import dataclass, field
 from typing import final
 
 from sqlalchemy.ext import asyncio
-from structlog.stdlib import get_logger
 
 from neva.database.transaction import BoundTransaction, TransactionState
 from neva.obs import LogManager
@@ -87,7 +86,7 @@ class ConnectionManager:
         self,
         name: str,
         tx_context: TransactionContext,
-        logger: LogManager | None,
+        logger: LogManager,
         engine: asyncio.AsyncEngine,
     ) -> None:
         self.name = name
@@ -149,12 +148,10 @@ class ConnectionManager:
         )
         label = "commit" if committed else "rollback"
         # A post-commit callback cannot un-commit the transaction, so its
-        # failure is reported rather than raised. It must never be lost: fall
-        # back to a module logger when the manager has none.
-        logger = self.logger if self.logger is not None else get_logger(__name__)
+        # failure is reported rather than raised.
         for result in results:
             if result.is_err:
-                logger.error(
+                self.logger.error(
                     f"{label} callback failed",
                     error=result.err().unwrap(),
                     connection=self.name,

{python_neva-4.1.0 → python_neva-5.1.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.1.0/neva/guidelines/fragments/facades.md

@@ -0,0 +1,95 @@
+---
+id: facades
+title: Facades
+requires: python-neva>=5.0
+triggers: [Log facade, DB facade, static access to a service, adding a facade, facade root, why does my facade raise AttributeError, pyi stub]
+priority: 25
+verified_by: [tests/arch/test_facade_resolution.py, tests/arch/test_facade_root_nesting.py, tests/testing/test_facade_restore.py]
+---
+
+# Facades
+
+A static front for a container-bound service. `Log.info(...)` resolves `LogManager` from the
+application and calls `info` on it.
+
+```python
+from neva.support.facade import App, Config, Crypt, DB, Event, Hash, Log
+```
+
+Each names one service through `get_facade_accessor()`. Nothing else is special: a facade holds
+no state and caches no instance.
+
+## When to use one
+
+Use a facade for genuinely cross-cutting access — logging, config, the ambient transaction.
+**Inject the service anywhere it is part of a unit's contract.** A class taking
+`DatabaseManager` in its constructor says what it needs and can be unit-tested by passing a
+double; the same class reaching for `DB` hides the dependency and can only be tested by
+installing a global. Actions, repositories and services take constructor parameters.
+
+## Resolution is per access
+
+`FacadeMeta.__getattr__` resolves the root on **every** attribute access. A swap installed
+mid-test therefore takes effect immediately, and a facade never pins a stale instance across a
+rebuild.
+
+The cost is that failures arrive as `AttributeError`, not as a `Result`:
+
+| Situation | What you get |
+| --- | --- |
+| No application set | `AttributeError: A facade root (App instance) has not been set for <Facade>. Call Facade.set_facade_application(app) first.` |
+| Service not bound | `AttributeError` carrying the container's resolution error. |
+| Attribute the service lacks | `AttributeError: 'LogManager' object has no attribute '...'` |
+
+An `AttributeError` from a facade almost always means a missing provider, not a typo. Check the
+`providers` config namespace first.
+
+**A swap bypasses the container but not the root check.** `DB.swap(manager)` outside a booted
+application still raises "a facade root has not been set" — the double is only consulted once
+an application is present. A test installing a double therefore needs an application anyway,
+which is what `TestCase` and the `application` fixture provide.
+
+## The facade root
+
+`Application.lifespan()` sets the root on entry and restores it on exit — you never call
+`set_facade_application` yourself outside a bespoke harness.
+
+The root is a single process-global slot, and teardown **hands it back rather than clearing
+it**: an application booted inside a longer-lived one restores the outer application on exit,
+and only the outermost teardown leaves it unset. Without that, a short-lived inner application
+would disarm every facade for whatever the outer one still had to do — exactly what a test
+harness does when its application outlives a single test.
+
+## Type checking needs a stub
+
+Forwarding through `__getattr__` is invisible to a type checker, so every facade ships a
+sibling `.pyi` declaring its methods as classmethods (`neva/support/facade/log.pyi`). Two
+consequences:
+
+- **Adding a method to a service does not add it to the facade's public API.** Update the stub
+  in the same change, or callers get an error on a call that works at runtime.
+- A stub can drift the other way too — the events fragment documents one such gap, where the
+  dispatcher accepts a list its contract does not declare.
+
+## Adding a facade
+
+```python
+class Cache(Facade):
+    @classmethod
+    @override
+    def get_facade_accessor(cls) -> type:
+        return CacheManager
+```
+
+Import the service inside the method when the module would otherwise import at package-import
+time — the shipped facades do this to keep `neva.support.facade` cheap. Bind the service in a
+provider, write the `.pyi`, and export it from your facade package.
+
+## Testing
+
+Doubles are installed on the concrete facade, never on `Facade` itself, and live in one global
+registry keyed by facade class. See the testing fragment for the full table — `fake()`,
+`swap()`, `spy()`, `faking()`, `restore()`, `restore_all()`.
+
+`TestCase` calls `Facade.restore_all()` after every test. Outside it, prefer `faking()` so a
+failing assertion cannot leak a double into the next test.

python_neva-5.1.0/neva/guidelines/fragments/factories.md

@@ -0,0 +1,79 @@
+---
+id: factories
+title: Model factories
+requires: python-neva>=5.0
+triggers: [building test data, ModelFactory, polyfactory, seeding a model, create_async, factory for a SQLAlchemy model]
+priority: 65
+verified_by: [tests/polyfactory/test_model_factory.py]
+---
+
+# Model factories
+
+`ModelFactory` builds SQLAlchemy models for tests and seeds, persisting them through the
+**caller's** transaction. It is a thin base over Polyfactory's `SQLAlchemyFactory`.
+
+Ships behind an extra — `python-neva[polyfactory]`. Importing `neva.polyfactory` without it
+fails, so it belongs in a dev dependency group, not in application code paths.
+
+```python
+from neva.polyfactory import ModelFactory
+
+class ActorFactory(ModelFactory[Actor]):
+    __model__ = Actor
+```
+
+## Persisting
+
+`create_async()` and `create_batch_async(n)` write through the ambient session — they read it
+from the `DB` facade rather than opening a transaction of their own, and they **flush without
+committing**. The enclosing block still owns settling, so a factory call inside a rolled-back
+test leaves nothing behind.
+
+```python
+async with DB.begin() as tx:
+    actor = await ActorFactory.create_async()
+    actors = await ActorFactory.create_batch_async(3)
+```
+
+**There must be an open transaction.** Outside one, `create_async` raises `UnwrapError` from
+the unwrapped `DB.session()` rather than quietly opening its own — the same rule the database
+fragment states for actions. Under `RefreshDatabase` the wrapper transaction already satisfies
+this.
+
+`build()` and `batch()` are inherited unchanged and touch no database. Use them when the model
+never needs to be persisted.
+
+## Relationships are not populated — but foreign keys still are
+
+`__set_relationships__` is `False` on the base, so a factory never sets a relationship
+attribute and never invents the related row.
+
+**It does still fill the foreign-key column**, because that is an ordinary column: a required
+`author_id` comes back a random integer pointing at no row. SQLite does not check the
+constraint by default and lets it through; Postgres rejects it. This is the failure to expect
+when a factory that passed locally breaks against a real database.
+
+Always supply the parent — the relationship or the id — rather than letting the factory invent
+one:
+
+```python
+author = await AuthorFactory.create_async()
+book = await BookFactory.create_async(author=author)          # or author_id=author.id
+```
+
+For a nullable key with no parent in the scenario, say so explicitly:
+
+```python
+book = await BookFactory.create_async(author_id=None)
+```
+
+Set `__set_relationships__ = True` on one factory where a fixture genuinely wants the whole
+graph built for it.
+
+## Rules
+
+- One factory per model, named `<Model>Factory`, beside the component's other test support.
+- Never call `session.commit()` from a factory or a seeder — the caller's block settles.
+- Do not give a factory its own `DB.begin()`; it inherits the caller's unit of work.
+- Override a field with a keyword argument rather than editing the instance afterwards, so the
+  value is present when the row is flushed.

python_neva-5.1.0/neva/guidelines/fragments/observability.md

@@ -0,0 +1,130 @@
+---
+id: observability
+title: Observability
+requires: python-neva>=5.0
+triggers: [logging, Log facade, log channel, structured logging, log level, JSON logs, audit log, obs config, tracing, OpenTelemetry, metrics, correlation id]
+priority: 55
+verified_by: [tests/obs/test_channels.py, tests/obs/test_resolver.py, tests/obs/test_manager.py, tests/obs/test_facade.py, tests/obs/test_provider_hook.py, tests/support/test_strategy.py]
+---
+
+# Observability
+
+The core ships **logging only**. Tracing, metrics, exporters and instrumentors live in the
+`neva-otel` plugin (`python-neva[otel]`), so installing the core commits an application to no
+observability backend. There is no `Trace` facade, no tracer, and no OpenTelemetry dependency
+here — do not add one. Asked for tracing, install the plugin; never reach for
+`opentelemetry-*` inside this package.
+
+## Channels
+
+Logging is a set of named channels, each with its own driver, level and output. One
+`config/obs.py` namespace configures them.
+
+```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"]},
+            "quiet":  {"driver": "null"},
+        },
+    },
+}
+```
+
+| Driver | Writes | Driver-specific keys |
+| --- | --- | --- |
+| `console` | human-readable, to a stream | `stream` |
+| `json` | one JSON object per line, to a stream | `stream` |
+| `file` | JSON lines appended to a path | `path` (required) |
+| `stack` | fans one record out to other channels | `channels` (required) |
+| `null` | nothing | — |
+
+`level` is one of `DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL`, default `DEBUG`. `stream` is
+`stdout` (default) or `stderr`. A `file` channel creates parent directories and holds its
+handle open for the process's life.
+
+**With no `config/obs.py` at all**, logging still works: a `console` channel named `stdout` on
+stdout at `DEBUG`.
+
+## Writing
+
+```python
+from neva.support.facade import Log
+
+Log.info("order placed", order_id=42)      # default channel
+Log.channel("audit").warning("role granted", actor="root")
+```
+
+Level methods are `debug`, `info`, `warning`, `error`, `critical` and `exception`, and go to the
+default channel. **Use `Log.exception(...)` inside an `except` block** — it attaches the
+traceback, which `Log.error(str(e))` throws away. Everything after the message is structured
+context, not format arguments — never build the message with an f-string when the value belongs
+in a field.
+
+`Log.channel(name)` **raises `UnwrapError`** on a name no channel is configured for, carrying
+the reason. A typo is a configuration mistake, and serving the default instead would hide it
+behind working output. Where the failure has to be a value, go through the resolver:
+`Log.channels` returns `Option[ChannelResolver]` — `Nothing` for a manager built with no
+application — and the resolver's `use(name)` returns `Result[Channel, str]`.
+
+```python
+channel = Log.channels.and_then(lambda r: r.use("audit").ok())
+```
+
+Three failures are told apart by their message: no channel of that name, an unknown `driver`
+(the error lists the drivers that are registered), and a `stack` channel that reaches itself,
+which reports being "defined in terms of itself" rather than recursing.
+
+## Ambient context
+
+```python
+Log.bind(tenant="acme")     # every subsequent record in this context, every channel
+Log.unbind("tenant")
+```
+
+Backed by structlog's contextvars, so a binding follows the async task rather than the
+channel. This is how a request's correlation ID reaches log lines without being passed
+around — `neva-asgi`'s middleware binds it the same way.
+
+## Enriching records from a plugin
+
+`LogManager.processor(fn)` appends a structlog processor to **every** channel's chain. This is
+the seam a plugin adds derived fields through — `neva-otel` injects the current span's ids
+this way.
+
+```python
+class MyProvider(ServiceProvider):
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        manager = (await self.app.make_async(LogManager)).unwrap()
+        _ = manager.processor(add_my_field)
+        yield
+```
+
+**Call it from `lifespan()`, never from `register()`.** Resolving anything during
+registration hands back an instance the booted application does not use, so a processor
+registered there silently never runs. See the service-providers fragment.
+
+Records emitted by base providers' own startup are not enriched — their lifespans run before
+a plugin's. Everything after is. Already-built channels are discarded on registration, so the
+next resolution picks the processor up.
+
+Custom drivers register the same way, through `resolver.driver(name, builder)` — the
+resolver is a `StrategyResolver`, described in the service-providers fragment.
+
+## Rules
+
+- **Never call `structlog.configure()`.** It is process-global; channels carry their own
+  chains precisely so one application's renderer cannot leak into another in the same
+  interpreter. Configuring it globally breaks that isolation and every channel's level.
+- **`merge_contextvars` must lead every chain.** A custom driver that omits it silently drops
+  the correlation ID from every line it renders.
+- **A broken default channel fails at boot**, not at the first log call — the framework logs
+  during provider startup, so a `file` channel with no `path` surfaces there. The error names
+  the channel and the reason.
+- `LogManager()` with no application is legitimate and serves one console channel; it is what
+  a test needing somewhere for records to go should use.