katagami 3.0.0 → 3.0.1

package/docs/README.de.md

@@ -0,0 +1,65 @@
+[English](../README.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [Español](./README.es.md) | [Deutsch](./README.de.md) | [Français](./README.fr.md)
+
+# Katagami
+
+**Typsichere Dependency Injection für TypeScript.**
+
+Mache Abhängigkeiten explizit und prüfbar, auch wenn KI-Coding-Agenten den Code schreiben. Katagami sammelt Typen mit jeder Registrierung, prüft die in einer Factory verfügbaren Tokens und verfolgt asynchrone Rückgaben. Ohne Decorators, reflect-metadata oder Laufzeitabhängigkeiten.
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## Schnellstart
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## Mit KI-Coding-Agenten arbeiten
+
+Der Agent ändert die Abhängigkeiten, führt den TypeScript-Checker aus und korrigiert den Code anhand der Diagnosen. Explizite Factories zeigen Abhängigkeiten als gewöhnlichen TypeScript-Code.
+
+Wenn eine Singleton-Factory auf Scoped-Zustand einer Anfrage zugreift, entsteht beispielsweise ein Typfehler.
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+Registriere handler in diesem Beispiel mit registerScoped. @ts-expect-error prüft das fehlerhafte Beispiel in CI. Korrigiere im Anwendungscode die Lebensdauer und führe npx tsc --noEmit aus, statt den Fehler zu unterdrücken.
+
+## Gesammelte Typen und Garantien
+
+createContainer() sammelt Typen aus Registrierungen. Solange Literalschlüssel und unique-symbol-Typen erhalten bleiben, werden Tokens außerhalb der sichtbaren Registrierungen abgelehnt. Eine manuelle Service-Typzuordnung ist nicht nötig.
+
+Klassentokens folgen struktureller Typisierung: Eine andere kompatible Klasse kann akzeptiert werden. Ein in createContainer<Services>() deklarierter Schlüssel ist ebenfalls im Typ sichtbar, auch ohne tatsächliche Registrierung.
+
+Unterstützt Singleton, Transient und Scoped, Modulkomposition mit use(), asynchrone Factories, optionale und mehrfache Auflösung, Ressourcenfreigabe und verzögerte Auflösung. Bei wenigen Abhängigkeiten reichen oft normale Parameter.
+
+## Anleitungen und ausführbares Beispiel
+
+- [Anleitung für KI-Agenten (Englisch)](./ai-coding-agents.md)
+- [Typgarantien (Englisch)](./type-safety.md)
+- [API und Anwendung (Englisch)](./guide.md)
+- [Starter für Anfrage-Scopes (Englisch)](../examples/request-scope/README.md)
+- [DI auswählen (Englisch)](./choosing-di.md)
+
+CI prüft Typbeispiele und Laufzeittests. Verbesserungen der Reparaturquote von Agenten oder Token-Einsparungen wurden noch nicht gemessen.
+
+Der Name stammt von 型紙, den Papierschablonen der traditionellen japanischen Färberei. Typen sammeln sich wie übereinandergelegte Schablonen.
+
+MIT

package/docs/README.es.md

@@ -0,0 +1,65 @@
+[English](../README.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [Español](./README.es.md) | [Deutsch](./README.de.md) | [Français](./README.fr.md)
+
+# Katagami
+
+**Inyección de dependencias con seguridad de tipos para TypeScript.**
+
+Haz explícitas y verificables las dependencias, incluso cuando el código lo escriben agentes de IA. Katagami acumula tipos con cada registro, comprueba los tokens accesibles en cada fábrica y conserva los resultados asíncronos. Sin decoradores, reflect-metadata ni dependencias en tiempo de ejecución.
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## Inicio rápido
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## Uso con agentes de programación de IA
+
+El agente modifica las dependencias, ejecuta el comprobador de TypeScript y corrige el código a partir de los diagnósticos. Las fábricas explícitas muestran las dependencias en código TypeScript normal.
+
+Por ejemplo, acceder a un estado Scoped desde una fábrica Singleton produce un error de tipos.
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+En este ejemplo, registra handler con registerScoped. @ts-expect-error verifica el ejemplo incorrecto en CI; en la aplicación, corrige el ciclo de vida y ejecuta npx tsc --noEmit sin suprimir el error.
+
+## Tipos acumulados y garantías
+
+createContainer() acumula los tipos de los registros. Si se conservan las claves literales y los tipos unique symbol, se rechazan los tokens fuera del conjunto visible de registros. No hace falta un mapa manual de servicios.
+
+Los tokens de clase siguen el tipado estructural: otra clase compatible puede ser aceptada. Una clave declarada en createContainer<Services>() también puede estar disponible en los tipos sin tener un registro real.
+
+Incluye ciclos de vida Singleton, Transient y Scoped, composición con use(), fábricas asíncronas, resolución opcional y múltiple, limpieza de recursos y resolución diferida. Para pocas dependencias, los parámetros normales pueden ser suficientes.
+
+## Guías y ejemplo ejecutable
+
+- [Guía para agentes de IA (inglés)](./ai-coding-agents.md)
+- [Garantías de tipos (inglés)](./type-safety.md)
+- [Guía de uso y API (inglés)](./guide.md)
+- [Ejemplo de ámbitos por petición (inglés)](../examples/request-scope/README.md)
+- [Cómo elegir DI (inglés)](./choosing-di.md)
+
+CI comprueba los ejemplos de tipos y las pruebas de ejecución. No se han medido mejoras en la tasa de reparación de agentes ni ahorro de tokens.
+
+El nombre viene de 型紙, las plantillas de papel de la tintura tradicional japonesa. Los tipos se acumulan como capas de plantillas.
+
+MIT

package/docs/README.fr.md

@@ -0,0 +1,65 @@
+[English](../README.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [Español](./README.es.md) | [Deutsch](./README.de.md) | [Français](./README.fr.md)
+
+# Katagami
+
+**Injection de dépendances avec sûreté des types pour TypeScript.**
+
+Rendez les dépendances explicites et vérifiables, même quand des agents de programmation IA écrivent le code. Katagami accumule les types à chaque enregistrement, vérifie les jetons accessibles aux fabriques et suit les retours asynchrones. Sans décorateurs, reflect-metadata ni dépendances à l’exécution.
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## Démarrage rapide
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## Travailler avec des agents de programmation IA
+
+L’agent modifie les dépendances, exécute le vérificateur TypeScript, puis corrige le code à partir des diagnostics. Les fabriques explicites rendent les dépendances visibles dans du code TypeScript ordinaire.
+
+Par exemple, accéder à un état Scoped depuis une fabrique Singleton produit une erreur de type.
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+Dans cet exemple, enregistrez handler avec registerScoped. @ts-expect-error sert à vérifier l’exemple incorrect en CI. Dans l’application, corrigez la durée de vie et lancez npx tsc --noEmit sans masquer l’erreur.
+
+## Types accumulés et garanties
+
+createContainer() accumule les types des enregistrements. En conservant les clés littérales et les types unique symbol, les jetons absents de l’ensemble visible sont rejetés. Aucune table manuelle des types de services n’est nécessaire.
+
+Les jetons de classe suivent le typage structurel : une autre classe compatible peut être acceptée. Une clé déclarée dans createContainer<Services>() peut aussi être visible dans les types sans enregistrement réel.
+
+Prend en charge Singleton, Transient et Scoped, la composition avec use(), les fabriques asynchrones, la résolution optionnelle et multiple, la libération des ressources et la résolution différée. Pour peu de dépendances, des paramètres ordinaires peuvent suffire.
+
+## Guides et exemple exécutable
+
+- [Guide pour agents IA (anglais)](./ai-coding-agents.md)
+- [Garanties de types (anglais)](./type-safety.md)
+- [Guide et API (anglais)](./guide.md)
+- [Exemple de portée par requête (anglais)](../examples/request-scope/README.md)
+- [Choisir une approche DI (anglais)](./choosing-di.md)
+
+Les exemples de types et les tests d’exécution sont vérifiés en CI. Les gains de réussite des agents ou de consommation de tokens n’ont pas encore été mesurés.
+
+Le nom vient de 型紙, les pochoirs de papier de la teinture traditionnelle japonaise. Les types s’accumulent comme des couches de pochoirs.
+
+MIT

package/docs/README.ja.md

@@ -0,0 +1,66 @@
+[English](../README.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [Español](./README.es.md) | [Deutsch](./README.de.md) | [Français](./README.fr.md)
+
+# Katagami
+
+**TypeScriptの型安全な依存性注入（DI）コンテナ。**
+
+AIエージェントが書くコードでも、依存関係の配線を明示し、型で検証できます。Katagamiは登録するたびに型が自動的に積み上がり、ファクトリから参照できる依存と非同期の戻り値を追跡します。デコレータ・reflect-metadata・ランタイム依存パッケージは不要です。
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## クイックスタート
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## AIエージェントによるコーディングで役立つ理由
+
+エージェントが依存関係を変更し、TypeScriptの型チェックを実行し、診断をもとに修正する。この手順に、登録漏れやライフタイムの誤用を検出する具体的なチェックを組み込めます。依存関係は通常のTypeScriptのファクトリとして記述します。
+
+例えば、リクエスト固有の状態をSingletonのファクトリから解決しようとすると、型エラーになります。
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+この例では、handlerもregisterScopedで登録すると解決できます。@ts-expect-errorは失敗例をCIで検証するための注記です。実際のアプリではエラーを抑制せず、ライフタイムを修正してnpx tsc --noEmitを実行します。
+
+## 型の蓄積方式と保証範囲
+
+デフォルトのcreateContainer()では、登録から型が積み上がります。リテラルキーやunique symbolの型を保てば、見えている登録集合に含まれないトークンは型エラーになります。事前にサービスの型マップを書く必要はありません。
+
+クラストークンにはTypeScriptの構造的型付けが適用されるため、同じ構造の別クラスを区別できない場合があります。また、createContainer<Services>()で事前宣言したキーは、未登録でも型として見えるようになります。この2つは蓄積方式の通常の登録チェックとは分けて説明しています。
+
+Singleton・Transient・Scoped、use()によるモジュール合成、非同期ファクトリ、複数・オプショナル解決、リソース破棄、遅延解決をサポートします。依存が少ない場合は、通常の引数やコンストラクタによる受け渡しでも十分です。
+
+## ガイドと実行可能な例
+
+- [AIコーディングガイド（英語）](./ai-coding-agents.md)
+- [型の保証範囲（英語）](./type-safety.md)
+- [API・利用ガイド（英語）](./guide.md)
+- [リクエストスコープのスターター（英語）](../examples/request-scope/README.md)
+- [DIの選び方（英語）](./choosing-di.md)
+- [AIと型に関する日本語記事](./articles/ai-coding-agents.ja.md)
+
+サンプルの型チェックと実行テストはCIで検証します。AIの修正成功率やトークン削減効果は未測定であり、性能向上の数値は主張していません。
+
+名前の由来は、伝統的な染色で模様を写す「型紙」です。型紙を重ねるように、登録ごとに型が積み上がります。
+
+MIT

package/docs/README.ko.md

@@ -0,0 +1,65 @@
+[English](../README.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [Español](./README.es.md) | [Deutsch](./README.de.md) | [Français](./README.fr.md)
+
+# Katagami
+
+**TypeScript를 위한 타입 안전한 의존성 주입(DI) 컨테이너.**
+
+AI 코딩 에이전트가 작성한 코드에서도 의존 관계를 명시하고 타입으로 검사하세요. Katagami는 등록할 때마다 타입을 누적하고, 팩터리에서 접근 가능한 토큰과 비동기 반환값을 추적합니다. 데코레이터, reflect-metadata, 런타임 의존 패키지가 필요하지 않습니다.
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## 빠른 시작
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## AI 코딩 에이전트와 함께 사용하기
+
+에이전트가 의존 관계를 수정하고 TypeScript 검사기를 실행한 뒤 진단에 따라 수정하는 흐름을 만듭니다. 팩터리에 의존 관계가 일반 TypeScript 코드로 드러납니다.
+
+예를 들어 Singleton 팩터리에서 요청별 Scoped 상태를 참조하면 타입 오류가 발생합니다.
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+handler를 registerScoped로 등록하면 이 오류를 해결할 수 있습니다. @ts-expect-error는 실패 예제를 검증하기 위한 것입니다. 앱에서는 오류를 억제하지 말고 수명을 수정한 뒤 npx tsc --noEmit을 실행하세요.
+
+## 누적 타입과 보장 범위
+
+기본 createContainer()는 등록에서 타입을 누적합니다. 리터럴 키와 unique symbol 타입을 유지하면, 현재 보이는 등록 집합에 없는 토큰은 거부됩니다. 별도의 서비스 타입 맵은 필요하지 않습니다.
+
+클래스 토큰은 구조적 타이핑을 따르므로 구조가 같은 다른 클래스가 허용될 수 있습니다. createContainer<Services>()에 미리 선언한 키 역시 실제 등록이 없어도 타입에 나타납니다.
+
+Singleton, Transient, Scoped 수명, use() 모듈 합성, 비동기 팩터리, 선택적·다중 해석, 리소스 정리 및 지연 해석을 지원합니다. 의존성이 적다면 일반 함수나 생성자 매개변수로 충분할 수 있습니다.
+
+## 가이드와 실행 가능한 예제
+
+- [AI 코딩 가이드 (영어)](./ai-coding-agents.md)
+- [타입 보장 범위 (영어)](./type-safety.md)
+- [API와 사용 가이드 (영어)](./guide.md)
+- [요청 스코프 스타터 (영어)](../examples/request-scope/README.md)
+- [DI 선택 가이드 (영어)](./choosing-di.md)
+
+타입 예제와 실행 테스트는 CI에서 검사합니다. AI 수정 성공률이나 토큰 절감 효과는 아직 측정하지 않았습니다.
+
+이름은 일본 전통 염색의 형지인 型紙에서 왔습니다. 형지를 겹치듯 등록마다 타입이 누적됩니다.
+
+MIT

package/docs/README.zh-CN.md

@@ -0,0 +1,65 @@
+[English](../README.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [Español](./README.es.md) | [Deutsch](./README.de.md) | [Français](./README.fr.md)
+
+# Katagami
+
+**适用于 TypeScript 的类型安全依赖注入（DI）容器。**
+
+即使代码由 AI 编程智能体编写，也能显式描述依赖关系并进行类型检查。Katagami 随注册逐步累积类型，检查工厂可访问的依赖，并追踪异步返回值。无需装饰器、reflect-metadata 或运行时依赖包。
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## 快速开始
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## 配合 AI 编程智能体使用
+
+让智能体修改依赖关系，运行 TypeScript 检查，再根据诊断修复。显式工厂让依赖关系直接体现在普通 TypeScript 代码中。
+
+例如，Singleton 工厂访问请求级 Scoped 状态时，会出现类型错误。
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+将 handler 改为 registerScoped 即可修正此例。@ts-expect-error 用于在 CI 中验证失败示例。在应用中应修正生命周期，而非抑制错误，然后运行 npx tsc --noEmit。
+
+## 类型累积与保证范围
+
+默认的 createContainer() 从注册中累积类型。保留字面量键或 unique symbol 类型时，当前可见注册集合之外的令牌会被拒绝，无需手写服务类型映射。
+
+类令牌遵循结构类型规则，因此可能接受结构相同的另一个类。通过 createContainer<Services>() 预先声明的键，即使没有实际注册，也会出现在类型中。
+
+支持 Singleton、Transient、Scoped 生命周期、use() 模块组合、异步工厂、可选及多重解析、资源清理和延迟解析。依赖较少时，普通函数或构造函数参数可能已经足够。
+
+## 指南与可运行示例
+
+- [AI 编程指南（英语）](./ai-coding-agents.md)
+- [类型保证范围（英语）](./type-safety.md)
+- [API 与使用指南（英语）](./guide.md)
+- [请求作用域入门示例（英语）](../examples/request-scope/README.md)
+- [DI 选型指南（英语）](./choosing-di.md)
+
+类型示例及运行测试由 CI 验证。尚未测量 AI 修复成功率或令牌节省效果。
+
+名称来自日本传统染色中使用的“型纸”。如同叠加型纸，类型也随注册逐步累积。
+
+MIT

package/docs/README.zh-TW.md

@@ -0,0 +1,65 @@
+[English](../README.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [Español](./README.es.md) | [Deutsch](./README.de.md) | [Français](./README.fr.md)
+
+# Katagami
+
+**適用於 TypeScript 的型別安全依賴注入（DI）容器。**
+
+即使程式碼由 AI 程式設計代理撰寫，也能明確描述依賴關係並進行型別檢查。Katagami 隨註冊逐步累積型別，檢查工廠可存取的依賴，並追蹤非同步回傳值。不需要裝飾器、reflect-metadata 或執行階段依賴套件。
+
+[![npm version](https://img.shields.io/npm/v/katagami)](https://www.npmjs.com/package/katagami)
+
+```sh
+npm install katagami
+```
+
+## 快速開始
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('name', () => 'Ada')
+  .registerScoped('greeting', r => `Hello, ${r.resolve('name')}!`);
+
+const greeting: string = createScope(container).resolve('greeting');
+console.log(greeting);
+```
+
+## 與 AI 程式設計代理搭配使用
+
+讓代理修改依賴關係，執行 TypeScript 檢查，再根據診斷修正。明確的工廠讓依賴關係直接呈現在一般 TypeScript 程式碼中。
+
+例如，Singleton 工廠存取請求層級的 Scoped 狀態時，會出現型別錯誤。
+
+```ts
+import { createContainer } from 'katagami';
+
+createContainer()
+  .registerScoped('request', () => ({ id: crypto.randomUUID() }))
+  // @ts-expect-error — singleton factories cannot access scoped tokens
+  .registerSingleton('handler', r => r.resolve('request'));
+```
+
+將 handler 改為 registerScoped 即可修正此例。@ts-expect-error 用於在 CI 中驗證失敗範例。在應用程式中應修正生命週期，而非抑制錯誤，再執行 npx tsc --noEmit。
+
+## 型別累積與保證範圍
+
+預設的 createContainer() 從註冊中累積型別。保留字面值鍵或 unique symbol 型別時，目前可見註冊集合以外的權杖會被拒絕，不需要手寫服務型別映射。
+
+類別權杖遵循結構型別規則，因此可能接受結構相同的另一個類別。透過 createContainer<Services>() 預先宣告的鍵，即使沒有實際註冊，也會出現在型別中。
+
+支援 Singleton、Transient、Scoped 生命週期、use() 模組組合、非同步工廠、可選及多重解析、資源清理與延遲解析。依賴較少時，一般函式或建構子參數可能已經足夠。
+
+## 指南與可執行範例
+
+- [AI 程式設計指南（英文）](./ai-coding-agents.md)
+- [型別保證範圍（英文）](./type-safety.md)
+- [API 與使用指南（英文）](./guide.md)
+- [請求範圍入門範例（英文）](../examples/request-scope/README.md)
+- [DI 選型指南（英文）](./choosing-di.md)
+
+型別範例與執行測試由 CI 驗證。尚未測量 AI 修正成功率或 token 節省效果。
+
+名稱來自日本傳統染色使用的「型紙」。如同疊加型紙，型別也隨註冊逐步累積。
+
+MIT

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)から、基本例と利用ガイドを読めます。