@ayepi/work 0.1.0

package/dist/index.js

@@ -0,0 +1,1920 @@
+import { ageDoer, balancedDoer, priorityDoer, unlimitedDoer, unlimitedDoer as unlimitedDoer$1 } from "@ayepi/core/doer";
+import { DEFAULT_RETRY_OPTIONS, RetryAbort, RetryAbort as RetryAbort$1, backoff, backoff as backoff$1, getDefaultRetryOptions, getDefaultRetryOptions as getDefaultRetryOptions$1, retry, retry as retry$1, setDefaultRetryOptions } from "@ayepi/core/retry";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { DEFAULT_BUCKETS, createMetrics, createMetrics as createMetrics$1, formatPrometheus } from "@ayepi/core/stats";
+//#region src/json.ts
+/** Wrapper key marking a tagged value (`{ [TAG]: 'Date', value: … }`). */
+const TAG = "$ayepi";
+const isTagged = (v) => v !== null && typeof v === "object" && TAG in v;
+/**
+* The default {@link JsonCodec}. Tags values JSON can't represent natively so they
+* survive a `stringify` → `parse` round-trip:
+*
+* | Value       | Encoded as                          |
+* |-------------|-------------------------------------|
+* | `undefined` | `{ $ayepi:'undefined' }`            |
+* | `bigint`    | `{ $ayepi:'BigInt', value:'123' }`  |
+* | `Date`      | `{ $ayepi:'Date', value:<iso> }`    |
+* | `Map`       | `{ $ayepi:'Map', value:[[k,v]…] }`  |
+* | `Set`       | `{ $ayepi:'Set', value:[…] }`       |
+* | `Error`     | `{ $ayepi:'Error', value:{name,message,stack} }` |
+*/
+const defaultCodec = {
+	stringify(value) {
+		return JSON.stringify(value, function(key, encoded) {
+			const raw = this[key];
+			if (raw === void 0) return { [TAG]: "undefined" };
+			if (typeof raw === "bigint") return {
+				[TAG]: "BigInt",
+				value: raw.toString()
+			};
+			if (raw instanceof Date) return {
+				[TAG]: "Date",
+				value: raw.toISOString()
+			};
+			if (raw instanceof Map) return {
+				[TAG]: "Map",
+				value: [...raw.entries()]
+			};
+			if (raw instanceof Set) return {
+				[TAG]: "Set",
+				value: [...raw.values()]
+			};
+			if (raw instanceof Error) return {
+				[TAG]: "Error",
+				value: {
+					name: raw.name,
+					message: raw.message,
+					stack: raw.stack
+				}
+			};
+			return encoded;
+		});
+	},
+	parse(text) {
+		return JSON.parse(text, (_key, value) => {
+			if (!isTagged(value)) return value;
+			switch (value[TAG]) {
+				case "undefined": return;
+				case "BigInt": return BigInt(value.value);
+				case "Date": return new Date(value.value);
+				case "Map": return new Map(value.value);
+				case "Set": return new Set(value.value);
+				case "Error": {
+					const e = value.value;
+					const err = new Error(e.message);
+					err.name = e.name;
+					if (e.stack) err.stack = e.stack;
+					return err;
+				}
+				default: return value;
+			}
+		});
+	}
+};
+//#endregion
+//#region src/internal.ts
+/**
+* # Internals
+*
+* Dependency-free helpers shared across the engine: id generation, the
+* backoff-with-jitter formula, an async sleep, a shallow merge, and the identity
+* `logWith` (so `@ayepi/log` is injected, never imported).
+*
+* @module
+*/
+/** A v4 UUID. Thin wrapper over `node:crypto` so callers don't import it directly. */
+const uuid = () => randomUUID();
+/** Resolve after `ms` (an unref'd timer, so it never keeps the process alive). */
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms).unref?.();
+	});
+}
+/** Shallow merge of two objects into a new object (`b` wins on collisions). */
+function merge(a, b) {
+	return {
+		...a ?? {},
+		...b ?? {}
+	};
+}
+/** The default {@link LogWith}: runs `inner` with no added context. */
+const identityLogWith = (_add, inner) => inner();
+//#endregion
+//#region src/memory.ts
+/**
+* # In-memory backend
+*
+* A zero-dependency implementation of all three {@link Backend} ports that
+* **simulates the distributed protocol** — visibility-timeout leases with
+* heartbeat-driven redelivery, TTL'd store with an atomic `setIfNotExists`, and
+* in-process fanout. Share one backend between several `createWork` instances to model
+* a multi-pod deployment in tests, and inject `now` to drive time deterministically.
+*
+* The {@link memoryQueue} can additionally be **file-backed** (`file: './work-queue.json'`)
+* so pending work survives a process restart — single-process durability without standing up
+* Redis/SQS. State is written atomically (temp file + rename) after every mutation; on startup
+* the file is reloaded and any in-flight (leased) item is redelivered, since the worker that
+* held its lease is gone.
+*
+* @module
+*/
+/** The default {@link QueueFsLike}, backed by synchronous `node:fs`. */
+const nodeQueueFs = {
+	readFile: (p) => existsSync(p) ? readFileSync(p, "utf8") : void 0,
+	writeFile: (p, d) => writeFileSync(p, d),
+	rename: (a, b) => renameSync(a, b),
+	mkdir: (p) => void mkdirSync(p, { recursive: true })
+};
+/**
+* In-process {@link PubSub} (the `localBroker` shape). Share one instance across
+* engines to fan a publish out to every "pod".
+*/
+function memoryPubSub() {
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		publish(m) {
+			for (const l of [...listeners]) l(m);
+		},
+		subscribe(l) {
+			listeners.add(l);
+			return () => void listeners.delete(l);
+		}
+	};
+}
+/**
+* In-memory {@link Store} with lazy TTL expiry and an atomic {@link Store.setIfNotExists}.
+* The compare-and-set every distributed claim relies on.
+*/
+function memoryStore(opts = {}) {
+	const now = opts.now ?? Date.now;
+	const map = /* @__PURE__ */ new Map();
+	const live = (key) => {
+		const e = map.get(key);
+		if (!e) return;
+		if (e.expires !== void 0 && e.expires <= now()) {
+			map.delete(key);
+			return;
+		}
+		return e;
+	};
+	return {
+		get: (key) => live(key)?.value,
+		set: (key, value, ttl) => void map.set(key, {
+			value,
+			expires: ttl ? now() + ttl : void 0
+		}),
+		delete: (key) => void map.delete(key),
+		setIfNotExists: (key, value, ttl) => {
+			if (live(key)) return false;
+			map.set(key, {
+				value,
+				expires: ttl ? now() + ttl : void 0
+			});
+			return true;
+		},
+		increment: (key, by, ttl) => {
+			const cur = Number(live(key)?.value ?? "0") + by;
+			map.set(key, {
+				value: String(cur),
+				expires: ttl ? now() + ttl : void 0
+			});
+			return cur;
+		}
+	};
+}
+/**
+* In-memory {@link Queue} with visibility-timeout leasing. `pop` first **reclaims**
+* items whose lease expired (a dead worker → redelivery, `attempt++`), then leases
+* fresh visible items. `ack`/`heartbeat`/`fail` are token-gated, so a stale worker
+* whose lease already lapsed cannot ack work another worker now owns.
+*
+* Pass `file` to make it **durable**: state is reloaded on construction and rewritten
+* atomically after every mutation. A heartbeat is *not* persisted (lease expiry is
+* reset on reload anyway), so steady-state heartbeating doesn't touch the disk.
+*/
+function memoryQueue(opts = {}) {
+	const now = opts.now ?? Date.now;
+	const items = [];
+	const dead = [];
+	const find = (token) => items.find((i) => i.leaseToken === token);
+	const file = opts.file;
+	const fs = opts.fs ?? nodeQueueFs;
+	const tmpFile = file !== void 0 ? `${file}.tmp` : "";
+	let dirEnsured = false;
+	const report = (err) => {
+		try {
+			opts.onError?.(err);
+		} catch {}
+	};
+	const persist = () => {
+		if (file === void 0) return;
+		try {
+			if (!dirEnsured) {
+				const dir = dirname(file);
+				if (dir !== ".") fs.mkdir(dir);
+				dirEnsured = true;
+			}
+			fs.writeFile(tmpFile, JSON.stringify({
+				items,
+				dead
+			}));
+			fs.rename(tmpFile, file);
+		} catch (err) {
+			report(err);
+		}
+	};
+	const load = () => {
+		if (file === void 0) return;
+		let raw;
+		try {
+			raw = fs.readFile(file);
+		} catch (err) {
+			report(err);
+			return;
+		}
+		if (raw === void 0) return;
+		try {
+			const parsed = JSON.parse(raw);
+			for (const i of parsed.items ?? []) {
+				if (i.leaseToken !== void 0) {
+					i.leaseToken = void 0;
+					i.leaseUntil = void 0;
+					i.attempt += 1;
+					i.visibleAt = now();
+				}
+				items.push(i);
+			}
+			for (const d of parsed.dead ?? []) dead.push(d);
+		} catch (err) {
+			report(err);
+		}
+	};
+	load();
+	return {
+		dead,
+		size: () => items.length,
+		push(body, o) {
+			if (o?.dedupeKey && items.some((i) => i.dedupeKey === o.dedupeKey)) return;
+			items.push({
+				body,
+				visibleAt: now() + (o?.delay ?? 0),
+				attempt: 0,
+				dedupeKey: o?.dedupeKey
+			});
+			persist();
+		},
+		pop(max, visibility) {
+			const t = now();
+			let changed = false;
+			for (const i of items) if (i.leaseToken && i.leaseUntil !== void 0 && i.leaseUntil <= t) {
+				i.leaseToken = void 0;
+				i.leaseUntil = void 0;
+				i.attempt += 1;
+				changed = true;
+			}
+			const out = [];
+			for (const i of items) {
+				if (out.length >= max) break;
+				if (i.leaseToken || i.visibleAt > t) continue;
+				const token = uuid();
+				i.leaseToken = token;
+				i.leaseUntil = t + visibility;
+				out.push({
+					body: i.body,
+					handle: token,
+					attempt: i.attempt + 1
+				});
+				changed = true;
+			}
+			if (changed) persist();
+			return out;
+		},
+		heartbeat(p, visibility) {
+			const i = find(p.handle);
+			if (i) i.leaseUntil = now() + visibility;
+		},
+		ack(p) {
+			const idx = items.findIndex((i) => i.leaseToken === p.handle);
+			if (idx >= 0) {
+				items.splice(idx, 1);
+				persist();
+			}
+		},
+		fail(p, delay) {
+			const i = find(p.handle);
+			if (!i) return;
+			i.leaseToken = void 0;
+			i.leaseUntil = void 0;
+			i.attempt = p.attempt;
+			i.visibleAt = now() + (delay ?? 0);
+			persist();
+		},
+		deadLetter(body, error) {
+			dead.push({
+				body,
+				error
+			});
+			persist();
+		}
+	};
+}
+/**
+* The three in-memory ports together, sharing one clock. The default backend when
+* `createWork()` is called with no ports.
+*
+* @example A two-pod test on one shared backend:
+* ```ts
+* const backend = memoryBackend()
+* const podA = createWork({ ...backend, work: [add] })
+* const podB = createWork({ ...backend, work: [add] })
+* ```
+*
+* @example A single durable process — pending work survives a restart:
+* ```ts
+* const backend = memoryBackend({ queue: { file: './work-queue.json' } })
+* const work = createWork({ ...backend, work: [add] })
+* ```
+*/
+function memoryBackend(opts = {}) {
+	return {
+		queue: memoryQueue({
+			now: opts.now,
+			...opts.queue
+		}),
+		pubsub: memoryPubSub(),
+		store: memoryStore(opts)
+	};
+}
+//#endregion
+//#region src/errors.ts
+/**
+* Throw from a work handler to **defer** the item to a future time (a reschedule, not a failure).
+*
+* ```ts
+* defineWork('poll', async (input, ctx) => {
+*   if (!(await upstreamReady())) throw new WorkDelayError({ delay: 5 * 60_000 }); // retry in 5 min, attempt unchanged
+*   return doWork(input);
+* });
+* ```
+*/
+var WorkDelayError = class extends Error {
+	when;
+	constructor(when, message = "work deferred") {
+		super(message);
+		this.when = when;
+		this.name = "WorkDelayError";
+	}
+};
+//#endregion
+//#region src/dependency.ts
+/**
+* # Dependencies
+*
+* A dependency is **itself a work item** ({@link DEPENDENCY_TYPE}) — so it lives on the
+* durable queue and survives a service disruption like any other work. Its handler is
+* **non-blocking**: each run reads the state of the works it waits `on`, and either
+*
+* - fires (queues its `queue` dependents, once, under a distributed {@link WorkContext.claim}), or
+* - **re-queues itself** with a small delay to check again later.
+*
+* It never holds a worker slot waiting, so a backlog of dependencies can't starve other
+* work. Build one with {@link dependency} and enqueue it like anything else — typically
+* alongside the works it depends on:
+*
+* ```ts
+* const a = stepA(), b = stepB()
+* ctx.queue([a, b, dependency({ on: [a, b], queue: [finalize()], config: 'all-success' })])
+* ```
+*
+* @module
+*/
+/** The built-in work type name for a dependency. */
+const DEPENDENCY_TYPE = "@work/dependency";
+/** Default re-check interval (ms). */
+const DEFAULT_POLL = 1e3;
+const TERMINAL = new Set([
+	"success",
+	"failed",
+	"dead"
+]);
+const isTerminal = (s) => s !== void 0 && TERMINAL.has(s.status);
+const isSuccess = (s) => s?.status === "success";
+/**
+* Evaluate a {@link DependencyCondition} against the watched items' states. A missing
+* state counts as "not yet done". Pure and JSON-driven, so every instance agrees.
+*/
+function conditionMet(condition, states) {
+	if (condition === "all-done") return states.every(isTerminal);
+	if (condition === "all-success") return states.every(isSuccess);
+	const pred = condition.of === "success" ? isSuccess : isTerminal;
+	return states.filter(pred).length >= condition.count;
+}
+const toId = (w) => typeof w === "string" ? w : w.id;
+const toSerialized = (w) => ({
+	id: w.id,
+	type: w.type,
+	input: w.input
+});
+const rehydrate = (s) => ({
+	id: s.id,
+	type: s.type,
+	input: s.input
+});
+/** Build a {@link DEPENDENCY_TYPE} work item from a (re-usable) input — a fresh queue id, same key. */
+const buildDependency = (input) => ({
+	id: uuid(),
+	type: DEPENDENCY_TYPE,
+	input
+});
+/**
+* Build a dependency: when the works it waits `on` satisfy `config`, it queues its
+* `queue` dependents (once). Enqueue it like any work.
+*/
+function dependency(opts) {
+	return buildDependency({
+		key: uuid(),
+		on: opts.on.map(toId),
+		queue: opts.queue.map(toSerialized),
+		config: opts.config ?? "all-success",
+		poll: opts.poll ?? DEFAULT_POLL,
+		deadline: opts.timeout !== void 0 ? Date.now() + opts.timeout : void 0
+	});
+}
+/**
+* The non-blocking handler for {@link DEPENDENCY_TYPE}: check once, then fire or
+* re-queue. Registered automatically by every work system. Remembers terminal statuses
+* (`resolved`) so it neither re-reads settled works nor treats an evicted state as a
+* failure.
+*/
+const dependencyHandler = async (input, ctx) => {
+	const resolved = { ...input.resolved };
+	const unknownIds = input.on.filter((id) => !(id in resolved));
+	const fresh = await ctx.states(unknownIds);
+	fresh.forEach((s, i) => {
+		if (s && TERMINAL.has(s.status)) resolved[unknownIds[i]] = s.status;
+	});
+	const freshById = new Map(unknownIds.map((id, i) => [id, fresh[i]]));
+	const states = input.on.map((id) => resolved[id] ? { status: resolved[id] } : freshById.get(id));
+	if (conditionMet(input.config, states)) {
+		if (await ctx.claim(`dep:${input.key}:fired`)) ctx.queue(input.queue.map(rehydrate));
+		return;
+	}
+	if (input.deadline !== void 0 && Date.now() >= input.deadline) throw new Error(`dependency: timed out waiting for [${input.on.join(", ")}]`);
+	ctx.queue(buildDependency({
+		...input,
+		resolved
+	}), { delay: input.poll });
+};
+//#endregion
+//#region src/schedule.ts
+const MS_PER_MINUTE = 6e4;
+/** Cap the forward scan so a never-matching expression can't loop forever (~1 year). */
+const MAX_SCAN_MINUTES = 366 * 24 * 60;
+/** `[min, max]` inclusive range for each of the five fields. */
+const FIELD_BOUNDS = [
+	[0, 59],
+	[0, 23],
+	[1, 31],
+	[1, 12],
+	[0, 6]
+];
+/** Expand one cron field — `*`, a number, an `a-b` range, a `<range>/<step>`, or a comma list — into the set of matching numbers. */
+function parseField(field, min, max) {
+	const out = /* @__PURE__ */ new Set();
+	for (const part of field.split(",")) {
+		const [rangePart, stepPart] = part.split("/");
+		const step = stepPart ? Number(stepPart) : 1;
+		if (!Number.isInteger(step) || step < 1) throw new Error(`cron: bad step in "${part}"`);
+		let lo = min;
+		let hi = max;
+		if (rangePart !== "*" && rangePart !== "") {
+			const [a, b] = rangePart.split("-");
+			lo = Number(a);
+			hi = b !== void 0 ? Number(b) : lo;
+			if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo < min || hi > max || lo > hi) throw new Error(`cron: bad range "${part}"`);
+		}
+		for (let v = lo; v <= hi; v += step) out.add(v);
+	}
+	return out;
+}
+/** Parse a 5-field cron expression (`min hour dom mon dow`). */
+function parseCron(expr) {
+	const fields = expr.trim().split(/\s+/);
+	if (fields.length !== 5) throw new Error(`cron: expected 5 fields, got ${fields.length} in "${expr}"`);
+	const [minute, hour, dom, month, dow] = fields.map((f, i) => parseField(f, FIELD_BOUNDS[i][0], FIELD_BOUNDS[i][1]));
+	return {
+		minute,
+		hour,
+		dom,
+		month,
+		dow,
+		domRestricted: fields[2] !== "*",
+		dowRestricted: fields[4] !== "*"
+	};
+}
+/** Does `date` (local time) satisfy the cron fields? Standard dom/dow OR semantics when both are restricted. */
+function matches(c, date) {
+	if (!c.minute.has(date.getMinutes()) || !c.hour.has(date.getHours()) || !c.month.has(date.getMonth() + 1)) return false;
+	const domOk = c.dom.has(date.getDate());
+	const dowOk = c.dow.has(date.getDay());
+	if (c.domRestricted && c.dowRestricted) return domOk || dowOk;
+	if (c.domRestricted) return domOk;
+	if (c.dowRestricted) return dowOk;
+	return true;
+}
+/**
+* The next epoch-ms strictly after `fromMs` that matches `expr`, or `undefined` if
+* none within ~a year. Minute-granular (cron's resolution).
+*/
+function nextAfter(expr, fromMs) {
+	const c = parseCron(expr);
+	const start = /* @__PURE__ */ new Date(Math.floor(fromMs / MS_PER_MINUTE) * MS_PER_MINUTE + MS_PER_MINUTE);
+	start.setSeconds(0, 0);
+	for (let i = 0; i < MAX_SCAN_MINUTES; i++) {
+		const candidate = new Date(start.getTime() + i * MS_PER_MINUTE);
+		if (matches(c, candidate)) return candidate.getTime();
+	}
+}
+const unref$1 = (t) => void t.unref?.();
+/** Compute the next fire time (epoch ms) for a schedule, or `undefined` to stop. */
+function computeNext(config, from) {
+	if (config.cron !== void 0) return nextAfter(config.cron, from);
+	if (config.next) {
+		const r = config.next(from);
+		if (r === void 0 || r === null) return;
+		return r instanceof Date ? r.getTime() : r;
+	}
+	throw new Error(`schedule "${config.name}": provide either "cron" or "next"`);
+}
+/**
+* Start a schedule's tick loop. Returns a cancel function. One instance fires per
+* occurrence (claimed via a `setNX` lease keyed by the fire's second-bucket).
+*/
+function startSchedule(config, deps) {
+	let cancelled = false;
+	let nextAt = computeNext(config, deps.now());
+	let timer;
+	const tick = async () => {
+		if (cancelled) return;
+		const t = deps.now();
+		if (nextAt !== void 0 && t >= nextAt) {
+			const bucket = Math.floor(nextAt / 1e3);
+			if (await deps.store.setIfNotExists(`${deps.prefix}sched:${config.name}:${bucket}`, "1", deps.leaseTtl)) {
+				const inst = config.run();
+				if (inst) deps.enqueueRaw(inst.type, inst.input);
+			}
+			nextAt = computeNext(config, deps.now());
+		}
+		if (!cancelled) {
+			timer = setTimeout(() => void tick(), deps.tick);
+			unref$1(timer);
+		}
+	};
+	timer = setTimeout(() => void tick(), 0);
+	unref$1(timer);
+	return () => {
+		cancelled = true;
+		clearTimeout(timer);
+	};
+}
+//#endregion
+//#region src/stats.ts
+/**
+* # Work stats — per-type metrics over `@ayepi/core`'s {@link Metrics}
+*
+* A thin recorder the engine drives at each lifecycle transition. It owns a
+* {@link Metrics} registry (bring your own via {@link WorkSystemOptions.metrics} to enable
+* quantiles or share one across systems) and records, **labelled by work type**:
+*
+* - **counters** — `queued` / `started` / `succeeded` / `failed` / `retried` / `deferred` / `rescheduled`
+* - **gauges** — live `active` / `pending` / `running`, the `peak_active` high-water mark, and
+*   `last_*_at` transition timestamps (epoch ms)
+* - **summaries** (ms) — `wait_time` (poll lag = `runAt − startAt`), `total_time` (end-to-end
+*   `endAt − queueAt`), `success_time` / `error_time` (run duration), `delay_time` /
+*   `reschedule_time` (re-queue horizons), and `attempts` (tries at terminal)
+*
+* Read it via {@link WorkSystem.metrics} (`list()` / `get()` / `subscribe()`) or the
+* {@link WorkSystem.stats} list snapshot.
+*
+* @module
+*/
+/** Metric names (dotted; `formatPrometheus` sanitizes the dots to underscores). Exported so consumers can reference series by name. */
+const WORK_METRICS = {
+	queued: "work.queued",
+	started: "work.started",
+	succeeded: "work.succeeded",
+	failed: "work.failed",
+	retried: "work.retried",
+	deferred: "work.deferred",
+	rescheduled: "work.rescheduled",
+	active: "work.active",
+	pending: "work.pending",
+	running: "work.running",
+	peak: "work.peak_active",
+	lastQueued: "work.last_queued_at",
+	lastStarted: "work.last_started_at",
+	lastSucceeded: "work.last_succeeded_at",
+	lastFailed: "work.last_failed_at",
+	waitTime: "work.wait_time",
+	totalTime: "work.total_time",
+	successTime: "work.success_time",
+	errorTime: "work.error_time",
+	delayTime: "work.delay_time",
+	rescheduleTime: "work.reschedule_time",
+	attempts: "work.attempts"
+};
+/** Create the work stats recorder over `metrics` (a fresh registry by default). */
+const createWorkStats = (metrics = createMetrics$1()) => {
+	const cache = /* @__PURE__ */ new Map();
+	const ms = { unit: "ms" };
+	const handles = (type) => {
+		let h = cache.get(type);
+		if (h) return h;
+		const l = { type };
+		h = {
+			queued: metrics.counter(WORK_METRICS.queued, l, { description: "items enqueued" }),
+			started: metrics.counter(WORK_METRICS.started, l, { description: "runs begun" }),
+			succeeded: metrics.counter(WORK_METRICS.succeeded, l, { description: "runs that succeeded" }),
+			failed: metrics.counter(WORK_METRICS.failed, l, { description: "items dead-lettered" }),
+			retried: metrics.counter(WORK_METRICS.retried, l, { description: "attempt-advancing retries" }),
+			deferred: metrics.counter(WORK_METRICS.deferred, l, { description: "handler/classifier reschedules" }),
+			rescheduled: metrics.counter(WORK_METRICS.rescheduled, l, { description: "early-arrival re-pushes" }),
+			active: metrics.gauge(WORK_METRICS.active, l, { description: "items in flight (pending + running)" }),
+			pending: metrics.gauge(WORK_METRICS.pending, l, { description: "items admitted, awaiting a doer slot" }),
+			running: metrics.gauge(WORK_METRICS.running, l, { description: "items executing" }),
+			peak: metrics.gauge(WORK_METRICS.peak, l, { description: "high-water mark of in-flight items" }),
+			lastQueued: metrics.gauge(WORK_METRICS.lastQueued, l, {
+				...ms,
+				description: "last enqueue time (epoch ms)"
+			}),
+			lastStarted: metrics.gauge(WORK_METRICS.lastStarted, l, {
+				...ms,
+				description: "last start time (epoch ms)"
+			}),
+			lastSucceeded: metrics.gauge(WORK_METRICS.lastSucceeded, l, {
+				...ms,
+				description: "last success time (epoch ms)"
+			}),
+			lastFailed: metrics.gauge(WORK_METRICS.lastFailed, l, {
+				...ms,
+				description: "last dead-letter time (epoch ms)"
+			}),
+			waitTime: metrics.summary(WORK_METRICS.waitTime, l, {
+				...ms,
+				description: "poll lag: runAt - startAt"
+			}),
+			totalTime: metrics.summary(WORK_METRICS.totalTime, l, {
+				...ms,
+				description: "end-to-end: endAt - queueAt"
+			}),
+			successTime: metrics.summary(WORK_METRICS.successTime, l, {
+				...ms,
+				description: "successful run duration"
+			}),
+			errorTime: metrics.summary(WORK_METRICS.errorTime, l, {
+				...ms,
+				description: "failed-to-terminal run duration"
+			}),
+			delayTime: metrics.summary(WORK_METRICS.delayTime, l, {
+				...ms,
+				description: "reschedule horizon"
+			}),
+			rescheduleTime: metrics.summary(WORK_METRICS.rescheduleTime, l, {
+				...ms,
+				description: "early-arrival re-push horizon"
+			}),
+			attempts: metrics.summary(WORK_METRICS.attempts, l, {
+				unit: "count",
+				description: "attempts used at terminal"
+			})
+		};
+		cache.set(type, h);
+		return h;
+	};
+	return {
+		metrics,
+		queued: (type, at) => {
+			const h = handles(type);
+			h.queued.inc();
+			h.lastQueued.set(at);
+		},
+		claimed: (type) => {
+			const h = handles(type);
+			h.pending.add(1);
+			h.active.add(1);
+			h.peak.max(h.active.value());
+		},
+		started: (type, at, pollLagMs) => {
+			const h = handles(type);
+			h.started.inc();
+			h.pending.add(-1);
+			h.running.add(1);
+			h.waitTime.observe(Math.max(0, pollLagMs));
+			h.lastStarted.set(at);
+		},
+		released: (type, wasRunning) => {
+			const h = handles(type);
+			(wasRunning ? h.running : h.pending).add(-1);
+			h.active.add(-1);
+		},
+		succeeded: (type, at, runMs, totalMs, attempt) => {
+			const h = handles(type);
+			h.succeeded.inc();
+			h.successTime.observe(Math.max(0, runMs));
+			h.totalTime.observe(Math.max(0, totalMs));
+			h.attempts.observe(attempt);
+			h.lastSucceeded.set(at);
+		},
+		failed: (type, at, runMs, totalMs, attempt) => {
+			const h = handles(type);
+			h.failed.inc();
+			if (runMs !== void 0) h.errorTime.observe(Math.max(0, runMs));
+			h.totalTime.observe(Math.max(0, totalMs));
+			h.attempts.observe(attempt);
+			h.lastFailed.set(at);
+		},
+		retried: (type) => void handles(type).retried.inc(),
+		deferred: (type, delayMs) => {
+			const h = handles(type);
+			h.deferred.inc();
+			h.delayTime.observe(Math.max(0, delayMs));
+		},
+		rescheduled: (type, delayMs) => {
+			const h = handles(type);
+			h.rescheduled.inc();
+			h.rescheduleTime.observe(Math.max(0, delayMs));
+		}
+	};
+};
+//#endregion
+//#region src/types.ts
+/**
+* # Types — the type-safe definition surface
+*
+* Defining a work type with {@link defineWork} yields a **callable builder**: call it
+* with the work's exact input and you get a type-checked, queueable {@link Work} (with
+* a build-time id) that also carries its output type. {@link createWork} takes a
+* `const` tuple of builders and produces a {@link WorkSystem} whose `enqueue` is fully
+* checked — by instance (`enqueue(add({ a, b }))`) or by name (`enqueue('add', { a, b })`).
+*
+* The **group result type** is the union of every registered work's non-void output
+* ({@link GroupResult}). All durations are **milliseconds**.
+*
+* @module
+*/
+const build = (name, input) => ({
+	id: uuid(),
+	type: name,
+	input
+});
+/**
+* Define a work type. Returns a {@link WorkBuilder} — a function that builds queueable
+* instances — typed by its input `I` and output `O`.
+*/
+function defineWork(name, handler, opts = {}) {
+	return Object.assign((input) => build(name, input), {
+		type: name,
+		def: {
+			name,
+			handler,
+			options: opts
+		}
+	});
+}
+/**
+* Define a **batched** work type. Items still enqueue, retry, prioritize, and join
+* groups individually, but execute together via {@link BatchConfig.run} once `size`
+* accumulate or `maxWait` ms elapse — so each `.result()` resolves to its aligned
+* output. The per-type {@link WorkOptions.doer} governs how many *batches* run at once.
+*/
+function defineBatchWork(name, config) {
+	const { size, maxWait, run, ...options } = config;
+	const batch = {
+		size,
+		maxWait,
+		run
+	};
+	const handler = async (input) => (await run([input]))[0];
+	return Object.assign((input) => build(name, input), {
+		type: name,
+		def: {
+			name,
+			handler,
+			options,
+			batch
+		}
+	});
+}
+//#endregion
+//#region src/engine.ts
+/**
+* # Engine
+*
+* `createWork` ties the ports together into a running {@link WorkSystem}: a typed
+* registry, a **doer**-driven worker loop (the doer decides how many items to pull and
+* which to run next), per-item heartbeats, retry by **re-enqueue**, group linking +
+* result resolution, batching, distributed wait handles, a built-in non-blocking
+* dependency type, and scheduling. A `skipQueue` work runs in-process (doer + retries,
+* no queue/store/heartbeat). Distributed coordination uses the store's
+* `setIfNotExists`/`increment` atoms and pub/sub fanout, so the same logic runs on one
+* process or a fleet.
+*
+* @module
+*/
+/** Default idle poll interval (ms). */
+const DEFAULT_POLL_INTERVAL = 1e3;
+/** Default lease/visibility timeout for a pulled item (ms). */
+const DEFAULT_VISIBILITY = 3e4;
+/** Heartbeat interval = visibility / this, so a lease is refreshed well before it lapses. */
+const HEARTBEAT_DIVISOR = 3;
+/** Default key namespace. */
+const DEFAULT_PREFIX = "work:";
+/** Hard cap on how many items one poll fetches, regardless of doer appetite. */
+const POLL_BATCH_CAP = 512;
+/** TTL for results / states / group bookkeeping (ms). */
+const RESULT_TTL = 864e5;
+/** TTL for the "someone is waiting" registry key (ms). */
+const WAIT_TTL = 36e5;
+/** How often a distributed waiter re-polls the store alongside pub/sub (ms). */
+const WAIT_POLL = 250;
+/** Grace before the orphan check, so an in-process awaiter can register first (ms). */
+const UNHANDLED_GRACE = 100;
+/** Re-delivery delay for a work type this instance doesn't know (ms). */
+const UNKNOWN_TYPE_DELAY = 5e3;
+/** A popped item this far (ms) before its `startAt` is put back rather than run (handles backends that can't honor a long delay). */
+const SCHED_TOLERANCE = 1e3;
+/** Scheduler tick interval (ms). */
+const SCHED_TICK = 1e3;
+/** TTL for a schedule's per-fire lease (ms). */
+const SCHED_LEASE_TTL = 9e4;
+/** Max time `stop()` waits for in-flight work to drain (ms). */
+const STOP_DRAIN = 5e3;
+/** A dependency dead-letters on timeout rather than retrying. */
+const DEP_RETRY_ATTEMPTS = 1;
+/** Default max messages redriven from the DLQ per idle poll. */
+const REDRIVE_DEFAULT = 10;
+const unref = (t) => void t.unref?.();
+const errString = (err) => err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+/**
+* Create a work system. Zero-config (`createWork()`) uses the bundled in-memory backend
+* and an {@link unlimitedDoer}; pass `work: [...] as const` for a typed registry, a
+* `doer` to govern concurrency, and/or `queue`/`pubsub`/`store` to go distributed.
+*/
+function createWork(opts = {}) {
+	const mem = opts.queue && opts.pubsub && opts.store ? null : memoryBackend({ now: opts.now });
+	const backend = {
+		queue: opts.queue ?? mem.queue,
+		pubsub: opts.pubsub ?? mem.pubsub,
+		store: opts.store ?? mem.store
+	};
+	const { pubsub, store } = backend;
+	const globalCodec = opts.codec ?? defaultCodec;
+	const globalDoer = opts.doer ?? unlimitedDoer$1();
+	const pollInterval = opts.pollInterval ?? DEFAULT_POLL_INTERVAL;
+	const visibility = opts.visibility ?? DEFAULT_VISIBILITY;
+	const heartbeatEvery = opts.heartbeat ?? Math.floor(visibility / HEARTBEAT_DIVISOR);
+	const prefix = opts.prefix ?? DEFAULT_PREFIX;
+	const logWith = opts.logWith ?? identityLogWith;
+	const now = opts.now ?? Date.now;
+	const random = opts.random ?? Math.random;
+	const attemptsOf = (r) => r.attempts ?? getDefaultRetryOptions$1().attempts ?? 1;
+	const stats = createWorkStats(opts.metrics);
+	const k = (suffix) => prefix + suffix;
+	/** Report a swallowed non-critical error (best-effort — a throwing `onError` is itself ignored). */
+	const report = (err, phase) => {
+		try {
+			opts.onError?.(err, phase);
+		} catch {}
+	};
+	/**
+	* Run a load-bearing backend call (store/queue write) with optional {@link WorkSystemOptions.portRetry}
+	* resilience — a transient blip is absorbed before the error reaches the engine's commit/queue handling.
+	* (The bundled Redis/SQS backends also retry per call; this is an engine-level safety net for any backend.)
+	*/
+	const port = (fn) => opts.portRetry ? retry$1(fn, { ...opts.portRetry }) : fn();
+	/**
+	* The lifecycle combinator: run `fn`, then **always** run `release` (the teardown for state
+	* acquired *before* the call — an active-set entry, a heartbeat, …). The `finally` guarantees the
+	* release on every path (success, throw, early return), so no failure can leak that state. Pair it
+	* with an acquire that returns its own `release` (e.g. {@link claim}) so start↔stop can't drift apart.
+	*/
+	const scoped = async (release, fn) => {
+		try {
+			return await fn();
+		} finally {
+			release();
+		}
+	};
+	/** Publish a best-effort notification; never throws synchronously (so callers can fire-and-forget it). */
+	const publish = (obj) => {
+		try {
+			return Promise.resolve(pubsub.publish(JSON.stringify(obj))).then(() => void 0);
+		} catch (err) {
+			return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+		}
+	};
+	/** Fire a best-effort pub/sub notification detached — waiters also reach it via the store poll. */
+	const notify = (obj) => void publish(obj).catch((err) => report(err, "commit"));
+	const emit = (event) => {
+		try {
+			opts.onEvent?.(event);
+		} catch {}
+		const type = event.type;
+		if (type !== void 0) try {
+			registry.get(type)?.def.options.onEvent?.(event);
+		} catch {}
+	};
+	const registry = /* @__PURE__ */ new Map();
+	for (const builder of opts.work ?? []) registry.set(builder.type, builder);
+	const codecFor = (type) => registry.get(type)?.def.options.codec ?? globalCodec;
+	const doerFor = (type) => registry.get(type)?.def.options.doer ?? globalDoer;
+	/** The queue a type's items live on (its own, or the system default). New pushes for `type` go here. */
+	const queueFor = (type) => registry.get(type)?.def.options.queue ?? backend.queue;
+	/** Every distinct queue the registry uses (the default + any per-type queues) — polled fairly by the loop. */
+	const distinctQueues = () => {
+		const set = new Set([backend.queue]);
+		for (const b of registry.values()) if (b.def.options.queue) set.add(b.def.options.queue);
+		return [...set];
+	};
+	/** Resolve an item's effective options: queue-time > type `options(input)` > type constants > defaults. */
+	const resolveOptions = (type, input, qOpts) => {
+		const tOpts = registry.get(type)?.def.options;
+		const computed = tOpts?.options?.(input) ?? {};
+		return {
+			delay: qOpts?.delay ?? computed.delay ?? 0,
+			runAt: qOpts?.runAt ?? computed.runAt,
+			priority: qOpts?.priority ?? computed.priority ?? tOpts?.priority ?? 0,
+			group: qOpts?.group ?? computed.group ?? tOpts?.group,
+			retry: {
+				...getDefaultRetryOptions$1(),
+				...opts.retry,
+				...tOpts?.retry,
+				...computed.retry,
+				...qOpts?.retry
+			},
+			skipQueue: qOpts?.skipQueue ?? computed.skipQueue ?? tOpts?.skipQueue ?? false
+		};
+	};
+	const allStates = /* @__PURE__ */ new Map();
+	const groupIndex = /* @__PURE__ */ new Map();
+	const recordState = (state, groupId) => {
+		allStates.set(state.id, state);
+		let g = groupIndex.get(groupId);
+		if (!g) {
+			g = /* @__PURE__ */ new Map();
+			groupIndex.set(groupId, g);
+		}
+		g.set(state.id, state);
+	};
+	const setState = async (state, groupId) => {
+		const { result: _result, ...forStore } = state;
+		await port(() => Promise.resolve(store.set(k(`state:${state.id}`), JSON.stringify(forStore), RESULT_TTL)));
+		recordState(state, groupId);
+	};
+	const readState = async (id) => {
+		const s = await Promise.resolve(store.get(k(`state:${id}`)));
+		if (s === void 0) return allStates.get(id);
+		try {
+			return JSON.parse(s);
+		} catch {
+			return;
+		}
+	};
+	/** Atomic add via the store `increment` atom, falling back to a (single-process-safe) get+set. */
+	const storeIncrement = (key, by, ttl) => port(async () => {
+		if (store.increment) return await Promise.resolve(store.increment(key, by, ttl));
+		const cur = Number(await Promise.resolve(store.get(key)) ?? "0") + by;
+		await Promise.resolve(store.set(key, String(cur), ttl));
+		return cur;
+	});
+	const groupIncr = (groupId, by) => storeIncrement(k(`group:${groupId}:open`), by, RESULT_TTL);
+	/** Roll back a group hold (`groupIncr(+1)`) whose item never reached the queue / a terminal path — best-effort, so the group can still settle. */
+	const undoHold = (groupId) => groupIncr(groupId, -1).then(() => void 0).catch((err) => report(err, "commit"));
+	const settleGroup = async (groupId) => {
+		if (await groupIncr(groupId, -1) > 0) return;
+		await port(() => Promise.resolve(store.set(k(`group:${groupId}:done`), "1", RESULT_TTL)));
+		notify({
+			kind: "group-done",
+			groupId
+		});
+		const r = await Promise.resolve(store.get(k(`group:${groupId}:result`)));
+		emit({
+			kind: "group-done",
+			groupId,
+			result: r === void 0 ? void 0 : globalCodec.parse(r),
+			at: now()
+		});
+		maybeUnhandled(groupId);
+	};
+	const makeContext = (impl) => {
+		const queue = (works, options) => Array.isArray(works) ? works.map((w) => impl.enqueueOne(w, options)) : impl.enqueueOne(works, options);
+		return {
+			id: impl.id,
+			groupId: impl.groupId,
+			attempt: impl.attempt,
+			queue,
+			setResult: impl.setResult,
+			states: impl.states,
+			claim: impl.claim
+		};
+	};
+	const storeStates = (ids) => Promise.all(ids.map(readState));
+	const storeClaim = (key) => Promise.resolve(store.setIfNotExists(k(key), "1", RESULT_TTL));
+	/** Push an envelope onto **its type's** queue (default or per-type), invisible for `delay` ms. */
+	const pushEnvelope = (env, delay) => port(() => Promise.resolve(queueFor(env.type).push(JSON.stringify(env), { delay })).then(() => void 0));
+	/** Resolve when a deferred/scheduled item should next run (absolute epoch ms). */
+	const resolveRunAt = (when) => when.runAt ?? now() + (when.delay ?? 0);
+	const submitQueued = (id, type, input, groupId, ro) => {
+		const queueAt = now();
+		const startAt = ro.runAt ?? queueAt + ro.delay;
+		return (async () => {
+			await groupIncr(groupId, 1);
+			try {
+				await setState({
+					id,
+					type,
+					status: "pending",
+					attempt: 1,
+					queueAt,
+					startAt,
+					priority: ro.priority,
+					group: ro.group
+				}, groupId);
+				await pushEnvelope({
+					id,
+					type,
+					groupId,
+					input: codecFor(type).stringify(input),
+					queueAt,
+					startAt,
+					attempt: 1,
+					priority: ro.priority,
+					group: ro.group,
+					retry: ro.retry
+				}, Math.max(0, startAt - queueAt));
+			} catch (err) {
+				await undoHold(groupId);
+				throw err;
+			}
+			stats.queued(type, queueAt);
+			emit({
+				kind: "queued",
+				id,
+				type,
+				groupId,
+				at: queueAt
+			});
+		})();
+	};
+	/** Re-enter the queue for a retry: a fresh delivery with `attempt + 1` and a recomputed `startAt`. */
+	const rePush = async (env, delay) => {
+		const startAt = now() + delay;
+		const next = {
+			...env,
+			attempt: env.attempt + 1,
+			startAt
+		};
+		await setState({
+			id: env.id,
+			type: env.type,
+			status: "pending",
+			attempt: next.attempt,
+			queueAt: env.queueAt,
+			startAt,
+			priority: env.priority,
+			group: env.group
+		}, env.groupId);
+		await pushEnvelope(next, delay);
+	};
+	const enqueueImpl = (a, b, c) => {
+		const fromName = typeof a === "string";
+		const id = fromName ? uuid() : a.id;
+		const type = fromName ? a : a.type;
+		const input = fromName ? b : a.input;
+		const qOpts = fromName ? c : b;
+		const groupId = uuid();
+		const ro = resolveOptions(type, input, qOpts);
+		return makeHandle(id, type, groupId, ro.skipQueue ? runImmediate(id, type, input, groupId, ro) : submitQueued(id, type, input, groupId, ro));
+	};
+	const enqueueRaw = (type, input) => void enqueueImpl(type, input);
+	const makeHandle = (id, type, groupId, ready) => {
+		const markWaiting = () => Promise.resolve(store.setIfNotExists(k(`wait:${groupId}`), "1", WAIT_TTL));
+		const result = async () => {
+			await ready;
+			await markWaiting();
+			return waitForItem(id, type);
+		};
+		const group = async () => {
+			await ready;
+			await markWaiting();
+			return waitForGroup(groupId);
+		};
+		return {
+			id,
+			groupId,
+			result,
+			group,
+			then: (onF, onR) => group().then(onF, onR)
+		};
+	};
+	const waitForItem = (id, type) => new Promise((resolve, reject) => {
+		let settled = false;
+		const teardown = [];
+		const cleanup = () => {
+			settled = true;
+			for (const t of teardown) t();
+		};
+		const check = async () => {
+			if (settled) return;
+			const res = await Promise.resolve(store.get(k(`result:${id}`)));
+			if (res !== void 0) {
+				cleanup();
+				resolve(codecFor(type).parse(res));
+				return;
+			}
+			const err = await Promise.resolve(store.get(k(`item:${id}:error`)));
+			if (err !== void 0) {
+				cleanup();
+				reject(new Error(err));
+			}
+		};
+		teardown.push(pubsub.subscribe((m) => {
+			try {
+				const e = JSON.parse(m);
+				if (e.kind === "done" && e.id === id) check();
+			} catch {}
+		}));
+		const poll = setInterval(() => void check(), WAIT_POLL);
+		unref(poll);
+		teardown.push(() => clearInterval(poll));
+		check();
+	});
+	const waitForGroup = (groupId) => new Promise((resolve) => {
+		let settled = false;
+		const teardown = [];
+		const cleanup = () => {
+			settled = true;
+			for (const t of teardown) t();
+		};
+		const check = async () => {
+			if (settled) return;
+			if (await Promise.resolve(store.get(k(`group:${groupId}:done`))) === void 0) return;
+			cleanup();
+			const r = await Promise.resolve(store.get(k(`group:${groupId}:result`)));
+			resolve(r === void 0 ? void 0 : globalCodec.parse(r));
+		};
+		teardown.push(pubsub.subscribe((m) => {
+			try {
+				const e = JSON.parse(m);
+				if (e.kind === "group-done" && e.groupId === groupId) check();
+			} catch {}
+		}));
+		const poll = setInterval(() => void check(), WAIT_POLL);
+		unref(poll);
+		teardown.push(() => clearInterval(poll));
+		check();
+	});
+	const maybeUnhandled = (groupId) => {
+		if (!opts.unhandledWorkGroup) return;
+		unref(setTimeout(async () => {
+			if (!await Promise.resolve(store.setIfNotExists(k(`group-handled:${groupId}`), "1", RESULT_TTL))) return;
+			if (await Promise.resolve(store.get(k(`wait:${groupId}`))) !== void 0) return;
+			const r = await Promise.resolve(store.get(k(`group:${groupId}:result`)));
+			const states = [...groupIndex.get(groupId)?.values() ?? []];
+			opts.unhandledWorkGroup?.({
+				groupId,
+				lastResult: r === void 0 ? void 0 : globalCodec.parse(r),
+				states
+			});
+		}, UNHANDLED_GRACE));
+	};
+	const activeMap = /* @__PURE__ */ new Map();
+	/**
+	* `skipQueue`: hand the first attempt straight to the doer (no queue hop, no lease,
+	* no heartbeat) for low latency. State/results/group still go through the store, and
+	* a **failure re-enqueues** the item (attempt + 1) onto the durable queue — so the
+	* retry survives a crash and any instance in the fleet can pick it up. (The first run
+	* itself is best-effort: that's the latency-for-durability trade `skipQueue` makes.)
+	*/
+	const runImmediate = (id, type, input, groupId, ro) => {
+		const queueAt = now();
+		const startAt = ro.runAt ?? queueAt + ro.delay;
+		const builder = registry.get(type);
+		const env = {
+			id,
+			type,
+			groupId,
+			input: codecFor(type).stringify(input),
+			queueAt,
+			startAt,
+			attempt: 1,
+			priority: ro.priority,
+			group: ro.group,
+			retry: ro.retry
+		};
+		return (async () => {
+			await groupIncr(groupId, 1);
+			try {
+				await setState({
+					id,
+					type,
+					status: "pending",
+					attempt: 1,
+					queueAt,
+					startAt,
+					priority: ro.priority,
+					group: ro.group
+				}, groupId);
+				stats.queued(type, queueAt);
+				emit({
+					kind: "queued",
+					id,
+					type,
+					groupId,
+					at: queueAt
+				});
+			} catch (err) {
+				await undoHold(groupId);
+				throw err;
+			}
+			if (!builder) {
+				await deadLetterItem(null, env, `unknown work type: ${type}`, null);
+				return;
+			}
+			const release = claim(env, null, null);
+			try {
+				doerFor(type).do(() => execute(null, env, input, builder.def, null, release));
+			} catch (err) {
+				release();
+				await undoHold(groupId);
+				throw err;
+			}
+		})();
+	};
+	/** Keep a leased item's lease (and its heartbeat key) alive on the **queue it came from**. */
+	const startHeartbeat = (p, id, q) => {
+		const hb = setInterval(() => {
+			Promise.resolve(q.heartbeat(p, visibility));
+			Promise.resolve(store.set(k(`hb:${id}`), String(now()), visibility));
+		}, heartbeatEvery);
+		unref(hb);
+		return hb;
+	};
+	/**
+	* Acquire the per-item processing state — register it in the active set and (if leased) start its
+	* heartbeat — and return the **paired teardown** that clears the heartbeat and drops it from the
+	* active set. This closure is the *sole owner* of that state: whoever runs the item passes the
+	* returned `release` to {@link scoped}, so it is torn down on every path and can never drift/leak.
+	* (A `skipQueue` item has no lease `p`/`q`, so no heartbeat.)
+	*/
+	const claim = (env, p, q) => {
+		activeMap.set(env.id, {
+			id: env.id,
+			type: env.type,
+			groupId: env.groupId,
+			status: "pending",
+			attempt: env.attempt,
+			priority: env.priority,
+			group: env.group,
+			queueAt: env.queueAt,
+			startAt: env.startAt
+		});
+		stats.claimed(env.type);
+		const hb = p && q ? startHeartbeat(p, env.id, q) : null;
+		return () => {
+			if (hb) clearInterval(hb);
+			const wasRunning = activeMap.get(env.id)?.status === "running";
+			activeMap.delete(env.id);
+			stats.released(env.type, wasRunning);
+		};
+	};
+	/**
+	* Re-enqueue an item to become runnable at `startAt` **without advancing its attempt** — a
+	* reschedule, not a retry. It **acks the current delivery and pushes a fresh message**, so a
+	* backend's per-message delivery count (e.g. SQS `ApproximateReceiveCount`) **resets** — a
+	* scheduled item that bounces (re-deferred each poll until due) can never trip the backend's
+	* native redrive/DLQ. Returns the resolved `startAt`.
+	*/
+	const reschedule = async (p, env, q, startAt) => {
+		const next = {
+			...env,
+			startAt
+		};
+		await setState({
+			id: env.id,
+			type: env.type,
+			status: "pending",
+			attempt: env.attempt,
+			queueAt: env.queueAt,
+			startAt,
+			priority: env.priority,
+			group: env.group
+		}, env.groupId);
+		if (p && q) await port(() => Promise.resolve(q.ack(p)));
+		await pushEnvelope(next, Math.max(0, startAt - now()));
+		return startAt;
+	};
+	/** A handler/classifier-initiated deferral: {@link reschedule} the item to `runAt` and emit a `deferred` event. */
+	const deferItem = async (p, env, q, runAt) => {
+		const startAt = await reschedule(p, env, q, Math.max(runAt, now()));
+		const at = now();
+		stats.deferred(env.type, startAt - at);
+		emit({
+			kind: "deferred",
+			id: env.id,
+			type: env.type,
+			groupId: env.groupId,
+			runAt: startAt,
+			at
+		});
+	};
+	const deadLetterItem = async (p, env, error, q, runAt) => {
+		const at = now();
+		stats.failed(env.type, at, runAt === void 0 ? void 0 : at - runAt, at - env.queueAt, env.attempt);
+		await port(() => Promise.resolve(store.set(k(`item:${env.id}:error`), error, RESULT_TTL)));
+		await setState({
+			id: env.id,
+			type: env.type,
+			status: "dead",
+			attempt: env.attempt,
+			error,
+			queueAt: env.queueAt,
+			startAt: env.startAt,
+			runAt,
+			endAt: at,
+			priority: env.priority,
+			group: env.group
+		}, env.groupId);
+		if (p && q) {
+			await Promise.resolve(q.deadLetter?.(p.body, error));
+			await port(() => Promise.resolve(q.ack(p)));
+		}
+		notify({
+			kind: "done",
+			id: env.id,
+			groupId: env.groupId,
+			error
+		});
+		emit({
+			kind: "failed",
+			id: env.id,
+			type: env.type,
+			groupId: env.groupId,
+			attempt: env.attempt,
+			error,
+			willRetry: false,
+			at
+		});
+		await settleGroup(env.groupId);
+	};
+	/** The synchronous part of marking running (the active-map flip) — kept on the critical path. */
+	const markRunningSync = (env, runAt) => {
+		stats.started(env.type, runAt, runAt - env.startAt);
+		const a = activeMap.get(env.id);
+		if (a) {
+			a.status = "running";
+			a.runAt = runAt;
+		}
+	};
+	/** The async part (persist the `running` state + emit `started`) — can run **alongside** the handler. */
+	const persistRunning = async (env, runAt) => {
+		await setState({
+			id: env.id,
+			type: env.type,
+			status: "running",
+			attempt: env.attempt,
+			queueAt: env.queueAt,
+			startAt: env.startAt,
+			runAt,
+			priority: env.priority,
+			group: env.group
+		}, env.groupId);
+		emit({
+			kind: "started",
+			id: env.id,
+			type: env.type,
+			groupId: env.groupId,
+			attempt: env.attempt,
+			at: runAt
+		});
+	};
+	const markRunning = async (env, runAt) => {
+		markRunningSync(env, runAt);
+		await persistRunning(env, runAt);
+	};
+	const finishSuccess = async (p, env, runAt, output, q) => {
+		const at = now();
+		stats.succeeded(env.type, at, at - runAt, at - env.queueAt, env.attempt);
+		await port(() => Promise.resolve(store.set(k(`result:${env.id}`), codecFor(env.type).stringify(output), RESULT_TTL)));
+		await setState({
+			id: env.id,
+			type: env.type,
+			status: "success",
+			attempt: env.attempt,
+			result: output,
+			queueAt: env.queueAt,
+			startAt: env.startAt,
+			runAt,
+			endAt: at,
+			priority: env.priority,
+			group: env.group
+		}, env.groupId);
+		if (p && q) await port(() => Promise.resolve(q.ack(p)));
+		notify({
+			kind: "done",
+			id: env.id,
+			groupId: env.groupId
+		});
+		emit({
+			kind: "succeeded",
+			id: env.id,
+			type: env.type,
+			groupId: env.groupId,
+			attempt: env.attempt,
+			result: output,
+			at
+		});
+		await settleGroup(env.groupId);
+	};
+	const finishFailure = async (p, env, runAt, err, q) => {
+		if (env.attempt < attemptsOf(env.retry)) {
+			const delay = backoff$1(env.attempt, env.retry, random);
+			stats.retried(env.type);
+			emit({
+				kind: "failed",
+				id: env.id,
+				type: env.type,
+				groupId: env.groupId,
+				attempt: env.attempt,
+				error: errString(err),
+				willRetry: true,
+				at: now()
+			});
+			if (p && q) await port(() => Promise.resolve(q.ack(p)));
+			await rePush(env, delay);
+		} else await deadLetterItem(p, env, errString(err), q, runAt);
+	};
+	/** Ask the per-type (else system) {@link FailureClassifier} what a handler error means; a throwing classifier falls back to the default. */
+	const classifyFailure = async (err, env) => {
+		const decide = registry.get(env.type)?.def.options.onFailure ?? opts.onFailure;
+		if (!decide) return;
+		try {
+			return await decide(err, {
+				id: env.id,
+				type: env.type,
+				attempt: env.attempt,
+				attempts: attemptsOf(env.retry)
+			}) ?? void 0;
+		} catch (e) {
+			report(e, "commit");
+			return;
+		}
+	};
+	/**
+	* Decide what a handler/batch failure does — the single owner of failure routing for both single and
+	* batched items. Explicit throws win (`WorkDelayError` → reschedule, `RetryAbort` → dead-letter now);
+	* otherwise the {@link classifyFailure} hook may `'abort'` or reschedule a `{ delay }`/`{ runAt }`
+	* (e.g. a rate limit — re-queued **without** advancing `attempt`); the default is retry/dead-letter.
+	*/
+	const handleFailure = async (p, env, runAt, err, q) => {
+		if (err instanceof WorkDelayError) {
+			await deferItem(p, env, q, resolveRunAt(err.when));
+			return;
+		}
+		if (err instanceof RetryAbort$1) {
+			await deadLetterItem(p, env, errString(err.cause ?? err), q, runAt);
+			return;
+		}
+		const decision = await classifyFailure(err, env);
+		if (decision === "abort") {
+			await deadLetterItem(p, env, errString(err), q, runAt);
+			return;
+		}
+		if (decision !== void 0 && decision !== "retry") {
+			await deferItem(p, env, q, "runAt" in decision ? decision.runAt : now() + decision.delay);
+			return;
+		}
+		await finishFailure(p, env, runAt, err, q);
+	};
+	const queuedContext = (env, pending) => makeContext({
+		id: env.id,
+		groupId: env.groupId,
+		attempt: env.attempt,
+		enqueueOne: (work, options) => {
+			pending.push(submitQueued(work.id, work.type, work.input, env.groupId, resolveOptions(work.type, work.input, options)));
+			return work.id;
+		},
+		setResult: (r) => {
+			pending.push(port(() => Promise.resolve(store.set(k(`group:${env.groupId}:result`), globalCodec.stringify(r), RESULT_TTL)).then(() => void 0)));
+		},
+		states: storeStates,
+		claim: storeClaim
+	});
+	/**
+	* The task handed to a doer: run a single item (leased from queue `q`, or `skipQueue` with `p`/`q`
+	* null). `release` is the {@link claim} teardown — {@link scoped} runs it in `finally`, so the
+	* active-set entry + heartbeat are always cleaned up regardless of how the run ends.
+	*/
+	const execute = (p, env, input, def, q, release) => scoped(release, async () => {
+		const runAt = now();
+		markRunningSync(env, runAt);
+		const running = persistRunning(env, runAt).catch((err) => report(err, "commit"));
+		const pending = [];
+		const ctx = queuedContext(env, pending);
+		let output;
+		try {
+			output = await logWith(merge(opts.logContext?.(input, env.type), def.options.logContext?.(input)), () => Promise.resolve(def.handler(input, ctx)));
+			await Promise.all(pending);
+		} catch (err) {
+			await running;
+			await handleFailure(p, env, runAt, err, q);
+			return;
+		}
+		try {
+			await running;
+			await finishSuccess(p, env, runAt, output, q);
+		} catch (err) {
+			report(err, "commit");
+		}
+	});
+	const executeBatch = (items, batch) => scoped(() => {
+		for (const it of items) it.release();
+	}, async () => {
+		const runAt = now();
+		await Promise.all(items.map((it) => markRunning(it.env, runAt)));
+		let outputs;
+		try {
+			const ran = await Promise.resolve(batch.run(items.map((it) => it.input)));
+			if (!Array.isArray(ran) || ran.length !== items.length) throw new Error(`batch "${items[0]?.env.type}" returned ${Array.isArray(ran) ? ran.length : "a non-array"} outputs for ${items.length} inputs`);
+			outputs = ran;
+		} catch (err) {
+			await Promise.all(items.map((it) => handleFailure(it.p, it.env, runAt, err, it.q)));
+			return;
+		}
+		await Promise.all(items.map((it, i) => Promise.resolve(finishSuccess(it.p, it.env, runAt, outputs[i], it.q)).catch((err) => report(err, "commit"))));
+	});
+	const batchers = /* @__PURE__ */ new Map();
+	const batcherFor = (type) => {
+		let b = batchers.get(type);
+		if (!b) {
+			const config = registry.get(type).def.batch;
+			const doer = doerFor(type);
+			const buffer = [];
+			let timer = null;
+			const flush = () => {
+				if (timer) {
+					clearTimeout(timer);
+					timer = null;
+				}
+				if (buffer.length === 0) return;
+				const items = buffer.splice(0);
+				try {
+					doer.do(() => executeBatch(items, config), { createdAt: items[0].env.queueAt });
+				} catch (err) {
+					for (const it of items) it.release();
+					report(err, "queue");
+				}
+			};
+			b = {
+				available: () => doer.available() <= 0 ? 0 : Math.max(0, config.size - buffer.length),
+				add: (item) => {
+					buffer.push(item);
+					if (buffer.length >= config.size) flush();
+					else if (!timer) {
+						timer = setTimeout(flush, config.maxWait);
+						unref(timer);
+					}
+				},
+				flushAll: flush
+			};
+			batchers.set(type, b);
+		}
+		return b;
+	};
+	/**
+	* Parse + validate an item leased from queue `q` and route it to a batcher or doer. Returns `true`
+	* if it **started** the item, `false` if it put it back (early/not-due, affinity decline, saturated
+	* doer/batcher, unknown type) or dropped it — the loop uses this to keep pulling vs back off.
+	*/
+	const accept = async (p, q) => {
+		let env;
+		try {
+			env = JSON.parse(p.body);
+		} catch {
+			await Promise.resolve(q.ack(p));
+			return false;
+		}
+		const due = now();
+		if (env.startAt - due > SCHED_TOLERANCE) {
+			await reschedule(p, env, q, env.startAt);
+			stats.rescheduled(env.type, env.startAt - due);
+			return false;
+		}
+		const { id, type, groupId } = env;
+		const builder = registry.get(type);
+		if (!builder) {
+			if (env.attempt >= attemptsOf(env.retry)) await deadLetterItem(p, env, `unknown work type: ${type}`, q);
+			else await Promise.resolve(q.fail(p, UNKNOWN_TYPE_DELAY));
+			return false;
+		}
+		let input;
+		try {
+			input = codecFor(type).parse(env.input);
+		} catch (e) {
+			await deadLetterItem(p, env, `bad input: ${errString(e)}`, q);
+			return false;
+		}
+		if (opts.accept && !opts.accept({
+			id,
+			type,
+			groupId,
+			attempt: env.attempt,
+			input
+		})) {
+			await Promise.resolve(q.fail(p, pollInterval));
+			return false;
+		}
+		if (builder.def.batch) {
+			const batcher = batcherFor(type);
+			if (batcher.available() <= 0) {
+				await Promise.resolve(q.fail(p, pollInterval));
+				return false;
+			}
+			batcher.add({
+				p,
+				env,
+				input,
+				release: claim(env, p, q),
+				q
+			});
+			return true;
+		}
+		const doer = doerFor(type);
+		if (doer.available() <= 0) {
+			await Promise.resolve(q.fail(p, pollInterval));
+			return false;
+		}
+		const release = claim(env, p, q);
+		try {
+			doer.do(() => execute(p, env, input, builder.def, q, release), {
+				group: env.group,
+				priority: env.priority,
+				createdAt: env.queueAt
+			});
+		} catch (err) {
+			release();
+			throw err;
+		}
+		return true;
+	};
+	/**
+	* Redrive up to `redriveCount` bodies from the configured {@link WorkSystemOptions.dlq} back onto
+	* their type's queue as **fresh** work — `attempt` reset to 1 (full retry budget), `queueAt`/`startAt`
+	* = now, a fresh group hold re-opened — then ack each off the DLQ. Called only when the normal queues
+	* are idle and capacity is free. An unparseable body is dropped (acked); a re-queue failure leaves the
+	* body leased on the DLQ to retry on a later idle tick. Returns how many were moved.
+	*/
+	const redriveCount = opts.redriveCount ?? REDRIVE_DEFAULT;
+	const redriveFromDLQ = async () => {
+		const dlq = opts.dlq;
+		if (!dlq || redriveCount <= 0) return 0;
+		const pulled = await Promise.resolve(dlq.pop(redriveCount, visibility));
+		let moved = 0;
+		for (const p of pulled) {
+			let env;
+			try {
+				env = JSON.parse(p.body);
+			} catch {
+				await Promise.resolve(dlq.ack(p)).catch((err) => report(err, "queue"));
+				continue;
+			}
+			const at = now();
+			const fresh = {
+				...env,
+				attempt: 1,
+				queueAt: at,
+				startAt: at
+			};
+			try {
+				await groupIncr(env.groupId, 1);
+				try {
+					await setState({
+						id: env.id,
+						type: env.type,
+						status: "pending",
+						attempt: 1,
+						queueAt: at,
+						startAt: at,
+						priority: env.priority,
+						group: env.group
+					}, env.groupId);
+					await pushEnvelope(fresh, 0);
+				} catch (err) {
+					await undoHold(env.groupId);
+					throw err;
+				}
+				await port(() => Promise.resolve(dlq.ack(p)));
+				stats.queued(env.type, at);
+				emit({
+					kind: "queued",
+					id: env.id,
+					type: env.type,
+					groupId: env.groupId,
+					at
+				});
+				moved += 1;
+			} catch (err) {
+				report(err, "queue");
+			}
+		}
+		return moved;
+	};
+	let running = false;
+	let loopPromise = null;
+	const scheduleCancels = /* @__PURE__ */ new Set();
+	const pollCount = () => {
+		const sources = new Set([globalDoer]);
+		for (const b of registry.values()) if (b.def.batch) sources.add(batcherFor(b.type));
+		else if (b.def.options.doer) sources.add(b.def.options.doer);
+		let n = 0;
+		for (const s of sources) n += s.available();
+		return Math.min(POLL_BATCH_CAP, n);
+	};
+	let pollCursor = 0;
+	const loop = async () => {
+		while (running) try {
+			const pause = (opts.backpressure ? await opts.backpressure({
+				metrics: stats.metrics,
+				active: activeMap.size
+			}) : 0) ?? 0;
+			if (pause > 0) {
+				await sleep(pause);
+				continue;
+			}
+			const n = pollCount();
+			if (n <= 0) {
+				await sleep(pollInterval);
+				continue;
+			}
+			const qs = distinctQueues();
+			const share = Math.max(1, Math.ceil(n / qs.length));
+			let accepted = 0;
+			let anyFull = false;
+			let pulledTotal = 0;
+			for (let i = 0; i < qs.length; i++) {
+				const q = qs[(pollCursor + i) % qs.length];
+				const pulled = await Promise.resolve(q.pop(share, visibility));
+				pulledTotal += pulled.length;
+				if (pulled.length >= share) anyFull = true;
+				const started = await Promise.all(pulled.map((p) => accept(p, q).catch((err) => (report(err, "queue"), false))));
+				accepted += started.filter(Boolean).length;
+			}
+			pollCursor = (pollCursor + 1) % qs.length;
+			if (pulledTotal === 0 && opts.dlq && await redriveFromDLQ() > 0) continue;
+			if (accepted === 0 || !anyFull) await sleep(pollInterval);
+		} catch (err) {
+			report(err, "queue");
+			await sleep(pollInterval);
+		}
+	};
+	registry.set(DEPENDENCY_TYPE, defineWork(DEPENDENCY_TYPE, dependencyHandler, { retry: { attempts: DEP_RETRY_ATTEMPTS } }));
+	const start = () => {
+		if (running) return;
+		running = true;
+		loopPromise = loop();
+	};
+	const stop = async () => {
+		running = false;
+		for (const cancel of scheduleCancels) cancel();
+		scheduleCancels.clear();
+		await loopPromise?.catch(() => {});
+		loopPromise = null;
+		for (const b of batchers.values()) b.flushAll();
+		const drained = Promise.all([...allDoers()].map((d) => d.done())).then(() => void 0);
+		await Promise.race([drained, sleep(STOP_DRAIN)]);
+	};
+	const allDoers = () => {
+		const set = new Set([globalDoer]);
+		for (const b of registry.values()) {
+			const d = b.def.options.doer;
+			if (d) set.add(d);
+		}
+		return set;
+	};
+	const schedule = (config) => {
+		const cancel = startSchedule(config, {
+			store,
+			now,
+			enqueueRaw,
+			prefix,
+			tick: SCHED_TICK,
+			leaseTtl: SCHED_LEASE_TTL
+		});
+		scheduleCancels.add(cancel);
+		return () => {
+			cancel();
+			scheduleCancels.delete(cancel);
+		};
+	};
+	const active = () => [...activeMap.values()].map((a) => ({ ...a }));
+	const api = {
+		enqueue: enqueueImpl,
+		schedule,
+		start,
+		stop,
+		list: () => Promise.resolve([...allStates.values()]),
+		active,
+		stats: () => stats.metrics.list(),
+		metrics: stats.metrics,
+		backend
+	};
+	if (opts.autoStart !== false) start();
+	return api;
+}
+//#endregion
+//#region src/adaptive.ts
+/**
+* Build an {@link AdaptiveDelay} controller for {@link WorkSystemOptions.backpressure}. It holds a
+* little state (the current pause + the last cumulative counts) across calls, so create **one** per
+* work system. Watching a subset of `types` lets one system protect a specific downstream.
+*/
+function adaptiveDelay(opts = {}) {
+	const maxFailRate = opts.maxFailRate ?? 0;
+	const min = opts.min ?? 0;
+	const max = opts.max ?? 3e4;
+	const base = opts.base ?? 100;
+	const factor = opts.factor ?? 2;
+	const step = opts.step ?? base;
+	let delay = min;
+	let prevCompleted = 0;
+	let prevFailed = 0;
+	const watch = opts.types ? new Set(opts.types) : null;
+	return (ctx) => {
+		let succeeded = 0;
+		let failed = 0;
+		for (const s of ctx.metrics.list()) {
+			const type = s.labels.type;
+			if (watch && (type === void 0 || !watch.has(type))) continue;
+			if (s.meta.name === WORK_METRICS.succeeded) succeeded += s.value;
+			else if (s.meta.name === WORK_METRICS.failed) failed += s.value;
+		}
+		const completed = succeeded + failed;
+		const dCompleted = completed - prevCompleted;
+		const dFailed = failed - prevFailed;
+		prevCompleted = completed;
+		prevFailed = failed;
+		if ((dCompleted > 0 ? dFailed / dCompleted : 0) > maxFailRate) delay = Math.min(max, Math.max(base, delay === 0 ? base : delay * factor));
+		else delay = Math.max(min, delay - step);
+		return delay;
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* # @ayepi/work
+*
+* Type-safe distributed work / job-queue + workflow engine. Define work types with
+* {@link defineWork} (each yields a typed, queueable builder), pass them to
+* {@link createWork} as a `const` registry, and `enqueue` is fully checked — by
+* instance or by name. Awaiting a handle resolves to the **group result**; work queued
+* inside a handler joins the same group.
+*
+* Built on three pluggable ports ({@link Queue}/{@link PubSub}/{@link Store}) with an
+* in-memory implementation bundled, so it runs zero-config and scales out by swapping
+* the ports for Redis/SQS/etc. Retries (backoff + jitter, by re-enqueue), batching,
+* non-blocking {@link dependency} gates, cron/fn {@link ScheduleConfig}, distributed
+* wait-for-result, in-process `skipQueue` execution, doers for concurrency/ordering,
+* an orphan-group hook, a JSON codec, and a `logWith` hook are all included.
+*
+* ```ts
+* import { defineWork, createWork } from '@ayepi/work'
+*
+* const add = defineWork('add', (i: { a: number; b: number }) => i.a + i.b)
+* const w = createWork({ work: [add] as const })
+*
+* const sum = await w.enqueue(add({ a: 1, b: 2 })).result() // 3, typed as number
+* await w.stop()
+* ```
+*
+* Bare `import` has **no side effects** — the default instance does not auto-start.
+*
+* @module
+*/
+const instance = createWork({ autoStart: false });
+/** The default (registry-less) work system. Most apps call {@link createWork} with their own registry instead. */
+const work = instance;
+/** Enqueue on the default system (instance form). */
+const enqueue = instance.enqueue;
+/** Register a recurring schedule on the default system. */
+const schedule = instance.schedule;
+/** Start the default system's worker loop. */
+const start = () => instance.start();
+/** Stop the default system. */
+const stop = () => instance.stop();
+/** Snapshot the default system's known work states. */
+const list = () => instance.list();
+//#endregion
+export { DEFAULT_BUCKETS, DEFAULT_RETRY_OPTIONS, DEPENDENCY_TYPE, RetryAbort, WORK_METRICS, WorkDelayError, adaptiveDelay, ageDoer, backoff, balancedDoer, conditionMet, createMetrics, createWork, defaultCodec, defineBatchWork, defineWork, dependency, enqueue, formatPrometheus, getDefaultRetryOptions, list, memoryBackend, memoryPubSub, memoryQueue, memoryStore, nextAfter, parseCron, priorityDoer, retry, schedule, setDefaultRetryOptions, start, stop, unlimitedDoer, work };