katagami 3.0.0 → 3.0.2

package/docs/ai-coding-agents.md

@@ -0,0 +1,78 @@
+# TypeScript dependency injection with AI coding agents
+
+Use Katagami's accumulated registration types as feedback while an agent edits dependency wiring.
+This guide describes the v3 API. Check the installed package version before editing an existing app.
+
+## A repeatable workflow
+
+1. Read the composition root, nearby service constructors and tests.
+2. Define dependencies explicitly in factories. Start with `createContainer()` and preserve inferred types.
+3. Register a dependency before the factory that uses it. Resolve services through `createScope(container)`.
+4. Choose a lifetime: singleton for shared infrastructure, scoped for request state, transient for a new instance per resolution.
+5. Run the application's `npx tsc --noEmit`, then its existing tests.
+6. Correct registration, lifetime or asynchronous usage based on diagnostics. Repeat until both checks pass.
+
+When changing Katagami itself, use `bun run verify` instead; it includes type tests,
+runtime tests, examples, the packed package and documentation checks.
+
+## Minimal working example
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('users', async () => ({ findName: (id: string) => `user-${id}` }))
+  .registerScoped('handler', async r => {
+    const users = await r.resolve('users');
+    return (id: string) => users.findName(id);
+  });
+
+const scope = createScope(container);
+const handler = await scope.resolve('handler');
+handler('42');
+```
+
+Use the [request-scope starter](../examples/request-scope/README.md) for cleanup,
+concurrent calls and replacement of infrastructure with a fake.
+
+## Diagnose the error before changing code
+
+| Diagnostic or symptom | Check | Typical correction |
+| --- | --- | --- |
+| `No overload matches this call` at `resolve`, often mentioning `never` | Is this exact token registered and visible here? | Register it earlier, correct its spelling, or compose the module first |
+| The same error inside a singleton/transient factory after a scoped registration | Does the factory capture request state? | Make the consumer scoped, or pass request data into a method without storing it |
+| A service method does not exist on `Promise<...>` | Is the dependency factory async? | Await the resolution; make the consuming factory async if needed |
+| `resolve` does not exist on `Container` | v3 separates registration from resolution | Call `createScope(container).resolve(token)` |
+| `lazy` rejects a token | Is it an async or PropertyKey token? | Use direct resolution; `lazy` accepts synchronous class tokens |
+| Runtime `Token ... is not registered` despite a passing type check | Predeclared map, compatible class, widened key or assertion? | Register the actual token and review the type-safety guide |
+
+The wording of compiler diagnostics varies with TypeScript versions. Check the failing
+expression and the resolver's visible registrations; do not match an error string blindly.
+
+## Project instruction you can copy
+
+```text
+Use the installed Katagami v3 API for dependency wiring. Read
+node_modules/katagami/docs/ai-coding-agents.md and
+node_modules/katagami/docs/type-safety.md first.
+Preserve inferred registration chains and narrow literal/unique-symbol tokens.
+Resolve through createScope. Keep request state scoped and await async dependencies.
+Use explicit factories and inject fakes in tests.
+Fix type errors at their cause; do not silence them with any, assertions,
+@ts-ignore, @ts-expect-error or optional resolution for required dependencies.
+Run this application's type checker and tests after changes.
+```
+
+Add this instruction to the project instructions your agent already reads, or pass it explicitly
+with the task. Installing a dependency does not ensure that an agent reads its documentation.
+
+## Guarantees and evidence
+
+Accumulated literal keys and unique symbols provide a finite set of registered tokens.
+Class tokens follow structural compatibility; predeclared service maps can name missing factories.
+See [the complete guarantee and boundary examples](./type-safety.md).
+
+The compiler checks and example tests are automated in CI. Agent repair success and token savings
+are hypotheses, not measured product claims. Use the
+[controlled evaluation protocol](https://github.com/hiroiku/katagami/tree/master/benchmarks/agent-wiring)
+before making quantitative comparisons.

package/docs/articles/ai-coding-agents.ja.md

@@ -0,0 +1,83 @@
+---
+title: "AIエージェントが書く依存関係を、TypeScriptの型で検証する"
+emoji: "🧩"
+type: "tech"
+topics: ["typescript", "ai", "di"]
+published: false
+---
+
+# AIエージェントが書く依存関係を、TypeScriptの型で検証する
+
+AIとコードを書くときも、変更の正しさを確認する手段が必要です。依存関係の配線なら、
+コードを変更し、TypeScriptを実行し、診断に沿って修正する流れを作れます。
+私が開発しているDIコンテナのKatagamiは、依存を登録するたびに型を積み上げ、
+ファクトリから参照できる依存を型として表現します。
+
+## 登録から型を積み上げる
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('users', () => ({ find: (id: string) => `user-${id}` }))
+  .registerScoped('handler', r => (id: string) => r.resolve('users').find(id));
+
+createScope(container).resolve('handler')('42');
+```
+
+この例にサービス一覧のインターフェースはありません。usersを登録すると、次のファクトリで
+usersを参照できる型になります。r.resolve('user')と書き間違えたり、usersの登録を削除したり
+すると、依存を使う側で型エラーが出ます。起動せずに確認できる検査です。
+
+## ライフタイムの誤りを検出する
+
+リクエスト固有の状態を、すべてのリクエストで共有するSingletonが保持すると問題になります。
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('requestId', () => crypto.randomUUID())
+  // @ts-expect-error — SingletonのファクトリにはScopedのトークンが見えない
+  .registerSingleton('handler', r => r.resolve('requestId'));
+```
+
+この場合、r.resolve('requestId')でNo overload matches this callという診断が出ます。
+handlerがリクエストの状態を保持するなら、registerScopedに変えるのが修正です。
+状態を保持する必要がなければ、共有サービスのメソッドへrequestIdを引数で渡す設計もできます。
+
+@ts-expect-errorは、この記事の失敗例をCIで検証するための注記です。
+実際のアプリでは注記でエラーを隠さず、依存関係やライフタイムを直します。
+
+## エージェントに渡すもの
+
+現行APIの説明、アプリの依存登録箇所、型チェックとテストのコマンドを渡します。
+エージェントには推論された型を保ち、渡されたファクトリのリゾルバを使ってもらいます。
+変更後にnpx tsc --noEmitとアプリのテストを実行し、問題があれば修正します。
+
+[実行可能なスターター](https://github.com/hiroiku/katagami/tree/master/examples/request-scope)には、
+リクエストごとの状態、テスト用のリポジトリ差し替え、成功・失敗時のリソース破棄を含めました。
+AI向けの利用ガイドもnpmパッケージに同梱します。
+
+## 型で保証できる範囲を分ける
+
+デフォルトの蓄積方式では、リテラルキーやunique symbolの型を保つことで、見えている登録集合に
+含まれないトークンを拒否できます。一方、createContainer<Services>()で事前宣言する方式は、
+後から登録する依存を参照できる代わりに、全キーの実際の登録までは証明しません。
+
+クラストークンには構造的型付けも関係します。同じ構造の別クラスは型として互換でも、
+実行時には別のトークンです。この区別が必要なら、unique symbolやリテラルキー、
+個別のprivateメンバーで区別したクラスを使います。
+[保証と例外](https://github.com/hiroiku/katagami/blob/master/docs/type-safety.md)をコード付きで整理しています。
+
+型チェックの例と実行テストは自動検証しています。ただし、AIの修正成功率やトークン消費の改善は
+まだ測定していません。同じ課題・モデル・条件で失敗も含めて記録する評価手順を用意しています。
+
+依存が少なければ、普通の関数やコンストラクタの引数でも十分です。
+依存の構築・共有・リクエスト単位の管理が増えた場面で、選択肢として試してもらえればと思います。
+
+```sh
+npm install katagami
+```
+
+[KatagamiのREADME](https://github.com/hiroiku/katagami)から、基本例と利用ガイドを読めます。

package/docs/articles/ai-coding-agents.md

@@ -0,0 +1,70 @@
+# Type-safe dependency injection for AI coding agents
+
+AI-assisted development still needs a way to check the code it produces. For dependency wiring,
+a useful loop is small: edit the composition root, run TypeScript, read the diagnostics, and repair
+the missing dependency or incorrect lifetime. Katagami makes some of those wiring constraints visible
+to the compiler by accumulating types as dependencies are registered.
+
+## Let registration define the available dependencies
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('users', () => ({ find: (id: string) => `user-${id}` }))
+  .registerScoped('handler', r => (id: string) => r.resolve('users').find(id));
+
+createScope(container).resolve('handler')('42');
+```
+
+There is no manually maintained service interface in this example. The first registration adds
+`users` to the type known by the next factory. The second adds `handler` to the scope's visible set.
+Changing `r.resolve('users')` to `r.resolve('user')` produces a type error. Removing the first
+registration also produces a type error at the consumer.
+
+The check is useful for both people and coding agents: the factory's actual dependency is written
+in the same code that TypeScript checks. The compiler can report a problem without starting the app.
+
+## Turn a diagnostic into a repair
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('requestId', () => crypto.randomUUID())
+  // @ts-expect-error — a singleton factory cannot access this scoped dependency
+  .registerSingleton('handler', r => r.resolve('requestId'));
+```
+
+The diagnostic includes `No overload matches this call`. Inspect the failing resolution and its
+lifetime: the factory requests state belonging to one request while asking to be shared as a singleton.
+Register the handler as scoped, or pass the request ID into a shared service's method without storing it.
+
+`@ts-expect-error` is only present to test this intentionally invalid example. It is not the repair.
+In application code, change the wiring, run `npx tsc --noEmit`, then run behavior tests.
+
+## Make the workflow usable
+
+Give the agent the [v3 usage guide](../ai-coding-agents.md), the application's composition root and
+its verification command. Have it use the supplied factory resolver, preserve inferred registration
+types and run the checker after changes. A [runnable request-scope starter](../../examples/request-scope/README.md)
+shows fake injection, concurrent calls and cleanup on both success and failure.
+
+Ordinary constructor or function injection is still a useful baseline. It also gets TypeScript's
+parameter checks and can be enough for small applications. Introduce a container when construction,
+sharing, request scope or module composition is otherwise becoming repetitive.
+
+## State the guarantee accurately
+
+Accumulated literal keys and unique symbols let the checker reject tokens outside the visible
+registered set. A predeclared `createContainer<Services>()` map instead permits forward references
+and does not establish runtime registration completeness. Class tokens follow TypeScript's
+structural typing, so another compatible class may pass the checker while being a different runtime key.
+See [working examples of these boundaries](../type-safety.md).
+
+The compiler cases in this article are tested. We have not measured agent repair success or token
+savings. Those need [controlled repeated trials](https://github.com/hiroiku/katagami/tree/master/benchmarks/agent-wiring),
+including failures and the same tasks, model settings and runtime tests across variants.
+
+Install with `npm install katagami`, then start with the
+[quick start](../../README.md#quick-start) or the [request-scope example](../../examples/request-scope/README.md).

package/docs/articles/request-scope.md

@@ -0,0 +1,48 @@
+# Catch request-scope mistakes at compile time in TypeScript
+
+A service shared by all requests should not retain state from just one request. A DI container
+can make that mistake easier to express if every factory can resolve every dependency. Katagami's
+typed singleton and transient factories receive a resolver that excludes scoped registrations.
+
+## Reproduce the problem
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — the request belongs to one scope, not a shared singleton
+  .registerSingleton('handler', r => ({ requestId: r.resolve('request').id }));
+```
+
+The checker rejects the resolution of `request`. The fix depends on what the handler should do.
+If it holds request state, give it a scoped lifetime:
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  .registerScoped('handler', r => ({ requestId: r.resolve('request').id }));
+
+const first = createScope(container);
+const second = createScope(container);
+first.resolve('handler').requestId !== second.resolve('handler').requestId; // true
+```
+
+If the service can be stateless and shared, take request data as a method parameter instead.
+Do not close over another request scope to get around the factory resolver.
+
+## Test what types cannot establish
+
+Type-check the wiring, then check that concurrent requests have distinct IDs, shared infrastructure
+stays shared, and resources are cleaned on rejection as well as success. The
+[request-scope starter](../../examples/request-scope/README.md) and its tests cover these cases.
+
+The compile-time example uses accumulated literal keys. A broad type annotation, predeclared map,
+compatible class token, assertion or captured external resolver can change what is checked.
+The runtime captive-dependency guard also has limits around work resumed after an `await`.
+The [type-safety guide](../type-safety.md) explains the exact scope of the guarantee.
+
+Katagami provides Singleton, Transient and Scoped lifetimes without decorator metadata.
+The [API guide](../guide.md) shows composition, async factories and optional disposal.

package/docs/articles/without-decorators.md

@@ -0,0 +1,54 @@
+# TypeScript dependency injection without decorators
+
+Dependency injection can be ordinary TypeScript: a factory receives a resolver and explicitly
+constructs a service. Katagami uses this model and has no runtime package dependencies, decorator
+compiler flags or reflect-metadata requirement.
+
+```sh
+npm install katagami
+```
+
+## Start with a factory
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+class Logger {
+  log(message: string) { console.log(message); }
+}
+class Greeting {
+  constructor(private logger: Logger) {}
+  say(name: string) { this.logger.log(`Hello, ${name}!`); }
+}
+
+const container = createContainer()
+  .registerSingleton(Logger, () => new Logger())
+  .registerTransient(Greeting, r => new Greeting(r.resolve(Logger)));
+
+createScope(container).resolve(Greeting).say('Ada');
+```
+
+The registration chain determines which class types the next factory can resolve. Class tokens
+are convenient when the classes are structurally distinguishable. Literal keys or unique symbols
+are also supported; see [token identity and type guarantees](../type-safety.md).
+
+## Substitute infrastructure in a test
+
+Factories can accept infrastructure as ordinary parameters. The
+[request-scope starter](../../examples/request-scope/README.md) takes a `UserRepository` argument.
+Its tests pass a small fake that returns a known name, then check the greeting. No global container
+or decorator setup is required.
+
+For larger compositions, group registrations in a container and copy them with `use()`.
+Apply the fake module before resolving anything. `use()` replaces matching registration entries;
+it is mutable composition, not automatic file loading or a snapshot API.
+
+## Choose only the lifecycle features you need
+
+Core imports come from `katagami`. Add cleanup from `katagami/disposable` or synchronous class-based
+lazy resolution from `katagami/lazy` when needed. Those entry points are separate so bundlers can
+omit unused implementations. Cleanup uses the host's disposal symbols; it does not provide a polyfill.
+
+For a small application, manual constructor parameters may remain the simplest choice.
+The [DI decision guide](../choosing-di.md) explains when accumulated registration types and request
+scopes are useful and links to other containers' own documentation.

package/docs/choosing-di.md

@@ -0,0 +1,143 @@
+# Choosing a TypeScript dependency injection approach
+
+Katagami is a strong fit when you want **registration-derived types, explicit request scopes and
+ordinary TypeScript factories without decorators or runtime dependencies**. The
+[README comparison](../README.md#library-comparison) covers all eight libraries, including their
+typing, setup, lifetimes, asynchronous behavior and cleanup. This guide records the evidence and
+the features that need more explanation than a table cell.
+
+## What distinguishes Katagami
+
+The default registration chain accumulates the tokens visible to each factory. With literal keys
+or unique symbols preserved, a missing required token is rejected before execution. Singleton and
+transient factories receive a resolver that excludes scoped tokens. Async results stay visible as
+Promises. This combination gives a coding agent actionable TypeScript errors while keeping the
+wiring in ordinary factory functions.
+
+Accumulation alone is not unique to Katagami: typed-inject checks accumulated tokens and injection
+tuples, and Awilix 13 infers cradle types from registrations. Effect tracks required services in its
+effect and layer types. Katagami adds a specific scope restriction to its factory resolver API.
+See [the guarantee examples](./type-safety.md) for narrow-token requirements, structural class
+typing, mutable aliases and predeclared-map boundaries.
+
+| Approach | A reason to choose it |
+| --- | --- |
+| Ordinary constructor/function parameters | Few dependencies; direct wiring remains easy to maintain |
+| Katagami | Registration checks and explicit scoped DI in standard TypeScript factories |
+| InversifyJS | Class-oriented binding, contextual constraints, container modules and snapshots |
+| tsyringe | Constructor injection with decorators, child containers and resolution interceptors |
+| TypeDI | An existing application built around its decorators, typed tokens and named containers |
+| Awilix | Proxy/classic injection, inferred cradles, module loading and runtime lifetime checks |
+| NestJS | The app already benefits from Nest modules, request handling and framework integrations |
+| Effect | Service composition belongs with typed errors, effectful execution and scoped resources |
+| typed-inject | Accumulated string-token checks with explicit injection tuples and child injectors |
+
+## Comparison sources
+
+Reviewed **2026-09-11**. Competitor versions are the npm `latest` dist-tag versions observed on that date,
+not prerelease versions or unreleased features from repository default branches. TypeDI refers to
+the `typedi` package maintained under TypeStack, not similarly named forks. NestJS's version is
+the version of `@nestjs/core`. The comparison uses Effect **3** documentation explicitly. Katagami 3.0.2 is this documentation
+release; its runtime and public APIs are unchanged from the reviewed 3.0.1 package.
+
+| Package | Reviewed version and registry metadata | Primary documentation / shipped API |
+| --- | --- | --- |
+| Katagami | [3.0.1](https://registry.npmjs.org/katagami/3.0.1) | [Type guarantees](./type-safety.md), [API guide](./guide.md) |
+| InversifyJS | [8.2.3](https://registry.npmjs.org/inversify/8.2.3) | [8.x setup](https://inversify.io/docs/introduction/getting-started/), [bindings](https://inversify.io/docs/fundamentals/binding/), [container API](https://inversify.io/docs/api/container/) |
+| tsyringe | [4.10.0](https://registry.npmjs.org/tsyringe/4.10.0) | [Release README](https://github.com/microsoft/tsyringe/blob/e033769d97cfb6cc4a8569e2b50eb32015453302/README.md), [container types](https://github.com/microsoft/tsyringe/blob/e033769d97cfb6cc4a8569e2b50eb32015453302/src/types/dependency-container.ts) |
+| TypeDI | [0.10.0](https://registry.npmjs.org/typedi/0.10.0) | [Release source](https://github.com/typestack/typedi/tree/v0.10.0), [container implementation](https://github.com/typestack/typedi/blob/v0.10.0/src/container-instance.class.ts) |
+| Awilix | [13.0.5](https://registry.npmjs.org/awilix/13.0.5) | [Release README](https://github.com/jeffijoe/awilix/blob/f72d175ddb950c3f13ef41e8be98b24471d59900/README.md), [container types/implementation](https://github.com/jeffijoe/awilix/blob/f72d175ddb950c3f13ef41e8be98b24471d59900/src/container.ts) |
+| NestJS | [12.0.1](https://registry.npmjs.org/@nestjs%2fcore/12.0.1) | [Providers](https://docs.nestjs.com/fundamentals/custom-providers), [scopes](https://docs.nestjs.com/fundamentals/injection-scopes), [async providers](https://docs.nestjs.com/fundamentals/async-providers), [lifecycle](https://docs.nestjs.com/fundamentals/lifecycle-events) |
+| Effect | [3.22.2](https://registry.npmjs.org/effect/3.22.2) | [v3 layers](https://effect.website/docs/v3/requirements-management/layers), [v3 scope](https://effect.website/docs/v3/resource-management/scope) |
+| typed-inject | [5.0.0](https://registry.npmjs.org/typed-inject/5.0.0) | [Release README](https://github.com/nicojs/typed-inject/blob/5d3c0276e65ade1d683239346488708b7a11e443/README.md), [injector types](https://github.com/nicojs/typed-inject/blob/5d3c0276e65ade1d683239346488708b7a11e443/src/api/Injector.ts) |
+
+Versioned npm tarballs were also inspected. A focused TypeScript 5.9.3 check confirmed that
+Awilix 13.0.5 infers registered cradle properties and rejects an unknown cradle property, while
+`resolve('missing')` still compiles through its broad overload. The same check confirmed that
+typed-inject 5.0.0 and Katagami 3.0.1 reject an unknown literal token, and that Awilix and
+typed-inject infer a Promise returned by a factory. This is a type check, not a performance benchmark
+or an exhaustive runtime compatibility test.
+
+## Reading the comparison
+
+### Registration types and scope restrictions
+
+A typed return value is different from proving that the container has a registration. InversifyJS,
+tsyringe and TypeDI expose class/generic-token APIs without accumulating the set of registered keys
+into the container's type. Awilix has both inferred cradle access and a broad string/symbol `resolve`
+overload. Its opt-in strict mode checks lifetime leaks at runtime. These observations come from the
+published APIs linked above, not from treating all of these libraries as “untyped.”
+
+NestJS handles request-scoped dependencies by propagating request scope up the dependency chain.
+That is a different policy from Katagami rejecting scoped access in a singleton factory. Effect's
+`Scope` requirement ensures resource acquisition has a scope; it does not use Katagami's
+singleton/transient/scoped categories. typed-inject has disposable child injectors, but its provider
+scope enum offers singleton and transient, not a separate scoped registration policy.
+
+### Setup and bundles
+
+Katagami, Awilix, Effect and typed-inject do not require decorator metadata for their DI APIs.
+The documented TypeScript class-injection paths for InversifyJS, tsyringe and TypeDI use metadata;
+explicit factory/value bindings should not be described as requiring decorators on every service.
+NestJS provides framework modules and metadata-based injection as well as custom providers.
+
+Katagami and typed-inject have no runtime dependency packages. TypeDI's manifest also has no
+`dependencies`, but its TypeScript setup asks the application to install `reflect-metadata`.
+Awilix's Node package lists `fast-glob`; its browser build excludes filesystem-based module loading.
+“No decorators” therefore does not mean “no dependency packages.”
+
+Katagami publishes ESM, CommonJS, subpath exports and `sideEffects: false`. Effect also exposes
+ESM/subpath exports and a side-effect declaration, and TypeDI declares `sideEffects: false`.
+The other libraries should not receive an automatic “no tree shaking” mark. Actual output size
+depends on the entry point, imports, bundler and application; no comparative bundle-size benchmark
+was run for this table.
+
+### Async and cleanup
+
+Katagami exposes `Promise<T>` for async factories: dependent factories explicitly await that value.
+Awilix, typed-inject and the generic factory/value APIs in tsyringe and TypeDI can also carry a
+Promise-valued service. This is different from InversifyJS's async resolution or NestJS's async
+providers, which await dependencies before constructing their consumers. Effect models acquisition
+as an effect. A binary “async factories: no” would conceal these distinctions.
+
+Katagami's `disposable()` owns container singletons or scope instances and calls disposal-symbol
+methods. Its [compatibility requirements](./guide.md#compatibility) still apply. InversifyJS has
+[singleton deactivation handlers](https://inversify.io/docs/fundamentals/lifecycle/deactivation/); tsyringe and typed-inject support disposable constructed instances;
+Awilix disposes cached scoped/singleton values through registered disposers. TypeDI can call
+`destroy()` during reset/removal but does not await its return. NestJS's application lifecycle hooks
+are not invoked for request-scoped classes. Effect scopes run registered finalizers. These are
+different ownership and shutdown models, not interchangeable cleanup guarantees.
+
+## Composition and tooling
+
+This table restores the broader feature comparison using concrete APIs. “Compose” means ordinary
+application code can implement the pattern; it does not claim a dedicated container feature.
+
+| Library | Optional / multiple resolution | Composition, discovery and extension |
+| --- | --- | --- |
+| Katagami | `tryResolve`, `resolveAll`, `tryResolveAll` | `use()` copies registrations; opt-in `lazy()`; ordinary higher-order factories |
+| InversifyJS | Optional get/inject, `getAll`, `getAllAsync` | Container modules/hierarchy, autobinding, contextual constraints, activation/deactivation, snapshot/restore |
+| tsyringe | Optional inject, `injectAll`, `resolveAll` | `@registry`, child containers, before/after resolution interceptors, `delay()` |
+| TypeDI | `has` before `get`; `getMany` with multiple registrations | Named containers, factory configuration and service decorators |
+| Awilix | `allowUnregistered`; compose collections as values/factories | `loadModules`, child scopes, local injections and proxy/classic injection |
+| NestJS | Optional injection/provider dependencies; compose array providers | Modules/dynamic modules, provider overrides, discovery service and lazy modules |
+| Effect | [`serviceOption`](https://effect.website/docs/v3/requirements-management/services#optional-services); compose collection-valued services | Layer composition, service substitution and scoped acquisition |
+| typed-inject | Required tokens checked statically; compose optional values/collections | Child injectors, provider replacement/decoration and explicit injection tuples |
+
+Katagami does not implement filesystem auto-discovery or snapshot/restore, and its runtime
+containers are mutable. `use()` and fresh test containers provide explicit composition and test
+substitution. Factory wrappers are an application pattern, not a middleware/interceptor API.
+Similarly, a lazy module loader is not the same feature as a proxy that constructs one service on
+first property access, and a resolution graph scope is not an HTTP request scope.
+
+Start with the [runnable starter](../examples/request-scope/README.md) and
+[composition guide](./guide.md#composition-and-test-substitution). For a project already built on
+NestJS or Effect, adopting its existing DI model can be simpler than maintaining a second container.
+
+## Updating the comparison
+
+Preserve a comparison and Katagami's supported advantages in the README when editing positioning.
+Refresh the date, npm dist-tag versions and official sources together. Check published declarations
+when a claim involves inference or registration guarantees, and distinguish built-in features from
+wrappers, configuration and framework behavior. Keep localized summaries aligned with the English
+comparison. Do not infer a feature's absence from its omission in a quick-start guide.

package/docs/growth/baseline-2026-09-11.json

@@ -0,0 +1,68 @@
+{
+	"collectedAt": "2026-09-11T10:53:46.834Z",
+	"package": "katagami",
+	"npm": {
+		"week": {
+			"downloads": 2,
+			"start": "2026-09-03",
+			"end": "2026-09-09",
+			"package": "katagami"
+		},
+		"month": {
+			"downloads": 109,
+			"start": "2026-08-11",
+			"end": "2026-09-09",
+			"package": "katagami"
+		},
+		"nonOverlappingWeeks": [
+			{
+				"start": "2026-07-16",
+				"end": "2026-07-22",
+				"downloads": 2
+			},
+			{
+				"start": "2026-07-23",
+				"end": "2026-07-29",
+				"downloads": 15
+			},
+			{
+				"start": "2026-07-30",
+				"end": "2026-08-05",
+				"downloads": 8
+			},
+			{
+				"start": "2026-08-06",
+				"end": "2026-08-12",
+				"downloads": 57
+			},
+			{
+				"start": "2026-08-13",
+				"end": "2026-08-19",
+				"downloads": 48
+			},
+			{
+				"start": "2026-08-20",
+				"end": "2026-08-26",
+				"downloads": 15
+			},
+			{
+				"start": "2026-08-27",
+				"end": "2026-09-02",
+				"downloads": 14
+			},
+			{
+				"start": "2026-09-03",
+				"end": "2026-09-09",
+				"downloads": 2
+			}
+		]
+	},
+	"github": {
+		"stars": 4,
+		"forks": 0,
+		"topics": [],
+		"homepage": null,
+		"pushedAt": "2026-02-09T11:30:14Z"
+	},
+	"errors": []
+}

package/docs/growth/github-metadata.json

@@ -0,0 +1,13 @@
+{
+	"description": "Type-safe dependency injection for TypeScript, with inferred types and scope checks for AI-assisted development. No decorators or reflect-metadata.",
+	"homepage": "https://github.com/hiroiku/katagami#readme",
+	"topics": [
+		"typescript",
+		"dependency-injection",
+		"di-container",
+		"type-safety",
+		"type-inference",
+		"ai-assisted-development",
+		"coding-agents"
+	]
+}

package/docs/growth/rollout.md

@@ -0,0 +1,77 @@
+# Katagami discovery and adoption rollout
+
+## Positioning and audience
+
+Type-safe dependency injection for TypeScript, with compiler feedback for AI-assisted development.
+The first audience is developers building a new TypeScript application with coding agents who need
+explicit dependency wiring, fake injection or request state. Avoid forcing a container into tiny apps.
+
+## Release assets
+
+- English and seven localized README entry points.
+- npm description/keywords and [GitHub metadata](./github-metadata.json).
+- [AI guide](../ai-coding-agents.md), [type guarantees](../type-safety.md), [API guide](../guide.md).
+- [Runnable starter](../../examples/request-scope/README.md) with checked examples.
+- [AI coding article](../articles/ai-coding-agents.md), [request scopes](../articles/request-scope.md),
+  [decorator-free DI](../articles/without-decorators.md) and a [Japanese Zenn draft](../articles/ai-coding-agents.ja.md).
+- [Evaluation protocol](../../benchmarks/agent-wiring/README.md) and results summarizer; agent benefits remain unmeasured.
+
+## First four weeks
+
+| Period | Action | Evidence to retain |
+| --- | --- | --- |
+| Week 1 | Ship checks, README, package metadata and starter; update GitHub Topics | Released version, CI run and public metrics snapshot |
+| Week 2 | Publish the worked-example article on the owner's chosen blog/Zenn account; adapt relative links to the published location | URL, date, channel and campaign label |
+| Weeks 3–4 | Observe 3–5 willing developers using the starter with their usual agent | Task attempted, first-run outcome, diagnostic confusion, whether they keep using it |
+| Weekly | Capture npm trends and, locally, owner-only repository traffic | Non-overlapping date ranges and unavailable data recorded as null |
+| After four weeks | Compare the funnel and fix the largest observed obstacle | Evidence for discovery, first successful use, continued use; no attribution from downloads alone |
+
+Publishing destinations and interview participants are selected by the owner. The article files
+are ready for adaptation, but an external publication or a participant interview must be recorded
+only after it actually happens. Do not post or message people without authorization for that destination.
+
+## Collect metrics
+
+```sh
+bun run metrics --output metrics.local/public.json
+bun run metrics --traffic --output metrics.local/owner-traffic.json
+```
+
+The second command requires authenticated owner access through `gh` and contains private traffic
+data. `metrics.local/` is ignored by Git. Do not commit those snapshots. Public release baselines can
+be recorded separately under this directory. Re-run weekly: GitHub traffic is a short rolling window.
+
+Track npm totals across four weeks using the non-overlapping weekly buckets, then compare with
+the preceding four weeks. Downloads are not unique users or installations and can include automation.
+Traffic, clones and external adoption reports provide different evidence; none alone is a conversion rate.
+Where the chosen publication platform supports it, use a per-channel campaign link to a page with
+analytics. GitHub alone does not provide complete visit-to-install attribution.
+
+## Interview script
+
+Ask a consenting participant to add a service and a fake to the starter using their normal agent.
+Observe rather than coach the first attempt. Record:
+
+1. What made the package seem relevant, and what almost stopped installation?
+2. Did the first run work? Which command or prerequisite was unclear?
+3. Could the agent fix a missing registration and an incorrect scope without suppressions?
+4. Were error messages actionable? Which documentation did the participant or agent actually read?
+5. Would the participant use it in a real project? Follow up on continued use with their consent.
+
+Record observations without names or private code unless the participant agrees. A suggested
+invitation, for an owner-approved channel:
+
+> TypeScriptのDIコンテナKatagamiの導入体験を改善しています。普段使っているAIエージェントで
+> 小さなサンプルにサービスとテスト用の依存を追加する、20分ほどの試用に協力いただける方を探しています。
+> うまく動かない点や分かりにくい点を知りたいです。公開コードだけで参加できます。
+
+## Search and claim hygiene
+
+Keep the description specific to dependency injection. Link guides from the README and use actual
+examples for queries about AI coding agents, request scopes and DI without decorators. `llms.txt`
+is a navigation aid, not a promised ranking boost.
+
+Sources: [npm discovery metadata](https://docs.npmjs.com/files/package.json/),
+[npm README publication](https://docs.npmjs.com/about-package-readme-files/),
+[GitHub Topics](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics),
+[Google AI search guidance](https://developers.google.com/search/docs/appearance/ai-features).