python-neva 4.1.0__py3-none-any.whl → 5.1.0__py3-none-any.whl

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,

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,

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.

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.

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.

neva/guidelines/fragments/security.md

@@ -0,0 +1,142 @@
+---
+id: security
+title: Hashing, tokens and encryption
+requires: python-neva>=5.0
+triggers: [hashing a password, checking a password, generating an API key, storing a token, encrypting a value, key rotation, app.key, Hash facade, Crypt facade]
+priority: 45
+verified_by: [tests/security/test_hash_manager.py, tests/security/test_encrypter.py, tests/security/test_tokens.py, tests/security/test_config_shapes.py, tests/support/test_strategy.py]
+---
+
+# Hashing, tokens and encryption
+
+Three separate concerns with three separate tools. Reaching for the wrong one is the mistake
+this fragment exists to prevent — they are not interchangeable, and two of the three pairings
+are outright vulnerabilities.
+
+| Secret | Tool | Why |
+| ------ | ---- | --- |
+| A user's password | `Hash` (argon2/bcrypt) | Human-chosen, low entropy. Needs a deliberately slow, salted KDF. |
+| A token you generated | `generate_token` + `hash_token` | Already high-entropy. A fast digest is correct and a KDF is pure cost. |
+| Data you must read back | `Crypt` (AES-256-GCM) | Reversible. Never a hash. |
+
+Never hash a password with `hash_token` — SHA-256 is unsalted and fast, so a stolen table is
+brute-forceable. Never encrypt a password with `Crypt` — a password must not be recoverable.
+
+Everything here comes from `SecurityProvider`, which binds `HashManager` and `Encrypter`. It is
+**not** a base provider: list it in the `providers` config namespace or `Hash` and `Crypt`
+resolve to nothing.
+
+## Hashing passwords
+
+```python
+from neva.support.facade import Hash
+
+hashed = await Hash.make_async(password)
+if await Hash.check_async(password, user.password):
+    ...
+```
+
+**In async code use `make_async` / `check_async`.** Hashing is deliberately CPU- and
+memory-expensive — argon2 defaults to 100 MiB and tens of milliseconds — so the sync `make` and
+`check` stall the whole event loop, blocking every other request for the duration. The async
+pair hands the work to a thread (`asyncio.to_thread`); they are otherwise identical.
+
+One `hashing` namespace, drivers `argon2` and `bcrypt`. `driver` is the only required key; both
+tuning namespaces are optional and every field has a default.
+
+```python
+from neva.security import HashingConfig
+
+config: HashingConfig = {"driver": "argon2", "argon": {"time_cost": 4}}
+```
+
+| Key | Default |
+| --- | ------- |
+| `argon.time_cost` | 2 |
+| `argon.memory_cost` | 102400 (KiB) |
+| `argon.parallelism` | 8 |
+| `argon.hash_len` | 16 |
+| `argon.salt_len` | 16 |
+| `bcrypt.rounds` | 12 |
+| `bcrypt.prefix` | `"2b"` |
+
+**A missing `hashing` namespace does not fail boot.** `HashManager` resolves fine and the
+failure surfaces at the first call, as `UnwrapError: Failed to resolve hasher 'default'` — the
+same shape as an unknown driver name. If you see it, check the namespace before anything else.
+Passing `hasher="bcrypt"` explicitly bypasses the default and works regardless.
+
+`Hash.needs_rehash(hashed)` reports whether a stored hash predates the current tuning. Check it
+on successful login and re-hash there — it is the only moment the plaintext is available.
+
+## Tokens
+
+```python
+from neva.security import generate_token, hash_token, verify_token
+
+token = generate_token()                 # give this to the caller, once
+user.api_key = hash_token(token)         # store only this
+```
+
+`generate_token(nbytes=32)` draws from `secrets.token_urlsafe`. **`nbytes` is entropy, not
+output length** — base64url makes the string roughly `4 * nbytes / 3` characters, so the default
+yields 43. Do not shrink it to control the column width.
+
+`hash_token` is a bare hex SHA-256, and `verify_token` compares with `hmac.compare_digest` so
+the check is constant-time. Both accept `str` or `bytes` and agree on either. Store the hash,
+never the token; a stolen database then yields nothing usable.
+
+## Encryption
+
+```python
+from neva.support.facade import Crypt
+
+match Crypt.encrypt({"iban": iban}):
+    case Ok(payload): ...
+    case Err(reason): ...
+```
+
+AES-256-GCM. `encrypt(value) -> Result[str, str]` takes any JSON-serialisable value — strings
+round-trip as strings, everything else through JSON — and returns a base64 payload carrying its
+own random IV, so the same input never produces the same ciphertext. `decrypt(payload) ->
+Result[JsonValue, str]`.
+
+**Both return `Result`; neither raises.** `DecryptionError` is exported but never raised
+anywhere in the core — an `except DecryptionError` block is dead code. Handle the `Err`.
+
+### Keys and rotation
+
+`app.key` is a base64-encoded 32 bytes; `AesEncrypter.generate_key()` mints one. `app.previous_keys`
+is a list of superseded keys.
+
+```python
+config: AppConfig = {"key": CURRENT, "previous_keys": [SUPERSEDED]}
+```
+
+Encryption always uses `app.key`. Decryption tries `app.key` first, then each previous key in
+order, so rotating a key leaves existing ciphertext readable without a migration. Re-encrypt at
+your own pace, then drop the old key from the list.
+
+**Keys load lazily, on the first encrypt or decrypt.** A missing or malformed `app.key` raises
+`ValueError` there, not at boot — an application with no key configured starts perfectly and
+fails at the first secret it touches.
+
+## Registering another hasher
+
+`HashManager` is a `StrategyResolver` — see the service-providers fragment for the pattern and
+its `use()` contract. Register a factory from a provider's `lifespan()`, never `register()`.
+
+```python
+manager = (await self.app.make_async(HashManager)).unwrap()
+_ = manager.register("scrypt", lambda resolver: ScryptHasher())
+```
+
+A hasher satisfies the `Hasher` protocol: `make`, `check`, `needs_rehash`.
+
+## Pitfalls
+
+- Sync `Hash.make` / `Hash.check` in async code. Use the `_async` pair.
+- `SecurityProvider` left out of the `providers` namespace.
+- Storing a token instead of `hash_token(token)`.
+- Treating `nbytes` as the token's length.
+- Expecting `Crypt` to raise. It returns `Err`.
+- Assuming a missing `hashing` namespace or `app.key` fails at boot. Both fail at first use.

neva/guidelines/fragments/service-providers.md

@@ -4,7 +4,7 @@ title: Service providers and bindings
 requires: python-neva>=4.0
 triggers: [registering a service, binding a dependency, provider.py, wiring a component, DI container, resolving a type]
 priority: 20
-verified_by: [tests/arch/test_lifetimes.py, tests/arch/test_registration.py, tests/arch/test_cache.py, tests/arch/test_scope.py, tests/arch/test_extends.py]
+verified_by: [tests/arch/test_lifetimes.py, tests/arch/test_registration.py, tests/arch/test_cache.py, tests/arch/test_scope.py, tests/arch/test_extends.py, tests/arch/test_register_resolution.py, tests/support/test_strategy.py]
 ---
 
 # Service providers and bindings
@@ -28,6 +28,36 @@ class ActorServiceProvider(ServiceProvider):
 `register()` returns `Ok(self)`, or `Err("...")` to abort boot with a message. Bind only — no
 I/O, no connections. Startup work goes in `lifespan()`.
 
+## Never resolve in register()
+
+`register()` **declares**; `lifespan()` **uses**. Calling `make()` or `make_async()` during
+registration cannot work, and fails in one of two ways depending on who bound the type:
+
+| Resolving | Outcome |
+| --- | --- |
+| A type **this provider** binds | `Err` — a provider joins the graph only once `register()` has returned, so its own bindings are not there yet. |
+| A type **another provider** bound | Succeeds, then is **orphaned**. Resolving builds the container early; a successful registration discards it, so the booted application serves a *different* instance. |
+
+The second is the dangerous one: nothing raises, nothing logs, and the object looks right. A
+provider that configures a manager this way — adding a log processor, registering a driver —
+silently configures a throwaway.
+
+```python
+def register(self) -> Result[Self, str]:
+    manager = self.app.make(SomeManager).unwrap()   # WRONG: discarded instance
+    manager.configure(...)                          # silently affects nothing
+    return Ok(self)
+
+@asynccontextmanager
+async def lifespan(self) -> AsyncIterator[None]:
+    manager = (await self.app.make_async(SomeManager)).unwrap()   # the real one
+    manager.configure(...)
+    yield
+```
+
+Needing another service in order to *bind* is a sign the binding wants a factory function
+taking it as a parameter — let the container inject it, rather than reaching for it.
+
 ## A lifetime is mandatory
 
 Bare `bind()` with neither `scope` nor `cache` **raises `TypeError`** since 4.0. Use the named
@@ -65,6 +95,33 @@ the binding behind a marker.
 - `when: ClassVar[Marker | None]` on the provider gates all of its bindings at once.
 - `listen: ClassVar[dict[type[Event], list[type[EventListener]]]]` — see the events fragment.
 
+## Strategy resolvers
+
+Where a service picks one of several interchangeable implementations by **name** from config,
+the core uses `StrategyResolver` (`neva.support.strategy`) rather than a second container.
+`HashManager` and the logging `ChannelResolver` are both instances of it, so the contract is
+worth knowing once:
+
+| Call | Meaning |
+| ---- | ------- |
+| `use(name=None)` | `Result[T, str]`. Resolves, **caches**, and returns. `None` means the configured default. |
+| `default()` | Abstract — each resolver reads its own config key (`hashing.driver`, `obs.logging.default`). |
+| `register(name, factory)` | Add an implementation. The factory takes the resolver, so it can read config. |
+| `resolve(name)` | Build without caching. Override to change what a name means. |
+| `clear()` | Drop cached instances, so the next `use` rebuilds. |
+
+Two failures come back as `Err`, never as an exception: `"No default strategy configured."`
+when `default()` is `Nothing`, and `"No strategy registered with name '<name>'"`. A factory that
+raises is caught and returned as `Err` naming the strategy.
+
+**Register from `lifespan()`, not `register()`** — the resolver is a container-bound service,
+so the rule above applies: one resolved during registration is discarded, and the
+implementation registered on it silently never serves. `clear()` matters when adding a
+processor or driver after something has already been resolved.
+
+Use it for named, config-selected implementations. Use the container for everything else —
+resolution there is by type, and a strategy resolver is not a general service locator.
+
 ## Startup and shutdown
 
 Implement `lifespan()` and the provider is `Bootable` — a runtime-checkable Protocol, so no
@@ -111,4 +168,6 @@ catches typos before boot. Each package declares the shape for the keys it reads
 - A provider absent from the `providers` config never boots, and nothing says so.
 - Resolution is by **type**. There are no string keys; for two implementations of one interface
   use distinct types or markers.
-- `register()` must be pure binding. Connections belong in `lifespan()`.
+- `register()` must be pure binding. Connections **and any `make()` call** belong in
+  `lifespan()` — see above; resolving during registration silently yields a discarded
+  instance.

neva/obs/__init__.py

@@ -1,9 +1,19 @@
-"""Observability tooling."""
+"""Observability tooling.
 
-from neva.obs.logging import LogManager, LogServiceProvider
+Logging only: tracing, metrics and their exporters live in the `neva-otel`
+plugin, so the core commits no application to an observability backend.
+"""
+
+from neva.obs.config import ChannelConfig, LoggingConfig, ObsConfig
+from neva.obs.logging import Channel, ChannelResolver, LogManager, LogServiceProvider
 
 
 __all__ = [
+    "Channel",
+    "ChannelConfig",
+    "ChannelResolver",
     "LogManager",
     "LogServiceProvider",
+    "LoggingConfig",
+    "ObsConfig",
 ]

neva/obs/config.py

@@ -0,0 +1,37 @@
+"""Observability configs."""
+
+from typing import Literal, NotRequired, TypedDict
+
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+ChannelDriver = Literal["console", "json", "file", "stack", "null"]
+Stream = Literal["stdout", "stderr"]
+
+
+class ChannelConfig(TypedDict):
+    """Configuration for a single log channel.
+
+    Three keys are driver-specific and carry no meaning elsewhere: `stream`
+    belongs to `console` and `json`, `path` to `file`, and `channels` to
+    `stack`. A `file` channel without `path`, or a `stack` without `channels`,
+    fails to resolve rather than logging nowhere.
+    """
+
+    driver: ChannelDriver
+    level: NotRequired[LogLevel]
+    stream: NotRequired[Stream]
+    path: NotRequired[str]
+    channels: NotRequired[list[str]]
+
+
+class LoggingConfig(TypedDict):
+    """Logging config."""
+
+    default: NotRequired[str]
+    channels: NotRequired[dict[str, ChannelConfig]]
+
+
+class ObsConfig(TypedDict):
+    """Observability config."""
+
+    logging: NotRequired[LoggingConfig]

neva/obs/logging/__init__.py

@@ -1,10 +1,22 @@
 """Logging module.
 
-Provides structured logging using structlog with Laravel-style facades.
+Structured logging over structlog, shaped as named channels resolved from
+configuration, reached through the `Log` facade.
 """
 
+from neva.obs.logging.channels import NullChannel, StackChannel
+from neva.obs.logging.contracts import Channel, Processor
 from neva.obs.logging.manager import LogManager
 from neva.obs.logging.provider import LogServiceProvider
+from neva.obs.logging.resolver import ChannelResolver
 
 
-__all__ = ["LogManager", "LogServiceProvider"]
+__all__ = [
+    "Channel",
+    "ChannelResolver",
+    "LogManager",
+    "LogServiceProvider",
+    "NullChannel",
+    "Processor",
+    "StackChannel",
+]