@aigne/afs-scheduler 1.12.0-beta.5

package/dist/scheduler-provider.mjs

@@ -0,0 +1,1237 @@
+import { DOJobExecutor } from "./do-job-executor.mjs";
+import { LocalExecutor } from "./local-executor.mjs";
+import { TaskStore } from "./task-store.mjs";
+import { CancelArgsSchema, CancelJobArgsSchema, ClaimArgsSchema, DispatchArgsSchema, HeartbeatArgsSchema, RetryArgsSchema, ScheduleArgsSchema, SchedulerSnapshotSchema, SubmitArgsSchema, SubmitJobArgsSchema, UnscheduleArgsSchema } from "./types.mjs";
+import { __decorate } from "./_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.mjs";
+import { v7 } from "@aigne/uuid";
+import { AFSConflictError, makeNsLog } from "@aigne/afs";
+import { AFSBaseProvider, Actions, Explain, List, Meta, PersistenceHelper, Read } from "@aigne/afs/provider";
+import { joinURL } from "ufo";
+import { z } from "zod/v4";
+
+//#region src/scheduler-provider.ts
+const log = makeNsLog("provider:scheduler");
+const DEFAULT_SCHEDULED_TASK_TIMEOUT_MS = 0;
+/** Default lease duration for claim-based tasks (#1067) when `claim` omits `leaseDuration`. */
+const DEFAULT_LEASE_DURATION_MS = 300 * 1e3;
+const ACTION_NAMES = [
+	"dispatch",
+	"cancel",
+	"retry",
+	"schedule",
+	"unschedule",
+	"heartbeat",
+	"submit-job",
+	"cancel-job",
+	"claim",
+	"submit"
+];
+var AFSScheduler = class extends AFSBaseProvider {
+	static manifest() {
+		return {
+			name: "scheduler",
+			description: "Task dispatch and execution management.\n- Dispatch tasks for background execution with optional proc budget integration\n- Cron-based scheduling with duplicate protection\n- Map-reduce job coordination with batch processing",
+			uriTemplate: "scheduler://",
+			category: "compute",
+			schema: z.object({
+				name: z.string().optional(),
+				description: z.string().optional(),
+				maxHistory: z.number().int().positive().optional(),
+				storagePath: z.string().optional(),
+				procPath: z.string().optional(),
+				budgetBlockedTTL: z.number().int().nonnegative().optional()
+			}),
+			tags: [
+				"scheduler",
+				"dispatch",
+				"cron",
+				"background"
+			],
+			capabilityTags: [
+				"read-write",
+				"auth:none",
+				"local"
+			],
+			security: {
+				riskLevel: "system",
+				resourceAccess: ["process-spawn"],
+				dataSensitivity: ["code"],
+				notes: ["Executes tasks by delegating to AFS exec, can spawn background processes"]
+			},
+			capabilities: { crossProvider: { afsAccess: true } }
+		};
+	}
+	name;
+	description;
+	accessMode = "readwrite";
+	/** @internal — exposed for conformance test pre-population */
+	store;
+	executor;
+	jobExecutor;
+	root;
+	options;
+	persistence;
+	constructor(options = {}) {
+		super();
+		this.name = options.name ?? "scheduler";
+		this.description = options.description ?? "Task dispatch and execution management";
+		this.options = options;
+		this.store = new TaskStore(options.maxHistory ?? 100, options.budgetBlockedTTL);
+		this.persistence = new PersistenceHelper({
+			storagePath: options.storagePath,
+			getSnapshot: () => this.store.snapshot(),
+			applySnapshot: (data, now) => this.store.restore(data, now),
+			snapshotVersion: 3,
+			validateSnapshot: (raw) => SchedulerSnapshotSchema.parse(raw)
+		});
+	}
+	onMount(root, _mountPath) {
+		this.root = root;
+		this.executor = this.options.executor ?? new LocalExecutor(() => this.root);
+		if (this.options.coordinatorNamespace) this.jobExecutor = new DOJobExecutor(this.options.coordinatorNamespace);
+		this.persistence.attachRoot(root);
+	}
+	/** Await all pending snapshot writes. Use before reading persisted state. */
+	async flush() {
+		await this.persistence.flush();
+	}
+	async read(path, options) {
+		await this.persistence.ensureReady();
+		return super.read(path, options);
+	}
+	async list(path, options) {
+		await this.persistence.ensureReady();
+		return super.list(path, options);
+	}
+	readRoot(ctx) {
+		return this.buildEntry(ctx.path, {
+			content: this.description,
+			meta: {
+				kind: "scheduler:root",
+				childrenCount: 4
+			}
+		});
+	}
+	readTasks(ctx) {
+		const tasks = this.store.listActive();
+		return this.buildEntry(ctx.path, {
+			content: `${tasks.length} active tasks`,
+			meta: {
+				kind: "scheduler:task-list",
+				childrenCount: tasks.length
+			}
+		});
+	}
+	readTask(ctx) {
+		const entry = this.store.getAny(ctx.params.id);
+		if (!entry) return void 0;
+		return this.buildEntry(ctx.path, {
+			id: entry.id,
+			content: entry,
+			meta: { kind: "scheduler:task" }
+		});
+	}
+	readTaskField(ctx) {
+		const entry = this.store.getAny(ctx.params.id);
+		if (!entry) return void 0;
+		return this.readEntryField(ctx.path, entry, ctx.params.field);
+	}
+	readHistory(ctx) {
+		const history = this.store.listHistory();
+		return this.buildEntry(ctx.path, {
+			content: `${history.length} history entries`,
+			meta: {
+				kind: "scheduler:history",
+				childrenCount: history.length
+			}
+		});
+	}
+	readHistoryTask(ctx) {
+		const entry = this.store.getFromHistory(ctx.params.id);
+		if (!entry) return void 0;
+		return this.buildEntry(ctx.path, {
+			id: entry.id,
+			content: entry,
+			meta: { kind: "scheduler:task" }
+		});
+	}
+	readHistoryTaskField(ctx) {
+		const entry = this.store.getFromHistory(ctx.params.id);
+		if (!entry) return void 0;
+		return this.readEntryField(ctx.path, entry, ctx.params.field);
+	}
+	readSchedules(ctx) {
+		const schedules = this.store.listSchedules();
+		return this.buildEntry(ctx.path, {
+			content: `${schedules.length} schedules`,
+			meta: {
+				kind: "scheduler:schedule-list",
+				childrenCount: schedules.length
+			}
+		});
+	}
+	readSchedule(ctx) {
+		const schedule = this.store.getSchedule(ctx.params.id);
+		if (!schedule) return void 0;
+		return this.buildEntry(ctx.path, {
+			id: schedule.id,
+			content: schedule,
+			meta: { kind: "scheduler:schedule" }
+		});
+	}
+	readJobs(ctx) {
+		const jobs = this.store.listJobs();
+		return this.buildEntry(ctx.path, {
+			content: `${jobs.length} jobs`,
+			meta: {
+				kind: "scheduler:job-list",
+				childrenCount: jobs.length
+			}
+		});
+	}
+	async readJob(ctx) {
+		if (this.jobExecutor) {
+			const job$1 = await this.jobExecutor.getStatus(ctx.params.id);
+			if (!job$1) return void 0;
+			return this.buildEntry(ctx.path, {
+				id: job$1.id,
+				content: job$1,
+				meta: { kind: "scheduler:job" }
+			});
+		}
+		const job = this.store.getJob(ctx.params.id);
+		if (!job) return void 0;
+		return this.buildEntry(ctx.path, {
+			id: job.id,
+			content: job,
+			meta: { kind: "scheduler:job" }
+		});
+	}
+	readCapabilities(ctx) {
+		return this.buildEntry(ctx.path, { content: { operations: this.getOperationsDeclaration() } });
+	}
+	listRoot(ctx) {
+		return { data: [
+			this.buildEntry(joinURL(ctx.path, "tasks"), { meta: {
+				kind: "scheduler:task-list",
+				childrenCount: this.store.listActive().length
+			} }),
+			this.buildEntry(joinURL(ctx.path, "history"), { meta: {
+				kind: "scheduler:history",
+				childrenCount: this.store.listHistory().length
+			} }),
+			this.buildEntry(joinURL(ctx.path, "schedules"), { meta: {
+				kind: "scheduler:schedule-list",
+				childrenCount: this.store.listSchedules().length
+			} }),
+			this.buildEntry(joinURL(ctx.path, "jobs"), { meta: {
+				kind: "scheduler:job-list",
+				childrenCount: this.store.listJobs().length
+			} })
+		] };
+	}
+	listTasks(ctx) {
+		return { data: this.store.listActive().map((t) => this.buildEntry(joinURL(ctx.path, t.id), {
+			id: t.id,
+			content: t,
+			meta: { kind: "scheduler:task" }
+		})) };
+	}
+	listHistory(ctx) {
+		return { data: this.store.listHistory().map((t) => this.buildEntry(joinURL(ctx.path, t.id), {
+			id: t.id,
+			content: t,
+			meta: { kind: "scheduler:task" }
+		})) };
+	}
+	listSchedules(ctx) {
+		return { data: this.store.listSchedules().map((s) => this.buildEntry(joinURL(ctx.path, s.id), {
+			id: s.id,
+			content: s,
+			meta: { kind: "scheduler:schedule" }
+		})) };
+	}
+	listJobsHandler(ctx) {
+		return { data: this.store.listJobs().map((j) => this.buildEntry(joinURL(ctx.path, j.id), {
+			id: j.id,
+			content: j,
+			meta: { kind: "scheduler:job" }
+		})) };
+	}
+	readRootMeta(ctx) {
+		const meta = {
+			kind: "scheduler:root",
+			childrenCount: 4
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readTasksMeta(ctx) {
+		const meta = {
+			kind: "scheduler:task-list",
+			childrenCount: this.store.listActive().length
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readHistoryMeta(ctx) {
+		const meta = {
+			kind: "scheduler:history",
+			childrenCount: this.store.listHistory().length
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readSchedulesMeta(ctx) {
+		const meta = {
+			kind: "scheduler:schedule-list",
+			childrenCount: this.store.listSchedules().length
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readJobsMeta(ctx) {
+		const meta = {
+			kind: "scheduler:job-list",
+			childrenCount: this.store.listJobs().length
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	explainRoot() {
+		return {
+			content: "Scheduler provider — dispatches tasks for background execution. Use dispatch to submit tasks, cancel to stop them, retry to re-run failed tasks. Read /tasks/{id}/status to check progress.",
+			format: "text"
+		};
+	}
+	explainPath(ctx) {
+		return {
+			content: `Scheduler path: /${ctx.params.path}`,
+			format: "text"
+		};
+	}
+	listActions(ctx) {
+		return { data: ACTION_NAMES.map((name) => this.buildEntry(joinURL(ctx.path, name), {
+			id: name,
+			meta: { kind: "afs:executable" }
+		})) };
+	}
+	async execDispatch(ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = DispatchArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		let procId;
+		if (parsed.data.proc) {
+			const procPath = this.options.procPath ?? "/proc";
+			if (!this.root.exec) return {
+				success: false,
+				error: {
+					code: "PROC_REGISTRATION_FAILED",
+					message: "AFS root does not support exec"
+				}
+			};
+			try {
+				const procData = {
+					...parsed.data.proc,
+					parentId: parsed.data.proc.parentId ?? args.parentProcId
+				};
+				const regResult = await this.root.exec(joinURL(procPath, ".actions", "register"), procData, {});
+				if (!regResult.success) return {
+					success: false,
+					error: {
+						code: "PROC_REGISTRATION_FAILED",
+						message: regResult.error?.message ?? "Failed to register proc"
+					}
+				};
+				procId = regResult.data.procId;
+			} catch (err) {
+				return {
+					success: false,
+					error: {
+						code: "PROC_REGISTRATION_FAILED",
+						message: String(err)
+					}
+				};
+			}
+		}
+		const isClaimable = parsed.data.assignee !== void 0;
+		const entry = this.store.create(parsed.data.task, parsed.data.args, procId, parsed.data.estimate, {
+			ownerKey: this.getCallerKey(ctx),
+			claimable: isClaimable,
+			assignee: parsed.data.assignee
+		});
+		this.persistence.schedulePersist();
+		if (isClaimable) return {
+			success: true,
+			data: {
+				taskId: entry.id,
+				procId,
+				claimable: true
+			}
+		};
+		const taskPromise = this.executeTask(entry.id).catch((err) => {
+			log.error("[scheduler] executeTask failed:", err);
+		});
+		this.options.waitUntil?.(taskPromise);
+		return {
+			success: true,
+			data: {
+				taskId: entry.id,
+				procId
+			}
+		};
+	}
+	async execCancel(ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = CancelArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		const { taskId } = parsed.data;
+		const entry = this.store.get(taskId);
+		if (!entry) return {
+			success: false,
+			error: {
+				code: "NOT_FOUND",
+				message: `Task ${taskId} not found`
+			}
+		};
+		const ownerError = this.checkTaskOwner(entry, ctx);
+		if (ownerError) return ownerError;
+		if (entry.status === "done" || entry.status === "failed" || entry.status === "timeout") return {
+			success: false,
+			error: {
+				code: "INVALID_STATE",
+				message: `Task ${taskId} is already ${entry.status}`
+			}
+		};
+		if (entry.status === "cancelled") return {
+			success: true,
+			data: {
+				cancelled: true,
+				alreadyCancelled: true
+			}
+		};
+		this.store.update(taskId, {
+			status: "cancelled",
+			ended: Date.now()
+		});
+		this.store.moveToHistory(taskId);
+		this.persistence.schedulePersist();
+		if (this.executor.cancel) try {
+			await this.executor.cancel(taskId);
+		} catch {}
+		if (entry.procId) await this.completeProc(entry.procId, "failed");
+		return {
+			success: true,
+			data: { cancelled: true }
+		};
+	}
+	async execRetry(ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = RetryArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		const { taskId } = parsed.data;
+		let entry = this.store.get(taskId);
+		if (entry) {
+			const ownerError = this.checkTaskOwner(entry, ctx);
+			if (ownerError) return ownerError;
+			if (entry.status === "running" || entry.status === "pending") return {
+				success: false,
+				error: {
+					code: "INVALID_STATE",
+					message: `Task ${taskId} is ${entry.status}, cannot retry`
+				}
+			};
+			if (entry.status === "done") return {
+				success: false,
+				error: {
+					code: "INVALID_STATE",
+					message: `Task ${taskId} is done, cannot retry`
+				}
+			};
+		} else {
+			entry = this.store.restoreFromHistory(taskId);
+			if (!entry) return {
+				success: false,
+				error: {
+					code: "NOT_FOUND",
+					message: `Task ${taskId} not found`
+				}
+			};
+			const ownerError = this.checkTaskOwner(entry, ctx);
+			if (ownerError) {
+				this.store.moveToHistory(taskId);
+				return ownerError;
+			}
+			if (entry.status === "done") {
+				this.store.moveToHistory(taskId);
+				return {
+					success: false,
+					error: {
+						code: "INVALID_STATE",
+						message: `Task ${taskId} is done, cannot retry`
+					}
+				};
+			}
+		}
+		this.store.update(taskId, {
+			status: "pending",
+			result: void 0,
+			error: void 0,
+			started: void 0,
+			ended: void 0
+		});
+		this.persistence.schedulePersist();
+		const retryPromise = this.executeTask(taskId).catch((err) => {
+			log.error("[scheduler] executeTask failed:", err);
+		});
+		this.options.waitUntil?.(retryPromise);
+		return {
+			success: true,
+			data: { taskId }
+		};
+	}
+	async execSchedule(ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = ScheduleArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		try {
+			const schedule = this.store.addSchedule({
+				name: parsed.data.name,
+				cron: parsed.data.cron,
+				taskPath: parsed.data.task,
+				args: parsed.data.args,
+				enabled: parsed.data.enabled,
+				ownerKey: this.getCallerKey(ctx)
+			});
+			this.persistence.schedulePersist();
+			return {
+				success: true,
+				data: { scheduleId: schedule.id }
+			};
+		} catch (err) {
+			return {
+				success: false,
+				error: {
+					code: "SCHEDULE_ERROR",
+					message: err instanceof Error ? err.message : String(err)
+				}
+			};
+		}
+	}
+	async execUnschedule(ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = UnscheduleArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		let removed = false;
+		let scheduleOwnerError;
+		if (parsed.data.scheduleId) {
+			const schedule = this.store.getSchedule(parsed.data.scheduleId);
+			scheduleOwnerError = schedule ? this.checkScheduleOwner(schedule, ctx) : void 0;
+			if (!scheduleOwnerError) removed = this.store.removeSchedule(parsed.data.scheduleId);
+		} else if (parsed.data.name) {
+			const schedule = this.store.getScheduleByName(parsed.data.name);
+			if (schedule) {
+				scheduleOwnerError = this.checkScheduleOwner(schedule, ctx);
+				if (!scheduleOwnerError) removed = this.store.removeSchedule(schedule.id);
+			}
+		}
+		if (scheduleOwnerError) return scheduleOwnerError;
+		if (!removed) return {
+			success: false,
+			error: {
+				code: "NOT_FOUND",
+				message: "Schedule not found"
+			}
+		};
+		this.persistence.schedulePersist();
+		return { success: true };
+	}
+	async execHeartbeat(_ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = HeartbeatArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		const { taskId } = parsed.data;
+		const entry = this.store.get(taskId);
+		if (!entry) return {
+			success: false,
+			error: {
+				code: "NOT_FOUND",
+				message: `Task ${taskId} not found`
+			}
+		};
+		if (entry.status !== "running") return {
+			success: false,
+			error: {
+				code: "INVALID_STATE",
+				message: `Task ${taskId} is ${entry.status}, not running`
+			}
+		};
+		if (!entry.timeout || !entry.deadline) return {
+			success: false,
+			error: {
+				code: "NO_TIMEOUT",
+				message: `Task ${taskId} has no timeout configured`
+			}
+		};
+		const now = Date.now();
+		this.store.update(taskId, {
+			lastHeartbeat: now,
+			deadline: now + entry.timeout
+		});
+		this.persistence.schedulePersist();
+		return { success: true };
+	}
+	async execClaim(_ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = ClaimArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		const { taskId, workerId, leaseDuration, ifMatch } = parsed.data;
+		const entry = this.store.get(taskId);
+		if (!entry) return {
+			success: false,
+			error: {
+				code: "NOT_FOUND",
+				message: `Task ${taskId} not found`
+			}
+		};
+		if (!entry.claimable) return {
+			success: false,
+			error: {
+				code: "NOT_CLAIMABLE",
+				message: `Task ${taskId} was not dispatched for claiming (missing assignee field)`
+			}
+		};
+		if (entry.assignee && entry.assignee !== workerId) return {
+			success: false,
+			error: {
+				code: "PERMISSION_DENIED",
+				message: `Task ${taskId} is reserved for a different assignee`
+			}
+		};
+		const now = Date.now();
+		if (ifMatch !== void 0 && ifMatch !== entry.version) throw new AFSConflictError(joinURL("/tasks", taskId), { cid: entry.version ?? null });
+		const leaseExpired = entry.claimedBy !== void 0 && entry.deadline !== void 0 && entry.deadline < now;
+		if (entry.claimedBy !== void 0 && entry.claimedBy !== workerId && !leaseExpired) return {
+			success: false,
+			error: {
+				code: "ALREADY_CLAIMED",
+				message: `Task ${taskId} is already claimed by another worker`
+			}
+		};
+		if (entry.status !== "pending" && !(entry.status === "running" && leaseExpired)) return {
+			success: false,
+			error: {
+				code: "INVALID_STATE",
+				message: `Task ${taskId} is ${entry.status}, cannot claim`
+			}
+		};
+		const lease = leaseDuration ?? this.options.defaultLeaseDuration ?? DEFAULT_LEASE_DURATION_MS;
+		const newVersion = v7();
+		this.store.update(taskId, {
+			status: "running",
+			claimedBy: workerId,
+			claimedAt: now,
+			started: entry.started ?? now,
+			attempts: entry.attempts + 1,
+			lastHeartbeat: now,
+			deadline: now + lease,
+			timeout: lease,
+			version: newVersion
+		});
+		this.persistence.schedulePersist();
+		return {
+			success: true,
+			data: {
+				taskId,
+				claimedBy: workerId,
+				leaseDeadline: now + lease,
+				version: newVersion
+			}
+		};
+	}
+	async execSubmit(ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = SubmitArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		const { taskId, workerId, success, result, artifacts, verifyArgs } = parsed.data;
+		const verifyTaskPath = parsed.data.verifyTask ?? this.options.verifyTaskPath;
+		if (!verifyTaskPath) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: "verifyTask is required (no verifyTaskPath configured on the scheduler provider)"
+			}
+		};
+		const entry = this.store.get(taskId);
+		if (!entry) return {
+			success: false,
+			error: {
+				code: "NOT_FOUND",
+				message: `Task ${taskId} not found`
+			}
+		};
+		if (!entry.claimable) return {
+			success: false,
+			error: {
+				code: "NOT_CLAIMABLE",
+				message: `Task ${taskId} is not a claim-based task`
+			}
+		};
+		if (entry.claimedBy !== workerId) return {
+			success: false,
+			error: {
+				code: "PERMISSION_DENIED",
+				message: `Task ${taskId} is not claimed by ${workerId}`
+			}
+		};
+		if (entry.status !== "running") return {
+			success: false,
+			error: {
+				code: "INVALID_STATE",
+				message: `Task ${taskId} is ${entry.status}, cannot submit`
+			}
+		};
+		const finalStatus = success === false ? "failed" : "done";
+		const now = Date.now();
+		this.store.update(taskId, {
+			status: finalStatus,
+			result: {
+				success: success !== false,
+				data: result
+			},
+			ended: now,
+			version: v7()
+		});
+		this.store.moveToHistory(taskId);
+		if (entry.procId) await this.completeProc(entry.procId, finalStatus === "done" ? "done" : "failed");
+		const verifyTaskId = this.store.create(verifyTaskPath, {
+			...typeof verifyArgs === "object" && verifyArgs !== null ? verifyArgs : {},
+			originalTaskId: taskId,
+			workerId,
+			result,
+			artifacts
+		}, void 0, void 0, { ownerKey: this.getCallerKey(ctx) }).id;
+		const verifyPromise = this.executeTask(verifyTaskId).catch((err) => {
+			log.error("[scheduler] executeTask failed:", err);
+		});
+		this.options.waitUntil?.(verifyPromise);
+		this.persistence.schedulePersist();
+		return {
+			success: true,
+			data: {
+				taskId,
+				status: finalStatus,
+				verifyTaskId
+			}
+		};
+	}
+	async execSubmitJob(_ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = SubmitJobArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		const batchSize = parsed.data.batchSize ?? 100;
+		const concurrency = parsed.data.concurrency ?? 10;
+		const jobId = v7();
+		if (this.jobExecutor) try {
+			return {
+				success: true,
+				data: { jobId: (await this.jobExecutor.submitJob({
+					jobId,
+					name: parsed.data.name,
+					mapTask: parsed.data.mapTask,
+					reduceTask: parsed.data.reduceTask,
+					totalItems: parsed.data.totalItems,
+					batchSize,
+					concurrency,
+					args: parsed.data.args,
+					timeout: parsed.data.timeout
+				})).jobId }
+			};
+		} catch (err) {
+			return {
+				success: false,
+				error: {
+					code: "COORDINATOR_ERROR",
+					message: String(err)
+				}
+			};
+		}
+		const totalBatches = Math.ceil(parsed.data.totalItems / batchSize);
+		const job = {
+			id: jobId,
+			name: parsed.data.name,
+			status: "mapping",
+			mapTask: parsed.data.mapTask,
+			reduceTask: parsed.data.reduceTask,
+			args: parsed.data.args,
+			totalItems: parsed.data.totalItems,
+			batchSize,
+			concurrency,
+			timeout: parsed.data.timeout,
+			totalBatches,
+			progress: {
+				pending: totalBatches,
+				running: 0,
+				done: 0,
+				failed: 0
+			},
+			mapTaskIds: new Array(totalBatches).fill(""),
+			mapResults: new Array(totalBatches).fill(null),
+			created: Date.now(),
+			started: Date.now()
+		};
+		this.store.addJob(job);
+		this.persistence.schedulePersist();
+		const firstWave = Math.min(concurrency, totalBatches);
+		for (let i = 0; i < firstWave; i++) this.dispatchMapTask(job, i);
+		return {
+			success: true,
+			data: { jobId: job.id }
+		};
+	}
+	async execCancelJob(_ctx, args) {
+		await this.persistence.ensureReady();
+		const parsed = CancelJobArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: parsed.error.message
+			}
+		};
+		if (this.jobExecutor) try {
+			await this.jobExecutor.cancelJob(parsed.data.jobId);
+			return { success: true };
+		} catch (err) {
+			return {
+				success: false,
+				error: {
+					code: "COORDINATOR_ERROR",
+					message: String(err)
+				}
+			};
+		}
+		const job = this.store.getJob(parsed.data.jobId);
+		if (!job) return {
+			success: false,
+			error: {
+				code: "NOT_FOUND",
+				message: `Job ${parsed.data.jobId} not found`
+			}
+		};
+		let cancelledTasks = 0;
+		for (const task of this.store.listActive()) if (task.jobId === job.id && (task.status === "pending" || task.status === "running")) {
+			this.store.update(task.id, {
+				status: "cancelled",
+				ended: Date.now()
+			});
+			this.store.moveToHistory(task.id);
+			cancelledTasks++;
+		}
+		this.store.updateJob(job.id, {
+			status: "cancelled",
+			ended: Date.now()
+		});
+		this.persistence.schedulePersist();
+		return {
+			success: true,
+			data: { cancelledTasks }
+		};
+	}
+	/**
+	* Evaluate cron schedules and scan for expired deadlines.
+	* Call from Worker `scheduled()` handler or `setInterval` in non-Worker environments.
+	*/
+	async tick() {
+		await this.persistence.ensureReady();
+		const now = Date.now();
+		let dispatched = 0;
+		let timedOut = 0;
+		let scheduleAdvanced = false;
+		for (const task of this.store.listActive()) {
+			const isScheduledTask = Boolean(task.scheduleId);
+			if (task.status !== "running" && !(isScheduledTask && task.status === "pending")) continue;
+			if (task.claimable) continue;
+			const deadline = this.getEffectiveDeadline(task);
+			if (deadline == null) continue;
+			if (deadline > now) continue;
+			this.store.update(task.id, {
+				status: "timeout",
+				error: `Task timed out (deadline exceeded by ${now - deadline}ms)`,
+				ended: now
+			});
+			if (task.procId) await this.completeProc(task.procId, "failed");
+			this.store.moveToHistory(task.id);
+			timedOut++;
+		}
+		for (const schedule of this.store.listSchedules()) {
+			if (!schedule.enabled) continue;
+			if (!schedule.nextRun || schedule.nextRun > now) continue;
+			if (this.store.listActive().some((t) => t.scheduleId === schedule.id && (t.status === "pending" || t.status === "running"))) {
+				this.store.recordScheduleRun(schedule.id, now);
+				scheduleAdvanced = true;
+				continue;
+			}
+			const entry = this.store.create(schedule.taskPath, schedule.args, void 0, void 0, {
+				ownerKey: schedule.ownerKey,
+				scheduleId: schedule.id
+			});
+			const scheduledTaskTimeoutMs = this.getScheduledTaskTimeoutMs();
+			if (scheduledTaskTimeoutMs > 0) this.store.update(entry.id, {
+				deadline: now + scheduledTaskTimeoutMs,
+				timeout: scheduledTaskTimeoutMs
+			});
+			this.store.recordScheduleRun(schedule.id, now);
+			const taskPromise = this.executeTask(entry.id).catch((err) => {
+				log.error("[scheduler] executeTask failed:", err);
+			});
+			this.options.waitUntil?.(taskPromise);
+			dispatched++;
+		}
+		if (dispatched > 0 || timedOut > 0 || scheduleAdvanced) this.persistence.schedulePersist();
+		return {
+			dispatched,
+			timedOut
+		};
+	}
+	getScheduledTaskTimeoutMs() {
+		return this.options.scheduledTaskTimeoutMs ?? DEFAULT_SCHEDULED_TASK_TIMEOUT_MS;
+	}
+	getEffectiveDeadline(task) {
+		if (task.deadline != null) return task.deadline;
+		if (!task.scheduleId) return void 0;
+		const scheduledTaskTimeoutMs = this.getScheduledTaskTimeoutMs();
+		if (scheduledTaskTimeoutMs <= 0) return void 0;
+		return (task.started ?? task.created) + scheduledTaskTimeoutMs;
+	}
+	getCallerKey(ctx) {
+		const context = ctx.context;
+		const userId = typeof context?.userId === "string" ? context.userId : void 0;
+		const sessionId = typeof context?.sessionId === "string" ? context.sessionId : void 0;
+		return userId ?? sessionId;
+	}
+	checkTaskOwner(entry, ctx) {
+		if (!entry.ownerKey) return void 0;
+		if (entry.ownerKey === this.getCallerKey(ctx)) return void 0;
+		return {
+			success: false,
+			error: {
+				code: "PERMISSION_DENIED",
+				message: `Task ${entry.id} is owned by a different caller`
+			}
+		};
+	}
+	checkScheduleOwner(schedule, ctx) {
+		if (!schedule.ownerKey) return void 0;
+		if (schedule.ownerKey === this.getCallerKey(ctx)) return void 0;
+		return {
+			success: false,
+			error: {
+				code: "PERMISSION_DENIED",
+				message: `Schedule ${schedule.id} is owned by a different caller`
+			}
+		};
+	}
+	async executeTask(taskId) {
+		const entry = this.store.get(taskId);
+		if (!entry) return;
+		if (entry.procId) {
+			const budgetCheck = await this.checkTaskBudget(entry.procId, entry.estimate);
+			if (!budgetCheck.allowed) {
+				this.store.update(taskId, {
+					status: "budget-blocked",
+					error: `Budget check failed: ${budgetCheck.reason}`
+				});
+				this.persistence.schedulePersist();
+				await this.persistence.flush();
+				return;
+			}
+		}
+		this.store.update(taskId, {
+			status: "running",
+			started: Date.now(),
+			attempts: entry.attempts + 1
+		});
+		this.persistence.schedulePersist();
+		const context = entry.procId ? { procId: entry.procId } : void 0;
+		let taskArgs = entry.args;
+		if (taskArgs && typeof taskArgs === "object" && !Array.isArray(taskArgs)) {
+			const a = taskArgs;
+			if (!a.job_dir) taskArgs = {
+				...a,
+				job_dir: `/data/jobs/${taskId}`
+			};
+		}
+		try {
+			const result = await this.executor.run(taskId, entry.taskPath, taskArgs, context);
+			const current = this.store.get(taskId);
+			if (!current || current.status !== "running") return;
+			this.store.update(taskId, {
+				status: "done",
+				result,
+				ended: Date.now()
+			});
+		} catch (err) {
+			const current = this.store.get(taskId);
+			if (!current || current.status !== "running") return;
+			this.store.update(taskId, {
+				status: "failed",
+				error: String(err),
+				ended: Date.now()
+			});
+		}
+		const finalEntry = this.store.get(taskId);
+		if (finalEntry?.procId) await this.completeProc(finalEntry.procId, finalEntry.status === "done" ? "done" : "failed");
+		this.store.moveToHistory(taskId);
+		const completedEntry = this.store.getFromHistory(taskId);
+		if (completedEntry?.jobId) await this.onJobTaskComplete(completedEntry);
+		this.persistence.schedulePersist();
+		await this.persistence.flush();
+	}
+	async checkTaskBudget(procId, estimate) {
+		const procPath = this.options.procPath ?? "/proc";
+		try {
+			if (!this.root.exec) return {
+				allowed: false,
+				reason: "AFS root does not support exec"
+			};
+			const args = { id: procId };
+			if (estimate) args.estimate = estimate;
+			const result = await this.root.exec(joinURL(procPath, ".actions", "check-budget"), args, {});
+			if (!result.success) return {
+				allowed: false,
+				reason: result.error?.message ?? "Budget check failed"
+			};
+			const data = result.data;
+			return {
+				allowed: data.allowed,
+				reason: data.reason
+			};
+		} catch (err) {
+			return {
+				allowed: false,
+				reason: `Budget check error: ${String(err)}`
+			};
+		}
+	}
+	async completeProc(procId, status) {
+		const procPath = this.options.procPath ?? "/proc";
+		try {
+			if (this.root.exec) await this.root.exec(joinURL(procPath, ".actions", "complete"), {
+				id: procId,
+				status
+			}, {});
+		} catch {}
+	}
+	dispatchMapTask(job, batchIndex) {
+		const batchStart = batchIndex * job.batchSize;
+		const batchEnd = Math.min(batchStart + job.batchSize, job.totalItems);
+		const taskArgs = {
+			...job.args ?? {},
+			jobId: job.id,
+			batchIndex,
+			batchSize: job.batchSize,
+			batchStart,
+			batchEnd,
+			totalItems: job.totalItems
+		};
+		const entry = this.store.create(job.mapTask, taskArgs, void 0, void 0, {
+			jobId: job.id,
+			batchIndex
+		});
+		job.mapTaskIds[batchIndex] = entry.id;
+		job.progress.pending--;
+		job.progress.running++;
+		const taskPromise = this.executeTask(entry.id).catch((err) => {
+			log.error("[scheduler] executeTask failed:", err);
+		});
+		this.options.waitUntil?.(taskPromise);
+	}
+	async onJobTaskComplete(task) {
+		const job = this.store.getJob(task.jobId);
+		if (!job || job.status === "cancelled") return;
+		if (job.reduceTaskId === task.id) {
+			if (task.status === "done" && task.result) this.store.updateJob(job.id, {
+				status: "done",
+				result: task.result.data,
+				ended: Date.now()
+			});
+			else this.store.updateJob(job.id, {
+				status: "failed",
+				error: task.error ?? "Reduce task failed",
+				ended: Date.now()
+			});
+			this.persistence.schedulePersist();
+			return;
+		}
+		const batchIndex = task.batchIndex;
+		const taskSucceeded = task.status === "done" && task.result?.success !== false;
+		if (taskSucceeded && task.result) job.mapResults[batchIndex] = task.result.data;
+		else job.mapResults[batchIndex] = null;
+		job.progress.running = Math.max(0, job.progress.running - 1);
+		if (taskSucceeded) job.progress.done++;
+		else job.progress.failed++;
+		const nextBatch = this.store.nextPendingBatch(job.id);
+		if (nextBatch >= 0) this.dispatchMapTask(job, nextBatch);
+		if (job.progress.done + job.progress.failed === job.totalBatches) if (job.reduceTask) {
+			job.status = "reducing";
+			const reduceArgs = {
+				...job.args ?? {},
+				jobId: job.id,
+				mapResults: job.mapResults,
+				totalBatches: job.totalBatches
+			};
+			const reduceEntry = this.store.create(job.reduceTask, reduceArgs, void 0, void 0, { jobId: job.id });
+			job.reduceTaskId = reduceEntry.id;
+			const reducePromise = this.executeTask(reduceEntry.id).catch((err) => {
+				log.error("[scheduler] executeTask failed:", err);
+			});
+			this.options.waitUntil?.(reducePromise);
+		} else this.store.updateJob(job.id, {
+			status: "done",
+			result: job.mapResults,
+			ended: Date.now()
+		});
+		this.persistence.schedulePersist();
+	}
+	readEntryField(path, entry, field) {
+		let content;
+		switch (field) {
+			case "status":
+				content = entry.status;
+				break;
+			case "result":
+				content = entry.result ?? null;
+				break;
+			case "error":
+				content = entry.error ?? null;
+				break;
+			case "task":
+				content = {
+					taskPath: entry.taskPath,
+					args: entry.args
+				};
+				break;
+			case "created":
+				content = entry.created;
+				break;
+			case "started":
+				content = entry.started ?? null;
+				break;
+			case "ended":
+				content = entry.ended ?? null;
+				break;
+			case "attempts":
+				content = entry.attempts;
+				break;
+			default: return;
+		}
+		return this.buildEntry(path, {
+			content,
+			meta: { kind: `scheduler:task:${field}` }
+		});
+	}
+};
+__decorate([Read("/")], AFSScheduler.prototype, "readRoot", null);
+__decorate([Read("/tasks")], AFSScheduler.prototype, "readTasks", null);
+__decorate([Read("/tasks/:id")], AFSScheduler.prototype, "readTask", null);
+__decorate([Read("/tasks/:id/:field")], AFSScheduler.prototype, "readTaskField", null);
+__decorate([Read("/history")], AFSScheduler.prototype, "readHistory", null);
+__decorate([Read("/history/:id")], AFSScheduler.prototype, "readHistoryTask", null);
+__decorate([Read("/history/:id/:field")], AFSScheduler.prototype, "readHistoryTaskField", null);
+__decorate([Read("/schedules")], AFSScheduler.prototype, "readSchedules", null);
+__decorate([Read("/schedules/:id")], AFSScheduler.prototype, "readSchedule", null);
+__decorate([Read("/jobs")], AFSScheduler.prototype, "readJobs", null);
+__decorate([Read("/jobs/:id")], AFSScheduler.prototype, "readJob", null);
+__decorate([Read("/.meta/.capabilities")], AFSScheduler.prototype, "readCapabilities", null);
+__decorate([List("/")], AFSScheduler.prototype, "listRoot", null);
+__decorate([List("/tasks")], AFSScheduler.prototype, "listTasks", null);
+__decorate([List("/history")], AFSScheduler.prototype, "listHistory", null);
+__decorate([List("/schedules")], AFSScheduler.prototype, "listSchedules", null);
+__decorate([List("/jobs")], AFSScheduler.prototype, "listJobsHandler", null);
+__decorate([Meta("/")], AFSScheduler.prototype, "readRootMeta", null);
+__decorate([Meta("/tasks")], AFSScheduler.prototype, "readTasksMeta", null);
+__decorate([Meta("/history")], AFSScheduler.prototype, "readHistoryMeta", null);
+__decorate([Meta("/schedules")], AFSScheduler.prototype, "readSchedulesMeta", null);
+__decorate([Meta("/jobs")], AFSScheduler.prototype, "readJobsMeta", null);
+__decorate([Explain("/")], AFSScheduler.prototype, "explainRoot", null);
+__decorate([Explain("/:path+")], AFSScheduler.prototype, "explainPath", null);
+__decorate([Actions("/")], AFSScheduler.prototype, "listActions", null);
+__decorate([Actions.Exec("/", "dispatch", "Submit a task for execution", { effect: "write" })], AFSScheduler.prototype, "execDispatch", null);
+__decorate([Actions.Exec("/", "cancel", "Cancel a running task", { effect: "write" })], AFSScheduler.prototype, "execCancel", null);
+__decorate([Actions.Exec("/", "retry", "Retry a failed task", { effect: "write" })], AFSScheduler.prototype, "execRetry", null);
+__decorate([Actions.Exec("/", "schedule", "Create a cron schedule", { effect: "write" })], AFSScheduler.prototype, "execSchedule", null);
+__decorate([Actions.Exec("/", "unschedule", "Remove a cron schedule", { effect: "write" })], AFSScheduler.prototype, "execUnschedule", null);
+__decorate([Actions.Exec("/", "heartbeat", "Send heartbeat for a running task", { effect: "write" })], AFSScheduler.prototype, "execHeartbeat", null);
+__decorate([Actions.Exec("/", "claim", "Atomically claim an unclaimed (or lease-expired) task for external worker execution", { effect: "write" })], AFSScheduler.prototype, "execClaim", null);
+__decorate([Actions.Exec("/", "submit", "Submit worker completion + artifacts for a claimed task, enqueuing a verification task", { effect: "write" })], AFSScheduler.prototype, "execSubmit", null);
+__decorate([Actions.Exec("/", "submit-job", "Submit a map-reduce job", { effect: "write" })], AFSScheduler.prototype, "execSubmitJob", null);
+__decorate([Actions.Exec("/", "cancel-job", "Cancel a map-reduce job", { effect: "write" })], AFSScheduler.prototype, "execCancelJob", null);
+
+//#endregion
+export { AFSScheduler };
+//# sourceMappingURL=scheduler-provider.mjs.map