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

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

@@ -1,3 +1,13 @@
+## 4.1.0 (2026-08-31)
+
+### ✅🤡🧪 Tests
+
+- **support**: add tests for results and options
+
+### 📝💡 Documentation
+
+- **guidelines**: ship agent guidelines in the wheel
+
 ## 4.0.0 (2026-08-28)
 
 ### 💥 Boom

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 4.0.0
+Version: 4.1.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0

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.

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

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

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

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

python_neva-4.1.0/neva/guidelines/fragments/result-option.md

@@ -0,0 +1,74 @@
+---
+id: result-option
+title: Result and Option
+requires: python-neva>=4.0
+triggers: [returning an error, handling a failure, unwrapping, a function that can fail, T | None]
+priority: 10
+verified_by: [tests/support/test_results.py]
+---
+
+# Result and Option
+
+Fallible operations return `Result[T, str]`. Absent values are `Option[T]`. Exceptions are for
+unrecoverable conditions only.
+
+```python
+from neva.support import Result, Ok, Err, Option, Some, Nothing, from_optional, UnwrapError
+```
+
+`Result` is the alias `Ok[T, E] | Err[T, E]`; `Option` is `Nothing[T] | Some[T]`. Construct the
+variants directly, annotate with the alias.
+
+## Rules
+
+- `is_ok`, `is_err`, `is_some`, `is_nothing` are **properties**. `if r.is_ok():` is always
+  truthy — it is a bound method.
+- Errors are `str` across the framework. Any type works as `E`; stay with strings.
+- `unwrap()` asserts "this cannot fail" and raises `UnwrapError`. Correct in tests and where an
+  `Err` is a bug; at a boundary use `unwrap_or` / `map` / `and_then` / `match`.
+- `map(f)` when `f` returns a plain value; `and_then(f)` when `f` returns a `Result`/`Option`.
+  `and_then` short-circuits on the first failure.
+- `ok_or` / `ok_or_else` exist **only on `Option`**. A `Result` cannot be `ok_or`'d — to reshape
+  its error use `map_err`, to supply a fallback use `unwrap_or`.
+
+## Converting
+
+| From | To | Call |
+| ---- | -- | ---- |
+| `Option` | `Result` | `ok_or(err)`, `ok_or_else(f)` |
+| `Result` | `Option` | `ok()` keeps the value, `err()` keeps the error |
+| `T \| None` | `Option` | `from_optional(x)` |
+
+```python
+Config.get("app.title").unwrap_or("Untitled")          # Result: fallback via unwrap_or
+Config.get("app.title").map_err(lambda e: f"config: {e}")
+find_user(uid).ok_or("user not found")                 # Option: absence becomes an error
+```
+
+## Pattern matching
+
+`Ok`/`Err`/`Some` are single-field frozen dataclasses, so positional `match` binds through
+`__match_args__`. Never name the private `_value` / `_err` fields.
+
+```python
+match ConfigLoader(path).load_all():
+    case Err(message):
+        raise RuntimeError(f"Failed to register config: {message}")
+    case Ok(configs):
+        ...
+```
+
+## Equality and hashing
+
+Value equality, and hashable. A variant never equals a different variant or a non-`Result`:
+`Ok(1) == Ok(1)`, `Ok(1) != Err(1)`, `Ok(1) != 1`. `Some`/`Ok` define `__eq__` explicitly;
+`Nothing`/`Err` use the dataclass one, so `Err(1) == Ok(1)` resolves through `Ok`'s reflected
+comparison.
+
+## Method reference
+
+Both: `map`, `map_or`, `map_or_else`, `and_then`, `unwrap`, `unwrap_or`, `unwrap_or_else`,
+`expect`.
+`Result` only: `map_err`, `unwrap_err`, `expect_err`, `ok`, `err`.
+`Option` only: `filter`, `or_else`, `flatten` (collapses one level), `zip`, `ok_or`,
+`ok_or_else`, `in` via `__contains__`.

python_neva-4.1.0/neva/guidelines/fragments/service-providers.md

@@ -0,0 +1,114 @@
+---
+id: service-providers
+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]
+---
+
+# Service providers and bindings
+
+Every component owns one `ServiceProvider` in its `provider.py`, listed in the `providers`
+config namespace. Registration happens in `register()`; nothing else binds.
+
+```python
+from typing import Self, override
+from neva.arch import ServiceProvider
+from neva.support import Ok, Result
+
+class ActorServiceProvider(ServiceProvider):
+    @override
+    def register(self) -> Result[Self, str]:
+        _ = self.singleton(CreateActor)
+        _ = self.singleton(SqlAlchemyActorRepository, interface=ActorRepository)
+        return Ok(self)
+```
+
+`register()` returns `Ok(self)`, or `Err("...")` to abort boot with a message. Bind only — no
+I/O, no connections. Startup work goes in `lifespan()`.
+
+## A lifetime is mandatory
+
+Bare `bind()` with neither `scope` nor `cache` **raises `TypeError`** since 4.0. Use the named
+lifetimes; they say what they mean and return `self`.
+
+| Call | Scope | Cached | Use for |
+| ---- | ----- | ------ | ------- |
+| `singleton(src)` | APP | yes | One instance per process. The default choice. |
+| `scoped(src)` | REQUEST | yes, per scope | Per-request state — request context, unit of work. |
+| `transient(src)` | provider's (APP) | never | Stateless helpers, anything that must not be shared. |
+| `instance(value)` | APP | n/a | An object you already built. `interface` defaults to `type(value)`. |
+
+`bind()` itself returns `None` and is the escape hatch for a scope the four do not cover — then
+pass `scope=` explicitly.
+
+```python
+_ = self.singleton(Mailer)
+_ = self.scoped(UnitOfWork, interface=UoW)
+_ = self.transient(Clock)
+_ = self.instance(settings_object)
+self.bind(Thing, scope=Scope.SESSION)      # only when a named lifetime cannot express it
+```
+
+Every helper takes `interface=` to register under a protocol or base type, and `when=` to gate
+the binding behind a marker.
+
+## Other seams
+
+- `extend(fn, interface=T)` — `dishka.decorate`: wrap or replace a binding declared elsewhere,
+  including in another package. The cross-package customisation seam.
+- `from_context(T, scope=...)` — the value is pushed in at scope entry, not constructed.
+  Integrations feed the HTTP request in this way.
+- `activator(predicate, *markers)` — decides whether marker-gated bindings activate. The
+  variadic arguments are **markers** (`neva.arch.markers`), never service classes.
+- `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.
+
+## Startup and shutdown
+
+Implement `lifespan()` and the provider is `Bootable` — a runtime-checkable Protocol, so no
+inheritance is needed.
+
+```python
+@asynccontextmanager
+async def lifespan(self) -> AsyncIterator[None]:
+    cache = (await self.app.make_async(Cache)).unwrap()
+    await cache.connect()
+    try:
+        yield
+    finally:
+        await cache.disconnect()
+```
+
+Lifespans enter in registration order and exit in reverse. Base providers — `LogServiceProvider`,
+`EventServiceProvider`, `DatabaseServiceProvider` — are always registered, first.
+
+## Resolving
+
+`make(T)` and `make_async(T)` return `Result[T, str]` and never raise. Use `make_async` when the
+construction path involves an async provider. Both read the innermost container entered in the
+current context, which is what makes scoped resolution work.
+
+`current_container` is the container backing resolution here — an integration handing a
+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()`.
+
+## Typed config shapes
+
+`AppConfig` and `ProviderConfig` (from `neva.arch`) annotate a config file so a type checker
+catches typos before boot. Each package declares the shape for the keys it reads.
+
+## Pitfalls
+
+- `Application.bind()` was removed in 4.0. Bind through a provider.
+- 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()`.