di-bag 0.1.0

package/dist/acquisition.js

@@ -0,0 +1,395 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeAcquisitions = void 0;
+const errors_1 = require("./errors");
+const errors_2 = require("./errors");
+const provider_execution_1 = require("./provider-execution");
+const acquisition_family_1 = require("./acquisition-family");
+/** Mutable, runtime-local attempts. Binding descriptions never carry ownership. */
+class ScopeAcquisitions {
+    graph;
+    context;
+    parent;
+    ownerId = Symbol('owner');
+    cache = new Map();
+    attempts = new Map();
+    retired = new Map();
+    failures = [];
+    invocationSequence = 0;
+    // Insertion order is successful ownership acceptance order, including promises.
+    owned = new Map();
+    state = 'open';
+    closing;
+    controller;
+    acquisitionContext;
+    cancellationStarted = false;
+    cancellationCause;
+    shared;
+    family;
+    constructor(graph, context, parent, shared = []) {
+        this.graph = graph;
+        this.context = context;
+        this.parent = parent;
+        this.shared = new Set(shared);
+        this.family = parent?.family ?? new acquisition_family_1.AcquisitionFamily();
+    }
+    owner(bindingId) {
+        if (this.parent && this.shared.has(bindingId))
+            return this.parent;
+        if (this.graph.registration(bindingId).lifetime.kind !== 'root')
+            return this;
+        // A child override introduces a new identity absent from older graphs.
+        // Inherited identities retain the earliest graph and its dependency context.
+        let owner = this;
+        for (let ancestor = this.parent; ancestor; ancestor = ancestor.parent) {
+            if (ancestor.graph.hasBinding(bindingId))
+                owner = ancestor;
+        }
+        return owner;
+    }
+    resolve(key) {
+        this.assertOpen();
+        return this.takeExposed(this.resolveBinding(this.graph.publicBinding(key)));
+    }
+    resolveAll(key) {
+        this.assertOpen();
+        return this.resolveCollection(key);
+    }
+    resolveCollection(key, from) {
+        return Object.freeze(this.graph.contributionBindings(key).map(id => this.takeExposed(this.resolveBinding(id, from))));
+    }
+    async acquire(key) {
+        this.assertOpen();
+        const attempt = this.resolveBinding(this.graph.publicBinding(key));
+        this.takeExposed(attempt);
+        await attempt.execution.ready();
+    }
+    takeExposed(attempt) {
+        const value = attempt.exposed;
+        // Aliases and owner routing have already selected the canonical lifetime.
+        if (attempt.transient)
+            attempt.exposed = undefined;
+        return value;
+    }
+    inspect(bindingId, path = []) {
+        if (this.parent && this.shared.has(bindingId))
+            return this.parent.inspect(bindingId, path);
+        const alias = this.graph.registration(bindingId).alias;
+        if (alias !== undefined) {
+            this.assertAliasPath(bindingId, path);
+            return this.inspect(this.graph.dependency(bindingId, alias), [...path, bindingId]);
+        }
+        const owner = this.owner(bindingId);
+        if (owner !== this)
+            return owner.inspect(bindingId);
+        const snapshots = [];
+        for (const attempt of this.attempts.values()) {
+            if (attempt.bindingId !== bindingId)
+                continue;
+            snapshots.push(Object.freeze({
+                acquisitionId: attempt.id,
+                state: attempt.state,
+                acquisitionMetadata: attempt.execution.inspectFrames(),
+            }));
+        }
+        return Object.freeze(snapshots);
+    }
+    isTransient(bindingId, path = []) {
+        if (this.parent && this.shared.has(bindingId))
+            return this.parent.isTransient(bindingId, path);
+        const description = this.graph.registration(bindingId);
+        if (description.alias === undefined)
+            return description.lifetime.kind === 'transient';
+        this.assertAliasPath(bindingId, path);
+        return this.isTransient(this.graph.dependency(bindingId, description.alias), [...path, bindingId]);
+    }
+    /** Relationship uses the effective owner graph; frames use canonical attempts. */
+    inspectDescription(bindingId) {
+        if (this.parent && this.shared.has(bindingId))
+            return this.parent.inspectDescription(bindingId);
+        const description = this.graph.registration(bindingId);
+        if (description.alias !== undefined) {
+            const target = this.graph.dependency(bindingId, description.alias);
+            return { registrationMetadata: description.metadata, aliasTarget: Object.freeze({ bindingId: target, label: this.graph.label(target) }) };
+        }
+        const owner = this.owner(bindingId);
+        return owner === this ? { registrationMetadata: description.metadata } : owner.inspectDescription(bindingId);
+    }
+    assertAliasPath(bindingId, path) {
+        if (path.includes(bindingId))
+            throw (0, errors_1.libraryError)('DI_BAG_CYCLE', `alias cycle: ${[...path, bindingId].map(id => this.graph.label(id)).join(' -> ')}`, { path: Object.freeze([...path, bindingId].map(id => this.graph.label(id))) });
+    }
+    assertOpen() {
+        if (this.state !== 'open')
+            throw (0, errors_1.libraryError)(this.state === 'closing' ? 'DI_BAG_CLOSING' : 'DI_BAG_CLOSED', `bag is ${this.state}`, { state: this.state });
+    }
+    close(beforeDispose, cause) {
+        if (this.closing)
+            return this.closing;
+        this.state = 'closing';
+        // Publish the barrier before invoking any finalizer, including reentrant ones.
+        this.closing = Promise.resolve().then(() => {
+            // Every descendant admission gate is closed before abort listeners run.
+            this.cancellationStarted = true;
+            this.cancellationCause = cause;
+            this.controller?.abort(cause);
+            return this.disposeAll(beforeDispose);
+        });
+        return this.closing;
+    }
+    getContext() {
+        if (!this.acquisitionContext) {
+            this.controller = new AbortController();
+            if (this.cancellationStarted)
+                this.controller.abort(this.cancellationCause);
+            this.acquisitionContext = Object.freeze({ signal: this.controller.signal });
+        }
+        return this.acquisitionContext;
+    }
+    resolveBinding(bindingId, from, path = []) {
+        // Sharing an alias borrows its lexical parent graph before following targets.
+        if (this.parent && this.shared.has(bindingId))
+            return this.parent.resolveBinding(bindingId, from, path);
+        const description = this.graph.registration(bindingId);
+        if (description.alias !== undefined) {
+            this.assertAliasPath(bindingId, path);
+            return this.resolveBinding(this.graph.dependency(bindingId, description.alias), from, [...path, bindingId]);
+        }
+        const { lifetime } = description;
+        // Validate before routing/cache lookup; retained proxies keep their boundary.
+        if (lifetime.kind === 'scoped' && from?.strictRoot !== undefined) {
+            throw (0, errors_1.libraryError)('DI_BAG_LIFETIME_DEPENDENCY', `root lifetime cannot capture scoped dependency: ${from.strictRoot} -> ${this.graph.label(bindingId)}`, { consumer: from.strictRoot, dependency: this.graph.label(bindingId), lifetime: 'root' });
+        }
+        const owner = this.owner(bindingId);
+        if (owner !== this)
+            return owner.resolveBinding(bindingId, from);
+        const cached = this.cache.get(bindingId);
+        if (cached) {
+            if (from)
+                this.family.recordEdge(from, cached);
+            // A factory or then getter can reenter through public resolve as well.
+            if (cached.state === 'creating')
+                this.family.ancestry(bindingId, this.ownerId, cached.label, from);
+            return cached;
+        }
+        const ancestry = this.family.ancestry(bindingId, this.ownerId, this.graph.label(bindingId), from);
+        const execution = new provider_execution_1.ProviderExecution({
+            accepted: () => { this.owned.set(attempt.id, attempt); },
+            settled: () => {
+                if (attempt.execution.state === 'failed') {
+                    this.observeAttempt(attempt, 'acquisition-failed', attempt.execution.error);
+                    this.retire(attempt);
+                }
+                else {
+                    attempt.state = 'ready';
+                    this.family.deactivate(attempt);
+                    this.observeAttempt(attempt, 'acquisition-ready');
+                }
+            },
+            drained: () => {
+                if (attempt.execution instanceof provider_execution_1.ProviderExecution)
+                    attempt.execution = attempt.execution.compact();
+            },
+            ...(this.context.observers ? {
+                cleanupStarted: () => this.observeAttempt(attempt, 'cleanup-started'),
+                cleanupCompleted: (outcome) => {
+                    this.context.observers.emit({ ...this.eventFields(attempt), kind: 'cleanup-completed', outcome });
+                },
+            } : {}),
+            invoking: () => this.invocationSequence++,
+            cleanupFailed: (sequence, error) => {
+                if (this.context.observers)
+                    this.context.observers.emit({ ...this.eventFields(attempt), kind: 'cleanup-failed', disposalSequence: sequence, error });
+                this.failures.push({ sequence, acquisitionId: attempt.id, bindingId: attempt.bindingId, label: attempt.label, error });
+            },
+        }, description, this.context);
+        const attempt = {
+            id: Symbol(this.graph.label(bindingId)),
+            bindingId,
+            ownerId: this.ownerId,
+            label: this.graph.label(bindingId),
+            dependencies: new Set(),
+            ancestry,
+            strictRoot: lifetime.kind === 'root'
+                ? lifetime.allowScopedDependencies ? undefined : this.graph.label(bindingId)
+                : from?.strictRoot,
+            state: 'creating',
+            transient: lifetime.kind === 'transient',
+            exposed: undefined,
+            execution,
+        };
+        if (lifetime.kind !== 'transient')
+            this.cache.set(bindingId, attempt);
+        this.attempts.set(attempt.id, attempt);
+        this.family.add(attempt);
+        if (from)
+            this.family.recordEdge(from, attempt);
+        const read = (key, optional = false, all = false) => {
+            // Only this attempt's in-flight factory can discover dependencies in close.
+            if (this.state === 'closed' || (this.state === 'closing' && !attempt.execution.sourceInFlight)) {
+                throw (0, errors_1.libraryError)(this.state === 'closing' ? 'DI_BAG_CLOSING' : 'DI_BAG_CLOSED', `bag is ${this.state}`, { state: this.state });
+            }
+            if (all)
+                return this.resolveCollection(key, attempt);
+            const target = this.graph.findDependency(bindingId, key);
+            if (target === undefined && !optional) {
+                const path = this.family.dependencyPath(attempt, String(key));
+                throw (0, errors_1.libraryError)('DI_BAG_MISSING_DEPENDENCY', `Cannot resolve ${JSON.stringify(attempt.label)}: dependency ${JSON.stringify(String(key))} is not registered. Resolution path: ${path.join(' -> ')}.`, { operation: 'resolve', consumer: attempt.label, dependency: key, path });
+            }
+            return target === undefined ? undefined : this.takeExposed(this.resolveBinding(target, attempt));
+        };
+        const references = new Map(description.references.map(reference => [reference.slot, reference]));
+        const deps = new Proxy(Object.create(null), {
+            get: (_, key) => {
+                const reference = typeof key === 'symbol' ? references.get(key) : undefined;
+                if (reference)
+                    return reference.kind === 'lazy' ? () => read(reference.key)
+                        : read(reference.key, reference.kind === 'optional', reference.kind === 'all');
+                if (typeof key === 'symbol' && !description.tokenKeys.includes(key))
+                    return undefined;
+                return read(key);
+            },
+        });
+        this.observeAttempt(attempt, 'acquisition-started');
+        this.family.enter(attempt);
+        const directSource = !description.contextual && !description.operations.length;
+        try {
+            let value;
+            if (directSource) {
+                const { create } = description;
+                value = create(deps);
+                execution.publishSource(value, description);
+            }
+            else {
+                value = execution.evaluate(description, deps, () => this.getContext());
+            }
+            attempt.exposed = value;
+            attempt.state = attempt.execution.state;
+            if (attempt.state === 'ready') {
+                this.family.deactivate(attempt);
+                this.observeAttempt(attempt, 'acquisition-ready');
+            }
+            attempt.execution = execution.compact();
+            return attempt;
+        }
+        catch (error) {
+            if (directSource)
+                execution.sourceInFlight = false;
+            this.observeAttempt(attempt, 'acquisition-failed', error);
+            this.retire(attempt);
+            throw error;
+        }
+        finally {
+            this.family.leave();
+        }
+    }
+    eventFields(attempt) {
+        const description = this.graph.registration(attempt.bindingId);
+        return {
+            scopeId: this.ownerId, bindingId: attempt.bindingId, acquisitionId: attempt.id,
+            label: attempt.label, lifetime: description.lifetime.kind,
+            registrationMetadata: Object.freeze({ ...description.metadata }), acquisitionMetadata: attempt.execution.inspectFrames(),
+        };
+    }
+    observeAttempt(attempt, kind, error) {
+        if (!this.context.observers)
+            return;
+        const fields = this.eventFields(attempt);
+        const event = kind === 'acquisition-failed' ? { ...fields, kind, error } : { ...fields, kind };
+        this.context.observers.emit(event);
+    }
+    retire(attempt) {
+        if (this.cache.get(attempt.bindingId) === attempt)
+            this.cache.delete(attempt.bindingId);
+        attempt.state = 'failed';
+        this.family.deactivate(attempt);
+        attempt.exposed = undefined;
+        // No consumer acquired this failed exposed value. Keep this attempt's
+        // outgoing edges and pending work, but abandon unsuccessful incoming reads.
+        this.family.retireIncoming(attempt);
+        if (this.retired.has(attempt.id))
+            return;
+        const release = () => {
+            this.family.release(attempt);
+            attempt.dependencies.clear();
+            attempt.execution.release();
+            this.attempts.delete(attempt.id);
+            this.owned.delete(attempt.id);
+            this.retired.delete(attempt.id);
+        };
+        // Incoming IDs may dangle; never substitute a cached retry's identity.
+        if (!attempt.execution.hasOwnership && !attempt.execution.work.length) {
+            release();
+            return;
+        }
+        const cleanup = attempt.execution.dispose().then(release);
+        this.retired.set(attempt.id, cleanup);
+    }
+    async disposeAll(beforeDispose) {
+        let failures = [];
+        try {
+            if (beforeDispose)
+                await beforeDispose;
+            // Sources and projections can still acquire dependencies or retire work.
+            while (true) {
+                const work = [...this.retired.values(), ...[...this.attempts.values()].flatMap(attempt => attempt.execution.work)];
+                if (!work.length)
+                    break;
+                await Promise.all(work);
+            }
+            const ordered = [];
+            const visited = new Set();
+            const stack = [];
+            const enter = (id) => {
+                if (visited.has(id))
+                    return;
+                visited.add(id);
+                const attempt = this.attempts.get(id);
+                if (!attempt)
+                    return;
+                stack.push({ attempt, dependencies: attempt.dependencies.values() });
+            };
+            // Explicit DFS frames preserve dependency/insertion order without using
+            // the JavaScript call stack for a potentially deep acquisition graph.
+            for (const id of this.owned.keys()) {
+                enter(id);
+                while (stack.length) {
+                    const frame = stack[stack.length - 1];
+                    const next = frame.dependencies.next();
+                    if (!next.done) {
+                        enter(next.value);
+                        continue;
+                    }
+                    stack.pop();
+                    if (frame.attempt.execution.hasOwnership)
+                        ordered.push(frame.attempt);
+                }
+            }
+            for (const attempt of ordered.reverse()) {
+                attempt.state = 'disposing';
+                await attempt.execution.dispose();
+                attempt.state = 'disposed';
+            }
+            failures = [...this.failures].sort((a, b) => a.sequence - b.sequence)
+                .map(({ acquisitionId, bindingId, label, error }) => ({ acquisitionId, bindingId, label, error }));
+        }
+        finally {
+            this.state = 'closed';
+            for (const attempt of this.attempts.values()) {
+                this.family.retireIncoming(attempt);
+                this.family.release(attempt);
+                attempt.dependencies.clear();
+                attempt.exposed = undefined;
+                attempt.execution.release();
+            }
+            this.cache.clear();
+            this.attempts.clear();
+            this.retired.clear();
+            this.failures.length = 0;
+            this.owned.clear();
+        }
+        if (failures.length > 0)
+            throw new errors_2.DiBagCleanupError(failures);
+    }
+}
+exports.ScopeAcquisitions = ScopeAcquisitions;

package/dist/alias-types.d.ts

@@ -0,0 +1,22 @@
+import type { Provider, ProviderOutput } from './provider';
+import type { Registrations } from './registration';
+import type { TokenBase, TokenService } from './tokens';
+import type { SelectionKey, TokenDependencyContract, ValidToken, WrongToken } from './token-types';
+import type { Singleton, Unsatisfied } from './types';
+export type AliasSelection = string | TokenBase;
+export type AliasAdmission<T> = Singleton<T> extends true ? unknown : ValidToken<T> extends true ? unknown : Unsatisfied<'alias requires one singleton name or genuine token', {}>;
+export type AliasTarget<R extends Registrations, T> = T extends string ? T extends keyof R ? unknown : Unsatisfied<'alias requires an existing named target', {}> : [WrongToken<T, R>] extends [never] ? unknown : Unsatisfied<'token dependency has an incompatible or opaque contract', {}>;
+/** Resolve the service type exposed by a possible alias target. */
+export type AliasOutput<R extends Registrations, T> = T extends string ? T extends keyof R ? ProviderOutput<R[T]> : never : TokenService<T>;
+export type AliasDestination<R extends Registrations, D, T> = D extends TokenBase ? [AliasOutput<R, T>] extends [TokenService<D>] ? unknown : Unsatisfied<'alias output is not assignable to destination service', {}> : unknown;
+/** A provider contract that forwards a destination to a canonical target acquisition. */
+export type AliasRegistration<R extends Registrations, D, T> = Provider<(this: void, deps: T extends string ? Record<T, AliasOutput<R, T>> : Record<never, never>) => AliasOutput<R, T>, Readonly<object>, readonly unknown[], TokenDependencyContract<T extends TokenBase ? readonly [T] : readonly [], D extends TokenBase ? D : never> & {
+    readonly alias: SelectionKey<T>;
+}, unknown>;
+/** The single registration-map entry introduced by an alias operation. */
+export type AliasEntries<R extends Registrations, D, T> = Record<SelectionKey<D>, AliasRegistration<R, D, T>>;
+/** Reflected generic methods cannot introduce a checked singleton destination. */
+export type AliasEntry<R extends Registrations, D, T> = unknown extends AliasAdmission<D> & AliasAdmission<T> ? {
+    key: SelectionKey<D>;
+    registration: AliasRegistration<R, D, T>;
+} : never;

package/dist/alias-types.js

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

package/dist/aliases.d.ts

@@ -0,0 +1,4 @@
+import type { Registration } from './registration';
+import type { BindingKey } from './runtime';
+/** Authenticate both selections before constructing any retained registration. */
+export declare function aliasEntry(destination: unknown, target: unknown, hasKey: (key: BindingKey) => boolean): readonly [BindingKey, Registration];

package/dist/aliases.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aliasEntry = aliasEntry;
+const errors_1 = require("./errors");
+const provider_1 = require("./provider");
+const provider_operations_1 = require("./provider-operations");
+const tokens_1 = require("./tokens");
+/** Authenticate both selections before constructing any retained registration. */
+function aliasEntry(destination, target, hasKey) {
+    const key = typeof destination === 'string' ? destination : (0, tokens_1.readTokenKey)(destination);
+    const targetKey = typeof target === 'string' ? target : (0, tokens_1.readTokenKey)(target);
+    if (hasKey(key))
+        throw (0, errors_1.libraryError)('DI_BAG_DUPLICATE_REGISTRATION', `duplicate registration: ${String(key)}`, { operation: 'alias', key });
+    if (typeof target === 'string' && !hasKey(targetKey))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_ALIAS', 'alias requires an existing named target', { operation: 'alias', target: targetKey });
+    const handle = (0, provider_1.createProvider)();
+    // This source is unreachable: canonical routing happens before evaluation.
+    // Raw prevents an alias from inventing Promise-classification requirements.
+    (0, provider_operations_1.retainDescription)(handle, Object.freeze({
+        ...(0, provider_operations_1.sourceDescription)(() => { throw (0, errors_1.libraryError)('DI_BAG_INTERNAL_STATE', 'alias source cannot execute', {}); }, undefined, [], 'raw'),
+        alias: targetKey,
+    }));
+    return [key, handle];
+}

package/dist/composition.d.ts

@@ -0,0 +1,41 @@
+import type { Acquired, AcquisitionMode, NativeOutput, StageOptions } from './acquisition-mode';
+import type { Provider } from './provider';
+import type { DependencyReference } from './dependency-references';
+import type { TokenArguments, ReferenceGraph, DependencyTupleAdmission } from './token-types';
+import type { Unsatisfied } from './types';
+type OutputFactory<O> = () => O;
+/** Compile-time admission that checks supplied token values against a callable's parameter tuple. */
+export type CompositionArguments<A extends readonly unknown[], P extends readonly unknown[]> = [A] extends [P] ? unknown : Unsatisfied<'composition arguments must match the declared parameter tuple', {
+    supplied: A;
+    parameters: P;
+}>;
+/** A receiver-free positional callback matching the values supplied by a dependency tuple. */
+export type CompositionFunction<T extends readonly DependencyReference[], O = unknown> = TokenArguments<T> extends [...infer A] ? (this: void, ...args: A) => O : never;
+/**
+ * Adapt a positional function without awaiting its arguments or return value.
+ * @param tokens - A finite tuple of typed tokens and dependency references.
+ * @param callback - The receiver-free function to call in tuple order.
+ * @param modeOptions - Optional acquisition mode for the function result.
+ * @returns A lazy provider retaining the dependency graph and exact return type.
+ * @typeParam F - The exact positional function signature retained by the provider.
+ */
+export declare function fromFunction<const T extends readonly DependencyReference[], F extends CompositionFunction<NoInfer<T>, 'nativePromise' extends M ? Promise<unknown> : unknown>, M extends AcquisitionMode = 'auto'>(tokens: T & DependencyTupleAdmission<T>, callback: F & CompositionArguments<TokenArguments<NoInfer<T>>, Parameters<NoInfer<F>>> & NativeOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...modeOptions: StageOptions<M>): Provider<OutputFactory<ReturnType<F>>, Readonly<{}>, readonly [], ReferenceGraph<T>, Acquired<ReturnType<F>, M>>;
+/**
+ * Adapt a positional function whose parameters exactly match the selected dependency values.
+ * @param tokens - A finite tuple of typed tokens and dependency references.
+ * @param callback - The function invoked once per provider acquisition with no receiver.
+ * @param modeOptions - Optional `auto`, `raw`, or `nativePromise` result classification.
+ * @returns A reusable provider; no dependency or result is implicitly awaited.
+ * @typeParam F - The exact positional function signature retained by the provider.
+ */
+export declare function fromFunction<const T extends readonly DependencyReference[], F extends CompositionFunction<NoInfer<T>>, M extends AcquisitionMode = 'auto'>(tokens: T & DependencyTupleAdmission<T>, callback: F & CompositionArguments<TokenArguments<NoInfer<T>>, Parameters<NoInfer<F>>> & NativeOutput<ReturnType<NoInfer<F>>, NoInfer<M>>, ...modeOptions: StageOptions<M>): Provider<OutputFactory<ReturnType<F>>, Readonly<{}>, readonly [], ReferenceGraph<T>, Acquired<ReturnType<F>, M>>;
+/**
+ * Adapt a concrete constructor while preserving its prototype, private fields, and `new.target`.
+ * @param tokens - A finite tuple whose dependency values match the constructor parameters.
+ * @param constructor - The concrete class or constructable function to instantiate.
+ * @param modeOptions - Optional acquisition mode for the constructed result.
+ * @returns A lazy provider that constructs one instance per acquisition attempt.
+ * @throws When the supplied runtime value is not constructable.
+ */
+export declare function fromClass<const T extends readonly DependencyReference[], C extends new (...args: TokenArguments<NoInfer<T>>) => unknown, M extends AcquisitionMode = 'auto'>(tokens: T & DependencyTupleAdmission<T>, constructor: C & CompositionArguments<TokenArguments<NoInfer<T>>, ConstructorParameters<NoInfer<C>>> & NativeOutput<InstanceType<NoInfer<C>>, NoInfer<M>>, ...modeOptions: StageOptions<M>): Provider<() => InstanceType<C>, Readonly<{}>, readonly [], ReferenceGraph<T>, Acquired<InstanceType<C>, M>>;
+export {};

package/dist/composition.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromFunction = fromFunction;
+exports.fromClass = fromClass;
+const errors_1 = require("./errors");
+const acquisition_mode_1 = require("./acquisition-mode");
+const provider_1 = require("./provider");
+const provider_operations_1 = require("./provider-operations");
+const dependency_references_1 = require("./dependency-references");
+function fromFunction(tokens, callback, ...modeOptions) {
+    const mode = (0, acquisition_mode_1.acquisitionMode)(modeOptions[0]);
+    const references = (0, dependency_references_1.snapshotReferences)(tokens);
+    if (typeof callback !== 'function')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_FUNCTION', 'fromFunction callback must be a function', { operation: 'fromFunction' });
+    const create = (deps) => Reflect.apply(callback, undefined, references.map(reference => Reflect.get(deps, reference.slot)));
+    const handle = (0, provider_1.createProvider)();
+    (0, provider_operations_1.retainDescription)(handle, (0, provider_operations_1.sourceDescription)(create, undefined, references.map(reference => reference.key), mode, false, references));
+    return handle;
+}
+/**
+ * Adapt a concrete constructor while preserving its prototype, private fields, and `new.target`.
+ * @param tokens - A finite tuple whose dependency values match the constructor parameters.
+ * @param constructor - The concrete class or constructable function to instantiate.
+ * @param modeOptions - Optional acquisition mode for the constructed result.
+ * @returns A lazy provider that constructs one instance per acquisition attempt.
+ * @throws When the supplied runtime value is not constructable.
+ */
+function fromClass(tokens, constructor, ...modeOptions) {
+    const mode = (0, acquisition_mode_1.acquisitionMode)(modeOptions[0]);
+    const references = (0, dependency_references_1.snapshotReferences)(tokens);
+    // A Proxy is constructable exactly when its target is. Its inert trap avoids
+    // running the target or reading its prototype, even when the target is a Proxy.
+    if (typeof constructor !== 'function')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_CONSTRUCTOR', 'fromClass requires a concrete constructor', { operation: 'fromClass' });
+    try {
+        Reflect.construct(new Proxy(constructor, { construct: () => ({}) }), []);
+    }
+    catch {
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_CONSTRUCTOR', 'fromClass requires a concrete constructor', { operation: 'fromClass' });
+    }
+    const create = (deps) => Reflect.construct(constructor, references.map(reference => Reflect.get(deps, reference.slot)));
+    const handle = (0, provider_1.createProvider)();
+    (0, provider_operations_1.retainDescription)(handle, (0, provider_operations_1.sourceDescription)(create, undefined, references.map(reference => reference.key), mode, false, references));
+    return handle;
+}

package/dist/contribution-types.d.ts

@@ -0,0 +1,57 @@
+import type { Registration, Registrations } from './registration';
+import type { TokenBase, TokenKey, TokenService } from './tokens';
+import type { ValidToken, TokenTupleAdmission, BindingOutput } from './token-types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, Unsatisfied, Entry, RegistrationsFromEntries } from './types';
+import type { ProviderCollectionTokens } from './provider';
+import type { Module } from './module';
+import type { RegistrationConstraints, PublicProvider, NeedConstraint, CheckedConstraints } from './module-types';
+import type { LexicalContext, ModuleScope, Enclosed, RenamedContext } from './lifetime-types';
+declare const contributionSite: unique symbol;
+/** Each union member retains one independently checked provider and its group. */
+export type Contribution<T extends TokenBase = TokenBase, V extends Registration = Registration, L = undefined> = {
+    readonly kind: 'contribution';
+    readonly token: T;
+    readonly registration: V;
+    readonly context: L;
+};
+/** The erased contribution contract retained by checked builders and modules. */
+export type ContributionConstraint = Contribution<TokenBase, Registration, unknown>;
+type Groups<C> = Extract<C, ContributionConstraint>;
+type Same<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false;
+type WrongMember<T, G> = G extends ContributionConstraint ? TokenKey<T> extends TokenKey<G['token']> ? Same<T, G['token']> extends true ? never : TokenKey<T> : never : never;
+export type WrongGroup<T, C> = T extends unknown ? ValidToken<T> extends true ? WrongMember<T, Groups<C>> : 'opaque collection contract' : never;
+export type CollectionMember<T, C> = [WrongGroup<T, C>] extends [never] ? unknown : Unsatisfied<'collection token has an incompatible or opaque contract', {}>;
+type ContributionGraph<A extends Registrations, V extends Registration> = A & Record<typeof contributionSite, V>;
+type WrongProvider<C, A extends Registrations> = C extends ContributionConstraint ? unknown extends CheckDependencyCompatibility<ContributionGraph<A, C['registration']>> ? never : C : never;
+type ContributionFailures<C, A extends Registrations> = C extends ContributionConstraint ? {
+    readonly consumer: TokenKey<C['token']>;
+    readonly diagnostic: CheckDependencyCompatibility<ContributionGraph<A, C['registration']>>;
+} : never;
+type MissingProvider<C, A extends Registrations> = C extends ContributionConstraint ? unknown extends CheckDependencyCompleteness<ContributionGraph<A, C['registration']>> ? never : C : never;
+type AllNeeds<C, A extends Registrations> = ProviderCollectionTokens<A[keyof A]> | (C extends ContributionConstraint ? ProviderCollectionTokens<C['registration']> : C extends {
+    kind: 'all';
+    token: infer T;
+} ? T : never);
+type GroupErrors<C, A extends Registrations> = WrongGroup<Groups<C>['token'] | AllNeeds<C, A>, C>;
+export type CheckedContributions<C, A extends Registrations> = [Groups<C>] extends [never] ? unknown : [GroupErrors<C, A>] extends [never] ? [WrongProvider<C, A>] extends [never] ? unknown : Unsatisfied<'contribution service is incompatible with its consumer dependency contract', {
+    readonly failures: ContributionFailures<WrongProvider<C, A>, A>;
+}> : Unsatisfied<'collection token has an incompatible or opaque contract', {}>;
+export type CompleteContributions<C, A extends Registrations> = [MissingProvider<C, A>] extends [never] ? unknown : Unsatisfied<'required service registrations are missing', {
+    readonly contributions: MissingProvider<C, A>;
+}>;
+/**
+ * Retain a contribution's provider checks and lexical private-service context when
+ * its builder seals. A contribution retained from an inner installation is already
+ * projected; sealing only encloses its scope in this module's scope.
+ */
+export type ModuleContributionConstraints<C, R extends Registrations, P extends keyof R> = C extends ContributionConstraint ? C['context'] extends LexicalContext ? Contribution<C['token'], C['registration'], Enclosed<C['context'], ModuleScope<R, P>>> : Contribution<C['token'], PublicProvider<C['registration']>, ModuleScope<R, P> & {
+    readonly registration: C['registration'];
+}> | RegistrationConstraints<C['registration'], R, P> : never;
+export type RenamedContribution<C extends ContributionConstraint, Old extends string, New extends string> = C['context'] extends LexicalContext ? Contribution<C['token'], C['registration'], RenamedContext<C['context'], Old, New>> : C;
+/** Project a module's typed-token collections as readonly service arrays. */
+export type ModuleContributions<M> = M extends Module<infer _P, infer _R, infer C, infer _D> ? Readonly<{
+    [T in Groups<C>['token'] as TokenKey<T>]: ReadonlyArray<TokenService<T>>;
+}> : never;
+/** The checked generic `contribute` callable exposed by a builder. */
+export type BuilderContribute<E extends Entry, C extends NeedConstraint> = <T extends TokenBase, V extends Registration>(token: T & TokenTupleAdmission<readonly [T]>, registration: V & Registration & BindingOutput<NoInfer<T>, NoInfer<V>> & CheckedConstraints<C | Contribution<NoInfer<T>, NoInfer<V>>, RegistrationsFromEntries<E>>, ...invalid: [T] extends [never] ? [never] : [V] extends [never] ? [never] : []) => import('./di-bag').Builder<E, C | Contribution<T, V>>;
+export {};

package/dist/contribution-types.js

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

package/dist/contributions.d.ts

@@ -0,0 +1,3 @@
+import type { Registration } from './registration';
+/** Authenticate and snapshot one entry before creating its independent binding. */
+export declare function contributionEntry(token: unknown, registration: Registration): readonly [symbol, Registration];

package/dist/contributions.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contributionEntry = contributionEntry;
+const registration_1 = require("./registration");
+const tokens_1 = require("./tokens");
+/** Authenticate and snapshot one entry before creating its independent binding. */
+function contributionEntry(token, registration) {
+    const key = (0, tokens_1.readTokenKey)(token);
+    (0, registration_1.normalize)(registration);
+    return Object.freeze([key, registration]);
+}