katagami 2.3.0 → 3.0.1

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).

package/docs/guide.md

@@ -0,0 +1,186 @@
+# Katagami usage guide and API
+
+## Compatibility
+
+Katagami publishes ESM, CommonJS and TypeScript declarations, with no runtime dependencies.
+The CI consumer checks run on Node.js 22 and 24; runtime tests and examples also run with Bun.
+Type examples use TypeScript 5.9, `strict: true`, and the `ES2022` and `ESNext.Disposable` libraries.
+Browser APIs in examples, such as `crypto.randomUUID`, additionally need the `DOM` library.
+
+Core DI does not require decorator compiler flags, metadata emission or polyfills.
+The optional disposable entry point uses `Symbol.dispose` / `Symbol.asyncDispose`; the runtime
+must supply those symbols. `await using` requires a compiler/runtime that supports or transforms it.
+Katagami does not provide those polyfills. `lazy` uses JavaScript `Proxy`.
+
+## Lifetimes
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const container = createContainer()
+  .registerSingleton('shared', () => ({ value: 0 }))
+  .registerTransient('fresh', () => ({ value: 0 }))
+  .registerScoped('request', () => ({ value: 0 }));
+
+const first = createScope(container);
+const second = createScope(container);
+first.resolve('shared') === second.resolve('shared'); // true
+first.resolve('request') === first.resolve('request'); // true
+first.resolve('request') === second.resolve('request'); // false
+first.resolve('fresh') === first.resolve('fresh'); // false
+```
+
+Factories run when first resolved; transient factories run on each resolution.
+Use `createScope(existingScope)` for another scope with its own scoped cache and shared singletons.
+Singleton and transient factories cannot directly resolve scoped registrations through their typed resolver.
+
+## Class tokens and async factories
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+class Database {
+  query() { return ['Ada']; }
+}
+class UserService {
+  constructor(private db: Database) {}
+  list() { return this.db.query(); }
+}
+
+const container = createContainer()
+  .registerSingleton(Database, async () => new Database())
+  .registerScoped(UserService, async r => new UserService(await r.resolve(Database)));
+
+const service = await createScope(container).resolve(UserService);
+service.list();
+```
+
+Class return types are inferred from constructors. Classes follow TypeScript's structural typing;
+see [token identity](./type-safety.md#class-tokens-use-structural-typing).
+Async factories produce Promise-typed resolutions. Await them explicitly.
+
+## Composition and test substitution
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const infrastructure = createContainer()
+  .registerSingleton('users', () => ({ find: (id: string) => `user-${id}` }));
+const fakeInfrastructure = createContainer()
+  .registerSingleton('users', () => ({ find: (id: string) => `fake-${id}` }));
+
+const testContainer = createContainer()
+  .use(infrastructure)
+  .use(fakeInfrastructure)
+  .registerScoped('handler', r => (id: string) => r.resolve('users').find(id));
+
+createScope(testContainer).resolve('handler')('1'); // fake-1
+```
+
+`use(source)` copies registration entries and replaces entries for matching tokens. It does not
+share the source's singleton cache. Containers are mutable: `register*` and `use` update the container
+and return it with accumulated types. Build the composition before creating or resolving scopes.
+Preserve each token's value type and lifetime when substituting registrations.
+
+## Optional and multiple resolution
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const scope = createScope(createContainer()
+  .registerSingleton('plugin', () => 'first')
+  .registerSingleton('plugin', () => 'second'));
+
+scope.resolve('plugin'); // 'second'
+scope.resolveAll('plugin'); // ['first', 'second']
+scope.tryResolve('optional'); // undefined
+scope.tryResolveAll('optional'); // undefined
+```
+
+Repeated `register*` calls accumulate factories for a token. `resolve` selects the last;
+`resolveAll` returns an array in registration order. For async factories, the array contains promises;
+use `Promise.all`. Keep one consistent value type and lifetime for a token.
+`tryResolve` and `tryResolveAll` accept missing tokens intentionally. They still report circular
+dependencies and operations on disposed scopes.
+
+## Resource cleanup
+
+```ts
+import { createContainer, createScope } from 'katagami';
+import { disposable } from 'katagami/disposable';
+
+const container = createContainer().registerScoped('connection', () => ({
+  query: () => 'ok',
+  [Symbol.dispose]() { console.log('connection closed'); },
+}));
+
+{
+  await using scope = disposable(createScope(container));
+  scope.resolve('connection').query();
+} // the scoped connection is disposed here
+```
+
+`disposable(containerOrScope)` returns a view with `[Symbol.asyncDispose]()` and hides registration
+methods. Disposable scopes retain resolution methods. `createScope` accepts either disposable view
+and retains its registered token types.
+
+Scope disposal cleans its cached scoped instances; container disposal cleans its singleton cache.
+Instances are processed in reverse cache insertion order, asynchronous results are awaited, and
+cleanup errors are combined in an `AggregateError`. Disposal is idempotent. Transient instances
+are not cached or automatically owned: arrange their cleanup explicitly.
+
+## Lazy resolution
+
+```ts
+import { createContainer, createScope } from 'katagami';
+import { lazy } from 'katagami/lazy';
+
+class Report { render() { return 'report'; } }
+const scope = createScope(createContainer().registerSingleton(Report, () => new Report()));
+const report = lazy(scope, Report);
+report.render(); // resolves on first access
+```
+
+`lazy` accepts synchronous class tokens on a scope or disposable scope. It does not accept async
+or PropertyKey tokens. Core imports do not include the lazy or disposable implementation; these
+are separate entry points with `sideEffects: false` for bundlers.
+
+## Predeclared service maps
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+interface Services {
+  greeting: string;
+  name: string;
+}
+const container = createContainer<Services>()
+  .registerSingleton('greeting', r => `Hello, ${r.resolve('name')}`)
+  .registerSingleton('name', () => 'Ada');
+
+createScope(container).resolve('greeting');
+```
+
+The first generic defines non-scoped PropertyKey tokens; the second defines scoped PropertyKey tokens.
+Maps permit forward references. They do not verify that each declared key has a registration.
+Default accumulated registration provides the registration-order checks described in the
+[type-safety guide](./type-safety.md).
+
+## API reference
+
+| API | Behavior |
+| --- | --- |
+| `createContainer<T, ScopedT>()` | Create a registration container; omit type maps to infer them by chaining |
+| `registerSingleton(token, factory)` | Register a shared, cached factory |
+| `registerTransient(token, factory)` | Register a factory called on every resolution |
+| `registerScoped(token, factory)` | Register a factory cached per scope |
+| `use(source)` | Copy another container's registrations, replacing matching token entries |
+| `createScope(source)` | Create a scope from a container, scope or disposable view |
+| `scope.resolve(token)` | Resolve the last registration; fail if missing |
+| `scope.resolveAll(token)` | Resolve every registration for a token |
+| `scope.tryResolve(token)` | Resolve the last registration or return `undefined` |
+| `scope.tryResolveAll(token)` | Resolve all registrations or return `undefined` |
+| `disposable(source)` from `katagami/disposable` | Add async cleanup and return a restricted view |
+| `lazy(scope, classToken)` from `katagami/lazy` | Defer synchronous resolution until first access |
+| `ContainerError` | Runtime error for missing registrations, cycles and invalid scope operations |
+| `Resolver` (type export) | Factory resolver type; retain inferred generics when extracting factories |

package/docs/type-safety.md

@@ -0,0 +1,126 @@
+# Type-safe dependency injection: what Katagami checks
+
+Katagami's default `createContainer()` accumulates types from registrations. With literal keys
+or unique symbols preserved, a resolver can only accept tokens accumulated into its visible
+registration set. No separate service interface is required. Run TypeScript with `strict: true`.
+
+## Accumulated registrations
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+const DATABASE = Symbol('database');
+const OTHER_DATABASE = Symbol('database');
+const container = createContainer()
+  .registerSingleton(DATABASE, () => ({ query: () => 'ok' }))
+  .registerSingleton('greeting', () => 'hello');
+
+const scope = createScope(container);
+const greeting: string = scope.resolve('greeting');
+scope.resolve(DATABASE).query();
+// @ts-expect-error — this literal key has not been accumulated
+scope.resolve('missing');
+// @ts-expect-error — the same description does not make two symbols identical
+scope.resolve(OTHER_DATABASE);
+```
+
+Inside a factory, the visible set is the set accumulated **before that registration**.
+Singleton and transient factories receive the non-scoped set. Scoped factories receive both sets.
+Scopes can resolve both. `use()` includes the source module's registration types.
+`disposable()` and nested scopes retain the registration state, including asynchronous results.
+
+| Pattern | Compile-time behavior |
+| --- | --- |
+| Unregistered literal key / distinct unique symbol in accumulated mode | Rejected |
+| A structurally incompatible, unregistered class | Rejected |
+| Scoped literal token in a singleton or transient factory | Rejected |
+| Accessing a service method on an unresolved `Promise<Service>` | Rejected |
+| A key declared in `createContainer<Services>()`, but never registered | Accepted; runtime resolution can fail |
+| An unregistered class structurally compatible with a registered class | Can be accepted; runtime resolution can fail |
+| `tryResolve` of an unregistered token | Intentionally accepted; absence is a normal result |
+
+The checked examples and regression tests establish these specific behaviors. They do not prove
+arbitrary program correctness or an improvement in AI coding performance.
+
+## Class tokens use structural typing
+
+Accumulating a class type does not give TypeScript a nominal identity for each constructor.
+The following compiles in accumulated mode, but throws `ContainerError` if executed:
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+class Registered { value = 1; }
+class NotRegistered { value = 1; }
+
+const scope = createScope(createContainer()
+  .registerSingleton(Registered, () => new Registered()));
+
+scope.resolve(NotRegistered); // Same structure to TypeScript; different runtime Map key
+```
+
+This includes empty classes and can include subclasses. TypeScript checks compatibility;
+the runtime registry checks token identity. When that distinction matters, use unique symbols
+or literal keys, or distinguish class types with separate private member declarations:
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+class Registered {
+  declare private brand: undefined;
+  value = 1;
+}
+class NotRegistered {
+  declare private brand: undefined;
+  value = 1;
+}
+
+const scope = createScope(createContainer()
+  .registerSingleton(Registered, () => new Registered()));
+// @ts-expect-error — these separately declared private members make the types incompatible
+scope.resolve(NotRegistered);
+```
+
+See [TypeScript's type compatibility documentation](https://www.typescriptlang.org/docs/handbook/type-compatibility).
+
+## Predeclared interface maps
+
+`createContainer<Services>()` starts with the declared keys already visible. This enables
+order-independent registration, but that type map is a declaration of intent, not a proof
+that every key has a runtime factory:
+
+```ts
+import { createContainer, createScope } from 'katagami';
+
+interface Services { greeting: string; }
+const scope = createScope(createContainer<Services>());
+scope.resolve('greeting'); // Compiles, but throws if executed: no factory was registered
+```
+
+Prefer default accumulated registration when you want registration-order checks.
+Use a predeclared map when order independence is useful and verify the composition in runtime tests.
+
+## Preserve the information the checker needs
+
+- Keep literal tokens narrow. A token widened to `string`, or a broad index signature, loses the finite key set.
+- Keep the return value of each registration chain. Do not replace its inferred type with a broader annotation.
+- Keep a token's value type and lifetime consistent across registrations and `use()` replacements.
+  Katagami is mutable at runtime; arbitrary mutation through aliases is not proven safe by the accumulated type.
+- Use the factory's supplied resolver. Closures over another scope can bypass its lifetime restrictions.
+- Fix the dependency or lifetime; `any`, assertions and suppressions can bypass TypeScript checks.
+- `tryResolve` is for optional dependencies, not a workaround for required registration errors.
+
+## Runtime checks and limits
+
+Runtime checks report missing registrations, disposed scopes and circular resolution paths.
+The captive-dependency guard detects scoped resolution in an active singleton call chain,
+including indirect synchronous calls. It does not prove all lifetime relationships: in particular,
+do not rely on it for work resumed after an `await` or for dependencies captured from another scope.
+Use the typed factory API and runtime tests together.
+
+## Verification
+
+`bun run typecheck` runs the original type tests and the guarantee regressions in
+`src/container/guarantees/typetest.ts`. Negative checks use `@ts-expect-error`, so a previously
+rejected expression becoming accepted makes the check fail. These files are not runtime examples.
+`bun run docs:check` type-checks every TypeScript fence in the maintained Markdown documentation.

package/examples/request-scope/README.md

@@ -0,0 +1,37 @@
+# TypeScript request scopes without decorators
+
+A small starter for an HTTP handler, CLI, or worker: inject a user repository,
+create isolated state for each request, and dispose that state after success or failure.
+It uses Katagami's accumulated literal tokens; no token-to-type interface is needed.
+
+Copy `app.ts`, `demo.ts`, and `tsconfig.json` into a new directory, then run:
+
+```sh
+npm init -y
+npm pkg set type=module
+npm install katagami
+npm install --save-dev typescript
+npx tsc --noEmit
+npx tsc
+node build/demo.js
+```
+
+The demo prints a greeting for Ada and a guest greeting with different request IDs.
+The example is checked on Node.js 22 and 24 in CI and runs on Bun as well.
+It relies on `crypto.randomUUID`, `Symbol.dispose`, and `Symbol.asyncDispose` in the host.
+TypeScript compiles `await using`; Katagami does not install polyfills.
+
+From this repository, run `bun run build`, then `bun examples/request-scope/demo.ts`.
+`bun run test:examples` checks concurrency, fake injection and cleanup on rejection.
+`bun run test:package` also compiles and runs this starter against the packed npm artifact in Node.js.
+
+For an HTTP application, call the returned `greet` function inside the request handler.
+Create the application once, outside the handler. Each call creates and disposes its own scope.
+Pass authentication context explicitly into the application when adding authentication;
+this example does not provide an authentication or authorization system.
+
+Try changing `registerScoped('greeting', ...)` to `registerSingleton('greeting', ...)`.
+`npx tsc --noEmit` will reject `r.resolve('request')`. Restore the scoped registration:
+the greeting captures request state, so it must share that request's lifetime.
+
+See the [AI coding guide](../../docs/ai-coding-agents.md) and [type guarantees](../../docs/type-safety.md).

package/examples/request-scope/app.ts

@@ -0,0 +1,31 @@
+import { createContainer, createScope } from 'katagami';
+import { disposable } from 'katagami/disposable';
+
+export interface UserRepository {
+	findName(id: string): Promise<string | undefined>;
+}
+
+/** Inject infrastructure once; create a separate scope for each request. */
+export function createApp(repository: UserRepository, onCleanup: (id: string) => void = () => {}) {
+	const container = createContainer()
+		.registerSingleton('users', () => repository)
+		.registerScoped('request', () => ({
+			id: crypto.randomUUID(),
+			[Symbol.dispose]() {
+				onCleanup(this.id);
+			},
+		}))
+		.registerScoped('greeting', r => {
+			const users = r.resolve('users');
+			const request = r.resolve('request');
+			return async (userId: string) => ({
+				requestId: request.id,
+				message: `Hello, ${(await users.findName(userId)) ?? 'guest'}!`,
+			});
+		});
+
+	return async (userId: string) => {
+		await using scope = disposable(createScope(container));
+		return await scope.resolve('greeting')(userId);
+	};
+}

package/examples/request-scope/demo.ts

@@ -0,0 +1,10 @@
+import { createApp } from './app.js';
+
+const greet = createApp({
+	async findName(id) {
+		return new Map([['1', 'Ada']]).get(id);
+	},
+});
+
+console.log(await greet('1'));
+console.log(await greet('unknown'));

package/examples/request-scope/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"lib": ["ES2022", "DOM", "ESNext.Disposable"],
+		"strict": true,
+		"outDir": "build"
+	},
+	"include": ["app.ts", "demo.ts"]
+}

package/llms.txt

@@ -0,0 +1,16 @@
+# Katagami
+
+> Type-safe dependency injection for TypeScript. Accumulated registration types, scope-aware factories and async tracking for AI-assisted development. No decorators or runtime dependencies.
+
+## Documentation
+
+- [Quick start](https://github.com/hiroiku/katagami/blob/master/README.md): installation and a checked example.
+- [AI coding agents](https://github.com/hiroiku/katagami/blob/master/docs/ai-coding-agents.md): workflow, diagnostics and project instructions.
+- [Type safety](https://github.com/hiroiku/katagami/blob/master/docs/type-safety.md): accumulated tokens, structural classes, declared maps and limits.
+- [API guide](https://github.com/hiroiku/katagami/blob/master/docs/guide.md): lifetimes, factories, modules, disposal and lazy resolution.
+- [Request-scope starter](https://github.com/hiroiku/katagami/tree/master/examples/request-scope): a runnable example with fake injection and cleanup.
+- [Choosing DI](https://github.com/hiroiku/katagami/blob/master/docs/choosing-di.md): use cases and trade-offs.
+
+## Optional
+
+- [Evaluation protocol](https://github.com/hiroiku/katagami/tree/master/benchmarks/agent-wiring): test agent outcomes before claiming performance benefits.