@vercel/factory 0.0.13 → 0.0.15

package/dist/store/driver.mjs

@@ -0,0 +1,42 @@
+//#region src/store/driver.ts
+/** Error raised when an insert targets an already occupied storage key. */
+var RecordExistsError = class extends Error {
+	constructor(collection, id) {
+		super(`record "${id}" already exists in "${collection}"`);
+		this.name = "RecordExistsError";
+	}
+};
+/** Error raised when an operation requires a storage record that does not exist. */
+var RecordNotFoundError = class extends Error {
+	constructor(collection, id) {
+		super(`record "${id}" not found in "${collection}"`);
+		this.name = "RecordNotFoundError";
+	}
+};
+/** Error raised when atomic update loses its expected-version comparison. */
+var VersionConflictError = class extends Error {
+	constructor(collection, id, expectedVersion) {
+		super(`record "${id}" in "${collection}" changed since version ${expectedVersion} was read`);
+		this.name = "VersionConflictError";
+	}
+};
+/**
+* A transient infrastructure failure (network error, 5xx/429 response) that
+* a driver's own bounded, backed-off low-level retries could not resolve.
+* Distinct from VersionConflictError (a concurrent writer legitimately won)
+* and from validation or "already exists" errors (the request itself is
+* rejected): the same operation may still succeed if retried again later,
+* but every caller retrying on this error must keep its own bound so a real
+* outage surfaces as a failure instead of hanging a dispatch cycle.
+*/
+var TransientStoreError = class extends Error {
+	constructor(collection, id, cause) {
+		const reason = cause instanceof Error ? cause.message : String(cause);
+		super(`record "${id}" in "${collection}" failed after transient retries were exhausted: ${reason}`, { cause: cause instanceof Error ? cause : void 0 });
+		this.name = "TransientStoreError";
+	}
+};
+//#endregion
+export { RecordExistsError, RecordNotFoundError, TransientStoreError, VersionConflictError };
+
+//# sourceMappingURL=driver.mjs.map

package/dist/store/driver.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.mjs","names":[],"sources":["../../src/store/driver.ts"],"sourcesContent":["/** Closed set of persistence collections understood by Factory store drivers. */\nexport type CollectionName =\n  | \"repositories\"\n  | \"signals\"\n  | \"tasks\"\n  | \"changes\"\n  | \"receipts\"\n  | \"budgets\"\n  | \"answers\"\n  | \"sessions\"\n  | \"externalSessions\"\n  | \"transcripts\"\n  | \"images\"\n  | \"questionRoutes\"\n  | \"taskCatalogs\"\n  | \"changeCatalogs\"\n  | \"sessionCatalogs\"\n  | \"externalSessionCatalogs\"\n  | \"taskRoutes\"\n  | \"outboxQueues\"\n  | \"outboxDeliveries\"\n  | \"taskGraphs\"\n  | \"taskMessages\"\n  | \"taskEffects\"\n  | \"taskInboxes\"\n  | \"taskMessageProcessing\"\n  | \"taskMessageDecisions\"\n  | \"taskMessageDiscards\"\n  | \"plannerActivations\"\n  | \"plannerCancellations\";\n\n/** Opaque persisted value paired with its compare-and-swap version. */\nexport interface StoredRecord {\n  readonly value: unknown;\n  readonly version: number;\n}\n\n/** Collection-listing entry containing its storage key and versioned record. */\nexport interface StoredEntry {\n  readonly id: string;\n  readonly record: StoredRecord;\n}\n\n/** Collection, storage key, and opaque value for one insert-only write. */\nexport interface InsertStoreRecordInput {\n  readonly collection: CollectionName;\n  readonly id: string;\n  readonly value: unknown;\n}\n\n/** Collection, storage key, opaque value, and compare-and-swap version for one update. */\nexport interface UpdateStoreRecordInput extends InsertStoreRecordInput {\n  readonly expectedVersion: number;\n}\n\n/** Error raised when an insert targets an already occupied storage key. */\nexport class RecordExistsError extends Error {\n  constructor(collection: CollectionName, id: string) {\n    super(`record \"${id}\" already exists in \"${collection}\"`);\n    this.name = \"RecordExistsError\";\n  }\n}\n\n/** Error raised when an operation requires a storage record that does not exist. */\nexport class RecordNotFoundError extends Error {\n  constructor(collection: CollectionName, id: string) {\n    super(`record \"${id}\" not found in \"${collection}\"`);\n    this.name = \"RecordNotFoundError\";\n  }\n}\n\n/** Error raised when atomic update loses its expected-version comparison. */\nexport class VersionConflictError extends Error {\n  constructor(collection: CollectionName, id: string, expectedVersion: number) {\n    super(`record \"${id}\" in \"${collection}\" changed since version ${expectedVersion} was read`);\n    this.name = \"VersionConflictError\";\n  }\n}\n\n/**\n * A transient infrastructure failure (network error, 5xx/429 response) that\n * a driver's own bounded, backed-off low-level retries could not resolve.\n * Distinct from VersionConflictError (a concurrent writer legitimately won)\n * and from validation or \"already exists\" errors (the request itself is\n * rejected): the same operation may still succeed if retried again later,\n * but every caller retrying on this error must keep its own bound so a real\n * outage surfaces as a failure instead of hanging a dispatch cycle.\n */\nexport class TransientStoreError extends Error {\n  constructor(collection: CollectionName, id: string, cause: unknown) {\n    const reason = cause instanceof Error ? cause.message : String(cause);\n    super(\n      `record \"${id}\" in \"${collection}\" failed after transient retries were exhausted: ${reason}`,\n      { cause: cause instanceof Error ? cause : undefined },\n    );\n    this.name = \"TransientStoreError\";\n  }\n}\n\n/**\n * Raw persistence contract. Drivers store opaque values and enforce nothing\n * about their content; every invariant lives in the engine above. `update`\n * must be an atomic compare-and-swap on `expectedVersion`. A driver may\n * throw TransientStoreError for a read or write that failed only because of\n * infrastructure trouble (network errors, 5xx/429 responses); it must not\n * use TransientStoreError for version conflicts or malformed input.\n */\nexport interface StoreDriver {\n  readonly name: string;\n  get(collection: CollectionName, id: string): Promise<StoredRecord | null>;\n  insert(input: InsertStoreRecordInput): Promise<void>;\n  update(input: UpdateStoreRecordInput): Promise<void>;\n  list(collection: CollectionName): Promise<readonly StoredEntry[]>;\n}\n"],"mappings":";;AAwDA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,YAAY,YAA4B,IAAY;EAClD,MAAM,WAAW,GAAG,uBAAuB,WAAW,EAAE;EACxD,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,sBAAb,cAAyC,MAAM;CAC7C,YAAY,YAA4B,IAAY;EAClD,MAAM,WAAW,GAAG,kBAAkB,WAAW,EAAE;EACnD,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,uBAAb,cAA0C,MAAM;CAC9C,YAAY,YAA4B,IAAY,iBAAyB;EAC3E,MAAM,WAAW,GAAG,QAAQ,WAAW,0BAA0B,gBAAgB,UAAU;EAC3F,KAAK,OAAO;CACd;AACF;;;;;;;;;;AAWA,IAAa,sBAAb,cAAyC,MAAM;CAC7C,YAAY,YAA4B,IAAY,OAAgB;EAClE,MAAM,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EACpE,MACE,WAAW,GAAG,QAAQ,WAAW,mDAAmD,UACpF,EAAE,OAAO,iBAAiB,QAAQ,QAAQ,KAAA,EAAU,CACtD;EACA,KAAK,OAAO;CACd;AACF"}

package/dist/store/engine.d.mts

@@ -0,0 +1,485 @@
+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 {
+  repositoryIds: RepositoryIds;
+  kind: Task["kind"];
+  replyTo: ReplyTo;
+  /** Same key creates one task and returns it on workflow retries. */
+  dedupeKey?: string;
+  area?: string;
+  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 = {
+  signalId: SignalId;
+  operator?: string;
+} | {
+  signalId?: SignalId;
+  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 {
+  readonly attempt: number;
+  readonly execution: ExecutionReference;
+}
+/** Provider execution and optional attempt fence recorded on one running Task. */
+interface RecordTaskExecutionInput {
+  readonly execution: ExecutionReference;
+  readonly expectAttempt?: number;
+}
+/** One measured usage step and optional exact-execution fence for a Task. */
+interface RecordTaskUsageInput {
+  readonly step: StepUsage;
+  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">>;
+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 {
+  readonly cost: Cost;
+  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 {
+  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;
+  messages: TaskMessageStore;
+  work: TaskWorkStore;
+  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>;
+  };
+  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[]>;
+  };
+  sessions: {
+    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>;
+  };
+  repositories: {
+    put(repository: Repository): Promise<Repository>;
+    get(id: RepositoryId): Promise<Repository | null>;
+    list(): Promise<readonly Repository[]>;
+  };
+  signals: {
+    create(input: CreateSignalInput): Promise<Signal>;
+    get(id: SignalId): 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[]>;
+  };
+  tasks: {
+    create(input: CreateTaskInput): Promise<Task>;
+    get(id: TaskId): Promise<Task | null>;
+    findOpenQuestions(replyTo: ReplyTo): Promise<readonly Task[]>;
+    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. Refused unless the task is running.
+     */
+    recordExecution(id: TaskId, input: RecordTaskExecutionInput): Promise<Task>;
+    /** Add one model step's usage to the task. Idempotent per (turnId, stepIndex). Never settles. */
+    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.
+     */
+    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[]>;
+  };
+  changes: {
+    create(input: CreateChangeInput): Promise<Change>;
+    get(id: ChangeId): Promise<Change | null>;
+    transition<To extends ChangeState>(id: ChangeId, to: To, ...args: ChangeTransitionArguments<NoInfer<To>>): Promise<ChangeInState<To>>;
+    list(): Promise<readonly Change[]>;
+  };
+  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[]>;
+  };
+  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>;
+  };
+  answers: {
+    get(id: AnswerId): Promise<AnswerEvent | null>;
+  };
+  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 {
+  driver: StoreDriver;
+  /** Awaited post-commit wakeups. Canonical work remains recoverable if publishing fails. */
+  workNotifications?: WorkNotifications;
+  now?: IsoDateTimeClock;
+  workflows?: WorkflowRegistry;
+  messages?: {
+    protocols: TaskMessageProtocols;
+    authorize: TaskMessageAuthorize;
+  };
+}
+/** Creates the validating Factory store engine over a deliberately policy-free driver. */
+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 };
+//# sourceMappingURL=engine.d.mts.map