di-bag 0.1.0

package/dist/errors.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiBagStartupCancelledError = exports.DiBagStartupError = exports.DiBagCleanupError = exports.DiBagPluginValidationError = void 0;
+exports.diagnostic = diagnostic;
+exports.libraryError = libraryError;
+exports.libraryTypeError = libraryTypeError;
+/** Attach only at library-owned error creation sites; never modify application errors. */
+function diagnostic(error, code, details = {}) {
+    Object.defineProperties(error, {
+        code: { value: code, enumerable: true },
+        details: { value: Object.freeze({ ...details }), enumerable: true },
+    });
+    return error;
+}
+function libraryError(code, message, details = {}) {
+    return diagnostic(new Error(message), code, details);
+}
+function libraryTypeError(code, message, details = {}) {
+    return diagnostic(new TypeError(message), code, details);
+}
+/** A plugin descriptor or produced value crossed the checked plugin boundary. */
+class DiBagPluginValidationError extends Error {
+    phase;
+    reason;
+    /**
+     * @param phase - Whether descriptor authentication or output validation failed.
+     * @param reason - A stable description of the rejected boundary condition.
+     */
+    constructor(phase, reason) {
+        super(`Invalid plugin ${phase}: ${reason}`);
+        this.phase = phase;
+        this.reason = reason;
+        this.name = 'DiBagPluginValidationError';
+        diagnostic(this, 'DI_BAG_PLUGIN_VALIDATION', { operation: 'fromPlugin', phase, reason });
+    }
+}
+exports.DiBagPluginValidationError = DiBagPluginValidationError;
+/** Original cleanup causes and detached acquisition diagnostics, in attempt order. */
+class DiBagCleanupError extends AggregateError {
+    /** Frozen cleanup failures in finalizer invocation order. */
+    failures;
+    /** @param failures - Structured failures whose original errors also populate `AggregateError.errors`. */
+    constructor(failures) {
+        const snapshot = Object.freeze(failures.map(item => Object.freeze({ ...item })));
+        super(snapshot.map(item => item.error), `Failed to run ${snapshot.length} disposal callback(s)`);
+        this.name = 'DiBagCleanupError';
+        diagnostic(this, 'DI_BAG_CLEANUP_FAILED', { operation: 'close', failedCallbacks: snapshot.length, failures: snapshot });
+        this.failures = snapshot;
+    }
+}
+exports.DiBagCleanupError = DiBagCleanupError;
+/** Acquisition failure after the new bag has finished releasing its resources. */
+class DiBagStartupError extends Error {
+    cleanupError;
+    /** Frozen rollback disposal failures in invocation order. */
+    cleanupFailures;
+    /**
+     * @param cause - The original selected-service acquisition failure.
+     * @param cleanupFailures - Structured failures collected while rolling back the new bag.
+     * @param cleanupError - The complete shutdown error, when rollback itself rejected.
+     */
+    constructor(cause, cleanupFailures, cleanupError) {
+        super('Failed to start bag', { cause });
+        this.cleanupError = cleanupError;
+        this.name = 'DiBagStartupError';
+        this.cleanupFailures = Object.freeze(cleanupFailures.map(item => Object.freeze({ ...item })));
+        diagnostic(this, 'DI_BAG_STARTUP_FAILED', { operation: 'buildAndStart', cleanupFailures: this.cleanupFailures });
+    }
+}
+exports.DiBagStartupError = DiBagStartupError;
+/** Prompt cancellation; cleanup remains awaitable for uncooperative factories. */
+class DiBagStartupCancelledError extends Error {
+    reason;
+    cleanupPromise;
+    /**
+     * @param reason - Whether an external abort or startup timeout cancelled the wait.
+     * @param cause - The abort reason or generated timeout error.
+     * @param cleanupPromise - Eventual shutdown of the partially started bag; cancellation does not await it.
+     */
+    constructor(reason, cause, cleanupPromise) {
+        super(`Bag startup ${reason}`, { cause });
+        this.reason = reason;
+        this.cleanupPromise = cleanupPromise;
+        this.name = 'DiBagStartupCancelledError';
+        diagnostic(this, 'DI_BAG_STARTUP_CANCELLED', { operation: 'buildAndStart', reason });
+        void cleanupPromise.catch(() => { });
+    }
+}
+exports.DiBagStartupCancelledError = DiBagStartupCancelledError;

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export { DiBag } from './di-bag';
+export { DiBagCleanupError, DiBagPluginValidationError, DiBagStartupError, DiBagStartupCancelledError } from './errors';
+export type { CleanupFailure, DiBagErrorCode, DiBagDiagnostic } from './errors';
+export type { Bag, Builder, DiBagApi, ConfigurationOptions } from './di-bag';
+export type { Module } from './module';
+export type { ModuleExportedServices, ModuleRequiredServices, ModuleConstraints, ModuleSealedConstraints, SealedConstraints, PublicProviders, ModulePublicProviders, Renamed } from './module-types';
+export type { FactoryWithDisposal, Registration } from './registration';
+export type { Provider, ProviderFactory, ProviderGraphContract, ProviderOutput, ProviderAcquiredValue, ProviderNamedDependencies, ProviderRegistrationMetadata, ProviderAcquisitionMetadata, ProviderRequiredTokens, ProviderOptionalTokens, ProviderCollectionTokens } from './provider';
+export type { AcquisitionMode, RuntimeOptions } from './acquisition-mode';
+export type { Lifetime } from './lifetime';
+export type { AcquisitionContext, ContextualFactory } from './acquisition-context';
+export type { StartupOptions } from './startup';
+export type { ScopeOptions, DisjointScopeSelection, UnsharedAliases, ScopedAliases, SharedAliasProviders } from './scope-types';
+export type { Token, TokenBase, TokenKey, TokenService } from './tokens';
+export type { TokenBinding, TokenMember, TokenDependencyContract, ReboundProviders, ReboundSelection, SelectionKey } from './token-types';
+export type { CheckedLifetimes, CheckedScopeLifetimes, LexicalContext, ModuleScope, Enclosed, RenamedContext, RenamedLifetimeObligation, EnclosedLifetimeObligation, RenamedLifetimeProviders } from './lifetime-types';
+export type { CheckDependencyCompatibility, CheckDependencyCompleteness, RegistrationEntries, OverrideFactoryContext, RegistrationsFromEntries, OverrideRegistrations, Overrides, ServicesOf, SelectedRegistrations, Selection } from './types';
+export type { Presence, AcquisitionMetadataPresence, AcquisitionSnapshot, RegistrationSnapshot } from './inspection';
+export type { CompositionArguments, CompositionFunction } from './composition';
+export type { OptionalDependency, LazyDependency, CollectionDependency, DependencyReference } from './dependency-references';
+export type { PluginProviderFactory, PluginAcquisitionMode, PluginOptions, PluginOutputValidator, PluginProvider } from './plugins';
+export type { AliasRegistration, AliasEntries, AliasOutput } from './alias-types';
+export type { Contribution, ContributionConstraint, ModuleContributions, ModuleContributionConstraints } from './contribution-types';
+export type { BuilderContribute } from './contribution-types';
+export type { LifecycleEvent, ObserverFailure, ObserverCallback, ObserverErrorCallback, ObserverOptions, ScopeEventFields, AcquisitionEventFields } from './observers';

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiBagStartupCancelledError = exports.DiBagStartupError = exports.DiBagPluginValidationError = exports.DiBagCleanupError = exports.DiBag = void 0;
+var di_bag_1 = require("./di-bag");
+Object.defineProperty(exports, "DiBag", { enumerable: true, get: function () { return di_bag_1.DiBag; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "DiBagCleanupError", { enumerable: true, get: function () { return errors_1.DiBagCleanupError; } });
+Object.defineProperty(exports, "DiBagPluginValidationError", { enumerable: true, get: function () { return errors_1.DiBagPluginValidationError; } });
+Object.defineProperty(exports, "DiBagStartupError", { enumerable: true, get: function () { return errors_1.DiBagStartupError; } });
+Object.defineProperty(exports, "DiBagStartupCancelledError", { enumerable: true, get: function () { return errors_1.DiBagStartupCancelledError; } });

package/dist/inspection.d.ts

@@ -0,0 +1,36 @@
+/** Structural optional presence; payloads are application-owned and not frozen. */
+export type Presence<T> = {
+    readonly present: false;
+} | {
+    readonly present: true;
+    readonly value: T;
+};
+/** A readonly tuple indicating whether each acquisition-stage frame is available. */
+export type AcquisitionMetadataPresence<A extends readonly unknown[]> = {
+    readonly [I in keyof A]: Presence<A[I]>;
+};
+/** A frozen point-in-time view of one acquisition attempt. */
+export interface AcquisitionSnapshot<A extends readonly unknown[] = readonly []> {
+    /** Stable identity for this attempt; retries receive a new symbol. */
+    readonly acquisitionId: symbol;
+    /** State at the instant the snapshot was copied. */
+    readonly state: 'creating' | 'pending' | 'ready' | 'failed' | 'disposing' | 'disposed';
+    /** Ordered presence records for metadata captured during acquisition. */
+    readonly acquisitionMetadata: AcquisitionMetadataPresence<A>;
+}
+/** A frozen registration description and copied acquisition state returned by bag inspection. */
+export interface RegistrationSnapshot<M = Readonly<{}>, A extends readonly unknown[] = readonly []> {
+    /** Stable identity for the canonical graph binding. */
+    readonly bindingId: symbol;
+    /** Human-readable binding label. */
+    readonly label: string;
+    /** Direct lexical target; acquisition snapshots follow the canonical target. */
+    readonly aliasTarget?: {
+        readonly bindingId: symbol;
+        readonly label: string;
+    };
+    /** Static registration metadata; application-owned payload values retain their identity. */
+    readonly registrationMetadata: Readonly<M>;
+    /** Point-in-time attempts; inspection does not retain failed-attempt history. */
+    readonly acquisitions: readonly AcquisitionSnapshot<A>[];
+}

package/dist/inspection.js

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

package/dist/lifetime-types.d.ts

@@ -0,0 +1,214 @@
+import type { ContributionConstraint } from './contribution-types';
+import type { Registration, Registrations } from './registration';
+import type { Provider, ProviderFactory, ProviderGraphContract, ProviderNamedDependencies, ProviderRequiredTokens, ProviderOptionalTokens, ProviderCollectionTokens, ProviderRegistrationMetadata, ProviderAcquisitionMetadata, ProviderAcquiredValue } from './provider';
+import type { GraphContract } from './token-types';
+import type { TokenKey } from './tokens';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, Unsatisfied } from './types';
+import type { CheckedConstraints, CompleteConstraints, NeedConstraint, Renamed } from './module-types';
+/**
+ * A module provider's retained local registrations and public-to-local export mapping.
+ * Contexts chain through `parent` when a module was sealed inside another module:
+ * a name absent from `registrations` resolves in the parent, and the chain end
+ * resolves in the installing host, matching runtime lexical lookup.
+ */
+export type LexicalContext<R extends Registrations = Registrations, E extends object = object> = {
+    readonly registrations: R;
+    /** Current public name -> original local name. */
+    readonly exports: E;
+    readonly parent?: LexicalContext;
+};
+/** The lexical scope a sealing builder gives its retained constraints and providers. */
+export type ModuleScope<R extends Registrations, P extends PropertyKey> = LexicalContext<R, ExportMap<P>>;
+type Extras<C> = Pick<C, Exclude<keyof C, keyof LexicalContext>>;
+type WithExtras<C, X> = [Exclude<keyof C, keyof LexicalContext>] extends [never] ? X : X & Extras<C>;
+/** Attach an enclosing scope at the end of a lexical chain; `undefined` leaves the chain unchanged. */
+export type Enclosed<C, Parent> = [Parent] extends [undefined] ? C : C extends LexicalContext<infer R, infer E> ? C extends {
+    readonly parent: infer P extends LexicalContext;
+} ? WithExtras<C, LexicalContext<R, E> & {
+    readonly parent: Enclosed<P, Parent>;
+}> : WithExtras<C, LexicalContext<R, E> & {
+    readonly parent: Parent;
+}> : C;
+/** Rename one public export at the chain end, where names meet the installing host. */
+export type RenamedContext<C, Old extends string, New extends string> = C extends LexicalContext<infer R, infer E> ? C extends {
+    readonly parent: infer P extends LexicalContext;
+} ? WithExtras<C, LexicalContext<R, E> & {
+    readonly parent: RenamedContext<P, Old, New>;
+}> : WithExtras<C, LexicalContext<R, Renamed<E, Old, New>>> : C;
+/** The plain scope of a sealed contribution, without its retained original registration. */
+type Scope<C> = C extends LexicalContext<infer R, infer E> ? C extends {
+    readonly parent: infer P extends LexicalContext;
+} ? LexicalContext<R, E> & {
+    readonly parent: P;
+} : LexicalContext<R, E> : undefined;
+type WithoutLexical<G> = G extends {
+    readonly lexical: unknown;
+} ? Omit<G, 'lexical'> : G;
+export type LifetimeObligation = {
+    readonly kind: 'lifetime';
+    readonly source: PropertyKey;
+    readonly context: LexicalContext;
+};
+type ExportMap<P extends PropertyKey> = {
+    readonly [K in P]: K;
+};
+type Strict<R> = ProviderGraphContract<R> extends infer G ? G extends {
+    readonly lifetime: {
+        readonly kind: 'root';
+        readonly allowScopedDependencies: infer C;
+    };
+} ? [C] extends [true] ? false : true : false : false;
+export type PrivateLifetimes<R extends Registrations, P extends keyof R> = {
+    [K in Exclude<keyof R, P>]: true extends Strict<R[K]> ? {
+        readonly kind: 'lifetime';
+        readonly source: K;
+        readonly context: LexicalContext<R, ExportMap<P>>;
+    } : never;
+}[Exclude<keyof R, P>];
+export type LexicalProvider<V extends Registration, R extends Registrations, P extends keyof R, K extends keyof R> = V extends infer T & {} ? T extends Registration ? [Extract<ProviderGraphContract<T>, {
+    readonly lifetime: {
+        readonly kind: 'root' | 'transient';
+    };
+} | {
+    readonly alias: PropertyKey;
+}>] extends [never] ? T : Provider<ProviderFactory<T>, ProviderRegistrationMetadata<T> & object, ProviderAcquisitionMetadata<T>, WithoutLexical<ProviderGraphContract<T>> & {
+    readonly lexical: {
+        readonly source: K;
+        readonly context: ModuleScope<R, P>;
+    };
+}, ProviderAcquiredValue<T>> : never : never;
+type RenamedGraph<G extends GraphContract, Old extends string, New extends string> = G extends {
+    readonly lexical: {
+        readonly source: infer K;
+        readonly context: infer L extends LexicalContext;
+    };
+} ? Omit<G, 'lexical'> & {
+    readonly lexical: {
+        readonly source: K;
+        readonly context: RenamedContext<L, Old, New>;
+    };
+} : G;
+export type RenamedLifetimeProvider<V extends Registration, Old extends string, New extends string> = V extends infer T & {} ? T extends Registration ? ProviderGraphContract<T> extends {
+    readonly lexical: unknown;
+} ? Provider<ProviderFactory<T>, ProviderRegistrationMetadata<T> & object, ProviderAcquisitionMetadata<T>, RenamedGraph<ProviderGraphContract<T>, Old, New>, ProviderAcquiredValue<T>> : T : never : never;
+/** Rename public lifetime-carrier registrations while preserving their lexical sources. */
+export type RenamedLifetimeProviders<D extends Registrations, Old extends string, New extends string> = {
+    [K in keyof D as K extends Old ? New : K]: RenamedLifetimeProvider<D[K], Old, New>;
+};
+/** Rename a retained lifetime obligation's public export view. */
+export type RenamedLifetimeObligation<C extends LifetimeObligation, Old extends string, New extends string> = {
+    readonly kind: 'lifetime';
+    readonly source: C['source'];
+    readonly context: RenamedContext<C['context'], Old, New>;
+};
+/** Re-scope a retained obligation when the builder holding it seals into a module. */
+export type EnclosedLifetimeObligation<C extends LifetimeObligation, R extends Registrations, P extends PropertyKey> = {
+    readonly kind: 'lifetime';
+    readonly source: C['source'];
+    readonly context: Enclosed<C['context'], ModuleScope<R, P>>;
+};
+type PublicSite<K> = {
+    readonly kind: 'public';
+    readonly key: K;
+};
+type PrivateSite<C, K> = {
+    readonly kind: 'private';
+    readonly context: C;
+    readonly key: K;
+};
+type Captive<Root, Site> = {
+    readonly root: Root;
+    readonly dependency: Site;
+};
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+type Seen<S, V> = true extends (V extends unknown ? Equal<S, V> : never) ? true : false;
+type PublicKey<E, K> = {
+    [P in keyof E]: Equal<E[P], K> extends true ? P : never;
+}[keyof E];
+type Dependencies<V extends Registration> = keyof ProviderNamedDependencies<V> | TokenKey<ProviderRequiredTokens<V> | ProviderOptionalTokens<V>>;
+type WalkEnclosing<H extends Registrations, C, K, Root, Visited, G> = C extends {
+    readonly parent: infer P extends LexicalContext;
+} ? WalkDependency<H, P, K, Root, Visited, G> : WalkPublic<H, K, Root, Visited, G>;
+type WalkDependency<H extends Registrations, C, K, Root, Visited, G> = K extends PropertyKey ? C extends LexicalContext<infer R, infer E> ? K extends keyof R ? [PublicKey<E, K>] extends [never] ? WalkTarget<H, R[K], C, Root, PrivateSite<C, K>, Visited, G> : WalkEnclosing<H, C, PublicKey<E, K>, Root, Visited, G> : WalkEnclosing<H, C, K, Root, Visited, G> : WalkPublic<H, K, Root, Visited, G> : never;
+type WalkPublic<H extends Registrations, K, Root, Visited, G> = K extends keyof H ? WalkTarget<H, H[K], undefined, Root, PublicSite<K>, Visited, G> : never;
+type WalkTarget<H extends Registrations, V extends Registration, C, Root, Site, Visited, G> = V extends infer T & {} ? T extends Registration ? ProviderGraphContract<T> extends infer PG ? PG extends {
+    readonly sharedAlias: {
+        readonly registrations: infer P extends Registrations;
+        readonly source: infer K;
+    };
+} ? WalkPublic<P, K, Root, never, G> : PG extends {
+    readonly kind: 'opaque';
+} ? never : PG extends {
+    readonly alias: PropertyKey;
+} ? Seen<Site, Visited> extends true ? never : WalkSource<H, T, C, Root, Visited | Site, G> : PG extends {
+    readonly lifetime: {
+        readonly kind: 'root';
+    };
+} ? never : PG extends {
+    readonly lifetime: {
+        readonly kind: 'transient';
+    };
+} ? Seen<Site, Visited> extends true ? never : WalkSource<H, T, C, Root, Visited | Site, G> : Captive<Root, Site> : never : never : never;
+type WalkSource<H extends Registrations, V extends Registration, C, Root, Visited, G> = ProviderGraphContract<V> extends {
+    readonly lexical: {
+        readonly source: infer K;
+        readonly context: infer L extends LexicalContext;
+    };
+} ? K extends keyof L['registrations'] ? WalkSource<H, L['registrations'][K], Enclosed<L, C>, Root, Visited, G> : never : WalkDeclared<H, V, C, Root, Visited, G>;
+type WalkDeclared<H extends Registrations, V extends Registration, C, Root, Visited, G> = unknown extends (C extends LexicalContext ? CheckDependencyCompatibility<C['registrations']> : unknown) ? WalkDependency<H, C, Dependencies<V>, Root, Visited, G> | WalkCollection<H, ProviderCollectionTokens<V>, Root, Visited, G> : never;
+type CheckRoot<H extends Registrations, V extends Registration, C, Site, G> = V extends infer T & {} ? T extends Registration ? true extends Strict<T> ? WalkSource<H, T, C, Site, Site, G> : never : never : never;
+type PublicCaptives<H extends Registrations, G> = {
+    [K in keyof H]: CheckRoot<H, H[K], undefined, PublicSite<K>, G>;
+}[keyof H];
+type PrivateCaptives<H extends Registrations, C, G> = C extends LifetimeObligation ? C['source'] extends keyof C['context']['registrations'] ? CheckRoot<H, C['context']['registrations'][C['source']], C['context'], PrivateSite<C['context'], C['source']>, G> : never : never;
+type ContributionSite<C> = {
+    readonly kind: 'contribution';
+    readonly contribution: C;
+};
+type ContributionRegistration<I extends ContributionConstraint> = I['context'] extends {
+    readonly registration: infer O extends Registration;
+} ? O : I['registration'];
+type ContributionScope<I extends ContributionConstraint> = Scope<I['context']>;
+type WalkCollection<H extends Registrations, T, Root, Visited, G, Items = Extract<G, ContributionConstraint>> = Items extends ContributionConstraint ? TokenKey<Items['token']> extends TokenKey<T> ? WalkTarget<H, ContributionRegistration<Items>, ContributionScope<Items>, Root, ContributionSite<Items>, Visited, G> : never : never;
+type ContributionCaptives<H extends Registrations, G, Items = Extract<G, ContributionConstraint>> = Items extends ContributionConstraint ? CheckRoot<H, ContributionRegistration<Items>, ContributionScope<Items>, ContributionSite<Items>, G> : never;
+type Captives<R extends Registrations, C> = PublicCaptives<R, C> | PrivateCaptives<R, C, C> | ContributionCaptives<R, C>;
+type OverrideCaptives<R extends Registrations, O extends Registrations, G> = {
+    [K in keyof O & keyof R]: CheckRoot<R, R[K], undefined, PublicSite<K>, G>;
+}[keyof O & keyof R];
+/** Reject root providers introduced by a scope override when they capture scoped dependencies. */
+export type CheckedScopeLifetimes<R extends Registrations, O extends Registrations, G = never> = [
+    OverrideCaptives<R, O, G>
+] extends [never] ? unknown : Unsatisfied<'root lifetime cannot capture scoped dependency', {
+    readonly captives: OverrideCaptives<R, O, G>;
+}>;
+/** Reject strict root providers that transitively capture scoped dependencies. */
+export type CheckedLifetimes<R extends Registrations, C extends NeedConstraint> = [
+    Captives<R, C>
+] extends [never] ? unknown : unknown extends CheckDependencyCompatibility<R> & CheckDependencyCompleteness<R> & CheckedConstraints<C, R> & CompleteConstraints<C, R> ? Unsatisfied<'root lifetime cannot capture scoped dependency', {
+    readonly captives: Captives<R, C>;
+}> : unknown;
+type PolicyEnclosing<H extends Registrations, C, K, Visited> = C extends {
+    readonly parent: infer P extends LexicalContext;
+} ? PolicyDependency<H, P, K, Visited> : PolicyPublic<H, K, Visited>;
+type PolicyDependency<H extends Registrations, C, K, Visited> = K extends PropertyKey ? C extends LexicalContext<infer R, infer E> ? K extends keyof R ? [PublicKey<E, K>] extends [never] ? PolicyTarget<H, R[K], C, PrivateSite<C, K>, Visited> : PolicyEnclosing<H, C, PublicKey<E, K>, Visited> : PolicyEnclosing<H, C, K, Visited> : PolicyPublic<H, K, Visited> : never;
+type PolicyPublic<H extends Registrations, K, Visited> = K extends keyof H ? PolicyTarget<H, H[K], undefined, PublicSite<K>, Visited> : never;
+type PolicyTarget<H extends Registrations, V extends Registration, C, Site, Visited> = Seen<Site, Visited> extends true ? never : PolicyGraph<H, V, C, Visited | Site>;
+type PolicyGraph<H extends Registrations, V extends Registration, C, Visited> = ProviderGraphContract<V> extends infer G ? G extends {
+    readonly sharedAlias: {
+        readonly registrations: infer P extends Registrations;
+        readonly source: infer K;
+    };
+} ? PolicyPublic<P, K, never> : G extends {
+    readonly lexical: {
+        readonly source: infer S;
+        readonly context: infer L extends LexicalContext;
+    };
+} ? S extends keyof L['registrations'] ? PolicyGraph<H, L['registrations'][S], Enclosed<L, C>, Visited> : never : G extends {
+    readonly alias: infer K;
+} ? PolicyDependency<H, C, K, Visited> : G extends {
+    readonly lifetime: {
+        readonly kind: infer K;
+    };
+} ? K : 'scoped' : never;
+export type CanonicalLifetime<R extends Registrations, K extends keyof R> = PolicyPublic<R, K, never>;
+export {};

package/dist/lifetime-types.js

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

package/dist/lifetime.d.ts

@@ -0,0 +1,42 @@
+import type { Registration } from './registration';
+import type { Provider, ProviderFactory, RetainedMetadata, ProviderAcquisitionMetadata, ProviderGraphContract, ProviderAcquiredValue } from './provider';
+import type { GraphContract } from './token-types';
+import type { Singleton, Unsatisfied } from './types';
+/** Cache at the ownership-family root, once per scope, or once per resolution. */
+export type Lifetime = 'root' | 'scoped' | 'transient';
+export interface LifetimePolicy {
+    readonly kind: Lifetime;
+    readonly allowScopedDependencies: boolean;
+}
+type Admission<L> = Singleton<L> extends true ? unknown : Unsatisfied<'lifetime requires an individually known policy literal', {}>;
+type InvalidOption<L, O> = O extends infer T & {} ? T extends unknown ? Exclude<keyof T, 'allowScopedDependencies'> extends never ? L extends 'root' ? T extends {
+    readonly allowScopedDependencies?: boolean;
+} ? never : true : 'allowScopedDependencies' extends keyof T ? true : never : true : never : never;
+type Options<L, O> = [InvalidOption<L, O>] extends [never] ? unknown : InvalidOptions;
+type InvalidOptions = Unsatisfied<'withLifetime allowScopedDependencies requires root lifetime and a boolean value', {}>;
+export type LifetimeGraph<G extends GraphContract, L extends Lifetime, O> = G extends infer T & {} ? T extends GraphContract ? L extends 'scoped' ? 'lifetime' extends keyof T ? Omit<T, 'lifetime'> : T : Omit<T, 'lifetime'> & {
+    readonly lifetime: {
+        readonly kind: L;
+        readonly allowScopedDependencies: [O] extends [{
+            readonly allowScopedDependencies: true;
+        }] ? true : false;
+    };
+} : never : never;
+/**
+ * Select family-root caching, per-scope caching, or a fresh owned attempt per read.
+ * Strict roots cannot capture scoped dependencies. Wrapping preserves the factory,
+ * acquired value, metadata, frames, and ownership stages.
+ * @param registration - The registration whose caching policy to replace.
+ * @param lifetime - An individually known `root`, `scoped`, or `transient` literal.
+ * @returns A provider with the selected lifetime policy.
+ */
+export declare function withLifetime<R extends Registration, const L extends Lifetime>(registration: R & Registration, lifetime: L & Admission<L>): Provider<ProviderFactory<R>, RetainedMetadata<R>, ProviderAcquisitionMetadata<R>, LifetimeGraph<ProviderGraphContract<R>, L, undefined>, ProviderAcquiredValue<R>>;
+/**
+ * Select a lifetime and optionally permit a root provider to capture scoped dependencies.
+ * @param registration - The registration whose caching policy to replace.
+ * @param lifetime - An individually known `root`, `scoped`, or `transient` literal.
+ * @param options - Root-only `{ allowScopedDependencies: boolean }` admission.
+ * @returns A provider preserving factory, output, metadata, frames, and ownership stages.
+ */
+export declare function withLifetime<R extends Registration, const L extends Lifetime, const O extends object | undefined>(registration: R & Registration, lifetime: L & Admission<L>, options: O & Options<NoInfer<L>, NoInfer<O>>): Provider<ProviderFactory<R>, RetainedMetadata<R>, ProviderAcquisitionMetadata<R>, LifetimeGraph<ProviderGraphContract<R>, L, O>, ProviderAcquiredValue<R>>;
+export {};

package/dist/lifetime.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withLifetime = withLifetime;
+const errors_1 = require("./errors");
+const provider_1 = require("./provider");
+const provider_operations_1 = require("./provider-operations");
+function withLifetime(registration, lifetime, options) {
+    if (lifetime !== 'root' && lifetime !== 'scoped' && lifetime !== 'transient')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_LIFETIME', 'invalid lifetime policy', { operation: 'withLifetime', lifetime });
+    let allowScopedDependencies = false;
+    if (options !== undefined) {
+        if (typeof options !== 'object' || options === null || Array.isArray(options))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_LIFETIME', 'invalid lifetime options', { operation: 'withLifetime', lifetime });
+        const keys = Reflect.ownKeys(options);
+        if (keys.some(key => key !== 'allowScopedDependencies') || ('allowScopedDependencies' in options && !Object.hasOwn(options, 'allowScopedDependencies')))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_LIFETIME', 'invalid lifetime options', { operation: 'withLifetime', lifetime });
+        if (keys.length) {
+            if (lifetime !== 'root')
+                throw (0, errors_1.libraryError)('DI_BAG_INVALID_LIFETIME', 'withLifetime allowScopedDependencies requires root lifetime', { operation: 'withLifetime', lifetime });
+            const selected = Reflect.get(options, 'allowScopedDependencies');
+            if (typeof selected !== 'boolean')
+                throw (0, errors_1.libraryError)('DI_BAG_INVALID_LIFETIME', 'withLifetime allowScopedDependencies must be boolean', { operation: 'withLifetime', lifetime });
+            allowScopedDependencies = selected;
+        }
+    }
+    const policy = Object.freeze({ kind: lifetime, allowScopedDependencies });
+    const description = (0, provider_operations_1.describe)(registration);
+    const handle = (0, provider_1.createProvider)();
+    (0, provider_operations_1.retainDescription)(handle, Object.freeze({ ...description, lifetime: policy }));
+    return handle;
+}