@vercel/factory 0.0.13 → 0.0.14

package/dist/engine-WaUM2cGA.mjs

@@ -0,0 +1,1068 @@
+import { a as receiptIdSchema, c as signalIdSchema, d as isoDateTimeSchema, f as replyToSchema, h as vocabularySchema, i as outboxIdSchema, l as taskIdSchema, m as usdSchema, n as changeIdSchema, o as repositoryIdSchema, p as schemaVersionSchema, s as repositoryIdsSchema, t as answerIdSchema } from "./id-BLIkCVue.mjs";
+import { i as standardTaskKinds, n as executionReferenceSchema, u as taskSchema } from "./task-CcOyOJ3k.mjs";
+import { _ as taskInitialState, d as changeInitialState, f as changeTransitions, g as signalOutcomeTransitions, l as InvalidTransitionError, m as legalNextStates, n as changeSchema, u as assertTransition, v as taskTransitions } from "./change-D2U6v7Ek.mjs";
+import { n as RecordNotFoundError, r as VersionConflictError, t as RecordExistsError } from "./driver-Bbd25rNM.mjs";
+import { i as repositorySchema, r as budgetSchema } from "./budget-DzSiIA4t.mjs";
+import { t as communicationEventSchema } from "./communication-Kd9nU5RP.mjs";
+import { z } from "zod";
+import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+//#region src/schema/answer.ts
+const answerEventSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: answerIdSchema,
+	questionTaskId: taskIdSchema,
+	parentTaskId: taskIdSchema.optional(),
+	repositoryIds: repositoryIdsSchema,
+	replyTo: replyToSchema,
+	question: z.string().min(1),
+	answer: z.string().min(1).max(4e3),
+	answeredBy: z.string().min(1),
+	recordedAt: isoDateTimeSchema
+});
+//#endregion
+//#region src/schema/receipt.ts
+/** States the engine writes on transitions. Any vocabulary value is valid. */
+const standardReceiptStates = [
+	"approved",
+	"rejected",
+	"queued",
+	"dispatched",
+	"stalled",
+	"succeeded",
+	"failed",
+	"needs_human",
+	"cancelled",
+	"settled",
+	"verifying",
+	"ready",
+	"merged",
+	"deployed",
+	"rolled_out",
+	"rolled_back"
+];
+/** Phases the standard loop uses. Any vocabulary value is valid. */
+const standardReceiptPhases = [
+	"approval",
+	"budget",
+	"dispatch",
+	"implementation",
+	"verification",
+	"pull_request",
+	"cleanup"
+];
+/** Kinds the standard loop writes: the standard task kinds plus "change". */
+const standardReceiptKinds = [...standardTaskKinds, "change"];
+const receiptStateSchema = vocabularySchema.describe("What happened, e.g. dispatched, settled, merged, or a custom event name.");
+const receiptPhaseSchema = vocabularySchema.describe("Where in the process it happened, e.g. dispatch or verification.");
+const receiptKindSchema = vocabularySchema.describe("What the receipt is about: a task kind, change, or a custom kind.");
+const costSchema = z.strictObject({ totalUsd: usdSchema });
+const receiptSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	receiptId: receiptIdSchema,
+	repositoryIds: repositoryIdsSchema.describe("Repositories the recorded event concerns."),
+	taskId: taskIdSchema.optional(),
+	changeId: changeIdSchema.optional(),
+	kind: receiptKindSchema,
+	state: receiptStateSchema,
+	phase: receiptPhaseSchema.optional(),
+	reason: z.string().min(1).max(2e3).optional().describe("Why it happened. Scrubbed and truncated; never secrets."),
+	attempt: z.number().int().min(1).describe("Attempt the event belongs to."),
+	cost: costSchema.optional().describe("Measured cost. Settled receipts only."),
+	decidedBy: z.string().min(1).optional().describe("Human who made the decision. Change and approval receipts only."),
+	recordedAt: isoDateTimeSchema
+}).superRefine((receipt, ctx) => {
+	if (receipt.state === "settled" && receipt.cost === void 0) ctx.addIssue({
+		code: "custom",
+		path: ["cost"],
+		message: "settled receipts require cost"
+	});
+	if (receipt.state !== "settled" && receipt.cost !== void 0) ctx.addIssue({
+		code: "custom",
+		path: ["cost"],
+		message: "cost is only valid on settled receipts"
+	});
+	if (receipt.decidedBy !== void 0 && receipt.kind !== "change" && receipt.state !== "approved" && receipt.state !== "rejected") ctx.addIssue({
+		code: "custom",
+		path: ["decidedBy"],
+		message: "decidedBy is only valid on change and approval receipts"
+	});
+});
+//#endregion
+//#region src/schema/outbox.ts
+const outboxStateSchema = z.enum([
+	"pending",
+	"delivering",
+	"delivered"
+]).describe("Durable connector delivery state.");
+const outboxMessageSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: outboxIdSchema,
+	event: communicationEventSchema.describe("Immutable provider-neutral delivery payload."),
+	state: outboxStateSchema,
+	attempt: z.number().int().nonnegative(),
+	availableAt: isoDateTimeSchema,
+	leaseUntil: isoDateTimeSchema.optional(),
+	deliveredAt: isoDateTimeSchema.optional(),
+	lastError: z.string().min(1).max(2e3).optional(),
+	createdAt: isoDateTimeSchema,
+	updatedAt: isoDateTimeSchema
+});
+const outboxQueueSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: z.string().regex(/^communication-[0-9a-f]$/u),
+	messages: z.array(outboxMessageSchema),
+	updatedAt: isoDateTimeSchema
+});
+//#endregion
+//#region src/schema/signal.ts
+/** Sources used by the standard connectors. Any vocabulary value is valid. */
+const standardSignalSources = [
+	"github_issue",
+	"github_pr",
+	"github_pr_comment",
+	"slack",
+	"human",
+	"github_ci_failure",
+	"vercel_deploy_failure",
+	"security_scan",
+	"investigation",
+	"api"
+];
+const signalSourceSchema = vocabularySchema.describe("What produced the signal, e.g. github_issue or a custom connector's own name.");
+const signalOutcomeSchema = z.enum([
+	"pending",
+	"accepted",
+	"duplicate",
+	"unactionable",
+	"low_confidence",
+	"ignored"
+]).describe("Triage outcome. A signal starts pending and is decided exactly once.");
+const signalSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: signalIdSchema.describe("Signal id, derived from source and deliveryId."),
+	repositoryId: repositoryIdSchema.describe("Repository the signal is about."),
+	source: signalSourceSchema,
+	deliveryId: z.string().min(1).describe("Provider idempotency key; a redelivered event maps to the same signal."),
+	replyTo: replyToSchema,
+	payload: z.unknown().describe("Provider-shaped payload. Untrusted data, never instructions."),
+	receivedAt: isoDateTimeSchema,
+	outcome: signalOutcomeSchema,
+	detail: z.string().min(1).optional().describe("Outcome nuance, e.g. severity when accepted or the duplicate-of signal id."),
+	reason: z.string().min(1).optional().describe("Why the outcome was chosen."),
+	decidedAt: isoDateTimeSchema.optional()
+}).superRefine((signal, ctx) => {
+	if (signal.outcome === "pending" && signal.decidedAt !== void 0) ctx.addIssue({
+		code: "custom",
+		path: ["decidedAt"],
+		message: "pending signals must not carry decidedAt"
+	});
+	if (signal.outcome !== "pending" && signal.decidedAt === void 0) ctx.addIssue({
+		code: "custom",
+		path: ["decidedAt"],
+		message: "decided signals require decidedAt"
+	});
+});
+//#endregion
+//#region src/schema/session.ts
+const agentSessionIdSchema = z.string().regex(/^ses_[a-z0-9]{6,64}$/u).describe("Stable Factory interaction ID; independent of provider session IDs.");
+const agentSessionSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: agentSessionIdSchema,
+	owner: z.string().min(1).describe("Authenticated principal owning this interaction."),
+	agent: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/u).describe("Selected application agent."),
+	repositoryId: repositoryIdSchema.optional().describe("Configured repository selected for this interaction."),
+	routeId: z.string().min(1).optional().describe("Declared workflow route for specialist work."),
+	message: z.string().min(1).max(16e3).describe("Initial request, retained for idempotent admission and recovery."),
+	changeId: changeIdSchema.optional().describe("Existing change selected for this work."),
+	taskId: taskIdSchema.optional().describe("Workflow-owned task; its execution reference is authoritative."),
+	execution: executionReferenceSchema.optional().describe("Provider reference for taskless conversations only."),
+	notifications: z.array(communicationEventSchema).default([]).describe("Durable connector deliveries, deduplicated by eventId."),
+	createdAt: isoDateTimeSchema
+}).refine((session) => session.taskId === void 0 || session.execution === void 0, "A session binds either a task or a conversation execution");
+//#endregion
+//#region src/store/engine.ts
+/** An approval decision that does not apply to the task's current approval or state. */
+var ApprovalError = class extends Error {
+	taskId;
+	reason;
+	constructor(taskId, reason) {
+		super(`approval decision on "${taskId}" refused: ${reason}`);
+		this.name = "ApprovalError";
+		this.taskId = taskId;
+		this.reason = reason;
+	}
+};
+/** A settlement that does not apply to the task's current state. */
+var SettlementError = class extends Error {
+	taskId;
+	reason;
+	constructor(taskId, reason) {
+		super(`settlement on "${taskId}" refused: ${reason}`);
+		this.name = "SettlementError";
+		this.taskId = taskId;
+		this.reason = reason;
+	}
+};
+var ChangeAssociationError = class extends Error {
+	taskId;
+	repositoryId;
+	reason;
+	constructor(taskId, repositoryId, reason) {
+		super(`change for task "${taskId}" refused: ${reason}`);
+		this.name = "ChangeAssociationError";
+		this.taskId = taskId;
+		this.repositoryId = repositoryId;
+		this.reason = reason;
+	}
+};
+var OutboxEventConflictError = class extends Error {
+	constructor(eventId) {
+		super(`outbox event "${eventId}" was reused with different content`);
+		this.name = "OutboxEventConflictError";
+	}
+};
+var AnswerEventConflictError = class extends Error {
+	constructor(questionTaskId) {
+		super(`question "${questionTaskId}" already has a different answer event`);
+		this.name = "AnswerEventConflictError";
+	}
+};
+var SessionConflictError = class extends Error {};
+function sameStoredValue(left, right) {
+	return isDeepStrictEqual(JSON.parse(JSON.stringify(left)), JSON.parse(JSON.stringify(right)));
+}
+const taskReceiptStates = {
+	queued: "queued",
+	running: "dispatched",
+	stalled: "stalled",
+	succeeded: "succeeded",
+	failed: "failed",
+	needs_human: "needs_human",
+	cancelled: "cancelled"
+};
+const changeReceiptStates = {
+	verifying: "verifying",
+	ready: "ready",
+	merged: "merged",
+	deployed: "deployed",
+	rolled_out: "rolled_out",
+	rolled_back: "rolled_back"
+};
+function randomId(prefix) {
+	return `${prefix}_${randomUUID().replaceAll("-", "")}`;
+}
+function derivedId(prefix, key) {
+	return `${prefix}_${createHash("sha256").update(key).digest("hex").slice(0, 32)}`;
+}
+function bumpsAttempt(from, to) {
+	return to === "queued" || from === "verifying" && to === "running";
+}
+const emptyUsage = {
+	costUsd: 0,
+	inputTokens: 0,
+	outputTokens: 0,
+	cacheReadTokens: 0,
+	cacheWriteTokens: 0,
+	steps: {}
+};
+const unverifiedEvidence = {
+	reproVerified: false,
+	testsAdded: 0,
+	checksGreen: false,
+	attackPassed: false,
+	scopeMatches: false
+};
+function addUsd(a, b) {
+	return (Math.round(a * 1e6) + Math.round(b * 1e6)) / 1e6;
+}
+function createStores(options) {
+	const { driver } = options;
+	const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+	async function read(collection, id, schema) {
+		const record = await driver.get(collection, id);
+		if (record === null) return null;
+		return {
+			value: schema.parse(record.value),
+			version: record.version
+		};
+	}
+	async function mustRead(collection, id, schema) {
+		const record = await read(collection, id, schema);
+		if (record === null) throw new RecordNotFoundError(collection, id);
+		return record;
+	}
+	async function listAll(collection, schema) {
+		return (await driver.list(collection)).map((entry) => schema.parse(entry.record.value));
+	}
+	async function insertReceipt(receiptId, receipt) {
+		const full = receiptSchema.parse({
+			...receipt,
+			schemaVersion: 1,
+			receiptId,
+			recordedAt: now()
+		});
+		try {
+			await driver.insert("receipts", receiptId, full);
+			return full;
+		} catch (error) {
+			if (error instanceof RecordExistsError) return (await mustRead("receipts", receiptId, receiptSchema)).value;
+			throw error;
+		}
+	}
+	async function appendReceipt(key, receipt) {
+		return insertReceipt(derivedId("rcpt", key), receipt);
+	}
+	const stores = {
+		driverName: driver.name,
+		sessions: {
+			async create({ operationId, ...input }) {
+				if (operationId.trim().length === 0 || operationId.length > 200) throw new Error("operationId must contain 1–200 characters");
+				const id = derivedId("ses", JSON.stringify([input.owner, operationId]));
+				const candidate = agentSessionSchema.parse({
+					...input,
+					id,
+					schemaVersion: 1,
+					createdAt: now()
+				});
+				try {
+					await driver.insert("sessions", id, candidate);
+					return candidate;
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) throw error;
+					const existing = (await mustRead("sessions", id, agentSessionSchema)).value;
+					const { createdAt: _at, execution: _execution, taskId: _task, notifications: _notifications, ...intent } = existing;
+					const { createdAt: _newAt, notifications: _newNotifications, ...nextIntent } = candidate;
+					if (!sameStoredValue(intent, nextIntent)) throw new SessionConflictError("Session operationId was reused with different input");
+					return existing;
+				}
+			},
+			async get(id) {
+				return (await read("sessions", id, agentSessionSchema))?.value ?? null;
+			},
+			list() {
+				return listAll("sessions", agentSessionSchema);
+			},
+			async bind(id, reference) {
+				for (;;) {
+					const existing = await mustRead("sessions", id, agentSessionSchema);
+					if ("taskId" in reference) {
+						const task = (await mustRead("tasks", reference.taskId, taskSchema)).value;
+						if (task.origin.operator !== existing.value.owner || task.replyTo.channel !== "api" || task.replyTo.address !== id || task.repositoryIds[0] !== existing.value.repositoryId) throw new SessionConflictError("Task does not belong to this session");
+					}
+					const previous = existing.value.taskId === void 0 ? existing.value.execution === void 0 ? void 0 : { execution: existing.value.execution } : { taskId: existing.value.taskId };
+					if (previous !== void 0) {
+						if (!sameStoredValue(previous, reference)) throw new SessionConflictError("Session execution binding cannot be replaced");
+						return existing.value;
+					}
+					const next = agentSessionSchema.parse({
+						...existing.value,
+						...reference
+					});
+					try {
+						await driver.update("sessions", id, next, existing.version);
+						return next;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async notify(input) {
+				const event = communicationEventSchema.parse(input);
+				if (event.replyTo.channel !== "api") throw new SessionConflictError("Expected an API notification");
+				for (;;) {
+					const record = await mustRead("sessions", event.replyTo.address, agentSessionSchema);
+					const existing = record.value.notifications.find((item) => item.eventId === event.eventId);
+					if (existing !== void 0) {
+						if (!sameStoredValue(existing, event)) throw new SessionConflictError("Notification eventId was reused");
+						return;
+					}
+					const next = agentSessionSchema.parse({
+						...record.value,
+						notifications: [...record.value.notifications, event]
+					});
+					try {
+						await driver.update("sessions", next.id, next, record.version);
+						return;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			}
+		},
+		repositories: {
+			async put(repository) {
+				const parsed = repositorySchema.parse(repository);
+				const existing = await read("repositories", parsed.id, repositorySchema);
+				if (existing === null) await driver.insert("repositories", parsed.id, parsed);
+				else await driver.update("repositories", parsed.id, parsed, existing.version);
+				return parsed;
+			},
+			async get(id) {
+				const record = await read("repositories", id, repositorySchema);
+				return record === null ? null : record.value;
+			},
+			list() {
+				return listAll("repositories", repositorySchema);
+			}
+		},
+		signals: {
+			async create(input) {
+				const id = derivedId("sig", `${input.source}:${input.deliveryId}`);
+				const signal = signalSchema.parse({
+					schemaVersion: 1,
+					id,
+					repositoryId: input.repositoryId,
+					source: input.source,
+					deliveryId: input.deliveryId,
+					replyTo: input.replyTo,
+					payload: input.payload,
+					receivedAt: now(),
+					outcome: "pending"
+				});
+				try {
+					await driver.insert("signals", id, signal);
+					return signal;
+				} catch (error) {
+					if (error instanceof RecordExistsError) return (await mustRead("signals", id, signalSchema)).value;
+					throw error;
+				}
+			},
+			async get(id) {
+				const record = await read("signals", id, signalSchema);
+				return record === null ? null : record.value;
+			},
+			async decide(id, outcome, decideOptions = {}) {
+				const existing = await mustRead("signals", id, signalSchema);
+				assertTransition(signalOutcomeTransitions, existing.value.outcome, outcome);
+				const next = signalSchema.parse({
+					...existing.value,
+					outcome,
+					detail: decideOptions.detail,
+					reason: decideOptions.reason,
+					decidedAt: now()
+				});
+				await driver.update("signals", id, next, existing.version);
+				return next;
+			},
+			list() {
+				return listAll("signals", signalSchema);
+			}
+		},
+		tasks: {
+			async create(input) {
+				const timestamp = now();
+				const id = input.dedupeKey === void 0 ? randomId("task") : derivedId("task", input.dedupeKey);
+				const task = taskSchema.parse({
+					schemaVersion: 1,
+					id,
+					repositoryIds: input.repositoryIds,
+					kind: input.kind,
+					area: input.area,
+					state: taskInitialState,
+					approval: input.approval,
+					origin: input.origin,
+					dependsOn: input.dependsOn,
+					replyTo: input.replyTo,
+					attempt: 1,
+					question: input.question,
+					changeId: input.changeId,
+					createdAt: timestamp,
+					updatedAt: timestamp
+				});
+				try {
+					await driver.insert("tasks", task.id, task);
+					return task;
+				} catch (error) {
+					if (input.dedupeKey !== void 0 && error instanceof RecordExistsError) return (await mustRead("tasks", task.id, taskSchema)).value;
+					throw error;
+				}
+			},
+			async approve(id, decision) {
+				const existing = await mustRead("tasks", id, taskSchema);
+				const task = existing.value;
+				if (task.approval !== "required") throw new ApprovalError(id, `approval is ${task.approval ?? "not required"}`);
+				if (task.state !== "queued") throw new ApprovalError(id, `task is ${task.state}, not queued`);
+				const next = taskSchema.parse({
+					...task,
+					approval: "granted",
+					updatedAt: now()
+				});
+				if (next.repositoryIds !== void 0) await appendReceipt(`task:${id}:approved:${next.attempt}`, {
+					repositoryIds: next.repositoryIds,
+					taskId: id,
+					kind: next.kind,
+					state: "approved",
+					phase: "approval",
+					reason: decision.reason,
+					attempt: next.attempt,
+					decidedBy: decision.by
+				});
+				await driver.update("tasks", id, next, existing.version);
+				return next;
+			},
+			async reject(id, decision) {
+				const existing = await mustRead("tasks", id, taskSchema);
+				const task = existing.value;
+				if (task.approval !== "required") throw new ApprovalError(id, `approval is ${task.approval ?? "not required"}`);
+				if (task.state !== "queued") throw new ApprovalError(id, `task is ${task.state}, not queued`);
+				const next = taskSchema.parse({
+					...task,
+					approval: "denied",
+					state: "cancelled",
+					updatedAt: now()
+				});
+				if (next.repositoryIds !== void 0) {
+					await appendReceipt(`task:${id}:rejected:${next.attempt}`, {
+						repositoryIds: next.repositoryIds,
+						taskId: id,
+						kind: next.kind,
+						state: "rejected",
+						phase: "approval",
+						reason: decision.reason,
+						attempt: next.attempt,
+						decidedBy: decision.by
+					});
+					await appendReceipt(`task:${id}:cancelled:${next.attempt}`, {
+						repositoryIds: next.repositoryIds,
+						taskId: id,
+						kind: next.kind,
+						state: "cancelled",
+						reason: decision.reason ?? `rejected by ${decision.by}`,
+						attempt: next.attempt
+					});
+				}
+				await driver.update("tasks", id, next, existing.version);
+				return next;
+			},
+			async recordExecution(id, execution) {
+				const existing = await mustRead("tasks", id, taskSchema);
+				const task = existing.value;
+				if (task.state !== "running") throw new InvalidTransitionError(task.state, "running", legalNextStates(taskTransitions, task.state));
+				const timestamp = now();
+				const next = taskSchema.parse({
+					...task,
+					execution,
+					lastProgressAt: timestamp,
+					updatedAt: timestamp
+				});
+				await driver.update("tasks", id, next, existing.version);
+				return next;
+			},
+			async recordUsage(id, step) {
+				for (;;) {
+					const existing = await mustRead("tasks", id, taskSchema);
+					const task = existing.value;
+					const usage = task.usage ?? emptyUsage;
+					const recordedIndex = usage.steps[step.turnId];
+					if (recordedIndex !== void 0 && step.stepIndex <= recordedIndex) return task;
+					const timestamp = now();
+					const next = taskSchema.parse({
+						...task,
+						lastProgressAt: timestamp,
+						usage: {
+							costUsd: addUsd(usage.costUsd, step.costUsd ?? 0),
+							inputTokens: usage.inputTokens + (step.inputTokens ?? 0),
+							outputTokens: usage.outputTokens + (step.outputTokens ?? 0),
+							cacheReadTokens: usage.cacheReadTokens + (step.cacheReadTokens ?? 0),
+							cacheWriteTokens: usage.cacheWriteTokens + (step.cacheWriteTokens ?? 0),
+							steps: {
+								...usage.steps,
+								[step.turnId]: step.stepIndex
+							}
+						},
+						updatedAt: timestamp
+					});
+					try {
+						await driver.update("tasks", id, next, existing.version);
+						return next;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async settle(id, cost, settleOptions = {}) {
+				const existing = await mustRead("tasks", id, taskSchema);
+				const task = existing.value;
+				if (task.settledUsd !== void 0) return task;
+				if (task.state !== "succeeded" && task.state !== "failed" && task.state !== "cancelled") throw new SettlementError(id, `task is ${task.state}, not terminal`);
+				const validated = costSchema.parse(cost);
+				const normalized = { totalUsd: Math.round(validated.totalUsd * 1e6) / 1e6 };
+				let recorded = normalized;
+				if (task.repositoryIds !== void 0) recorded = (await appendReceipt(`task:${id}:settled:${task.attempt}`, {
+					repositoryIds: task.repositoryIds,
+					taskId: id,
+					changeId: task.changeId,
+					kind: task.kind,
+					state: "settled",
+					phase: "budget",
+					reason: settleOptions.reason,
+					attempt: task.attempt,
+					cost: normalized
+				})).cost ?? normalized;
+				const next = taskSchema.parse({
+					...task,
+					settledUsd: recorded.totalUsd,
+					updatedAt: now()
+				});
+				await driver.update("tasks", id, next, existing.version);
+				return next;
+			},
+			async get(id) {
+				const record = await read("tasks", id, taskSchema);
+				return record === null ? null : record.value;
+			},
+			async answerQuestion(input) {
+				const question = await mustRead("tasks", input.questionTaskId, taskSchema);
+				if (question.value.kind !== "question" || question.value.question === void 0) throw new Error(`task ${input.questionTaskId} is not a question`);
+				if (question.value.state !== "needs_human" && question.value.state !== "succeeded") throw new Error(`question task ${input.questionTaskId} is ${question.value.state}, not waiting`);
+				const questionDetails = question.value.question;
+				const id = answerIdSchema.parse(derivedId("ans", input.questionTaskId));
+				const candidate = answerEventSchema.parse({
+					schemaVersion: 1,
+					id,
+					questionTaskId: input.questionTaskId,
+					parentTaskId: question.value.origin.parentTaskId,
+					repositoryIds: question.value.repositoryIds,
+					replyTo: question.value.replyTo,
+					question: questionDetails.text,
+					answer: input.answer,
+					answeredBy: input.answeredBy,
+					recordedAt: now()
+				});
+				let answerEvent = candidate;
+				try {
+					await driver.insert("answers", id, candidate);
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) throw error;
+					const existing = await mustRead("answers", id, answerEventSchema);
+					const { recordedAt: _existingAt, ...existingIntent } = existing.value;
+					const { recordedAt: _candidateAt, ...candidateIntent } = candidate;
+					if (!isDeepStrictEqual(existingIntent, candidateIntent)) throw new AnswerEventConflictError(input.questionTaskId);
+					answerEvent = existing.value;
+				}
+				let parentTask = null;
+				if (answerEvent.parentTaskId !== void 0) {
+					parentTask = await stores.tasks.get(answerEvent.parentTaskId);
+					if (parentTask === null) throw new Error(`parent task ${answerEvent.parentTaskId} does not exist`);
+					for (;;) {
+						const parent = await mustRead("tasks", answerEvent.parentTaskId, taskSchema);
+						if (parent.value.answerEventIds?.includes(answerEvent.id) === true) {
+							parentTask = parent.value;
+							break;
+						}
+						const projected = taskSchema.parse({
+							...parent.value,
+							answerEventIds: [...parent.value.answerEventIds ?? [], answerEvent.id],
+							updatedAt: now()
+						});
+						try {
+							await driver.update("tasks", parent.value.id, projected, parent.version);
+							parentTask = projected;
+							break;
+						} catch (error) {
+							if (!(error instanceof VersionConflictError)) throw error;
+						}
+					}
+					if (parentTask.state === "needs_human") parentTask = await stores.tasks.transition(parentTask.id, "queued", { reason: `question ${answerEvent.questionTaskId} answered by ${answerEvent.answeredBy}` });
+				}
+				let questionTask = await mustRead("tasks", input.questionTaskId, taskSchema).then((record) => record.value);
+				if (questionTask.state === "needs_human") questionTask = await stores.tasks.transition(questionTask.id, "succeeded", {
+					patch: { question: {
+						...questionDetails,
+						answer: answerEvent.answer,
+						answeredBy: answerEvent.answeredBy
+					} },
+					reason: "question answered through Foreman"
+				});
+				else if (questionTask.state !== "succeeded" || questionTask.question?.answer !== answerEvent.answer || questionTask.question.answeredBy !== answerEvent.answeredBy) throw new Error(`question task ${questionTask.id} is ${questionTask.state}, not waiting`);
+				return {
+					answerEvent,
+					questionTask,
+					parentTask
+				};
+			},
+			async transition(id, to, transitionOptions = {}) {
+				if (transitionOptions.patch !== void 0 && "settledUsd" in transitionOptions.patch) throw new SettlementError(id, "settledUsd is set only by settle, not a transition");
+				if (transitionOptions.patch !== void 0 && "usage" in transitionOptions.patch) throw new SettlementError(id, "usage is set only by recordUsage, not a transition");
+				const existing = await mustRead("tasks", id, taskSchema);
+				if (transitionOptions.expectFrom !== void 0 && existing.value.state !== transitionOptions.expectFrom) throw new InvalidTransitionError(existing.value.state, to, legalNextStates(taskTransitions, existing.value.state));
+				assertTransition(taskTransitions, existing.value.state, to);
+				if (to === "needs_human" && existing.value.kind !== "question") {
+					if (transitionOptions.questionTaskId === void 0) throw new Error(`task ${id} cannot enter needs_human without a QuestionTask id`);
+					const question = await mustRead("tasks", transitionOptions.questionTaskId, taskSchema);
+					if (question.value.kind !== "question" || question.value.state !== "needs_human" || question.value.origin.parentTaskId !== id) throw new Error(`task ${id} cannot enter needs_human for question ${question.value.id}`);
+				}
+				const bumps = bumpsAttempt(existing.value.state, to);
+				const timestamp = now();
+				const { stalledAt: _stalledAt, stalledReason: _stalledReason, questionTaskId: _questionTaskId, ...cleared } = existing.value;
+				const next = taskSchema.parse({
+					...cleared,
+					...bumps ? { execution: void 0 } : {},
+					...transitionOptions.patch,
+					...to === "needs_human" && existing.value.kind !== "question" ? { questionTaskId: transitionOptions.questionTaskId } : {},
+					...to === "stalled" ? {
+						stalledAt: timestamp,
+						stalledReason: transitionOptions.reason
+					} : {},
+					...to === "running" ? { lastProgressAt: timestamp } : {},
+					state: to,
+					attempt: bumps ? existing.value.attempt + 1 : existing.value.attempt,
+					updatedAt: timestamp
+				});
+				const receiptState = taskReceiptStates[to];
+				if (receiptState !== void 0 && next.repositoryIds !== void 0) await appendReceipt(JSON.stringify([
+					"task",
+					id,
+					receiptState,
+					next.attempt,
+					next.changeId ?? null,
+					transitionOptions.reason ?? null
+				]), {
+					repositoryIds: next.repositoryIds,
+					taskId: id,
+					changeId: next.changeId,
+					kind: next.kind,
+					state: receiptState,
+					reason: transitionOptions.reason,
+					attempt: next.attempt
+				});
+				await driver.update("tasks", id, next, existing.version);
+				return next;
+			},
+			list() {
+				return listAll("tasks", taskSchema);
+			}
+		},
+		changes: {
+			async create(input) {
+				const timestamp = now();
+				const id = derivedId("chg", `${input.repositoryId}:github-pr:${input.prNumber}`);
+				const change = changeSchema.parse({
+					schemaVersion: 1,
+					id,
+					repositoryId: input.repositoryId,
+					taskId: input.taskId,
+					groupId: input.groupId,
+					prNumber: input.prNumber,
+					prUrl: input.prUrl,
+					author: input.author,
+					risk: input.risk,
+					confidence: input.confidence,
+					evidence: input.evidence,
+					state: changeInitialState,
+					createdAt: timestamp,
+					updatedAt: timestamp
+				});
+				await mustRead("repositories", change.repositoryId, repositorySchema);
+				if (change.taskId !== void 0) {
+					const task = (await mustRead("tasks", change.taskId, taskSchema)).value;
+					if (task.kind !== "code_change") throw new ChangeAssociationError(change.taskId, change.repositoryId, "changes can only be produced by code_change tasks");
+					const taskRepositoryId = task.repositoryIds[0];
+					if (taskRepositoryId !== change.repositoryId) throw new ChangeAssociationError(change.taskId, change.repositoryId, `repository "${change.repositoryId}" does not match task repository "${taskRepositoryId}"`);
+				}
+				try {
+					await driver.insert("changes", change.id, change);
+					return change;
+				} catch (error) {
+					if (error instanceof RecordExistsError) return (await mustRead("changes", change.id, changeSchema)).value;
+					throw error;
+				}
+			},
+			async get(id) {
+				const record = await read("changes", id, changeSchema);
+				return record === null ? null : record.value;
+			},
+			async transition(id, to, transitionOptions = {}) {
+				const existing = await mustRead("changes", id, changeSchema);
+				assertTransition(changeTransitions, existing.value.state, to);
+				const invalidated = existing.value.state === "ready" && to === "verifying";
+				const next = changeSchema.parse({
+					...existing.value,
+					...transitionOptions.patch,
+					...invalidated ? {
+						confidence: "low",
+						evidence: unverifiedEvidence
+					} : {},
+					state: to,
+					updatedAt: now()
+				});
+				const receiptState = changeReceiptStates[to];
+				if (receiptState !== void 0) await appendReceipt(`change:${id}:${receiptState}`, {
+					repositoryIds: [next.repositoryId],
+					taskId: next.taskId,
+					changeId: id,
+					kind: "change",
+					state: receiptState,
+					reason: transitionOptions.reason,
+					attempt: 1,
+					decidedBy: next.decidedBy
+				});
+				await driver.update("changes", id, next, existing.version);
+				return next;
+			},
+			list() {
+				return listAll("changes", changeSchema);
+			}
+		},
+		receipts: {
+			append(input) {
+				const { dedupeKey, attempt, ...fields } = input;
+				return insertReceipt(dedupeKey === void 0 ? randomId("rcpt") : derivedId("rcpt", `custom:${dedupeKey}`), {
+					...fields,
+					attempt: attempt ?? 1
+				});
+			},
+			async get(id) {
+				const record = await read("receipts", id, receiptSchema);
+				return record === null ? null : record.value;
+			},
+			list() {
+				return listAll("receipts", receiptSchema);
+			}
+		},
+		budgets: {
+			async ensure(input) {
+				const budget = budgetSchema.parse({
+					schemaVersion: 1,
+					factoryId: input.factoryId,
+					month: input.month,
+					limits: input.limits,
+					notices: {}
+				});
+				try {
+					await driver.insert("budgets", input.month, budget);
+					return budget;
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) throw error;
+				}
+				const existing = await mustRead("budgets", input.month, budgetSchema);
+				const refreshed = budgetSchema.parse({
+					...existing.value,
+					limits: input.limits
+				});
+				if (JSON.stringify(refreshed) === JSON.stringify(existing.value)) return existing.value;
+				try {
+					await driver.update("budgets", input.month, refreshed, existing.version);
+					return refreshed;
+				} catch (error) {
+					if (error instanceof VersionConflictError) return (await mustRead("budgets", input.month, budgetSchema)).value;
+					throw error;
+				}
+			},
+			async get(month) {
+				const record = await read("budgets", month, budgetSchema);
+				return record === null ? null : record.value;
+			},
+			async stampNotice(month, notice) {
+				const field = notice === "warning" ? "warningAt" : "exhaustedAt";
+				for (;;) {
+					const existing = await mustRead("budgets", month, budgetSchema);
+					if (existing.value.notices[field] !== void 0) return {
+						budget: existing.value,
+						stamped: false
+					};
+					const next = budgetSchema.parse({
+						...existing.value,
+						notices: {
+							...existing.value.notices,
+							[field]: now()
+						}
+					});
+					try {
+						await driver.update("budgets", month, next, existing.version);
+						return {
+							budget: next,
+							stamped: true
+						};
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			}
+		},
+		answers: { async get(id) {
+			return (await read("answers", id, answerEventSchema))?.value ?? null;
+		} },
+		outbox: {
+			async enqueue(input) {
+				const event = communicationEventSchema.parse(input);
+				const id = outboxIdSchema.parse(derivedId("out", event.eventId));
+				const delivered = await read("outboxDeliveries", id, outboxMessageSchema);
+				if (delivered !== null) {
+					if (!isDeepStrictEqual(delivered.value.event, event)) throw new OutboxEventConflictError(event.eventId);
+					return delivered.value;
+				}
+				const queueId = `communication-${id.slice(4, 5)}`;
+				for (;;) {
+					const existing = await read("outboxQueues", queueId, outboxQueueSchema);
+					const duplicate = existing?.value.messages.find((message) => message.id === id);
+					if (duplicate !== void 0) {
+						if (!isDeepStrictEqual(duplicate.event, event)) throw new OutboxEventConflictError(event.eventId);
+						return duplicate;
+					}
+					const timestamp = now();
+					const message = outboxMessageSchema.parse({
+						schemaVersion: 1,
+						id,
+						event,
+						state: "pending",
+						attempt: 0,
+						availableAt: timestamp,
+						createdAt: timestamp,
+						updatedAt: timestamp
+					});
+					const queue = outboxQueueSchema.parse({
+						schemaVersion: 1,
+						id: queueId,
+						messages: [...existing?.value.messages ?? [], message],
+						updatedAt: timestamp
+					});
+					try {
+						if (existing === null) await driver.insert("outboxQueues", queueId, queue);
+						else await driver.update("outboxQueues", queueId, queue, existing.version);
+						return message;
+					} catch (error) {
+						if (!(error instanceof RecordExistsError) && !(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async get(id) {
+				const delivered = await read("outboxDeliveries", id, outboxMessageSchema);
+				if (delivered !== null) return delivered.value;
+				return (await read("outboxQueues", `communication-${id.slice(4, 5)}`, outboxQueueSchema))?.value.messages.find((message) => message.id === id) ?? null;
+			},
+			async claim(id, leaseMs = 6e4) {
+				if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0) throw new Error("outbox leaseMs must be a positive safe integer");
+				const queueId = `communication-${id.slice(4, 5)}`;
+				for (;;) {
+					const queue = await mustRead("outboxQueues", queueId, outboxQueueSchema);
+					const index = queue.value.messages.findIndex((message) => message.id === id);
+					if (index < 0) return null;
+					if (await read("outboxDeliveries", id, outboxMessageSchema) !== null) {
+						const messages = queue.value.messages.filter((message) => message.id !== id);
+						try {
+							await driver.update("outboxQueues", queueId, outboxQueueSchema.parse({
+								...queue.value,
+								messages,
+								updatedAt: now()
+							}), queue.version);
+							return null;
+						} catch (error) {
+							if (!(error instanceof VersionConflictError)) throw error;
+							continue;
+						}
+					}
+					const message = queue.value.messages[index];
+					const timestamp = now();
+					if (!(message.state === "pending" && message.availableAt <= timestamp || message.state === "delivering" && message.leaseUntil !== void 0 && message.leaseUntil <= timestamp)) return null;
+					const next = outboxMessageSchema.parse({
+						...message,
+						state: "delivering",
+						attempt: message.attempt + 1,
+						leaseUntil: new Date(Date.parse(timestamp) + leaseMs).toISOString(),
+						updatedAt: timestamp
+					});
+					const messages = [...queue.value.messages];
+					messages[index] = next;
+					try {
+						await driver.update("outboxQueues", queueId, outboxQueueSchema.parse({
+							...queue.value,
+							messages,
+							updatedAt: timestamp
+						}), queue.version);
+						return next;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async retry(id, attempt, reason, delayMs) {
+				if (!Number.isSafeInteger(delayMs) || delayMs < 0) throw new Error("outbox delayMs must be a nonnegative safe integer");
+				const queueId = `communication-${id.slice(4, 5)}`;
+				for (;;) {
+					const queue = await mustRead("outboxQueues", queueId, outboxQueueSchema);
+					const index = queue.value.messages.findIndex((message) => message.id === id);
+					if (index < 0) return null;
+					const message = queue.value.messages[index];
+					if (message.state !== "delivering" || message.attempt !== attempt) return null;
+					const timestamp = now();
+					const { leaseUntil: _leaseUntil, ...leased } = message;
+					const next = outboxMessageSchema.parse({
+						...leased,
+						state: "pending",
+						availableAt: new Date(Date.parse(timestamp) + delayMs).toISOString(),
+						lastError: reason.trim().slice(0, 2e3) || "delivery failed",
+						updatedAt: timestamp
+					});
+					const messages = [...queue.value.messages];
+					messages[index] = next;
+					try {
+						await driver.update("outboxQueues", queueId, outboxQueueSchema.parse({
+							...queue.value,
+							messages,
+							updatedAt: timestamp
+						}), queue.version);
+						return next;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async complete(id, attempt) {
+				const queueId = `communication-${id.slice(4, 5)}`;
+				let delivered = await read("outboxDeliveries", id, outboxMessageSchema);
+				for (;;) {
+					const queue = await mustRead("outboxQueues", queueId, outboxQueueSchema);
+					const index = queue.value.messages.findIndex((message) => message.id === id);
+					if (index < 0) return delivered?.value ?? null;
+					const message = queue.value.messages[index];
+					const timestamp = now();
+					if (delivered === null) {
+						if (message.state !== "delivering" || message.attempt !== attempt) return null;
+						const { leaseUntil: _leaseUntil, lastError: _lastError, ...leased } = message;
+						const next = outboxMessageSchema.parse({
+							...leased,
+							state: "delivered",
+							deliveredAt: timestamp,
+							updatedAt: timestamp
+						});
+						try {
+							await driver.insert("outboxDeliveries", id, next);
+							delivered = {
+								value: next,
+								version: 1
+							};
+						} catch (error) {
+							if (!(error instanceof RecordExistsError)) throw error;
+							delivered = await mustRead("outboxDeliveries", id, outboxMessageSchema);
+							if (!isDeepStrictEqual(delivered.value.event, message.event)) throw new OutboxEventConflictError(message.event.eventId);
+						}
+					}
+					const messages = queue.value.messages.filter((candidate) => candidate.id !== id);
+					try {
+						await driver.update("outboxQueues", queueId, outboxQueueSchema.parse({
+							...queue.value,
+							messages,
+							updatedAt: timestamp
+						}), queue.version);
+						return delivered.value;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async pending(limit = 100) {
+				if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error("outbox pending limit must be a positive safe integer");
+				const queues = await Promise.all("0123456789abcdef".split("").map((shard) => read("outboxQueues", `communication-${shard}`, outboxQueueSchema)));
+				const timestamp = now();
+				return queues.flatMap((queue) => queue?.value.messages ?? []).filter((message) => message.state === "pending" && message.availableAt <= timestamp || message.state === "delivering" && message.leaseUntil !== void 0 && message.leaseUntil <= timestamp).sort((a, b) => a.createdAt.localeCompare(b.createdAt)).slice(0, limit);
+			}
+		}
+	};
+	return stores;
+}
+//#endregion
+export { standardReceiptPhases as C, standardReceiptKinds as S, answerEventSchema as T, costSchema as _, SessionConflictError as a, receiptSchema as b, agentSessionIdSchema as c, signalSchema as d, signalSourceSchema as f, outboxStateSchema as g, outboxQueueSchema as h, OutboxEventConflictError as i, agentSessionSchema as l, outboxMessageSchema as m, ApprovalError as n, SettlementError as o, standardSignalSources as p, ChangeAssociationError as r, createStores as s, AnswerEventConflictError as t, signalOutcomeSchema as u, receiptKindSchema as v, standardReceiptStates as w, receiptStateSchema as x, receiptPhaseSchema as y };
+
+//# sourceMappingURL=engine-WaUM2cGA.mjs.map