katagami 3.0.3 → 4.0.0

package/README.md

@@ -58,14 +58,14 @@ These checks assume narrow tokens and preserved registration types; see the
 ### Library comparison
 
 **27 features across eight libraries.** Reviewed **2026-09-11**, against the npm `latest`
-versions shown below and official documentation. [Versions, sources and detailed notes](./docs/choosing-di.md#comparison-sources).
+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>**3.0.3** | 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 |
+| 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` |
@@ -79,7 +79,7 @@ Short labels identify the actual API or limitation.
 
 #### Lifetimes, async services and cleanup
 
-| Feature | **Katagami**<br>**3.0.3** | 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 |
+| 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 |
@@ -92,7 +92,7 @@ Short labels identify the actual API or limitation.
 
 #### Composition and advanced features
 
-| Feature | **Katagami**<br>**3.0.3** | 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 |
+| 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 |
@@ -101,7 +101,7 @@ Short labels identify the actual API or limitation.
 | **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⁶** | **⚠️ Higher-order factories** | ✅ Activation / deactivation hooks | ✅ Before / after resolution | ⚠️ Factory wrappers | ⚠️ Factory wrappers | ⚠️ Request interceptors, not DI hooks | ⚠️ Effect composition | ⚠️ Provider decoration |
+| **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 |
 
@@ -132,8 +132,8 @@ compile-time checks, as shown above.
    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, and fresh
-   containers are not snapshots. [Composition details](./docs/choosing-di.md#composition-and-tooling).
+   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.
@@ -190,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.
@@ -199,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 {};