di-bag 0.1.0

package/dist/startup.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startRuntime = startRuntime;
+const errors_1 = require("./errors");
+const runtime_1 = require("./runtime");
+const tokens_1 = require("./tokens");
+const errors_2 = require("./errors");
+function snapshotOptions(options) {
+    if (options === undefined)
+        return {};
+    if (typeof options !== 'object' || options === null || Array.isArray(options))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_STARTUP', 'invalid buildAndStart options', { operation: 'buildAndStart' });
+    const supported = ['signal', 'timeoutMs', 'startupOrder'];
+    if (Reflect.ownKeys(options).some(key => typeof key !== 'string' || !supported.includes(key)) ||
+        supported.some(key => key in options && !Object.hasOwn(options, key)))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_STARTUP', 'invalid buildAndStart options', { operation: 'buildAndStart' });
+    const selected = Object.create(null);
+    for (const key of supported)
+        if (Object.hasOwn(options, key))
+            selected[key] = Reflect.get(options, key);
+    if (Object.hasOwn(selected, 'timeoutMs') && (typeof selected.timeoutMs !== 'number' || !Number.isFinite(selected.timeoutMs) || selected.timeoutMs <= 0)) {
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_STARTUP', 'buildAndStart timeoutMs must be finite and positive', { operation: 'buildAndStart' });
+    }
+    if (Object.hasOwn(selected, 'startupOrder') && selected.startupOrder !== 'parallel' && selected.startupOrder !== 'sequential' &&
+        !(typeof selected.startupOrder === 'number' && Number.isSafeInteger(selected.startupOrder) && selected.startupOrder > 0))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_STARTUP', 'buildAndStart startupOrder must be parallel, sequential, or a positive safe integer', { operation: 'buildAndStart', option: 'startupOrder' });
+    if (Object.hasOwn(selected, 'signal')) {
+        try {
+            Object.getOwnPropertyDescriptor(AbortSignal.prototype, 'aborted').get.call(selected.signal);
+        }
+        catch {
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_STARTUP', 'buildAndStart signal must be an AbortSignal', { operation: 'buildAndStart' });
+        }
+    }
+    return selected;
+}
+/** One startup transaction; never assimilate an exposed service to establish readiness. */
+function startRuntime(graph, context, keys, options) {
+    if (!Array.isArray(keys))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_STARTUP', 'buildAndStart requires selected keys', { operation: 'buildAndStart' });
+    const selected = [];
+    const length = keys.length;
+    for (let index = 0; index < length; index++) {
+        const value = keys[index];
+        const key = typeof value === 'string' ? value : (0, tokens_1.readTokenKey)(value);
+        if (!graph.hasPublic(key))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_STARTUP', `buildAndStart accepts existing names or typed tokens only: ${String(key)}`, { operation: 'buildAndStart' });
+        selected.push(key);
+    }
+    const { signal, timeoutMs, startupOrder = 'parallel' } = snapshotOptions(options);
+    const runtime = new runtime_1.BagRuntime(graph, context);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const began = performance.now();
+        const release = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', aborted);
+        };
+        const cancel = (reason, cause) => {
+            if (settled)
+                return;
+            settled = true;
+            release();
+            reject(new errors_2.DiBagStartupCancelledError(reason, cause, runtime.close(cause)));
+        };
+        const aborted = () => { if (signal?.aborted)
+            cancel('aborted', signal.reason); };
+        const checkCancellation = () => {
+            aborted();
+            if (!settled && timeoutMs !== undefined && performance.now() - began >= timeoutMs) {
+                cancel('timeout', (0, errors_1.diagnostic)(new DOMException('Bag startup timed out', 'TimeoutError'), 'DI_BAG_STARTUP_TIMEOUT', { operation: 'buildAndStart', timeoutMs }));
+            }
+            return settled;
+        };
+        const schedule = () => {
+            if (checkCancellation() || timeoutMs === undefined)
+                return;
+            // Long deadlines must not wrap into an immediate timer on Node/Bun.
+            timer = setTimeout(schedule, Math.min(2 ** 31 - 1, Math.max(1, timeoutMs - (performance.now() - began))));
+        };
+        signal?.addEventListener('abort', aborted, { once: true });
+        if (checkCancellation())
+            return;
+        if (timeoutMs !== undefined)
+            schedule();
+        const runBounded = (limit) => {
+            let next = 0;
+            let failed = false;
+            const worker = async () => {
+                while (next < selected.length) {
+                    if (failed || checkCancellation())
+                        return;
+                    const key = selected[next++];
+                    try {
+                        await runtime.acquire(key);
+                    }
+                    catch (cause) {
+                        // Stop other workers before rollback begins, even if cleanup waits.
+                        failed = true;
+                        throw cause;
+                    }
+                }
+            };
+            return Promise.all(Array.from({ length: Math.min(limit, selected.length) }, worker));
+        };
+        const runParallel = () => {
+            const pending = [];
+            for (const key of selected) {
+                if (checkCancellation())
+                    break;
+                pending.push(runtime.acquire(key));
+            }
+            return Promise.all(pending);
+        };
+        const work = startupOrder === 'parallel' ? runParallel() : runBounded(startupOrder === 'sequential' ? 1 : startupOrder);
+        void work.then(() => {
+            if (checkCancellation())
+                return;
+            settled = true;
+            release();
+            resolve(runtime);
+        }, async (cause) => {
+            if (checkCancellation())
+                return;
+            let cleanupError;
+            try {
+                await runtime.close(cause);
+            }
+            catch (error) {
+                cleanupError = error;
+            }
+            if (checkCancellation())
+                return;
+            settled = true;
+            release();
+            reject(new errors_2.DiBagStartupError(cause, cleanupError instanceof errors_2.DiBagCleanupError ? cleanupError.failures : [], cleanupError));
+        });
+    });
+}

package/dist/token-types.d.ts

@@ -0,0 +1,67 @@
+import type { TokenBase, TokenKey, TokenService } from './tokens';
+import type { DependencyReference, DependencyValue, DependencyToken, DependencyKind, ValidDependency } from './dependency-references';
+import type { Unsatisfied } from './types';
+import type { Registration, Registrations } from './registration';
+import type { BoundToken, Provider, ProviderFactory, ProviderGraphContract, ProviderRegistrationMetadata, ProviderAcquisitionMetadata, ProviderAcquiredValue, ProviderOutput, ProviderRequiredTokens, ProviderOptionalTokens } from './provider';
+/** A provider's retained required, bound, and optional typed-token contracts. */
+export type TokenDependencyContract<T extends readonly TokenBase[] = readonly [], B extends TokenBase = never, O extends readonly TokenBase[] = readonly []> = {
+    readonly kind: 'tokens';
+    readonly required: T;
+    readonly bound: B;
+    readonly optional: O;
+};
+export type OpaqueGraph = {
+    readonly kind: 'opaque';
+};
+export type GraphContract = TokenDependencyContract<readonly TokenBase[], TokenBase, readonly TokenBase[]> | OpaqueGraph;
+type IsUnion<T, Whole = T> = T extends Whole ? [Whole] extends [T] ? false : true : never;
+type SingletonSymbol<K> = [K] extends [never] ? false : [K] extends [symbol] ? symbol extends K ? false : true extends IsUnion<K> ? false : true : false;
+export type TokenKeyAdmission<K> = SingletonSymbol<K> extends true ? unknown : Unsatisfied<'token requires a singleton unique-symbol key', {}>;
+export type ValidToken<T> = [T] extends [never] ? false : true extends IsUnion<T> ? false : T extends TokenBase ? SingletonSymbol<TokenKey<T>> : false;
+type InvalidElements<T extends readonly unknown[]> = {
+    [I in keyof T]-?: ValidToken<T[I]> extends true ? never : I;
+}[number];
+export type TokenTupleAdmission<T extends readonly unknown[]> = true extends IsUnion<T> ? InvalidTuple : number extends T['length'] ? InvalidTuple : T extends Required<T> ? [InvalidElements<T>] extends [never] ? unknown : InvalidTuple : InvalidTuple;
+type InvalidTuple = Unsatisfied<'tokens require a finite tuple of individually known token handles', {}>;
+type InvalidDependencies<T extends readonly unknown[]> = {
+    [I in keyof T]-?: true extends IsUnion<T[I]> ? I : ValidDependency<T[I]> extends true ? never : I;
+}[number];
+export type DependencyTupleAdmission<T extends readonly unknown[]> = true extends IsUnion<T> ? InvalidTuple : number extends T['length'] ? InvalidTuple : T extends Required<T> ? [InvalidDependencies<T>] extends [never] ? unknown : InvalidTuple : InvalidTuple;
+export type TokenArguments<T extends readonly DependencyReference[]> = {
+    -readonly [I in keyof T]: DependencyValue<T[I]>;
+};
+type ReferenceTokens<T extends readonly DependencyReference[], Kind extends 'required' | 'optional' | 'all', SelectedRegistrations extends readonly TokenBase[] = readonly []> = T extends readonly [infer H extends DependencyReference, ...infer Rest extends readonly DependencyReference[]] ? (DependencyKind<H> extends 'lazy' ? 'required' : DependencyKind<H>) extends Kind ? ReferenceTokens<Rest, Kind, readonly [...SelectedRegistrations, DependencyToken<H>]> : ReferenceTokens<Rest, Kind, SelectedRegistrations> : SelectedRegistrations;
+export type ReferenceGraph<T extends readonly DependencyReference[]> = T extends readonly TokenBase[] ? TokenDependencyContract<T> : TokenDependencyContract<ReferenceTokens<T, 'required'>, never, ReferenceTokens<T, 'optional'>> & (ReferenceTokens<T, 'all'> extends readonly [] ? unknown : {
+    readonly all: ReferenceTokens<T, 'all'>;
+});
+export type ReboundGraph<G extends GraphContract, T extends TokenBase> = G extends infer U & {} ? U extends TokenDependencyContract<readonly TokenBase[], TokenBase, readonly TokenBase[]> ? {
+    [K in keyof U]: K extends 'bound' ? T : U[K];
+} : U extends GraphContract ? U : never : never;
+/** A registration rebound to an invariant typed-token service contract. */
+export type TokenBinding<T extends TokenBase, R extends Registration> = Provider<ProviderFactory<R>, ProviderRegistrationMetadata<R> & object, ProviderAcquisitionMetadata<R>, ReboundGraph<ProviderGraphContract<R>, T>, ProviderAcquiredValue<R>>;
+export type BindingOutput<T extends TokenBase, R extends Registration> = [ProviderOutput<R>] extends [TokenService<T>] ? unknown : Unsatisfied<'token binding output is not assignable to its service', {
+    token: TokenKey<T>;
+    expected: TokenService<T>;
+    provided: ProviderOutput<R>;
+}>;
+/** Convert a string selection to itself or a typed token to its symbol key. */
+export type SelectionKey<T> = T extends string ? T : TokenKey<T>;
+type SameToken<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false;
+export type WrongToken<T, R extends Registrations> = T extends unknown ? ValidToken<T> extends true ? TokenKey<T> extends keyof R ? SameToken<T, BoundToken<R[TokenKey<T>]>> extends true ? never : TokenKey<T> : never : 'opaque token contract' : never;
+export type MissingToken<T, R extends Registrations> = T extends unknown ? ValidToken<T> extends true ? Exclude<TokenKey<T>, keyof R> : 'opaque token contract' : never;
+/** Admit a genuine token only when it exactly matches an existing binding contract. */
+export type TokenMember<R extends Registrations, T> = ValidToken<T> extends true ? [WrongToken<T, R> | MissingToken<T, R>] extends [never] ? unknown : Unsatisfied<'token must match an existing binding contract', {}> : Unsatisfied<'token must be an individually known genuine handle', {}>;
+export type InvalidGraphs<R extends Registrations> = {
+    [K in keyof R]: [ProviderGraphContract<R[K]>] extends [TokenDependencyContract<readonly TokenBase[], TokenBase, readonly TokenBase[]>] ? WrongToken<ProviderRequiredTokens<R[K]> | ProviderOptionalTokens<R[K]>, R> | InvalidBound<BoundToken<R[K]>> : K;
+}[keyof R];
+type InvalidBound<B> = B extends unknown ? ValidToken<B> extends true ? never : 'opaque binding contract' : never;
+export type MissingTokens<R extends Registrations> = {
+    [K in keyof R]: MissingToken<ProviderRequiredTokens<R[K]>, R>;
+}[keyof R];
+/** Rebind symbol-keyed override registrations to the original typed-token contracts. */
+export type ReboundProviders<R extends Registrations, O extends Registrations> = {
+    [K in keyof O]: K extends keyof R ? K extends symbol ? TokenBinding<BoundToken<R[K]>, O[K]> : O[K] : O[K];
+};
+/** Preserve named overrides and rebind any symbol-keyed override providers. */
+export type ReboundSelection<R extends Registrations, O extends Registrations> = [Extract<keyof O, symbol>] extends [never] ? O : ReboundProviders<R, O>;
+export {};

package/dist/token-types.js

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

package/dist/tokens.d.ts

@@ -0,0 +1,47 @@
+import type { TokenKeyAdmission } from './token-types';
+declare const tokenInvariant: unique symbol;
+/**
+ * The common type-only base for genuine typed-token handles.
+ * Create tokens through `DiBag.token`; fabricated structural values are not authenticated.
+ */
+declare class TokenBase {
+    private readonly nominal;
+}
+/**
+ * An immutable typed-token handle pairing a canonical symbol with an invariant service contract.
+ * Create one with `DiBag.token(key).of<Service>()`.
+ */
+declare class Token<K extends symbol, S> extends TokenBase {
+    readonly key: K;
+    /** @internal */
+    readonly [tokenInvariant]: (value: [K, S]) => [K, S];
+    constructor(key: K);
+}
+/** Extract the canonical unique-symbol key from a typed token. */
+export type TokenKey<T> = T extends infer U & {} ? U extends Token<infer K, infer _S> ? K : never : never;
+/** Extract the invariant service contract declared by a typed token. */
+export type TokenService<T> = T extends infer U & {} ? U extends Token<infer _K, infer S> ? S : never : never;
+/**
+ * Create a typed-token factory from the caller's canonical unique symbol.
+ * Reusing the same key and service type produces compatible handles; copied or fabricated
+ * objects are rejected at runtime.
+ * @param key - An individually known unique symbol used as the runtime binding identity.
+ * @returns An object whose `of<Service>()` method creates an immutable typed token.
+ * @example
+ * ```ts
+ * const clockKey = Symbol('clock');
+ * const clock = DiBag.token(clockKey).of<{ now(): number }>();
+ * ```
+ */
+export declare function token<const K extends symbol>(key: K & TokenKeyAdmission<K>, ...invalid: [K] extends [never] ? [TokenKeyAdmission<K>] : []): {
+    /**
+     * Declare the invariant service contract carried by this token handle.
+     * @typeParam S - The service type accepted by bindings and returned by resolution.
+     * @returns A genuine immutable token paired with the canonical symbol key.
+     */
+    readonly of: <S>() => Token<K, S>;
+};
+/** A copied, proxied or fabricated shape cannot authenticate a token. */
+export declare function readTokenKey(value: unknown): symbol;
+export declare function snapshotTokens(value: unknown): readonly TokenBase[];
+export type { Token, TokenBase };

package/dist/tokens.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.token = token;
+exports.readTokenKey = readTokenKey;
+exports.snapshotTokens = snapshotTokens;
+const errors_1 = require("./errors");
+/**
+ * The common type-only base for genuine typed-token handles.
+ * Create tokens through `DiBag.token`; fabricated structural values are not authenticated.
+ */
+class TokenBase {
+}
+/**
+ * An immutable typed-token handle pairing a canonical symbol with an invariant service contract.
+ * Create one with `DiBag.token(key).of<Service>()`.
+ */
+class Token extends TokenBase {
+    key;
+    constructor(key) {
+        super();
+        this.key = key;
+    }
+}
+const keys = new WeakMap();
+/**
+ * Create a typed-token factory from the caller's canonical unique symbol.
+ * Reusing the same key and service type produces compatible handles; copied or fabricated
+ * objects are rejected at runtime.
+ * @param key - An individually known unique symbol used as the runtime binding identity.
+ * @returns An object whose `of<Service>()` method creates an immutable typed token.
+ * @example
+ * ```ts
+ * const clockKey = Symbol('clock');
+ * const clock = DiBag.token(clockKey).of<{ now(): number }>();
+ * ```
+ */
+function token(key, 
+// An uninhabited key is assignable to every intersection; arity rejects its
+// explicit generic erasure without weakening ordinary key inference.
+...invalid) {
+    if (typeof key !== 'symbol')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_TOKEN', 'token key must be a symbol', { operation: 'token' });
+    return Object.freeze({ of: () => {
+            const handle = new Token(key);
+            keys.set(handle, key);
+            Object.freeze(handle);
+            return handle;
+        } });
+}
+/** A copied, proxied or fabricated shape cannot authenticate a token. */
+function readTokenKey(value) {
+    if (typeof value !== 'object' || value === null)
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_TOKEN', 'invalid token', { expected: 'genuine typed token' });
+    const key = keys.get(value);
+    if (key === undefined)
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_TOKEN', 'invalid token', { expected: 'genuine typed token' });
+    return key;
+}
+function snapshotTokens(value) {
+    if (!Array.isArray(value))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_TOKEN', 'tokens must be a tuple', { expected: 'finite token tuple' });
+    const selected = [];
+    const length = value.length;
+    for (let index = 0; index < length; index++)
+        selected[index] = value[index];
+    for (const handle of selected)
+        readTokenKey(handle);
+    return Object.freeze(selected);
+}

package/dist/types.d.ts

@@ -0,0 +1,174 @@
+import type { FactoryWithDisposal, Registration, Registrations } from './registration';
+import type { ProviderContext, ProviderNamedDependencies, ProviderOutput, ProviderGraphContract, ProviderRequiredTokens, ProviderOptionalTokens } from './provider';
+import type { InvalidGraphs, MissingTokens, SelectionKey, TokenMember, ValidToken, TokenDependencyContract, WrongToken } from './token-types';
+export type Needs<R extends Registration> = ProviderNamedDependencies<R>;
+/** Map registrations to the exact service values they expose. */
+export type ServicesOf<R extends Registrations> = {
+    [K in keyof R]: ProviderOutput<R[K]>;
+};
+export type Entry = {
+    key: string | symbol;
+    registration: Registration;
+};
+type RegistrationEntry<K extends string | symbol, V extends Registration> = {
+    key: K;
+    registration: V;
+};
+/** Convert a registration map to the union of entries retained by a builder. */
+export type RegistrationEntries<R extends Registrations> = {
+    [K in keyof R & (string | symbol)]: RegistrationEntry<K, R[K]>;
+}[keyof R & (string | symbol)];
+/** Reconstruct a registration map from a builder's retained entry union. */
+export type RegistrationsFromEntries<E extends Entry> = {
+    [P in E as P['key']]: P['registration'];
+};
+/** Replace overlapping registrations in `F` with registrations from `N`. */
+export type OverrideRegistrations<F extends Registrations, N extends Registrations> = Omit<F, keyof N> & N;
+declare const diBagTypeError: unique symbol;
+export type Unsatisfied<Message extends string, Details> = {
+    readonly [diBagTypeError]: Message;
+} & Details;
+type IsUnion<T, Whole = T> = T extends Whole ? [Whole] extends [T] ? false : true : never;
+type NonFiniteKeys<T> = {
+    [K in keyof T]-?: Record<never, never> extends Record<K, never> ? K : never;
+}[keyof T];
+type InvalidNeeds<R extends Registrations> = {
+    [K in keyof R]: true extends IsUnion<Needs<R[K]>> ? K : Needs<R[K]> extends (...args: never[]) => unknown ? K : Needs<R[K]> extends abstract new (...args: never[]) => unknown ? K : [Needs<R[K]>] extends [object] ? [NonFiniteKeys<Needs<R[K]>>] extends [never] ? [Exclude<keyof Needs<R[K]>, string>] extends [never] ? never : K : K : K;
+}[keyof R];
+type WrongShapes<R extends Registrations> = {
+    [K in keyof R]: Pick<ServicesOf<R>, keyof Needs<R[K]> & keyof R> extends Pick<Needs<R[K]>, keyof Needs<R[K]> & keyof R> ? never : K;
+}[keyof R];
+type WrongRelationships<R extends Registrations, Consumers extends keyof R> = {
+    [Consumer in Consumers]: {
+        [DependencyReference in keyof Needs<R[Consumer]> & keyof R]: ServicesOf<R>[DependencyReference] extends Required<Needs<R[Consumer]>>[DependencyReference] ? never : {
+            consumer: Consumer;
+            dependency: DependencyReference;
+            expected: Required<Needs<R[Consumer]>>[DependencyReference];
+            provided: ServicesOf<R>[DependencyReference];
+        };
+    }[keyof Needs<R[Consumer]> & keyof R];
+}[Consumers];
+type MissingRelationships<R extends Registrations> = {
+    [Consumer in keyof R]: {
+        [DependencyReference in Exclude<keyof Needs<R[Consumer]>, keyof R>]: {
+            consumer: Consumer;
+            dependency: DependencyReference;
+            expected: Needs<R[Consumer]>[DependencyReference];
+            provided: undefined;
+        };
+    }[Exclude<keyof Needs<R[Consumer]>, keyof R>];
+}[keyof R];
+/** Compile-time admission for finite dependency objects and compatible known services. */
+export type CheckDependencyCompatibility<R extends Registrations> = [
+    InvalidNeeds<R> | NonFiniteKeys<R> | Extract<keyof R, number>
+] extends [never] ? [InvalidGraphs<R>] extends [never] ? [WrongShapes<R>] extends [never] ? unknown : Unsatisfied<'provided service does not satisfy its consumer dependency', {
+    tokens: WrongShapes<R>;
+    relationships: WrongRelationships<R, WrongShapes<R>>;
+}> : Unsatisfied<'token dependency has an incompatible or opaque contract', {
+    tokens: InvalidGraphs<R>;
+}> : [NonFiniteKeys<R> | Extract<keyof R, number>] extends [never] ? Unsatisfied<'factory dependencies must be finite string-keyed objects', {
+    tokens: InvalidNeeds<R>;
+}> : Unsatisfied<'registration keys must be finite string or unique-symbol keys', {
+    keys: NonFiniteKeys<R> | Extract<keyof R, number>;
+}>;
+type NewWrong<E extends Entry, N extends Registrations> = {
+    [K in keyof N]: [Exclude<keyof Needs<N[K]>, keyof N> & E['key']] extends [never] ? never : Pick<ServicesOf<RegistrationsFromEntries<E>>, Exclude<keyof Needs<N[K]>, keyof N> & E['key']> extends Pick<Needs<N[K]>, Exclude<keyof Needs<N[K]>, keyof N> & E['key']> ? never : K;
+}[keyof N];
+type OldWrong<E extends Entry, N extends Registrations> = E extends Entry ? E['key'] extends keyof N ? never : Pick<ServicesOf<N>, keyof Needs<E['registration']> & keyof N> extends Pick<Needs<E['registration']>, keyof Needs<E['registration']> & keyof N> ? never : E['key'] : never;
+type NewTokenWrong<E extends Entry, N extends Registrations> = {
+    [K in keyof N]: WrongToken<ProviderRequiredTokens<N[K]> | ProviderOptionalTokens<N[K]>, RegistrationsFromEntries<[E['key'] & keyof N] extends [never] ? E : Exclude<E, {
+        key: keyof N;
+    }>>>;
+}[keyof N];
+type OpaqueTokenNeeds<E extends Entry> = E extends Entry ? E['key'] extends never ? never : WrongToken<ProviderRequiredTokens<E['registration']> | ProviderOptionalTokens<E['registration']>, {}> : never;
+type RetainedTokenNeeds<E extends Entry> = E extends Entry ? E['key'] extends never ? never : ProviderRequiredTokens<E['registration']> | ProviderOptionalTokens<E['registration']> : never;
+type OldTokenWrong<E extends Entry, N extends Registrations> = [Extract<keyof N, symbol>] extends [never] ? OpaqueTokenNeeds<[E['key'] & keyof N] extends [never] ? E : Exclude<E, {
+    key: keyof N;
+}>> : string extends E['key'] ? E extends Entry ? E['key'] extends keyof N ? never : WrongToken<ProviderRequiredTokens<E['registration']> | ProviderOptionalTokens<E['registration']>, N> : never : [E['key']] extends [never] ? never : WrongToken<RetainedTokenNeeds<[E['key'] & keyof N] extends [never] ? E : Exclude<E, {
+    key: keyof N;
+}>>, N>;
+export type IncrementalChecked<E extends Entry, N extends Registrations> = unknown extends CheckDependencyCompatibility<N> ? [NewTokenWrong<E, N> | OldTokenWrong<E, N>] extends [never] ? [NewWrong<E, N> | OldWrong<E, N>] extends [never] ? unknown : Unsatisfied<'provided service does not satisfy its consumer dependency', {
+    tokens: NewWrong<E, N> | OldWrong<E, N>;
+    relationships: WrongRelationships<OverrideRegistrations<RegistrationsFromEntries<E>, N>, (NewWrong<E, N> | OldWrong<E, N>) & keyof OverrideRegistrations<RegistrationsFromEntries<E>, N>>;
+}> : Unsatisfied<'token dependency has an incompatible or opaque contract', {
+    tokens: NewTokenWrong<E, N> | OldTokenWrong<E, N>;
+}> : CheckDependencyCompatibility<N>;
+export type NamedAdmission<R> = [NonFiniteKeys<R> | Exclude<keyof R, string>] extends [never] ? unknown : Unsatisfied<'register requires finite string-keyed registration objects', {
+    keys: NonFiniteKeys<R> | Exclude<keyof R, string>;
+}>;
+type RequiredOf<R extends Registrations> = {
+    [K in keyof R]: keyof Needs<R[K]>;
+}[keyof R];
+type CompletionMap<R extends Registrations> = {
+    [K in keyof R]: R[K];
+};
+/** Compile-time admission requiring every named and typed-token dependency to be bound. */
+export type CheckDependencyCompleteness<R extends Registrations> = [
+    Exclude<RequiredOf<R>, keyof R> | MissingTokens<CompletionMap<R>>
+] extends [never] ? [InvalidGraphs<CompletionMap<R>>] extends [never] ? unknown : Unsatisfied<'token dependency has an incompatible or opaque contract', {
+    tokens: InvalidGraphs<CompletionMap<R>>;
+}> : Unsatisfied<'required service registrations are missing', {
+    missing: Exclude<RequiredOf<R>, keyof R> | MissingTokens<CompletionMap<R>>;
+    relationships: MissingRelationships<R>;
+}>;
+type BadOverrides<F extends Registrations, O extends Registrations> = {
+    [K in keyof O & keyof F]: ServicesOf<O>[K] extends ServicesOf<F>[K] ? never : K;
+}[keyof O & keyof F];
+/** Admit overrides only for existing keys whose service values remain assignable. */
+export type Overrides<F extends Registrations, O extends Registrations> = [
+    Exclude<keyof O, keyof F>
+] extends [never] ? [BadOverrides<F, O>] extends [never] ? unknown : Unsatisfied<'override value is not assignable to the original token', {
+    tokens: BadOverrides<F, O>;
+}> : Unsatisfied<'fork accepts existing names or typed tokens only', {
+    extra: Exclude<keyof O, keyof F>;
+}>;
+export type Introduces<F extends Registrations, N extends Registrations> = [
+    keyof F & keyof N
+] extends [never] ? unknown : Unsatisfied<'register introduces new names or typed tokens only', {
+    duplicates: keyof F & keyof N;
+}>;
+export type EntryKeys<E extends Entry> = string extends E['key'] ? keyof RegistrationsFromEntries<E> : E['key'];
+export type IntroducesKeys<Known extends PropertyKey, New extends PropertyKey> = [Known & New] extends [never] ? unknown : Unsatisfied<'register introduces new names or typed tokens only', {
+    duplicates: Known & New;
+}>;
+export type Singleton<K> = [K] extends [never] ? false : [K] extends [string] ? true extends IsUnion<K> ? false : [NonFiniteKeys<Record<K & string, never>>] extends [never] ? true : false : false;
+export type ReplacementKey<R extends Registrations, K extends string> = Singleton<K> extends true ? K extends keyof R ? unknown : Unsatisfied<'replace requires one existing singleton string-literal key', {
+    key: K;
+}> : Unsatisfied<'replace requires one existing singleton string-literal key', {
+    key: K;
+}>;
+export type ReplacementKeyOf<Keys extends PropertyKey, K extends string> = Singleton<K> extends true ? K extends Keys ? unknown : Unsatisfied<'replace requires one existing singleton string-literal key', {
+    key: K;
+}> : Unsatisfied<'replace requires one existing singleton string-literal key', {
+    key: K;
+}>;
+type ReplacementRequirement<N, K extends PropertyKey> = K extends keyof N ? (value: N[K]) => void : never;
+type LocalReplacementRequirement<R extends Registrations, K extends PropertyKey, P extends keyof R> = P extends unknown ? ReplacementRequirement<Required<Needs<R[P]>>, K> : never;
+type LocalReplacementRequirements<R extends Registrations, K extends PropertyKey> = LocalReplacementRequirement<R, K, Exclude<keyof R, K>>;
+type RetainedReplacementRequirements<C, K extends PropertyKey> = C extends {
+    readonly needs: infer N;
+} ? ReplacementRequirement<N, K> : never;
+type ReplacementRequirements<R extends Registrations, K extends PropertyKey, C> = LocalReplacementRequirements<R, K> | RetainedReplacementRequirements<C, K>;
+export type ReplacementOutput<R extends Registrations, K extends PropertyKey, C = never> = [
+    ReplacementRequirements<R, K, C>
+] extends [never] ? unknown : ReplacementRequirements<R, K, C> extends (value: infer O) => void ? O : unknown;
+type InvalidElements<K extends readonly unknown[]> = {
+    [I in keyof K]-?: Singleton<K[I]> extends true ? never : ValidToken<K[I]> extends true ? never : I;
+}[number];
+type InvalidMembers<R extends Registrations, T> = T extends string ? never : unknown extends TokenMember<R, T> ? never : T;
+/** Validate a finite tuple of existing singleton names or genuine typed tokens. */
+export type Selection<R extends Registrations, K extends readonly unknown[], Operation extends string = 'fork'> = true extends IsUnion<K> ? InvalidSelection<Operation> : number extends K['length'] ? InvalidSelection<Operation> : K extends Required<K> ? [InvalidElements<K>] extends [never] ? [Exclude<SelectionKey<K[number]>, keyof R> | InvalidMembers<R, K[number]>] extends [never] ? unknown : Unsatisfied<`${Operation} accepts existing names or typed tokens only`, {
+    extra: Exclude<SelectionKey<K[number]>, keyof R> | InvalidMembers<R, K[number]>;
+}> : InvalidSelection<Operation> : InvalidSelection<Operation>;
+type InvalidSelection<Operation extends string> = Unsatisfied<`${Operation} requires a finite tuple of singleton string-literal names or typed tokens`, {
+    selection: 'use a const tuple with individually known names or typed tokens';
+}>;
+/** Select registration-valued own fields corresponding to a checked key tuple. */
+export type SelectedRegistrations<K extends readonly unknown[], O> = {
+    [P in Extract<SelectionKey<K[number]>, keyof O>]: Extract<O[P], Registration>;
+};
+/** Contextual override shape used to infer a selected fork or child-scope graph. */
+export type OverrideFactoryContext<R extends Registrations, K extends readonly unknown[], O> = {
+    [P in Extract<SelectionKey<K[number]>, keyof R>]: ((this: void, deps: ServicesOf<OverrideRegistrations<R, SelectedRegistrations<K, O>>>) => ServicesOf<R>[P]) | FactoryWithDisposal<(this: void, deps: ServicesOf<OverrideRegistrations<R, SelectedRegistrations<K, O>>>) => ServicesOf<R>[P]> | ProviderContext<(this: void, deps: ServicesOf<OverrideRegistrations<R, SelectedRegistrations<K, O>>>) => ServicesOf<R>[P], P extends keyof O ? ProviderGraphContract<Extract<O[P], Registration>> : TokenDependencyContract>;
+};
+export {};

package/dist/types.js

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "di-bag",
+  "version": "0.1.0",
+  "description": "Type-checked dependency composition with lazy factories, forks, and optional disposal.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "bun test tests",
+    "typecheck": "tsc6 -p tsconfig.json",
+    "typecheck:native": "tsc -p tsconfig.json",
+    "build:native": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "check:native": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/check-native-contracts.ts",
+    "example:wbs": "bun run examples/wbs-scope.ts",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc6 -p ./tsconfig.build.json",
+    "benchmark:types": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/benchmark-types.ts",
+    "benchmark:compiler-controls": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/benchmark-compiler-controls.ts",
+    "benchmark:runtime": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/performance-evidence.ts --current",
+    "evidence:platform": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/platform-evidence.ts",
+    "platform:pin": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/pin-platform-tools.ts",
+    "check:platform": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/platform-evidence.ts --required",
+    "docs:generate": "node tools/docs/generate.mjs",
+    "docs:check": "node --test --test-isolation=none tools/docs/test/*.test.mjs && node tools/docs/generate.mjs --check && node tools/docs/site.mjs check",
+    "docs:build": "node tools/docs/site.mjs build",
+    "docs:dev": "node tools/docs/site.mjs dev",
+    "docs:preview": "node tools/docs/site.mjs preview",
+    "prepack": "npm run build",
+    "check": "npm run typecheck && npm test && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dany-fedorov/di-bag.git"
+  },
+  "homepage": "https://dany-fedorov.github.io/di-bag",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "di",
+    "bag"
+  ],
+  "author": "Dany Fedorov",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "typescript": "npm:@typescript/typescript6@6.0.2"
+  },
+  "overrides": {
+    "@typescript/old": "npm:typescript@6.0.3"
+  }
+}