@codefast/di 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @codefast/di
 
+## 0.8.1
+
+### Patch Changes
+
+- [#791](https://github.com/codefastlabs/codefast/pull/791) [`37a212b`](https://github.com/codefastlabs/codefast/commit/37a212b4d805588413159e11e872b98db82326bf) Thanks [@thevuong](https://github.com/thevuong)! - Point the README's license badge and "License" section at the package's own `LICENSE` file instead of the monorepo root.
+
+- [#796](https://github.com/codefastlabs/codefast/pull/796) [`ba04d27`](https://github.com/codefastlabs/codefast/commit/ba04d2703c59a1677f52e6a9fffd0ec202328218) Thanks [@thevuong](https://github.com/thevuong)! - Rewrite the README around one structure — what the package is, installation and requirements, a complete quick start,
+  the concepts in learning order, then the documents and the license — with every API claim checked against the current
+  code and no figures that go stale.
+
+- [#784](https://github.com/codefastlabs/codefast/pull/784) [`ad2f93a`](https://github.com/codefastlabs/codefast/commit/ad2f93a688e99c3ed8be6ceeae9d6cdd6be861bc) Thanks [@thevuong](https://github.com/thevuong)! - Ship the MIT `LICENSE` file in the published package. `files` already listed it, but the file was missing from the
+  package directory, so the tarball had none.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -1,41 +1,47 @@
 # @codefast/di
 
-Lightweight, type-safe dependency injection for modern TypeScript — built on TC39 Stage 3 decorators, with no
+Lightweight, type-safe dependency injection for TypeScript applications, built on TC39 Stage 3 decorators with no
 `reflect-metadata` and no `experimentalDecorators`.
 
 [![npm version](https://img.shields.io/npm/v/@codefast/di)](https://www.npmjs.com/package/@codefast/di)
-[![license](https://img.shields.io/npm/l/@codefast/di)](https://github.com/codefastlabs/codefast/blob/main/LICENSE)
+[![license](https://img.shields.io/npm/l/@codefast/di)](./LICENSE)
 
-- **Typed tokens.** `Token<Value>` flows through every `bind → resolve` path; `resolve()` returns the type you
-  registered.
-- **Native Stage 3 decorators.** `@injectable`, `inject`, `optional`, `@postConstruct`, `@preDestroy` — no runtime
-  reflection tricks.
-- **Fluent bindings.** Constants, classes, sync/async factories, aliases, named/tagged/predicate constraints, lifecycle
-  hooks.
-- **Scopes with validation.** `singleton` / `scoped` / `transient`, plus `validate()` to catch captive dependencies
-  early.
-- **Modules.** Bundle bindings into reusable units; load, unload, and compose them across containers.
-- **Async-aware.** Async factories, deduped async singleton construction, and `await using` disposal.
+## Overview
 
-> Published on `0.x` and versioned on its own track — while it is there, breaking changes ship as minor versions, which
-> keeps them cheap. Pin the minor if you need stability.
+`@codefast/di` manages the services your app depends on. You describe how to build each service once, then ask a
+container for it by a typed key. The container constructs that service — and everything it depends on — in the right
+order.
 
-## Requirements
+Two calls carry the whole model: `bind` registers a service, and `resolve` returns a fully wired instance.
 
-- **Node.js 24 or later — required**, matching the monorepo's own floor (`engines.node` is `>=24`). Nothing the
-  container calls is newer than that, so a Node 24 serverless runtime needs no polyfill.
-- **TypeScript 5.2+** with native Stage 3 decorators — leave `experimentalDecorators` **off** (it is off by default).
+Use dependency injection when you want swappable implementations, scoping, and lifecycle handled for you, with the
+wiring checked by the TypeScript compiler. Reach for plain `new` while a few objects still do the job; the library earns
+its keep as the dependency graph grows.
+
+- **Typed tokens.** `Token<Value>` flows through every `bind → resolve` path, so `resolve()` returns exactly the type
+  you registered.
+- **Native Stage 3 decorators.** `@injectable`, `inject`, `optional`, `injectAll`, `@postConstruct`, and `@preDestroy`
+  declare dependencies explicitly — no runtime reflection.
+- **Fluent bindings.** Constants, classes, sync and async factories, aliases, named/tagged/predicate constraints, and
+  lifecycle hooks compose in one invariant chain order.
+- **Scopes with validation.** Choose `singleton`, `scoped`, or `transient`, and call `validate()` to catch captive
+  dependencies before the first request.
+- **Modules and introspection.** Bundle bindings into reusable modules, and inspect a container or render its dependency
+  graph as DOT, Mermaid, Cytoscape, or React Flow.
 
 ## Installation
 
 ```bash
 pnpm add @codefast/di
-# or: npm install @codefast/di
 ```
 
-## Quick Start
+`@codefast/di` requires Node.js 24 or later and TypeScript 5.9 or later, with native Stage 3 decorators. Leave
+`experimentalDecorators` off — it's off by default. The package is published on 0.x and versioned on its own track:
+breaking changes ship as minor versions, so pin the minor version when you need stability.
+
+## Quick start
 
-```typescript
+```ts
 import { Container, injectable, token } from "@codefast/di";
 
 interface Logger {
@@ -68,37 +74,40 @@ container.rebind(LoggerToken).toConstantValue({
 });
 ```
 
-`@injectable([...])` lists constructor dependencies in parameter order — no parameter-type reflection, so it works in
-any ESM runtime that supports Stage 3 decorators.
+`@injectable([...])` declares a class's constructor dependencies, in parameter order. The decorator checks the list
+against the constructor signature, so a dependency of the wrong type — or a list of the wrong length — is a compile-time
+error.
 
 ## Tokens
 
-A token pairs a name with a TypeScript type. Tokens compare by reference — always reuse the same `const`.
+A token is a typed key that identifies a service. It pairs a name with a TypeScript type, and it's the identity you bind
+and resolve against. Tokens compare by reference, so declare each one once and reuse the `const`.
 
-```typescript
+```ts
 import { token } from "@codefast/di";
 
 const DbToken = token<Database>("Database");
 ```
 
-A class constructor can also be a key directly: `container.bind(UserService).toSelf()` then
-`container.resolve(UserService)`.
+A class constructor works as a key too: `container.bind(UserService).toSelf()`, then `container.resolve(UserService)`.
 
 ## Bindings
 
-Start with `container.bind(key)`, chain a strategy, then optional constraints and a scope.
-
-| Strategy                          | Produces                                                    |
-| --------------------------------- | ----------------------------------------------------------- |
-| `.toConstantValue(value)`         | A fixed value (always singleton)                            |
-| `.toSelf()` / `.to(Constructor)`  | A class instance built from `@injectable` metadata          |
-| `.toDynamic(factory)`             | Sync factory `(ctx: ResolutionContext) => Value`            |
-| `.toDynamicAsync(factory)`        | Async factory — resolve with the `*Async` container methods |
-| `.toResolved(factory, deps)`      | Factory with a typed dependency tuple, resolved in order    |
-| `.toResolvedAsync(factory, deps)` | Same, returning a `Promise`                                 |
-| `.toAlias(targetToken)`           | Redirects resolution to another token                       |
-
-```typescript
+A binding describes how the container produces a value for a token. You declare it as a chain, in one fixed order: a
+strategy (the `to*` step, which produces the value), then optional constraints, a scope, and lifecycle hooks. Only
+`container.bind(key).to*(…)` is required; everything after it is optional.
+
+| Strategy                          | Produces                                                          |
+| --------------------------------- | ----------------------------------------------------------------- |
+| `.toConstantValue(value)`         | A fixed value (always singleton)                                  |
+| `.toSelf()` / `.to(Constructor)`  | A class instance built from its `@injectable` metadata            |
+| `.toDynamic(factory)`             | A sync factory `(ctx: ResolutionContext) => Value`                |
+| `.toDynamicAsync(factory)`        | An async factory — resolve it with the `*Async` container methods |
+| `.toResolved(factory, deps)`      | A factory called with its typed dependency tuple already resolved |
+| `.toResolvedAsync(factory, deps)` | The same, returning a `Promise`                                   |
+| `.toAlias(targetToken)`           | An alias — a redirect to another token's binding                  |
+
+```ts
 container.bind(ConfigToken).toConstantValue({ dbUrl: "postgres://…" });
 
 container.bind(DbToken).toDynamicAsync(async (ctx) => {
@@ -109,75 +118,127 @@ container.bind(DbToken).toDynamicAsync(async (ctx) => {
 
 container
   .bind(UserServiceToken)
-  .toResolved((repo, config) => new UserService(repo, config), [UserRepository, ConfigToken] as const);
+  .toResolved((repo, config) => new UserService(repo, config), [UserRepository, ConfigToken]);
 ```
 
 ### Scopes
 
-| Scope          | Lifetime                                                   |
-| -------------- | ---------------------------------------------------------- |
-| `.singleton()` | One instance per root container, shared with children      |
-| `.scoped()`    | One instance per child container (request-scoped services) |
-| `.transient()` | New instance on every resolution — the default             |
+A scope determines how long an instance lives and which container owns it. The default is `transient`, so a binding with
+no scope produces a new instance every time.
+
+| Scope          | Lifetime                                                                                 |
+| -------------- | ---------------------------------------------------------------------------------------- |
+| `.singleton()` | One instance for the container that owns the binding; children resolve the same instance |
+| `.scoped()`    | One instance per child container — resolving from a container with no child scope throws |
+| `.transient()` | A new instance on every resolution — the default                                         |
 
-```typescript
+```ts
 container.bind(DbToken).toDynamic(createDb).singleton();
 container.bind(RequestContextToken).toSelf().scoped();
 ```
 
+> **Important.** Resolving a `scoped` binding from a container with no child scope throws `MissingScopeContextError`.
+> Open a scope with [`createChild()`](#child-containers) first.
+
+### Lifecycle hooks
+
+A lifecycle hook runs your code as an instance is created or torn down. `.onActivation(fn)` runs right after an instance
+is created, and may replace it; `.onDeactivation(fn)` runs when the owning container is disposed or the binding is
+unbound. Both are also available container-wide, through `container.onActivation(token, fn)` and
+`container.onDeactivation(token, fn)`:
+
+```ts
+container
+  .bind(DbToken)
+  .toDynamicAsync(connectDb)
+  .singleton()
+  .onDeactivation((db) => db.close());
+```
+
 ### Constraints
 
-Multiple bindings can share one token; a constraint picks the winner at resolution time. Named slots take a plain
-string; tagged slots take a **criterion** minted from a tag key.
+Several bindings can share one token, and a constraint decides which one a given `resolve` receives. A binding's set of
+constraints is its slot — think of a slot as a labelled variant of the token.
+
+**Named — the common case.** A named slot is keyed by a plain string. Declare it with `whenNamed`, and request it with
+`{ name }`:
 
-```typescript
+```ts
+container.bind(LoggerToken).toConstantValue(consoleLogger).whenNamed("console");
+container.bind(LoggerToken).toConstantValue(fileLogger).whenNamed("file");
+
+container.resolve(LoggerToken, { name: "file" }); // → fileLogger
+```
+
+**Tagged — for typed, collision-proof keys.** A criterion is a `[key, value]` pair. Declare the key once with
+`tag<Value>(name)`, then mint a criterion with `key.of(value)`. The bind site and the resolve site share the same typed
+key: a key declared `tag<"s3" | "gcs">` refuses any other value, so the two sites can't drift apart.
+
+```ts
 import { tag } from "@codefast/di";
 
 const Provider = tag<"s3" | "gcs">("provider");
 
-container.bind(LoggerToken).toConstantValue(fileLogger).whenNamed("file");
 container.bind(StorageToken).to(S3Storage).whenTagged(Provider.of("s3"));
-
-container.resolve(LoggerToken, { name: "file" });
-container.resolve(StorageToken, { tag: Provider.of("s3") });
+container.resolve(StorageToken, { tag: Provider.of("s3") }); // → S3Storage
 ```
 
-`tag<Value>(name)` declares the key once and types both ends: a key declared `tag<"s3" | "gcs">` refuses any other
-value, so a bind site and a resolve site cannot drift apart silently. `key.of(value)` interns, so the same value always
-yields the same criterion — which is what lets lookup compare by identity. Build a criterion by hand and it matches
-nothing.
+**How a request selects a slot.** In one line: a request matches a slot when it carries every tag the slot declares.
 
-`{ tag: criterion }` and `{ tags: [criterion] }` are the same request and take the same lookup path, on `resolve` and on
-`inject` / `optional` / `injectAll` alike. Reach for `tags` when a slot carries more than one tag:
+- Adding tags to a request makes it match more slots, not fewer — it's a superset filter.
+- When several slots match, the slot declaring more of the request's tags wins (most-specific-wins).
+- A tie between equally specific slots throws `AmbiguousBindingError`.
+- A request with no criteria selects the binding marked `.whenDefault()` — or, equivalently, the binding that declares
+  no constraint at all.
 
-```typescript
-const Env = tag<"prod" | "dev">("env");
-const Tier = tag<"premium" | "basic">("tier");
+> **Note.** `key.of(value)` interns each value: the same value always yields the same criterion object, which lets
+> lookup compare by identity. A criterion built by hand — not through `.of()` — matches nothing.
 
-container.bind(LoggerToken).toConstantValue(auditLogger).whenTagged(Env.of("prod")).whenTagged(Tier.of("premium"));
+`{ tag: criterion }` and `{ tags: [criterion] }` are the same request — for `resolve`, and for `inject`, `optional`, and
+`injectAll` alike. Chain `.whenTagged(...)` once per criterion a slot carries, and request several at once with
+`{ tags: [...] }`.
 
-container.resolve(LoggerToken, { tags: [Env.of("prod"), Tier.of("premium")] });
-```
+**Predicate constraints — graph-aware selection.** When a slot isn't enough — when you need to choose based on _who_ is
+resolving — pass a predicate to `.when(ctx => boolean)`. It runs at resolve time, after slot matching. These ready-made
+predicates ship from the root entry:
 
-A request matches a slot when it carries **every** tag that slot declares — adding tags to a request makes it match more
-slots, not fewer. When several match, the slot declaring more of them wins.
+| Predicate                            | Matches when                                           |
+| ------------------------------------ | ------------------------------------------------------ |
+| `whenParentIs(token)`                | the direct parent resolves `token`                     |
+| `whenNoParentIs(token)`              | there is no parent, or it resolves a different token   |
+| `whenAnyAncestorIs(token)`           | some ancestor resolves `token`                         |
+| `whenNoAncestorIs(token)`            | no ancestor resolves `token`                           |
+| `whenParentNamed(name)`              | the parent's slot carries that name                    |
+| `whenAnyAncestorNamed(name)`         | some ancestor's slot carries that name                 |
+| `whenParentTagged(criterion)`        | the parent's slot carries that criterion               |
+| `whenAnyAncestorTagged(criterion)`   | some ancestor's slot carries that criterion            |
+| `whenParentTaggedAll(criteria)`      | the parent's slot carries all criteria in the array    |
+| `whenAnyAncestorTaggedAll(criteria)` | some ancestor's slot carries all criteria in the array |
 
-For graph-aware selection, pass a predicate to `.when(...)` — helpers like `whenParentIs`, `whenAnyAncestorNamed`, and
-`whenParentTagged` ship from the root entry (`import { whenParentIs } from "@codefast/di"`).
+For the exact matching and most-specific-wins rules, see [`SPEC.md` → Slots and last-wins](./SPEC.md#slot-matching).
 
 ## Decorators
 
-All decorators use TC39 Stage 3 syntax. `inject()` wraps a dependency with resolve options, `optional()` resolves to
-`undefined` when unbound, and `injectAll()` collects every matching binding into an array.
+Decorators are optional: you can wire an entire app with explicit bindings and never write one. When you do reach for
+them:
+
+- `@injectable([...deps])` — declares a class's constructor dependencies, in parameter order.
+- `inject(token, options)` — wraps one dependency with slot options (`name`, `tag`, `tags`).
+- `optional(token)` — resolves to `undefined` when nothing is bound.
+- `injectAll(token)` — collects every matching binding into an array.
+- `@postConstruct()` — runs after wiring; `@preDestroy()` runs on disposal. An async `@postConstruct` needs
+  `resolveAsync`.
 
-```typescript
-import { inject, injectable, optional, postConstruct, preDestroy } from "@codefast/di";
+```ts
+import { inject, injectable, injectAll, optional, postConstruct, preDestroy } from "@codefast/di";
 
-@injectable([DbToken, optional(CacheToken)])
+@injectable([DbToken, optional(CacheToken), injectAll(PluginToken), inject(LoggerToken, { name: "audit" })])
 class UserRepository {
   constructor(
     private readonly db: Database,
-    private readonly cache?: Cache,
+    private readonly cache: Cache | undefined,
+    private readonly plugins: Array<Plugin>,
+    private readonly audit: Logger,
   ) {}
 
   @postConstruct()
@@ -192,84 +253,109 @@ class UserRepository {
 }
 ```
 
-`inject` also works as an accessor decorator for post-construction property injection:
+### Accessor injection
+
+Accessor injection sets a property from the container instead of through the constructor. `inject` doubles as an
+accessor decorator:
+
+```ts
+import { inject, injectable, runWithContainer } from "@codefast/di";
 
-```typescript
 @injectable()
 class Controller {
   @inject(LoggerToken) accessor logger!: Logger;
 }
+
+const fromContainer = container.resolve(Controller);
+const byHand = runWithContainer(container, () => new Controller());
 ```
 
-An accessor resolves from the container that is constructing the instance. When something else owns the `new` — a
-router, an ORM, a test helper — open that context yourself with `runWithContainer(container, () => new Controller())`;
-otherwise the accessor throws `MissingContainerContextError`.
+An accessor resolves from the container that's constructing the instance. When something else owns the `new` — a router,
+an ORM, a test helper — open that context with `runWithContainer`. Without one, the accessor throws
+`MissingContainerContextError`. `getActiveContainer()` reads the open context.
 
-Classes you cannot decorate (a dependency's class, generated code, plain JavaScript) are wired by supplying their
-metadata yourself:
+### Auto-registration
 
-```typescript
-const container = Container.create({ metadataReader: myReader });
-```
+To avoid binding classes one by one, let them register themselves.
+`@injectable(deps, { autoRegister: registry, scope })` records the class in a registry from
+`createAutoRegisterRegistry()`, and `container.loadAutoRegistered(registry)` binds the whole set in one call.
+
+### Custom metadata
 
-A `MetadataReader` reports constructor parameters, lifecycle method names, and `@inject` accessors; delegate misses to
-`defaultMetadataReader` so decorated classes keep working. The reader is read while the container is constructed, so the
-option — not a later `MetadataReaderToken` binding — is what resolution sees. See
-[examples/19-custom-metadata-reader](https://github.com/codefastlabs/codefast/tree/main/packages/di/examples/19-custom-metadata-reader)
-and the MetadataReader section of [SPEC.md](https://github.com/codefastlabs/codefast/blob/main/packages/di/SPEC.md).
+Some classes you can't decorate — a dependency's class, generated code, plain JavaScript. Wire them by supplying their
+metadata through a `MetadataReader`, passed as `Container.create({ metadataReader })`. A reader reports constructor
+parameters, lifecycle method names, and `@inject` accessors; delegate misses to `defaultMetadataReader` so decorated
+classes keep working. The reader is fixed when the container is created, and inherited by its children.
 
 ## Container
 
-```typescript
+```ts
 const container = Container.create();
 
 container.resolve(ServiceToken); // throws TokenNotBoundError when unbound
 container.resolveOptional(CacheToken); // undefined when unbound
 container.resolveAll(HandlerToken); // every matching binding
+container.has(ServiceToken); // true when this container or an ancestor binds it
 
 const db = await container.resolveAsync(DbToken); // required for async bindings
 ```
 
-Mixing an async binding into a sync `resolve()` throws `AsyncResolutionError` — use `resolveAsync` / `resolveAllAsync` /
-`resolveOptionalAsync` whenever the chain contains async work.
+### Sync vs async resolution
+
+The rule is simple: if anything in the chain is async, resolve with an `*Async` method. A synchronous `resolve()` that
+reaches an async factory — its own, or a dependency's — throws `AsyncResolutionError` rather than silently returning a
+`Promise`.
+
+| Sync              | Async counterpart      |
+| ----------------- | ---------------------- |
+| `resolve`         | `resolveAsync`         |
+| `resolveOptional` | `resolveOptionalAsync` |
+| `resolveAll`      | `resolveAllAsync`      |
+
+An async `@postConstruct` or `onActivation` hook needs an `*Async` resolve too; on a synchronous path, it throws
+`AsyncActivationError`. `initializeAsync()` warms every eligible singleton up front, so later `resolve()` calls stay
+synchronous.
 
 ### Child containers
 
-Children fall through to the parent's bindings and share its singleton cache, while `scoped` bindings get one instance
-per child — ideal for per-request wiring.
+A child container implements the request-scope pattern. It falls through to its parent's bindings and shares the
+parent's singletons, while each `scoped` binding gets a fresh instance per child.
 
-```typescript
-const requestContainer = container.createChild();
-const service = requestContainer.resolve(RequestScopedService);
-await requestContainer.dispose(); // releases scoped instances owned by this child
+```ts
+{
+  await using requestContainer = container.createChild();
+  requestContainer.bind(RequestIdToken).toConstantValue(crypto.randomUUID());
+  const service = requestContainer.resolve(RequestScopedService);
+} // dispose() runs here and releases what this child owns
 ```
 
 ### Validation
 
-`validate()` fails fast on captive dependencies — for example a `singleton` depending on a `scoped` or `transient`
-binding.
+A captive dependency is a long-lived binding that holds a shorter-lived one — a `singleton` that depends on a `scoped`
+or `transient` binding — which silently freezes that dependency for the singleton's whole life. `validate()` fails fast
+on captive dependencies, and on constraints no request can satisfy, before the first resolve.
 
-```typescript
+```ts
 container.validate(); // throws ScopeViolationError on the first violation
 ```
 
 ### Disposal
 
-`Container` implements `AsyncDisposable`, so `await using` runs deactivation hooks automatically:
+`Container` implements `AsyncDisposable`, so `await using` runs every deactivation hook automatically as the block
+exits. Synchronous `using` isn't supported — `onDeactivation` may be async — and `Symbol.dispose` throws
+`SyncDisposalNotSupportedError`.
 
-```typescript
-{
-  await using container = Container.create();
-  container.bind(DbToken).toDynamicAsync(connectDb).singleton().onDeactivation(disconnectDb);
-  const db = await container.resolveAsync(DbToken);
-} // dispose() runs here
-```
+### Introspection
+
+`container.inspect()` returns a `ContainerSnapshot`; `container.lookupBindings(token)` returns the snapshots of one
+token's bindings; and `container.generateDependencyGraph()` returns a JSON graph. Adapters render that graph for common
+viewers: `toDotGraph`, `toMermaidGraph`, `toCytoscapeGraph`, and `toReactFlowGraph`.
 
 ## Modules
 
-Modules bundle related bindings into reusable, stateless units.
+A module is a reusable, stateless bundle of related bindings. Group them once, then load them into any container.
 
-```typescript
+```ts
 import { Container, Module } from "@codefast/di";
 
 const InfrastructureModule = Module.create("Infra", (api) => {
@@ -284,65 +370,62 @@ const AppModule = Module.create("App", (api) => {
 const container = Container.fromModules(AppModule);
 ```
 
-`Module.createAsync` supports awaiting during setup (remote config, connections); load those with
-`Container.fromModulesAsync` or `container.loadAsync`. Modules are ref-counted: re-loading is a no-op and `unload` only
-removes bindings once the count reaches zero.
+`Module.createAsync` lets you await during setup — for remote config or connections. Load those with
+`Container.fromModulesAsync` or `container.loadAsync`. Modules are ref-counted: loading one twice counts once, and
+`unload` removes its bindings only when the count reaches zero.
 
 ## Errors
 
-Every error extends `DiError` and carries a stable `code` — `TokenNotBoundError` (`"TOKEN_NOT_BOUND"`),
-`CircularDependencyError`, `ScopeViolationError`, `AsyncResolutionError`, `AmbiguousBindingError`, and friends. Import
-them from the root or from `@codefast/di/errors/errors`.
+Every error extends `DiError` and carries a stable `code`, so you can branch on the code rather than the message:
+
+| Error                          | Code                        | Raised when                                                                |
+| ------------------------------ | --------------------------- | -------------------------------------------------------------------------- |
+| `TokenNotBoundError`           | `TOKEN_NOT_BOUND`           | No binding exists for the token in the container chain                     |
+| `NoMatchingBindingError`       | `NO_MATCHING_BINDING`       | The token has bindings but none matches the request's slot                 |
+| `AmbiguousBindingError`        | `AMBIGUOUS_BINDING`         | Several bindings match with no more-specific winner                        |
+| `CircularDependencyError`      | `CIRCULAR_DEPENDENCY`       | A cycle appears on the resolution path                                     |
+| `AsyncResolutionError`         | `ASYNC_RESOLUTION`          | A sync `resolve()` reaches an async factory                                |
+| `AsyncActivationError`         | `ASYNC_ACTIVATION`          | A `@postConstruct` or `onActivation` hook returns a promise on a sync path |
+| `ScopeViolationError`          | `SCOPE_VIOLATION`           | `validate()` finds a captive dependency                                    |
+| `MissingScopeContextError`     | `MISSING_SCOPE_CONTEXT`     | A `scoped` binding is resolved outside a child container                   |
+| `MissingContainerContextError` | `MISSING_CONTAINER_CONTEXT` | An `@inject` accessor initializes with no container open                   |
+| `DisposedContainerError`       | `DISPOSED_CONTAINER`        | A disposed container is used                                               |
+
+The full taxonomy — including `MissingMetadataError`, `InvalidMetadataError`, `RebindUnboundTokenError`,
+`AsyncModuleLoadError`, and the rest — is exported from the root entry and from `@codefast/di/errors/errors`.
 
 ## Subpath exports
 
-The root entry re-exports the full public API — prefer it
-(`import { Container, token, toReactFlowGraph } from "@codefast/di"`). Every module is also published as a
-tree-shakeable subpath mirroring the source layout:
+Prefer the root entry: it re-exports the whole public API. Reach for a subpath only to trim a bundle, or to pull in
+something the root doesn't surface.
 
-- **Model** under `/core/*` — `@codefast/di/core/token`, `/core/types`, `/core/binding`, `/core/tag`, `/core/registry`,
-  `/core/module`
-- **Errors** under `/errors/*` — `@codefast/di/errors/errors`, `/errors/diagnostics`
-- **Runtime** under `/container/*`, `/injection/*`, `/lifecycle/*` and `/resolution/*` — e.g.
-  `@codefast/di/resolution/select/constraints`
-- **Introspection** ships at flat specifiers, without the directory prefix — `@codefast/di/inspector`,
-  `/dependency-graph`, and the graph adapters (`@codefast/di/graph-adapters/{dot,cytoscape,mermaid,reactflow}`) for
-  visualizing `container.generateDependencyGraph()` output
-- **Decorators & metadata** under `/decorators/*` and `/metadata/*`
+Every module is also published as a subpath that mirrors the source layout: the model under `@codefast/di/core/*`
+(`core/token`, `core/tag`, `core/module`, …), errors under `errors/*`, the runtime under `container/*`, `injection/*`,
+`lifecycle/*`, and `resolution/*` (for example `@codefast/di/resolution/select/constraints`), and decorators and
+metadata under `decorators/*` and `metadata/*`. Introspection ships at flat specifiers: `@codefast/di/inspector`,
+`@codefast/di/dependency-graph`, and `@codefast/di/graph-adapters/{dot,mermaid,cytoscape,reactflow}`.
 
 ## Benchmarks
 
-A head-to-head benchmark suite lives in the monorepo:
-[benchmarks/di-inversify](https://github.com/codefastlabs/codefast/tree/main/benchmarks/di-inversify). It compares
-`@codefast/di` against **InversifyJS 8** on the full scenario set, plus **Awilix** and **tsyringe** on a shared core
-subset. Each library runs in its canonical mode, in isolated subprocesses, reported as per-trial medians with
-interquartile range — designed so the results are re-runnable rather than taken on faith.
-
-Against InversifyJS — the only one of the three that covers a comparable feature surface — `@codefast/di` currently wins
-**all 44 comparable scenarios** in both profiles, at a median of 2.21×–2.39× and a geometric mean of 2.68×–2.90×.
-Against the two deliberately leaner containers it wins the shared core subset as well, with one exception:
-`realistic-graph-cold-resolve` against tsyringe, which reads parity in the default profile and a loss under the
-forced-GC one. See [RESULTS.md](https://github.com/codefastlabs/codefast/blob/main/benchmarks/di-inversify/RESULTS.md)
-for the full tables, the caveats, and the losses that earlier revisions reported — or run `pnpm bench` in that package
-to reproduce them on your machine.
-
-## Learning how it works
-
-Curious how the engine is built, or want to learn from it?
-[LEARNING.md](https://github.com/codefastlabs/codefast/blob/main/packages/di/LEARNING.md) is a guided read of the real
-architectural patterns, design patterns, algorithms, TypeScript techniques, and performance work in this codebase — a
-tour of one `resolve()` call, then a catalogue by topic, each pointing at the code. For the exact behavioural contract
-see [SPEC.md](https://github.com/codefastlabs/codefast/blob/main/packages/di/SPEC.md); for the invariants the engine
-depends on see [ARCHITECTURE.md](https://github.com/codefastlabs/codefast/blob/main/packages/di/ARCHITECTURE.md).
+A first-party benchmark suite lives in the monorepo, at [`benchmarks/di-inversify`](../../benchmarks/di-inversify). It
+runs the same workloads through `@codefast/di`, InversifyJS, Awilix, and tsyringe, and its `RESULTS.md` ledger records
+the numbers alongside the method that produced them. Run it yourself rather than taking any figure on faith.
+
+## Documentation
+
+- [Rendered docs on codefastlabs.com](https://codefastlabs.com/docs/di)
+- [`SPEC.md`](./SPEC.md) — the behavioural contract: public API, semantics, and errors.
+- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — the internal shape and the invariants the hot paths depend on.
+- [`LEARNING.md`](./LEARNING.md) — a guided tour of the techniques the engine applies, pointing at the code.
+- [`examples/`](./examples/README.md) — runnable examples from basic tokens to a multi-file Ports & Adapters app.
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — the package workflow: build, exports mirror, tests, and the perf guard.
+- [`CHANGELOG.md`](./CHANGELOG.md) — release history.
 
 ## Contributing
 
-Changing this package's source?
-[CONTRIBUTING.md](https://github.com/codefastlabs/codefast/blob/main/packages/di/CONTRIBUTING.md) is the full workflow —
-build, exports mirror, tests, the mandatory perf-guard for resolver changes, and the release gate.
+See the repo-wide [contributing guide](../../CONTRIBUTING.md) for setup and conventions, and this package's
+[`CONTRIBUTING.md`](./CONTRIBUTING.md) for the resolver perf guard and the exports mirror.
 
 ## License
 
-[MIT](https://github.com/codefastlabs/codefast/blob/main/LICENSE) — part of the
-[codefast monorepo](https://github.com/codefastlabs/codefast). See
-[CHANGELOG.md](https://github.com/codefastlabs/codefast/blob/main/packages/di/CHANGELOG.md) for release history.
+Released under the [MIT License](./LICENSE).

package/dist/ambient/active-container.d.ts

@@ -37,5 +37,4 @@ export declare function getActiveContainer(): Container | undefined;
  *
  * @since 0.6.0
  */
-export declare function getAmbientResolution(): AmbientResolution | undefined;
-//# sourceMappingURL=active-container.d.ts.map
+export declare function getAmbientResolution(): AmbientResolution | undefined;

package/dist/ambient/active-container.js

@@ -41,5 +41,4 @@ export function getActiveContainer() {
  */
 export function getAmbientResolution() {
     return activeResolution;
-}
-//# sourceMappingURL=active-container.js.map
+}

package/dist/container/binding-builders.d.ts

@@ -56,5 +56,4 @@ export declare class BindingChain<Value> implements AliasBindingBuilder, Binding
     onActivation(fn: ActivationHandler<Value>): this;
     onDeactivation(fn: DeactivationHandler<Value>): this;
     id(): BindingIdentifier;
-}
-//# sourceMappingURL=binding-builders.d.ts.map
+}

package/dist/container/binding-builders.js

@@ -225,5 +225,4 @@ export class BindingChain {
             }
         }
     }
-}
-//# sourceMappingURL=binding-builders.js.map
+}

package/dist/container/container.d.ts

@@ -74,5 +74,4 @@ export interface ContainerStatic {
  *
  * @since 0.3.16-canary.0
  */
-export declare const Container: ContainerStatic;
-//# sourceMappingURL=container.d.ts.map
+export declare const Container: ContainerStatic;