alepha 0.20.4 → 0.20.6

package/dist/api/jobs/index.js

@@ -1,11 +1,11 @@
 import { $atom, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, PipelinePrimitive, createPrimitive, t } from "alepha";
-import { AlephaLock } from "alepha/lock";
+import { AlephaLock, LockProvider } from "alepha/lock";
 import { $queue, AlephaQueue } from "alepha/queue";
 import { AlephaScheduler, CronProvider } from "alepha/scheduler";
 import { $secure } from "alepha/security";
 import { $action, NotFoundError, okSchema } from "alepha/server";
 import { $logger, logEntrySchema } from "alepha/logger";
-import { $entity, $repository, db, sql } from "alepha/orm";
+import { $entity, $repository, DbEntityNotFoundError, db, sql } from "alepha/orm";
 import { DateTimeProvider } from "alepha/datetime";
 //#region ../../src/api/jobs/schemas/jobExecutionQuerySchema.ts
 const jobExecutionQuerySchema = t.object({
@@ -33,11 +33,11 @@ const jobExecutionQuerySchema = t.object({
 * the last N rows per job (configurable via `jobConfig.keepLastSuccess`).
 *
 * Status transitions:
-* - queue push            → pending
+* - queue push            → pending (or `scheduled` if `delay`/`scheduledAt` was given)
 * - worker claim          → running
-* - success               → ok
+* - success               → ok (or row deleted, depending on `record` and `keepLastSuccess`)
 * - terminal failure      → error
-* - retry                 → scheduled (with scheduledAt = now + backoff)
+* - retryable failure     → scheduled (with scheduledAt = now; sweep picks it up)
 * - delay                 → scheduled (with scheduledAt = now + delay)
 * - sweep picks due ones  → pending
 * - cancel                → cancelled
@@ -90,10 +90,28 @@ const jobExecutionEntity = $entity({
 });
 //#endregion
 //#region ../../src/api/jobs/schemas/jobExecutionResourceSchema.ts
-const jobExecutionResourceSchema = t.extend(jobExecutionEntity.schema, { can: t.object({
-	retry: t.boolean(),
-	cancel: t.boolean()
-}) }, {
+/**
+* Public-facing schema for a job execution row.
+*
+* Diverges from the raw entity in two places, both for API ergonomics:
+*
+* - `priority` is exposed as the **string enum** (`critical`/`high`/...)
+*   instead of the numeric value used internally for SQL ordering. The
+*   `JobService` is responsible for the int → string transform.
+* - `can` derives the available admin actions from the row's status.
+*/
+const jobExecutionResourceSchema = t.extend(jobExecutionEntity.schema, {
+	priority: t.enum([
+		"critical",
+		"high",
+		"normal",
+		"low"
+	]),
+	can: t.object({
+		retry: t.boolean(),
+		cancel: t.boolean()
+	})
+}, {
 	title: "JobExecutionResource",
 	description: "A job execution row with derived actions."
 });
@@ -102,7 +120,11 @@ const jobExecutionResourceSchema = t.extend(jobExecutionEntity.schema, { can: t.
 const jobRegistrationSchema = t.object({
 	name: t.text(),
 	description: t.optional(t.text()),
-	type: t.enum(["cron", "queue"]),
+	type: t.enum([
+		"cron",
+		"queue",
+		"direct"
+	], { description: "Effective runtime mode. 'cron' = scheduled. 'queue' = push-driven, dispatched via AlephaApiJobsQueue. 'direct' = push-driven, processed in-process (no queue infrastructure loaded), with the sweep as the safety net." }),
 	priority: t.enum([
 		"critical",
 		"high",
@@ -111,10 +133,7 @@ const jobRegistrationSchema = t.object({
 	]),
 	cron: t.optional(t.text()),
 	timeout: t.optional(t.text()),
-	retry: t.optional(t.object({
-		retries: t.integer(),
-		hasBackoff: t.boolean()
-	})),
+	retry: t.optional(t.object({ retries: t.integer() })),
 	recent: t.object({
 		ok: t.integer(),
 		error: t.integer(),
@@ -130,7 +149,7 @@ const jobConfig = $atom({
 	name: "alepha.jobs",
 	description: "Configuration for the $job primitive.",
 	schema: t.object({
-		sweepInterval: t.integer({ description: "Sweep cron interval in milliseconds." }),
+		sweepCron: t.text({ description: "Cron expression for the sweep tick. Must be minute-granular at minimum (cron resolution). On Cloudflare Workers this expression is emitted into wrangler.jsonc by the build." }),
 		staleThreshold: t.integer({ description: "Pending age (ms) before the sweep re-dispatches it." }),
 		runTimeout: t.integer({ description: "Running age (ms) before assumed crash (fallback when no per-job timeout)." }),
 		keepLastSuccess: t.integer({ description: "Max successful rows to keep per job. Set 0 to disable and delete on success." }),
@@ -139,7 +158,7 @@ const jobConfig = $atom({
 		drainTimeout: t.integer({ description: "Max time (ms) to wait for in-flight jobs during shutdown." })
 	}),
 	default: {
-		sweepInterval: 3e5,
+		sweepCron: "*/5 * * * *",
 		staleThreshold: 3e5,
 		runTimeout: 18e5,
 		keepLastSuccess: 10,
@@ -149,6 +168,135 @@ const jobConfig = $atom({
 	}
 });
 //#endregion
+//#region ../../src/api/jobs/providers/JobDispatcher.ts
+/**
+* Abstract dispatcher for queued/direct job executions.
+*
+* The default implementation, {@link DirectJobDispatcher}, runs the handler
+* in-process after the caller's `push()` returns — fast and dependency-free.
+*
+* `AlephaApiJobsQueue` substitutes this with `JobQueueProvider`, which
+* publishes the executionId to `AlephaQueue` so a worker pool can consume
+* the work asynchronously.
+*
+* Substitute via DI:
+* ```ts
+* Alepha.create()
+*   .with({ provide: JobDispatcher, use: MyCustomDispatcher })
+*   .with(AlephaApiJobs);
+* ```
+*
+* The `kind` getter is read by the `JobProvider.effectiveMode` accessor
+* and by the admin UI so users can see which dispatcher is currently active.
+*/
+var JobDispatcher = class {
+	/**
+	* Optional batch dispatch. The default implementation loops, but
+	* dispatchers backed by a real queue should override this to use the
+	* provider's batch send (e.g. Cloudflare Queues `sendBatch`).
+	*/
+	async dispatchMany(items) {
+		for (const item of items) await this.dispatch(item.jobName, item.executionId);
+	}
+};
+//#endregion
+//#region ../../src/api/jobs/providers/DirectJobDispatcher.ts
+/**
+* Default `JobDispatcher` for environments without `AlephaApiJobsQueue`.
+*
+* Runs `JobProvider.processExecution` in the background — the caller's
+* `push()` returns immediately while the handler continues to completion
+* in the same process. The DB outbox row is the durability guarantee:
+* if the process dies before the handler finishes, the next sweep tick
+* picks the row up and re-dispatches.
+*
+* **Cloudflare Workers** — when an `executionCtx.waitUntil` is available
+* in the alepha store at `cloudflare.waitUntil`, the dispatch wraps the
+* background promise with `waitUntil` so the runtime keeps the isolate
+* alive past the HTTP response. Without this, the handler would be
+* terminated when the response is returned and only the next sweep
+* (every 5 min by default) would re-dispatch.
+*
+* **Vercel / single-Node** — on long-running runtimes the event loop
+* keeps the promise alive naturally; no special wiring is required.
+*/
+var DirectJobDispatcher = class extends JobDispatcher {
+	kind = "direct";
+	alepha = $inject(Alepha);
+	log = $logger();
+	jobProviderRef;
+	getJobProvider() {
+		if (!this.jobProviderRef) this.jobProviderRef = this.alepha.inject(JobProvider);
+		return this.jobProviderRef;
+	}
+	async dispatch(jobName, executionId) {
+		const promise = this.getJobProvider().processExecution(jobName, executionId).catch((err) => {
+			this.log.warn(`Direct execution failed for '${jobName}' (sweep will retry)`, err);
+		});
+		const waitUntil = this.alepha.store.get("cloudflare.waitUntil");
+		if (typeof waitUntil === "function") try {
+			waitUntil(promise);
+		} catch (e) {
+			this.log.debug("waitUntil rejected — falling back to fire-and-track", e);
+		}
+	}
+};
+//#endregion
+//#region ../../src/api/jobs/providers/JobQueueProvider.ts
+/**
+* Queue-backed `JobDispatcher` registered by `AlephaApiJobsQueue`.
+*
+* Extends {@link JobDispatcher} and substitutes the default
+* `DirectJobDispatcher` so that `$job.push()` is delivered through
+* `AlephaQueue` (e.g. Cloudflare Queues, Redis, in-memory) instead of
+* being processed in-process.
+*
+* The class is also kept as a `JobQueueProvider` export name for backwards
+* compatibility — it has always been the queue path's entry point.
+*/
+var JobQueueProvider = class extends JobDispatcher {
+	kind = "queue";
+	alepha = $inject(Alepha);
+	jobProviderRef;
+	getJobProvider() {
+		if (!this.jobProviderRef) this.jobProviderRef = this.alepha.inject(JobProvider);
+		return this.jobProviderRef;
+	}
+	queue = $queue({
+		name: "api:jobs:dispatch",
+		schema: t.object({
+			jobName: t.text(),
+			executionId: t.text()
+		}),
+		handler: async (msg) => {
+			await this.getJobProvider().processExecution(msg.payload.jobName, msg.payload.executionId);
+		}
+	});
+	async dispatch(jobName, executionId) {
+		await this.queue.push({
+			jobName,
+			executionId
+		});
+	}
+	/**
+	* Fan-out to a single variadic `queue.push(...payloads)` call so the
+	* underlying queue provider can batch the network round-trips when it
+	* supports it (Cloudflare Queues, Redis pipelines).
+	*/
+	async dispatchMany(items) {
+		if (items.length === 0) return;
+		await this.queue.push(...items);
+	}
+	/**
+	* Backwards-compatible alias for {@link dispatch}. Older code paths called
+	* `JobQueueProvider.push(jobName, executionId)` directly; new code should
+	* go through the `JobDispatcher.dispatch` API.
+	*/
+	async push(jobName, executionId) {
+		return this.dispatch(jobName, executionId);
+	}
+};
+//#endregion
 //#region ../../src/api/jobs/providers/JobProvider.ts
 const PRIORITY_MAP = {
 	critical: 0,
@@ -162,29 +310,50 @@ const PRIORITY_REVERSE = {
 	2: "normal",
 	3: "low"
 };
-const SWEEP_CRON = "*/5 * * * *";
 /**
-* Coordinates cron (scheduler) and queue (push) jobs with a durable outbox
-* table and a single reconciliation sweep.
+* Coordinates cron and push jobs with a durable outbox table and a single
+* reconciliation sweep. The actual delivery channel (queue / direct) is
+* abstracted behind {@link JobDispatcher}, substituted by DI:
 *
-* Queue-mode flow:
-*   push()  → INSERT row (pending) + queue.send({ executionId })
-*   worker  → SELECT row → UPDATE running → handler → DELETE (ok) / UPDATE (error)
+* - **DirectJobDispatcher** (default, registered by `AlephaApiJobs`) —
+*   runs the handler in-process right after `push()` returns.
+* - **QueueJobDispatcher** (registered by `AlephaApiJobsQueue`) — sends
+*   the executionId through `AlephaQueue` so a pool of workers can pick
+*   it up.
 *
-* Cron-mode flow:
-*   scheduler tick → handler runs inline → INSERT row only on error
+* Push flow:
+*   push()  → INSERT row (pending) → dispatcher.dispatch(jobName, id)
+*   worker  → claim → UPDATE running → handler → DELETE/UPDATE on success
+*           → UPDATE error / scheduled (retry) on failure
 *
-* Sweep responsibilities (every `sweepInterval`):
+* Cron flow:
+*   scheduler tick → acquire lock → executeInline (no retry)
+*                                 → enqueue + dispatch (retry declared)
+*
+* Sweep responsibilities (every `sweepCron`):
 *   - re-enqueue pending rows older than `staleThreshold`
-*   - fail running rows older than `max(timeout*2, runTimeout)`
-*   - move `scheduled` rows with `scheduledAt <= now` to pending + enqueue
+*   - mark crashed running rows as failed and apply retry policy
+*   - move `scheduled` rows with `scheduledAt <= now` to pending + dispatch
 *   - trim per-job history beyond `keepLastSuccess` / `keepLastError`
 */
 var JobProvider = class {
 	alepha = $inject(Alepha);
 	dt = $inject(DateTimeProvider);
 	cronProvider = $inject(CronProvider);
+	lockProvider = $inject(LockProvider);
 	config = $state(jobConfig);
+	/**
+	* Resolved at first use (after the container is fully wired) — picks
+	* the queue dispatcher when `AlephaApiJobsQueue` was loaded, otherwise
+	* the direct dispatcher. Lazy because both dispatchers inject
+	* `JobProvider` themselves; resolving them at field-init time would
+	* create a circular construction.
+	*/
+	dispatcherRef;
+	get dispatcher() {
+		if (!this.dispatcherRef) this.dispatcherRef = this.alepha.has(JobQueueProvider) ? this.alepha.inject(JobQueueProvider) : this.alepha.inject(DirectJobDispatcher);
+		return this.dispatcherRef;
+	}
 	log = $logger();
 	executions = $repository(jobExecutionEntity);
 	jobs = /* @__PURE__ */ new Map();
@@ -192,22 +361,17 @@ var JobProvider = class {
 	abortControllers = /* @__PURE__ */ new Map();
 	perExecutionLogs = /* @__PURE__ */ new Map();
 	stopping = false;
-	/**
-	* Set by `JobQueueProvider` when `AlephaApiJobsQueue` is loaded.
-	* When null, queue-mode jobs cannot be pushed.
-	*/
-	queueDispatch = null;
 	registerJob(name, options) {
 		if (this.jobs.has(name)) throw new AlephaError(`Job already registered: ${name}`);
 		if (options.cron && options.schema) throw new AlephaError(`Job '${name}' declares both 'cron' and 'schema'. A job must be either cron-only (recurring) or queue-only (push-based). Split into two jobs.`);
 		if (!options.cron && !options.schema) throw new AlephaError(`Job '${name}' must declare either 'cron' (for recurring tasks) or 'schema' (for queue-mode tasks).`);
-		const type = options.cron ? "cron" : "queue";
+		const kind = options.cron ? "cron" : "queue";
 		this.jobs.set(name, {
 			name,
 			options,
-			type
+			kind
 		});
-		this.log.debug(`Registered ${type} job '${name}'`, {
+		this.log.debug(`Registered ${kind} job '${name}'`, {
 			cron: options.cron,
 			priority: options.priority ?? "normal",
 			retries: options.retry?.retries ?? 0
@@ -223,24 +387,155 @@ var JobProvider = class {
 	getRegisteredJobs() {
 		return this.jobs;
 	}
+	/**
+	* Resolves what *actually* runs at dispatch time. Cron jobs are always
+	* "cron"; non-cron jobs delegate to the active `JobDispatcher` (queue
+	* vs. direct), which is determined by which modules the app loaded.
+	*/
+	effectiveMode(name) {
+		if (this.getRegistration(name).kind === "cron") return "cron";
+		return this.dispatcher.kind;
+	}
 	async runCron(name) {
 		const registration = this.getRegistration(name);
-		if (registration.type !== "cron") throw new AlephaError(`Job '${name}' is not cron-mode`);
-		if (this.stopping) return;
-		const executionId = crypto.randomUUID();
-		const promise = this.executeInline(registration, executionId, {
-			payload: void 0,
-			attempt: 1,
+		if (registration.kind !== "cron") throw new AlephaError(`Job '${name}' is not cron-mode`);
+		await this.runCronLocked(registration, {
 			triggeredBy: "system",
 			triggeredByName: "system (cron)"
 		});
-		this.inFlight.add(promise);
+	}
+	/**
+	* Cron-mode runner that respects the per-job distributed lock.
+	* Used by both the scheduled tick and manual `trigger()` calls so that an
+	* admin-triggered run on one instance can't race a scheduled run on another.
+	*
+	* **Two paths depending on `retry`:**
+	*
+	* - **No `retry`** — runs the handler inline. No DB row on success;
+	*   error row only on failure. The "next tick" is the implicit retry.
+	* - **`retry` declared** — enqueues a synthetic execution row and hands
+	*   it to the dispatcher. The handler then runs through the same path
+	*   as a queue/direct push (claim, retry-on-fail, sweep recovery). Use
+	*   this when a single failed tick must not block work for the whole
+	*   `cron` interval (e.g. once-daily jobs).
+	*/
+	async runCronLocked(registration, ctx) {
+		if (this.stopping) return;
+		const useLock = registration.options.lock !== false;
+		if (useLock) {
+			if (!await this.acquireCronLock(registration)) {
+				this.log.debug(`Cron '${registration.name}' skipped — another instance holds the lock`);
+				return;
+			}
+		}
 		try {
-			await promise;
+			if (registration.options.retry) {
+				await this.enqueueCronExecution(registration, ctx);
+				return;
+			}
+			const executionId = crypto.randomUUID();
+			const promise = this.executeInline(registration, executionId, {
+				payload: void 0,
+				attempt: 1,
+				triggeredBy: ctx.triggeredBy,
+				triggeredByName: ctx.triggeredByName
+			});
+			this.inFlight.add(promise);
+			try {
+				await promise;
+			} finally {
+				this.inFlight.delete(promise);
+			}
 		} finally {
-			this.inFlight.delete(promise);
+			if (useLock) await this.releaseCronLock(registration);
+		}
+	}
+	/**
+	* Materialize a cron tick into the outbox so it goes through the normal
+	* retry/sweep path. Used when the user opts into `retry` on a cron job —
+	* a transient failure no longer means "wait for the next cron tick", it
+	* means "the sweep will retry within `sweepCron`".
+	*/
+	async enqueueCronExecution(registration, ctx) {
+		const opts = registration.options;
+		const maxAttempts = (opts.retry?.retries ?? 0) + 1;
+		const execution = await this.executions.create({
+			jobName: registration.name,
+			payload: void 0,
+			status: "pending",
+			priority: PRIORITY_MAP[opts.priority ?? "normal"],
+			maxAttempts,
+			triggeredBy: ctx.triggeredBy,
+			triggeredByName: ctx.triggeredByName
+		});
+		await this.dispatch(registration.name, execution.id);
+	}
+	/**
+	* Acquire a per-job NX lock keyed by `cron-job:<name>` so that a single
+	* tick across all replicas runs exactly one execution. Auto-expires after
+	* `2 * timeout` (or 5 minutes if no per-job timeout) so a crashed worker
+	* cannot permanently block the cron from firing.
+	*
+	* **Caveat — same-process double-fire is not prevented.** The lock value
+	* is a per-process holder id, so two concurrent ticks on the same process
+	* (e.g. a scheduled tick overlapping an admin `trigger()` call) will both
+	* see "we own it". This is acceptable for the multi-replica use case the
+	* lock targets; a process that overlaps its own cron handler should set a
+	* smaller `timeout` or use idempotent handler logic. A future fix can add
+	* a per-process Set guard before reaching the LockProvider.
+	*/
+	async acquireCronLock(registration) {
+		const lockKey = this.cronLockKey(registration.name);
+		const ttlMs = registration.options.timeout ? this.dt.duration(registration.options.timeout).as("milliseconds") * 2 : 300 * 1e3;
+		const value = `${this.lockHolderId},${this.dt.nowISOString()}`;
+		try {
+			const [holderId] = (await this.lockProvider.set(lockKey, value, true, ttlMs)).split(",");
+			return holderId === this.lockHolderId;
+		} catch (e) {
+			this.log.warn(`Cron lock acquire failed for '${registration.name}'`, e);
+			return true;
+		}
+	}
+	/**
+	* Update only when the row is still in one of the expected statuses.
+	* Logs and returns silently when the guard rejects — this happens when a
+	* concurrent operation (most often `cancel()`) has already moved the row
+	* into a terminal state. We must not overwrite that.
+	*/
+	async guardedUpdate(executionId, expectedStatuses, patch, label) {
+		try {
+			await this.executions.updateOne({
+				id: { eq: executionId },
+				status: { inArray: expectedStatuses }
+			}, patch);
+		} catch (e) {
+			if (e instanceof DbEntityNotFoundError) {
+				this.log.debug(`${label}: row ${executionId} not in expected status — skipping write`);
+				return;
+			}
+			throw e;
+		}
+	}
+	async releaseCronLock(registration) {
+		try {
+			await this.lockProvider.del(this.cronLockKey(registration.name));
+		} catch (e) {
+			this.log.debug(`Cron lock release failed for '${registration.name}' (will expire by TTL)`, e);
 		}
 	}
+	cronLockKey(jobName) {
+		return `alepha.api.jobs.cron:${jobName}`;
+	}
+	/**
+	* Stable per-process id used as the lock value — survives multiple ticks.
+	* Lazy so that Cloudflare Workers (which forbid random in global scope)
+	* stay happy.
+	*/
+	lockHolderIdValue;
+	get lockHolderId() {
+		if (!this.lockHolderIdValue) this.lockHolderIdValue = crypto.randomUUID();
+		return this.lockHolderIdValue;
+	}
 	/**
 	* Execute a cron handler inline. Records a row only on error (or always,
 	* when `record: 'all'`). No DB writes on the happy path by default.
@@ -339,7 +634,7 @@ var JobProvider = class {
 	}
 	async push(name, payload, options) {
 		const registration = this.getRegistration(name);
-		if (registration.type !== "queue") throw new AlephaError(`Job '${name}' is not queue-mode (no schema declared). Use trigger() instead.`);
+		if (registration.kind !== "queue") throw new AlephaError(`Job '${name}' is not queue-mode (no schema declared). Use trigger() instead.`);
 		const opts = registration.options;
 		const validated = this.alepha.codec.validate(opts.schema, payload);
 		const priority = PRIORITY_MAP[options?.priority ?? opts.priority ?? "normal"];
@@ -368,7 +663,7 @@ var JobProvider = class {
 				triggeredBy: options.triggeredBy,
 				triggeredByName: options.triggeredByName
 			});
-			if (status === "pending") await this.dispatchToQueue(name, execution.id);
+			if (status === "pending") await this.dispatch(name, execution.id);
 			else if (status === "scheduled" && scheduledAt) this.scheduleOptimisticDispatch(name, execution.id, scheduledAt);
 			return execution.id;
 		}
@@ -382,7 +677,7 @@ var JobProvider = class {
 			triggeredBy: options?.triggeredBy,
 			triggeredByName: options?.triggeredByName
 		});
-		if (status === "pending") await this.dispatchToQueue(name, execution.id);
+		if (status === "pending") await this.dispatch(name, execution.id);
 		else if (status === "scheduled" && scheduledAt) this.scheduleOptimisticDispatch(name, execution.id, scheduledAt);
 		return execution.id;
 	}
@@ -401,7 +696,7 @@ var JobProvider = class {
 	async pushMany(name, items) {
 		if (items.length === 0) return [];
 		const registration = this.getRegistration(name);
-		if (registration.type !== "queue") throw new AlephaError(`Job '${name}' is not queue-mode (no schema declared).`);
+		if (registration.kind !== "queue") throw new AlephaError(`Job '${name}' is not queue-mode (no schema declared).`);
 		const opts = registration.options;
 		const maxAttempts = (opts.retry?.retries ?? 0) + 1;
 		const keyed = [];
@@ -440,11 +735,16 @@ var JobProvider = class {
 		}
 		if (bulk.length > 0) {
 			const created = await this.executions.createMany(bulk);
+			const toDispatch = [];
 			for (const exec of created) {
 				ids.push(exec.id);
-				if (exec.status === "pending" && !this.stopping) await this.dispatchToQueue(name, exec.id);
+				if (exec.status === "pending" && !this.stopping) toDispatch.push({
+					jobName: name,
+					executionId: exec.id
+				});
 				else if (exec.status === "scheduled" && exec.scheduledAt && !this.stopping) this.scheduleOptimisticDispatch(name, exec.id, exec.scheduledAt);
 			}
+			if (toDispatch.length > 0) await this.dispatchMany(toDispatch);
 		}
 		this.log.debug(`pushMany '${name}': ${ids.length} jobs created`, {
 			bulk: bulk.length,
@@ -452,18 +752,27 @@ var JobProvider = class {
 		});
 		return ids;
 	}
-	async dispatchToQueue(jobName, executionId) {
+	/**
+	* Hand a single execution to the active `JobDispatcher`. Whether that
+	* results in a queue send or in-process execution depends on which
+	* dispatcher is wired (see {@link JobDispatcher}).
+	*/
+	async dispatch(jobName, executionId) {
 		if (this.stopping) return;
-		if (!this.queueDispatch) throw new AlephaError(`Queue-mode job '${jobName}' cannot be pushed: AlephaApiJobsQueue is not loaded. Add '.with(AlephaApiJobsQueue)' to your app.`);
-		await this.queueDispatch(jobName, executionId);
+		await this.dispatcher.dispatch(jobName, executionId);
+	}
+	/**
+	* Batched variant. Used by `pushMany` so a backing queue can do a single
+	* batch network call (e.g. Cloudflare Queues `sendBatch`).
+	*/
+	async dispatchMany(items) {
+		if (this.stopping || items.length === 0) return;
+		await this.dispatcher.dispatchMany(items);
 	}
 	async trigger(name, context) {
 		const registration = this.getRegistration(name);
-		if (registration.type === "cron") {
-			const executionId = crypto.randomUUID();
-			await this.executeInline(registration, executionId, {
-				payload: void 0,
-				attempt: 1,
+		if (registration.kind === "cron") {
+			await this.runCronLocked(registration, {
 				triggeredBy: context?.triggeredBy,
 				triggeredByName: context?.triggeredByName
 			});
@@ -499,8 +808,8 @@ var JobProvider = class {
 			this.log.warn(`Unknown job '${jobName}' — skipping execution`, { executionId });
 			return;
 		}
-		if (registration.type !== "queue") {
-			this.log.warn(`Job '${jobName}' is not queue-mode — skipping`, { executionId });
+		if (registration.kind !== "queue" && !registration.options.retry) {
+			this.log.warn(`Job '${jobName}' has no outbox path (no schema and no retry) — skipping`, { executionId });
 			return;
 		}
 		const promise = this.processQueueExecution(registration, executionId);
@@ -515,12 +824,11 @@ var JobProvider = class {
 		const jobName = registration.name;
 		const opts = registration.options;
 		const record = opts.record ?? "error";
-		if (!await this.claim(executionId)) {
+		const execution = await this.claim(executionId);
+		if (!execution) {
 			this.log.debug(`Execution ${executionId} already claimed, skipping`);
 			return;
 		}
-		const execution = await this.executions.findById(executionId);
-		if (!execution) return;
 		const contextId = this.alepha.context.createContextId();
 		this.perExecutionLogs.set(contextId, []);
 		const abortController = new AbortController();
@@ -581,56 +889,58 @@ var JobProvider = class {
 			this.perExecutionLogs.delete(contextId);
 		}
 	}
+	/**
+	* Transition pending → running and return the post-update row.
+	* Two round-trips: read current attempt, then guarded UPDATE … RETURNING.
+	* Returns null when the row is gone or already claimed by another worker.
+	* The returned row replaces a separate post-claim findById, so the dispatch
+	* path is 2 queries instead of 3.
+	*/
 	async claim(executionId) {
-		const execution = await this.executions.findById(executionId);
-		if (!execution) return false;
+		const current = await this.executions.findById(executionId);
+		if (!current) return null;
 		try {
-			await this.executions.updateOne({
+			return await this.executions.updateOne({
 				id: { eq: executionId },
 				status: { eq: "pending" }
 			}, {
 				status: "running",
-				attempt: execution.attempt + 1,
+				attempt: current.attempt + 1,
 				startedAt: this.dt.nowISOString()
 			});
-			return true;
-		} catch {
-			return false;
+		} catch (e) {
+			if (e instanceof DbEntityNotFoundError) return null;
+			throw e;
 		}
 	}
 	async handleFailure(executionId, registration, currentAttempt, error, contextId) {
 		const jobName = registration.name;
 		const retry = registration.options.retry;
 		const maxAttempts = (retry?.retries ?? 0) + 1;
-		if (retry && currentAttempt + 1 < maxAttempts && (retry.when ? retry.when(error) : true)) {
-			const nextScheduledAt = this.computeBackoff(retry, currentAttempt + 1);
-			this.log.info(`Job '${jobName}' failed, scheduling retry ${currentAttempt + 1}/${maxAttempts}`, {
+		if (retry && currentAttempt < maxAttempts && (retry.when ? retry.when(error) : true)) {
+			const nextScheduledAt = this.dt.nowISOString();
+			this.log.info(`Job '${jobName}' failed, scheduling retry ${currentAttempt + 1}/${maxAttempts} (sweep will pick up)`, {
 				executionId,
-				error: error.message,
-				nextScheduledAt
+				error: error.message
 			});
-			await this.executions.updateById(executionId, {
+			await this.guardedUpdate(executionId, ["running"], {
 				status: "scheduled",
 				error: error.message,
 				scheduledAt: nextScheduledAt,
 				logs: this.snapshotLogs(contextId)
-			});
-			const delayMs = Math.max(0, new Date(nextScheduledAt).getTime() - this.dt.nowMillis());
-			this.dt.createTimeout(() => {
-				this.dispatchScheduled(jobName, executionId);
-			}, delayMs);
+			}, "retry-after-failure");
 		} else {
 			this.log.info(`Job '${jobName}' dead after ${currentAttempt} attempt(s)`, {
 				executionId,
 				error: error.message
 			});
-			await this.executions.updateById(executionId, {
+			await this.guardedUpdate(executionId, ["running"], {
 				status: "error",
 				error: error.message,
 				completedAt: this.dt.nowISOString(),
 				key: null,
 				logs: this.snapshotLogs(contextId)
-			});
+			}, "terminal-failure");
 		}
 		await this.alepha.events.emit("job:error", {
 			name: jobName,
@@ -638,16 +948,6 @@ var JobProvider = class {
 			executionId
 		}, { catch: true });
 	}
-	computeBackoff(retry, attempt) {
-		const now = this.dt.now();
-		if (!retry.backoff) return now.add(1, "second").toISOString();
-		if (Array.isArray(retry.backoff)) return now.add(this.dt.duration(retry.backoff)).toISOString();
-		const backoff = retry.backoff;
-		let delayMs = this.dt.duration(backoff.initial).as("milliseconds") * (backoff.factor ?? 2) ** (attempt - 1);
-		if (backoff.max) delayMs = Math.min(delayMs, this.dt.duration(backoff.max).as("milliseconds"));
-		if (backoff.jitter) delayMs = delayMs * (.75 + Math.random() * .5);
-		return now.add(delayMs, "millisecond").toISOString();
-	}
 	snapshotLogs(contextId) {
 		const entries = this.perExecutionLogs.get(contextId);
 		if (!entries || entries.length === 0) return void 0;
@@ -683,7 +983,7 @@ var JobProvider = class {
 			for (const exec of due) {
 				if (!this.jobs.has(exec.jobName)) continue;
 				await this.executions.updateById(exec.id, { status: "pending" });
-				await this.dispatchToQueueSafe(exec.jobName, exec.id);
+				await this.dispatchSafe(exec.jobName, exec.id);
 			}
 			const staleIso = now.subtract(this.config.staleThreshold, "millisecond").toISOString();
 			const staleWhere = this.executions.createQueryWhere();
@@ -698,7 +998,7 @@ var JobProvider = class {
 			});
 			for (const exec of stale) {
 				if (!this.jobs.has(exec.jobName)) continue;
-				await this.dispatchToQueueSafe(exec.jobName, exec.id);
+				await this.dispatchSafe(exec.jobName, exec.id);
 			}
 			const runningWhere = this.executions.createQueryWhere();
 			runningWhere.status = { eq: "running" };
@@ -721,9 +1021,9 @@ var JobProvider = class {
 			this.log.error("Sweep failed", { error: e });
 		}
 	}
-	async dispatchToQueueSafe(jobName, executionId) {
+	async dispatchSafe(jobName, executionId) {
 		try {
-			await this.dispatchToQueue(jobName, executionId);
+			await this.dispatch(jobName, executionId);
 		} catch (e) {
 			this.log.warn(`Sweep failed to dispatch ${jobName} (${executionId})`, e);
 		}
@@ -740,7 +1040,7 @@ var JobProvider = class {
 				id: { eq: executionId },
 				status: { eq: "scheduled" }
 			}, { status: "pending" });
-			await this.dispatchToQueueSafe(jobName, executionId);
+			await this.dispatchSafe(jobName, executionId);
 		} catch {}
 	}
 	async trimRingBuffers() {
@@ -777,10 +1077,21 @@ var JobProvider = class {
 	onStart = $hook({
 		on: "start",
 		handler: async () => {
-			if ([...this.jobs.values()].some((j) => j.type === "queue") && !this.queueDispatch) throw new AlephaError(`Queue-mode jobs are registered but no queue dispatcher is available. Add '.with(AlephaApiJobsQueue)' to your app.`);
+			const modes = {
+				cron: 0,
+				queue: 0,
+				direct: 0
+			};
+			const perJob = {};
+			for (const [name] of this.jobs) {
+				const m = this.effectiveMode(name);
+				modes[m]++;
+				perJob[name] = m;
+			}
 			this.log.info(`Job system OK`, {
-				dispatch: this.queueDispatch ? "queue" : "inline-only",
-				jobs: this.jobs.size
+				modes,
+				jobs: this.jobs.size,
+				perJob
 			});
 			this.alepha.events.on("log", ({ entry }) => {
 				const ctx = entry.context;
@@ -790,7 +1101,7 @@ var JobProvider = class {
 				entries.push(entry);
 			});
 			if (!this.alepha.isServerless()) await this.sweep();
-			this.cronProvider.createCronJob("api:jobs:sweep", SWEEP_CRON, async () => {
+			this.cronProvider.createCronJob("api:jobs:sweep", this.config.sweepCron, async () => {
 				await this.sweep();
 			}, true);
 		}
@@ -889,6 +1200,19 @@ var JobService = class {
 		};
 	}
 	/**
+	* Convert the int-priority storage column into the public enum string.
+	* The cast through `unknown` skips TypeScript's structural check between
+	* the entity-level row (`priority: number`) and the resource schema
+	* (`priority: enum`); the runtime values are correct.
+	*/
+	toResource(row) {
+		return {
+			...row,
+			priority: PRIORITY_REVERSE[row.priority] ?? "normal",
+			can: this.computeCan(row.status)
+		};
+	}
+	/**
 	* List every registered job with recent ok/error counts and lastRun.
 	* One aggregate query covers all jobs.
 	*/
@@ -936,14 +1260,11 @@ var JobService = class {
 			result.push({
 				name,
 				description: opts.description,
-				type: reg.type,
+				type: this.jobProvider.effectiveMode(name),
 				cron: opts.cron,
 				priority: opts.priority ?? "normal",
 				timeout: opts.timeout ? String(opts.timeout) : void 0,
-				retry: opts.retry ? {
-					retries: opts.retry.retries,
-					hasBackoff: Boolean(opts.retry.backoff)
-				} : void 0,
+				retry: opts.retry ? { retries: opts.retry.retries } : void 0,
 				recent: counts
 			});
 		}
@@ -964,10 +1285,7 @@ var JobService = class {
 				direction: "desc"
 			},
 			limit: query.limit ?? 20
-		})).map((row) => ({
-			...row,
-			can: this.computeCan(row.status)
-		}));
+		})).map((row) => this.toResource(row));
 	}
 	/**
 	* Full execution detail (includes captured logs).
@@ -975,10 +1293,7 @@ var JobService = class {
 	async getExecution(id) {
 		const execution = await this.executions.findById(id);
 		if (!execution) throw new NotFoundError(`Execution not found: ${id}`);
-		return {
-			...execution,
-			can: this.computeCan(execution.status)
-		};
+		return this.toResource(execution);
 	}
 	/**
 	* Manual trigger (cron jobs) or push-with-payload (queue jobs).
@@ -1103,69 +1418,69 @@ var AdminJobController = class {
 	});
 };
 //#endregion
-//#region ../../src/api/jobs/providers/JobQueueProvider.ts
-/**
-* Plumbs outbox-style dispatch through `AlephaQueue`.
-*
-* Registered only when the app imports `AlephaApiJobsQueue`. Sets
-* `JobProvider.queueDispatch` eagerly at instantiation so queue-mode jobs
-* can dispatch regardless of start-hook ordering.
-*/
-var JobQueueProvider = class {
-	jobProvider = $inject(JobProvider);
-	queue = $queue({
-		name: "api:jobs:dispatch",
-		schema: t.object({
-			jobName: t.text(),
-			executionId: t.text()
-		}),
-		handler: async (msg) => {
-			await this.jobProvider.processExecution(msg.payload.jobName, msg.payload.executionId);
-		}
-	});
-	constructor() {
-		this.wireDispatcher();
-	}
-	wireDispatcher() {
-		this.jobProvider.queueDispatch = (jobName, executionId) => this.push(jobName, executionId);
-	}
-	async push(jobName, executionId) {
-		await this.queue.push({
-			jobName,
-			executionId
-		});
-	}
-};
-//#endregion
 //#region ../../src/api/jobs/index.ts
 /**
 * Job execution framework — cron and durable queue work with a single primitive.
 *
-* A `$job` is either **cron-only** (declares `cron`) or **queue-only** (declares `schema`).
-* Cron jobs run inline on their schedule and only record errors by default.
-* Queue jobs use the outbox pattern: push commits to DB first, then notifies via queue.
+* A `$job` is either **cron-only** (declares `cron`) or **payload-only** (declares `schema`).
+*
+* **Three runtime modes:**
+*
+* - **cron** — fires on a schedule. Cron-mode jobs are protected by a
+*   distributed lock by default (`lock: true`), so multi-replica Docker
+*   deployments only run the handler once per tick. Override with
+*   `lock: false` if you genuinely want every replica to fire.
+* - **queue** — push-driven, dispatched through the queue infrastructure
+*   (`AlephaQueue`, e.g. Cloudflare Queues, Redis). Real-time delivery,
+*   ideal for high-volume systems. Requires `AlephaApiJobsQueue`.
+* - **direct** — push-driven, processed in-process right after the caller
+*   awaits the push. The DB outbox row is the durability guarantee — if
+*   the process dies, the reconciliation sweep re-dispatches. Default
+*   when `AlephaApiJobsQueue` is *not* loaded. Best for cheap deployments
+*   (Cloudflare Workers, single-instance Node) where standing up a queue
+*   is overkill.
+*
+* **Retries** are sweep-driven across all modes (no exponential backoff).
+* Granularity is bounded by `sweepCron` (default 5 min). The first retry
+* may land anywhere from a few seconds to ~5 min later depending on when
+* the next sweep tick fires. Cron jobs that declare `retry` go through
+* the same sweep path — a transient failure no longer means waiting for
+* the next cron tick (useful for once-daily jobs).
+*
+* **Runtime support for cron triggers**
 *
-* **This module provides cron support only.** To enable queue-mode jobs, also
-* import {@link AlephaApiJobsQueue} — it brings in the queue layer and infrastructure
-* binding (e.g. Cloudflare Queues). Cron-only deployments (Vercel, CF-without-Queues)
-* do not need `AlephaApiJobsQueue`.
+* - **Long-running Node / Docker** — `CronProvider` runs an in-process
+*   timer loop. Multi-replica deployments serialize ticks via the cron
+*   lock (see `$job.lock`).
+* - **Cloudflare Workers** — the build emits cron expressions into
+*   `wrangler.jsonc`; Cloudflare invokes the worker on schedule and the
+*   `cloudflare:scheduled` hook routes the event to the matching jobs.
+* - **Vercel** — the build emits cron entries into
+*   `.vercel/output/config.json` mapped to `/_alepha/cron/:name`; the
+*   serverless handler emits `serverless:cron` and `CronProvider` runs
+*   the matching job. Set `CRON_SECRET` to require authenticated calls.
 *
 * @module alepha.api.jobs
 */
 const AlephaApiJobs = $module({
 	name: "alepha.api.jobs",
+	primitives: [$job],
 	imports: [AlephaScheduler, AlephaLock],
 	services: [
 		JobProvider,
 		JobService,
-		AdminJobController
+		AdminJobController,
+		DirectJobDispatcher
 	]
 });
 /**
 * Queue support for `$job`. Import alongside {@link AlephaApiJobs} when your
-* app declares queue-mode jobs (any `$job` with a `schema`).
+* app declares queue-mode jobs (any `$job` with a `schema`) and you want a
+* real queue (e.g. Cloudflare Queues, Redis) instead of in-process direct
+* execution.
 *
-* Adds `JobQueueProvider` which plumbs the outbox dispatch through `AlephaQueue`.
+* Adds `JobQueueProvider` to the container. `JobProvider` detects its
+* presence at start-up and routes dispatches through it.
 *
 * @module alepha.api.jobs.queue
 */
@@ -1175,6 +1490,6 @@ const AlephaApiJobsQueue = $module({
 	services: [JobQueueProvider]
 });
 //#endregion
-export { $job, AdminJobController, AlephaApiJobs, AlephaApiJobsQueue, JobPrimitive, JobProvider, JobQueueProvider, JobService, PRIORITY_MAP, PRIORITY_REVERSE, jobConfig, jobExecutionEntity, jobExecutionQuerySchema, jobExecutionResourceSchema, jobRegistrationSchema, triggerJobSchema };
+export { $job, AdminJobController, AlephaApiJobs, AlephaApiJobsQueue, DirectJobDispatcher, JobDispatcher, JobPrimitive, JobProvider, JobQueueProvider, JobService, PRIORITY_MAP, PRIORITY_REVERSE, jobConfig, jobExecutionEntity, jobExecutionQuerySchema, jobExecutionResourceSchema, jobRegistrationSchema, triggerJobSchema };
 
 //# sourceMappingURL=index.js.map