bunderstack 0.23.1 → 0.23.3

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `bunderstack` will be documented in this file.
 
+## [0.23.2] - 2026-08-31
+
+### Fixed
+
+- **Renewable job leases.** Active handlers renew their fenced lease while
+  running, preventing a healthy long-running job from being reclaimed.
+- **Bounded execution.** Jobs may use `leaseDuration`, `maxRuntime`, and
+  `ctx.signal`; `timeout` remains a deprecated alias for the lease duration.
+- **Safe observability.** Queue lifecycle events are structured JSON without
+  payloads or exception stacks; agent-chat forwards queue cancellation to its
+  provider request.
+
 ## [0.23.1] - 2026-08-31
 
 ### Changed

package/dist/jobs/define.d.ts

@@ -4,7 +4,18 @@ import type { EmailFacade } from '../email.js';
 import type { StorageFacade } from '../runtime.js';
 import { type CatchUp } from './slots.js';
 export declare const DEFAULT_RETRIES = 3;
+export declare const DEFAULT_LEASE_DURATION_MS = 60000;
+/** @deprecated Use DEFAULT_LEASE_DURATION_MS. */
 export declare const DEFAULT_TIMEOUT_MS = 60000;
+export type BackgroundTiming = {
+    /** Lease duration in ms; an expired lease sends the job back to pending. */
+    leaseDuration?: number;
+    /** Optional cooperative execution deadline in ms. */
+    maxRuntime?: number;
+    /** @deprecated Use leaseDuration. */
+    timeout?: number;
+};
+export declare function leaseDurationFor<T extends BackgroundTiming>(def: T): number;
 export type EnqueueOptions = {
     /** Collapse duplicate enqueues while the queue row is non-terminal. */
     dedupeKey?: string;
@@ -40,9 +51,11 @@ export type JobContext<TSchema extends Record<string, unknown> = Record<string,
     storage: StorageFacade;
     jobs: JobsRuntimeFacade;
     realtime: RealtimeFacade<TSchema>;
+    /** Aborted when execution reaches its deadline or the job loses its lease. */
+    signal: AbortSignal;
 };
 export type BunderstackJobContext<TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>> = JobContext<TSchema, TEnvResult>;
-export type QueueJobDefinition<TInput, TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>> = {
+export type QueueJobDefinition<TInput, TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>> = BackgroundTiming & {
     kind: 'job';
     /** Standard Schema payload; parsed at enqueue AND before the handler runs. */
     input?: StandardSchemaV1<unknown, TInput>;
@@ -55,8 +68,6 @@ export type QueueJobDefinition<TInput, TSchema extends Record<string, unknown> =
     };
     /** Max simultaneous `running` rows of this type, enforced per worker. */
     concurrency?: number;
-    /** Lease duration in ms; an expired lease sends the job back to pending. */
-    timeout?: number;
     handler: (input: TInput, ctx: JobContext<TSchema, TEnvResult>) => Promise<void> | void;
     /** Fires once, after the final attempt fails. Errors here are logged, never retried. */
     onFailed?: (input: TInput, error: Error, ctx: JobContext<TSchema, TEnvResult>) => Promise<void> | void;
@@ -64,7 +75,7 @@ export type QueueJobDefinition<TInput, TSchema extends Record<string, unknown> =
 export type CronInvocation = {
     scheduledFor: Date;
 };
-export type CronDefinition<TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>, TSchedule extends string = string> = {
+export type CronDefinition<TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>, TSchedule extends string = string> = BackgroundTiming & {
     kind: 'cron';
     schedule: TSchedule;
     /** Attempts after the first failure. Default 3 (so 4 total attempts). */
@@ -74,8 +85,6 @@ export type CronDefinition<TSchema extends Record<string, unknown> = Record<stri
         baseMs?: number;
         factor?: number;
     };
-    /** Lease duration in ms; an expired lease sends the slot back to pending. */
-    timeout?: number;
     /** How missed slots are handled on wake. Default 'latest'. */
     catchUp?: CatchUp;
     /** How far back catch-up looks, in ms. Default 1 hour. */

package/dist/jobs/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/jobs/define.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/jobs/define.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAA;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG/C,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AAEnD,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAC/C,iDAAiD;AACjD,eAAO,MAAM,kBAAkB,QAA4B,CAAA;AAE3D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,gBAAgB,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,CAE3E;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAA;IACf,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAA;IACX,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,OAAO,EACf,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1B,kFAAkF;IAClF,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CACxC,CAAA;AAED,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD,MAAM,MAAM,UAAU,CACpB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAClC;IACF,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAClB,GAAG,EAAE,UAAU,CAAA;IACf,KAAK,EAAE,WAAW,CAAA;IAClB,OAAO,EAAE,aAAa,CAAA;IACtB,IAAI,EAAE,iBAAiB,CAAA;IACvB,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IACjC,8EAA8E;IAC9E,MAAM,EAAE,WAAW,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,qBAAqB,CAC/B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAClC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;AAEnC,MAAM,MAAM,kBAAkB,CAC5B,MAAM,EACN,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAClC,gBAAgB,GAAG;IACrB,IAAI,EAAE,KAAK,CAAA;IACX,8EAA8E;IAC9E,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACzC,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9E,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,CACP,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,KACjC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACzB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,CACT,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,KACjC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AAEnD,MAAM,MAAM,cAAc,CACxB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,SAAS,SAAS,MAAM,GAAG,MAAM,IAC/B,gBAAgB,GAAG;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,SAAS,CAAA;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9E,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,EAAE,CACP,UAAU,EAAE,cAAc,EAC1B,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,KACjC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACzB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,CACT,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,KACjC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,oBAAoB,GAC5B,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GACjC,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;AAC5B,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;AAEjE,0CAA0C;AAC1C,MAAM,MAAM,aAAa,CACvB,MAAM,EACN,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAClC,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAA;AAGnD,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAEhE,MAAM,MAAM,uBAAuB,GAC/B,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GACjC,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AACjC,MAAM,MAAM,QAAQ,GAAG,cAAc,CAAA;AAErC,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,cAAc,IAAI;KACtD,CAAC,IAAI,MAAM,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,kBAAkB,CAC9D,GAAG,EACH,GAAG,EACH,GAAG,CACJ,GACG,CAAC,GACD,KAAK;CACV,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAA;AAEvB,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAyDjE;AAED,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,+BAAyB,CAAA;AAEtD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,uBAAuB,EAC5B,OAAO,EAAE,MAAM,GACd,MAAM,CAOR;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAGlC,mEAAmE;QAC/D,MAAM,mBACH,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,GACjE,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC;eAGvC,SAAS,SAAS,MAAM,OAC5B,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,GAChE,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC;IAIjD,6DAA6D;WACtD,KAAK,SAAS,cAAc,QAAQ,KAAK,GAAG,KAAK;EAK3D;AAED,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,CAChC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAClC,UAAU,CAAC,OAAO,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAA;AAM7D,KAAK,UAAU,CAAC,IAAI,IAClB,IAAI,SAAS,kBAAkB,CAAC,MAAM,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,SAAS,CAAA;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,KAAK,SAAS,QAAQ,IAAI,IAAI,CACnD,iBAAiB,EACjB,SAAS,CACV,GAAG;IACF,OAAO,CAAC,CAAC,SAAS,YAAY,CAAC,KAAK,CAAC,EACnC,IAAI,EAAE,CAAC,EACP,GAAG,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,GAC3C,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,cAAc,CAAC,GAC1C,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,CAAC,GACvD,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC3B,CAAA"}

package/dist/jobs/define.js

@@ -1,7 +1,12 @@
 import { parseCron } from './cron.js';
 import { CRON_PREFIX } from './slots.js';
 export const DEFAULT_RETRIES = 3;
-export const DEFAULT_TIMEOUT_MS = 60_000;
+export const DEFAULT_LEASE_DURATION_MS = 60_000;
+/** @deprecated Use DEFAULT_LEASE_DURATION_MS. */
+export const DEFAULT_TIMEOUT_MS = DEFAULT_LEASE_DURATION_MS;
+export function leaseDurationFor(def) {
+    return def.leaseDuration ?? def.timeout ?? DEFAULT_LEASE_DURATION_MS;
+}
 /** Throws when a definition is unusable. Safe to call more than once. */
 export function validateBackgroundDefs(defs) {
     for (const [name, def] of Object.entries(defs)) {
@@ -15,8 +20,15 @@ export function validateBackgroundDefs(defs) {
             (def.retries < 0 || !Number.isInteger(def.retries))) {
             throw new Error(`[bunderstack] background task "${name}": retries must be a non-negative integer`);
         }
-        if (def.timeout !== undefined && def.timeout <= 0) {
-            throw new Error(`[bunderstack] background task "${name}": timeout must be positive`);
+        if (def.timeout !== undefined && def.leaseDuration !== undefined) {
+            throw new Error(`[bunderstack] background task "${name}": timeout and leaseDuration cannot both be declared`);
+        }
+        for (const field of ['timeout', 'leaseDuration', 'maxRuntime']) {
+            const value = def[field];
+            if (value !== undefined &&
+                (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0)) {
+                throw new Error(`[bunderstack] background task "${name}": ${field} must be a positive finite integer`);
+            }
         }
         if (def.kind === 'cron') {
             parseCron(def.schedule);

package/dist/jobs/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/jobs/define.ts"],"names":[],"mappings":"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","sourcesContent":["// src/jobs/define.ts — job definition types and the typed builder.\n// `createJobsBuilder` exists purely to carry\n// TSchema/TEnvResult typing into inline callbacks and extracted files.\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\n\nimport type { DbFor } from '../db'\nimport type { EmailFacade } from '../email'\nimport type { StorageFacade } from '../runtime'\n\nimport { parseCron } from './cron'\nimport { CRON_PREFIX, type CatchUp } from './slots'\n\nexport const DEFAULT_RETRIES = 3\nexport const DEFAULT_TIMEOUT_MS = 60_000\n\nexport type EnqueueOptions = {\n  /** Collapse duplicate enqueues while the queue row is non-terminal. */\n  dedupeKey?: string\n  /** Milliseconds from now until the job becomes claimable. */\n  delay?: number\n  /** Absolute time the job becomes claimable; wins over `delay`. */\n  runAt?: Date | number\n}\n\nexport type TickResult = {\n  /** Rows moved from pending to running this tick. */\n  claimed: number\n  /** Handlers that completed successfully. */\n  ran: number\n  /** Handlers that threw, whether or not they will be retried. */\n  failed: number\n}\n\n/**\n * The untyped runtime facade. Job handlers and API context expose this shape;\n * `app.jobs` narrows `enqueue` to the declared job names/payloads.\n */\nexport type JobsRuntimeFacade = {\n  enqueue(\n    name: string,\n    input?: unknown,\n    opts?: EnqueueOptions,\n  ): Promise<{ id: string }>\n  /** Run one poll cycle deterministically (tests). `now` defaults to Date.now(). */\n  tick(now?: number): Promise<TickResult>\n}\n\nimport type { RealtimeFacade } from '../realtime/facade'\n\nexport type JobContext<\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = {\n  db: DbFor<TSchema>\n  env: TEnvResult\n  email: EmailFacade\n  storage: StorageFacade\n  jobs: JobsRuntimeFacade\n  realtime: RealtimeFacade<TSchema>\n}\n\nexport type BunderstackJobContext<\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = JobContext<TSchema, TEnvResult>\n\nexport type QueueJobDefinition<\n  TInput,\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = {\n  kind: 'job'\n  /** Standard Schema payload; parsed at enqueue AND before the handler runs. */\n  input?: StandardSchemaV1<unknown, TInput>\n  /** Attempts after the first failure. Default 3 (so 4 total attempts). */\n  retries?: number\n  /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */\n  backoff?: ((attempt: number) => number) | { baseMs?: number; factor?: number }\n  /** Max simultaneous `running` rows of this type, enforced per worker. */\n  concurrency?: number\n  /** Lease duration in ms; an expired lease sends the job back to pending. */\n  timeout?: number\n  handler: (\n    input: TInput,\n    ctx: JobContext<TSchema, TEnvResult>,\n  ) => Promise<void> | void\n  /** Fires once, after the final attempt fails. Errors here are logged, never retried. */\n  onFailed?: (\n    input: TInput,\n    error: Error,\n    ctx: JobContext<TSchema, TEnvResult>,\n  ) => Promise<void> | void\n}\n\nexport type CronInvocation = { scheduledFor: Date }\n\nexport type CronDefinition<\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n  TSchedule extends string = string,\n> = {\n  kind: 'cron'\n  schedule: TSchedule\n  /** Attempts after the first failure. Default 3 (so 4 total attempts). */\n  retries?: number\n  /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */\n  backoff?: ((attempt: number) => number) | { baseMs?: number; factor?: number }\n  /** Lease duration in ms; an expired lease sends the slot back to pending. */\n  timeout?: number\n  /** How missed slots are handled on wake. Default 'latest'. */\n  catchUp?: CatchUp\n  /** How far back catch-up looks, in ms. Default 1 hour. */\n  catchUpWindow?: number\n  handler: (\n    invocation: CronInvocation,\n    ctx: JobContext<TSchema, TEnvResult>,\n  ) => Promise<void> | void\n  /** Fires once, after the final attempt fails. Errors here are logged, never retried. */\n  onFailed?: (\n    invocation: CronInvocation,\n    error: Error,\n    ctx: JobContext<TSchema, TEnvResult>,\n  ) => Promise<void> | void\n}\n\nexport type BackgroundDefinition =\n  | QueueJobDefinition<any, any, any>\n  | CronDefinition<any, any>\nexport type BackgroundDefs = Record<string, BackgroundDefinition>\n\n/** @deprecated Use QueueJobDefinition. */\nexport type JobDefinition<\n  TInput,\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = QueueJobDefinition<TInput, TSchema, TEnvResult>\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyJobDefinition = QueueJobDefinition<any, any, any>\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyBackgroundDefinition =\n  | QueueJobDefinition<any, any, any>\n  | CronDefinition<any, any, any>\nexport type JobsDefs = BackgroundDefs\n\nexport type QueueJobKeys<TDefs extends BackgroundDefs> = {\n  [K in keyof TDefs & string]: TDefs[K] extends QueueJobDefinition<\n    any,\n    any,\n    any\n  >\n    ? K\n    : never\n}[keyof TDefs & string]\n\n/** Throws when a definition is unusable. Safe to call more than once. */\nexport function validateBackgroundDefs(defs: BackgroundDefs): void {\n  for (const [name, def] of Object.entries(defs)) {\n    if (typeof def.handler !== 'function') {\n      throw new Error(`[bunderstack] background task \"${name}\" has no handler`)\n    }\n    if (def.kind === 'job' && name.startsWith(CRON_PREFIX)) {\n      throw new Error(\n        `[bunderstack] job \"${name}\": the \"${CRON_PREFIX}\" prefix is reserved for cron tasks`,\n      )\n    }\n    if (\n      def.retries !== undefined &&\n      (def.retries < 0 || !Number.isInteger(def.retries))\n    ) {\n      throw new Error(\n        `[bunderstack] background task \"${name}\": retries must be a non-negative integer`,\n      )\n    }\n    if (def.timeout !== undefined && def.timeout <= 0) {\n      throw new Error(\n        `[bunderstack] background task \"${name}\": timeout must be positive`,\n      )\n    }\n    if (def.kind === 'cron') {\n      parseCron(def.schedule)\n      if ((def as { concurrency?: number }).concurrency !== undefined) {\n        throw new Error(\n          `[bunderstack] cron \"${name}\": concurrency is not supported for cron tasks — slots are already unique`,\n        )\n      }\n      if (def.catchUpWindow !== undefined && def.catchUpWindow <= 0) {\n        throw new Error(\n          `[bunderstack] cron \"${name}\": catchUpWindow must be positive`,\n        )\n      }\n      continue\n    }\n    if (\n      def.concurrency !== undefined &&\n      (def.concurrency < 1 || !Number.isInteger(def.concurrency))\n    ) {\n      throw new Error(\n        `[bunderstack] job \"${name}\": concurrency must be a positive integer`,\n      )\n    }\n  }\n}\n\n/** @deprecated Use validateBackgroundDefs. */\nexport const validateJobsDefs = validateBackgroundDefs\n\n/**\n * Delay in ms before retry `attempt` (1-based = the attempt that just failed).\n * Jittered by ±20% so a shared outage does not retry every job in lockstep.\n * A caller-supplied backoff function is returned verbatim — the caller owns it.\n */\nexport function backoffMs(\n  def: AnyBackgroundDefinition,\n  attempt: number,\n): number {\n  const b = def.backoff\n  if (typeof b === 'function') return b(attempt)\n  const baseMs = b?.baseMs ?? 1000\n  const factor = b?.factor ?? 2\n  const flat = baseMs * factor ** (attempt - 1)\n  return Math.round(flat * (0.8 + Math.random() * 0.4))\n}\n\n/**\n * Build the `j` instance bunderstack hands to the config's `jobs` builder\n * callback (and exports for multi-file job setups).\n */\nexport function createJobsBuilder<\n  TSchema extends Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n>() {\n  return {\n    /** Identity with inference: pins TInput from the schema output. */\n    job<TInput = undefined>(\n      def: Omit<QueueJobDefinition<TInput, TSchema, TEnvResult>, 'kind'>,\n    ): QueueJobDefinition<TInput, TSchema, TEnvResult> {\n      return { kind: 'job', ...def }\n    },\n    cron<const TSchedule extends string>(\n      def: Omit<CronDefinition<TSchema, TEnvResult, TSchedule>, 'kind'>,\n    ): CronDefinition<TSchema, TEnvResult, TSchedule> {\n      parseCron(def.schedule)\n      return { kind: 'cron', ...def }\n    },\n    /** Identity with validation: returns the defs map, typed. */\n    define<TDefs extends BackgroundDefs>(defs: TDefs): TDefs {\n      validateBackgroundDefs(defs)\n      return defs\n    },\n  }\n}\n\n/** Type of the `j` instance — for builder callbacks declared in separate files. */\nexport type BunderstackJobsBuilder<\n  TSchema extends Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = ReturnType<typeof createJobsBuilder<TSchema, TEnvResult>>\n\n// Infers TInput from the JobDefinition's own type argument rather than\n// pattern-matching the (optional, so union-with-undefined) `input` property —\n// A required-property pattern fails structurally because `input` is optional,\n// so infer from the definition's own type argument instead.\ntype JobInputOf<TDef> =\n  TDef extends QueueJobDefinition<infer TInput, any, any> ? TInput : undefined\n\n/**\n * `app.jobs`: `enqueue` narrowed to declared names + payloads. `Omit`s the\n * runtime facade's loose `enqueue` first — intersecting two same-named\n * methods instead would make TS treat them as overloaded, so the loose\n * `(name: string, ...)` signature would still accept any name.\n */\nexport type JobsFacade<TDefs extends JobsDefs> = Omit<\n  JobsRuntimeFacade,\n  'enqueue'\n> & {\n  enqueue<K extends QueueJobKeys<TDefs>>(\n    name: K,\n    ...rest: JobInputOf<TDefs[K]> extends undefined\n      ? [input?: undefined, opts?: EnqueueOptions]\n      : [input: JobInputOf<TDefs[K]>, opts?: EnqueueOptions]\n  ): Promise<{ id: string }>\n}\n"]}
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/jobs/define.ts"],"names":[],"mappings":"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","sourcesContent":["// src/jobs/define.ts — job definition types and the typed builder.\n// `createJobsBuilder` exists purely to carry\n// TSchema/TEnvResult typing into inline callbacks and extracted files.\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\n\nimport type { DbFor } from '../db'\nimport type { EmailFacade } from '../email'\nimport type { StorageFacade } from '../runtime'\n\nimport { parseCron } from './cron'\nimport { CRON_PREFIX, type CatchUp } from './slots'\n\nexport const DEFAULT_RETRIES = 3\nexport const DEFAULT_LEASE_DURATION_MS = 60_000\n/** @deprecated Use DEFAULT_LEASE_DURATION_MS. */\nexport const DEFAULT_TIMEOUT_MS = DEFAULT_LEASE_DURATION_MS\n\nexport type BackgroundTiming = {\n  /** Lease duration in ms; an expired lease sends the job back to pending. */\n  leaseDuration?: number\n  /** Optional cooperative execution deadline in ms. */\n  maxRuntime?: number\n  /** @deprecated Use leaseDuration. */\n  timeout?: number\n}\n\nexport function leaseDurationFor<T extends BackgroundTiming>(def: T): number {\n  return def.leaseDuration ?? def.timeout ?? DEFAULT_LEASE_DURATION_MS\n}\n\nexport type EnqueueOptions = {\n  /** Collapse duplicate enqueues while the queue row is non-terminal. */\n  dedupeKey?: string\n  /** Milliseconds from now until the job becomes claimable. */\n  delay?: number\n  /** Absolute time the job becomes claimable; wins over `delay`. */\n  runAt?: Date | number\n}\n\nexport type TickResult = {\n  /** Rows moved from pending to running this tick. */\n  claimed: number\n  /** Handlers that completed successfully. */\n  ran: number\n  /** Handlers that threw, whether or not they will be retried. */\n  failed: number\n}\n\n/**\n * The untyped runtime facade. Job handlers and API context expose this shape;\n * `app.jobs` narrows `enqueue` to the declared job names/payloads.\n */\nexport type JobsRuntimeFacade = {\n  enqueue(\n    name: string,\n    input?: unknown,\n    opts?: EnqueueOptions,\n  ): Promise<{ id: string }>\n  /** Run one poll cycle deterministically (tests). `now` defaults to Date.now(). */\n  tick(now?: number): Promise<TickResult>\n}\n\nimport type { RealtimeFacade } from '../realtime/facade'\n\nexport type JobContext<\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = {\n  db: DbFor<TSchema>\n  env: TEnvResult\n  email: EmailFacade\n  storage: StorageFacade\n  jobs: JobsRuntimeFacade\n  realtime: RealtimeFacade<TSchema>\n  /** Aborted when execution reaches its deadline or the job loses its lease. */\n  signal: AbortSignal\n}\n\nexport type BunderstackJobContext<\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = JobContext<TSchema, TEnvResult>\n\nexport type QueueJobDefinition<\n  TInput,\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = BackgroundTiming & {\n  kind: 'job'\n  /** Standard Schema payload; parsed at enqueue AND before the handler runs. */\n  input?: StandardSchemaV1<unknown, TInput>\n  /** Attempts after the first failure. Default 3 (so 4 total attempts). */\n  retries?: number\n  /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */\n  backoff?: ((attempt: number) => number) | { baseMs?: number; factor?: number }\n  /** Max simultaneous `running` rows of this type, enforced per worker. */\n  concurrency?: number\n  handler: (\n    input: TInput,\n    ctx: JobContext<TSchema, TEnvResult>,\n  ) => Promise<void> | void\n  /** Fires once, after the final attempt fails. Errors here are logged, never retried. */\n  onFailed?: (\n    input: TInput,\n    error: Error,\n    ctx: JobContext<TSchema, TEnvResult>,\n  ) => Promise<void> | void\n}\n\nexport type CronInvocation = { scheduledFor: Date }\n\nexport type CronDefinition<\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n  TSchedule extends string = string,\n> = BackgroundTiming & {\n  kind: 'cron'\n  schedule: TSchedule\n  /** Attempts after the first failure. Default 3 (so 4 total attempts). */\n  retries?: number\n  /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */\n  backoff?: ((attempt: number) => number) | { baseMs?: number; factor?: number }\n  /** How missed slots are handled on wake. Default 'latest'. */\n  catchUp?: CatchUp\n  /** How far back catch-up looks, in ms. Default 1 hour. */\n  catchUpWindow?: number\n  handler: (\n    invocation: CronInvocation,\n    ctx: JobContext<TSchema, TEnvResult>,\n  ) => Promise<void> | void\n  /** Fires once, after the final attempt fails. Errors here are logged, never retried. */\n  onFailed?: (\n    invocation: CronInvocation,\n    error: Error,\n    ctx: JobContext<TSchema, TEnvResult>,\n  ) => Promise<void> | void\n}\n\nexport type BackgroundDefinition =\n  | QueueJobDefinition<any, any, any>\n  | CronDefinition<any, any>\nexport type BackgroundDefs = Record<string, BackgroundDefinition>\n\n/** @deprecated Use QueueJobDefinition. */\nexport type JobDefinition<\n  TInput,\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = QueueJobDefinition<TInput, TSchema, TEnvResult>\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyJobDefinition = QueueJobDefinition<any, any, any>\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyBackgroundDefinition =\n  | QueueJobDefinition<any, any, any>\n  | CronDefinition<any, any, any>\nexport type JobsDefs = BackgroundDefs\n\nexport type QueueJobKeys<TDefs extends BackgroundDefs> = {\n  [K in keyof TDefs & string]: TDefs[K] extends QueueJobDefinition<\n    any,\n    any,\n    any\n  >\n    ? K\n    : never\n}[keyof TDefs & string]\n\n/** Throws when a definition is unusable. Safe to call more than once. */\nexport function validateBackgroundDefs(defs: BackgroundDefs): void {\n  for (const [name, def] of Object.entries(defs)) {\n    if (typeof def.handler !== 'function') {\n      throw new Error(`[bunderstack] background task \"${name}\" has no handler`)\n    }\n    if (def.kind === 'job' && name.startsWith(CRON_PREFIX)) {\n      throw new Error(\n        `[bunderstack] job \"${name}\": the \"${CRON_PREFIX}\" prefix is reserved for cron tasks`,\n      )\n    }\n    if (\n      def.retries !== undefined &&\n      (def.retries < 0 || !Number.isInteger(def.retries))\n    ) {\n      throw new Error(\n        `[bunderstack] background task \"${name}\": retries must be a non-negative integer`,\n      )\n    }\n    if (def.timeout !== undefined && def.leaseDuration !== undefined) {\n      throw new Error(\n        `[bunderstack] background task \"${name}\": timeout and leaseDuration cannot both be declared`,\n      )\n    }\n    for (const field of ['timeout', 'leaseDuration', 'maxRuntime'] as const) {\n      const value = def[field]\n      if (\n        value !== undefined &&\n        (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0)\n      ) {\n        throw new Error(\n          `[bunderstack] background task \"${name}\": ${field} must be a positive finite integer`,\n        )\n      }\n    }\n    if (def.kind === 'cron') {\n      parseCron(def.schedule)\n      if ((def as { concurrency?: number }).concurrency !== undefined) {\n        throw new Error(\n          `[bunderstack] cron \"${name}\": concurrency is not supported for cron tasks — slots are already unique`,\n        )\n      }\n      if (def.catchUpWindow !== undefined && def.catchUpWindow <= 0) {\n        throw new Error(\n          `[bunderstack] cron \"${name}\": catchUpWindow must be positive`,\n        )\n      }\n      continue\n    }\n    if (\n      def.concurrency !== undefined &&\n      (def.concurrency < 1 || !Number.isInteger(def.concurrency))\n    ) {\n      throw new Error(\n        `[bunderstack] job \"${name}\": concurrency must be a positive integer`,\n      )\n    }\n  }\n}\n\n/** @deprecated Use validateBackgroundDefs. */\nexport const validateJobsDefs = validateBackgroundDefs\n\n/**\n * Delay in ms before retry `attempt` (1-based = the attempt that just failed).\n * Jittered by ±20% so a shared outage does not retry every job in lockstep.\n * A caller-supplied backoff function is returned verbatim — the caller owns it.\n */\nexport function backoffMs(\n  def: AnyBackgroundDefinition,\n  attempt: number,\n): number {\n  const b = def.backoff\n  if (typeof b === 'function') return b(attempt)\n  const baseMs = b?.baseMs ?? 1000\n  const factor = b?.factor ?? 2\n  const flat = baseMs * factor ** (attempt - 1)\n  return Math.round(flat * (0.8 + Math.random() * 0.4))\n}\n\n/**\n * Build the `j` instance bunderstack hands to the config's `jobs` builder\n * callback (and exports for multi-file job setups).\n */\nexport function createJobsBuilder<\n  TSchema extends Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n>() {\n  return {\n    /** Identity with inference: pins TInput from the schema output. */\n    job<TInput = undefined>(\n      def: Omit<QueueJobDefinition<TInput, TSchema, TEnvResult>, 'kind'>,\n    ): QueueJobDefinition<TInput, TSchema, TEnvResult> {\n      return { kind: 'job', ...def }\n    },\n    cron<const TSchedule extends string>(\n      def: Omit<CronDefinition<TSchema, TEnvResult, TSchedule>, 'kind'>,\n    ): CronDefinition<TSchema, TEnvResult, TSchedule> {\n      parseCron(def.schedule)\n      return { kind: 'cron', ...def }\n    },\n    /** Identity with validation: returns the defs map, typed. */\n    define<TDefs extends BackgroundDefs>(defs: TDefs): TDefs {\n      validateBackgroundDefs(defs)\n      return defs\n    },\n  }\n}\n\n/** Type of the `j` instance — for builder callbacks declared in separate files. */\nexport type BunderstackJobsBuilder<\n  TSchema extends Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n> = ReturnType<typeof createJobsBuilder<TSchema, TEnvResult>>\n\n// Infers TInput from the JobDefinition's own type argument rather than\n// pattern-matching the (optional, so union-with-undefined) `input` property —\n// A required-property pattern fails structurally because `input` is optional,\n// so infer from the definition's own type argument instead.\ntype JobInputOf<TDef> =\n  TDef extends QueueJobDefinition<infer TInput, any, any> ? TInput : undefined\n\n/**\n * `app.jobs`: `enqueue` narrowed to declared names + payloads. `Omit`s the\n * runtime facade's loose `enqueue` first — intersecting two same-named\n * methods instead would make TS treat them as overloaded, so the loose\n * `(name: string, ...)` signature would still accept any name.\n */\nexport type JobsFacade<TDefs extends JobsDefs> = Omit<\n  JobsRuntimeFacade,\n  'enqueue'\n> & {\n  enqueue<K extends QueueJobKeys<TDefs>>(\n    name: K,\n    ...rest: JobInputOf<TDefs[K]> extends undefined\n      ? [input?: undefined, opts?: EnqueueOptions]\n      : [input: JobInputOf<TDefs[K]>, opts?: EnqueueOptions]\n  ): Promise<{ id: string }>\n}\n"]}

package/dist/jobs/index.d.ts

@@ -1,5 +1,5 @@
-export { createJobsBuilder, validateBackgroundDefs, validateJobsDefs, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS, } from './define.js';
-export type { AnyJobDefinition, BackgroundDefinition, BackgroundDefs, BunderstackJobContext, BunderstackJobsBuilder, EnqueueOptions, JobContext, JobDefinition, QueueJobDefinition, CronDefinition, CronInvocation, QueueJobKeys, JobsDefs, JobsFacade, JobsRuntimeFacade, } from './define.js';
+export { createJobsBuilder, validateBackgroundDefs, validateJobsDefs, DEFAULT_RETRIES, DEFAULT_LEASE_DURATION_MS, DEFAULT_TIMEOUT_MS, leaseDurationFor, } from './define.js';
+export type { AnyJobDefinition, BackgroundTiming, BackgroundDefinition, BackgroundDefs, BunderstackJobContext, BunderstackJobsBuilder, EnqueueOptions, JobContext, JobDefinition, QueueJobDefinition, CronDefinition, CronInvocation, QueueJobKeys, JobsDefs, JobsFacade, JobsRuntimeFacade, } from './define.js';
 export { enqueueJob } from './queue.js';
 export { createJobRunner } from './worker.js';
 export { startJobWorker } from './runtime.js';

package/dist/jobs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,GACnB,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,iBAAiB,GAClB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACnE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,iBAAiB,GAClB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACnE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA"}

package/dist/jobs/index.js

@@ -1,5 +1,5 @@
 // src/jobs/index.ts — module surface consumed by bunderstack.
-export { createJobsBuilder, validateBackgroundDefs, validateJobsDefs, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS, } from './define.js';
+export { createJobsBuilder, validateBackgroundDefs, validateJobsDefs, DEFAULT_RETRIES, DEFAULT_LEASE_DURATION_MS, DEFAULT_TIMEOUT_MS, leaseDurationFor, } from './define.js';
 export { enqueueJob } from './queue.js';
 export { createJobRunner } from './worker.js';
 export { startJobWorker } from './runtime.js';

package/dist/jobs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,GACnB,MAAM,UAAU,CAAA;AAkBjB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAO1C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA","sourcesContent":["// src/jobs/index.ts — module surface consumed by bunderstack.\nexport {\n  createJobsBuilder,\n  validateBackgroundDefs,\n  validateJobsDefs,\n  DEFAULT_RETRIES,\n  DEFAULT_TIMEOUT_MS,\n} from './define'\nexport type {\n  AnyJobDefinition,\n  BackgroundDefinition,\n  BackgroundDefs,\n  BunderstackJobContext,\n  BunderstackJobsBuilder,\n  EnqueueOptions,\n  JobContext,\n  JobDefinition,\n  QueueJobDefinition,\n  CronDefinition,\n  CronInvocation,\n  QueueJobKeys,\n  JobsDefs,\n  JobsFacade,\n  JobsRuntimeFacade,\n} from './define'\nexport { enqueueJob } from './queue'\nexport { createJobRunner } from './worker'\nexport { startJobWorker } from './runtime'\nexport type {\n  StartWorkerOptions,\n  RunWorkerOptions,\n  WorkerCycleResult,\n  WorkerHandle,\n} from './runtime'\nexport { parseCron, cronMatches } from './cron'\nexport { slotsDue, floorSlot, CRON_PREFIX, SLOT_MS } from './slots'\nexport type { CatchUp } from './slots'\nexport type { TickResult } from './define'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,UAAU,CAAA;AAmBjB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAO1C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA","sourcesContent":["// src/jobs/index.ts — module surface consumed by bunderstack.\nexport {\n  createJobsBuilder,\n  validateBackgroundDefs,\n  validateJobsDefs,\n  DEFAULT_RETRIES,\n  DEFAULT_LEASE_DURATION_MS,\n  DEFAULT_TIMEOUT_MS,\n  leaseDurationFor,\n} from './define'\nexport type {\n  AnyJobDefinition,\n  BackgroundTiming,\n  BackgroundDefinition,\n  BackgroundDefs,\n  BunderstackJobContext,\n  BunderstackJobsBuilder,\n  EnqueueOptions,\n  JobContext,\n  JobDefinition,\n  QueueJobDefinition,\n  CronDefinition,\n  CronInvocation,\n  QueueJobKeys,\n  JobsDefs,\n  JobsFacade,\n  JobsRuntimeFacade,\n} from './define'\nexport { enqueueJob } from './queue'\nexport { createJobRunner } from './worker'\nexport { startJobWorker } from './runtime'\nexport type {\n  StartWorkerOptions,\n  RunWorkerOptions,\n  WorkerCycleResult,\n  WorkerHandle,\n} from './runtime'\nexport { parseCron, cronMatches } from './cron'\nexport { slotsDue, floorSlot, CRON_PREFIX, SLOT_MS } from './slots'\nexport type { CatchUp } from './slots'\nexport type { TickResult } from './define'\n"]}

package/dist/jobs/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/jobs/worker.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,KAAK,EAEV,QAAQ,EACR,iBAAiB,EACjB,UAAU,EACX,MAAM,UAAU,CAAA;AA4BjB,KAAK,UAAU,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAA;AAmC1C,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,EAAE,EAAE,KAAK,CAAA;IACT,IAAI,EAAE,QAAQ,CAAA;IACd,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5B,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAC3B;eA4WmB,MAAM,GAAgB,OAAO,CAAC,UAAU,CAAC;iBAnBlC,MAAM,KAAgB,OAAO,CAAC,UAAU,CAAC;iBAa1C,OAAO,CAAC,IAAI,CAAC;iBAYhB,MAAM;;;;;;;;;;;;oBAiEb,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ;;;;;;;qBAQH,iBAAiB;EAIrC"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/jobs/worker.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,KAAK,EAEV,QAAQ,EACR,iBAAiB,EACjB,UAAU,EACX,MAAM,UAAU,CAAA;AAqDjB,KAAK,UAAU,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAA;AAkD1C,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,EAAE,EAAE,KAAK,CAAA;IACT,IAAI,EAAE,QAAQ,CAAA;IACd,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5B,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAC3B;eA0fmB,MAAM,GAAgB,OAAO,CAAC,UAAU,CAAC;iBAnBlC,MAAM,KAAgB,OAAO,CAAC,UAAU,CAAC;iBAa1C,OAAO,CAAC,IAAI,CAAC;iBAYhB,MAAM;;;;;;;;;;;;oBAiEb,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ;;;;;;;qBAQH,iBAAiB;EAIrC"}

package/dist/jobs/worker.js

@@ -6,12 +6,34 @@ import { jobsTableFor } from '../internal-tables.js';
 import { consoleLogger } from '../logging.js';
 import { validateStandardSchema } from '../standard-schema.js';
 import { parseCron } from './cron.js';
-import { backoffMs, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS } from './define.js';
+import { backoffMs, DEFAULT_RETRIES, leaseDurationFor } from './define.js';
 import { enqueueJob } from './queue.js';
 import { CRON_PREFIX, floorSlot, slotsDue, SLOT_MS } from './slots.js';
 const CLAIM_BATCH = 10;
 const SUCCEEDED_RETENTION_MS = 24 * 60 * 60 * 1000;
 const REAP_INTERVAL_MS = 60 * 60_000;
+class JobExecutionTimeoutError extends Error {
+    constructor(maxRuntime) {
+        super(`execution timed out after ${maxRuntime}ms`);
+        this.name = 'JobExecutionTimeoutError';
+    }
+}
+class JobLeaseLostError extends Error {
+    constructor() {
+        super('job lease ownership was lost');
+        this.name = 'JobLeaseLostError';
+    }
+}
+function jobEvent(event, row, fields = {}) {
+    return {
+        source: 'bunderstack.jobs',
+        event,
+        jobId: row.id,
+        jobType: row.type,
+        attempt: Number(row.attempts),
+        ...fields,
+    };
+}
 function capacityFor(def) {
     return def.kind === 'job' && def.concurrency !== undefined
         ? def.concurrency
@@ -44,6 +66,54 @@ export function createJobRunner(deps) {
     const ctx = { ...deps.ctx };
     let lastReapAt = 0;
     const active = new Map();
+    function ownershipPredicate(id, owner) {
+        return and(eq(t.id, id), eq(t.status, 'running'), eq(t.attempts, owner.attempt), eq(t.lockedUntil, owner.lockedUntil));
+    }
+    function startLeaseHeartbeat(args) {
+        const owner = args.owner;
+        const intervalMs = Math.max(10, Math.floor(leaseDurationFor(args.def) / 3));
+        let stopped = false;
+        let resolveLost;
+        const lost = new Promise((resolve) => {
+            resolveLost = resolve;
+        });
+        let chain = Promise.resolve();
+        const lose = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(timer);
+            resolveLost();
+            args.onLost();
+        };
+        const renew = () => {
+            chain = chain
+                .then(async () => {
+                if (stopped)
+                    return;
+                const nextLockedUntil = Date.now() + leaseDurationFor(args.def);
+                const updated = await db
+                    .update(t)
+                    .set({ lockedUntil: nextLockedUntil })
+                    .where(ownershipPredicate(args.row.id, owner))
+                    .returning({ id: t.id });
+                if (!updated[0])
+                    return lose();
+                owner.lockedUntil = nextLockedUntil;
+            })
+                .catch(() => lose());
+        };
+        const timer = setInterval(renew, intervalMs);
+        return {
+            owner,
+            lost,
+            async stop() {
+                stopped = true;
+                clearInterval(timer);
+                await chain;
+            },
+        };
+    }
     /** Cron rows carry no payload — their handler input is the slot itself. */
     function resolveInput(def, row) {
         if (def.kind === 'cron') {
@@ -110,10 +180,15 @@ export function createJobRunner(deps) {
             attempts: t.attempts,
             lastError: t.lastError,
             runAt: t.runAt,
+            lockedUntil: t.lockedUntil,
         })
             .from(t)
             .where(and(eq(t.status, 'running'), isNotNull(t.lockedUntil), lt(t.lockedUntil, now)));
         for (const row of expired) {
+            const owner = {
+                attempt: Number(row.attempts),
+                lockedUntil: Number(row.lockedUntil),
+            };
             const def = definitionFor(defs, row.type);
             const error = new Error('lease expired (worker crashed or timed out)');
             if (!def) {
@@ -126,11 +201,11 @@ export function createJobRunner(deps) {
                     lastError: `unknown job type "${row.type}"`,
                     dedupeKey: null,
                 })
-                    .where(eq(t.id, row.id));
+                    .where(ownershipPredicate(row.id, owner));
                 continue;
             }
             if (Number(row.attempts) >= maxAttempts(def)) {
-                await db
+                const updated = await db
                     .update(t)
                     .set({
                     status: 'failed',
@@ -139,8 +214,10 @@ export function createJobRunner(deps) {
                     lastError: error.message,
                     ...terminalPatch(),
                 })
-                    .where(eq(t.id, row.id));
-                await fireOnFailed(def, resolveInput(def, row), error);
+                    .where(ownershipPredicate(row.id, owner))
+                    .returning({ id: t.id });
+                if (updated[0])
+                    await fireOnFailed(def, resolveInput(def, row), error);
             }
             else {
                 await db
@@ -151,7 +228,7 @@ export function createJobRunner(deps) {
                     runAt: now + backoffMs(def, Number(row.attempts)),
                     lastError: error.message,
                 })
-                    .where(eq(t.id, row.id));
+                    .where(ownershipPredicate(row.id, owner));
             }
         }
     }
@@ -198,13 +275,18 @@ export function createJobRunner(deps) {
         let available = capacityFor(def) - runningRows.length;
         if (available <= 0)
             return [];
-        const leaseUntil = now + (def.timeout ?? DEFAULT_TIMEOUT_MS);
+        const leaseUntil = now + leaseDurationFor(def);
         const work = [];
         while (available > 0) {
             const limit = Math.min(CLAIM_BATCH, available);
             const rows = await claim(type, limit, now, leaseUntil);
-            for (const row of rows)
-                work.push({ row, def, leaseUntil });
+            for (const row of rows) {
+                work.push({
+                    row,
+                    def,
+                    owner: { attempt: Number(row.attempts), lockedUntil: leaseUntil },
+                });
+            }
             available -= rows.length;
             if (rows.length < limit)
                 break;
@@ -214,7 +296,8 @@ export function createJobRunner(deps) {
     // `now` is the tick's injected clock: retry runAt math uses it so tests can
     // drive backoff deterministically. finishedAt uses the real clock (a handler
     // may run long past the tick's start).
-    async function runJob(row, def, now, leaseUntil) {
+    async function runJob(row, def, now, owner) {
+        const startedAt = Date.now();
         let input;
         try {
             input = resolveInput(def, row);
@@ -231,15 +314,47 @@ export function createJobRunner(deps) {
                 lastError: e.message,
                 ...terminalPatch(),
             })
-                .where(and(eq(t.id, row.id), eq(t.lockedUntil, leaseUntil)))
+                .where(ownershipPredicate(row.id, owner))
                 .returning({ id: t.id });
             if (!updated[0])
                 return 'lost';
             await fireOnFailed(def, undefined, e);
             return 'failed';
         }
+        const controller = new AbortController();
+        const handlerCtx = { ...ctx, signal: controller.signal };
+        logger.info(JSON.stringify(jobEvent('job.claimed', row)));
+        let lost = false;
+        const heartbeat = startLeaseHeartbeat({
+            row,
+            def,
+            owner,
+            onLost: () => {
+                lost = true;
+                controller.abort(new JobLeaseLostError());
+                logger.warn(JSON.stringify(jobEvent('job.lease_lost', row, {
+                    durationMs: Date.now() - startedAt,
+                })));
+            },
+        });
+        const deadline = def.maxRuntime === undefined
+            ? undefined
+            : setTimeout(() => {
+                controller.abort(new JobExecutionTimeoutError(def.maxRuntime));
+                logger.warn(JSON.stringify(jobEvent('job.execution_timed_out', row, {
+                    durationMs: Date.now() - startedAt,
+                })));
+            }, def.maxRuntime);
         try {
-            await def.handler(input, ctx);
+            await def.handler(input, handlerCtx);
+            if (controller.signal.reason instanceof JobExecutionTimeoutError) {
+                throw controller.signal.reason;
+            }
+            if (deadline)
+                clearTimeout(deadline);
+            await heartbeat.stop();
+            if (lost)
+                return 'lost';
             const updated = await db
                 .update(t)
                 .set({
@@ -248,14 +363,22 @@ export function createJobRunner(deps) {
                 lockedUntil: null,
                 ...terminalPatch(),
             })
-                .where(and(eq(t.id, row.id), eq(t.lockedUntil, leaseUntil)))
+                .where(ownershipPredicate(row.id, owner))
                 .returning({ id: t.id });
             if (!updated[0])
                 return 'lost';
+            logger.info(JSON.stringify(jobEvent('job.completed', row, { durationMs: Date.now() - startedAt })));
             return 'ran';
         }
         catch (err) {
-            const e = toError(err);
+            if (deadline)
+                clearTimeout(deadline);
+            const e = controller.signal.reason instanceof JobExecutionTimeoutError
+                ? controller.signal.reason
+                : toError(err);
+            await heartbeat.stop();
+            if (lost)
+                return 'lost';
             if (Number(row.attempts) < maxAttempts(def)) {
                 const updated = await db
                     .update(t)
@@ -265,10 +388,14 @@ export function createJobRunner(deps) {
                     runAt: now + backoffMs(def, Number(row.attempts)),
                     lastError: e.message,
                 })
-                    .where(and(eq(t.id, row.id), eq(t.lockedUntil, leaseUntil)))
+                    .where(ownershipPredicate(row.id, owner))
                     .returning({ id: t.id });
                 if (!updated[0])
                     return 'lost';
+                logger.warn(JSON.stringify(jobEvent('job.retrying', row, {
+                    durationMs: Date.now() - startedAt,
+                    error: e.message,
+                })));
             }
             else {
                 const updated = await db
@@ -280,10 +407,14 @@ export function createJobRunner(deps) {
                     lastError: e.message,
                     ...terminalPatch(),
                 })
-                    .where(and(eq(t.id, row.id), eq(t.lockedUntil, leaseUntil)))
+                    .where(ownershipPredicate(row.id, owner))
                     .returning({ id: t.id });
                 if (!updated[0])
                     return 'lost';
+                logger.error(JSON.stringify(jobEvent('job.failed', row, {
+                    durationMs: Date.now() - startedAt,
+                    error: e.message,
+                })));
                 await fireOnFailed(def, input, e);
             }
             return 'failed';
@@ -301,7 +432,7 @@ export function createJobRunner(deps) {
         // Claim the whole tick snapshot before starting any handler. Work enqueued
         // by a handler therefore belongs to the next tick, regardless of the
         // declaration order of its target job type.
-        const outcomes = await Promise.all(claimedWork.map(({ row, def, leaseUntil }) => runJob(row, def, now, leaseUntil)));
+        const outcomes = await Promise.all(claimedWork.map(({ row, def, owner }) => runJob(row, def, now, owner)));
         let ran = 0;
         let failed = 0;
         for (const outcome of outcomes) {
@@ -327,7 +458,7 @@ export function createJobRunner(deps) {
             active.set(type, tasks);
         }
         let task;
-        task = runJob(work.row, work.def, claimedAt, work.leaseUntil)
+        task = runJob(work.row, work.def, claimedAt, work.owner)
             .then(() => undefined)
             .catch((error) => {
             logger.error('[bunderstack] background job execution failed:', error);