@warlock.js/core 4.4.0 → 4.6.0

package/esm/storage/utils/contain-path.d.mts

@@ -0,0 +1,23 @@
+//#region ../@warlock.js/core/src/storage/utils/contain-path.d.ts
+/**
+ * Resolve `location` against `root` and assert the result stays *inside*
+ * `root` — the local-storage path-traversal guard.
+ *
+ * Without this, a `location` like `../../etc/passwd`, `..\..\windows\...`,
+ * an absolute path (`/etc/passwd`, `C:\secret`), or a prefix breakout could
+ * escape the configured storage root and read or clobber arbitrary files on
+ * the host.
+ *
+ * The check compares the relative path from `root` to the resolved target:
+ * if it climbs out (`..` prefix) or is itself absolute (different drive /
+ * root on Windows), the location is rejected.
+ *
+ * @param root - Absolute, normalized storage root.
+ * @param location - Caller-supplied (already prefix-applied) location.
+ * @returns The absolute, contained filesystem path.
+ * @throws {StorageError} When the location escapes `root`.
+ */
+declare function resolveWithinRoot(root: string, location: string): string;
+//#endregion
+export { resolveWithinRoot };
+//# sourceMappingURL=contain-path.d.mts.map

package/esm/storage/utils/contain-path.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contain-path.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/core/src/storage/utils/contain-path.ts"],"mappings":";;AAqBA;;;;AAAgE;;;;;;;;;;;;;iBAAhD,iBAAA,CAAkB,IAAA,UAAc,QAAgB"}

package/esm/storage/utils/contain-path.mjs

@@ -0,0 +1,35 @@
+import { StorageError } from "./storage-error.mjs";
+import path from "path";
+
+//#region ../@warlock.js/core/src/storage/utils/contain-path.ts
+/**
+* Resolve `location` against `root` and assert the result stays *inside*
+* `root` — the local-storage path-traversal guard.
+*
+* Without this, a `location` like `../../etc/passwd`, `..\..\windows\...`,
+* an absolute path (`/etc/passwd`, `C:\secret`), or a prefix breakout could
+* escape the configured storage root and read or clobber arbitrary files on
+* the host.
+*
+* The check compares the relative path from `root` to the resolved target:
+* if it climbs out (`..` prefix) or is itself absolute (different drive /
+* root on Windows), the location is rejected.
+*
+* @param root - Absolute, normalized storage root.
+* @param location - Caller-supplied (already prefix-applied) location.
+* @returns The absolute, contained filesystem path.
+* @throws {StorageError} When the location escapes `root`.
+*/
+function resolveWithinRoot(root, location) {
+	const resolved = path.resolve(root, location);
+	const rel = path.relative(root, resolved);
+	if (rel !== "" && (rel.startsWith("..") || path.isAbsolute(rel))) throw new StorageError(`Storage location escapes the storage root: "${location}"`, { context: {
+		location,
+		root
+	} });
+	return resolved;
+}
+
+//#endregion
+export { resolveWithinRoot };
+//# sourceMappingURL=contain-path.mjs.map

package/esm/storage/utils/contain-path.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contain-path.mjs","names":[],"sources":["../../../../../../../../@warlock.js/core/src/storage/utils/contain-path.ts"],"sourcesContent":["import path from \"path\";\nimport { StorageError } from \"./storage-error\";\n\n/**\n * Resolve `location` against `root` and assert the result stays *inside*\n * `root` — the local-storage path-traversal guard.\n *\n * Without this, a `location` like `../../etc/passwd`, `..\\..\\windows\\...`,\n * an absolute path (`/etc/passwd`, `C:\\secret`), or a prefix breakout could\n * escape the configured storage root and read or clobber arbitrary files on\n * the host.\n *\n * The check compares the relative path from `root` to the resolved target:\n * if it climbs out (`..` prefix) or is itself absolute (different drive /\n * root on Windows), the location is rejected.\n *\n * @param root - Absolute, normalized storage root.\n * @param location - Caller-supplied (already prefix-applied) location.\n * @returns The absolute, contained filesystem path.\n * @throws {StorageError} When the location escapes `root`.\n */\nexport function resolveWithinRoot(root: string, location: string): string {\n  const resolved = path.resolve(root, location);\n  const rel = path.relative(root, resolved);\n\n  if (rel !== \"\" && (rel.startsWith(\"..\") || path.isAbsolute(rel))) {\n    throw new StorageError(\n      `Storage location escapes the storage root: \"${location}\"`,\n      { context: { location, root } },\n    );\n  }\n\n  return resolved;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,kBAAkB,MAAc,UAA0B;CACxE,MAAM,WAAW,KAAK,QAAQ,MAAM,QAAQ;CAC5C,MAAM,MAAM,KAAK,SAAS,MAAM,QAAQ;CAExC,IAAI,QAAQ,OAAO,IAAI,WAAW,IAAI,KAAK,KAAK,WAAW,GAAG,IAC5D,MAAM,IAAI,aACR,+CAA+C,SAAS,IACxD,EAAE,SAAS;EAAE;EAAU;CAAK,EAAE,CAChC;CAGF,OAAO;AACT"}

package/esm/storage/utils/safe-fetch.d.mts

@@ -0,0 +1,68 @@
+//#region ../@warlock.js/core/src/storage/utils/safe-fetch.d.ts
+/**
+ * Options controlling a guarded outbound fetch. Every field is optional;
+ * {@link resolveFetchPolicy} fills safe defaults. The defaults are
+ * deliberately strict (https+http, private-IP deny ON, 30s timeout,
+ * 50 MiB cap) so a caller that does not tune them still gets a hardened
+ * request.
+ */
+type SafeFetchOptions = {
+  /**
+   * Whether to ALLOW private / loopback / link-local / metadata hosts.
+   * Default `false` — the SSRF guard is on (private hosts are denied).
+   */
+  allowPrivateHosts?: boolean;
+  /**
+   * Maximum response body size in bytes. A declared `content-length` over
+   * this fails fast; otherwise the body is read with a running cap and the
+   * stream is aborted on overflow. Default `52_428_800` (50 MiB).
+   */
+  maxBytes?: number; /** Per-request timeout in milliseconds. Default `30_000`. */
+  timeoutMs?: number;
+  /**
+   * URL schemes permitted for the request, compared case-insensitively.
+   * Default `["https", "http"]`.
+   */
+  allowedSchemes?: string[];
+  /**
+   * Injected `fetch` implementation (for tests or proxies). Defaults to the
+   * global `fetch`.
+   */
+  fetch?: typeof fetch;
+};
+/**
+ * True when `ip` is a private, loopback, link-local, unique-local,
+ * carrier-grade-NAT, unspecified, or otherwise non-public address — the set
+ * an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including
+ * IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns
+ * `false` (the caller resolves hostnames via DNS first).
+ *
+ * The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4
+ * link-local range `169.254.0.0/16`.
+ */
+declare function isPrivateOrReservedIp(ip: string): boolean;
+/**
+ * Result of {@link safeFetchToBuffer}: the (capped) body plus the response's
+ * content-type, so callers can derive a MIME type and enforce a non-empty
+ * content-type check.
+ */
+type SafeFetchResult = {
+  buffer: Buffer;
+  contentType: string | null;
+  status: number;
+  statusText: string;
+  ok: boolean;
+};
+/**
+ * SSRF-guarded download: validates the URL (scheme allowlist + post-DNS
+ * private-IP deny), performs the request with a timeout via
+ * `AbortController`, then streams the body with a hard byte cap — aborting
+ * the moment the running total exceeds `maxBytes`. A declared
+ * `content-length` over the cap fails fast.
+ *
+ * @throws {StorageError} On a blocked URL, timeout, or oversized body.
+ */
+declare function safeFetchToBuffer(rawUrl: string, options?: SafeFetchOptions): Promise<SafeFetchResult>;
+//#endregion
+export { SafeFetchOptions, SafeFetchResult, isPrivateOrReservedIp, safeFetchToBuffer };
+//# sourceMappingURL=safe-fetch.d.mts.map

package/esm/storage/utils/safe-fetch.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-fetch.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/core/src/storage/utils/safe-fetch.ts"],"mappings":";;AA0BA;;;;;;KAAY,gBAAA;EAkBV;;;;EAbA,iBAAA;EA2Hc;;;;AAAgC;EArH9C,QAAA,WAgNyB;EA9MzB,SAAA;EA+Mc;;;;EA1Md,cAAA;EA6MA;;;AACE;EAzMF,KAAA,UAAe,KAAK;AAAA;;;;;;;;;;;iBAyGN,qBAAA,CAAsB,EAAU;;AA+GtB;;;;KApBd,eAAA;EACV,MAAA,EAAQ,MAAM;EACd,WAAA;EACA,MAAA;EACA,UAAA;EACA,EAAA;AAAA;;;;;;;;;;iBAYoB,iBAAA,CACpB,MAAA,UACA,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA"}

package/esm/storage/utils/safe-fetch.mjs

@@ -0,0 +1,205 @@
+import { StorageError } from "./storage-error.mjs";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+//#region ../@warlock.js/core/src/storage/utils/safe-fetch.ts
+/**
+* SSRF / resource-exhaustion guard for storage's outbound downloads
+* (`putFromUrl`).
+*
+* NOTE: this MIRRORS `@warlock.js/ai`'s `src/security/private-ip.ts` and
+* `src/security/outbound-policy.ts`. It is duplicated here intentionally
+* because `@warlock.js/core` cannot depend on `@warlock.js/ai`. Pending
+* extraction of a shared security package, keep the two copies in sync.
+*/
+/** 50 MiB — default cap on a downloaded body (storage files run larger than AI payloads). */
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+/** 30s — default per-request timeout. */
+const DEFAULT_TIMEOUT_MS = 3e4;
+/**
+* Fill a {@link SafeFetchOptions} with strict defaults: https+http,
+* private-IP deny on, 30s timeout, 50 MiB cap, global `fetch`.
+*/
+function resolveFetchPolicy(options = {}) {
+	return {
+		allowPrivateHosts: options.allowPrivateHosts ?? false,
+		maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+		timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		allowedSchemes: options.allowedSchemes ?? ["https", "http"],
+		fetch: options.fetch ?? globalThis.fetch
+	};
+}
+/** Parse a dotted-quad into four octets, or `null` if malformed. */
+function parseIpv4(ip) {
+	const parts = ip.split(".");
+	if (parts.length !== 4) return null;
+	const octets = parts.map((part) => Number(part));
+	if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+	return octets;
+}
+function isPrivateIpv4(ip) {
+	const octets = parseIpv4(ip);
+	if (!octets) return true;
+	const [a, b] = octets;
+	return a === 0 || a === 10 || a === 127 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 192 && b === 0 || a === 198 && (b === 18 || b === 19) || a === 198 && b === 51 || a === 203 && b === 0 || a >= 224;
+}
+function isPrivateIpv6(ip) {
+	const normalized = ip.toLowerCase().split("%")[0];
+	const v4 = normalized.match(/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+	if (v4) return isPrivateIpv4(v4[1]);
+	if (normalized === "::1" || normalized === "::") return true;
+	const firstGroup = normalized.split(":")[0];
+	const head = firstGroup === "" ? 0 : Number.parseInt(firstGroup, 16);
+	if ((head & 65024) === 64512) return true;
+	if ((head & 65472) === 65152) return true;
+	return false;
+}
+/**
+* True when `ip` is a private, loopback, link-local, unique-local,
+* carrier-grade-NAT, unspecified, or otherwise non-public address — the set
+* an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including
+* IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns
+* `false` (the caller resolves hostnames via DNS first).
+*
+* The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4
+* link-local range `169.254.0.0/16`.
+*/
+function isPrivateOrReservedIp(ip) {
+	const family = isIP(ip);
+	if (family === 4) return isPrivateIpv4(ip);
+	if (family === 6) return isPrivateIpv6(ip);
+	return false;
+}
+/** Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. */
+function stripBrackets(host) {
+	return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+/**
+* Reject when `host` is — or resolves to — a private / reserved address.
+* IP literals are checked directly; hostnames are resolved via DNS and every
+* returned address is checked (a public name pointing inward is caught). A
+* resolution failure fails closed.
+*/
+async function assertHostNotPrivate(host, rawUrl) {
+	if (isIP(host) !== 0) {
+		if (isPrivateOrReservedIp(host)) throw new StorageError(`outbound request blocked — "${host}" is a private/reserved address`, { context: {
+			url: rawUrl,
+			address: host
+		} });
+		return;
+	}
+	let addresses;
+	try {
+		addresses = await lookup(host, { all: true });
+	} catch (cause) {
+		throw new StorageError(`outbound request blocked — could not resolve host "${host}" to verify it is public`, {
+			cause,
+			context: {
+				url: rawUrl,
+				host
+			}
+		});
+	}
+	for (const { address } of addresses) if (isPrivateOrReservedIp(address)) throw new StorageError(`outbound request blocked — host "${host}" resolves to a private/reserved address (${address})`, { context: {
+		url: rawUrl,
+		host,
+		address
+	} });
+}
+/**
+* Validate a URL against the policy BEFORE any network call: scheme
+* allowlist and (when private hosts are not allowed) a DNS resolution that
+* rejects private / loopback / link-local / metadata addresses — the SSRF
+* guard. Returns the parsed `URL` on success; throws {@link StorageError}
+* otherwise.
+*/
+async function assertUrlAllowed(rawUrl, policy) {
+	let url;
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		throw new StorageError(`outbound request blocked — invalid URL: ${rawUrl}`, { context: { url: rawUrl } });
+	}
+	const scheme = url.protocol.replace(/:$/, "").toLowerCase();
+	if (!policy.allowedSchemes.some((s) => s.toLowerCase() === scheme)) throw new StorageError(`outbound request blocked — scheme "${scheme}" is not allowed (allowed: ${policy.allowedSchemes.join(", ")})`, { context: {
+		url: rawUrl,
+		scheme
+	} });
+	if (!policy.allowPrivateHosts) await assertHostNotPrivate(stripBrackets(url.hostname), rawUrl);
+	return url;
+}
+/**
+* SSRF-guarded download: validates the URL (scheme allowlist + post-DNS
+* private-IP deny), performs the request with a timeout via
+* `AbortController`, then streams the body with a hard byte cap — aborting
+* the moment the running total exceeds `maxBytes`. A declared
+* `content-length` over the cap fails fast.
+*
+* @throws {StorageError} On a blocked URL, timeout, or oversized body.
+*/
+async function safeFetchToBuffer(rawUrl, options = {}) {
+	const policy = resolveFetchPolicy(options);
+	const url = await assertUrlAllowed(rawUrl, policy);
+	const controller = new AbortController();
+	const timer = setTimeout(() => {
+		controller.abort(new StorageError(`outbound request timed out after ${policy.timeoutMs}ms`, { context: {
+			url: rawUrl,
+			timeoutMs: policy.timeoutMs
+		} }));
+	}, policy.timeoutMs);
+	try {
+		const response = await policy.fetch(url, { signal: controller.signal });
+		const declared = Number(response.headers.get("content-length"));
+		if (Number.isFinite(declared) && declared > policy.maxBytes) throw new StorageError(`outbound response body too large — declared ${declared} bytes exceeds the ${policy.maxBytes}-byte cap`, { context: {
+			url: rawUrl,
+			declared,
+			maxBytes: policy.maxBytes
+		} });
+		return {
+			buffer: await readBodyCapped(response, policy.maxBytes, rawUrl),
+			contentType: response.headers.get("content-type"),
+			status: response.status,
+			statusText: response.statusText,
+			ok: response.ok
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Read a response body into a Buffer with a hard byte cap. The stream is
+* read chunk-by-chunk and cancelled the moment the running total exceeds
+* `maxBytes`. Throws {@link StorageError} on overflow.
+*/
+async function readBodyCapped(response, maxBytes, rawUrl) {
+	if (!response.body) {
+		const arrayBuffer = await response.arrayBuffer();
+		if (arrayBuffer.byteLength > maxBytes) throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, { context: {
+			url: rawUrl,
+			maxBytes
+		} });
+		return Buffer.from(arrayBuffer);
+	}
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (!value) continue;
+		total += value.byteLength;
+		if (total > maxBytes) {
+			await reader.cancel();
+			throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, { context: {
+				url: rawUrl,
+				maxBytes
+			} });
+		}
+		chunks.push(value);
+	}
+	return Buffer.concat(chunks);
+}
+
+//#endregion
+export { isPrivateOrReservedIp, safeFetchToBuffer };
+//# sourceMappingURL=safe-fetch.mjs.map

package/esm/storage/utils/safe-fetch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-fetch.mjs","names":[],"sources":["../../../../../../../../@warlock.js/core/src/storage/utils/safe-fetch.ts"],"sourcesContent":["import { lookup } from \"node:dns/promises\";\nimport { isIP } from \"node:net\";\nimport { StorageError } from \"./storage-error\";\n\n/**\n * SSRF / resource-exhaustion guard for storage's outbound downloads\n * (`putFromUrl`).\n *\n * NOTE: this MIRRORS `@warlock.js/ai`'s `src/security/private-ip.ts` and\n * `src/security/outbound-policy.ts`. It is duplicated here intentionally\n * because `@warlock.js/core` cannot depend on `@warlock.js/ai`. Pending\n * extraction of a shared security package, keep the two copies in sync.\n */\n\n/** 50 MiB — default cap on a downloaded body (storage files run larger than AI payloads). */\nconst DEFAULT_MAX_BYTES = 50 * 1024 * 1024;\n/** 30s — default per-request timeout. */\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\n/**\n * Options controlling a guarded outbound fetch. Every field is optional;\n * {@link resolveFetchPolicy} fills safe defaults. The defaults are\n * deliberately strict (https+http, private-IP deny ON, 30s timeout,\n * 50 MiB cap) so a caller that does not tune them still gets a hardened\n * request.\n */\nexport type SafeFetchOptions = {\n  /**\n   * Whether to ALLOW private / loopback / link-local / metadata hosts.\n   * Default `false` — the SSRF guard is on (private hosts are denied).\n   */\n  allowPrivateHosts?: boolean;\n  /**\n   * Maximum response body size in bytes. A declared `content-length` over\n   * this fails fast; otherwise the body is read with a running cap and the\n   * stream is aborted on overflow. Default `52_428_800` (50 MiB).\n   */\n  maxBytes?: number;\n  /** Per-request timeout in milliseconds. Default `30_000`. */\n  timeoutMs?: number;\n  /**\n   * URL schemes permitted for the request, compared case-insensitively.\n   * Default `[\"https\", \"http\"]`.\n   */\n  allowedSchemes?: string[];\n  /**\n   * Injected `fetch` implementation (for tests or proxies). Defaults to the\n   * global `fetch`.\n   */\n  fetch?: typeof fetch;\n};\n\n/** {@link SafeFetchOptions} with every default resolved — never partial. */\ntype ResolvedFetchPolicy = {\n  allowPrivateHosts: boolean;\n  maxBytes: number;\n  timeoutMs: number;\n  allowedSchemes: string[];\n  fetch: typeof fetch;\n};\n\n/**\n * Fill a {@link SafeFetchOptions} with strict defaults: https+http,\n * private-IP deny on, 30s timeout, 50 MiB cap, global `fetch`.\n */\nfunction resolveFetchPolicy(options: SafeFetchOptions = {}): ResolvedFetchPolicy {\n  return {\n    allowPrivateHosts: options.allowPrivateHosts ?? false,\n    maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,\n    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    allowedSchemes: options.allowedSchemes ?? [\"https\", \"http\"],\n    fetch: options.fetch ?? globalThis.fetch,\n  };\n}\n\n/** Parse a dotted-quad into four octets, or `null` if malformed. */\nfunction parseIpv4(ip: string): [number, number, number, number] | null {\n  const parts = ip.split(\".\");\n  if (parts.length !== 4) {\n    return null;\n  }\n\n  const octets = parts.map((part) => Number(part));\n  if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) {\n    return null;\n  }\n\n  return octets as [number, number, number, number];\n}\n\nfunction isPrivateIpv4(ip: string): boolean {\n  const octets = parseIpv4(ip);\n  if (!octets) {\n    return true; // unparseable → refuse, fail closed\n  }\n\n  const [a, b] = octets;\n\n  return (\n    a === 0 || // 0.0.0.0/8 \"this network\"\n    a === 10 || // 10.0.0.0/8 private\n    a === 127 || // 127.0.0.0/8 loopback\n    (a === 100 && b >= 64 && b <= 127) || // 100.64.0.0/10 CGNAT\n    (a === 169 && b === 254) || // 169.254.0.0/16 link-local + metadata\n    (a === 172 && b >= 16 && b <= 31) || // 172.16.0.0/12 private\n    (a === 192 && b === 168) || // 192.168.0.0/16 private\n    (a === 192 && b === 0) || // 192.0.0.0/24 + 192.0.2.0/24 (IETF/test)\n    (a === 198 && (b === 18 || b === 19)) || // 198.18.0.0/15 benchmarking\n    (a === 198 && b === 51) || // 198.51.100.0/24 test-net-2\n    (a === 203 && b === 0) || // 203.0.113.0/24 test-net-3\n    a >= 224 // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + 255.255.255.255\n  );\n}\n\nfunction isPrivateIpv6(ip: string): boolean {\n  const normalized = ip.toLowerCase().split(\"%\")[0]; // drop zone id\n\n  // IPv4-mapped / -embedded (::ffff:a.b.c.d, ::a.b.c.d) — defer to the v4\n  // check on the trailing dotted-quad so an inward-mapped address is caught.\n  const v4 = normalized.match(/(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$/);\n  if (v4) {\n    return isPrivateIpv4(v4[1]);\n  }\n\n  if (normalized === \"::1\" || normalized === \"::\") {\n    return true; // loopback / unspecified\n  }\n\n  // Expand only the leading group enough to classify the reserved blocks.\n  const firstGroup = normalized.split(\":\")[0];\n  const head = firstGroup === \"\" ? 0 : Number.parseInt(firstGroup, 16);\n\n  // fc00::/7 unique-local (fc.. / fd..)\n  if ((head & 0xfe00) === 0xfc00) {\n    return true;\n  }\n  // fe80::/10 link-local\n  if ((head & 0xffc0) === 0xfe80) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * True when `ip` is a private, loopback, link-local, unique-local,\n * carrier-grade-NAT, unspecified, or otherwise non-public address — the set\n * an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including\n * IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns\n * `false` (the caller resolves hostnames via DNS first).\n *\n * The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4\n * link-local range `169.254.0.0/16`.\n */\nexport function isPrivateOrReservedIp(ip: string): boolean {\n  const family = isIP(ip);\n  if (family === 4) {\n    return isPrivateIpv4(ip);\n  }\n  if (family === 6) {\n    return isPrivateIpv6(ip);\n  }\n  return false;\n}\n\n/** Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. */\nfunction stripBrackets(host: string): string {\n  return host.startsWith(\"[\") && host.endsWith(\"]\") ? host.slice(1, -1) : host;\n}\n\n/**\n * Reject when `host` is — or resolves to — a private / reserved address.\n * IP literals are checked directly; hostnames are resolved via DNS and every\n * returned address is checked (a public name pointing inward is caught). A\n * resolution failure fails closed.\n */\nasync function assertHostNotPrivate(host: string, rawUrl: string): Promise<void> {\n  if (isIP(host) !== 0) {\n    if (isPrivateOrReservedIp(host)) {\n      throw new StorageError(\n        `outbound request blocked — \"${host}\" is a private/reserved address`,\n        { context: { url: rawUrl, address: host } },\n      );\n    }\n    return;\n  }\n\n  let addresses: Array<{ address: string }>;\n  try {\n    addresses = await lookup(host, { all: true });\n  } catch (cause) {\n    throw new StorageError(\n      `outbound request blocked — could not resolve host \"${host}\" to verify it is public`,\n      { cause, context: { url: rawUrl, host } },\n    );\n  }\n\n  for (const { address } of addresses) {\n    if (isPrivateOrReservedIp(address)) {\n      throw new StorageError(\n        `outbound request blocked — host \"${host}\" resolves to a private/reserved address (${address})`,\n        { context: { url: rawUrl, host, address } },\n      );\n    }\n  }\n}\n\n/**\n * Validate a URL against the policy BEFORE any network call: scheme\n * allowlist and (when private hosts are not allowed) a DNS resolution that\n * rejects private / loopback / link-local / metadata addresses — the SSRF\n * guard. Returns the parsed `URL` on success; throws {@link StorageError}\n * otherwise.\n */\nasync function assertUrlAllowed(rawUrl: string, policy: ResolvedFetchPolicy): Promise<URL> {\n  let url: URL;\n  try {\n    url = new URL(rawUrl);\n  } catch {\n    throw new StorageError(`outbound request blocked — invalid URL: ${rawUrl}`, {\n      context: { url: rawUrl },\n    });\n  }\n\n  const scheme = url.protocol.replace(/:$/, \"\").toLowerCase();\n  if (!policy.allowedSchemes.some((s) => s.toLowerCase() === scheme)) {\n    throw new StorageError(\n      `outbound request blocked — scheme \"${scheme}\" is not allowed (allowed: ${policy.allowedSchemes.join(\", \")})`,\n      { context: { url: rawUrl, scheme } },\n    );\n  }\n\n  if (!policy.allowPrivateHosts) {\n    const host = stripBrackets(url.hostname);\n    await assertHostNotPrivate(host, rawUrl);\n  }\n\n  return url;\n}\n\n/**\n * Result of {@link safeFetchToBuffer}: the (capped) body plus the response's\n * content-type, so callers can derive a MIME type and enforce a non-empty\n * content-type check.\n */\nexport type SafeFetchResult = {\n  buffer: Buffer;\n  contentType: string | null;\n  status: number;\n  statusText: string;\n  ok: boolean;\n};\n\n/**\n * SSRF-guarded download: validates the URL (scheme allowlist + post-DNS\n * private-IP deny), performs the request with a timeout via\n * `AbortController`, then streams the body with a hard byte cap — aborting\n * the moment the running total exceeds `maxBytes`. A declared\n * `content-length` over the cap fails fast.\n *\n * @throws {StorageError} On a blocked URL, timeout, or oversized body.\n */\nexport async function safeFetchToBuffer(\n  rawUrl: string,\n  options: SafeFetchOptions = {},\n): Promise<SafeFetchResult> {\n  const policy = resolveFetchPolicy(options);\n  const url = await assertUrlAllowed(rawUrl, policy);\n\n  const controller = new AbortController();\n  const timer = setTimeout(() => {\n    controller.abort(\n      new StorageError(`outbound request timed out after ${policy.timeoutMs}ms`, {\n        context: { url: rawUrl, timeoutMs: policy.timeoutMs },\n      }),\n    );\n  }, policy.timeoutMs);\n\n  try {\n    const response = await policy.fetch(url, { signal: controller.signal });\n\n    const declared = Number(response.headers.get(\"content-length\"));\n    if (Number.isFinite(declared) && declared > policy.maxBytes) {\n      throw new StorageError(\n        `outbound response body too large — declared ${declared} bytes exceeds the ${policy.maxBytes}-byte cap`,\n        { context: { url: rawUrl, declared, maxBytes: policy.maxBytes } },\n      );\n    }\n\n    const buffer = await readBodyCapped(response, policy.maxBytes, rawUrl);\n\n    return {\n      buffer,\n      contentType: response.headers.get(\"content-type\"),\n      status: response.status,\n      statusText: response.statusText,\n      ok: response.ok,\n    };\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Read a response body into a Buffer with a hard byte cap. The stream is\n * read chunk-by-chunk and cancelled the moment the running total exceeds\n * `maxBytes`. Throws {@link StorageError} on overflow.\n */\nasync function readBodyCapped(\n  response: Response,\n  maxBytes: number,\n  rawUrl: string,\n): Promise<Buffer> {\n  if (!response.body) {\n    const arrayBuffer = await response.arrayBuffer();\n    if (arrayBuffer.byteLength > maxBytes) {\n      throw new StorageError(\n        `outbound response body exceeded the ${maxBytes}-byte cap`,\n        { context: { url: rawUrl, maxBytes } },\n      );\n    }\n    return Buffer.from(arrayBuffer);\n  }\n\n  const reader = response.body.getReader();\n  const chunks: Uint8Array[] = [];\n  let total = 0;\n\n  for (;;) {\n    const { done, value } = await reader.read();\n    if (done) {\n      break;\n    }\n    if (!value) {\n      continue;\n    }\n\n    total += value.byteLength;\n    if (total > maxBytes) {\n      await reader.cancel();\n      throw new StorageError(\n        `outbound response body exceeded the ${maxBytes}-byte cap`,\n        { context: { url: rawUrl, maxBytes } },\n      );\n    }\n    chunks.push(value);\n  }\n\n  return Buffer.concat(chunks);\n}\n"],"mappings":"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"}

package/esm/storage/utils/storage-error.d.mts

@@ -0,0 +1,35 @@
+//#region ../@warlock.js/core/src/storage/utils/storage-error.d.ts
+/**
+ * Base error for the storage subsystem.
+ *
+ * The storage drivers historically threw bare `Error`s. The security
+ * guards added to the local and cloud drivers (path-traversal containment,
+ * SSRF-guarded `putFromUrl`) need a named, catchable error so callers can
+ * branch on `instanceof StorageError` instead of string-matching messages.
+ *
+ * `context` is a free-form diagnostic bag (offending location, host, URL)
+ * mirroring the convention used by `@warlock.js/ai`'s error classes — it is
+ * for logs and telemetry, treated as opaque by consumers.
+ */
+type StorageErrorOptions = {
+  cause?: unknown;
+  context?: Record<string, unknown>;
+};
+/**
+ * Error thrown by storage drivers for refused or invalid operations
+ * (path-traversal attempts, blocked outbound fetches, oversized downloads).
+ */
+declare class StorageError extends Error {
+  /**
+   * Optional original thrown value preserved through re-wrapping.
+   */
+  readonly cause?: unknown;
+  /**
+   * Optional free-form diagnostic bag (location, host, url, …).
+   */
+  readonly context?: Record<string, unknown>;
+  constructor(message: string, options?: StorageErrorOptions);
+}
+//#endregion
+export { StorageError, StorageErrorOptions };
+//# sourceMappingURL=storage-error.d.mts.map

package/esm/storage/utils/storage-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-error.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/core/src/storage/utils/storage-error.ts"],"mappings":";;AAYA;;;;;;;;AAEkB;AAOlB;;KATY,mBAAA;EACV,KAAA;EACA,OAAA,GAAU,MAAM;AAAA;;;;;cAOL,YAAA,SAAqB,KAAA;EASN;;;EAAA,SALV,KAAA;EAOoB;;AAA6B;EAA7B,SAFpB,OAAA,GAAU,MAAA;cAEP,OAAA,UAAiB,OAAA,GAAU,mBAAA;AAAA"}

package/esm/storage/utils/storage-error.mjs

@@ -0,0 +1,17 @@
+//#region ../@warlock.js/core/src/storage/utils/storage-error.ts
+/**
+* Error thrown by storage drivers for refused or invalid operations
+* (path-traversal attempts, blocked outbound fetches, oversized downloads).
+*/
+var StorageError = class extends Error {
+	constructor(message, options) {
+		super(message);
+		this.name = "StorageError";
+		this.cause = options?.cause;
+		this.context = options?.context;
+	}
+};
+
+//#endregion
+export { StorageError };
+//# sourceMappingURL=storage-error.mjs.map

package/esm/storage/utils/storage-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-error.mjs","names":[],"sources":["../../../../../../../../@warlock.js/core/src/storage/utils/storage-error.ts"],"sourcesContent":["/**\n * Base error for the storage subsystem.\n *\n * The storage drivers historically threw bare `Error`s. The security\n * guards added to the local and cloud drivers (path-traversal containment,\n * SSRF-guarded `putFromUrl`) need a named, catchable error so callers can\n * branch on `instanceof StorageError` instead of string-matching messages.\n *\n * `context` is a free-form diagnostic bag (offending location, host, URL)\n * mirroring the convention used by `@warlock.js/ai`'s error classes — it is\n * for logs and telemetry, treated as opaque by consumers.\n */\nexport type StorageErrorOptions = {\n  cause?: unknown;\n  context?: Record<string, unknown>;\n};\n\n/**\n * Error thrown by storage drivers for refused or invalid operations\n * (path-traversal attempts, blocked outbound fetches, oversized downloads).\n */\nexport class StorageError extends Error {\n  /**\n   * Optional original thrown value preserved through re-wrapping.\n   */\n  public readonly cause?: unknown;\n\n  /**\n   * Optional free-form diagnostic bag (location, host, url, …).\n   */\n  public readonly context?: Record<string, unknown>;\n\n  public constructor(message: string, options?: StorageErrorOptions) {\n    super(message);\n    this.name = \"StorageError\";\n    this.cause = options?.cause;\n    this.context = options?.context;\n  }\n}\n"],"mappings":";;;;;AAqBA,IAAa,eAAb,cAAkC,MAAM;CAWtC,AAAO,YAAY,SAAiB,SAA+B;EACjE,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,QAAQ,SAAS;EACtB,KAAK,UAAU,SAAS;CAC1B;AACF"}

package/esm/use-cases/use-case-pipeline.mjs

@@ -31,7 +31,10 @@ async function runPipeline(opts) {
 		useCase: ucOnExecuting ? [ucOnExecuting] : void 0,
 		global: globalEventsCallbacksMap.onExecuting.length ? globalEventsCallbacksMap.onExecuting : void 0
 	});
-	if (guards) for (const guard of guards) await guard(Object.freeze(data), ctx);
+	if (guards) {
+		const frozenData = Object.freeze(Array.isArray(data) ? [...data] : { ...data });
+		for (const guard of guards) await guard(frozenData, ctx);
+	}
 	if (schema) {
 		const result = await v.validate(schema, data);
 		if (!result.isValid) throw new BadSchemaUseCaseError(result);

package/esm/use-cases/use-case-pipeline.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-case-pipeline.mjs","names":[],"sources":["../../../../../../../@warlock.js/core/src/use-cases/use-case-pipeline.ts"],"sourcesContent":["import type { ObjectValidator } from \"@warlock.js/seal\";\r\nimport { v } from \"@warlock.js/seal\";\r\nimport type {\r\n  UseCaseBeforeMiddleware,\r\n  UseCaseContext,\r\n  UseCaseGuard,\r\n  UseCaseOnExecutingContext,\r\n} from \"./types\";\r\nimport { fireLifecycleEvent, globalEventsCallbacksMap } from \"./use-case-events\";\r\nimport { BadSchemaUseCaseError } from \"./use-case.errors\";\r\n\r\nexport type PipelineOptions<Input> = {\r\n  name: string;\r\n  id: string;\r\n  data: Input;\r\n  ctx: UseCaseContext;\r\n  startedAt: Date;\r\n  schema?: ObjectValidator;\r\n  guards?: UseCaseGuard<Input>[];\r\n  before?: UseCaseBeforeMiddleware<Input>[];\r\n  /** Invocation-level onExecuting override */\r\n  onExecuting?: (ctx: UseCaseOnExecutingContext) => void;\r\n  /** Use-case-level onExecuting */\r\n  ucOnExecuting?: (ctx: UseCaseOnExecutingContext) => void;\r\n};\r\n\r\n/**\r\n * Runs the pre-handler pipeline in order:\r\n * onExecuting event → guards → validation → before middleware.\r\n *\r\n * Returns the validated, transformed data ready for the handler. The handler is\r\n * invoked by the caller so retry/benchmark can wrap it in isolation — keeping\r\n * guards, validation, and onExecuting from re-running on each retry attempt.\r\n *\r\n * Throws on guard failure or validation failure.\r\n *\r\n * @example\r\n * const data = await runPipeline({ name, id, data, ctx, startedAt, schema, guards, before });\r\n */\r\nexport async function runPipeline<Input>(opts: PipelineOptions<Input>): Promise<Input> {\r\n  const { name, id, ctx, startedAt, schema, guards, before, onExecuting, ucOnExecuting } = opts;\r\n  let data = opts.data;\r\n\r\n  await fireLifecycleEvent<UseCaseOnExecutingContext>(\r\n    { name, id, data, schema, ctx, startedAt },\r\n    {\r\n      invocation: onExecuting ? [onExecuting] : undefined,\r\n      useCase: ucOnExecuting ? [ucOnExecuting] : undefined,\r\n      global: globalEventsCallbacksMap.onExecuting.length\r\n        ? globalEventsCallbacksMap.onExecuting\r\n        : undefined,\r\n    },\r\n  );\r\n\r\n  if (guards) {\r\n    for (const guard of guards) {\r\n      await guard(Object.freeze(data) as Readonly<Input>, ctx);\r\n    }\r\n  }\r\n\r\n  if (schema) {\r\n    const result = await v.validate(schema, data);\r\n\r\n    if (!result.isValid) {\r\n      throw new BadSchemaUseCaseError(result);\r\n    }\r\n\r\n    data = result.data;\r\n  }\r\n\r\n  let transformed = data;\r\n\r\n  if (before) {\r\n    for (const middleware of before) {\r\n      transformed = await middleware(transformed, ctx);\r\n    }\r\n  }\r\n\r\n  return transformed;\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;AAuCA,eAAsB,YAAmB,MAA8C;CACrF,MAAM,EAAE,MAAM,IAAI,KAAK,WAAW,QAAQ,QAAQ,QAAQ,aAAa,kBAAkB;CACzF,IAAI,OAAO,KAAK;CAEhB,MAAM,mBACJ;EAAE;EAAM;EAAI;EAAM;EAAQ;EAAK;CAAU,GACzC;EACE,YAAY,cAAc,CAAC,WAAW,IAAI;EAC1C,SAAS,gBAAgB,CAAC,aAAa,IAAI;EAC3C,QAAQ,yBAAyB,YAAY,SACzC,yBAAyB,cACzB;CACN,CACF;CAEA,IAAI,QACF,KAAK,MAAM,SAAS,QAClB,MAAM,MAAM,OAAO,OAAO,IAAI,GAAsB,GAAG;CAI3D,IAAI,QAAQ;EACV,MAAM,SAAS,MAAM,EAAE,SAAS,QAAQ,IAAI;EAE5C,IAAI,CAAC,OAAO,SACV,MAAM,IAAI,sBAAsB,MAAM;EAGxC,OAAO,OAAO;CAChB;CAEA,IAAI,cAAc;CAElB,IAAI,QACF,KAAK,MAAM,cAAc,QACvB,cAAc,MAAM,WAAW,aAAa,GAAG;CAInD,OAAO;AACT"}
+{"version":3,"file":"use-case-pipeline.mjs","names":[],"sources":["../../../../../../../@warlock.js/core/src/use-cases/use-case-pipeline.ts"],"sourcesContent":["import type { ObjectValidator } from \"@warlock.js/seal\";\nimport { v } from \"@warlock.js/seal\";\nimport type {\n  UseCaseBeforeMiddleware,\n  UseCaseContext,\n  UseCaseGuard,\n  UseCaseOnExecutingContext,\n} from \"./types\";\nimport { fireLifecycleEvent, globalEventsCallbacksMap } from \"./use-case-events\";\nimport { BadSchemaUseCaseError } from \"./use-case.errors\";\n\nexport type PipelineOptions<Input> = {\n  name: string;\n  id: string;\n  data: Input;\n  ctx: UseCaseContext;\n  startedAt: Date;\n  schema?: ObjectValidator;\n  guards?: UseCaseGuard<Input>[];\n  before?: UseCaseBeforeMiddleware<Input>[];\n  /** Invocation-level onExecuting override */\n  onExecuting?: (ctx: UseCaseOnExecutingContext) => void;\n  /** Use-case-level onExecuting */\n  ucOnExecuting?: (ctx: UseCaseOnExecutingContext) => void;\n};\n\n/**\n * Runs the pre-handler pipeline in order:\n * onExecuting event → guards → validation → before middleware.\n *\n * Returns the validated, transformed data ready for the handler. The handler is\n * invoked by the caller so retry/benchmark can wrap it in isolation — keeping\n * guards, validation, and onExecuting from re-running on each retry attempt.\n *\n * Throws on guard failure or validation failure.\n *\n * @example\n * const data = await runPipeline({ name, id, data, ctx, startedAt, schema, guards, before });\n */\nexport async function runPipeline<Input>(opts: PipelineOptions<Input>): Promise<Input> {\n  const { name, id, ctx, startedAt, schema, guards, before, onExecuting, ucOnExecuting } = opts;\n  let data = opts.data;\n\n  await fireLifecycleEvent<UseCaseOnExecutingContext>(\n    { name, id, data, schema, ctx, startedAt },\n    {\n      invocation: onExecuting ? [onExecuting] : undefined,\n      useCase: ucOnExecuting ? [ucOnExecuting] : undefined,\n      global: globalEventsCallbacksMap.onExecuting.length\n        ? globalEventsCallbacksMap.onExecuting\n        : undefined,\n    },\n  );\n\n  if (guards) {\n    // Guards get a frozen SHALLOW CLONE so a guard can't mutate the input, while\n    // the original `data` (and the reference that reaches before-middleware and the\n    // handler) stays writable. Freezing `data` in place would leak the frozen ref\n    // downstream and make a handler mutating its input throw under strict mode.\n    // The guard contract is read-only by design; the clone is shallow (deep-freeze\n    // is optional and intentionally not done here).\n    const frozenData = Object.freeze(\n      Array.isArray(data) ? [...data] : { ...(data as object) },\n    ) as Readonly<Input>;\n\n    for (const guard of guards) {\n      await guard(frozenData, ctx);\n    }\n  }\n\n  if (schema) {\n    const result = await v.validate(schema, data);\n\n    if (!result.isValid) {\n      throw new BadSchemaUseCaseError(result);\n    }\n\n    data = result.data;\n  }\n\n  let transformed = data;\n\n  if (before) {\n    for (const middleware of before) {\n      transformed = await middleware(transformed, ctx);\n    }\n  }\n\n  return transformed;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAuCA,eAAsB,YAAmB,MAA8C;CACrF,MAAM,EAAE,MAAM,IAAI,KAAK,WAAW,QAAQ,QAAQ,QAAQ,aAAa,kBAAkB;CACzF,IAAI,OAAO,KAAK;CAEhB,MAAM,mBACJ;EAAE;EAAM;EAAI;EAAM;EAAQ;EAAK;CAAU,GACzC;EACE,YAAY,cAAc,CAAC,WAAW,IAAI;EAC1C,SAAS,gBAAgB,CAAC,aAAa,IAAI;EAC3C,QAAQ,yBAAyB,YAAY,SACzC,yBAAyB,cACzB;CACN,CACF;CAEA,IAAI,QAAQ;EAOV,MAAM,aAAa,OAAO,OACxB,MAAM,QAAQ,IAAI,IAAI,CAAC,GAAG,IAAI,IAAI,EAAE,GAAI,KAAgB,CAC1D;EAEA,KAAK,MAAM,SAAS,QAClB,MAAM,MAAM,YAAY,GAAG;CAE/B;CAEA,IAAI,QAAQ;EACV,MAAM,SAAS,MAAM,EAAE,SAAS,QAAQ,IAAI;EAE5C,IAAI,CAAC,OAAO,SACV,MAAM,IAAI,sBAAsB,MAAM;EAGxC,OAAO,OAAO;CAChB;CAEA,IAAI,cAAc;CAElB,IAAI,QACF,KAAK,MAAM,cAAc,QACvB,cAAc,MAAM,WAAW,aAAa,GAAG;CAInD,OAAO;AACT"}

package/esm/use-cases/use-case.mjs

@@ -34,7 +34,7 @@ function useCase(options) {
 		let output;
 		let error;
 		let benchmarkResult;
-		let currentRetry = 0;
+		let failedAttempts = 0;
 		if (logEnabled) log.debug("use-cases", name, "executing", { id });
 		try {
 			const transformed = await runPipeline({
@@ -62,7 +62,7 @@ function useCase(options) {
 			output = retryConfig ? await retry(runHandler, {
 				...retryConfig,
 				onError: (retryError, attempt) => {
-					currentRetry = attempt;
+					failedAttempts = attempt;
 					retryConfig.onError?.(retryError, attempt);
 				}
 			}) : await runHandler();
@@ -70,11 +70,12 @@ function useCase(options) {
 			error = err;
 		}
 		const endedAt = /* @__PURE__ */ new Date();
-		if (!error && after && output !== void 0) for (const middleware of after) try {
+		if (!error && after) for (const middleware of after) try {
 			await middleware(output, ctx);
 		} catch (afterError) {
 			log.error("use-cases", name, "after middleware failed", { error: afterError });
 		}
+		const currentRetry = error ? Math.max(failedAttempts - 1, 0) : failedAttempts;
 		const snapshot = {
 			output,
 			ctx,
@@ -111,7 +112,14 @@ function useCase(options) {
 			id,
 			latency: benchmarkResult?.latency
 		});
-		await addUseCaseHistory(name, snapshot);
+		try {
+			await addUseCaseHistory(name, snapshot);
+		} catch (historyError) {
+			log.error("use-cases", name, "history persistence failed", {
+				id,
+				error: historyError
+			});
+		}
 		await fireLifecycleEvent(snapshot, {
 			invocation: invocationOnCompleted ? [invocationOnCompleted] : void 0,
 			useCase: onCompleted ? [onCompleted] : void 0,

package/esm/use-cases/use-case.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-case.mjs","names":["runWithRetry"],"sources":["../../../../../../../@warlock.js/core/src/use-cases/use-case.ts"],"sourcesContent":["import { except, Random, retry as runWithRetry } from \"@mongez/reinforcements\";\r\nimport { log } from \"@warlock.js/logger\";\r\nimport type { Infer, ObjectValidator } from \"@warlock.js/seal\";\r\nimport { measure } from \"../benchmark\";\r\nimport { config } from \"../config\";\r\nimport type {\r\n  UseCase,\r\n  UseCaseConfigurations,\r\n  UseCaseContext,\r\n  UseCaseErrorResult,\r\n  UseCaseHandler,\r\n  UseCaseResult,\r\n  UseCaseRuntimeOptions,\r\n  UseCaseWithSchema,\r\n} from \"./types\";\r\nimport { broadcastUseCaseResult } from \"./use-case-broadcast\";\r\nimport { fireLifecycleEvent, globalEventsCallbacksMap } from \"./use-case-events\";\r\nimport { runPipeline } from \"./use-case-pipeline\";\r\nimport {\r\n  $registerUseCase,\r\n  $unregisterUseCase,\r\n  addUseCaseHistory,\r\n  increaseUseCaseFailedCalls,\r\n  increaseUseCaseSuccessCalls,\r\n} from \"./use-cases-registry\";\r\n\r\nconst defaultUseCaseOptions: UseCaseConfigurations = {\r\n  benchmark: true,\r\n};\r\n\r\n/**\r\n * Defines and registers a use case.\r\n *\r\n * A use case is a named, observable, optionally benchmarked unit of business logic.\r\n * The returned handler is a typed async function you call with the input data.\r\n *\r\n * Execution order: onExecuting → guards → validation → before → handler → after →\r\n * onCompleted → broadcast. Retry and benchmark wrap the **handler** only.\r\n *\r\n * When a `schema` is provided, the handler's input is inferred from it — no manual\r\n * `Input` generic needed.\r\n *\r\n * @example\r\n * export const createOrderUseCase = useCase({\r\n *   name: \"create_order\",\r\n *   schema: createOrderSchema,           // handler `data` is inferred from this\r\n *   guards: [authGuard],\r\n *   handler: async (data, ctx) => orderService.create(data),\r\n *   after: [sendConfirmationEmail],\r\n *   retry: { attempts: 3, delay: 500, backoff: \"exponential\" },\r\n *   broadcast: true,\r\n * });\r\n *\r\n * // In a controller:\r\n * const output = await createOrderUseCase({ ...validated, user_id: req.user.id });\r\n */\r\nexport function useCase<\r\n  Output,\r\n  Schema extends ObjectValidator,\r\n  Ctx extends UseCaseContext = UseCaseContext,\r\n>(options: UseCaseWithSchema<Output, Schema, Ctx>): UseCaseHandler<Output, Infer<Schema>>;\r\nexport function useCase<Output = any, Input = any, Ctx extends UseCaseContext = UseCaseContext>(\r\n  options: UseCase<Output, Input, Ctx>,\r\n): UseCaseHandler<Output, Input>;\r\nexport function useCase<Output = any, Input = any>(\r\n  options: UseCase<Output, Input>,\r\n): UseCaseHandler<Output, Input> {\r\n  const { name, handler, schema, guards, before, after, onExecuting, onCompleted, onError } =\r\n    options;\r\n\r\n  // Merge per-use-case options with global config defaults\r\n  const useCaseConfig = config.get<UseCaseConfigurations>(\"use-cases\", defaultUseCaseOptions);\r\n  const benchmark = options.benchmark ?? useCaseConfig?.benchmark ?? true;\r\n  const retryConfig = options.retry ?? useCaseConfig?.retry;\r\n  const broadcast = options.broadcast;\r\n  const broadcastConfig = useCaseConfig?.broadcast;\r\n  const logEnabled = useCaseConfig?.log === true;\r\n\r\n  $registerUseCase(name, {\r\n    ...options,\r\n    calls: { success: 0, failed: 0, total: 0 },\r\n  });\r\n\r\n  const useCaseHandler = async (\r\n    data: Input,\r\n    {\r\n      ctx = {},\r\n      id = `uc-${name}-` + Random.string(),\r\n      onExecuting: invocationOnExecuting,\r\n      onCompleted: invocationOnCompleted,\r\n      onError: invocationOnError,\r\n    }: UseCaseRuntimeOptions = {},\r\n  ): Promise<Output> => {\r\n    ctx.schema = schema;\r\n    ctx.id = id;\r\n\r\n    const startedAt = new Date();\r\n    let output: Output | undefined;\r\n    let error: Error | undefined;\r\n    let benchmarkResult: { latency: number; state: \"excellent\" | \"good\" | \"poor\" } | undefined;\r\n    let currentRetry = 0;\r\n\r\n    if (logEnabled) {\r\n      log.debug(\"use-cases\", name, \"executing\", { id });\r\n    }\r\n\r\n    try {\r\n      const transformed = await runPipeline<Input>({\r\n        name,\r\n        id,\r\n        data,\r\n        ctx,\r\n        startedAt,\r\n        schema,\r\n        guards,\r\n        before,\r\n        onExecuting: invocationOnExecuting,\r\n        ucOnExecuting: onExecuting,\r\n      });\r\n\r\n      // Benchmark wraps ONLY the handler (per attempt) so latency reflects business\r\n      // logic — not the guard/validation prelude, and not the retry backoff delays.\r\n      const runHandler = async (): Promise<Output> => {\r\n        if (!benchmark) {\r\n          return handler(transformed, ctx);\r\n        }\r\n\r\n        const measured = await measure(\r\n          name,\r\n          () => handler(transformed, ctx),\r\n          benchmark === true ? undefined : benchmark,\r\n        );\r\n\r\n        benchmarkResult = { latency: measured.latency, state: measured.state };\r\n\r\n        // measure() never throws — it returns an error result. Re-throw so retry\r\n        // and the outer catch handle failures uniformly.\r\n        if (!measured.success) {\r\n          throw measured.error;\r\n        }\r\n\r\n        return measured.value;\r\n      };\r\n\r\n      output = retryConfig\r\n        ? await runWithRetry(runHandler, {\r\n            ...retryConfig,\r\n            onError: (retryError, attempt) => {\r\n              currentRetry = attempt;\r\n              retryConfig.onError?.(retryError, attempt);\r\n            },\r\n          })\r\n        : await runHandler();\r\n    } catch (err) {\r\n      error = err as Error;\r\n    }\r\n\r\n    const endedAt = new Date();\r\n\r\n    // After middleware — fire-and-forget side effects, only on success\r\n    if (!error && after && output !== undefined) {\r\n      for (const middleware of after) {\r\n        try {\r\n          await middleware(output, ctx);\r\n        } catch (afterError) {\r\n          log.error(\"use-cases\", name, \"after middleware failed\", { error: afterError });\r\n        }\r\n      }\r\n    }\r\n\r\n    const snapshot: UseCaseResult<Output> = {\r\n      output,\r\n      ctx,\r\n      startedAt,\r\n      endedAt,\r\n      id,\r\n      name,\r\n      retries: retryConfig\r\n        ? { attempts: retryConfig.attempts ?? 3, delay: retryConfig.delay, currentRetry }\r\n        : undefined,\r\n      benchmarkResult,\r\n      // Set per-branch below so the counter reflects the actual outcome —\r\n      // a failure must never increment the success tally.\r\n      calls: 0,\r\n    };\r\n\r\n    if (error) {\r\n      snapshot.calls = increaseUseCaseFailedCalls(name);\r\n\r\n      if (logEnabled) {\r\n        log.error(\"use-cases\", name, \"failed\", { id, error });\r\n      }\r\n\r\n      await fireLifecycleEvent<UseCaseErrorResult>(\r\n        { ...except(snapshot, [\"output\"]), error },\r\n        {\r\n          invocation: invocationOnError ? [invocationOnError] : undefined,\r\n          useCase: onError ? [onError] : undefined,\r\n          global: globalEventsCallbacksMap.onError.length\r\n            ? globalEventsCallbacksMap.onError\r\n            : undefined,\r\n        },\r\n      );\r\n\r\n      throw error;\r\n    }\r\n\r\n    snapshot.calls = increaseUseCaseSuccessCalls(name);\r\n\r\n    if (logEnabled) {\r\n      log.debug(\"use-cases\", name, \"completed\", { id, latency: benchmarkResult?.latency });\r\n    }\r\n\r\n    await addUseCaseHistory(name, snapshot);\r\n\r\n    await fireLifecycleEvent<UseCaseResult<Output>>(snapshot, {\r\n      invocation: invocationOnCompleted ? [invocationOnCompleted] : undefined,\r\n      useCase: onCompleted ? [onCompleted] : undefined,\r\n      global: globalEventsCallbacksMap.onCompleted.length\r\n        ? globalEventsCallbacksMap.onCompleted\r\n        : undefined,\r\n    });\r\n\r\n    await broadcastUseCaseResult({\r\n      name,\r\n      id,\r\n      output: output!,\r\n      result: snapshot,\r\n      broadcast,\r\n      config: broadcastConfig,\r\n    });\r\n\r\n    return output!;\r\n  };\r\n\r\n  useCaseHandler.$cleanup = () => {\r\n    $unregisterUseCase(name);\r\n  };\r\n\r\n  return useCaseHandler;\r\n}\r\n"],"mappings":"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"}
+{"version":3,"file":"use-case.mjs","names":["runWithRetry"],"sources":["../../../../../../../@warlock.js/core/src/use-cases/use-case.ts"],"sourcesContent":["import { except, Random, retry as runWithRetry } from \"@mongez/reinforcements\";\nimport { log } from \"@warlock.js/logger\";\nimport type { Infer, ObjectValidator } from \"@warlock.js/seal\";\nimport { measure } from \"../benchmark\";\nimport { config } from \"../config\";\nimport type {\n  UseCase,\n  UseCaseConfigurations,\n  UseCaseContext,\n  UseCaseErrorResult,\n  UseCaseHandler,\n  UseCaseResult,\n  UseCaseRuntimeOptions,\n  UseCaseWithSchema,\n} from \"./types\";\nimport { broadcastUseCaseResult } from \"./use-case-broadcast\";\nimport { fireLifecycleEvent, globalEventsCallbacksMap } from \"./use-case-events\";\nimport { runPipeline } from \"./use-case-pipeline\";\nimport {\n  $registerUseCase,\n  $unregisterUseCase,\n  addUseCaseHistory,\n  increaseUseCaseFailedCalls,\n  increaseUseCaseSuccessCalls,\n} from \"./use-cases-registry\";\n\nconst defaultUseCaseOptions: UseCaseConfigurations = {\n  benchmark: true,\n};\n\n/**\n * Defines and registers a use case.\n *\n * A use case is a named, observable, optionally benchmarked unit of business logic.\n * The returned handler is a typed async function you call with the input data.\n *\n * Execution order: onExecuting → guards → validation → before → handler → after →\n * onCompleted → broadcast. Retry and benchmark wrap the **handler** only.\n *\n * When a `schema` is provided, the handler's input is inferred from it — no manual\n * `Input` generic needed.\n *\n * @example\n * export const createOrderUseCase = useCase({\n *   name: \"create_order\",\n *   schema: createOrderSchema,           // handler `data` is inferred from this\n *   guards: [authGuard],\n *   handler: async (data, ctx) => orderService.create(data),\n *   after: [sendConfirmationEmail],\n *   retry: { attempts: 3, delay: 500, backoff: \"exponential\" },\n *   broadcast: true,\n * });\n *\n * // In a controller:\n * const output = await createOrderUseCase({ ...validated, user_id: req.user.id });\n */\nexport function useCase<\n  Output,\n  Schema extends ObjectValidator,\n  Ctx extends UseCaseContext = UseCaseContext,\n>(options: UseCaseWithSchema<Output, Schema, Ctx>): UseCaseHandler<Output, Infer<Schema>>;\nexport function useCase<Output = any, Input = any, Ctx extends UseCaseContext = UseCaseContext>(\n  options: UseCase<Output, Input, Ctx>,\n): UseCaseHandler<Output, Input>;\nexport function useCase<Output = any, Input = any>(\n  options: UseCase<Output, Input>,\n): UseCaseHandler<Output, Input> {\n  const { name, handler, schema, guards, before, after, onExecuting, onCompleted, onError } =\n    options;\n\n  // Merge per-use-case options with global config defaults\n  const useCaseConfig = config.get<UseCaseConfigurations>(\"use-cases\", defaultUseCaseOptions);\n  const benchmark = options.benchmark ?? useCaseConfig?.benchmark ?? true;\n  const retryConfig = options.retry ?? useCaseConfig?.retry;\n  const broadcast = options.broadcast;\n  const broadcastConfig = useCaseConfig?.broadcast;\n  const logEnabled = useCaseConfig?.log === true;\n\n  $registerUseCase(name, {\n    ...options,\n    calls: { success: 0, failed: 0, total: 0 },\n  });\n\n  const useCaseHandler = async (\n    data: Input,\n    {\n      ctx = {},\n      id = `uc-${name}-` + Random.string(),\n      onExecuting: invocationOnExecuting,\n      onCompleted: invocationOnCompleted,\n      onError: invocationOnError,\n    }: UseCaseRuntimeOptions = {},\n  ): Promise<Output> => {\n    ctx.schema = schema;\n    ctx.id = id;\n\n    const startedAt = new Date();\n    let output: Output | undefined;\n    let error: Error | undefined;\n    let benchmarkResult: { latency: number; state: \"excellent\" | \"good\" | \"poor\" } | undefined;\n    // 1-based count of failed attempts (reinforcements' `attempt` arg). Translated\n    // into \"retries performed\" at snapshot time — see the `currentRetry` derivation.\n    let failedAttempts = 0;\n\n    if (logEnabled) {\n      log.debug(\"use-cases\", name, \"executing\", { id });\n    }\n\n    try {\n      const transformed = await runPipeline<Input>({\n        name,\n        id,\n        data,\n        ctx,\n        startedAt,\n        schema,\n        guards,\n        before,\n        onExecuting: invocationOnExecuting,\n        ucOnExecuting: onExecuting,\n      });\n\n      // Benchmark wraps ONLY the handler (per attempt) so latency reflects business\n      // logic — not the guard/validation prelude, and not the retry backoff delays.\n      const runHandler = async (): Promise<Output> => {\n        if (!benchmark) {\n          return handler(transformed, ctx);\n        }\n\n        const measured = await measure(\n          name,\n          () => handler(transformed, ctx),\n          benchmark === true ? undefined : benchmark,\n        );\n\n        benchmarkResult = { latency: measured.latency, state: measured.state };\n\n        // measure() never throws — it returns an error result. Re-throw so retry\n        // and the outer catch handle failures uniformly.\n        if (!measured.success) {\n          throw measured.error;\n        }\n\n        return measured.value;\n      };\n\n      output = retryConfig\n        ? await runWithRetry(runHandler, {\n            ...retryConfig,\n            onError: (retryError, attempt) => {\n              failedAttempts = attempt;\n              retryConfig.onError?.(retryError, attempt);\n            },\n          })\n        : await runHandler();\n    } catch (err) {\n      error = err as Error;\n    }\n\n    const endedAt = new Date();\n\n    // After middleware — fire-and-forget side effects, only on success.\n    // Keyed off the error flag alone so void handlers (which return undefined)\n    // still run their after middleware.\n    if (!error && after) {\n      for (const middleware of after) {\n        try {\n          // On the success path `output` holds the handler's return value; for a\n          // void handler that's undefined, which the middleware receives as-is.\n          await middleware(output as Output, ctx);\n        } catch (afterError) {\n          log.error(\"use-cases\", name, \"after middleware failed\", { error: afterError });\n        }\n      }\n    }\n\n    // Retries actually performed (0 = succeeded on the first try). On success every\n    // failed attempt was followed by a retry; on failure the final failed attempt\n    // was NOT retried, so it doesn't count as a retry performed.\n    const currentRetry = error ? Math.max(failedAttempts - 1, 0) : failedAttempts;\n\n    const snapshot: UseCaseResult<Output> = {\n      output,\n      ctx,\n      startedAt,\n      endedAt,\n      id,\n      name,\n      retries: retryConfig\n        ? { attempts: retryConfig.attempts ?? 3, delay: retryConfig.delay, currentRetry }\n        : undefined,\n      benchmarkResult,\n      // Set per-branch below so the counter reflects the actual outcome —\n      // a failure must never increment the success tally.\n      calls: 0,\n    };\n\n    if (error) {\n      snapshot.calls = increaseUseCaseFailedCalls(name);\n\n      if (logEnabled) {\n        log.error(\"use-cases\", name, \"failed\", { id, error });\n      }\n\n      await fireLifecycleEvent<UseCaseErrorResult>(\n        { ...except(snapshot, [\"output\"]), error },\n        {\n          invocation: invocationOnError ? [invocationOnError] : undefined,\n          useCase: onError ? [onError] : undefined,\n          global: globalEventsCallbacksMap.onError.length\n            ? globalEventsCallbacksMap.onError\n            : undefined,\n        },\n      );\n\n      throw error;\n    }\n\n    snapshot.calls = increaseUseCaseSuccessCalls(name);\n\n    if (logEnabled) {\n      log.debug(\"use-cases\", name, \"completed\", { id, latency: benchmarkResult?.latency });\n    }\n\n    // History is best-effort — a cache rejection must not turn a successful run\n    // into a thrown error or skip onCompleted/broadcast.\n    try {\n      await addUseCaseHistory(name, snapshot);\n    } catch (historyError) {\n      log.error(\"use-cases\", name, \"history persistence failed\", { id, error: historyError });\n    }\n\n    await fireLifecycleEvent<UseCaseResult<Output>>(snapshot, {\n      invocation: invocationOnCompleted ? [invocationOnCompleted] : undefined,\n      useCase: onCompleted ? [onCompleted] : undefined,\n      global: globalEventsCallbacksMap.onCompleted.length\n        ? globalEventsCallbacksMap.onCompleted\n        : undefined,\n    });\n\n    await broadcastUseCaseResult({\n      name,\n      id,\n      // A void handler resolves to undefined — broadcast it as-is rather than\n      // asserting a non-null value that would fabricate a bogus payload.\n      output: output as Output,\n      result: snapshot,\n      broadcast,\n      config: broadcastConfig,\n    });\n\n    return output as Output;\n  };\n\n  useCaseHandler.$cleanup = () => {\n    $unregisterUseCase(name);\n  };\n\n  return useCaseHandler;\n}\n"],"mappings":";;;;;;;;;;;;AA0BA,MAAM,wBAA+C,EACnD,WAAW,KACb;AAoCA,SAAgB,QACd,SAC+B;CAC/B,MAAM,EAAE,MAAM,SAAS,QAAQ,QAAQ,QAAQ,OAAO,aAAa,aAAa,YAC9E;CAGF,MAAM,gBAAgB,OAAO,IAA2B,aAAa,qBAAqB;CAC1F,MAAM,YAAY,QAAQ,aAAa,eAAe,aAAa;CACnE,MAAM,cAAc,QAAQ,SAAS,eAAe;CACpD,MAAM,YAAY,QAAQ;CAC1B,MAAM,kBAAkB,eAAe;CACvC,MAAM,aAAa,eAAe,QAAQ;CAE1C,iBAAiB,MAAM;EACrB,GAAG;EACH,OAAO;GAAE,SAAS;GAAG,QAAQ;GAAG,OAAO;EAAE;CAC3C,CAAC;CAED,MAAM,iBAAiB,OACrB,MACA,EACE,MAAM,CAAC,GACP,KAAK,MAAM,KAAK,KAAK,OAAO,OAAO,GACnC,aAAa,uBACb,aAAa,uBACb,SAAS,sBACgB,CAAC,MACR;EACpB,IAAI,SAAS;EACb,IAAI,KAAK;EAET,MAAM,4BAAY,IAAI,KAAK;EAC3B,IAAI;EACJ,IAAI;EACJ,IAAI;EAGJ,IAAI,iBAAiB;EAErB,IAAI,YACF,IAAI,MAAM,aAAa,MAAM,aAAa,EAAE,GAAG,CAAC;EAGlD,IAAI;GACF,MAAM,cAAc,MAAM,YAAmB;IAC3C;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA,aAAa;IACb,eAAe;GACjB,CAAC;GAID,MAAM,aAAa,YAA6B;IAC9C,IAAI,CAAC,WACH,OAAO,QAAQ,aAAa,GAAG;IAGjC,MAAM,WAAW,MAAM,QACrB,YACM,QAAQ,aAAa,GAAG,GAC9B,cAAc,OAAO,SAAY,SACnC;IAEA,kBAAkB;KAAE,SAAS,SAAS;KAAS,OAAO,SAAS;IAAM;IAIrE,IAAI,CAAC,SAAS,SACZ,MAAM,SAAS;IAGjB,OAAO,SAAS;GAClB;GAEA,SAAS,cACL,MAAMA,MAAa,YAAY;IAC7B,GAAG;IACH,UAAU,YAAY,YAAY;KAChC,iBAAiB;KACjB,YAAY,UAAU,YAAY,OAAO;IAC3C;GACF,CAAC,IACD,MAAM,WAAW;EACvB,SAAS,KAAK;GACZ,QAAQ;EACV;EAEA,MAAM,0BAAU,IAAI,KAAK;EAKzB,IAAI,CAAC,SAAS,OACZ,KAAK,MAAM,cAAc,OACvB,IAAI;GAGF,MAAM,WAAW,QAAkB,GAAG;EACxC,SAAS,YAAY;GACnB,IAAI,MAAM,aAAa,MAAM,2BAA2B,EAAE,OAAO,WAAW,CAAC;EAC/E;EAOJ,MAAM,eAAe,QAAQ,KAAK,IAAI,iBAAiB,GAAG,CAAC,IAAI;EAE/D,MAAM,WAAkC;GACtC;GACA;GACA;GACA;GACA;GACA;GACA,SAAS,cACL;IAAE,UAAU,YAAY,YAAY;IAAG,OAAO,YAAY;IAAO;GAAa,IAC9E;GACJ;GAGA,OAAO;EACT;EAEA,IAAI,OAAO;GACT,SAAS,QAAQ,2BAA2B,IAAI;GAEhD,IAAI,YACF,IAAI,MAAM,aAAa,MAAM,UAAU;IAAE;IAAI;GAAM,CAAC;GAGtD,MAAM,mBACJ;IAAE,GAAG,OAAO,UAAU,CAAC,QAAQ,CAAC;IAAG;GAAM,GACzC;IACE,YAAY,oBAAoB,CAAC,iBAAiB,IAAI;IACtD,SAAS,UAAU,CAAC,OAAO,IAAI;IAC/B,QAAQ,yBAAyB,QAAQ,SACrC,yBAAyB,UACzB;GACN,CACF;GAEA,MAAM;EACR;EAEA,SAAS,QAAQ,4BAA4B,IAAI;EAEjD,IAAI,YACF,IAAI,MAAM,aAAa,MAAM,aAAa;GAAE;GAAI,SAAS,iBAAiB;EAAQ,CAAC;EAKrF,IAAI;GACF,MAAM,kBAAkB,MAAM,QAAQ;EACxC,SAAS,cAAc;GACrB,IAAI,MAAM,aAAa,MAAM,8BAA8B;IAAE;IAAI,OAAO;GAAa,CAAC;EACxF;EAEA,MAAM,mBAA0C,UAAU;GACxD,YAAY,wBAAwB,CAAC,qBAAqB,IAAI;GAC9D,SAAS,cAAc,CAAC,WAAW,IAAI;GACvC,QAAQ,yBAAyB,YAAY,SACzC,yBAAyB,cACzB;EACN,CAAC;EAED,MAAM,uBAAuB;GAC3B;GACA;GAGQ;GACR,QAAQ;GACR;GACA,QAAQ;EACV,CAAC;EAED,OAAO;CACT;CAEA,eAAe,iBAAiB;EAC9B,mBAAmB,IAAI;CACzB;CAEA,OAAO;AACT"}

package/esm/use-cases/use-cases-registry.d.mts

@@ -1,4 +1,4 @@
-import { RegisteredUseCase, UseCase, UseCaseResult } from "./types.mjs";
+import { RegisteredUseCase, UseCaseResult } from "./types.mjs";
 
 //#region ../@warlock.js/core/src/use-cases/use-cases-registry.d.ts
 /**
@@ -6,13 +6,21 @@ import { RegisteredUseCase, UseCase, UseCaseResult } from "./types.mjs";
  */
 declare function $registerUseCase<Output, Input>(name: string, useCase: RegisteredUseCase<Output, Input>): void;
 /**
- * Unregister a use case
+ * Unregister a use case.
+ *
+ * Dropping the history namespace is best-effort: `$cleanup` is synchronous, so the
+ * async cache removal is fire-and-forget with a `.catch` guard — a rejecting cache
+ * driver must never turn cleanup into an unhandled rejection.
  */
 declare function $unregisterUseCase(name: string): void;
 /**
- * Get a use case
+ * Get a use case.
+ *
+ * Returns the `RegisteredUseCase` shape — including the runtime `calls` counters
+ * the registry actually stores — so consumers can read call stats without an
+ * ad-hoc cast.
  */
-declare function getUseCase<Output, Input>(name: string): UseCase<Output, Input> | undefined;
+declare function getUseCase<Output, Input>(name: string): RegisteredUseCase<Output, Input> | undefined;
 /**
  * Get all use cases
  */

package/esm/use-cases/use-cases-registry.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"use-cases-registry.d.mts","names":[],"sources":["../../../../../../../@warlock.js/core/src/use-cases/use-cases-registry.ts"],"mappings":";;;;;AAaA;iBAAgB,gBAAA,gBACd,IAAA,UACA,OAAA,EAAS,iBAAA,CAAkB,MAAA,EAAQ,KAAA;;;;iBAgBrB,kBAAA,CAAmB,IAAY;;;;iBAS/B,UAAA,gBAA0B,IAAA,WACJ,OAAA,CAAQ,MAAA,EAAQ,KAAA;;;;iBAMtC,WAAA,IAAW,GAAA,SAAA,iBAAA;;;AAhCgB;iBAuC3B,2BAAA,CAA4B,IAAY;;;;iBAexC,0BAAA,CAA2B,IAAY;AA7BvD;;;;;AAAA,iBAwDsB,iBAAA,CAAkB,IAAA,WAAe,OAAO,CAAC,aAAA;;;;;iBA8BzC,iBAAA,CAAkB,IAAA,UAAc,MAAA,EAAQ,aAAA,QAAkB,OAAA"}
+{"version":3,"file":"use-cases-registry.d.mts","names":[],"sources":["../../../../../../../@warlock.js/core/src/use-cases/use-cases-registry.ts"],"mappings":";;;;;AAaA;iBAAgB,gBAAA,gBACd,IAAA,UACA,OAAA,EAAS,iBAAA,CAAkB,MAAA,EAAQ,KAAA;;;;;;;;iBAoBrB,kBAAA,CAAmB,IAAY;;;;;;;AApBJ;iBAmC3B,UAAA,gBAA0B,IAAA,WACJ,iBAAA,CAAkB,MAAA,EAAQ,KAAA;;;;iBAMhD,WAAA,IAAW,GAAA,SAAA,iBAAA;AAP3B;;;AAAA,iBAcgB,2BAAA,CAA4B,IAAY;;;;iBAexC,0BAAA,CAA2B,IAAY;;;;;;iBA2BjC,iBAAA,CAAkB,IAAA,WAAe,OAAO,CAAC,aAAA;;AAvDM;AAMrE;;iBA+EsB,iBAAA,CAAkB,IAAA,UAAc,MAAA,EAAQ,aAAA,QAAkB,OAAA"}