@storyshelf/core 0.7.0 → 0.9.0-next-d2cc082

package/dist/adapters/remote-limiter.mjs

@@ -0,0 +1,121 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { stoppedError } from "./remote-lease-error.mjs";
+// src/adapters/remote-limiter.ts
+/** A counting semaphore with a FIFO queue whose waiters can be cancelled. */
+var ConnectionLimiter = class {
+	limit;
+	#held = 0;
+	#queue = [];
+	constructor(limit) {
+		this.limit = limit;
+	}
+	/** Slots in use. */
+	get held() {
+		return this.#held;
+	}
+	/** Callers waiting for a slot. */
+	get waiting() {
+		return this.#queue.length;
+	}
+	/**
+	* Take a slot, waiting for one when all are in use. Rejects with the stopped error when `signal`
+	* aborts (or the process shuts down) while waiting, without having taken anything.
+	* `onLongWait` runs once if the wait outlasts `longWaitMs`.
+	*/
+	async acquire(signal, onLongWait, longWaitMs = 0) {
+		if (signal?.aborted === true) throw stoppedError();
+		if (this.#held < this.limit && this.#queue.length === 0) {
+			this.#held += 1;
+			return this.#slot();
+		}
+		return await new Promise((resolve, reject) => {
+			const timer = onLongWait === void 0 ? void 0 : setTimeout(onLongWait, longWaitMs).unref();
+			const settle = () => {
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+			};
+			const waiter = {
+				grant: () => {
+					settle();
+					this.#held += 1;
+					resolve(this.#slot());
+				},
+				stop: () => {
+					settle();
+					const index = this.#queue.indexOf(waiter);
+					if (index >= 0) this.#queue.splice(index, 1);
+					reject(stoppedError());
+				}
+			};
+			const onAbort = () => {
+				waiter.stop();
+			};
+			signal?.addEventListener("abort", onAbort, { once: true });
+			this.#queue.push(waiter);
+		});
+	}
+	/** Reject every waiter (shutdown). Slots already taken are released by their leases. */
+	stopWaiting() {
+		for (const waiter of this.#queue.splice(0)) waiter.stop();
+	}
+	#slot() {
+		let released = false;
+		return { release: () => {
+			if (released) return;
+			released = true;
+			this.#held -= 1;
+			this.#queue.shift()?.grant();
+		} };
+	}
+};
+const limiters = /* @__PURE__ */ new Map();
+let epoch = 0;
+/** The limiter of a service, created on first use; undefined when it has no `maxConnections`. */
+function limiterOf(remote) {
+	if (remote.maxConnections === void 0) return;
+	let limiter = limiters.get(remote);
+	if (limiter === void 0) {
+		limiter = new ConnectionLimiter(remote.maxConnections);
+		limiters.set(remote, limiter);
+	}
+	return limiter;
+}
+/**
+* Take the connection slot of `entry`'s service, or undefined when it has no cap. Not `async`: without
+* a cap the caller must not wait even one tick before it connects. A wait longer than
+* `timeouts.acquireMs` is logged once, with the target and the limit and nothing about the endpoint.
+*/
+function takeSlot(entry, signal, logger) {
+	const limiter = limiterOf(entry.remote);
+	if (limiter === void 0) return;
+	return limiter.acquire(signal, () => {
+		logger?.warn({
+			target: entry.target,
+			limit: limiter.limit,
+			waiting: limiter.waiting
+		}, "waiting for a remote browser connection slot");
+	}, entry.remote.timeouts.acquireMs);
+}
+/**
+* Shutdown: reject every caller still waiting for a slot and forget every limiter, so a service used
+* again starts with none held. A lease that is released later gives its slot back to the limiter it
+* took it from, which nothing uses any more.
+*/
+function resetAllLimiters() {
+	epoch += 1;
+	for (const limiter of limiters.values()) limiter.stopWaiting();
+	limiters.clear();
+}
+/**
+* Counts shutdowns. A caller that took a slot compares it with the value from before it waited: a
+* slot granted just before a shutdown resumes a tick later, after the attempts were stopped, and
+* must not open a connection nobody will release.
+*/
+function shutdownEpoch() {
+	return epoch;
+}
+export { ConnectionLimiter, limiterOf, resetAllLimiters, shutdownEpoch, takeSlot };
+
+//# sourceMappingURL=remote-limiter.mjs.map

package/dist/adapters/remote-limiter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-limiter.mjs","names":[],"sources":["../../src/adapters/remote-limiter.ts"],"sourcesContent":["/**\n * The per-process cap on a remote service's connections (ADR 0007, decision 4): a separate limiter,\n * never the page gate. A slot is taken before `connect` is called and given back with the lease,\n * exactly once, so a connection counts from the moment it is requested until its render has ended.\n * Waiting for a slot ends on the run's cancel and at shutdown, and frees nothing it did not take.\n */\nimport type { Logger } from \"../logger.ts\";\nimport type { RemoteBrowser, RemoteTarget } from \"./remote-browser.ts\";\nimport { stoppedError } from \"./remote-lease-error.ts\";\n\n/** One connection's place under the cap; `release` is safe to call more than once. */\nexport interface ConnectionSlot {\n  release(): void;\n}\n\ninterface Waiter {\n  grant(): void;\n  stop(): void;\n}\n\n/** A counting semaphore with a FIFO queue whose waiters can be cancelled. */\nexport class ConnectionLimiter {\n  readonly limit: number;\n  #held = 0;\n  readonly #queue: Waiter[] = [];\n\n  constructor(limit: number) {\n    this.limit = limit;\n  }\n\n  /** Slots in use. */\n  get held(): number {\n    return this.#held;\n  }\n\n  /** Callers waiting for a slot. */\n  get waiting(): number {\n    return this.#queue.length;\n  }\n\n  /**\n   * Take a slot, waiting for one when all are in use. Rejects with the stopped error when `signal`\n   * aborts (or the process shuts down) while waiting, without having taken anything.\n   * `onLongWait` runs once if the wait outlasts `longWaitMs`.\n   */\n  async acquire(\n    signal?: AbortSignal,\n    onLongWait?: () => void,\n    longWaitMs = 0,\n  ): Promise<ConnectionSlot> {\n    if (signal?.aborted === true) {\n      throw stoppedError();\n    }\n    if (this.#held < this.limit && this.#queue.length === 0) {\n      this.#held += 1;\n      return this.#slot();\n    }\n    return await new Promise<ConnectionSlot>((resolve, reject) => {\n      const timer =\n        onLongWait === undefined ? undefined : setTimeout(onLongWait, longWaitMs).unref();\n      const settle = (): void => {\n        clearTimeout(timer);\n        signal?.removeEventListener(\"abort\", onAbort);\n      };\n      const waiter: Waiter = {\n        grant: () => {\n          settle();\n          this.#held += 1;\n          resolve(this.#slot());\n        },\n        stop: () => {\n          settle();\n          const index = this.#queue.indexOf(waiter);\n          if (index >= 0) {\n            this.#queue.splice(index, 1);\n          }\n          reject(stoppedError());\n        },\n      };\n      const onAbort = (): void => {\n        waiter.stop();\n      };\n      signal?.addEventListener(\"abort\", onAbort, { once: true });\n      this.#queue.push(waiter);\n    });\n  }\n\n  /** Reject every waiter (shutdown). Slots already taken are released by their leases. */\n  stopWaiting(): void {\n    for (const waiter of this.#queue.splice(0)) {\n      waiter.stop();\n    }\n  }\n\n  #slot(): ConnectionSlot {\n    let released = false;\n    return {\n      release: () => {\n        if (released) {\n          return;\n        }\n        released = true;\n        this.#held -= 1;\n        this.#queue.shift()?.grant();\n      },\n    };\n  }\n}\n\nconst limiters = new Map<RemoteBrowser, ConnectionLimiter>();\nlet epoch = 0;\n\n/** The limiter of a service, created on first use; undefined when it has no `maxConnections`. */\nexport function limiterOf(remote: RemoteBrowser): ConnectionLimiter | undefined {\n  if (remote.maxConnections === undefined) {\n    return undefined;\n  }\n  let limiter = limiters.get(remote);\n  if (limiter === undefined) {\n    limiter = new ConnectionLimiter(remote.maxConnections);\n    limiters.set(remote, limiter);\n  }\n  return limiter;\n}\n\n/**\n * Take the connection slot of `entry`'s service, or undefined when it has no cap. Not `async`: without\n * a cap the caller must not wait even one tick before it connects. A wait longer than\n * `timeouts.acquireMs` is logged once, with the target and the limit and nothing about the endpoint.\n */\nexport function takeSlot(\n  entry: RemoteTarget,\n  signal: AbortSignal | undefined,\n  logger: Logger | undefined,\n): Promise<ConnectionSlot> | undefined {\n  const limiter = limiterOf(entry.remote);\n  if (limiter === undefined) {\n    return undefined;\n  }\n  return limiter.acquire(\n    signal,\n    () => {\n      logger?.warn(\n        { target: entry.target, limit: limiter.limit, waiting: limiter.waiting },\n        \"waiting for a remote browser connection slot\",\n      );\n    },\n    entry.remote.timeouts.acquireMs,\n  );\n}\n\n/**\n * Shutdown: reject every caller still waiting for a slot and forget every limiter, so a service used\n * again starts with none held. A lease that is released later gives its slot back to the limiter it\n * took it from, which nothing uses any more.\n */\nexport function resetAllLimiters(): void {\n  epoch += 1;\n  for (const limiter of limiters.values()) {\n    limiter.stopWaiting();\n  }\n  limiters.clear();\n}\n\n/**\n * Counts shutdowns. A caller that took a slot compares it with the value from before it waited: a\n * slot granted just before a shutdown resumes a tick later, after the attempts were stopped, and\n * must not open a connection nobody will release.\n */\nexport function shutdownEpoch(): number {\n  return epoch;\n}\n"],"mappings":";;;;;;AAqBA,IAAa,oBAAb,MAA+B;CAC7B;CACA,QAAQ;CACR,SAA4B,CAAC;CAE7B,YAAY,OAAe;EACzB,KAAK,QAAQ;CACf;;CAGA,IAAI,OAAe;EACjB,OAAO,KAAK;CACd;;CAGA,IAAI,UAAkB;EACpB,OAAO,KAAK,OAAO;CACrB;;;;;;CAOA,MAAM,QACJ,QACA,YACA,aAAa,GACY;EACzB,IAAI,QAAQ,YAAY,MACtB,MAAM,aAAa;EAErB,IAAI,KAAK,QAAQ,KAAK,SAAS,KAAK,OAAO,WAAW,GAAG;GACvD,KAAK,SAAS;GACd,OAAO,KAAK,MAAM;EACpB;EACA,OAAO,MAAM,IAAI,SAAyB,SAAS,WAAW;GAC5D,MAAM,QACJ,eAAe,KAAA,IAAY,KAAA,IAAY,WAAW,YAAY,UAAU,CAAC,CAAC,MAAM;GAClF,MAAM,eAAqB;IACzB,aAAa,KAAK;IAClB,QAAQ,oBAAoB,SAAS,OAAO;GAC9C;GACA,MAAM,SAAiB;IACrB,aAAa;KACX,OAAO;KACP,KAAK,SAAS;KACd,QAAQ,KAAK,MAAM,CAAC;IACtB;IACA,YAAY;KACV,OAAO;KACP,MAAM,QAAQ,KAAK,OAAO,QAAQ,MAAM;KACxC,IAAI,SAAS,GACX,KAAK,OAAO,OAAO,OAAO,CAAC;KAE7B,OAAO,aAAa,CAAC;IACvB;GACF;GACA,MAAM,gBAAsB;IAC1B,OAAO,KAAK;GACd;GACA,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;GACzD,KAAK,OAAO,KAAK,MAAM;EACzB,CAAC;CACH;;CAGA,cAAoB;EAClB,KAAK,MAAM,UAAU,KAAK,OAAO,OAAO,CAAC,GACvC,OAAO,KAAK;CAEhB;CAEA,QAAwB;EACtB,IAAI,WAAW;EACf,OAAO,EACL,eAAe;GACb,IAAI,UACF;GAEF,WAAW;GACX,KAAK,SAAS;GACd,KAAK,OAAO,MAAM,CAAC,EAAE,MAAM;EAC7B,EACF;CACF;AACF;AAEA,MAAM,2BAAW,IAAI,IAAsC;AAC3D,IAAI,QAAQ;;AAGZ,SAAgB,UAAU,QAAsD;CAC9E,IAAI,OAAO,mBAAmB,KAAA,GAC5B;CAEF,IAAI,UAAU,SAAS,IAAI,MAAM;CACjC,IAAI,YAAY,KAAA,GAAW;EACzB,UAAU,IAAI,kBAAkB,OAAO,cAAc;EACrD,SAAS,IAAI,QAAQ,OAAO;CAC9B;CACA,OAAO;AACT;;;;;;AAOA,SAAgB,SACd,OACA,QACA,QACqC;CACrC,MAAM,UAAU,UAAU,MAAM,MAAM;CACtC,IAAI,YAAY,KAAA,GACd;CAEF,OAAO,QAAQ,QACb,cACM;EACJ,QAAQ,KACN;GAAE,QAAQ,MAAM;GAAQ,OAAO,QAAQ;GAAO,SAAS,QAAQ;EAAQ,GACvE,8CACF;CACF,GACA,MAAM,OAAO,SAAS,SACxB;AACF;;;;;;AAOA,SAAgB,mBAAyB;CACvC,SAAS;CACT,KAAK,MAAM,WAAW,SAAS,OAAO,GACpC,QAAQ,YAAY;CAEtB,SAAS,MAAM;AACjB;;;;;;AAOA,SAAgB,gBAAwB;CACtC,OAAO;AACT"}

package/dist/adapters/remote-pool.d.mts

@@ -0,0 +1,56 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { RemoteConnectContext, RemoteConnection, RemoteLeasedConnection, RemoteReleaseInfo } from "./remote-browser.mjs";
+import { Logger } from "../logger.mjs";
+/** Options of {@link refCounted}. */
+interface RefCountedOptions<TResource> {
+  /**
+   * Start the resource (wake the computer) and return what connections need of it. Called by the
+   * first connection; concurrent first connections share the call. Must be idempotent: it runs
+   * again after a failed `close`, and may overlap a `close` that timed out. `signal` aborts when
+   * every waiting connection was cancelled, and at shutdown: clean up after yourself when it does,
+   * or throw an error with a `resource` property so the pool closes it.
+   */
+  open: (context: RemoteConnectContext, signal: AbortSignal) => Promise<TResource>;
+  /** Stop the resource (suspend the computer). */
+  close: (resource: TResource) => Promise<void> | void;
+  /**
+   * How long the resource stays open with no connection, in ms. Required: set it longer than the
+   * gap between a build's passes (the extract and tests pre-passes and its shards connect close
+   * together), for example 120 000.
+   */
+  idleMs: number;
+  /** How long `close` may take in ms before it counts as failed (default 30 000). */
+  closeTimeoutMs?: number | undefined;
+  /** Where close failures go (error class only, never the message). */
+  logger?: Logger | undefined;
+  /**
+   * Runs `run` after `ms` and returns what cancels it (default: an unref'd `setTimeout`). A seam
+   * for tests to drive the idle timer without real time.
+   */
+  schedule?: ((run: () => void, ms: number) => () => void) | undefined;
+}
+/** What the pool hands to `release`: an opaque token for one connection. */
+interface PoolLease {
+  readonly pool: "refCounted";
+}
+/** A reference-counted resource, wired into a service's `connect` and `release`. */
+interface RefCounted<TResource> {
+  /** Build the service's `connect`: `build` gets the shared resource and returns the connection. */
+  connect(build: (resource: TResource, context: RemoteConnectContext) => RemoteConnection | Promise<RemoteConnection>): (context: RemoteConnectContext) => Promise<RemoteLeasedConnection<PoolLease>>;
+  /** The service's `release`. */
+  release(lease: PoolLease, info: RemoteReleaseInfo): Promise<void>;
+  /** Close now: abort a pending `open`, then close the resource. Runs at shutdown. */
+  flush(): Promise<void>;
+  /** Unregister from shutdown and drop the idle timer, without closing (for tests). */
+  dispose(): void;
+}
+/**
+ * Share one resource between connections: opened by the first, closed `idleMs` after the last
+ * was released (or at once on shutdown). A connection arriving while it closes waits, then opens it
+ * again. After a failed `close` the resource is `unknown`: the next connection opens it again and
+ * the idle timer retries the close.
+ */
+declare function refCounted<TResource>(options: RefCountedOptions<TResource>): RefCounted<TResource>;
+export { PoolLease, RefCounted, RefCountedOptions, refCounted };
+//# sourceMappingURL=remote-pool.d.mts.map

package/dist/adapters/remote-pool.mjs

@@ -0,0 +1,195 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { onRemoteShutdown } from "./remote-lease-shutdown.mjs";
+// src/adapters/remote-pool.ts
+/**
+* Share one resource between connections: opened by the first, closed `idleMs` after the last
+* was released (or at once on shutdown). A connection arriving while it closes waits, then opens it
+* again. After a failed `close` the resource is `unknown`: the next connection opens it again and
+* the idle timer retries the close.
+*/
+function refCounted(options) {
+	const pool = new Pool(options);
+	const unregister = onRemoteShutdown(async () => {
+		await pool.flush();
+	});
+	return {
+		connect: (build) => async (context) => {
+			const slot = await pool.take(context);
+			try {
+				return {
+					...await build(slot.resource, context),
+					lease: slot
+				};
+			} catch (error) {
+				pool.give(slot);
+				throw error;
+			}
+		},
+		release: async (lease) => {
+			pool.give(lease);
+			await Promise.resolve();
+		},
+		flush: async () => {
+			await pool.flush();
+		},
+		dispose: () => {
+			unregister();
+			pool.dispose();
+		}
+	};
+}
+var Pool = class {
+	#state = "idle";
+	#slot;
+	#stale;
+	#hasStale = false;
+	#cancelIdle;
+	#opening;
+	#openController;
+	#waiters = /* @__PURE__ */ new Set();
+	#closing;
+	#options;
+	constructor(options) {
+		this.#options = options;
+	}
+	/** A connection's share of the resource, opening it first when nobody has. */
+	async take(context) {
+		for (;;) if (this.#state === "closing") await this.#closing?.catch(() => {});
+		else if (this.#state === "opening") await this.#waitOpen(context.signal);
+		else if (this.#state === "open" && this.#slot !== void 0) {
+			this.#clearIdle();
+			this.#slot.count += 1;
+			return this.#slot;
+		} else this.#startOpen(context);
+	}
+	/** A connection is done with its slot; the last one starts the idle timer. */
+	give(slot) {
+		slot.count = Math.max(0, slot.count - 1);
+		if (slot === this.#slot && slot.count === 0 && this.#state === "open") this.#armIdle();
+	}
+	/** Close now, aborting a pending open first. */
+	async flush() {
+		this.#clearIdle();
+		this.#openController?.abort();
+		await this.#opening?.catch(() => {});
+		if (this.#state === "closing") await this.#closing?.catch(() => {});
+		if (this.#state === "open" || this.#state === "unknown") await this.#close();
+	}
+	dispose() {
+		this.#clearIdle();
+	}
+	#startOpen(context) {
+		this.#clearIdle();
+		const controller = new AbortController();
+		this.#openController = controller;
+		this.#state = "opening";
+		this.#opening = this.#options.open(context, controller.signal).then((resource) => {
+			this.#slot = {
+				resource,
+				count: 0
+			};
+			this.#hasStale = false;
+			this.#stale = void 0;
+			this.#state = "open";
+		}, async (error) => {
+			this.#state = this.#hasStale ? "unknown" : "idle";
+			if (this.#hasStale) this.#armIdle();
+			await this.#closeLeftover(error);
+			throw error;
+		}).finally(() => {
+			this.#openController = void 0;
+			this.#waiters.clear();
+		});
+		this.#opening.catch(() => {});
+		this.#waitOpen(context.signal).catch(() => {});
+	}
+	/** Wait for the open in flight; it is aborted once every waiter has given up. */
+	async #waitOpen(signal) {
+		this.#waiters.add(signal);
+		const onAbort = () => {
+			this.#waiters.delete(signal);
+			if (this.#waiters.size === 0) this.#openController?.abort();
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			await this.#opening;
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+	#armIdle() {
+		this.#clearIdle();
+		const schedule = this.#options.schedule ?? scheduleTimeout;
+		this.#cancelIdle = schedule(() => {
+			if ((this.#slot?.count ?? 0) === 0) this.#close().catch(() => {});
+		}, this.#options.idleMs);
+	}
+	#clearIdle() {
+		this.#cancelIdle?.();
+		this.#cancelIdle = void 0;
+	}
+	async #close() {
+		const resource = this.#slot?.resource ?? this.#stale;
+		if (resource === void 0 || this.#state === "closing") return;
+		this.#state = "closing";
+		this.#closing = this.#runClose(resource);
+		await this.#closing;
+	}
+	async #runClose(resource) {
+		try {
+			await timed(async () => {
+				await this.#options.close(resource);
+			}, this.#options.closeTimeoutMs ?? 3e4);
+			this.#settle("idle");
+		} catch (error) {
+			this.#settle("unknown", resource);
+			this.#options.logger?.warn({ err: error instanceof Error ? error.name : "Error" }, "remote pool close failed, will retry after the idle period");
+			this.#armIdle();
+		}
+	}
+	/** After a close: `idle` with nothing, or `unknown` holding the resource to close again. */
+	#settle(state, stale) {
+		this.#slot = void 0;
+		this.#stale = stale;
+		this.#hasStale = state === "unknown";
+		this.#state = state;
+	}
+	/** An `open` that failed after starting something may name it, so it is not left running. */
+	async #closeLeftover(error) {
+		const leftover = error?.resource;
+		if (leftover === void 0) return;
+		try {
+			await timed(async () => {
+				await this.#options.close(leftover);
+			}, this.#options.closeTimeoutMs ?? 3e4);
+		} catch (closeError) {
+			this.#options.logger?.warn({ err: closeError instanceof Error ? closeError.name : "Error" }, "remote pool close failed after a failed open");
+		}
+	}
+};
+/** The default scheduler: an unref'd timer, so an idle pool never keeps the process alive. */
+function scheduleTimeout(run, ms) {
+	const timer = setTimeout(run, ms);
+	timer.unref();
+	return () => {
+		clearTimeout(timer);
+	};
+}
+async function timed(run, ms) {
+	let timer;
+	const deadline = new Promise((_, reject) => {
+		timer = setTimeout(() => {
+			reject(Object.assign(/* @__PURE__ */ new Error(`close timed out after ${ms} ms`), { name: "CloseTimeout" }));
+		}, ms);
+	});
+	try {
+		await Promise.race([run(), deadline]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+export { refCounted };
+
+//# sourceMappingURL=remote-pool.mjs.map

package/dist/adapters/remote-pool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-pool.mjs","names":[],"sources":["../../src/adapters/remote-pool.ts"],"sourcesContent":["/**\n * A shared resource behind a remote service, opened by the first connection and closed once the\n * last one has been idle for a while: a computer woken for the builds' shards and suspended after\n * (ADR 0007, decision 4). One pool per service; its connections share the resource.\n */\nimport type { Logger } from \"../logger.ts\";\nimport type {\n  RemoteConnectContext,\n  RemoteConnection,\n  RemoteLeasedConnection,\n  RemoteReleaseInfo,\n} from \"./remote-browser.ts\";\nimport { onRemoteShutdown } from \"./remote-lease.ts\";\n\n/** Options of {@link refCounted}. */\nexport interface RefCountedOptions<TResource> {\n  /**\n   * Start the resource (wake the computer) and return what connections need of it. Called by the\n   * first connection; concurrent first connections share the call. Must be idempotent: it runs\n   * again after a failed `close`, and may overlap a `close` that timed out. `signal` aborts when\n   * every waiting connection was cancelled, and at shutdown: clean up after yourself when it does,\n   * or throw an error with a `resource` property so the pool closes it.\n   */\n  open: (context: RemoteConnectContext, signal: AbortSignal) => Promise<TResource>;\n  /** Stop the resource (suspend the computer). */\n  close: (resource: TResource) => Promise<void> | void;\n  /**\n   * How long the resource stays open with no connection, in ms. Required: set it longer than the\n   * gap between a build's passes (the extract and tests pre-passes and its shards connect close\n   * together), for example 120 000.\n   */\n  idleMs: number;\n  /** How long `close` may take in ms before it counts as failed (default 30 000). */\n  closeTimeoutMs?: number | undefined;\n  /** Where close failures go (error class only, never the message). */\n  logger?: Logger | undefined;\n  /**\n   * Runs `run` after `ms` and returns what cancels it (default: an unref'd `setTimeout`). A seam\n   * for tests to drive the idle timer without real time.\n   */\n  schedule?: ((run: () => void, ms: number) => () => void) | undefined;\n}\n\n/** What the pool hands to `release`: an opaque token for one connection. */\nexport interface PoolLease {\n  readonly pool: \"refCounted\";\n}\n\n/** A reference-counted resource, wired into a service's `connect` and `release`. */\nexport interface RefCounted<TResource> {\n  /** Build the service's `connect`: `build` gets the shared resource and returns the connection. */\n  connect(\n    build: (\n      resource: TResource,\n      context: RemoteConnectContext,\n    ) => RemoteConnection | Promise<RemoteConnection>,\n  ): (context: RemoteConnectContext) => Promise<RemoteLeasedConnection<PoolLease>>;\n  /** The service's `release`. */\n  release(lease: PoolLease, info: RemoteReleaseInfo): Promise<void>;\n  /** Close now: abort a pending `open`, then close the resource. Runs at shutdown. */\n  flush(): Promise<void>;\n  /** Unregister from shutdown and drop the idle timer, without closing (for tests). */\n  dispose(): void;\n}\n\ntype State = \"idle\" | \"opening\" | \"open\" | \"closing\" | \"unknown\";\n\ninterface Slot<TResource> {\n  resource: TResource;\n  count: number;\n}\n\n/**\n * Share one resource between connections: opened by the first, closed `idleMs` after the last\n * was released (or at once on shutdown). A connection arriving while it closes waits, then opens it\n * again. After a failed `close` the resource is `unknown`: the next connection opens it again and\n * the idle timer retries the close.\n */\nexport function refCounted<TResource>(\n  options: RefCountedOptions<TResource>,\n): RefCounted<TResource> {\n  const pool = new Pool(options);\n  const unregister = onRemoteShutdown(async () => {\n    await pool.flush();\n  });\n  return {\n    connect: (build) => async (context) => {\n      const slot = await pool.take(context);\n      try {\n        const connection = await build(slot.resource, context);\n        return { ...connection, lease: slot as unknown as PoolLease };\n      } catch (error) {\n        pool.give(slot);\n        throw error;\n      }\n    },\n    release: async (lease) => {\n      pool.give(lease as unknown as Slot<TResource>);\n      await Promise.resolve();\n    },\n    flush: async () => {\n      await pool.flush();\n    },\n    dispose: () => {\n      unregister();\n      pool.dispose();\n    },\n  };\n}\n\nclass Pool<TResource> {\n  #state: State = \"idle\";\n  #slot: Slot<TResource> | undefined;\n  #stale: TResource | undefined;\n  #hasStale = false;\n  #cancelIdle: (() => void) | undefined;\n  #opening: Promise<void> | undefined;\n  #openController: AbortController | undefined;\n  #waiters = new Set<AbortSignal>();\n  #closing: Promise<void> | undefined;\n  readonly #options: RefCountedOptions<TResource>;\n\n  constructor(options: RefCountedOptions<TResource>) {\n    this.#options = options;\n  }\n\n  /** A connection's share of the resource, opening it first when nobody has. */\n  async take(context: RemoteConnectContext): Promise<Slot<TResource>> {\n    for (;;) {\n      if (this.#state === \"closing\") {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- a connection waits for the close to end\n        await this.#closing?.catch(() => {});\n      } else if (this.#state === \"opening\") {\n        // oxlint-disable-next-line eslint/no-await-in-loop -- waiters share the one open\n        await this.#waitOpen(context.signal);\n      } else if (this.#state === \"open\" && this.#slot !== undefined) {\n        this.#clearIdle();\n        this.#slot.count += 1;\n        return this.#slot;\n      } else {\n        this.#startOpen(context);\n      }\n    }\n  }\n\n  /** A connection is done with its slot; the last one starts the idle timer. */\n  give(slot: Slot<TResource>): void {\n    slot.count = Math.max(0, slot.count - 1);\n    if (slot === this.#slot && slot.count === 0 && this.#state === \"open\") {\n      this.#armIdle();\n    }\n  }\n\n  /** Close now, aborting a pending open first. */\n  async flush(): Promise<void> {\n    this.#clearIdle();\n    this.#openController?.abort();\n    await this.#opening?.catch(() => {});\n    if (this.#state === \"closing\") {\n      await this.#closing?.catch(() => {});\n    }\n    if (this.#state === \"open\" || this.#state === \"unknown\") {\n      await this.#close();\n    }\n  }\n\n  dispose(): void {\n    this.#clearIdle();\n  }\n\n  #startOpen(context: RemoteConnectContext): void {\n    this.#clearIdle();\n    const controller = new AbortController();\n    this.#openController = controller;\n    this.#state = \"opening\";\n    this.#opening = this.#options\n      .open(context, controller.signal)\n      .then(\n        (resource) => {\n          this.#slot = { resource, count: 0 };\n          this.#hasStale = false;\n          this.#stale = undefined;\n          this.#state = \"open\";\n        },\n        async (error: unknown) => {\n          this.#state = this.#hasStale ? \"unknown\" : \"idle\";\n          if (this.#hasStale) {\n            // Reopening cancelled the retry of the failed close; it is still owed.\n            this.#armIdle();\n          }\n          await this.#closeLeftover(error);\n          throw error;\n        },\n      )\n      .finally(() => {\n        this.#openController = undefined;\n        this.#waiters.clear();\n      });\n    // The first waiter is the caller that started it.\n    this.#opening.catch(() => {});\n    this.#waitOpen(context.signal).catch(() => {});\n  }\n\n  /** Wait for the open in flight; it is aborted once every waiter has given up. */\n  async #waitOpen(signal: AbortSignal): Promise<void> {\n    this.#waiters.add(signal);\n    const onAbort = (): void => {\n      this.#waiters.delete(signal);\n      if (this.#waiters.size === 0) {\n        this.#openController?.abort();\n      }\n    };\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n    try {\n      await this.#opening;\n    } finally {\n      signal.removeEventListener(\"abort\", onAbort);\n    }\n  }\n\n  #armIdle(): void {\n    this.#clearIdle();\n    const schedule = this.#options.schedule ?? scheduleTimeout;\n    this.#cancelIdle = schedule(() => {\n      if ((this.#slot?.count ?? 0) === 0) {\n        this.#close().catch(() => {});\n      }\n    }, this.#options.idleMs);\n  }\n\n  #clearIdle(): void {\n    this.#cancelIdle?.();\n    this.#cancelIdle = undefined;\n  }\n\n  async #close(): Promise<void> {\n    const resource = this.#slot?.resource ?? this.#stale;\n    if (resource === undefined || this.#state === \"closing\") {\n      return;\n    }\n    this.#state = \"closing\";\n    this.#closing = this.#runClose(resource);\n    await this.#closing;\n  }\n\n  async #runClose(resource: TResource): Promise<void> {\n    try {\n      await timed(async () => {\n        await this.#options.close(resource);\n      }, this.#options.closeTimeoutMs ?? 30_000);\n      this.#settle(\"idle\");\n    } catch (error) {\n      // The suspend may have worked on the server: keep the reference, but trust nothing about it.\n      this.#settle(\"unknown\", resource);\n      this.#options.logger?.warn(\n        { err: error instanceof Error ? error.name : \"Error\" },\n        \"remote pool close failed, will retry after the idle period\",\n      );\n      this.#armIdle();\n    }\n  }\n\n  /** After a close: `idle` with nothing, or `unknown` holding the resource to close again. */\n  #settle(state: \"idle\" | \"unknown\", stale?: TResource): void {\n    this.#slot = undefined;\n    this.#stale = stale;\n    this.#hasStale = state === \"unknown\";\n    this.#state = state;\n  }\n\n  /** An `open` that failed after starting something may name it, so it is not left running. */\n  async #closeLeftover(error: unknown): Promise<void> {\n    const leftover = (error as { resource?: TResource } | null)?.resource;\n    if (leftover === undefined) {\n      return;\n    }\n    try {\n      await timed(async () => {\n        await this.#options.close(leftover);\n      }, this.#options.closeTimeoutMs ?? 30_000);\n    } catch (closeError) {\n      this.#options.logger?.warn(\n        { err: closeError instanceof Error ? closeError.name : \"Error\" },\n        \"remote pool close failed after a failed open\",\n      );\n    }\n  }\n}\n\n/** The default scheduler: an unref'd timer, so an idle pool never keeps the process alive. */\nfunction scheduleTimeout(run: () => void, ms: number): () => void {\n  const timer = setTimeout(run, ms);\n  timer.unref();\n  return () => {\n    clearTimeout(timer);\n  };\n}\n\nasync function timed(run: () => Promise<void>, ms: number): Promise<void> {\n  let timer: NodeJS.Timeout | undefined;\n  const deadline = new Promise<never>((_, reject) => {\n    timer = setTimeout(() => {\n      reject(Object.assign(new Error(`close timed out after ${ms} ms`), { name: \"CloseTimeout\" }));\n    }, ms);\n  });\n  try {\n    await Promise.race([run(), deadline]);\n  } finally {\n    clearTimeout(timer);\n  }\n}\n"],"mappings":"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"}

package/dist/adapters/remote-sizing.d.mts

@@ -0,0 +1,44 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CaptureTarget } from "./capture-target.mjs";
+import { RemoteBrowser } from "./remote-browser.mjs";
+/** Said of every experimental preset until someone verifies it against the provider. */
+declare const UNVERIFIED_NOTE = "not verified against live infrastructure";
+/** The loggable limits of one remote target. A `null` limit is not capped. */
+interface RemoteSizing {
+  target: CaptureTarget;
+  /** Pages the plan allows at once: the target's page gate. Per target, per process. */
+  pages: number | null;
+  /** Pages on one connection, when capped. */
+  pagesPerConnection: number | null;
+  /** Pages one connection can hold: the lowest of `pages`, `pagesPerConnection` (when the runner enforces it) and the run's `concurrency`. */
+  effectivePagesPerConnection: number | null;
+  /** Connections this process holds at once, when capped. Per process. */
+  maxConnections: number | null;
+  scope: {
+    pages: "target";
+    connections: "process";
+  };
+  experimental: boolean;
+  /** Present only for an experimental preset. */
+  verification?: typeof UNVERIFIED_NOTE;
+}
+/** What the runner actually enforces, so the effective limit is not overstated. */
+interface RemoteSizingEnforced {
+  /** The shared page gate of the target; its size is the effective page limit. */
+  gate?: {
+    readonly size: number;
+  } | undefined;
+  /** The run's configured page concurrency, when set. */
+  concurrency?: number | undefined;
+  /** Whether the runner applies `maxPagesPerConnection` (default true). */
+  pagesPerConnection?: boolean | undefined;
+}
+/** The configured and effective limits of `remote`, as far as the runner enforces them. */
+declare function remoteSizingOf(target: CaptureTarget, remote: RemoteBrowser, enforced?: RemoteSizingEnforced): RemoteSizing;
+/** Log the limits at run start, before any connection is attempted. */
+declare function logRemoteSizing(logger: {
+  info(fields: object, message: string): void;
+} | undefined, target: CaptureTarget, remote: RemoteBrowser, enforced?: RemoteSizingEnforced): void;
+export { RemoteSizing, RemoteSizingEnforced, UNVERIFIED_NOTE, logRemoteSizing, remoteSizingOf };
+//# sourceMappingURL=remote-sizing.d.mts.map

package/dist/adapters/remote-sizing.mjs

@@ -0,0 +1,53 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/adapters/remote-sizing.ts
+/** Said of every experimental preset until someone verifies it against the provider. */
+const UNVERIFIED_NOTE = "not verified against live infrastructure";
+/** The configured and effective limits of `remote`, as far as the runner enforces them. */
+function remoteSizingOf(target, remote, enforced = {}) {
+	const pages = enforced.gate === void 0 ? pagesOf(remote) : gatePagesOf(enforced.gate);
+	const perConnection = remote.maxPagesPerConnection ?? null;
+	const limits = [
+		pages,
+		enforced.pagesPerConnection === false ? null : perConnection,
+		enforced.concurrency ?? null
+	].filter((value) => value !== null);
+	return {
+		target,
+		pages,
+		pagesPerConnection: perConnection,
+		effectivePagesPerConnection: limits.length === 0 ? null : Math.min(...limits),
+		maxConnections: remote.maxConnections ?? null,
+		scope: {
+			pages: "target",
+			connections: "process"
+		},
+		experimental: remote.experimental === true,
+		...remote.experimental === true ? { verification: UNVERIFIED_NOTE } : {}
+	};
+}
+/** Log the limits at run start, before any connection is attempted. */
+function logRemoteSizing(logger, target, remote, enforced) {
+	logger?.info(remoteSizingOf(target, remote, enforced), "remote sizing");
+}
+/** The shared gate's cap; a `sessions` callback that throws reads as unknown. */
+function gatePagesOf(gate) {
+	try {
+		return gate.size;
+	} catch {
+		return null;
+	}
+}
+/** The page limit now; a `sessions` function that throws or returns nonsense reads as unknown. */
+function pagesOf(remote) {
+	try {
+		const value = typeof remote.sessions === "function" ? remote.sessions() : remote.sessions;
+		return Number.isInteger(value) && value > 0 ? value : null;
+	} catch {
+		return null;
+	}
+}
+export { UNVERIFIED_NOTE, logRemoteSizing, remoteSizingOf };
+
+//# sourceMappingURL=remote-sizing.mjs.map

package/dist/adapters/remote-sizing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-sizing.mjs","names":[],"sources":["../../src/adapters/remote-sizing.ts"],"sourcesContent":["/** What a remote target may open, for the run's log (ADR 0007, decision 4): limits only, no endpoints. */\nimport type { CaptureTarget } from \"./capture-target.ts\";\nimport type { RemoteBrowser } from \"./remote-browser.ts\";\n\n/** Said of every experimental preset until someone verifies it against the provider. */\nexport const UNVERIFIED_NOTE = \"not verified against live infrastructure\";\n\n/** The loggable limits of one remote target. A `null` limit is not capped. */\nexport interface RemoteSizing {\n  target: CaptureTarget;\n  /** Pages the plan allows at once: the target's page gate. Per target, per process. */\n  pages: number | null;\n  /** Pages on one connection, when capped. */\n  pagesPerConnection: number | null;\n  /** Pages one connection can hold: the lowest of `pages`, `pagesPerConnection` (when the runner enforces it) and the run's `concurrency`. */\n  effectivePagesPerConnection: number | null;\n  /** Connections this process holds at once, when capped. Per process. */\n  maxConnections: number | null;\n  scope: { pages: \"target\"; connections: \"process\" };\n  experimental: boolean;\n  /** Present only for an experimental preset. */\n  verification?: typeof UNVERIFIED_NOTE;\n}\n\n/** What the runner actually enforces, so the effective limit is not overstated. */\nexport interface RemoteSizingEnforced {\n  /** The shared page gate of the target; its size is the effective page limit. */\n  gate?: { readonly size: number } | undefined;\n  /** The run's configured page concurrency, when set. */\n  concurrency?: number | undefined;\n  /** Whether the runner applies `maxPagesPerConnection` (default true). */\n  pagesPerConnection?: boolean | undefined;\n}\n\n/** The configured and effective limits of `remote`, as far as the runner enforces them. */\nexport function remoteSizingOf(\n  target: CaptureTarget,\n  remote: RemoteBrowser,\n  enforced: RemoteSizingEnforced = {},\n): RemoteSizing {\n  const pages = enforced.gate === undefined ? pagesOf(remote) : gatePagesOf(enforced.gate);\n  const perConnection = remote.maxPagesPerConnection ?? null;\n  const limits = [\n    pages,\n    enforced.pagesPerConnection === false ? null : perConnection,\n    enforced.concurrency ?? null,\n  ].filter((value): value is number => value !== null);\n  return {\n    target,\n    pages,\n    pagesPerConnection: perConnection,\n    effectivePagesPerConnection: limits.length === 0 ? null : Math.min(...limits),\n    maxConnections: remote.maxConnections ?? null,\n    scope: { pages: \"target\", connections: \"process\" },\n    experimental: remote.experimental === true,\n    ...(remote.experimental === true ? { verification: UNVERIFIED_NOTE } : {}),\n  };\n}\n\n/** Log the limits at run start, before any connection is attempted. */\nexport function logRemoteSizing(\n  logger: { info(fields: object, message: string): void } | undefined,\n  target: CaptureTarget,\n  remote: RemoteBrowser,\n  enforced?: RemoteSizingEnforced,\n): void {\n  logger?.info(remoteSizingOf(target, remote, enforced), \"remote sizing\");\n}\n\n/** The shared gate's cap; a `sessions` callback that throws reads as unknown. */\nfunction gatePagesOf(gate: { readonly size: number }): number | null {\n  try {\n    return gate.size;\n  } catch {\n    return null;\n  }\n}\n\n/** The page limit now; a `sessions` function that throws or returns nonsense reads as unknown. */\nfunction pagesOf(remote: RemoteBrowser): number | null {\n  try {\n    const value = typeof remote.sessions === \"function\" ? remote.sessions() : remote.sessions;\n    return Number.isInteger(value) && value > 0 ? value : null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;AAKA,MAAa,kBAAkB;;AA8B/B,SAAgB,eACd,QACA,QACA,WAAiC,CAAC,GACpB;CACd,MAAM,QAAQ,SAAS,SAAS,KAAA,IAAY,QAAQ,MAAM,IAAI,YAAY,SAAS,IAAI;CACvF,MAAM,gBAAgB,OAAO,yBAAyB;CACtD,MAAM,SAAS;EACb;EACA,SAAS,uBAAuB,QAAQ,OAAO;EAC/C,SAAS,eAAe;CAC1B,CAAC,CAAC,QAAQ,UAA2B,UAAU,IAAI;CACnD,OAAO;EACL;EACA;EACA,oBAAoB;EACpB,6BAA6B,OAAO,WAAW,IAAI,OAAO,KAAK,IAAI,GAAG,MAAM;EAC5E,gBAAgB,OAAO,kBAAkB;EACzC,OAAO;GAAE,OAAO;GAAU,aAAa;EAAU;EACjD,cAAc,OAAO,iBAAiB;EACtC,GAAI,OAAO,iBAAiB,OAAO,EAAE,cAAc,gBAAgB,IAAI,CAAC;CAC1E;AACF;;AAGA,SAAgB,gBACd,QACA,QACA,QACA,UACM;CACN,QAAQ,KAAK,eAAe,QAAQ,QAAQ,QAAQ,GAAG,eAAe;AACxE;;AAGA,SAAS,YAAY,MAAgD;CACnE,IAAI;EACF,OAAO,KAAK;CACd,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,SAAS,QAAQ,QAAsC;CACrD,IAAI;EACF,MAAM,QAAQ,OAAO,OAAO,aAAa,aAAa,OAAO,SAAS,IAAI,OAAO;EACjF,OAAO,OAAO,UAAU,KAAK,KAAK,QAAQ,IAAI,QAAQ;CACxD,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/adapters/render-runs.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/adapters/render-runs.d.ts
 /** In-flight render calls of a capture runner, so `cancel` reaches exactly the runs it names. */
 /**
  * Every render call a runner has in flight, by build and run id.
@@ -20,6 +19,5 @@ declare class RenderRuns<T> {
   /** The runs `cancel(buildId, runId)` should stop: every run of the build without a run id. */
   matching(buildId: string, runId?: string): T[];
 }
-//#endregion
 export { RenderRuns };
 //# sourceMappingURL=render-runs.d.mts.map

package/dist/adapters/render-runs.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/adapters/render-runs.ts
+// src/adapters/render-runs.ts
 /** In-flight render calls of a capture runner, so `cancel` reaches exactly the runs it names. */
 /**
 * Every render call a runner has in flight, by build and run id.
@@ -35,7 +35,6 @@ var RenderRuns = class {
 		return [...this.#byBuild.get(buildId) ?? []].filter((entry) => runId === void 0 || entry.runId === runId).map((e) => e.run);
 	}
 };
-//#endregion
 export { RenderRuns };
 
 //# sourceMappingURL=render-runs.mjs.map

package/dist/adapters/setup-runner.d.mts

@@ -3,7 +3,6 @@ import __tsdown_shims_url from 'node:url';
 import { AdapterSetupContext } from "../adapter/metadata.mjs";
 import { AdapterSetupResult, AdapterSetupSources, HookEntry } from "../adapter/setup.mjs";
 import { Logger } from "pino";
-//#region src/adapters/setup-runner.d.ts
 /** Collect every available `setup` hook in deterministic order. */
 declare function collectSetups(sources: AdapterSetupSources): HookEntry[];
 /** Collect every available `teardown` hook in deterministic order. */
@@ -18,6 +17,5 @@ declare function bindAdapterLoggers(sources: AdapterSetupSources, logger: Logger
 declare function runAdapterSetups(entries: HookEntry[], ctx: AdapterSetupContext, logger: Logger): Promise<AdapterSetupResult>;
 /** Run teardown hooks concurrently; failures are collected, never thrown. */
 declare function runAdapterTeardowns(entries: HookEntry[], ctx: AdapterSetupContext, logger: Logger): Promise<AdapterSetupResult>;
-//#endregion
 export { bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns };
 //# sourceMappingURL=setup-runner.d.mts.map

package/dist/adapters/setup-runner.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { sanitizeErrorText } from "../utils/redact.mjs";
-//#region src/adapters/setup-runner.ts
+// src/adapters/setup-runner.ts
 function hookEntry(adapter, hook) {
 	const lifecycle = adapter.lifecycle;
 	if (!lifecycle) return null;
@@ -141,7 +141,6 @@ async function runAdapterSetups(entries, ctx, logger) {
 async function runAdapterTeardowns(entries, ctx, logger) {
 	return await runHooks(entries, ctx, logger, "teardown", SLOW_TEARDOWN_MS);
 }
-//#endregion
 export { bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns };
 
 //# sourceMappingURL=setup-runner.mjs.map

package/dist/adapters/sources.d.mts

@@ -2,11 +2,9 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { ShelfOptions } from "../config.mjs";
 import { AdapterSetupSources } from "../adapter/setup.mjs";
-//#region src/adapters/sources.d.ts
 /** The adapter slots of `options`, with `auth` carried along for boot validation. */
 declare function adapterSourcesOf(options: ShelfOptions): AdapterSetupSources & {
   auth?: unknown;
 };
-//#endregion
 export { adapterSourcesOf };
 //# sourceMappingURL=sources.d.mts.map

package/dist/adapters/sources.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/adapters/sources.ts
+// src/adapters/sources.ts
 /** The adapter slots of `options`, with `auth` carried along for boot validation. */
 function adapterSourcesOf(options) {
 	return {
@@ -14,7 +14,6 @@ function adapterSourcesOf(options) {
 		auth: options.auth
 	};
 }
-//#endregion
 export { adapterSourcesOf };
 
 //# sourceMappingURL=sources.mjs.map

package/dist/adapters/validate.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { AdapterSetupFailure, AdapterSetupSources } from "../adapter/setup.mjs";
-//#region src/adapters/validate.d.ts
 /**
  * Validate one adapter against its slot. Returns human-readable reasons
  * (empty when valid). Never throws — callers decide fail-fast vs collect.
@@ -25,6 +24,5 @@ declare function validateAdapterSources(sources: AdapterSetupSources): AdapterSe
 declare function validateBootAssembly(sources: AdapterSetupSources & {
   auth?: unknown;
 }): AdapterSetupFailure[];
-//#endregion
 export { validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly };
 //# sourceMappingURL=validate.d.mts.map