katagami 3.0.2 → 4.0.0

package/README.md

@@ -57,43 +57,88 @@ These checks assume narrow tokens and preserved registration types; see the
 
 ### 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.
+**27 features across eight libraries.** Reviewed **2026-09-11**, against the npm `latest`
+versions shown below and official documentation; Katagami's column describes this release, 4.0.0. [Versions, sources and detailed notes](./docs/choosing-di.md#comparison-sources).
+
+**✅ Built-in support · ⚠️ Conditions, a different model or application composition · ➖ No built-in support for this specific capability.**
+Short labels identify the actual API or limitation.
+
+#### Type safety and setup
+
+| Feature | **Katagami**<br>**4.0.0** | InversifyJS<br>8.2.3 | tsyringe<br>4.10.0 | TypeDI<br>0.10.0 | Awilix<br>13.0.5 | NestJS<br>12.0.1 | Effect<br>3.22.2 | typed-inject<br>5.0.0 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| **Runtime requirements** | **✅ Standard TypeScript** | ⚠️ Reflect metadata for class DI | ⚠️ Reflect metadata for class DI | ⚠️ Reflect metadata setup | ✅ No DI metadata | ⚠️ Nest modules / metadata | ✅ Effect / Layer APIs | ✅ Standard TypeScript |
+| **Injection style** | **Explicit factories / constructors** | Constructor / property / factory | Constructor / factory | Constructor / property / factory | Proxy / classic / factory | Constructor / property / factory | Functional services / layers | Constructor / factory + `inject` |
+| **Token types** | **Class / string / number / symbol** | Class / string / symbol | Class / string / symbol | Class / string / `Token<T>` | String / symbol | Class / string / symbol | `Context.Tag` | String literals |
+| **Type safety** | **✅ Inferred services + scope checks** | ✅ Typed identifiers / bindings | ✅ Class / generic types | ✅ Class / `Token<T>` | ✅ Inferred cradle | ✅ Typed providers | ✅ Typed service requirements | ✅ Tokens + `inject` tuples |
+| **Registration-derived types** | **✅ Accumulated tokens** | ➖ | ➖ | ➖ | ✅ `register` → cradle | ➖ | ⚠️ Layer requirements | ✅ Accumulated tokens |
+| **Missing required tokens: compile-time check¹** | **✅ Literal / unique-symbol keys** | ➖ Runtime check | ➖ Runtime check | ➖ Runtime check | ⚠️ Cradle only | ➖ Runtime graph | ✅ Unsatisfied requirements | ✅ Literal keys |
+| **Scoped access from singleton/transient factories: compile-time check¹** | **✅ Scoped tokens excluded** | ➖ | ➖ | ➖ | ⚠️ Runtime strict mode | ⚠️ Request-scope propagation | ⚠️ Different `Scope` model | ➖ No scoped lifetime |
+| **Zero runtime dependency packages²** | **✅** | ➖ | ➖ | ⚠️ Reflect polyfill installed separately | ⚠️ Browser entry differs | ➖ | ➖ | ✅ |
+| **Tree-shaking support²** | **✅ ESM / subpaths / `sideEffects: false`** | ⚠️ ESM; `sideEffects: true` | ⚠️ ESM build | ✅ ESM / `sideEffects: false` | ⚠️ ESM / browser builds | ⚠️ ESM / framework setup | ✅ ESM / subpaths / side-effect declaration | ⚠️ ESM build |
+
+#### Lifetimes, async services and cleanup
+
+| Feature | **Katagami**<br>**4.0.0** | InversifyJS<br>8.2.3 | tsyringe<br>4.10.0 | TypeDI<br>0.10.0 | Awilix<br>13.0.5 | NestJS<br>12.0.1 | Effect<br>3.22.2 | typed-inject<br>5.0.0 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| **Lifetimes** | **✅ Singleton / Transient / Scoped** | ✅ Singleton / Transient / Request | ✅ Singleton / Transient / Resolution / Container | ✅ Shared / Transient | ✅ Singleton / Transient / Scoped | ✅ Singleton / Transient / Request | ⚠️ Memoized / fresh layers + scopes | ✅ Singleton / Transient |
+| **Request / scoped lifetime³** | **✅ Explicit per-request scope** | ⚠️ One resolution graph | ✅ Container / resolution scoped | ⚠️ Named containers | ✅ Explicit per-request scope | ✅ HTTP request scope | ⚠️ Resource scopes | ⚠️ Child injectors; no Scoped provider |
+| **Child containers / nested scopes³** | **✅ Nested scopes** | ✅ Container hierarchy | ✅ Child containers | ⚠️ Named containers | ✅ Child scopes | ⚠️ Module / request contexts | ⚠️ Nested resource scopes | ✅ Child injectors |
+| **Async factories** | **✅ Promise-valued factories** | ✅ Async bindings | ✅ Promise-valued factories | ✅ Promise-valued services | ✅ Promise-valued factories | ✅ Async providers | ✅ Effectful acquisition | ✅ Promise-valued factories |
+| **Async result type tracking** | **✅ Inferred `Promise<T>`** | ✅ `getAsync<T>` | ⚠️ Promise-valued service type | ⚠️ Promise-valued service type | ✅ Inferred `Promise<T>` | ⚠️ Provider / consumer types | ✅ Effect result / error / requirements | ✅ Inferred `Promise<T>` |
+| **Automatically await async dependencies⁴** | **➖ Explicit `await`** | ✅ `getAsync` / `getAllAsync` | ➖ Consumer awaits | ➖ Consumer awaits | ➖ Consumer awaits | ✅ Before consumer construction | ✅ Effect composition | ➖ Consumer awaits |
+| **Resource cleanup⁵** | **✅ Disposal symbols / `await using`** | ⚠️ Singleton deactivation | ✅ Constructed disposables | ⚠️ `destroy()` on reset / removal | ⚠️ Cached values + disposer | ⚠️ App lifecycle hooks | ✅ Scope finalizers | ✅ Owned disposable instances |
+| **Await asynchronous cleanup⁵** | **✅ `Symbol.asyncDispose`** | ✅ Async deactivation | ✅ `container.dispose()` | ➖ `destroy()` is not awaited | ✅ `container.dispose()` | ⚠️ App hooks; not request-scoped classes | ✅ Effect finalizers | ✅ `injector.dispose()` |
+
+#### Composition and advanced features
+
+| Feature | **Katagami**<br>**4.0.0** | InversifyJS<br>8.2.3 | tsyringe<br>4.10.0 | TypeDI<br>0.10.0 | Awilix<br>13.0.5 | NestJS<br>12.0.1 | Effect<br>3.22.2 | typed-inject<br>5.0.0 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| **Optional resolution** | **✅ `tryResolve` / `tryResolveAll`** | ✅ Optional get / inject | ✅ Optional injection | ⚠️ `has` then `get` | ✅ `allowUnregistered` | ✅ Optional injection | ✅ `serviceOption` | ⚠️ Compose optional values |
+| **Multi-binding** | **✅ `resolveAll`** | ✅ `getAll` / `getAllAsync` | ✅ `injectAll` / `resolveAll` | ✅ `getMany` | ⚠️ Collection-valued service | ⚠️ Array provider | ⚠️ Collection-valued service | ⚠️ Collection-valued service |
+| **Lazy resolution⁶** | **✅ `lazy()`; sync class tokens** | ⚠️ Deferred identifiers / factories | ✅ `delay()` proxy | ⚠️ Deferred type reference | ⚠️ Cradle property access | ⚠️ `LazyModuleLoader` | ⚠️ Lazy effect execution | ⚠️ Inject a factory |
+| **Conditional bindings** | **⚠️ Tokens / factory logic** | ✅ Contextual constraints | ✅ Predicate-aware factory | ⚠️ Factory logic | ⚠️ Local injection / factory logic | ⚠️ Dynamic modules / factories | ⚠️ Select / compose layers | ⚠️ Factory logic |
+| **Auto-loading / discovery⁶** | **➖ Explicit `use()`** | ⚠️ Class autobinding | ➖ Explicit registrations | ➖ Explicit imports | ✅ `loadModules` (Node) | ⚠️ `DiscoveryService` | ➖ Explicit layers | ➖ Explicit providers |
+| **Module system / composition** | **✅ `use()`** | ✅ Container modules | ✅ `@registry` | ⚠️ Group registrations | ✅ `loadModules` / `register` | ✅ Modules / dynamic modules | ✅ Layer composition | ⚠️ Compose provider chains |
+| **Circular dependency detection⁷** | **✅ Runtime cycle path** | ✅ Runtime detection | ⚠️ Constructor error / `delay` | ⚠️ Deferred type references | ✅ Runtime cycle path | ⚠️ Cycle errors / `forwardRef` | ⚠️ Typed Layer requirements | ⚠️ Registration order constrains dependencies |
+| **Middleware / interceptors⁶** | **⚠️ `beforeResolve` checks / higher-order factories** | ✅ Activation / deactivation hooks | ✅ Before / after resolution | ⚠️ Factory wrappers | ⚠️ Factory wrappers | ⚠️ Request interceptors, not DI hooks | ⚠️ Effect composition | ⚠️ Provider decoration |
+| **Snapshot / restore⁶** | **➖** | ✅ `snapshot` / `restore` | ➖ | ➖ | ➖ | ➖ | ➖ | ➖ |
+| **Test substitution / isolation** | **✅ Fresh scopes / containers + `use()`** | ✅ Rebind / snapshots | ✅ Child container overrides | ✅ Named containers / reset | ✅ Child scopes / overrides | ✅ `overrideProvider` | ✅ Substitute test layers | ✅ Child injector overrides |
+
+**What stands out:** Katagami combines **accumulated registration types, scope-filtered factory
+resolvers, three lifetimes and zero runtime dependencies** with direct `r.resolve(token)` calls.
+Optional/multiple resolution, module composition, lazy class resolution and standards-based cleanup
+stay available without decorator setup. Awilix, Effect and typed-inject also provide meaningful
+compile-time checks, as shown above.
+
+<details>
+<summary>Comparison notes: type guarantees, scopes, async behavior and feature boundaries</summary>
+
+1. **Type guarantees:** Katagami's missing-token guarantee applies to accumulated literal keys and
+   unique symbols with their types preserved. Class tokens, predeclared maps and mutable aliases
+   have [documented boundaries](./docs/type-safety.md). Awilix rejects unknown cradle properties,
+   but its broad `resolve` overload accepts unknown names. Effect checks service requirements in
+   its own model. Scope checks here mean excluding scoped tokens from singleton/transient resolvers.
+2. **Setup and bundles:** Metadata notes describe the documented class-injection path; explicit
+   value/factory bindings can avoid decorating individual services. Core Katagami needs no polyfills;
+   disposal has [host/compiler requirements](./docs/guide.md#compatibility). ESM and side-effect
+   declarations help tree shaking, but these are packaging comparisons, not measured bundle sizes.
+3. **Scopes:** InversifyJS Request means one resolution graph, not an HTTP request. Named containers,
+   module contexts, child injectors and Effect resource scopes are not identical lifetime policies.
+4. **Async:** Returning a Promise is distinct from awaiting dependencies before injection.
+   Katagami keeps the Promise in the inferred type and leaves `await` explicit.
+5. **Cleanup:** Katagami's opt-in `disposable()` integrates `Symbol.dispose`, `Symbol.asyncDispose`
+   and `await using`. Ownership varies by library; InversifyJS deactivation is for singletons,
+   Awilix disposers are for cached values, and Nest hooks exclude request-scoped classes.
+6. **Composition versus dedicated APIs:** A service proxy, deferred token and lazy module are
+   different features. Autobinding/discovery is not filesystem loading. Katagami's `use()` copies
+   registrations; containers are mutable. Factory wrappers are not interceptor APIs, `beforeResolve`
+   can reject a resolution but not replace its result, and fresh containers are not snapshots. [Composition details](./docs/choosing-di.md#composition-and-tooling).
+7. **Cycles:** Runtime cycle detection, deferred references and static dependency requirements are
+   different mechanisms. A ⚠️ entry does not promise a general cycle detector; runtime checks do
+   not imply detection of every asynchronous deadlock.
+
+</details>
 
 ## Why Katagami for AI-assisted development?
 
@@ -145,6 +190,7 @@ describes how to test them.
 | 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` |
+| Registration policies and operations | Share one `policy` across modules, require registration metadata and check what resolutions and operations return |
 | 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.
@@ -154,6 +200,7 @@ See [choosing a DI approach](./docs/choosing-di.md) for trade-offs and links to
 ## Documentation
 
 - [Usage guide and API](./docs/guide.md): lifetimes, composition, classes, async factories, cleanup and lazy resolution.
+- [Registration policies and operations](./docs/registration-policies.md): a shared `policy`, required metadata, return checks and operations scopes.
 - [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.

package/dist/chunk-R66WOZUM.js

@@ -0,0 +1,71 @@
+// src/internal.ts
+var INTERNALS = /* @__PURE__ */ Symbol.for("katagami.internals.v4");
+var CREATIONS = /* @__PURE__ */ Symbol.for("katagami.creations.v4");
+var shared = globalThis;
+if (!shared[CREATIONS]) {
+  Object.defineProperty(shared, CREATIONS, { value: /* @__PURE__ */ new WeakMap() });
+}
+var creations = shared[CREATIONS];
+function settle(creation) {
+  return creation.then(
+    (value) => ({ failed: false, value }),
+    (error) => ({ error, failed: true })
+  );
+}
+var CONSTRUCTING = /* @__PURE__ */ Symbol.for("katagami.constructing.v4");
+var running = globalThis;
+if (!running[CONSTRUCTING]) {
+  Object.defineProperty(running, CONSTRUCTING, { value: [] });
+}
+var constructing = running[CONSTRUCTING];
+
+// src/disposable/index.ts
+function disposable(container) {
+  const asyncDispose = async () => {
+    const internals = container[INTERNALS];
+    if (internals.isDisposed()) {
+      return;
+    }
+    internals.markDisposed();
+    const instances = [...internals.ownCache.values()].reverse();
+    const errors = [];
+    for (const instance of instances) {
+      let resolved = instance;
+      if (instance instanceof Promise) {
+        const creation = await (creations.get(instance) ?? settle(instance));
+        if (creation.failed) {
+          continue;
+        }
+        resolved = creation.value;
+      }
+      try {
+        if (resolved != null && typeof resolved === "object") {
+          if (Symbol.asyncDispose in resolved) {
+            await resolved[Symbol.asyncDispose]();
+          } else if (Symbol.dispose in resolved) {
+            resolved[Symbol.dispose]();
+          }
+        }
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    internals.ownCache.clear();
+    if (errors.length > 0) {
+      throw new AggregateError(errors, "One or more errors occurred during disposal.");
+    }
+  };
+  Object.defineProperty(container, Symbol.asyncDispose, {
+    configurable: true,
+    value: asyncDispose
+  });
+  return container;
+}
+
+export {
+  INTERNALS,
+  creations,
+  settle,
+  constructing,
+  disposable
+};

package/dist/container/index.d.cts

@@ -1,5 +1,84 @@
-import { type ContainerInternals, INTERNALS } from '../internal.cjs';
+import { type Callable, type EntrypointFactory } from '../entrypoint/index.cjs';
+import { type ContainerInternals, INTERNALS, type REGISTRATION_STATE } from '../internal.cjs';
+import { type AnyMetadataEntry, type AnyMetadataKey, type MetadataKeyOf, type MetadataReader, type RegistrationArguments } from '../metadata/index.cjs';
 import type { AbstractConstructor, Resolver } from '../resolver/index.cjs';
+import { type ContainerPolicy, type RequiredMetadata } from './policy.cjs';
+export type RegisteredTokens<C> = C extends {
+    readonly [REGISTRATION_STATE]: infer S;
+} ? S extends {
+    readonly untracked: true;
+} ? never : S extends {
+    readonly token: infer K;
+} ? K : never : never;
+export interface RegistrationState {
+    readonly token: unknown;
+    readonly metadata: AnyMetadataKey;
+    readonly callable: Callable | never;
+}
+type State<K, E extends readonly AnyMetadataEntry[], F = never> = {
+    readonly token: K;
+    readonly metadata: MetadataKeyOf<E[number]>;
+    readonly callable: F;
+};
+type Replace<S, K, N> = (unknown extends S ? UntrackedState : Exclude<S, {
+    readonly token: K;
+}>) | N;
+type UntrackedState<K = unknown> = {
+    readonly token: K;
+    readonly metadata: never;
+    readonly callable: never;
+    readonly untracked: true;
+};
+type SourceState<S, K> = unknown extends S ? UntrackedState<K> : S extends {
+    readonly untracked: true;
+} ? UntrackedState<K> : S;
+type SourceTokens<S, K> = unknown extends S ? K : S extends {
+    readonly untracked: true;
+} ? K : S extends {
+    readonly token: infer Token;
+} ? Token : never;
+type Append<S, K, E extends readonly AnyMetadataEntry[], F = never> = unknown extends S ? [MetadataKeyOf<E[number]> | F] extends [never] ? unknown : UntrackedState | State<K, E, F> : Replace<S, K, {
+    readonly token: K;
+    readonly metadata: [Extract<S, {
+        readonly token: K;
+    }>] extends [never] ? MetadataKeyOf<E[number]> : Extract<Extract<S, {
+        readonly token: K;
+    }> extends {
+        readonly metadata: infer M;
+    } ? M : never, MetadataKeyOf<E[number]>>;
+    readonly callable: F;
+}>;
+type TrackedState<S> = S extends {
+    readonly metadata: infer M;
+    readonly callable: infer F;
+} ? [M | F] extends [never] ? never : S : never;
+type Merge<S, K, N> = unknown extends S ? [TrackedState<N>] extends [never] ? unknown : Replace<S, K, N> : Replace<S, K, N>;
+type MissingMetadata<R, S> = unknown extends S ? R : S extends {
+    readonly metadata: infer M;
+} ? Exclude<R, M> : never;
+/**
+ * Create a new DI container that follows a shared policy.
+ *
+ * Containers created with the same policy object share its settings and the origins it observes.
+ * Every registration must carry the policy's `requiredMetadata`, and `use()` accepts only modules
+ * with the same policy or without one. Declare the policy with `satisfies ContainerPolicy` to keep
+ * its concrete types.
+ *
+ * @param options `policy`: the shared policy object
+ */
+export declare function createContainer<const P extends ContainerPolicy>(options: {
+    readonly policy: P;
+}): Container<Record<never, never>, never, never, Record<never, never>, never, never, RequiredMetadata<P>, never>;
+/**
+ * Create a new DI container that follows a shared policy, with predeclared token type maps.
+ *
+ * @template T PropertyKey-based token type map (defined via interface, order-independent)
+ * @template ScopedT PropertyKey-based token type map for scoped registrations
+ * @param options `policy`: the shared policy object
+ */
+export declare function createContainer<T, ScopedT, const P extends ContainerPolicy>(options: {
+    readonly policy: P;
+}): Container<T, never, never, ScopedT, never, never, RequiredMetadata<P>, never>;
 /**
  * Create a new DI container.
  *
@@ -14,7 +93,9 @@ import type { AbstractConstructor, Resolver } from '../resolver/index.cjs';
  *   .registerTransient(GenerateTextUseCase, r => new GenerateTextUseCase(r.resolve(TextGenerationService)));
  * ```
  */
-export declare function createContainer<T = Record<never, never>, ScopedT = Record<never, never>>(): Container<T, never, never, ScopedT>;
+export declare function createContainer<T = Record<never, never>, ScopedT = Record<never, never>>(): Container<T, never, never, ScopedT, never, never, readonly [], [
+    keyof T | keyof ScopedT
+] extends [never] ? never : unknown>;
 /**
  * Lightweight DI container — registration only.
  *
@@ -29,33 +110,43 @@ export declare function createContainer<T = Record<never, never>, ScopedT = Reco
  * @template ScopedT PropertyKey-based token type map for scoped registrations
  * @template ScopedSync Union of scoped sync class constructors (accumulated via chaining, order-dependent)
  * @template ScopedAsync Union of scoped async class constructors (accumulated via chaining, order-dependent)
+ * @template Required Metadata keys the container's policy requires on every registration
+ * @template Registrations Registration state that tracks metadata and operations per token
  */
-export declare class Container<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never> {
+export declare class Container<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never, Required extends readonly AnyMetadataKey[] = readonly [], Registrations = unknown> {
     private readonly registrations;
     private readonly singletonCache;
+    private readonly requiredMetadata;
+    private readonly policy;
     private disposed;
-    /**
-     * Internal state accessor for extension modules (scope, disposable).
-     *
-     * @internal
-     */
-    readonly [INTERNALS]: ContainerInternals;
-    constructor();
+    readonly [REGISTRATION_STATE]: Registrations;
+    readonly [INTERNALS]: ContainerInternals & {
+        readonly kind: 'container';
+    };
+    constructor(options?: {
+        readonly policy: ContainerPolicy<Required>;
+    });
     /**
      * Register a factory function as a singleton for the given token.
      *
      * Creates the instance on the first resolve and returns the cached value thereafter.
      * If the same token is registered multiple times, all factories are accumulated.
      * `resolve()` returns the last registered instance; `resolveAll()` returns all.
+     * Register request-dependent work as scoped instead.
      *
      * @param token Any value to use as a token
-     * @param factory Factory function that receives a resolver and returns an instance
+     * @param factory Factory function that receives a resolver and returns an instance. Wrap it with
+     *   `entrypoint()` to expose the function it returns as an operation.
+     * @param options `metadata`: entries created with metadata keys. Required when the policy declares
+     *   `requiredMetadata`.
      * @returns The container for method chaining
      */
-    registerSingleton<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync>;
-    registerSingleton<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync>;
-    registerSingleton<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-    registerSingleton<V>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerSingleton<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: ((resolver: Resolver<T, Sync, Async>) => F) & EntrypointFactory<Resolver<T, Sync, Async>, F>, ...options: RegistrationArguments<Required, E>): Container<Record<K, F> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerSingleton<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: EntrypointFactory<Resolver<T, Sync, Async>, F>, ...options: RegistrationArguments<Required, E>): Container<Record<K, Promise<F>> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerSingleton<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerSingleton<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerSingleton<K extends PropertyKey, V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E>>;
+    registerSingleton<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations | State<unknown, E>>;
     /**
      * Register a factory function as transient for the given token.
      *
@@ -64,13 +155,18 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
      * `resolve()` returns the last registered instance; `resolveAll()` returns all.
      *
      * @param token Any value to use as a token
-     * @param factory Factory function that receives a resolver and returns an instance
+     * @param factory Factory function that receives a resolver and returns an instance. Wrap it with
+     *   `entrypoint()` to expose the function it returns as an operation.
+     * @param options `metadata`: entries created with metadata keys. Required when the policy declares
+     *   `requiredMetadata`.
      * @returns The container for method chaining
      */
-    registerTransient<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync>;
-    registerTransient<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync>;
-    registerTransient<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-    registerTransient<V>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerTransient<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: ((resolver: Resolver<T, Sync, Async>) => F) & EntrypointFactory<Resolver<T, Sync, Async>, F>, ...options: RegistrationArguments<Required, E>): Container<Record<K, F> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerTransient<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: EntrypointFactory<Resolver<T, Sync, Async>, F>, ...options: RegistrationArguments<Required, E>): Container<Record<K, Promise<F>> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerTransient<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerTransient<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerTransient<K extends PropertyKey, V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E>>;
+    registerTransient<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations | State<unknown, E>>;
     /**
      * Register a factory function as scoped for the given token.
      *
@@ -79,30 +175,41 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
      * Scoped tokens cannot be resolved from the root container — use createScope() first.
      *
      * @param token Any value to use as a token
-     * @param factory Factory function that receives a resolver and returns an instance
+     * @param factory Factory function that receives a resolver and returns an instance. Wrap it with
+     *   `entrypoint()` to expose the function it returns as an operation.
+     * @param options `metadata`: entries created with metadata keys. Required when the policy declares
+     *   `requiredMetadata`.
      * @returns The container for method chaining
      */
-    registerScoped<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => Promise<V>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync | AbstractConstructor<V>>;
-    registerScoped<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, ScopedT, ScopedSync | AbstractConstructor<V>, ScopedAsync>;
-    registerScoped<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, Record<K, V> & ScopedT, ScopedSync, ScopedAsync>;
-    registerScoped<V>(token: unknown, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerScoped<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: ((resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => F) & EntrypointFactory<Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, F>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, Record<K, F> & ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerScoped<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: EntrypointFactory<Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, F>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, Record<K, Promise<F>> & ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerScoped<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => Promise<V>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync | AbstractConstructor<V>, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerScoped<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync | AbstractConstructor<V>, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerScoped<K extends PropertyKey, V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, Record<K, V> & ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E>>;
+    registerScoped<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: unknown, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations | State<unknown, E>>;
+    /**
+     * Read the metadata of the last registration for a token without creating the instance.
+     *
+     * @param token A registered token
+     * @returns A read-only metadata reader
+     * @throws ContainerError if the token is not registered
+     */
+    getMetadata<V>(token: AbstractConstructor<V> & (Sync | Async | ScopedSync | ScopedAsync)): MetadataReader;
+    getMetadata<K extends keyof (T & ScopedT)>(token: K): MetadataReader;
     /**
      * Apply all registrations from another container (module) to this container.
      *
-     * Copies registration entries (factory + lifetime) by replacing existing entries for each token.
+     * Copies registration entries by replacing existing entries for each token.
      * Singleton instance caches are not shared — each container manages its own.
+     * A module with a policy must use this container's policy, and every copied registration must carry
+     * the metadata this container's policy requires; otherwise nothing is copied.
      *
      * @param source A container whose registrations will be copied into this container
      * @returns The container for method chaining
      */
-    use<MT, MSync extends AbstractConstructor, MAsync extends AbstractConstructor, MScopedT, MScopedSync extends AbstractConstructor, MScopedAsync extends AbstractConstructor>(source: Container<MT, MSync, MAsync, MScopedT, MScopedSync, MScopedAsync>): Container<T & MT, Sync | MSync, Async | MAsync, ScopedT & MScopedT, ScopedSync | MScopedSync, ScopedAsync | MScopedAsync>;
-    /**
-     * Add a registration entry. Accumulates registrations for the same token.
-     *
-     * @param token Token
-     * @param factory Factory function
-     * @param lifetime Lifetime of the registration
-     * @returns The container for method chaining
-     */
+    use<MT, MS extends AbstractConstructor, MA extends AbstractConstructor, MST, MSS extends AbstractConstructor, MSA extends AbstractConstructor, MR extends readonly AnyMetadataKey[], State>(source: Container<MT, MS, MA, MST, MSS, MSA, MR, State> & ([MissingMetadata<Required[number], State>] extends [never] ? unknown : {
+        readonly missingRequiredMetadata: never;
+    })): Container<T & MT, Sync | MS, Async | MA, ScopedT & MST, ScopedSync | MSS, ScopedAsync | MSA, Required, Merge<Registrations, SourceTokens<State, keyof MT | keyof MST | MS | MA | MSS | MSA>, SourceState<State, keyof MT | keyof MST | MS | MA | MSS | MSA>>>;
     private addRegistration;
 }
+export {};