katagami 3.0.2 → 4.0.0

package/dist/internal.d.cts

@@ -1,4 +1,6 @@
+import type { PolicyState } from './container/policy.cjs';
 import type { Registration } from './resolver/index.cjs';
+import type { BeforeResolve } from './scope/index.cjs';
 /**
  * Symbol used by extension modules (scope, disposable) to access container/scope internals.
  *
@@ -7,6 +9,7 @@ import type { Registration } from './resolver/index.cjs';
 export declare const INTERNALS: unique symbol;
 /** Type-only registration state retained by disposable views. No runtime property is emitted. */
 export declare const TYPE_STATE: unique symbol;
+export declare const REGISTRATION_STATE: unique symbol;
 /**
  * Internal state exposed via the INTERNALS symbol.
  *
@@ -16,6 +19,9 @@ export declare const TYPE_STATE: unique symbol;
  * @internal
  */
 export interface ContainerInternals {
+    readonly kind: 'container' | 'scope';
+    readonly policy: PolicyState | undefined;
+    readonly beforeResolve: readonly BeforeResolve[];
     /** All registrations (singleton / transient / scoped). Each token maps to an array of registrations. */
     readonly registrations: Map<unknown, Registration[]>;
     /** Singleton cache keyed by Registration object (Container: singletons, Scope: shared with parent). */
@@ -27,3 +33,62 @@ export interface ContainerInternals {
     /** Mark this container / scope as disposed. */
     markDisposed(): void;
 }
+/**
+ * Outcome of an asynchronous creation.
+ *
+ * Disposal needs the created value in order to close it, but must not listen to the promise the
+ * scope handed to the caller: that would take over a failure the caller was meant to see. The
+ * scope records the outcome on a chain of its own, which never rejects.
+ *
+ * @internal
+ */
+export type Creation = {
+    readonly failed: false;
+    readonly value: unknown;
+} | {
+    readonly failed: true;
+    readonly error: unknown;
+};
+/**
+ * Settlement records for cached asynchronous creations, keyed by the promise the scope caches.
+ *
+ * @internal
+ */
+export declare const creations: WeakMap<Promise<unknown>, Promise<Creation>>;
+/**
+ * Record how a creation settles, on a chain that never rejects.
+ *
+ * @internal
+ */
+export declare function settle(creation: Promise<unknown>): Promise<Creation>;
+/**
+ * A factory running synchronously right now.
+ *
+ * @internal
+ */
+export interface RunningFactory {
+    readonly scope: object;
+    readonly token: unknown;
+    readonly registration: Registration;
+    /** The singleton cache of the container the scope belongs to. */
+    readonly singletons: object;
+    readonly context: unknown;
+}
+/**
+ * Factories running synchronously right now, innermost last, across every scope and module copy.
+ *
+ * @internal
+ */
+export declare const constructing: RunningFactory[];
+/**
+ * Internal state of a Scope.
+ *
+ * `resolveInternal` resolves without the policy return check: the value stays inside the
+ * face that asked for it. The operations face uses it to obtain the callable it never hands out.
+ *
+ * @internal
+ */
+export interface ScopeInternals extends ContainerInternals {
+    readonly kind: 'scope';
+    resolveInternal(token: unknown): unknown;
+}

package/dist/internal.d.ts

@@ -1,4 +1,6 @@
+import type { PolicyState } from './container/policy.js';
 import type { Registration } from './resolver/index.js';
+import type { BeforeResolve } from './scope/index.js';
 /**
  * Symbol used by extension modules (scope, disposable) to access container/scope internals.
  *
@@ -7,6 +9,7 @@ import type { Registration } from './resolver/index.js';
 export declare const INTERNALS: unique symbol;
 /** Type-only registration state retained by disposable views. No runtime property is emitted. */
 export declare const TYPE_STATE: unique symbol;
+export declare const REGISTRATION_STATE: unique symbol;
 /**
  * Internal state exposed via the INTERNALS symbol.
  *
@@ -16,6 +19,9 @@ export declare const TYPE_STATE: unique symbol;
  * @internal
  */
 export interface ContainerInternals {
+    readonly kind: 'container' | 'scope';
+    readonly policy: PolicyState | undefined;
+    readonly beforeResolve: readonly BeforeResolve[];
     /** All registrations (singleton / transient / scoped). Each token maps to an array of registrations. */
     readonly registrations: Map<unknown, Registration[]>;
     /** Singleton cache keyed by Registration object (Container: singletons, Scope: shared with parent). */
@@ -27,3 +33,62 @@ export interface ContainerInternals {
     /** Mark this container / scope as disposed. */
     markDisposed(): void;
 }
+/**
+ * Outcome of an asynchronous creation.
+ *
+ * Disposal needs the created value in order to close it, but must not listen to the promise the
+ * scope handed to the caller: that would take over a failure the caller was meant to see. The
+ * scope records the outcome on a chain of its own, which never rejects.
+ *
+ * @internal
+ */
+export type Creation = {
+    readonly failed: false;
+    readonly value: unknown;
+} | {
+    readonly failed: true;
+    readonly error: unknown;
+};
+/**
+ * Settlement records for cached asynchronous creations, keyed by the promise the scope caches.
+ *
+ * @internal
+ */
+export declare const creations: WeakMap<Promise<unknown>, Promise<Creation>>;
+/**
+ * Record how a creation settles, on a chain that never rejects.
+ *
+ * @internal
+ */
+export declare function settle(creation: Promise<unknown>): Promise<Creation>;
+/**
+ * A factory running synchronously right now.
+ *
+ * @internal
+ */
+export interface RunningFactory {
+    readonly scope: object;
+    readonly token: unknown;
+    readonly registration: Registration;
+    /** The singleton cache of the container the scope belongs to. */
+    readonly singletons: object;
+    readonly context: unknown;
+}
+/**
+ * Factories running synchronously right now, innermost last, across every scope and module copy.
+ *
+ * @internal
+ */
+export declare const constructing: RunningFactory[];
+/**
+ * Internal state of a Scope.
+ *
+ * `resolveInternal` resolves without the policy return check: the value stays inside the
+ * face that asked for it. The operations face uses it to obtain the callable it never hands out.
+ *
+ * @internal
+ */
+export interface ScopeInternals extends ContainerInternals {
+    readonly kind: 'scope';
+    resolveInternal(token: unknown): unknown;
+}

package/dist/metadata/index.d.cts

@@ -0,0 +1,67 @@
+declare const KEY: unique symbol;
+declare const ENTRY: unique symbol;
+/**
+ * A typed metadata key. Call it with a value to create a metadata entry for a registration.
+ *
+ * The name is used by type checking; runtime lookups use the key object's identity.
+ */
+export interface MetadataKey<T, Name extends PropertyKey = PropertyKey> {
+    (value: T): MetadataEntry<T, Name>;
+    readonly name: Name;
+    readonly [KEY]: true;
+}
+export interface MetadataEntry<T = unknown, Name extends PropertyKey = PropertyKey> {
+    readonly key: MetadataKey<T, Name>;
+    readonly value: T;
+    readonly [ENTRY]: true;
+}
+export interface AnyMetadataKey {
+    readonly name: PropertyKey;
+    readonly [KEY]: true;
+}
+export interface AnyMetadataEntry {
+    readonly key: AnyMetadataKey;
+    readonly value: unknown;
+    readonly [ENTRY]: true;
+}
+export type MetadataKeyOf<E> = E extends MetadataEntry<infer T, infer N> ? MetadataKey<T, N> : never;
+/**
+ * Define a typed metadata key.
+ *
+ * The value type is given first and the name is inferred in a second call, so keys with different
+ * names are never confused.
+ *
+ * @example
+ * ```ts
+ * const AREA = createMetadataKey<'internal' | 'public'>()('area');
+ * container.registerScoped('read', factory, { metadata: [AREA('public')] });
+ * ```
+ */
+export declare function createMetadataKey<T>(): <const Name extends PropertyKey>(name: Name) => MetadataKey<T, Name>;
+export interface MetadataReader {
+    get<T>(key: MetadataKey<T>): T | undefined;
+    require<T>(key: MetadataKey<T>): T;
+    has(key: AnyMetadataKey): boolean;
+}
+/** Registration metadata as a key/value pair, so origins can be compared by content. */
+export type MetadataPair = readonly [key: AnyMetadataKey, value: unknown];
+/** A reader and the key/value pairs for the same registration metadata, built from one copy. */
+export interface RegisteredMetadata {
+    readonly reader: MetadataReader;
+    readonly pairs: readonly MetadataPair[];
+}
+/** Copy the metadata at registration, so later changes to the array or entries do not affect checks. */
+export declare function readMetadata(entries: readonly AnyMetadataEntry[], required: readonly AnyMetadataKey[]): RegisteredMetadata;
+export declare function validateMetadataKeys(keys: readonly AnyMetadataKey[]): void;
+export type RegistrationArguments<Required extends readonly AnyMetadataKey[], Entries extends readonly AnyMetadataEntry[]> = Required extends readonly [] ? [options?: {
+    readonly metadata?: Entries;
+}] : [
+    options: {
+        readonly metadata: Entries;
+    } & ([Exclude<Required[number], MetadataKeyOf<Entries[number]>>] extends [
+        never
+    ] ? unknown : {
+        readonly missingRequiredMetadata: never;
+    })
+];
+export {};

package/dist/metadata/index.d.ts

@@ -0,0 +1,67 @@
+declare const KEY: unique symbol;
+declare const ENTRY: unique symbol;
+/**
+ * A typed metadata key. Call it with a value to create a metadata entry for a registration.
+ *
+ * The name is used by type checking; runtime lookups use the key object's identity.
+ */
+export interface MetadataKey<T, Name extends PropertyKey = PropertyKey> {
+    (value: T): MetadataEntry<T, Name>;
+    readonly name: Name;
+    readonly [KEY]: true;
+}
+export interface MetadataEntry<T = unknown, Name extends PropertyKey = PropertyKey> {
+    readonly key: MetadataKey<T, Name>;
+    readonly value: T;
+    readonly [ENTRY]: true;
+}
+export interface AnyMetadataKey {
+    readonly name: PropertyKey;
+    readonly [KEY]: true;
+}
+export interface AnyMetadataEntry {
+    readonly key: AnyMetadataKey;
+    readonly value: unknown;
+    readonly [ENTRY]: true;
+}
+export type MetadataKeyOf<E> = E extends MetadataEntry<infer T, infer N> ? MetadataKey<T, N> : never;
+/**
+ * Define a typed metadata key.
+ *
+ * The value type is given first and the name is inferred in a second call, so keys with different
+ * names are never confused.
+ *
+ * @example
+ * ```ts
+ * const AREA = createMetadataKey<'internal' | 'public'>()('area');
+ * container.registerScoped('read', factory, { metadata: [AREA('public')] });
+ * ```
+ */
+export declare function createMetadataKey<T>(): <const Name extends PropertyKey>(name: Name) => MetadataKey<T, Name>;
+export interface MetadataReader {
+    get<T>(key: MetadataKey<T>): T | undefined;
+    require<T>(key: MetadataKey<T>): T;
+    has(key: AnyMetadataKey): boolean;
+}
+/** Registration metadata as a key/value pair, so origins can be compared by content. */
+export type MetadataPair = readonly [key: AnyMetadataKey, value: unknown];
+/** A reader and the key/value pairs for the same registration metadata, built from one copy. */
+export interface RegisteredMetadata {
+    readonly reader: MetadataReader;
+    readonly pairs: readonly MetadataPair[];
+}
+/** Copy the metadata at registration, so later changes to the array or entries do not affect checks. */
+export declare function readMetadata(entries: readonly AnyMetadataEntry[], required: readonly AnyMetadataKey[]): RegisteredMetadata;
+export declare function validateMetadataKeys(keys: readonly AnyMetadataKey[]): void;
+export type RegistrationArguments<Required extends readonly AnyMetadataKey[], Entries extends readonly AnyMetadataEntry[]> = Required extends readonly [] ? [options?: {
+    readonly metadata?: Entries;
+}] : [
+    options: {
+        readonly metadata: Entries;
+    } & ([Exclude<Required[number], MetadataKeyOf<Entries[number]>>] extends [
+        never
+    ] ? unknown : {
+        readonly missingRequiredMetadata: never;
+    })
+];
+export {};

package/dist/resolver/index.d.cts

@@ -1,3 +1,4 @@
+import type { MetadataPair, MetadataReader } from '../metadata/index.cjs';
 export type AbstractConstructor<T = unknown> = abstract new (...args: never[]) => T;
 /**
  * Resolver passed to factory callbacks.
@@ -64,6 +65,10 @@ export type Lifetime = 'singleton' | 'transient' | 'scoped';
  * Factory registration entry.
  */
 export interface Registration {
+    readonly metadata: MetadataReader;
+    /** The same metadata as key/value pairs, so origins can be compared by content. */
+    readonly metadataPairs: readonly MetadataPair[];
+    readonly entrypoint: boolean;
     /**
      * Factory function.
      *

package/dist/resolver/index.d.ts

@@ -1,3 +1,4 @@
+import type { MetadataPair, MetadataReader } from '../metadata/index.js';
 export type AbstractConstructor<T = unknown> = abstract new (...args: never[]) => T;
 /**
  * Resolver passed to factory callbacks.
@@ -64,6 +65,10 @@ export type Lifetime = 'singleton' | 'transient' | 'scoped';
  * Factory registration entry.
  */
 export interface Registration {
+    readonly metadata: MetadataReader;
+    /** The same metadata as key/value pairs, so origins can be compared by content. */
+    readonly metadataPairs: readonly MetadataPair[];
+    readonly entrypoint: boolean;
     /**
      * Factory function.
      *

package/dist/scope/index.d.cts

@@ -1,7 +1,26 @@
 import type { Container } from '../container/index.cjs';
+import { type PolicyState } from '../container/policy.cjs';
 import type { DisposableContainer, DisposableScope } from '../disposable/index.cjs';
-import { type ContainerInternals, INTERNALS } from '../internal.cjs';
-import type { AbstractConstructor, Registration } from '../resolver/index.cjs';
+import type { REGISTRATION_STATE } from '../internal.cjs';
+import { type ContainerInternals, INTERNALS, type ScopeInternals } from '../internal.cjs';
+import type { AnyMetadataKey, MetadataReader } from '../metadata/index.cjs';
+import type { AbstractConstructor, Lifetime, Registration } from '../resolver/index.cjs';
+import { type OperationsScope, type OperationsScopeOptions } from './operations.cjs';
+export interface RegistrationDescription {
+    readonly token: unknown;
+    readonly lifetime: Lifetime;
+    readonly metadata: MetadataReader;
+    readonly entrypoint: boolean;
+}
+export interface ResolutionEvent extends RegistrationDescription {
+    readonly requester: RegistrationDescription | undefined;
+    readonly path: readonly unknown[];
+}
+export type BeforeResolve = (event: ResolutionEvent) => void;
+export interface ScopeOptions {
+    readonly access?: never;
+    readonly beforeResolve?: BeforeResolve;
+}
 /**
  * Create a new scope (child container) from a Container, Scope, or their disposable variants.
  *
@@ -12,10 +31,14 @@ import type { AbstractConstructor, Registration } from '../resolver/index.cjs';
  * @returns A new Scope instance
  * @throws ContainerError if the source has been disposed
  */
-export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function createScope<C extends {
+    readonly [INTERNALS]: ContainerInternals;
+    readonly [REGISTRATION_STATE]: unknown;
+}>(source: C, options: OperationsScopeOptions): OperationsScope<C[typeof REGISTRATION_STATE]>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Required extends readonly AnyMetadataKey[], Registrations>(source: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations>, options?: ScopeOptions): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Registrations>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>, options?: ScopeOptions): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Required extends readonly AnyMetadataKey[], Registrations>(source: DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations>, options?: ScopeOptions): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Registrations>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>, options?: ScopeOptions): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;
 /**
  * Scoped child container.
  *
@@ -30,20 +53,21 @@ export declare function createScope<T, Sync extends AbstractConstructor, Async e
  * @template ScopedSync Union of scoped sync class constructors
  * @template ScopedAsync Union of scoped async class constructors
  */
-export declare class Scope<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 Scope<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never, Registrations = unknown> {
     private readonly registrations;
     private readonly singletonCache;
     private readonly scopedCache;
-    private readonly resolvingTokens;
-    private singletonDepth;
+    private readonly beforeResolve;
+    private readonly policy;
     private disposed;
     /**
      * Internal state accessor for extension modules (scope, disposable).
      *
      * @internal
      */
-    readonly [INTERNALS]: ContainerInternals;
-    constructor(registrations: Map<unknown, Registration[]>, singletonCache: Map<Registration, unknown>);
+    readonly [REGISTRATION_STATE]: Registrations;
+    readonly [INTERNALS]: ScopeInternals;
+    constructor(registrations: Map<unknown, Registration[]>, singletonCache: Map<Registration, unknown>, beforeResolve?: readonly BeforeResolve[], policy?: PolicyState);
     /**
      * Resolve an instance for the given token.
      *
@@ -99,22 +123,23 @@ export declare class Scope<T = Record<never, never>, Sync extends AbstractConstr
     tryResolveAll<K extends keyof (T & ScopedT)>(token: K): (T & ScopedT)[K][] | undefined;
     tryResolveAll<V>(token: AbstractConstructor<V>): (V | Promise<V>)[] | undefined;
     tryResolveAll(token: PropertyKey): unknown;
+    /** The context of a call through a public method: the running factory's, or the outside of this scope. */
+    private entry;
+    private describe;
+    private check;
+    private lookup;
+    /** Create a value that may leave this scope; a synchronous value passes the policy's return check here. */
+    private create;
     /**
-     * Internal resolution logic shared by resolve and tryResolve.
-     * Resolves the last registered factory for the token.
+     * Shape a created value for the caller.
      *
-     * @param token Token to resolve
-     * @param required If true, throws when the token is not registered. If false, returns undefined.
-     * @returns The resolved instance, or undefined if not registered and required is false
+     * The return check runs on every resolution, so under a policy with a return check, an asynchronous
+     * creation leaving the scope is handed out as a per-call Promise that checks the resolved value. No
+     * listener is attached to a Promise already handed out. The per-call Promise is built only after every
+     * synchronous failure is ruled out, so no Promise is left without a receiver.
      */
+    private handOut;
     private resolveToken;
-    /**
-     * Internal resolution logic shared by resolveAll and tryResolveAll.
-     * Resolves all registered factories for the token.
-     *
-     * @param token Token to resolve
-     * @param required If true, throws when the token is not registered. If false, returns undefined.
-     * @returns An array of resolved instances, or undefined if not registered and required is false
-     */
     private resolveAllTokens;
+    private instantiate;
 }

package/dist/scope/index.d.ts

@@ -1,7 +1,26 @@
 import type { Container } from '../container/index.js';
+import { type PolicyState } from '../container/policy.js';
 import type { DisposableContainer, DisposableScope } from '../disposable/index.js';
-import { type ContainerInternals, INTERNALS } from '../internal.js';
-import type { AbstractConstructor, Registration } from '../resolver/index.js';
+import type { REGISTRATION_STATE } from '../internal.js';
+import { type ContainerInternals, INTERNALS, type ScopeInternals } from '../internal.js';
+import type { AnyMetadataKey, MetadataReader } from '../metadata/index.js';
+import type { AbstractConstructor, Lifetime, Registration } from '../resolver/index.js';
+import { type OperationsScope, type OperationsScopeOptions } from './operations.js';
+export interface RegistrationDescription {
+    readonly token: unknown;
+    readonly lifetime: Lifetime;
+    readonly metadata: MetadataReader;
+    readonly entrypoint: boolean;
+}
+export interface ResolutionEvent extends RegistrationDescription {
+    readonly requester: RegistrationDescription | undefined;
+    readonly path: readonly unknown[];
+}
+export type BeforeResolve = (event: ResolutionEvent) => void;
+export interface ScopeOptions {
+    readonly access?: never;
+    readonly beforeResolve?: BeforeResolve;
+}
 /**
  * Create a new scope (child container) from a Container, Scope, or their disposable variants.
  *
@@ -12,10 +31,14 @@ import type { AbstractConstructor, Registration } from '../resolver/index.js';
  * @returns A new Scope instance
  * @throws ContainerError if the source has been disposed
  */
-export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function createScope<C extends {
+    readonly [INTERNALS]: ContainerInternals;
+    readonly [REGISTRATION_STATE]: unknown;
+}>(source: C, options: OperationsScopeOptions): OperationsScope<C[typeof REGISTRATION_STATE]>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Required extends readonly AnyMetadataKey[], Registrations>(source: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations>, options?: ScopeOptions): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Registrations>(source: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>, options?: ScopeOptions): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Required extends readonly AnyMetadataKey[], Registrations>(source: DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations>, options?: ScopeOptions): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;
+export declare function createScope<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Registrations>(source: DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>, options?: ScopeOptions): Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;
 /**
  * Scoped child container.
  *
@@ -30,20 +53,21 @@ export declare function createScope<T, Sync extends AbstractConstructor, Async e
  * @template ScopedSync Union of scoped sync class constructors
  * @template ScopedAsync Union of scoped async class constructors
  */
-export declare class Scope<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 Scope<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never, Registrations = unknown> {
     private readonly registrations;
     private readonly singletonCache;
     private readonly scopedCache;
-    private readonly resolvingTokens;
-    private singletonDepth;
+    private readonly beforeResolve;
+    private readonly policy;
     private disposed;
     /**
      * Internal state accessor for extension modules (scope, disposable).
      *
      * @internal
      */
-    readonly [INTERNALS]: ContainerInternals;
-    constructor(registrations: Map<unknown, Registration[]>, singletonCache: Map<Registration, unknown>);
+    readonly [REGISTRATION_STATE]: Registrations;
+    readonly [INTERNALS]: ScopeInternals;
+    constructor(registrations: Map<unknown, Registration[]>, singletonCache: Map<Registration, unknown>, beforeResolve?: readonly BeforeResolve[], policy?: PolicyState);
     /**
      * Resolve an instance for the given token.
      *
@@ -99,22 +123,23 @@ export declare class Scope<T = Record<never, never>, Sync extends AbstractConstr
     tryResolveAll<K extends keyof (T & ScopedT)>(token: K): (T & ScopedT)[K][] | undefined;
     tryResolveAll<V>(token: AbstractConstructor<V>): (V | Promise<V>)[] | undefined;
     tryResolveAll(token: PropertyKey): unknown;
+    /** The context of a call through a public method: the running factory's, or the outside of this scope. */
+    private entry;
+    private describe;
+    private check;
+    private lookup;
+    /** Create a value that may leave this scope; a synchronous value passes the policy's return check here. */
+    private create;
     /**
-     * Internal resolution logic shared by resolve and tryResolve.
-     * Resolves the last registered factory for the token.
+     * Shape a created value for the caller.
      *
-     * @param token Token to resolve
-     * @param required If true, throws when the token is not registered. If false, returns undefined.
-     * @returns The resolved instance, or undefined if not registered and required is false
+     * The return check runs on every resolution, so under a policy with a return check, an asynchronous
+     * creation leaving the scope is handed out as a per-call Promise that checks the resolved value. No
+     * listener is attached to a Promise already handed out. The per-call Promise is built only after every
+     * synchronous failure is ruled out, so no Promise is left without a receiver.
      */
+    private handOut;
     private resolveToken;
-    /**
-     * Internal resolution logic shared by resolveAll and tryResolveAll.
-     * Resolves all registered factories for the token.
-     *
-     * @param token Token to resolve
-     * @param required If true, throws when the token is not registered. If false, returns undefined.
-     * @returns An array of resolved instances, or undefined if not registered and required is false
-     */
     private resolveAllTokens;
+    private instantiate;
 }

package/dist/scope/operations.d.cts

@@ -0,0 +1,22 @@
+import type { Callable } from '../entrypoint/index.cjs';
+import type { Scope, ScopeOptions } from './index.cjs';
+type PublicState<S> = S extends {
+    readonly callable: infer F;
+} ? ([F] extends [never] ? never : S) : never;
+type Token<S> = PublicState<S> extends infer P ? (P extends {
+    readonly token: infer K;
+} ? K : never) : never;
+type Operation<S, K> = Extract<PublicState<S>, {
+    readonly token: K;
+}> extends {
+    readonly callable: infer F extends Callable;
+} ? F : never;
+export interface OperationsScopeOptions extends Omit<ScopeOptions, 'access'> {
+    readonly access: 'operations';
+}
+export interface OperationsScope<Registrations> extends AsyncDisposable {
+    get<K extends Token<Registrations>>(token: K): (...args: Parameters<Operation<Registrations, K>>) => Promise<Awaited<ReturnType<Operation<Registrations, K>>>>;
+}
+/** Build an operations scope: keep the resolver inside, and stop new calls and wait for running ones in one place. */
+export declare function operations<Registrations>(source: Scope): OperationsScope<Registrations>;
+export {};

package/dist/scope/operations.d.ts

@@ -0,0 +1,22 @@
+import type { Callable } from '../entrypoint/index.js';
+import type { Scope, ScopeOptions } from './index.js';
+type PublicState<S> = S extends {
+    readonly callable: infer F;
+} ? ([F] extends [never] ? never : S) : never;
+type Token<S> = PublicState<S> extends infer P ? (P extends {
+    readonly token: infer K;
+} ? K : never) : never;
+type Operation<S, K> = Extract<PublicState<S>, {
+    readonly token: K;
+}> extends {
+    readonly callable: infer F extends Callable;
+} ? F : never;
+export interface OperationsScopeOptions extends Omit<ScopeOptions, 'access'> {
+    readonly access: 'operations';
+}
+export interface OperationsScope<Registrations> extends AsyncDisposable {
+    get<K extends Token<Registrations>>(token: K): (...args: Parameters<Operation<Registrations, K>>) => Promise<Awaited<ReturnType<Operation<Registrations, K>>>>;
+}
+/** Build an operations scope: keep the resolver inside, and stop new calls and wait for running ones in one place. */
+export declare function operations<Registrations>(source: Scope): OperationsScope<Registrations>;
+export {};

package/docs/README.de.md

@@ -29,11 +29,11 @@ console.log(greeting);
 
 Katagami verbindet **aus Registrierungen abgeleitete Typen, Scope-Prüfungen zur Compile-Zeit und keine Laufzeitabhängigkeiten** mit gewöhnlichen TypeScript-Factories. Decorators und Metadaten sind nicht nötig. Ressourcenfreigabe und Lazy Resolution haben eigene Einstiegspunkte.
 
-**Geprüft am 2026-09-11**, anhand stabiler npm-Versionen und offizieller Quellen. Siehe [Versionen und Quellen](./choosing-di.md#comparison-sources) sowie den [vollständigen Vergleich mit Async-Verhalten und Ressourcenfreigabe](../README.md#library-comparison).
+**Geprüft am 2026-09-11**, anhand stabiler npm-Versionen und offizieller Quellen. Die Katagami-Angaben beschreiben diese Version (4.0.0). Siehe [Versionen und Quellen](./choosing-di.md#comparison-sources) sowie den [vollständigen Vergleich mit Async-Verhalten und Ressourcenfreigabe](../README.md#library-comparison).
 
 | Bibliothek / Version | Abhängigkeitstypen und Registrierungsprüfung | Scope-Verhalten |
 | --- | --- | --- |
-| **Katagami 3.0.2** | **Sammelt Literal-/unique-symbol-Tokens; fehlende erforderliche Tokens sind Typfehler** | **Scoped-Tokens im Resolver von Singleton-/Transient-Factories ausgeschlossen** |
+| **Katagami 4.0.0** | **Sammelt Literal-/unique-symbol-Tokens; fehlende erforderliche Tokens sind Typfehler** | **Scoped-Tokens im Resolver von Singleton-/Transient-Factories ausgeschlossen** |
 | InversifyJS 8.2.3 | Typisierte Bindings; Existenzprüfung zur Laufzeit | Konfigurierte Binding-Lebensdauer |
 | tsyringe 4.10.0 | Klassen-/generische Typen; Registrierungsprüfung zur Laufzeit | Lebensdauer und Kindcontainer |
 | TypeDI 0.10.0 | Klassen und `Token<T>`; Registrierungsprüfung zur Laufzeit | Geteilte/Transient-Services, benannte Container |
@@ -74,6 +74,7 @@ Unterstützt Singleton, Transient und Scoped, Modulkomposition mit use(), asynch
 - [Anleitung für KI-Agenten (Englisch)](./ai-coding-agents.md)
 - [Typgarantien (Englisch)](./type-safety.md)
 - [API und Anwendung (Englisch)](./guide.md)
+- [Registrierungsrichtlinien und Operationen (Englisch)](./registration-policies.md)
 - [Starter für Anfrage-Scopes (Englisch)](../examples/request-scope/README.md)
 - [DI auswählen (Englisch)](./choosing-di.md)