@vercel/factory 0.0.11 → 0.0.13

package/dist/change-CzEAoFVE.mjs

@@ -0,0 +1,620 @@
+import { d as schemaVersionSchema, i as repositoryIdSchema, l as isoDateTimeSchema, n as factoryIdSchema, s as taskIdSchema, t as changeIdSchema } from "./id-DwCihQr4.mjs";
+import { _ as taskExecutionRepositoryIdsSchema } from "./approval-CwhTP1XB.mjs";
+import { n as RecordNotFoundError, r as VersionConflictError } from "./driver-Bbd25rNM.mjs";
+import { z } from "zod";
+import { createHash } from "node:crypto";
+//#region src/budget.ts
+/**
+* Stable factory identity for budget rows. Nothing mints factory ids yet, so
+* the app derives one from a deployment-stable seed such as the Vercel
+* project id.
+*/
+function deriveFactoryId(seed) {
+	return factoryIdSchema.parse(`fac_${createHash("sha256").update(seed).digest("hex").slice(0, 32)}`);
+}
+/** The budget month ("YYYY-MM", UTC) a timestamp falls into. */
+function budgetMonthOf(isoDateTime) {
+	return isoDateTime.slice(0, 7);
+}
+function microsOf(usd) {
+	return Math.round(usd * 1e6);
+}
+/**
+* Monthly spend is derived from task rows, never stored: each task counts its
+* settled cost once that exists, otherwise its held reservation. A task
+* settles once, so a settled row never also counts its reservation.
+* Attribution uses the reservation time so tasks that wait across a month
+* boundary charge the month they actually ran in.
+*/
+function computeMonthSpendUsd(tasks, month) {
+	let spendMicros = 0;
+	for (const task of tasks) {
+		if (budgetMonthOf(task.reservedAt ?? task.createdAt) !== month) continue;
+		spendMicros += microsOf(task.settledUsd ?? task.reservedUsd ?? 0);
+	}
+	return spendMicros / 1e6;
+}
+/**
+* True when one more per-task slice fits under the monthly total. Dispatch
+* refuses on this exact predicate and budgetStatus reports "exhausted" on its
+* negation, so refusing and reporting can never disagree.
+*/
+function canReserve(spendUsd, limits) {
+	return microsOf(spendUsd) + microsOf(limits.perTaskReservationUsd) <= microsOf(limits.totalUsd);
+}
+function budgetStatus(spendUsd, limits) {
+	if (!canReserve(spendUsd, limits)) return "exhausted";
+	if (microsOf(spendUsd) * 100 >= microsOf(limits.totalUsd) * limits.warningPercent) return "warning";
+	return "ok";
+}
+const TERMINAL_TASK_STATES = /* @__PURE__ */ new Set([
+	"succeeded",
+	"failed",
+	"cancelled"
+]);
+/**
+* Settle reserved terminal tasks the session hook did not: a task that ended
+* after its session (a change verified later) or whose session died. Settles
+* at the recorded usage, or at zero with a warning reason when none was
+* recorded within the grace window.
+*/
+async function sweepSettlements(stores, options = {}) {
+	const graceMs = (options.graceMinutes ?? 10) * 6e4;
+	const nowMs = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	const settled = [];
+	for (const task of await stores.tasks.list()) {
+		if (task.reservedUsd === void 0 || task.settledUsd !== void 0) continue;
+		if (!TERMINAL_TASK_STATES.has(task.state)) continue;
+		if (nowMs - Date.parse(task.updatedAt) < graceMs) continue;
+		const totalUsd = task.usage?.costUsd ?? 0;
+		try {
+			const result = await stores.tasks.settle(task.id, { totalUsd }, { reason: task.usage === void 0 ? "usage missing after ten minutes; settled at zero" : "measured usage settled by sweep" });
+			settled.push({
+				taskId: result.id,
+				totalUsd
+			});
+		} catch {
+			continue;
+		}
+	}
+	return { settled };
+}
+/**
+* Ensure the month's budget row, derive spend, and record threshold crossings
+* write-once. Delivery comes first and the stamp only lands after it, so a
+* failed notification retries on the next sweep instead of being lost; the
+* write-once stamp still keeps each threshold to one message per month.
+*/
+async function sweepBudget(stores, options) {
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	const month = options.month ?? budgetMonthOf(now().toISOString());
+	const budget = await stores.budgets.ensure({
+		factoryId: options.factoryId,
+		month,
+		limits: options.limits
+	});
+	const spendUsd = computeMonthSpendUsd(await stores.tasks.list(), month);
+	const status = budgetStatus(spendUsd, options.limits);
+	async function crossThreshold(notice, outcome) {
+		const field = notice === "warning" ? "warningAt" : "exhaustedAt";
+		if (budget.notices[field] !== void 0) return false;
+		if (options.notify !== void 0) try {
+			await options.notify({
+				outcome,
+				month,
+				spendUsd,
+				limits: options.limits
+			});
+		} catch {
+			return false;
+		}
+		return (await stores.budgets.stampNotice(month, notice)).stamped;
+	}
+	let warned = false;
+	let exhausted = false;
+	if (status === "exhausted") {
+		exhausted = await crossThreshold("exhausted", "budget_exhausted");
+		if (budget.notices.warningAt === void 0) await stores.budgets.stampNotice(month, "warning");
+	} else if (status === "warning") warned = await crossThreshold("warning", "budget_warning");
+	return {
+		month,
+		spendUsd,
+		status,
+		warned,
+		exhausted
+	};
+}
+//#endregion
+//#region src/coordination.ts
+/** Create one non-executable parent and one independently executable child per repository. */
+async function createCoordination(stores, input) {
+	const repositoryIds = [...new Set(input.repositoryIds)];
+	if (repositoryIds.length < 2) throw new Error("coordination requires at least two distinct repositories");
+	const parent = await stores.tasks.create({
+		repositoryIds,
+		kind: "coordination",
+		origin: input.signalId === void 0 ? { operator: input.operator } : { signalId: input.signalId },
+		replyTo: input.replyTo,
+		dedupeKey: input.dedupeKey
+	});
+	return {
+		parent: parent.state === "queued" ? await stores.tasks.transition(parent.id, "running", { reason: "repository-scoped child tasks created" }) : parent,
+		children: await Promise.all(repositoryIds.map((repositoryId) => stores.tasks.create({
+			repositoryIds: [repositoryId],
+			kind: "code_change",
+			origin: { parentTaskId: parent.id },
+			replyTo: input.replyTo,
+			dedupeKey: input.dedupeKey === void 0 ? void 0 : `${input.dedupeKey}:${repositoryId}`
+		})))
+	};
+}
+/** Reconcile a coordination parent from its direct children without ever dispatching the parent. */
+async function reconcileCoordination(stores, parentTaskId, options) {
+	const parent = await stores.tasks.get(parentTaskId);
+	if (parent === null) throw new RecordNotFoundError("tasks", parentTaskId);
+	if (parent.kind !== "coordination") throw new Error(`task ${parentTaskId} is ${parent.kind}, not coordination`);
+	const children = (await stores.tasks.list()).filter((task) => task.origin.parentTaskId === parentTaskId);
+	if (children.length !== parent.repositoryIds.length) return {
+		status: "pending",
+		parent,
+		children
+	};
+	if (parent.state === "succeeded" || parent.state === "failed") return {
+		status: parent.state,
+		transitioned: false,
+		parent,
+		children
+	};
+	if (children.some((child) => child.state === "failed" || child.state === "cancelled")) {
+		await options.present({
+			status: "failed",
+			parent,
+			children
+		});
+		return {
+			status: "failed",
+			transitioned: true,
+			parent: await stores.tasks.transition(parent.id, "failed", { reason: "one or more repository tasks failed" }),
+			children
+		};
+	}
+	if (!children.every((child) => child.state === "succeeded")) return {
+		status: "pending",
+		parent,
+		children
+	};
+	await options.present({
+		status: "succeeded",
+		parent,
+		children
+	});
+	await stores.tasks.transition(parent.id, "verifying", { reason: "all repository tasks succeeded" });
+	return {
+		status: "succeeded",
+		transitioned: true,
+		parent: await stores.tasks.transition(parent.id, "succeeded", { reason: "aggregate multi-repository handoff is ready" }),
+		children
+	};
+}
+//#endregion
+//#region src/schema/transitions.ts
+const taskInitialState = "queued";
+const taskTransitions = [
+	{
+		from: "queued",
+		to: "running",
+		trigger: "dependencies have a change, reservation succeeded, devbox created",
+		actor: "reconciler"
+	},
+	{
+		from: "queued",
+		to: "failed",
+		trigger: "reservation refused",
+		actor: "reconciler"
+	},
+	{
+		from: "queued",
+		to: "needs_human",
+		trigger: "kind is question",
+		actor: "system"
+	},
+	{
+		from: "queued",
+		to: "cancelled",
+		trigger: "cancel or kill",
+		actor: "operator"
+	},
+	{
+		from: "running",
+		to: "verifying",
+		trigger: "devbox task reported complete",
+		actor: "reconciler"
+	},
+	{
+		from: "running",
+		to: "queued",
+		trigger: "launch failed below attempt limit",
+		actor: "reconciler"
+	},
+	{
+		from: "running",
+		to: "failed",
+		trigger: "devbox task errored, deadline exceeded, or launch failed at attempt limit",
+		actor: "reconciler"
+	},
+	{
+		from: "running",
+		to: "needs_human",
+		trigger: "an open QuestionTask requests human input or action",
+		actor: "reconciler"
+	},
+	{
+		from: "running",
+		to: "cancelled",
+		trigger: "cancel or kill",
+		actor: "operator"
+	},
+	{
+		from: "running",
+		to: "stalled",
+		trigger: "no progress within the stall window",
+		actor: "reconciler"
+	},
+	{
+		from: "stalled",
+		to: "queued",
+		trigger: "replacement attempt below attempt limit, or operator retry",
+		actor: "reconciler"
+	},
+	{
+		from: "stalled",
+		to: "failed",
+		trigger: "attempt limit exhausted",
+		actor: "reconciler"
+	},
+	{
+		from: "stalled",
+		to: "cancelled",
+		trigger: "cancel or kill",
+		actor: "operator"
+	},
+	{
+		from: "verifying",
+		to: "succeeded",
+		trigger: "kind criterion true",
+		actor: "reconciler"
+	},
+	{
+		from: "verifying",
+		to: "running",
+		trigger: "verification failed below attempt limit",
+		actor: "reconciler"
+	},
+	{
+		from: "verifying",
+		to: "failed",
+		trigger: "verification failed at attempt limit",
+		actor: "reconciler"
+	},
+	{
+		from: "verifying",
+		to: "cancelled",
+		trigger: "cancel or kill",
+		actor: "operator"
+	},
+	{
+		from: "needs_human",
+		to: "succeeded",
+		trigger: "question answered",
+		actor: "operator"
+	},
+	{
+		from: "needs_human",
+		to: "queued",
+		trigger: "operator retry",
+		actor: "operator"
+	},
+	{
+		from: "needs_human",
+		to: "cancelled",
+		trigger: "cancel or kill",
+		actor: "operator"
+	},
+	{
+		from: "failed",
+		to: "queued",
+		trigger: "operator retry",
+		actor: "operator"
+	}
+];
+const changeInitialState = "verifying";
+const changeTransitions = [
+	{
+		from: "verifying",
+		to: "ready",
+		trigger: "configured verification policy completed, risk and confidence written",
+		actor: "reconciler"
+	},
+	{
+		from: "verifying",
+		to: "closed",
+		trigger: "verification failed at attempt limit or pr closed upstream",
+		actor: "reconciler"
+	},
+	{
+		from: "ready",
+		to: "merged",
+		trigger: "pr merged on github",
+		actor: "webhook"
+	},
+	{
+		from: "ready",
+		to: "closed",
+		trigger: "pr closed without merge",
+		actor: "webhook"
+	},
+	{
+		from: "merged",
+		to: "deployed",
+		trigger: "production deployment ready containing the merge sha",
+		actor: "webhook"
+	},
+	{
+		from: "deployed",
+		to: "rolled_out",
+		trigger: "no flag, or flag ramped to full and held",
+		actor: "foreman"
+	},
+	{
+		from: "deployed",
+		to: "rolled_back",
+		trigger: "rollback rule crossed",
+		actor: "foreman"
+	},
+	{
+		from: "rolled_out",
+		to: "rolled_back",
+		trigger: "rollback rule crossed or flag flipped off",
+		actor: "foreman"
+	},
+	{
+		from: "rolled_back",
+		to: "deployed",
+		trigger: "human retried the ramp",
+		actor: "human"
+	}
+];
+const signalInitialOutcome = "pending";
+const signalOutcomeTransitions = [
+	{
+		from: "pending",
+		to: "accepted",
+		trigger: "classified as actionable",
+		actor: "reconciler"
+	},
+	{
+		from: "pending",
+		to: "duplicate",
+		trigger: "classified as duplicate",
+		actor: "reconciler"
+	},
+	{
+		from: "pending",
+		to: "unactionable",
+		trigger: "classified as unactionable",
+		actor: "reconciler"
+	},
+	{
+		from: "pending",
+		to: "low_confidence",
+		trigger: "classified below confidence threshold",
+		actor: "reconciler"
+	},
+	{
+		from: "pending",
+		to: "ignored",
+		trigger: "classified as ignorable",
+		actor: "reconciler"
+	}
+];
+function isTransitionAllowed(transitions, from, to) {
+	return transitions.some((transition) => transition.from === from && transition.to === to);
+}
+function legalNextStates(transitions, from) {
+	return [...new Set(transitions.filter((transition) => transition.from === from).map((t) => t.to))];
+}
+var InvalidTransitionError = class extends Error {
+	from;
+	to;
+	legalNextStates;
+	constructor(from, to, legal) {
+		super(legal.length > 0 ? `invalid transition from "${from}" to "${to}"; legal next states: ${legal.map((state) => `"${state}"`).join(", ")}` : `invalid transition from "${from}" to "${to}"; "${from}" is terminal`);
+		this.name = "InvalidTransitionError";
+		this.from = from;
+		this.to = to;
+		this.legalNextStates = legal;
+	}
+};
+function assertTransition(transitions, from, to) {
+	if (!isTransitionAllowed(transitions, from, to)) throw new InvalidTransitionError(from, to, legalNextStates(transitions, from));
+}
+function terminalStates(transitions) {
+	const states = /* @__PURE__ */ new Set();
+	for (const transition of transitions) {
+		states.add(transition.from);
+		states.add(transition.to);
+	}
+	return [...states].filter((state) => !transitions.some((transition) => transition.from === state));
+}
+//#endregion
+//#region src/dispatch.ts
+var DispatchRefusedError = class extends Error {
+	taskId;
+	reason;
+	constructor(taskId, reason) {
+		super(`dispatch of "${taskId}" refused: ${reason}`);
+		this.name = "DispatchRefusedError";
+		this.taskId = taskId;
+		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;
+	}
+};
+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, taskId, options) {
+	const task = await stores.tasks.get(taskId);
+	if (task === null) throw new RecordNotFoundError("tasks", taskId);
+	if (task.kind === "question") throw new DispatchRefusedError(taskId, "question tasks are answered, not dispatched");
+	if (task.kind === "coordination") throw new DispatchRefusedError(taskId, "coordination tasks are reconciled, not dispatched");
+	if (!taskExecutionRepositoryIdsSchema.safeParse(task.repositoryIds).success) throw new DispatchRefusedError(taskId, "task execution requires exactly one repository");
+	if (task.approval === "required") throw new DispatchRefusedError(taskId, "awaiting human approval");
+	if (task.approval === "denied") throw new DispatchRefusedError(taskId, "approval was denied");
+	for (const dependencyId of task.dependsOn ?? []) {
+		const dependency = await stores.tasks.get(dependencyId);
+		if (dependency === null) throw new DispatchRefusedError(taskId, `dependency "${dependencyId}" does not exist`);
+		if (dependency.changeId === void 0) throw new DispatchRefusedError(taskId, `dependency "${dependencyId}" has not produced a change`);
+	}
+	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 spendUsd = computeMonthSpendUsd((await stores.tasks.list()).map((row) => row.id === taskId ? {
+			...row,
+			reservedUsd: void 0
+		} : row), 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, "another dispatcher took the task");
+				throw error;
+			}
+			if (task.repositoryIds !== void 0) 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", reservation === void 0 ? void 0 : { patch: {
+		reservedUsd: reservation.reservedUsd,
+		reservedAt: reservation.reservedAt
+	} });
+	let execution;
+	try {
+		execution = await options.launch(running);
+	} catch (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 }).catch(() => void 0);
+			if (running.repositoryIds !== void 0) await stores.receipts.append({
+				repositoryIds: running.repositoryIds,
+				taskId,
+				kind: "task",
+				state: "launch_retry",
+				reason: retryReason,
+				dedupeKey: `task:${taskId}:launch_retry:${running.attempt}`
+			}).catch(() => void 0);
+		} else await stores.tasks.transition(taskId, "failed", { reason: `launch failed after ${running.attempt} attempts: ${reason}` }).catch(() => void 0);
+		throw error;
+	}
+	if (execution === void 0) return running;
+	return stores.tasks.recordExecution(taskId, execution).catch(() => running);
+}
+//#endregion
+//#region src/schema/change.ts
+const levelSchema = z.enum([
+	"low",
+	"medium",
+	"high"
+]);
+const changeStateSchema = z.enum([
+	"verifying",
+	"ready",
+	"merged",
+	"deployed",
+	"rolled_out",
+	"rolled_back",
+	"closed"
+]);
+const postMergeStates = [
+	"merged",
+	"deployed",
+	"rolled_out",
+	"rolled_back"
+];
+const changeEvidenceSchema = z.strictObject({
+	reproVerified: z.boolean(),
+	testsAdded: z.number().int().min(0),
+	checksGreen: z.boolean(),
+	attackPassed: z.boolean(),
+	scopeMatches: z.boolean(),
+	previewUrl: z.url().optional()
+});
+const changeSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: changeIdSchema,
+	repositoryId: repositoryIdSchema,
+	taskId: taskIdSchema.optional(),
+	groupId: taskIdSchema.optional(),
+	prNumber: z.number().int().min(1),
+	prUrl: z.url(),
+	author: z.string().min(1),
+	risk: levelSchema,
+	confidence: levelSchema,
+	evidence: changeEvidenceSchema,
+	state: changeStateSchema,
+	mergeSha: z.string().regex(/^[0-9a-f]{40}$/).optional().describe("Merge commit sha recorded when the pull request merges, matched against production deployments."),
+	decidedBy: z.string().min(1).optional(),
+	createdAt: isoDateTimeSchema,
+	updatedAt: isoDateTimeSchema
+}).superRefine((change, ctx) => {
+	if (postMergeStates.includes(change.state) && change.decidedBy === void 0) ctx.addIssue({
+		code: "custom",
+		path: ["decidedBy"],
+		message: `${change.state} changes require decidedBy`
+	});
+});
+//#endregion
+export { budgetStatus as C, sweepBudget as D, deriveFactoryId as E, sweepSettlements as O, budgetMonthOf as S, computeMonthSpendUsd as T, taskInitialState as _, BudgetExhaustedError as a, createCoordination as b, dispatchTask as c, changeInitialState as d, changeTransitions as f, signalOutcomeTransitions as g, signalInitialOutcome as h, levelSchema as i, InvalidTransitionError as l, legalNextStates as m, changeSchema as n, DEFAULT_MAX_LAUNCH_ATTEMPTS as o, isTransitionAllowed as p, changeStateSchema as r, DispatchRefusedError as s, changeEvidenceSchema as t, assertTransition as u, taskTransitions as v, canReserve as w, reconcileCoordination as x, terminalStates as y };
+
+//# sourceMappingURL=change-CzEAoFVE.mjs.map