@vercel/factory 0.0.13 → 0.0.15

package/dist/delivery-metrics/metrics.mjs

@@ -0,0 +1,200 @@
+//#region src/delivery-metrics/metrics.ts
+const bucketTable = {
+	low: {
+		low: "review",
+		medium: "stamp",
+		high: "stamp"
+	},
+	medium: {
+		low: "review",
+		medium: "review",
+		high: "stamp"
+	},
+	high: {
+		low: "blocked",
+		medium: "review",
+		high: "review"
+	}
+};
+/** Derives the default human-review bucket from a change's risk and confidence. */
+function changeReviewBucket(input) {
+	return bucketTable[input.risk][input.confidence];
+}
+function collectFacts(rows) {
+	const byChange = /* @__PURE__ */ new Map();
+	for (const receipt of rows.receipts) {
+		if (receipt.kind !== "change" || receipt.changeId === void 0) continue;
+		const list = byChange.get(receipt.changeId) ?? [];
+		list.push(receipt);
+		byChange.set(receipt.changeId, list);
+	}
+	const at = (receipts, state) => {
+		const found = receipts?.find((receipt) => receipt.state === state);
+		return found === void 0 ? null : Date.parse(found.recordedAt);
+	};
+	return rows.changes.map((change) => {
+		const receipts = byChange.get(change.id);
+		const requiredState = change.risk === "high" ? "rolled_out" : "deployed";
+		return {
+			change,
+			readyAt: at(receipts, "ready"),
+			mergedAt: at(receipts, "merged"),
+			reachedAt: at(receipts, requiredState),
+			rolledBackAt: at(receipts, "rolled_back")
+		};
+	});
+}
+/** True for a change a human saw as ready and then closed unmerged. */
+function closedAfterReady(facts) {
+	return facts.change.state === "closed" && (facts.readyAt !== null || facts.change.decidedBy !== void 0);
+}
+function median(values) {
+	if (values.length === 0) return null;
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+/**
+* The six product metrics from ledger rows alone. One rule governs them: a
+* change counts only after a human merged it and it stayed. Activity that
+* never landed is not a result. Compute over rows already filtered to the
+* period and repositories you are reporting on.
+*/
+function computeLedgerMetrics(rows, options = {}) {
+	const now = (options.now ?? /* @__PURE__ */ new Date()).getTime();
+	const holdMs = (options.holdDays ?? 7) * 24 * 60 * 60 * 1e3;
+	const facts = collectFacts(rows);
+	let landed = 0;
+	let provisional = 0;
+	let rolledBack = 0;
+	let closedAfterReadyCount = 0;
+	let closedInVerification = 0;
+	const landedChangeIds = /* @__PURE__ */ new Set();
+	for (const fact of facts) {
+		const { change } = fact;
+		if (fact.rolledBackAt !== null) {
+			rolledBack += 1;
+			continue;
+		}
+		if (change.state === "closed") {
+			if (closedAfterReady(fact)) closedAfterReadyCount += 1;
+			else closedInVerification += 1;
+			continue;
+		}
+		if (change.decidedBy !== void 0 && fact.reachedAt !== null) {
+			landed += 1;
+			landedChangeIds.add(change.id);
+			if (now - fact.reachedAt < holdMs) provisional += 1;
+		}
+	}
+	const stickDenominator = landed + rolledBack + closedAfterReadyCount;
+	const humanTimes = {
+		stamp: [],
+		review: []
+	};
+	for (const fact of facts) {
+		if (fact.readyAt === null || fact.mergedAt === null) continue;
+		const bucket = changeReviewBucket({
+			risk: fact.change.risk,
+			confidence: fact.change.confidence
+		});
+		if (bucket === "blocked") continue;
+		humanTimes[bucket].push(fact.mergedAt - fact.readyAt);
+	}
+	let settledOverLanded = 0;
+	let sawSettledCost = false;
+	for (const task of rows.tasks) {
+		if (task.settledUsd === void 0) continue;
+		if (task.kind === "code_change" && task.changeId !== void 0 && landedChangeIds.has(task.changeId)) {
+			settledOverLanded += task.settledUsd;
+			sawSettledCost = true;
+		}
+	}
+	const rejectedSignals = rows.signals.filter((signal) => signal.outcome !== "pending" && signal.outcome !== "accepted").length;
+	return {
+		landed,
+		provisional,
+		stickRate: stickDenominator === 0 ? null : landed / stickDenominator,
+		stampedClean: null,
+		humanTimeMs: {
+			stamp: median(humanTimes.stamp),
+			review: median(humanTimes.review)
+		},
+		costPerLandedUsd: sawSettledCost && landed > 0 ? settledOverLanded / landed : null,
+		filtered: rejectedSignals + closedInVerification
+	};
+}
+const openChangeStates = /* @__PURE__ */ new Set(["verifying", "ready"]);
+function matchesGraphNode(task, node) {
+	return task.id === node.taskId && task.rootTaskId === node.admission.rootTaskId && task.parentTaskId === node.parentTaskId && task.repositoryIds.length === node.admission.repositoryIds.length && task.repositoryIds.every((id, index) => id === node.admission.repositoryIds[index]);
+}
+function dependencyStatus(task, tasks, graphs) {
+	const graph = graphs?.get(task.rootTaskId);
+	const node = graph?.nodes.find((entry) => entry.taskId === task.id);
+	if (!graph || graph.rootTaskId !== task.rootTaskId || !node || !matchesGraphNode(task, node)) return "unknown";
+	let ready = true;
+	for (const id of node.dependencies) {
+		const dependency = tasks.get(id);
+		const dependencyNode = graph.nodes.find((entry) => entry.taskId === id);
+		if (!dependency || !dependencyNode || !matchesGraphNode(dependency, dependencyNode)) return "unknown";
+		if (dependency.state !== "succeeded") ready = false;
+	}
+	return ready ? "ready" : "waiting";
+}
+/**
+* Green, yellow, or red from rows, never from a model. Budget threshold and
+* onboarding rules are not evaluated here yet: budget notices live on the
+* budgets collection (not in these rows), and onboarding investigations are
+* not recorded.
+*/
+function computeRepositoryHealth(rows, options = {}) {
+	const now = (options.now ?? /* @__PURE__ */ new Date()).getTime();
+	const dayMs = 864e5;
+	const red = [];
+	const yellow = [];
+	const tasksById = new Map(rows.tasks.map((task) => [task.id, task]));
+	for (const receipt of rows.receipts) {
+		if (now - Date.parse(receipt.recordedAt) >= dayMs) continue;
+		if (receipt.state === "rolled_back") red.push(`rollback in the last 24h (${receipt.receiptId})`);
+		if (receipt.state === "cancelled" && receipt.reason?.toLowerCase().includes("kill")) red.push(`kill in the last 24h (${receipt.receiptId})`);
+	}
+	const openQuestions = rows.tasks.filter((task) => task.kind === "question" && task.state === "needs_human").length;
+	if (openQuestions > 0) yellow.push(`${openQuestions} open question(s)`);
+	const needsHuman = rows.tasks.filter((task) => task.kind !== "question" && task.state === "needs_human").length;
+	if (needsHuman > 0) yellow.push(`${needsHuman} task(s) waiting on a human`);
+	const maxQueuedMinutes = options.maxQueuedMinutes ?? 5;
+	let staleQueued = 0;
+	let unknownDependencies = 0;
+	for (const task of rows.tasks) {
+		const status = dependencyStatus(task, tasksById, rows.graphs);
+		if (status === "unknown") unknownDependencies += 1;
+		if (status === "ready" && task.state === "queued" && task.approval !== "required" && task.approval !== "denied" && now - Date.parse(task.updatedAt) >= maxQueuedMinutes * 60 * 1e3) staleQueued += 1;
+	}
+	if (unknownDependencies > 0) yellow.push(`${unknownDependencies} task(s) with missing or inconsistent graph/dependency snapshots`);
+	if (staleQueued > 0) yellow.push(`${staleQueued} eligible task(s) queued for at least ${maxQueuedMinutes} minutes`);
+	const blocked = rows.changes.filter((change) => openChangeStates.has(change.state) && changeReviewBucket({
+		risk: change.risk,
+		confidence: change.confidence
+	}) === "blocked").length;
+	if (blocked > 0) yellow.push(`${blocked} change(s) in the blocked bucket`);
+	if (options.maxOpenChanges !== void 0) {
+		const open = rows.changes.filter((change) => openChangeStates.has(change.state)).length;
+		if (open >= options.maxOpenChanges) yellow.push(`open changes at the cap (${open}/${options.maxOpenChanges})`);
+	}
+	if (red.length > 0) return {
+		color: "red",
+		reasons: red
+	};
+	if (yellow.length > 0) return {
+		color: "yellow",
+		reasons: yellow
+	};
+	return {
+		color: "green",
+		reasons: []
+	};
+}
+//#endregion
+export { changeReviewBucket, computeLedgerMetrics, computeRepositoryHealth };
+
+//# sourceMappingURL=metrics.mjs.map

package/dist/delivery-metrics/metrics.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.mjs","names":[],"sources":["../../src/delivery-metrics/metrics.ts"],"sourcesContent":["import type { Change, ChangeLevel } from \"../schema/change\";\nimport type { Receipt } from \"../schema/receipt\";\nimport type { Signal } from \"../schema/signal\";\nimport type { Task } from \"../schema/task\";\nimport type { TaskGraph, TaskGraphNode } from \"../schema/task-graph\";\n\n/**\n * The derived review bucket from the default risk x confidence table. Derived\n * at read time, never stored; \"blocked\" is a bucket, not a change state.\n */\nexport type ChangeReviewBucket = \"stamp\" | \"review\" | \"blocked\";\n\nconst bucketTable: Record<ChangeLevel, Record<ChangeLevel, ChangeReviewBucket>> = {\n  low: { low: \"review\", medium: \"stamp\", high: \"stamp\" },\n  medium: { low: \"review\", medium: \"review\", high: \"stamp\" },\n  high: { low: \"blocked\", medium: \"review\", high: \"review\" },\n};\n\n/** Risk and confidence inputs used to derive a human-review bucket. */\nexport interface ChangeReviewFactors {\n  risk: ChangeLevel;\n  confidence: ChangeLevel;\n}\n\n/** Derives the default human-review bucket from a change's risk and confidence. */\nexport function changeReviewBucket(input: ChangeReviewFactors): ChangeReviewBucket {\n  return bucketTable[input.risk][input.confidence];\n}\n\n/** Validated ledger rows used to derive Factory metrics and health. */\nexport interface DeliveryLedgerRows {\n  changes: readonly Change[];\n  signals: readonly Signal[];\n  receipts: readonly Receipt[];\n  tasks: readonly Task[];\n  /** Validated graph snapshots keyed by rootTaskId. Missing snapshots make health yellow, never runnable. */\n  graphs?: ReadonlyMap<string, TaskGraph>;\n}\n\n/** Options controlling ledger metric evaluation. */\nexport interface ComputeLedgerMetricsOptions {\n  /** Evaluation time; defaults to the current time. */\n  now?: Date;\n  /** Days a landed change must hold without a rollback. Default 7. */\n  holdDays?: number;\n}\n\n/** Product metrics derived deterministically from ledger rows. */\nexport interface DeliveryMetrics {\n  /**\n   * Changes a human merged that reached deployed (rolled_out for high risk)\n   * and did not roll back within the hold window. Includes provisional ones.\n   */\n  landed: number;\n  /** Landed changes still inside the hold window; the number may drop. */\n  provisional: number;\n  /** landed / (landed + rolled back + closed after ready). Null when nothing decided. */\n  stickRate: number | null;\n  /**\n   * Not computable from ledger rows: needs a record of human commits pushed\n   * to the pull request after ready, which nothing writes today.\n   */\n  stampedClean: null;\n  /** Median ms from the ready receipt to the merged receipt, per review bucket. */\n  humanTimeMs: { stamp: number | null; review: number | null };\n  /** Sum of settled task cost over landed changes / landed. Null until budgets settle. */\n  costPerLandedUsd: number | null;\n  /** Signals triage turned away plus changes closed in verification. */\n  filtered: number;\n}\n\ninterface ChangeFacts {\n  change: Change;\n  readyAt: number | null;\n  mergedAt: number | null;\n  reachedAt: number | null;\n  rolledBackAt: number | null;\n}\n\nfunction collectFacts(rows: DeliveryLedgerRows): ChangeFacts[] {\n  const byChange = new Map<string, Receipt[]>();\n  for (const receipt of rows.receipts) {\n    if (receipt.kind !== \"change\" || receipt.changeId === undefined) continue;\n    const list = byChange.get(receipt.changeId) ?? [];\n    list.push(receipt);\n    byChange.set(receipt.changeId, list);\n  }\n  const at = (receipts: Receipt[] | undefined, state: string): number | null => {\n    const found = receipts?.find((receipt) => receipt.state === state);\n    return found === undefined ? null : Date.parse(found.recordedAt);\n  };\n  return rows.changes.map((change) => {\n    const receipts = byChange.get(change.id);\n    const requiredState = change.risk === \"high\" ? \"rolled_out\" : \"deployed\";\n    return {\n      change,\n      readyAt: at(receipts, \"ready\"),\n      mergedAt: at(receipts, \"merged\"),\n      reachedAt: at(receipts, requiredState),\n      rolledBackAt: at(receipts, \"rolled_back\"),\n    };\n  });\n}\n\n/** True for a change a human saw as ready and then closed unmerged. */\nfunction closedAfterReady(facts: ChangeFacts): boolean {\n  return (\n    facts.change.state === \"closed\" &&\n    (facts.readyAt !== null || facts.change.decidedBy !== undefined)\n  );\n}\n\nfunction median(values: number[]): number | null {\n  if (values.length === 0) return null;\n  const sorted = [...values].sort((a, b) => a - b);\n  const mid = Math.floor(sorted.length / 2);\n  return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;\n}\n\n/**\n * The six product metrics from ledger rows alone. One rule governs them: a\n * change counts only after a human merged it and it stayed. Activity that\n * never landed is not a result. Compute over rows already filtered to the\n * period and repositories you are reporting on.\n */\nexport function computeLedgerMetrics(\n  rows: DeliveryLedgerRows,\n  options: ComputeLedgerMetricsOptions = {},\n): DeliveryMetrics {\n  const now = (options.now ?? new Date()).getTime();\n  const holdMs = (options.holdDays ?? 7) * 24 * 60 * 60 * 1000;\n  const facts = collectFacts(rows);\n\n  let landed = 0;\n  let provisional = 0;\n  let rolledBack = 0;\n  let closedAfterReadyCount = 0;\n  let closedInVerification = 0;\n  const landedChangeIds = new Set<string>();\n\n  for (const fact of facts) {\n    const { change } = fact;\n    if (fact.rolledBackAt !== null) {\n      rolledBack += 1;\n      continue;\n    }\n    if (change.state === \"closed\") {\n      if (closedAfterReady(fact)) closedAfterReadyCount += 1;\n      else closedInVerification += 1;\n      continue;\n    }\n    if (change.decidedBy !== undefined && fact.reachedAt !== null) {\n      landed += 1;\n      landedChangeIds.add(change.id);\n      if (now - fact.reachedAt < holdMs) provisional += 1;\n    }\n  }\n\n  const stickDenominator = landed + rolledBack + closedAfterReadyCount;\n  const humanTimes: Record<\"stamp\" | \"review\", number[]> = { stamp: [], review: [] };\n  for (const fact of facts) {\n    if (fact.readyAt === null || fact.mergedAt === null) continue;\n    const bucket = changeReviewBucket({\n      risk: fact.change.risk,\n      confidence: fact.change.confidence,\n    });\n    if (bucket === \"blocked\") continue;\n    humanTimes[bucket].push(fact.mergedAt - fact.readyAt);\n  }\n\n  let settledOverLanded = 0;\n  let sawSettledCost = false;\n  for (const task of rows.tasks) {\n    if (task.settledUsd === undefined) continue;\n    if (\n      task.kind === \"code_change\" &&\n      task.changeId !== undefined &&\n      landedChangeIds.has(task.changeId)\n    ) {\n      settledOverLanded += task.settledUsd;\n      sawSettledCost = true;\n    }\n  }\n\n  const rejectedSignals = rows.signals.filter(\n    (signal) => signal.outcome !== \"pending\" && signal.outcome !== \"accepted\",\n  ).length;\n\n  return {\n    landed,\n    provisional,\n    stickRate: stickDenominator === 0 ? null : landed / stickDenominator,\n    stampedClean: null,\n    humanTimeMs: { stamp: median(humanTimes.stamp), review: median(humanTimes.review) },\n    costPerLandedUsd: sawSettledCost && landed > 0 ? settledOverLanded / landed : null,\n    filtered: rejectedSignals + closedInVerification,\n  };\n}\n\n/** Overall repository health severity derived from operational evidence. */\nexport type RepositoryHealthColor = \"green\" | \"yellow\" | \"red\";\n\n/** Options controlling repository health evaluation. */\nexport interface ComputeRepositoryHealthOptions {\n  now?: Date;\n  /** Open-change cap from factory configuration; omitted disables that check. */\n  maxOpenChanges?: number;\n  /** Minutes an eligible executable task may remain queued before health turns yellow. Default 5. */\n  maxQueuedMinutes?: number;\n}\n\n/** Explainable repository health derived from ledger and graph state. */\nexport interface RepositoryHealth {\n  readonly color: RepositoryHealthColor;\n  /** Every rule that fired, so the color is explainable from rows. */\n  readonly reasons: readonly string[];\n}\n\nconst openChangeStates = new Set([\"verifying\", \"ready\"]);\n\nfunction matchesGraphNode(task: Task, node: TaskGraphNode): boolean {\n  return (\n    task.id === node.taskId &&\n    task.rootTaskId === node.admission.rootTaskId &&\n    task.parentTaskId === node.parentTaskId &&\n    task.repositoryIds.length === node.admission.repositoryIds.length &&\n    task.repositoryIds.every((id, index) => id === node.admission.repositoryIds[index])\n  );\n}\n\nfunction dependencyStatus(\n  task: Task,\n  tasks: ReadonlyMap<string, Task>,\n  graphs: DeliveryLedgerRows[\"graphs\"],\n): \"ready\" | \"waiting\" | \"unknown\" {\n  const graph = graphs?.get(task.rootTaskId);\n  const node = graph?.nodes.find((entry) => entry.taskId === task.id);\n  if (!graph || graph.rootTaskId !== task.rootTaskId || !node || !matchesGraphNode(task, node)) {\n    return \"unknown\";\n  }\n  let ready = true;\n  for (const id of node.dependencies) {\n    const dependency = tasks.get(id);\n    const dependencyNode = graph.nodes.find((entry) => entry.taskId === id);\n    if (!dependency || !dependencyNode || !matchesGraphNode(dependency, dependencyNode))\n      return \"unknown\";\n    if (dependency.state !== \"succeeded\") ready = false;\n  }\n  return ready ? \"ready\" : \"waiting\";\n}\n\n/**\n * Green, yellow, or red from rows, never from a model. Budget threshold and\n * onboarding rules are not evaluated here yet: budget notices live on the\n * budgets collection (not in these rows), and onboarding investigations are\n * not recorded.\n */\nexport function computeRepositoryHealth(\n  rows: DeliveryLedgerRows,\n  options: ComputeRepositoryHealthOptions = {},\n): RepositoryHealth {\n  const now = (options.now ?? new Date()).getTime();\n  const dayMs = 24 * 60 * 60 * 1000;\n  const red: string[] = [];\n  const yellow: string[] = [];\n  const tasksById = new Map(rows.tasks.map((task) => [task.id, task]));\n\n  for (const receipt of rows.receipts) {\n    if (now - Date.parse(receipt.recordedAt) >= dayMs) continue;\n    if (receipt.state === \"rolled_back\")\n      red.push(`rollback in the last 24h (${receipt.receiptId})`);\n    if (receipt.state === \"cancelled\" && receipt.reason?.toLowerCase().includes(\"kill\")) {\n      red.push(`kill in the last 24h (${receipt.receiptId})`);\n    }\n  }\n\n  const openQuestions = rows.tasks.filter(\n    (task) => task.kind === \"question\" && task.state === \"needs_human\",\n  ).length;\n  if (openQuestions > 0) yellow.push(`${openQuestions} open question(s)`);\n\n  const needsHuman = rows.tasks.filter(\n    (task) => task.kind !== \"question\" && task.state === \"needs_human\",\n  ).length;\n  if (needsHuman > 0) yellow.push(`${needsHuman} task(s) waiting on a human`);\n\n  const maxQueuedMinutes = options.maxQueuedMinutes ?? 5;\n  let staleQueued = 0;\n  let unknownDependencies = 0;\n  for (const task of rows.tasks) {\n    const status = dependencyStatus(task, tasksById, rows.graphs);\n    if (status === \"unknown\") unknownDependencies += 1;\n    if (\n      status === \"ready\" &&\n      task.state === \"queued\" &&\n      task.approval !== \"required\" &&\n      task.approval !== \"denied\" &&\n      now - Date.parse(task.updatedAt) >= maxQueuedMinutes * 60 * 1000\n    )\n      staleQueued += 1;\n  }\n  if (unknownDependencies > 0) {\n    yellow.push(\n      `${unknownDependencies} task(s) with missing or inconsistent graph/dependency snapshots`,\n    );\n  }\n  if (staleQueued > 0) {\n    yellow.push(`${staleQueued} eligible task(s) queued for at least ${maxQueuedMinutes} minutes`);\n  }\n\n  const blocked = rows.changes.filter(\n    (change) =>\n      openChangeStates.has(change.state) &&\n      changeReviewBucket({ risk: change.risk, confidence: change.confidence }) === \"blocked\",\n  ).length;\n  if (blocked > 0) yellow.push(`${blocked} change(s) in the blocked bucket`);\n\n  if (options.maxOpenChanges !== undefined) {\n    const open = rows.changes.filter((change) => openChangeStates.has(change.state)).length;\n    if (open >= options.maxOpenChanges) {\n      yellow.push(`open changes at the cap (${open}/${options.maxOpenChanges})`);\n    }\n  }\n\n  if (red.length > 0) return { color: \"red\", reasons: red };\n  if (yellow.length > 0) return { color: \"yellow\", reasons: yellow };\n  return { color: \"green\", reasons: [] };\n}\n"],"mappings":"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"}

package/dist/delivery-metrics.d.mts

@@ -0,0 +1,2 @@
+import { ChangeReviewBucket, ComputeLedgerMetricsOptions, ComputeRepositoryHealthOptions, DeliveryLedgerRows, DeliveryMetrics, RepositoryHealth, RepositoryHealthColor, changeReviewBucket, computeLedgerMetrics, computeRepositoryHealth } from "./delivery-metrics/metrics.mjs";
+export { type ChangeReviewBucket, type ComputeLedgerMetricsOptions, type ComputeRepositoryHealthOptions, type DeliveryLedgerRows, type DeliveryMetrics, type RepositoryHealth, type RepositoryHealthColor, changeReviewBucket, computeLedgerMetrics, computeRepositoryHealth };

package/dist/delivery-metrics.mjs

@@ -0,0 +1,2 @@
+import { changeReviewBucket, computeLedgerMetrics, computeRepositoryHealth } from "./delivery-metrics/metrics.mjs";
+export { changeReviewBucket, computeLedgerMetrics, computeRepositoryHealth };

package/dist/dispatch.d.mts

@@ -0,0 +1,81 @@
+import { TaskId } from "./schema/id.mjs";
+import { AgentRouteBinding } from "./schema/agent-route.mjs";
+import { ExecutionReference, Task } from "./schema/task.mjs";
+import "./agent-routes.mjs";
+import { DateClock } from "./schema/common.mjs";
+import { BudgetLimits, BudgetMonth } from "./schema/budget.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+//#region src/dispatch.d.ts
+/** Minimal persistence capabilities required to gate and record one dispatch. */
+type DispatchStores = Pick<FactoryStores, "graphs" | "receipts" | "tasks">;
+/** The provider may have accepted the request. Keep this attempt for recovery using its original launch key. */
+declare class ExecutionLaunchPendingError extends Error {}
+/** Stable machine-readable reason a Task could not be dispatched. */
+type DispatchRefusalCode = "route_mismatch" | "awaiting_approval" | "approval_denied" | "dependencies_unsatisfied" | "dispatch_race";
+/** Non-terminal dispatch refusal that identifies the gated Task and retryable reason. */
+declare class DispatchRefusedError extends Error {
+  readonly taskId: TaskId;
+  readonly code: DispatchRefusalCode;
+  readonly reason: string;
+  constructor(taskId: TaskId, code: DispatchRefusalCode, reason: string);
+}
+/**
+ * An exhausted budget is definitive, not a retryable refusal: the task has
+ * already been failed and receipted when this throws, so it never re-enters
+ * the sweep. Operator retry recovers it once budget frees up.
+ */
+declare class BudgetExhaustedError extends Error {
+  readonly taskId: TaskId;
+  readonly month: BudgetMonth;
+  readonly spendUsd: number;
+  constructor(taskId: TaskId, month: BudgetMonth, spendUsd: number);
+}
+/** Factory-wide reservation limits and snapshot used to gate one dispatch. */
+interface DispatchBudget {
+  limits: Pick<BudgetLimits, "totalUsd" | "perTaskReservationUsd">;
+  /** Defaults to the current UTC month. */
+  month?: BudgetMonth;
+  now?: DateClock;
+  /** A dispatcher-wide snapshot used to calculate spend without another list. */
+  tasks?: readonly Task[];
+}
+interface DispatchContext {
+  /** How many launches to try before the task fails for good; a failure re-queues for the next sweep. */
+  maxLaunchAttempts?: number;
+  /** Reserve-before-execution policy for this dispatch. */
+  budget?: DispatchBudget;
+}
+/** Exact provider launch or explicit workflow-owned execution for one Task dispatch. */
+type DispatchOptions = DispatchContext & ({
+  /** Required exact binding when the Task declares an agent route. */
+  route?: AgentRouteBinding;
+  /**
+   * Starts the durable execution for the task (an Eve agent run). Runs after
+   * the task has won the queued -> running transition. Its provider reference
+   * is mandatory so recovery can always find an accepted run.
+   */
+  launch: (task: Task) => Promise<ExecutionReference>;
+  workflowOwned?: never;
+} | {
+  /** Marks work whose workflow advances the running Task without a provider session. */
+  workflowOwned: true;
+  route?: never;
+  launch?: never;
+});
+/** Task identity and exact launch mode supplied to one dispatch attempt. */
+type DispatchTaskInput = {
+  readonly taskId: TaskId;
+} & DispatchOptions;
+/** Default launch-attempt allowance covering delayed identity provisioning. */
+declare const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;
+/**
+ * The handshake between recorded work and execution: win the store-gated
+ * transition (at most one dispatcher can succeed), then start the run. A
+ * launch failure re-queues the task (bumping its attempt) until the attempt
+ * limit, then fails it; a crash between the transition and the launch leaves
+ * a running task with no execution, which the sweep reaps.
+ */
+declare function dispatchTask(stores: DispatchStores, input: DispatchTaskInput): Promise<Task>;
+//#endregion
+export { BudgetExhaustedError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchBudget, DispatchOptions, DispatchRefusalCode, DispatchRefusedError, DispatchStores, DispatchTaskInput, ExecutionLaunchPendingError, dispatchTask };
+//# sourceMappingURL=dispatch.d.mts.map

package/dist/dispatch.mjs

@@ -0,0 +1,140 @@
+import { budgetMonthOf, canReserve, computeMonthSpendUsd } from "./budget.mjs";
+import { InvalidTransitionError } from "./schema/transitions.mjs";
+import { routeKey } from "./agent-routes.mjs";
+import { RecordNotFoundError, VersionConflictError } from "./store/driver.mjs";
+//#region src/dispatch.ts
+/** The provider may have accepted the request. Keep this attempt for recovery using its original launch key. */
+var ExecutionLaunchPendingError = class extends Error {};
+/** Non-terminal dispatch refusal that identifies the gated Task and retryable reason. */
+var DispatchRefusedError = class extends Error {
+	taskId;
+	code;
+	reason;
+	constructor(taskId, code, reason) {
+		super(`dispatch of "${taskId}" refused: ${reason}`);
+		this.name = "DispatchRefusedError";
+		this.taskId = taskId;
+		this.code = code;
+		this.reason = reason;
+	}
+};
+/**
+* An exhausted budget is definitive, not a retryable refusal: the task has
+* already been failed and receipted when this throws, so it never re-enters
+* the sweep. Operator retry recovers it once budget frees up.
+*/
+var BudgetExhaustedError = class extends Error {
+	taskId;
+	month;
+	spendUsd;
+	constructor(taskId, month, spendUsd) {
+		super(`dispatch of "${taskId}" refused: budget for ${month} is exhausted at $${spendUsd}`);
+		this.name = "BudgetExhaustedError";
+		this.taskId = taskId;
+		this.month = month;
+		this.spendUsd = spendUsd;
+	}
+};
+/** Default launch-attempt allowance covering delayed identity provisioning. */
+const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;
+/**
+* The handshake between recorded work and execution: win the store-gated
+* transition (at most one dispatcher can succeed), then start the run. A
+* launch failure re-queues the task (bumping its attempt) until the attempt
+* limit, then fails it; a crash between the transition and the launch leaves
+* a running task with no execution, which the sweep reaps.
+*/
+async function dispatchTask(stores, input) {
+	const { taskId } = input;
+	const options = input;
+	const task = await stores.tasks.get(taskId);
+	if (task === null) throw new RecordNotFoundError("tasks", taskId);
+	const route = task.work.route;
+	if (route !== void 0 && options.workflowOwned === true) throw new DispatchRefusedError(taskId, "route_mismatch", `agent route ${routeKey(route)} requires a launcher`);
+	if (route !== void 0 && (options.route?.id !== route.id || options.route?.version !== route.version)) throw new DispatchRefusedError(taskId, "route_mismatch", `launch requires exact agent route ${routeKey(route)}`);
+	if (task.approval === "required") throw new DispatchRefusedError(taskId, "awaiting_approval", "awaiting human approval");
+	if (task.approval === "denied") throw new DispatchRefusedError(taskId, "approval_denied", "approval was denied");
+	if (!await stores.graphs.dependenciesSatisfied({
+		rootTaskId: task.rootTaskId,
+		taskId: task.id
+	})) throw new DispatchRefusedError(taskId, "dependencies_unsatisfied", "graph dependencies must all be succeeded before dispatch");
+	let reservation;
+	if (options.budget !== void 0 && task.state === "queued") {
+		const budgetNow = (options.budget.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+		const month = options.budget.month ?? budgetMonthOf(budgetNow);
+		const rows = (options.budget.tasks ?? await stores.tasks.list()).map((row) => row.id === taskId ? {
+			...row,
+			reservedUsd: void 0
+		} : row);
+		const spendUsd = computeMonthSpendUsd(rows, month);
+		const { totalUsd, perTaskReservationUsd } = options.budget.limits;
+		if (!canReserve(spendUsd, options.budget.limits)) {
+			const reason = `budget exhausted: ${month} spend $${spendUsd} cannot fit a $${perTaskReservationUsd} reservation under $${totalUsd}`;
+			try {
+				await stores.tasks.transition(taskId, "failed", {
+					reason,
+					expectFrom: "queued"
+				});
+			} catch (error) {
+				if (error instanceof InvalidTransitionError || error instanceof VersionConflictError) throw new DispatchRefusedError(taskId, "dispatch_race", "another dispatcher took the task");
+				throw error;
+			}
+			await stores.receipts.append({
+				repositoryIds: task.repositoryIds,
+				taskId,
+				kind: task.kind,
+				state: "reservation_refused",
+				phase: "budget",
+				reason,
+				attempt: task.attempt,
+				dedupeKey: `task:${taskId}:reservation_refused:${task.attempt}`
+			}).catch(() => void 0);
+			throw new BudgetExhaustedError(taskId, month, spendUsd);
+		}
+		reservation = {
+			reservedUsd: perTaskReservationUsd,
+			reservedAt: budgetNow
+		};
+	}
+	const running = await stores.tasks.transition(taskId, "running", {
+		expectFrom: "queued",
+		expectAttempt: task.attempt,
+		...reservation === void 0 ? {} : { patch: {
+			reservedUsd: reservation.reservedUsd,
+			reservedAt: reservation.reservedAt
+		} },
+		...task.attempt > 1 ? { phase: "retry" } : {}
+	});
+	if (options.workflowOwned === true) return running;
+	let execution;
+	try {
+		execution = await options.launch(running);
+	} catch (error) {
+		if (error instanceof ExecutionLaunchPendingError) throw error;
+		const reason = (error instanceof Error ? error.message : String(error)).slice(0, 500);
+		const limit = options.maxLaunchAttempts ?? 45;
+		if (running.attempt < limit) {
+			const retryReason = `launch failed (attempt ${running.attempt} of ${limit}), will retry: ${reason}`;
+			await stores.tasks.transition(taskId, "queued", {
+				reason: retryReason,
+				phase: "retry",
+				expectFrom: "running",
+				expectAttempt: running.attempt
+			}).catch(() => void 0);
+		} else await stores.tasks.transition(taskId, "failed", {
+			reason: `launch failed after ${running.attempt} attempts: ${reason}`,
+			phase: "retry",
+			expectFrom: "running",
+			expectAttempt: running.attempt
+		}).catch(() => void 0);
+		throw error;
+	}
+	return stores.tasks.recordExecution(taskId, {
+		execution,
+		expectAttempt: running.attempt
+	});
+}
+//#endregion
+export { BudgetExhaustedError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchRefusedError, ExecutionLaunchPendingError, dispatchTask };
+
+//# sourceMappingURL=dispatch.mjs.map

package/dist/dispatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.mjs","names":[],"sources":["../src/dispatch.ts"],"sourcesContent":["import { budgetMonthOf, canReserve, computeMonthSpendUsd } from \"./budget\";\nimport type { AgentRouteBinding } from \"./agent-routes\";\nimport type { BudgetLimits, BudgetMonth } from \"./schema/budget\";\nimport type { DateClock } from \"./schema/common\";\nimport type { TaskId } from \"./schema/id\";\nimport type { ExecutionReference, Task } from \"./schema/task\";\nimport { routeKey } from \"./agent-routes\";\nimport { InvalidTransitionError } from \"./schema/transitions\";\nimport { RecordNotFoundError, VersionConflictError } from \"./store/driver\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/** Minimal persistence capabilities required to gate and record one dispatch. */\nexport type DispatchStores = Pick<FactoryStores, \"graphs\" | \"receipts\" | \"tasks\">;\n\n/** The provider may have accepted the request. Keep this attempt for recovery using its original launch key. */\nexport class ExecutionLaunchPendingError extends Error {}\n\n/** Stable machine-readable reason a Task could not be dispatched. */\nexport type DispatchRefusalCode =\n  | \"route_mismatch\"\n  | \"awaiting_approval\"\n  | \"approval_denied\"\n  | \"dependencies_unsatisfied\"\n  | \"dispatch_race\";\n\n/** Non-terminal dispatch refusal that identifies the gated Task and retryable reason. */\nexport class DispatchRefusedError extends Error {\n  readonly taskId: TaskId;\n  readonly code: DispatchRefusalCode;\n  readonly reason: string;\n\n  constructor(taskId: TaskId, code: DispatchRefusalCode, reason: string) {\n    super(`dispatch of \"${taskId}\" refused: ${reason}`);\n    this.name = \"DispatchRefusedError\";\n    this.taskId = taskId;\n    this.code = code;\n    this.reason = reason;\n  }\n}\n\n/**\n * An exhausted budget is definitive, not a retryable refusal: the task has\n * already been failed and receipted when this throws, so it never re-enters\n * the sweep. Operator retry recovers it once budget frees up.\n */\nexport class BudgetExhaustedError extends Error {\n  readonly taskId: TaskId;\n  readonly month: BudgetMonth;\n  readonly spendUsd: number;\n\n  constructor(taskId: TaskId, month: BudgetMonth, spendUsd: number) {\n    super(`dispatch of \"${taskId}\" refused: budget for ${month} is exhausted at $${spendUsd}`);\n    this.name = \"BudgetExhaustedError\";\n    this.taskId = taskId;\n    this.month = month;\n    this.spendUsd = spendUsd;\n  }\n}\n\n/** Factory-wide reservation limits and snapshot used to gate one dispatch. */\nexport interface DispatchBudget {\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\">;\n  /** Defaults to the current UTC month. */\n  month?: BudgetMonth;\n  now?: DateClock;\n  /** A dispatcher-wide snapshot used to calculate spend without another list. */\n  tasks?: readonly Task[];\n}\n\ninterface DispatchContext {\n  /** How many launches to try before the task fails for good; a failure re-queues for the next sweep. */\n  maxLaunchAttempts?: number;\n  /** Reserve-before-execution policy for this dispatch. */\n  budget?: DispatchBudget;\n}\n\n/** Exact provider launch or explicit workflow-owned execution for one Task dispatch. */\nexport type DispatchOptions = DispatchContext &\n  (\n    | {\n        /** Required exact binding when the Task declares an agent route. */\n        route?: AgentRouteBinding;\n        /**\n         * Starts the durable execution for the task (an Eve agent run). Runs after\n         * the task has won the queued -> running transition. Its provider reference\n         * is mandatory so recovery can always find an accepted run.\n         */\n        launch: (task: Task) => Promise<ExecutionReference>;\n        workflowOwned?: never;\n      }\n    | {\n        /** Marks work whose workflow advances the running Task without a provider session. */\n        workflowOwned: true;\n        route?: never;\n        launch?: never;\n      }\n  );\n\n/** Task identity and exact launch mode supplied to one dispatch attempt. */\nexport type DispatchTaskInput = { readonly taskId: TaskId } & DispatchOptions;\n\n// A fresh Vercel project rejects its own agents' sessions until its identity\n// finishes provisioning; at one sweep per minute the budget must outlast that.\n/** Default launch-attempt allowance covering delayed identity provisioning. */\nexport const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;\n\n/**\n * The handshake between recorded work and execution: win the store-gated\n * transition (at most one dispatcher can succeed), then start the run. A\n * launch failure re-queues the task (bumping its attempt) until the attempt\n * limit, then fails it; a crash between the transition and the launch leaves\n * a running task with no execution, which the sweep reaps.\n */\nexport async function dispatchTask(\n  stores: DispatchStores,\n  input: DispatchTaskInput,\n): Promise<Task> {\n  const { taskId } = input;\n  const options: DispatchOptions = input;\n  const task = await stores.tasks.get(taskId);\n  if (task === null) {\n    throw new RecordNotFoundError(\"tasks\", taskId);\n  }\n  const route = task.work.route;\n  if (route !== undefined && options.workflowOwned === true) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"route_mismatch\",\n      `agent route ${routeKey(route)} requires a launcher`,\n    );\n  }\n  if (\n    route !== undefined &&\n    (options.route?.id !== route.id || options.route?.version !== route.version)\n  ) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"route_mismatch\",\n      `launch requires exact agent route ${routeKey(route)}`,\n    );\n  }\n  if (task.approval === \"required\") {\n    throw new DispatchRefusedError(taskId, \"awaiting_approval\", \"awaiting human approval\");\n  }\n  if (task.approval === \"denied\") {\n    throw new DispatchRefusedError(taskId, \"approval_denied\", \"approval was denied\");\n  }\n  if (\n    !(await stores.graphs.dependenciesSatisfied({\n      rootTaskId: task.rootTaskId,\n      taskId: task.id,\n    }))\n  ) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"dependencies_unsatisfied\",\n      \"graph dependencies must all be succeeded before dispatch\",\n    );\n  }\n\n  // The reservation gates queued -> running only; any other state falls\n  // through to the transition below, which rejects it as invalid.\n  let reservation: { reservedUsd: number; reservedAt: string } | undefined;\n  if (options.budget !== undefined && task.state === \"queued\") {\n    const budgetNow = (options.budget.now ?? (() => new Date()))().toISOString();\n    const month = options.budget.month ?? budgetMonthOf(budgetNow);\n    // This task's own retained reservation from a prior attempt is excluded,\n    // because re-reserving overwrites it. Its settled cost stays counted:\n    // that money was actually spent and a retry must not reopen it.\n    const rows = (options.budget.tasks ?? (await stores.tasks.list())).map((row) =>\n      row.id === taskId ? { ...row, reservedUsd: undefined } : row,\n    );\n    const spendUsd = computeMonthSpendUsd(rows, month);\n    const { totalUsd, perTaskReservationUsd } = options.budget.limits;\n    if (!canReserve(spendUsd, options.budget.limits)) {\n      const reason = `budget exhausted: ${month} spend $${spendUsd} cannot fit a $${perTaskReservationUsd} reservation under $${totalUsd}`;\n      // Fail first, so BudgetExhaustedError's contract (task already failed)\n      // holds; losing the task to a concurrent dispatcher surfaces as a\n      // refusal, never as a false exhaustion with a misleading receipt.\n      try {\n        await stores.tasks.transition(taskId, \"failed\", { reason, expectFrom: \"queued\" });\n      } catch (error) {\n        if (error instanceof InvalidTransitionError || error instanceof VersionConflictError) {\n          throw new DispatchRefusedError(\n            taskId,\n            \"dispatch_race\",\n            \"another dispatcher took the task\",\n          );\n        }\n        throw error;\n      }\n      // Best-effort: the failed transition above already wrote its own\n      // receipt carrying this reason, so losing this supplementary one\n      // cannot lose the evidence.\n      await stores.receipts\n        .append({\n          repositoryIds: task.repositoryIds,\n          taskId,\n          kind: task.kind,\n          state: \"reservation_refused\",\n          phase: \"budget\",\n          reason,\n          attempt: task.attempt,\n          dedupeKey: `task:${taskId}:reservation_refused:${task.attempt}`,\n        })\n        .catch(() => undefined);\n      throw new BudgetExhaustedError(taskId, month, spendUsd);\n    }\n    reservation = { reservedUsd: perTaskReservationUsd, reservedAt: budgetNow };\n  }\n\n  const running = await stores.tasks.transition(taskId, \"running\", {\n    expectFrom: \"queued\",\n    expectAttempt: task.attempt,\n    ...(reservation === undefined\n      ? {}\n      : {\n          patch: {\n            reservedUsd: reservation.reservedUsd,\n            reservedAt: reservation.reservedAt,\n          },\n        }),\n    ...(task.attempt > 1 ? { phase: \"retry\" } : {}),\n  });\n  if (options.workflowOwned === true) return running;\n  let execution: ExecutionReference;\n  try {\n    execution = await options.launch(running);\n  } catch (error) {\n    if (error instanceof ExecutionLaunchPendingError) throw error;\n    const reason = (error instanceof Error ? error.message : String(error)).slice(0, 500);\n    const limit = options.maxLaunchAttempts ?? DEFAULT_MAX_LAUNCH_ATTEMPTS;\n    if (running.attempt < limit) {\n      const retryReason = `launch failed (attempt ${running.attempt} of ${limit}), will retry: ${reason}`;\n      await stores.tasks\n        .transition(taskId, \"queued\", {\n          reason: retryReason,\n          phase: \"retry\",\n          expectFrom: \"running\",\n          expectAttempt: running.attempt,\n        })\n        .catch(() => undefined);\n    } else {\n      await stores.tasks\n        .transition(taskId, \"failed\", {\n          reason: `launch failed after ${running.attempt} attempts: ${reason}`,\n          phase: \"retry\",\n          expectFrom: \"running\",\n          expectAttempt: running.attempt,\n        })\n        .catch(() => undefined);\n    }\n    throw error;\n  }\n  // Surface a failed binding so a durable caller can recover the same launch;\n  // never report acceptance with an unrecorded or stale execution.\n  return stores.tasks.recordExecution(taskId, {\n    execution,\n    expectAttempt: running.attempt,\n  });\n}\n"],"mappings":"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"}

package/dist/errors.d.mts

@@ -0,0 +1,15 @@
+//#region src/errors.d.ts
+/** Returns an error message with supplied secrets and recognized credentials removed. */
+declare function redactedErrorMessage(error: unknown, secrets?: readonly (string | undefined)[], fallback?: string): string;
+/** Bounded, recursively redacted diagnostic details safe for structured reporting. */
+interface RedactedErrorDetails {
+  name: string;
+  message: string;
+  stack?: string;
+  cause?: RedactedErrorDetails;
+}
+/** Builds bounded, recursively redacted diagnostic details from an unknown error. */
+declare function redactedErrorDetails(error: unknown, secrets?: readonly (string | undefined)[]): RedactedErrorDetails;
+//#endregion
+export { RedactedErrorDetails, redactedErrorDetails, redactedErrorMessage };
+//# sourceMappingURL=errors.d.mts.map

package/dist/errors.mjs

@@ -0,0 +1,38 @@
+//#region src/errors.ts
+const credentialPatterns = [
+	/github_pat_[A-Za-z0-9_]+/gu,
+	/gh[psoru]_[A-Za-z0-9_]+/gu,
+	/xox[baprs]-[A-Za-z0-9-]+/gu,
+	/Basic [A-Za-z0-9+/=]+/gu,
+	/Bearer [A-Za-z0-9._~+/-]+=*/giu,
+	/vercel_blob_rw_[A-Za-z0-9_]+/gu
+];
+function errorMessage(error, fallback) {
+	return error instanceof Error ? error.message : fallback ?? String(error);
+}
+/** Returns an error message with supplied secrets and recognized credentials removed. */
+function redactedErrorMessage(error, secrets = [], fallback) {
+	let message = errorMessage(error, fallback);
+	for (const secret of secrets) {
+		const value = secret?.trim();
+		if (value) message = message.replaceAll(value, "[REDACTED]");
+	}
+	for (const pattern of credentialPatterns) message = message.replace(pattern, (match) => match.startsWith("Basic ") ? "Basic [REDACTED]" : "[REDACTED]");
+	return message;
+}
+/** Builds bounded, recursively redacted diagnostic details from an unknown error. */
+function redactedErrorDetails(error, secrets = []) {
+	return nestedRedactedErrorDetails(error, secrets, 0);
+}
+function nestedRedactedErrorDetails(error, secrets, depth) {
+	return {
+		name: error instanceof Error ? error.name : "UnknownError",
+		message: redactedErrorMessage(error, secrets, "Unknown error").slice(0, 2e3),
+		...error instanceof Error && error.stack ? { stack: redactedErrorMessage(error.stack, secrets).slice(0, 8e3) } : {},
+		...error instanceof Error && error.cause !== void 0 && depth < 2 ? { cause: nestedRedactedErrorDetails(error.cause, secrets, depth + 1) } : {}
+	};
+}
+//#endregion
+export { redactedErrorDetails, redactedErrorMessage };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["const credentialPatterns = [\n  /github_pat_[A-Za-z0-9_]+/gu,\n  /gh[psoru]_[A-Za-z0-9_]+/gu,\n  /xox[baprs]-[A-Za-z0-9-]+/gu,\n  /Basic [A-Za-z0-9+/=]+/gu,\n  /Bearer [A-Za-z0-9._~+/-]+=*/giu,\n  /vercel_blob_rw_[A-Za-z0-9_]+/gu,\n] as const;\n\nfunction errorMessage(error: unknown, fallback?: string): string {\n  return error instanceof Error ? error.message : (fallback ?? String(error));\n}\n\n/** Returns an error message with supplied secrets and recognized credentials removed. */\nexport function redactedErrorMessage(\n  error: unknown,\n  secrets: readonly (string | undefined)[] = [],\n  fallback?: string,\n): string {\n  let message = errorMessage(error, fallback);\n  for (const secret of secrets) {\n    const value = secret?.trim();\n    if (value) message = message.replaceAll(value, \"[REDACTED]\");\n  }\n  for (const pattern of credentialPatterns) {\n    message = message.replace(pattern, (match) =>\n      match.startsWith(\"Basic \") ? \"Basic [REDACTED]\" : \"[REDACTED]\",\n    );\n  }\n  return message;\n}\n\n/** Bounded, recursively redacted diagnostic details safe for structured reporting. */\nexport interface RedactedErrorDetails {\n  name: string;\n  message: string;\n  stack?: string;\n  cause?: RedactedErrorDetails;\n}\n\n/** Builds bounded, recursively redacted diagnostic details from an unknown error. */\nexport function redactedErrorDetails(\n  error: unknown,\n  secrets: readonly (string | undefined)[] = [],\n): RedactedErrorDetails {\n  return nestedRedactedErrorDetails(error, secrets, 0);\n}\n\nfunction nestedRedactedErrorDetails(\n  error: unknown,\n  secrets: readonly (string | undefined)[],\n  depth: number,\n): RedactedErrorDetails {\n  return {\n    name: error instanceof Error ? error.name : \"UnknownError\",\n    message: redactedErrorMessage(error, secrets, \"Unknown error\").slice(0, 2000),\n    ...(error instanceof Error && error.stack\n      ? { stack: redactedErrorMessage(error.stack, secrets).slice(0, 8000) }\n      : {}),\n    ...(error instanceof Error && error.cause !== undefined && depth < 2\n      ? { cause: nestedRedactedErrorDetails(error.cause, secrets, depth + 1) }\n      : {}),\n  };\n}\n"],"mappings":";AAAA,MAAM,qBAAqB;CACzB;CACA;CACA;CACA;CACA;CACA;AACF;AAEA,SAAS,aAAa,OAAgB,UAA2B;CAC/D,OAAO,iBAAiB,QAAQ,MAAM,UAAW,YAAY,OAAO,KAAK;AAC3E;;AAGA,SAAgB,qBACd,OACA,UAA2C,CAAC,GAC5C,UACQ;CACR,IAAI,UAAU,aAAa,OAAO,QAAQ;CAC1C,KAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,QAAQ,QAAQ,KAAK;EAC3B,IAAI,OAAO,UAAU,QAAQ,WAAW,OAAO,YAAY;CAC7D;CACA,KAAK,MAAM,WAAW,oBACpB,UAAU,QAAQ,QAAQ,UAAU,UAClC,MAAM,WAAW,QAAQ,IAAI,qBAAqB,YACpD;CAEF,OAAO;AACT;;AAWA,SAAgB,qBACd,OACA,UAA2C,CAAC,GACtB;CACtB,OAAO,2BAA2B,OAAO,SAAS,CAAC;AACrD;AAEA,SAAS,2BACP,OACA,SACA,OACsB;CACtB,OAAO;EACL,MAAM,iBAAiB,QAAQ,MAAM,OAAO;EAC5C,SAAS,qBAAqB,OAAO,SAAS,eAAe,CAAC,CAAC,MAAM,GAAG,GAAI;EAC5E,GAAI,iBAAiB,SAAS,MAAM,QAChC,EAAE,OAAO,qBAAqB,MAAM,OAAO,OAAO,CAAC,CAAC,MAAM,GAAG,GAAI,EAAE,IACnE,CAAC;EACL,GAAI,iBAAiB,SAAS,MAAM,UAAU,KAAA,KAAa,QAAQ,IAC/D,EAAE,OAAO,2BAA2B,MAAM,OAAO,SAAS,QAAQ,CAAC,EAAE,IACrE,CAAC;CACP;AACF"}