@vercel/factory 0.0.14 → 0.0.16

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,152 @@
+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, so the running attempt must remain available for
+ * recovery with its original launch key. Catchers must not queue a replacement attempt blindly.
+ */
+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 {
+  /** Exact Task whose current dispatch attempt was refused. */
+  readonly taskId: TaskId;
+  /** Stable gate or race category suitable for branching and telemetry. */
+  readonly code: DispatchRefusalCode;
+  /** Human-readable refusal context; canonical Task state remains authoritative. */
+  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 {
+  /** Exact Task already transitioned to `failed` by the exhausted admission. */
+  readonly taskId: TaskId;
+  /** UTC budget month whose limit refused the reservation. */
+  readonly month: BudgetMonth;
+  /** Counted settled cost and live reservations observed for that month. */
+  readonly spendUsd: number;
+  constructor(taskId: TaskId, month: BudgetMonth, spendUsd: number);
+}
+/** Factory-wide reservation limits and snapshot used to gate one dispatch. */
+interface DispatchBudget {
+  /** Factory-wide monthly ceiling and amount reserved for each admitted Task. */
+  limits: Pick<BudgetLimits, "totalUsd" | "perTaskReservationUsd">;
+  /** Defaults to true. False records reservations without enforcing the monthly ceiling. */
+  enforce?: boolean;
+  /** Defaults to the current UTC month. */
+  month?: BudgetMonth;
+  /** Clock used only to derive the reservation month and timestamp. Defaults to `new Date()`. */
+  now?: DateClock;
+  /** A dispatcher-wide snapshot used to calculate spend without another list. */
+  tasks?: readonly Task[];
+}
+interface DispatchContext {
+  /** Exact workflow-confirmed continuation attempt; other replacement attempts count as retries. */
+  continuationAttempt?: number;
+  /**
+   * Maximum Task attempt number allowed for launch failure retries. Defaults to 45. A normal
+   * failure below the limit requeues the Task, which increments its attempt 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 route-less work whose workflow advances the running Task without a provider
+   * session. The caller must schedule that workflow after this admission returns.
+   */
+  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;
+/**
+ * Claims one queued Task and starts its exact execution mode.
+ *
+ * @remarks
+ * Dispatch first checks route, approval, dependency, and optional budget gates, then atomically
+ * transitions the Task from `queued` to `running`. Only the winner invokes `launch`. A successful
+ * provider dispatch returns only after its execution reference is stored; it does not mean the
+ * Task completed. `workflowOwned: true` returns the claimed running Task without starting a
+ * provider session.
+ *
+ * An ordinary launch failure is rethrown after a best-effort transition back to `queued`, or to
+ * `failed` once `maxLaunchAttempts` is exhausted. `ExecutionLaunchPendingError` instead leaves the
+ * attempt running because the provider may have accepted the request; recovery must inspect or
+ * repeat the launch with the original idempotency key. Budget exhaustion fails and receipts the
+ * Task before throwing `BudgetExhaustedError`. Since compensating transitions are best-effort,
+ * callers handling any thrown launch error should reread canonical Task state before deciding
+ * whether to schedule another attempt.
+ *
+ * @param stores - Task, graph, and receipt stores that own the dispatch gates.
+ * @param input - Exact Task identity plus either a launcher or workflow-owned marker.
+ * @returns The running Task, including its durably recorded execution when a launcher was used.
+ * @throws `RecordNotFoundError` when the Task is absent.
+ * @throws `DispatchRefusedError` when routing, approval, dependencies, or a budget-admission race refuses dispatch.
+ * @throws `InvalidTransitionError` when the Task is no longer queued when this caller claims it.
+ * @throws `BudgetExhaustedError` after the Task has been failed because no reservation fits.
+ * @throws `ExecutionLaunchPendingError` when provider acceptance is ambiguous and requires recovery.
+ * @see The shipped `docs/recipes/eve-agent.md` and `docs/recipes/retry-recovery.md` recipes.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   DispatchRefusedError,
+ *   dispatchTask,
+ *   type DispatchStores,
+ * } from "@vercel/factory/execution";
+ * import type { TaskId } from "@vercel/factory/tasks";
+ * import { parseAgentRouteBinding } from "@vercel/factory/workflows";
+ *
+ * declare const stores: DispatchStores;
+ * declare const taskId: TaskId;
+ * const route = parseAgentRouteBinding({ id: "worker", version: 1 });
+ *
+ * try {
+ *   await dispatchTask(stores, {
+ *     taskId,
+ *     route,
+ *     launch: async () => ({ provider: "eve", sessionId: "ses_example" }),
+ *   });
+ * } catch (error) {
+ *   if (error instanceof DispatchRefusedError) {
+ *     // `error.code` identifies the gate; canonical Task state remains authoritative.
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+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