@vercel/factory 0.0.13 → 0.0.15

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}\n\n/**\n * Store driver on Vercel Blob: durable and dependency-free (one Blob store on\n * the project, no database). Inserts and receipts are exactly as safe as on\n * Postgres (create-if-absent is atomic). 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\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[] = [];\n      for (const pathname of paths) {\n        const id = pathname.slice(dir.length).replace(/\\.json$/u, \"\");\n        const record = await readRecord(collection, id);\n        if (record !== null) {\n          entries.push({ id, record: { value: record.value, version: record.version } });\n        }\n      }\n      return entries;\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  body: string;\n  etag: string;\n}\n\n/** Exact blob pathname requested from storage. */\nexport interface ReadBlobInput {\n  pathname: string;\n}\n\n/** Blob body and conditional-write policy used for one storage write. */\nexport interface WriteBlobInput extends ReadBlobInput {\n  body: string;\n  overwrite: boolean;\n  ifMatch?: string;\n}\n\n/** Path prefix used to list matching blobs. */\nexport interface ListBlobPathsInput {\n  prefix: 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(input: ReadBlobInput): 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(input: WriteBlobInput): Promise<void>;\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// @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\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/** Default private Vercel Blob client used by the durable Factory store driver. */\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  /** Maximum attempts of a single read or write, including the first. Default 3. */\n  attempts?: number;\n  /** Backoff base in milliseconds; doubles each retry. Default 250. */\n  baseDelayMs?: number;\n  /** Ceiling on total elapsed retry time so a real outage still surfaces as a failure. Default 5000. */\n  maxTotalMs?: number;\n}\n\n/** Configures the Blob client, namespace, read concurrency, and transient retries. */\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  /** 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 * 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. Reads and writes retry with backoff on transient\n * (5xx/429/network) failures, bounded by attempts and total elapsed time;\n * once exhausted, the failure surfaces as TransientStoreError so a real\n * outage does not hang a caller retrying forever.\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  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,108 @@
+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 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: "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,141 @@
+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);
+	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

package/dist/budget.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.mjs","names":[],"sources":["../src/budget.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { DateClock } from \"./schema/common\";\nimport { factoryIdSchema, type FactoryId, type TaskId } from \"./schema/id\";\nimport { budgetMonthSchema, type BudgetLimits, type BudgetMonth } from \"./schema/budget\";\nimport type { Task } from \"./schema/task\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/**\n * Stable factory identity for budget rows. Nothing mints factory ids yet, so\n * the app derives one from a deployment-stable seed such as the Vercel\n * project id.\n */\nexport function deriveFactoryId(seed: string): FactoryId {\n  return factoryIdSchema.parse(\n    `fac_${createHash(\"sha256\").update(seed).digest(\"hex\").slice(0, 32)}`,\n  );\n}\n\n/** The budget month (\"YYYY-MM\", UTC) a timestamp falls into. */\nexport function budgetMonthOf(isoDateTime: string): BudgetMonth {\n  return budgetMonthSchema.parse(isoDateTime.slice(0, 7));\n}\n\n// Currency math runs in integer micro-dollars so decimal limits compare\n// exactly; 0.1 + 0.2 must never refuse an exact-fit reservation.\nfunction microsOf(usd: number): number {\n  return Math.round(usd * 1_000_000);\n}\n\n/**\n * Monthly spend is derived from task rows, never stored: each task counts its\n * settled cost once that exists, otherwise its held reservation. A task\n * settles once, so a settled row never also counts its reservation.\n * Attribution uses the reservation time so tasks that wait across a month\n * boundary charge the month they actually ran in.\n */\nexport function computeMonthSpendUsd(tasks: readonly Task[], month: BudgetMonth): number {\n  let spendMicros = 0;\n  for (const task of tasks) {\n    if (budgetMonthOf(task.reservedAt ?? task.createdAt) !== month) {\n      continue;\n    }\n    spendMicros += microsOf(task.settledUsd ?? task.reservedUsd ?? 0);\n  }\n  return spendMicros / 1_000_000;\n}\n\n/** Derived monthly capacity state before another per-Task reservation. */\nexport type BudgetStatus = \"ok\" | \"warning\" | \"exhausted\";\n\n/**\n * True when one more per-task slice fits under the monthly total. Dispatch\n * refuses on this exact predicate and budgetStatus reports \"exhausted\" on its\n * negation, so refusing and reporting can never disagree.\n */\nexport function canReserve(\n  spendUsd: number,\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\">,\n): boolean {\n  return microsOf(spendUsd) + microsOf(limits.perTaskReservationUsd) <= microsOf(limits.totalUsd);\n}\n\n/** Classify monthly spend using the same exact-fit predicate enforced by dispatch. */\nexport function budgetStatus(\n  spendUsd: number,\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\" | \"warningPercent\">,\n): BudgetStatus {\n  if (!canReserve(spendUsd, limits)) {\n    return \"exhausted\";\n  }\n  // Integer comparison: spend/total * 100 >= warningPercent without float\n  // drift on decimal limits.\n  if (microsOf(spendUsd) * 100 >= microsOf(limits.totalUsd) * limits.warningPercent) {\n    return \"warning\";\n  }\n  return \"ok\";\n}\n\nconst TERMINAL_TASK_STATES = new Set<Task[\"state\"]>([\"succeeded\", \"failed\", \"cancelled\"]);\n\n/** Grace period, clock, and optional snapshot for terminal usage settlement. */\nexport interface SweepSettlementsOptions {\n  /** How long a terminal task waits for late usage before the sweep settles it. */\n  graceMinutes?: number;\n  now?: DateClock;\n  /** A dispatcher-wide snapshot avoids another complete task read. */\n  tasks?: readonly Task[];\n}\n\n/** Task-local charges newly settled by one reconciliation pass. */\nexport interface SweepSettlementsResult {\n  readonly settled: readonly { readonly taskId: TaskId; readonly totalUsd: number }[];\n}\n\n/** Task capability required to settle terminal reservations. */\nexport type SettlementSweepStores = Pick<FactoryStores, \"tasks\">;\n\n/**\n * Settle reserved terminal tasks the session hook did not: a task that ended\n * after its session (a change verified later) or whose session died. Settles\n * at the recorded usage, or at zero with a warning reason when none was\n * recorded within the grace window.\n */\nexport async function sweepSettlements(\n  stores: SettlementSweepStores,\n  options: SweepSettlementsOptions = {},\n): Promise<SweepSettlementsResult> {\n  const graceMs = (options.graceMinutes ?? 10) * 60_000;\n  const nowMs = (options.now ?? (() => new Date()))().getTime();\n  const settled: { taskId: TaskId; totalUsd: number }[] = [];\n  for (const task of options.tasks ?? (await stores.tasks.list())) {\n    if (task.reservedUsd === undefined || task.settledUsd !== undefined) {\n      continue;\n    }\n    if (!TERMINAL_TASK_STATES.has(task.state)) {\n      continue;\n    }\n    if (nowMs - Date.parse(task.updatedAt) < graceMs) {\n      continue;\n    }\n    // A concurrent writer (operator retry, another sweep) may move the task\n    // between the list and the settle; skip it rather than aborting the pass.\n    const totalUsd = task.usage?.costUsd ?? 0;\n    try {\n      const result = await stores.tasks.settle(task.id, {\n        cost: { totalUsd },\n        ...{\n          reason:\n            task.usage === undefined\n              ? \"usage missing after ten minutes; settled at zero\"\n              : \"measured usage settled by sweep\",\n        },\n      });\n      // Report this settlement's amount, not the task's accumulated total.\n      settled.push({ taskId: result.id, totalUsd });\n    } catch {\n      continue;\n    }\n  }\n  return { settled };\n}\n\n/** Owner-only notification emitted when monthly spend crosses a budget threshold. */\nexport interface BudgetNotice {\n  outcome: \"budget_warning\" | \"budget_exhausted\";\n  month: BudgetMonth;\n  spendUsd: number;\n  limits: BudgetLimits;\n}\n\n/** Monthly limits, delivery hook, and optional snapshot used for budget reconciliation. */\nexport interface BudgetSweepOptions {\n  factoryId: FactoryId;\n  limits: BudgetLimits;\n  /** Defaults to the current UTC month. */\n  month?: BudgetMonth;\n  now?: DateClock;\n  /** Owner-only delivery; invoked at most once per month per outcome. */\n  notify?: (notice: BudgetNotice) => Promise<void>;\n  /** A dispatcher-wide snapshot avoids another complete task read. */\n  tasks?: readonly Task[];\n}\n\n/**\n * Derived monthly spend and exact notice outcome produced by budget reconciliation.\n * `stamped` means this sweep recorded the threshold, `already_stamped` means no\n * new stamp was needed, and `delivery_failed` remains eligible for retry.\n */\nexport type BudgetSweepResult =\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"ok\";\n      readonly noticeState: \"not_applicable\";\n    }\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"warning\";\n      readonly noticeState: \"stamped\" | \"already_stamped\" | \"delivery_failed\";\n    }\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"exhausted\";\n      readonly noticeState: \"stamped\" | \"already_stamped\" | \"delivery_failed\";\n    };\n\n/** Budget and Task capabilities required to reconcile monthly budget thresholds. */\nexport type BudgetSweepStores = Pick<FactoryStores, \"budgets\" | \"tasks\">;\n\n/**\n * Ensure the month's budget row, derive spend, and record threshold crossings\n * write-once. Delivery comes first and the stamp only lands after it, so a\n * failed notification retries on the next sweep instead of being lost; the\n * write-once stamp still keeps each threshold to one message per month.\n */\nexport async function sweepBudget(\n  stores: BudgetSweepStores,\n  options: BudgetSweepOptions,\n): Promise<BudgetSweepResult> {\n  const now = options.now ?? (() => new Date());\n  const month = options.month ?? budgetMonthOf(now().toISOString());\n  const budget = await stores.budgets.ensure({\n    factoryId: options.factoryId,\n    month,\n    limits: options.limits,\n  });\n  const spendUsd = computeMonthSpendUsd(options.tasks ?? (await stores.tasks.list()), month);\n  const status = budgetStatus(spendUsd, options.limits);\n\n  async function crossThreshold(\n    notice: \"warning\" | \"exhausted\",\n    outcome: BudgetNotice[\"outcome\"],\n  ): Promise<\"stamped\" | \"already_stamped\" | \"delivery_failed\"> {\n    const field = notice === \"warning\" ? \"warningAt\" : \"exhaustedAt\";\n    if (budget.notices[field] !== undefined) {\n      return \"already_stamped\";\n    }\n    if (options.notify !== undefined) {\n      try {\n        await options.notify({ outcome, month, spendUsd, limits: options.limits });\n      } catch {\n        // Leave the notice unstamped so the next sweep retries delivery.\n        return \"delivery_failed\";\n      }\n    }\n    return (await stores.budgets.stampNotice(month, notice)).stamped\n      ? \"stamped\"\n      : \"already_stamped\";\n  }\n\n  if (status === \"exhausted\") {\n    const noticeState = await crossThreshold(\"exhausted\", \"budget_exhausted\");\n    // The warning threshold was necessarily crossed too; stamp it silently so\n    // a later settle-down cannot deliver \"warning\" after \"exhausted\".\n    if (budget.notices.warningAt === undefined) {\n      await stores.budgets.stampNotice(month, \"warning\");\n    }\n    return { month, spendUsd, status, noticeState };\n  }\n  if (status === \"warning\") {\n    const noticeState = await crossThreshold(\"warning\", \"budget_warning\");\n    return { month, spendUsd, status, noticeState };\n  }\n  return { month, spendUsd, status, noticeState: \"not_applicable\" };\n}\n"],"mappings":";;;;;;;;;AAYA,SAAgB,gBAAgB,MAAyB;CACvD,OAAO,gBAAgB,MACrB,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,GAAG,EAAE,GACpE;AACF;;AAGA,SAAgB,cAAc,aAAkC;CAC9D,OAAO,kBAAkB,MAAM,YAAY,MAAM,GAAG,CAAC,CAAC;AACxD;AAIA,SAAS,SAAS,KAAqB;CACrC,OAAO,KAAK,MAAM,MAAM,GAAS;AACnC;;;;;;;;AASA,SAAgB,qBAAqB,OAAwB,OAA4B;CACvF,IAAI,cAAc;CAClB,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,cAAc,KAAK,cAAc,KAAK,SAAS,MAAM,OACvD;EAEF,eAAe,SAAS,KAAK,cAAc,KAAK,eAAe,CAAC;CAClE;CACA,OAAO,cAAc;AACvB;;;;;;AAUA,SAAgB,WACd,UACA,QACS;CACT,OAAO,SAAS,QAAQ,IAAI,SAAS,OAAO,qBAAqB,KAAK,SAAS,OAAO,QAAQ;AAChG;;AAGA,SAAgB,aACd,UACA,QACc;CACd,IAAI,CAAC,WAAW,UAAU,MAAM,GAC9B,OAAO;CAIT,IAAI,SAAS,QAAQ,IAAI,OAAO,SAAS,OAAO,QAAQ,IAAI,OAAO,gBACjE,OAAO;CAET,OAAO;AACT;AAEA,MAAM,uCAAuB,IAAI,IAAmB;CAAC;CAAa;CAAU;AAAW,CAAC;;;;;;;AAyBxF,eAAsB,iBACpB,QACA,UAAmC,CAAC,GACH;CACjC,MAAM,WAAW,QAAQ,gBAAgB,MAAM;CAC/C,MAAM,SAAS,QAAQ,8BAAc,IAAI,KAAK,GAAA,CAAI,CAAC,CAAC,QAAQ;CAC5D,MAAM,UAAkD,CAAC;CACzD,KAAK,MAAM,QAAQ,QAAQ,SAAU,MAAM,OAAO,MAAM,KAAK,GAAI;EAC/D,IAAI,KAAK,gBAAgB,KAAA,KAAa,KAAK,eAAe,KAAA,GACxD;EAEF,IAAI,CAAC,qBAAqB,IAAI,KAAK,KAAK,GACtC;EAEF,IAAI,QAAQ,KAAK,MAAM,KAAK,SAAS,IAAI,SACvC;EAIF,MAAM,WAAW,KAAK,OAAO,WAAW;EACxC,IAAI;GACF,MAAM,SAAS,MAAM,OAAO,MAAM,OAAO,KAAK,IAAI;IAChD,MAAM,EAAE,SAAS;IAEf,QACE,KAAK,UAAU,KAAA,IACX,qDACA;GAEV,CAAC;GAED,QAAQ,KAAK;IAAE,QAAQ,OAAO;IAAI;GAAS,CAAC;EAC9C,QAAQ;GACN;EACF;CACF;CACA,OAAO,EAAE,QAAQ;AACnB;;;;;;;AAyDA,eAAsB,YACpB,QACA,SAC4B;CAC5B,MAAM,MAAM,QAAQ,8BAAc,IAAI,KAAK;CAC3C,MAAM,QAAQ,QAAQ,SAAS,cAAc,IAAI,CAAC,CAAC,YAAY,CAAC;CAChE,MAAM,SAAS,MAAM,OAAO,QAAQ,OAAO;EACzC,WAAW,QAAQ;EACnB;EACA,QAAQ,QAAQ;CAClB,CAAC;CACD,MAAM,WAAW,qBAAqB,QAAQ,SAAU,MAAM,OAAO,MAAM,KAAK,GAAI,KAAK;CACzF,MAAM,SAAS,aAAa,UAAU,QAAQ,MAAM;CAEpD,eAAe,eACb,QACA,SAC4D;EAC5D,MAAM,QAAQ,WAAW,YAAY,cAAc;EACnD,IAAI,OAAO,QAAQ,WAAW,KAAA,GAC5B,OAAO;EAET,IAAI,QAAQ,WAAW,KAAA,GACrB,IAAI;GACF,MAAM,QAAQ,OAAO;IAAE;IAAS;IAAO;IAAU,QAAQ,QAAQ;GAAO,CAAC;EAC3E,QAAQ;GAEN,OAAO;EACT;EAEF,QAAQ,MAAM,OAAO,QAAQ,YAAY,OAAO,MAAM,EAAA,CAAG,UACrD,YACA;CACN;CAEA,IAAI,WAAW,aAAa;EAC1B,MAAM,cAAc,MAAM,eAAe,aAAa,kBAAkB;EAGxE,IAAI,OAAO,QAAQ,cAAc,KAAA,GAC/B,MAAM,OAAO,QAAQ,YAAY,OAAO,SAAS;EAEnD,OAAO;GAAE;GAAO;GAAU;GAAQ;EAAY;CAChD;CACA,IAAI,WAAW,WAEb,OAAO;EAAE;EAAO;EAAU;EAAQ,aAAA,MADR,eAAe,WAAW,gBAAgB;CACtB;CAEhD,OAAO;EAAE;EAAO;EAAU;EAAQ,aAAa;CAAiB;AAClE"}

package/dist/budgets.d.mts

@@ -0,0 +1,4 @@
+import { Budget, BudgetLimits, BudgetMonth, budgetLimitsSchema, budgetMonthSchema, budgetSchema } from "./schema/budget.mjs";
+import { BudgetNoticeStampResult, EnsureBudgetInput, SettleTaskInput, SettlementError } from "./store/engine.mjs";
+import { BudgetNotice, BudgetStatus, BudgetSweepOptions, BudgetSweepResult, BudgetSweepStores, SettlementSweepStores, SweepSettlementsOptions, SweepSettlementsResult, budgetMonthOf, budgetStatus, canReserve, computeMonthSpendUsd, sweepBudget, sweepSettlements } from "./budget.mjs";
+export { type Budget, type BudgetLimits, type BudgetMonth, type BudgetNotice, type BudgetNoticeStampResult, type BudgetStatus, type BudgetSweepOptions, type BudgetSweepResult, type BudgetSweepStores, type EnsureBudgetInput, type SettleTaskInput, SettlementError, type SettlementSweepStores, type SweepSettlementsOptions, type SweepSettlementsResult, budgetLimitsSchema, budgetMonthOf, budgetMonthSchema, budgetSchema, budgetStatus, canReserve, computeMonthSpendUsd, sweepBudget, sweepSettlements };

package/dist/budgets.mjs

@@ -0,0 +1,4 @@
+import { budgetLimitsSchema, budgetMonthSchema, budgetSchema } from "./schema/budget.mjs";
+import { budgetMonthOf, budgetStatus, canReserve, computeMonthSpendUsd, sweepBudget, sweepSettlements } from "./budget.mjs";
+import { SettlementError } from "./store/engine.mjs";
+export { SettlementError, budgetLimitsSchema, budgetMonthOf, budgetMonthSchema, budgetSchema, budgetStatus, canReserve, computeMonthSpendUsd, sweepBudget, sweepSettlements };

package/dist/build-factory.d.mts

@@ -1,12 +1,14 @@
-import { r as FactoryConfigInput } from "./factory-config-D2yU3G0c.mjs";
+import { FactoryConfigInput } from "./schema/factory-config.mjs";
 import { EveNextConfig, EveNextConfigFunction, EveNextConfigInput } from "eve/next";
 //#region src/build-factory.d.ts
-interface FactoryArgs<TConfig extends EveNextConfig = EveNextConfig> {
+/** Inputs for validating a Factory configuration and discovering its Eve agents at build time. */
+interface BuildFactoryOptions<TConfig extends EveNextConfig = EveNextConfig> {
   factoryConfig: FactoryConfigInput;
   nextConfig: EveNextConfigInput<TConfig>;
   root?: string;
 }
-declare function buildFactory<TConfig extends EveNextConfig>({ factoryConfig, nextConfig, root }: FactoryArgs<TConfig>): EveNextConfigFunction<TConfig>;
+/** Create an Eve Next.js configuration wrapper for the agents beneath a Factory project root. */
+declare function buildFactory<TConfig extends EveNextConfig>({ factoryConfig, nextConfig, root }: BuildFactoryOptions<TConfig>): EveNextConfigFunction<TConfig>;
 //#endregion
-export { FactoryArgs, buildFactory };
+export { BuildFactoryOptions, buildFactory };
 //# sourceMappingURL=build-factory.d.mts.map

package/dist/build-factory.mjs

@@ -1,7 +1,8 @@
-import { n as defineFactory } from "./factory-config-BJcjsPKl.mjs";
+import { defineFactory } from "./schema/factory-config.mjs";
 import { readdirSync } from "node:fs";
 import path from "node:path";
 //#region src/build-factory.ts
+/** Create an Eve Next.js configuration wrapper for the agents beneath a Factory project root. */
 function buildFactory({ factoryConfig, nextConfig, root = process.cwd() }) {
 	defineFactory(factoryConfig);
 	const agentDefinitions = Object.fromEntries(readdirSync(path.join(root, "agents"), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => [entry.name, path.join(root, "agents", entry.name)]));

package/dist/build-factory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"build-factory.mjs","names":[],"sources":["../src/build-factory.ts"],"sourcesContent":["import { readdirSync } from \"node:fs\";\nimport path from \"node:path\";\nimport {\n  type EveNextConfig,\n  type EveNextConfigFunction,\n  type EveNextConfigInput,\n  type WithEveAgentsConfig,\n} from \"eve/next\";\nimport { defineFactory, type FactoryConfigInput } from \"./schema/factory-config\";\n\nexport interface FactoryArgs<TConfig extends EveNextConfig = EveNextConfig> {\n  factoryConfig: FactoryConfigInput;\n  nextConfig: EveNextConfigInput<TConfig>;\n  root?: string;\n}\n\nexport function buildFactory<TConfig extends EveNextConfig>({\n  factoryConfig,\n  nextConfig,\n  root = process.cwd(),\n}: FactoryArgs<TConfig>): EveNextConfigFunction<TConfig> {\n  defineFactory(factoryConfig);\n  const agentDefinitions: WithEveAgentsConfig = Object.fromEntries(\n    readdirSync(path.join(root, \"agents\"), { withFileTypes: true })\n      .filter((entry) => entry.isDirectory())\n      .map((entry) => [entry.name, path.join(root, \"agents\", entry.name)]),\n  );\n  return async (phase, context) => {\n    const { withEve } = await import(\"eve/next\");\n    return withEve(nextConfig, { agents: agentDefinitions })(phase, context);\n  };\n}\n"],"mappings":";;;;AAgBA,SAAgB,aAA4C,EAC1D,eACA,YACA,OAAO,QAAQ,IAAI,KACoC;CACvD,cAAc,aAAa;CAC3B,MAAM,mBAAwC,OAAO,YACnD,YAAY,KAAK,KAAK,MAAM,QAAQ,GAAG,EAAE,eAAe,KAAK,CAAC,CAAC,CAC5D,QAAQ,UAAU,MAAM,YAAY,CAAC,CAAC,CACtC,KAAK,UAAU,CAAC,MAAM,MAAM,KAAK,KAAK,MAAM,UAAU,MAAM,IAAI,CAAC,CAAC,CACvE;CACA,OAAO,OAAO,OAAO,YAAY;EAC/B,MAAM,EAAE,YAAY,MAAM,OAAO;EACjC,OAAO,QAAQ,YAAY,EAAE,QAAQ,iBAAiB,CAAC,CAAC,CAAC,OAAO,OAAO;CACzE;AACF"}
+{"version":3,"file":"build-factory.mjs","names":[],"sources":["../src/build-factory.ts"],"sourcesContent":["import { readdirSync } from \"node:fs\";\nimport path from \"node:path\";\nimport {\n  type EveNextConfig,\n  type EveNextConfigFunction,\n  type EveNextConfigInput,\n  type WithEveAgentsConfig,\n} from \"eve/next\";\nimport { defineFactory, type FactoryConfigInput } from \"./schema/factory-config\";\n\n/** Inputs for validating a Factory configuration and discovering its Eve agents at build time. */\nexport interface BuildFactoryOptions<TConfig extends EveNextConfig = EveNextConfig> {\n  factoryConfig: FactoryConfigInput;\n  nextConfig: EveNextConfigInput<TConfig>;\n  root?: string;\n}\n\n/** Create an Eve Next.js configuration wrapper for the agents beneath a Factory project root. */\nexport function buildFactory<TConfig extends EveNextConfig>({\n  factoryConfig,\n  nextConfig,\n  root = process.cwd(),\n}: BuildFactoryOptions<TConfig>): EveNextConfigFunction<TConfig> {\n  defineFactory(factoryConfig);\n  const agentDefinitions: WithEveAgentsConfig = Object.fromEntries(\n    readdirSync(path.join(root, \"agents\"), { withFileTypes: true })\n      .filter((entry) => entry.isDirectory())\n      .map((entry) => [entry.name, path.join(root, \"agents\", entry.name)]),\n  );\n  return async (phase, context) => {\n    const { withEve } = await import(\"eve/next\");\n    return withEve(nextConfig, { agents: agentDefinitions })(phase, context);\n  };\n}\n"],"mappings":";;;;;AAkBA,SAAgB,aAA4C,EAC1D,eACA,YACA,OAAO,QAAQ,IAAI,KAC4C;CAC/D,cAAc,aAAa;CAC3B,MAAM,mBAAwC,OAAO,YACnD,YAAY,KAAK,KAAK,MAAM,QAAQ,GAAG,EAAE,eAAe,KAAK,CAAC,CAAC,CAC5D,QAAQ,UAAU,MAAM,YAAY,CAAC,CAAC,CACtC,KAAK,UAAU,CAAC,MAAM,MAAM,KAAK,KAAK,MAAM,UAAU,MAAM,IAAI,CAAC,CAAC,CACvE;CACA,OAAO,OAAO,OAAO,YAAY;EAC/B,MAAM,EAAE,YAAY,MAAM,OAAO;EACjC,OAAO,QAAQ,YAAY,EAAE,QAAQ,iBAAiB,CAAC,CAAC,CAAC,OAAO,OAAO;CACzE;AACF"}

package/dist/change-verification/brief.d.mts

@@ -0,0 +1,9 @@
+import { Repository } from "../schema/repository.mjs";
+import { Task } from "../schema/task.mjs";
+import { Change } from "../schema/change.mjs";
+//#region src/change-verification/brief.d.ts
+/** Format the starting brief for independently verifying a recorded Change. */
+declare function formatChangeVerificationBrief(task: Task, repository: Repository, change: Change): string;
+//#endregion
+export { formatChangeVerificationBrief };
+//# sourceMappingURL=brief.d.mts.map

package/dist/change-verification/brief.mjs

@@ -0,0 +1,13 @@
+//#region src/change-verification/brief.ts
+/** Format the starting brief for independently verifying a recorded Change. */
+function formatChangeVerificationBrief(task, repository, change) {
+	return [
+		`You are assigned factory verification task ${task.id} in repository ${repository.slug}.`,
+		`Change under review: ${change.id} (${change.prUrl}).`,
+		"Read the task with get_task, independently inspect and test the change, then call record_verification with every evidence field."
+	].join("\n");
+}
+//#endregion
+export { formatChangeVerificationBrief };
+
+//# sourceMappingURL=brief.mjs.map

package/dist/change-verification/brief.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"brief.mjs","names":[],"sources":["../../src/change-verification/brief.ts"],"sourcesContent":["import type { Change } from \"../schema/change\";\nimport type { Repository } from \"../schema/repository\";\nimport type { Task } from \"../schema/task\";\n\n/** Format the starting brief for independently verifying a recorded Change. */\nexport function formatChangeVerificationBrief(\n  task: Task,\n  repository: Repository,\n  change: Change,\n): string {\n  return [\n    `You are assigned factory verification task ${task.id} in repository ${repository.slug}.`,\n    `Change under review: ${change.id} (${change.prUrl}).`,\n    \"Read the task with get_task, independently inspect and test the change, then call record_verification with every evidence field.\",\n  ].join(\"\\n\");\n}\n"],"mappings":";;AAKA,SAAgB,8BACd,MACA,YACA,QACQ;CACR,OAAO;EACL,8CAA8C,KAAK,GAAG,iBAAiB,WAAW,KAAK;EACvF,wBAAwB,OAAO,GAAG,IAAI,OAAO,MAAM;EACnD;CACF,CAAC,CAAC,KAAK,IAAI;AACb"}

package/dist/change-verification/dispatch.d.mts

@@ -0,0 +1,24 @@
+import { TaskId } from "../schema/id.mjs";
+import { AgentRouteBinding } from "../schema/agent-route.mjs";
+import { Task } from "../schema/task.mjs";
+import "../agent-routes.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+//#region src/change-verification/dispatch.d.ts
+/** Store capabilities required to inspect and create verification Tasks. */
+type ChangeVerificationStores = Pick<FactoryStores, "tasks">;
+/** Verification Tasks admitted or found idempotently by one reconciliation pass. */
+interface EnsureChangeVerificationTasksResult {
+  readonly created: readonly TaskId[];
+  readonly existing: readonly TaskId[];
+}
+/** Stores, optional snapshot, and exact verifier route used by one admission pass. */
+interface EnsureChangeVerificationTasksOptions {
+  readonly stores: ChangeVerificationStores;
+  readonly tasks?: readonly Task[];
+  readonly route?: AgentRouteBinding;
+}
+/** Supplied code-change policy: admit one verification child per Change and exact verifier binding. */
+declare function ensureChangeVerificationTasks(options: EnsureChangeVerificationTasksOptions): Promise<EnsureChangeVerificationTasksResult>;
+//#endregion
+export { ChangeVerificationStores, EnsureChangeVerificationTasksOptions, EnsureChangeVerificationTasksResult, ensureChangeVerificationTasks };
+//# sourceMappingURL=dispatch.d.mts.map

package/dist/change-verification/dispatch.mjs

@@ -0,0 +1,45 @@
+import { parseAgentRouteBinding } from "../schema/agent-route.mjs";
+import { routeKey, routeTaskWork } from "../agent-routes.mjs";
+//#region src/change-verification/dispatch.ts
+/** Supplied code-change policy: admit one verification child per Change and exact verifier binding. */
+async function ensureChangeVerificationTasks(options) {
+	const { stores } = options;
+	const route = options.route ?? parseAgentRouteBinding({
+		id: "verification",
+		version: 1
+	});
+	const tasks = options.tasks ?? await stores.tasks.list();
+	const existingIds = new Set(tasks.map((task) => task.id));
+	const result = {
+		created: [],
+		existing: []
+	};
+	const sources = tasks.filter((task) => task.work.route?.id === "code-change" && task.state === "verifying" && task.changeId !== void 0);
+	for (const source of sources) {
+		const existing = tasks.find((task) => task.work.route !== void 0 && routeKey(task.work.route) === routeKey(route) && task.parentTaskId === source.id && task.changeId === source.changeId);
+		if (existing !== void 0) {
+			result.existing.push(existing.id);
+			continue;
+		}
+		const verification = await stores.tasks.create({
+			repositoryIds: source.repositoryIds,
+			kind: "verification",
+			work: routeTaskWork({
+				route,
+				title: `Verify change ${source.changeId}`,
+				input: { changeId: source.changeId }
+			}),
+			origin: {},
+			parentTaskId: source.id,
+			replyTo: source.replyTo,
+			changeId: source.changeId,
+			dedupeKey: `verification:${source.id}:${source.changeId}:${routeKey(route)}`
+		});
+		(existingIds.has(verification.id) ? result.existing : result.created).push(verification.id);
+	}
+	return result;
+}
+//#endregion
+export { ensureChangeVerificationTasks };
+
+//# sourceMappingURL=dispatch.mjs.map

package/dist/change-verification/dispatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.mjs","names":[],"sources":["../../src/change-verification/dispatch.ts"],"sourcesContent":["import {\n  parseAgentRouteBinding,\n  routeKey,\n  routeTaskWork,\n  type AgentRouteBinding,\n} from \"../agent-routes\";\nimport type { TaskId } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport type { FactoryStores } from \"../store/engine\";\n\n/** Store capabilities required to inspect and create verification Tasks. */\nexport type ChangeVerificationStores = Pick<FactoryStores, \"tasks\">;\n\n/** Verification Tasks admitted or found idempotently by one reconciliation pass. */\nexport interface EnsureChangeVerificationTasksResult {\n  readonly created: readonly TaskId[];\n  readonly existing: readonly TaskId[];\n}\n\n/** Stores, optional snapshot, and exact verifier route used by one admission pass. */\nexport interface EnsureChangeVerificationTasksOptions {\n  readonly stores: ChangeVerificationStores;\n  readonly tasks?: readonly Task[];\n  readonly route?: AgentRouteBinding;\n}\n\n/** Supplied code-change policy: admit one verification child per Change and exact verifier binding. */\nexport async function ensureChangeVerificationTasks(\n  options: EnsureChangeVerificationTasksOptions,\n): Promise<EnsureChangeVerificationTasksResult> {\n  const { stores } = options;\n  const route = options.route ?? parseAgentRouteBinding({ id: \"verification\", version: 1 });\n  const tasks = options.tasks ?? (await stores.tasks.list());\n  const existingIds = new Set(tasks.map((task) => task.id));\n  const result: { created: TaskId[]; existing: TaskId[] } = { created: [], existing: [] };\n  const sources = tasks.filter(\n    (task) =>\n      task.work.route?.id === \"code-change\" &&\n      task.state === \"verifying\" &&\n      task.changeId !== undefined,\n  );\n\n  for (const source of sources) {\n    const existing = tasks.find(\n      (task) =>\n        task.work.route !== undefined &&\n        routeKey(task.work.route) === routeKey(route) &&\n        task.parentTaskId === source.id &&\n        task.changeId === source.changeId,\n    );\n    if (existing !== undefined) {\n      result.existing.push(existing.id);\n      continue;\n    }\n    const verification = await stores.tasks.create({\n      repositoryIds: source.repositoryIds,\n      kind: \"verification\",\n      work: routeTaskWork({\n        route: route,\n        title: `Verify change ${source.changeId}`,\n        input: {\n          changeId: source.changeId!,\n        },\n      }),\n      origin: {},\n      parentTaskId: source.id,\n      replyTo: source.replyTo,\n      changeId: source.changeId,\n      dedupeKey: `verification:${source.id}:${source.changeId}:${routeKey(route)}`,\n    });\n    (existingIds.has(verification.id) ? result.existing : result.created).push(verification.id);\n  }\n\n  return result;\n}\n"],"mappings":";;;;AA2BA,eAAsB,8BACpB,SAC8C;CAC9C,MAAM,EAAE,WAAW;CACnB,MAAM,QAAQ,QAAQ,SAAS,uBAAuB;EAAE,IAAI;EAAgB,SAAS;CAAE,CAAC;CACxF,MAAM,QAAQ,QAAQ,SAAU,MAAM,OAAO,MAAM,KAAK;CACxD,MAAM,cAAc,IAAI,IAAI,MAAM,KAAK,SAAS,KAAK,EAAE,CAAC;CACxD,MAAM,SAAoD;EAAE,SAAS,CAAC;EAAG,UAAU,CAAC;CAAE;CACtF,MAAM,UAAU,MAAM,QACnB,SACC,KAAK,KAAK,OAAO,OAAO,iBACxB,KAAK,UAAU,eACf,KAAK,aAAa,KAAA,CACtB;CAEA,KAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,WAAW,MAAM,MACpB,SACC,KAAK,KAAK,UAAU,KAAA,KACpB,SAAS,KAAK,KAAK,KAAK,MAAM,SAAS,KAAK,KAC5C,KAAK,iBAAiB,OAAO,MAC7B,KAAK,aAAa,OAAO,QAC7B;EACA,IAAI,aAAa,KAAA,GAAW;GAC1B,OAAO,SAAS,KAAK,SAAS,EAAE;GAChC;EACF;EACA,MAAM,eAAe,MAAM,OAAO,MAAM,OAAO;GAC7C,eAAe,OAAO;GACtB,MAAM;GACN,MAAM,cAAc;IACX;IACP,OAAO,iBAAiB,OAAO;IAC/B,OAAO,EACL,UAAU,OAAO,SACnB;GACF,CAAC;GACD,QAAQ,CAAC;GACT,cAAc,OAAO;GACrB,SAAS,OAAO;GAChB,UAAU,OAAO;GACjB,WAAW,gBAAgB,OAAO,GAAG,GAAG,OAAO,SAAS,GAAG,SAAS,KAAK;EAC3E,CAAC;EACD,CAAC,YAAY,IAAI,aAAa,EAAE,IAAI,OAAO,WAAW,OAAO,QAAA,CAAS,KAAK,aAAa,EAAE;CAC5F;CAEA,OAAO;AACT"}

package/dist/change-verification/eve-tool.d.mts

@@ -0,0 +1,60 @@
+import { ChangeId, TaskId } from "../schema/id.mjs";
+import { ChangeEvidence, ChangeLevel, ChangeState } from "../schema/change.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { ToolContext, ToolDefinition } from "eve/tools";
+//#region src/change-verification/eve-tool.d.ts
+/** Change and Task capabilities required by the verification-result tool. */
+type RecordVerificationToolStores = Pick<FactoryStores, "changes" | "tasks">;
+/** Verified outcome presented after its Task and Change updates commit. */
+interface PresentVerificationResultInput {
+  taskId: TaskId;
+  changeId: ChangeId;
+  verdict: "pass" | "fail";
+  summary: string;
+}
+/** Configures presentation after a verification verdict has been durably recorded. */
+interface RecordVerificationToolOptions {
+  presentResult?: (input: PresentVerificationResultInput) => Promise<void>;
+}
+/** Evidence and verdict supplied by the verifier for one Change. */
+interface RecordVerificationInput {
+  taskId: TaskId;
+  changeId: ChangeId;
+  verdict: "pass" | "fail";
+  evidence: ChangeEvidence;
+  confidence: ChangeLevel;
+  summary: string;
+}
+/** Bounded refusal returned when a verification result cannot be associated safely. */
+interface RecordVerificationRefusal {
+  readonly recorded: false;
+  readonly reason: string;
+}
+/** Durable lifecycle state returned after a verification verdict is recorded. */
+interface RecordVerificationSuccess {
+  readonly recorded: true;
+  readonly verdict: "pass" | "fail";
+  readonly changeState: ChangeState;
+  readonly taskState: "succeeded" | "failed";
+}
+/** Recorded verification state or bounded association refusal. */
+type RecordVerificationResult = RecordVerificationRefusal | RecordVerificationSuccess;
+/** Eve outcome tool that records evidence and a verdict for one Change. */
+interface RecordVerificationTool extends ToolDefinition<RecordVerificationInput, RecordVerificationResult> {
+  execute(input: RecordVerificationInput, ctx: ToolContext): Promise<RecordVerificationResult>;
+}
+/**
+ * The verifier's outcome tool. Writes evidence onto the change and moves it
+ * to ready only when the verdict is pass; a failed verdict leaves the change
+ * verifying with the evidence recorded, and the verification task itself
+ * ends with a receipt either way. The change's own code_change task follows
+ * the verdict too: succeeded on pass, failed on fail with the verifier's
+ * summary as the reason, so the ledger never shows a verified-and-rejected fix
+ * as still in progress. Fail closed: the agent cannot mark a change ready
+ * without supplying every evidence field. Requires the authenticated current
+ * Task execution and matching parent, Change, and repository associations.
+ */
+declare function createRecordVerificationTool(stores: RecordVerificationToolStores, options?: RecordVerificationToolOptions): RecordVerificationTool;
+//#endregion
+export { PresentVerificationResultInput, RecordVerificationInput, RecordVerificationRefusal, RecordVerificationResult, RecordVerificationSuccess, RecordVerificationTool, RecordVerificationToolOptions, RecordVerificationToolStores, createRecordVerificationTool };
+//# sourceMappingURL=eve-tool.d.mts.map