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

{python_neva-3.7.0 → python_neva-4.1.0}/CHANGELOG.md

@@ -1,3 +1,45 @@
+## 4.1.0 (2026-08-31)
+
+### ✅🤡🧪 Tests
+
+- **support**: add tests for results and options
+
+### 📝💡 Documentation
+
+- **guidelines**: ship agent guidelines in the wheel
+
+## 4.0.0 (2026-08-28)
+
+### 💥 Boom
+
+- **testing**: require create_config overrides to be classmethods
+- **arch**: require an explicit lifetime, drop Application.bind
+
+### ✨ Features
+
+- **deps**: offer the ASGI middleware through the asgi extra
+- **config**: scope the core config shapes to what the core reads, export them
+
+### 🐛🚑️ Fixes
+
+- **security**: name generate_token's argument nbytes, cover the token helpers
+- **arch**: fail the boot when declared listeners cannot be wired
+- **config**: default the config directory to ./config, not the project root
+- **database**: accept sync transaction callbacks, never lose their failures
+
+### ♻️ Refactorings
+
+- **obs**: move the ASGI middleware to neva-asgi
+- **arch**: describe the FastStream lifespan without starlette
+
+### ⚡️ Performance
+
+- **GED-16633**: build the TestCase application once per class
+
+### 📝💡 Documentation
+
+- **database**: un-deprecate register_engine, say what it is for
+
 ## 3.7.0 (2026-08-28)
 
 ### ✨ Features

{python_neva-3.7.0 → python_neva-4.1.0}/CLAUDE.md

@@ -75,7 +75,7 @@ await Event.dispatch(UserCreated(event_id=1, user_id=42))
 **Service Providers** - Register services with lifecycle hooks. Bindings
 declare a lifetime by name — `singleton` (one per process), `scoped` (one per
 REQUEST scope), `transient` (one per resolution), `instance` (an object you
-already have). Bare `bind` without an explicit `scope`/`cache` is deprecated:
+already have). Bare `bind` with neither `scope` nor `cache` raises `TypeError`:
 ```python
 class MyProvider(ServiceProvider):
     def register(self) -> Result[Self, str]:
@@ -138,4 +138,15 @@ rendered changelog. See `README.md` for the full flow and the plugin list.
 
 ## Documentation
 
-- Architecture guides: `wiki/architecture/`
+Agent guidelines live in `neva/guidelines/fragments/` and ship inside the wheel, so a
+consuming project gets the guidance for the version it actually installed. They are
+discovered by `neva-boost` through the `neva.boost` entry point (`neva/guidelines/manifest.py`).
+
+- One fragment per topic, with frontmatter: `id`, `title`, `requires` (a version
+  specifier), `triggers`, `priority`, `verified_by`.
+- **`verified_by` lists the tests that prove the fragment's claims.** Every path must
+  resolve. When you change behaviour, update the fragment in the same commit as the code
+  and the test — that pairing is what keeps the guidance honest.
+- Terse and rule-shaped, not narrative: this text is loaded into an agent's context.
+- Nothing here may describe another package. `neva-fastapi` and friends ship their own
+  fragments; a cross-package claim made here cannot be verified or maintained.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 3.7.0
+Version: 4.1.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
@@ -12,9 +12,10 @@ 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: starlette>=0.41
 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: fastapi
 Requires-Dist: neva-fastapi>=1.1.1; extra == 'fastapi'
 Provides-Extra: faststream
@@ -48,6 +49,7 @@ independent repo, independently versioned and published.
 | ----------------- | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------- |
 | `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/)) |
 | `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-example`    | `neva-example/`    | Reference application consuming `python-neva[fastapi]`. Not published; demonstration + integration test bed. | unpublished                     |

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

@@ -20,6 +20,7 @@ independent repo, independently versioned and published.
 | ----------------- | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------- |
 | `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/)) |
 | `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-example`    | `neva-example/`    | Reference application consuming `python-neva[fastapi]`. Not published; demonstration + integration test bed. | unpublished                     |

{python_neva-3.7.0 → python_neva-4.1.0}/neva/arch/__init__.py

@@ -5,6 +5,7 @@ and facade implementations.
 """
 
 from neva.arch.application import Application
+from neva.arch.config import AppConfig, ProviderConfig
 from neva.arch.facade import Facade
 from neva.arch.service_provider import (
     Bootable,
@@ -13,8 +14,10 @@ from neva.arch.service_provider import (
 
 
 __all__ = [
+    "AppConfig",
     "Application",
     "Bootable",
     "Facade",
+    "ProviderConfig",
     "ServiceProvider",
 ]

{python_neva-3.7.0 → python_neva-4.1.0}/neva/arch/application.py

@@ -6,17 +6,16 @@ from collections.abc import AsyncGenerator, Sequence
 from contextlib import AsyncExitStack, asynccontextmanager
 from contextvars import ContextVar
 from pathlib import Path
-from typing import Any, Callable, Self
+from typing import Any, Self
 
 import dishka
 from dishka.provider import BaseProvider
-from typing_extensions import deprecated
 
 from neva.arch.facade import Facade
 from neva.arch.scopes import BaseScope, Scope
 from neva.arch.service_provider import Bootable, ServiceProvider
 from neva.config.loader import ConfigLoader
-from neva.support import Err, Ok, Result
+from neva.support import Err, Ok, Result, Some
 
 
 _current_container: ContextVar["dishka.AsyncContainer"] = ContextVar(
@@ -24,6 +23,26 @@ _current_container: ContextVar["dishka.AsyncContainer"] = ContextVar(
 )
 
 
+def _resolve_config_path(config_path: str | Path | None) -> Path:
+    """Resolve the directory config files are loaded from.
+
+    The config directory is a dedicated folder, never the project root: every
+    ``.py`` in it is imported to read its ``config`` dict, so pointing this at
+    a directory holding ordinary modules would execute them.
+
+    Returns:
+        The explicit argument, else $NEVA_CONFIG_PATH, else ./config.
+    """
+    if config_path is not None:
+        return Path(config_path)
+
+    env_path = os.getenv("NEVA_CONFIG_PATH")
+    if env_path:
+        return Path(env_path)
+
+    return Path.cwd() / "config"
+
+
 class Application:
     """Base application for DI and facade injection."""
 
@@ -31,8 +50,9 @@ class Application:
         """Initialize the application and its bindings.
 
         Args:
-            config_path: Path to the configuration directory. Defaults to "./config"
-                relative to the current working directory.
+            config_path: Path to the configuration directory. Defaults to
+                ``$NEVA_CONFIG_PATH``, else ``./config`` relative to the
+                current working directory.
 
         Raises:
             RuntimeError: If the application fails to initialize.
@@ -47,11 +67,7 @@ class Application:
         self._container: dishka.AsyncContainer | None = None
         self._booted: bool = False
 
-        configuration_path = (
-            config_path
-            if config_path is not None
-            else os.getenv("NEVA_CONFIG_PATH", default=Path.cwd())
-        )
+        configuration_path = _resolve_config_path(config_path)
         match ConfigLoader(configuration_path).load_all():
             case Err(e):
                 raise RuntimeError(f"Failed to register config: {e}")
@@ -150,21 +166,6 @@ class Application:
         for provider in providers:
             _ = self.register(provider)
 
-    @deprecated("Use the new bind() method directly with a Service Provider.")
-    def bind(
-        self,
-        source: type | Callable[..., Any],
-        *,
-        interface: type | None = None,
-        scope: BaseScope | None = None,
-    ) -> None:
-        """Binds a source to the container."""
-        _ = self.root_provider.provide(
-            source=source,
-            scope=scope,
-            provides=interface,
-        )
-
     @property
     def current_container(self) -> dishka.AsyncContainer:
         """The container backing resolution in the current context.
@@ -226,6 +227,11 @@ class Application:
     @asynccontextmanager
     async def lifespan(self) -> AsyncGenerator[None]:
         """Wire the facades and providers."""
+        # The facade root is a single process-global slot, so a short-lived
+        # application nested inside a longer-lived one must hand it back rather
+        # than clear it -- otherwise it disarms every facade for whatever the
+        # outer application still has to do.
+        previous_facade_application = Facade.get_facade_application()
         Facade.set_facade_application(self)
         self._booted = True
 
@@ -243,27 +249,50 @@ class Application:
             if self._container is not None:
                 await self._container.close()
             self._booted = False
-            Facade.reset_facade_application()
+            match previous_facade_application:
+                case Some(application):
+                    Facade.set_facade_application(application)
+                case _:
+                    Facade.reset_facade_application()
 
     def _bind_event_listeners(self) -> None:
         """Bind all listener classes declared in provider ``listen`` dicts."""
         for provider in self.providers.values():
             for listeners in provider.listen.values():
                 for listener_cls in listeners:
-                    # Straight onto the root provider: routing this through the
-                    # deprecated `bind` warned on every boot.
+                    # Straight onto the root provider: these listeners are not
+                    # a provider's own bindings, so they do not belong in one.
                     _ = self.root_provider.provide(listener_cls, scope=Scope.APP)
 
     async def _wire_event_listeners(self) -> None:
-        """Wire event-listener mappings from all providers onto the dispatcher."""
+        """Wire event-listener mappings from all providers onto the dispatcher.
+
+        Raises:
+            RuntimeError: If listeners are declared but the dispatcher cannot
+                be resolved. Booting on regardless would leave every one of
+                them unwired, so the events would simply never fire — with
+                nothing anywhere saying why.
+        """
         from neva.events.dispatcher import EventDispatcher
 
-        result = await self.make_async(EventDispatcher)
-        if result.is_err:
+        declared = [
+            (event_cls, listener_cls)
+            for provider in self.providers.values()
+            for event_cls, listeners in provider.listen.items()
+            for listener_cls in listeners
+        ]
+        if not declared:
             return
 
-        dispatcher = result.unwrap()
-        for provider in self.providers.values():
-            for event_cls, listeners in provider.listen.items():
-                for listener_cls in listeners:
+        match await self.make_async(EventDispatcher):
+            case Err(e):
+                msg = (
+                    f"Cannot wire {len(declared)} declared event listener(s): "
+                    f"the EventDispatcher could not be resolved ({e}). "
+                    "Register EventServiceProvider, or remove the 'listen' "
+                    "mappings that need it."
+                )
+                raise RuntimeError(msg)
+            case Ok(dispatcher):
+                for event_cls, listener_cls in declared:
                     dispatcher.listen(event_cls, listener_cls)

python_neva-4.1.0/neva/arch/config.py

@@ -0,0 +1,49 @@
+"""Config shapes for the namespaces the core itself reads.
+
+Annotate a config file with one of these to have a type checker catch typos
+and wrong value types before boot:
+
+```python
+# src/config/app.py
+from neva.arch import AppConfig
+
+config: AppConfig = {"providers": [MyProvider]}
+```
+
+Keys read by an integration package are declared by that package, not here —
+`neva-fastapi` owns the OpenAPI and title keys of the `app` namespace, for
+instance. The core only describes what the core consumes.
+"""
+
+from typing import NotRequired, TypedDict
+
+from neva.arch.service_provider import ServiceProvider
+
+
+class AppConfig(TypedDict):
+    """The `app` namespace keys the core reads.
+
+    Attributes:
+        key: Base64-encoded 32-byte key for `Crypt`. Generate one with
+            `AesEncrypter.generate_key()`.
+        previous_keys: Superseded keys, still accepted when decrypting so a
+            key rotation does not orphan existing ciphertext.
+        providers: Service providers to register, appended after those from
+            the `providers` namespace.
+    """
+
+    key: NotRequired[str]
+    previous_keys: NotRequired[list[str]]
+    providers: NotRequired[list[type[ServiceProvider]]]
+
+
+class ProviderConfig(TypedDict):
+    """The `providers` namespace.
+
+    A dedicated namespace for the provider list, read before `app.providers`.
+
+    Attributes:
+        providers: Service providers to register.
+    """
+
+    providers: NotRequired[list[type[ServiceProvider]]]

{python_neva-3.7.0 → python_neva-4.1.0}/neva/arch/integrations/faststream.py

@@ -1,18 +1,23 @@
 """FastStream wrapper for Neva."""
 
-from collections.abc import AsyncGenerator, AsyncIterator
-from contextlib import asynccontextmanager
+from collections.abc import AsyncGenerator, AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from typing import Any
 
 import faststream
 from faststream._internal.broker import BrokerUsecase
 from faststream._internal.configs import BrokerConfig
-from starlette.types import StatelessLifespan
 
 from neva.arch import Application, ServiceProvider
 from neva.support import Result
 
 
+# Spelled out locally rather than borrowed from starlette.types: a messaging
+# app's lifespan is not a web concern, and the core must not import an ASGI
+# framework to describe one.
+type FastStreamLifespan = Callable[["FastStream"], AbstractAsyncContextManager[None]]
+
+
 class FastStream(faststream.FastStream):
     """FastStream wrapper for Neva."""
 
@@ -42,9 +47,7 @@ class FastStream(faststream.FastStream):
         async with self.application.lifespan():
             yield
 
-    def _create_lifespan(
-        self,
-    ) -> StatelessLifespan["FastStream"]:
+    def _create_lifespan(self) -> FastStreamLifespan:
         @asynccontextmanager
         async def composed_lifespan(_: faststream.FastStream) -> AsyncIterator[None]:
             async with self.lifespan():

{python_neva-3.7.0 → python_neva-4.1.0}/neva/arch/service_provider.py

@@ -8,7 +8,6 @@ container and optionally managing their lifecycle.
 from __future__ import annotations
 
 import abc
-import warnings
 from contextlib import AbstractAsyncContextManager
 from typing import (
     TYPE_CHECKING,
@@ -115,9 +114,9 @@ class ServiceProvider(abc.ABC):
         `instance` — which say what they mean. Use `bind` directly only to
         reach a scope those do not cover, and then pass `scope` explicitly.
 
-        Calling this with neither `scope` nor `cache` is deprecated: the
-        resulting binding is a process-wide singleton, which is the opposite of
-        Laravel's transient `bind`, and nothing at the call site says so.
+        A lifetime is required. Without one the binding would be a
+        process-wide singleton — the opposite of Laravel's transient `bind` —
+        with nothing at the call site saying so.
 
         Args:
             source: The class or factory to bind.
@@ -125,16 +124,17 @@ class ServiceProvider(abc.ABC):
             scope: The dishka scope. Defaults to the provider's (APP).
             when: Marker gating this binding.
             cache: Whether to reuse one instance per scope. Defaults to True.
+
+        Raises:
+            TypeError: If neither `scope` nor `cache` is given.
         """
         if scope is None and cache is None:
-            warnings.warn(
-                "bind() without an explicit lifetime is deprecated and will "
-                "require one in 4.0. It currently creates a process-wide "
-                "singleton: use singleton() for that, or scoped() / "
-                "transient() / instance(), or pass scope= or cache= yourself.",
-                DeprecationWarning,
-                stacklevel=2,
+            msg = (
+                "bind() requires an explicit lifetime: use singleton() for a "
+                "process-wide instance, or scoped() / transient() / "
+                "instance(), or pass scope= or cache= yourself."
             )
+            raise TypeError(msg)
 
         _ = self.provider.provide(
             source=source,

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

@@ -7,6 +7,7 @@ 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
@@ -147,9 +148,13 @@ class ConnectionManager:
             else await tx.execute_on_rollback_callbacks()
         )
         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__)
         for result in results:
-            if result.is_err and self.logger is not None:
-                self.logger.error(
+            if result.is_err:
+                logger.error(
                     f"{label} callback failed",
                     error=result.err().unwrap(),
                     connection=self.name,

{python_neva-3.7.0 → python_neva-4.1.0}/neva/database/manager.py

@@ -5,7 +5,6 @@ from contextlib import asynccontextmanager
 from typing import final
 
 from sqlalchemy.ext import asyncio
-from typing_extensions import deprecated
 
 from neva.database.config import ConnectionConfig
 from neva.database.connection import ConnectionManager, TransactionContext
@@ -24,9 +23,14 @@ class DatabaseManager:
         self._logger = logger
         self._connections: dict[str, ConnectionManager] = {}
 
-    @deprecated("Please use DatabaseManager.register_connection instead.")
     def register_engine(self, name: str, engine: asyncio.AsyncEngine) -> None:
-        """Register an engine and create a session factory for a connection.
+        """Register a connection around an engine you already built.
+
+        Prefer `register_connection`, which builds the engine from config. Use
+        this when the caller must own the engine — a test that creates the
+        schema on an in-memory database has to hand over that exact engine,
+        since a second engine to `sqlite:///:memory:` is a second, empty
+        database.
 
         Args:
             name: The connection name.

{python_neva-3.7.0 → python_neva-4.1.0}/neva/database/transaction.py

@@ -1,17 +1,41 @@
 """Transaction management systems."""
 
 import asyncio
-from collections.abc import Awaitable
+import inspect
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from enum import Enum, auto
-from typing import Callable, Self
+from typing import Self
 
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from neva.support import Err, Nothing, Option, Result, Some
+from neva.support import Err, Nothing, Ok, Option, Result, Some
 
 
-type TransactionCallback = Callable[[], Awaitable[Result[None, str]]]
+type TransactionOutcome = Result[None, str] | None
+type TransactionCallback = Callable[
+    [], TransactionOutcome | Awaitable[TransactionOutcome]
+]
+
+
+async def _run_callback(callback: TransactionCallback) -> Result[None, str]:
+    """Invoke a transaction callback, whether it is sync or async.
+
+    A callback may return a ``Result`` to report its own failure, or ``None``
+    to say "done, nothing to report" — which is what a bare side-effecting
+    lambda does.
+
+    Returns:
+        The callback's own Result, Ok(None) if it returned None, or Err if it
+        raised.
+    """
+    try:
+        outcome = callback()
+        if inspect.isawaitable(outcome):
+            outcome = await outcome
+    except Exception as e:
+        return Err(f"Callback raised: {e}")
+    return Ok(None) if outcome is None else outcome
 
 
 class TransactionState(Enum):
@@ -77,10 +101,7 @@ class Transaction:
         """
         results: list[Result[None, str]] = []
         for callback in self._on_commit:
-            try:
-                results.append(await callback())
-            except Exception as e:
-                results.append(Err(f"Callback raised: {e}"))
+            results.append(await _run_callback(callback))
         self._on_commit.clear()
         return results
 
@@ -92,10 +113,7 @@ class Transaction:
         """
         results: list[Result[None, str]] = []
         for callback in self._on_rollback:
-            try:
-                results.append(await callback())
-            except Exception as e:
-                results.append(Err(f"Callback raised: {e}"))
+            results.append(await _run_callback(callback))
         self._on_rollback.clear()
         return results
 

python_neva-4.1.0/neva/guidelines/__init__.py

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

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

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