@warlock.js/core 4.8.0 → 4.8.2

package/esm/ai/src/batch/batch.mjs

@@ -1,198 +0,0 @@
-import { accumulateCost } from "../utils/compute-cost.mjs";
-import { generateRunId } from "../utils/generate-run-id.mjs";
-import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
-import { runBatchItem } from "./run-batch-item.mjs";
-import { runWithConcurrency } from "./run-with-concurrency.mjs";
-
-//#region ../@warlock.js/ai/src/batch/batch.ts
-/** Batch size above which an unset (unbounded) concurrency warns once (D5). */
-const BATCH_UNBOUNDED_WARN_THRESHOLD = 50;
-/** Process-lifetime flag so the unbounded-batch warning fires at most once. */
-let warnedUnboundedBatch = false;
-/**
-* Run an executable AI primitive (agent, workflow, supervisor, tool,
-* or anything satisfying {@link ExecutableContract}) over a dataset
-* with bounded concurrency and per-item retry, returning per-item
-* outcomes plus rolled-up usage and a walkable report tree.
-*
-* **Role.** The fan-out primitive of `@warlock.js/ai`. Where an agent
-* runs once, `batch` runs the SAME executable N times — once per item
-* — and aggregates the results into the unified {@link ExecuteResult}
-* envelope, so a batch slots into cost dashboards and trace tooling
-* exactly like a single run does.
-*
-* **Isolation.** Items are independent: one item's failure (after its
-* retries are exhausted) never cancels a sibling, and the batch as a
-* whole never rejects — failures live on each {@link BatchItemResult}.
-* Reach for `result.report.failed` / `item.status` to inspect them.
-*
-* **Usage rollup.** `result.usage` and `result.report.usage` sum every
-* item's usage, satisfying the universal rollup invariant ("own cost
-* + sum of children"; a batch has zero own cost). Each item's own
-* report is attached under `report.children[]`, in original item
-* order, so a trace walker sees every run.
-*
-* @example
-* const result = await batch(summarizer, articles, {
-*   concurrency: 4,
-*   retry: { attempts: 3, backoff: "exponential" },
-*   onItem: (item) => log.info("batch", "item", "settled", { index: item.index }),
-* });
-*
-* console.log(`${result.report.succeeded}/${result.report.total} ok`);
-* console.log(`${result.usage.total} tokens total`);
-*/
-async function batch(executable, items, options = {}) {
-	return new BatchRun(executable, items, options).run();
-}
-/**
-* Per-call orchestration state for one {@link batch} invocation.
-* Instantiated fresh inside the factory so the mutable accumulators
-* (`results`, `usage`) are never shared across batches. Unexported —
-* callers only ever see the plain {@link BatchResult}.
-*/
-var BatchRun = class {
-	constructor(executable, items, options) {
-		this.executable = executable;
-		this.items = items;
-		this.options = options;
-		this.startedAt = (/* @__PURE__ */ new Date()).toISOString();
-		this.startPerf = performance.now();
-		this.runId = generateRunId("batch");
-		this.results = new Array(items.length);
-	}
-	/**
-	* Dispatch every item through the concurrency pool, then assemble
-	* the rolled-up {@link BatchResult}. Runs once per `batch()` call.
-	*/
-	async run() {
-		const concurrency = this.resolveConcurrency();
-		await runWithConcurrency(this.items.length, concurrency, (index) => this.processItem(index));
-		return this.buildResult();
-	}
-	/**
-	* Resolve the effective concurrency from {@link BatchOptions.concurrency}
-	* (D5). An explicit number or `"unbounded"` is honored as-is; an omitted
-	* value runs unbounded for back-compat but warns once (outside tests)
-	* for a large batch so an accidental all-at-once run is visible.
-	*/
-	resolveConcurrency() {
-		const configured = this.options.concurrency;
-		if (configured === "unbounded") return this.items.length;
-		if (typeof configured === "number") return configured;
-		if (this.items.length > BATCH_UNBOUNDED_WARN_THRESHOLD && !warnedUnboundedBatch && !process.env.VITEST && process.env.NODE_ENV !== "test") {
-			warnedUnboundedBatch = true;
-			console.warn(`[warlock-ai] ai.batch() is running ${this.items.length} items with unbounded concurrency (no \`concurrency\` set). Each concurrent item consumes tokens/quota/memory — pass an explicit \`concurrency\` cap, or \`concurrency: "unbounded"\` to silence this.`);
-		}
-		return this.items.length;
-	}
-	/**
-	* Run a single item with retry, record it positionally, then fire
-	* the `onItem` hook. A throw from the hook is swallowed — a progress
-	* callback must never break the batch.
-	*/
-	async processItem(index) {
-		const item = await runBatchItem({
-			index,
-			input: this.items[index],
-			executable: this.executable,
-			retry: this.options.retry,
-			signal: this.options.signal
-		});
-		this.results[index] = item;
-		if (this.options.onItem) try {
-			await this.options.onItem(item);
-		} catch {}
-	}
-	/**
-	* Fold the per-item outcomes into rolled-up usage, the child report
-	* list, and the final {@link BatchResult}, then stamp lineage across
-	* the whole subtree so every child shares this batch's root run id.
-	*/
-	buildResult() {
-		const usage = {
-			input: 0,
-			output: 0,
-			total: 0
-		};
-		const children = [];
-		const data = new Array(this.items.length).fill(void 0);
-		let succeeded = 0;
-		let failed = 0;
-		let cancelled = 0;
-		for (const item of this.results) {
-			if (item.status === "completed") succeeded += 1;
-			else if (item.status === "failed") failed += 1;
-			else cancelled += 1;
-			const itemResult = item.result;
-			if (itemResult) {
-				this.mergeUsage(usage, itemResult.usage);
-				if ("report" in itemResult && itemResult.report) children.push(itemResult.report);
-				if (item.status === "completed" && "data" in itemResult) data[item.index] = itemResult.data;
-			}
-		}
-		const report = this.buildReport(usage, children, {
-			succeeded,
-			failed,
-			cancelled
-		});
-		stampReportLineage(report, {
-			rootRunId: this.runId,
-			sessionId: this.options.sessionId
-		});
-		return {
-			type: "batch",
-			data,
-			usage,
-			report,
-			items: this.results
-		};
-	}
-	/**
-	* Add a child's usage into the running batch total. Scalar token
-	* channels sum directly; the optional cost breakdown merges via
-	* {@link accumulateCost} so a single unpriced child can't erase the
-	* cost of priced siblings. Optional token sub-channels
-	* (`cachedTokens`, etc.) accumulate only when some child reports
-	* them, preserving the "never reported anywhere" signal.
-	*/
-	mergeUsage(target, child) {
-		target.input += child.input;
-		target.output += child.output;
-		target.total += child.total;
-		if (child.cachedTokens !== void 0) target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;
-		if (child.reasoningTokens !== void 0) target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;
-		if (child.cacheWriteTokens !== void 0) target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;
-		const mergedCost = accumulateCost(target.cost, child.cost);
-		if (mergedCost !== void 0) target.cost = mergedCost;
-	}
-	/**
-	* Build the batch's own {@link BatchReport} node. `parentRunId` /
-	* `rootRunId` are placeholders here — {@link stampReportLineage}
-	* rewrites them across the whole subtree right after.
-	*/
-	buildReport(usage, children, counts) {
-		const status = counts.failed > 0 || counts.cancelled > 0 ? "failed" : "completed";
-		return {
-			runId: this.runId,
-			rootRunId: this.runId,
-			name: this.options.name ?? "batch",
-			type: "batch",
-			status,
-			startedAt: this.startedAt,
-			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			duration: performance.now() - this.startPerf,
-			usage,
-			children,
-			total: this.items.length,
-			succeeded: counts.succeeded,
-			failed: counts.failed,
-			cancelled: counts.cancelled,
-			reportSchemaVersion: 1
-		};
-	}
-};
-
-//#endregion
-export { batch };
-//# sourceMappingURL=batch.mjs.map

package/esm/ai/src/batch/batch.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"batch.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/batch/batch.ts"],"sourcesContent":["import type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { ExecutableContract } from \"../contracts/executable.contract\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { accumulateCost } from \"../utils/compute-cost\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\nimport type {\n  BatchItemResult,\n  BatchOptions,\n  BatchReport,\n  BatchResult,\n} from \"./batch.type\";\nimport { runBatchItem } from \"./run-batch-item\";\nimport { runWithConcurrency } from \"./run-with-concurrency\";\n\n/** Batch size above which an unset (unbounded) concurrency warns once (D5). */\nconst BATCH_UNBOUNDED_WARN_THRESHOLD = 50;\n\n/** Process-lifetime flag so the unbounded-batch warning fires at most once. */\nlet warnedUnboundedBatch = false;\n\n/**\n * Run an executable AI primitive (agent, workflow, supervisor, tool,\n * or anything satisfying {@link ExecutableContract}) over a dataset\n * with bounded concurrency and per-item retry, returning per-item\n * outcomes plus rolled-up usage and a walkable report tree.\n *\n * **Role.** The fan-out primitive of `@warlock.js/ai`. Where an agent\n * runs once, `batch` runs the SAME executable N times — once per item\n * — and aggregates the results into the unified {@link ExecuteResult}\n * envelope, so a batch slots into cost dashboards and trace tooling\n * exactly like a single run does.\n *\n * **Isolation.** Items are independent: one item's failure (after its\n * retries are exhausted) never cancels a sibling, and the batch as a\n * whole never rejects — failures live on each {@link BatchItemResult}.\n * Reach for `result.report.failed` / `item.status` to inspect them.\n *\n * **Usage rollup.** `result.usage` and `result.report.usage` sum every\n * item's usage, satisfying the universal rollup invariant (\"own cost\n * + sum of children\"; a batch has zero own cost). Each item's own\n * report is attached under `report.children[]`, in original item\n * order, so a trace walker sees every run.\n *\n * @example\n * const result = await batch(summarizer, articles, {\n *   concurrency: 4,\n *   retry: { attempts: 3, backoff: \"exponential\" },\n *   onItem: (item) => log.info(\"batch\", \"item\", \"settled\", { index: item.index }),\n * });\n *\n * console.log(`${result.report.succeeded}/${result.report.total} ok`);\n * console.log(`${result.usage.total} tokens total`);\n */\nexport async function batch<TInput, TOptions, TResult extends BaseResult = ExecuteResult>(\n  executable: ExecutableContract<TInput, TOptions, TResult>,\n  items: readonly TInput[],\n  options: BatchOptions<TResult> = {},\n): Promise<BatchResult<TResult>> {\n  return new BatchRun(executable, items, options).run();\n}\n\n/**\n * Per-call orchestration state for one {@link batch} invocation.\n * Instantiated fresh inside the factory so the mutable accumulators\n * (`results`, `usage`) are never shared across batches. Unexported —\n * callers only ever see the plain {@link BatchResult}.\n */\nclass BatchRun<TInput, TOptions, TResult extends BaseResult> {\n  private readonly runId: string;\n  private readonly results: BatchItemResult<TResult>[];\n  private readonly startedAt = new Date().toISOString();\n  private readonly startPerf = performance.now();\n\n  public constructor(\n    private readonly executable: ExecutableContract<TInput, TOptions, TResult>,\n    private readonly items: readonly TInput[],\n    private readonly options: BatchOptions<TResult>,\n  ) {\n    this.runId = generateRunId(\"batch\");\n    this.results = new Array<BatchItemResult<TResult>>(items.length);\n  }\n\n  /**\n   * Dispatch every item through the concurrency pool, then assemble\n   * the rolled-up {@link BatchResult}. Runs once per `batch()` call.\n   */\n  public async run(): Promise<BatchResult<TResult>> {\n    const concurrency = this.resolveConcurrency();\n\n    await runWithConcurrency(this.items.length, concurrency, (index) =>\n      this.processItem(index),\n    );\n\n    return this.buildResult();\n  }\n\n  /**\n   * Resolve the effective concurrency from {@link BatchOptions.concurrency}\n   * (D5). An explicit number or `\"unbounded\"` is honored as-is; an omitted\n   * value runs unbounded for back-compat but warns once (outside tests)\n   * for a large batch so an accidental all-at-once run is visible.\n   */\n  private resolveConcurrency(): number {\n    const configured = this.options.concurrency;\n\n    if (configured === \"unbounded\") {\n      return this.items.length;\n    }\n    if (typeof configured === \"number\") {\n      return configured;\n    }\n\n    if (\n      this.items.length > BATCH_UNBOUNDED_WARN_THRESHOLD &&\n      !warnedUnboundedBatch &&\n      !process.env.VITEST &&\n      process.env.NODE_ENV !== \"test\"\n    ) {\n      warnedUnboundedBatch = true;\n      console.warn(\n        `[warlock-ai] ai.batch() is running ${this.items.length} items with unbounded concurrency (no \\`concurrency\\` set). ` +\n          'Each concurrent item consumes tokens/quota/memory — pass an explicit `concurrency` cap, or `concurrency: \"unbounded\"` to silence this.',\n      );\n    }\n\n    return this.items.length;\n  }\n\n  /**\n   * Run a single item with retry, record it positionally, then fire\n   * the `onItem` hook. A throw from the hook is swallowed — a progress\n   * callback must never break the batch.\n   */\n  private async processItem(index: number): Promise<void> {\n    const item = await runBatchItem({\n      index,\n      input: this.items[index] as TInput,\n      executable: this.executable,\n      retry: this.options.retry,\n      signal: this.options.signal,\n    });\n\n    this.results[index] = item;\n\n    if (this.options.onItem) {\n      try {\n        await this.options.onItem(item);\n      } catch {\n        // A progress hook must never break the batch — swallow its throw.\n      }\n    }\n  }\n\n  /**\n   * Fold the per-item outcomes into rolled-up usage, the child report\n   * list, and the final {@link BatchResult}, then stamp lineage across\n   * the whole subtree so every child shares this batch's root run id.\n   */\n  private buildResult(): BatchResult<TResult> {\n    const usage: Usage = { input: 0, output: 0, total: 0 };\n    const children: BaseReport[] = [];\n    const data: (unknown | undefined)[] = new Array(this.items.length).fill(undefined);\n\n    let succeeded = 0;\n    let failed = 0;\n    let cancelled = 0;\n\n    for (const item of this.results) {\n      if (item.status === \"completed\") {\n        succeeded += 1;\n      } else if (item.status === \"failed\") {\n        failed += 1;\n      } else {\n        cancelled += 1;\n      }\n\n      const itemResult = item.result;\n      if (itemResult) {\n        this.mergeUsage(usage, itemResult.usage);\n\n        if (\"report\" in itemResult && itemResult.report) {\n          children.push(itemResult.report as BaseReport);\n        }\n\n        if (item.status === \"completed\" && \"data\" in itemResult) {\n          data[item.index] = (itemResult as { data?: unknown }).data;\n        }\n      }\n    }\n\n    const report = this.buildReport(usage, children, { succeeded, failed, cancelled });\n\n    stampReportLineage(report, {\n      rootRunId: this.runId,\n      sessionId: this.options.sessionId,\n    });\n\n    return {\n      type: \"batch\",\n      data,\n      usage,\n      report,\n      items: this.results,\n    };\n  }\n\n  /**\n   * Add a child's usage into the running batch total. Scalar token\n   * channels sum directly; the optional cost breakdown merges via\n   * {@link accumulateCost} so a single unpriced child can't erase the\n   * cost of priced siblings. Optional token sub-channels\n   * (`cachedTokens`, etc.) accumulate only when some child reports\n   * them, preserving the \"never reported anywhere\" signal.\n   */\n  private mergeUsage(target: Usage, child: Usage): void {\n    target.input += child.input;\n    target.output += child.output;\n    target.total += child.total;\n\n    if (child.cachedTokens !== undefined) {\n      target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;\n    }\n\n    if (child.reasoningTokens !== undefined) {\n      target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;\n    }\n\n    if (child.cacheWriteTokens !== undefined) {\n      target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;\n    }\n\n    const mergedCost = accumulateCost(target.cost, child.cost);\n    if (mergedCost !== undefined) {\n      target.cost = mergedCost;\n    }\n  }\n\n  /**\n   * Build the batch's own {@link BatchReport} node. `parentRunId` /\n   * `rootRunId` are placeholders here — {@link stampReportLineage}\n   * rewrites them across the whole subtree right after.\n   */\n  private buildReport(\n    usage: Usage,\n    children: BaseReport[],\n    counts: { succeeded: number; failed: number; cancelled: number },\n  ): BatchReport {\n    const status = counts.failed > 0 || counts.cancelled > 0 ? \"failed\" : \"completed\";\n\n    return {\n      runId: this.runId,\n      rootRunId: this.runId,\n      name: this.options.name ?? \"batch\",\n      type: \"batch\",\n      status,\n      startedAt: this.startedAt,\n      endedAt: new Date().toISOString(),\n      duration: performance.now() - this.startPerf,\n      usage,\n      children,\n      total: this.items.length,\n      succeeded: counts.succeeded,\n      failed: counts.failed,\n      cancelled: counts.cancelled,\n      reportSchemaVersion: REPORT_SCHEMA_VERSION,\n    };\n  }\n}\n"],"mappings":"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"}

package/esm/ai/src/batch/index.mjs

@@ -1,3 +0,0 @@
-import { batch } from "./batch.mjs";
-
-export {  };

package/esm/ai/src/batch/run-batch-item.mjs

@@ -1,100 +0,0 @@
-import { isAbortError, resolveBackoff, resolveRetryConfig } from "../workflow/retry.mjs";
-import { toAIError } from "../workflow/step-runner.mjs";
-
-//#region ../@warlock.js/ai/src/batch/run-batch-item.ts
-/**
-* Sleep for `ms`, settling early (without throwing) if `signal`
-* aborts during the wait. The caller re-checks `signal.aborted` after
-* this resolves, so a silent early return is enough — we never want a
-* pending timer to keep the batch alive past cancellation.
-*/
-function sleep(ms, signal) {
-	return new Promise((resolve) => {
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		const onAbort = () => {
-			clearTimeout(timer);
-			resolve();
-		};
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
-}
-/**
-* Execute one item with per-item retry, isolated so a failure can
-* neither throw nor disturb sibling items running in the same pool.
-*
-* Reuses the workflow retry vocabulary verbatim
-* ({@link resolveRetryConfig} / {@link resolveBackoff}) so batch and
-* workflow steps retry identically. An item is `"completed"` when the
-* primitive's own result carries no `error`; a primitive that returns
-* `result.error` (rather than throwing) is treated as a failed attempt
-* and re-run under the same policy.
-*
-* Cancellation short-circuits: if the signal is already aborted on
-* entry the item is reported `"cancelled"` without executing; an abort
-* observed mid-flight surfaces as `"cancelled"` too.
-*/
-async function runBatchItem(params) {
-	const { index, input, executable, signal } = params;
-	if (signal?.aborted) return {
-		index,
-		status: "cancelled",
-		attempts: 0
-	};
-	const retryConfig = resolveRetryConfig({ retry: params.retry }, void 0);
-	const totalAttempts = Math.max(1, retryConfig.attempts ?? 1);
-	let lastResult;
-	let lastError;
-	let attemptsMade = 0;
-	for (let attempt = 1; attempt <= totalAttempts; attempt++) {
-		if (signal?.aborted) return {
-			index,
-			status: "cancelled",
-			result: lastResult,
-			attempts: attemptsMade
-		};
-		attemptsMade = attempt;
-		try {
-			const result = await executable.execute(input, { signal });
-			lastResult = result;
-			if (!result.error) return {
-				index,
-				status: "completed",
-				result,
-				attempts: attempt
-			};
-			lastError = result.error;
-		} catch (error) {
-			if (isAbortError(error)) return {
-				index,
-				status: "cancelled",
-				result: lastResult,
-				attempts: attempt
-			};
-			lastError = error;
-		}
-		if (!(attempt < totalAttempts && (retryConfig.retryOn ? retryConfig.retryOn(lastError, attempt) !== false : true))) break;
-		retryConfig.onRetry?.(attempt + 1, lastError);
-		const delay = resolveBackoff(attempt, retryConfig.backoff);
-		if (delay > 0) await sleep(delay, signal);
-	}
-	if (signal?.aborted) return {
-		index,
-		status: "cancelled",
-		result: lastResult,
-		attempts: attemptsMade
-	};
-	return {
-		index,
-		status: "failed",
-		result: lastResult,
-		error: toAIError(lastError),
-		attempts: attemptsMade
-	};
-}
-
-//#endregion
-export { runBatchItem };
-//# sourceMappingURL=run-batch-item.mjs.map

package/esm/ai/src/batch/run-batch-item.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"run-batch-item.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/batch/run-batch-item.ts"],"sourcesContent":["import type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { ExecutableContract } from \"../contracts/executable.contract\";\nimport type { RetryConfig } from \"../contracts/workflow/retry-config.type\";\nimport { isAbortError, resolveBackoff, resolveRetryConfig } from \"../workflow/retry\";\nimport { toAIError } from \"../workflow/step-runner\";\nimport type { BatchItemResult } from \"./batch.type\";\n\n/**\n * Parameters for {@link runBatchItem}. Kept as a plain bag so the\n * concurrency pool can build it once per index without a long\n * positional argument list.\n */\nexport type RunBatchItemParams<TInput, TOptions, TResult extends BaseResult> = {\n  index: number;\n  input: TInput;\n  executable: ExecutableContract<TInput, TOptions, TResult>;\n  retry: RetryConfig | undefined;\n  signal: AbortSignal | undefined;\n};\n\n/**\n * Sleep for `ms`, settling early (without throwing) if `signal`\n * aborts during the wait. The caller re-checks `signal.aborted` after\n * this resolves, so a silent early return is enough — we never want a\n * pending timer to keep the batch alive past cancellation.\n */\nfunction sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {\n  return new Promise((resolve) => {\n    const timer = setTimeout(() => {\n      signal?.removeEventListener(\"abort\", onAbort);\n      resolve();\n    }, ms);\n\n    const onAbort = (): void => {\n      clearTimeout(timer);\n      resolve();\n    };\n\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n  });\n}\n\n/**\n * Execute one item with per-item retry, isolated so a failure can\n * neither throw nor disturb sibling items running in the same pool.\n *\n * Reuses the workflow retry vocabulary verbatim\n * ({@link resolveRetryConfig} / {@link resolveBackoff}) so batch and\n * workflow steps retry identically. An item is `\"completed\"` when the\n * primitive's own result carries no `error`; a primitive that returns\n * `result.error` (rather than throwing) is treated as a failed attempt\n * and re-run under the same policy.\n *\n * Cancellation short-circuits: if the signal is already aborted on\n * entry the item is reported `\"cancelled\"` without executing; an abort\n * observed mid-flight surfaces as `\"cancelled\"` too.\n */\nexport async function runBatchItem<TInput, TOptions, TResult extends BaseResult>(\n  params: RunBatchItemParams<TInput, TOptions, TResult>,\n): Promise<BatchItemResult<TResult>> {\n  const { index, input, executable, signal } = params;\n\n  if (signal?.aborted) {\n    return { index, status: \"cancelled\", attempts: 0 };\n  }\n\n  const retryConfig = resolveRetryConfig({ retry: params.retry }, undefined);\n  const totalAttempts = Math.max(1, retryConfig.attempts ?? 1);\n\n  let lastResult: TResult | undefined;\n  let lastError: unknown;\n  let attemptsMade = 0;\n\n  for (let attempt = 1; attempt <= totalAttempts; attempt++) {\n    if (signal?.aborted) {\n      return { index, status: \"cancelled\", result: lastResult, attempts: attemptsMade };\n    }\n\n    attemptsMade = attempt;\n\n    try {\n      const result = await executable.execute(input, { signal } as TOptions);\n      lastResult = result;\n\n      if (!result.error) {\n        return { index, status: \"completed\", result, attempts: attempt };\n      }\n\n      lastError = result.error;\n    } catch (error) {\n      if (isAbortError(error)) {\n        return { index, status: \"cancelled\", result: lastResult, attempts: attempt };\n      }\n\n      lastError = error;\n    }\n\n    const canRetry =\n      attempt < totalAttempts &&\n      (retryConfig.retryOn ? retryConfig.retryOn(lastError, attempt) !== false : true);\n\n    if (!canRetry) {\n      break;\n    }\n\n    retryConfig.onRetry?.(attempt + 1, lastError);\n\n    const delay = resolveBackoff(attempt, retryConfig.backoff);\n    if (delay > 0) {\n      await sleep(delay, signal);\n    }\n  }\n\n  if (signal?.aborted) {\n    return { index, status: \"cancelled\", result: lastResult, attempts: attemptsMade };\n  }\n\n  return {\n    index,\n    status: \"failed\",\n    result: lastResult,\n    error: toAIError(lastError),\n    attempts: attemptsMade,\n  };\n}\n"],"mappings":";;;;;;;;;;AA0BA,SAAS,MAAM,IAAY,QAAgD;CACzE,OAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,QAAQ,iBAAiB;GAC7B,QAAQ,oBAAoB,SAAS,OAAO;GAC5C,QAAQ;EACV,GAAG,EAAE;EAEL,MAAM,gBAAsB;GAC1B,aAAa,KAAK;GAClB,QAAQ;EACV;EAEA,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAC3D,CAAC;AACH;;;;;;;;;;;;;;;;AAiBA,eAAsB,aACpB,QACmC;CACnC,MAAM,EAAE,OAAO,OAAO,YAAY,WAAW;CAE7C,IAAI,QAAQ,SACV,OAAO;EAAE;EAAO,QAAQ;EAAa,UAAU;CAAE;CAGnD,MAAM,cAAc,mBAAmB,EAAE,OAAO,OAAO,MAAM,GAAG,MAAS;CACzE,MAAM,gBAAgB,KAAK,IAAI,GAAG,YAAY,YAAY,CAAC;CAE3D,IAAI;CACJ,IAAI;CACJ,IAAI,eAAe;CAEnB,KAAK,IAAI,UAAU,GAAG,WAAW,eAAe,WAAW;EACzD,IAAI,QAAQ,SACV,OAAO;GAAE;GAAO,QAAQ;GAAa,QAAQ;GAAY,UAAU;EAAa;EAGlF,eAAe;EAEf,IAAI;GACF,MAAM,SAAS,MAAM,WAAW,QAAQ,OAAO,EAAE,OAAO,CAAa;GACrE,aAAa;GAEb,IAAI,CAAC,OAAO,OACV,OAAO;IAAE;IAAO,QAAQ;IAAa;IAAQ,UAAU;GAAQ;GAGjE,YAAY,OAAO;EACrB,SAAS,OAAO;GACd,IAAI,aAAa,KAAK,GACpB,OAAO;IAAE;IAAO,QAAQ;IAAa,QAAQ;IAAY,UAAU;GAAQ;GAG7E,YAAY;EACd;EAMA,IAAI,EAHF,UAAU,kBACT,YAAY,UAAU,YAAY,QAAQ,WAAW,OAAO,MAAM,QAAQ,QAG3E;EAGF,YAAY,UAAU,UAAU,GAAG,SAAS;EAE5C,MAAM,QAAQ,eAAe,SAAS,YAAY,OAAO;EACzD,IAAI,QAAQ,GACV,MAAM,MAAM,OAAO,MAAM;CAE7B;CAEA,IAAI,QAAQ,SACV,OAAO;EAAE;EAAO,QAAQ;EAAa,QAAQ;EAAY,UAAU;CAAa;CAGlF,OAAO;EACL;EACA,QAAQ;EACR,QAAQ;EACR,OAAO,UAAU,SAAS;EAC1B,UAAU;CACZ;AACF"}

package/esm/ai/src/batch/run-with-concurrency.mjs

@@ -1,39 +0,0 @@
-//#region ../@warlock.js/ai/src/batch/run-with-concurrency.ts
-/**
-* Run an async `worker` over every index `0..total-1` with at most
-* `limit` workers in flight at any moment, preserving nothing about
-* completion order (the worker is responsible for recording results
-* positionally). Resolves once every index has settled.
-*
-* A fixed pool of `limit` runners each pull the next unclaimed index
-* from a shared cursor — this keeps exactly `limit` items in flight
-* even when item durations vary wildly, unlike fixed-size chunking
-* which stalls a chunk on its slowest member.
-*
-* `limit` is clamped to `[1, total]`: a non-positive limit runs fully
-* serially, a limit larger than `total` simply starts every item.
-* `total === 0` resolves immediately.
-*
-* The worker must never reject — it owns its own try/catch and records
-* outcomes. A rejection here would abort sibling runners, which is not
-* the batch contract (one item's failure never cancels another's).
-*/
-async function runWithConcurrency(total, limit, worker) {
-	if (total <= 0) return;
-	const poolSize = Math.max(1, Math.min(limit, total));
-	let cursor = 0;
-	const runner = async () => {
-		while (cursor < total) {
-			const index = cursor;
-			cursor += 1;
-			await worker(index);
-		}
-	};
-	const pool = [];
-	for (let slot = 0; slot < poolSize; slot++) pool.push(runner());
-	await Promise.all(pool);
-}
-
-//#endregion
-export { runWithConcurrency };
-//# sourceMappingURL=run-with-concurrency.mjs.map

package/esm/ai/src/batch/run-with-concurrency.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"run-with-concurrency.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/batch/run-with-concurrency.ts"],"sourcesContent":["/**\n * Run an async `worker` over every index `0..total-1` with at most\n * `limit` workers in flight at any moment, preserving nothing about\n * completion order (the worker is responsible for recording results\n * positionally). Resolves once every index has settled.\n *\n * A fixed pool of `limit` runners each pull the next unclaimed index\n * from a shared cursor — this keeps exactly `limit` items in flight\n * even when item durations vary wildly, unlike fixed-size chunking\n * which stalls a chunk on its slowest member.\n *\n * `limit` is clamped to `[1, total]`: a non-positive limit runs fully\n * serially, a limit larger than `total` simply starts every item.\n * `total === 0` resolves immediately.\n *\n * The worker must never reject — it owns its own try/catch and records\n * outcomes. A rejection here would abort sibling runners, which is not\n * the batch contract (one item's failure never cancels another's).\n */\nexport async function runWithConcurrency(\n  total: number,\n  limit: number,\n  worker: (index: number) => Promise<void>,\n): Promise<void> {\n  if (total <= 0) {\n    return;\n  }\n\n  const poolSize = Math.max(1, Math.min(limit, total));\n  let cursor = 0;\n\n  const runner = async (): Promise<void> => {\n    while (cursor < total) {\n      const index = cursor;\n      cursor += 1;\n      await worker(index);\n    }\n  };\n\n  const pool: Promise<void>[] = [];\n  for (let slot = 0; slot < poolSize; slot++) {\n    pool.push(runner());\n  }\n\n  await Promise.all(pool);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAmBA,eAAsB,mBACpB,OACA,OACA,QACe;CACf,IAAI,SAAS,GACX;CAGF,MAAM,WAAW,KAAK,IAAI,GAAG,KAAK,IAAI,OAAO,KAAK,CAAC;CACnD,IAAI,SAAS;CAEb,MAAM,SAAS,YAA2B;EACxC,OAAO,SAAS,OAAO;GACrB,MAAM,QAAQ;GACd,UAAU;GACV,MAAM,OAAO,KAAK;EACpB;CACF;CAEA,MAAM,OAAwB,CAAC;CAC/B,KAAK,IAAI,OAAO,GAAG,OAAO,UAAU,QAClC,KAAK,KAAK,OAAO,CAAC;CAGpB,MAAM,QAAQ,IAAI,IAAI;AACxB"}

package/esm/ai/src/checkpoint/memory.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/checkpoint/memory.ts"],"sourcesContent":["import type {\n  CheckpointRecord,\n  CheckpointStore,\n} from \"../contracts/orchestrator/checkpoint-store.contract\";\n\n/**\n * Composite key for the in-memory session index — one bucket per\n * `(orchestratorName, sessionId)` pair. The separator can't appear in\n * the segments in practice (names are identifiers, sessionIds are\n * dev-owned opaque strings), so a simple join is collision-safe enough\n * for an in-process store.\n */\nfunction bucketKey(orchestratorName: string, sessionId: string): string {\n  return `${orchestratorName}\u0000${sessionId}`;\n}\n\n/**\n * In-memory {@link CheckpointStore} — append-only session checkpoints\n * held in a process-local `Map`, never persisted to disk.\n *\n * Owns: the per-session bucket of {@link CheckpointRecord} rows and the\n * \"latest turn wins\" load semantics. Does NOT own: durability,\n * cross-process sharing, or TTL eviction — it is the zero-config\n * default for dev, tests, and single-process apps that don't need\n * resume across restarts. Reach for `ai.checkpoint.pg()` /\n * `ai.checkpoint.redis()` (Phase 2) when durability matters.\n *\n * Front it with the {@link memory} factory — callers never `new` it.\n */\nclass MemoryCheckpointStore implements CheckpointStore {\n  /** Per-session append-only row buckets, keyed by `(orchestratorName, sessionId)`. */\n  private readonly sessions = new Map<string, CheckpointRecord[]>();\n\n  /**\n   * Return the latest checkpoint (highest `turn_index`) for a session,\n   * or `undefined` when the session has no rows. Rows are appended in\n   * turn order, so the last element is the latest — no scan needed.\n   */\n  public async load(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<CheckpointRecord | undefined> {\n    const rows = this.sessions.get(bucketKey(orchestratorName, sessionId));\n\n    if (!rows || rows.length === 0) {\n      return undefined;\n    }\n\n    return rows[rows.length - 1];\n  }\n\n  /**\n   * Append a checkpoint row to its session bucket. Append-only — an\n   * existing `turn_index` is never overwritten; a fresh row is pushed.\n   */\n  public async save(record: CheckpointRecord): Promise<void> {\n    const key = bucketKey(record.orchestrator_name, record.session_id);\n    const rows = this.sessions.get(key);\n\n    if (rows) {\n      rows.push(record);\n\n      return;\n    }\n\n    this.sessions.set(key, [record]);\n  }\n\n  /**\n   * Drop every row for a session, ending it.\n   */\n  public async delete(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    this.sessions.delete(bucketKey(orchestratorName, sessionId));\n  }\n\n  /**\n   * List the session ids known for an orchestrator, optionally filtered\n   * by a session-id prefix. Reads the latest row of each bucket so the\n   * authoritative `session_id` is returned even if the key encoding\n   * ever changes.\n   */\n  public async list(\n    orchestratorName: string,\n    prefix?: string,\n  ): Promise<string[]> {\n    const sessionIds: string[] = [];\n\n    for (const rows of this.sessions.values()) {\n      const latest = rows[rows.length - 1];\n\n      if (!latest || latest.orchestrator_name !== orchestratorName) {\n        continue;\n      }\n\n      if (prefix !== undefined && !latest.session_id.startsWith(prefix)) {\n        continue;\n      }\n\n      sessionIds.push(latest.session_id);\n    }\n\n    return sessionIds;\n  }\n\n  /**\n   * Drop every row for a session whose `turn_index` is strictly below\n   * `keepBeforeTurnIndex`, enforcing the `keepSnapshots` retention bound\n   * (§4 Phase 6, Q20). Rebuilds the bucket in place with the surviving\n   * tail; an emptied bucket is removed so `list()` no longer reports the\n   * session.\n   */\n  public async prune(\n    orchestratorName: string,\n    sessionId: string,\n    keepBeforeTurnIndex: number,\n  ): Promise<void> {\n    const key = bucketKey(orchestratorName, sessionId);\n    const rows = this.sessions.get(key);\n\n    if (!rows) {\n      return;\n    }\n\n    const kept = rows.filter((row) => row.turn_index >= keepBeforeTurnIndex);\n\n    if (kept.length === 0) {\n      this.sessions.delete(key);\n\n      return;\n    }\n\n    if (kept.length !== rows.length) {\n      this.sessions.set(key, kept);\n    }\n  }\n\n  /**\n   * The memory store has no backing table — there is nothing to\n   * migrate. Returns an empty string so callers can treat `schema()`\n   * uniformly across drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n}\n\n/**\n * Create an in-memory {@link CheckpointStore}. Zero-config — no client,\n * no connection. Suitable for dev, tests, and single-process apps that\n * don't need resume across restarts.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n *\n * const orchestrator = ai.orchestrator({\n *   name: \"support\",\n *   intents: { ... },\n *   checkpointStore: ai.checkpoint.memory(),\n * });\n */\nexport function memory(): CheckpointStore {\n  return new MemoryCheckpointStore();\n}\n"],"mappings":";;;;;;;;AAYA,SAAS,UAAU,kBAA0B,WAA2B;CACtE,OAAO,GAAG,iBAAiB,GAAG;AAChC;;;;;;;;;;;;;;AAeA,IAAM,wBAAN,MAAuD;;kCAEzB,IAAI,IAAgC;;;;;;;CAOhE,MAAa,KACX,kBACA,WACuC;EACvC,MAAM,OAAO,KAAK,SAAS,IAAI,UAAU,kBAAkB,SAAS,CAAC;EAErE,IAAI,CAAC,QAAQ,KAAK,WAAW,GAC3B;EAGF,OAAO,KAAK,KAAK,SAAS;CAC5B;;;;;CAMA,MAAa,KAAK,QAAyC;EACzD,MAAM,MAAM,UAAU,OAAO,mBAAmB,OAAO,UAAU;EACjE,MAAM,OAAO,KAAK,SAAS,IAAI,GAAG;EAElC,IAAI,MAAM;GACR,KAAK,KAAK,MAAM;GAEhB;EACF;EAEA,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC;CACjC;;;;CAKA,MAAa,OACX,kBACA,WACe;EACf,KAAK,SAAS,OAAO,UAAU,kBAAkB,SAAS,CAAC;CAC7D;;;;;;;CAQA,MAAa,KACX,kBACA,QACmB;EACnB,MAAM,aAAuB,CAAC;EAE9B,KAAK,MAAM,QAAQ,KAAK,SAAS,OAAO,GAAG;GACzC,MAAM,SAAS,KAAK,KAAK,SAAS;GAElC,IAAI,CAAC,UAAU,OAAO,sBAAsB,kBAC1C;GAGF,IAAI,WAAW,UAAa,CAAC,OAAO,WAAW,WAAW,MAAM,GAC9D;GAGF,WAAW,KAAK,OAAO,UAAU;EACnC;EAEA,OAAO;CACT;;;;;;;;CASA,MAAa,MACX,kBACA,WACA,qBACe;EACf,MAAM,MAAM,UAAU,kBAAkB,SAAS;EACjD,MAAM,OAAO,KAAK,SAAS,IAAI,GAAG;EAElC,IAAI,CAAC,MACH;EAGF,MAAM,OAAO,KAAK,QAAQ,QAAQ,IAAI,cAAc,mBAAmB;EAEvE,IAAI,KAAK,WAAW,GAAG;GACrB,KAAK,SAAS,OAAO,GAAG;GAExB;EACF;EAEA,IAAI,KAAK,WAAW,KAAK,QACvB,KAAK,SAAS,IAAI,KAAK,IAAI;CAE/B;;;;;;CAOA,AAAO,SAAiB;EACtB,OAAO;CACT;AACF;;;;;;;;;;;;;;;AAgBA,SAAgB,SAA0B;CACxC,OAAO,IAAI,sBAAsB;AACnC"}