di-bag 0.2.0 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,149 @@
+# DI Bag: notes for coding agents
+
+DI Bag composes TypeScript factories into a dependency graph that the compiler
+checks. Modules keep a feature's services private behind exported keys; a bag
+creates services on first use and releases what it owns when closed.
+
+This file ships in `node_modules/di-bag/`. Every call, with one way per task and an example:
+[docs/agent/api-card.md](docs/agent/api-card.md). Task recipes: [docs/agent/recipes.md](docs/agent/recipes.md).
+Every compiler and runtime message: [docs/agent/errors.md](docs/agent/errors.md).
+
+## Rules
+
+1. **Import from `di-bag`:** `import { DiBag } from 'di-bag';`. It configures
+   itself on Node, Bun, and Deno; `di-bag/node` is the same API in explicit form.
+   In browsers and workers `build()` throws
+   [`DI_BAG_CLASSIFIER_REQUIRED`](docs/agent/errors.md#di-bag-classifier-required)
+   for factories without an explicit `acquisitionMode`.
+2. **A factory declares its dependencies in the type of its one object
+   parameter; destructure it** (`({ clock }: { clock: Clock }) => ...`) or read
+   `deps.clock` directly. The object is a Proxy that resolves each property when
+   read: spreading it, `Object.keys`, `in`, and `JSON.stringify` throw
+   [`DI_BAG_INVALID_DEPENDENCY_ACCESS`](docs/agent/errors.md#di-bag-invalid-dependency-access).
+3. **Lifetimes.** The default is `scoped`: one instance per bag or child scope.
+   Mark a shared client `DiBag.withLifetime(factory, 'root')` only when nothing
+   it depends on is scoped; otherwise the compiler reports a
+   [root capture](docs/agent/errors.md#root-capture) naming both keys.
+   `'transient'` creates an instance on every read.
+4. **Async is explicit.** An async factory's service is its Promise. A consumer
+   declares `{ db: Promise<Db> }` and awaits it; nothing is awaited for you.
+5. **No thenables.** A factory that returns a non-Promise object with a `then`
+   method (query builders) is [rejected](docs/agent/errors.md#structural-thenable).
+   Return `Promise.resolve(builder)` or use `DiBag.fromFactory(create, { acquisitionMode: 'raw' })`.
+6. **Ownership.** `DiBag.withDisposal(factory, dispose)` makes the bag own the
+   value; `close()` runs disposers, dependents first. Close every scope and fork
+   you create. A parent closes its live scopes, never forks.
+7. **Replace dependencies in tests with `fork(keys, overrides)`**; each
+   override must satisfy the original contract.
+8. **Modules.** Register a feature's factories, then `buildModule(['exported'])`.
+   What its factories need and the module does not register becomes a
+   requirement: the host that calls `installModule(module)` must register it.
+   Pass `buildModule(keys, { label: 'billing' })` so messages name private
+   services `billing/store`.
+9. **Read a rejection at its name.** A graph error is an assignability error
+   whose type is `Unsatisfied<"message", details>`, reported where the builder
+   expression starts. `builder.verifyGraph() satisfies void;` reports the same
+   message on its own line; `"noErrorTruncation": true` prints the details.
+   Runtime errors carry `code` and `details`: branch on `code`, never on message
+   text. The section for a code is `docs/agent/errors.md#<code>`, lower-cased
+   with `_` replaced by `-`.
+
+## Module layout
+
+```text
+src/features/invoicing/
+  contract.ts        # exported service types and the requirements the host must supply
+  module.ts          # buildModule([...]) over the private factories
+  store.ts           # private services; free to use names other modules also use
+  check.ts           # type-checks this module alone; never imported, not built
+  tsconfig.json      # extends the root tsconfig and includes only this directory
+  invoicing.test.ts
+src/app.ts           # installs every module, one installModule call per line
+src/app.check.ts     # verifyGraph() on the application builder: the merge check
+```
+
+Inside a file, keep the same order: contract types, private factories, the
+sealed module, then the host. Exclude `check.ts` files and `src/app.check.ts`
+from an emitting build; they have no runtime purpose.
+
+A complete module:
+
+```ts
+// src/features/greeting/contract.ts
+export type Greeter = { greet(name: string): string };
+export type GreetingConfig = { greeting: string };
+```
+
+```ts
+// src/features/greeting/module.ts
+import { DiBag } from 'di-bag';
+import type { Greeter, GreetingConfig } from './contract.js';
+
+export const greetingModule = DiBag.createBuilder()
+  .register({
+    greeter: ({ config }: { config: GreetingConfig }): Greeter => ({
+      greet: name => `${config.greeting}, ${name}!`,
+    }),
+  })
+  .buildModule(['greeter']);
+```
+
+`check.ts` is one statement: install the module, register a typed fixture for
+each requirement, and verify.
+
+```ts
+// src/features/greeting/check.ts
+import { DiBag } from 'di-bag';
+import type { GreetingConfig } from './contract.js';
+import { greetingModule } from './module.js';
+
+DiBag.createBuilder()
+  .installModule(greetingModule)
+  .register({ config: (): GreetingConfig => ({ greeting: 'Hello' }) })
+  .verifyGraph() satisfies void;
+```
+
+## Check one module
+
+`src/features/<name>/tsconfig.json`:
+
+```json
+{
+  "extends": "../../../tsconfig.json",
+  "include": ["."]
+}
+```
+
+Type-check the module and its `check.ts` without the rest of the application:
+
+```sh
+npx tsc --noEmit -p src/features/<name>/tsconfig.json
+```
+
+A missing requirement fails with its key:
+`required service registrations are missing: config`.
+
+## Fast check
+
+Define `check:fast` in the consumer's `package.json` as the per-module
+type-check plus that module's tests, and run it after every edit:
+
+```json
+"check:fast": "tsc --noEmit -p src/features/$MODULE/tsconfig.json && tsx --test src/features/$MODULE/*.test.ts"
+```
+
+```sh
+MODULE=greeting npm run check:fast
+```
+
+Replace `tsx --test` with the project's test runner. Run the full type-check and
+test suite before merging: [review a merge](docs/agent/recipes.md#review-merge).
+
+## Recipes
+
+- [Add a request-scoped service with cleanup](docs/agent/recipes.md#add-scoped-service)
+- [Write a fixture test with `fork`](docs/agent/recipes.md#fixture-test)
+- [Split a feature into a module with private services](docs/agent/recipes.md#split-module)
+- [Debug a missing-dependency rejection](docs/agent/recipes.md#debug-missing-dependency)
+- [Add and consume an async client](docs/agent/recipes.md#async-client)
+- [Review a merge](docs/agent/recipes.md#review-merge)

package/README.md

@@ -1,18 +1,21 @@
 # DI Bag
 
-TypeScript dependency composition and resource ownership for agentic development, LLM harnesses, and agent graphs.
+TypeScript dependency composition and resource ownership for modular codebases,
+including the ones coding agents build one feature at a time.
 
-[Documentation](https://dany-fedorov.github.io/di-bag/) · [Quickstart](#quickstart) · [Agent harnesses](docs/guides/agent-harnesses-and-graphs.md) · [Comparison](#how-it-compares) · [Tutorial](docs/guides/tutorial.md) · [API reference](docs/guides/api-reference.md)
+[Documentation](https://dany-fedorov.github.io/di-bag/) · [Quickstart](#quickstart) · [Modules as units of work](#modules-as-units-of-work) · [Comparison](#how-it-compares) · [Tutorial](docs/guides/tutorial.md) · [API reference](docs/guides/api-reference.md)
 
 ## Why DI Bag?
 
 Compose ordinary TypeScript factories into reusable features. DI Bag checks
 declared dependencies, keeps module internals private, and manages resource
-creation and cleanup. Build services, tools, or graph nodes against explicit
-contracts, then replace their dependencies for tests.
+creation and cleanup. Build each feature against an explicit contract, test it
+with replaced dependencies, and let the compiler check the composition when
+independently developed features come together.
 
-- **[Reusable modules with private bindings](docs/guides/examples-modularity.md).**
-  Compose independently developed features without exposing their internals.
+- **[Modules a single owner can build in isolation](docs/guides/examples-modularity.md).**
+  A person or a coding agent implements one feature against its contract
+  without exposing its internals or reading another feature's source.
 - **[Compile-time wiring checks](docs/guides/examples-type-checking.md).**
   Catch missing dependencies and incompatible replacements before starting the app.
 - **[Metadata inspection without service startup](docs/guides/examples-extensibility.md).**
@@ -42,11 +45,11 @@ A **factory** creates a service. A **bag** holds those factories and gives each
 one access to the services it needs. Services are created when needed, and
 resources are cleaned up when you provide a disposer and close their bag.
 
-Use `di-bag/node` in Node or Bun. Here, `greeter` needs `config`. Its parameter
+Import from `di-bag`. Here, `greeter` needs `config`. Its parameter
 type describes that dependency, and its return value is the service it provides:
 
 ```ts
-import { DiBag } from 'di-bag/node';
+import { DiBag } from 'di-bag';
 
 const app = DiBag.createBuilder()
   .register({
@@ -100,7 +103,7 @@ An async factory provides a promise. Declare that promise in any dependent
 factory and await it where you need the value:
 
 ```ts
-import { DiBag } from 'di-bag/node';
+import { DiBag } from 'di-bag';
 
 const app = DiBag.createBuilder()
   .register({
@@ -122,7 +125,7 @@ factories keep returning ordinary values. See
 Wrap a factory with `withDisposal` to tell the bag how to release its result:
 
 ```ts
-import { DiBag } from 'di-bag/node';
+import { DiBag } from 'di-bag';
 
 const resources = DiBag.createBuilder()
   .register({
@@ -161,32 +164,37 @@ The [tutorial](docs/guides/tutorial.md) also covers modules with private service
 typed tokens, class and function adapters, optional and lazy dependencies,
 collections, startup, metadata, observers, and plugin validation.
 
-## LLM harnesses and agent graphs
-
-Compose an **LLM harness** from model clients, tools, context sources, and
-ordinary functions that serve as **agent graph** nodes.
-
-- **Explicit feature boundaries:** give each node or tool a small contract
-  and private implementation. Keep feature contracts and focused tests together;
-  select tools and context for the LLM in the harness.
-- **Contract checks and fixture tests:** check declared wiring before a model call,
-  then fork the composition with typed model and tool fixtures for deterministic
-  behavioral tests. Keep live-model evals for quality and task success.
-- **Inspectable capability descriptions:** describe public nodes and tools next
-  to their factories. Inspect that metadata without creating services, and use
-  it in application-defined catalogs, diagnostics, or dispatch policies.
-
-DI Bag's dependency graph describes how services are supplied. The agent graph
-describes execution: which node runs next and what state it receives. Your
-harness or graph framework owns routing, retries, persistence, and execution;
-DI Bag supplies checked composition and resource ownership.
-
-The [agent harness and graph guide](docs/guides/agent-harnesses-and-graphs.md)
-combines private feature modules, an LLM-backed node, metadata inspection, and
-fork-based fixture tests in one runnable example. `inspectGraph()` lists every
-binding and the edges observed at runtime; declared edges come from the static
-graph tool. Observers track acquisition, not ordinary node calls. Use your graph
-framework for workflow checkpoints.
+## Modules as units of work
+
+A DI Bag **module** is the unit of work that one person or one coding agent can
+own: a directory with a small exported contract, private services, and its own
+tests. The composition is checked when the modules meet, so several modules can
+be developed in parallel and merged with confidence.
+
+- **A boundary an owner can hold.** `buildModule(keys)` seals a feature and
+  exports only the named services. Private services and their types stay
+  inside, and two modules can use the same private names without collision.
+- **Verification without the whole application.** A module type-checks
+  against the contracts it declares. `fork()` replaces its external
+  dependencies with typed fixtures for deterministic tests, so a module's tests
+  need neither the other modules nor live clients.
+- **Checks at merge time.** Installing every module into one builder is where
+  independently developed work meets. A missing requirement, an incompatible
+  replacement, or a contract that no longer matches its consumers fails at
+  `build()` or `verifyGraph()`. The `di-bag-graph` tool exports the declared
+  edges and cycles for review.
+
+For discovery, the directory layout is the map: one directory per module, the
+contract first. The [modularity guide](docs/guides/examples-modularity.md)
+describes the recommended layout and shows separately owned features, isolated
+tests, and contributed tools in three runnable programs.
+
+DI Bag's dependency graph describes how services are supplied, not what runs
+next. LLM harnesses and agent graphs are one application of the module pattern:
+model clients, tools, and context sources become modules, and the harness or
+graph framework owns routing, retries, persistence, and execution. The
+[agent harness and graph guide](docs/guides/agent-harnesses-and-graphs.md) is a
+complete example.
 
 ## How it compares
 
@@ -213,12 +221,13 @@ The package has **zero runtime dependencies** and two entry points:
 
 | Import | Purpose |
 | --- | --- |
-| `di-bag/node` | Ready-to-use factory composition in Node and Bun, with native Promise detection. |
-| `di-bag` | Portable core for other hosts, including Deno and bundled browsers. Use explicit acquisition modes or configure a trusted native Promise predicate. |
+| `di-bag` | The entry to use. Configures native Promise detection itself on Node, Bun, and Deno through `process.getBuiltinModule`; has no `node:` imports, so it also bundles for browsers. |
+| `di-bag/node` | The same API with detection configured explicitly at import, for Node and Bun. |
 
-The portable entry rejects automatic acquisition stages unless you configure a
-trusted classifier. See [portable mode](docs/guides/tutorial.md#portable-mode)
-for both setup options.
+On hosts without `process.getBuiltinModule` (browsers, workers), `build()`
+rejects automatic acquisition stages unless you configure a trusted classifier
+or give each stage an explicit acquisition mode. See
+[portable mode](docs/guides/tutorial.md#portable-mode) for both options.
 
 ## Tradeoffs and limits
 
@@ -226,11 +235,13 @@ for both setup options.
   boundaries, manage an agent's context window, or replace behavioral tests.
 - **Async dependencies are explicit.** A factory returning `Promise<T>` exposes
   that promise. Consumers declare and await it themselves.
-- **Cleanup waits for your work.** Cancellation is cooperative; a factory or
-  disposer that never settles can keep `close()` pending.
+- **Cleanup waits for your work by default.** Cancellation is cooperative; a
+  factory or disposer that never settles keeps `close()` pending. Pass
+  `close({ timeoutMs, signal })` to stop waiting: the rejection names the
+  disposers still running and cleanup continues in the background.
 - **Type safety follows the declared graph.** Casts, unchecked JavaScript, and
   unknown plugins need appropriate runtime checks. Dependency cycles are detected
-  at runtime.
+  at runtime, or before running by [`di-bag-graph`](tools/graph/README.md).
 - **Graph types have a compiler cost.** Very long fluent expressions can exceed
   compiler limits. Classic TypeScript still fails the recorded 1,000-call named
   registration and replacement cases; use bulk registration or smaller groups.
@@ -246,8 +257,10 @@ for both setup options.
 | [Complete tutorial](docs/guides/tutorial.md) | Learn every public API through examples, from first composition to advanced ownership. |
 | [API reference](docs/guides/api-reference.md) | Exact generated signatures, overloads, type parameters, and API inventories. |
 | [Server guide](docs/guides/server-integration.md) | Node HTTP, Express, Fastify, Bun, and Deno: shared services, request scopes, startup, and shutdown. |
-| [Agent harnesses and graphs](docs/guides/agent-harnesses-and-graphs.md) | Compose model and tool dependencies, inspect metadata, and test nodes with typed fixtures. |
-| [Static dependency graph](docs/guides/agent-harnesses-and-graphs.md#export-the-declared-dependency-graph) | Export every builder chain, declared edge, and cycle to JSON with `di-bag-graph`. |
+| [Radical modularity](docs/guides/examples-modularity.md) | The recommended module layout, separately owned features, isolated tests, and contributed tools. |
+| [Agent docs](AGENTS.md) | Rules, module layout, and check commands for coding agents, with [recipes](docs/agent/recipes.md) and [errors](docs/agent/errors.md). Shipped in the package. |
+| [Agent harnesses and graphs](docs/guides/agent-harnesses-and-graphs.md) | One worked application: model and tool modules, metadata inspection, and node tests with typed fixtures. |
+| [Static dependency graph](docs/agent/recipes.md#review-merge) | Export every builder chain, declared edge, and cycle to JSON with `di-bag-graph` for merge review and CI. |
 | [Runnable examples](examples) | Modules, tokens, composition, collections, plugins, observers, scopes, and provider metadata. |
 | [Integration guide](docs/guides/enterprise-integration.md) | Tested recipes for request ownership, substitutions, and dynamic features. |
 | [Comparison with alternatives](docs/guides/comparison.md) | When DI Bag or another approach may be a better fit, with primary sources. |

package/dist/acquisition-context.d.ts

@@ -2,13 +2,19 @@ import type { Provider } from './provider';
 import type { Factory } from './registration';
 import type { Acquired, AcquisitionMode, AutoOutput, NativeOutput, ModeOptions } from './acquisition-mode';
 import type { TokenDependencyContract } from './token-types';
-/** Cooperative cancellation information supplied to a context-aware acquisition. */
+/**
+ * Cooperative cancellation information supplied to a context-aware acquisition.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#start-selected-services-and-cancel-cooperatively
+ */
 export interface AcquisitionContext {
     /** Aborted when the acquisition's owning scope begins closing. */
     readonly signal: AbortSignal;
 }
 type ContextFactory = (this: void, deps: never, context: AcquisitionContext) => unknown;
-/** The named-dependency factory contract retained by an acquisition-context callback. */
+/**
+ * The named-dependency factory contract retained by an acquisition-context callback.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#start-selected-services-and-cancel-cooperatively
+ */
 export type ContextualFactory<F extends ContextFactory> = (this: void, deps: Parameters<F> extends [] ? {} : Parameters<F>[0]) => ReturnType<F>;
 type FactoryOptions<M extends AcquisitionMode> = 'auto' extends M ? [options?: {
     readonly context?: never;

package/dist/acquisition-mode.d.ts

@@ -1,11 +1,15 @@
 import type { LifecycleObservers } from './observers';
-import type { StructuralThenable, Unsatisfied } from './types';
+import type { SeeErrors, StructuralThenable, Unsatisfied } from './types';
 /**
  * How an acquisition stage treats its returned value: configured classification,
  * the exact raw value, or an observed native Promise fulfillment.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#portable-mode
  */
 export type AcquisitionMode = 'auto' | 'raw' | 'nativePromise';
-/** Portable facade configuration for `auto` acquisition stages. */
+/**
+ * Portable facade configuration for `auto` acquisition stages.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#portable-mode
+ */
 export interface RuntimeOptions {
     /** Return true only for native Promises the host can observe without thenable assimilation. */
     readonly isNativePromise: (this: void, value: unknown) => boolean;
@@ -29,8 +33,9 @@ export type StageOptions<M extends AcquisitionMode> = 'auto' extends M ? [option
 }];
 export type NativeOutput<O, M extends AcquisitionMode> = 'nativePromise' extends M ? [O] extends [Promise<unknown>] ? unknown : Unsatisfied<'nativePromise acquisition requires a Promise output', {}> : unknown;
 /** Reject a structural thenable output when the stage would classify it automatically. */
-export type AutoOutput<O, M extends AcquisitionMode> = 'auto' extends M ? true extends StructuralThenable<O> ? Unsatisfied<'factory output is a structural thenable; return a native Promise or select acquisitionMode raw or nativePromise', {}> : unknown : unknown;
+export type AutoOutput<O, M extends AcquisitionMode> = 'auto' extends M ? true extends StructuralThenable<O> ? Unsatisfied<`factory output is a structural thenable; return a native Promise or select acquisitionMode raw or nativePromise${SeeErrors<'structural-thenable'>}`, {}> : unknown : unknown;
 export declare function acquisitionMode(options: {
     readonly acquisitionMode?: AcquisitionMode;
 } | undefined, fallback?: AcquisitionMode): AcquisitionMode;
-export declare function requireClassificationCapability(modes: Iterable<AcquisitionMode>, context: RuntimeContext): void;
+/** Resolve the classifier when a graph first needs one; a configured classifier always wins. */
+export declare function requireClassifier(context: RuntimeContext): RuntimeContext;

package/dist/acquisition-mode.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.unconfigured = void 0;
 exports.runtimeContext = runtimeContext;
 exports.acquisitionMode = acquisitionMode;
-exports.requireClassificationCapability = requireClassificationCapability;
+exports.requireClassifier = requireClassifier;
 const errors_1 = require("./errors");
 exports.unconfigured = Object.freeze({});
 function runtimeContext(options, previous = exports.unconfigured) {
@@ -25,11 +25,29 @@ function acquisitionMode(options, fallback = 'auto') {
         throw (0, errors_1.libraryError)('DI_BAG_INVALID_ACQUISITION_MODE', 'invalid acquisitionMode: use auto, raw, or nativePromise', { option: 'acquisitionMode' });
     return mode;
 }
-function requireClassificationCapability(modes, context) {
+/**
+ * Read the host classifier through `process.getBuiltinModule` (Node, Bun, Deno). A call, not an
+ * import, keeps `node:` specifiers out of the root entry's module graph for bundlers and browsers.
+ */
+function hostClassifier() {
+    const host = globalThis.process;
+    if (typeof host !== 'object' || host === null)
+        return undefined;
+    const load = host.getBuiltinModule;
+    if (typeof load !== 'function')
+        return undefined;
+    const types = Reflect.apply(load, host, ['node:util/types']);
+    if (typeof types !== 'object' || types === null)
+        return undefined;
+    const { isPromise } = types;
+    return typeof isPromise === 'function' ? isPromise : undefined;
+}
+/** Resolve the classifier when a graph first needs one; a configured classifier always wins. */
+function requireClassifier(context) {
     if (context.isNativePromise)
-        return;
-    for (const mode of modes)
-        if (mode === 'auto') {
-            throw (0, errors_1.libraryError)('DI_BAG_CLASSIFIER_REQUIRED', 'Automatic acquisition classification requires DiBag.withConfiguration({ runtime }), di-bag/node, or explicit acquisitionMode options', { option: 'runtime.isNativePromise' });
-        }
+        return context;
+    const isNativePromise = hostClassifier();
+    if (isNativePromise)
+        return Object.freeze({ ...context, isNativePromise });
+    throw (0, errors_1.libraryError)('DI_BAG_CLASSIFIER_REQUIRED', 'this host has no process.getBuiltinModule; configure DiBag.withConfiguration({ runtime: { isNativePromise } }) or give each automatic registration an explicit acquisitionMode', { option: 'runtime.isNativePromise' });
 }

package/dist/acquisition.d.ts

@@ -39,6 +39,8 @@ export declare class ScopeAcquisitions {
     private assertAliasPath;
     assertOpen(): void;
     close(beforeDispose?: Promise<void>, cause?: unknown): Promise<void>;
+    /** Labels of this scope's running disposers and of acquisitions close is still draining. */
+    collectProgress(pending: string[], acquiring: string[]): void;
     private getContext;
     private resolveBinding;
     private eventFields;

package/dist/acquisition.js

@@ -138,6 +138,15 @@ class ScopeAcquisitions {
         });
         return this.closing;
     }
+    /** Labels of this scope's running disposers and of acquisitions close is still draining. */
+    collectProgress(pending, acquiring) {
+        for (const attempt of this.attempts.values()) {
+            if (attempt.state === 'disposing' || this.retired.has(attempt.id))
+                pending.push(attempt.label);
+            else if (attempt.state === 'creating' || attempt.state === 'pending')
+                acquiring.push(attempt.label);
+        }
+    }
     getContext() {
         if (!this.acquisitionContext) {
             this.controller = new AbortController();

package/dist/alias-types.d.ts

@@ -6,14 +6,23 @@ import type { Singleton, Unsatisfied } from './types';
 export type AliasSelection = string | TokenBase;
 export type AliasAdmission<T> = Singleton<T> extends true ? unknown : ValidToken<T> extends true ? unknown : Unsatisfied<'alias requires one singleton name or genuine token', {}>;
 export type AliasTarget<R extends Registrations, T> = T extends string ? T extends keyof R ? unknown : Unsatisfied<'alias requires an existing named target', {}> : [WrongToken<T, R>] extends [never] ? unknown : Unsatisfied<'token dependency has an incompatible or opaque contract', {}>;
-/** Resolve the service type exposed by a possible alias target. */
+/**
+ * Resolve the service type exposed by a possible alias target.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#give-a-dependency-another-lookup-name
+ */
 export type AliasOutput<R extends Registrations, T> = T extends string ? T extends keyof R ? ProviderOutput<R[T]> : never : TokenService<T>;
 export type AliasDestination<R extends Registrations, D, T> = D extends TokenBase ? [AliasOutput<R, T>] extends [TokenService<D>] ? unknown : Unsatisfied<'alias output is not assignable to destination service', {}> : unknown;
-/** A provider contract that forwards a destination to a canonical target acquisition. */
+/**
+ * A provider contract that forwards a destination to a canonical target acquisition.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#give-a-dependency-another-lookup-name
+ */
 export type AliasRegistration<R extends Registrations, D, T> = Provider<(this: void, deps: T extends string ? Record<T, AliasOutput<R, T>> : Record<never, never>) => AliasOutput<R, T>, Readonly<object>, readonly unknown[], TokenDependencyContract<T extends TokenBase ? readonly [T] : readonly [], D extends TokenBase ? D : never> & {
     readonly alias: SelectionKey<T>;
 }, unknown>;
-/** The single registration-map entry introduced by an alias operation. */
+/**
+ * The single registration-map entry introduced by an alias operation.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#give-a-dependency-another-lookup-name
+ */
 export type AliasEntries<R extends Registrations, D, T> = Record<SelectionKey<D>, AliasRegistration<R, D, T>>;
 /** Reflected generic methods cannot introduce a checked singleton destination. */
 export type AliasEntry<R extends Registrations, D, T> = unknown extends AliasAdmission<D> & AliasAdmission<T> ? {

package/dist/composition-report.d.ts

@@ -1,13 +1,14 @@
 import type { Builder } from './di-bag';
 import type { CheckedLifetimes } from './lifetime-types';
 import type { CheckedConstraints, CompleteConstraints, NeedConstraint } from './module-types';
-import type { CheckDependencyCompatibility, CheckDependencyCompleteness, Entry, RegistrationsFromEntries } from './types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, ConsumerReport, Entry, RegistrationsFromEntries } from './types';
 type ReportOf<Check> = unknown extends Check ? never : Check;
-type Reports<E extends Entry, C extends NeedConstraint> = ReportOf<CheckDependencyCompatibility<RegistrationsFromEntries<E>>> | ReportOf<CheckDependencyCompleteness<RegistrationsFromEntries<E>>> | ReportOf<CheckedConstraints<C, RegistrationsFromEntries<E>>> | ReportOf<CompleteConstraints<C, RegistrationsFromEntries<E>>> | ReportOf<CheckedLifetimes<RegistrationsFromEntries<E>, C>>;
+type Reports<E extends Entry, C extends NeedConstraint> = ReportOf<ConsumerReport<CheckDependencyCompatibility<RegistrationsFromEntries<E>>>> | ReportOf<CheckDependencyCompleteness<RegistrationsFromEntries<E>>> | ReportOf<ConsumerReport<CheckedConstraints<C, RegistrationsFromEntries<E>>>> | ReportOf<CompleteConstraints<C, RegistrationsFromEntries<E>>> | ReportOf<CheckedLifetimes<RegistrationsFromEntries<E>, C>>;
 /**
  * The compile-time verdict for a builder: `void` when `build()` would be accepted,
  * otherwise the same failure `build()` reports, including its details.
  * Read it through `builder.verifyGraph() satisfies void;` or as `CompositionReport<typeof builder>`.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#read-compile-time-rejections
  */
 export type CompositionReport<B> = B extends Builder<infer E, infer C> ? [Reports<E, C>] extends [never] ? void : Reports<E, C> : never;
 export {};

package/dist/composition.d.ts

@@ -4,12 +4,18 @@ import type { DependencyReference } from './dependency-references';
 import type { TokenArguments, ReferenceGraph, DependencyTupleAdmission } from './token-types';
 import type { Unsatisfied } from './types';
 type OutputFactory<O> = () => O;
-/** Compile-time admission that checks supplied token values against a callable's parameter tuple. */
+/**
+ * Compile-time admission that checks supplied token values against a callable's parameter tuple.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#adapt-classes-and-positional-functions
+ */
 export type CompositionArguments<A extends readonly unknown[], P extends readonly unknown[]> = [A] extends [P] ? unknown : Unsatisfied<'composition arguments must match the declared parameter tuple', {
     supplied: A;
     parameters: P;
 }>;
-/** A receiver-free positional callback matching the values supplied by a dependency tuple. */
+/**
+ * A receiver-free positional callback matching the values supplied by a dependency tuple.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#adapt-classes-and-positional-functions
+ */
 export type CompositionFunction<T extends readonly DependencyReference[], O = unknown> = TokenArguments<T> extends [...infer A] ? (this: void, ...args: A) => O : never;
 /**
  * Adapt a positional function without awaiting its arguments or return value.

package/dist/contribution-types.d.ts

@@ -1,21 +1,25 @@
 import type { Registration, Registrations } from './registration';
 import type { TokenBase, TokenKey, TokenService } from './tokens';
 import type { ValidToken, TokenTupleAdmission, BindingOutput } from './token-types';
-import type { CheckDependencyCompatibility, CheckDependencyCompleteness, Unsatisfied, Entry, RegistrationsFromEntries } from './types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, SeeErrors, Unsatisfied, Entry, RegistrationsFromEntries } from './types';
 import type { ProviderCollectionTokens } from './provider';
 import type { Module } from './module';
 import type { RegistrationConstraints, PublicProvider, NeedConstraint, CheckedConstraints } from './module-types';
-import type { LexicalContext, ModuleScope, Enclosed, RenamedContext } from './lifetime-types';
 declare const contributionSite: unique symbol;
-/** Each union member retains one independently checked provider and its group. */
-export type Contribution<T extends TokenBase = TokenBase, V extends Registration = Registration, L = undefined> = {
+/**
+ * Each union member retains one independently checked provider and its group.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
+export type Contribution<T extends TokenBase = TokenBase, V extends Registration = Registration> = {
     readonly kind: 'contribution';
     readonly token: T;
     readonly registration: V;
-    readonly context: L;
 };
-/** The erased contribution contract retained by checked builders and modules. */
-export type ContributionConstraint = Contribution<TokenBase, Registration, unknown>;
+/**
+ * The erased contribution contract retained by checked builders and modules.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
+export type ContributionConstraint = Contribution<TokenBase, Registration>;
 type Groups<C> = Extract<C, ContributionConstraint>;
 type Same<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false;
 type WrongMember<T, G> = G extends ContributionConstraint ? TokenKey<T> extends TokenKey<G['token']> ? Same<T, G['token']> extends true ? never : TokenKey<T> : never : never;
@@ -33,25 +37,29 @@ type AllNeeds<C, A extends Registrations> = ProviderCollectionTokens<A[keyof A]>
     token: infer T;
 } ? T : never);
 type GroupErrors<C, A extends Registrations> = WrongGroup<Groups<C>['token'] | AllNeeds<C, A>, C>;
-export type CheckedContributions<C, A extends Registrations> = [Groups<C>] extends [never] ? unknown : [GroupErrors<C, A>] extends [never] ? [WrongProvider<C, A>] extends [never] ? unknown : Unsatisfied<'contribution service is incompatible with its consumer dependency contract', {
+export type CheckedContributions<C, A extends Registrations> = [Groups<C>] extends [never] ? unknown : [GroupErrors<C, A>] extends [never] ? [WrongProvider<C, A>] extends [never] ? unknown : Unsatisfied<`contribution service is incompatible with its consumer dependency contract${SeeErrors<'unsatisfied-consumer'>}`, {
     readonly failures: ContributionFailures<WrongProvider<C, A>, A>;
 }> : Unsatisfied<'collection token has an incompatible or opaque contract', {}>;
-export type CompleteContributions<C, A extends Registrations> = [MissingProvider<C, A>] extends [never] ? unknown : Unsatisfied<'required service registrations are missing', {
+export type CompleteContributions<C, A extends Registrations> = [MissingProvider<C, A>] extends [never] ? unknown : Unsatisfied<`required service registrations are missing${SeeErrors<'missing-service'>}`, {
     readonly contributions: MissingProvider<C, A>;
 }>;
 /**
- * Retain a contribution's provider checks and lexical private-service context when
- * its builder seals. A contribution retained from an inner installation is already
- * projected; sealing only encloses its scope in this module's scope.
+ * Retain a contribution's projected provider and its checked needs when its builder seals.
+ * Lifetime reach is retained separately as compact obligations. A contribution retained
+ * from an inner installation is already projected and has no needs left to re-scope.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
+export type ModuleContributionConstraints<C, R extends Registrations, P extends keyof R> = C extends ContributionConstraint ? Contribution<C['token'], PublicProvider<C['registration']>> | RegistrationConstraints<C['registration'], R, P> : never;
+/**
+ * Project a module's typed-token collections as readonly service arrays.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
  */
-export type ModuleContributionConstraints<C, R extends Registrations, P extends keyof R> = C extends ContributionConstraint ? C['context'] extends LexicalContext ? Contribution<C['token'], C['registration'], Enclosed<C['context'], ModuleScope<R, P>>> : Contribution<C['token'], PublicProvider<C['registration']>, ModuleScope<R, P> & {
-    readonly registration: C['registration'];
-}> | RegistrationConstraints<C['registration'], R, P> : never;
-export type RenamedContribution<C extends ContributionConstraint, Old extends string, New extends string> = C['context'] extends LexicalContext ? Contribution<C['token'], C['registration'], RenamedContext<C['context'], Old, New>> : C;
-/** Project a module's typed-token collections as readonly service arrays. */
 export type ModuleContributions<M> = M extends Module<infer _P, infer _R, infer C, infer _D> ? Readonly<{
     [T in Groups<C>['token'] as TokenKey<T>]: ReadonlyArray<TokenService<T>>;
 }> : never;
-/** The checked generic `contribute` callable exposed by a builder. */
+/**
+ * The checked generic `contribute` callable exposed by a builder.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
 export type BuilderContribute<E extends Entry, C extends NeedConstraint> = <T extends TokenBase, V extends Registration>(token: T & TokenTupleAdmission<readonly [T]>, registration: V & Registration & BindingOutput<NoInfer<T>, NoInfer<V>> & CheckedConstraints<C | Contribution<NoInfer<T>, NoInfer<V>>, RegistrationsFromEntries<E>>, ...invalid: [T] extends [never] ? [never] : [V] extends [never] ? [never] : []) => import('./di-bag').Builder<E, C | Contribution<T, V>>;
 export {};