@vercel/factory 0.0.14 → 0.0.15

package/dist/deepsec/finding.mjs

@@ -0,0 +1,56 @@
+import { findingSchema } from "../schema/finding.mjs";
+import { z } from "zod";
+//#region src/deepsec/finding.ts
+/** Deepsec's exported finding shape, as far as Factory depends on it. */
+const deepsecFindingSchema = z.looseObject({
+	title: z.string().min(1),
+	description: z.string().min(1),
+	severity: z.string().min(1),
+	metadata: z.looseObject({
+		filePath: z.string().min(1).optional(),
+		lineNumbers: z.array(z.number().int().min(1)).readonly().optional(),
+		vulnSlug: z.string().min(1).optional(),
+		confidence: z.string().optional(),
+		runId: z.string().optional()
+	}).optional()
+}).readonly();
+const deepsecFindingsSchema = z.array(deepsecFindingSchema).readonly();
+/** Deepsec export document accepted by the optional scanner adapter. */
+const deepsecExportSchema = z.union([deepsecFindingsSchema, z.looseObject({ findings: deepsecFindingsSchema }).transform((value) => value.findings)]);
+const priorityBySeverity = {
+	CRITICAL: "P0",
+	HIGH: "P1",
+	MEDIUM: "P2",
+	HIGH_BUG: "P2",
+	BUG: "P3",
+	LOW: "P3"
+};
+/** Validate and convert one Deepsec finding into Factory's normalized Finding contract. */
+function findingFromDeepsec(input) {
+	const raw = deepsecFindingSchema.parse(input);
+	const meta = raw.metadata ?? {};
+	const confidence = (meta.confidence ?? "").toLowerCase();
+	const line = meta.lineNumbers?.[0];
+	const endLine = meta.lineNumbers === void 0 ? void 0 : Math.max(...meta.lineNumbers);
+	return findingSchema.parse({
+		title: raw.title.replace(/^\[[A-Z_]+\]\s*/u, "").slice(0, 200),
+		body: raw.description.slice(0, 8e3),
+		...meta.filePath === void 0 ? {} : { path: meta.filePath.slice(0, 500) },
+		...line === void 0 ? {} : { line },
+		...endLine === void 0 || endLine === line ? {} : { endLine },
+		priority: priorityBySeverity[raw.severity.toUpperCase()] ?? "P3",
+		category: "security",
+		verification: {
+			level: confidence === "high" ? "supported" : "unverified",
+			method: "static_analysis",
+			summary: `deepsec ${meta.vulnSlug ?? "finding"} with ${confidence || "unknown"} confidence${meta.runId === void 0 ? "" : ` (run ${meta.runId})`}.`,
+			limitations: "AI-assisted static analysis of the checkout; not reproduced at runtime."
+		},
+		tool: "deepsec",
+		...meta.vulnSlug === void 0 ? {} : { ruleId: meta.vulnSlug }
+	});
+}
+//#endregion
+export { deepsecExportSchema, deepsecFindingSchema, findingFromDeepsec };
+
+//# sourceMappingURL=finding.mjs.map

package/dist/deepsec/finding.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding.mjs","names":[],"sources":["../../src/deepsec/finding.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { findingSchema, type Finding, type FindingPriority } from \"../schema/finding\";\n\n/** Deepsec's exported finding shape, as far as Factory depends on it. */\nexport const deepsecFindingSchema = z\n  .looseObject({\n    title: z.string().min(1),\n    description: z.string().min(1),\n    severity: z.string().min(1),\n    metadata: z\n      .looseObject({\n        filePath: z.string().min(1).optional(),\n        lineNumbers: z.array(z.number().int().min(1)).readonly().optional(),\n        vulnSlug: z.string().min(1).optional(),\n        confidence: z.string().optional(),\n        runId: z.string().optional(),\n      })\n      .optional(),\n  })\n  .readonly();\n\nconst deepsecFindingsSchema = z.array(deepsecFindingSchema).readonly();\n\n/** Deepsec export document accepted by the optional scanner adapter. */\nexport const deepsecExportSchema = z.union([\n  deepsecFindingsSchema,\n  z.looseObject({ findings: deepsecFindingsSchema }).transform((value) => value.findings),\n]);\n\n/** Provider payload accepted for one Deepsec finding before normalization. */\nexport type DeepsecFindingInput = z.input<typeof deepsecFindingSchema>;\n\n/** Parsed Deepsec finding payload used by the normalization adapter. */\nexport type DeepsecFinding = z.output<typeof deepsecFindingSchema>;\n\n/** Provider export document accepted before its wrapper is normalized. */\nexport type DeepsecExportInput = z.input<typeof deepsecExportSchema>;\n\n/** Parsed list of Deepsec findings produced by the export schema. */\nexport type DeepsecExport = z.output<typeof deepsecExportSchema>;\n\nconst priorityBySeverity: Record<string, FindingPriority> = {\n  CRITICAL: \"P0\",\n  HIGH: \"P1\",\n  MEDIUM: \"P2\",\n  HIGH_BUG: \"P2\",\n  BUG: \"P3\",\n  LOW: \"P3\",\n};\n\n/** Validate and convert one Deepsec finding into Factory's normalized Finding contract. */\nexport function findingFromDeepsec(input: DeepsecFindingInput): Finding {\n  const raw = deepsecFindingSchema.parse(input);\n  const meta = raw.metadata ?? {};\n  const confidence = (meta.confidence ?? \"\").toLowerCase();\n  const line = meta.lineNumbers?.[0];\n  const endLine = meta.lineNumbers === undefined ? undefined : Math.max(...meta.lineNumbers);\n  return findingSchema.parse({\n    title: raw.title.replace(/^\\[[A-Z_]+\\]\\s*/u, \"\").slice(0, 200),\n    body: raw.description.slice(0, 8000),\n    ...(meta.filePath === undefined ? {} : { path: meta.filePath.slice(0, 500) }),\n    ...(line === undefined ? {} : { line }),\n    ...(endLine === undefined || endLine === line ? {} : { endLine }),\n    priority: priorityBySeverity[raw.severity.toUpperCase()] ?? \"P3\",\n    category: \"security\",\n    verification: {\n      level: confidence === \"high\" ? \"supported\" : \"unverified\",\n      method: \"static_analysis\",\n      summary: `deepsec ${meta.vulnSlug ?? \"finding\"} with ${confidence || \"unknown\"} confidence${meta.runId === undefined ? \"\" : ` (run ${meta.runId})`}.`,\n      limitations: \"AI-assisted static analysis of the checkout; not reproduced at runtime.\",\n    },\n    tool: \"deepsec\",\n    ...(meta.vulnSlug === undefined ? {} : { ruleId: meta.vulnSlug }),\n  });\n}\n"],"mappings":";;;;AAIA,MAAa,uBAAuB,EACjC,YAAY;CACX,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CACvB,aAAa,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CAC7B,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CAC1B,UAAU,EACP,YAAY;EACX,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;EACrC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS;EAClE,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;EACrC,YAAY,EAAE,OAAO,CAAC,CAAC,SAAS;EAChC,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS;CAC7B,CAAC,CAAC,CACD,SAAS;AACd,CAAC,CAAC,CACD,SAAS;AAEZ,MAAM,wBAAwB,EAAE,MAAM,oBAAoB,CAAC,CAAC,SAAS;;AAGrE,MAAa,sBAAsB,EAAE,MAAM,CACzC,uBACA,EAAE,YAAY,EAAE,UAAU,sBAAsB,CAAC,CAAC,CAAC,WAAW,UAAU,MAAM,QAAQ,CACxF,CAAC;AAcD,MAAM,qBAAsD;CAC1D,UAAU;CACV,MAAM;CACN,QAAQ;CACR,UAAU;CACV,KAAK;CACL,KAAK;AACP;;AAGA,SAAgB,mBAAmB,OAAqC;CACtE,MAAM,MAAM,qBAAqB,MAAM,KAAK;CAC5C,MAAM,OAAO,IAAI,YAAY,CAAC;CAC9B,MAAM,cAAc,KAAK,cAAc,GAAA,CAAI,YAAY;CACvD,MAAM,OAAO,KAAK,cAAc;CAChC,MAAM,UAAU,KAAK,gBAAgB,KAAA,IAAY,KAAA,IAAY,KAAK,IAAI,GAAG,KAAK,WAAW;CACzF,OAAO,cAAc,MAAM;EACzB,OAAO,IAAI,MAAM,QAAQ,oBAAoB,EAAE,CAAC,CAAC,MAAM,GAAG,GAAG;EAC7D,MAAM,IAAI,YAAY,MAAM,GAAG,GAAI;EACnC,GAAI,KAAK,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,MAAM,GAAG,GAAG,EAAE;EAC3E,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK;EACrC,GAAI,YAAY,KAAA,KAAa,YAAY,OAAO,CAAC,IAAI,EAAE,QAAQ;EAC/D,UAAU,mBAAmB,IAAI,SAAS,YAAY,MAAM;EAC5D,UAAU;EACV,cAAc;GACZ,OAAO,eAAe,SAAS,cAAc;GAC7C,QAAQ;GACR,SAAS,WAAW,KAAK,YAAY,UAAU,QAAQ,cAAc,UAAU,aAAa,KAAK,UAAU,KAAA,IAAY,KAAK,SAAS,KAAK,MAAM,GAAG;GACnJ,aAAa;EACf;EACA,MAAM;EACN,GAAI,KAAK,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,KAAK,SAAS;CACjE,CAAC;AACH"}

package/dist/deepsec.d.mts

@@ -0,0 +1,3 @@
+import { DeepsecExport, DeepsecExportInput, DeepsecFinding, DeepsecFindingInput, deepsecExportSchema, deepsecFindingSchema, findingFromDeepsec } from "./deepsec/finding.mjs";
+import { DeepsecAgent, DeepsecCommandResult, DeepsecCredentialCommandInput, DeepsecScanFailure, DeepsecScanFailureCode, DeepsecScanFinding, DeepsecScanInput, DeepsecScanResult, DeepsecScanSuccess, DeepsecScanTool, DeepsecScanToolOptions, DeepsecScanToolStores, DeepsecThinkingLevel, createDeepsecScanTool, deepsecScanInputSchema } from "./deepsec/eve-tool.mjs";
+export { type DeepsecAgent, type DeepsecCommandResult, type DeepsecCredentialCommandInput, type DeepsecExport, type DeepsecExportInput, type DeepsecFinding, type DeepsecFindingInput, type DeepsecScanFailure, type DeepsecScanFailureCode, type DeepsecScanFinding, type DeepsecScanInput, type DeepsecScanResult, type DeepsecScanSuccess, type DeepsecScanTool, type DeepsecScanToolOptions, type DeepsecScanToolStores, type DeepsecThinkingLevel, createDeepsecScanTool, deepsecExportSchema, deepsecFindingSchema, deepsecScanInputSchema, findingFromDeepsec };

package/dist/delivery-metrics/metrics.d.mts

@@ -0,0 +1,93 @@
+import { Signal } from "../schema/signal.mjs";
+import { Task } from "../schema/task.mjs";
+import { TaskGraph } from "../schema/task-graph.mjs";
+import { Change, ChangeLevel } from "../schema/change.mjs";
+import { Receipt } from "../schema/receipt.mjs";
+//#region src/delivery-metrics/metrics.d.ts
+/**
+ * The derived review bucket from the default risk x confidence table. Derived
+ * at read time, never stored; "blocked" is a bucket, not a change state.
+ */
+type ChangeReviewBucket = "stamp" | "review" | "blocked";
+/** Risk and confidence inputs used to derive a human-review bucket. */
+interface ChangeReviewFactors {
+  risk: ChangeLevel;
+  confidence: ChangeLevel;
+}
+/** Derives the default human-review bucket from a change's risk and confidence. */
+declare function changeReviewBucket(input: ChangeReviewFactors): ChangeReviewBucket;
+/** Validated ledger rows used to derive Factory metrics and health. */
+interface DeliveryLedgerRows {
+  changes: readonly Change[];
+  signals: readonly Signal[];
+  receipts: readonly Receipt[];
+  tasks: readonly Task[];
+  /** Validated graph snapshots keyed by rootTaskId. Missing snapshots make health yellow, never runnable. */
+  graphs?: ReadonlyMap<string, TaskGraph>;
+}
+/** Options controlling ledger metric evaluation. */
+interface ComputeLedgerMetricsOptions {
+  /** Evaluation time; defaults to the current time. */
+  now?: Date;
+  /** Days a landed change must hold without a rollback. Default 7. */
+  holdDays?: number;
+}
+/** Product metrics derived deterministically from ledger rows. */
+interface DeliveryMetrics {
+  /**
+   * Changes a human merged that reached deployed (rolled_out for high risk)
+   * and did not roll back within the hold window. Includes provisional ones.
+   */
+  landed: number;
+  /** Landed changes still inside the hold window; the number may drop. */
+  provisional: number;
+  /** landed / (landed + rolled back + closed after ready). Null when nothing decided. */
+  stickRate: number | null;
+  /**
+   * Not computable from ledger rows: needs a record of human commits pushed
+   * to the pull request after ready, which nothing writes today.
+   */
+  stampedClean: null;
+  /** Median ms from the ready receipt to the merged receipt, per review bucket. */
+  humanTimeMs: {
+    stamp: number | null;
+    review: number | null;
+  };
+  /** Sum of settled task cost over landed changes / landed. Null until budgets settle. */
+  costPerLandedUsd: number | null;
+  /** Signals triage turned away plus changes closed in verification. */
+  filtered: number;
+}
+/**
+ * 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.
+ */
+declare function computeLedgerMetrics(rows: DeliveryLedgerRows, options?: ComputeLedgerMetricsOptions): DeliveryMetrics;
+/** Overall repository health severity derived from operational evidence. */
+type RepositoryHealthColor = "green" | "yellow" | "red";
+/** Options controlling repository health evaluation. */
+interface ComputeRepositoryHealthOptions {
+  now?: Date;
+  /** Open-change cap from factory configuration; omitted disables that check. */
+  maxOpenChanges?: number;
+  /** Minutes an eligible executable task may remain queued before health turns yellow. Default 5. */
+  maxQueuedMinutes?: number;
+}
+/** Explainable repository health derived from ledger and graph state. */
+interface RepositoryHealth {
+  readonly color: RepositoryHealthColor;
+  /** Every rule that fired, so the color is explainable from rows. */
+  readonly reasons: readonly string[];
+}
+/**
+ * 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.
+ */
+declare function computeRepositoryHealth(rows: DeliveryLedgerRows, options?: ComputeRepositoryHealthOptions): RepositoryHealth;
+//#endregion
+export { ChangeReviewBucket, ChangeReviewFactors, ComputeLedgerMetricsOptions, ComputeRepositoryHealthOptions, DeliveryLedgerRows, DeliveryMetrics, RepositoryHealth, RepositoryHealthColor, changeReviewBucket, computeLedgerMetrics, computeRepositoryHealth };
+//# sourceMappingURL=metrics.d.mts.map

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