@orkestrel/pool 0.0.3 → 0.0.5

package/dist/src/core/index.cjs

@@ -1,255 +1,623 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _orkestrel_emitter = require("@orkestrel/emitter");
+//#region src/core/errors.ts
+/**
+* A stable, machine-readable pool failure with the original cause and structured context.
+*
+* @example
+* ```ts
+* import { PoolError, isPoolError } from '@orkestrel/pool'
+*
+* try {
+* 	await pool.acquire()
+* } catch (error: unknown) {
+* 	if (isPoolError(error)) console.error(error.code, error.cause)
+* }
+* ```
+*/
+var PoolError = class extends Error {
+	/** Stable machine-readable failure category. */
+	code;
+	/** Optional structured input or aggregate-cleanup details. */
+	context;
+	/**
+	* Create a pool failure without coercing a hostile thrown value.
+	*
+	* @param options - Stable code plus optional cause and structured context
+	*/
+	constructor(options) {
+		let message = "pool input is invalid";
+		if (options.code === "destroyed") message = "pool is destroyed";
+		if (options.code === "create") message = "pool create failed";
+		if (options.code === "cleanup") message = "pool cleanup failed";
+		try {
+			if (options.cause instanceof Error && typeof options.cause.message === "string" && options.cause.message.length > 0) message = `${message}: ${options.cause.message}`;
+		} catch {}
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "PoolError";
+		this.code = options.code;
+		this.context = options.context;
+	}
+};
+/**
+* Test whether an unknown value is a {@link PoolError}, returning `false` for hostile proxies.
+*
+* @param value - The unknown boundary value
+* @returns Whether the value is a real `PoolError` instance
+*
+* @example
+* ```ts
+* isPoolError(new PoolError({ code: 'destroyed' })) // true
+* isPoolError(new Error('other')) // false
+* ```
+*/
+function isPoolError(value) {
+	try {
+		return value instanceof PoolError;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/core/validators.ts
+/**
+* Test whether a value is a valid finite pool maximum.
+*
+* @param value - The unknown maximum candidate
+* @returns Whether the value is a positive safe integer
+*
+* @example
+* ```ts
+* isPoolMax(8) // true
+* isPoolMax(Infinity) // false
+* ```
+*/
+function isPoolMax(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+/**
+* Test whether a value is a native `AbortSignal`, returning `false` for hostile proxies.
+*
+* @param value - The unknown signal candidate
+* @returns Whether the value is a native `AbortSignal`
+*
+* @example
+* ```ts
+* isPoolSignal(new AbortController().signal) // true
+* isPoolSignal({ aborted: false }) // false
+* ```
+*/
+function isPoolSignal(value) {
+	try {
+		const getter = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "aborted")?.get;
+		if (getter === void 0) return false;
+		Reflect.apply(getter, value, []);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/core/Pool.ts
 /**
-* A bounded resource pool with idle reuse + FIFO waiting.
+* A capacity-aware resource pool whose opaque ownership records preserve FIFO settlement,
+* cancellation, exact lease release, and deterministic teardown under concurrent hooks.
 *
-* @remarks
-* - **Idle reuse.** `acquire` first takes an idle resource (validating it when a
-*   `validate` hook is set — an invalid one is destroyed and the next idle / a fresh
-*   one is tried). When no usable idle resource exists and the pool is below `max`, it
-*   `create`s a new one. At `max` with none idle, the acquire PARKS on a FIFO waiter
-*   list until a `release` hands it a resource.
-* - **FIFO handoff (validated).** `release` (on the token) hands the resource to the next
-*   parked waiter (oldest first) — the resource stays leased, the lessee just changes —
-*   or returns it to idle when no one is waiting. With a waiter parked the resource is
-*   re-validated first (the same `validate` hook the idle path uses), so a resource that
-*   went invalid WHILE leased (e.g. a terminated worker thread) is destroyed and the
-*   waiter is served a fresh/valid one instead — a dead resource is never handed on. The
-*   no-waiter path stays synchronous; releasing the same token twice is a no-op (an
-*   idempotent token guard).
-* - **`validate` is total.** A `validate` hook that THROWS is treated exactly like one
-*   returning `false` — the resource is "not usable", so it is destroyed and replaced —
-*   rather than escaping. This holds on both the idle reuse and the FIFO handoff paths, so
-*   a throwing validator can never strand a parked waiter on an unhandled rejection.
-* - **Abort-cancellable waiting.** A parked `acquire` given an `AbortSignal` rejects
-*   when that signal fires and removes its waiter from the queue — no leaked waiter, so
-*   a later `release` still serves the next live waiter. The signal is supplied by the
-*   caller (a worker, for example, passes its per-attempt execution signal); the pool adds no abort
-*   of its own.
-* - **Counts.** `size` = idle + leased; `idle` = available now; `active` = leased out.
-* - **Teardown.** `clear` destroys every IDLE resource (leased ones keep running);
-*   `destroy` destroys ALL resources and rejects any parked waiters. Both await the
-*   `destroy` hook.
-* - **Observable (§13).** The owned {@link emitter} ({@link PoolEventMap}) carries the
-*   resource lifecycle — `create` / `acquire` / `release` / `destroy` — for fire-and-forget
-*   observers. Every event is emitted directly, strictly AFTER the relevant transition —
-*   OUTSIDE the `#handoff` / `#serve` await-chain, never across a waiter's resolve; the
-*   emitter isolates a listener throw and routes it to its `error` handler (the `error`
-*   option), so a buggy observer can NEVER corrupt the validated FIFO handoff-eviction
-*   machinery (it cannot strand a parked waiter or unbalance the lease count). Observation is
-*   purely a side-channel.
-* - **De-bloated.** No warm-floor / `min`, no eviction timers — lean.
+* @typeParam T - The pooled resource value
+*
+* @example
+* ```ts
+* import { Pool } from '@orkestrel/pool'
+*
+* const pool = new Pool({ create: () => new Uint8Array(64), max: 2 })
+* const token = await pool.acquire()
+* try {
+* 	consume(token.value)
+* } finally {
+* 	token.release()
+* }
+* await pool.destroy()
+* ```
 */
 var Pool = class {
 	#create;
-	#destroy;
+	#cleanup;
 	#validate;
 	#max;
 	#emitter;
-	#idle = [];
+	#resources = /* @__PURE__ */ new Map();
+	#available = [];
+	#validating = /* @__PURE__ */ new Set();
+	#leased = /* @__PURE__ */ new Set();
+	#readyRecords = /* @__PURE__ */ new Set();
+	#destroying = /* @__PURE__ */ new Map();
 	#waiters = [];
-	#active = 0;
-	#destroyed = false;
+	#assigned = /* @__PURE__ */ new Set();
+	#reservations = /* @__PURE__ */ new Set();
+	#signals = /* @__PURE__ */ new Map();
+	#ready = /* @__PURE__ */ new Map();
+	#operations = /* @__PURE__ */ new Set();
+	#owned = /* @__PURE__ */ new Set();
+	#failures = [];
+	#ending;
+	#pumping = false;
+	#repump = false;
+	/**
+	* Construct a pool and synchronously validate its capacity contract.
+	*
+	* @param options - Resource hooks, observation hooks, and optional positive safe `max`
+	*/
 	constructor(options) {
+		if (options.max !== void 0 && !isPoolMax(options.max)) throw new PoolError({
+			code: "invalid",
+			context: { value: options.max }
+		});
 		this.#create = options.create;
-		this.#destroy = options.destroy;
+		this.#cleanup = options.destroy;
 		this.#validate = options.validate;
-		this.#max = Math.max(1, options.max ?? Number.POSITIVE_INFINITY);
+		this.#max = options.max;
 		this.#emitter = new _orkestrel_emitter.Emitter({
-			on: options?.on,
-			error: options?.error
+			...options.on === void 0 ? {} : { on: options.on },
+			...options.error === void 0 ? {} : { error: options.error }
 		});
 	}
+	/** The typed synchronous lifecycle observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
+	/** All owned records, including records validating or destroying. */
 	get size() {
-		return this.#idle.length + this.#active;
+		return this.#resources.size;
 	}
+	/** Records immediately available without validation work. */
 	get idle() {
-		return this.#idle.length;
+		return this.#available.length;
 	}
+	/** Records represented by unsettled released-once lease tokens. */
 	get active() {
-		return this.#active;
+		return this.#leased.size;
 	}
-	async acquire(signal) {
-		if (this.#destroyed) throw new Error("pool is destroyed");
-		if (signal?.aborted === true) throw signal.reason;
-		const reused = await this.#reuse();
-		if (reused !== void 0) {
-			this.#emitter.emit("acquire");
-			return reused;
+	/**
+	* Queue and lease one resource in FIFO settlement order.
+	*
+	* @param signal - Optional native cancellation signal
+	* @returns A promise for the unique resource lease
+	*/
+	acquire(signal) {
+		if (signal !== void 0 && !isPoolSignal(signal)) throw new PoolError({
+			code: "invalid",
+			context: { value: signal }
+		});
+		if (this.#ending !== void 0) return Promise.reject(new PoolError({ code: "destroyed" }));
+		if (signal !== void 0) {
+			const state = this.#state(signal);
+			if (state[0]) return Promise.reject(state[1]);
 		}
-		if (this.size < this.#max) {
-			const grown = await this.#grow();
-			this.#emitter.emit("acquire");
-			return grown;
+		const waiter = Promise.withResolvers();
+		this.#waiters.push(waiter);
+		if (signal !== void 0) {
+			const listener = this.#createAbort(waiter, signal);
+			AbortSignal.prototype.addEventListener.call(signal, "abort", listener, { once: true });
+			this.#signals.set(waiter, {
+				signal,
+				listener
+			});
+			const state = this.#state(signal);
+			if (state[0]) this.#abort(waiter, state[1]);
 		}
-		return await this.#wait(signal);
+		this.#pump();
+		return waiter.promise;
 	}
-	async clear() {
-		const resources = this.#idle.splice(0);
-		await Promise.all(resources.map((resource) => this.#release(resource)));
+	/**
+	* Destroy the records that are idle at this call's synchronous snapshot.
+	*
+	* @returns A promise that settles after every snapshot cleanup attempt
+	*/
+	clear() {
+		if (this.#ending !== void 0) return Promise.reject(new PoolError({ code: "destroyed" }));
+		const records = this.#available.splice(0);
+		const cleanups = [];
+		for (const record of records) cleanups.push(this.#dispose(record));
+		return this.#settleClear(cleanups);
 	}
-	async destroy() {
-		if (this.#destroyed) return;
-		this.#destroyed = true;
+	/**
+	* Permanently tear down the pool and return its stable completion barrier.
+	*
+	* @returns The exact promise shared by every destroy call
+	*/
+	destroy() {
+		if (this.#ending !== void 0) return this.#ending.promise;
+		const ending = Promise.withResolvers();
+		this.#ending = ending;
 		const waiters = this.#waiters.splice(0);
-		const error = /* @__PURE__ */ new Error("pool is destroyed");
 		for (const waiter of waiters) {
-			waiter.clear();
-			waiter.reject(error);
+			this.#detach(waiter);
+			waiter.reject(new PoolError({ code: "destroyed" }));
 		}
-		const resources = this.#idle.splice(0);
-		await Promise.all(resources.map((resource) => this.#release(resource)));
-	}
-	async #reuse() {
-		while (this.#idle.length > 0) {
-			const resource = this.#idle.shift();
-			if (resource === void 0) continue;
-			if (await this.#valid(resource)) {
-				this.#active += 1;
-				return this.#token(resource);
+		this.#ready.clear();
+		this.#assigned.clear();
+		this.#available.splice(0);
+		for (const cleanup of this.#destroying.values()) this.#own(cleanup);
+		for (const record of this.#resources.keys()) if (!this.#validating.has(record)) this.#own(this.#dispose(record));
+		this.#finish();
+		return ending.promise;
+	}
+	#createAbort(waiter, signal) {
+		return () => {
+			let reason;
+			try {
+				reason = this.#state(signal)[1];
+			} catch (error) {
+				reason = error;
 			}
-			await this.#release(resource);
-		}
+			this.#abort(waiter, reason);
+		};
 	}
-	async #grow() {
-		this.#active += 1;
-		let resource;
+	#state(signal) {
+		const aborted = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "aborted")?.get;
+		const reason = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "reason")?.get;
+		if (aborted === void 0 || reason === void 0) throw new PoolError({
+			code: "invalid",
+			context: { value: signal }
+		});
 		try {
-			resource = await this.#create();
+			const stopped = Reflect.apply(aborted, signal, []) === true;
+			return [stopped, stopped ? Reflect.apply(reason, signal, []) : void 0];
 		} catch (error) {
-			this.#active -= 1;
-			throw error instanceof Error ? error : new Error(String(error));
+			throw new PoolError({
+				code: "invalid",
+				cause: error,
+				context: { value: signal }
+			});
 		}
-		if (this.#destroyed) {
-			this.#active -= 1;
-			await this.#release(resource);
-			throw new Error("pool is destroyed");
-		}
-		this.#emitter.emit("create");
-		return this.#token(resource);
-	}
-	#wait(signal) {
-		return new Promise((resolve, reject) => {
-			const waiter = {
-				resolve,
-				reject,
-				clear: () => {}
-			};
-			this.#waiters.push(waiter);
-			if (signal !== void 0) {
-				const onAbort = () => {
-					const index = this.#waiters.indexOf(waiter);
-					if (index >= 0) this.#waiters.splice(index, 1);
-					reject(signal.reason);
-				};
-				signal.addEventListener("abort", onAbort, { once: true });
-				waiter.clear = () => signal.removeEventListener("abort", onAbort);
-			}
-		});
 	}
-	#token(resource) {
+	#createRelease(record) {
 		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			this.#release(record);
+		};
+	}
+	#token(record, value) {
 		return {
-			value: resource,
-			release: () => {
-				if (released) return;
-				released = true;
-				this.#return(resource);
-			}
+			value,
+			release: this.#createRelease(record)
 		};
 	}
-	#return(resource) {
-		if (this.#waiters.length === 0) {
-			this.#active -= 1;
-			if (this.#destroyed) {
-				this.#release(resource);
-				return;
-			}
-			this.#idle.push(resource);
-			this.#emitter.emit("release");
+	#abort(waiter, reason) {
+		const index = this.#waiters.indexOf(waiter);
+		if (index < 0) return;
+		this.#waiters.splice(index, 1);
+		this.#detach(waiter);
+		const ready = this.#ready.get(waiter);
+		this.#ready.delete(waiter);
+		this.#assigned.delete(waiter);
+		if (ready?.success === true) {
+			this.#readyRecords.delete(ready.record);
+			this.#recycle(ready.record);
+		}
+		waiter.reject(reason);
+		this.#commit();
+		this.#pump();
+	}
+	#detach(waiter) {
+		const entry = this.#signals.get(waiter);
+		if (entry === void 0) return;
+		AbortSignal.prototype.removeEventListener.call(entry.signal, "abort", entry.listener);
+		this.#signals.delete(waiter);
+	}
+	#pump() {
+		if (this.#ending !== void 0) return;
+		if (this.#pumping) {
+			this.#repump = true;
 			return;
 		}
-		this.#handoff(resource);
+		this.#pumping = true;
+		do {
+			this.#repump = false;
+			for (const waiter of this.#waiters) {
+				if (this.#assigned.has(waiter) || this.#ready.has(waiter)) continue;
+				const record = this.#available.shift();
+				if (record !== void 0) {
+					this.#assigned.add(waiter);
+					this.#validating.add(record);
+					this.#startValidation(waiter, record);
+					continue;
+				}
+				if (this.#max === void 0 || this.#resources.size + this.#reservations.size < this.#max) {
+					this.#assigned.add(waiter);
+					this.#reservations.add(waiter);
+					this.#startCreate(waiter);
+					continue;
+				}
+				break;
+			}
+		} while (this.#repump);
+		this.#pumping = false;
+	}
+	#startCreate(waiter) {
+		const operation = Promise.resolve().then(() => this.#createResource(waiter));
+		this.#operations.add(operation);
+		operation.then(() => this.#completeOperation(operation), (error) => this.#failOperation(operation, waiter, error, "create"));
 	}
-	async #handoff(resource) {
-		if (await this.#valid(resource)) {
-			this.#serve(resource);
+	#startValidation(waiter, record) {
+		for (const [owned, value] of this.#resources) {
+			if (owned !== record) continue;
+			if (this.#validate === void 0) {
+				this.#validating.delete(record);
+				this.#prepare(waiter, record, value);
+				return;
+			}
+			const operation = Promise.resolve().then(() => this.#validateResource(waiter, record, value));
+			this.#operations.add(operation);
+			operation.then(() => this.#completeOperation(operation), (error) => this.#failOperation(operation, waiter, error, "invalid"));
 			return;
 		}
-		this.#release(resource);
-		let replacement;
+		this.#validating.delete(record);
+		this.#assigned.delete(waiter);
+		this.#repump = true;
+	}
+	async #createResource(waiter) {
+		let value;
 		try {
-			replacement = await this.#create();
+			value = await this.#create();
 		} catch (error) {
-			this.#active -= 1;
-			const waiter = this.#waiters.shift();
-			waiter?.clear();
-			waiter?.reject(error instanceof Error ? error : new Error(String(error)));
+			this.#reservations.delete(waiter);
+			if (this.#waiters.includes(waiter)) this.#ready.set(waiter, {
+				success: false,
+				error: new PoolError({
+					code: "create",
+					cause: error
+				})
+			});
+			else this.#assigned.delete(waiter);
+			this.#commit();
 			return;
 		}
+		this.#reservations.delete(waiter);
+		const record = {};
+		this.#resources.set(record, value);
+		this.#readyRecords.add(record);
 		this.#emitter.emit("create");
-		this.#serve(replacement);
-	}
-	#serve(resource) {
-		const waiter = this.#destroyed ? void 0 : this.#waiters.shift();
-		if (waiter !== void 0) {
-			waiter.clear();
-			waiter.resolve(this.#token(resource));
-			this.#emitter.emit("acquire");
+		if (this.#ending !== void 0) {
+			this.#readyRecords.delete(record);
+			this.#assigned.delete(waiter);
+			try {
+				await this.#dispose(record);
+			} catch {}
 			return;
 		}
-		this.#active -= 1;
-		if (this.#destroyed) {
-			this.#release(resource);
+		if (!this.#waiters.includes(waiter)) {
+			this.#readyRecords.delete(record);
+			this.#assigned.delete(waiter);
+			this.#recycle(record);
 			return;
 		}
-		this.#idle.push(resource);
-		this.#emitter.emit("release");
+		this.#ready.set(waiter, {
+			success: true,
+			record,
+			token: this.#token(record, value)
+		});
+		this.#commit();
 	}
-	async #valid(resource) {
-		if (this.#validate === void 0) return true;
+	async #validateResource(waiter, record, value) {
+		let valid = false;
 		try {
-			return await this.#validate(resource);
-		} catch {
-			return false;
+			valid = await this.#validate?.(value) === true;
+		} catch {}
+		this.#validating.delete(record);
+		if (this.#ending !== void 0) {
+			this.#assigned.delete(waiter);
+			try {
+				await this.#dispose(record);
+			} catch {}
+			return;
 		}
+		if (!this.#waiters.includes(waiter)) {
+			this.#assigned.delete(waiter);
+			if (valid) this.#recycle(record);
+			else try {
+				await this.#dispose(record);
+			} catch (error) {
+				this.#record(error);
+			}
+			return;
+		}
+		if (valid) {
+			this.#prepare(waiter, record, value);
+			return;
+		}
+		try {
+			await this.#dispose(record);
+		} catch (error) {
+			if (this.#waiters.includes(waiter)) {
+				this.#ready.set(waiter, {
+					success: false,
+					error: new PoolError({
+						code: "cleanup",
+						cause: error
+					})
+				});
+				this.#commit();
+				return;
+			}
+			this.#record(error);
+		}
+		this.#assigned.delete(waiter);
+		this.#pump();
+	}
+	#prepare(waiter, record, value) {
+		if (!this.#waiters.includes(waiter) || this.#ending !== void 0) {
+			this.#assigned.delete(waiter);
+			this.#recycle(record);
+			return;
+		}
+		this.#readyRecords.add(record);
+		this.#ready.set(waiter, {
+			success: true,
+			record,
+			token: this.#token(record, value)
+		});
+		this.#commit();
+	}
+	#commit() {
+		while (this.#ending === void 0) {
+			const waiter = this.#waiters[0];
+			if (waiter === void 0) return;
+			const result = this.#ready.get(waiter);
+			if (result === void 0) return;
+			this.#waiters.shift();
+			this.#ready.delete(waiter);
+			this.#assigned.delete(waiter);
+			this.#detach(waiter);
+			if (!result.success) {
+				waiter.reject(result.error);
+				continue;
+			}
+			this.#readyRecords.delete(result.record);
+			this.#leased.add(result.record);
+			waiter.resolve(result.token);
+			this.#emitter.emit("acquire");
+		}
+	}
+	#completeOperation(operation) {
+		this.#operations.delete(operation);
+		this.#commit();
+		this.#pump();
+		this.#finish();
+	}
+	#failOperation(operation, waiter, error, code) {
+		this.#operations.delete(operation);
+		this.#reservations.delete(waiter);
+		this.#assigned.delete(waiter);
+		if (this.#waiters.includes(waiter)) this.#ready.set(waiter, {
+			success: false,
+			error: new PoolError({
+				code,
+				cause: error
+			})
+		});
+		this.#commit();
+		this.#pump();
+		this.#finish();
+	}
+	#release(record) {
+		if (!this.#leased.delete(record)) return;
+		if (this.#ending !== void 0) {
+			this.#own(this.#dispose(record));
+			return;
+		}
+		this.#available.push(record);
+		this.#pump();
+		if (this.#available.includes(record)) this.#emitter.emit("release");
 	}
-	async #release(resource) {
-		if (this.#destroy === void 0) {
-			this.#emitter.emit("destroy");
+	#recycle(record) {
+		if (this.#ending !== void 0) {
+			this.#own(this.#dispose(record));
 			return;
 		}
+		this.#available.push(record);
+		this.#pump();
+		if (this.#available.includes(record)) this.#emitter.emit("release");
+	}
+	#dispose(record) {
+		const existing = this.#destroying.get(record);
+		if (existing !== void 0) return existing;
+		for (const [owned, value] of this.#resources) {
+			if (owned !== record) continue;
+			const cleanup = Promise.withResolvers();
+			this.#destroying.set(record, cleanup.promise);
+			const index = this.#available.indexOf(record);
+			if (index >= 0) this.#available.splice(index, 1);
+			this.#validating.delete(record);
+			this.#leased.delete(record);
+			this.#readyRecords.delete(record);
+			if (this.#ending !== void 0) this.#own(cleanup.promise);
+			this.#clean(record, value, cleanup);
+			return cleanup.promise;
+		}
+		return Promise.resolve();
+	}
+	async #clean(record, value, cleanup) {
+		let failure;
+		let failed = false;
 		try {
-			await this.#destroy(resource);
-		} catch {}
+			await this.#cleanup?.(value);
+		} catch (error) {
+			failure = error;
+			failed = true;
+		}
+		this.#resources.delete(record);
 		this.#emitter.emit("destroy");
+		this.#destroying.delete(record);
+		this.#pump();
+		if (failed) cleanup.reject(failure);
+		else cleanup.resolve();
+		this.#finish();
+	}
+	async #settleClear(cleanups) {
+		const settled = await Promise.allSettled(cleanups);
+		const failures = [];
+		for (const result of settled) if (result.status === "rejected" && !failures.some((failure) => Object.is(failure, result.reason))) failures.push(result.reason);
+		if (failures.length > 0) throw this.#cleanupError(failures);
+	}
+	#own(cleanup) {
+		if (this.#owned.has(cleanup)) return;
+		this.#owned.add(cleanup);
+		cleanup.then(() => this.#completeCleanup(cleanup), (error) => this.#failCleanup(cleanup, error));
+	}
+	#completeCleanup(cleanup) {
+		this.#owned.delete(cleanup);
+		this.#finish();
+	}
+	#failCleanup(cleanup, error) {
+		this.#owned.delete(cleanup);
+		this.#record(error);
+		this.#finish();
+	}
+	#record(error) {
+		if (!this.#failures.some((failure) => Object.is(failure, error))) this.#failures.push(error);
+	}
+	#cleanupError(failures) {
+		return new PoolError({
+			code: "cleanup",
+			...failures[0] === void 0 ? {} : { cause: failures[0] },
+			context: { failures: [...failures] }
+		});
+	}
+	#finish() {
+		const ending = this.#ending;
+		if (ending === void 0 || this.#operations.size > 0 || this.#owned.size > 0) return;
+		let claimed = false;
+		for (const record of this.#resources.keys()) {
+			if (this.#validating.has(record) || this.#destroying.has(record)) continue;
+			claimed = true;
+			this.#own(this.#dispose(record));
+		}
+		if (claimed || this.#resources.size > 0 || this.#destroying.size > 0) return;
+		this.#emitter.destroy();
+		if (this.#failures.length > 0) ending.reject(this.#cleanupError(this.#failures));
+		else ending.resolve();
 	}
 };
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a bounded resource pool with idle reuse and FIFO waiting — `acquire` leases a
-* resource (reusing a validated idle one, growing up to `max`, or parking until a
-* `release` frees one) and the returned token's `release` returns it for reuse.
+* Create a resource pool with optional bounded capacity, unique ownership, and FIFO settlement.
 *
 * @remarks
-* A parked `acquire` given an `AbortSignal` rejects + de-queues itself when the signal
-* fires (no leaked waiter). `clear` destroys idle resources (leased ones keep running);
-* `destroy` destroys all and rejects waiters. The pool is lean — no warm-floor (`min`),
-* no eviction timers — and observable (§13): a typed `emitter` surfaces
-* `create` / `acquire` / `release` / `destroy`.
+* Concurrent create and validation hooks may overlap, while acquire promises settle in
+* request order. `clear` owns its idle snapshot; `destroy` returns one stable barrier and
+* waits for every in-flight hook and cleanup before destroying the emitter last.
 *
 * @typeParam T - The pooled resource type
-* @param options - The `create` hook plus optional `destroy` / `validate` / `max`
+* @param options - Lifecycle hooks, optional positive safe `max`, and observation hooks
 * @returns A working {@link PoolInterface}
 *
 * @example
 * ```ts
-* import { createPool } from '@src/core'
+* import { createPool } from '@orkestrel/pool'
 *
 * const pool = createPool<Connection>({
 * 	create: () => connect(),
@@ -271,6 +639,10 @@ function createPool(options) {
 }
 //#endregion
 exports.Pool = Pool;
+exports.PoolError = PoolError;
 exports.createPool = createPool;
+exports.isPoolError = isPoolError;
+exports.isPoolMax = isPoolMax;
+exports.isPoolSignal = isPoolSignal;
 
 //# sourceMappingURL=index.cjs.map