katagami 3.0.0 → 3.0.2

package/README.md

@@ -2,618 +2,174 @@
 
 # Katagami
 
-Lightweight TypeScript DI container with full type inference.
+**Type-safe dependency injection for TypeScript.**
+
+Make dependency wiring explicit and type-checked—even when AI coding agents write the code.
+Katagami accumulates types as you register dependencies, checks which tokens a factory can access,
+and tracks asynchronous results. No decorators, no reflect-metadata, no runtime dependencies.
 
 [![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+[![CI](https://github.com/hiroiku/katagami/actions/workflows/ci.yml/badge.svg)](https://github.com/hiroiku/katagami/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/katagami)](https://github.com/hiroiku/katagami/blob/master/LICENSE)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/katagami)](https://bundlephobia.com/package/katagami)
-
-> The name comes from 型紙 _(katagami)_ — precision stencil paper used in traditional Japanese dyeing to transfer exact patterns onto fabric. Multiple stencils are layered to compose intricate designs, just as types accumulate through each method-chain call. Each stencil is a self-contained piece — chosen only for the current work, the rest left behind — just as subpath exports ensure only the code you use enters your bundle. The cut pattern determines exactly where dye passes and where it is blocked, much like Katagami's type system catches misuse at compile time, not at runtime. And a stencil needs only paper and a brush, no elaborate machinery — likewise, Katagami requires no decorators or metadata mechanisms and works with any build tool out of the box.
-
-## Features
-
-| Feature                       | Description                                                                                               |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Zero dependencies             | No decorators, no reflect-metadata, no polyfills — works with any bundler out of the box                  |
-| Full type inference           | Types accumulate through method chaining; unregistered tokens are compile-time errors                     |
-| Tree-shakeable                | Subpath exports (`katagami/disposable`, `katagami/lazy`) and `sideEffects: false` for minimal bundle size |
-| Captive dependency prevention | Singleton/Transient factories cannot access scoped tokens; caught at compile time and runtime in scopes   |
-| Hybrid token strategy         | Class tokens for strict type safety, PropertyKey tokens for flexibility                                   |
-| Interface type map            | Pass an interface to `createContainer<T>()` for order-independent registration                            |
-| Three lifetimes               | Singleton, Transient, and Scoped with child containers                                                    |
-| Disposable support            | TC39 Explicit Resource Management (`Symbol.dispose` / `Symbol.asyncDispose` / `await using`)              |
-| Module composition            | Containers can be composed via `use()` to group and reuse registrations                                   |
-| Async factories               | Promise-returning factories are automatically tracked by the type system                                  |
-| Circular dependency detection | Clear error messages with the full cycle path                                                             |
-| Optional resolution           | `tryResolve` returns `undefined` for unregistered tokens instead of throwing                              |
-| Lazy resolution               | Proxy-based deferred instantiation via `lazy()` from `katagami/lazy`; instance created on first access    |
-
-## Install
-
-```bash
-npm install katagami
-```
-
-## Quick Start
-
-```ts
-import { createContainer, createScope } from 'katagami';
-
-class Logger {
-	log(msg: string) {
-		console.log(msg);
-	}
-}
-
-class UserService {
-	constructor(private logger: Logger) {}
-	greet(name: string) {
-		this.logger.log(`Hello, ${name}`);
-	}
-}
-
-const container = createContainer()
-	.registerSingleton(Logger, () => new Logger())
-	.registerSingleton(UserService, r => new UserService(r.resolve(Logger)));
-
-const userService = createScope(container).resolve(UserService);
-//    ^? UserService (fully inferred)
-userService.greet('world');
-```
-
-## Why Katagami
-
-Most TypeScript DI containers rely on decorators, reflect-metadata, or string-based tokens — each bringing trade-offs in tooling compatibility, type safety, or bundle size. Katagami takes a different approach.
-
-> **Note:** This comparison was researched on 2026-02-09. Features may have changed since then.
-
-| Aspect                            | Katagami                                                         | InversifyJS                      | tsyringe                                        | TypeDI                                  | Awilix                              | NestJS                                | Effect                            | typed-inject                   |
-| --------------------------------- | ---------------------------------------------------------------- | -------------------------------- | ----------------------------------------------- | --------------------------------------- | ----------------------------------- | ------------------------------------- | --------------------------------- | ------------------------------ |
-| **Runtime requirements**          | ✅ None                                                          | ❌ reflect-metadata, decorators  | ❌ reflect-metadata, decorators                 | ❌ reflect-metadata, decorators         | ✅ None                             | ❌ reflect-metadata, decorators       | ✅ None                           | ✅ None                        |
-| **Lifetimes**                     | ✅ Singleton, Transient, Scoped                                  | ✅ Singleton, Transient, Request | ✅ Singleton, Transient, Resolution / Container | Singleton, Transient (named containers) | ✅ Singleton, Transient, Scoped     | ✅ Singleton, Transient, Request      | Shared (memoized), Scoped         | ❌ Singleton, Transient        |
-| **Injection style**               | Constructor (explicit factory)                                   | Constructor, Property            | Constructor                                     | Constructor, Property                   | Constructor (proxy / classic)       | Constructor                           | Functional (Tag + Layer)          | Constructor (static inject)    |
-| **Token types**                   | Class, PropertyKey, Interface map                                | Class, String, Symbol            | Class, String, Symbol                           | Class, String, Token\<T\>               | String                              | Class, String, Symbol, InjectionToken | Context.Tag                       | String literal                 |
-| **Type safety**                   | ✅ Compile-time; full inference, captive-dep guard (+ runtime)   | ❌ Generic binding types         | ❌ Generic types                                | ❌ Generic types, Token\<T\>            | ❌ Cradle interface typing          | ❌ Generic types                      | ✅ Compile-time; R type parameter | ✅ Compile-time; static inject |
-| **Resource cleanup**              | ✅ TC39 Symbol.dispose / asyncDispose; await using               | Deactivation handlers            | container.dispose()                             | Container.reset()                       | Disposer functions                  | Lifecycle hooks (onModuleDestroy)     | Scope finalizers; acquireRelease  | injector.dispose()             |
-| **Tree-shaking**                  | ✅ Subpath exports; sideEffects: false                           | ❌                               | ❌                                              | ❌                                      | ✅ No decorator / metadata overhead | ❌                                    | ✅ Subpath exports; ESM           | ✅ Zero deps; small bundle     |
-| **Async factories**               | ✅                                                               | ✅                               | ❌                                              | ❌                                      | ❌                                  | ✅                                    | ✅                                | ❌                             |
-| **Optional resolution**           | ✅                                                               | ✅                               | ✅                                              | ✅                                      | ✅                                  | ✅                                    | ✅                                | ❌                             |
-| **Multi-binding**                 | ✅                                                               | ✅                               | ✅                                              | ✅                                      | ❌                                  | ❌                                    | ❌                                | ❌                             |
-| **Lazy resolution**               | ✅                                                               | ✅                               | ✅                                              | ❌                                      | ✅                                  | ✅ LazyModuleLoader                   | ✅ Lazy by design                 | ❌                             |
-| **Conditional bindings**          | ✅ Token separation + factory logic + scopes                     | ✅ Named, tagged, contextual     | ❌                                              | ❌                                      | ❌                                  | ❌                                    | ❌                                | ❌                             |
-| **Auto-loading**                  | ✅ use() module composition (explicit, decorator-free by design) | ✅                               | ❌                                              | ❌                                      | ✅                                  | ❌                                    | ❌                                | ❌                             |
-| **Child containers**              | ✅                                                               | ✅                               | ✅                                              | ✅                                      | ✅                                  | ✅                                    | ✅                                | ✅                             |
-| **Module system**                 | ✅                                                               | ✅                               | ❌                                              | ❌                                      | ✅                                  | ✅                                    | ✅                                | ❌                             |
-| **Circular dependency detection** | ✅                                                               | ✅                               | ✅                                              | ❌                                      | ✅                                  | ✅                                    | ✅                                | ❌                             |
-| **Middleware / Interceptors**     | ✅ Higher-order factory wrappers                                 | ✅                               | ✅                                              | ❌                                      | ❌                                  | ❌                                    | ❌                                | ❌                             |
-| **Snapshot / Restore**            | ✅ Immutable containers; use() for test isolation                | ✅                               | ❌                                              | ❌                                      | ❌                                  | ❌                                    | ❌                                | ❌                             |
-
-### No decorators, no reflect-metadata
-
-Decorator-based DI requires `experimentalDecorators` and `emitDecoratorMetadata` compiler options. Modern build tools such as esbuild and Vite (default configuration) do not support `emitDecoratorMetadata`, and the TC39 standard decorators proposal does not include an equivalent for automatic type metadata emission. Katagami depends on none of these — it works with any build tool out of the box.
-
-### Tree-shakeable
 
-Katagami is split into subpath exports. Import only what you use — `katagami/disposable` and `katagami/lazy` are completely eliminated from the bundle if not imported. Combined with `sideEffects: false`, bundlers can remove every unused byte.
-
-```ts
-// Core only — disposable and lazy are not included in the bundle
-import { createContainer, createScope } from 'katagami';
-
-// Import only what you need
-import { disposable } from 'katagami/disposable';
-import { lazy } from 'katagami/lazy';
+```sh
+npm install katagami
 ```
 
-### Full type inference from class tokens
-
-String-token DI forces you to maintain manual token-to-type mappings. Parameter-name matching breaks under minification. Katagami uses classes directly as tokens, so `resolve` automatically infers the correct return type — synchronous or `Promise` — with no extra annotations.
-
-### Method-chain type accumulation
-
-Types accumulate with each `register` call. Inside a factory, the resolver only accepts tokens that have already been registered at that point in the chain. Resolving an unregistered token is a compile-time error, not a runtime surprise.
-
-### Hybrid token strategy
-
-Class tokens give you strict, order-dependent type safety through method chaining. But sometimes you want to define a set of services upfront and register them in any order. Pass an interface to `createContainer<T>()` and use PropertyKey tokens — the type map is fixed at creation time, so registration order does not matter.
-
-### Zero dependencies
-
-No runtime dependencies, no polyfills. No need to add reflect-metadata (~50 KB unminified) to your bundle.
-
-## Guide
-
-### Singleton & Transient
-
-Singleton creates the instance on the first `resolve` and caches it. Transient creates a new instance every time.
+## Quick start
 
 ```ts
 import { createContainer, createScope } from 'katagami';
 
-class Database {
-	constructor(public id = Math.random()) {}
-}
-
-class RequestHandler {
-	constructor(public id = Math.random()) {}
-}
-
 const container = createContainer()
-	.registerSingleton(Database, () => new Database())
-	.registerTransient(RequestHandler, () => new RequestHandler());
+  .registerSingleton('logger', () => ({ log: (message: string) => console.log(message) }))
+  .registerScoped('greeting', r => {
+    const logger = r.resolve('logger'); // Inferred from the previous registration
+    return (name: string) => logger.log(`Hello, ${name}!`);
+  });
 
 const scope = createScope(container);
-
-// Singleton — same instance every time
-scope.resolve(Database) === scope.resolve(Database); // true
-
-// Transient — new instance every time
-scope.resolve(RequestHandler) === scope.resolve(RequestHandler); // false
-```
-
-### Scoped Lifetime & Child Containers
-
-Scoped registrations behave like singletons within a scope but produce a fresh instance in each new scope. Use `createScope` to create a child container. Scoped tokens cannot be resolved from the root container.
-
-```ts
-import { createContainer, createScope } from 'katagami';
-
-class DbPool {
-	constructor(public name = 'main') {}
-}
-
-class RequestContext {
-	constructor(public id = Math.random()) {}
-}
-
-const root = createContainer()
-	.registerSingleton(DbPool, () => new DbPool())
-	.registerScoped(RequestContext, () => new RequestContext());
-
-// Create a scope for each request
-const scope1 = createScope(root);
-const scope2 = createScope(root);
-
-// Scoped — same within a scope, different across scopes
-scope1.resolve(RequestContext) === scope1.resolve(RequestContext); // true
-scope1.resolve(RequestContext) === scope2.resolve(RequestContext); // false
-
-// Singleton — shared across all scopes
-scope1.resolve(DbPool) === scope2.resolve(DbPool); // true
+scope.resolve('greeting')('world');
+// scope.resolve('missing'); // Type error: this token has not been registered
 ```
 
-Scopes can also be nested. Each nested scope has its own scoped instance cache while sharing singletons with its parent:
-
-```ts
-const parentScope = createScope(root);
-const childScope = createScope(parentScope);
-
-// Each nested scope gets its own scoped instances
-parentScope.resolve(RequestContext) === childScope.resolve(RequestContext); // false
-
-// Singletons are still shared
-parentScope.resolve(DbPool) === childScope.resolve(DbPool); // true
-```
+No service interface or explicit generic argument is needed here. Literal string keys,
+unique symbols and class tokens can all be used. See [type guarantees](./docs/type-safety.md)
+for the difference between accumulated registrations and a predeclared type map.
 
-### Module Composition
+## Why Katagami
 
-Group related registrations into a reusable module by creating a container with `createContainer()`, then apply it to another container with `use()`. Only registration entries are copied — singleton instance caches are not shared.
+Katagami combines **registration-derived types, compile-time scope restrictions and zero runtime
+dependencies** in an ordinary TypeScript factory API.
+
+- **Types grow with your registrations.** Literal keys and unique symbols carry their inferred
+  service types into subsequent factories; required tokens outside that set are compile-time errors.
+- **Request state stays explicit.** Singleton and transient factories cannot resolve scoped tokens
+  through their supplied typed resolver. You can find this mistake before starting the application.
+- **No decorator setup.** No `experimentalDecorators`, `emitDecoratorMetadata` or Reflect polyfill
+  is needed for DI. Constructors and factories stay ordinary TypeScript.
+- **Import the capabilities you use.** Core DI, `katagami/disposable` and `katagami/lazy` are separate
+  entry points. ESM exports and `sideEffects: false` support tree shaking; optional cleanup integrates
+  with `await using` and the host's disposal symbols.
+
+These checks assume narrow tokens and preserved registration types; see the
+[class-token, mutation and predeclared-map boundaries](./docs/type-safety.md).
+
+### Library comparison
+
+Reviewed **2026-09-11**, against the npm `latest` versions below and official documentation.
+The tables describe the built-in APIs; add-ons and application-specific wrappers can change the
+trade-offs. [Version sources and detailed comparison notes](./docs/choosing-di.md#comparison-sources)
+explain the distinctions.
+
+| Library / reviewed version | Dependency typing and missing registrations | Scoped-dependency handling | DI setup |
+| --- | --- | --- | --- |
+| **Katagami 3.0.2** | **Accumulated literal/unique-symbol tokens; missing required tokens rejected** | **Scoped tokens excluded from singleton/transient factory resolvers** | **No decorators or metadata; zero runtime dependencies** |
+| [InversifyJS 8.2.3](https://inversify.io/docs/fundamentals/binding/) | Typed identifiers and bindings; binding existence checked at runtime | Declared binding scopes; not a scope-filtered resolver type | Metadata-based class injection; explicit value/factory bindings also available |
+| [tsyringe 4.10.0](https://github.com/microsoft/tsyringe#readme) | Class/generic resolution types; registrations checked at runtime | Runtime lifetime settings; factory receives the container | Decorators and a Reflect metadata polyfill for class injection |
+| [TypeDI 0.10.0](https://github.com/typestack/typedi/tree/v0.10.0) | Class and `Token<T>` types; registrations checked at runtime | Shared/transient services and named containers | Decorators and `reflect-metadata` in the TypeScript setup |
+| [Awilix 13.0.5](https://github.com/jeffijoe/awilix#readme) | Registration-derived cradle types; broad `resolve` overload still accepts unknown names | `strict: true` checks lifetime leaks at runtime | No decorators or metadata |
+| [NestJS 12.0.1](https://docs.nestjs.com/fundamentals/custom-providers) | Typed providers; module/provider graph resolved at runtime | Request scope propagates to dependent providers | Framework modules and metadata-based class injection |
+| [Effect 3.22.2](https://effect.website/docs/v3/requirements-management/layers) | Service requirements tracked in `Effect` / `Layer` types | Typed `Scope` requirements and resource finalizers; a different lifetime model | No decorators or metadata; Effect's service/layer model |
+| [typed-inject 5.0.0](https://github.com/nicojs/typed-inject#readme) | Accumulated string tokens and checked `inject` tuples | Singleton/transient providers and child injectors; no separate scoped lifetime | No decorators or metadata; zero runtime dependencies |
+
+Awilix's inferred `cradle` and typed-inject's registration types are real compile-time features.
+Katagami's distinction is the combination of accumulated registration checks with **scope-filtered
+factory resolvers**, using direct `r.resolve(token)` calls. Effect also checks unsatisfied service
+requirements, within its broader effect and resource model.
+
+| Library | Lifetimes / scope model | Asynchronous services | Resource cleanup |
+| --- | --- | --- | --- |
+| **Katagami** | **Singleton, transient, scoped; nested scopes** | **Inferred `Promise<T>`; explicitly await dependencies** | **`Symbol.dispose` / `Symbol.asyncDispose` via `disposable()`; `await using`** |
+| InversifyJS | Singleton, transient, request (one resolution graph); container hierarchy | Async bindings via `getAsync` / `getAllAsync`; awaits dependencies | Singleton deactivation handlers |
+| tsyringe | Singleton, transient, resolution-scoped, container-scoped | Factories can return Promise-valued services; consumer handles the Promise | `container.dispose()` for constructed disposable instances |
+| TypeDI | Shared or transient services; named containers | Promise-valued services; consumer handles the Promise | `reset()` / removal can call `destroy()`; returned Promise is not awaited |
+| Awilix | Singleton, transient, scoped | Promise-valued factories; consumer handles the Promise | Registered disposers for cached singleton/scoped values |
+| NestJS | Singleton, transient, HTTP request; scope propagation | Async providers are awaited before dependent construction | Application lifecycle hooks; not called for request-scoped classes |
+| Effect | Memoized layers and explicit resource scopes | Effectful acquisition, including async effects | Scope finalizers and `acquireRelease` |
+| typed-inject | Singleton, transient; disposable child injectors | Promise-valued factories with inferred return types | `injector.dispose()` awaits owned instances' `dispose()` |
+
+“Request” is not identical across libraries: InversifyJS uses a resolution graph, while NestJS can
+use an HTTP request. Katagami and Awilix let you create an explicit scope per request.
+Returning a Promise and automatically awaiting dependencies are also different capabilities.
+See [composition, optional/multiple resolution and tooling](./docs/choosing-di.md#composition-and-tooling)
+for the rest of the feature comparison.
+
+## Why Katagami for AI-assisted development?
+
+Give coding agents a concrete feedback loop: edit dependency wiring, run the TypeScript checker,
+and use the diagnostics to fix invalid dependencies. Explicit factories keep dependency edges
+in ordinary TypeScript code that both people and agents can read.
+
+For example, a singleton must not capture state that belongs to one request:
 
 ```ts
 import { createContainer } from 'katagami';
 
-class AuthService {
-	authenticate() {
-		return true;
-	}
-}
-
-class TokenService {
-	issue() {
-		return 'token';
-	}
-}
-
-class UserService {
-	constructor(private auth: AuthService, private tokens: TokenService) {}
-}
-
-// Define a reusable module
-const authModule = createContainer()
-	.registerSingleton(AuthService, () => new AuthService())
-	.registerSingleton(TokenService, () => new TokenService());
-
-// Compose modules
-const container = createContainer()
-	.use(authModule)
-	.registerSingleton(UserService, r => new UserService(r.resolve(AuthService), r.resolve(TokenService)));
-```
-
-Modules can also compose other modules:
-
-```ts
-const infraModule = createContainer().registerSingleton(AuthService, () => new AuthService());
-
-const appModule = createContainer()
-	.use(infraModule)
-	.registerSingleton(UserService, r => new UserService(r.resolve(AuthService), r.resolve(TokenService)));
-
-// appModule includes both AuthService and UserService
-const container = createContainer().use(appModule);
-```
-
-### Async Factories
-
-Factories that return a `Promise` are automatically tracked by the type system. When you `resolve` an async token, the return type is `Promise<V>` instead of `V`:
-
-```ts
-import { createContainer, createScope } from 'katagami';
-
-class Database {
-	constructor(public connected: boolean) {}
-}
-
-class Logger {
-	log(msg: string) {
-		console.log(msg);
-	}
-}
-
-const container = createContainer()
-	.registerSingleton(Logger, () => new Logger())
-	.registerSingleton(Database, async () => {
-		await new Promise(r => setTimeout(r, 100)); // simulate async init
-		return new Database(true);
-	});
-
-const scope = createScope(container);
-
-const logger = scope.resolve(Logger);
-//    ^? Logger
-
-const db = await scope.resolve(Database);
-//    ^? Promise<Database>  (awaited → Database)
-db.connected; // true
-```
-
-Async factories can depend on both sync and async registrations:
-
-```ts
-const container = createContainer()
-	.registerSingleton(Logger, () => new Logger())
-	.registerSingleton(Database, async r => {
-		const logger = r.resolve(Logger); // sync → Logger
-		logger.log('Connecting...');
-		return new Database(true);
-	});
-```
-
-### Circular Dependency Detection
-
-Katagami tracks which tokens are currently being resolved. If a circular dependency is found, a `ContainerError` is thrown with a clear message showing the full cycle path:
-
-```ts
-import { createContainer, createScope } from 'katagami';
-
-class ServiceA {
-	constructor(public b: ServiceB) {}
-}
-
-class ServiceB {
-	constructor(public a: ServiceA) {}
-}
-
-const container = createContainer()
-	.registerSingleton(ServiceA, r => new ServiceA(r.resolve(ServiceB)))
-	.registerSingleton(ServiceB, r => new ServiceB(r.resolve(ServiceA)));
-
-createScope(container).resolve(ServiceA);
-// ContainerError: Circular dependency detected: ServiceA -> ServiceB -> ServiceA
-```
-
-Indirect cycles are also detected:
-
-```
-ContainerError: Circular dependency detected: ServiceX -> ServiceY -> ServiceZ -> ServiceX
-```
-
-### Disposable Support
-
-Disposal is provided by the `disposable()` wrapper from `katagami/disposable`. Wrapping a container or scope attaches `[Symbol.asyncDispose]`, enabling `await using` syntax. When disposed, owned instances are iterated in reverse creation order (LIFO) and their `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` methods are called automatically.
-
-```ts
-import { createContainer, createScope } from 'katagami';
-import { disposable } from 'katagami/disposable';
-
-class Connection {
-	async [Symbol.asyncDispose]() {
-		console.log('Connection closed');
-	}
-}
-
-// Manual disposal
-const container = createContainer().registerSingleton(Connection, () => new Connection());
-const dc = disposable(container);
-
-createScope(container).resolve(Connection);
-await dc[Symbol.asyncDispose]();
-// => "Connection closed"
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — a singleton factory cannot resolve this scoped token
+  .registerSingleton('handler', r => r.resolve('request'));
 ```
 
-With `await using`, scopes are automatically disposed at the end of the block:
-
-```ts
-import { createContainer, createScope } from 'katagami';
-import { disposable } from 'katagami/disposable';
-
-const root = createContainer()
-	.registerSingleton(DbPool, () => new DbPool())
-	.registerScoped(Connection, () => new Connection());
-
-{
-	await using scope = disposable(createScope(root));
-	const conn = scope.resolve(Connection);
-	// ... use conn ...
-} // scope is disposed here — Connection is cleaned up, DbPool is not
-```
-
-Scope disposal only affects scoped instances. Singleton instances are owned by the root container and are disposed when the container itself is disposed.
-
-The `disposable()` wrapper also narrows the returned type so that registration methods (`registerSingleton`, `registerTransient`, `registerScoped`, `use`) are removed at the type level. This prevents accidental registration on a potentially-disposed container:
-
-```ts
-const dc = disposable(createContainer().registerSingleton(Connection, () => new Connection()));
-
-dc.registerSingleton(/* ... */); // Compile-time error — registration methods are hidden
-```
-
-### Lazy Resolution
-
-The `lazy()` function from `katagami/lazy` creates a proxy that defers instance creation until the first property access. This is useful for optimizing startup time or breaking circular dependencies.
-
-```ts
-import { createContainer, createScope } from 'katagami';
-import { lazy } from 'katagami/lazy';
-
-class HeavyService {
-	constructor() {
-		// expensive initialization
-	}
-	process() {
-		return 'done';
-	}
-}
-
-const container = createContainer().registerSingleton(HeavyService, () => new HeavyService());
-const scope = createScope(container);
-
-const service = lazy(scope, HeavyService);
-// HeavyService is NOT instantiated yet
-
-service.process(); // instance created here, then cached
-service.process(); // uses the cached instance
-```
-
-The proxy transparently forwards all property access, method calls, `in` checks, and prototype lookups to the real instance. Methods are automatically bound to the real instance, so `this` works correctly even when destructured.
-
-Only **sync class tokens** are supported. Async tokens and PropertyKey tokens are rejected at the type level because Proxy traps are synchronous.
-
-`lazy()` works with Scope and DisposableScope:
-
-```ts
-const root = createContainer().registerScoped(RequestContext, () => new RequestContext());
-const scope = createScope(root);
-
-const ctx = lazy(scope, RequestContext); // deferred scoped resolution
-```
-
-### Tree Shaking
-
-Katagami uses subpath exports to split functionality into independent entry points. If you only need the core container, `katagami/disposable` and `katagami/lazy` are completely excluded from the bundle. The package declares `sideEffects: false`, so bundlers can safely eliminate any unused code.
-
-```ts
-// Core only — disposable and lazy are not included in the bundle
-import { createContainer, createScope } from 'katagami';
-
-// Import only what you need
-import { disposable } from 'katagami/disposable';
-import { lazy } from 'katagami/lazy';
-```
-
-### Interface Type Map
-
-When you pass an interface to `createContainer<T>()`, PropertyKey tokens are typed from the interface rather than accumulated through chaining. This means you can register and resolve tokens in any order:
-
-```ts
-import { createContainer, createScope } from 'katagami';
-
-class Logger {
-	log(msg: string) {
-		console.log(msg);
-	}
-}
-
-interface Services {
-	logger: Logger;
-	greeting: string;
-}
-
-const container = createContainer<Services>()
-	// 'greeting' can reference 'logger' even though it is registered later
-	.registerSingleton('greeting', r => {
-		r.resolve('logger').log('Building greeting...');
-		return 'Hello!';
-	})
-	.registerSingleton('logger', () => new Logger());
-
-const greeting = createScope(container).resolve('greeting');
-//    ^? string
-```
-
-### Hybrid Token Strategy
-
-You can mix both approaches — use class tokens for order-dependent type safety and PropertyKey tokens for order-independent flexibility:
-
-```ts
-const container = createContainer<Services>()
-	.registerSingleton(Logger, () => new Logger())
-	.registerSingleton('logger', () => new Logger())
-	.registerSingleton('greeting', r => {
-		r.resolve(Logger).log('Building greeting...');
-		return 'Hello!';
-	});
-```
-
-### Captive Dependency Prevention
-
-A "captive dependency" occurs when a long-lived service (singleton or transient) captures a short-lived service (scoped), keeping it alive beyond its intended scope. Katagami prevents this at compile time — singleton and transient factories only receive a resolver limited to non-scoped tokens:
+The compiler reports `No overload matches this call` at `r.resolve('request')`.
+The factory's resolver does not include scoped tokens. Give the handler the same lifetime as the request:
 
 ```ts
 import { createContainer } from 'katagami';
 
-class DbPool {}
-class RequestContext {}
-
 const container = createContainer()
-	.registerScoped(RequestContext, () => new RequestContext())
-	// @ts-expect-error — singleton factory cannot resolve scoped token
-	.registerSingleton(DbPool, r => new DbPool(r.resolve(RequestContext)));
-```
-
-Scoped factories, on the other hand, can resolve both scoped and non-scoped tokens:
-
-```ts
-const container = createContainer()
-	.registerSingleton(DbPool, () => new DbPool())
-	.registerScoped(RequestContext, r => {
-		r.resolve(DbPool); // OK — scoped factory can resolve singleton tokens
-		return new RequestContext();
-	});
-```
-
-Katagami also enforces this rule at runtime within scopes. If a singleton factory attempts to resolve a scoped token — directly or through intermediaries — a `ContainerError` is thrown:
-
-```ts
-import { createContainer, createScope } from 'katagami';
-
-class DbPool {}
-class RequestContext {}
-
-const container = createContainer()
-	.registerScoped(RequestContext, () => new RequestContext())
-	.registerSingleton(DbPool, r => new DbPool(r.resolve(RequestContext)));
-
-const scope = createScope(container);
-scope.resolve(DbPool);
-// ContainerError: Captive dependency detected: scoped token "RequestContext" cannot be resolved inside a singleton factory.
-```
-
-### Optional Resolution (tryResolve)
-
-When you need to handle optional dependencies or want to check if a token is registered without throwing an error, use `tryResolve`. Unlike `resolve`, it returns `undefined` for unregistered tokens instead of throwing `ContainerError`:
-
-```ts
-import { createContainer, createScope } from 'katagami';
-
-class Logger {
-	log(msg: string) {
-		console.log(msg);
-	}
-}
-
-class Analytics {
-	track(event: string) {
-		console.log(`Track: ${event}`);
-	}
-}
-
-const container = createContainer().registerSingleton(Logger, () => new Logger());
-const scope = createScope(container);
-
-// resolve throws for unregistered tokens
-scope.resolve(Analytics); // ContainerError: Token "Analytics" is not registered.
-
-// tryResolve returns undefined for unregistered tokens
-const analytics = scope.tryResolve(Analytics);
-//    ^? Analytics | undefined
-if (analytics) {
-	analytics.track('event');
-}
-```
-
-`tryResolve` is especially useful for optional dependencies in factories. Unlike `resolve`, it accepts unregistered tokens without compile-time errors:
-
-```ts
-const container = createContainer()
-	.registerSingleton(Logger, () => new Logger())
-	.registerSingleton('UserService', r => {
-		const logger = r.tryResolve(Logger); // Optional dependency
-		const analytics = r.tryResolve(Analytics); // No compile error even though Analytics is not registered
-
-		return {
-			greet(name: string) {
-				logger?.log(`Hello, ${name}`);
-				analytics?.track('user_greeted');
-			},
-		};
-	});
-```
-
-`tryResolve` still throws `ContainerError` for circular dependencies and operations on disposed containers/scopes — only unregistered tokens return `undefined`.
-
-## API
-
-### `createContainer<T, ScopedT>()`
-
-Creates a new DI container. Pass an interface as `T` to define the type map for PropertyKey tokens. Pass `ScopedT` to define a separate type map for scoped PropertyKey tokens (order-independent, just like `T`).
-
-### `Container.prototype.registerSingleton(token, factory)`
-
-Registers a factory as a singleton. The instance is created on the first `resolve` and cached thereafter. Returns the container for method chaining.
-
-### `Container.prototype.registerTransient(token, factory)`
-
-Registers a factory as transient. A new instance is created on every `resolve`. Returns the container for method chaining.
-
-### `Container.prototype.registerScoped(token, factory)`
-
-Registers a factory as scoped. Within a scope, the instance is created on the first `resolve` and cached for that scope. Each scope maintains its own cache. Scoped tokens cannot be resolved from the root container. Returns the container for method chaining.
-
-### `Container.prototype.use(source)`
-
-Copies all registrations from `source` (another `Container`) into this container. Only factory and lifetime entries are copied — singleton instance caches are not shared. Returns the container for method chaining.
-
-### `createScope(source)`
-
-Creates a new `Scope` (child container) from a `Container` or an existing `Scope`. The scope inherits all registrations from the source. Singleton instances are shared with the parent, while scoped instances are local to the scope.
-
-### `class Scope`
-
-A scoped child container created by `createScope()`.
-
-### `Scope.prototype.resolve(token)`
-
-Resolves and returns the instance for the given token. Throws `ContainerError` if the token is not registered or if a circular dependency is detected. Can resolve both non-scoped and scoped tokens.
-
-### `Scope.prototype.tryResolve(token)`
-
-Attempts to resolve the instance for the given token. Returns `undefined` if the token is not registered, instead of throwing. Still throws `ContainerError` for circular dependencies or operations on disposed scopes.
-
-### `lazy(source, token)` — `katagami/lazy`
-
-Creates a Proxy that defers `resolve()` until the first property access. The resolved instance is cached — subsequent accesses use the cache. Only sync class tokens are supported; async tokens and PropertyKey tokens are rejected at the type level. Works with `Scope` and `DisposableScope`.
-
-### `disposable(container)` — `katagami/disposable`
-
-Attaches `[Symbol.asyncDispose]` to a `Container` or `Scope`, enabling `await using` syntax. Disposes all owned instances in reverse creation order (LIFO). Calls `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them. Idempotent — subsequent calls are no-ops. After disposal, `resolve()` and `createScope()` will throw `ContainerError`. The returned type is narrowed to `DisposableContainer` or `DisposableScope`. `DisposableContainer` exposes only disposal capability — registration and resolution methods are excluded. `DisposableScope` retains `resolve`, `tryResolve`, `resolveAll`, and `tryResolveAll` for resolution.
-
-### `class ContainerError`
-
-Error class thrown for container failures such as resolving an unregistered token, circular dependencies, or operations on a disposed container/scope.
-
-### `type Resolver`
-
-Type export representing the resolver passed to factory callbacks. Useful when you need to type a function that accepts a resolver parameter.
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  .registerScoped('handler', r => r.resolve('request'));
+```
+
+The `@ts-expect-error` above makes the deliberately invalid example a checked regression test.
+In application code, fix the lifetime and run `npx tsc --noEmit`; do not add a suppression.
+These examples prove specific compiler checks. Improvements in agent success rate or token usage
+have not been measured; the [evaluation protocol](https://github.com/hiroiku/katagami/tree/master/benchmarks/agent-wiring)
+describes how to test them.
+
+**Start here:** [Guide for AI coding agents](./docs/ai-coding-agents.md) ·
+[Runnable request-scope starter](./examples/request-scope/README.md) ·
+[Type safety and its boundaries](./docs/type-safety.md)
+
+## What you get
+
+| Capability | Practical use |
+| --- | --- |
+| Accumulated registration types | Resolve registered literal tokens with inferred return types |
+| Scope-aware factory resolvers | Detect direct access to scoped dependencies from singleton/transient factories |
+| Async type tracking | Keep `Promise` results visible to the compiler |
+| Singleton, transient and scoped lifetimes | Share infrastructure and isolate request state |
+| Explicit factories and `use()` composition | Group registrations and replace infrastructure in tests |
+| Class, string, number and symbol tokens | Choose the token style that fits your application |
+| Optional and multiple resolution | Use `tryResolve`, `resolveAll` and `tryResolveAll` |
+| Resource cleanup and lazy resolution | Opt in through `katagami/disposable` and `katagami/lazy` |
+| ESM, CommonJS and zero runtime dependencies | Use standard tooling without decorator metadata setup |
+
+Use Katagami when dependency wiring, test substitution or request lifetimes need structure.
+For a few dependencies, ordinary constructor/function parameters may be enough.
+See [choosing a DI approach](./docs/choosing-di.md) for trade-offs and links to alternatives.
+
+## Documentation
+
+- [Usage guide and API](./docs/guide.md): lifetimes, composition, classes, async factories, cleanup and lazy resolution.
+- [Type guarantees](./docs/type-safety.md): accumulated tokens, interface maps and structural class typing.
+- [AI coding guide](./docs/ai-coding-agents.md): workflow, diagnostics and a prompt to use in your project.
+- [Request-scope starter](./examples/request-scope/README.md): concurrent requests, fake repositories and cleanup.
+- [AI-assisted dependency wiring](./docs/articles/ai-coding-agents.md): a worked example.
+- [Request-scope mistakes](./docs/articles/request-scope.md): identifying and fixing a captive dependency.
+- [DI without decorators](./docs/articles/without-decorators.md): installation and test substitution.
+- [Contributing](https://github.com/hiroiku/katagami/blob/master/CONTRIBUTING.md) and [changelog](https://github.com/hiroiku/katagami/blob/master/CHANGELOG.md).
+
+TypeScript examples use strict type checking. Core DI needs no polyfills. Optional resource
+cleanup requires the host's disposal symbols; `await using` also requires suitable TypeScript
+compiler/lib settings. See the [compatibility notes](./docs/guide.md#compatibility).
+
+## About the name
+
+型紙 (*katagami*) is stencil paper used in traditional Japanese dyeing.
+Layered stencils compose a pattern, just as registrations accumulate types in a method chain.
 
 ## License