@vercel/factory 0.0.12 → 0.0.13

package/dist/index.d.mts

@@ -1,8 +1,7 @@
-import { a as StoredEntry, i as StoreDriver, n as RecordExistsError, o as StoredRecord, r as RecordNotFoundError, s as VersionConflictError, t as CollectionName } from "./driver-CrZsy7sm.mjs";
-import { a as factoryConfigSchema, i as factoryConfigRepositorySchema, n as FactoryConfigInput, r as defineFactory, t as FactoryConfig } from "./factory-config-Bu4mklm9.mjs";
+import { a as StoredEntry, i as StoreDriver, n as RecordExistsError, o as StoredRecord, r as RecordNotFoundError, s as VersionConflictError, t as CollectionName } from "./driver-BJutB0PE.mjs";
+import { a as defineFactory, c as factoryConfigSchema, i as defaultExecutionPolicy, n as FactoryConfig, o as executionPolicySchema, r as FactoryConfigInput, s as factoryConfigRepositorySchema, t as ExecutionPolicy } from "./factory-config-D2yU3G0c.mjs";
 import { a as signalSchema, c as ReplyTo, d as replyToSchema, f as schemaVersionSchema, i as signalOutcomeSchema, l as SCHEMA_VERSION, m as vocabularySchema, n as SignalOutcome, o as signalSourceSchema, p as usdSchema, r as SignalSource, s as standardSignalSources, t as Signal, u as isoDateTimeSchema } from "./signal-CHVEmzvI.mjs";
-import { $ as Cost, A as FactoryStores, At as repositoryIdsSchema, B as standardTaskKinds, C as ChangePatch, Ct as RepositoryId, D as CreateStoresOptions, Dt as factoryIdSchema, E as CreateSignalInput, Et as changeIdSchema, F as TaskApproval, G as taskOriginSchema, H as taskDevboxSchema, I as TaskKind, J as taskStateSchema, K as taskQuestionSchema, L as TaskState, M as TaskTransitionOptions, Mt as taskIdSchema, N as createStores, O as CreateTaskInput, Ot as receiptIdSchema, P as Task, Q as repositorySlugSchema, R as coordinationRepositoryIdsSchema, S as ChangeAssociationError, St as ReceiptId, T as CreateChangeInput, Tt as TaskId, U as taskExecutionRepositoryIdsSchema, V as taskApprovalSchema, W as taskKindSchema, X as RepositorySlug, Y as Repository, Z as repositorySchema, _ as findingVerificationMethodSchema, _t as changeSchema, a as approvalRuleSchema, at as receiptKindSchema, b as ApprovalDecision, bt as ChangeId, c as Finding, ct as receiptStateSchema, d as FindingVerification, dt as standardReceiptStates, et as Receipt, f as findingCategorySchema, ft as Change, g as findingVerificationLevelSchema, gt as changeEvidenceSchema, h as findingSchema, ht as Level, i as approvalPolicySchema, it as costSchema, j as TaskPatch, jt as signalIdSchema, k as DecideSignalOptions, kt as repositoryIdSchema, l as FindingCategory, lt as standardReceiptKinds, m as findingPrioritySchema, mt as ChangeState, n as ApprovalRule, nt as ReceiptPhase, o as defaultApprovalPolicy, ot as receiptPhaseSchema, p as findingFingerprint, pt as ChangeEvidence, q as taskSchema, r as ApprovalSubject, rt as ReceiptState, s as requiresApproval, st as receiptSchema, t as ApprovalPolicy, tt as ReceiptKind, u as FindingPriority, ut as standardReceiptPhases, v as findingVerificationSchema, vt as changeStateSchema, w as ChangeTransitionOptions, wt as SignalId, x as ApprovalError, xt as FactoryId, y as AppendReceiptInput, yt as levelSchema, z as harnessSchema } from "./approval-CIXB8IF8.mjs";
-import { z } from "zod";
+import { $ as Cost, $t as taskSchema, A as AppendReceiptInput, At as TaskId, B as DecideSignalOptions, Bt as TaskApproval, C as findingCategorySchema, Ct as budgetMonthSchema, D as findingVerificationLevelSchema, Dt as ReceiptId, E as findingSchema, Et as FactoryId, F as ChangeTransitionOptions, Ft as repositoryIdsSchema, G as StepUsage, Gt as executionReferenceSchema, H as FactoryStores, Ht as TaskState, I as CreateChangeInput, It as signalIdSchema, J as createStores, Jt as taskApprovalSchema, K as TaskPatch, Kt as harnessSchema, L as CreateSignalInput, Lt as taskIdSchema, M as ApprovalError, Mt as factoryIdSchema, N as ChangeAssociationError, Nt as receiptIdSchema, O as findingVerificationMethodSchema, Ot as RepositoryId, P as ChangePatch, Pt as repositoryIdSchema, Q as repositorySlugSchema, Qt as taskQuestionSchema, R as CreateStoresOptions, Rt as ExecutionReference, S as FindingVerification, St as budgetLimitsSchema, T as findingPrioritySchema, Tt as ChangeId, U as SettleTaskOptions, Ut as TaskUsage, V as EnsureBudgetInput, Vt as TaskKind, W as SettlementError, Wt as coordinationRepositoryIdsSchema, X as RepositorySlug, Xt as taskKindSchema, Y as Repository, Yt as taskExecutionRepositoryIdsSchema, Z as repositorySchema, Zt as taskOriginSchema, _ as defaultApprovalPolicy, _t as changeSchema, a as DispatchRefusedError, at as receiptKindSchema, b as FindingCategory, bt as Budget, c as AgentRouteInput, ct as receiptStateSchema, d as defineAgentRoutes, dt as standardReceiptStates, en as taskStateSchema, et as Receipt, f as ApprovalPolicy, ft as Change, g as approvalRuleSchema, gt as changeEvidenceSchema, h as approvalPolicySchema, ht as Level, i as DispatchOptions, it as costSchema, j as ApprovalDecision, jt as changeIdSchema, k as findingVerificationSchema, kt as SignalId, l as AgentRouteRegistry, lt as standardReceiptKinds, m as ApprovalSubject, mt as ChangeState, n as DEFAULT_MAX_LAUNCH_ATTEMPTS, nt as ReceiptPhase, o as dispatchTask, ot as receiptPhaseSchema, p as ApprovalRule, pt as ChangeEvidence, q as TaskTransitionOptions, qt as standardTaskKinds, r as DispatchBudget, rt as ReceiptState, s as AgentRoute, st as receiptSchema, t as BudgetExhaustedError, tn as taskUsageSchema, tt as ReceiptKind, u as agentRouteSchema, ut as standardReceiptPhases, v as requiresApproval, vt as changeStateSchema, w as findingFingerprint, wt as budgetSchema, x as FindingPriority, xt as BudgetLimits, y as Finding, yt as levelSchema, z as CreateTaskInput, zt as Task } from "./dispatch-B77cuPxh.mjs";
 //#region src/briefs.d.ts
 /** The finding behind a task, when its signal carries one. */
 declare function findingForTask(stores: FactoryStores, task: Task): Promise<Finding | null>;
@@ -16,6 +15,79 @@ declare function scanBrief(task: Task, repository: Repository): string;
 /** The verifier's starting message for a recorded pull request. */
 declare function verificationBrief(task: Task, repository: Repository, change: Change): string;
 //#endregion
+//#region src/budget.d.ts
+/**
+ * Stable factory identity for budget rows. Nothing mints factory ids yet, so
+ * the app derives one from a deployment-stable seed such as the Vercel
+ * project id.
+ */
+declare function deriveFactoryId(seed: string): FactoryId;
+/** The budget month ("YYYY-MM", UTC) a timestamp falls into. */
+declare function budgetMonthOf(isoDateTime: string): string;
+/**
+ * Monthly spend is derived from task rows, never stored: each task counts its
+ * settled cost once that exists, otherwise its held reservation. A task
+ * settles once, so a settled row never also counts its reservation.
+ * Attribution uses the reservation time so tasks that wait across a month
+ * boundary charge the month they actually ran in.
+ */
+declare function computeMonthSpendUsd(tasks: readonly Task[], month: string): number;
+type BudgetStatus = "ok" | "warning" | "exhausted";
+/**
+ * True when one more per-task slice fits under the monthly total. Dispatch
+ * refuses on this exact predicate and budgetStatus reports "exhausted" on its
+ * negation, so refusing and reporting can never disagree.
+ */
+declare function canReserve(spendUsd: number, limits: Pick<BudgetLimits, "totalUsd" | "perTaskReservationUsd">): boolean;
+declare function budgetStatus(spendUsd: number, limits: Pick<BudgetLimits, "totalUsd" | "perTaskReservationUsd" | "warningPercent">): BudgetStatus;
+interface SettleSweepOptions {
+  /** How long a terminal task waits for late usage before the sweep settles it. */
+  graceMinutes?: number;
+  now?: () => Date;
+}
+interface SettleSweepResult {
+  settled: {
+    taskId: TaskId;
+    totalUsd: number;
+  }[];
+}
+/**
+ * Settle reserved terminal tasks the session hook did not: a task that ended
+ * after its session (a change verified later) or whose session died. Settles
+ * at the recorded usage, or at zero with a warning reason when none was
+ * recorded within the grace window.
+ */
+declare function sweepSettlements(stores: FactoryStores, options?: SettleSweepOptions): Promise<SettleSweepResult>;
+interface BudgetNotice {
+  outcome: "budget_warning" | "budget_exhausted";
+  month: string;
+  spendUsd: number;
+  limits: BudgetLimits;
+}
+interface BudgetSweepOptions {
+  factoryId: FactoryId;
+  limits: BudgetLimits;
+  /** Defaults to the current UTC month. */
+  month?: string;
+  now?: () => Date;
+  /** Owner-only delivery; invoked at most once per month per outcome. */
+  notify?: (notice: BudgetNotice) => Promise<void>;
+}
+interface BudgetSweepResult {
+  month: string;
+  spendUsd: number;
+  status: BudgetStatus;
+  warned: boolean;
+  exhausted: boolean;
+}
+/**
+ * Ensure the month's budget row, derive spend, and record threshold crossings
+ * write-once. Delivery comes first and the stamp only lands after it, so a
+ * failed notification retries on the next sweep instead of being lost; the
+ * write-once stamp still keeps each threshold to one message per month.
+ */
+declare function sweepBudget(stores: FactoryStores, options: BudgetSweepOptions): Promise<BudgetSweepResult>;
+//#endregion
 //#region src/changes.d.ts
 interface AdoptPullRequestInput {
   repositoryId: RepositoryId;
@@ -26,11 +98,19 @@ interface AdoptPullRequestInput {
 declare function adoptPullRequest(stores: Pick<FactoryStores, "changes">, input: AdoptPullRequestInput): Promise<Change>;
 //#endregion
 //#region src/coordination.d.ts
-interface CreateCoordinationInput {
+interface CreateCoordinationInputBase {
   repositoryIds: readonly [RepositoryId, RepositoryId, ...RepositoryId[]];
-  signalId: SignalId;
   replyTo: ReplyTo;
+  /** Same key recreates neither the parent nor its repository-scoped children. */
+  dedupeKey?: string;
 }
+type CreateCoordinationInput = CreateCoordinationInputBase & ({
+  signalId: SignalId;
+  operator?: never;
+} | {
+  operator: string;
+  signalId?: never;
+});
 interface CoordinationPlan {
   parent: Task;
   children: readonly Task[];
@@ -57,33 +137,6 @@ declare function createCoordination(stores: FactoryStores, input: CreateCoordina
 /** Reconcile a coordination parent from its direct children without ever dispatching the parent. */
 declare function reconcileCoordination(stores: FactoryStores, parentTaskId: TaskId, options: ReconcileCoordinationOptions): Promise<CoordinationReconciliation>;
 //#endregion
-//#region src/dispatch.d.ts
-declare class DispatchRefusedError extends Error {
-  readonly taskId: TaskId;
-  readonly reason: string;
-  constructor(taskId: TaskId, reason: string);
-}
-interface DispatchOptions {
-  /**
-   * Starts the durable execution for the task (an Eve agent run). Runs after
-   * the task has won the queued -> running transition. The execution owns its
-   * own provisioning: it creates its Devbox as its first step and patches the
-   * task record with the result.
-   */
-  launch: (task: Task) => Promise<void>;
-  /** How many launches to try before the task fails for good; a failure re-queues for the next sweep. */
-  maxLaunchAttempts?: number;
-}
-declare const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;
-/**
- * The handshake between recorded work and execution: win the store-gated
- * transition (at most one dispatcher can succeed), then start the run. A
- * launch failure re-queues the task (bumping its attempt) until the attempt
- * limit, then fails it; a crash between the transition and the launch leaves
- * a running task with no execution, which the sweep reaps.
- */
-declare function dispatchTask(stores: FactoryStores, taskId: TaskId, options: DispatchOptions): Promise<Task>;
-//#endregion
 //#region src/metrics.d.ts
 /**
  * The derived review bucket from the default risk x confidence table. Derived
@@ -147,32 +200,13 @@ interface RepositoryHealth {
   reasons: string[];
 }
 /**
- * Green, yellow, or red from rows, never from a model. Budget and onboarding
- * signals are not evaluated yet: budgets do not settle and onboarding
- * investigations are not recorded, so those spec rules have no rows to read.
+ * Green, yellow, or red from rows, never from a model. Budget threshold and
+ * onboarding rules are not evaluated here yet: budget notices live on the
+ * budgets collection (not in these rows), and onboarding investigations are
+ * not recorded.
  */
 declare function computeRepositoryHealth(rows: LedgerRows, options?: HealthOptions): RepositoryHealth;
 //#endregion
-//#region src/schema/budget.d.ts
-declare const budgetMonthSchema: z.ZodString;
-declare const budgetSchema: z.ZodObject<{
-  schemaVersion: z.ZodLiteral<1>;
-  factoryId: z.ZodString;
-  month: z.ZodString;
-  limits: z.ZodObject<{
-    totalUsd: z.ZodNumber;
-    investigationUsd: z.ZodNumber;
-    perTaskReservationUsd: z.ZodNumber;
-    warningPercent: z.ZodNumber;
-    perRepositoryUsd: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
-  }, z.core.$strict>;
-  notices: z.ZodObject<{
-    warningAt: z.ZodOptional<z.ZodISODateTime>;
-    exhaustedAt: z.ZodOptional<z.ZodISODateTime>;
-  }, z.core.$strict>;
-}, z.core.$strict>;
-type Budget = z.infer<typeof budgetSchema>;
-//#endregion
 //#region src/schema/transitions.d.ts
 type TransitionActor = "system" | "reconciler" | "foreman" | "operator" | "webhook" | "human";
 interface Transition<State extends string> {
@@ -209,15 +243,41 @@ interface SignalCreator {
  */
 declare function createSignalCreator(stores: Pick<FactoryStores, "signals">): SignalCreator;
 //#endregion
+//#region src/stall.d.ts
+interface StallSweepOptions {
+  policy: ExecutionPolicy;
+  now?: () => Date;
+}
+interface StallSweepResult {
+  stalled: TaskId[];
+  requeued: TaskId[];
+  failed: TaskId[];
+}
+declare function stallWindowMinutes(policy: ExecutionPolicy, kind: Task["kind"]): number;
+/**
+ * The reconciler's stall pass. A running task whose execution has not
+ * progressed within its stall window is marked stalled; a stalled task is
+ * re-queued for a replacement attempt while attempts remain, and failed once
+ * they are exhausted. Only `running` tasks can stall: a task whose result has
+ * already been recorded (verifying, or terminal) is never retried by this
+ * pass. Coordination parents run only through their children and are skipped.
+ */
+declare function sweepStalled(stores: FactoryStores, options: StallSweepOptions): Promise<StallSweepResult>;
+//#endregion
 //#region src/store/memory.d.ts
 declare function createInMemoryDriver(): StoreDriver;
 //#endregion
 //#region src/sweep.d.ts
-/** Starts the agent for one task kind. Supplied by the app, which knows its agents' addresses. */
-type TaskLauncher = (task: Task, repository: Repository) => Promise<void>;
+/**
+ * Starts the agent for one task kind. Supplied by the app, which knows its
+ * agents' addresses. Returns the provider's execution reference when it has one.
+ */
+type TaskLauncher = (task: Task, repository: Repository) => Promise<ExecutionReference | void>;
 interface SweepOptions {
   /** Launcher per task kind, e.g. code_change -> foreman, security_scan -> security-scanner. */
   launchers: Readonly<Record<string, TaskLauncher>>;
+  /** Reserve-before-execution limits, passed through to every dispatch. */
+  budget?: DispatchBudget;
 }
 interface SweepResult {
   dispatched: string[];
@@ -250,5 +310,5 @@ interface VerificationTaskSweep {
 /** Ensure every recorded code change has exactly one durable verification task. */
 declare function ensureVerificationTasks(stores: FactoryStores): Promise<VerificationTaskSweep>;
 //#endregion
-export { AdoptPullRequestInput, AppendReceiptInput, ApprovalDecision, ApprovalError, ApprovalPolicy, ApprovalRule, ApprovalSubject, Budget, Change, ChangeAssociationError, ChangeEvidence, ChangeId, ChangePatch, ChangeState, ChangeTransitionOptions, CollectionName, CoordinationPlan, CoordinationReconciliation, Cost, CreateChangeInput, CreateCoordinationInput, CreateSignalInput, CreateStoresOptions, CreateTaskInput, DEFAULT_MAX_LAUNCH_ATTEMPTS, DecideSignalOptions, DispatchOptions, DispatchRefusedError, FactoryConfig, FactoryConfigInput, FactoryId, FactoryStores, Finding, FindingCategory, FindingPriority, FindingVerification, HealthColor, HealthOptions, InvalidTransitionError, LedgerMetrics, LedgerRows, Level, MetricsOptions, Receipt, ReceiptId, ReceiptKind, ReceiptPhase, ReceiptState, ReconcileCoordinationOptions, RecordExistsError, RecordNotFoundError, ReplyTo, Repository, RepositoryHealth, RepositoryId, RepositorySlug, ReviewBucket, SCHEMA_VERSION, Signal, SignalCreator, SignalId, SignalOutcome, SignalSource, StoreDriver, StoredEntry, StoredRecord, SweepOptions, SweepResult, Task, TaskApproval, TaskId, TaskKind, TaskLauncher, TaskPatch, TaskState, TaskTransitionOptions, Transition, TransitionActor, VerificationTaskSweep, VersionConflictError, adoptPullRequest, approvalPolicySchema, approvalRuleSchema, assertTransition, budgetMonthSchema, budgetSchema, changeEvidenceSchema, changeIdSchema, changeInitialState, changeSchema, changeStateSchema, changeTransitions, computeLedgerMetrics, computeRepositoryHealth, coordinationRepositoryIdsSchema, costSchema, createCoordination, createInMemoryDriver, createSignalCreator, createStores, defaultApprovalPolicy, defineFactory, dispatchTask, ensureVerificationTasks, factoryConfigRepositorySchema, factoryConfigSchema, factoryIdSchema, findingCategorySchema, findingFingerprint, findingForTask, findingPrioritySchema, findingSchema, findingVerificationLevelSchema, findingVerificationMethodSchema, findingVerificationSchema, fixBrief, harnessSchema, isTransitionAllowed, isoDateTimeSchema, legalNextStates, levelSchema, receiptIdSchema, receiptKindSchema, receiptPhaseSchema, receiptSchema, receiptStateSchema, reconcileCoordination, replyToSchema, repositoryIdSchema, repositoryIdsSchema, repositorySchema, repositorySlugSchema, requiresApproval, reviewBucket, scanBrief, schemaVersionSchema, signalIdSchema, signalInitialOutcome, signalOutcomeSchema, signalOutcomeTransitions, signalSchema, signalSourceSchema, standardReceiptKinds, standardReceiptPhases, standardReceiptStates, standardSignalSources, standardTaskKinds, sweepQueued, taskApprovalSchema, taskDevboxSchema, taskExecutionRepositoryIdsSchema, taskIdSchema, taskInitialState, taskKindSchema, taskOriginSchema, taskQuestionSchema, taskSchema, taskStateSchema, taskTransitions, terminalStates, usdSchema, verificationBrief, vocabularySchema };
+export { AdoptPullRequestInput, AgentRoute, AgentRouteInput, AgentRouteRegistry, AppendReceiptInput, ApprovalDecision, ApprovalError, ApprovalPolicy, ApprovalRule, ApprovalSubject, Budget, BudgetExhaustedError, BudgetLimits, BudgetNotice, BudgetStatus, BudgetSweepOptions, BudgetSweepResult, Change, ChangeAssociationError, ChangeEvidence, ChangeId, ChangePatch, ChangeState, ChangeTransitionOptions, CollectionName, CoordinationPlan, CoordinationReconciliation, Cost, CreateChangeInput, CreateCoordinationInput, CreateSignalInput, CreateStoresOptions, CreateTaskInput, DEFAULT_MAX_LAUNCH_ATTEMPTS, DecideSignalOptions, DispatchBudget, DispatchOptions, DispatchRefusedError, EnsureBudgetInput, ExecutionPolicy, ExecutionReference, FactoryConfig, FactoryConfigInput, FactoryId, FactoryStores, Finding, FindingCategory, FindingPriority, FindingVerification, HealthColor, HealthOptions, InvalidTransitionError, LedgerMetrics, LedgerRows, Level, MetricsOptions, Receipt, ReceiptId, ReceiptKind, ReceiptPhase, ReceiptState, ReconcileCoordinationOptions, RecordExistsError, RecordNotFoundError, ReplyTo, Repository, RepositoryHealth, RepositoryId, RepositorySlug, ReviewBucket, SCHEMA_VERSION, SettleSweepOptions, SettleSweepResult, SettleTaskOptions, SettlementError, Signal, SignalCreator, SignalId, SignalOutcome, SignalSource, StallSweepOptions, StallSweepResult, StepUsage, StoreDriver, StoredEntry, StoredRecord, SweepOptions, SweepResult, Task, TaskApproval, TaskId, TaskKind, TaskLauncher, TaskPatch, TaskState, TaskTransitionOptions, TaskUsage, Transition, TransitionActor, VerificationTaskSweep, VersionConflictError, adoptPullRequest, agentRouteSchema, approvalPolicySchema, approvalRuleSchema, assertTransition, budgetLimitsSchema, budgetMonthOf, budgetMonthSchema, budgetSchema, budgetStatus, canReserve, changeEvidenceSchema, changeIdSchema, changeInitialState, changeSchema, changeStateSchema, changeTransitions, computeLedgerMetrics, computeMonthSpendUsd, computeRepositoryHealth, coordinationRepositoryIdsSchema, costSchema, createCoordination, createInMemoryDriver, createSignalCreator, createStores, defaultApprovalPolicy, defaultExecutionPolicy, defineAgentRoutes, defineFactory, deriveFactoryId, dispatchTask, ensureVerificationTasks, executionPolicySchema, executionReferenceSchema, factoryConfigRepositorySchema, factoryConfigSchema, factoryIdSchema, findingCategorySchema, findingFingerprint, findingForTask, findingPrioritySchema, findingSchema, findingVerificationLevelSchema, findingVerificationMethodSchema, findingVerificationSchema, fixBrief, harnessSchema, isTransitionAllowed, isoDateTimeSchema, legalNextStates, levelSchema, receiptIdSchema, receiptKindSchema, receiptPhaseSchema, receiptSchema, receiptStateSchema, reconcileCoordination, replyToSchema, repositoryIdSchema, repositoryIdsSchema, repositorySchema, repositorySlugSchema, requiresApproval, reviewBucket, scanBrief, schemaVersionSchema, signalIdSchema, signalInitialOutcome, signalOutcomeSchema, signalOutcomeTransitions, signalSchema, signalSourceSchema, stallWindowMinutes, standardReceiptKinds, standardReceiptPhases, standardReceiptStates, standardSignalSources, standardTaskKinds, sweepBudget, sweepQueued, sweepSettlements, sweepStalled, taskApprovalSchema, taskExecutionRepositoryIdsSchema, taskIdSchema, taskInitialState, taskKindSchema, taskOriginSchema, taskQuestionSchema, taskSchema, taskStateSchema, taskTransitions, taskUsageSchema, terminalStates, usdSchema, verificationBrief, vocabularySchema };
 //# sourceMappingURL=index.d.mts.map