@makerkit/workers-outbox 0.0.0-stage → 0.0.2

package/dist/create-outbox-C4vdn6Dr.d.mts

@@ -0,0 +1,959 @@
+import { t as SqlRunner } from "./catalog-DzvOuOHQ.mjs";
+import { i as QueueSender, n as LaneConnection, r as OutboxDb, t as Clock } from "./types-ClomUJ_8.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+type MessageRedactor = (message: string) => string;
+/** Database-only and re-runnable: it may run again after a transient fault. */
+type CommitFn = (tx: OutboxDb) => Promise<void>;
+/** Expected results are values; throw only for unanticipated faults (`classify` maps them). */
+type HandlerOutcome = {
+  type: 'ok';
+  commit?: CommitFn;
+} | {
+  type: 'retry';
+  code: string;
+  afterMs?: number;
+  message?: string;
+} | {
+  type: 'fail';
+  code: string;
+  message?: string;
+} | {
+  type: 'cancel';
+  reason: string;
+};
+/** `commit` runs in the settle transaction: its writes and `succeeded` land together, lease-fenced. */
+declare const ok: (options?: {
+  commit?: CommitFn;
+}) => HandlerOutcome;
+/** `after` overrides the backoff (e.g. a provider's Retry-After). */
+declare const retry: (input: {
+  code: string;
+  after?: number | undefined;
+  message?: string | undefined;
+}) => HandlerOutcome;
+declare const fail: (input: {
+  code: string;
+  message?: string | undefined;
+}) => HandlerOutcome;
+declare const cancel: (input: {
+  reason: string;
+}) => HandlerOutcome;
+/** Budgets count attempts since the last replay; crashes are charged only to `maxCrashes`. */
+interface RetryPolicy {
+  /** Handled attempts including the first; `Infinity` never gives up. */
+  readonly maxAttempts: number;
+  readonly backoff: {
+    readonly baseMs: number;
+    readonly maxMs: number;
+    readonly factor: number;
+  };
+  /** Consecutive same-code attempt caps; reaching one is exhaustion. */
+  readonly perCode: Readonly<Record<string, number>>;
+  /** Consecutive crashes before `dead(crash_loop)`. */
+  readonly maxCrashes: number;
+  readonly codes: Readonly<Record<string, CodeRule>>;
+}
+interface CodeRule {
+  /** Only ever widens the job's `maxAttempts`. */
+  readonly maxAttempts?: number;
+  /** This code's `maxAttempts` keeps applying to every later code until replay. */
+  readonly sticky: boolean;
+  /** Milliseconds. */
+  readonly maxDelayMs?: number;
+  readonly onExhaustion: 'dead' | 'cancel';
+}
+/** A number is a streak cap; an object adds `CodeRule` fields plus `streak`. */
+type CodeRuleInput = number | {
+  streak?: number;
+  maxAttempts?: number;
+  sticky?: boolean;
+  maxDelayMs?: number;
+  onExhaustion?: 'dead' | 'cancel';
+};
+interface RetryPolicyInput {
+  maxAttempts?: number;
+  backoff?: {
+    baseMs?: number;
+    maxMs?: number;
+    factor?: number;
+  };
+  /** Merged over the defaults; an object without `streak` keeps the default cap. */
+  perCode?: Record<string, CodeRuleInput>;
+  maxCrashes?: number;
+}
+interface JobContext<Deps = unknown> {
+  readonly jobId: string;
+  readonly kind: string;
+  /** 1-based over the job's whole life. */
+  readonly attempt: number;
+  /** Stable across attempts; delivery is at-least-once, so pass it to providers that dedupe. */
+  readonly idempotencyKey: string;
+  /**
+   * Aborts once the attempt has been settled as `timeout`, to stop abandoned I/O: pass it to every
+   * I/O call. A result returned after the abort is discarded, so to stop early and still return
+   * `ok()`, watch `deadline` / `remainingMs()` instead.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Epoch ms, on the outbox's clock, at which this attempt is settled as `timeout`: the attempt's
+   * start plus `timeoutMs` (payload validation counts against it). Return before it, with room
+   * for the work after your last check, and enqueue the rest as a continuation.
+   */
+  readonly deadline: number;
+  /**
+   * Milliseconds left until `deadline` on the outbox's clock, never below 0. A test clock moves it
+   * only when advanced; the timeout itself is real time.
+   */
+  remainingMs(): number;
+  /**
+   * The lane's own session (the outbox's `connect`, its role and Hyperdrive config), not your
+   * app's database. Fenced: once the attempt returns or is settled as `timeout`, every method call
+   * on it, on a `tx` from its `transaction()`, or on a captured method rejects. A query builder
+   * created before that and awaited after it is not covered. Typed as the minimal `OutboxDb`; the
+   * object is whatever your connector's `db` is (e.g. a drizzle database). Never await an external
+   * call inside `ctx.db.transaction()`; for writes that must commit with the job's completion, use
+   * `ok({ commit })`.
+   */
+  readonly db: OutboxDb;
+  readonly deps: Deps;
+  readonly tenantKey: string | null;
+  readonly correlationId: string | null;
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+interface JobDefinitionInput<K extends string, S extends StandardSchemaV1, D> {
+  kind: K;
+  payload: S;
+  timeoutMs: number;
+  lane?: string;
+  retry?: RetryPolicyInput;
+  /**
+   * Maps a thrown error to an outcome. Return `undefined` to fall back to `defaultClassify` (retry
+   * with code `unexpected`), which is also the default when `classify` is omitted.
+   */
+  classify?: (error: unknown) => HandlerOutcome | undefined;
+  handle: (payload: StandardSchemaV1.InferOutput<S>, ctx: JobContext<D>) => Promise<HandlerOutcome>;
+}
+interface JobDefinition<K extends string = string, S extends StandardSchemaV1 = StandardSchemaV1, D = unknown> {
+  readonly kind: K;
+  readonly payload: S;
+  readonly timeoutMs: number;
+  readonly lane: string;
+  readonly graceMs: number;
+  /** Derived: always outlives the handler plus its grace. */
+  readonly leaseMs: number;
+  readonly retry: RetryPolicy;
+  readonly classify: (error: unknown) => HandlerOutcome;
+  handle(payload: StandardSchemaV1.InferOutput<S>, ctx: JobContext<D>): Promise<HandlerOutcome>;
+}
+type AnyJob = JobDefinition<string, StandardSchemaV1, any>;
+/** The `deps` a job's handler expects; `unknown` when it declares none. */
+type JobDeps<T> = T extends JobDefinition<string, StandardSchemaV1, infer D> ? D : never;
+declare function defineJob<K extends string, S extends StandardSchemaV1, D = unknown>(input: JobDefinitionInput<K, S, D>): JobDefinition<K, S, D>;
+/**
+ * `defineJob` with `ctx.deps` typed, without annotating every handler:
+ *
+ * ```ts
+ * const defineAppJob = defineJobFor<AppDeps>();
+ * export const welcome = defineAppJob({ kind: 'welcome', …, handle: async (p, ctx) => ctx.deps.mailer… });
+ * ```
+ */
+declare function defineJobFor<D>(): <K extends string, S extends StandardSchemaV1>(input: JobDefinitionInput<K, S, D>) => JobDefinition<K, S, D>;
+/** What a thrown error becomes when `classify` is omitted or returns `undefined`: retry with code `unexpected`. */
+declare function defaultClassify(error: unknown): HandlerOutcome;
+interface KindBacklog {
+  readonly kind: string;
+  readonly due: number;
+  readonly aged: number;
+  readonly scheduled: number;
+  readonly processing: number;
+  readonly stuck: number;
+  readonly oldestDueAgeMs: number | null;
+}
+interface BacklogThresholds {
+  readonly maxDue: number;
+  readonly maxAged: number;
+  readonly maxStuck: number;
+  /** Critical at `criticalFactor ×` the threshold (any value over a 0 threshold). */
+  readonly criticalFactor: number;
+  /** `'warning'` for lanes that must never page. */
+  readonly maxSeverity: 'warning' | 'critical';
+}
+type BacklogSeverity = 'ok' | 'warning' | 'critical';
+type BacklogMetric = 'due' | 'aged' | 'stuck';
+interface BacklogBreach {
+  readonly metric: BacklogMetric;
+  readonly value: number;
+  readonly threshold: number;
+  readonly severity: Exclude<BacklogSeverity, 'ok'>;
+}
+interface BacklogTotals {
+  readonly due: number;
+  readonly aged: number;
+  readonly scheduled: number;
+  readonly processing: number;
+  readonly stuck: number;
+}
+interface LaneBacklog extends BacklogTotals {
+  readonly lane: string;
+  readonly kinds: readonly KindBacklog[];
+  readonly oldestDueAgeMs: number | null;
+  readonly severity: BacklogSeverity;
+  readonly breaches: readonly BacklogBreach[];
+  readonly thresholds: BacklogThresholds;
+}
+interface BacklogAlert {
+  readonly severity: Exclude<BacklogSeverity, 'ok'>;
+  readonly message: string;
+  readonly lanes: readonly LaneBacklog[];
+  readonly totals: BacklogTotals;
+}
+interface BacklogReport {
+  readonly severity: BacklogSeverity;
+  readonly totals: BacklogTotals;
+  readonly lanes: readonly LaneBacklog[];
+  readonly alert: BacklogAlert | null;
+}
+declare const DEFAULT_BACKLOG_THRESHOLDS: BacklogThresholds;
+/** Milliseconds a due job may wait before it counts as aged. */
+declare const DEFAULT_BACKLOG_AGED_MS = 900000;
+declare function evaluateBacklog(input: {
+  counts: readonly KindBacklog[];
+  laneOf: (kind: string) => string | undefined;
+  thresholds?: Partial<BacklogThresholds>;
+  lanes?: Readonly<Record<string, Partial<BacklogThresholds>>>;
+}): BacklogReport;
+interface ClaimableKind {
+  readonly kind: string;
+  readonly leaseMs: number;
+}
+declare function createJobRegistry(jobs: readonly AnyJob[]): {
+  get: (kind: string) => AnyJob | undefined;
+  laneOf: (kind: string) => string | undefined;
+  lanes: () => string[];
+  claimable: (budgetMs?: number, options?: {
+    lane?: string;
+  }) => ClaimableKind[];
+};
+type JobRegistry = ReturnType<typeof createJobRegistry>;
+declare const JOB_STATUSES: readonly ['pending', 'processing', 'retrying', 'succeeded', 'dead', 'cancelled'];
+type JobStatus = (typeof JOB_STATUSES)[number];
+declare const ATTEMPT_TRIGGERS: readonly ['nudge', 'sweep', 'drain'];
+type AttemptTrigger = (typeof ATTEMPT_TRIGGERS)[number];
+declare const ATTEMPT_OUTCOMES: readonly ['succeeded', 'retry', 'failed', 'cancelled', 'timeout', 'lease_expired'];
+type AttemptOutcome = (typeof ATTEMPT_OUTCOMES)[number];
+/** Open: values may grow in minor versions. */
+type DeadReason = 'failed' | 'exhausted' | 'crash_loop' | (string & {});
+/** Delays are relative to the DB clock. Absent `stickyCode` keeps the row's episode. */
+type Transition = {
+  to: 'succeeded';
+  attemptOutcome: 'succeeded';
+} | {
+  to: 'cancelled';
+  reason: string;
+  attemptOutcome: 'cancelled';
+} | {
+  to: 'cancelled';
+  reason: 'exhausted';
+  code: string;
+  message: string | null;
+  codeStreak: number;
+  stickyCode?: string;
+  attemptOutcome: Extract<AttemptOutcome, 'retry' | 'timeout'>;
+} | {
+  to: 'retrying';
+  delayMs: number;
+  code: string;
+  message: string | null;
+  codeStreak: number;
+  stickyCode?: string;
+  attemptOutcome: Extract<AttemptOutcome, 'retry' | 'timeout' | 'lease_expired'>;
+} | {
+  to: 'dead';
+  reason: DeadReason;
+  code: string;
+  message: string | null;
+  codeStreak: number;
+  stickyCode?: string;
+  attemptOutcome: Extract<AttemptOutcome, 'failed' | 'retry' | 'timeout' | 'lease_expired'>;
+};
+interface ClaimedJob {
+  id: string;
+  kind: string;
+  payload: unknown;
+  tenantKey: string | null;
+  correlationId: string | null;
+  metadata: Record<string, unknown>;
+  leaseToken: string;
+  attemptNo: number;
+  spentAttempts: number;
+  codeStreak: number;
+  lastErrorCode: string | null;
+  /** Always set by the store; optional only for hand-built values. */
+  stickyCode?: string | null;
+}
+type ClaimByIdResult = {
+  id: string;
+  result: 'claimed';
+  job: ClaimedJob;
+} | {
+  id: string;
+  result: 'not_found' | 'unregistered_kind' | 'over_budget' | 'newer_version' | 'terminal' | 'leased' | 'not_due' | 'locked';
+};
+/**
+ * A worker's own deploy version: it skips jobs a newer deploy enqueued (their payload may
+ * be a shape it can't read) until `gateMs` after enqueue, so a rollback never strands them.
+ */
+interface VersionGate {
+  mineMs: number;
+  gateMs: number;
+}
+/** `undefined` = every tenant, `null` = untenanted only; out-of-scope jobs read as `not_found`. */
+type TenantScope$1 = string | null | undefined;
+/** A job mid-attempt is `in_flight`: its worker owns it until it settles. */
+declare function cancelJob(db: SqlRunner, input: {
+  /** A dedupe key is unique per tenant, so it needs its tenant (`null` = none). */
+  ref: {
+    id: string;
+  } | {
+    dedupeKey: string;
+    tenantKey: string | null;
+  };
+  reason: string;
+  now: Date | null;
+  tenantKey?: TenantScope$1;
+}): Promise<"already_terminal" | "cancelled" | "in_flight" | "not_found">;
+/** Dead or cancelled → pending, with a fresh retry budget. */
+declare function replayJob(db: SqlRunner, input: {
+  id: string;
+  now: Date | null;
+  tenantKey?: TenantScope$1;
+}): Promise<"not_found" | "not_replayable" | "replayed">;
+interface JobSummary {
+  id: string;
+  kind: string;
+  status: JobStatus;
+  dedupeKey: string;
+  tenantKey: string | null;
+  correlationId: string | null;
+  metadata: Record<string, unknown>;
+  startedAttempts: number;
+  finishedAttempts: number;
+  spentAttempts: number;
+  codeStreak: number;
+  stickyCode: string | null;
+  lastErrorCode: string | null;
+  lastErrorMessage: string | null;
+  terminalReason: string | null;
+  availableAt: Date;
+  nextAttemptAt: Date | null;
+  leasedUntil: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+  finishedAt: Date | null;
+  nudgeSentAt: Date | null;
+  nudgeAttempts: number;
+  lastNudgeError: string | null;
+}
+interface JobFilter {
+  status: JobStatus;
+  kind?: string;
+  tenantKey?: TenantScope$1;
+  dedupeKey?: string;
+  terminalReason?: string;
+  createdAfter?: Date;
+  createdBefore?: Date;
+  finishedAfter?: Date;
+  finishedBefore?: Date;
+}
+interface AttemptOutcomeGroup {
+  kind: string;
+  tenantKey: string | null;
+  outcome: AttemptOutcome;
+  code: string | null;
+  count: number;
+}
+/** Makes a pending or retrying job due now ("retry now"). */
+declare function rescheduleNow(db: SqlRunner, input: {
+  id: string;
+  now: Date | null;
+  tenantKey?: TenantScope$1;
+}): Promise<{
+  result: 'not_found';
+  kind: null;
+} | {
+  result: "not_waiting" | "rescheduled";
+  kind: string;
+}>;
+/** Cancels many waiting jobs in one statement; every requested id gets a result. */
+declare function cancelJobs(db: SqlRunner, input: {
+  ids: readonly string[];
+  reason: string;
+  now: Date | null;
+  tenantKey?: TenantScope$1;
+}): Promise<Record<string, "already_terminal" | "cancelled" | "in_flight" | "not_found">>;
+/** Replays many dead or cancelled jobs in one statement, each with a fresh budget. */
+declare function replayJobs(db: SqlRunner, input: {
+  ids: readonly string[];
+  now: Date | null;
+  tenantKey?: TenantScope$1;
+}): Promise<Record<string, "not_found" | "not_replayable" | "replayed">>;
+/**
+ * Default bound on one inspection read. A long scan holds back the xmin horizon, so autovacuum
+ * can't clean the queue table's dead tuples while it runs.
+ */
+declare const DEFAULT_INSPECT_STATEMENT_TIMEOUT_MS = 30000;
+interface InspectBound {
+  /** Per-statement bound for this read. Default 30 s; `0` leaves the session's own setting. */
+  statementTimeoutMs?: number | undefined;
+}
+declare const aggregateAttemptOutcomes: (db: SqlRunner, input: {
+  windowMs: number;
+  maxRows: number;
+  now: Date | null;
+  kinds?: readonly string[];
+  tenantKey?: TenantScope$1;
+  outcomes?: readonly AttemptOutcome[];
+  code?: string;
+} & InspectBound) => Promise<{
+  cutoff: Date;
+  groups: AttemptOutcomeGroup[];
+  truncated: boolean;
+}>;
+declare const countBacklog: (db: SqlRunner, input: {
+  agedMs: number;
+  now: Date | null;
+  kinds?: readonly string[];
+  tenantKey?: TenantScope$1;
+} & InspectBound) => Promise<KindBacklog[]>;
+declare const countJobs: (db: SqlRunner, input: JobFilter & InspectBound) => Promise<number>;
+declare const findJobsByCorrelationId: (db: SqlRunner, input: {
+  correlationId: string;
+  limit: number;
+  tenantKey?: TenantScope$1;
+} & InspectBound) => Promise<JobSummary[]>;
+declare const getJob: (db: SqlRunner, input: {
+  id: string;
+  tenantKey?: TenantScope$1;
+} & InspectBound) => Promise<{
+  id: string;
+  kind: string;
+  status: JobStatus;
+  dedupeKey: string;
+  tenantKey: string | null;
+  correlationId: string | null;
+  metadata: Record<string, unknown>;
+  startedAttempts: number;
+  finishedAttempts: number;
+  spentAttempts: number;
+  codeStreak: number;
+  stickyCode: string | null;
+  lastErrorCode: string | null;
+  lastErrorMessage: string | null;
+  terminalReason: string | null;
+  availableAt: Date;
+  nextAttemptAt: Date | null;
+  leasedUntil: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+  finishedAt: Date | null;
+  nudgeSentAt: Date | null;
+  nudgeAttempts: number;
+  lastNudgeError: string | null;
+  attempts: {
+    attemptNo: number;
+    trigger: "drain" | "nudge" | "sweep";
+    outcome: "cancelled" | "failed" | "lease_expired" | "retry" | "succeeded" | "timeout" | null;
+    code: string | null;
+    message: string | null;
+    durationMs: number | null;
+    startedAt: Date;
+    finishedAt: Date | null;
+  }[];
+} | null>;
+declare const listJobs: (db: SqlRunner, input: JobFilter & {
+  limit: number;
+  cursor?: string | null;
+} & InspectBound) => Promise<{
+  jobs: JobSummary[];
+  nextCursor: string | null;
+}>;
+type TransitionHook = (tx: OutboxDb, event: TransitionHookEvent) => Promise<void>;
+interface TransitionHookEvent {
+  job: ClaimedJob;
+  transition: Transition;
+}
+interface RuntimeConfig {
+  registry: JobRegistry;
+  deps: unknown;
+  connect: () => Promise<LaneConnection>;
+  lanes: number;
+  queues: Readonly<Record<string, QueueSender>>;
+  recordNudges: boolean;
+  onTransition: TransitionHook | undefined;
+  emit: Emit;
+  clock: Clock;
+  redact: MessageRedactor | undefined;
+  warnAtStreak: number | undefined;
+  settleRetry: {
+    attempts: number;
+    delaysMs: readonly number[];
+    lockTimeoutMs: number;
+    /** One settlement's whole budget, retries included; inside the lease margin. */
+    budgetMs: number;
+  };
+  /** This deploy's version gate; claims skip jobs a newer deploy enqueued. */
+  version: VersionGate | undefined;
+}
+interface Budget {
+  maxJobs: number;
+  deadlineMs: number;
+}
+interface OutcomeTally {
+  claimed: number;
+  succeeded: number;
+  retrying: number;
+  dead: number;
+  cancelled: number;
+  leaseLost: number;
+  settleFailed: number;
+}
+interface RunReport extends OutcomeTally {
+  byKind: Record<string, OutcomeTally>;
+  /** Runtime faults, not handler failures. */
+  errored: number;
+  erroredSamples: string[];
+  reachedLimit: boolean;
+  reachedDeadline: boolean;
+}
+/** One connection at a time, owned by the runtime for an invocation. */
+interface Lane {
+  readonly db: OutboxDb;
+  /** Holds a live connection and was not retired. */
+  readonly usable: boolean;
+  /** Its connection reports a dead session (`LaneConnection.isBroken`). */
+  readonly broken: boolean;
+  /** Before each claim: reconnects a lane whose reconnect failed or whose session died; false once retired. */
+  ready(deadlineAt: number): Promise<boolean>;
+  /** Destroys the session, then acquires a replacement. */
+  replace(): Promise<void>;
+  /** Destroys the session; the lane claims nothing more this invocation. */
+  retire(): Promise<void>;
+  /** `work` on this lane's session, bounded: past the deadline the lane retires and this throws. */
+  bounded<T>(work: () => PromiseLike<T>, deadlineAt: number, what: string): Promise<T>;
+  close(): Promise<void>;
+}
+interface NudgeVia {
+  /** An idle connection the caller holds and bounds itself (an operator action). */
+  db?: SqlRunner;
+  /** The idle lane that just settled: bookkeeping runs on it, bounded, and retires it on expiry. */
+  lane?: Lane;
+  /** The deadline this nudge (its send and bookkeeping) must not outlive. */
+  deadlineAt?: number;
+  /** Stamp even with `recordNudges` off: the handoff cooldown reads `nudge_sent_at`. */
+  record?: boolean;
+}
+interface Scope {
+  lane?: string;
+  kinds?: readonly string[];
+}
+declare function createRuntime(config: RuntimeConfig): {
+  emit: (event: OutboxEvent) => void;
+  nudge: (jobs: readonly (string | {
+    id: string;
+    kind: string;
+  })[], delaySeconds?: number, via?: NudgeVia) => Promise<void>;
+  processNudge: (ids: readonly string[], budget: Budget, scope?: Scope, options?: {
+    deadlineAt?: number;
+  }) => Promise<RunReport>;
+  drain: (budget: Budget, trigger: 'sweep' | 'drain', scope?: Scope, options?: {
+    deadlineAt?: number;
+  }) => Promise<RunReport>;
+  handoff: (budgetMs: number, limit?: number, options?: {
+    deadlineAt?: number;
+  }) => Promise<number>;
+  recover: (limit: number, options?: {
+    deadlineAt?: number;
+  }) => Promise<RunReport>;
+  cleanup: (retention: {
+    succeededRetentionMs: number;
+    terminalRetentionMs: number;
+    batch: number;
+    maxBatches: number;
+  }, options?: {
+    deadlineAt?: number;
+  }) => Promise<number>;
+  hasBacklog: (scope?: Scope, options?: {
+    deadlineAt?: number;
+  }) => Promise<boolean>;
+  monitorBacklog: (options?: {
+    agedMs?: number;
+    thresholds?: Partial<BacklogThresholds>;
+    lanes?: Readonly<Record<string, Partial<BacklogThresholds>>>;
+    deadlineAt?: number;
+  }) => Promise<BacklogReport>;
+  continueDrain: (lane?: string, options?: {
+    deadlineAt?: number;
+  }) => Promise<boolean>;
+  lanes: () => string[];
+  nowMs: () => number;
+  sleep: (ms: number) => Promise<void>;
+};
+type Runtime = ReturnType<typeof createRuntime>;
+interface SerializedError {
+  name: string;
+  message: string;
+  stack?: string;
+  code?: string;
+  cause?: SerializedError;
+}
+/** Transition events fire only after the settle (and its hook) committed. */
+type OutboxEvent = {
+  type: 'enqueued';
+  jobId: string;
+  kind: string;
+  created: boolean;
+} | {
+  type: 'transition';
+  severity: 'info' | 'warn' | 'error';
+  jobId: string;
+  kind: string;
+  tenantKey: string | null;
+  correlationId: string | null;
+  attemptNo: number;
+  to: 'succeeded' | 'retrying' | 'dead' | 'cancelled';
+  reason: string | null;
+  code: string | null;
+  codeStreak: number;
+  attemptsUsed: number;
+  maxAttempts: number;
+  delayMs: number | null;
+  recovered: boolean;
+  trigger: 'nudge' | 'sweep' | 'drain' | 'recovery';
+} | {
+  type: 'attempt_threshold';
+  jobId: string;
+  kind: string;
+  code: string;
+  codeStreak: number;
+  threshold: number;
+} | {
+  type: 'handler_threw';
+  jobId: string;
+  kind: string;
+  attemptNo: number;
+  error: SerializedError;
+} | {
+  type: 'handler_timeout';
+  jobId: string;
+  kind: string;
+  attemptNo: number;
+  timeoutMs: number;
+} | {
+  type: 'lease_lost';
+  jobId: string;
+  kind: string;
+  attemptNo: number;
+} | {
+  type: 'hook_failed';
+  jobId: string;
+  kind: string;
+  to: string;
+  error: SerializedError;
+} | {
+  type: 'settle_retried';
+  jobId: string;
+  kind: string;
+  dbCode: string | null;
+  retry: number;
+} | {
+  type: 'settle_failed';
+  jobId: string;
+  kind: string;
+  attemptNo: number;
+  dbCode: string | null;
+  transient: boolean;
+  error: SerializedError;
+} | {
+  type: 'nudge_miss';
+  jobId: string;
+  result: Exclude<ClaimByIdResult['result'], 'claimed'>;
+} | {
+  /** The claim's reply arrived too late to run the handler: it never started. */
+  type: 'claim_late';
+  jobId: string;
+  kind: string;
+  attemptNo: number;
+  claimLatencyMs: number;
+} | {
+  type: 'nudge_sent';
+  ids: string[];
+  lane: string;
+  delaySeconds: number;
+} | {
+  type: 'nudge_failed';
+  ids: string[];
+  lane: string;
+  error: SerializedError;
+} | {
+  type: 'nudge_skipped';
+  ids: string[];
+  lane: string;
+  reason: 'no_queue';
+} | {
+  type: 'cleanup';
+  deleted: number;
+} | {
+  type: 'backlog';
+  report: BacklogReport;
+} | {
+  type: 'continuation_sent';
+  lane: string;
+} | {
+  type: 'continuation_skipped';
+  lane: string;
+  reason: 'no_queue';
+} | {
+  type: 'continuation_failed';
+  lane: string;
+  error: SerializedError;
+} | {
+  type: 'message_received';
+  messageType: 'nudge' | 'drain';
+  ids: string[];
+  attempts: number;
+} | {
+  type: 'message_rejected';
+  reason: 'malformed' | 'unknown_version';
+  body: string;
+} | {
+  type: 'message_retried';
+  messageType: 'nudge' | 'drain';
+  delaySeconds: number;
+  attempts: number;
+  error: SerializedError;
+} | {
+  type: 'dlq_message';
+  queue: string;
+  attempts: number;
+  body: string;
+} | {
+  type: 'phase_failed';
+  phase: 'recover' | 'reserved' | 'drain' | 'handoff' | 'cleanup' | 'backlog';
+  cron: string | null;
+  error: SerializedError;
+} | {
+  /** A schedule's occurrence committed. `existing` > 0 means a repeated tick found its jobs. */
+  type: 'schedule_ran';
+  name: string;
+  cron: string;
+  scheduledAt: string;
+  created: number;
+  existing: number;
+  /** Enqueues a `run` schedule got back as `invalid_payload` or `dedupe_conflict`. */
+  rejected: number;
+  attempts: number;
+} | {
+  /** The occurrence enqueued nothing: it is skipped, not retried on a later tick. */
+  type: 'schedule_failed';
+  severity: 'error';
+  name: string;
+  cron: string;
+  scheduledAt: string;
+  attempts: number;
+  error: SerializedError;
+} | {
+  type: 'sweep_finished';
+  cron: string | null;
+  recovered: number;
+  report: RunReport;
+  deleted: number;
+  continued: boolean;
+} | {
+  type: 'infra_error';
+  operation: string;
+  dbCode: string | null;
+  transient: boolean;
+  error: SerializedError;
+};
+type EventSink = (event: OutboxEvent) => void;
+declare function createEmitter(sink: EventSink | undefined): (event: OutboxEvent) => void;
+type Emit = ReturnType<typeof createEmitter>;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+/** What `deps` must satisfy: every registered job's needs at once. */
+type DepsOf<J extends readonly AnyJob[]> = UnionToIntersection<JobDeps<J[number]>>;
+type DepsOption<D> = [D] extends [never] ? {
+  deps?: unknown;
+} : unknown extends D ? {
+  deps?: unknown;
+} : {
+  deps: D;
+};
+type OutboxOptions<J extends readonly AnyJob[]> = OutboxBaseOptions<J> & DepsOption<NoInfer<DepsOf<J>>>;
+interface OutboxBaseOptions<J extends readonly AnyJob[]> {
+  jobs: J;
+  /** One call per lane per invocation, plus short-lived ones; never at construction. */
+  connect: () => Promise<LaneConnection>;
+  /** Default 1; one connection per lane. */
+  lanes?: number;
+  /** One queue or one per lane; a lane without a queue is driven by cron only. */
+  queue?: QueueSender | Readonly<Record<string, QueueSender>>;
+  /** Costs one connection per nudge. */
+  recordNudges?: boolean;
+  /**
+   * Bound for one operator action (cancel, replay, retryNow, eraseTenant, …): acquisition, SQL
+   * and close. Past it the connection is destroyed and the call rejects. Default 60 s.
+   */
+  operationTimeoutMs?: number;
+  /**
+   * Largest payload `enqueue` accepts, in UTF-8 bytes of its JSON form; a bigger one returns
+   * `invalid_payload`. Every claim reads the payload back from the hot table, so put large data in
+   * object storage (e.g. R2) and enqueue its key. Default 256 KiB.
+   */
+  maxPayloadBytes?: number;
+  /** Runs in the settle transaction before the job row write; commits only if the transition applies. */
+  onTransition?: TransitionHook;
+  events?: EventSink;
+  redactError?: MessageRedactor;
+  warnAtStreak?: number;
+  clock?: Clock;
+  /**
+   * Mints job ids. Default: `uuidv7()`. Must return a UUID string (the `id` column is `uuid`);
+   * time-ordered ids keep the primary-key index and `(created_at, id)` pagination well-behaved.
+   */
+  generateId?: () => string;
+  /**
+   * Opt-in: `enqueue`, `transaction`'s `enqueue` and a `run` schedule's `enqueue` throw
+   * `EnqueueRefusedError` instead of returning `invalid_payload` or `dedupe_conflict`, so a
+   * business write can't commit without its job. With `true`, `createOutbox` returns a
+   * `StrictOutbox`, accepted wherever an `Outbox` is. Default `false`: refusals are returned.
+   */
+  strictEnqueue?: boolean;
+  /**
+   * This deploy's version, e.g. `env.CF_VERSION_METADATA`. Jobs are stamped with it, and an
+   * older deploy skips newer jobs for `gateMs` (default 6 h) during a gradual rollout.
+   */
+  version?: {
+    timestamp: string | number;
+    gateMs?: number;
+  };
+}
+type EnqueueRequest<T extends AnyJob> = {
+  payload: StandardSchemaV1.InferInput<T['payload']>;
+  dedupeKey: string;
+  tenantKey?: string | null;
+  correlationId?: string | null;
+  metadata?: Record<string, unknown>;
+  /** Milliseconds. */
+  delayMs?: number;
+};
+type EnqueueResult = {
+  status: 'created' | 'exists';
+  id: string;
+  kind: string;
+} | {
+  status: 'dedupe_conflict';
+  reason: 'kind';
+  id: string;
+  existingKind: string;
+} | {
+  status: 'invalid_payload';
+  issues: readonly StandardSchemaV1.Issue[];
+};
+type AcceptedEnqueueResult = Extract<EnqueueResult, {
+  status: 'created' | 'exists';
+}>;
+type RefusedEnqueueResult = Exclude<EnqueueResult, AcceptedEnqueueResult>;
+/** Thrown by a strict outbox's enqueue (`strictEnqueue: true`) instead of returning a refusal. */
+declare class EnqueueRefusedError extends Error {
+  readonly kind: string;
+  readonly result: RefusedEnqueueResult;
+  constructor(kind: string, result: RefusedEnqueueResult);
+}
+/** Not part of the public API. */
+declare const RUNTIME: unique symbol;
+declare function createOutbox<const J extends readonly AnyJob[]>(options: OutboxOptions<J> & {
+  strictEnqueue: true;
+}): StrictOutbox<J>;
+declare function createOutbox<const J extends readonly AnyJob[]>(options: OutboxOptions<J>): Outbox<J>;
+/**
+ * Restricts an operator action to one tenant. Out-of-scope jobs report `not_found`.
+ * - omitted (or `undefined`): any tenant — the unscoped, admin form;
+ * - `null`: only jobs enqueued without a tenant;
+ * - a string: only that tenant's jobs.
+ */
+interface TenantScope {
+  tenantKey?: string | null | undefined;
+}
+/** `enqueue` bound to one transaction. `R` narrows to `AcceptedEnqueueResult` on a strict outbox. */
+type ScopedEnqueue<J extends readonly AnyJob[], R extends EnqueueResult = EnqueueResult> = <T extends J[number]>(job: T, request: EnqueueRequest<T>) => Promise<R>;
+/**
+ * What `createOutbox` returns. Named, so an exported `outboxFor` compiles under `declaration`
+ * without reaching the runtime's internal key.
+ */
+interface Outbox<J extends readonly AnyJob[] = readonly AnyJob[],
+/** What an enqueue resolves to: `AcceptedEnqueueResult` on a `StrictOutbox`, whose refusals throw. */
+R extends EnqueueResult = EnqueueResult> {
+  /** Runs iff the caller's transaction commits; a duplicate `dedupeKey` returns the existing job. */
+  enqueue<T extends J[number]>(tx: SqlRunner, job: T, request: EnqueueRequest<T>): Promise<R>;
+  /**
+   * Runs `work` in `db.transaction` and nudges the jobs it created once that commits. A throw
+   * rolls back and nudges nothing. Pass the top-level db, not a transaction (drizzle would open a
+   * savepoint, and the nudge would precede the outer commit). With `recordNudges`, recording the
+   * nudge checks out a connection from `connect`: if `db` holds a client from that same pool, size
+   * the pool for both, or pass a pool-backed db that releases its client when the commit returns.
+   */
+  transaction<Tx extends SqlRunner, Result>(db: {
+    transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+  }, work: (tx: Tx, enqueue: ScopedEnqueue<J, R>) => Promise<Result>): Promise<Result>;
+  /** Call after commit; bare ids go to the default lane. Never throws. */
+  nudge(jobs: readonly (string | {
+    id: string;
+    kind: string;
+  })[]): Promise<void>;
+  cancel(ref: {
+    id: string;
+  } | {
+    dedupeKey: string;
+    tenantKey: string | null;
+  }, reason: string, scope?: TenantScope): Promise<Result<typeof cancelJob>>;
+  /** dead/cancelled → a fresh retry budget. */
+  replay(id: string, scope?: TenantScope): Promise<Result<typeof replayJob>>;
+  /** Makes a pending or retrying job due now, and nudges it. */
+  retryNow(id: string, scope?: TenantScope): Promise<Result<typeof rescheduleNow>['result']>;
+  /** One statement; every id gets a result. */
+  cancelMany(ids: readonly string[], reason: string, scope?: TenantScope): Promise<Result<typeof cancelJobs>>;
+  /** One statement; every id gets a result. */
+  replayMany(ids: readonly string[], scope?: TenantScope): Promise<Result<typeof replayJobs>>;
+  /** Erasure: deletes every job of one tenant, including in-flight ones. Returns the count. */
+  eraseTenant(tenantKey: string, opts?: {
+    batch?: number;
+  }): Promise<number>;
+  /** Not part of the public API. */
+  readonly [RUNTIME]: OutboxRuntime;
+}
+/** `ScopedEnqueue` of a strict outbox: a refusal throws `EnqueueRefusedError`, so it resolves only to an accepted result. */
+type StrictScopedEnqueue<J extends readonly AnyJob[]> = ScopedEnqueue<J, AcceptedEnqueueResult>;
+/**
+ * What `createOutbox({ strictEnqueue: true })` returns: an `Outbox` whose enqueues (`enqueue`,
+ * `transaction`'s, a `run` schedule's) throw `EnqueueRefusedError` on a refusal. Assignable to
+ * `Outbox`, so every helper taking one accepts it.
+ */
+type StrictOutbox<J extends readonly AnyJob[] = readonly AnyJob[]> = Outbox<J, AcceptedEnqueueResult>;
+/** Jobs a transaction created, by nudge delay in seconds, awaiting their post-commit nudge. */
+type PendingNudges = Map<number, {
+  id: string;
+  kind: string;
+}[]>;
+/** Not part of the public API: the runtime plus a bounded connection for one-off work. */
+type OutboxRuntime = Runtime & {
+  withConnection<T>(work: (connection: LaneConnection) => Promise<T>, invocationDeadlineAt?: number): Promise<T>;
+  /** `outbox.transaction` without its nudges, for a caller that must release its connection first. */
+  collectTransaction<Tx extends SqlRunner, R>(db: {
+    transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+  }, work: (tx: Tx, enqueue: ScopedEnqueue<readonly AnyJob[]>) => Promise<R>): Promise<{
+    result: R;
+    pending: PendingNudges;
+  }>;
+  nudgePending(pending: PendingNudges, deadlineAt?: number): Promise<void>;
+};
+export { cancel as $, DeadReason as A, KindBacklog as B, countBacklog as C, listJobs as D, getJob as E, BacklogReport as F, JobDefinitionInput as G, AnyJob as H, BacklogSeverity as I, defineJob as J, JobDeps as K, BacklogThresholds as L, AttemptOutcome as M, AttemptTrigger as N, DEFAULT_INSPECT_STATEMENT_TIMEOUT_MS as O, JobStatus as P, HandlerOutcome as Q, DEFAULT_BACKLOG_AGED_MS as R, aggregateAttemptOutcomes as S, findJobsByCorrelationId as T, JobContext as U, evaluateBacklog as V, JobDefinition as W, RetryPolicy as X, defineJobFor as Y, RetryPolicyInput as Z, Budget as _, EnqueueResult as a, TransitionHook as b, RUNTIME as c, StrictOutbox as d, fail as et, StrictScopedEnqueue as f, OutboxEvent as g, EventSink as h, EnqueueRequest as i, Transition as j, InspectBound as k, RefusedEnqueueResult as l, createOutbox as m, DepsOf as n, retry as nt, Outbox as o, TenantScope as p, defaultClassify as q, EnqueueRefusedError as r, MessageRedactor as rt, OutboxOptions as s, AcceptedEnqueueResult as t, ok as tt, ScopedEnqueue as u, OutcomeTally as v, countJobs as w, TransitionHookEvent as x, RunReport as y, DEFAULT_BACKLOG_THRESHOLDS as z };