di-bag 0.1.0

package/dist/provider-operations.d.ts

@@ -0,0 +1,59 @@
+import type { ArgumentReference } from './dependency-references';
+import type { Factory } from './registration';
+import type { AcquisitionMode } from './acquisition-mode';
+import type { LifetimePolicy } from './lifetime';
+interface SourceOperation {
+    readonly kind: 'source';
+    readonly create: Factory;
+    readonly acquisitionMode: AcquisitionMode;
+    readonly tokenKeys: readonly symbol[];
+    readonly references: readonly ArgumentReference[];
+    readonly contextual: boolean;
+    readonly dispose?: (value: never) => void | Promise<void>;
+}
+interface MetadataOperation {
+    readonly kind: 'metadata';
+    readonly metadata: Readonly<object>;
+}
+export interface OwnedOperation {
+    readonly kind: 'owned';
+    readonly dispose: (value: never) => void | Promise<void>;
+}
+interface MapOperation {
+    readonly kind: 'map-sync' | 'map-async';
+    readonly acquisitionMode: AcquisitionMode;
+    readonly project: (this: void, value: never) => unknown;
+}
+interface FrameOperation {
+    readonly kind: 'frame-sync' | 'frame-async';
+    readonly acquisitionMode: AcquisitionMode;
+    readonly project: (this: void, value: never) => {
+        readonly value: unknown;
+        readonly frame: unknown;
+    };
+}
+export type ProviderOperation = MetadataOperation | OwnedOperation | MapOperation | FrameOperation;
+export interface ProviderDescription {
+    readonly lifetime: LifetimePolicy;
+    readonly alias?: string | symbol;
+    readonly source: SourceOperation;
+    readonly operations: readonly ProviderOperation[];
+    readonly metadata: Readonly<object>;
+}
+export declare function sourceDescription(create: Factory, dispose?: (value: never) => void | Promise<void>, tokenKeys?: readonly symbol[], acquisitionMode?: AcquisitionMode, contextual?: boolean, references?: readonly ArgumentReference[]): ProviderDescription;
+/** One registry authenticates both ownership handles and transformed providers. */
+export declare function retainDescription(handle: object, description: ProviderDescription): void;
+export declare function describe(registration: unknown): ProviderDescription;
+export declare function normalize(registration: unknown): {
+    lifetime: LifetimePolicy;
+    alias?: string | symbol;
+    create: Factory;
+    acquisitionMode: AcquisitionMode;
+    tokenKeys: readonly symbol[];
+    references: readonly ArgumentReference[];
+    contextual: boolean;
+    dispose?: (value: never) => void | Promise<void>;
+    metadata: Readonly<object>;
+    operations: readonly ProviderOperation[];
+};
+export {};

package/dist/provider-operations.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceDescription = sourceDescription;
+exports.retainDescription = retainDescription;
+exports.describe = describe;
+exports.normalize = normalize;
+const errors_1 = require("./errors");
+const emptyMetadata = Object.freeze({});
+const scopedLifetime = Object.freeze({ kind: 'scoped', allowScopedDependencies: false });
+const descriptions = new WeakMap();
+function sourceDescription(create, dispose, tokenKeys = [], acquisitionMode = 'auto', contextual = false, references = []) {
+    const selected = Object.freeze([...tokenKeys]);
+    const argumentsSnapshot = Object.freeze(references.map(reference => Object.freeze({ ...reference })));
+    const source = Object.freeze(dispose ? { kind: 'source', create, dispose, tokenKeys: selected, references: argumentsSnapshot, acquisitionMode, contextual } : { kind: 'source', create, tokenKeys: selected, references: argumentsSnapshot, acquisitionMode, contextual });
+    return Object.freeze({ source, operations: Object.freeze([]), metadata: emptyMetadata, lifetime: scopedLifetime });
+}
+/** One registry authenticates both ownership handles and transformed providers. */
+function retainDescription(handle, description) {
+    descriptions.set(handle, description);
+    Object.freeze(handle);
+}
+function describe(registration) {
+    if (typeof registration === 'function')
+        return sourceDescription(registration);
+    if (typeof registration === 'object' && registration !== null) {
+        const description = descriptions.get(registration);
+        if (description)
+            return description;
+    }
+    throw (0, errors_1.libraryError)('DI_BAG_INVALID_REGISTRATION', 'invalid factory registration', { operation: 'register' });
+}
+function normalize(registration) {
+    const description = describe(registration);
+    const { create, dispose, tokenKeys, references, acquisitionMode, contextual } = description.source;
+    const { metadata, operations, lifetime } = description;
+    const alias = description.alias === undefined ? {} : { alias: description.alias };
+    return dispose ? { ...alias, create, dispose, tokenKeys, references, acquisitionMode, metadata, operations, lifetime, contextual } : { ...alias, create, tokenKeys, references, acquisitionMode, metadata, operations, lifetime, contextual };
+}

package/dist/provider.d.ts

@@ -0,0 +1,199 @@
+import type { FactoryWithDisposal, Factory, Registration } from './registration';
+import type { Unsatisfied } from './types';
+import type { ProviderOperation } from './provider-operations';
+import type { TokenBase, TokenKey, TokenService } from './tokens';
+import type { GraphContract, TokenDependencyContract, OpaqueGraph, TokenTupleAdmission, ReboundGraph } from './token-types';
+import type { Acquired, AcquisitionMode, ModeOptions } from './acquisition-mode';
+declare const providerInvariant: unique symbol;
+/** A type-only common contract for immutable provider descriptions. */
+declare class ProviderBase {
+    private readonly nominal;
+}
+/**
+ * An immutable provider description retaining factory, metadata, inspection-frame,
+ * dependency-graph, and acquired-value contracts.
+ *
+ * Create providers through {@link DiBagApi.fromFactory}, composition adapters, or provider
+ * decorators. This type-only class has no public constructor.
+ * @typeParam F - The exact exposed factory signature, including named dependencies.
+ * @typeParam M - Static registration metadata available before resolution.
+ * @typeParam A - The ordered tuple of acquisition metadata frame payloads.
+ * @typeParam G - The retained token, lifetime, and graph compatibility contract.
+ * @typeParam V - The raw or fulfilled value supplied to an outer disposal stage.
+ */
+declare class Provider<F extends Factory, M extends object = Readonly<{}>, A extends readonly unknown[] = readonly [], G extends GraphContract = TokenDependencyContract, V = Awaited<ReturnType<F>>> extends ProviderBase {
+    /** @internal */
+    readonly [providerInvariant]: (value: [F, M, A, G, V]) => [F, M, A, G, V];
+}
+/** Internal construction bridge; authentication remains in retainDescription. */
+export declare function createProvider<F extends Factory, M extends object, A extends readonly unknown[], G extends GraphContract, V>(): Provider<F, M, A, G, V>;
+export type ProviderContext<F extends Factory, G extends GraphContract = GraphContract> = ProviderBase & {
+    readonly [providerInvariant]: (...args: never[]) => [F, object, readonly unknown[], G, unknown];
+};
+/** Extract the callable factory contract retained by a registration. */
+export type ProviderFactory<R extends Registration> = R extends infer T & {} ? FactoryOf<T> : never;
+type FactoryOf<R> = R extends Factory ? R : R extends {
+    create: infer F extends Factory;
+} ? F : R extends ProviderContext<infer F> ? F : R extends ProviderBase ? (this: void, deps: unknown) => unknown : never;
+/** Extract the exact service value exposed by a registration, including Promise identity. */
+export type ProviderOutput<R extends Registration> = ProviderBase extends R ? unknown : ReturnType<ProviderFactory<R>>;
+/** Extract the fulfilled or raw value passed to the registration's outer disposer. */
+export type ProviderAcquiredValue<R extends Registration> = ProviderBase extends R ? unknown : R extends infer T & {} ? AcquiredOf<T> : unknown;
+type AcquiredOf<R> = R extends {
+    readonly [providerInvariant]: (...args: never[]) => [Factory, object, readonly unknown[], GraphContract, infer V];
+} ? V : R extends Factory ? Awaited<ReturnType<R>> : R extends FactoryWithDisposal<infer F> ? Awaited<ReturnType<F>> : unknown;
+/** Extract the registration's named dependency object. */
+export type ProviderNamedDependencies<R extends Registration> = ProviderBase extends R ? unknown : Parameters<ProviderFactory<R>> extends [] ? Record<never, never> : Exclude<Parameters<ProviderFactory<R>>[0], undefined>;
+/** Extract static metadata attached to a registration. */
+export type ProviderRegistrationMetadata<R> = R extends infer T & {} ? MetadataOf<T> : unknown;
+type MetadataOf<R> = R extends Provider<infer _F, infer M, infer _A, infer _G, infer _V> ? M : R extends Factory | FactoryWithDisposal<Factory> ? Readonly<{}> : unknown;
+/** Extract the ordered acquisition-frame metadata tuple exposed by inspection. */
+export type ProviderAcquisitionMetadata<R> = ProviderBase extends R ? readonly unknown[] : R extends infer T & {} ? AcquisitionMetadataOf<T> : readonly unknown[];
+type AcquisitionMetadataOf<R> = R extends Provider<infer _F, infer _M, infer A, infer _G, infer _V> ? A : R extends Factory | FactoryWithDisposal<Factory> ? readonly [] : readonly unknown[];
+/** Extract the retained typed-token and lifetime graph contract. */
+export type ProviderGraphContract<R> = ProviderBase extends R ? OpaqueGraph : R extends infer T & {} ? GraphOf<T> : OpaqueGraph;
+type GraphOf<R> = R extends Provider<infer _F, infer _M, infer _A, infer G, infer _V> ? G : R extends Factory | FactoryWithDisposal<Factory> ? TokenDependencyContract : R extends ProviderContext<Factory, infer G> ? G : OpaqueGraph;
+type RequiredTokens<G> = G extends TokenDependencyContract<infer T, TokenBase, readonly TokenBase[]> ? T[number] : TokenBase;
+type Bound<G> = G extends TokenDependencyContract<readonly TokenBase[], infer B, readonly TokenBase[]> ? B : TokenBase;
+type OptionalTokens<G> = G extends TokenDependencyContract<readonly TokenBase[], TokenBase, infer O> ? O[number] : TokenBase;
+/** Extract token collection requirements from a registration. */
+export type ProviderCollectionTokens<R> = ProviderGraphContract<R> extends infer G ? G extends {
+    readonly all: infer T extends readonly TokenBase[];
+} ? T[number] : never : never;
+/** Extract optional typed-token requirements from a registration. */
+export type ProviderOptionalTokens<R> = OptionalTokens<ProviderGraphContract<R>>;
+/** Extract required typed-token dependencies from a registration. */
+export type ProviderRequiredTokens<R> = RequiredTokens<ProviderGraphContract<R>>;
+export type BoundToken<R> = Bound<ProviderGraphContract<R>>;
+/** Bind a checked output without changing the reusable source's retained needs. */
+export declare function withTokenBinding<T extends TokenBase, R extends Registration>(token: T & TokenTupleAdmission<readonly [T]>, registration: R & Registration & ([ProviderOutput<NoInfer<R>>] extends [TokenService<NoInfer<T>>] ? unknown : Unsatisfied<'token binding output is not assignable to its service', {
+    token: TokenKey<T>;
+    expected: TokenService<T>;
+    provided: ProviderOutput<R>;
+}>)): Provider<ProviderFactory<R>, RetainedMetadata<R>, ProviderAcquisitionMetadata<R>, ReboundGraph<ProviderGraphContract<R>, T>, ProviderAcquiredValue<R>>;
+type MappedFactory<R extends Registration, O> = (this: void, deps: ProviderNamedDependencies<R>) => O;
+export type RetainedMetadata<R> = ProviderRegistrationMetadata<R> extends object ? ProviderRegistrationMetadata<R> : object;
+/** Extend an authenticated description without exposing its operations. */
+export declare function transform<R extends Registration, F extends Factory, A extends readonly unknown[] = ProviderAcquisitionMetadata<R>, V = Awaited<ReturnType<F>>>(registration: R, operation: ProviderOperation): Provider<F, RetainedMetadata<R>, A, ProviderGraphContract<R>, V>;
+/**
+ * Transform the exact exposed service without awaiting the input or callback result.
+ * Retains dependencies, lifetime, metadata, and earlier cleanup; the result adds no ownership.
+ * @param registration - The source registration whose exact output is transformed.
+ * @param options - Direct mode, a transform callback, and optional output acquisitionMode (auto by default).
+ * @returns A provider exposing the callback's exact result, with the selected output acquisition policy.
+ * @typeParam R - The source registration and its retained contracts.
+ * @typeParam P - The exact transform callback signature and output.
+ * @typeParam M - The result's auto, raw, or nativePromise acquisition policy.
+ */
+export declare function transformService<R extends Registration, P extends (this: void, value: ProviderOutput<NoInfer<R>>) => ('nativePromise' extends M ? Promise<unknown> : unknown), M extends AcquisitionMode = 'auto'>(registration: R & Registration, options: {
+    readonly mode: 'direct';
+    readonly transform: P;
+} & ModeOptions<M>): Provider<MappedFactory<R, ReturnType<P>>, RetainedMetadata<R>, ProviderAcquisitionMetadata<R>, ProviderGraphContract<R>, Acquired<ReturnType<P>, M>>;
+/**
+ * Await the input and adopt the transformed result into a native Promise stage.
+ * Retains dependencies, lifetime, metadata, and existing cleanup; adds no result ownership.
+ * @param registration - The source registration whose fulfilled value is transformed.
+ * @param options - Awaited mode and a transform callback; acquisitionMode cannot be overridden.
+ * @returns A provider exposing a Promise of the awaited transform result.
+ * @typeParam R - The source registration and retained contracts.
+ * @typeParam P - The callback signature; its result may itself be a Promise.
+ */
+export declare function transformService<R extends Registration, P extends (this: void, value: Awaited<ProviderOutput<NoInfer<R>>>) => unknown>(registration: R & Registration, options: {
+    readonly mode: 'awaited';
+    readonly transform: P;
+    readonly acquisitionMode?: never;
+}): Provider<MappedFactory<R, Promise<Awaited<ReturnType<P>>>>, RetainedMetadata<R>, ProviderAcquisitionMetadata<R>, ProviderGraphContract<R>>;
+type InvalidAcquisitionMetadata<M> = M extends unknown ? M extends readonly unknown[] | ((...args: never[]) => unknown) ? true : 'then' extends keyof M ? unknown extends M['then'] ? true : Extract<M['then'], (...args: never[]) => unknown> extends never ? never : true : never : never;
+type AcquisitionMetadataAdmission<M> = [InvalidAcquisitionMetadata<M>] extends [never] ? unknown : Unsatisfied<'acquisition metadata must be a synchronous object record', {}>;
+type AcquisitionFrames<R, M> = readonly [...ProviderAcquisitionMetadata<R>, Readonly<M>];
+export type MetadataKeyUnion<M> = M extends unknown ? keyof M : never;
+type NonFiniteKeys<M> = M extends unknown ? {
+    [K in keyof M]-?: Record<never, never> extends Record<K, never> ? K : never;
+}[keyof M] : never;
+type MetadataKeys<R, M> = [NonFiniteKeys<M> | Extract<MetadataKeyUnion<M>, number>] extends [never] ? [MetadataKeyUnion<M> & MetadataKeyUnion<ProviderRegistrationMetadata<R>>] extends [never] ? unknown : Unsatisfied<'duplicate metadata keys', {
+    duplicates: MetadataKeyUnion<M> & MetadataKeyUnion<ProviderRegistrationMetadata<R>>;
+}> : Unsatisfied<'metadata keys must be finite string or unique-symbol keys', {}>;
+export type { Provider, ProviderBase };
+/**
+ * Attach registration metadata without evaluating the source or changing ownership.
+ * Own keys are copied and frozen; static key collisions reject before getters run.
+ * @param registration - The source registration to describe.
+ * @param options - A static record with finite noncolliding string or unique-symbol keys.
+ * @returns A provider preserving exact output, acquisition policy, and ordered dynamic frames.
+ * @typeParam R - The source registration and retained contracts.
+ * @typeParam M - The additional static registration metadata record.
+ */
+export declare function withMetadata<R extends Registration, M extends object>(registration: R & Registration, options: {
+    readonly static: M & MetadataKeys<NoInfer<R>, M>;
+    readonly dynamic?: never;
+}): Provider<ProviderFactory<R>, Readonly<RetainedMetadata<R> & M>, ProviderAcquisitionMetadata<R>, ProviderGraphContract<R>, ProviderAcquiredValue<R>>;
+/**
+ * Describe the exact exposed service with a synchronous plain metadata record.
+ * Direct mode preserves Promise identity and source acquisition policy, adding no ownership.
+ * @param registration - The source registration whose exact output is described.
+ * @param options - Required static metadata and mandatory direct dynamic mode with a synchronous describe callback.
+ * @returns A provider with merged registration metadata and one appended acquisition metadata frame.
+ * @typeParam R - The source registration and retained contracts.
+ * @typeParam P - The synchronous describe callback and its record result.
+ * @typeParam M - The required static metadata record.
+ */
+export declare function withMetadata<R extends Registration, P extends (this: void, value: ProviderOutput<NoInfer<R>>) => object, M extends object = {}>(registration: R & Registration, options: {
+    readonly static: M & MetadataKeys<NoInfer<R>, M>;
+    readonly dynamic: {
+        readonly mode: 'direct';
+        readonly describe: P & AcquisitionMetadataAdmission<ReturnType<P>>;
+    };
+}): Provider<ProviderFactory<R>, Readonly<RetainedMetadata<R> & M>, AcquisitionFrames<R, ReturnType<P>>, ProviderGraphContract<R>, ProviderAcquiredValue<R>>;
+/**
+ * Describe the exact exposed service with a synchronous plain metadata record.
+ * Direct mode preserves Promise identity and source acquisition policy, adding no ownership.
+ * @param registration - The source registration whose exact output is described.
+ * @param options - Optional static metadata and mandatory direct dynamic mode with a synchronous describe callback.
+ * If the static level may be absent, its added keys remain optional in inspection.
+ * @returns A provider with merged registration metadata and one appended acquisition metadata frame.
+ * @typeParam R - The source registration and retained contracts.
+ * @typeParam P - The synchronous describe callback and its record result.
+ * @typeParam M - The optional static metadata record.
+ */
+export declare function withMetadata<R extends Registration, P extends (this: void, value: ProviderOutput<NoInfer<R>>) => object, M extends object = {}>(registration: R & Registration, options: {
+    readonly static?: M & MetadataKeys<NoInfer<R>, M>;
+    readonly dynamic: {
+        readonly mode: 'direct';
+        readonly describe: P & AcquisitionMetadataAdmission<ReturnType<P>>;
+    };
+}): Provider<ProviderFactory<R>, Readonly<RetainedMetadata<R> & Partial<M>>, AcquisitionFrames<R, ReturnType<P>>, ProviderGraphContract<R>, ProviderAcquiredValue<R>>;
+/**
+ * Await the source and append a synchronous metadata record through a native Promise stage.
+ * Existing ownership and metadata frames remain ordered; annotation adds no ownership.
+ * @param registration - The source registration whose fulfilled value is described.
+ * @param options - Required static metadata and mandatory awaited mode with a synchronous describe callback.
+ * @returns A provider exposing a Promise of the source value with one appended metadata frame.
+ * @typeParam R - The source registration and retained contracts.
+ * @typeParam P - The synchronous describe callback and its record result.
+ * @typeParam M - The required static metadata record.
+ */
+export declare function withMetadata<R extends Registration, P extends (this: void, value: Awaited<ProviderOutput<NoInfer<R>>>) => object, M extends object = {}>(registration: R & Registration, options: {
+    readonly static: M & MetadataKeys<NoInfer<R>, M>;
+    readonly dynamic: {
+        readonly mode: 'awaited';
+        readonly describe: P & AcquisitionMetadataAdmission<ReturnType<P>>;
+    };
+}): Provider<MappedFactory<R, Promise<Awaited<ProviderOutput<R>>>>, Readonly<RetainedMetadata<R> & M>, AcquisitionFrames<R, ReturnType<P>>, ProviderGraphContract<R>, Awaited<ProviderOutput<R>>>;
+/**
+ * Await the source and append a synchronous metadata record through a native Promise stage.
+ * Existing ownership and metadata frames remain ordered; annotation adds no ownership.
+ * @param registration - The source registration whose fulfilled value is described.
+ * @param options - Optional static metadata and mandatory awaited mode with a synchronous describe callback.
+ * If the static level may be absent, its added keys remain optional in inspection.
+ * @returns A provider exposing a Promise of the source value with one appended metadata frame.
+ * @typeParam R - The source registration and retained contracts.
+ * @typeParam P - The synchronous describe callback and its record result.
+ * @typeParam M - The optional static metadata record.
+ */
+export declare function withMetadata<R extends Registration, P extends (this: void, value: Awaited<ProviderOutput<NoInfer<R>>>) => object, M extends object = {}>(registration: R & Registration, options: {
+    readonly static?: M & MetadataKeys<NoInfer<R>, M>;
+    readonly dynamic: {
+        readonly mode: 'awaited';
+        readonly describe: P & AcquisitionMetadataAdmission<ReturnType<P>>;
+    };
+}): Provider<MappedFactory<R, Promise<Awaited<ProviderOutput<R>>>>, Readonly<RetainedMetadata<R> & Partial<M>>, AcquisitionFrames<R, ReturnType<P>>, ProviderGraphContract<R>, Awaited<ProviderOutput<R>>>;

package/dist/provider.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProvider = createProvider;
+exports.withTokenBinding = withTokenBinding;
+exports.transform = transform;
+exports.transformService = transformService;
+exports.withMetadata = withMetadata;
+const errors_1 = require("./errors");
+const provider_operations_1 = require("./provider-operations");
+const tokens_1 = require("./tokens");
+const acquisition_mode_1 = require("./acquisition-mode");
+// Non-generic admission preserves invariant concrete contracts at graph boundaries.
+/** A type-only common contract for immutable provider descriptions. */
+class ProviderBase {
+}
+/**
+ * An immutable provider description retaining factory, metadata, inspection-frame,
+ * dependency-graph, and acquired-value contracts.
+ *
+ * Create providers through {@link DiBagApi.fromFactory}, composition adapters, or provider
+ * decorators. This type-only class has no public constructor.
+ * @typeParam F - The exact exposed factory signature, including named dependencies.
+ * @typeParam M - Static registration metadata available before resolution.
+ * @typeParam A - The ordered tuple of acquisition metadata frame payloads.
+ * @typeParam G - The retained token, lifetime, and graph compatibility contract.
+ * @typeParam V - The raw or fulfilled value supplied to an outer disposal stage.
+ */
+class Provider extends ProviderBase {
+}
+/** Internal construction bridge; authentication remains in retainDescription. */
+function createProvider() {
+    return new Provider();
+}
+/** Bind a checked output without changing the reusable source's retained needs. */
+function withTokenBinding(token, registration) {
+    (0, tokens_1.readTokenKey)(token);
+    const handle = new Provider();
+    (0, provider_operations_1.retainDescription)(handle, (0, provider_operations_1.describe)(registration));
+    return handle;
+}
+/** Extend an authenticated description without exposing its operations. */
+function transform(registration, operation) {
+    const description = (0, provider_operations_1.describe)(registration);
+    const handle = new Provider();
+    (0, provider_operations_1.retainDescription)(handle, Object.freeze({ ...description, operations: Object.freeze([...description.operations, Object.freeze(operation)]) }));
+    return handle;
+}
+function transformService(registration, options) {
+    if (typeof options !== 'object' || options === null || (options.mode !== 'direct' && options.mode !== 'awaited'))
+        throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_TRANSFORM', 'transformService mode must be direct or awaited', { operation: 'transformService' });
+    if (typeof options.transform !== 'function')
+        throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_TRANSFORM', 'transformService requires a transform callback', { operation: 'transformService' });
+    if (options.mode === 'awaited' && 'acquisitionMode' in options)
+        throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_TRANSFORM', 'transformService awaited mode does not accept acquisitionMode', { operation: 'transformService' });
+    return transform(registration, { kind: options.mode === 'direct' ? 'map-sync' : 'map-async', project: options.transform, acquisitionMode: options.mode === 'direct' ? (0, acquisition_mode_1.acquisitionMode)(options) : 'nativePromise' });
+}
+function annotate(registration, callback, async) {
+    if (typeof callback !== 'function')
+        throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_METADATA', 'acquisition metadata requires a function', { operation: 'withMetadata' });
+    const description = (0, provider_operations_1.describe)(registration);
+    // Decoration retains the current output stage's mode even across metadata and ownership.
+    let acquisitionMode = description.source.acquisitionMode;
+    for (const operation of description.operations) {
+        if ('acquisitionMode' in operation)
+            acquisitionMode = operation.acquisitionMode;
+    }
+    return transform(registration, {
+        kind: async ? 'frame-async' : 'frame-sync',
+        acquisitionMode: async ? 'nativePromise' : acquisitionMode,
+        project(value) {
+            const metadata = callback(value);
+            if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata)) {
+                return invalidAcquisitionMetadata(metadata);
+            }
+            const prototype = Object.getPrototypeOf(metadata);
+            if (prototype !== null && prototype !== Object.prototype)
+                return invalidAcquisitionMetadata(metadata);
+            const frame = Object.create(null);
+            for (const key of Reflect.ownKeys(metadata))
+                frame[key] = Reflect.get(metadata, key);
+            const then = Object.hasOwn(frame, 'then') ? frame.then : Reflect.get(metadata, 'then');
+            if (typeof then === 'function')
+                return invalidAcquisitionMetadata(metadata);
+            return { value, frame: Object.freeze(frame) };
+        },
+    });
+}
+function invalidAcquisitionMetadata(value) {
+    // A widened callback can return a rejected Promise. Observe that invalid result
+    // before throwing, without reading its `then` or assimilating service values.
+    // The intrinsic rejects non-Promise receivers without invoking user code.
+    try {
+        Promise.prototype.then.call(value, () => { }, () => { });
+    }
+    catch { /* Not an observable native Promise. */ }
+    throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_METADATA', 'acquisition metadata must be a synchronous plain object record', { operation: 'withMetadata' });
+}
+/**
+ * Attach static metadata without evaluating the registration or transferring ownership.
+ * Own string and symbol keys are copied and frozen; payload objects keep their identity.
+ * @param registration - The source registration to describe.
+ * @param metadata - A finite, noncolliding metadata record.
+ * @returns A provider retaining the source output, dependencies, frames, and ownership stages.
+ * @throws If metadata is not an object or an own key duplicates existing metadata.
+ */
+function attachStaticMetadata(registration, metadata) {
+    const description = (0, provider_operations_1.describe)(registration);
+    if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata)) {
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_METADATA', 'metadata must be a string or symbol-keyed object', { operation: 'withMetadata' });
+    }
+    const keys = Reflect.ownKeys(metadata);
+    for (const key of keys) {
+        if (Object.hasOwn(description.metadata, key))
+            throw (0, errors_1.libraryError)('DI_BAG_DUPLICATE_METADATA', `duplicate metadata: ${String(key)}`, { operation: 'withMetadata', key });
+    }
+    // Preflight all keys before evaluating a getter; copy hidden entries as data too.
+    const added = Object.create(null);
+    for (const key of keys)
+        added[key] = Reflect.get(metadata, key);
+    Object.freeze(added);
+    const combined = Object.freeze(Object.assign(Object.create(null), description.metadata, added));
+    const handle = new Provider();
+    (0, provider_operations_1.retainDescription)(handle, Object.freeze({
+        ...description,
+        operations: Object.freeze([...description.operations, Object.freeze({ kind: 'metadata', metadata: added })]),
+        metadata: combined,
+    }));
+    return handle;
+}
+function withMetadata(registration, options) {
+    if (typeof options !== 'object' || options === null || Array.isArray(options))
+        throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_METADATA', 'withMetadata requires static or dynamic metadata', { operation: 'withMetadata' });
+    const hasStatic = Object.hasOwn(options, 'static');
+    const hasDynamic = Object.hasOwn(options, 'dynamic');
+    if (!hasStatic && !hasDynamic)
+        throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_METADATA', 'withMetadata requires static or dynamic metadata', { operation: 'withMetadata' });
+    if ((!hasStatic && 'static' in options) || (!hasDynamic && 'dynamic' in options))
+        throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_METADATA', 'withMetadata static and dynamic options must be own properties', { operation: 'withMetadata' });
+    // Snapshot every executed dynamic field once, before static metadata getters can
+    // change it. A checked mode must be the same mode used to build the operation.
+    let frame;
+    if (hasDynamic) {
+        const dynamic = options.dynamic;
+        if (typeof dynamic !== 'object' || dynamic === null)
+            throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_METADATA', 'withMetadata dynamic mode must be direct or awaited', { operation: 'withMetadata' });
+        const mode = dynamic.mode;
+        if (mode !== 'direct' && mode !== 'awaited')
+            throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_METADATA', 'withMetadata dynamic mode must be direct or awaited', { operation: 'withMetadata' });
+        const callback = dynamic.describe;
+        if (typeof callback !== 'function')
+            throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_METADATA', 'acquisition metadata requires a function', { operation: 'withMetadata' });
+        frame = { mode, describe: callback };
+    }
+    let result = hasStatic ? attachStaticMetadata(registration, options.static) : registration;
+    if (frame !== undefined)
+        result = annotate(result, frame.describe, frame.mode === 'awaited');
+    return result;
+}

package/dist/registration.d.ts

@@ -0,0 +1,32 @@
+import type { ProviderBase, Provider, ProviderFactory, ProviderAcquiredValue, RetainedMetadata, ProviderAcquisitionMetadata, ProviderGraphContract } from './provider';
+export { normalize } from './provider-operations';
+export type Factory = (this: void, deps: never) => unknown;
+/** A nominal registration pairing a factory with fulfilled-value cleanup. */
+declare class FactoryWithDisposal<F extends Factory> {
+    readonly create: F;
+    private readonly nominal;
+    constructor(create: F);
+}
+/** A nominal registration pairing a factory with fulfilled-value cleanup. */
+export type { FactoryWithDisposal };
+/** A factory, disposable factory, or immutable provider accepted by builders and decorators. */
+export type Registration = Factory | FactoryWithDisposal<Factory> | ProviderBase;
+export type Registrations = Record<string, Registration>;
+/**
+ * Declare that each acquiring bag owns a factory's fulfilled value.
+ * Neither callback runs until acquisition; cleanup runs once after dependent resources.
+ * @param create - The receiver-free service factory.
+ * @param dispose - Cleanup for its fulfilled value; it may complete synchronously or asynchronously.
+ * @returns A nominal disposable registration preserving the factory's exact output.
+ */
+export declare function withDisposal<F extends Factory>(create: F, dispose: (this: void, value: Awaited<ReturnType<NoInfer<F>>>) => void | Promise<void>): FactoryWithDisposal<F>;
+/**
+ * Add an ownership stage to an existing registration.
+ * Earlier disposal stages remain attached and run after this stage in reverse order.
+ * @param provider - The registration whose acquired value becomes owned at this stage.
+ * @param dispose - Cleanup for the registration's acquired value.
+ * @returns A provider retaining output, dependencies, metadata, frames, and earlier ownership.
+ */
+export declare function withDisposal<R extends Registration>(provider: R & Registration, dispose: (this: void, value: ProviderAcquiredValue<NoInfer<R>>) => void | Promise<void>): Provider<ProviderFactory<R>, RetainedMetadata<R>, ProviderAcquisitionMetadata<R>, ProviderGraphContract<R>, ProviderAcquiredValue<R>>;
+/** Preflight every own key before reading getters; retain hidden own entries. */
+export declare function snapshotAdd(more: unknown, hasKey: (key: string) => boolean): Registrations;

package/dist/registration.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalize = void 0;
+exports.withDisposal = withDisposal;
+exports.snapshotAdd = snapshotAdd;
+const errors_1 = require("./errors");
+const provider_1 = require("./provider");
+const provider_operations_1 = require("./provider-operations");
+var provider_operations_2 = require("./provider-operations");
+Object.defineProperty(exports, "normalize", { enumerable: true, get: function () { return provider_operations_2.normalize; } });
+// A private member is lost on spread; structural copies cannot be registrations.
+/** A nominal registration pairing a factory with fulfilled-value cleanup. */
+class FactoryWithDisposal {
+    create;
+    constructor(create) {
+        this.create = create;
+    }
+}
+function withDisposal(registration, dispose) {
+    if (typeof registration !== 'function')
+        return (0, provider_1.transform)(registration, { kind: 'owned', dispose });
+    const handle = new FactoryWithDisposal(registration);
+    (0, provider_operations_1.retainDescription)(handle, (0, provider_operations_1.sourceDescription)(registration, dispose));
+    return handle;
+}
+/** Preflight every own key before reading getters; retain hidden own entries. */
+function snapshotAdd(more, hasKey) {
+    if (typeof more !== 'object' || more === null || Array.isArray(more)) {
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_REGISTRATION', 'registrations must be a string-keyed object', { operation: 'register' });
+    }
+    const keys = Reflect.ownKeys(more);
+    for (const key of keys) {
+        if (typeof key !== 'string')
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_REGISTRATION', 'registration keys must be strings', { operation: 'register' });
+        if (hasKey(key))
+            throw (0, errors_1.libraryError)('DI_BAG_DUPLICATE_REGISTRATION', `duplicate registration: ${key}`, { operation: 'register', key });
+    }
+    const snapshot = Object.create(null);
+    for (const key of keys) {
+        const registration = Reflect.get(more, key);
+        (0, provider_operations_1.normalize)(registration);
+        snapshot[key] = registration;
+    }
+    return snapshot;
+}

package/dist/replacement-types.d.ts

@@ -0,0 +1,30 @@
+import type { NeedConstraint, CheckedConstraints } from './module-types';
+import type { ProviderFactory } from './provider';
+import type { Registration, Registrations } from './registration';
+import type { TokenBinding, BindingOutput, TokenMember } from './token-types';
+import type { TokenBase, TokenKey } from './tokens';
+import type { Entry, RegistrationsFromEntries, IncrementalChecked, OverrideRegistrations, ReplacementKey } from './types';
+type DependencyBearingRegistration<R extends Registration> = R extends unknown ? Parameters<ProviderFactory<R>> extends [] ? never : R : never;
+export type ZeroDependencyAdmission<R extends Registration> = [
+    DependencyBearingRegistration<R>
+] extends [never] ? unknown : never;
+export type ReplacementAdmission<R extends Registrations, K extends string | TokenBase> = [
+    K
+] extends [string] ? ReplacementKey<R, K> : TokenMember<R, K>;
+export type BuilderReplacementRegistration<E extends Entry, C extends NeedConstraint, K extends string | TokenBase, V extends Registration> = [K] extends [string] ? IncrementalChecked<E, Record<K, NoInfer<V>>> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, Record<K, NoInfer<V>>>> : [K] extends [TokenBase] ? BindingOutput<NoInfer<K>, NoInfer<V>> & IncrementalChecked<E, Record<TokenKey<K>, TokenBinding<NoInfer<K>, NoInfer<V>>>> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, Record<TokenKey<K>, TokenBinding<NoInfer<K>, NoInfer<V>>>>> : never;
+type ReflectedEntry = {
+    key: never;
+    registration: TokenBinding<TokenBase, Registration>;
+};
+export type ReplacedEntries<E extends Entry, K extends string | TokenBase, V extends Registration> = [K] extends [string] ? Exclude<E, {
+    key: K;
+}> | {
+    key: K;
+    registration: V;
+} : [K] extends [TokenBase] ? Exclude<E, {
+    key: TokenKey<K>;
+}> | {
+    key: TokenKey<K>;
+    registration: TokenBinding<K, V>;
+} : E | ReflectedEntry;
+export {};

package/dist/replacement-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });