di-bag 0.1.0

package/dist/persistent-map.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistentMap = void 0;
+// Registered symbols cannot be weak keys. Hash their registry strings; local and
+// well-known symbols use collectible identities where the host supports them.
+const symbolHashes = new WeakMap();
+let nextSymbolHash = 0;
+const weakSymbols = (() => {
+    try {
+        symbolHashes.set(Symbol(), 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+})();
+function stringHash(key) {
+    let hash = 2166136261;
+    for (let i = 0; i < key.length; i++)
+        hash = Math.imul(hash ^ key.charCodeAt(i), 16777619);
+    return hash >>> 0;
+}
+function hashKey(key) {
+    if (typeof key === 'string')
+        return stringHash(key);
+    const registered = Symbol.keyFor(key);
+    if (registered !== undefined)
+        return stringHash(registered);
+    if (!weakSymbols)
+        return stringHash(String(key));
+    const weakKey = key;
+    let hash = symbolHashes.get(weakKey);
+    if (hash === undefined) {
+        hash = nextSymbolHash = (nextSymbolHash + 1) >>> 0;
+        symbolHashes.set(weakKey, hash);
+    }
+    return hash;
+}
+function index(bitmap, bit) {
+    let bits = bitmap & (bit - 1);
+    bits -= (bits >>> 1) & 0x5555;
+    bits = (bits & 0x3333) + ((bits >>> 2) & 0x3333);
+    return (((bits + (bits >>> 4)) & 0x0f0f) * 0x0101 >>> 8) & 0xff;
+}
+function join(left, right, shift) {
+    if (left.hash === right.hash)
+        return { kind: 'collision', hash: right.hash, entries: left.kind === 'leaf' ? [left, right] : [...left.entries, right] };
+    const a = (left.hash >>> shift) & 15, b = (right.hash >>> shift) & 15;
+    return a === b
+        ? { kind: 'branch', bitmap: 1 << a, children: [join(left, right, shift + 4)] }
+        : { kind: 'branch', bitmap: (1 << a) | (1 << b), children: a < b ? [left, right] : [right, left] };
+}
+function put(node, leaf, shift) {
+    if (!node)
+        return leaf;
+    if (node.kind === 'leaf')
+        return node.key === leaf.key ? leaf : join(node, leaf, shift);
+    if (node.kind === 'collision') {
+        if (node.hash !== leaf.hash)
+            return join(node, leaf, shift);
+        const at = node.entries.findIndex(entry => entry.key === leaf.key);
+        if (at < 0)
+            return { ...node, entries: [...node.entries, leaf] };
+        const entries = node.entries.slice();
+        entries[at] = leaf;
+        return { ...node, entries };
+    }
+    const bit = 1 << ((leaf.hash >>> shift) & 15), at = index(node.bitmap, bit);
+    const children = node.children.slice();
+    if (node.bitmap & bit)
+        children[at] = put(children[at], leaf, shift + 4);
+    else
+        children.splice(at, 0, leaf);
+    return { kind: 'branch', bitmap: node.bitmap | bit, children };
+}
+function remove(node, key, hash, shift) {
+    if (!node)
+        return undefined;
+    if (node.kind === 'leaf')
+        return node.key === key ? undefined : node;
+    if (node.kind === 'collision') {
+        const at = node.entries.findIndex(entry => entry.key === key);
+        if (at < 0)
+            return node;
+        const entries = node.entries.slice();
+        entries.splice(at, 1);
+        return entries.length === 1 ? entries[0] : { ...node, entries };
+    }
+    const bit = 1 << ((hash >>> shift) & 15);
+    if (!(node.bitmap & bit))
+        return node;
+    const at = index(node.bitmap, bit), previous = node.children[at];
+    const child = remove(previous, key, hash, shift + 4);
+    if (child === previous)
+        return node;
+    const children = node.children.slice();
+    if (child)
+        children[at] = child;
+    else
+        children.splice(at, 1);
+    if (children.length === 0)
+        return undefined;
+    // A branch cannot move up: its bitmap describes a particular hash nibble.
+    if (children.length === 1 && children[0].kind !== 'branch')
+        return children[0];
+    return { kind: 'branch', bitmap: child ? node.bitmap : node.bitmap & ~bit, children };
+}
+class PersistentMap {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    get(key) {
+        const hash = hashKey(key);
+        let node = this.root, shift = 0;
+        while (node?.kind === 'branch') {
+            const bit = 1 << ((hash >>> shift) & 15);
+            if (!(node.bitmap & bit))
+                return undefined;
+            node = node.children[index(node.bitmap, bit)];
+            shift += 4;
+        }
+        if (node?.kind === 'leaf')
+            return node.key === key ? node.value : undefined;
+        return node?.entries.find(entry => entry.key === key)?.value;
+    }
+    has(key) { return this.get(key) !== undefined; }
+    set(key, value) {
+        return new PersistentMap(put(this.root, { kind: 'leaf', key, hash: hashKey(key), value }, 0));
+    }
+    delete(key) { return new PersistentMap(remove(this.root, key, hashKey(key), 0)); }
+    *[Symbol.iterator]() {
+        const stack = this.root ? [this.root] : [];
+        while (stack.length) {
+            const node = stack.pop();
+            if (node.kind === 'branch')
+                stack.push(...node.children);
+            else if (node.kind === 'collision')
+                for (const entry of node.entries)
+                    yield [entry.key, entry.value];
+            else
+                yield [node.key, node.value];
+        }
+    }
+}
+exports.PersistentMap = PersistentMap;

package/dist/persistent-sequence.d.ts

@@ -0,0 +1,9 @@
+/** Append/concat nodes contain no version-specific materialization cache. */
+export type Sequence<T> = {
+    readonly values: readonly T[];
+} | {
+    readonly left: Sequence<T>;
+    readonly right: Sequence<T>;
+};
+export declare function append<T>(previous: Sequence<T> | undefined, next: Sequence<T>): Sequence<T>;
+export declare function materialize<T>(sequence: Sequence<T>): readonly T[];

package/dist/persistent-sequence.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.append = append;
+exports.materialize = materialize;
+function append(previous, next) {
+    return previous ? { left: previous, right: next } : next;
+}
+function materialize(sequence) {
+    const values = [], stack = [sequence];
+    while (stack.length) {
+        const node = stack.pop();
+        if ('values' in node)
+            for (const value of node.values)
+                values.push(value);
+        else {
+            stack.push(node.right, node.left);
+        }
+    }
+    return Object.freeze(values);
+}

package/dist/plugins.d.ts

@@ -0,0 +1,32 @@
+import type { DependencyReference } from './dependency-references';
+import type { Provider } from './provider';
+import type { DependencyTupleAdmission, ReferenceGraph } from './token-types';
+/** The explicit output boundary used for an application-selected plugin. */
+export type PluginAcquisitionMode = 'raw' | 'nativePromise';
+/** A synchronous predicate that admits an unknown plugin output as a service type. */
+export type PluginOutputValidator<V> = (this: void, value: unknown) => value is V;
+/** Validation and acquisition choices for {@link DiBagApi.fromPlugin}. */
+export interface PluginOptions<M extends PluginAcquisitionMode, V> {
+    /** Preserve the exact result with `raw`, or await a genuine native Promise with `nativePromise`. */
+    readonly acquisitionMode: M;
+    /** Must synchronously return exactly `true` for acceptable output values. */
+    readonly validate: PluginOutputValidator<V>;
+}
+/** The provider contract produced by {@link DiBagApi.fromPlugin}. */
+export type PluginProvider<T extends readonly DependencyReference[], V, M extends PluginAcquisitionMode> = Provider<() => M extends 'raw' ? V : Promise<Awaited<V>>, Readonly<{}>, readonly [], ReferenceGraph<T>, M extends 'raw' ? V : Awaited<V>>;
+/**
+ * Callable checked plugin adapter exposed by DiBag.fromPlugin.
+ * The descriptor must have own `apiVersion: 1` and callable `create`, with an optional
+ * callable `dispose`. A disposer owns the original acquired value before validation.
+ * The named call signature keeps extracted methods nameable in consumer declarations.
+ * @param dependencies - Host values supplied to the plugin in positional order.
+ * @param plugin - The application-selected unknown descriptor.
+ * @param options - Required raw/nativePromise acquisition and a synchronous output predicate.
+ * @returns A lazy provider that validates its output when acquired.
+ * @throws {@link DiBagPluginValidationError} for an invalid descriptor or rejected output.
+ * @typeParam T - The exact positional dependency-reference tuple.
+ * @typeParam V - The service admitted by the synchronous output validator.
+ * @typeParam M - The raw or nativePromise plugin acquisition policy.
+ */
+export type PluginProviderFactory = <const T extends readonly DependencyReference[], V, M extends PluginAcquisitionMode>(dependencies: T & DependencyTupleAdmission<T>, plugin: unknown, options: PluginOptions<M, V>) => PluginProvider<T, V, M>;
+export declare const fromPlugin: PluginProviderFactory;

package/dist/plugins.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromPlugin = void 0;
+const errors_1 = require("./errors");
+const dependency_references_1 = require("./dependency-references");
+const errors_2 = require("./errors");
+const provider_1 = require("./provider");
+const provider_operations_1 = require("./provider-operations");
+function invalidDescriptor(reason) {
+    return new errors_2.DiBagPluginValidationError('descriptor', reason);
+}
+function validateOptions(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_PLUGIN_OPTIONS', 'fromPlugin requires acquisitionMode and validate options', { operation: 'fromPlugin' });
+    }
+    if (!Object.hasOwn(value, 'acquisitionMode'))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_PLUGIN_OPTIONS', 'fromPlugin requires acquisitionMode', { operation: 'fromPlugin' });
+    const acquisitionMode = Reflect.get(value, 'acquisitionMode');
+    if (acquisitionMode !== 'raw' && acquisitionMode !== 'nativePromise')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_PLUGIN_OPTIONS', 'fromPlugin acquisitionMode must be raw or nativePromise', { operation: 'fromPlugin' });
+    if (!Object.hasOwn(value, 'validate'))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_PLUGIN_OPTIONS', 'fromPlugin requires a validation predicate', { operation: 'fromPlugin' });
+    const validate = Reflect.get(value, 'validate');
+    if (typeof validate !== 'function')
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_PLUGIN_OPTIONS', 'fromPlugin validate must be a function', { operation: 'fromPlugin' });
+    return Object.freeze({ acquisitionMode, validate: validate });
+}
+function validateDescriptor(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw invalidDescriptor('plugin descriptor must be a non-array object');
+    }
+    if (!Object.hasOwn(value, 'apiVersion'))
+        throw invalidDescriptor('plugin descriptor requires own apiVersion');
+    if (Reflect.get(value, 'apiVersion') !== 1)
+        throw invalidDescriptor('plugin apiVersion must be 1');
+    if (!Object.hasOwn(value, 'create'))
+        throw invalidDescriptor('plugin descriptor requires own create');
+    const create = Reflect.get(value, 'create');
+    if (typeof create !== 'function')
+        throw invalidDescriptor('plugin create must be a function');
+    if (!Object.hasOwn(value, 'dispose'))
+        return Object.freeze({ apiVersion: 1, create });
+    const dispose = Reflect.get(value, 'dispose');
+    if (typeof dispose !== 'function')
+        throw invalidDescriptor('plugin dispose must be a function when present');
+    return Object.freeze({ apiVersion: 1, create, dispose });
+}
+/**
+ * Validate an unknown plugin descriptor and its output at a declared dependency boundary.
+ * The descriptor must have own `apiVersion: 1` and callable `create`, with an optional
+ * callable `dispose`. A disposer owns the original acquired value before validation.
+ * @param dependencies - Host values supplied to the plugin in positional order.
+ * @param plugin - The application-selected unknown descriptor.
+ * @param options - Required raw/nativePromise acquisition and a synchronous output predicate.
+ * @returns A lazy provider that validates its output when acquired.
+ * @throws {@link DiBagPluginValidationError} for an invalid descriptor or rejected output.
+ */
+function createPluginProvider(dependencies, plugin, options) {
+    const references = (0, dependency_references_1.snapshotReferences)(dependencies);
+    const selected = validateOptions(options);
+    const descriptor = validateDescriptor(plugin);
+    const create = (deps) => Reflect.apply(descriptor.create, undefined, references.map(reference => Reflect.get(deps, reference.slot)));
+    const dispose = descriptor.dispose === undefined ? undefined : (value) => Reflect.apply(descriptor.dispose, undefined, [value]);
+    const project = (value) => {
+        if (Reflect.apply(selected.validate, undefined, [value]) !== true) {
+            throw new errors_2.DiBagPluginValidationError('output', 'plugin output failed validation');
+        }
+        return value;
+    };
+    if (selected.acquisitionMode === 'raw') {
+        const source = (0, provider_1.createProvider)();
+        (0, provider_operations_1.retainDescription)(source, (0, provider_operations_1.sourceDescription)(create, dispose, references.map(reference => reference.key), 'raw', false, references));
+        return (0, provider_1.transformService)(source, { mode: 'direct', transform: project, acquisitionMode: 'raw' });
+    }
+    const source = (0, provider_1.createProvider)();
+    (0, provider_operations_1.retainDescription)(source, (0, provider_operations_1.sourceDescription)(create, dispose, references.map(reference => reference.key), 'nativePromise', false, references));
+    return (0, provider_1.transformService)(source, { mode: 'awaited', transform: project });
+}
+// Both signatures retain the same tuple admission and invariant provider result.
+// Generic assignability otherwise re-infers T as T & DependencyTupleAdmission<T>,
+// applying admission twice. Name the public callable without widening either contract.
+exports.fromPlugin = createPluginProvider;

package/dist/provider-execution.d.ts

@@ -0,0 +1,59 @@
+import type { normalize } from './provider-operations';
+import type { AcquisitionMetadataPresence } from './inspection';
+import type { RuntimeContext } from './acquisition-mode';
+import type { AcquisitionContext } from './acquisition-context';
+type RegistrationDescription = ReturnType<typeof normalize>;
+interface ExecutionEvents {
+    accepted(): void;
+    settled(): void;
+    drained(): void;
+    invoking(): number;
+    cleanupStarted?(): void;
+    cleanupCompleted?(outcome: 'success' | 'failure'): void;
+    cleanupFailed(sequence: number, error: unknown): void;
+}
+/** Fully drained borrowed attempts keep frames, but no execution closures or payloads. */
+export declare class CompletedExecution {
+    private frames;
+    readonly state = "ready";
+    readonly sourceInFlight = false;
+    readonly hasOwnership = false;
+    readonly error: undefined;
+    readonly work: readonly Promise<void>[];
+    constructor(frames: AcquisitionMetadataPresence<readonly unknown[]>);
+    inspectFrames(): AcquisitionMetadataPresence<readonly unknown[]>;
+    ready(): Promise<void>;
+    dispose(): Promise<void>;
+    release(): void;
+}
+/** One source invocation and its ordered projections/ownership, local to an attempt. */
+export declare class ProviderExecution {
+    private readonly events;
+    private readonly context;
+    private readonly frames;
+    private readonly stages;
+    private readonly pending;
+    private result;
+    private cleaning;
+    sourceInFlight: boolean;
+    constructor(events: ExecutionEvents, description: RegistrationDescription, context: RuntimeContext);
+    inspectFrames(): AcquisitionMetadataPresence<readonly unknown[]>;
+    get state(): 'pending' | 'ready' | 'failed';
+    get error(): unknown;
+    get hasOwnership(): boolean;
+    get work(): readonly Promise<void>[];
+    /** Observe the selected stage, retaining its failure even after retirement. */
+    ready(): Promise<void>;
+    compact(): ProviderExecution | CompletedExecution;
+    /** Classify/own only after the direct operation-free source call has returned. */
+    publishSource(value: unknown, description: RegistrationDescription): void;
+    evaluate(description: RegistrationDescription, deps: unknown, acquisitionContext: () => AcquisitionContext): unknown;
+    private consume;
+    private capture;
+    private own;
+    private accept;
+    dispose(): Promise<void>;
+    private disposeStages;
+    release(): void;
+}
+export {};

package/dist/provider-execution.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderExecution = exports.CompletedExecution = void 0;
+const errors_1 = require("./errors");
+const observePromise = (Promise.prototype.then);
+const emptyFrames = Object.freeze([]);
+const emptyWork = Object.freeze([]);
+/** Fully drained borrowed attempts keep frames, but no execution closures or payloads. */
+class CompletedExecution {
+    frames;
+    state = 'ready';
+    sourceInFlight = false;
+    hasOwnership = false;
+    error = undefined;
+    work = emptyWork;
+    constructor(frames) {
+        this.frames = frames;
+    }
+    inspectFrames() { return Object.freeze([...this.frames]); }
+    async ready() { }
+    async dispose() { }
+    release() {
+        // Frame-bearing records belong to one attempt; the shared empty record is
+        // never mutated. Inspection arrays already returned to callers stay intact.
+        if (this.frames.length)
+            this.frames = emptyFrames;
+    }
+}
+exports.CompletedExecution = CompletedExecution;
+const completedWithoutFrames = new CompletedExecution(emptyFrames);
+/** One source invocation and its ordered projections/ownership, local to an attempt. */
+class ProviderExecution {
+    events;
+    context;
+    frames;
+    stages = [];
+    pending = new Set();
+    result;
+    cleaning;
+    // Source permission is independent of the exposed projection's cache state.
+    sourceInFlight = true;
+    constructor(events, description, context) {
+        this.events = events;
+        this.context = context;
+        // Reserve every metadata frame before the source can reenter inspection.
+        this.frames = description.operations.filter(operation => operation.kind === 'frame-sync' || operation.kind === 'frame-async')
+            .map(() => Object.freeze({ present: false }));
+    }
+    inspectFrames() { return Object.freeze([...this.frames]); }
+    get state() { return this.result?.state ?? 'failed'; }
+    get error() { return this.result?.error; }
+    get hasOwnership() { return this.stages.length > 0; }
+    get work() { return [...this.pending]; }
+    /** Observe the selected stage, retaining its failure even after retirement. */
+    async ready() {
+        const result = this.result;
+        if (!result)
+            throw (0, errors_1.libraryError)('DI_BAG_INTERNAL_STATE', 'acquisition has no result', {});
+        if (result.state === 'pending')
+            await result.settled;
+        if (result.state === 'failed')
+            throw result.error;
+    }
+    compact() {
+        if (this.state !== 'ready' || this.pending.size || this.hasOwnership)
+            return this;
+        return this.frames.length ? new CompletedExecution(this.inspectFrames()) : completedWithoutFrames;
+    }
+    /** Classify/own only after the direct operation-free source call has returned. */
+    publishSource(value, description) {
+        if (description.acquisitionMode === 'raw') {
+            this.sourceInFlight = false;
+            this.result = { exposed: undefined, consumed: true, state: 'ready', value: undefined, error: undefined, owners: [] };
+            if (description.dispose)
+                this.accept(0, value, description.dispose);
+            return;
+        }
+        const stage = this.capture(() => value, true, description.acquisitionMode);
+        if (description.dispose)
+            this.own(stage, 0, description.dispose);
+        this.result = stage;
+        this.consume(stage);
+        if (stage.state === 'failed')
+            throw stage.error;
+    }
+    evaluate(description, deps, acquisitionContext) {
+        const { create, dispose } = description;
+        let current = this.capture(() => description.contextual
+            ? Reflect.apply(create, undefined, [deps, acquisitionContext()])
+            : create(deps), true, description.acquisitionMode);
+        let nextFrame = 0;
+        if (dispose)
+            this.own(current, 0, dispose);
+        description.operations.forEach((operation, offset) => {
+            const inputStage = current;
+            const index = offset + 1;
+            if (operation.kind === 'owned') {
+                this.own(current, index, operation.dispose);
+            }
+            else if (operation.kind === 'map-sync') {
+                if (current.state !== 'failed') {
+                    const input = current.exposed;
+                    const { project } = operation;
+                    current = this.capture(() => project(input), false, operation.acquisitionMode);
+                }
+            }
+            else if (operation.kind === 'map-async') {
+                const input = current;
+                const { project } = operation;
+                current = this.capture(async () => {
+                    if (input.state === 'failed')
+                        throw input.error;
+                    return project(await input.exposed);
+                }, false, 'nativePromise');
+            }
+            else if (operation.kind === 'frame-sync' || operation.kind === 'frame-async') {
+                const frameIndex = nextFrame++;
+                const input = current;
+                const { project } = operation;
+                const apply = (value) => {
+                    const projected = project(value);
+                    this.frames[frameIndex] = Object.freeze({ present: true, value: projected.frame });
+                    return projected.value;
+                };
+                if (operation.kind === 'frame-async') {
+                    current = this.capture(async () => {
+                        if (input.state === 'failed')
+                            throw input.error;
+                        return apply(await input.exposed);
+                    }, false, 'nativePromise');
+                }
+                else if (input.state !== 'failed') {
+                    current = this.capture(() => apply(input.exposed), false, operation.acquisitionMode);
+                }
+            }
+            if (current !== inputStage)
+                this.consume(inputStage);
+        });
+        this.result = current;
+        if (current.state === 'failed')
+            throw current.error;
+        const exposed = current.exposed;
+        this.consume(current);
+        return exposed;
+    }
+    consume(stage) {
+        // Projections have captured their input and ownership has its own value.
+        // Pending callbacks still accept ownership, but must not retain fulfillment.
+        stage.consumed = true;
+        stage.exposed = undefined;
+        stage.value = undefined;
+    }
+    capture(create, source, mode) {
+        try {
+            const exposed = create();
+            const stage = { exposed, consumed: false, state: 'ready', value: exposed, error: undefined, owners: [] };
+            let native = mode === 'nativePromise';
+            if (mode === 'auto') {
+                const { isNativePromise } = this.context;
+                // Whole-graph preflight establishes capability before invoking this factory.
+                const classified = isNativePromise(exposed);
+                if (typeof classified !== 'boolean')
+                    throw (0, errors_1.libraryError)('DI_BAG_INVALID_CLASSIFIER_RESULT', 'isNativePromise must return a boolean', { option: 'isNativePromise', provided: classified });
+                native = classified;
+            }
+            if (mode !== 'raw' && exposed !== null && (typeof exposed === 'object' || typeof exposed === 'function') && 'then' in exposed) {
+                // Preserve original getter failures, but never use callability as native branding.
+                const then = Reflect.get(exposed, 'then');
+                if (!native && typeof then === 'function')
+                    throw (0, errors_1.libraryTypeError)('DI_BAG_STRUCTURAL_THENABLE', 'Structural thenables require explicit native Promise conversion or raw acquisitionMode', { acquisitionMode: mode });
+            }
+            if (native) {
+                let settled;
+                const barrier = new Promise(resolve => { settled = resolve; });
+                // The species result is untrusted; only our independently made barrier
+                // participates in draining. No structural assimilation or error fallback.
+                observePromise.call(exposed, value => {
+                    stage.state = 'ready';
+                    if (!stage.consumed)
+                        stage.value = value;
+                    for (const owner of stage.owners)
+                        this.accept(owner.index, value, owner.dispose);
+                    stage.owners.length = 0;
+                    finish();
+                }, error => {
+                    stage.state = 'failed';
+                    stage.error = error;
+                    stage.owners.length = 0;
+                    finish();
+                });
+                stage.state = 'pending';
+                stage.value = undefined;
+                stage.settled = barrier;
+                this.pending.add(barrier);
+                const finish = () => {
+                    if (source)
+                        this.sourceInFlight = false;
+                    this.pending.delete(barrier);
+                    settled();
+                    if (this.result === stage)
+                        this.events.settled();
+                    if (!this.pending.size)
+                        this.events.drained();
+                };
+            }
+            else if (source) {
+                this.sourceInFlight = false;
+            }
+            return stage;
+        }
+        catch (error) {
+            if (source)
+                this.sourceInFlight = false;
+            return { exposed: undefined, consumed: true, state: 'failed', value: undefined, error, owners: [] };
+        }
+    }
+    own(stage, index, dispose) {
+        if (stage.state === 'ready')
+            this.accept(index, stage.value, dispose);
+        else if (stage.state === 'pending')
+            stage.owners.push({ index, dispose });
+    }
+    accept(index, value, dispose) {
+        this.stages.push({ index, value, dispose, state: 'accepted' });
+        this.events.accepted();
+    }
+    dispose() {
+        if (this.cleaning)
+            return this.cleaning;
+        let complete;
+        this.cleaning = new Promise(resolve => { complete = resolve; });
+        // Publish before invoking user code, including synchronous finalizers.
+        void this.disposeStages().then(complete);
+        return this.cleaning;
+    }
+    async disposeStages() {
+        // All later acceptances must be known before reversing stable stage indices.
+        while (this.pending.size)
+            await Promise.all(this.pending);
+        const owned = this.stages.length > 0;
+        let failed = false;
+        if (owned)
+            this.events.cleanupStarted?.();
+        for (const stage of this.stages.sort((a, b) => b.index - a.index)) {
+            stage.state = 'disposing';
+            const sequence = this.events.invoking();
+            const { dispose, value } = stage;
+            try {
+                await dispose(value);
+            }
+            catch (error) {
+                failed = true;
+                this.events.cleanupFailed(sequence, error);
+            }
+            finally {
+                stage.state = 'disposed';
+            }
+        }
+        if (owned)
+            this.events.cleanupCompleted?.(failed ? 'failure' : 'success');
+        this.stages.length = 0;
+        this.result = undefined;
+    }
+    release() {
+        this.frames.length = 0;
+        this.stages.length = 0;
+        this.pending.clear();
+        this.result = undefined;
+    }
+}
+exports.ProviderExecution = ProviderExecution;