@vercel/factory 0.0.14 → 0.0.16

package/dist/blob/index.mjs

@@ -1,4 +1,5 @@
-import { n as RecordNotFoundError, r as VersionConflictError, t as RecordExistsError } from "../driver-Bbd25rNM.mjs";
+import { RecordExistsError, RecordNotFoundError, TransientStoreError, VersionConflictError } from "../store/driver.mjs";
+import { artifactReference, createArtifactStore, parseArtifactRef } from "./artifacts.mjs";
 import { get, list, put } from "@vercel/blob";
 //#region src/blob/index.ts
 function isNotFoundError(error) {
@@ -8,10 +9,49 @@ function isAlreadyExistsError(error) {
 	return error instanceof Error && /already exists|not allowed to overwrite|overwrite/iu.test(error.message);
 }
 function isPreconditionError(error) {
-	return error instanceof Error && (error.name === "BlobPreconditionFailedError" || /precondition|etag|412/iu.test(error.message));
+	return error instanceof Error && (error.name === "BlobPreconditionFailedError" || /precondition|etag|412/iu.test(error.message) || error.message === "Vercel Blob: The conditional request cannot succeed due to a conflicting operation against this resource.");
 }
+const TRANSIENT_NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"ETIMEDOUT",
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"EPIPE",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"UND_ERR_CONNECT_TIMEOUT",
+	"UND_ERR_SOCKET",
+	"UND_ERR_HEADERS_TIMEOUT"
+]);
+function isTransientBlobError(error) {
+	if (!(error instanceof Error)) return false;
+	if (isAlreadyExistsError(error) || isPreconditionError(error) || isNotFoundError(error)) return false;
+	const code = error.code;
+	if (code !== void 0 && TRANSIENT_NETWORK_ERROR_CODES.has(code)) return true;
+	if (error.name === "AbortError") return true;
+	if (/fetch failed|network|socket hang up|timed? ?out|ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN/iu.test(error.message)) return true;
+	return /(?:^|[^0-9])(?:429|5\d{2})(?:[^0-9]|$)/u.test(error.message);
+}
+function jsonValuesEqual(a, b) {
+	if (a === b) return true;
+	if (typeof a !== typeof b) return false;
+	if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((item, index) => jsonValuesEqual(item, b[index]));
+	}
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) return false;
+	return aKeys.every((key) => Object.hasOwn(b, key) && jsonValuesEqual(a[key], b[key]));
+}
+/**
+* Default private Vercel Blob client used by the durable Factory store driver.
+* Reads explicitly bypass the CDN cache, and writes resolve only after the SDK accepts them.
+*/
 const vercelBlobClient = {
-	async read(pathname) {
+	async read({ pathname }) {
 		let result;
 		try {
 			result = await get(pathname, {
@@ -28,15 +68,15 @@ const vercelBlobClient = {
 			etag: result.blob.etag
 		};
 	},
-	async write(pathname, body, overwrite, ifMatch) {
-		await put(pathname, body, {
+	async write({ pathname, body, overwrite, ifMatch }) {
+		await put(pathname, body === "" ? Buffer.alloc(0) : body, {
 			access: "private",
 			allowOverwrite: overwrite,
 			contentType: "application/json",
-			...ifMatch === void 0 ? {} : { ifMatch }
+			...ifMatch === void 0 ? {} : { ifMatch: ifMatch.replace(/^W\//u, "") }
 		});
 	},
-	async listPaths(prefix) {
+	async listPaths({ prefix }) {
 		const paths = [];
 		let cursor;
 		do {
@@ -52,24 +92,71 @@ const vercelBlobClient = {
 	}
 };
 /**
-* Store driver on Vercel Blob: durable and dependency-free (one Blob store on
-* the project, no database). Inserts are create-if-absent. Updates read the latest content,
-* bypassing Blob's CDN cache, and write with an ETag precondition, so a
-* writer that lost a race gets a VersionConflictError rather than
-* overwriting the winner.
+* Creates a durable Vercel Blob driver with atomic compare-and-swap updates.
+*
+* @remarks
+* Inserts are create-if-absent. Updates bypass Blob's CDN cache and use the current ETag, so a
+* writer that loses a race receives `VersionConflictError` instead of overwriting the winner.
+* Reads and writes retry only 5xx, 429, and network failures within the configured attempt and
+* elapsed-time bounds; exhaustion surfaces as `TransientStoreError`. If a transient write may
+* have landed before its response was lost, the retry reads the record back and treats only the
+* exact intended value and version as success. A different value remains a real conflict.
+*
+* Collection listing downloads records under the shared `readConcurrency` bound, coalesces
+* concurrent lists of the same collection, and rejects malformed persisted values. Listing the
+* provider's paths itself is not retried by this driver. The caller owns credentials and any
+* injected client's lifecycle.
+*
+* @param options - Optional Blob transport, namespace, read limit, retry policy, and retry clock.
+* @returns A `blob` driver suitable for `createStores`.
+* @throws When concurrency or retry bounds are invalid.
 */
 function createBlobDriver(options = {}) {
 	const client = options.client ?? vercelBlobClient;
+	const now = options.now ?? Date.now;
 	const prefix = options.prefix ?? "factory";
 	const readConcurrency = options.readConcurrency ?? 32;
 	if (!Number.isInteger(readConcurrency) || readConcurrency < 1) throw new Error("Blob read concurrency must be a positive integer");
+	const retry = {
+		attempts: options.retry?.attempts ?? 3,
+		baseDelayMs: options.retry?.baseDelayMs ?? 250,
+		maxTotalMs: options.retry?.maxTotalMs ?? 5e3
+	};
+	if (!Number.isInteger(retry.attempts) || retry.attempts < 1) throw new Error("Blob retry attempts must be a positive integer");
+	if (!Number.isFinite(retry.baseDelayMs) || retry.baseDelayMs < 0) throw new Error("Blob retry base delay must be a finite non-negative number");
+	if (!Number.isFinite(retry.maxTotalMs) || retry.maxTotalMs < 0) throw new Error("Blob retry elapsed-time limit must be a finite non-negative number");
+	let activeReads = 0;
+	const readWaiters = [];
+	const activeLists = /* @__PURE__ */ new Map();
+	async function withTransientRetry(collection, id, operation) {
+		const start = now();
+		for (let attempt = 0;; attempt += 1) try {
+			return await operation();
+		} catch (error) {
+			if (!isTransientBlobError(error)) throw error;
+			const nextDelayMs = retry.baseDelayMs * 2 ** attempt;
+			if (attempt >= retry.attempts - 1 || now() - start + nextDelayMs > retry.maxTotalMs) throw new TransientStoreError(collection, id, error);
+			await new Promise((resolve) => setTimeout(resolve, nextDelayMs));
+		}
+	}
+	async function limitedRead(pathname) {
+		if (activeReads < readConcurrency) activeReads += 1;
+		else await new Promise((resolve) => readWaiters.push(resolve));
+		try {
+			return await client.read({ pathname });
+		} finally {
+			const waiter = readWaiters.shift();
+			if (waiter === void 0) activeReads -= 1;
+			else waiter();
+		}
+	}
 	function pathFor(collection, id) {
 		return `${prefix}/${collection}/${id}.json`;
 	}
 	async function readRecord(collection, id) {
 		let object;
 		try {
-			object = await client.read(pathFor(collection, id));
+			object = await withTransientRetry(collection, id, () => limitedRead(pathFor(collection, id)));
 		} catch (error) {
 			if (isNotFoundError(error)) return null;
 			throw error;
@@ -83,6 +170,14 @@ function createBlobDriver(options = {}) {
 			etag: object.etag
 		};
 	}
+	async function wroteThisInsert(collection, id, value) {
+		const after = await readRecord(collection, id);
+		return after !== null && after.version === 1 && jsonValuesEqual(after.value, value);
+	}
+	async function wroteThisUpdate(collection, id, value, expectedNewVersion) {
+		const after = await readRecord(collection, id);
+		return after !== null && after.version === expectedNewVersion && jsonValuesEqual(after.value, value);
+	}
 	return {
 		name: "blob",
 		async get(collection, id) {
@@ -92,56 +187,95 @@ function createBlobDriver(options = {}) {
 				version: record.version
 			};
 		},
-		async insert(collection, id, value) {
+		async insert({ collection, id, value }) {
+			let attempts = 0;
 			try {
-				await client.write(pathFor(collection, id), JSON.stringify({
-					value,
-					version: 1
-				}), false);
+				await withTransientRetry(collection, id, () => {
+					attempts += 1;
+					return client.write({
+						pathname: pathFor(collection, id),
+						body: JSON.stringify({
+							value,
+							version: 1
+						}),
+						overwrite: false
+					});
+				});
 			} catch (error) {
-				if (isAlreadyExistsError(error)) throw new RecordExistsError(collection, id);
+				if (isAlreadyExistsError(error)) {
+					if (attempts > 1 && await wroteThisInsert(collection, id, value)) return;
+					throw new RecordExistsError(collection, id);
+				}
 				throw error;
 			}
 		},
-		async update(collection, id, value, expectedVersion) {
+		async update({ collection, id, value, expectedVersion }) {
 			const existing = await readRecord(collection, id);
 			if (existing === null) throw new RecordNotFoundError(collection, id);
 			if (existing.version !== expectedVersion) throw new VersionConflictError(collection, id, expectedVersion);
+			let attempts = 0;
 			try {
-				await client.write(pathFor(collection, id), JSON.stringify({
-					value,
-					version: expectedVersion + 1
-				}), true, existing.etag.replace(/^W\//u, ""));
+				await withTransientRetry(collection, id, () => {
+					attempts += 1;
+					return client.write({
+						pathname: pathFor(collection, id),
+						body: JSON.stringify({
+							value,
+							version: expectedVersion + 1
+						}),
+						overwrite: true,
+						ifMatch: existing.etag.replace(/^W\//u, "")
+					});
+				});
 			} catch (error) {
-				if (isPreconditionError(error)) throw new VersionConflictError(collection, id, expectedVersion);
+				if (isPreconditionError(error)) {
+					if (attempts > 1 && await wroteThisUpdate(collection, id, value, expectedVersion + 1)) return;
+					throw new VersionConflictError(collection, id, expectedVersion);
+				}
 				throw error;
 			}
 		},
 		async list(collection) {
-			const dir = `${prefix}/${collection}/`;
-			const paths = await client.listPaths(dir);
-			const entries = new Array(paths.length);
-			let next = 0;
-			const workers = Array.from({ length: Math.min(readConcurrency, paths.length) }, async () => {
-				while (next < paths.length) {
-					const index = next++;
-					const id = paths[index].slice(dir.length).replace(/\.json$/u, "");
-					const record = await readRecord(collection, id);
-					entries[index] = record === null ? null : {
-						id,
-						record: {
-							value: record.value,
-							version: record.version
+			const active = activeLists.get(collection);
+			if (active !== void 0) return active;
+			const listing = (async () => {
+				const dir = `${prefix}/${collection}/`;
+				const paths = await client.listPaths({ prefix: dir });
+				const entries = new Array(paths.length);
+				let next = 0;
+				let failure;
+				const workers = Array.from({ length: Math.min(readConcurrency, paths.length) }, async () => {
+					while (next < paths.length && failure === void 0) {
+						const index = next++;
+						const id = paths[index].slice(dir.length).replace(/\.json$/u, "");
+						try {
+							const record = await readRecord(collection, id);
+							entries[index] = record === null ? null : {
+								id,
+								record: {
+									value: record.value,
+									version: record.version
+								}
+							};
+						} catch (error) {
+							failure ??= error;
 						}
-					};
-				}
-			});
-			await Promise.all(workers);
-			return entries.filter((entry) => entry !== null);
+					}
+				});
+				await Promise.all(workers);
+				if (failure !== void 0) throw failure;
+				return entries.filter((entry) => entry !== null);
+			})();
+			activeLists.set(collection, listing);
+			try {
+				return await listing;
+			} finally {
+				if (activeLists.get(collection) === listing) activeLists.delete(collection);
+			}
 		}
 	};
 }
 //#endregion
-export { createBlobDriver, vercelBlobClient };
+export { artifactReference, createArtifactStore, createBlobDriver, parseArtifactRef, vercelBlobClient };
 
 //# sourceMappingURL=index.mjs.map

package/dist/blob/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/blob/index.ts"],"sourcesContent":["import { get, list, put } from \"@vercel/blob\";\nimport {\n  RecordExistsError,\n  RecordNotFoundError,\n  VersionConflictError,\n  type CollectionName,\n  type StoredEntry,\n  type StoreDriver,\n} from \"../store/driver\";\n\nexport interface BlobObject {\n  body: string;\n  etag: string;\n}\n\n/** The narrow blob operations the driver needs; injectable for tests. */\nexport interface BlobClient {\n  /** Must return the latest content, never a cached copy. */\n  read(pathname: string): Promise<BlobObject | null>;\n  /** Must reject if overwrite is false and the path exists, or if ifMatch is given and the ETag differs. */\n  write(pathname: string, body: string, overwrite: boolean, ifMatch?: string): Promise<void>;\n  listPaths(prefix: string): Promise<string[]>;\n}\n\n// @vercel/blob throws BlobNotFoundError with the message\n// \"Vercel Blob: The requested blob does not exist\".\nfunction isNotFoundError(error: unknown): boolean {\n  return (\n    error instanceof Error &&\n    (error.name === \"BlobNotFoundError\" ||\n      /does not exist|not.?found|404/iu.test(error.message))\n  );\n}\n\nfunction isAlreadyExistsError(error: unknown): boolean {\n  return (\n    error instanceof Error &&\n    /already exists|not allowed to overwrite|overwrite/iu.test(error.message)\n  );\n}\n\n// @vercel/blob throws BlobPreconditionFailedError when ifMatch does not hold.\nfunction isPreconditionError(error: unknown): boolean {\n  return (\n    error instanceof Error &&\n    (error.name === \"BlobPreconditionFailedError\" || /precondition|etag|412/iu.test(error.message))\n  );\n}\n\nexport const vercelBlobClient: BlobClient = {\n  async read(pathname) {\n    let result;\n    try {\n      // Uncached: the ledger is read-modify-write and must see the latest version.\n      result = await get(pathname, { access: \"private\", useCache: false });\n    } catch (error) {\n      if (isNotFoundError(error)) {\n        return null;\n      }\n      throw error;\n    }\n    if (result === null || result.stream === null) {\n      return null;\n    }\n    return { body: await new Response(result.stream).text(), etag: result.blob.etag };\n  },\n\n  async write(pathname, body, overwrite, ifMatch) {\n    await put(pathname, body, {\n      access: \"private\",\n      allowOverwrite: overwrite,\n      contentType: \"application/json\",\n      ...(ifMatch === undefined ? {} : { ifMatch }),\n    });\n  },\n\n  async listPaths(prefix) {\n    const paths: string[] = [];\n    let cursor: string | undefined;\n    do {\n      const page = await list({ prefix, cursor, limit: 1000 });\n      paths.push(...page.blobs.map((blob) => blob.pathname));\n      cursor = page.hasMore ? page.cursor : undefined;\n    } while (cursor !== undefined);\n    return paths;\n  },\n};\n\nexport interface BlobDriverOptions {\n  client?: BlobClient;\n  /** Path prefix inside the blob store; defaults to \"factory\". */\n  prefix?: string;\n  /** Maximum Blob downloads in flight while listing a collection. Default 32. */\n  readConcurrency?: number;\n}\n\n/**\n * Store driver on Vercel Blob: durable and dependency-free (one Blob store on\n * the project, no database). Inserts are create-if-absent. Updates read the latest content,\n * bypassing Blob's CDN cache, and write with an ETag precondition, so a\n * writer that lost a race gets a VersionConflictError rather than\n * overwriting the winner.\n */\nexport function createBlobDriver(options: BlobDriverOptions = {}): StoreDriver {\n  const client = options.client ?? vercelBlobClient;\n  const prefix = options.prefix ?? \"factory\";\n  const readConcurrency = options.readConcurrency ?? 32;\n  if (!Number.isInteger(readConcurrency) || readConcurrency < 1) {\n    throw new Error(\"Blob read concurrency must be a positive integer\");\n  }\n\n  function pathFor(collection: CollectionName, id: string): string {\n    return `${prefix}/${collection}/${id}.json`;\n  }\n\n  async function readRecord(\n    collection: CollectionName,\n    id: string,\n  ): Promise<{ value: unknown; version: number; etag: string } | null> {\n    let object: BlobObject | null;\n    try {\n      object = await client.read(pathFor(collection, id));\n    } catch (error) {\n      if (isNotFoundError(error)) {\n        return null;\n      }\n      throw error;\n    }\n    if (object === null) {\n      return null;\n    }\n    const parsed = JSON.parse(object.body) as { value: unknown; version: number };\n    if (typeof parsed.version !== \"number\") {\n      throw new Error(`malformed stored record at ${pathFor(collection, id)}`);\n    }\n    return { value: parsed.value, version: parsed.version, etag: object.etag };\n  }\n\n  return {\n    name: \"blob\",\n\n    async get(collection, id) {\n      const record = await readRecord(collection, id);\n      return record === null ? null : { value: record.value, version: record.version };\n    },\n\n    async insert(collection, id, value) {\n      try {\n        await client.write(\n          pathFor(collection, id),\n          JSON.stringify({ value, version: 1 }),\n          false,\n        );\n      } catch (error) {\n        if (isAlreadyExistsError(error)) {\n          throw new RecordExistsError(collection, id);\n        }\n        throw error;\n      }\n    },\n\n    async update(collection, id, value, expectedVersion) {\n      const existing = await readRecord(collection, id);\n      if (existing === null) {\n        throw new RecordNotFoundError(collection, id);\n      }\n      if (existing.version !== expectedVersion) {\n        throw new VersionConflictError(collection, id, expectedVersion);\n      }\n      try {\n        await client.write(\n          pathFor(collection, id),\n          JSON.stringify({ value, version: expectedVersion + 1 }),\n          true,\n          // The write API's ifMatch rejects the weak form (W/\"…\") that reads return.\n          existing.etag.replace(/^W\\//u, \"\"),\n        );\n      } catch (error) {\n        if (isPreconditionError(error)) {\n          throw new VersionConflictError(collection, id, expectedVersion);\n        }\n        throw error;\n      }\n    },\n\n    async list(collection) {\n      const dir = `${prefix}/${collection}/`;\n      const paths = await client.listPaths(dir);\n      const entries: (StoredEntry | null)[] = new Array(paths.length);\n      let next = 0;\n      const workers = Array.from(\n        { length: Math.min(readConcurrency, paths.length) },\n        async () => {\n          while (next < paths.length) {\n            const index = next++;\n            const pathname = paths[index]!;\n            const id = pathname.slice(dir.length).replace(/\\.json$/u, \"\");\n            const record = await readRecord(collection, id);\n            entries[index] = record === null\n              ? null\n              : { id, record: { value: record.value, version: record.version } };\n          }\n        },\n      );\n      await Promise.all(workers);\n      return entries.filter((entry): entry is StoredEntry => entry !== null);\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/blob/index.ts"],"sourcesContent":["import { get, list, put } from \"@vercel/blob\";\nexport {\n  artifactReference,\n  createArtifactStore,\n  parseArtifactRef,\n  type ArtifactRef,\n  type ArtifactInput,\n  type ArtifactKind,\n  type ReadArtifactInput,\n  type ArtifactStore,\n} from \"./artifacts\";\nimport {\n  RecordExistsError,\n  RecordNotFoundError,\n  TransientStoreError,\n  VersionConflictError,\n  type CollectionName,\n  type StoredEntry,\n  type StoreDriver,\n} from \"../store/driver\";\nimport type { MillisecondClock } from \"../schema/common\";\n\n/** Blob content paired with the ETag required for compare-and-swap persistence. */\nexport interface BlobObject {\n  /** Complete UTF-8 body returned by an uncached read. */\n  body: string;\n  /** Current object ETag used to fence a later conditional write. */\n  etag: string;\n}\n\n/** Exact blob pathname requested from storage. */\nexport interface ReadBlobInput {\n  /** Exact namespaced object path; the client must not apply a second namespace. */\n  pathname: string;\n}\n\n/** Blob body and conditional-write policy used for one storage write. */\nexport interface WriteBlobInput extends ReadBlobInput {\n  /** Complete replacement body to persist. */\n  body: string;\n  /** Whether an existing path may be replaced; `false` means create-if-absent. */\n  overwrite: boolean;\n  /** Optional ETag that must still match atomically when overwriting. */\n  ifMatch?: string;\n}\n\n/** Path prefix used to list matching blobs. */\nexport interface ListBlobPathsInput {\n  /** Path prefix whose complete matching object names are requested. */\n  prefix: string;\n}\n\n/** The narrow blob operations the driver needs; injectable for tests. */\nexport interface BlobClient {\n  /**\n   * Returns the latest content rather than a cached copy, or `null` when absent.\n   *\n   * @param input - Exact object path to read.\n   * @returns Current body and ETag, or `null` when the path does not exist.\n   */\n  read(input: ReadBlobInput): Promise<BlobObject | null>;\n  /**\n   * Persists one complete object and enforces its create or ETag precondition atomically.\n   *\n   * @param input - Exact path, body, overwrite policy, and optional ETag fence.\n   * @returns After the object write is durable at the provider boundary.\n   */\n  write(input: WriteBlobInput): Promise<void>;\n  /**\n   * Lists every object path matching the prefix, following all provider pages.\n   *\n   * @param input - Namespace prefix to enumerate.\n   * @returns Matching exact paths; callers do not depend on their order.\n   */\n  listPaths(input: ListBlobPathsInput): Promise<readonly string[]>;\n}\n\n// @vercel/blob throws BlobNotFoundError with the message\n// \"Vercel Blob: The requested blob does not exist\".\nfunction isNotFoundError(error: unknown): boolean {\n  return (\n    error instanceof Error &&\n    (error.name === \"BlobNotFoundError\" || /does not exist|not.?found|404/iu.test(error.message))\n  );\n}\n\nfunction isAlreadyExistsError(error: unknown): boolean {\n  return (\n    error instanceof Error &&\n    /already exists|not allowed to overwrite|overwrite/iu.test(error.message)\n  );\n}\n\n// The SDK also forwards provider conditional-operation conflicts as generic BlobErrors.\nfunction isPreconditionError(error: unknown): boolean {\n  return (\n    error instanceof Error &&\n    (error.name === \"BlobPreconditionFailedError\" ||\n      /precondition|etag|412/iu.test(error.message) ||\n      error.message ===\n        \"Vercel Blob: The conditional request cannot succeed due to a conflicting operation against this resource.\")\n  );\n}\n\nconst TRANSIENT_NETWORK_ERROR_CODES = new Set([\n  \"ECONNRESET\",\n  \"ECONNREFUSED\",\n  \"ETIMEDOUT\",\n  \"ENOTFOUND\",\n  \"EAI_AGAIN\",\n  \"EPIPE\",\n  \"EHOSTUNREACH\",\n  \"ENETUNREACH\",\n  \"UND_ERR_CONNECT_TIMEOUT\",\n  \"UND_ERR_SOCKET\",\n  \"UND_ERR_HEADERS_TIMEOUT\",\n]);\n\n// Blob 5xx/429s and plain network failures are transient: the same read or\n// write is worth retrying with backoff. Direct downloads bypass the SDK's\n// own request-retry policy entirely, and outages can also surface as a\n// generic HTTP error on the write path, so this checks the error's code and\n// message rather than one fixed message shape.\nfunction isTransientBlobError(error: unknown): boolean {\n  if (!(error instanceof Error)) return false;\n  if (isAlreadyExistsError(error) || isPreconditionError(error) || isNotFoundError(error))\n    return false;\n  const code = (error as NodeJS.ErrnoException).code;\n  if (code !== undefined && TRANSIENT_NETWORK_ERROR_CODES.has(code)) return true;\n  if (error.name === \"AbortError\") return true;\n  if (\n    /fetch failed|network|socket hang up|timed? ?out|ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN/iu.test(\n      error.message,\n    )\n  ) {\n    return true;\n  }\n  // Matches an HTTP 429 or 5xx status appearing anywhere in the message,\n  // whether from the direct-download fetch or a generic API error.\n  return /(?:^|[^0-9])(?:429|5\\d{2})(?:[^0-9]|$)/u.test(error.message);\n}\n\n// Structural equality over JSON-serializable values: good enough to tell\n// whether a record we just read back is the exact one we tried to write,\n// without depending on key order surviving a JSON round-trip.\nfunction jsonValuesEqual(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  if (typeof a !== typeof b) return false;\n  if (a === null || b === null || typeof a !== \"object\" || typeof b !== \"object\") return false;\n  if (Array.isArray(a) || Array.isArray(b)) {\n    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;\n    return a.every((item, index) => jsonValuesEqual(item, b[index]));\n  }\n  const aKeys = Object.keys(a as Record<string, unknown>);\n  const bKeys = Object.keys(b as Record<string, unknown>);\n  if (aKeys.length !== bKeys.length) return false;\n  return aKeys.every(\n    (key) =>\n      Object.hasOwn(b as Record<string, unknown>, key) &&\n      jsonValuesEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),\n  );\n}\n\n/**\n * Default private Vercel Blob client used by the durable Factory store driver.\n * Reads explicitly bypass the CDN cache, and writes resolve only after the SDK accepts them.\n */\nexport const vercelBlobClient: BlobClient = {\n  async read({ pathname }) {\n    let result;\n    try {\n      // Uncached: the ledger is read-modify-write and must see the latest version.\n      result = await get(pathname, { access: \"private\", useCache: false });\n    } catch (error) {\n      if (isNotFoundError(error)) {\n        return null;\n      }\n      throw error;\n    }\n    if (result === null || result.stream === null) {\n      return null;\n    }\n    return { body: await new Response(result.stream).text(), etag: result.blob.etag };\n  },\n\n  async write({ pathname, body, overwrite, ifMatch }) {\n    // The SDK treats an empty string as a missing body.\n    await put(pathname, body === \"\" ? Buffer.alloc(0) : body, {\n      access: \"private\",\n      allowOverwrite: overwrite,\n      contentType: \"application/json\",\n      ...(ifMatch === undefined ? {} : { ifMatch: ifMatch.replace(/^W\\//u, \"\") }),\n    });\n  },\n\n  async listPaths({ prefix }) {\n    const paths: string[] = [];\n    let cursor: string | undefined;\n    do {\n      const page = await list({ prefix, cursor, limit: 1000 });\n      paths.push(...page.blobs.map((blob) => blob.pathname));\n      cursor = page.hasMore ? page.cursor : undefined;\n    } while (cursor !== undefined);\n    return paths;\n  },\n};\n\n/** Bounds retries and exponential backoff for transient Blob operations. */\nexport interface BlobRetryOptions {\n  /** Positive integer attempts for one read or write, including the first. Default 3. */\n  attempts?: number;\n  /** Finite non-negative backoff base in milliseconds; doubles each retry. Default 250. */\n  baseDelayMs?: number;\n  /** Finite non-negative elapsed-time ceiling in milliseconds. Default 5000. */\n  maxTotalMs?: number;\n}\n\n/** Configures the Blob client, namespace, read concurrency, and transient retries. */\nexport interface BlobDriverOptions {\n  /** Blob transport used for reads, conditional writes, and listings; defaults to Vercel Blob. */\n  client?: BlobClient;\n  /** Path prefix inside the blob store; defaults to \"factory\". */\n  prefix?: string;\n  /** Maximum Blob downloads in flight while listing a collection. Default 32. */\n  readConcurrency?: number;\n  /** Bounds retry of transient (5xx/429/network) Blob failures on reads and writes. */\n  retry?: BlobRetryOptions;\n  /** Millisecond clock used to bound total retry time. */\n  now?: MillisecondClock;\n}\n\n/**\n * Creates a durable Vercel Blob driver with atomic compare-and-swap updates.\n *\n * @remarks\n * Inserts are create-if-absent. Updates bypass Blob's CDN cache and use the current ETag, so a\n * writer that loses a race receives `VersionConflictError` instead of overwriting the winner.\n * Reads and writes retry only 5xx, 429, and network failures within the configured attempt and\n * elapsed-time bounds; exhaustion surfaces as `TransientStoreError`. If a transient write may\n * have landed before its response was lost, the retry reads the record back and treats only the\n * exact intended value and version as success. A different value remains a real conflict.\n *\n * Collection listing downloads records under the shared `readConcurrency` bound, coalesces\n * concurrent lists of the same collection, and rejects malformed persisted values. Listing the\n * provider's paths itself is not retried by this driver. The caller owns credentials and any\n * injected client's lifecycle.\n *\n * @param options - Optional Blob transport, namespace, read limit, retry policy, and retry clock.\n * @returns A `blob` driver suitable for `createStores`.\n * @throws When concurrency or retry bounds are invalid.\n */\nexport function createBlobDriver(options: BlobDriverOptions = {}): StoreDriver {\n  const client = options.client ?? vercelBlobClient;\n  const now = options.now ?? Date.now;\n  const prefix = options.prefix ?? \"factory\";\n  const readConcurrency = options.readConcurrency ?? 32;\n  if (!Number.isInteger(readConcurrency) || readConcurrency < 1) {\n    throw new Error(\"Blob read concurrency must be a positive integer\");\n  }\n  const retry = {\n    attempts: options.retry?.attempts ?? 3,\n    baseDelayMs: options.retry?.baseDelayMs ?? 250,\n    maxTotalMs: options.retry?.maxTotalMs ?? 5000,\n  };\n  if (!Number.isInteger(retry.attempts) || retry.attempts < 1) {\n    throw new Error(\"Blob retry attempts must be a positive integer\");\n  }\n  if (!Number.isFinite(retry.baseDelayMs) || retry.baseDelayMs < 0) {\n    throw new Error(\"Blob retry base delay must be a finite non-negative number\");\n  }\n  if (!Number.isFinite(retry.maxTotalMs) || retry.maxTotalMs < 0) {\n    throw new Error(\"Blob retry elapsed-time limit must be a finite non-negative number\");\n  }\n  let activeReads = 0;\n  const readWaiters: (() => void)[] = [];\n  const activeLists = new Map<CollectionName, Promise<StoredEntry[]>>();\n\n  // Retries only transient failures, with exponential backoff bounded by\n  // both attempt count and total elapsed time. Non-transient errors (not\n  // found, already exists, precondition/version conflicts, malformed data)\n  // are rethrown immediately and untouched by this loop.\n  async function withTransientRetry<T>(\n    collection: CollectionName,\n    id: string,\n    operation: () => Promise<T>,\n  ): Promise<T> {\n    const start = now();\n    for (let attempt = 0; ; attempt += 1) {\n      try {\n        return await operation();\n      } catch (error) {\n        if (!isTransientBlobError(error)) throw error;\n        const nextDelayMs = retry.baseDelayMs * 2 ** attempt;\n        if (attempt >= retry.attempts - 1 || now() - start + nextDelayMs > retry.maxTotalMs) {\n          throw new TransientStoreError(collection, id, error);\n        }\n        await new Promise((resolve) => setTimeout(resolve, nextDelayMs));\n      }\n    }\n  }\n\n  async function limitedRead(pathname: string): Promise<BlobObject | null> {\n    if (activeReads < readConcurrency) activeReads += 1;\n    else await new Promise<void>((resolve) => readWaiters.push(resolve));\n    try {\n      return await client.read({ pathname });\n    } finally {\n      const waiter = readWaiters.shift();\n      if (waiter === undefined) activeReads -= 1;\n      else waiter();\n    }\n  }\n\n  function pathFor(collection: CollectionName, id: string): string {\n    return `${prefix}/${collection}/${id}.json`;\n  }\n\n  async function readRecord(\n    collection: CollectionName,\n    id: string,\n  ): Promise<{ value: unknown; version: number; etag: string } | null> {\n    let object: BlobObject | null;\n    try {\n      object = await withTransientRetry(collection, id, () => limitedRead(pathFor(collection, id)));\n    } catch (error) {\n      if (isNotFoundError(error)) {\n        return null;\n      }\n      throw error;\n    }\n    if (object === null) {\n      return null;\n    }\n    const parsed = JSON.parse(object.body) as { value: unknown; version: number };\n    if (typeof parsed.version !== \"number\") {\n      throw new Error(`malformed stored record at ${pathFor(collection, id)}`);\n    }\n    return { value: parsed.value, version: parsed.version, etag: object.etag };\n  }\n\n  // A write that fails with a transient error (network drop, 5xx) may still\n  // have landed on the server before the response reached us: the retry\n  // withTransientRetry just took then legitimately collides with our own\n  // prior success. These two helpers disambiguate that case from a real\n  // conflict with another writer by reading the record back and comparing\n  // it to what this call tried to write; only called after this call itself\n  // retried (a fresh, non-retried collision is always a real conflict).\n  async function wroteThisInsert(\n    collection: CollectionName,\n    id: string,\n    value: unknown,\n  ): Promise<boolean> {\n    const after = await readRecord(collection, id);\n    return after !== null && after.version === 1 && jsonValuesEqual(after.value, value);\n  }\n\n  async function wroteThisUpdate(\n    collection: CollectionName,\n    id: string,\n    value: unknown,\n    expectedNewVersion: number,\n  ): Promise<boolean> {\n    const after = await readRecord(collection, id);\n    return (\n      after !== null && after.version === expectedNewVersion && jsonValuesEqual(after.value, value)\n    );\n  }\n\n  return {\n    name: \"blob\",\n\n    async get(collection, id) {\n      const record = await readRecord(collection, id);\n      return record === null ? null : { value: record.value, version: record.version };\n    },\n\n    async insert({ collection, id, value }) {\n      // Tracks whether this call itself retried: a write that fails with a\n      // transient error can still have landed on the server before the\n      // response was lost, so a *retried* write's own \"already exists\"\n      // collision is ambiguous rather than automatically a real conflict.\n      let attempts = 0;\n      try {\n        await withTransientRetry(collection, id, () => {\n          attempts += 1;\n          return client.write({\n            pathname: pathFor(collection, id),\n            body: JSON.stringify({ value, version: 1 }),\n            overwrite: false,\n          });\n        });\n      } catch (error) {\n        if (isAlreadyExistsError(error)) {\n          if (attempts > 1 && (await wroteThisInsert(collection, id, value))) {\n            return;\n          }\n          throw new RecordExistsError(collection, id);\n        }\n        throw error;\n      }\n    },\n\n    async update({ collection, id, value, expectedVersion }) {\n      const existing = await readRecord(collection, id);\n      if (existing === null) {\n        throw new RecordNotFoundError(collection, id);\n      }\n      if (existing.version !== expectedVersion) {\n        throw new VersionConflictError(collection, id, expectedVersion);\n      }\n      // Tracks whether this call itself retried: see the matching comment on\n      // insert() above. A retried update's own precondition failure is\n      // ambiguous in the same way.\n      let attempts = 0;\n      try {\n        await withTransientRetry(collection, id, () => {\n          attempts += 1;\n          return client.write({\n            pathname: pathFor(collection, id),\n            body: JSON.stringify({ value, version: expectedVersion + 1 }),\n            overwrite: true,\n            // The write API's ifMatch rejects the weak form (W/\"…\") that reads return.\n            ifMatch: existing.etag.replace(/^W\\//u, \"\"),\n          });\n        });\n      } catch (error) {\n        if (isPreconditionError(error)) {\n          if (attempts > 1 && (await wroteThisUpdate(collection, id, value, expectedVersion + 1))) {\n            return;\n          }\n          throw new VersionConflictError(collection, id, expectedVersion);\n        }\n        throw error;\n      }\n    },\n\n    async list(collection) {\n      const active = activeLists.get(collection);\n      if (active !== undefined) return active;\n      const listing = (async () => {\n        const dir = `${prefix}/${collection}/`;\n        const paths = await client.listPaths({ prefix: dir });\n        const entries: (StoredEntry | null)[] = new Array(paths.length);\n        let next = 0;\n        let failure: unknown;\n        const workers = Array.from(\n          { length: Math.min(readConcurrency, paths.length) },\n          async () => {\n            while (next < paths.length && failure === undefined) {\n              const index = next++;\n              const pathname = paths[index]!;\n              const id = pathname.slice(dir.length).replace(/\\.json$/u, \"\");\n              try {\n                const record = await readRecord(collection, id);\n                entries[index] =\n                  record === null\n                    ? null\n                    : { id, record: { value: record.value, version: record.version } };\n              } catch (error) {\n                failure ??= error;\n              }\n            }\n          },\n        );\n        await Promise.all(workers);\n        if (failure !== undefined) throw failure;\n        return entries.filter((entry): entry is StoredEntry => entry !== null);\n      })();\n      activeLists.set(collection, listing);\n      try {\n        return await listing;\n      } finally {\n        if (activeLists.get(collection) === listing) activeLists.delete(collection);\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/budget.d.mts

@@ -0,0 +1,115 @@
+import { FactoryId, TaskId } from "./schema/id.mjs";
+import { Task } from "./schema/task.mjs";
+import { DateClock } from "./schema/common.mjs";
+import { BudgetLimits, BudgetMonth } from "./schema/budget.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+//#region src/budget.d.ts
+/**
+ * Stable factory identity for budget rows. Nothing mints factory ids yet, so
+ * the app derives one from a deployment-stable seed such as the Vercel
+ * project id.
+ */
+declare function deriveFactoryId(seed: string): FactoryId;
+/** The budget month ("YYYY-MM", UTC) a timestamp falls into. */
+declare function budgetMonthOf(isoDateTime: string): BudgetMonth;
+/**
+ * Monthly spend is derived from task rows, never stored: each task counts its
+ * settled cost once that exists, otherwise its held reservation. A task
+ * settles once, so a settled row never also counts its reservation.
+ * Attribution uses the reservation time so tasks that wait across a month
+ * boundary charge the month they actually ran in.
+ */
+declare function computeMonthSpendUsd(tasks: readonly Task[], month: BudgetMonth): number;
+/** Derived monthly capacity state before another per-Task reservation. */
+type BudgetStatus = "ok" | "warning" | "exhausted";
+/**
+ * True when one more per-task slice fits under the monthly total. Dispatch
+ * refuses on this exact predicate and budgetStatus reports "exhausted" on its
+ * negation, so refusing and reporting can never disagree.
+ */
+declare function canReserve(spendUsd: number, limits: Pick<BudgetLimits, "totalUsd" | "perTaskReservationUsd">): boolean;
+/** Classify monthly spend using the same exact-fit predicate enforced by dispatch. */
+declare function budgetStatus(spendUsd: number, limits: Pick<BudgetLimits, "totalUsd" | "perTaskReservationUsd" | "warningPercent">): BudgetStatus;
+/** Grace period, clock, and optional snapshot for terminal usage settlement. */
+interface SweepSettlementsOptions {
+  /** How long a terminal task waits for late usage before the sweep settles it. */
+  graceMinutes?: number;
+  now?: DateClock;
+  /** A dispatcher-wide snapshot avoids another complete task read. */
+  tasks?: readonly Task[];
+}
+/** Task-local charges newly settled by one reconciliation pass. */
+interface SweepSettlementsResult {
+  readonly settled: readonly {
+    readonly taskId: TaskId;
+    readonly totalUsd: number;
+  }[];
+}
+/** Task capability required to settle terminal reservations. */
+type SettlementSweepStores = Pick<FactoryStores, "tasks">;
+/**
+ * Settle reserved terminal tasks the session hook did not: a task that ended
+ * after its session (a change verified later) or whose session died. Settles
+ * at the recorded usage, or at zero with a warning reason when none was
+ * recorded within the grace window.
+ */
+declare function sweepSettlements(stores: SettlementSweepStores, options?: SweepSettlementsOptions): Promise<SweepSettlementsResult>;
+/** Owner-only notification emitted when monthly spend crosses a budget threshold. */
+interface BudgetNotice {
+  outcome: "budget_warning" | "budget_exhausted";
+  month: BudgetMonth;
+  spendUsd: number;
+  limits: BudgetLimits;
+}
+/** Monthly limits, delivery hook, and optional snapshot used for budget reconciliation. */
+interface BudgetSweepOptions {
+  factoryId: FactoryId;
+  limits: BudgetLimits;
+  /** Defaults to true. False reports spending without threshold checks or budget notices. */
+  enforce?: boolean;
+  /** Defaults to the current UTC month. */
+  month?: BudgetMonth;
+  now?: DateClock;
+  /** Owner-only delivery; invoked at most once per month per outcome. */
+  notify?: (notice: BudgetNotice) => Promise<void>;
+  /** A dispatcher-wide snapshot avoids another complete task read. */
+  tasks?: readonly Task[];
+}
+/**
+ * Derived monthly spend and exact notice outcome produced by budget reconciliation.
+ * `stamped` means this sweep recorded the threshold, `already_stamped` means no
+ * new stamp was needed, and `delivery_failed` remains eligible for retry.
+ */
+type BudgetSweepResult = {
+  readonly month: BudgetMonth;
+  readonly spendUsd: number;
+  readonly status: "disabled";
+  readonly noticeState: "not_applicable";
+} | {
+  readonly month: BudgetMonth;
+  readonly spendUsd: number;
+  readonly status: "ok";
+  readonly noticeState: "not_applicable";
+} | {
+  readonly month: BudgetMonth;
+  readonly spendUsd: number;
+  readonly status: "warning";
+  readonly noticeState: "stamped" | "already_stamped" | "delivery_failed";
+} | {
+  readonly month: BudgetMonth;
+  readonly spendUsd: number;
+  readonly status: "exhausted";
+  readonly noticeState: "stamped" | "already_stamped" | "delivery_failed";
+};
+/** Budget and Task capabilities required to reconcile monthly budget thresholds. */
+type BudgetSweepStores = Pick<FactoryStores, "budgets" | "tasks">;
+/**
+ * Ensure the month's budget row, derive spend, and record threshold crossings
+ * write-once. Delivery comes first and the stamp only lands after it, so a
+ * failed notification retries on the next sweep instead of being lost; the
+ * write-once stamp still keeps each threshold to one message per month.
+ */
+declare function sweepBudget(stores: BudgetSweepStores, options: BudgetSweepOptions): Promise<BudgetSweepResult>;
+//#endregion
+export { BudgetNotice, BudgetStatus, BudgetSweepOptions, BudgetSweepResult, BudgetSweepStores, SettlementSweepStores, SweepSettlementsOptions, SweepSettlementsResult, budgetMonthOf, budgetStatus, canReserve, computeMonthSpendUsd, deriveFactoryId, sweepBudget, sweepSettlements };
+//# sourceMappingURL=budget.d.mts.map

package/dist/budget.mjs

@@ -0,0 +1,147 @@
+import { factoryIdSchema } from "./schema/id.mjs";
+import { budgetMonthSchema } from "./schema/budget.mjs";
+import { createHash } from "node:crypto";
+//#region src/budget.ts
+/**
+* Stable factory identity for budget rows. Nothing mints factory ids yet, so
+* the app derives one from a deployment-stable seed such as the Vercel
+* project id.
+*/
+function deriveFactoryId(seed) {
+	return factoryIdSchema.parse(`fac_${createHash("sha256").update(seed).digest("hex").slice(0, 32)}`);
+}
+/** The budget month ("YYYY-MM", UTC) a timestamp falls into. */
+function budgetMonthOf(isoDateTime) {
+	return budgetMonthSchema.parse(isoDateTime.slice(0, 7));
+}
+function microsOf(usd) {
+	return Math.round(usd * 1e6);
+}
+/**
+* Monthly spend is derived from task rows, never stored: each task counts its
+* settled cost once that exists, otherwise its held reservation. A task
+* settles once, so a settled row never also counts its reservation.
+* Attribution uses the reservation time so tasks that wait across a month
+* boundary charge the month they actually ran in.
+*/
+function computeMonthSpendUsd(tasks, month) {
+	let spendMicros = 0;
+	for (const task of tasks) {
+		if (budgetMonthOf(task.reservedAt ?? task.createdAt) !== month) continue;
+		spendMicros += microsOf(task.settledUsd ?? task.reservedUsd ?? 0);
+	}
+	return spendMicros / 1e6;
+}
+/**
+* True when one more per-task slice fits under the monthly total. Dispatch
+* refuses on this exact predicate and budgetStatus reports "exhausted" on its
+* negation, so refusing and reporting can never disagree.
+*/
+function canReserve(spendUsd, limits) {
+	return microsOf(spendUsd) + microsOf(limits.perTaskReservationUsd) <= microsOf(limits.totalUsd);
+}
+/** Classify monthly spend using the same exact-fit predicate enforced by dispatch. */
+function budgetStatus(spendUsd, limits) {
+	if (!canReserve(spendUsd, limits)) return "exhausted";
+	if (microsOf(spendUsd) * 100 >= microsOf(limits.totalUsd) * limits.warningPercent) return "warning";
+	return "ok";
+}
+const TERMINAL_TASK_STATES = /* @__PURE__ */ new Set([
+	"succeeded",
+	"failed",
+	"cancelled"
+]);
+/**
+* Settle reserved terminal tasks the session hook did not: a task that ended
+* after its session (a change verified later) or whose session died. Settles
+* at the recorded usage, or at zero with a warning reason when none was
+* recorded within the grace window.
+*/
+async function sweepSettlements(stores, options = {}) {
+	const graceMs = (options.graceMinutes ?? 10) * 6e4;
+	const nowMs = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	const settled = [];
+	for (const task of options.tasks ?? await stores.tasks.list()) {
+		if (task.reservedUsd === void 0 || task.settledUsd !== void 0) continue;
+		if (!TERMINAL_TASK_STATES.has(task.state)) continue;
+		if (nowMs - Date.parse(task.updatedAt) < graceMs) continue;
+		const totalUsd = task.usage?.costUsd ?? 0;
+		try {
+			const result = await stores.tasks.settle(task.id, {
+				cost: { totalUsd },
+				reason: task.usage === void 0 ? "usage missing after ten minutes; settled at zero" : "measured usage settled by sweep"
+			});
+			settled.push({
+				taskId: result.id,
+				totalUsd
+			});
+		} catch {
+			continue;
+		}
+	}
+	return { settled };
+}
+/**
+* Ensure the month's budget row, derive spend, and record threshold crossings
+* write-once. Delivery comes first and the stamp only lands after it, so a
+* failed notification retries on the next sweep instead of being lost; the
+* write-once stamp still keeps each threshold to one message per month.
+*/
+async function sweepBudget(stores, options) {
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	const month = options.month ?? budgetMonthOf(now().toISOString());
+	const budget = await stores.budgets.ensure({
+		factoryId: options.factoryId,
+		month,
+		limits: options.limits
+	});
+	const spendUsd = computeMonthSpendUsd(options.tasks ?? await stores.tasks.list(), month);
+	if (options.enforce === false) return {
+		month,
+		spendUsd,
+		status: "disabled",
+		noticeState: "not_applicable"
+	};
+	const status = budgetStatus(spendUsd, options.limits);
+	async function crossThreshold(notice, outcome) {
+		const field = notice === "warning" ? "warningAt" : "exhaustedAt";
+		if (budget.notices[field] !== void 0) return "already_stamped";
+		if (options.notify !== void 0) try {
+			await options.notify({
+				outcome,
+				month,
+				spendUsd,
+				limits: options.limits
+			});
+		} catch {
+			return "delivery_failed";
+		}
+		return (await stores.budgets.stampNotice(month, notice)).stamped ? "stamped" : "already_stamped";
+	}
+	if (status === "exhausted") {
+		const noticeState = await crossThreshold("exhausted", "budget_exhausted");
+		if (budget.notices.warningAt === void 0) await stores.budgets.stampNotice(month, "warning");
+		return {
+			month,
+			spendUsd,
+			status,
+			noticeState
+		};
+	}
+	if (status === "warning") return {
+		month,
+		spendUsd,
+		status,
+		noticeState: await crossThreshold("warning", "budget_warning")
+	};
+	return {
+		month,
+		spendUsd,
+		status,
+		noticeState: "not_applicable"
+	};
+}
+//#endregion
+export { budgetMonthOf, budgetStatus, canReserve, computeMonthSpendUsd, deriveFactoryId, sweepBudget, sweepSettlements };
+
+//# sourceMappingURL=budget.mjs.map