@vercel/factory 0.0.14 → 0.0.16

package/dist/store/engine.mjs

@@ -0,0 +1,2309 @@
+import { answerIdSchema, changeIdSchema, outboxIdSchema, repositoryIdsSchema, taskIdSchema } from "../schema/id.mjs";
+import { replyToSchema, usdSchema } from "../schema/common.mjs";
+import { repositorySchema } from "../schema/repository.mjs";
+import { budgetSchema } from "../schema/budget.mjs";
+import { parseAgentRouteBinding } from "../schema/agent-route.mjs";
+import { jsonValueSchema, taskWorkSchema } from "../schema/work.mjs";
+import { taskKindSchema, taskOriginSchema, taskQuestionSchema, taskSchema } from "../schema/task.mjs";
+import { InvalidTransitionError, assertTransition, changeInitialState, changeTransitions, legalNextStates, signalOutcomeTransitions, signalTriageTransitions, taskInitialState, taskTransitions } from "../schema/transitions.mjs";
+import { costSchema, receiptSchema } from "../schema/receipt.mjs";
+import { imageAttachmentSchema, imageAttachmentsSchema, imageIdSchema, imageUploadSchema } from "../image-input.mjs";
+import { transcriptSnapshotSchema } from "../schema/transcript.mjs";
+import { routeTaskWork } from "../agent-routes.mjs";
+import { RecordExistsError, RecordNotFoundError, TransientStoreError, VersionConflictError } from "./driver.mjs";
+import { answerEventSchema } from "../schema/answer.mjs";
+import { taskGraphDependenciesSchema } from "../schema/task-graph.mjs";
+import { defineTaskMessageProtocols } from "../schema/task-message.mjs";
+import { createTaskGraphStore } from "./task-graphs.mjs";
+import { createTaskMessageStore } from "./task-messages.mjs";
+import { createTaskWorkStore } from "./task-work.mjs";
+import { createTaskEffectStore } from "./task-effects.mjs";
+import { defaultTaskWorkflow, defineWorkflows } from "../workflows.mjs";
+import { createWorkNotifier } from "./work-notifications.mjs";
+import { communicationEventSchema } from "../schema/communication.mjs";
+import { agentSessionIdSchema, agentSessionSchema } from "../schema/session.mjs";
+import { externalSessionSchema, storedSessionSchema } from "../schema/stored-session.mjs";
+import { changeSchema } from "../schema/change.mjs";
+import { outboxMessageSchema, outboxQueueSchema } from "../schema/outbox.mjs";
+import { storedTaskSchema } from "../schema/stored-task.mjs";
+import { changeCatalogSchema, externalSessionCatalogSchema, sessionCatalogSchema, taskCatalogSchema, taskRouteSchema } from "../schema/catalog.mjs";
+import { questionRouteSchema } from "../schema/question-route.mjs";
+import { signalSchema } from "../schema/signal.mjs";
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+//#region src/store/engine.ts
+const storedImageSchema = imageAttachmentSchema.extend({
+	schemaVersion: z.literal(1).describe("Stored image schema version."),
+	owner: z.string().min(1).describe("Authenticated image owner."),
+	base64: imageUploadSchema.shape.base64,
+	createdAt: z.iso.datetime().describe("Image creation time.")
+}).refine((image) => {
+	const bytes = Buffer.from(image.base64, "base64");
+	if (bytes.length !== image.size || bytes.toString("base64") !== image.base64) return false;
+	if (image.mediaType === "image/png") return bytes.length >= 24 && bytes.subarray(0, 8).equals(Buffer.from([
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	]));
+	if (image.mediaType === "image/jpeg") return bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
+	return bytes.length >= 16 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP";
+}, "Image bytes do not match the declared PNG, JPEG, or WebP format");
+const storedTranscriptSchema = z.object({
+	schemaVersion: z.literal(1),
+	execution: z.object({
+		provider: z.string().min(1),
+		sessionId: z.string().min(1)
+	}),
+	snapshot: transcriptSnapshotSchema,
+	updatedAt: z.iso.datetime()
+});
+/** Error raised when uploaded image bytes, ownership, or attachment metadata is invalid. */
+var ImageInputError = class extends Error {};
+/** 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;
+	}
+};
+/** Error raised when a Task is not authorized to create or update a requested Change. */
+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;
+	}
+};
+/** Error raised when a stable outbox event ID is reused with different content. */
+var OutboxEventConflictError = class extends Error {
+	constructor(eventId) {
+		super(`outbox event "${eventId}" was reused with different content`);
+		this.name = "OutboxEventConflictError";
+	}
+};
+/** Error raised when a QuestionTask already has a different immutable answer event. */
+var AnswerEventConflictError = class extends Error {
+	constructor(questionTaskId) {
+		super(`question "${questionTaskId}" already has a different answer event`);
+		this.name = "AnswerEventConflictError";
+	}
+};
+const createTaskInputSchema = z.strictObject({
+	repositoryIds: repositoryIdsSchema,
+	kind: taskKindSchema,
+	origin: taskOriginSchema,
+	replyTo: replyToSchema,
+	dedupeKey: z.string().min(1).refine((key) => key.trim().length > 0).optional().describe("Stable key for retryable task admission; omitted for one-shot creation."),
+	area: z.string().min(1).optional(),
+	changeId: changeIdSchema.optional(),
+	question: taskQuestionSchema.optional(),
+	approval: z.literal("required").optional().describe("Require approval before execution."),
+	work: taskWorkSchema,
+	parentTaskId: taskIdSchema.optional(),
+	parentTaskAttempt: z.number().int().positive().optional(),
+	dependencies: taskGraphDependenciesSchema.optional()
+});
+/** One completed model step's usage, as eve's step.completed event carries it. */
+const stepUsageSchema = z.strictObject({
+	turnId: z.string().min(1).describe("Provider turn containing the completed step."),
+	stepIndex: z.number().int().nonnegative().describe("Nonnegative index of the completed step."),
+	costUsd: usdSchema.optional().describe("Measured cost for this step."),
+	inputTokens: z.number().int().nonnegative().optional().describe("Input tokens charged for this step."),
+	outputTokens: z.number().int().nonnegative().optional().describe("Output tokens charged for this step."),
+	cacheReadTokens: z.number().int().nonnegative().optional().describe("Cached input tokens read for this step."),
+	cacheWriteTokens: z.number().int().nonnegative().optional().describe("Input tokens written to cache for this step.")
+});
+/** Error raised when a Task operation loses its exact-attempt concurrency fence. */
+var TaskAttemptConflictError = class extends Error {
+	taskId;
+	actualAttempt;
+	expectedAttempt;
+	constructor(taskId, actualAttempt, expectedAttempt) {
+		super(`task ${taskId} is on attempt ${actualAttempt}, not ${expectedAttempt}`);
+		this.taskId = taskId;
+		this.actualAttempt = actualAttempt;
+		this.expectedAttempt = expectedAttempt;
+		this.name = "TaskAttemptConflictError";
+	}
+};
+/** Error raised when an idempotent session operation conflicts with its original intent. */
+var SessionConflictError = class extends Error {};
+function sameStoredValue(left, right) {
+	return isDeepStrictEqual(JSON.parse(JSON.stringify(left)), JSON.parse(JSON.stringify(right)));
+}
+/**
+* Whether an operator's answer matches one of the question's declared
+* closing options (trimmed, case-insensitive). The asker judged that these
+* exact replies mean no further attempt can help, so answering with one
+* resolves the parent task instead of requeuing it for identical retry.
+*/
+function isClosingAnswer(closingOptions, answer) {
+	if (closingOptions === void 0 || closingOptions.length === 0) return false;
+	const normalized = answer.trim().toLowerCase();
+	return closingOptions.some((option) => option.trim().toLowerCase() === normalized);
+}
+const taskReceiptStates = {
+	queued: "queued",
+	running: "dispatched",
+	stalled: "stalled",
+	succeeded: "succeeded",
+	failed: "failed",
+	needs_human: "needs_human",
+	cancelled: "cancelled"
+};
+function needsLifecycleCommunication(task, state, phase) {
+	if (state === "needs_human") return task.question !== void 0;
+	if (task.parentTaskId !== void 0) return false;
+	if (state === "dispatched") return phase === "retry";
+	if (state === "failed" || state === "cancelled") return true;
+	if (state !== "succeeded") return false;
+	return task.question === void 0;
+}
+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;
+}
+const TRANSIENT_RETRY_BASE_MS = 200;
+const TRANSIENT_RETRY_MAX_TOTAL_MS = 1e4;
+/**
+* Backs off and returns the next attempt count, or rethrows `error` once
+* the bound (attempts or total elapsed time) is reached.
+*/
+async function nextTransientRetry(error, attempt, startedAt) {
+	const nextDelayMs = TRANSIENT_RETRY_BASE_MS * 2 ** attempt;
+	if (attempt >= 4 || Date.now() - startedAt + nextDelayMs > TRANSIENT_RETRY_MAX_TOTAL_MS) throw error;
+	await new Promise((resolve) => setTimeout(resolve, nextDelayMs));
+	return attempt + 1;
+}
+/**
+* Creates the validating Factory store engine over a deliberately policy-free driver.
+*
+* @remarks
+* The returned stores validate entities on read and write, enforce legal transitions and
+* compare-and-swap fences, and emit immutable receipts. Construct one configured instance per
+* runtime and share it with launchers, hooks, and tools. A custom workflow must be registered on
+* every process that may read its Tasks; omission is a configuration error rather than permission
+* to select a newer workflow version. Supplying `workflows` replaces the default registry, so
+* include `defaultTaskWorkflow` when generic `task@1` work, Factory tools, or human questions may
+* be created.
+*
+* Wakeups run after their source write commits. Notification failure therefore cannot roll the
+* mutation back; reconciliation must be able to rediscover canonical state.
+*
+* @param options - Persistence and exact workflow/message configuration for this runtime.
+* @returns The complete set of validating Factory stores backed by `options.driver`.
+* @see The version-matched `docs/getting-started.md` shipped with the package.
+*
+* @example
+* ```ts
+* import { createInMemoryDriver, createStores } from "@vercel/factory/storage";
+* import {
+*   defaultTaskWorkflow,
+*   defineWorkflow,
+*   defineWorkflows,
+* } from "@vercel/factory/workflows";
+* import { z } from "zod";
+*
+* const greeting = defineWorkflow({
+*   id: "greeting",
+*   version: 1,
+*   input: z.object({ name: z.string() }),
+*   output: z.object({ message: z.string() }),
+* });
+* const stores = createStores({
+*   driver: createInMemoryDriver(),
+*   workflows: defineWorkflows([defaultTaskWorkflow, greeting]),
+* });
+* ```
+*/
+function createStores(options) {
+	const { driver } = options;
+	const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+	const workflows = options.workflows ?? defineWorkflows([defaultTaskWorkflow]);
+	const notifications = createWorkNotifier(options.workNotifications);
+	function validateTaskWork(task) {
+		workflows.validateStoredInput(task.work.workflow, task.work.input);
+		if (task.workResult !== void 0) workflows.validateStoredOutput(task.work.workflow, task.workResult.output);
+	}
+	async function read(collection, id, schema) {
+		const record = await driver.get(collection, id);
+		if (record === null) return null;
+		const value = schema.parse(record.value);
+		if (collection === "tasks") {
+			const task = taskSchema.parse(value);
+			if (task.id !== id) throw new Error(`Task ${id} does not match its storage key`);
+			validateTaskWork(task);
+		}
+		return {
+			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 forEachConcurrent(values, limit, operation) {
+		let next = 0;
+		await Promise.all(Array.from({ length: Math.min(limit, values.length) }, async () => {
+			while (next < values.length) await operation(values[next++]);
+		}));
+	}
+	const catalogShards = "0123456789abcdef".split("");
+	const shardFor = (id) => createHash("sha256").update(id).digest("hex")[0];
+	function sessionSummary(session) {
+		return agentSessionSchema.parse({
+			...session,
+			continuations: session.continuations?.map(({ context: _context, ...continuation }) => continuation)
+		});
+	}
+	async function projectCatalogEntry(collection, prefix, schema, value, sourceVersion) {
+		const id = `${prefix}-${shardFor(value.id)}`;
+		for (;;) {
+			const existing = await driver.get(collection, id);
+			const parsed = existing === null ? null : schema.parse(existing.value);
+			const previous = parsed?.entries.find((entry) => entry.value.id === value.id);
+			const repairs = parsed?.repairs.filter((repair) => repair.id !== value.id || repair.sourceVersion > sourceVersion) ?? [];
+			if (previous !== void 0 && previous.sourceVersion >= sourceVersion && repairs.length === parsed?.repairs.length) return;
+			const entries = previous !== void 0 && previous.sourceVersion >= sourceVersion ? parsed?.entries ?? [] : [...parsed?.entries.filter((entry) => entry.value.id !== value.id) ?? [], {
+				sourceVersion,
+				value
+			}];
+			const next = schema.parse({
+				schemaVersion: 1,
+				id,
+				entries,
+				repairs,
+				updatedAt: now()
+			});
+			try {
+				if (existing === null) await driver.insert({
+					collection,
+					id,
+					value: next
+				});
+				else await driver.update({
+					collection,
+					id,
+					value: next,
+					expectedVersion: existing.version
+				});
+				return;
+			} catch (error) {
+				if (!(error instanceof RecordExistsError) && !(error instanceof VersionConflictError)) throw error;
+			}
+		}
+	}
+	const projectTaskCatalog = (value, sourceVersion) => projectCatalogEntry("taskCatalogs", "tasks", taskCatalogSchema, value, sourceVersion);
+	const projectChangeCatalog = (value, sourceVersion) => projectCatalogEntry("changeCatalogs", "changes", changeCatalogSchema, value, sourceVersion);
+	const projectSessionCatalog = (value, sourceVersion) => projectCatalogEntry("sessionCatalogs", "sessions", sessionCatalogSchema, sessionSummary(value), sourceVersion);
+	const projectExternalSessionCatalog = (value, sourceVersion) => projectCatalogEntry("externalSessionCatalogs", "external-sessions", externalSessionCatalogSchema, sessionSummary(value), sourceVersion);
+	async function markCatalogRepair(collection, prefix, schema, sourceId, sourceVersion) {
+		const id = `${prefix}-${shardFor(sourceId)}`;
+		for (;;) {
+			const existing = await driver.get(collection, id);
+			const parsed = existing === null ? null : schema.parse(existing.value);
+			const previous = parsed?.repairs.find((repair) => repair.id === sourceId);
+			if (previous !== void 0 && previous.sourceVersion >= sourceVersion) return;
+			const repairs = parsed?.repairs.filter((repair) => repair.id !== sourceId) ?? [];
+			const next = schema.parse({
+				schemaVersion: 1,
+				id,
+				entries: parsed?.entries ?? [],
+				repairs: [...repairs, {
+					id: sourceId,
+					sourceVersion
+				}],
+				updatedAt: now()
+			});
+			try {
+				if (existing === null) await driver.insert({
+					collection,
+					id,
+					value: next
+				});
+				else await driver.update({
+					collection,
+					id,
+					value: next,
+					expectedVersion: existing.version
+				});
+				return;
+			} catch (error) {
+				if (!(error instanceof RecordExistsError) && !(error instanceof VersionConflictError)) throw error;
+			}
+		}
+	}
+	const markTaskCatalogRepair = (id, sourceVersion) => markCatalogRepair("taskCatalogs", "tasks", taskCatalogSchema, id, sourceVersion);
+	const markChangeCatalogRepair = (id, sourceVersion) => markCatalogRepair("changeCatalogs", "changes", changeCatalogSchema, id, sourceVersion);
+	const markSessionCatalogRepair = (id, sourceVersion) => markCatalogRepair("sessionCatalogs", "sessions", sessionCatalogSchema, id, sourceVersion);
+	const markExternalSessionCatalogRepair = (id, sourceVersion) => markCatalogRepair("externalSessionCatalogs", "external-sessions", externalSessionCatalogSchema, id, sourceVersion);
+	async function projectTaskRoute(value, sourceVersion) {
+		if (value.replyTo.channel !== "api") return;
+		const id = derivedId("task-route", JSON.stringify([value.replyTo.channel, value.replyTo.address]));
+		for (;;) {
+			const existing = await read("taskRoutes", id, taskRouteSchema);
+			const previous = existing?.value.entries.find((entry) => entry.value.id === value.id);
+			const repairs = existing?.value.repairs.filter((repair) => repair.id !== value.id || repair.sourceVersion > sourceVersion) ?? [];
+			if (previous !== void 0 && previous.sourceVersion >= sourceVersion && repairs.length === existing?.value.repairs.length) return;
+			const entries = previous !== void 0 && previous.sourceVersion >= sourceVersion ? existing?.value.entries ?? [] : [...existing?.value.entries.filter((entry) => entry.value.id !== value.id) ?? [], {
+				sourceVersion,
+				value
+			}];
+			const next = taskRouteSchema.parse({
+				schemaVersion: 1,
+				id,
+				replyTo: value.replyTo,
+				entries,
+				repairs,
+				updatedAt: now()
+			});
+			try {
+				if (existing === null) await driver.insert({
+					collection: "taskRoutes",
+					id,
+					value: next
+				});
+				else await driver.update({
+					collection: "taskRoutes",
+					id,
+					value: next,
+					expectedVersion: existing.version
+				});
+				return;
+			} catch (error) {
+				if (!(error instanceof RecordExistsError) && !(error instanceof VersionConflictError)) throw error;
+			}
+		}
+	}
+	async function markTaskRouteRepair(value, sourceVersion) {
+		if (value.replyTo.channel !== "api") return;
+		const id = derivedId("task-route", JSON.stringify([value.replyTo.channel, value.replyTo.address]));
+		for (;;) {
+			const existing = await read("taskRoutes", id, taskRouteSchema);
+			const previous = existing?.value.repairs.find((repair) => repair.id === value.id);
+			if (previous !== void 0 && previous.sourceVersion >= sourceVersion) return;
+			const repairs = existing?.value.repairs.filter((repair) => repair.id !== value.id) ?? [];
+			const next = taskRouteSchema.parse({
+				schemaVersion: 1,
+				id,
+				replyTo: value.replyTo,
+				entries: existing?.value.entries ?? [],
+				repairs: [...repairs, {
+					id: value.id,
+					sourceVersion
+				}],
+				updatedAt: now()
+			});
+			try {
+				if (existing === null) await driver.insert({
+					collection: "taskRoutes",
+					id,
+					value: next
+				});
+				else await driver.update({
+					collection: "taskRoutes",
+					id,
+					value: next,
+					expectedVersion: existing.version
+				});
+				return;
+			} catch (error) {
+				if (!(error instanceof RecordExistsError) && !(error instanceof VersionConflictError)) throw error;
+			}
+		}
+	}
+	async function prepareTaskProjection(value, sourceVersion) {
+		await Promise.all([markTaskCatalogRepair(value.id, sourceVersion), markTaskRouteRepair(value, sourceVersion)]);
+	}
+	async function projectTask(value, sourceVersion) {
+		await Promise.all([projectTaskCatalog(value, sourceVersion), projectTaskRoute(value, sourceVersion)]);
+	}
+	async function projectSafely(project) {
+		try {
+			await project();
+		} catch {
+			return;
+		}
+	}
+	async function catalogValues(source, collection, prefix, sourceSchema, catalogSchema, project, fallbackValue = (value) => value) {
+		let catalogs = await Promise.all(catalogShards.map((shard) => driver.get(collection, `${prefix}-${shard}`)));
+		if (catalogs.some((catalog) => catalog === null)) {
+			const entries = await driver.list(source);
+			const values = entries.map((entry) => fallbackValue(sourceSchema.parse(entry.record.value)));
+			let projectionFailed = false;
+			await forEachConcurrent(entries, 16, async (entry) => {
+				try {
+					await project(sourceSchema.parse(entry.record.value), entry.record.version);
+				} catch {
+					projectionFailed = true;
+				}
+			});
+			if (!projectionFailed) for (const shard of catalogShards) {
+				const id = `${prefix}-${shard}`;
+				if (await driver.get(collection, id) !== null) continue;
+				const empty = catalogSchema.parse({
+					schemaVersion: 1,
+					id,
+					entries: [],
+					updatedAt: now()
+				});
+				try {
+					await driver.insert({
+						collection,
+						id,
+						value: empty
+					});
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) projectionFailed = true;
+				}
+			}
+			if (projectionFailed) return values;
+			catalogs = await Promise.all(catalogShards.map((shard) => driver.get(collection, `${prefix}-${shard}`)));
+			if (catalogs.some((catalog) => catalog === null)) return values;
+		}
+		const parsedCatalogs = catalogs.flatMap((catalog) => catalog === null ? [] : [catalogSchema.parse(catalog.value)]);
+		const values = /* @__PURE__ */ new Map();
+		for (const catalog of parsedCatalogs) for (const entry of catalog.entries) {
+			const value = sourceSchema.parse(entry.value);
+			values.set(value.id, value);
+		}
+		const repairs = /* @__PURE__ */ new Map();
+		for (const catalog of parsedCatalogs) for (const repair of catalog.repairs) repairs.set(repair.id, Math.max(repairs.get(repair.id) ?? 0, repair.sourceVersion));
+		await forEachConcurrent([...repairs.keys()], 16, async (id) => {
+			const record = await driver.get(source, id);
+			if (record === null) {
+				values.delete(id);
+				return;
+			}
+			const canonical = sourceSchema.parse(record.value);
+			values.set(id, fallbackValue(canonical));
+			await projectSafely(() => project(canonical, record.version));
+		});
+		return [...values.values()];
+	}
+	async function updateTask(input, expectedVersion) {
+		const value = taskSchema.parse(input);
+		validateTaskWork(value);
+		const previous = options.workNotifications ? await mustRead("tasks", value.id, storedTaskSchema) : null;
+		await prepareTaskProjection(value, expectedVersion + 1);
+		await driver.update({
+			collection: "tasks",
+			id: value.id,
+			value,
+			expectedVersion
+		});
+		await projectSafely(() => projectTask(value, expectedVersion + 1));
+		await notifications.task(value, previous?.value ?? null, expectedVersion + 1);
+	}
+	async function updateChange(value, expectedVersion) {
+		await markChangeCatalogRepair(value.id, expectedVersion + 1);
+		await driver.update({
+			collection: "changes",
+			id: value.id,
+			value,
+			expectedVersion
+		});
+		await projectSafely(() => projectChangeCatalog(value, expectedVersion + 1));
+	}
+	async function updateSession(value, expectedVersion) {
+		await markSessionCatalogRepair(value.id, expectedVersion + 1);
+		await driver.update({
+			collection: "sessions",
+			id: value.id,
+			value,
+			expectedVersion
+		});
+		await projectSafely(() => projectSessionCatalog(value, expectedVersion + 1));
+	}
+	async function insertReceipt(receiptId, receipt) {
+		const reason = receipt.reason?.trim().slice(0, 2e3) || void 0;
+		const full = receiptSchema.parse({
+			...receipt,
+			reason,
+			schemaVersion: 1,
+			receiptId,
+			recordedAt: now()
+		});
+		try {
+			await driver.insert({
+				collection: "receipts",
+				id: receiptId,
+				value: full
+			});
+			return full;
+		} catch (error) {
+			if (error instanceof RecordExistsError) return (await mustRead("receipts", receiptId, receiptSchema)).value;
+			throw error;
+		}
+	}
+	async function readApprovalReceipt(task) {
+		const current = await read("receipts", derivedId("rcpt", `task:${task.id}:approval`), receiptSchema);
+		if (current) return current.value;
+		return null;
+	}
+	async function decideApproval(id, state, decision) {
+		const by = z.string().trim().min(1).parse(decision.by);
+		const reason = state === "rejected" ? z.string().trim().min(1).max(2e3).parse(decision.reason) : decision.reason?.trim().slice(0, 2e3) || void 0;
+		const receiptId = derivedId("rcpt", `task:${id}:approval`);
+		for (;;) {
+			const existing = await mustRead("tasks", id, storedTaskSchema);
+			const task = existing.value;
+			const saved = await readApprovalReceipt(task);
+			if (saved && (saved.state !== state || saved.decidedBy !== by || saved.reason !== reason)) throw new ApprovalError(id, "a different decision has already been recorded");
+			const approval = state === "approved" ? "granted" : "denied";
+			if (saved && task.approval === approval) {
+				await projectSafely(() => projectTask(task, existing.version));
+				return task;
+			}
+			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}`);
+			const receipt = saved ?? await insertReceipt(receiptId, {
+				repositoryIds: task.repositoryIds,
+				taskId: id,
+				kind: task.kind,
+				state,
+				phase: "approval",
+				reason,
+				attempt: task.attempt,
+				decidedBy: by
+			});
+			if (receipt.state !== state || receipt.decidedBy !== by || receipt.reason !== reason) throw new ApprovalError(id, "a different decision has already been recorded");
+			if (state === "rejected") assertTransition(taskTransitions, {
+				from: task.state,
+				to: "cancelled"
+			});
+			let next = taskSchema.parse({
+				...task,
+				approval,
+				state: state === "rejected" ? "cancelled" : task.state,
+				updatedAt: now()
+			});
+			if (state === "rejected") {
+				const cancelled = await appendReceipt(`task:${id}:cancelled:${task.attempt}`, {
+					repositoryIds: task.repositoryIds,
+					taskId: id,
+					kind: task.kind,
+					state: "cancelled",
+					phase: "approval",
+					reason: reason ?? `rejected by ${by}`,
+					attempt: task.attempt
+				});
+				if (needsLifecycleCommunication(next, "cancelled", "approval")) next = taskSchema.parse({
+					...next,
+					pendingCommunicationReceiptIds: [.../* @__PURE__ */ new Set([...next.pendingCommunicationReceiptIds ?? [], cancelled.receiptId])]
+				});
+			}
+			try {
+				await updateTask(next, existing.version);
+				return next;
+			} catch (error) {
+				if (!(error instanceof VersionConflictError)) throw error;
+			}
+		}
+	}
+	async function appendReceipt(key, receipt) {
+		return insertReceipt(derivedId("rcpt", key), receipt);
+	}
+	async function setQuestionRoute(replyTo, questionTaskId, present) {
+		const id = derivedId("qroute", JSON.stringify([replyTo.channel, replyTo.address]));
+		for (;;) {
+			const existing = await read("questionRoutes", id, questionRouteSchema);
+			const currentIds = existing?.value.questionTaskIds ?? [];
+			const questionTaskIds = present ? [.../* @__PURE__ */ new Set([...currentIds, questionTaskId])] : currentIds.filter((candidate) => candidate !== questionTaskId);
+			if (existing !== null && questionTaskIds.length === existing.value.questionTaskIds.length) return;
+			const next = questionRouteSchema.parse({
+				schemaVersion: 1,
+				id,
+				replyTo,
+				questionTaskIds,
+				updatedAt: now()
+			});
+			try {
+				if (existing === null) await driver.insert({
+					collection: "questionRoutes",
+					id,
+					value: next
+				});
+				else await driver.update({
+					collection: "questionRoutes",
+					id,
+					value: next,
+					expectedVersion: existing.version
+				});
+				return;
+			} catch (error) {
+				if (!(error instanceof RecordExistsError) && !(error instanceof VersionConflictError)) throw error;
+			}
+		}
+	}
+	const stores = {
+		driverName: driver.name,
+		workflowRecords: {
+			get: driver.get.bind(driver),
+			insert: driver.insert.bind(driver),
+			update: driver.update.bind(driver)
+		},
+		taskEffects: createTaskEffectStore({
+			driver,
+			now,
+			getTask: (id) => stores.tasks.get(id)
+		}),
+		graphs: createTaskGraphStore({
+			driver,
+			now,
+			getTask: (id) => stores.tasks.get(id),
+			validateTask: validateTaskWork,
+			notify: notifications.publish
+		}),
+		messages: createTaskMessageStore({
+			driver,
+			now: () => new Date(now()),
+			getTask: (id) => stores.tasks.get(id),
+			protocols: options.messages?.protocols ?? defineTaskMessageProtocols([]),
+			authorize: options.messages?.authorize ?? (() => false),
+			notify: notifications.publish
+		}),
+		work: createTaskWorkStore({
+			driver,
+			now,
+			stores: () => stores,
+			workflows,
+			update: async (task, version) => {
+				await updateTask(task, version);
+			},
+			restore: async (task) => {
+				validateTaskWork(task);
+				await prepareTaskProjection(task, 1);
+				try {
+					await driver.insert({
+						collection: "tasks",
+						id: task.id,
+						value: task
+					});
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) throw error;
+				}
+				const existing = await mustRead("tasks", task.id, taskSchema);
+				await projectSafely(() => projectTask(existing.value, existing.version));
+				await notifications.task(existing.value, null, existing.version);
+				return existing.value;
+			}
+		}),
+		transcripts: {
+			async get(execution) {
+				const record = await read("transcripts", derivedId("transcript", JSON.stringify([execution.provider, execution.sessionId])), storedTranscriptSchema);
+				if (record === null) return null;
+				if (record.value.execution.provider !== execution.provider || record.value.execution.sessionId !== execution.sessionId) throw new Error("Transcript execution key does not match its stored value");
+				return record.value.snapshot;
+			},
+			async put(execution, value) {
+				const snapshot = transcriptSnapshotSchema.parse(value);
+				const id = derivedId("transcript", JSON.stringify([execution.provider, execution.sessionId]));
+				for (;;) {
+					const existing = await read("transcripts", id, storedTranscriptSchema);
+					if (existing !== null && existing.value.snapshot.cursor >= snapshot.cursor) return existing.value.snapshot;
+					const next = storedTranscriptSchema.parse({
+						schemaVersion: 1,
+						execution,
+						snapshot,
+						updatedAt: now()
+					});
+					try {
+						if (existing === null) await driver.insert({
+							collection: "transcripts",
+							id,
+							value: next
+						});
+						else await driver.update({
+							collection: "transcripts",
+							id,
+							value: next,
+							expectedVersion: existing.version
+						});
+						return snapshot;
+					} catch (error) {
+						if (!(error instanceof RecordExistsError) && !(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			}
+		},
+		images: {
+			async put(owner, input) {
+				const parsed = imageUploadSchema.parse(input);
+				const id = imageIdSchema.parse(`img_${createHash("sha256").update(JSON.stringify([
+					owner,
+					parsed.filename,
+					parsed.mediaType,
+					parsed.base64
+				])).digest("hex")}`);
+				const image = storedImageSchema.parse({
+					...parsed,
+					id,
+					owner,
+					schemaVersion: 1,
+					size: Buffer.from(parsed.base64, "base64").length,
+					createdAt: now()
+				});
+				try {
+					await driver.insert({
+						collection: "images",
+						id,
+						value: image
+					});
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) throw error;
+					await stores.images.get(owner, id);
+				}
+				return imageAttachmentSchema.parse({
+					id,
+					filename: image.filename,
+					mediaType: image.mediaType,
+					size: image.size
+				});
+			},
+			async get(owner, id) {
+				imageIdSchema.parse(id);
+				const record = await driver.get("images", id);
+				if (!record) return null;
+				const image = storedImageSchema.parse(record.value);
+				return image.owner === owner ? image : null;
+			},
+			async validate(owner, attachments) {
+				imageAttachmentsSchema.parse(attachments);
+				return Promise.all(attachments.map(async (attachment) => {
+					const image = await stores.images.get(owner, attachment.id);
+					if (!image) throw new ImageInputError("Image is unavailable; upload it again");
+					const ref = {
+						id: image.id,
+						filename: image.filename,
+						mediaType: image.mediaType,
+						size: image.size
+					};
+					if (!sameStoredValue(ref, attachment)) throw new ImageInputError("Image metadata does not match the uploaded image");
+					return ref;
+				}));
+			}
+		},
+		sessions: {
+			async getByOperation(owner, operationId) {
+				return stores.sessions.get(derivedId("ses", JSON.stringify([owner, operationId])));
+			},
+			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 = storedSessionSchema.parse({
+					...input,
+					id,
+					schemaVersion: 1,
+					createdAt: now()
+				});
+				await stores.images.validate(input.owner, input.attachments ?? []);
+				await markSessionCatalogRepair(candidate.id, 1);
+				try {
+					await driver.insert({
+						collection: "sessions",
+						id,
+						value: candidate
+					});
+					await projectSafely(() => projectSessionCatalog(candidate, 1));
+					return candidate;
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) throw error;
+					const record = await mustRead("sessions", id, storedSessionSchema);
+					await projectSafely(() => projectSessionCatalog(record.value, record.version));
+					const existing = record.value;
+					const { createdAt: _at, execution: _execution, taskId: _task, notifications: _notifications, continuations: _continuations, ...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 attachConversation(input) {
+				const id = derivedId("ses", JSON.stringify([
+					"conversation",
+					input.owner,
+					input.execution.provider,
+					input.execution.sessionId
+				]));
+				const candidate = externalSessionSchema.parse({
+					...input,
+					id,
+					schemaVersion: 1,
+					createdAt: input.createdAt ?? now()
+				});
+				await markExternalSessionCatalogRepair(id, 1);
+				try {
+					await driver.insert({
+						collection: "externalSessions",
+						id,
+						value: candidate
+					});
+					await projectSafely(() => projectExternalSessionCatalog(candidate, 1));
+					return candidate;
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) throw error;
+					const record = await mustRead("externalSessions", id, externalSessionSchema);
+					const existing = record.value;
+					if (existing.owner !== candidate.owner || existing.agent !== candidate.agent || !sameStoredValue(existing.external, candidate.external) || !sameStoredValue(existing.execution, candidate.execution)) throw new SessionConflictError("External conversation binding cannot be replaced");
+					await projectSafely(() => projectExternalSessionCatalog(existing, record.version));
+					return existing;
+				}
+			},
+			async attachTask(input) {
+				const task = (await mustRead("tasks", input.taskId, storedTaskSchema)).value;
+				if (task.repositoryIds.length !== 1) throw new SessionConflictError("Only single-repository tasks can be opened");
+				if (task.replyTo.channel === "api") {
+					const original = await stores.sessions.get(agentSessionIdSchema.parse(task.replyTo.address));
+					if (original?.owner !== input.owner) throw new SessionConflictError("Task belongs to another operator interaction");
+					const record = await mustRead("sessions", original.id, storedSessionSchema);
+					await projectSafely(() => projectSessionCatalog(record.value, record.version));
+					return original;
+				}
+				if (task.work.route === void 0) throw new SessionConflictError("Only tasks with an exact agent route can be opened");
+				const id = derivedId("ses", JSON.stringify([
+					"task",
+					input.owner,
+					task.id
+				]));
+				const candidate = storedSessionSchema.parse({
+					schemaVersion: 1,
+					id,
+					owner: input.owner,
+					agent: input.agent,
+					route: task.work.route,
+					repositoryId: task.repositoryIds[0],
+					message: input.message,
+					taskId: task.id,
+					attached: true,
+					createdAt: task.createdAt
+				});
+				await markSessionCatalogRepair(candidate.id, 1);
+				try {
+					await driver.insert({
+						collection: "sessions",
+						id,
+						value: candidate
+					});
+					await projectSafely(() => projectSessionCatalog(candidate, 1));
+					return candidate;
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) throw error;
+					const existing = await mustRead("sessions", id, storedSessionSchema);
+					await projectSafely(() => projectSessionCatalog(existing.value, existing.version));
+					return existing.value;
+				}
+			},
+			async cacheContinuationContext(id, input) {
+				const { taskId, context, attachments } = input;
+				for (;;) {
+					const record = await mustRead("sessions", id, storedSessionSchema);
+					const continuation = record.value.continuations?.find((item) => item.taskId === taskId);
+					if (!continuation) throw new SessionConflictError("Task is not a conversation continuation");
+					if (continuation.context !== void 0) return continuation.context;
+					await stores.images.validate(record.value.owner, attachments ?? []);
+					const next = storedSessionSchema.parse({
+						...record.value,
+						continuations: record.value.continuations?.map((item) => item.taskId === taskId ? {
+							...item,
+							context,
+							...attachments?.length ? { contextAttachments: attachments } : {}
+						} : item)
+					});
+					try {
+						await updateSession(next, record.version);
+						return context;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async continue(id, input) {
+				if (input.operationId.trim().length === 0 || input.operationId.length > 200) throw new SessionConflictError("operationId must contain 1–200 characters");
+				const dedupeKey = `session:${id}:follow-up:${input.operationId}`;
+				for (;;) {
+					const record = await mustRead("sessions", id, storedSessionSchema);
+					const session = record.value;
+					await stores.images.validate(session.owner, input.attachments ?? []);
+					if (session.repositoryId === void 0 || session.taskId === void 0) throw new SessionConflictError("Follow-up work requires a repository-bound task conversation");
+					const parent = (await mustRead("tasks", input.parentTaskId, storedTaskSchema)).value;
+					if (parent.id !== session.taskId && !(parent.replyTo.channel === "api" && parent.replyTo.address === id)) throw new SessionConflictError("Follow-up parent is outside this conversation");
+					if (parent.repositoryIds.length !== 1 || parent.repositoryIds[0] !== session.repositoryId) throw new SessionConflictError("Follow-up repository differs from its conversation");
+					const previous = session.continuations?.find((item) => item.operationId === input.operationId);
+					if (previous !== void 0 && !sameStoredValue({
+						operationId: input.operationId,
+						parentTaskId: input.parentTaskId,
+						agent: input.agent,
+						message: input.message,
+						attachments: input.attachments ?? []
+					}, {
+						operationId: previous.operationId,
+						parentTaskId: previous.parentTaskId,
+						agent: previous.agent,
+						message: previous.message,
+						attachments: previous.attachments ?? []
+					})) throw new SessionConflictError("Follow-up operationId was reused with different input");
+					const continuation = previous ?? {
+						...input,
+						taskId: derivedId("task", JSON.stringify([
+							"task",
+							parent.id,
+							dedupeKey
+						])),
+						createdAt: now()
+					};
+					let next = session;
+					if (previous === void 0) {
+						if (![
+							"succeeded",
+							"failed",
+							"cancelled",
+							"verifying"
+						].includes(parent.state)) throw new SessionConflictError("Wait for this task or answer its pending question before starting a follow-up");
+						const latest = session.continuations?.at(-1);
+						if (latest !== void 0 && latest.taskId !== parent.id) {
+							let ancestor = parent;
+							const visited = /* @__PURE__ */ new Set();
+							while (ancestor && ancestor.id !== latest.taskId && !visited.has(ancestor.id)) {
+								visited.add(ancestor.id);
+								ancestor = ancestor.parentTaskId ? await stores.tasks.get(ancestor.parentTaskId) : null;
+							}
+							if (ancestor?.id !== latest.taskId) throw new SessionConflictError("Conversation changed; refresh before sending another follow-up");
+							const latestTask = await stores.tasks.get(latest.taskId);
+							if (latestTask === null || ![
+								"succeeded",
+								"failed",
+								"cancelled"
+							].includes(latestTask.state)) throw new SessionConflictError("A follow-up is already being started; refresh the conversation");
+						}
+						next = storedSessionSchema.parse({
+							...session,
+							continuations: [...session.continuations ?? [], continuation]
+						});
+						try {
+							await updateSession(next, record.version);
+						} catch (error) {
+							if (error instanceof VersionConflictError) continue;
+							throw error;
+						}
+					}
+					const replyTo = {
+						channel: "api",
+						address: id
+					};
+					const signal = await stores.signals.create({
+						repositoryId: session.repositoryId,
+						source: "api",
+						deliveryId: dedupeKey,
+						replyTo,
+						payload: {
+							message: continuation.message,
+							parentTaskId: parent.id
+						}
+					});
+					if (signal.outcome === "pending") try {
+						await stores.signals.decide(signal.id, {
+							outcome: "accepted",
+							reason: `Follow-up requested by ${session.owner}`
+						});
+					} catch (error) {
+						if (!(error instanceof VersionConflictError || error instanceof InvalidTransitionError)) throw error;
+					}
+					await stores.tasks.create({
+						repositoryIds: [session.repositoryId],
+						kind: "investigation",
+						area: "conversation",
+						origin: {
+							operator: session.owner,
+							signalId: signal.id
+						},
+						parentTaskId: parent.id,
+						work: routeTaskWork({
+							route: parseAgentRouteBinding({
+								id: "conversation",
+								version: 1
+							}),
+							title: "Conversation follow-up",
+							input: { message: continuation.message }
+						}),
+						replyTo,
+						dedupeKey,
+						changeId: parent.changeId
+					});
+					return next;
+				}
+			},
+			async get(id) {
+				const records = (await Promise.all([read("sessions", id, storedSessionSchema), read("externalSessions", id, externalSessionSchema)])).filter((record) => record !== null);
+				if (records.length > 1) throw new SessionConflictError("Session ID exists in multiple collections");
+				return records[0]?.value ?? null;
+			},
+			async list() {
+				return (await Promise.all([listAll("sessions", storedSessionSchema), listAll("externalSessions", externalSessionSchema)])).flat();
+			},
+			async summaries() {
+				return (await Promise.all([catalogValues("sessions", "sessionCatalogs", "sessions", storedSessionSchema, sessionCatalogSchema, projectSessionCatalog, sessionSummary), catalogValues("externalSessions", "externalSessionCatalogs", "external-sessions", externalSessionSchema, externalSessionCatalogSchema, projectExternalSessionCatalog, sessionSummary)])).flat();
+			},
+			async bind(id, reference) {
+				const external = await read("externalSessions", id, externalSessionSchema);
+				if (external) {
+					if (!("execution" in reference) || !sameStoredValue(external.value.execution, reference.execution)) throw new SessionConflictError("Session execution binding cannot be replaced");
+					await projectSafely(() => projectExternalSessionCatalog(external.value, external.version));
+					return external.value;
+				}
+				for (;;) {
+					const existing = await mustRead("sessions", id, storedSessionSchema);
+					if (reference.taskId !== void 0) {
+						const task = (await mustRead("tasks", reference.taskId, storedTaskSchema)).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");
+						await projectSafely(() => projectSessionCatalog(existing.value, existing.version));
+						return existing.value;
+					}
+					const next = storedSessionSchema.parse({
+						...existing.value,
+						...reference
+					});
+					try {
+						await updateSession(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, storedSessionSchema);
+					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 = storedSessionSchema.parse({
+						...record.value,
+						notifications: [...record.value.notifications, event]
+					});
+					try {
+						await updateSession(next, record.version);
+						return;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			}
+		},
+		repositories: {
+			async setModelDefaults(id, input) {
+				const existing = await mustRead("repositories", id, repositorySchema);
+				if ((existing.value.modelDefaults?.revision ?? 0) !== input.expectedRevision) throw new VersionConflictError("repositories", id, existing.version);
+				const next = repositorySchema.parse({
+					...existing.value,
+					modelDefaults: {
+						revision: input.expectedRevision + 1,
+						agents: input.agents
+					}
+				});
+				await driver.update({
+					collection: "repositories",
+					id,
+					value: next,
+					expectedVersion: existing.version
+				});
+				return next;
+			},
+			async put(repository) {
+				let parsed = repositorySchema.parse(repository);
+				const existing = await read("repositories", parsed.id, repositorySchema);
+				if (existing === null) await driver.insert({
+					collection: "repositories",
+					id: parsed.id,
+					value: parsed
+				});
+				else {
+					parsed = repositorySchema.parse({
+						...parsed,
+						modelDefaults: existing.value.modelDefaults
+					});
+					await driver.update({
+						collection: "repositories",
+						id: parsed.id,
+						value: parsed,
+						expectedVersion: 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({
+						collection: "signals",
+						id,
+						value: 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 getByDelivery({ source, deliveryId }) {
+				return stores.signals.get(derivedId("sig", `${source}:${deliveryId}`));
+			},
+			async beginTriage(id, options) {
+				const existing = await mustRead("signals", id, signalSchema);
+				const current = existing.value;
+				if (current.outcome !== "pending" || (current.triage?.attempt ?? 0) !== options.expectedAttempt) throw new VersionConflictError("signals", id, existing.version);
+				if (current.triage) assertTransition(signalTriageTransitions, {
+					from: current.triage.state,
+					to: "running"
+				});
+				const timestamp = now();
+				const next = signalSchema.parse({
+					...current,
+					triage: {
+						attempt: options.expectedAttempt + 1,
+						state: "running",
+						by: options.by,
+						startedAt: timestamp,
+						updatedAt: timestamp
+					}
+				});
+				await driver.update({
+					collection: "signals",
+					id,
+					value: next,
+					expectedVersion: existing.version
+				});
+				return next;
+			},
+			async updateTriage(id, attempt, observation) {
+				for (let retry = 0; retry < 5; retry++) {
+					const existing = await mustRead("signals", id, signalSchema);
+					const current = existing.value;
+					const triage = current.triage;
+					if (current.outcome !== "pending" || triage?.attempt !== attempt || triage.state === "blocked") return current;
+					if (triage.sessionId && observation.sessionId && triage.sessionId !== observation.sessionId) return current;
+					if (triage.state !== observation.state) assertTransition(signalTriageTransitions, {
+						from: triage.state,
+						to: observation.state
+					});
+					const next = signalSchema.parse({
+						...current,
+						triage: {
+							...triage,
+							...observation,
+							sessionId: observation.sessionId ?? triage.sessionId,
+							updatedAt: now()
+						}
+					});
+					try {
+						await driver.update({
+							collection: "signals",
+							id,
+							value: next,
+							expectedVersion: existing.version
+						});
+						return next;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError) || retry === 4) throw error;
+					}
+				}
+				throw new Error("Triage update retries exhausted");
+			},
+			async decide(id, input) {
+				const { outcome, detail, reason } = input;
+				const existing = await mustRead("signals", id, signalSchema);
+				assertTransition(signalOutcomeTransitions, {
+					from: existing.value.outcome,
+					to: outcome
+				});
+				const next = signalSchema.parse({
+					...existing.value,
+					outcome,
+					detail,
+					reason,
+					decidedAt: now()
+				});
+				await driver.update({
+					collection: "signals",
+					id,
+					value: next,
+					expectedVersion: existing.version
+				});
+				return next;
+			},
+			list() {
+				return listAll("signals", signalSchema);
+			}
+		},
+		tasks: {
+			async pinModel(id, input) {
+				for (let retry = 0; retry < 5; retry++) {
+					const existing = await mustRead("tasks", id, storedTaskSchema);
+					if (existing.value.attempt !== input.attempt) throw new Error("Cannot select a model for a replaced Task attempt");
+					if (existing.value.model !== void 0) {
+						if (existing.value.model !== input.model) throw new Error("Task model cannot be replaced");
+						return existing.value;
+					}
+					if (!["queued", "running"].includes(existing.value.state)) throw new Error("Select a model before work completes or waits");
+					const next = taskSchema.parse({
+						...existing.value,
+						model: input.model
+					});
+					try {
+						await updateTask(next, existing.version);
+						return next;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError) || retry === 4) throw error;
+					}
+				}
+				throw new Error("Task model selection conflicted repeatedly");
+			},
+			async create(value) {
+				const input = createTaskInputSchema.parse(value);
+				const timestamp = now();
+				const id = input.dedupeKey === void 0 ? randomId("task") : derivedId("task", JSON.stringify([
+					"task",
+					input.parentTaskId ?? null,
+					input.dedupeKey
+				]));
+				const parsedWork = structuredClone(taskWorkSchema.parse(input.work));
+				const work = {
+					...parsedWork,
+					input: workflows.validateInput(parsedWork.workflow, parsedWork.input)
+				};
+				const parent = input.parentTaskId === void 0 ? null : await stores.tasks.get(input.parentTaskId);
+				if (input.parentTaskId !== void 0 && parent === null) throw new Error("Child Tasks require an existing parent");
+				if (input.parentTaskAttempt !== void 0 && (parent === null || input.question === void 0 || input.parentTaskAttempt !== parent.attempt)) throw new Error("Child questions must bind the current parent execution attempt");
+				const origin = taskOriginSchema.parse(input.origin);
+				let task = taskSchema.parse({
+					schemaVersion: 1,
+					id,
+					repositoryIds: input.repositoryIds,
+					kind: input.kind,
+					area: input.area,
+					state: taskInitialState,
+					approval: input.approval,
+					origin: origin.signalId === void 0 && origin.operator === void 0 && parent ? parent.origin : origin,
+					work,
+					rootTaskId: parent?.rootTaskId ?? id,
+					parentTaskId: input.parentTaskId,
+					parentTaskAttempt: input.question === void 0 ? void 0 : parent?.attempt,
+					replyTo: input.replyTo,
+					attempt: 1,
+					question: input.question,
+					changeId: input.changeId,
+					createdAt: timestamp,
+					updatedAt: timestamp
+				});
+				validateTaskWork(task);
+				await stores.graphs.admit({
+					task,
+					dependencies: input.dependencies
+				});
+				const admission = (await stores.graphs.get(task.rootTaskId))?.nodes.find((node) => node.taskId === id)?.admission;
+				if (admission === void 0) throw new Error(`Task ${id} has no durable graph admission`);
+				task = admission;
+				await prepareTaskProjection(task, 1);
+				try {
+					await driver.insert({
+						collection: "tasks",
+						id: task.id,
+						value: task
+					});
+					await projectSafely(() => projectTask(task, 1));
+					await notifications.task(task, null, 1);
+					return task;
+				} catch (error) {
+					if (input.dedupeKey !== void 0 && error instanceof RecordExistsError) {
+						const existing = await mustRead("tasks", task.id, storedTaskSchema);
+						await projectSafely(() => projectTask(existing.value, existing.version));
+						await notifications.task(existing.value, null, existing.version);
+						return existing.value;
+					}
+					throw error;
+				}
+			},
+			approve: (id, decision) => decideApproval(id, "approved", decision),
+			reject: (id, decision) => decideApproval(id, "rejected", decision),
+			async approvalReceipt(id) {
+				return readApprovalReceipt((await mustRead("tasks", id, storedTaskSchema)).value);
+			},
+			async recordExecution(id, input) {
+				const { execution, expectAttempt } = input;
+				const startedAt = Date.now();
+				for (let retries = 0;;) try {
+					const existing = await mustRead("tasks", id, storedTaskSchema);
+					const task = existing.value;
+					if (task.state !== "running") throw new InvalidTransitionError(task.state, "running", legalNextStates(taskTransitions, task.state));
+					if (expectAttempt !== void 0 && task.attempt !== expectAttempt) throw new TaskAttemptConflictError(id, task.attempt, expectAttempt);
+					if (expectAttempt !== void 0 && task.execution) {
+						if (!sameStoredValue(task.execution, execution)) throw new Error(`Task ${id} already has a different execution for attempt ${expectAttempt}`);
+						return task;
+					}
+					const timestamp = now();
+					const next = taskSchema.parse({
+						...task,
+						execution,
+						lastProgressAt: timestamp,
+						updatedAt: timestamp
+					});
+					await updateTask(next, existing.version);
+					return next;
+				} catch (error) {
+					if (!(error instanceof TransientStoreError)) throw error;
+					retries = await nextTransientRetry(error, retries, startedAt);
+				}
+			},
+			async recordUsage(id, input) {
+				const step = stepUsageSchema.parse(input.step);
+				const { fence } = input;
+				const startedAt = Date.now();
+				let transientAttempt = 0;
+				for (;;) {
+					let existing;
+					try {
+						existing = await mustRead("tasks", id, storedTaskSchema);
+					} catch (error) {
+						if (!(error instanceof TransientStoreError)) throw error;
+						transientAttempt = await nextTransientRetry(error, transientAttempt, startedAt);
+						continue;
+					}
+					const task = existing.value;
+					if (fence && (task.attempt !== fence.attempt || !sameStoredValue(task.execution, fence.execution))) throw new Error(`Usage for task ${id} belongs to a replaced execution`);
+					const usage = task.usage ?? emptyUsage;
+					const recordedIndex = Object.hasOwn(usage.steps, step.turnId) ? usage.steps[step.turnId] : void 0;
+					if (task.settledUsd !== void 0 && (recordedIndex === void 0 || step.stepIndex > recordedIndex)) throw new SettlementError(id, "task is already settled; new usage cannot be silently added");
+					if (recordedIndex !== void 0 && step.stepIndex <= recordedIndex) {
+						await projectSafely(() => projectTask(task, existing.version));
+						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 updateTask(next, existing.version);
+						return next;
+					} catch (error) {
+						if (error instanceof VersionConflictError) continue;
+						if (error instanceof TransientStoreError) {
+							transientAttempt = await nextTransientRetry(error, transientAttempt, startedAt);
+							continue;
+						}
+						throw error;
+					}
+				}
+			},
+			async settle(id, input) {
+				const existing = await mustRead("tasks", id, storedTaskSchema);
+				const task = existing.value;
+				if (task.settledUsd !== void 0) {
+					await projectSafely(() => projectTask(task, existing.version));
+					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(input.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: input.reason,
+					attempt: task.attempt,
+					cost: normalized
+				})).cost ?? normalized;
+				const next = taskSchema.parse({
+					...task,
+					settledUsd: recorded.totalUsd,
+					updatedAt: now()
+				});
+				await updateTask(next, existing.version);
+				return next;
+			},
+			async get(id) {
+				const record = await read("tasks", id, storedTaskSchema);
+				return record === null ? null : record.value;
+			},
+			async findOpenQuestions(replyTo) {
+				const route = await read("questionRoutes", derivedId("qroute", JSON.stringify([replyTo.channel, replyTo.address])), questionRouteSchema);
+				if (route === null) return [];
+				const openQuestions = (await Promise.all(route.value.questionTaskIds.map((taskId) => stores.tasks.get(taskId)))).filter((task) => task !== null && task.question !== void 0 && task.state === "needs_human" && task.replyTo.channel === replyTo.channel && task.replyTo.address === replyTo.address);
+				const openIds = new Set(openQuestions.map((task) => task.id));
+				for (const taskId of route.value.questionTaskIds) if (!openIds.has(taskId)) await setQuestionRoute(replyTo, taskId, false);
+				return openQuestions;
+			},
+			async answerQuestion(input) {
+				const question = await mustRead("tasks", input.questionTaskId, storedTaskSchema);
+				if (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.parentTaskId,
+					repositoryIds: question.value.repositoryIds,
+					replyTo: question.value.replyTo,
+					question: questionDetails.text,
+					answer: input.answer,
+					answeredBy: input.answeredBy,
+					recordedAt: now()
+				});
+				const answerOutput = jsonValueSchema.parse({
+					answer: candidate.answer,
+					answeredBy: candidate.answeredBy,
+					questionTaskId: candidate.questionTaskId
+				});
+				let answerEvent = candidate;
+				try {
+					await driver.insert({
+						collection: "answers",
+						id,
+						value: 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, storedTaskSchema);
+						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 updateTask(projected, parent.version);
+							parentTask = projected;
+							break;
+						} catch (error) {
+							if (!(error instanceof VersionConflictError)) throw error;
+						}
+					}
+					if (parentTask.state === "needs_human" && parentTask.questionTaskId === input.questionTaskId) {
+						const closes = isClosingAnswer(questionDetails.closingOptions, answerEvent.answer);
+						parentTask = await stores.tasks.transition(parentTask.id, closes ? "cancelled" : "queued", {
+							expectFrom: "needs_human",
+							expectAttempt: parentTask.attempt,
+							expectQuestionTaskId: input.questionTaskId,
+							reason: closes ? `question ${answerEvent.questionTaskId} answered by ${answerEvent.answeredBy}: ${answerEvent.answer}` : `question ${answerEvent.questionTaskId} answered by ${answerEvent.answeredBy}`
+						});
+					}
+				}
+				let questionTask = await mustRead("tasks", input.questionTaskId, storedTaskSchema).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
+					} },
+					output: answerOutput,
+					reason: "question answered by authenticated operator"
+				});
+				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, ...args) {
+				const transitionOptions = args[0] ?? {};
+				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");
+				let existing = await mustRead("tasks", id, storedTaskSchema);
+				if (transitionOptions.expectFrom !== void 0 && existing.value.state !== transitionOptions.expectFrom) throw new InvalidTransitionError(existing.value.state, to, legalNextStates(taskTransitions, existing.value.state));
+				if (transitionOptions.expectAttempt !== void 0 && existing.value.attempt !== transitionOptions.expectAttempt) throw new TaskAttemptConflictError(id, existing.value.attempt, transitionOptions.expectAttempt);
+				if (transitionOptions.expectExecution !== void 0 && !sameStoredValue(existing.value.execution, transitionOptions.expectExecution)) throw new Error(`Task ${id} execution has been replaced`);
+				if (transitionOptions.expectQuestionTaskId !== void 0 && existing.value.questionTaskId !== transitionOptions.expectQuestionTaskId) throw new Error(`task ${id} is no longer waiting for question ${transitionOptions.expectQuestionTaskId}`);
+				assertTransition(taskTransitions, {
+					from: existing.value.state,
+					to
+				});
+				if (transitionOptions.patch !== void 0 && Object.keys(transitionOptions.patch).some((key) => ![
+					"changeId",
+					"reportRef",
+					"reservedUsd",
+					"reservedAt",
+					"question"
+				].includes(key))) throw new Error("Task transitions cannot replace workflow-owned fields");
+				if (to !== "succeeded" && (transitionOptions.output !== void 0 || transitionOptions.reuseRecordedOutput === true)) throw new Error("Workflow output can only be recorded when succeeding");
+				if (to === "succeeded" && transitionOptions.output === void 0 && transitionOptions.reuseRecordedOutput !== true) throw new Error("Succeeded transitions require output or reuseRecordedOutput after work completion");
+				if (to === "succeeded" && transitionOptions.output !== void 0 && transitionOptions.reuseRecordedOutput === true) throw new Error("Choose output or reuseRecordedOutput, not both");
+				if (to !== "needs_human" && (transitionOptions.needsHumanAction !== void 0 || transitionOptions.questionTaskId !== void 0)) throw new Error("Question context is only valid when entering needs_human");
+				if (to === "running") {
+					if (existing.value.approval !== void 0 && existing.value.approval !== "granted") throw new Error(`Task ${id} requires approval before execution`);
+				}
+				const timestamp = now();
+				let workResult = existing.value.workResult;
+				if (to === "succeeded") {
+					const output = transitionOptions.output === void 0 ? existing.value.workResult?.output : workflows.validateOutput(existing.value.work.workflow, transitionOptions.output);
+					if (output === void 0) throw new Error(`Task ${id} requires validated output to succeed`);
+					if (existing.value.workResult && !isDeepStrictEqual(existing.value.workResult.output, output)) throw new Error(`Task ${id} already recorded a different workflow output`);
+					workResult ??= {
+						output,
+						completedAt: timestamp
+					};
+				}
+				if (to === "stalled" && existing.value.waitingForMessages) throw new Error(`Task ${id} is waiting for messages, not stalled execution`);
+				if (bumpsAttempt(existing.value.state, to) && existing.value.settledUsd !== void 0) throw new Error(`Task ${id} is settled; create new work rather than silently losing retry costs`);
+				if (to === "needs_human" && existing.value.question === void 0) {
+					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, storedTaskSchema);
+					if (question.value.question === void 0 || question.value.state !== "needs_human" || question.value.parentTaskId !== id || question.value.rootTaskId !== existing.value.rootTaskId || question.value.parentTaskAttempt !== existing.value.attempt || !sameStoredValue(question.value.replyTo, existing.value.replyTo)) throw new Error(`task ${id} cannot enter needs_human for question ${question.value.id}`);
+				}
+				const needsHumanAction = transitionOptions.needsHumanAction?.trim();
+				if (to === "needs_human" && (needsHumanAction === void 0 || needsHumanAction === "")) throw new Error(`task ${id} cannot enter needs_human without an actionable needsHumanAction`);
+				const bumps = bumpsAttempt(existing.value.state, to);
+				const { stalledAt: _stalledAt, stalledReason: _stalledReason, questionTaskId: _questionTaskId, needsHumanAction: _needsHumanAction, needsHumanNotifiedAt: _needsHumanNotifiedAt, failureReceiptId: _failureReceiptId, ...cleared } = existing.value;
+				let next = taskSchema.parse({
+					...cleared,
+					workResult,
+					...bumps ? {
+						execution: void 0,
+						workResult: void 0
+					} : {},
+					waitingForMessages: void 0,
+					...transitionOptions.patch,
+					...to === "needs_human" && existing.value.question === void 0 ? { questionTaskId: transitionOptions.questionTaskId } : {},
+					...to === "needs_human" ? { needsHumanAction } : {},
+					...to === "stalled" ? {
+						stalledAt: timestamp,
+						stalledReason: transitionOptions.reason
+					} : {},
+					...to === "running" ? { lastProgressAt: timestamp } : {},
+					state: to,
+					attempt: bumps ? existing.value.attempt + 1 : existing.value.attempt,
+					updatedAt: timestamp
+				});
+				validateTaskWork(next);
+				if (to === "running") await stores.graphs.seal({
+					rootTaskId: existing.value.rootTaskId,
+					taskId: id
+				});
+				if (existing.value.question !== void 0 && to === "needs_human") await setQuestionRoute(existing.value.replyTo, existing.value.id, true);
+				await projectSafely(() => projectTask(existing.value, existing.version));
+				if (to === "succeeded" && existing.value.workResult === void 0) {
+					const prepared = taskSchema.parse({
+						...existing.value,
+						workResult: next.workResult,
+						updatedAt: timestamp
+					});
+					await updateTask(prepared, existing.version);
+					existing = {
+						value: prepared,
+						version: existing.version + 1
+					};
+				}
+				const receiptState = taskReceiptStates[to];
+				if (receiptState !== void 0 && next.repositoryIds !== void 0) {
+					const receipt = await appendReceipt(JSON.stringify([
+						"task",
+						id,
+						receiptState,
+						next.attempt,
+						next.changeId ?? null,
+						transitionOptions.phase ?? null,
+						transitionOptions.reason ?? null
+					]), {
+						repositoryIds: next.repositoryIds,
+						taskId: id,
+						changeId: next.changeId,
+						kind: next.kind,
+						state: receiptState,
+						phase: transitionOptions.phase,
+						reason: transitionOptions.reason,
+						attempt: next.attempt,
+						execution: next.execution
+					});
+					if (to === "failed") next = taskSchema.parse({
+						...next,
+						failureReceiptId: receipt.receiptId
+					});
+					if (needsLifecycleCommunication(next, receiptState, transitionOptions.phase)) next = taskSchema.parse({
+						...next,
+						pendingCommunicationReceiptIds: [...next.pendingCommunicationReceiptIds ?? [], receipt.receiptId]
+					});
+				}
+				if (existing.value.question !== void 0 && existing.value.state === "needs_human" && to !== "needs_human" && existing.value.parentTaskId !== void 0) {
+					const parent = await stores.tasks.get(existing.value.parentTaskId);
+					if (parent?.state === "needs_human" && parent.questionTaskId === id && parent.attempt === existing.value.parentTaskAttempt) await stores.tasks.transition(parent.id, "queued", {
+						expectFrom: "needs_human",
+						expectAttempt: parent.attempt,
+						expectQuestionTaskId: id,
+						reason: `question ${id} is no longer waiting`
+					});
+				}
+				await updateTask(next, existing.version);
+				if (existing.value.question !== void 0 && existing.value.state === "needs_human" && to !== "needs_human") await setQuestionRoute(existing.value.replyTo, existing.value.id, false);
+				return next;
+			},
+			async acknowledgeCommunication(id, receiptId) {
+				for (;;) {
+					const existing = await mustRead("tasks", id, storedTaskSchema);
+					const pending = existing.value.pendingCommunicationReceiptIds ?? [];
+					if (!pending.includes(receiptId)) {
+						await projectSafely(() => projectTask(existing.value, existing.version));
+						return existing.value;
+					}
+					const remaining = pending.filter((candidate) => candidate !== receiptId);
+					const { pendingCommunicationReceiptIds: _pending, ...task } = existing.value;
+					const next = taskSchema.parse({
+						...task,
+						...remaining.length === 0 ? {} : { pendingCommunicationReceiptIds: remaining },
+						updatedAt: now()
+					});
+					try {
+						await updateTask(next, existing.version);
+						return next;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async recordNeedsHumanDelivery(id, deliveryOptions = {}) {
+				const at = deliveryOptions.at ?? now();
+				let question;
+				for (;;) {
+					const existing = await mustRead("tasks", id, storedTaskSchema);
+					if (existing.value.question === void 0) throw new Error(`task ${id} is not a QuestionTask`);
+					if (existing.value.state !== "needs_human" || deliveryOptions.attempt !== void 0 && existing.value.attempt !== deliveryOptions.attempt) return existing.value;
+					if (existing.value.needsHumanNotifiedAt !== void 0) {
+						question = existing.value;
+						break;
+					}
+					const next = taskSchema.parse({
+						...existing.value,
+						needsHumanNotifiedAt: existing.value.needsHumanNotifiedAt ?? at,
+						updatedAt: now()
+					});
+					try {
+						await updateTask(next, existing.version);
+						question = next;
+						break;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+				const parentId = question.parentTaskId;
+				if (parentId !== void 0) for (;;) {
+					const parent = await mustRead("tasks", parentId, storedTaskSchema);
+					if (parent.value.state !== "needs_human" || parent.value.questionTaskId !== id || parent.value.attempt !== question.parentTaskAttempt || parent.value.needsHumanNotifiedAt !== void 0) break;
+					const current = await mustRead("tasks", id, storedTaskSchema);
+					if (current.value.state !== "needs_human" || current.value.attempt !== question.attempt) break;
+					const next = taskSchema.parse({
+						...parent.value,
+						needsHumanNotifiedAt: question.needsHumanNotifiedAt,
+						updatedAt: now()
+					});
+					try {
+						await updateTask(next, parent.version);
+						break;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+				return question;
+			},
+			async forReplyTo(replyTo) {
+				const id = derivedId("task-route", JSON.stringify([replyTo.channel, replyTo.address]));
+				let route = await read("taskRoutes", id, taskRouteSchema);
+				let discovered = [];
+				if (route === null) {
+					discovered = (await stores.tasks.list()).filter((task) => task.replyTo.channel === replyTo.channel && task.replyTo.address === replyTo.address);
+					for (const task of discovered) {
+						const record = await mustRead("tasks", task.id, storedTaskSchema);
+						await projectSafely(() => projectTaskRoute(record.value, record.version));
+					}
+					if (discovered.length === 0) {
+						const empty = taskRouteSchema.parse({
+							schemaVersion: 1,
+							id,
+							replyTo,
+							entries: [],
+							updatedAt: now()
+						});
+						await projectSafely(async () => {
+							try {
+								await driver.insert({
+									collection: "taskRoutes",
+									id,
+									value: empty
+								});
+							} catch (error) {
+								if (!(error instanceof RecordExistsError)) throw error;
+							}
+						});
+					}
+					route = await read("taskRoutes", id, taskRouteSchema);
+				}
+				if (route === null) return discovered;
+				const values = new Map(route.value.entries.map((entry) => [entry.value.id, entry.value]));
+				await forEachConcurrent(route.value.repairs, 16, async (repair) => {
+					const repairTaskId = taskIdSchema.parse(repair.id);
+					const record = await driver.get("tasks", repairTaskId);
+					if (record === null) {
+						values.delete(repairTaskId);
+						return;
+					}
+					const canonical = storedTaskSchema.parse(record.value);
+					if (canonical.replyTo.channel === replyTo.channel && canonical.replyTo.address === replyTo.address) values.set(canonical.id, canonical);
+					else values.delete(canonical.id);
+					await projectSafely(() => projectTaskRoute(canonical, record.version));
+				});
+				const tasks = [...values.values()];
+				for (const task of tasks) validateTaskWork(task);
+				return tasks;
+			},
+			async list() {
+				const tasks = await catalogValues("tasks", "taskCatalogs", "tasks", storedTaskSchema, taskCatalogSchema, projectTaskCatalog);
+				for (const task of tasks) validateTaskWork(task);
+				return tasks;
+			}
+		},
+		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, storedTaskSchema)).value;
+					const taskRepositoryId = task.repositoryIds[0];
+					if (!task.repositoryIds.includes(change.repositoryId)) throw new ChangeAssociationError(change.taskId, change.repositoryId, `repository "${change.repositoryId}" does not match task repository "${taskRepositoryId}"`);
+				}
+				await markChangeCatalogRepair(change.id, 1);
+				try {
+					await driver.insert({
+						collection: "changes",
+						id: change.id,
+						value: change
+					});
+					await projectSafely(() => projectChangeCatalog(change, 1));
+					return change;
+				} catch (error) {
+					if (error instanceof RecordExistsError) for (;;) {
+						const existing = await mustRead("changes", change.id, changeSchema);
+						if (change.taskId !== void 0) {
+							if (existing.value.prUrl !== change.prUrl || existing.value.taskId !== void 0 && existing.value.taskId !== change.taskId) throw new ChangeAssociationError(change.taskId, change.repositoryId, "pull request is already recorded with a different URL or producing Task");
+							if (existing.value.taskId === void 0) {
+								const associated = changeSchema.parse({
+									...existing.value,
+									taskId: change.taskId,
+									updatedAt: now()
+								});
+								try {
+									await updateChange(associated, existing.version);
+									return associated;
+								} catch (conflict) {
+									if (conflict instanceof VersionConflictError) continue;
+									throw conflict;
+								}
+							}
+						}
+						await projectSafely(() => projectChangeCatalog(existing.value, existing.version));
+						return existing.value;
+					}
+					throw error;
+				}
+			},
+			async get(id) {
+				const record = await read("changes", id, changeSchema);
+				return record === null ? null : record.value;
+			},
+			async updateEvidence(id, input) {
+				const existing = await mustRead("changes", id, changeSchema);
+				if (!sameStoredValue(existing.value, input.expected)) throw new VersionConflictError("changes", id, existing.version);
+				const next = changeSchema.parse({
+					...existing.value,
+					evidence: input.evidence,
+					confidence: input.confidence,
+					updatedAt: now()
+				});
+				await updateChange(next, existing.version);
+				return next;
+			},
+			async transition(id, to, ...args) {
+				const transitionOptions = args[0] ?? {};
+				const existing = await mustRead("changes", id, changeSchema);
+				await projectSafely(() => projectChangeCatalog(existing.value, existing.version));
+				assertTransition(changeTransitions, {
+					from: 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 updateChange(next, existing.version);
+				return next;
+			},
+			list() {
+				return catalogValues("changes", "changeCatalogs", "changes", changeSchema, changeCatalogSchema, projectChangeCatalog);
+			}
+		},
+		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({
+						collection: "budgets",
+						id: input.month,
+						value: 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({
+						collection: "budgets",
+						id: input.month,
+						value: refreshed,
+						expectedVersion: 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({
+							collection: "budgets",
+							id: month,
+							value: next,
+							expectedVersion: 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({
+							collection: "outboxQueues",
+							id: queueId,
+							value: queue
+						});
+						else await driver.update({
+							collection: "outboxQueues",
+							id: queueId,
+							value: queue,
+							expectedVersion: 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({
+								collection: "outboxQueues",
+								id: queueId,
+								value: outboxQueueSchema.parse({
+									...queue.value,
+									messages,
+									updatedAt: now()
+								}),
+								expectedVersion: 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({
+							collection: "outboxQueues",
+							id: queueId,
+							value: outboxQueueSchema.parse({
+								...queue.value,
+								messages,
+								updatedAt: timestamp
+							}),
+							expectedVersion: queue.version
+						});
+						return next;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async retry(id, input) {
+				const { attempt, reason, delayMs } = input;
+				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({
+							collection: "outboxQueues",
+							id: queueId,
+							value: outboxQueueSchema.parse({
+								...queue.value,
+								messages,
+								updatedAt: timestamp
+							}),
+							expectedVersion: 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({
+								collection: "outboxDeliveries",
+								id,
+								value: 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({
+							collection: "outboxQueues",
+							id: queueId,
+							value: outboxQueueSchema.parse({
+								...queue.value,
+								messages,
+								updatedAt: timestamp
+							}),
+							expectedVersion: 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 { AnswerEventConflictError, ApprovalError, ChangeAssociationError, ImageInputError, OutboxEventConflictError, SessionConflictError, SettlementError, TaskAttemptConflictError, createStores };
+
+//# sourceMappingURL=engine.mjs.map