python-neva 5.0.0__py3-none-any.whl → 5.3.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/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

@@ -4,14 +4,16 @@ 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]
+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 a
-separate plugin, 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.
+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
 
@@ -57,14 +59,25 @@ Log.info("order placed", order_id=42)      # default channel
 Log.channel("audit").warning("role granted", actor="root")
 ```
 
-Level methods go to the default channel. 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.
+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** 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, `Log.channels` gives the resolver and
-`use(name)` returns `Result`.
+`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
 
@@ -80,8 +93,8 @@ 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 — the OpenTelemetry plugin injects the current
-span's ids this way.
+the seam a plugin adds derived fields through — `neva-otel` injects the current span's ids
+this way.
 
 ```python
 class MyProvider(ServiceProvider):
@@ -100,7 +113,8 @@ Records emitted by base providers' own startup are not enriched — their lifesp
 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)`.
+Custom drivers register the same way, through `resolver.driver(name, builder)` — the
+resolver is a `StrategyResolver`, described in the service-providers fragment.
 
 ## Rules
 

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, tests/arch/test_register_resolution.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
@@ -95,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
@@ -125,10 +152,15 @@ request-scoped container to another framework wants that, not `container`.
 
 ## Registration is closed after boot
 
-`register()` is idempotent for an already-registered class, but **returns `Err` once the
-application has booted**: dishka validates the graph at build time, and the booted container
-holds APP-scoped instances a rebuild would orphan. Declare providers in config, or register
-before entering `lifespan()`.
+`register()` **returns `Err` once the application has booted**: dishka validates the graph at
+build time, and the booted container holds APP-scoped instances a rebuild would orphan. Declare
+providers in config, or register before entering `lifespan()`.
+
+One case slips past that, and the order is what makes it: the already-registered check is read
+**first**, so re-registering a class the application already holds returns `Ok(existing)` even
+booted. Nothing is rebuilt, so nothing is at risk. It does mean a test asserting the refusal
+must pass a provider the application never registered: hand it one the config or the setup
+already installed and the assertion comes back `Ok`, proving nothing.
 
 ## Typed config shapes
 

neva/guidelines/fragments/testing.md

@@ -1,10 +1,10 @@
 ---
 id: testing
 title: Testing
-requires: python-neva>=4.0
-triggers: [writing a test, TestCase, RefreshDatabase, faking a facade, database isolation in tests, create_config]
+requires: python-neva>=5.2
+triggers: [writing a test, TestCase, RefreshDatabase, faking a facade, database isolation in tests, create_config, boot_application]
 priority: 60
-verified_by: [tests/testing/test_test_case.py, tests/testing/test_application_reuse.py, tests/testing/test_create_config_migration.py, tests/testing/test_refresh_database.py, tests/testing/test_facade_restore.py, tests/testing/test_event_fake.py, tests/testing/test_fixtures.py]
+verified_by: [tests/testing/test_test_case.py, tests/testing/test_boot_application.py, tests/testing/test_application_reuse.py, tests/testing/test_create_config_migration.py, tests/testing/test_refresh_database.py, tests/testing/test_facade_restore.py, tests/testing/test_event_fake.py, tests/testing/test_fixtures.py]
 ---
 
 # Testing
@@ -66,6 +66,33 @@ naming the fix. There is no instance-method fallback and no deprecation path —
 Omit the override entirely and the default writes a minimal `app.py` / `providers.py` into
 `tmp_path`.
 
+## boot_application picks the application, not just its config
+
+`create_config` says what configuration the class runs on; `boot_application` says what
+application runs over it, and which lifespan holds it open. Override it when the thing under
+test **owns** an `Application` instead of being one — an HTTP app, whose own lifespan is what
+seeds its per-request state — so entering `Application.lifespan()` would boot the container and
+skip everything wrapped around it.
+
+```python
+class HttpTestCase(TestCase):
+    @override
+    @classmethod
+    @asynccontextmanager
+    async def boot_application(cls, config_path: Path) -> AsyncIterator[Application]:
+        webapp = App(config_path=config_path)
+        async with webapp.router.lifespan_context(webapp):
+            yield webapp.application
+```
+
+Yield the application `self.app` and the facade root must point at. It is a **context manager**,
+so `@classmethod` and `@asynccontextmanager` both belong on the override — a factory returning
+an application would hand the lifespan back to `TestCase`. `FreshApplication` routes through the
+same hook, once per test.
+
+Registration order still holds: register providers and include routers *before* entering the
+lifespan. `Application.register` returns `Err` once booted.
+
 ## RefreshDatabase
 
 Mix it in **alongside** `TestCase`; it cannot boot an application alone.

neva/security/__init__.py

@@ -1,17 +1,33 @@
 """Security module for authentication and hashing."""
 
-from neva.security.encryption import AesEncrypter, DecryptionError, Encrypter
-from neva.security.hashing import Argon2Hasher, BcryptHasher, Hasher, HashManager
+from neva.security.encryption import AesEncrypter, DecryptionError, Encrypter, JsonValue
+from neva.security.hashing import (
+    Argon2Config,
+    Argon2Hasher,
+    BcryptConfig,
+    BcryptHasher,
+    Hasher,
+    HashingConfig,
+    HashManager,
+)
 from neva.security.provider import SecurityProvider
+from neva.security.tokens import generate_token, hash_token, verify_token
 
 
 __all__ = [
     "AesEncrypter",
+    "Argon2Config",
     "Argon2Hasher",
+    "BcryptConfig",
     "BcryptHasher",
     "DecryptionError",
     "Encrypter",
     "HashManager",
     "Hasher",
+    "HashingConfig",
+    "JsonValue",
     "SecurityProvider",
+    "generate_token",
+    "hash_token",
+    "verify_token",
 ]

neva/security/hashing/__init__.py

@@ -1,5 +1,6 @@
 """Hashing module for password hashing."""
 
+from neva.security.hashing.config import Argon2Config, BcryptConfig, HashingConfig
 from neva.security.hashing.hash_manager import HashManager
 from neva.security.hashing.hashers.argon2 import Argon2Hasher
 from neva.security.hashing.hashers.bcrypt import BcryptHasher
@@ -7,8 +8,11 @@ from neva.security.hashing.hashers.protocol import Hasher
 
 
 __all__ = [
+    "Argon2Config",
     "Argon2Hasher",
+    "BcryptConfig",
     "BcryptHasher",
     "HashManager",
     "Hasher",
+    "HashingConfig",
 ]

neva/support/facade/log.pyi

@@ -1,11 +1,16 @@
 """Type stub for Log facade."""
 
-from typing import override
+from typing import ClassVar, override
 
 from neva.arch import Facade
 from neva.obs.logging.contracts import Channel, Processor
+from neva.obs.logging.resolver import ChannelResolver
+from neva.support import Option
 
 class Log(Facade):
+    channels: ClassVar[Option[ChannelResolver]]
+    """The resolver, for callers wanting a resolution failure as a value."""
+
     @classmethod
     @override
     def get_facade_accessor(cls) -> type: ...

neva/testing/test_case.py

@@ -2,6 +2,7 @@
 
 import inspect
 from collections.abc import AsyncIterator, Iterator
+from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import override
 
@@ -39,6 +40,10 @@ class TestCase:
 
     A class that genuinely needs a fresh application per test -- one varying the
     *shape* of its config rather than reading it -- inherits `FreshApplication`.
+
+    Two public override points: `create_config` for the configuration, and
+    `boot_application` for the application built over it and the lifespan it is
+    held open by.
     """
 
     pytestmark = pytest.mark.asyncio(loop_scope="class")
@@ -103,6 +108,39 @@ class TestCase:
         )
         raise TypeError(msg)
 
+    @classmethod
+    @asynccontextmanager
+    async def boot_application(cls, config_path: Path) -> AsyncIterator[Application]:
+        """Build the application under test and hold it booted.
+
+        The public override point for *what* a class tests and *how* it starts.
+        `create_config` decides the configuration; this decides the application.
+        Overriding it is how a downstream package tests something that owns an
+        `Application` rather than being one -- an HTTP app whose own lifespan has
+        to be the one entered, because that is what seeds its per-request state.
+
+        An override yields the `Application` the facades and `self.app` must point
+        at, from inside whatever lifespan it needs::
+
+            @classmethod
+            @asynccontextmanager
+            async def boot_application(cls, config_path):
+                webapp = App(config_path=config_path)
+                async with webapp.router.lifespan_context(webapp):
+                    yield webapp.application
+
+        It is a context manager rather than a factory so that the lifespan stays
+        the subclass's to choose. A factory would leave `TestCase` entering
+        `Application.lifespan()` itself, which boots the container but skips any
+        lifespan wrapped around it.
+
+        Yields:
+            The booted application under test.
+        """
+        app = Application(config_path=config_path)
+        async with app.lifespan():
+            yield app
+
     @pytest_asyncio.fixture(scope="class", loop_scope="class")
     @classmethod
     async def _test_case_application(
@@ -113,8 +151,7 @@ class TestCase:
         Yields:
             Application instance with lifespan managed.
         """
-        app = Application(config_path=_test_case_config)
-        async with app.lifespan():
+        async with cls.boot_application(_test_case_config) as app:
             yield app
 
     @pytest.fixture(autouse=True)
@@ -174,8 +211,7 @@ class FreshApplication(TestCase):
         Yields:
             A freshly built Application, torn down at the end of the test.
         """
-        app = Application(config_path=self._build_config(tmp_path))
-        async with app.lifespan():
+        async with self.boot_application(self._build_config(tmp_path)) as app:
             yield app
 
 

{python_neva-5.0.0.dist-info → python_neva-5.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 5.0.0
+Version: 5.3.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
@@ -20,6 +20,8 @@ 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
@@ -52,7 +54,7 @@ independent repo, independently versioned and published.
 | `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-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                     |
 
@@ -65,20 +67,6 @@ independent repo, independently versioned and published.
 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
 
@@ -100,6 +88,9 @@ current span's ids on every record.
 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
@@ -147,7 +138,6 @@ rewrite the new tag with the rendered changelog as its annotation.
 - Feature-parity FastStream integration (now scaffolded as `neva-faststream`)
 - Improved router registration (auto-discovery OR provider-based? both?)
 - Improved security tooling (performance improvements, better defaults, etc.)
-- 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-5.0.0.dist-info → python_neva-5.3.0.dist-info}/RECORD

@@ -15,7 +15,7 @@ neva/config/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/config/repository.py,sha256=p8PjTfjV23ioy_iyb5b6oYPnYq1bVe6q6gVRSegJr7Q,5505
 neva/database/__init__.py,sha256=3yYnEe8HQM86tURyAhTbMtE7AXubIEMN3GuwxkkT-bk,508
 neva/database/config.py,sha256=bVKUqlrYDFrURqg_FbntPXyVkbOUPSVXQJTKjyucjL0,451
-neva/database/connection.py,sha256=PkpC--RyLh0K2AR26a1ZlpHN0p4uFFlcbwSpPdSj8Y8,7274
+neva/database/connection.py,sha256=XPVrzJiGYtm1Za7RYaC11XZqVG_ezsH1CBsRyzF-pLw,7061
 neva/database/manager.py,sha256=UNQh1xorvoBWHoNS5N8By7lxt5wtGtRixIcMhjZjzYI,4731
 neva/database/provider.py,sha256=XCi8-mfJ5KDVpVO10YlNX4jt0a9ESSeTyn8o3ohOe9c,1701
 neva/database/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -39,10 +39,13 @@ neva/guidelines/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/guidelines/fragments/configuration.md,sha256=rrjxaZW6JPwAnJ1ow9r5sx0itLUzBIQjvVRUZ7zn8SA,4607
 neva/guidelines/fragments/database-transactions.md,sha256=i0IBbz_DZ19w7Sz_e8t-sAwYQiVU55GJRxM11azjGcM,5941
 neva/guidelines/fragments/events.md,sha256=0eG0zGTfCQpToClydlGhpj5BjXhnKfi2GGve3jz7lv8,6071
-neva/guidelines/fragments/observability.md,sha256=E3ekECOAJ7K5NlPrgjw2dO10r0r0J85DmW-aeEuD_2M,4858
+neva/guidelines/fragments/facades.md,sha256=4GCoeUGCiuduWY0msgZO0yJ8MOfDwqqQfm_WsWvjHq8,4308
+neva/guidelines/fragments/factories.md,sha256=4ajYgtN1z4Fwb55FnXw7ROGQUrhqE4N9sgGHbg7UUmA,3101
+neva/guidelines/fragments/observability.md,sha256=RjX73YXulr30v-SCw1J3NHN_f6CGLCKUHQPS-rFeOLE,5760
 neva/guidelines/fragments/result-option.md,sha256=fGyuGwJmSIqb7gWjecbQXiKBdstJ7p5_k82j8KLOzcc,2809
-neva/guidelines/fragments/service-providers.md,sha256=IM-UOhtrfy0uFe2z7RsMuDMcWQblpCDSkr1rfoorDZQ,6412
-neva/guidelines/fragments/testing.md,sha256=0HZEdv1RmKbdVnzVVEe5ug4AD73gJoD6r74WC9WT5kI,5659
+neva/guidelines/fragments/security.md,sha256=Pz9OHB7o7qVE-Pc3JpSNfMwPqov0ZxLlaIxMmsYfxbQ,5994
+neva/guidelines/fragments/service-providers.md,sha256=NAJfbChBUq9JC5GyWH7eZbUg55lvVi0tOGnxbvkbQtI,8445
+neva/guidelines/fragments/testing.md,sha256=cFOwNHjjyorpooUyEwsSk3O8XynAlkyk3_AzlQUO_K0,6993
 neva/obs/__init__.py,sha256=SShyp-wlNt6USx7Eus8_Csy0miEHXOS2YnVbP2EARjs,490
 neva/obs/config.py,sha256=cFDverbec3QSpLn0txcXnBnMvnUV7dGRTEdVERhl9L4,1026
 neva/obs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -56,13 +59,13 @@ neva/polyfactory/__init__.py,sha256=t7uAXaleAyshSyBdGXNzvgY0nNpb5AqFU4zjE8lyKyk,
 neva/polyfactory/factories.py,sha256=8VoZJlY0-_ZOM8rmfUcvEbt-KOZsaDj8f6R5EQF62u8,600
 neva/polyfactory/persistence.py,sha256=1qBg8L_xkiRFq6J2XoZFez43oxNWDaUM8SrlNAeOkQA,605
 neva/polyfactory/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-neva/security/__init__.py,sha256=Dhh3ZsseP6biWgRQY4hYKkoYFCR7ehhxz4VBqN8e02k,440
+neva/security/__init__.py,sha256=VycgRsm4qfkfdj6PWPCf95tGzuwi-j6nbGP92qTTLLw,739
 neva/security/provider.py,sha256=6GqSzAsgHtOEnkQFmd0Dusgbv65QhJRxOEBfmObspmc,533
 neva/security/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 neva/security/encryption/__init__.py,sha256=eVWW-qk03vy7Bn-sNQ2WJHWZI6tPJOkknJz8llc1m0M,288
 neva/security/encryption/encrypter.py,sha256=YiJrLmv2C_CkqU3eZDvBHnkwA5zzjb6T3-X2kThywZs,5152
 neva/security/encryption/protocol.py,sha256=pZtkTCz0k6eUX0fivJrvb7yDXy2eTAg--ZbCXhfUXWc,847
-neva/security/hashing/__init__.py,sha256=k3SviEvtJLjBXTkR5I6w9YMPw6Q-LIoE1wGNz3GYvOE,374
+neva/security/hashing/__init__.py,sha256=LoLeOTXifNDFR5_SAsJ_dk135X0TKYFTODCiALCGQ-E,518
 neva/security/hashing/config.py,sha256=ltj7_GW44gSg2N0i8CEYaw6Y6xUfzwsr4zXk5ic_sJI,624
 neva/security/hashing/hash_manager.py,sha256=F55T1xcQpIEV3A52L4KeAbkUeS7ogCgm8lI79RUJP_M,6123
 neva/security/hashing/hashers/__init__.py,sha256=Zn_Q2tj_8lhhwJRZ7RXeJLYujd-3j7Rr8JQO2sSGgJs,44
@@ -94,13 +97,13 @@ neva/support/facade/event.pyi,sha256=7R6osyTZbHt_zkCfQ-uZnTLfyZTeN1bi3exsgl3-36k
 neva/support/facade/hash.py,sha256=tGhsvfGovt-mcRXSjDKf4jt1n7ib0eDPXFvRUfVxLUc,292
 neva/support/facade/hash.pyi,sha256=Uy0CkV67MImPjHc6BmmLQPd7qF1QNDtO1oDFyyRr-1A,2950
 neva/support/facade/log.py,sha256=_uLoHB9tkpHkiqEJXazbaqfiKUOtv3NS71ZCZAprzOI,347
-neva/support/facade/log.pyi,sha256=yC1yhn1EiDGsxryG7K5lQ6esHnaxg3qC_B4U2hei6e8,2548
+neva/support/facade/log.pyi,sha256=6ZI72G3mgn2cUAnPvKMO9cLYhiTrjzwNGDV2WNxtWoA,2770
 neva/testing/__init__.py,sha256=QW9inJP1lC_HeoJbKjD_kyHCy4cFV6qt9Rp-EjsKmOY,245
 neva/testing/fakes.py,sha256=w2dnFaO6x14l0_si7iBNELMCxaFi8VsVOSQ6PmTlclE,2936
 neva/testing/fixtures.py,sha256=oiPa5ntUkW-SbySDvwEHXtti8NqSwI-R0CT1_ezTx_Y,1445
 neva/testing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-neva/testing/test_case.py,sha256=quVjECLWw5ZOnf7kwvtRsyD-_mkyxv5yRuvNSOAJYUI,8145
-python_neva-5.0.0.dist-info/METADATA,sha256=DkBt1UZCLD8-RTloyFVKSpSJhGLmYdvUNk1vm4v2JEw,7523
-python_neva-5.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-python_neva-5.0.0.dist-info/entry_points.txt,sha256=DmWZ-qNgvl4eUAXxwX4iLgb38e6X-zU8JDx_brlmkyk,45
-python_neva-5.0.0.dist-info/RECORD,,
+neva/testing/test_case.py,sha256=GdIKrHz9ZuirJybUuaXbW8o-PhOzkvg-pJwe8PAwFD4,9789
+python_neva-5.3.0.dist-info/METADATA,sha256=oGUx6-CaM5vaFk2bx2Jq8anhB-ZETQCktJrh3XwTJl4,7352
+python_neva-5.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+python_neva-5.3.0.dist-info/entry_points.txt,sha256=DmWZ-qNgvl4eUAXxwX4iLgb38e6X-zU8JDx_brlmkyk,45
+python_neva-5.3.0.dist-info/RECORD,,