di-bag 0.1.0

package/dist/runtime.d.ts

@@ -0,0 +1,90 @@
+import { ScopeAcquisitions } from './acquisition';
+import { normalize } from './registration';
+import type { Registration, Registrations } from './registration';
+import type { RegistrationSnapshot } from './inspection';
+import type { RuntimeContext } from './acquisition-mode';
+export type BindingId = symbol;
+export type BindingKey = string | symbol;
+export type BindingRef = {
+    readonly kind: 'private';
+    readonly id: BindingId;
+} | {
+    readonly kind: 'public';
+    readonly key: BindingKey;
+};
+export interface BindingDescription {
+    readonly id: BindingId;
+    readonly label: string;
+    readonly registration: Registration;
+    readonly localNames: ReadonlyMap<BindingKey, BindingRef>;
+}
+export interface GraphDescription {
+    readonly bindings: ReadonlyMap<BindingId, BindingDescription>;
+    readonly publicSlots: ReadonlyMap<BindingKey, BindingId>;
+    readonly contributions?: ReadonlyMap<symbol, readonly BindingId[]>;
+}
+type Normalized = Readonly<ReturnType<typeof normalize>>;
+/** Immutable descriptions and path-copied lookup storage. Retained maps never escape. */
+export declare class BindingGraph {
+    #private;
+    constructor(description?: GraphDescription);
+    /** Share only storage roots. Caches never retain ancestor wrappers or old arrays. */
+    private copy;
+    private entry;
+    private slot;
+    private addBinding;
+    contributionBindings(key: symbol): readonly BindingId[];
+    withContribution(key: symbol, registration: Registration): BindingGraph;
+    hasPublic(key: BindingKey): boolean;
+    hasBinding(id: BindingId): boolean;
+    /** Immutable graphs need explicit-mode validation only once; configured forks are O(1). */
+    preflight(context: RuntimeContext): void;
+    publicBinding(key: BindingKey): BindingId;
+    private requirePublicBinding;
+    findDependency(from: BindingId, localName: BindingKey): BindingId | undefined;
+    dependency(from: BindingId, localName: BindingKey): BindingId;
+    registration(id: BindingId): Normalized;
+    private requireRegistration;
+    label(id: BindingId): string;
+    withPublicRegistrations(registrations: Registrations): BindingGraph;
+    /** Replace ordered slots and prune only unreferenced public replacement history. */
+    withPublicBindings(entries: readonly (readonly [BindingKey, Registration])[]): BindingGraph;
+    withPublicBinding(key: BindingKey, registration: Registration): BindingGraph;
+    private releaseLexical;
+    /** No recursion or graph-wide scan, even when losing a snapshot unlocks a chain. */
+    private prune;
+    /**
+     * Snapshot every retained binding for sealing into a module. Public bindings
+     * come first in declaration order, then contributions in their group order,
+     * then any privately retained binding. Nothing beyond the graph's own storage
+     * is kept to produce this order.
+     */
+    describe(): GraphDescription;
+    /** Install disjoint public slots atomically, retaining lexical private refs. */
+    withInstallation(description: GraphDescription): BindingGraph;
+}
+/** Each runtime owns its acquisitions; immutable descriptions remain reusable. */
+export declare class BagRuntime {
+    private readonly graph;
+    private readonly context;
+    private detach;
+    private readonly parentAcquisitions?;
+    private readonly acquisitions;
+    private readonly children;
+    private closing;
+    private state;
+    constructor(graph: BindingGraph, context: RuntimeContext, detach?: (() => void) | undefined, parentAcquisitions?: ScopeAcquisitions | undefined, shared?: readonly BindingId[]);
+    resolve(key: BindingKey): unknown;
+    resolveAll(key: symbol): readonly unknown[];
+    inspectAll(key: symbol): readonly RegistrationSnapshot<object, readonly unknown[]>[];
+    acquire(key: BindingKey): Promise<void>;
+    isTransient(key: BindingKey): boolean;
+    inspect(key: BindingKey): RegistrationSnapshot<object, readonly unknown[]>;
+    private inspectBinding;
+    assertOpen(): void;
+    scope(graph?: BindingGraph, shared?: readonly BindingId[]): BagRuntime;
+    close(cause?: unknown): Promise<void>;
+    private observeScope;
+    private finishClose;
+}
+export {};

package/dist/runtime.js

@@ -0,0 +1,428 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BagRuntime = exports.BindingGraph = void 0;
+const errors_1 = require("./errors");
+const acquisition_1 = require("./acquisition");
+const persistent_map_1 = require("./persistent-map");
+const persistent_sequence_1 = require("./persistent-sequence");
+const errors_2 = require("./errors");
+const registration_1 = require("./registration");
+const acquisition_mode_1 = require("./acquisition-mode");
+const emptyContributions = Object.freeze([]);
+const emptyNames = new Map();
+/** Immutable descriptions and path-copied lookup storage. Retained maps never escape. */
+class BindingGraph {
+    #bindings = new persistent_map_1.PersistentMap();
+    #publicSlots = new persistent_map_1.PersistentMap();
+    #publicReferences = new persistent_map_1.PersistentMap();
+    #lexicalUsers = new persistent_map_1.PersistentMap();
+    #privateReferences = new persistent_map_1.PersistentMap();
+    #contributed = new persistent_map_1.PersistentMap();
+    // Only former public bindings are candidates; constructor-only private
+    // registrations remain available to whole-graph preflight.
+    #obsolete = new persistent_map_1.PersistentMap();
+    #contributions = new persistent_map_1.PersistentMap();
+    // First public registration order by key, for module snapshots. Keys are
+    // never unregistered, so this retains nothing a graph would otherwise drop.
+    #publicOrder;
+    #bindingCache = new Map();
+    #registrationCache = new Map();
+    #publicCache = new Map();
+    #contributionCache = new Map();
+    #explicitlyClassified = false;
+    constructor(description = { bindings: new Map(), publicSlots: new Map() }) {
+        const lexicalSnapshots = new Map();
+        for (const [id, binding] of description.bindings) {
+            let lexical = lexicalSnapshots.get(binding.localNames);
+            if (!lexical) {
+                const snapshot = new Map();
+                const privateIds = [];
+                for (const [name, ref] of binding.localNames) {
+                    const copiedRef = Object.freeze({ ...ref });
+                    snapshot.set(name, copiedRef);
+                    if (copiedRef.kind === 'private')
+                        privateIds.push(copiedRef.id);
+                }
+                lexical = { id: Symbol('lexical'), names: snapshot, privateIds };
+                lexicalSnapshots.set(binding.localNames, lexical);
+                for (const target of privateIds)
+                    this.#privateReferences = this.#privateReferences.set(target, (this.#privateReferences.get(target) ?? 0) + 1);
+            }
+            this.#lexicalUsers = this.#lexicalUsers.set(lexical.id, (this.#lexicalUsers.get(lexical.id) ?? 0) + 1);
+            this.#bindings = this.#bindings.set(id, {
+                lexical,
+                description: Object.freeze({ id: binding.id, label: binding.label, registration: binding.registration, localNames: lexical.names }),
+                normalized: Object.freeze((0, registration_1.normalize)(binding.registration)),
+            });
+        }
+        for (const [key, id] of description.publicSlots) {
+            this.#publicOrder = (0, persistent_sequence_1.append)(this.#publicOrder, { values: [key] });
+            this.#publicSlots = this.#publicSlots.set(key, id);
+            this.#publicReferences = this.#publicReferences.set(id, (this.#publicReferences.get(id) ?? 0) + 1);
+        }
+        for (const [key, ids] of description.contributions ?? []) {
+            const snapshot = Object.freeze([...ids]);
+            this.#contributions = this.#contributions.set(key, { values: snapshot });
+            for (const id of snapshot)
+                this.#contributed = this.#contributed.set(id, true);
+        }
+    }
+    /** Share only storage roots. Caches never retain ancestor wrappers or old arrays. */
+    copy() {
+        const graph = new BindingGraph();
+        graph.#bindings = this.#bindings;
+        graph.#publicSlots = this.#publicSlots;
+        graph.#publicReferences = this.#publicReferences;
+        graph.#lexicalUsers = this.#lexicalUsers;
+        graph.#privateReferences = this.#privateReferences;
+        graph.#contributed = this.#contributed;
+        graph.#obsolete = this.#obsolete;
+        graph.#contributions = this.#contributions;
+        graph.#publicOrder = this.#publicOrder;
+        return graph;
+    }
+    entry(id) {
+        const entry = this.#bindings.get(id);
+        if (entry) {
+            this.#bindingCache.set(id, entry.description);
+            this.#registrationCache.set(id, entry.normalized);
+        }
+        return entry;
+    }
+    slot(key) {
+        const id = this.#publicSlots.get(key);
+        if (id !== undefined)
+            this.#publicCache.set(key, id);
+        return id;
+    }
+    addBinding(label, registration) {
+        const id = Symbol(label);
+        this.#bindings = this.#bindings.set(id, {
+            description: Object.freeze({ id, label, registration, localNames: emptyNames }),
+            normalized: Object.freeze((0, registration_1.normalize)(registration)),
+        });
+        return id;
+    }
+    contributionBindings(key) {
+        let ids = this.#contributionCache.get(key);
+        if (!ids) {
+            const sequence = this.#contributions.get(key);
+            if (!sequence)
+                return emptyContributions;
+            ids = (0, persistent_sequence_1.materialize)(sequence);
+            this.#contributionCache.set(key, ids);
+        }
+        return ids;
+    }
+    withContribution(key, registration) {
+        const graph = this.copy();
+        const id = graph.addBinding(`contribution:${String(key)}`, registration);
+        graph.#contributions = graph.#contributions.set(key, (0, persistent_sequence_1.append)(graph.#contributions.get(key), { values: [id] }));
+        graph.#contributed = graph.#contributed.set(id, true);
+        return graph;
+    }
+    hasPublic(key) { return this.#publicCache.has(key) || this.#publicSlots.has(key); }
+    hasBinding(id) { return this.#bindings.has(id); }
+    /** Immutable graphs need explicit-mode validation only once; configured forks are O(1). */
+    preflight(context) {
+        if (context.isNativePromise || this.#explicitlyClassified)
+            return;
+        for (const [, { normalized: description }] of this.#bindings) {
+            (0, acquisition_mode_1.requireClassificationCapability)([description.acquisitionMode, ...description.operations.flatMap(operation => 'acquisitionMode' in operation ? [operation.acquisitionMode] : [])], context);
+        }
+        this.#explicitlyClassified = true;
+    }
+    publicBinding(key) {
+        return this.#publicCache.get(key) ?? this.requirePublicBinding(key);
+    }
+    requirePublicBinding(key) {
+        const id = this.slot(key);
+        if (id === undefined)
+            throw (0, errors_1.libraryError)('DI_BAG_MISSING_REGISTRATION', `Service ${JSON.stringify(String(key))} is not registered.`, { operation: 'resolve', key });
+        return id;
+    }
+    findDependency(from, localName) {
+        const ref = (this.#bindingCache.get(from) ?? this.entry(from)?.description)?.localNames.get(localName);
+        if (ref?.kind === 'private')
+            return ref.id;
+        const key = ref?.key ?? localName;
+        return this.#publicCache.get(key) ?? this.slot(key);
+    }
+    dependency(from, localName) {
+        const target = this.findDependency(from, localName);
+        if (target === undefined)
+            throw (0, errors_1.libraryError)('DI_BAG_MISSING_DEPENDENCY', `Cannot resolve ${JSON.stringify(this.label(from))}: dependency ${JSON.stringify(String(localName))} is not registered.`, { operation: 'resolve', consumer: this.label(from), dependency: localName, path: Object.freeze([this.label(from), String(localName)]) });
+        return target;
+    }
+    registration(id) {
+        return this.#registrationCache.get(id) ?? this.requireRegistration(id);
+    }
+    requireRegistration(id) {
+        const registration = this.entry(id)?.normalized;
+        if (!registration)
+            throw (0, errors_1.libraryError)('DI_BAG_MISSING_REGISTRATION', `Service ${JSON.stringify(this.label(id))} is not registered.`, { bindingId: id });
+        return registration;
+    }
+    label(id) { return (this.#bindingCache.get(id) ?? this.entry(id)?.description)?.label ?? String(id); }
+    withPublicRegistrations(registrations) {
+        return this.withPublicBindings(Object.keys(registrations).map(key => [key, registrations[key]]));
+    }
+    /** Replace ordered slots and prune only unreferenced public replacement history. */
+    withPublicBindings(entries) {
+        if (entries.length === 0)
+            return this;
+        const graph = this.copy();
+        for (const [key, registration] of entries) {
+            const previous = graph.#publicSlots.get(key);
+            if (previous === undefined)
+                graph.#publicOrder = (0, persistent_sequence_1.append)(graph.#publicOrder, { values: [key] });
+            const id = graph.addBinding(String(key), registration);
+            graph.#publicSlots = graph.#publicSlots.set(key, id);
+            graph.#publicReferences = graph.#publicReferences.set(id, 1);
+            if (previous !== undefined) {
+                const remaining = (graph.#publicReferences.get(previous) ?? 1) - 1;
+                if (remaining)
+                    graph.#publicReferences = graph.#publicReferences.set(previous, remaining);
+                else {
+                    graph.#publicReferences = graph.#publicReferences.delete(previous);
+                    graph.#obsolete = graph.#obsolete.set(previous, true);
+                    graph.prune([previous]);
+                }
+            }
+        }
+        return graph;
+    }
+    withPublicBinding(key, registration) {
+        return this.withPublicBindings([[key, registration]]);
+    }
+    releaseLexical(entry, pending) {
+        const lexical = entry.lexical;
+        if (!lexical)
+            return;
+        const remaining = this.#lexicalUsers.get(lexical.id) - 1;
+        if (remaining) {
+            this.#lexicalUsers = this.#lexicalUsers.set(lexical.id, remaining);
+            return;
+        }
+        this.#lexicalUsers = this.#lexicalUsers.delete(lexical.id);
+        for (const id of lexical.privateIds) {
+            const count = this.#privateReferences.get(id) - 1;
+            if (count)
+                this.#privateReferences = this.#privateReferences.set(id, count);
+            else {
+                this.#privateReferences = this.#privateReferences.delete(id);
+                pending.push(id);
+            }
+        }
+    }
+    /** No recursion or graph-wide scan, even when losing a snapshot unlocks a chain. */
+    prune(pending) {
+        while (pending.length) {
+            const id = pending.pop();
+            if (!this.#obsolete.has(id) || this.#publicReferences.has(id) || this.#privateReferences.has(id) || this.#contributed.has(id))
+                continue;
+            const entry = this.#bindings.get(id);
+            this.#bindings = this.#bindings.delete(id);
+            this.#obsolete = this.#obsolete.delete(id);
+            if (entry)
+                this.releaseLexical(entry, pending);
+        }
+    }
+    /**
+     * Snapshot every retained binding for sealing into a module. Public bindings
+     * come first in declaration order, then contributions in their group order,
+     * then any privately retained binding. Nothing beyond the graph's own storage
+     * is kept to produce this order.
+     */
+    describe() {
+        const bindings = new Map();
+        const seen = new Set();
+        const take = (id) => {
+            if (bindings.has(id))
+                return;
+            const entry = this.#bindings.get(id);
+            if (entry)
+                bindings.set(id, entry.description);
+        };
+        if (this.#publicOrder)
+            for (const key of (0, persistent_sequence_1.materialize)(this.#publicOrder)) {
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const id = this.#publicSlots.get(key);
+                if (id !== undefined)
+                    take(id);
+            }
+        const contributions = new Map();
+        for (const [key, sequence] of this.#contributions) {
+            const ids = (0, persistent_sequence_1.materialize)(sequence);
+            contributions.set(key, ids);
+            for (const id of ids)
+                take(id);
+        }
+        for (const [id] of this.#bindings)
+            take(id);
+        const publicSlots = new Map();
+        for (const [key, id] of this.#publicSlots)
+            publicSlots.set(key, id);
+        return { bindings, publicSlots, contributions };
+    }
+    /** Install disjoint public slots atomically, retaining lexical private refs. */
+    withInstallation(description) {
+        for (const key of description.publicSlots.keys()) {
+            if (this.hasPublic(key))
+                throw (0, errors_1.libraryError)('DI_BAG_DUPLICATE_REGISTRATION', `duplicate registration: ${String(key)}`, { operation: 'installModule', key });
+        }
+        const installation = new BindingGraph(description);
+        const graph = this.copy();
+        const pending = [];
+        // Publish all incoming protection before releasing overwritten descriptions.
+        for (const [id, count] of installation.#lexicalUsers)
+            graph.#lexicalUsers = graph.#lexicalUsers.set(id, count);
+        for (const [id, count] of installation.#privateReferences)
+            graph.#privateReferences = graph.#privateReferences.set(id, (graph.#privateReferences.get(id) ?? 0) + count);
+        for (const [id] of installation.#contributed)
+            graph.#contributed = graph.#contributed.set(id, true);
+        for (const [key, id] of installation.#publicSlots) {
+            graph.#publicOrder = (0, persistent_sequence_1.append)(graph.#publicOrder, { values: [key] });
+            graph.#publicSlots = graph.#publicSlots.set(key, id);
+        }
+        for (const [id, count] of installation.#publicReferences)
+            graph.#publicReferences = graph.#publicReferences.set(id, (graph.#publicReferences.get(id) ?? 0) + count);
+        for (const [id, entry] of installation.#bindings) {
+            const previous = graph.#bindings.get(id);
+            if (previous)
+                graph.releaseLexical(previous, pending);
+            graph.#bindings = graph.#bindings.set(id, entry);
+            graph.#obsolete = graph.#obsolete.delete(id);
+        }
+        for (const [key, sequence] of installation.#contributions)
+            graph.#contributions = graph.#contributions.set(key, (0, persistent_sequence_1.append)(graph.#contributions.get(key), sequence));
+        graph.prune(pending);
+        return graph;
+    }
+}
+exports.BindingGraph = BindingGraph;
+/** Each runtime owns its acquisitions; immutable descriptions remain reusable. */
+class BagRuntime {
+    graph;
+    context;
+    detach;
+    parentAcquisitions;
+    acquisitions;
+    children = new Set();
+    closing;
+    state = 'open';
+    constructor(graph, context, detach = undefined, parentAcquisitions, shared = []) {
+        this.graph = graph;
+        this.context = context;
+        this.detach = detach;
+        this.parentAcquisitions = parentAcquisitions;
+        graph.preflight(context);
+        this.acquisitions = new acquisition_1.ScopeAcquisitions(graph, context, parentAcquisitions, shared);
+        this.observeScope('scope-opened');
+    }
+    resolve(key) {
+        return this.acquisitions.resolve(key);
+    }
+    resolveAll(key) { return this.acquisitions.resolveAll(key); }
+    inspectAll(key) {
+        return Object.freeze(this.graph.contributionBindings(key).map(bindingId => this.inspectBinding(bindingId)));
+    }
+    acquire(key) {
+        return this.acquisitions.acquire(key);
+    }
+    isTransient(key) {
+        return this.acquisitions.isTransient(this.graph.publicBinding(key));
+    }
+    inspect(key) {
+        return this.inspectBinding(this.graph.publicBinding(key));
+    }
+    inspectBinding(bindingId) {
+        return Object.freeze({
+            bindingId,
+            label: this.graph.label(bindingId),
+            ...this.acquisitions.inspectDescription(bindingId),
+            acquisitions: this.acquisitions.inspect(bindingId),
+        });
+    }
+    assertOpen() {
+        if (this.state !== 'open')
+            throw (0, errors_1.libraryError)(this.state === 'closing' ? 'DI_BAG_CLOSING' : 'DI_BAG_CLOSED', `bag is ${this.state}`, { state: this.state });
+        this.acquisitions.assertOpen();
+    }
+    scope(graph = this.graph, shared = []) {
+        this.assertOpen();
+        let child;
+        child = new BagRuntime(graph, this.context, () => { this.children.delete(child); }, this.acquisitions, shared);
+        this.children.add(child);
+        return child;
+    }
+    close(cause) {
+        if (this.closing)
+            return this.closing;
+        let fulfill;
+        let reject;
+        const closing = new Promise((resolve, fail) => { fulfill = resolve; reject = fail; });
+        // Publish before recursively closing children or starting local cleanup.
+        this.closing = closing;
+        this.state = 'closing';
+        this.observeScope('scope-closing');
+        const childClosing = [...this.children].map(child => {
+            try {
+                return child.close(cause);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+        });
+        const childResults = Promise.allSettled(childClosing);
+        let localClosing;
+        try {
+            localClosing = this.acquisitions.close(childClosing.length > 0 ? childResults.then(() => undefined) : undefined, cause);
+        }
+        catch (error) {
+            localClosing = Promise.reject(error);
+        }
+        void this.finishClose(childResults, localClosing).then(() => { this.state = 'closed'; fulfill(); this.observeScope('scope-closed'); }, error => { this.state = 'closed'; reject(error); this.observeScope('scope-close-failed', error); });
+        const detach = this.detach;
+        this.detach = undefined;
+        if (detach)
+            void closing.then(() => { detach(); }, () => { detach(); });
+        return closing;
+    }
+    observeScope(kind, error) {
+        if (!this.context.observers)
+            return;
+        const fields = {
+            scopeId: this.acquisitions.ownerId,
+            ...(this.parentAcquisitions ? { parentScopeId: this.parentAcquisitions.ownerId } : {}),
+        };
+        this.context.observers.emit(kind === 'scope-close-failed' ? { ...fields, kind, error } : { ...fields, kind });
+    }
+    async finishClose(childResults, localClosing) {
+        const [children, local] = await Promise.all([
+            childResults,
+            localClosing.then(() => ({ status: 'fulfilled', value: undefined }), reason => ({ status: 'rejected', reason })),
+        ]);
+        const failures = [];
+        const unexpected = [];
+        for (const result of [...children, local]) {
+            if (result.status === 'fulfilled')
+                continue;
+            if (result.reason instanceof errors_2.DiBagCleanupError)
+                failures.push(...result.reason.failures);
+            else
+                unexpected.push(result.reason);
+        }
+        if (unexpected.length > 0) {
+            const errors = failures.length > 0
+                ? [new errors_2.DiBagCleanupError(failures), ...unexpected]
+                : unexpected;
+            throw (0, errors_1.diagnostic)(new AggregateError(errors, `Failed to close ${errors.length} runtime operation(s)`), 'DI_BAG_CLOSE_FAILED', { operation: 'close', failedOperations: errors.length });
+        }
+        if (failures.length > 0)
+            throw new errors_2.DiBagCleanupError(failures);
+    }
+}
+exports.BagRuntime = BagRuntime;

package/dist/scope-selection.d.ts

@@ -0,0 +1,6 @@
+import type { BindingGraph, BindingKey, BindingId } from './runtime';
+/** Validate both selections before reading any override value or building a graph. */
+export declare function selectScope(graph: BindingGraph, args: readonly unknown[], isTransient: (key: BindingKey) => boolean): {
+    readonly graph: BindingGraph;
+    readonly shared: readonly BindingId[];
+};

package/dist/scope-selection.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectScope = selectScope;
+const errors_1 = require("./errors");
+const registration_1 = require("./registration");
+const tokens_1 = require("./tokens");
+function snapshot(selection) {
+    if (!Array.isArray(selection))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_SCOPE', 'createScope requires a selected key array', { operation: 'createScope' });
+    const values = [];
+    const length = selection.length;
+    for (let index = 0; index < length; index++)
+        values.push(selection[index]);
+    return values.map(value => typeof value === 'string' ? value : (0, tokens_1.readTokenKey)(value));
+}
+/** Validate both selections before reading any override value or building a graph. */
+function selectScope(graph, args, isTransient) {
+    if (args.length === 0)
+        return { graph, shared: [] };
+    if (args.length > 3)
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_SCOPE', 'createScope accepts sharing options or selected keys, overrides and optional sharing options', { operation: 'createScope' });
+    const hasOverrides = args.length >= 2;
+    const selected = hasOverrides ? snapshot(args[0]) : [];
+    const overrides = hasOverrides ? args[1] : undefined;
+    if (hasOverrides && (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides))) {
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_SCOPE', 'createScope requires an override object', { operation: 'createScope' });
+    }
+    const options = hasOverrides ? args[2] : args[0];
+    let shareKeys = [];
+    if (options !== undefined || !hasOverrides) {
+        if (typeof options !== 'object' || options === null || Array.isArray(options) ||
+            ![Object.prototype, null].includes(Object.getPrototypeOf(options)) ||
+            Reflect.ownKeys(options).some(key => key !== 'share') || !Object.hasOwn(options, 'share')) {
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_SCOPE', 'createScope options require only an own share selection', { operation: 'createScope' });
+        }
+        shareKeys = snapshot(Reflect.get(options, 'share'));
+    }
+    for (const key of [...selected, ...shareKeys]) {
+        if (!graph.hasPublic(key))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_SCOPE', `createScope accepts existing names or typed tokens only: ${String(key)}`, { operation: 'createScope' });
+    }
+    const selectedSet = new Set(selected);
+    const shared = [...new Set(shareKeys)].map(key => {
+        if (selectedSet.has(key))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_SCOPE', `createScope cannot share and override the same token: ${String(key)}`, { operation: 'createScope' });
+        const id = graph.publicBinding(key);
+        if (isTransient(key))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_SCOPE', `createScope cannot share transient providers: ${String(key)}`, { operation: 'createScope' });
+        return id;
+    });
+    for (const key of selectedSet) {
+        if (!Object.hasOwn(overrides, key))
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_SCOPE', `missing createScope override: ${String(key)}`, { operation: 'createScope' });
+    }
+    const bindings = [];
+    for (const key of selectedSet) {
+        const registration = Reflect.get(overrides, key);
+        (0, registration_1.normalize)(registration);
+        bindings.push([key, registration]);
+    }
+    return { graph: graph.withPublicBindings(bindings), shared };
+}

package/dist/scope-types.d.ts

@@ -0,0 +1,58 @@
+import type { CanonicalLifetime } from './lifetime-types';
+import type { Provider, ProviderGraphContract, ProviderFactory, ProviderRegistrationMetadata, ProviderAcquisitionMetadata, ProviderAcquiredValue } from './provider';
+import type { Registration, Registrations } from './registration';
+import type { SelectionKey } from './token-types';
+import type { Selection, Unsatisfied } from './types';
+type Transients<R extends Registrations, S extends readonly unknown[]> = {
+    [K in SelectionKey<S[number]> & keyof R]: 'transient' extends CanonicalLifetime<R, K> ? K : never;
+}[SelectionKey<S[number]> & keyof R];
+/** CheckDependencyCompatibility options for borrowing selected non-transient parent acquisitions in a child scope. */
+export type ScopeOptions<R extends Registrations, S extends readonly unknown[]> = {
+    /** Existing names or tokens to resolve through the parent's acquisition and ownership context. */
+    readonly share: S & Selection<R, S, 'createScope share'> & ([
+        Transients<R, S>
+    ] extends [never] ? unknown : Unsatisfied<'createScope cannot share transient providers', {
+        tokens: Transients<R, S>;
+    }>);
+};
+/** Reject a child-scope key selected for both replacement and parent sharing. */
+export type DisjointScopeSelection<K extends readonly unknown[], S extends readonly unknown[]> = [
+    SelectionKey<K[number]> & SelectionKey<S[number]>
+] extends [never] ? unknown : Unsatisfied<'createScope cannot share and override the same token', {
+    tokens: SelectionKey<K[number]> & SelectionKey<S[number]>;
+}>;
+type SharedKeys<R extends Registrations> = {
+    [K in keyof R]: ProviderGraphContract<R[K]> extends {
+        readonly sharedAlias: unknown;
+    } ? K : never;
+}[keyof R];
+type Unshared<V extends Registration> = ProviderGraphContract<V> extends {
+    readonly sharedAlias: {
+        readonly original: infer O extends Registration;
+    };
+} ? O : V;
+/** Remove parent-sharing routes when creating a fresh scope or independent fork. */
+export type UnsharedAliases<R extends Registrations> = [SharedKeys<R>] extends [never] ? R : Omit<R, SharedKeys<R>> & {
+    [K in SharedKeys<R>]: Unshared<R[K]>;
+};
+type AliasKeys<R extends Registrations, S extends readonly unknown[]> = {
+    [K in SelectionKey<S[number]> & keyof R]: ProviderGraphContract<R[K]> extends {
+        readonly alias: PropertyKey;
+    } ? K : never;
+}[SelectionKey<S[number]> & keyof R];
+type SharedAlias<R extends Registrations, Parent extends Registrations, K extends keyof R> = Provider<ProviderFactory<R[K]>, ProviderRegistrationMetadata<R[K]> & object, ProviderAcquisitionMetadata<R[K]>, ProviderGraphContract<R[K]> & {
+    readonly sharedAlias: {
+        readonly registrations: Parent;
+        readonly source: K;
+        readonly original: R[K];
+    };
+}, ProviderAcquiredValue<R[K]>>;
+/** Named mapping keeps reflected package declarations inside this checked generic boundary. */
+export type SharedAliasProviders<R extends Registrations, Parent extends Registrations, S extends readonly unknown[]> = [
+    AliasKeys<R, S>
+] extends [never] ? R : Omit<R, AliasKeys<R, S>> & {
+    [K in AliasKeys<R, S>]: SharedAlias<R, Parent, K>;
+};
+/** The registration map visible in a child after clearing and applying selected sharing routes. */
+export type ScopedAliases<R extends Registrations, Parent extends Registrations, S extends readonly unknown[]> = SharedAliasProviders<UnsharedAliases<R>, Parent, S>;
+export {};

package/dist/scope-types.js

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

package/dist/startup.d.ts

@@ -0,0 +1,14 @@
+import { BagRuntime } from './runtime';
+import type { BindingGraph } from './runtime';
+import type { RuntimeContext } from './acquisition-mode';
+/** Controls eager acquisition performed by {@link Builder.buildAndStart}. */
+export interface StartupOptions {
+    /** An external signal that promptly cancels the startup wait and begins cleanup. */
+    readonly signal?: AbortSignal;
+    /** A finite positive deadline in milliseconds. */
+    readonly timeoutMs?: number;
+    /** Start together (`parallel`, default), in tuple order (`sequential`), or with a positive safe integer bound on selected readiness waits. Dependency fanout is not bounded. */
+    readonly startupOrder?: 'parallel' | 'sequential' | number;
+}
+/** One startup transaction; never assimilate an exposed service to establish readiness. */
+export declare function startRuntime(graph: BindingGraph, context: RuntimeContext, keys: readonly unknown[], options?: StartupOptions): Promise<BagRuntime>;