@vercel/factory 0.0.14 → 0.0.16

package/dist/store/engine.d.mts

@@ -0,0 +1,683 @@
+import { Signal, SignalOutcome, SignalSource, SignalTriage } from "../schema/signal.mjs";
+import { AnswerId, ChangeId, FactoryId, OutboxId, ReceiptId, RepositoryId, RepositoryIds, SignalId, TaskId } from "../schema/id.mjs";
+import { Repository } from "../schema/repository.mjs";
+import { ExecutionReference, Task, TaskOrigin, TaskQuestion, TaskState } from "../schema/task.mjs";
+import { WorkflowRegistry } from "../workflows.mjs";
+import { TaskMessageProtocols } from "../schema/task-message.mjs";
+import { WorkNotifications } from "./work-notifications.mjs";
+import { IsoDateTimeClock, ReplyTo } from "../schema/common.mjs";
+import { StoreDriver } from "./driver.mjs";
+import { TaskMessageAuthorize, TaskMessageStore } from "./task-messages.mjs";
+import { TaskGraphStore } from "./task-graphs.mjs";
+import { TaskEffectStore } from "./task-effects.mjs";
+import { TaskWorkStore } from "./task-work.mjs";
+import { ImageAttachment, ImageId, imageUploadSchema } from "../image-input.mjs";
+import { AnswerEvent } from "../schema/answer.mjs";
+import { AgentSession, AgentSessionId } from "../schema/session.mjs";
+import { CommunicationEvent } from "../schema/communication.mjs";
+import { Budget, BudgetMonth } from "../schema/budget.mjs";
+import { Change, ChangeInState, ChangeLevel, ChangeState } from "../schema/change.mjs";
+import { OutboxMessage } from "../schema/outbox.mjs";
+import { TranscriptSnapshot } from "../schema/transcript.mjs";
+import { Cost, Receipt, ReceiptDelivery, ReceiptKind, ReceiptPhase, ReceiptState, StandardReceiptKind, StandardReceiptPhase, StandardReceiptState } from "../schema/receipt.mjs";
+import { z } from "zod";
+//#region src/store/engine.d.ts
+declare const storedImageSchema: z.ZodObject<{
+  id: z.ZodType<`img_${string}`, string, z.core.$ZodTypeInternals<`img_${string}`, string>>;
+  filename: z.ZodString;
+  mediaType: z.ZodEnum<{
+    "image/png": "image/png";
+    "image/jpeg": "image/jpeg";
+    "image/webp": "image/webp";
+  }>;
+  size: z.ZodNumber;
+  schemaVersion: z.ZodLiteral<1>;
+  owner: z.ZodString;
+  base64: z.ZodString;
+  createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+type StoredImage = z.infer<typeof storedImageSchema>;
+/** Error raised when uploaded image bytes, ownership, or attachment metadata is invalid. */
+declare class ImageInputError extends Error {}
+/** An approval decision that does not apply to the task's current approval or state. */
+declare class ApprovalError extends Error {
+  readonly taskId: TaskId;
+  readonly reason: string;
+  constructor(taskId: TaskId, reason: string);
+}
+/** A settlement that does not apply to the task's current state. */
+declare class SettlementError extends Error {
+  readonly taskId: TaskId;
+  readonly reason: string;
+  constructor(taskId: TaskId, reason: string);
+}
+/** Error raised when a Task is not authorized to create or update a requested Change. */
+declare class ChangeAssociationError extends Error {
+  readonly taskId: TaskId;
+  readonly repositoryId: RepositoryId;
+  readonly reason: string;
+  constructor(taskId: TaskId, repositoryId: RepositoryId, reason: string);
+}
+/** Error raised when a stable outbox event ID is reused with different content. */
+declare class OutboxEventConflictError extends Error {
+  constructor(eventId: string);
+}
+/** Error raised when a QuestionTask already has a different immutable answer event. */
+declare class AnswerEventConflictError extends Error {
+  constructor(questionTaskId: TaskId);
+}
+/** Normalized, authenticated input required to persist one inbound Signal. */
+interface CreateSignalInput {
+  repositoryId: RepositoryId;
+  source: SignalSource;
+  deliveryId: string;
+  replyTo: ReplyTo;
+  payload: unknown;
+}
+/** Outcome and optional human-readable context for one Signal decision. */
+interface DecideSignalInput {
+  readonly outcome: SignalOutcome;
+  readonly detail?: string;
+  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 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";
+  /** Required explicit versioned workflow contract. */
+  work: Task["work"];
+  /** Graph prerequisites that must succeed before this Task can run. */
+  dependencies?: readonly TaskId[];
+}
+/** 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. */
+type CreateTaskInput = CreateTaskInputBase & ({
+  origin: RootTaskOrigin;
+  parentTaskId?: never;
+  parentTaskAttempt?: never;
+  question?: TaskQuestion;
+} | ({
+  origin: TaskOrigin;
+  parentTaskId: TaskId;
+} & ({
+  question?: undefined;
+  parentTaskAttempt?: never;
+} | {
+  question: TaskQuestion;
+  parentTaskAttempt?: number;
+})));
+/** Authenticated operator and optional rationale for an immutable approval decision. */
+interface ApprovalDecision {
+  /** Authenticated operator making the decision. */
+  by: string;
+  reason?: string;
+}
+/** Authenticated operator and required rationale for denying a Task approval. */
+interface RejectionDecision {
+  /** Authenticated operator making the decision. */
+  by: string;
+  /** Human-readable reason retained on the immutable rejection receipt. */
+  reason: string;
+}
+/** Authenticated answer submitted for one open QuestionTask. */
+interface AnswerQuestionInput {
+  questionTaskId: TaskId;
+  answer: string;
+  answeredBy: string;
+}
+/** Persisted answer and affected question/parent Tasks after answering a question. */
+interface AnswerQuestionResult {
+  readonly answerEvent: AnswerEvent;
+  readonly questionTask: Task;
+  readonly parentTask: Task | null;
+}
+/** Exclusive binding of a Factory interaction to a Task or provider execution. */
+type AgentSessionBinding = {
+  taskId: TaskId;
+  execution?: never;
+} | {
+  execution: ExecutionReference;
+  taskId?: never;
+};
+/** Continuation Task, prompt context, and optional images cached on one Agent Session. */
+interface CacheContinuationContextInput {
+  readonly taskId: TaskId;
+  readonly context: string;
+  readonly attachments?: readonly ImageAttachment[];
+}
+/** Lifecycle-transition fields that may be changed without bypassing settlement or usage APIs. */
+type TaskPatch = Partial<Pick<Task, "changeId" | "reportRef" | "reservedUsd" | "reservedAt" | "question">>;
+/** One completed model step's usage, as eve's step.completed event carries it. */
+declare const stepUsageSchema: z.ZodObject<{
+  turnId: z.ZodString;
+  stepIndex: z.ZodNumber;
+  costUsd: z.ZodOptional<z.ZodNumber>;
+  inputTokens: z.ZodOptional<z.ZodNumber>;
+  outputTokens: z.ZodOptional<z.ZodNumber>;
+  cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+  cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Measured usage for one completed provider turn step, used for idempotent accounting. */
+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 {
+  patch?: TaskPatch;
+  reason?: string;
+  /** Classifies the transition receipt for lifecycle communication. */
+  phase?: ReceiptPhase;
+  /**
+   * Refuse unless the task is in this state at write time. Closes
+   * check-then-act races where the transition would also be legal from the
+   * state a concurrent writer moved the task into.
+   */
+  expectFrom?: TaskState;
+  /** Refuse late events from a previous execution attempt. */
+  expectAttempt?: number;
+  /** Refuse completion from a provider execution that has been replaced. */
+  expectExecution?: ExecutionReference;
+  /** Refuse cleanup or answers for a question that no longer blocks this task. */
+  expectQuestionTaskId?: TaskId;
+}
+/** Destination-correlated data and concurrency fences for one Task transition. */
+type TaskTransitionOptions<To extends TaskState = TaskState> = To extends "needs_human" ? TaskTransitionContext & {
+  /** Actionable description required whenever a Task enters needs_human. */
+  needsHumanAction: string;
+  /** Open child question required when the Task is not itself a QuestionTask. */
+  questionTaskId?: TaskId;
+  output?: never;
+  reuseRecordedOutput?: never;
+} : To extends "succeeded" ? TaskTransitionContext & ({
+  /** Candidate output validated against the Task's exact workflow. */
+  output: unknown;
+  reuseRecordedOutput?: never;
+} | {
+  output?: never;
+  /** Explicitly finish with output already persisted by the work store. */
+  reuseRecordedOutput: true;
+}) & {
+  needsHumanAction?: never;
+  questionTaskId?: never;
+} : TaskTransitionContext & {
+  output?: never;
+  reuseRecordedOutput?: never;
+  needsHumanAction?: never;
+  questionTaskId?: never;
+};
+/** Argument tuple requiring destination-specific data only for constrained transitions. */
+type TaskTransitionArguments<To extends TaskState> = To extends "needs_human" | "succeeded" ? [options: TaskTransitionOptions<To>] : [options?: TaskTransitionOptions<To>];
+/** Pull-request identity, ownership, and initial trust evidence used to create a Change. */
+interface CreateChangeInput {
+  repositoryId: RepositoryId;
+  taskId?: TaskId;
+  groupId?: TaskId;
+  prNumber: number;
+  prUrl: string;
+  author: string;
+  risk: ChangeLevel;
+  confidence: ChangeLevel;
+  evidence: Change["evidence"];
+}
+/** 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;
+}
+/** Destination-correlated patch and audit reason accompanying a Change transition. */
+type ChangeTransitionOptions<To extends ChangeState = ChangeState> = To extends "merged" ? Omit<ChangeTransitionContext, "patch"> & {
+  /** The merge actor must be recorded when a Change first enters its merged lifecycle. */
+  patch: ChangePatch & {
+    decidedBy: string;
+  };
+} : ChangeTransitionContext;
+/** Argument tuple requiring merge attribution for the transition into merged. */
+type ChangeTransitionArguments<To extends ChangeState> = To extends "merged" ? [options: ChangeTransitionOptions<To>] : [options?: ChangeTransitionOptions<To>];
+/** Factory, month, and configured limits used to create or refresh a monthly Budget. */
+interface EnsureBudgetInput {
+  factoryId: FactoryId;
+  month: BudgetMonth;
+  limits: Budget["limits"];
+}
+/** Monthly Budget returned with whether this call durably stamped a notice. */
+interface BudgetNoticeStampResult {
+  readonly budget: Budget;
+  readonly stamped: boolean;
+}
+/** 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. */
+interface RetryOutboxMessageInput {
+  readonly attempt: number;
+  readonly reason: string;
+  readonly delayMs: number;
+}
+interface AppendReceiptInputBase<State extends ReceiptState, Kind extends ReceiptKind> {
+  repositoryIds: RepositoryIds;
+  taskId?: TaskId;
+  changeId?: ChangeId;
+  kind: Kind;
+  state: State;
+  reason?: string;
+  attempt?: number;
+  execution?: ExecutionReference;
+  /** Same key twice appends one receipt and returns the existing one. */
+  dedupeKey?: string;
+}
+type AppendReceiptCost<State extends ReceiptState> = State extends "settled" ? {
+  cost: Cost;
+} : {
+  cost?: never;
+};
+type AppendReceiptDelivery<Phase extends ReceiptPhase | undefined> = Phase extends "communication" ? {
+  phase: Phase;
+  delivery?: ReceiptDelivery;
+} : {
+  phase?: Phase;
+  delivery?: never;
+};
+type AppendReceiptDecision<Kind extends ReceiptKind, State extends ReceiptState> = Kind extends "change" ? {
+  decidedBy?: string;
+} : State extends "approved" | "rejected" ? {
+  decidedBy?: string;
+} : {
+  decidedBy?: never;
+};
+type AppendReceiptCallInput<State extends ReceiptState, Kind extends ReceiptKind, Phase extends ReceiptPhase | undefined> = AppendReceiptInputBase<State, Kind> & AppendReceiptCost<State> & AppendReceiptDelivery<Phase> & AppendReceiptDecision<Kind, State>;
+/** Subject, event, cost, and deduplication input for appending immutable audit evidence. */
+type AppendReceiptInput<State extends ReceiptState = StandardReceiptState, Kind extends ReceiptKind = StandardReceiptKind, Phase extends ReceiptPhase | undefined = StandardReceiptPhase | "communication" | "workflow" | undefined> = State extends ReceiptState ? Kind extends ReceiptKind ? Phase extends ReceiptPhase | undefined ? AppendReceiptInputBase<State, Kind> & AppendReceiptCost<State> & AppendReceiptDelivery<Phase> & AppendReceiptDecision<Kind, State> : never : never : never;
+/** Error raised when an idempotent session operation conflicts with its original intent. */
+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">;
+  /** Durable, task-scoped external-effect references and reconciliation stamps. */
+  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>;
+    attachTask(input: {
+      owner: string;
+      taskId: TaskId;
+      agent: string;
+      message: string;
+    }): Promise<AgentSession>;
+    attachConversation(input: {
+      owner: string;
+      agent: string;
+      message: string;
+      execution: ExecutionReference;
+      external: NonNullable<AgentSession["external"]>;
+      createdAt?: string;
+    }): Promise<AgentSession>;
+    cacheContinuationContext(id: AgentSessionId, input: CacheContinuationContextInput): Promise<string>;
+    continue(id: AgentSessionId, input: {
+      operationId: string;
+      parentTaskId: TaskId;
+      agent: string;
+      message: string;
+      attachments?: readonly ImageAttachment[];
+    }): Promise<AgentSession>;
+    get(id: AgentSessionId): Promise<AgentSession | null>;
+    list(): Promise<readonly AgentSession[]>;
+    /** Compact session snapshots from fixed shards for discovery; large cached continuation context is omitted. */
+    summaries(): Promise<readonly AgentSession[]>;
+    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;
+    }): Promise<Signal>;
+    updateTriage(id: SignalId, attempt: number, observation: Pick<SignalTriage, "state" | "failure" | "sessionId">): Promise<Signal>;
+    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>;
+    answerQuestion(input: AnswerQuestionInput): Promise<AnswerQuestionResult>;
+    /** Grant a required approval. The task stays queued; dispatch may now take it. */
+    approve(id: TaskId, decision: ApprovalDecision): Promise<Task>;
+    /** Immutable human decision, addressed directly by Task ID. */
+    approvalReceipt(id: TaskId): Promise<Receipt | null>;
+    /** Deny a required approval. The task is cancelled with the reason. */
+    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.
+     *
+     * @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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Stamp a QuestionTask and the parent it currently blocks after Slack delivery.
+     * An attempt guard rejects confirmations from an earlier question episode.
+     * Retrying repairs either stamp independently; persistence errors propagate.
+     */
+    recordNeedsHumanDelivery(id: TaskId, options?: {
+      at?: string;
+      attempt?: number;
+    }): Promise<Task>;
+    /** Tasks addressed to one connector or operator conversation without a collection scan. */
+    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;
+      kind: Kind;
+      phase?: Phase;
+    }): Promise<Receipt>;
+    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
+     * preserves notices. Safe under concurrent sweeps.
+     */
+    ensure(input: EnsureBudgetInput): Promise<Budget>;
+    get(month: BudgetMonth): Promise<Budget | null>;
+    /**
+     * Write-once notice stamp. `stamped` is false when the notice was already
+     * set or a concurrent stamp won, so callers notify at most once.
+     */
+    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>;
+    claim(id: OutboxId, leaseMs?: number): Promise<OutboxMessage | null>;
+    retry(id: OutboxId, input: RetryOutboxMessageInput): Promise<OutboxMessage | null>;
+    complete(id: OutboxId, attempt: number): Promise<OutboxMessage | null>;
+    pending(limit?: number): Promise<readonly OutboxMessage[]>;
+  };
+}
+/** 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;
+  /**
+   * 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.
+ *
+ * @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, TaskAttemptConflictError, TaskExecutionFence, TaskPatch, TaskTransitionArguments, TaskTransitionOptions, UpdateChangeEvidenceInput, createStores };
+//# sourceMappingURL=engine.d.mts.map