di-bag 0.1.0

package/dist/module-types.d.ts

@@ -0,0 +1,182 @@
+import type { ContributionConstraint, CheckedContributions, CompleteContributions, RenamedContribution, ModuleContributionConstraints } from './contribution-types';
+import type { Module } from './module';
+import type { Registrations } from './registration';
+import type { Entry, Needs, RegistrationsFromEntries, ServicesOf, Singleton, Unsatisfied } from './types';
+import type { MetadataKeyUnion, Provider, ProviderOutput, ProviderNamedDependencies, ProviderRegistrationMetadata, ProviderAcquisitionMetadata, ProviderAcquiredValue, ProviderGraphContract, ProviderRequiredTokens, ProviderOptionalTokens, ProviderCollectionTokens, BoundToken } from './provider';
+import type { TokenDependencyContract, WrongToken, MissingToken } from './token-types';
+import type { TokenBase, TokenKey, TokenService } from './tokens';
+import type { LifetimeObligation, PrivateLifetimes, LexicalProvider, RenamedLifetimeObligation, EnclosedLifetimeObligation } from './lifetime-types';
+export type NeedConstraint = LifetimeObligation | ContributionConstraint | {
+    readonly kind: 'all';
+    readonly token: TokenBase;
+} | {
+    readonly kind: 'export' | 'external';
+    readonly consumer: string | symbol;
+    readonly needs: object;
+} | {
+    readonly kind: 'token-export' | 'token-external' | 'optional-token-export' | 'optional-token-external';
+    readonly consumer: string | symbol;
+    readonly token: TokenBase;
+} | {
+    readonly kind: 'opaque';
+};
+type WrongConstraint<C extends NeedConstraint, A extends Registrations> = C extends {
+    readonly needs: object;
+    readonly consumer: string | symbol;
+} ? {
+    [K in keyof C['needs'] & keyof ServicesOf<A>]: ServicesOf<A>[K] extends C['needs'][K] ? never : C['consumer'];
+}[keyof C['needs'] & keyof ServicesOf<A>] : never;
+type MissingConstraint<C extends NeedConstraint, Available extends object> = C extends {
+    readonly needs: object;
+} ? Exclude<keyof C['needs'], keyof Available> : never;
+type WrongTokenConstraint<C, A extends Registrations> = C extends {
+    kind: 'contribution' | 'all';
+} ? never : C extends {
+    token: infer T;
+} ? WrongToken<T, A> : C extends {
+    kind: 'opaque';
+} ? 'opaque' : never;
+type MissingTokenConstraint<C, A extends Registrations> = C extends {
+    kind: 'contribution' | 'all' | 'optional-token-export' | 'optional-token-external';
+} ? never : C extends {
+    token: infer T;
+} ? MissingToken<T, A> : C extends {
+    kind: 'opaque';
+} ? 'opaque' : never;
+type ConstraintRelationships<C, A extends object> = C extends {
+    readonly consumer: infer Consumer;
+    readonly needs: infer N;
+} ? {
+    [K in keyof N & keyof A]: A[K] extends N[K] ? never : {
+        consumer: Consumer;
+        dependency: K;
+        expected: N[K];
+        provided: A[K];
+    };
+}[keyof N & keyof A] : never;
+type MissingConstraintRelationships<C, A extends object> = C extends {
+    readonly consumer: infer Consumer;
+    readonly needs: infer N;
+} ? {
+    [K in Exclude<keyof N, keyof A>]: {
+        consumer: Consumer;
+        dependency: K;
+        expected: N[K];
+        provided: undefined;
+    };
+}[Exclude<keyof N, keyof A>] : never;
+export type CheckedConstraints<C extends NeedConstraint, A extends Registrations> = [
+    WrongConstraint<C, A> | WrongTokenConstraint<C, A>
+] extends [never] ? CheckedContributions<C, A> : Unsatisfied<'provided service does not satisfy its consumer dependency', {
+    tokens: WrongConstraint<C, A> | WrongTokenConstraint<C, A>;
+    relationships: ConstraintRelationships<C, ServicesOf<A>>;
+}>;
+export type IncrementalConstraints<C extends NeedConstraint, MC extends NeedConstraint, Old extends Registrations, Incoming extends Registrations> = [Extract<C | MC, {
+    kind: 'contribution' | 'all' | 'opaque' | 'lifetime';
+}>] extends [never] ? unknown extends CheckedConstraints<C, Incoming> ? CheckedConstraints<MC, import('./types').OverrideRegistrations<Old, Incoming>> : CheckedConstraints<C, Incoming> : CheckedConstraints<C | MC, import('./types').OverrideRegistrations<Old, Incoming>>;
+export type CompleteConstraints<C extends NeedConstraint, A extends Registrations> = [
+    MissingConstraint<C, ServicesOf<A>> | MissingTokenConstraint<C, A>
+] extends [never] ? CompleteContributions<C, A> : Unsatisfied<'required service registrations are missing', {
+    missing: MissingConstraint<C, ServicesOf<A>> | MissingTokenConstraint<C, A>;
+    relationships: MissingConstraintRelationships<C, ServicesOf<A>>;
+}>;
+type Constraint<K extends string | symbol, N, Keys extends keyof N, Kind extends string> = [
+    Keys
+] extends [never] ? never : {
+    readonly consumer: K;
+    readonly needs: Pick<N, Keys>;
+    readonly kind: Kind;
+};
+export type RegistrationConstraints<V extends Registrations[string], R extends Registrations, Public extends keyof R, K extends string | symbol = string | symbol> = Constraint<K, Needs<V>, Extract<keyof Needs<V>, Public>, 'export'> | Constraint<K, Needs<V>, Exclude<keyof Needs<V>, keyof R>, 'external'> | (ProviderCollectionTokens<V> extends infer T ? T extends TokenBase ? {
+    readonly kind: 'all';
+    readonly token: T;
+} : never : never) | TokenConstraint<K, ProviderRequiredTokens<V>, R, Public> | TokenConstraint<K, ProviderOptionalTokens<V>, R, Public, true> | ([ProviderGraphContract<V>] extends [TokenDependencyContract<readonly TokenBase[], TokenBase, readonly TokenBase[]>] ? never : {
+    readonly kind: 'opaque';
+});
+/** Retained requirements of a module's public and private registrations. */
+export type ModuleConstraints<R extends Registrations, Public extends keyof R> = {
+    [K in keyof R & (string | symbol)]: RegistrationConstraints<R[K], R, Public, K>;
+}[keyof R & (string | symbol)] | PrivateLifetimes<R, Public>;
+type TokenConstraint<K extends string | symbol, T, R, Public, Optional extends boolean = false> = T extends TokenBase ? TokenKey<T> extends Public ? {
+    readonly consumer: K;
+    readonly token: T;
+    readonly kind: Optional extends true ? 'optional-token-export' : 'token-export';
+} : TokenKey<T> extends keyof R ? never : {
+    readonly consumer: K;
+    readonly token: T;
+    readonly kind: Optional extends true ? 'optional-token-external' : 'token-external';
+} : never;
+type Intersect<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
+type External<C> = C extends {
+    kind: 'external';
+    needs: infer N;
+} ? N : C extends {
+    kind: 'token-external';
+    token: infer T;
+} ? Record<TokenKey<T>, TokenService<T>> : C extends {
+    kind: 'optional-token-external';
+    token: infer T;
+} ? Partial<Record<TokenKey<T>, TokenService<T>>> : never;
+export type ExternalRequirements<C> = [External<C>] extends [never] ? Readonly<{}> : Readonly<Intersect<External<C>>>;
+type OutputFactory<O> = () => O;
+export type PublicRegistrations<P extends object> = {
+    [K in keyof P]: () => P[K];
+};
+export type PublicProvider<R> = R extends Registrations[string] ? unknown extends ProviderNamedDependencies<R> ? R : [ProviderGraphContract<R>] extends [TokenDependencyContract<readonly TokenBase[], TokenBase, readonly TokenBase[]>] ? [Extract<ProviderGraphContract<R>, {
+    readonly lifetime: unknown;
+} | {
+    readonly alias: PropertyKey;
+}>] extends [never] ? [MetadataKeyUnion<ProviderRegistrationMetadata<R>> | BoundToken<R>] extends [never] ? ProviderAcquisitionMetadata<R> extends readonly [] ? [ProviderAcquiredValue<R>] extends [Awaited<ProviderOutput<R>>] ? [Awaited<ProviderOutput<R>>] extends [ProviderAcquiredValue<R>] ? OutputFactory<ProviderOutput<R>> : RetainedPublicProvider<R> : RetainedPublicProvider<R> : RetainedPublicProvider<R> : RetainedPublicProvider<R> : RetainedPublicProvider<R> : R : never;
+type PublicGraph<G> = G extends TokenDependencyContract<readonly TokenBase[], TokenBase, readonly TokenBase[]> ? {
+    [K in keyof G]: K extends 'required' | 'optional' | 'all' ? readonly [] : G[K];
+} : never;
+type RetainedPublicProvider<R extends Registrations[string]> = Provider<OutputFactory<ProviderOutput<R>>, ProviderRegistrationMetadata<R> & object, ProviderAcquisitionMetadata<R>, PublicGraph<ProviderGraphContract<R>>, ProviderAcquiredValue<R>>;
+/** Project registrations to dependency-free public descriptions while retaining behavioral contracts. */
+export type PublicProviders<R extends object> = {
+    [K in keyof R]: PublicProvider<R[K]>;
+};
+/** Project selected module exports while retaining their lexical private graph where required. */
+export type ModulePublicProviders<R extends Registrations, P extends keyof R> = {
+    [K in P]: LexicalProvider<PublicProvider<R[K]>, R, P, K>;
+};
+/** Rename one string key in an object contract. */
+export type Renamed<P extends object, Old extends string, New extends string> = {
+    [K in keyof P as K extends Old ? New : K]: P[K];
+};
+export type RenamedConstraints<C extends NeedConstraint, Old extends string, New extends string> = C extends ContributionConstraint ? RenamedContribution<C, Old, New> : C extends LifetimeObligation ? RenamedLifetimeObligation<C, Old, New> : C extends {
+    readonly kind: 'export';
+    readonly consumer: string | symbol;
+    readonly needs: object;
+} ? {
+    readonly consumer: C['consumer'];
+    readonly needs: Renamed<C['needs'], Old, New>;
+    readonly kind: 'export';
+} : C;
+export type RenameKeys<P, Old extends string, New extends string> = Singleton<Old> extends true ? Singleton<New> extends true ? Old extends keyof P ? New extends Exclude<keyof P, Old> ? InvalidRename : unknown : InvalidRename : InvalidRename : InvalidRename;
+type InvalidRename = Unsatisfied<'renameExport requires an existing export and a noncolliding singleton string-literal name', {}>;
+/**
+ * Re-scope every constraint a builder retained from installed modules and
+ * contributions when that builder seals into a module with exports `P`.
+ * Needs on an export stay checkable by the host; needs satisfied privately are
+ * final and drop; unsatisfied needs remain external requirements of the module.
+ */
+export type SealedConstraints<C extends NeedConstraint, R extends Registrations, P extends keyof R> = C extends ContributionConstraint ? ModuleContributionConstraints<C, R, P> : C extends LifetimeObligation ? EnclosedLifetimeObligation<C, R, P> : C extends {
+    readonly kind: 'export' | 'external';
+    readonly consumer: infer K extends string | symbol;
+    readonly needs: infer N extends object;
+} ? Constraint<K, N, Extract<keyof N, P>, 'export'> | Constraint<K, N, Exclude<keyof N, keyof R>, 'external'> : C extends {
+    readonly kind: 'token-export' | 'token-external';
+    readonly consumer: infer K extends string | symbol;
+    readonly token: infer T;
+} ? TokenConstraint<K, T, R, P> : C extends {
+    readonly kind: 'optional-token-export' | 'optional-token-external';
+    readonly consumer: infer K extends string | symbol;
+    readonly token: infer T;
+} ? TokenConstraint<K, T, R, P, true> : C;
+/** Every constraint a sealed module carries: its own registrations' needs plus re-scoped retained constraints. */
+export type ModuleSealedConstraints<E extends Entry, C extends NeedConstraint, P extends keyof RegistrationsFromEntries<E>> = ModuleConstraints<RegistrationsFromEntries<E>, P> | SealedConstraints<C, RegistrationsFromEntries<E>, P>;
+/** Extract a readonly map of services publicly exposed by a module. */
+export type ModuleExportedServices<M> = M extends Module<infer P, infer _R, infer _C, infer _D> ? Readonly<P> : never;
+/** Extract a readonly map of services a module requires from its host. */
+export type ModuleRequiredServices<M> = M extends Module<infer _P, infer R, infer _C, infer _D> ? Readonly<R> : never;
+export {};

package/dist/module-types.js

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

package/dist/module.d.ts

@@ -0,0 +1,45 @@
+import type { BindingGraph, BindingKey, GraphDescription } from './runtime';
+import type { Registrations } from './registration';
+import type { NeedConstraint, PublicRegistrations, Renamed, RenamedConstraints, RenameKeys } from './module-types';
+import type { RenamedLifetimeProviders } from './lifetime-types';
+interface ModuleDescription {
+    /** The sealed graph: every binding that was retained when the builder sealed. */
+    readonly graph: GraphDescription;
+    /** Public slot -> original local name. Factory parameter names never change. */
+    readonly exports: ReadonlyMap<BindingKey, BindingKey>;
+}
+declare const moduleInvariant: unique symbol;
+/**
+ * A sealed, non-resolving module with private registrations and selected public exports.
+ * Create modules through {@link DiBagApi.createBuilder} and {@link Builder.buildModule}; this
+ * type-only class has no public constructor.
+ */
+declare class Module<P extends object, R extends object, C extends NeedConstraint = never, D extends Registrations = PublicRegistrations<P>> {
+    private readonly nominal;
+    /** @internal */
+    readonly [moduleInvariant]: (value: [P, R, C, D]) => [P, R, C, D];
+    constructor(description: ModuleDescription);
+    /**
+     * Return a module view with one string-named export renamed.
+     * Factory dependency names and private identities remain unchanged.
+     * @param oldKey - An existing public string export.
+     * @param newKey - A noncolliding string-literal export name.
+     * @returns A new sealed module, or the same instance when both names are equal.
+     * @throws If runtime input names are invalid, absent, or collide.
+     */
+    renameExport<const Old extends string, const New extends string>(oldKey: Old & RenameKeys<P, Old, New>, newKey: New & RenameKeys<P, Old, New>): Module<Renamed<P, Old, New>, R, RenamedConstraints<C, Old, New>, RenamedLifetimeProviders<D, Old, New>>;
+}
+/**
+ * Seal a builder graph into a module. Runtime validation only: the selected
+ * keys must be a tuple of existing public names or typed tokens.
+ * @internal
+ */
+export declare function sealModule(graph: BindingGraph, keys: unknown): Module<never, never, never, never>;
+/**
+ * Internal normalization: every install receives fresh binding identities at
+ * every nesting depth. Names resolve lexically: a binding's own local names
+ * (from an inner installation) win, then the module's public names, then the
+ * installing host's public slots.
+ */
+export declare function moduleGraph(value: object): GraphDescription;
+export type { Module };

package/dist/module.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sealModule = sealModule;
+exports.moduleGraph = moduleGraph;
+const errors_1 = require("./errors");
+const tokens_1 = require("./tokens");
+const descriptions = new WeakMap();
+/**
+ * A sealed, non-resolving module with private registrations and selected public exports.
+ * Create modules through {@link DiBagApi.createBuilder} and {@link Builder.buildModule}; this
+ * type-only class has no public constructor.
+ */
+class Module {
+    constructor(description) {
+        descriptions.set(this, { graph: description.graph, exports: new Map(description.exports) });
+        Object.freeze(this);
+    }
+    /**
+     * Return a module view with one string-named export renamed.
+     * Factory dependency names and private identities remain unchanged.
+     * @param oldKey - An existing public string export.
+     * @param newKey - A noncolliding string-literal export name.
+     * @returns A new sealed module, or the same instance when both names are equal.
+     * @throws If runtime input names are invalid, absent, or collide.
+     */
+    renameExport(oldKey, newKey) {
+        const description = descriptions.get(this);
+        if (typeof oldKey !== 'string' || !description.exports.has(oldKey))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_EXPORT', 'renameExport requires an existing export', { operation: 'renameExport', oldKey, newKey });
+        if (typeof newKey !== 'string')
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_EXPORT', 'renameExport requires a string name', { operation: 'renameExport', oldKey, newKey });
+        if (oldKey === newKey)
+            return this;
+        if (description.exports.has(newKey))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_EXPORT', `duplicate export: ${newKey}`, { operation: 'renameExport', oldKey, newKey });
+        const exports = new Map(description.exports);
+        const localName = exports.get(oldKey);
+        exports.delete(oldKey);
+        exports.set(newKey, localName);
+        return new Module({ graph: description.graph, exports });
+    }
+}
+/**
+ * Seal a builder graph into a module. Runtime validation only: the selected
+ * keys must be a tuple of existing public names or typed tokens.
+ * @internal
+ */
+function sealModule(graph, keys) {
+    if (!Array.isArray(keys))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_EXPORT', 'buildModule requires a key tuple', { operation: 'buildModule' });
+    // Snapshot indexed entries before a custom iterator can substitute keys.
+    const selected = [];
+    const length = keys.length;
+    for (let index = 0; index < length; index++)
+        selected[index] = keys[index];
+    const exports = new Map();
+    for (const value of selected) {
+        const key = typeof value === 'string' ? value : (0, tokens_1.readTokenKey)(value);
+        if (!graph.hasPublic(key))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_EXPORT', 'buildModule accepts existing names or typed tokens only', { operation: 'buildModule' });
+        exports.set(key, key);
+    }
+    return new Module({ graph: graph.describe(), exports });
+}
+/**
+ * Internal normalization: every install receives fresh binding identities at
+ * every nesting depth. Names resolve lexically: a binding's own local names
+ * (from an inner installation) win, then the module's public names, then the
+ * installing host's public slots.
+ */
+function moduleGraph(value) {
+    const description = descriptions.get(value);
+    if (!description)
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_MODULE', 'installModule requires a genuine module', { operation: 'installModule' });
+    const { graph, exports } = description;
+    const ids = new Map();
+    for (const [id, binding] of graph.bindings)
+        ids.set(id, Symbol(binding.label));
+    const exportNames = new Map();
+    for (const [publicKey, localKey] of exports)
+        exportNames.set(localKey, publicKey);
+    // Every public name of the sealed graph, as seen by its own bindings.
+    const scopeNames = new Map();
+    for (const [key, id] of graph.publicSlots) {
+        const exported = exportNames.get(key);
+        scopeNames.set(key, exported === undefined ? { kind: 'private', id: ids.get(id) } : { kind: 'public', key: exported });
+    }
+    const remap = (ref) => ref.kind === 'private'
+        ? { kind: 'private', id: ids.get(ref.id) ?? ref.id }
+        : scopeNames.get(ref.key) ?? ref;
+    // Share one lexical map per distinct inner scope so the graph deduplicates snapshots.
+    const nested = new Map();
+    const localNamesFor = (binding) => {
+        if (binding.localNames.size === 0)
+            return scopeNames;
+        let names = nested.get(binding.localNames);
+        if (!names) {
+            const merged = new Map(scopeNames);
+            for (const [name, ref] of binding.localNames)
+                merged.set(name, remap(ref));
+            names = merged;
+            nested.set(binding.localNames, names);
+        }
+        return names;
+    };
+    const bindings = new Map();
+    for (const [id, binding] of graph.bindings) {
+        const fresh = ids.get(id);
+        bindings.set(fresh, { id: fresh, label: binding.label, registration: binding.registration, localNames: localNamesFor(binding) });
+    }
+    const publicSlots = new Map();
+    for (const [publicKey, localKey] of exports)
+        publicSlots.set(publicKey, ids.get(graph.publicSlots.get(localKey)));
+    const contributions = new Map();
+    for (const [key, group] of graph.contributions ?? [])
+        contributions.set(key, group.map(id => ids.get(id)));
+    return { bindings, publicSlots, contributions };
+}

package/dist/node.d.ts

@@ -0,0 +1,4 @@
+import { DiBag as CoreDiBag } from './di-bag';
+export * from './index';
+/** The Node/Bun facade preconfigured with the host's native-Promise classifier. */
+export declare const DiBag: typeof CoreDiBag;

package/dist/node.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiBag = void 0;
+const { isPromise } = require('node:util/types');
+const di_bag_1 = require("./di-bag");
+__exportStar(require("./index"), exports);
+/** The Node/Bun facade preconfigured with the host's native-Promise classifier. */
+exports.DiBag = di_bag_1.DiBag.withConfiguration({ runtime: { isNativePromise: isPromise } });

package/dist/observers.d.ts

@@ -0,0 +1,71 @@
+import type { AcquisitionMetadataPresence } from './inspection';
+import type { Lifetime } from './lifetime';
+/** Identity shared by lifecycle events for one owning scope. */
+export interface ScopeEventFields {
+    /** The scope that owns the transition. */
+    readonly scopeId: symbol;
+    /** The tracked parent, present only for child-scope events. */
+    readonly parentScopeId?: symbol;
+}
+/** Copied binding and acquisition details carried by acquisition and cleanup events. */
+export interface AcquisitionEventFields {
+    readonly scopeId: symbol;
+    readonly bindingId: symbol;
+    readonly acquisitionId: symbol;
+    readonly label: string;
+    readonly lifetime: Lifetime;
+    readonly registrationMetadata: Readonly<object>;
+    readonly acquisitionMetadata: AcquisitionMetadataPresence<readonly unknown[]>;
+}
+/**
+ * A frozen discriminated lifecycle transition emitted after the corresponding state change.
+ * Narrow on `kind` to access failure, cleanup outcome, or disposal-index fields.
+ */
+export type LifecycleEvent = (ScopeEventFields & {
+    readonly kind: 'scope-opened';
+}) | (ScopeEventFields & {
+    readonly kind: 'scope-closing';
+}) | (ScopeEventFields & {
+    readonly kind: 'scope-closed';
+}) | (ScopeEventFields & {
+    readonly kind: 'scope-close-failed';
+    readonly error: unknown;
+}) | (AcquisitionEventFields & {
+    readonly kind: 'acquisition-started';
+}) | (AcquisitionEventFields & {
+    readonly kind: 'acquisition-ready';
+}) | (AcquisitionEventFields & {
+    readonly kind: 'cleanup-started';
+}) | (AcquisitionEventFields & {
+    readonly kind: 'acquisition-failed';
+    readonly error: unknown;
+}) | (AcquisitionEventFields & {
+    readonly kind: 'cleanup-failed';
+    readonly error: unknown;
+    readonly disposalSequence: number;
+}) | (AcquisitionEventFields & {
+    readonly kind: 'cleanup-completed';
+    readonly outcome: 'success' | 'failure';
+});
+/** A failure thrown or rejected by an observer together with its original event. */
+export interface ObserverFailure {
+    readonly error: unknown;
+    readonly event: LifecycleEvent;
+}
+/** An asynchronous, non-gating callback for frozen lifecycle events. */
+export type ObserverCallback = (this: void, event: LifecycleEvent) => unknown;
+/** Reports failures from one observer's event callback; its own failures are consumed. */
+export type ObserverErrorCallback = (this: void, failure: ObserverFailure) => unknown;
+/** Both callbacks required by {@link DiBagApi.withConfiguration}. */
+export interface ObserverOptions {
+    /** Receives events in transition and observer-registration order on a microtask queue. */
+    readonly onEvent: ObserverCallback;
+    /** Receives synchronous throws and rejected results from `onEvent`. */
+    readonly onError: ObserverErrorCallback;
+}
+export declare class LifecycleObservers {
+    private readonly callbacks;
+    private constructor();
+    static append(previous: LifecycleObservers | undefined, options: ObserverOptions): LifecycleObservers;
+    emit(event: LifecycleEvent): void;
+}

package/dist/observers.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifecycleObservers = void 0;
+const errors_1 = require("./errors");
+const then = (Promise.prototype.then);
+const ignore = () => { };
+/** Assimilate only callback results, always through a library-owned Promise. */
+function monitor(result, failed) {
+    if ((typeof result !== 'object' || result === null) && typeof result !== 'function')
+        return;
+    const pending = new Promise(resolve => { resolve(result); });
+    then.call(pending, ignore, failed);
+}
+// One lazy queue preserves ordering when a callback observes multiple facades.
+let queue;
+class LifecycleObservers {
+    callbacks;
+    constructor(callbacks) {
+        this.callbacks = callbacks;
+    }
+    static append(previous, options) {
+        if (typeof options !== 'object' || options === null)
+            throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_CONFIGURATION', 'withConfiguration observers require onEvent and onError callbacks', { operation: 'withConfiguration' });
+        const { onEvent, onError } = options;
+        if (typeof onEvent !== 'function' || typeof onError !== 'function')
+            throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_CONFIGURATION', 'withConfiguration observers require onEvent and onError callbacks', { operation: 'withConfiguration' });
+        return new LifecycleObservers([...(previous?.callbacks ?? []), Object.freeze({ onEvent, onError })]);
+    }
+    emit(event) {
+        const delivery = { event: Object.freeze(event), callbacks: this.callbacks };
+        if (queue) {
+            queue.push(delivery);
+            return;
+        }
+        queue = [delivery];
+        queueMicrotask(() => {
+            // Detach this batch: reentrant transitions schedule another microtask.
+            const deliveries = queue;
+            queue = undefined;
+            for (const { event, callbacks } of deliveries)
+                for (const { onEvent, onError } of callbacks) {
+                    const failed = (error) => {
+                        try {
+                            monitor(onError(Object.freeze({ error, event })), ignore);
+                        }
+                        catch { /* Error reporting must not recursively report itself. */ }
+                    };
+                    try {
+                        monitor(onEvent(event), failed);
+                    }
+                    catch (error) {
+                        failed(error);
+                    }
+                }
+        });
+    }
+}
+exports.LifecycleObservers = LifecycleObservers;

package/dist/persistent-map.d.ts

@@ -0,0 +1,29 @@
+/** Private immutable hash trie. Versions share nodes, never map wrappers or caches. */
+type Key = string | symbol;
+type Leaf<V> = {
+    readonly kind: 'leaf';
+    readonly hash: number;
+    readonly key: Key;
+    readonly value: V;
+};
+type Collision<V> = {
+    readonly kind: 'collision';
+    readonly hash: number;
+    readonly entries: readonly Leaf<V>[];
+};
+type Branch<V> = {
+    readonly kind: 'branch';
+    readonly bitmap: number;
+    readonly children: readonly Node<V>[];
+};
+type Node<V> = Leaf<V> | Collision<V> | Branch<V>;
+export declare class PersistentMap<V> {
+    private readonly root?;
+    constructor(root?: Node<V> | undefined);
+    get(key: Key): V | undefined;
+    has(key: Key): boolean;
+    set(key: Key, value: V): PersistentMap<V>;
+    delete(key: Key): PersistentMap<V>;
+    [Symbol.iterator](): IterableIterator<readonly [Key, V]>;
+}
+export {};