@vercel/factory 0.0.15 → 0.0.17

package/dist/store/engine.d.mts

@@ -81,12 +81,17 @@ interface DecideSignalInput {
   readonly reason?: string;
 }
 interface CreateTaskInputBase {
+  /** Repository authorization scope; children must remain within their parent's scope. */
   repositoryIds: RepositoryIds;
+  /** Descriptive work vocabulary; routing comes only from `work.route`. */
   kind: Task["kind"];
+  /** Destination for lifecycle communication produced by this Task. */
   replyTo: ReplyTo;
-  /** Same key creates one task and returns it on workflow retries. */
+  /** Same key under the same parent creates one Task and returns its current snapshot on retries. */
   dedupeKey?: string;
+  /** Optional application-owned grouping label. */
   area?: string;
+  /** Optional associated software Change. */
   changeId?: ChangeId;
   /** Stamp the task as needing a human decision before dispatch. */
   approval?: "required";
@@ -97,10 +102,14 @@ interface CreateTaskInputBase {
 }
 /** Provenance required when admitting a root Task with no parent to inherit from. */
 type RootTaskOrigin = {
+  /** Durable inbound Signal that caused the root work. */
   signalId: SignalId;
+  /** Authenticated operator additionally associated with the work. */
   operator?: string;
 } | {
+  /** Optional inbound Signal additionally associated with operator-created work. */
   signalId?: SignalId;
+  /** Authenticated operator that caused the root work. */
   operator: string;
 };
 /** Explicit work, graph placement, provenance, and policy input for Task admission. */
@@ -174,17 +183,30 @@ declare const stepUsageSchema: z.ZodObject<{
 type StepUsage = z.infer<typeof stepUsageSchema>;
 /** Attempt and provider execution that must still own a Task usage observation. */
 interface TaskExecutionFence {
+  /** Current positive attempt that emitted the observation. */
   readonly attempt: number;
+  /** Exact provider execution that emitted the observation. */
   readonly execution: ExecutionReference;
 }
+/** Error raised when a Task operation loses its exact-attempt concurrency fence. */
+declare class TaskAttemptConflictError extends Error {
+  readonly taskId: TaskId;
+  readonly actualAttempt: number;
+  readonly expectedAttempt: number;
+  constructor(taskId: TaskId, actualAttempt: number, expectedAttempt: number);
+}
 /** Provider execution and optional attempt fence recorded on one running Task. */
 interface RecordTaskExecutionInput {
+  /** Provider handle to persist for later inspection, cancellation, and callback fencing. */
   readonly execution: ExecutionReference;
+  /** Current running attempt required at the write; identical replay is then a no-op while running. */
   readonly expectAttempt?: number;
 }
 /** One measured usage step and optional exact-execution fence for a Task. */
 interface RecordTaskUsageInput {
+  /** Monotonic step observation to aggregate once per provider turn. */
   readonly step: StepUsage;
+  /** Optional current-attempt and execution guard for provider-originated observations. */
   readonly fence?: TaskExecutionFence;
 }
 interface TaskTransitionContext {
@@ -246,6 +268,12 @@ interface CreateChangeInput {
 }
 /** Verification and merge fields that may accompany a legal Change transition. */
 type ChangePatch = Partial<Pick<Change, "confidence" | "evidence" | "decidedBy" | "mergeSha">>;
+/** Trust evidence update fenced to the complete observed Change snapshot. */
+interface UpdateChangeEvidenceInput {
+  evidence: Change["evidence"];
+  confidence: ChangeLevel;
+  expected: Change;
+}
 interface ChangeTransitionContext {
   patch?: ChangePatch;
   reason?: string;
@@ -272,7 +300,9 @@ interface BudgetNoticeStampResult {
 }
 /** Measured cost and optional audit reason used to settle one terminal Task. */
 interface SettleTaskInput {
+  /** Final measured Task cost, normalized to micro-dollar precision. */
   readonly cost: Cost;
+  /** Optional audit context retained on the immutable settlement receipt. */
   readonly reason?: string;
 }
 /** Delivery attempt, failure reason, and retry delay for one outbox message. */
@@ -319,6 +349,7 @@ type AppendReceiptInput<State extends ReceiptState = StandardReceiptState, Kind
 declare class SessionConflictError extends Error {}
 /** Validating engine API for all canonical Factory state and auxiliary persistence. */
 interface FactoryStores {
+  /** Name supplied by the configured persistence driver for diagnostics and health reporting. */
   driverName: string;
   /** Trusted workflow records bound to the same persistence backend as every validating store. */
   workflowRecords: Pick<StoreDriver, "get" | "insert" | "update">;
@@ -326,19 +357,26 @@ interface FactoryStores {
   taskEffects: TaskEffectStore;
   /** Trusted workflow capabilities; application transports must authenticate and authorize callers. */
   graphs: TaskGraphStore;
+  /** Validated, authorized Task-message operations; omitted protocols remain unavailable. */
   messages: TaskMessageStore;
+  /** Workflow completion, message waiting, graph recovery, and usage aggregation operations. */
   work: TaskWorkStore;
+  /** Materialized transcript snapshots keyed by exact provider execution. */
   transcripts: {
     get(execution: ExecutionReference): Promise<TranscriptSnapshot | null>;
     /** Persist only forward progress; safe to repeat from response-boundary hooks. */
     put(execution: ExecutionReference, snapshot: TranscriptSnapshot): Promise<TranscriptSnapshot>;
   };
+  /** Owner-scoped image persistence and attachment validation. */
   images: {
     put(owner: string, input: z.infer<typeof imageUploadSchema>): Promise<ImageAttachment>;
     get(owner: string, id: ImageId): Promise<StoredImage | null>;
     validate(owner: string, attachments: readonly ImageAttachment[]): Promise<readonly ImageAttachment[]>;
   };
+  /** Durable operator-session admission, binding, continuation, and notification operations. */
   sessions: {
+    /** Looks up an admitted session without recomputing defaults on a repeated operation. */
+    getByOperation(owner: string, operationId: string): Promise<AgentSession | null>;
     create(input: Omit<AgentSession, "schemaVersion" | "id" | "createdAt" | "execution" | "taskId" | "notifications" | "attached" | "continuations" | "external"> & {
       operationId: string;
     }): Promise<AgentSession>;
@@ -371,14 +409,23 @@ interface FactoryStores {
     bind(id: AgentSessionId, reference: AgentSessionBinding): Promise<AgentSession>;
     notify(event: CommunicationEvent): Promise<void>;
   };
+  /** Configured repository snapshots used for admission and routing. */
   repositories: {
+    /** Atomically replaces model overrides when their observed revision still matches. */
+    setModelDefaults(id: RepositoryId, input: {
+      expectedRevision: number;
+      agents: Readonly<Record<string, string>>;
+    }): Promise<Repository>;
     put(repository: Repository): Promise<Repository>;
     get(id: RepositoryId): Promise<Repository | null>;
     list(): Promise<readonly Repository[]>;
   };
+  /** External intake records and their explicit triage lifecycle. */
   signals: {
     create(input: CreateSignalInput): Promise<Signal>;
     get(id: SignalId): Promise<Signal | null>;
+    /** Read a deterministic source/delivery record without scanning the Signal collection. */
+    getByDelivery(input: Pick<CreateSignalInput, "source" | "deliveryId">): Promise<Signal | null>;
     beginTriage(id: SignalId, options: {
       expectedAttempt: number;
       by: string;
@@ -387,10 +434,61 @@ interface FactoryStores {
     decide(id: SignalId, input: DecideSignalInput): Promise<Signal>;
     list(): Promise<readonly Signal[]>;
   };
+  /** Canonical Task lifecycle operations. */
   tasks: {
+    /** Pins an application's model choice once, fencing the current attempt. */
+    pinModel(id: TaskId, input: {
+      attempt: number;
+      model: string;
+    }): Promise<Task>;
+    /**
+     * Validates and durably admits a queued Task into its canonical graph.
+     *
+     * @remarks
+     * Admission writes the immutable graph node before the mutable Task snapshot. A failure after
+     * graph admission can therefore leave a repairable missing snapshot; call
+     * `stores.work.recover(rootTaskId)` with the known root to restore it. The method returns only
+     * after both admission and the canonical Task snapshot are durable.
+     *
+     * A `dedupeKey` derives a stable ID within the parent scope. An identical retry returns the
+     * Task's current mutable snapshot, while changed immutable admission data is refused. Without
+     * a key, every call creates a new Task.
+     *
+     * @param input - Explicit workflow work, scope, provenance, graph placement, and policy.
+     * @returns The newly admitted Task, or the current snapshot selected by `dedupeKey`.
+     * @throws When workflow input is invalid or its exact version is unregistered, parent or
+     * dependency constraints fail, or a dedupe key conflicts with an earlier admission.
+     */
     create(input: CreateTaskInput): Promise<Task>;
+    /**
+     * Returns the validated current Task snapshot without repairing a missing admitted snapshot.
+     *
+     * @param id - Exact Task ID to read.
+     * @returns Current Task state, or `null` when its canonical snapshot is absent.
+     */
     get(id: TaskId): Promise<Task | null>;
     findOpenQuestions(replyTo: ReplyTo): Promise<readonly Task[]>;
+    /**
+     * Performs one legal lifecycle transition with optional attempt, source-state, execution, and
+     * question fences.
+     *
+     * @remarks
+     * Lifecycle evidence is appended before the final Task-state write. A successful completion
+     * first persists its validated `workResult`, then its receipt, then the terminal state. The
+     * promise resolves only after the final Task snapshot is durable, but a rejected call may have
+     * persisted prepared output or its idempotent receipt before a later write failed. Reread
+     * canonical Task state before retrying, and retain the same fences so a late callback cannot
+     * advance a replacement attempt or execution. Transitions that re-enter `queued`, and
+     * `verifying` to `running`, increment the attempt and clear attempt-owned execution state.
+     *
+     * @param id - Exact Task to advance.
+     * @param to - Legal destination state.
+     * @param args - Destination data and optional concurrency fences.
+     * @returns The durably updated Task snapshot.
+     * @throws `InvalidTransitionError` for an illegal or stale source state,
+     * `TaskAttemptConflictError` for a replaced attempt, or a persistence conflict when a
+     * concurrent writer wins.
+     */
     transition<To extends TaskState>(id: TaskId, to: To, ...args: TaskTransitionArguments<NoInfer<To>>): Promise<Task>;
     /** Remove a receipt after its CommunicationEvent is durable in the outbox. */
     acknowledgeCommunication(id: TaskId, receiptId: ReceiptId): Promise<Task>;
@@ -403,14 +501,51 @@ interface FactoryStores {
     reject(id: TaskId, decision: RejectionDecision): Promise<Task>;
     /**
      * Record the provider's handle on the running attempt's execution, so the
-     * reconciler can inspect or cancel it. Refused unless the task is running.
+     * reconciler can inspect or cancel it.
+     *
+     * @remarks
+     * The returned Task contains the durably recorded handle. Supply `expectAttempt` for launch
+     * callbacks: while that attempt remains running, replaying the same handle is a no-op, while a
+     * different handle or replaced attempt is refused. Terminal Tasks reject every binding call.
+     * The engine retries bounded transient driver failures, but surfaces compare-and-swap
+     * conflicts; callers should reread and reconcile rather than start an unkeyed replacement
+     * execution.
+     *
+     * @param id - Exact running Task to bind.
+     * @param input - Provider reference and recommended attempt fence.
+     * @returns The Task containing the durable execution reference.
+     * @throws When the Task is not running, the attempt or existing execution differs, or bounded
+     * persistence retries are exhausted.
      */
     recordExecution(id: TaskId, input: RecordTaskExecutionInput): Promise<Task>;
-    /** Add one model step's usage to the task. Idempotent per (turnId, stepIndex). Never settles. */
+    /**
+     * Adds one provider step's measured usage without settling the Task.
+     *
+     * @remarks
+     * Step indexes advance monotonically per `turnId`; replaying the recorded index or an earlier
+     * one returns the current Task without charging it again. Use an execution fence for provider
+     * callbacks. Version races are retried, transient storage failures are retried within bounded
+     * limits, and new usage after settlement is refused so measured cost cannot silently diverge
+     * from the immutable settlement receipt.
+     *
+     * @param id - Exact Task to charge.
+     * @param input - Validated step observation and optional execution fence.
+     * @returns The Task after aggregation, or unchanged when the step was already covered.
+     */
     recordUsage(id: TaskId, input: RecordTaskUsageInput): Promise<Task>;
     /**
-     * Record measured cost on a terminal task. Idempotent: an already settled
-     * task returns unchanged and writes no second receipt.
+     * Records measured cost on a terminal Task using receipt-first persistence.
+     *
+     * @remarks
+     * Cost is normalized to micro-dollar precision. The immutable receipt is written before the
+     * Task snapshot, so retrying after an interrupted snapshot write adopts the receipt's original
+     * cost. Once settled, every replay returns the unchanged Task even if a different cost is
+     * supplied; callers must treat the first settlement as authoritative.
+     *
+     * @param id - Exact terminal Task to settle.
+     * @param input - Final measured cost and optional audit reason.
+     * @returns The Task with its authoritative `settledUsd` value.
+     * @throws `SettlementError` when the Task is not terminal.
      */
     settle(id: TaskId, input: SettleTaskInput): Promise<Task>;
     /**
@@ -426,12 +561,16 @@ interface FactoryStores {
     forReplyTo(replyTo: ReplyTo): Promise<readonly Task[]>;
     list(): Promise<readonly Task[]>;
   };
+  /** Canonical software Change admission and lifecycle operations. */
   changes: {
     create(input: CreateChangeInput): Promise<Change>;
     get(id: ChangeId): Promise<Change | null>;
+    /** Save evidence without inventing a lifecycle transition; reject a changed snapshot. */
+    updateEvidence(id: ChangeId, input: UpdateChangeEvidenceInput): Promise<Change>;
     transition<To extends ChangeState>(id: ChangeId, to: To, ...args: ChangeTransitionArguments<NoInfer<To>>): Promise<ChangeInState<To>>;
     list(): Promise<readonly Change[]>;
   };
+  /** Immutable audit evidence appended by engine and application policy. */
   receipts: {
     append<const State extends ReceiptState, const Kind extends ReceiptKind, const Phase extends ReceiptPhase | undefined = undefined>(input: AppendReceiptCallInput<State, Kind, Phase> & {
       state: State;
@@ -441,6 +580,7 @@ interface FactoryStores {
     get(id: ReceiptId): Promise<Receipt | null>;
     list(): Promise<readonly Receipt[]>;
   };
+  /** Monthly budget snapshots, limits, and once-only notification stamps. */
   budgets: {
     /**
      * Insert-once per month; refreshes limits when configuration changed and
@@ -454,9 +594,11 @@ interface FactoryStores {
      */
     stampNotice(month: BudgetMonth, notice: "warning" | "exhausted"): Promise<BudgetNoticeStampResult>;
   };
+  /** Immutable authenticated answers addressed by deterministic event ID. */
   answers: {
     get(id: AnswerId): Promise<AnswerEvent | null>;
   };
+  /** Durable communication delivery queue with attempt-fenced leases. */
   outbox: {
     enqueue(event: CommunicationEvent): Promise<OutboxMessage>;
     get(id: OutboxId): Promise<OutboxMessage | null>;
@@ -468,18 +610,74 @@ interface FactoryStores {
 }
 /** Persistence, workflow, messaging, clock, and wakeup configuration for the Factory engine. */
 interface CreateStoresOptions {
+  /** Persistence implementation. The engine owns validation and lifecycle policy above it. */
   driver: StoreDriver;
-  /** Awaited post-commit wakeups. Canonical work remains recoverable if publishing fails. */
+  /**
+   * Optional post-commit wakeup transport. Delivery failure is reported through its `onError`
+   * callback and never rolls back the canonical write.
+   */
   workNotifications?: WorkNotifications;
+  /** ISO timestamp source used for engine-owned records. Defaults to the current wall clock. */
   now?: IsoDateTimeClock;
+  /**
+   * Every workflow version that stored Tasks may reference. Omission registers only the generic
+   * `task@1` workflow. A supplied registry replaces that default, so include `defaultTaskWorkflow`
+   * when Factory tools or human-question flows may create generic work.
+   */
   workflows?: WorkflowRegistry;
+  /**
+   * Versioned Task-message protocols and deny-by-default authorization. Omit when the runtime
+   * does not use Task messages.
+   */
   messages?: {
+    /** Exact protocol versions accepted by this runtime. */
     protocols: TaskMessageProtocols;
+    /** Trusted application policy applied to every message operation. */
     authorize: TaskMessageAuthorize;
   };
 }
-/** Creates the validating Factory store engine over a deliberately policy-free driver. */
+/**
+ * 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]),
+ * });
+ * ```
+ */
 declare function createStores(options: CreateStoresOptions): FactoryStores;
 //#endregion
-export { AgentSessionBinding, AnswerEventConflictError, AnswerQuestionInput, AnswerQuestionResult, AppendReceiptInput, ApprovalDecision, ApprovalError, BudgetNoticeStampResult, CacheContinuationContextInput, ChangeAssociationError, ChangePatch, ChangeTransitionArguments, ChangeTransitionOptions, CreateChangeInput, CreateSignalInput, CreateStoresOptions, CreateTaskInput, DecideSignalInput, EnsureBudgetInput, FactoryStores, ImageInputError, OutboxEventConflictError, RecordTaskExecutionInput, RecordTaskUsageInput, RejectionDecision, RetryOutboxMessageInput, RootTaskOrigin, SessionConflictError, SettleTaskInput, SettlementError, StepUsage, TaskExecutionFence, TaskPatch, TaskTransitionArguments, TaskTransitionOptions, createStores };
+export { AgentSessionBinding, AnswerEventConflictError, AnswerQuestionInput, AnswerQuestionResult, AppendReceiptInput, ApprovalDecision, ApprovalError, BudgetNoticeStampResult, CacheContinuationContextInput, ChangeAssociationError, ChangePatch, ChangeTransitionArguments, ChangeTransitionOptions, CreateChangeInput, CreateSignalInput, CreateStoresOptions, CreateTaskInput, DecideSignalInput, EnsureBudgetInput, FactoryStores, ImageInputError, OutboxEventConflictError, RecordTaskExecutionInput, RecordTaskUsageInput, RejectionDecision, RetryOutboxMessageInput, RootTaskOrigin, SessionConflictError, SettleTaskInput, SettlementError, StepUsage, TaskAttemptConflictError, TaskExecutionFence, TaskPatch, TaskTransitionArguments, TaskTransitionOptions, UpdateChangeEvidenceInput, createStores };
 //# sourceMappingURL=engine.d.mts.map

package/dist/store/engine.mjs

@@ -139,6 +139,19 @@ const stepUsageSchema = z.strictObject({
 	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) {
@@ -170,7 +183,7 @@ function needsLifecycleCommunication(task, state, phase) {
 	if (state === "dispatched") return phase === "retry";
 	if (state === "failed" || state === "cancelled") return true;
 	if (state !== "succeeded") return false;
-	return task.question === void 0 && task.changeId === void 0;
+	return task.question === void 0;
 }
 const changeReceiptStates = {
 	verifying: "verifying",
@@ -219,7 +232,47 @@ async function nextTransientRetry(error, attempt, startedAt) {
 	await new Promise((resolve) => setTimeout(resolve, nextDelayMs));
 	return attempt + 1;
 }
-/** Creates the validating Factory store engine over a deliberately policy-free driver. */
+/**
+* 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());
@@ -794,6 +847,9 @@ function createStores(options) {
 			}
 		},
 		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]));
@@ -1104,20 +1160,44 @@ function createStores(options) {
 			}
 		},
 		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) {
-				const parsed = repositorySchema.parse(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 await driver.update({
-					collection: "repositories",
-					id: parsed.id,
-					value: parsed,
-					expectedVersion: existing.version
-				});
+				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) {
@@ -1158,6 +1238,9 @@ function createStores(options) {
 				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;
@@ -1246,6 +1329,28 @@ function createStores(options) {
 			}
 		},
 		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();
@@ -1323,7 +1428,7 @@ function createStores(options) {
 					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 Error(`task ${id} is on attempt ${task.attempt}, not ${expectAttempt}`);
+					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;
@@ -1531,7 +1636,7 @@ function createStores(options) {
 				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 Error(`task ${id} is on attempt ${existing.value.attempt}, not ${transitionOptions.expectAttempt}`);
+				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, {
@@ -1815,8 +1920,25 @@ function createStores(options) {
 					await projectSafely(() => projectChangeCatalog(change, 1));
 					return change;
 				} catch (error) {
-					if (error instanceof RecordExistsError) {
+					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;
 					}
@@ -1827,6 +1949,18 @@ function createStores(options) {
 				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);
@@ -2170,6 +2304,6 @@ function createStores(options) {
 	return stores;
 }
 //#endregion
-export { AnswerEventConflictError, ApprovalError, ChangeAssociationError, ImageInputError, OutboxEventConflictError, SessionConflictError, SettlementError, createStores };
+export { AnswerEventConflictError, ApprovalError, ChangeAssociationError, ImageInputError, OutboxEventConflictError, SessionConflictError, SettlementError, TaskAttemptConflictError, createStores };
 
 //# sourceMappingURL=engine.mjs.map