alepha 0.20.1 → 0.20.2

package/dist/api/jobs/index.js

@@ -1,47 +1,47 @@
 import { $atom, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, PipelinePrimitive, createPrimitive, t } from "alepha";
-import { AlephaLock, LockProvider } from "alepha/lock";
+import { AlephaLock } 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, DatabaseProvider, db, pageQuerySchema, sql } from "alepha/orm";
+import { $entity, $repository, db, sql } from "alepha/orm";
 import { DateTimeProvider } from "alepha/datetime";
-//#region ../../src/api/jobs/schemas/jobActivitySchema.ts
-const jobActivityPointSchema = t.object({
-	date: t.text(),
-	completed: t.integer(),
-	failed: t.integer()
-});
-const jobActivityQuerySchema = t.object({ days: t.optional(t.integer({
-	minimum: 1,
-	maximum: 90
-})) });
-//#endregion
-//#region ../../src/api/jobs/schemas/jobCronInfoSchema.ts
-const jobCronInfoSchema = t.object({
-	name: t.text(),
-	cron: t.text(),
-	lock: t.boolean(),
-	priority: t.enum([
-		"critical",
-		"high",
-		"normal",
-		"low"
-	]),
-	concurrency: t.integer(),
-	hasSchema: t.boolean(),
-	paused: t.boolean(),
-	lastExecution: t.optional(t.object({
-		id: t.uuid(),
-		status: t.text(),
-		startedAt: t.optional(t.datetime()),
-		completedAt: t.optional(t.datetime()),
-		error: t.optional(t.text())
+//#region ../../src/api/jobs/schemas/jobExecutionQuerySchema.ts
+const jobExecutionQuerySchema = t.object({
+	status: t.optional(t.enum([
+		"pending",
+		"running",
+		"scheduled",
+		"ok",
+		"error",
+		"cancelled"
+	])),
+	limit: t.optional(t.integer({
+		minimum: 1,
+		maximum: 200,
+		default: 20
 	}))
 });
 //#endregion
 //#region ../../src/api/jobs/entities/jobExecutionEntity.ts
+/**
+* Job execution record.
+*
+* Stores durable state for queue-mode jobs (outbox pattern) and error records
+* for cron-mode jobs. Successful executions are trimmed by the sweep to keep
+* the last N rows per job (configurable via `jobConfig.keepLastSuccess`).
+*
+* Status transitions:
+* - queue push            → pending
+* - worker claim          → running
+* - success               → ok
+* - terminal failure      → error
+* - retry                 → scheduled (with scheduledAt = now + backoff)
+* - delay                 → scheduled (with scheduledAt = now + delay)
+* - sweep picks due ones  → pending
+* - cancel                → cancelled
+*/
 const jobExecutionEntity = $entity({
 	name: "job_executions",
 	schema: t.object({
@@ -50,14 +50,12 @@ const jobExecutionEntity = $entity({
 		updatedAt: db.updatedAt(),
 		jobName: t.text(),
 		key: t.optional(t.nullable(t.text())),
-		payload: t.optional(t.record(t.text(), t.any())),
 		status: db.default(t.enum([
 			"pending",
-			"scheduled",
-			"retrying",
 			"running",
-			"completed",
-			"dead",
+			"scheduled",
+			"ok",
+			"error",
 			"cancelled"
 		]), "pending"),
 		priority: db.default(t.integer({
@@ -66,12 +64,12 @@ const jobExecutionEntity = $entity({
 		}), 2),
 		attempt: db.default(t.integer(), 0),
 		maxAttempts: db.default(t.integer(), 1),
+		payload: t.optional(t.record(t.text(), t.any())),
 		scheduledAt: t.optional(t.datetime()),
 		startedAt: t.optional(t.datetime()),
 		completedAt: t.optional(t.datetime()),
-		result: t.optional(t.record(t.text(), t.any())),
 		error: t.optional(t.text()),
-		workerId: t.optional(t.text()),
+		logs: t.optional(t.array(logEntrySchema)),
 		triggeredBy: t.optional(t.text()),
 		triggeredByName: t.optional(t.text()),
 		cancelledBy: t.optional(t.text()),
@@ -81,15 +79,9 @@ const jobExecutionEntity = $entity({
 		{ columns: [
 			"jobName",
 			"status",
-			"priority",
 			"scheduledAt"
 		] },
-		{ columns: [
-			"jobName",
-			"status",
-			"startedAt"
-		] },
-		{ columns: ["jobName", "completedAt"] },
+		{ columns: ["jobName", "startedAt"] },
 		{
 			columns: ["jobName", "key"],
 			unique: true
@@ -98,140 +90,60 @@ const jobExecutionEntity = $entity({
 });
 //#endregion
 //#region ../../src/api/jobs/schemas/jobExecutionResourceSchema.ts
-const jobExecutionCanSchema = t.object({
+const jobExecutionResourceSchema = t.extend(jobExecutionEntity.schema, { can: t.object({
 	retry: t.boolean(),
 	cancel: t.boolean()
-});
-const jobExecutionResourceSchema = t.extend(jobExecutionEntity.schema, { can: jobExecutionCanSchema }, {
+}) }, {
 	title: "JobExecutionResource",
-	description: "A job execution resource."
-});
-//#endregion
-//#region ../../src/api/jobs/schemas/jobExecutionDetailResourceSchema.ts
-const jobExecutionDetailResourceSchema = t.extend(jobExecutionEntity.schema, {
-	can: jobExecutionCanSchema,
-	logs: t.optional(t.array(logEntrySchema))
-}, {
-	title: "JobExecutionDetailResource",
-	description: "A job execution resource with logs."
-});
-//#endregion
-//#region ../../src/api/jobs/schemas/jobExecutionQuerySchema.ts
-const jobExecutionQuerySchema = t.extend(pageQuerySchema, {
-	job: t.optional(t.text({ description: "Filter by job name" })),
-	status: t.optional(t.enum([
-		"pending",
-		"scheduled",
-		"retrying",
-		"running",
-		"completed",
-		"dead",
-		"cancelled"
-	])),
-	priority: t.optional(t.enum([
-		"critical",
-		"high",
-		"normal",
-		"low"
-	])),
-	from: t.optional(t.datetime({ description: "From date (ISO)" })),
-	to: t.optional(t.datetime({ description: "To date (ISO)" }))
-});
-//#endregion
-//#region ../../src/api/jobs/schemas/jobFailureSchema.ts
-const jobFailureSchema = t.object({
-	jobName: t.text(),
-	failures: t.integer(),
-	lastError: t.optional(t.text())
-});
-//#endregion
-//#region ../../src/api/jobs/schemas/jobQueueDepthSchema.ts
-const jobQueueDepthSchema = t.object({
-	jobName: t.text(),
-	pending: t.integer(),
-	running: t.integer(),
-	scheduled: t.integer(),
-	retrying: t.integer(),
-	dead: t.integer(),
-	concurrency: t.integer(),
-	paused: t.boolean()
+	description: "A job execution row with derived actions."
 });
 //#endregion
 //#region ../../src/api/jobs/schemas/jobRegistrationSchema.ts
 const jobRegistrationSchema = t.object({
 	name: t.text(),
-	type: t.enum([
-		"cron",
-		"push",
-		"both"
-	]),
+	description: t.optional(t.text()),
+	type: t.enum(["cron", "queue"]),
 	priority: t.enum([
 		"critical",
 		"high",
 		"normal",
 		"low"
 	]),
-	concurrency: t.integer(),
-	hasSchema: t.boolean(),
 	cron: t.optional(t.text()),
 	timeout: t.optional(t.text()),
 	retry: t.optional(t.object({
 		retries: t.integer(),
 		hasBackoff: t.boolean()
 	})),
-	paused: t.boolean()
-});
-//#endregion
-//#region ../../src/api/jobs/schemas/jobStatsSchema.ts
-const jobStatsSchema = t.object({
-	registered: t.integer(),
-	running: t.integer(),
-	pending: t.integer(),
-	scheduled: t.integer(),
-	retrying: t.integer(),
-	dead: t.integer(),
-	completed: t.integer(),
-	failed: t.integer()
+	recent: t.object({
+		ok: t.integer(),
+		error: t.integer(),
+		lastRun: t.optional(t.datetime())
+	})
 });
 //#endregion
 //#region ../../src/api/jobs/schemas/triggerJobSchema.ts
-const triggerJobSchema = t.object({
-	name: t.text(),
-	payload: t.optional(t.record(t.text(), t.any()))
-});
-//#endregion
-//#region ../../src/api/jobs/entities/jobExecutionLogEntity.ts
-const jobExecutionLogEntity = $entity({
-	name: "job_execution_logs",
-	schema: t.object({
-		id: db.primaryKey(t.uuid()),
-		logs: t.array(logEntrySchema)
-	})
-});
+const triggerJobSchema = t.object({ payload: t.optional(t.record(t.text(), t.any())) });
 //#endregion
 //#region ../../src/api/jobs/schemas/jobConfigAtom.ts
 const jobConfig = $atom({
 	name: "alepha.jobs",
-	description: "Configuration for the $job v2 primitive.",
+	description: "Configuration for the $job primitive.",
 	schema: t.object({
-		recovery: t.object({
-			interval: t.integer({ description: "Sweep interval (ms)." }),
-			staleThreshold: t.integer({ description: "Pending age (ms) before re-dispatch." }),
-			runTimeout: t.integer({ description: "Running age (ms) before assumed crash. Used as fallback when no per-job timeout is set." })
-		}),
-		delayed: t.object({ interval: t.integer({ description: "Sweep interval (ms)." }) }),
-		logRetentionDays: t.integer({ description: "Days to keep completed/dead executions." }),
+		sweepInterval: t.integer({ description: "Sweep cron interval in milliseconds." }),
+		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." }),
+		keepLastError: t.integer({ description: "Max error rows to keep per job." }),
 		logMaxEntries: t.integer({ description: "Max log entries captured per execution." }),
 		drainTimeout: t.integer({ description: "Max time (ms) to wait for in-flight jobs during shutdown." })
 	}),
 	default: {
-		recovery: {
-			interval: 3e5,
-			staleThreshold: 3e5,
-			runTimeout: 18e5
-		},
-		delayed: { interval: 3e5 },
-		logRetentionDays: 30,
+		sweepInterval: 3e5,
+		staleThreshold: 3e5,
+		runTimeout: 18e5,
+		keepLastSuccess: 10,
+		keepLastError: 10,
 		logMaxEntries: 100,
 		drainTimeout: 3e4
 	}
@@ -250,59 +162,185 @@ const PRIORITY_REVERSE = {
 	2: "normal",
 	3: "low"
 };
-var JobProvider = class JobProvider {
+const SWEEP_CRON = "*/5 * * * *";
+/**
+* Coordinates cron (scheduler) and queue (push) jobs with a durable outbox
+* table and a single reconciliation sweep.
+*
+* Queue-mode flow:
+*   push()  → INSERT row (pending) + queue.send({ executionId })
+*   worker  → SELECT row → UPDATE running → handler → DELETE (ok) / UPDATE (error)
+*
+* Cron-mode flow:
+*   scheduler tick → handler runs inline → INSERT row only on error
+*
+* Sweep responsibilities (every `sweepInterval`):
+*   - 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
+*   - 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);
 	log = $logger();
 	executions = $repository(jobExecutionEntity);
-	executionLogs = $repository(jobExecutionLogEntity);
 	jobs = /* @__PURE__ */ new Map();
-	pausedJobs = /* @__PURE__ */ new Set();
 	inFlight = /* @__PURE__ */ new Set();
+	abortControllers = /* @__PURE__ */ new Map();
+	perExecutionLogs = /* @__PURE__ */ new Map();
+	stopping = false;
 	/**
-	* When set, job executions are dispatched through a queue (e.g. `JobQueueProvider`).
-	* When null, jobs execute inline (fire-and-forget). Useful for serverless environments.
+	* Set by `JobQueueProvider` when `AlephaApiJobsQueue` is loaded.
+	* When null, queue-mode jobs cannot be pushed.
 	*/
 	queueDispatch = null;
-	logs = /* @__PURE__ */ new Map();
-	abortControllers = /* @__PURE__ */ new Map();
-	static SWEEP_CRON = "*/5 * * * *";
-	stopping = false;
-	workerId = "";
 	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";
 		this.jobs.set(name, {
 			name,
-			options
+			options,
+			type
 		});
-		this.log.debug(`Registered job '${name}'`, {
+		this.log.debug(`Registered ${type} job '${name}'`, {
 			cron: options.cron,
 			priority: options.priority ?? "normal",
 			retries: options.retry?.retries ?? 0
 		});
 		if (options.cron) this.cronProvider.createCronJob(name, options.cron, async () => {
 			try {
-				await this.trigger(name, {
-					triggeredBy: "system",
-					triggeredByName: "system (cron)"
-				});
+				await this.runCron(name);
 			} catch (error) {
-				this.log.error(`Cron trigger failed for job '${name}'`, error);
+				this.log.error(`Cron tick failed for job '${name}'`, error);
 			}
 		});
 	}
-	/**
-	* Get all registered job definitions.
-	*/
 	getRegisteredJobs() {
 		return this.jobs;
 	}
+	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,
+			triggeredBy: "system",
+			triggeredByName: "system (cron)"
+		});
+		this.inFlight.add(promise);
+		try {
+			await promise;
+		} finally {
+			this.inFlight.delete(promise);
+		}
+	}
+	/**
+	* 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.
+	*/
+	async executeInline(registration, executionId, ctx) {
+		const opts = registration.options;
+		const name = registration.name;
+		const record = opts.record ?? "error";
+		const contextId = this.alepha.context.createContextId();
+		this.perExecutionLogs.set(contextId, []);
+		const abortController = new AbortController();
+		this.abortControllers.set(executionId, abortController);
+		let timeoutId;
+		if (opts.timeout) {
+			const ms = this.dt.duration(opts.timeout).as("milliseconds");
+			timeoutId = setTimeout(() => abortController.abort(), ms);
+		}
+		const startedAt = this.dt.now();
+		try {
+			await this.alepha.context.run(async () => {
+				await this.alepha.events.emit("job:begin", {
+					name,
+					now: startedAt,
+					executionId
+				});
+				try {
+					await opts.handler({
+						payload: ctx.payload,
+						attempt: ctx.attempt,
+						now: startedAt,
+						signal: abortController.signal,
+						executionId
+					});
+					if (record === "all") await this.writeTerminalRow(executionId, name, "ok", {
+						payload: ctx.payload,
+						attempt: ctx.attempt,
+						startedAt,
+						error: void 0,
+						context: contextId,
+						triggeredBy: ctx.triggeredBy,
+						triggeredByName: ctx.triggeredByName
+					});
+					await this.alepha.events.emit("job:success", {
+						name,
+						executionId
+					}, { catch: true });
+				} catch (error) {
+					const err = error instanceof Error ? error : new Error(String(error));
+					if (record !== "none") await this.writeTerminalRow(executionId, name, "error", {
+						payload: ctx.payload,
+						attempt: ctx.attempt,
+						startedAt,
+						error: err,
+						context: contextId,
+						triggeredBy: ctx.triggeredBy,
+						triggeredByName: ctx.triggeredByName
+					});
+					await this.alepha.events.emit("job:error", {
+						name,
+						error: err,
+						executionId
+					}, { catch: true });
+				} finally {
+					if (timeoutId) clearTimeout(timeoutId);
+					this.abortControllers.delete(executionId);
+					await this.alepha.events.emit("job:end", {
+						name,
+						executionId
+					}, { catch: true });
+				}
+			}, { context: contextId });
+		} finally {
+			this.perExecutionLogs.delete(contextId);
+		}
+	}
+	async writeTerminalRow(executionId, jobName, status, fields) {
+		try {
+			const logs = status === "error" ? this.snapshotLogs(fields.context) : void 0;
+			await this.executions.create({
+				id: executionId,
+				jobName,
+				status,
+				payload: fields.payload,
+				attempt: fields.attempt,
+				maxAttempts: fields.attempt,
+				startedAt: fields.startedAt.toISOString(),
+				completedAt: this.dt.nowISOString(),
+				error: fields.error?.message,
+				logs,
+				triggeredBy: fields.triggeredBy,
+				triggeredByName: fields.triggeredByName
+			});
+		} catch (e) {
+			this.log.warn(`Failed to write terminal row for ${executionId}`, e);
+		}
+	}
 	async push(name, payload, options) {
-		const opts = this.getRegistration(name).options;
-		if (!opts.schema) throw new AlephaError(`Cannot push to job '${name}': no schema defined. Use trigger() for cron-only jobs.`);
+		const registration = this.getRegistration(name);
+		if (registration.type !== "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"];
 		const maxAttempts = (opts.retry?.retries ?? 0) + 1;
@@ -311,8 +349,15 @@ var JobProvider = class JobProvider {
 		if (options?.scheduledAt) scheduledAt = options.scheduledAt.toISOString();
 		else if (options?.delay) scheduledAt = this.dt.now().add(this.dt.duration(options.delay)).toISOString();
 		if (options?.key) {
-			const now = this.dt.nowISOString();
-			const execution = await this.executions.upsert({
+			const existing = await this.executions.findMany({
+				where: {
+					jobName: { eq: name },
+					key: { eq: options.key }
+				},
+				limit: 1
+			});
+			if (existing.length > 0) return existing[0].id;
+			const execution = await this.executions.create({
 				jobName: name,
 				key: options.key,
 				payload: validated,
@@ -320,14 +365,11 @@ var JobProvider = class JobProvider {
 				priority,
 				maxAttempts,
 				scheduledAt,
-				createdAt: now,
-				updatedAt: now
-			}, {
-				target: ["jobName", "key"],
-				set: {},
-				now
+				triggeredBy: options.triggeredBy,
+				triggeredByName: options.triggeredByName
 			});
-			if (execution.createdAt === execution.updatedAt && status === "pending" && !this.stopping) await this.scheduleProcessing(name, execution.id);
+			if (status === "pending") await this.dispatchToQueue(name, execution.id);
+			else if (status === "scheduled" && scheduledAt) this.scheduleOptimisticDispatch(name, execution.id, scheduledAt);
 			return execution.id;
 		}
 		const execution = await this.executions.create({
@@ -336,43 +378,55 @@ var JobProvider = class JobProvider {
 			status,
 			priority,
 			maxAttempts,
-			scheduledAt
-		});
-		this.log.debug(`Pushed job '${name}'`, {
-			executionId: execution.id,
-			status,
-			priority: PRIORITY_REVERSE[priority]
+			scheduledAt,
+			triggeredBy: options?.triggeredBy,
+			triggeredByName: options?.triggeredByName
 		});
-		if (status === "pending" && !this.stopping) await this.scheduleProcessing(name, execution.id);
+		if (status === "pending") await this.dispatchToQueue(name, execution.id);
+		else if (status === "scheduled" && scheduledAt) this.scheduleOptimisticDispatch(name, execution.id, scheduledAt);
 		return execution.id;
 	}
+	/**
+	* Fire a local setTimeout so delayed/retrying rows dispatch as close to
+	* `scheduledAt` as possible, rather than waiting for the next sweep tick.
+	* No-op on stateless runtimes where timers won't survive (the sweep
+	* handles those).
+	*/
+	scheduleOptimisticDispatch(jobName, executionId, scheduledAt) {
+		const delayMs = Math.max(0, new Date(scheduledAt).getTime() - this.dt.nowMillis());
+		this.dt.createTimeout(() => {
+			this.dispatchScheduled(jobName, executionId);
+		}, delayMs);
+	}
 	async pushMany(name, items) {
 		if (items.length === 0) return [];
-		const opts = this.getRegistration(name).options;
-		if (!opts.schema) throw new AlephaError(`Cannot push to job '${name}': no schema defined. Use trigger() for cron-only jobs.`);
+		const registration = this.getRegistration(name);
+		if (registration.type !== "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 = [];
-		const bulkRows = [];
+		const bulk = [];
 		for (const item of items) {
 			const validated = this.alepha.codec.validate(opts.schema, item.payload);
-			if (item.key) keyed.push({
-				...item,
-				payload: validated
-			});
-			else {
-				const status = item.delay || item.scheduledAt ? "scheduled" : "pending";
-				let scheduledAt;
-				if (item.scheduledAt) scheduledAt = item.scheduledAt.toISOString();
-				else if (item.delay) scheduledAt = this.dt.now().add(this.dt.duration(item.delay)).toISOString();
-				bulkRows.push({
-					jobName: name,
-					payload: validated,
-					status,
-					priority: PRIORITY_MAP[item.priority ?? opts.priority ?? "normal"],
-					maxAttempts,
-					scheduledAt
+			if (item.key) {
+				keyed.push({
+					...item,
+					payload: validated
 				});
+				continue;
 			}
+			const status = item.delay || item.scheduledAt ? "scheduled" : "pending";
+			let scheduledAt;
+			if (item.scheduledAt) scheduledAt = item.scheduledAt.toISOString();
+			else if (item.delay) scheduledAt = this.dt.now().add(this.dt.duration(item.delay)).toISOString();
+			bulk.push({
+				jobName: name,
+				payload: validated,
+				status,
+				priority: PRIORITY_MAP[item.priority ?? opts.priority ?? "normal"],
+				maxAttempts,
+				scheduledAt
+			});
 		}
 		const ids = [];
 		for (const item of keyed) {
@@ -384,49 +438,47 @@ var JobProvider = class JobProvider {
 			});
 			ids.push(id);
 		}
-		if (bulkRows.length > 0) {
-			const created = await this.executions.createMany(bulkRows);
+		if (bulk.length > 0) {
+			const created = await this.executions.createMany(bulk);
 			for (const exec of created) {
 				ids.push(exec.id);
-				if (exec.status === "pending" && !this.stopping) await this.scheduleProcessing(name, exec.id);
+				if (exec.status === "pending" && !this.stopping) await this.dispatchToQueue(name, exec.id);
+				else if (exec.status === "scheduled" && exec.scheduledAt && !this.stopping) this.scheduleOptimisticDispatch(name, exec.id, exec.scheduledAt);
 			}
 		}
 		this.log.debug(`pushMany '${name}': ${ids.length} jobs created`, {
-			bulk: bulkRows.length,
+			bulk: bulk.length,
 			keyed: keyed.length
 		});
 		return ids;
 	}
+	async dispatchToQueue(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);
+	}
 	async trigger(name, context) {
-		const opts = this.getRegistration(name).options;
-		if (context?.payload && opts.schema) {
-			const id = await this.push(name, context.payload, {});
-			await this.executions.updateById(id, {
+		const registration = this.getRegistration(name);
+		if (registration.type === "cron") {
+			const executionId = crypto.randomUUID();
+			await this.executeInline(registration, executionId, {
+				payload: void 0,
+				attempt: 1,
 				triggeredBy: context?.triggeredBy,
 				triggeredByName: context?.triggeredByName
 			});
 			return;
 		}
-		const maxAttempts = (opts.retry?.retries ?? 0) + 1;
-		const priority = PRIORITY_MAP[opts.priority ?? "normal"];
-		const execution = await this.executions.create({
-			jobName: name,
-			status: "pending",
-			priority,
-			maxAttempts,
-			triggeredBy: context?.triggeredBy,
-			triggeredByName: context?.triggeredByName
-		});
-		this.log.debug(`Triggered job '${name}'`, {
-			executionId: execution.id,
-			triggeredBy: context?.triggeredByName ?? context?.triggeredBy
+		if (!context?.payload) throw new AlephaError(`Queue-mode job '${name}' requires a payload for manual trigger.`);
+		await this.push(name, context.payload, {
+			triggeredBy: context.triggeredBy,
+			triggeredByName: context.triggeredByName
 		});
-		if (!this.stopping) await this.scheduleProcessing(name, execution.id);
 	}
 	async cancel(executionId, context) {
 		const execution = await this.executions.findById(executionId);
 		if (!execution) throw new AlephaError(`Execution not found: ${executionId}`);
-		if (execution.status === "completed" || execution.status === "dead" || execution.status === "cancelled") throw new AlephaError(`Cannot cancel execution in '${execution.status}' status`);
+		if (execution.status === "ok" || execution.status === "error" || execution.status === "cancelled") throw new AlephaError(`Cannot cancel execution in '${execution.status}' status`);
 		const controller = this.abortControllers.get(executionId);
 		if (controller) controller.abort();
 		await this.executions.updateById(executionId, {
@@ -441,30 +493,17 @@ var JobProvider = class JobProvider {
 			cancelledBy: context?.cancelledByName ?? context?.cancelledBy
 		});
 	}
-	async scheduleProcessing(jobName, executionId) {
-		if (this.pausedJobs.has(jobName)) {
-			this.log.debug(`Job '${jobName}' is paused, deferring`, { executionId });
+	async processExecution(jobName, executionId) {
+		const registration = this.jobs.get(jobName);
+		if (!registration) {
+			this.log.warn(`Unknown job '${jobName}' — skipping execution`, { executionId });
 			return;
 		}
-		const maxConcurrency = this.getRegistration(jobName).options.concurrency ?? 1;
-		const runningCount = await this.executions.count({
-			jobName: { eq: jobName },
-			status: { eq: "running" }
-		});
-		if (runningCount >= maxConcurrency) {
-			this.log.debug(`Job '${jobName}' at concurrency limit (${runningCount}/${maxConcurrency}), deferring`, { executionId });
+		if (registration.type !== "queue") {
+			this.log.warn(`Job '${jobName}' is not queue-mode — skipping`, { executionId });
 			return;
 		}
-		if (this.queueDispatch) {
-			this.log.debug(`Dispatching job '${jobName}' via queue`, { executionId });
-			await this.queueDispatch(jobName, executionId);
-		} else {
-			this.log.debug(`Executing job '${jobName}' inline`, { executionId });
-			await this.processExecution(jobName, executionId);
-		}
-	}
-	async processExecution(jobName, executionId) {
-		const promise = this.processExecutionInner(jobName, executionId);
+		const promise = this.processQueueExecution(registration, executionId);
 		this.inFlight.add(promise);
 		try {
 			await promise;
@@ -472,71 +511,63 @@ var JobProvider = class JobProvider {
 			this.inFlight.delete(promise);
 		}
 	}
-	async processExecutionInner(jobName, executionId) {
-		const registration = this.getRegistration(jobName);
+	async processQueueExecution(registration, executionId) {
+		const jobName = registration.name;
+		const opts = registration.options;
+		const record = opts.record ?? "error";
 		if (!await this.claim(executionId)) {
 			this.log.debug(`Execution ${executionId} already claimed, skipping`);
 			return;
 		}
-		const context = this.alepha.context.createContextId();
-		this.logs.set(context, []);
-		this.log.debug(`Started processing job '${jobName}'`, { executionId });
+		const execution = await this.executions.findById(executionId);
+		if (!execution) return;
+		const contextId = this.alepha.context.createContextId();
+		this.perExecutionLogs.set(contextId, []);
+		const abortController = new AbortController();
+		this.abortControllers.set(executionId, abortController);
+		let timeoutId;
+		if (opts.timeout) {
+			const ms = this.dt.duration(opts.timeout).as("milliseconds");
+			timeoutId = setTimeout(() => abortController.abort(), ms);
+		}
+		const now = this.dt.now();
 		try {
 			await this.alepha.context.run(async () => {
-				const abortController = new AbortController();
-				this.abortControllers.set(executionId, abortController);
-				let timeoutId;
-				const opts = registration.options;
-				if (opts.timeout) {
-					const ms = this.dt.duration(opts.timeout).as("milliseconds");
-					timeoutId = setTimeout(() => abortController.abort(), ms);
-				}
-				const now = this.dt.now();
 				await this.alepha.events.emit("job:begin", {
 					name: jobName,
 					now,
 					executionId
 				});
 				try {
-					const execution = await this.executions.findById(executionId);
-					const items = [];
-					if (execution?.payload) items.push({
-						id: executionId,
-						payload: execution.payload,
-						attempt: execution.attempt
-					});
-					this.log.debug(`Running job '${jobName}'`, {
-						executionId,
-						attempt: execution?.attempt,
-						items: items.length
-					});
 					await opts.handler({
-						items,
+						payload: execution.payload,
+						attempt: execution.attempt,
 						now,
-						signal: abortController.signal
+						signal: abortController.signal,
+						executionId
 					});
-					await this.executions.updateById(executionId, {
-						status: "completed",
+					if (record === "all" && this.config.keepLastSuccess > 0) await this.executions.updateById(executionId, {
+						status: "ok",
 						completedAt: this.dt.nowISOString(),
 						key: null
 					});
-					this.log.info(`Job '${jobName}' completed`, { executionId });
-					await this.writeLogs(executionId, context);
+					else await this.executions.deleteById(executionId);
 					await this.alepha.events.emit("job:success", {
 						name: jobName,
 						executionId
 					}, { catch: true });
 				} catch (error) {
 					const err = error instanceof Error ? error : new Error(String(error));
-					if (abortController.signal.aborted) if ((await this.executions.findById(executionId))?.status !== "cancelled") await this.handleFailure(executionId, jobName, err, context);
-					else {
-						await this.writeLogs(executionId, context);
-						await this.alepha.events.emit("job:cancel", {
-							name: jobName,
-							executionId
-						}, { catch: true });
+					if (abortController.signal.aborted) {
+						if ((await this.executions.findById(executionId))?.status === "cancelled") {
+							await this.alepha.events.emit("job:cancel", {
+								name: jobName,
+								executionId
+							}, { catch: true });
+							return;
+						}
 					}
-					else await this.handleFailure(executionId, jobName, err, context);
+					await this.handleFailure(executionId, registration, execution.attempt, err, contextId);
 				} finally {
 					if (timeoutId) clearTimeout(timeoutId);
 					this.abortControllers.delete(executionId);
@@ -544,39 +575,12 @@ var JobProvider = class JobProvider {
 						name: jobName,
 						executionId
 					}, { catch: true });
-					await this.dispatchNextPending(jobName);
 				}
-			}, { context });
+			}, { context: contextId });
 		} finally {
-			this.logs.delete(context);
+			this.perExecutionLogs.delete(contextId);
 		}
 	}
-	/**
-	* After a job finishes (success, failure, or cancel), dispatch any pending
-	* jobs that were deferred due to the concurrency limit.
-	*/
-	async dispatchNextPending(jobName) {
-		if (this.stopping || this.pausedJobs.has(jobName)) return;
-		const registration = this.jobs.get(jobName);
-		if (!registration) return;
-		const available = (registration.options.concurrency ?? 1) - await this.executions.count({
-			jobName: { eq: jobName },
-			status: { eq: "running" }
-		});
-		if (available <= 0) return;
-		const pending = await this.executions.findMany({
-			where: {
-				jobName: { eq: jobName },
-				status: { eq: "pending" }
-			},
-			orderBy: {
-				column: "priority",
-				direction: "asc"
-			},
-			limit: available
-		});
-		for (const exec of pending) await this.scheduleProcessing(jobName, exec.id);
-	}
 	async claim(executionId) {
 		const execution = await this.executions.findById(executionId);
 		if (!execution) return false;
@@ -587,45 +591,46 @@ var JobProvider = class JobProvider {
 			}, {
 				status: "running",
 				attempt: execution.attempt + 1,
-				startedAt: this.dt.nowISOString(),
-				workerId: this.workerId
+				startedAt: this.dt.nowISOString()
 			});
 			return true;
 		} catch {
 			return false;
 		}
 	}
-	async handleFailure(executionId, jobName, error, context) {
-		const execution = await this.executions.findById(executionId);
-		if (!execution) return;
-		const retryOpts = this.getRegistration(jobName).options.retry;
-		if (retryOpts && execution.attempt < execution.maxAttempts && (retryOpts.when ? retryOpts.when(error) : true)) {
-			const nextScheduledAt = this.computeBackoff(retryOpts, execution.attempt);
-			this.log.info(`Job '${jobName}' failed, scheduling retry ${execution.attempt}/${execution.maxAttempts}`, {
+	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}`, {
 				executionId,
 				error: error.message,
 				nextScheduledAt
 			});
 			await this.executions.updateById(executionId, {
-				status: "retrying",
+				status: "scheduled",
 				error: error.message,
-				scheduledAt: nextScheduledAt
+				scheduledAt: nextScheduledAt,
+				logs: this.snapshotLogs(contextId)
 			});
-			await this.writeLogs(executionId, context);
 			const delayMs = Math.max(0, new Date(nextScheduledAt).getTime() - this.dt.nowMillis());
-			this.dt.createTimeout(() => void this.dispatchRetrying(jobName, executionId), delayMs);
+			this.dt.createTimeout(() => {
+				this.dispatchScheduled(jobName, executionId);
+			}, delayMs);
 		} else {
-			this.log.info(`Job '${jobName}' is dead after ${execution.attempt} attempt(s)`, {
+			this.log.info(`Job '${jobName}' dead after ${currentAttempt} attempt(s)`, {
 				executionId,
 				error: error.message
 			});
 			await this.executions.updateById(executionId, {
-				status: "dead",
+				status: "error",
 				error: error.message,
 				completedAt: this.dt.nowISOString(),
-				key: null
+				key: null,
+				logs: this.snapshotLogs(contextId)
 			});
-			await this.writeLogs(executionId, context);
 		}
 		await this.alepha.events.emit("job:error", {
 			name: jobName,
@@ -633,238 +638,160 @@ var JobProvider = class JobProvider {
 			executionId
 		}, { catch: true });
 	}
-	computeBackoff(retryOpts, attempt) {
+	computeBackoff(retry, attempt) {
 		const now = this.dt.now();
-		if (!retryOpts.backoff) return now.add(1, "second").toISOString();
-		if (Array.isArray(retryOpts.backoff)) {
-			const delay = this.dt.duration(retryOpts.backoff);
-			return now.add(delay).toISOString();
-		}
-		const backoff = retryOpts.backoff;
+		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) {
-			const maxMs = this.dt.duration(backoff.max).as("milliseconds");
-			delayMs = Math.min(delayMs, maxMs);
-		}
+		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();
 	}
-	async writeLogs(executionId, context) {
-		const entries = this.logs.get(context);
-		if (!entries || entries.length === 0) return;
-		const maxEntries = this.config.logMaxEntries;
-		if (maxEntries === 0) return;
-		let logs = entries;
-		if (logs.length > maxEntries) {
-			logs = logs.slice(0, maxEntries);
-			logs.push({
-				level: "WARN",
-				message: `Log entries truncated at ${maxEntries}`,
-				timestamp: this.dt.nowMillis(),
-				service: "alepha.jobs",
-				module: "JobProvider"
-			});
-		}
-		try {
-			await this.executionLogs.create({
-				id: executionId,
-				logs
-			});
-		} catch {
-			this.log.warn(`Failed to write logs for execution ${executionId}`);
-		}
-	}
-	async dispatchRetrying(jobName, executionId) {
-		if (this.stopping) return;
-		try {
-			await this.executions.updateOne({
-				id: { eq: executionId },
-				status: { eq: "retrying" }
-			}, { status: "pending" });
-			await this.scheduleProcessing(jobName, executionId);
-		} catch {}
+	snapshotLogs(contextId) {
+		const entries = this.perExecutionLogs.get(contextId);
+		if (!entries || entries.length === 0) return void 0;
+		const max = this.config.logMaxEntries;
+		if (max === 0) return void 0;
+		if (entries.length <= max) return [...entries];
+		const truncated = entries.slice(0, max);
+		truncated.push({
+			level: "WARN",
+			message: `Log entries truncated at ${max}`,
+			timestamp: this.dt.nowMillis(),
+			service: "alepha.jobs",
+			module: "JobProvider"
+		});
+		return truncated;
 	}
-	/**
-	* Recovery Sweep (Section 5.1)
-	*
-	* Runs every `recovery.interval` (default: 1 minute).
-	* - Stale `pending` jobs older than `staleThreshold` → re-dispatch.
-	* - Crashed `running` jobs older than `max(job.timeout * 2, recovery.runTimeout)` → mark failed, apply retry policy.
-	*/
-	async recoverySweep() {
-		this.log.trace("Starting recovery sweep");
+	async sweep() {
 		if (this.stopping) return;
-		if (!await this.tryLock("_alepha:jobs:recovery-lock", 3e5)) return;
+		this.log.trace("Starting job sweep");
+		const now = this.dt.now();
+		const nowIso = now.toISOString();
 		try {
-			const now = this.dt.now();
-			const staleThreshold = now.subtract(this.config.recovery.staleThreshold, "millisecond").toISOString();
-			const pendingWhere = this.executions.createQueryWhere();
-			pendingWhere.status = { eq: "pending" };
-			pendingWhere.createdAt = { lte: staleThreshold };
-			const stalePending = await this.executions.findMany({
-				where: pendingWhere,
+			const dueWhere = this.executions.createQueryWhere();
+			dueWhere.status = { eq: "scheduled" };
+			dueWhere.scheduledAt = { lte: nowIso };
+			const due = await this.executions.findMany({
+				where: dueWhere,
+				orderBy: {
+					column: "priority",
+					direction: "asc"
+				}
+			});
+			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);
+			}
+			const staleIso = now.subtract(this.config.staleThreshold, "millisecond").toISOString();
+			const staleWhere = this.executions.createQueryWhere();
+			staleWhere.status = { eq: "pending" };
+			staleWhere.createdAt = { lte: staleIso };
+			const stale = await this.executions.findMany({
+				where: staleWhere,
 				orderBy: {
 					column: "priority",
 					direction: "asc"
 				}
 			});
-			for (const exec of stalePending) {
+			for (const exec of stale) {
 				if (!this.jobs.has(exec.jobName)) continue;
-				this.log.debug(`Recovery sweep: re-dispatching stale pending job ${exec.jobName} (${exec.id})`);
-				await this.scheduleProcessing(exec.jobName, exec.id);
+				await this.dispatchToQueueSafe(exec.jobName, exec.id);
 			}
 			const runningWhere = this.executions.createQueryWhere();
 			runningWhere.status = { eq: "running" };
 			const running = await this.executions.findMany({ where: runningWhere });
 			const nowMs = now.valueOf();
 			for (const exec of running) {
-				const registration = this.jobs.get(exec.jobName);
-				if (!registration) continue;
+				const reg = this.jobs.get(exec.jobName);
+				if (!reg) continue;
 				if (this.abortControllers.has(exec.id)) continue;
-				const opts = registration.options;
-				let crashThresholdMs;
-				if (opts.timeout) crashThresholdMs = this.dt.duration(opts.timeout).as("milliseconds") * 2;
-				else crashThresholdMs = this.config.recovery.runTimeout;
-				const startedAt = exec.startedAt ? new Date(exec.startedAt).getTime() : 0;
-				if (startedAt > 0 && nowMs - startedAt > crashThresholdMs) {
-					this.log.warn(`Recovery sweep: marking crashed job ${exec.jobName} (${exec.id}) as failed`);
-					const error = /* @__PURE__ */ new Error("Execution assumed crashed (recovered by sweep)");
-					await this.handleFailure(exec.id, exec.jobName, error, "");
+				const crashThresholdMs = reg.options.timeout ? this.dt.duration(reg.options.timeout).as("milliseconds") * 2 : this.config.runTimeout;
+				const startedAtMs = exec.startedAt ? new Date(exec.startedAt).getTime() : 0;
+				if (startedAtMs > 0 && nowMs - startedAtMs > crashThresholdMs) {
+					this.log.warn(`Sweep: marking crashed ${exec.jobName} (${exec.id}) as failed`);
+					const err = /* @__PURE__ */ new Error("Execution assumed crashed (recovered by sweep)");
+					await this.handleFailure(exec.id, reg, exec.attempt, err, "");
 				}
 			}
+			await this.trimRingBuffers();
 		} catch (e) {
-			this.log.error("Recovery sweep failed", { error: e });
-		} finally {
-			await this.releaseLock("_alepha:jobs:recovery-lock");
+			this.log.error("Sweep failed", { error: e });
 		}
 	}
-	/**
-	* Delayed Dispatch Sweep (Section 5.2)
-	*
-	* Runs every `delayed.interval` (default: 30 seconds).
-	* Scans for `scheduled` and `retrying` jobs where `scheduledAt <= now`,
-	* moves them to `pending`, and dispatches to the queue layer.
-	*/
-	async delayedDispatchSweep() {
-		this.log.trace("Starting delayed dispatch sweep");
-		if (this.stopping) return;
-		if (!await this.tryLock("_alepha:jobs:dispatch-lock", 6e4)) return;
+	async dispatchToQueueSafe(jobName, executionId) {
 		try {
-			const now = this.dt.nowISOString();
-			const where = this.executions.createQueryWhere();
-			where.status = { inArray: ["scheduled", "retrying"] };
-			where.scheduledAt = { lte: now };
-			const ready = await this.executions.findMany({
-				where,
-				orderBy: {
-					column: "priority",
-					direction: "asc"
-				}
-			});
-			for (const exec of ready) {
-				if (!this.jobs.has(exec.jobName)) continue;
-				await this.executions.updateById(exec.id, { status: "pending" });
-				await this.scheduleProcessing(exec.jobName, exec.id);
-			}
+			await this.dispatchToQueue(jobName, executionId);
 		} catch (e) {
-			this.log.error("Delayed dispatch sweep failed", { error: e });
-		} finally {
-			await this.releaseLock("_alepha:jobs:dispatch-lock");
+			this.log.warn(`Sweep failed to dispatch ${jobName} (${executionId})`, e);
 		}
 	}
 	/**
-	* Log Purge (Section 5.3)
-	*
-	* Runs daily at 03:00 via cron.
-	* Deletes completed/dead/cancelled execution records older than `logRetentionDays`.
+	* Move a row from `scheduled` → `pending` and dispatch it.
+	* Used by the optimistic retry/delay timer. If the sweep has already moved
+	* the row, or another worker has claimed it, the UPDATE guard fails silently.
 	*/
-	async logPurge() {
+	async dispatchScheduled(jobName, executionId) {
 		if (this.stopping) return;
 		try {
-			const cutoff = this.dt.now().subtract(this.config.logRetentionDays, "day").toISOString();
-			const where = this.executions.createQueryWhere();
-			where.status = { inArray: [
-				"completed",
-				"dead",
-				"cancelled"
-			] };
-			where.completedAt = { lte: cutoff };
-			const expiredIds = await this.executions.findMany({
-				where,
-				columns: ["id"]
+			await this.executions.updateOne({
+				id: { eq: executionId },
+				status: { eq: "scheduled" }
+			}, { status: "pending" });
+			await this.dispatchToQueueSafe(jobName, executionId);
+		} catch {}
+	}
+	async trimRingBuffers() {
+		for (const [jobName, reg] of this.jobs) {
+			const okLimit = reg.options.keep?.ok ?? this.config.keepLastSuccess;
+			const errLimit = reg.options.keep?.error ?? this.config.keepLastError;
+			if (okLimit > 0) await this.trimByStatus(jobName, "ok", okLimit);
+			if (errLimit > 0) await this.trimByStatus(jobName, "error", errLimit);
+		}
+	}
+	async trimByStatus(jobName, status, keep) {
+		try {
+			const rows = await this.executions.findMany({
+				where: {
+					jobName: { eq: jobName },
+					status: { eq: status }
+				},
+				orderBy: {
+					column: "startedAt",
+					direction: "desc"
+				},
+				limit: keep + 50
 			});
-			if (expiredIds.length > 0) {
-				const ids = expiredIds.map((e) => e.id);
-				await this.executionLogs.deleteMany({ id: { inArray: ids } });
-				await this.executions.deleteMany({ id: { inArray: ids } });
-				this.log.info(`Log purge: deleted ${ids.length} old execution records`);
+			if (rows.length <= keep) return;
+			const toDelete = rows.slice(keep).map((r) => r.id);
+			if (toDelete.length > 0) {
+				await this.executions.deleteMany({ id: { inArray: toDelete } });
+				this.log.debug(`Trimmed ${toDelete.length} ${status} rows for '${jobName}'`);
 			}
 		} catch (e) {
-			this.log.error("Log purge failed", { error: e });
+			this.log.warn(`Failed to trim ${status} rows for '${jobName}'`, e);
 		}
 	}
-	pauseJob(name) {
-		this.getRegistration(name);
-		this.pausedJobs.add(name);
-		this.log.info(`Paused job '${name}'`);
-	}
-	async resumeJob(name) {
-		this.getRegistration(name);
-		this.pausedJobs.delete(name);
-		this.log.info(`Resumed job '${name}'`);
-		const pending = await this.executions.findMany({
-			where: {
-				jobName: { eq: name },
-				status: { eq: "pending" }
-			},
-			orderBy: {
-				column: "priority",
-				direction: "asc"
-			}
-		});
-		for (const exec of pending) await this.scheduleProcessing(name, exec.id);
-	}
-	isJobPaused(name) {
-		return this.pausedJobs.has(name);
-	}
-	getPausedJobs() {
-		return [...this.pausedJobs];
-	}
-	async tryLock(key, ttlMs) {
-		const lockValue = `${this.workerId},${this.dt.nowISOString()}`;
-		const [lockId] = (await this.lockProvider.set(key, lockValue, true, ttlMs)).split(",");
-		return lockId === this.workerId;
-	}
-	async releaseLock(key) {
-		await this.lockProvider.del(key);
-	}
 	onStart = $hook({
 		on: "start",
 		handler: async () => {
-			this.workerId = crypto.randomUUID().slice(0, 12);
+			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.`);
 			this.log.info(`Job system OK`, {
-				workerId: this.workerId,
-				dispatch: this.queueDispatch ? "queue" : "inline"
+				dispatch: this.queueDispatch ? "queue" : "inline-only",
+				jobs: this.jobs.size
 			});
 			this.alepha.events.on("log", ({ entry }) => {
 				const ctx = entry.context;
 				if (!ctx) return;
-				const entries = this.logs.get(ctx);
+				const entries = this.perExecutionLogs.get(ctx);
 				if (!entries) return;
 				entries.push(entry);
 			});
-			if (!this.alepha.isServerless()) {
-				await this.delayedDispatchSweep();
-				await this.recoverySweep();
-			}
-			this.cronProvider.createCronJob("_alepha:jobs:recovery", JobProvider.SWEEP_CRON, async () => {
-				await this.recoverySweep();
-			}, true);
-			this.cronProvider.createCronJob("_alepha:jobs:dispatch", JobProvider.SWEEP_CRON, async () => {
-				await this.delayedDispatchSweep();
-			}, true);
-			this.cronProvider.createCronJob("_alepha:jobs:log-purge", "0 0 * * *", async () => {
-				await this.logPurge();
+			if (!this.alepha.isServerless()) await this.sweep();
+			this.cronProvider.createCronJob("api:jobs:sweep", SWEEP_CRON, async () => {
+				await this.sweep();
 			}, true);
 		}
 	});
@@ -891,7 +818,12 @@ var JobProvider = class JobProvider {
 //#endregion
 //#region ../../src/api/jobs/primitives/$job.ts
 /**
-* Job primitive for defining scheduled and on-demand tasks with payload validation and retry policies.
+* Job primitive for defining scheduled (cron) or queued (push) tasks.
+*
+* A job must be either **cron-only** (pass `cron`) or **queue-only**
+* (pass `schema`), never both. To run scheduled work that processes
+* payloads, compose two jobs: a cron that pushes payloads, and a
+* queue job that handles them.
 */
 const $job = (options) => {
 	return createPrimitive(JobPrimitive, options);
@@ -899,7 +831,7 @@ const $job = (options) => {
 var JobPrimitive = class extends PipelinePrimitive {
 	jobProvider = $inject(JobProvider);
 	get name() {
-		return `${this.config.service.name}.${this.config.propertyKey}`;
+		return this.options.name ?? `${this.config.service.name}.${this.config.propertyKey}`;
 	}
 	onInit() {
 		const handler = this.handler.run.bind(this.handler);
@@ -909,173 +841,148 @@ var JobPrimitive = class extends PipelinePrimitive {
 		});
 	}
 	/**
-	* Push a single payload or an array of payloads.
+	* Push a single payload to the queue (queue-mode only).
 	*/
 	async push(payload, options) {
-		if (Array.isArray(payload)) return await Promise.all(payload.map((p) => this.jobProvider.push(this.name, p, options)));
 		return this.jobProvider.push(this.name, payload, options);
 	}
 	/**
-	* Push multiple payloads with per-item options.
+	* Push multiple payloads at once (queue-mode only).
+	* Batched INSERT + batched queue send when supported.
 	*/
 	async pushMany(items) {
 		return this.jobProvider.pushMany(this.name, items);
 	}
 	/**
-	* Cancel a running or pending execution.
+	* Cancel a pending or running execution.
 	*/
 	async cancel(executionId) {
 		return this.jobProvider.cancel(executionId);
 	}
 	/**
-	* Manually trigger the job (admin / CLI).
+	* Manually fire a cron-mode job, or trigger a queue-mode job with an explicit payload.
 	*/
 	async trigger(context) {
 		return this.jobProvider.trigger(this.name, context);
 	}
-	/**
-	* Pause this job. Pushed items are still accepted but processing is held.
-	*/
-	pause() {
-		this.jobProvider.pauseJob(this.name);
-	}
-	/**
-	* Resume a paused job and dispatch any pending items.
-	*/
-	async resume() {
-		return this.jobProvider.resumeJob(this.name);
-	}
-	/**
-	* Whether this job is currently paused.
-	*/
-	get paused() {
-		return this.jobProvider.isJobPaused(this.name);
-	}
 };
 $job[KIND] = JobPrimitive;
 //#endregion
 //#region ../../src/api/jobs/services/JobService.ts
+/**
+* Admin surface for the job system.
+*
+* Six methods: list jobs, list executions, get execution,
+* trigger, retry, cancel. Everything else lives in events — any
+* analytics/observability is an external concern that subscribes
+* to `job:begin` / `job:success` / `job:error`.
+*/
 var JobService = class {
 	alepha = $inject(Alepha);
-	dt = $inject(DateTimeProvider);
 	log = $logger();
 	jobProvider = $inject(JobProvider);
-	database = $inject(DatabaseProvider);
 	executions = $repository(jobExecutionEntity);
-	executionLogs = $repository(jobExecutionLogEntity);
 	computeCan(status) {
 		return {
-			retry: status === "dead" || status === "cancelled",
-			cancel: status === "pending" || status === "running" || status === "scheduled" || status === "retrying"
+			retry: status === "error" || status === "cancelled",
+			cancel: status === "pending" || status === "running" || status === "scheduled"
 		};
 	}
 	/**
-	* Convert an ISO date string to the raw SQL parameter format
-	* expected by the current database dialect.
-	*
-	* - PostgreSQL: ISO string (timestamp comparison)
-	* - SQLite: epoch milliseconds (integer comparison)
+	* List every registered job with recent ok/error counts and lastRun.
+	* One aggregate query covers all jobs.
 	*/
-	toRawDate(iso) {
-		return this.database.dialect === "sqlite" ? new Date(iso).getTime() : iso;
-	}
-	async getStats(days) {
-		const jobs = this.jobProvider.getRegisteredJobs();
-		const periodAgo = this.toRawDate(this.dt.now().subtract(days ?? 1, "day").toISOString());
-		const row = (await this.executions.query((e) => sql`
+	async listJobs() {
+		const registry = this.jobProvider.getRegisteredJobs();
+		const aggRows = await this.executions.query((e) => sql`
         SELECT
-          COUNT(*) FILTER (WHERE ${e.status} = 'running') AS running,
-          COUNT(*) FILTER (WHERE ${e.status} = 'pending') AS pending,
-          COUNT(*) FILTER (WHERE ${e.status} = 'scheduled') AS scheduled,
-          COUNT(*) FILTER (WHERE ${e.status} = 'retrying') AS retrying,
-          COUNT(*) FILTER (WHERE ${e.status} = 'dead') AS dead,
-          COUNT(*) FILTER (WHERE ${e.status} = 'completed' AND ${e.completedAt} >= ${periodAgo}) AS completed_24h,
-          COUNT(*) FILTER (WHERE ${e.status} = 'dead' AND ${e.completedAt} >= ${periodAgo}) AS failed_24h
+          ${e.jobName} AS job_name,
+          ${e.status} AS status,
+          COUNT(*) AS count,
+          MAX(${e.completedAt}) AS last_run
         FROM ${e}
+        WHERE ${e.status} IN ('ok', 'error')
+        GROUP BY ${e.jobName}, ${e.status}
       `, t.object({
-			running: t.string(),
-			pending: t.string(),
-			scheduled: t.string(),
-			retrying: t.string(),
-			dead: t.string(),
-			completed_24h: t.string(),
-			failed_24h: t.string()
-		})))[0];
-		return {
-			registered: jobs.size,
-			running: Number(row.running),
-			pending: Number(row.pending),
-			scheduled: Number(row.scheduled),
-			retrying: Number(row.retrying),
-			dead: Number(row.dead),
-			completed: Number(row.completed_24h),
-			failed: Number(row.failed_24h)
+			job_name: t.string(),
+			status: t.string(),
+			count: t.string(),
+			last_run: t.optional(t.nullable(t.union([t.string(), t.number()])))
+		}));
+		const toIso = (v) => {
+			if (v === null || v === void 0) return void 0;
+			if (typeof v === "number") return new Date(v).toISOString();
+			return v;
 		};
-	}
-	getRegistry() {
-		const jobs = this.jobProvider.getRegisteredJobs();
+		const byJob = /* @__PURE__ */ new Map();
+		for (const row of aggRows) {
+			const entry = byJob.get(row.job_name) ?? {
+				ok: 0,
+				error: 0
+			};
+			if (row.status === "ok") entry.ok = Number(row.count);
+			if (row.status === "error") entry.error = Number(row.count);
+			const iso = toIso(row.last_run);
+			if (iso && (!entry.lastRun || iso > entry.lastRun)) entry.lastRun = iso;
+			byJob.set(row.job_name, entry);
+		}
 		const result = [];
-		for (const [name, reg] of jobs) {
+		for (const [name, reg] of registry) {
 			const opts = reg.options;
-			const hasCron = Boolean(opts.cron);
-			const hasSchema = Boolean(opts.schema);
-			let type;
-			if (hasCron && hasSchema) type = "both";
-			else if (hasCron) type = "cron";
-			else type = "push";
-			const registration = {
+			const counts = byJob.get(name) ?? {
+				ok: 0,
+				error: 0
+			};
+			result.push({
 				name,
-				type,
-				priority: opts.priority ?? "normal",
-				concurrency: opts.concurrency ?? 1,
-				hasSchema,
+				description: opts.description,
+				type: reg.type,
 				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,
-				paused: this.jobProvider.isJobPaused(name)
-			};
-			result.push(registration);
+				recent: counts
+			});
 		}
 		return result;
 	}
-	async findExecutions(query = {}) {
-		query.sort ??= "-createdAt";
+	/**
+	* Recent executions for a single job, ORDER BY startedAt DESC.
+	*/
+	async getExecutions(jobName, query = {}) {
+		if (!this.jobProvider.getRegisteredJobs().has(jobName)) throw new NotFoundError(`Job not found: ${jobName}`);
 		const where = this.executions.createQueryWhere();
-		if (query.job) where.jobName = { eq: query.job };
+		where.jobName = { eq: jobName };
 		if (query.status) where.status = { eq: query.status };
-		if (query.priority) where.priority = { eq: {
-			critical: 0,
-			high: 1,
-			normal: 2,
-			low: 3
-		}[query.priority] };
-		if (query.from) where.createdAt = { gte: query.from };
-		if (query.to) where.createdAt = {
-			...where.createdAt,
-			lte: query.to
-		};
-		const page = await this.executions.paginate(query, { where }, { count: true });
-		return {
-			...page,
-			content: page.content.map((exec) => ({
-				...exec,
-				can: this.computeCan(exec.status)
-			}))
-		};
+		return (await this.executions.findMany({
+			where,
+			orderBy: {
+				column: "startedAt",
+				direction: "desc"
+			},
+			limit: query.limit ?? 20
+		})).map((row) => ({
+			...row,
+			can: this.computeCan(row.status)
+		}));
 	}
+	/**
+	* Full execution detail (includes captured logs).
+	*/
 	async getExecution(id) {
 		const execution = await this.executions.findById(id);
 		if (!execution) throw new NotFoundError(`Execution not found: ${id}`);
-		const logRecord = await this.executionLogs.findById(id);
 		return {
 			...execution,
-			can: this.computeCan(execution.status),
-			logs: logRecord?.logs
+			can: this.computeCan(execution.status)
 		};
 	}
+	/**
+	* Manual trigger (cron jobs) or push-with-payload (queue jobs).
+	*/
 	async triggerJob(name, context) {
 		const job = this.alepha.primitives($job).find((j) => j.name === name);
 		if (!job) throw new NotFoundError(`Job not found: ${name}`);
@@ -1083,18 +990,21 @@ var JobService = class {
 		await job.trigger(context);
 		return { ok: true };
 	}
+	/**
+	* Retry a dead or cancelled execution by re-pushing with the original payload.
+	*/
 	async retryExecution(id, context) {
 		const execution = await this.executions.findById(id);
 		if (!execution) throw new NotFoundError(`Execution not found: ${id}`);
-		if (execution.status !== "dead" && execution.status !== "cancelled") throw new AlephaError(`Cannot retry execution in '${execution.status}' status`);
+		if (execution.status !== "error" && execution.status !== "cancelled") throw new AlephaError(`Cannot retry execution in '${execution.status}' status`);
+		const job = this.alepha.primitives($job).find((j) => j.name === execution.jobName);
+		if (!job) throw new NotFoundError(`Job not found: ${execution.jobName}`);
 		this.log.info(`Retrying execution ${id}`, {
 			jobName: execution.jobName,
 			previousStatus: execution.status,
 			triggeredBy: context?.triggeredByName ?? context?.triggeredBy
 		});
-		const job = this.alepha.primitives($job).find((j) => j.name === execution.jobName);
-		if (!job) throw new NotFoundError(`Job not found: ${execution.jobName}`);
-		if (execution.payload) await job.push(execution.payload, {});
+		if (execution.payload) await job.push(execution.payload);
 		else await job.trigger({
 			triggeredBy: context?.triggeredBy,
 			triggeredByName: context?.triggeredByName
@@ -1109,302 +1019,61 @@ var JobService = class {
 		});
 		return { ok: true };
 	}
-	pauseJob(name, context) {
-		const job = this.alepha.primitives($job).find((j) => j.name === name);
-		if (!job) throw new NotFoundError(`Job not found: ${name}`);
-		this.log.info(`Pausing job '${name}'`, { pausedBy: context?.pausedByName ?? context?.pausedBy });
-		job.pause();
-		return { ok: true };
-	}
-	async resumeJob(name, context) {
-		const job = this.alepha.primitives($job).find((j) => j.name === name);
-		if (!job) throw new NotFoundError(`Job not found: ${name}`);
-		this.log.info(`Resuming job '${name}'`, { resumedBy: context?.resumedByName ?? context?.resumedBy });
-		await job.resume();
-		return { ok: true };
-	}
-	getPausedJobs() {
-		return this.jobProvider.getPausedJobs();
-	}
-	async getCronJobs() {
-		const jobs = this.jobProvider.getRegisteredJobs();
-		const cronJobNames = [];
-		for (const [name, reg] of jobs) if (reg.options.cron) cronJobNames.push(name);
-		const lastByJob = await this.getLastExecutionPerJob(cronJobNames);
-		const result = [];
-		for (const name of cronJobNames) {
-			const opts = jobs.get(name).options;
-			const last = lastByJob.get(name);
-			result.push({
-				name,
-				cron: opts.cron,
-				lock: opts.lock !== false,
-				priority: opts.priority ?? "normal",
-				concurrency: opts.concurrency ?? 1,
-				hasSchema: Boolean(opts.schema),
-				paused: this.jobProvider.isJobPaused(name),
-				lastExecution: last ? {
-					id: last.id,
-					status: last.status,
-					startedAt: last.started_at ?? void 0,
-					completedAt: last.completed_at ?? void 0,
-					error: last.error ?? void 0
-				} : void 0
-			});
-		}
-		return result;
-	}
-	async getQueueDepth() {
-		const jobs = this.jobProvider.getRegisteredJobs();
-		const rows = await this.executions.query((e) => sql`
-        SELECT
-          ${e.jobName} AS job_name,
-          COUNT(*) FILTER (WHERE ${e.status} = 'pending') AS pending,
-          COUNT(*) FILTER (WHERE ${e.status} = 'running') AS running,
-          COUNT(*) FILTER (WHERE ${e.status} = 'scheduled') AS scheduled,
-          COUNT(*) FILTER (WHERE ${e.status} = 'retrying') AS retrying,
-          COUNT(*) FILTER (WHERE ${e.status} = 'dead') AS dead
-        FROM ${e}
-        WHERE ${e.status} IN ('pending', 'running', 'scheduled', 'retrying', 'dead')
-        GROUP BY ${e.jobName}
-      `, t.object({
-			job_name: t.string(),
-			pending: t.string(),
-			running: t.string(),
-			scheduled: t.string(),
-			retrying: t.string(),
-			dead: t.string()
-		}));
-		const counts = new Map(rows.map((r) => [r.job_name, r]));
-		const result = [];
-		for (const [name, reg] of jobs) {
-			const row = counts.get(name);
-			result.push({
-				jobName: name,
-				pending: Number(row?.pending ?? 0),
-				running: Number(row?.running ?? 0),
-				scheduled: Number(row?.scheduled ?? 0),
-				retrying: Number(row?.retrying ?? 0),
-				dead: Number(row?.dead ?? 0),
-				concurrency: reg.options.concurrency ?? 1,
-				paused: this.jobProvider.isJobPaused(name)
-			});
-		}
-		return result;
-	}
-	async getActivity(days = 14) {
-		if (this.database.dialect === "sqlite") return this.getActivitySqlite(days);
-		return (await this.executions.query((e) => sql`
-        WITH date_series AS (
-          SELECT generate_series(
-            CURRENT_DATE - ${days - 1}::int,
-            CURRENT_DATE,
-            '1 day'::interval
-          )::date AS date
-        )
-        SELECT
-          ds.date::text AS date,
-          COALESCE(COUNT(*) FILTER (WHERE ${e.status} = 'completed'), 0) AS completed,
-          COALESCE(COUNT(*) FILTER (WHERE ${e.status} = 'dead'), 0) AS failed
-        FROM date_series ds
-        LEFT JOIN ${e} ON DATE(${e.completedAt}) = ds.date
-          AND ${e.status} IN ('completed', 'dead')
-        GROUP BY ds.date
-        ORDER BY ds.date ASC
-      `, t.object({
-			date: t.string(),
-			completed: t.string(),
-			failed: t.string()
-		}))).map((row) => ({
-			date: row.date,
-			completed: Number(row.completed),
-			failed: Number(row.failed)
-		}));
-	}
-	async getActivitySqlite(days = 14) {
-		const startDate = this.dt.now().subtract(days - 1, "day");
-		const where = this.executions.createQueryWhere();
-		where.status = { inArray: ["completed", "dead"] };
-		where.completedAt = { gte: startDate.startOf("day").toISOString() };
-		const executions = await this.executions.findMany({ where });
-		const byDate = /* @__PURE__ */ new Map();
-		for (let i = 0; i < days; i++) {
-			const date = startDate.add(i, "day").format("YYYY-MM-DD");
-			byDate.set(date, {
-				completed: 0,
-				failed: 0
-			});
-		}
-		for (const exec of executions) {
-			if (!exec.completedAt) continue;
-			const date = this.dt.of(exec.completedAt).format("YYYY-MM-DD");
-			const entry = byDate.get(date);
-			if (!entry) continue;
-			if (exec.status === "completed") entry.completed++;
-			else entry.failed++;
-		}
-		return [...byDate.entries()].map(([date, counts]) => ({
-			date,
-			...counts
-		}));
-	}
-	async getTopFailures(days) {
-		const periodAgoIso = this.dt.now().subtract(days ?? 7, "day").toISOString();
-		if (this.database.dialect === "sqlite") return this.getTopFailuresSqlite(periodAgoIso);
-		return (await this.executions.query((e) => sql`
-        SELECT
-          ${e.jobName} AS job_name,
-          COUNT(*) AS failures,
-          (ARRAY_AGG(${e.error} ORDER BY ${e.completedAt} DESC))[1] AS last_error
-        FROM ${e}
-        WHERE ${e.status} = 'dead'
-          AND ${e.completedAt} >= ${periodAgoIso}
-        GROUP BY ${e.jobName}
-        ORDER BY failures DESC
-      `, t.object({
-			job_name: t.string(),
-			failures: t.string(),
-			last_error: t.optional(t.nullable(t.string()))
-		}))).map((row) => ({
-			jobName: row.job_name,
-			failures: Number(row.failures),
-			lastError: row.last_error ?? void 0
-		}));
-	}
-	async getTopFailuresSqlite(periodAgoIso) {
-		const where = this.executions.createQueryWhere();
-		where.status = { eq: "dead" };
-		where.completedAt = { gte: periodAgoIso };
-		const failures = await this.executions.findMany({
-			where,
-			orderBy: {
-				column: "completedAt",
-				direction: "desc"
-			}
-		});
-		const byJob = /* @__PURE__ */ new Map();
-		for (const exec of failures) {
-			const entry = byJob.get(exec.jobName) ?? { failures: 0 };
-			entry.failures++;
-			if (!entry.lastError) entry.lastError = exec.error ?? void 0;
-			byJob.set(exec.jobName, entry);
-		}
-		return [...byJob.entries()].map(([jobName, data]) => ({
-			jobName,
-			failures: data.failures,
-			lastError: data.lastError
-		})).sort((a, b) => b.failures - a.failures);
-	}
-	/**
-	* Fetch the most recent execution per job name.
-	*
-	* - PostgreSQL: uses `DISTINCT ON` for a single-pass query
-	* - SQLite: uses ORM queries (one per job name) since `DISTINCT ON` is not supported
-	*/
-	async getLastExecutionPerJob(jobNames) {
-		if (jobNames.length === 0) return /* @__PURE__ */ new Map();
-		if (this.database.dialect === "sqlite") {
-			const result = /* @__PURE__ */ new Map();
-			for (const name of jobNames) {
-				const rows = await this.executions.findMany({
-					where: { jobName: { eq: name } },
-					orderBy: {
-						column: "createdAt",
-						direction: "desc"
-					},
-					limit: 1
-				});
-				if (rows[0]) result.set(name, {
-					id: rows[0].id,
-					job_name: rows[0].jobName,
-					status: rows[0].status,
-					started_at: rows[0].startedAt,
-					completed_at: rows[0].completedAt,
-					error: rows[0].error
-				});
-			}
-			return result;
-		}
-		const schema = t.object({
-			id: t.string(),
-			job_name: t.string(),
-			status: t.string(),
-			started_at: t.optional(t.nullable(t.string())),
-			completed_at: t.optional(t.nullable(t.string())),
-			error: t.optional(t.nullable(t.string()))
-		});
-		const rows = await this.executions.query((e) => sql`
-        SELECT DISTINCT ON (${e.jobName})
-          ${e.id}, ${e.jobName} AS job_name, ${e.status},
-          ${e.startedAt} AS started_at, ${e.completedAt} AS completed_at, ${e.error}
-        FROM ${e}
-        WHERE ${e.jobName} IN (${sql.join(jobNames.map((n) => sql`${n}`), sql`, `)})
-        ORDER BY ${e.jobName}, ${e.createdAt} DESC
-      `, schema);
-		return new Map(rows.map((r) => [r.job_name, r]));
-	}
 };
 //#endregion
 //#region ../../src/api/jobs/controllers/AdminJobController.ts
+/**
+* Minimal admin surface for the job system. Six endpoints.
+*/
 var AdminJobController = class {
 	url = "/jobs";
 	group = "admin:jobs";
 	jobService = $inject(JobService);
-	getJobStats = $action({
-		path: `${this.url}/stats`,
-		group: this.group,
-		use: [$secure({ permissions: ["admin:job:read"] })],
-		schema: {
-			query: jobActivityQuerySchema,
-			response: jobStatsSchema
-		},
-		handler: ({ query }) => this.jobService.getStats(query.days)
-	});
-	getJobRegistry = $action({
+	listJobs = $action({
 		path: this.url,
 		group: this.group,
 		use: [$secure({ permissions: ["admin:job:read"] })],
 		schema: { response: t.array(jobRegistrationSchema) },
-		handler: () => this.jobService.getRegistry()
+		handler: () => this.jobService.listJobs()
 	});
-	findJobExecutions = $action({
-		path: `${this.url}/executions`,
+	listExecutions = $action({
+		path: `${this.url}/:name/executions`,
 		group: this.group,
 		use: [$secure({ permissions: ["admin:job:read"] })],
 		schema: {
+			params: t.object({ name: t.text() }),
 			query: jobExecutionQuerySchema,
-			response: t.page(jobExecutionResourceSchema)
+			response: t.array(jobExecutionResourceSchema)
 		},
-		handler: ({ query }) => this.jobService.findExecutions(query)
+		handler: ({ params, query }) => this.jobService.getExecutions(params.name, query)
 	});
-	getJobExecution = $action({
+	getExecution = $action({
 		path: `${this.url}/executions/:id`,
 		group: this.group,
 		use: [$secure({ permissions: ["admin:job:read"] })],
 		schema: {
 			params: t.object({ id: t.uuid() }),
-			response: jobExecutionDetailResourceSchema
+			response: jobExecutionResourceSchema
 		},
 		handler: ({ params }) => this.jobService.getExecution(params.id)
 	});
 	triggerJob = $action({
 		method: "POST",
-		path: `${this.url}/trigger`,
+		path: `${this.url}/:name/trigger`,
 		group: this.group,
 		use: [$secure({ permissions: ["admin:job:trigger"] })],
 		schema: {
+			params: t.object({ name: t.text() }),
 			body: triggerJobSchema,
 			response: okSchema
 		},
-		handler: async ({ body, user }) => {
-			return this.jobService.triggerJob(body.name, {
-				payload: body.payload,
-				triggeredBy: user?.id,
-				triggeredByName: user?.name
-			});
-		}
+		handler: ({ params, body, user }) => this.jobService.triggerJob(params.name, {
+			payload: body.payload,
+			triggeredBy: user?.id,
+			triggeredByName: user?.name
+		})
 	});
-	retryJobExecution = $action({
+	retryExecution = $action({
 		method: "POST",
 		path: `${this.url}/executions/:id/retry`,
 		group: this.group,
@@ -1413,14 +1082,12 @@ var AdminJobController = class {
 			params: t.object({ id: t.uuid() }),
 			response: okSchema
 		},
-		handler: async ({ params, user }) => {
-			return this.jobService.retryExecution(params.id, {
-				triggeredBy: user?.id,
-				triggeredByName: user?.name
-			});
-		}
+		handler: ({ params, user }) => this.jobService.retryExecution(params.id, {
+			triggeredBy: user?.id,
+			triggeredByName: user?.name
+		})
 	});
-	cancelJobExecution = $action({
+	cancelExecution = $action({
 		method: "POST",
 		path: `${this.url}/executions/:id/cancel`,
 		group: this.group,
@@ -1429,101 +1096,25 @@ var AdminJobController = class {
 			params: t.object({ id: t.uuid() }),
 			response: okSchema
 		},
-		handler: async ({ params, user }) => {
-			return this.jobService.cancelExecution(params.id, {
-				cancelledBy: user?.id,
-				cancelledByName: user?.name
-			});
-		}
-	});
-	getJobActivity = $action({
-		path: `${this.url}/activity`,
-		group: this.group,
-		use: [$secure({ permissions: ["admin:job:read"] })],
-		schema: {
-			query: jobActivityQuerySchema,
-			response: t.array(jobActivityPointSchema)
-		},
-		handler: ({ query }) => this.jobService.getActivity(query.days)
-	});
-	getCronJobs = $action({
-		path: `${this.url}/cron`,
-		group: this.group,
-		use: [$secure({ permissions: ["admin:job:read"] })],
-		schema: { response: t.array(jobCronInfoSchema) },
-		handler: () => this.jobService.getCronJobs()
-	});
-	getJobQueueDepth = $action({
-		path: `${this.url}/queue`,
-		group: this.group,
-		use: [$secure({ permissions: ["admin:job:read"] })],
-		schema: { response: t.array(jobQueueDepthSchema) },
-		handler: () => this.jobService.getQueueDepth()
-	});
-	getJobTopFailures = $action({
-		path: `${this.url}/failures`,
-		group: this.group,
-		use: [$secure({ permissions: ["admin:job:read"] })],
-		schema: {
-			query: jobActivityQuerySchema,
-			response: t.array(jobFailureSchema)
-		},
-		handler: ({ query }) => this.jobService.getTopFailures(query.days)
-	});
-	pauseJob = $action({
-		method: "POST",
-		path: `${this.url}/pause`,
-		group: this.group,
-		use: [$secure({ permissions: ["admin:job:trigger"] })],
-		schema: {
-			body: t.object({ name: t.text() }),
-			response: okSchema
-		},
-		handler: ({ body, user }) => {
-			return this.jobService.pauseJob(body.name, {
-				pausedBy: user?.id,
-				pausedByName: user?.name
-			});
-		}
-	});
-	resumeJob = $action({
-		method: "POST",
-		path: `${this.url}/resume`,
-		group: this.group,
-		use: [$secure({ permissions: ["admin:job:trigger"] })],
-		schema: {
-			body: t.object({ name: t.text() }),
-			response: okSchema
-		},
-		handler: async ({ body, user }) => {
-			return this.jobService.resumeJob(body.name, {
-				resumedBy: user?.id,
-				resumedByName: user?.name
-			});
-		}
-	});
-	getPausedJobs = $action({
-		path: `${this.url}/paused`,
-		group: this.group,
-		use: [$secure({ permissions: ["admin:job:read"] })],
-		schema: { response: t.array(t.text()) },
-		handler: () => this.jobService.getPausedJobs()
+		handler: ({ params, user }) => this.jobService.cancelExecution(params.id, {
+			cancelledBy: user?.id,
+			cancelledByName: user?.name
+		})
 	});
 };
 //#endregion
 //#region ../../src/api/jobs/providers/JobQueueProvider.ts
 /**
-* Optional queue-backed dispatch for the job system.
+* Plumbs outbox-style dispatch through `AlephaQueue`.
 *
-* When registered, `JobProvider` will push work through this queue instead of
-* executing inline. This is the default for long-running (non-serverless) environments.
-* In serverless environments (Cloudflare Workers, Vercel), this provider is typically
-* omitted so jobs execute inline without requiring an external queue resource.
+* 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: "_alepha:jobs:dispatch",
+		name: "api:jobs:dispatch",
 		schema: t.object({
 			jobName: t.text(),
 			executionId: t.text()
@@ -1532,15 +1123,12 @@ var JobQueueProvider = class {
 			await this.jobProvider.processExecution(msg.payload.jobName, msg.payload.executionId);
 		}
 	});
-	onStart = $hook({
-		on: "start",
-		handler: async () => {
-			this.jobProvider.queueDispatch = (jobName, executionId) => this.push(jobName, executionId);
-		}
-	});
-	/**
-	* Push a job execution onto the queue for async processing.
-	*/
+	constructor() {
+		this.wireDispatcher();
+	}
+	wireDispatcher() {
+		this.jobProvider.queueDispatch = (jobName, executionId) => this.push(jobName, executionId);
+	}
 	async push(jobName, executionId) {
 		await this.queue.push({
 			jobName,
@@ -1550,17 +1138,17 @@ var JobQueueProvider = class {
 };
 //#endregion
 //#region ../../src/api/jobs/index.ts
-const jobEnvSchema = t.object({ ALEPHA_JOBS_QUEUE: t.optional(t.integer({ description: "Set to 1 to always use queue, 0 to disable queue (default: auto-detect based on environment)" })) });
 /**
-* Job execution framework — unified primitive for deferred, scheduled, and queued work.
+* Job execution framework — cron and durable queue work with a single primitive.
 *
-* **Features:**
-* - Push-based jobs with typed payloads
-* - Cron scheduling with execution tracking
-* - Retry with exponential backoff
-* - Priority, delay, cancellation
-* - Deduplication via unique keys
-* - Per-execution log capture
+* 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.
+*
+* **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`.
 *
 * @module alepha.api.jobs
 */
@@ -1571,17 +1159,22 @@ const AlephaApiJobs = $module({
 		JobProvider,
 		JobService,
 		AdminJobController
-	],
-	variants: [JobQueueProvider],
-	register: (alepha) => {
-		const env = alepha.parseEnv(jobEnvSchema);
-		if (env.ALEPHA_JOBS_QUEUE === 1 ? true : env.ALEPHA_JOBS_QUEUE === 0 ? false : !alepha.isServerless()) {
-			alepha.with(AlephaQueue);
-			alepha.with(JobQueueProvider);
-		}
-	}
+	]
+});
+/**
+* Queue support for `$job`. Import alongside {@link AlephaApiJobs} when your
+* app declares queue-mode jobs (any `$job` with a `schema`).
+*
+* Adds `JobQueueProvider` which plumbs the outbox dispatch through `AlephaQueue`.
+*
+* @module alepha.api.jobs.queue
+*/
+const AlephaApiJobsQueue = $module({
+	name: "alepha.api.jobs.queue",
+	imports: [AlephaApiJobs, AlephaQueue],
+	services: [JobQueueProvider]
 });
 //#endregion
-export { $job, AdminJobController, AlephaApiJobs, JobPrimitive, JobProvider, JobQueueProvider, JobService, jobActivityPointSchema, jobActivityQuerySchema, jobConfig, jobCronInfoSchema, jobExecutionCanSchema, jobExecutionDetailResourceSchema, jobExecutionEntity, jobExecutionLogEntity, jobExecutionQuerySchema, jobExecutionResourceSchema, jobFailureSchema, jobQueueDepthSchema, jobRegistrationSchema, jobStatsSchema, triggerJobSchema };
+export { $job, AdminJobController, AlephaApiJobs, AlephaApiJobsQueue, JobPrimitive, JobProvider, JobQueueProvider, JobService, PRIORITY_MAP, PRIORITY_REVERSE, jobConfig, jobExecutionEntity, jobExecutionQuerySchema, jobExecutionResourceSchema, jobRegistrationSchema, triggerJobSchema };
 
 //# sourceMappingURL=index.js.map