@apisurf/ngn-core 0.2.6 → 0.2.8

package/dist/core.js

@@ -133,7 +133,6 @@ __exports;`);
     ...buildGlobals(),
     require: createRequire(requireResolutionRoot),
     // Provide CommonJS-style globals for bundled dependencies that expect them
-    // (e.g., node-cron uses __dirname for its daemon path)
     __dirname: process.cwd(),
     __filename: `${process.cwd()}/vm-script.js`
   });
@@ -314,6 +313,10 @@ var Entry = class {
       return {
         task: taskFunction,
         timing: taskExports.timing,
+        overlap: taskExports.overlap,
+        budget: taskExports.budget,
+        exclusive: taskExports.exclusive,
+        retry: taskExports.retry,
         shouldSkip: taskExports.shouldSkip,
         shouldRetry: taskExports.shouldRetry,
         onSuccess: taskExports.onSuccess,
@@ -342,18 +345,843 @@ var Entry = class {
   }
 };
 
+// src/runtime/duration.ts
+var UNIT_MS = { ms: 1, s: 1e3, m: 6e4, h: 36e5, d: 864e5 };
+function toMs(value, what = "duration") {
+  if (typeof value === "number") {
+    if (Number.isFinite(value) && value >= 0) return value;
+  } else {
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)\s*$/.exec(value);
+    if (match) return Number(match[1]) * UNIT_MS[match[2]];
+  }
+  throw new Error(
+    `Invalid ${what} ${JSON.stringify(value)}: expected milliseconds or a string like "30s", "4m"`
+  );
+}
+
+// src/runtime/runWindow.ts
+function runDeadline({
+  startedAt,
+  scheduledAt,
+  nextAt,
+  budgetMs
+}) {
+  const candidates = [];
+  if (nextAt != null) {
+    const period = nextAt - (scheduledAt ?? startedAt);
+    candidates.push(nextAt - Math.min(5e3, Math.max(0, period) * 0.1));
+  }
+  if (budgetMs != null) candidates.push(startedAt + budgetMs);
+  return candidates.length ? Math.floor(Math.min(...candidates)) : null;
+}
+function deadlineSignal(deadline) {
+  const controller = new AbortController();
+  if (deadline == null) return { signal: controller.signal, dispose: () => {
+  } };
+  const abort = () => controller.abort(new Error("The run reached its deadline"));
+  const delay = deadline - Date.now();
+  if (delay <= 0) {
+    abort();
+    return { signal: controller.signal, dispose: () => {
+    } };
+  }
+  const timer = setTimeout(abort, delay);
+  timer.unref();
+  return { signal: controller.signal, dispose: () => clearTimeout(timer) };
+}
+
+// src/runtime/locks.ts
+var LockBusyError = class extends Error {
+  constructor(lockName) {
+    super(`Lock "${lockName}" is held by another run`);
+    this.lockName = lockName;
+  }
+  name = "LockBusyError";
+};
+var DEFAULT_TTL_MS = 6e4;
+var MAX_POLL_MS = 1e3;
+var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+function assertLockName(name) {
+  if (typeof name !== "string" || !name.trim()) {
+    throw new Error(`A lock name must be a non-empty string, got ${JSON.stringify(name)}`);
+  }
+}
+function createRunLocks(service, taskRunId) {
+  async function tryHold(name, ttlMs) {
+    const holder = await service.tryAcquire(name, ttlMs, taskRunId);
+    if (!holder) return null;
+    const renewal = setInterval(() => {
+      service.renew(name, holder, ttlMs).catch(() => {
+      });
+    }, ttlMs / 3);
+    renewal.unref();
+    return {
+      async release() {
+        clearInterval(renewal);
+        await service.release(name, holder);
+      }
+    };
+  }
+  async function hold(name, ttlMs, waitUntil) {
+    for (let pause = 25; ; pause = Math.min(pause * 2, MAX_POLL_MS)) {
+      const held = await tryHold(name, ttlMs);
+      if (held) return held;
+      const left = waitUntil - Date.now();
+      if (left <= 0) return null;
+      await sleep(Math.min(pause, left));
+    }
+  }
+  return {
+    /** `ctx.lock`: run `fn` holding `name`, released however `fn` ends. */
+    async lock(name, fn, options, deadline) {
+      assertLockName(name);
+      const ttlMs = options.ttl == null ? DEFAULT_TTL_MS : toMs(options.ttl, "lock ttl");
+      const { wait = true } = options;
+      const waitUntil = wait === true ? deadline ?? Number.POSITIVE_INFINITY : wait === false ? Date.now() : Date.now() + toMs(wait, "lock wait");
+      const held = await hold(name, ttlMs, waitUntil);
+      if (!held) throw new LockBusyError(name);
+      try {
+        return await fn();
+      } finally {
+        await held.release();
+      }
+    },
+    /**
+     * Take every lock in `names` without waiting, for `exclusive`. Names are
+     * taken in sorted order so two runs asking for overlapping sets cannot
+     * each hold half. If any is busy, the ones already taken are given back.
+     */
+    async holdAll(names) {
+      const taken = [];
+      const releaseAll = async () => {
+        await Promise.all(taken.map((held) => held.release()));
+      };
+      for (const name of [...new Set(names)].toSorted()) {
+        const held = await tryHold(name, DEFAULT_TTL_MS);
+        if (!held) {
+          await releaseAll();
+          return { busy: name };
+        }
+        taken.push(held);
+      }
+      return { release: releaseAll };
+    }
+  };
+}
+function exclusiveNames(value, taskPath) {
+  if (value == null) return [];
+  const names = Array.isArray(value) ? value : [value];
+  for (const name of names) {
+    if (typeof name !== "string" || !name.trim()) {
+      throw new Error(
+        `Invalid exclusive for ${taskPath}: expected a lock name or a list of them, got ${JSON.stringify(value)}`
+      );
+    }
+  }
+  return names;
+}
+
+// src/runtime/taskSqlite.ts
+import { mkdirSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, resolve, sep } from "node:path";
+import {
+  openDbClient
+} from "@apisurf/ngn-persistence";
+var openClients = /* @__PURE__ */ new Map();
+async function runMigrations(client, migrations) {
+  if (!migrations.length) return;
+  await client.execute(`
+    CREATE TABLE IF NOT EXISTS _ngn_migrations (
+      id TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL
+    )
+  `);
+  const applied = await client.execute("SELECT id FROM _ngn_migrations");
+  const appliedIds = new Set(applied.rows.map((r) => r.id));
+  for (const migration of migrations) {
+    if (appliedIds.has(migration.id)) continue;
+    await client.execute(migration.up);
+    await client.execute({
+      sql: "INSERT INTO _ngn_migrations (id, applied_at) VALUES (?, ?)",
+      args: [migration.id, (/* @__PURE__ */ new Date()).toISOString()]
+    });
+  }
+}
+function resolveTaskDbPath(taskDir, file) {
+  if (typeof file !== "string" || !file.trim()) {
+    throw new Error("A database file name is required");
+  }
+  const relativePath = file.startsWith("file:") ? file.slice(5) : file;
+  if (!relativePath) {
+    throw new Error("A database file name is required");
+  }
+  if (isAbsolute(relativePath)) {
+    throw new Error(
+      `Database file must be relative to the task folder, got an absolute path: "${file}"`
+    );
+  }
+  const resolved = resolve(taskDir, relativePath);
+  const taskDirRoot = taskDir.endsWith(sep) ? taskDir : `${taskDir}${sep}`;
+  if (!resolved.startsWith(taskDirRoot)) {
+    throw new Error(
+      `Database file "${file}" resolves outside the task folder (${taskDir}). A task can only manage databases in its own folder.`
+    );
+  }
+  return resolved;
+}
+function getClient(absolutePath) {
+  const existing = openClients.get(absolutePath);
+  if (existing) {
+    return existing;
+  }
+  mkdirSync(dirname(absolutePath), { recursive: true });
+  const client = openDbClient(`file:${absolutePath}`);
+  openClients.set(absolutePath, client);
+  return client;
+}
+function closeClient(absolutePath) {
+  const client = openClients.get(absolutePath);
+  if (client) {
+    client.close();
+    openClients.delete(absolutePath);
+  }
+}
+function createTaskSqlite(taskSourcePath) {
+  const taskDir = dirname(taskSourcePath);
+  const defaultDbPath = join(taskDir, `${basename(taskSourcePath, extname(taskSourcePath))}.db`);
+  const defaultClient = () => getClient(defaultDbPath);
+  return {
+    get client() {
+      return defaultClient();
+    },
+    get path() {
+      return defaultDbPath;
+    },
+    execute: (sql, args) => defaultClient().execute(args ? { sql, args } : sql),
+    batch: (statements) => defaultClient().batch(statements),
+    async initDB(options) {
+      const dbPath = resolveTaskDbPath(taskDir, options.file);
+      const client = getClient(dbPath);
+      if (options.migrations?.length) {
+        await runMigrations(client, options.migrations);
+      }
+      return {
+        client,
+        path: dbPath,
+        execute: (sql, args) => client.execute(args ? { sql, args } : sql),
+        batch: (statements) => client.batch(statements),
+        close: () => closeClient(dbPath)
+      };
+    },
+    async destroyDB(file) {
+      const dbPath = resolveTaskDbPath(taskDir, file);
+      closeClient(dbPath);
+      await unlink(dbPath);
+    }
+  };
+}
+function closeTaskDatabases() {
+  for (const client of openClients.values()) {
+    client.close();
+  }
+  openClients.clear();
+}
+
+// src/runtime/queue/schema.ts
+var QUEUE_MIGRATIONS = [
+  {
+    id: "ngn-queue-0001",
+    up: `CREATE TABLE IF NOT EXISTS _ngn_jobs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      queue TEXT NOT NULL,
+      key TEXT,
+      grp TEXT,
+      payload TEXT,
+      priority INTEGER NOT NULL DEFAULT 0,
+      status TEXT NOT NULL DEFAULT 'ready',
+      attempts INTEGER NOT NULL DEFAULT 0,
+      max_attempts INTEGER NOT NULL,
+      run_after INTEGER NOT NULL,
+      lease_until INTEGER,
+      last_error TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE (queue, key)
+    )`
+  },
+  {
+    id: "ngn-queue-0002",
+    up: "CREATE INDEX IF NOT EXISTS _ngn_jobs_claim_idx ON _ngn_jobs (queue, status, run_after)"
+  }
+];
+
+// src/runtime/queue/work.ts
+function untilSignal(until) {
+  if (until === void 0) return new AbortController().signal;
+  if (typeof until !== "number") return until;
+  const left = until - Date.now();
+  return left <= 0 ? AbortSignal.abort() : AbortSignal.timeout(left);
+}
+var WorkRun = class {
+  constructor(queue, handler, options) {
+    this.queue = queue;
+    this.handler = handler;
+    this.options = options;
+    this.signal = untilSignal(options.until);
+    this.concurrency = Math.max(1, Math.floor(options.concurrency ?? 1));
+    this.max = options.max ?? Number.POSITIVE_INFINITY;
+  }
+  buffer = [];
+  /** Groups with a job buffered or being worked. */
+  busyGroups = /* @__PURE__ */ new Set();
+  stopped = /* @__PURE__ */ new Set();
+  perGroupCount = /* @__PURE__ */ new Map();
+  capped = /* @__PURE__ */ new Set();
+  /**
+   * Every job this call has claimed. Never claimed twice: without a next tick
+   * to back off to (run:once), a failed or released job is due again at once,
+   * and the call would spend all its attempts in one go.
+   */
+  seen = /* @__PURE__ */ new Set();
+  signal;
+  concurrency;
+  max;
+  claiming = null;
+  claimed = 0;
+  working = 0;
+  /** Workers waiting for a job in hand to finish and free its group. */
+  waiting = [];
+  stoppedBy = "empty";
+  /** Set when a worker breaks: the others finish what they hold and stop. */
+  broken = false;
+  tally = { done: 0, failed: 0, dead: 0, released: 0 };
+  async run() {
+    const workers = Array.from({ length: this.concurrency }, (_, index) => this.worker(index));
+    try {
+      const results = await Promise.allSettled(workers);
+      const failure = results.find((result) => result.status === "rejected");
+      if (failure) throw failure.reason;
+    } finally {
+      await this.releaseJobs(this.buffer.splice(0), { kind: "release" });
+    }
+    const stats = await this.queue.stats();
+    return {
+      ...this.tally,
+      remaining: stats.due,
+      oldestAgeMs: stats.oldestReadyAgeMs,
+      stoppedGroups: [...this.stopped],
+      stoppedBy: this.stoppedBy
+    };
+  }
+  shouldStop() {
+    if (this.broken) return true;
+    if (this.signal.aborted) this.stoppedBy = "deadline";
+    return this.signal.aborted;
+  }
+  /**
+   * The next job for a worker: one from the buffer, refilled when empty.
+   * `"empty"` when nothing is claimable and no job in hand could change that;
+   * null to ask again (after a refill, a wait, or a job put back).
+   */
+  async nextJob() {
+    const job = this.buffer.shift();
+    if (job && this.atCap(job.group)) {
+      this.capped.add(job.group);
+      await this.releaseJobs([job], { kind: "release" });
+      return null;
+    }
+    if (job) return job;
+    if (await this.refill()) return null;
+    if (this.working === 0) return "empty";
+    await new Promise((resolve2) => this.waiting.push(resolve2));
+    return null;
+  }
+  async worker(index) {
+    let resource = null;
+    try {
+      for (; ; ) {
+        if (this.shouldStop()) return;
+        const job = await this.nextJob();
+        if (job === "empty") return;
+        if (!job) continue;
+        try {
+          resource ??= { value: await this.options.worker?.setup?.(index) };
+        } catch (error) {
+          this.buffer.unshift(job);
+          throw error;
+        }
+        await this.work(job, index, resource.value);
+      }
+    } catch (error) {
+      this.broken = true;
+      throw error;
+    } finally {
+      if (resource) await this.options.worker?.teardown?.(resource.value, index);
+    }
+  }
+  /** Claim up to one job per free worker. Shared by workers that ask at once. */
+  refill() {
+    this.claiming ??= this.claim().finally(() => this.claiming = null);
+    return this.claiming;
+  }
+  async claim() {
+    const room = Math.min(this.concurrency, this.max - this.claimed);
+    if (room <= 0) {
+      this.stoppedBy = "max";
+      return 0;
+    }
+    const jobs = await this.queue.claim({
+      limit: room,
+      perGroup: 1,
+      skipGroups: [...this.busyGroups, ...this.stopped, ...this.capped],
+      skipIds: [...this.seen]
+    });
+    this.claimed += jobs.length;
+    for (const job of jobs) {
+      this.seen.add(job.id);
+      if (job.group != null) this.busyGroups.add(job.group);
+      this.buffer.push(job);
+    }
+    if (this.claimed >= this.max) this.stoppedBy = "max";
+    return jobs.length;
+  }
+  async work(job, index, resource) {
+    this.working++;
+    this.countForGroup(job.group);
+    let settle = null;
+    const handle = {
+      index,
+      resource,
+      signal: this.signal,
+      release: (options = {}) => {
+        settle ??= { kind: "release", ...options };
+      },
+      stopGroup: (options = {}) => {
+        settle ??= { kind: "stopGroup", ...options };
+      }
+    };
+    try {
+      try {
+        await this.handler(job, handle);
+        const asked = settle;
+        if (asked) await this.settleAsked(job, asked);
+        else if (await this.queue.complete(job)) this.tally.done++;
+      } catch (error) {
+        await this.failJob(job, error);
+      }
+    } finally {
+      if (job.group != null) this.busyGroups.delete(job.group);
+      this.working--;
+      for (const resolve2 of this.waiting.splice(0)) resolve2();
+    }
+  }
+  async failJob(job, error) {
+    if (!await this.queue.fail(job, error)) return;
+    this.tally.failed++;
+    if (job.attempts >= job.maxAttempts) this.tally.dead++;
+  }
+  async settleAsked(job, settle) {
+    if (settle.kind === "stopGroup" && job.group != null) {
+      this.stopped.add(job.group);
+      const rest = this.buffer.filter((other) => other.group === job.group);
+      const keep = this.buffer.filter((other) => other.group !== job.group);
+      this.buffer.splice(0, this.buffer.length, ...keep);
+      await this.releaseJobs(rest, settle);
+    }
+    await this.releaseJobs([job], settle);
+  }
+  async releaseJobs(jobs, { delay, refund }) {
+    for (const job of jobs) {
+      if (await this.queue.release(job, { delay, refund })) this.tally.released++;
+      if (job.group != null) this.busyGroups.delete(job.group);
+    }
+  }
+  groupLimit(group) {
+    const { perGroup } = this.options;
+    if (perGroup == null) return Number.POSITIVE_INFINITY;
+    return typeof perGroup === "function" ? perGroup(group) : perGroup;
+  }
+  atCap(group) {
+    return group != null && (this.perGroupCount.get(group) ?? 0) >= this.groupLimit(group);
+  }
+  countForGroup(group) {
+    if (group == null) return;
+    const count = (this.perGroupCount.get(group) ?? 0) + 1;
+    this.perGroupCount.set(group, count);
+    if (count >= this.groupLimit(group)) this.capped.add(group);
+  }
+};
+function work(queue, handler, options) {
+  return new WorkRun(queue, handler, options).run();
+}
+
+// src/runtime/queue/queue.ts
+var DEFAULT_MAX_ATTEMPTS = 3;
+var DEFAULT_LEASE_MS = 10 * 6e4;
+var MAX_ERROR_LENGTH = 2e3;
+var placeholders = (n) => Array.from({ length: n }, () => "?").join(", ");
+var asList = (value) => typeof value === "string" ? [value] : value;
+function toJob(row) {
+  return {
+    id: row.id,
+    key: row.key,
+    group: row.grp,
+    payload: row.payload == null ? void 0 : JSON.parse(row.payload),
+    priority: row.priority,
+    attempts: row.attempts,
+    maxAttempts: row.max_attempts,
+    lastError: row.last_error,
+    createdAt: row.created_at
+  };
+}
+function errorText(error) {
+  const text = error instanceof Error ? error.message : String(error);
+  return text.slice(0, MAX_ERROR_LENGTH);
+}
+function filterSql(filter) {
+  const parts = [];
+  const args = [];
+  if (filter.group != null) {
+    const groups = asList(filter.group);
+    parts.push(groups.length ? `grp IN (${placeholders(groups.length)})` : "0");
+    args.push(...groups);
+  }
+  if (filter.groupNotIn?.length) {
+    parts.push(`(grp IS NULL OR grp NOT IN (${placeholders(filter.groupNotIn.length)}))`);
+    args.push(...filter.groupNotIn);
+  }
+  if (filter.key != null) {
+    const keys = asList(filter.key);
+    parts.push(keys.length ? `key IN (${placeholders(keys.length)})` : "0");
+    args.push(...keys);
+  }
+  return { sql: parts.length ? ` AND ${parts.join(" AND ")}` : "", args };
+}
+var Queue = class {
+  constructor(client, name, options, run) {
+    this.client = client;
+    this.name = name;
+    this.options = options;
+    this.run = run;
+    this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    this.leaseMs = options.lease == null ? DEFAULT_LEASE_MS : toMs(options.lease, "queue lease");
+    if (!Number.isInteger(this.maxAttempts) || this.maxAttempts < 1) {
+      throw new Error(`Invalid maxAttempts for queue "${name}": expected a whole number above 0`);
+    }
+  }
+  maxAttempts;
+  leaseMs;
+  /**
+   * The INSERT for one job, to run in your own `batch` beside the row the job
+   * is about. A key already in the queue makes it a no-op.
+   */
+  addStatement(job) {
+    const now = Date.now();
+    return {
+      sql: `INSERT INTO _ngn_jobs
+              (queue, key, grp, payload, priority, status, attempts, max_attempts, run_after, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, 'ready', 0, ?, ?, ?, ?)
+            ON CONFLICT (queue, key) DO NOTHING`,
+      args: [
+        this.name,
+        job.key ?? null,
+        job.group ?? null,
+        job.payload === void 0 ? null : JSON.stringify(job.payload),
+        job.priority ?? 0,
+        job.maxAttempts ?? this.maxAttempts,
+        now + (job.delay == null ? 0 : toMs(job.delay, "job delay")),
+        now,
+        now
+      ]
+    };
+  }
+  /** Add one job or several. Returns how many were new; the rest had keys already queued. */
+  async add(jobs) {
+    const list = Array.isArray(jobs) ? jobs : [jobs];
+    if (list.length === 0) return 0;
+    const results = await this.client.batch(
+      list.map((job) => this.addStatement(job)),
+      "write"
+    );
+    return results.reduce((sum, result) => sum + result.rowsAffected, 0);
+  }
+  /**
+   * Take up to `limit` jobs that are due, counting an attempt on each and
+   * leasing them for the queue's `lease`.
+   *
+   * With groups, the jobs are drawn a group at a time: every group's first job
+   * before any group's second, groups in a fresh random order each claim. So
+   * a claim spreads over as many groups as it can, and when `limit` cuts a
+   * round short it is not always the same groups left out.
+   */
+  async claim({ limit, perGroup, skipGroups = [], skipIds = [] }) {
+    if (limit <= 0) return [];
+    const now = Date.now();
+    const skip = skipGroups.length ? `AND (grp IS NULL OR grp NOT IN (${placeholders(skipGroups.length)}))` : "";
+    const [, claimed] = await this.client.batch(
+      [
+        this.retireStatement(now),
+        {
+          sql: `UPDATE _ngn_jobs
+                SET status = 'leased', lease_until = ?, attempts = attempts + 1, updated_at = ?
+                WHERE id IN (
+                  SELECT id FROM (
+                    SELECT id, grp, priority, run_after,
+                           ROW_NUMBER() OVER (
+                             PARTITION BY COALESCE(grp, 'id:' || id)
+                             ORDER BY priority DESC, run_after, id
+                           ) AS turn
+                    FROM _ngn_jobs
+                    WHERE queue = ?
+                      AND attempts < max_attempts
+                      AND ((status = 'ready' AND run_after <= ?)
+                        OR (status = 'leased' AND lease_until <= ?))
+                      ${skip}
+                      AND id NOT IN (SELECT value FROM json_each(?))
+                  )
+                  WHERE turn <= ?
+                  ORDER BY turn, CASE WHEN grp IS NULL THEN NULL ELSE random() END,
+                           priority DESC, run_after, id
+                  LIMIT ?
+                )
+                RETURNING *`,
+          args: [
+            now + this.leaseMs,
+            now,
+            this.name,
+            now,
+            now,
+            ...skipGroups,
+            // One JSON parameter however many ids, rather than one per id.
+            JSON.stringify(skipIds),
+            perGroup ?? Number.MAX_SAFE_INTEGER,
+            limit
+          ]
+        }
+      ],
+      "write"
+    );
+    return claimed.rows.toSorted((a, b) => b.priority - a.priority || a.run_after - b.run_after || a.id - b.id).map((row) => toJob(row));
+  }
+  /**
+   * Jobs whose lease ran out on their last attempt: no claim will take them
+   * again, so they are marked `dead` rather than left looking leased forever.
+   */
+  retireStatement(now) {
+    return {
+      sql: `UPDATE _ngn_jobs
+            SET status = 'dead', lease_until = NULL, updated_at = ?,
+                last_error = COALESCE(last_error, 'lease expired')
+            WHERE queue = ? AND status = 'leased' AND lease_until <= ? AND attempts >= max_attempts`,
+      args: [now, this.name, now]
+    };
+  }
+  /**
+   * Settle a claimed job, if the claim is still ours: same job, same attempt,
+   * still leased. False when the lease expired and the job moved on.
+   */
+  async settle(job, set, args) {
+    const { rowsAffected } = await this.client.execute({
+      sql: `UPDATE _ngn_jobs SET ${set}, updated_at = ?
+            WHERE id = ? AND queue = ? AND status = 'leased' AND attempts = ?`,
+      args: [...args, Date.now(), job.id, this.name, job.attempts]
+    });
+    return rowsAffected > 0;
+  }
+  /** The job is finished. */
+  complete(job) {
+    return this.settle(job, "status = 'done', lease_until = NULL, last_error = NULL", []);
+  }
+  /**
+   * The attempt failed. The job backs off and is tried again, or is `dead`
+   * once it has had all its attempts. `delay` overrides the backoff.
+   */
+  fail(job, error, { delay } = {}) {
+    const runAfter = Date.now() + (delay == null ? this.backoffMs(job.attempts) : toMs(delay));
+    return this.settle(
+      job,
+      `status = CASE WHEN attempts >= max_attempts THEN 'dead' ELSE 'ready' END,
+       lease_until = NULL, last_error = ?, run_after = ?`,
+      [errorText(error), runAfter]
+    );
+  }
+  /**
+   * Hand a claimed job back unworked. By default the attempt is refunded: for
+   * a job that never got a fair try, such as a site that walled the run.
+   */
+  release(job, { delay, refund = true } = {}) {
+    const runAfter = Date.now() + (delay == null ? 0 : toMs(delay));
+    return this.settle(
+      job,
+      `status = 'ready', lease_until = NULL, run_after = ?,
+       attempts = ${refund ? "MAX(attempts - 1, 0)" : "attempts"}`,
+      [runAfter]
+    );
+  }
+  /** How long a job that just failed its `attempts`th attempt waits. */
+  backoffMs(attempts) {
+    const { backoff = "next-tick" } = this.options;
+    if (backoff === "next-tick") {
+      const { nextAt } = this.run;
+      return nextAt == null ? 0 : Math.max(0, nextAt - Date.now());
+    }
+    if (typeof backoff === "object") {
+      const base = toMs(backoff.base, "backoff base");
+      const max = backoff.max == null ? Number.POSITIVE_INFINITY : toMs(backoff.max, "backoff max");
+      return Math.min(max, base * 2 ** Math.max(0, attempts - 1));
+    }
+    return toMs(backoff, "backoff");
+  }
+  /**
+   * Set ready jobs aside, e.g. ones no handler can read yet. Parked jobs are
+   * never claimed until `reopen`. Returns how many were parked.
+   */
+  async park(filter, reason) {
+    const where = filterSql(filter);
+    const { rowsAffected } = await this.client.execute({
+      sql: `UPDATE _ngn_jobs SET status = 'parked', last_error = COALESCE(?, last_error), updated_at = ?
+            WHERE queue = ? AND status = 'ready'${where.sql}`,
+      args: [reason ?? null, Date.now(), this.name, ...where.args]
+    });
+    return rowsAffected;
+  }
+  /**
+   * Make jobs ready again with their attempts reset: parked ones by default,
+   * or any of `from`, e.g. `["dead"]` to retry what gave up.
+   */
+  async reopen(filter = {}, { from = ["parked"] } = {}) {
+    if (from.length === 0) return 0;
+    const where = filterSql(filter);
+    const now = Date.now();
+    const { rowsAffected } = await this.client.execute({
+      sql: `UPDATE _ngn_jobs SET status = 'ready', attempts = 0, run_after = ?, updated_at = ?
+            WHERE queue = ? AND status IN (${placeholders(from.length)})${where.sql}`,
+      args: [now, now, this.name, ...from, ...where.args]
+    });
+    return rowsAffected;
+  }
+  /**
+   * Delete finished jobs last touched more than `olderThan` ago, `done` ones by
+   * default. A pruned key can be added again.
+   */
+  async prune({
+    olderThan,
+    status = ["done"]
+  }) {
+    if (status.length === 0) return 0;
+    const { rowsAffected } = await this.client.execute({
+      sql: `DELETE FROM _ngn_jobs
+            WHERE queue = ? AND status IN (${placeholders(status.length)}) AND updated_at < ?`,
+      args: [this.name, ...status, Date.now() - toMs(olderThan, "prune age")]
+    });
+    return rowsAffected;
+  }
+  /**
+   * Work through the queue until it is empty, `max` is reached or the run's
+   * deadline passes, `concurrency` jobs at a time and never two of one group
+   * at once. A handler that returns completes its job; one that throws fails
+   * it. Whatever is left waits for the next run.
+   */
+  // NoInfer: the resource type comes from `worker.setup`, not from the handler's parameter.
+  work(handler, options = {}) {
+    return work(this, handler, { until: this.run.signal, ...options });
+  }
+  /** The job with `key`, in whatever state it is in. */
+  async get(key) {
+    const { rows } = await this.client.execute({
+      sql: "SELECT * FROM _ngn_jobs WHERE queue = ? AND key = ?",
+      args: [this.name, key]
+    });
+    const row = rows[0];
+    return row ? { ...toJob(row), status: row.status } : null;
+  }
+  async stats() {
+    const now = Date.now();
+    const { rows } = await this.client.execute({
+      sql: `SELECT
+              COUNT(*) FILTER (WHERE status = 'ready')                       AS ready,
+              COUNT(*) FILTER (WHERE status = 'ready' AND run_after <= ?)    AS due,
+              COUNT(*) FILTER (WHERE status = 'leased')                      AS leased,
+              COUNT(*) FILTER (WHERE status = 'done')                        AS done,
+              COUNT(*) FILTER (WHERE status = 'dead')                        AS dead,
+              COUNT(*) FILTER (WHERE status = 'parked')                      AS parked,
+              MIN(created_at) FILTER (WHERE status = 'ready')                AS oldest
+            FROM _ngn_jobs WHERE queue = ?`,
+      args: [now, this.name]
+    });
+    const row = rows[0];
+    return {
+      ready: Number(row.ready),
+      due: Number(row.due),
+      leased: Number(row.leased),
+      done: Number(row.done),
+      dead: Number(row.dead),
+      parked: Number(row.parked),
+      oldestReadyAgeMs: row.oldest == null ? null : now - Number(row.oldest)
+    };
+  }
+};
+async function openQueue(client, name, options, run) {
+  if (typeof name !== "string" || !name.trim()) {
+    throw new Error(`A queue name must be a non-empty string, got ${JSON.stringify(name)}`);
+  }
+  await runMigrations(client, QUEUE_MIGRATIONS);
+  return new Queue(client, name, options, run);
+}
+
+// src/runtime/retry.ts
+var DEFAULT_MAX_SKIP = 32;
+var isCount = (value) => typeof value === "number" && Number.isInteger(value) && value >= 1;
+function resolveRetry(value, taskPath) {
+  if (value == null) return { attempts: 1, delayMs: 0, breaker: null };
+  const fail = (what) => {
+    throw new Error(`Invalid retry for ${taskPath}: ${what}`);
+  };
+  if (typeof value !== "object") fail('expected an object like { attempts: 3, delay: "30s" }');
+  const { attempts = 1, delay = 0, breaker } = value;
+  if (!isCount(attempts)) fail("attempts must be a whole number above 0");
+  if (breaker != null) {
+    if (!isCount(breaker.after)) fail("breaker.after must be a whole number above 0");
+    if (breaker.maxSkip != null && !isCount(breaker.maxSkip)) {
+      fail("breaker.maxSkip must be a whole number above 0");
+    }
+  }
+  return {
+    attempts,
+    delayMs: toMs(delay, `retry delay for ${taskPath}`),
+    breaker: breaker ? { after: breaker.after, maxSkip: breaker.maxSkip ?? DEFAULT_MAX_SKIP } : null
+  };
+}
+function retryFits({
+  attempt,
+  retry,
+  nextAt,
+  now = Date.now()
+}) {
+  if (attempt >= retry.attempts) return false;
+  return nextAt == null || now + retry.delayMs < nextAt;
+}
+var BREAKER_SKIP_REASON = "circuit open after repeated failures";
+function breakerSkips(failedInARow, breaker) {
+  if (!breaker || failedInARow < breaker.after) return 0;
+  return Math.min(breaker.maxSkip, 2 ** (failedInARow - breaker.after));
+}
+
 // src/runtime/task.ts
+var sleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 var Task = class {
   taskCallbacks;
-  runtimeCallbacks;
+  startRun;
+  history;
   env;
   kv;
-  log;
-  timing;
   sqlite;
   meta;
   entry = null;
   entryExports = null;
+  /** Executions started and not yet settled. */
+  inFlight = 0;
   constructor({
     entryParams,
     buildConfigFn
@@ -362,12 +1190,13 @@ var Task = class {
     this.entry = new Entry(entryParams, {
       onTaskCodeLoaded: this.taskCallbacks?.onTaskCodeLoaded
     });
-    const { taskCallbacks, runtimeCallbacks, env, kv, log, timing, sqlite } = buildConfigFn({
+    const { taskCallbacks, startRun, history, env, kv, sqlite } = buildConfigFn({
       sourcePath: this.entry.paths.source,
       compiledPath: this.entry.paths.compiled
     });
     this.taskCallbacks = taskCallbacks;
-    this.runtimeCallbacks = runtimeCallbacks;
+    this.startRun = startRun;
+    this.history = history;
     this.sqlite = sqlite;
     this.meta = {
       fileTaskId: -1,
@@ -377,8 +1206,6 @@ var Task = class {
     };
     this.env = env;
     this.kv = kv;
-    this.log = log;
-    this.timing = timing;
   }
   get sourcePath() {
     invariant5(this.entry, "Entry not initialized.");
@@ -403,6 +1230,45 @@ var Task = class {
     invariant5(this.entryExports, "Entry exports not initialized.");
     return this.entryExports.timing;
   }
+  /**
+   * The task's `overlap` export, `"skip"` when it has none. Throws on anything
+   * else, naming the task, so a typo fails at schedule time.
+   */
+  get overlapPolicy() {
+    invariant5(this.entryExports, "Entry exports not initialized.");
+    const { overlap = "skip" } = this.entryExports;
+    invariant5(
+      overlap === "skip" || overlap === "allow",
+      `Invalid overlap "${String(overlap)}" for ${this.taskPath}: expected "skip" or "allow"`
+    );
+    return overlap;
+  }
+  /**
+   * Check the exports that shape how the task is scheduled, so a bad value
+   * fails when the task is scheduled rather than on its first tick.
+   */
+  validateExports() {
+    invariant5(this.entryExports, "Entry exports not initialized.");
+    void this.overlapPolicy;
+    const { budget, exclusive, retry } = this.entryExports;
+    if (budget != null) toMs(budget, `budget for ${this.taskPath}`);
+    exclusiveNames(exclusive, this.taskPath);
+    resolveRetry(retry, this.taskPath);
+  }
+  /** Whether an execution of this task is in progress. */
+  get isRunning() {
+    return this.inFlight > 0;
+  }
+  /**
+   * Record a run that ngn decided not to start, without loading or calling any
+   * of the task's code. Needs the task to have been registered by an earlier
+   * execution, which is always so for a run skipped because one is in progress.
+   */
+  async skip(reason) {
+    invariant5(this.entry, "Entry not initialized.");
+    const run = await this.startRun();
+    await run.callbacks.onSkip?.({ path: this.entry.paths.relativeEntry, reason });
+  }
   hasTaskExport() {
     return this.entryExports?.task !== void 0;
   }
@@ -416,68 +1282,174 @@ var Task = class {
   }
   async loadAndRegister() {
     invariant5(this.entry, "Entry not initialized.");
-    try {
-      await this.loadEntry();
-      invariant5(this.entry.isLoaded(), "Entry failed to load.");
-      invariant5(this.entryExports, "Entry failed to get exports.");
-      this.taskCallbacks?.onTaskExportsLoaded?.();
-      const loadResult = await this.taskCallbacks?.onTaskLoadComplete?.({
-        paths: this.entry.paths,
-        md5Hash: this.entry.codeHash,
-        compiledCode: this.entry.code
-      });
-      this.meta.fileTaskId = loadResult?.fileTaskId ?? -1;
-      this.meta.fileTaskVersionId = loadResult?.fileTaskVersionId ?? -1;
-    } catch (error) {
-      if (this.entry.paths.relativeEntry) {
-        await this.runtimeCallbacks?.onFailure?.({
-          path: this.entry.paths.relativeEntry
-        });
-      }
-      throw error;
-    }
+    await this.loadEntry();
+    invariant5(this.entry.isLoaded(), "Entry failed to load.");
+    invariant5(this.entryExports, "Entry failed to get exports.");
+    this.taskCallbacks?.onTaskExportsLoaded?.();
+    const loadResult = await this.taskCallbacks?.onTaskLoadComplete?.({
+      paths: this.entry.paths,
+      md5Hash: this.entry.codeHash,
+      compiledCode: this.entry.code
+    });
+    this.meta.fileTaskId = loadResult?.fileTaskId ?? -1;
+    this.meta.fileTaskVersionId = loadResult?.fileTaskVersionId ?? -1;
   }
-  async runTask(task, taskContext, hooks) {
+  async runTask(task, taskContext, hooks, run) {
     invariant5(this.entry, "Entry not initialized.");
     const path = this.entry.paths.relativeEntry;
     try {
-      await this.runtimeCallbacks?.onStart?.({ path });
+      await run.callbacks.onStart?.({ path });
       const taskReturnValue = await task(taskContext);
-      await this.runtimeCallbacks?.onSuccess?.({ path });
+      await run.callbacks.onSuccess?.({ path, result: taskReturnValue });
       await hooks.onSuccess?.(taskContext);
       return taskReturnValue;
     } catch (err) {
-      await this.runtimeCallbacks?.onFailure?.({ path });
+      await run.callbacks.onFailure?.({ path });
       await hooks.onError?.(err, taskContext);
       throw err;
     } finally {
       await hooks.onComplete?.(taskContext);
     }
   }
-  async execute() {
+  /**
+   * Run the task for one tick, retrying as its `retry` export allows. A
+   * scheduled tick passes when it fired and when the next one is due, which
+   * `ctx.run.deadline` and the retry window are worked out from.
+   */
+  async execute(schedule = {}) {
+    this.inFlight++;
+    try {
+      return await this.executeWithRetries(schedule);
+    } finally {
+      this.inFlight--;
+    }
+  }
+  async executeWithRetries(schedule) {
+    const tick2 = {
+      firstRunId: null,
+      retry: resolveRetry(void 0, this.taskPath),
+      failedContext: null
+    };
+    for (let attempt = 1; ; attempt++) {
+      tick2.failedContext = null;
+      try {
+        return await this.executeOnce(schedule, tick2);
+      } catch (error) {
+        if (!await this.shouldRetry(error, attempt, schedule, tick2)) throw error;
+        await sleep2(tick2.retry.delayMs);
+      }
+    }
+  }
+  /**
+   * Retry only a run that got as far as running: a module that will not load
+   * fails the same way every time. Then it has to fit before the next tick,
+   * and the task's `shouldRetry` gets the last word.
+   */
+  async shouldRetry(error, attempt, { nextAt = null }, tick2) {
+    if (!tick2.failedContext || !retryFits({ attempt, retry: tick2.retry, nextAt })) return false;
+    const { shouldRetry } = this.entryExports ?? {};
+    return shouldRetry ? await shouldRetry(error, tick2.failedContext) !== false : true;
+  }
+  /**
+   * Whether the breaker holds this tick back: after `after` failed ticks in a
+   * row it skips 1, 2, 4… ticks (counted since the latest failure), letting
+   * one through in between to see whether things have recovered.
+   */
+  async breakerOpen(retry) {
+    if (!retry.breaker) return false;
+    const outcomes = await this.history.recentTickOutcomes(retry.breaker.after + 64);
+    const failedInARow = outcomes.findIndex((tick2) => tick2.outcome !== "failure");
+    const wanted = breakerSkips(
+      failedInARow === -1 ? outcomes.length : failedInARow,
+      retry.breaker
+    );
+    if (wanted === 0) return false;
+    return await this.history.countSkipsSince(BREAKER_SKIP_REASON, outcomes[0].id) < wanted;
+  }
+  /**
+   * Why ngn will not start this run, or null. Checked in order: the breaker
+   * (scheduled first attempts only), then the `exclusive` locks, which are
+   * left held on success.
+   */
+  async holdBack(run, {
+    firstAttempt,
+    scheduled,
+    exclusiveLocks,
+    retry
+  }) {
+    if (firstAttempt && scheduled && await this.breakerOpen(retry)) {
+      return { reason: BREAKER_SKIP_REASON };
+    }
+    if (!exclusiveLocks.length) return { held: null };
+    const held = await run.locks.holdAll(exclusiveLocks);
+    return "busy" in held ? { reason: `lock "${held.busy}" is held` } : { held };
+  }
+  buildContext(run, meta, window, signal) {
+    const { scheduledAt, nextAt, deadline } = window;
+    return {
+      env: this.env,
+      meta,
+      kv: this.kv,
+      log: run.log,
+      timing: run.timing,
+      sqlite: this.sqlite,
+      run: { id: run.id, scheduledAt, nextAt, deadline, signal },
+      lock: (name, fn, options = {}) => run.locks.lock(name, fn, options, deadline),
+      queue: (name, options = {}) => openQueue(options.db?.client ?? this.sqlite.client, name, options, { nextAt, signal })
+    };
+  }
+  async executeOnce({ scheduledAt = null, nextAt = null }, tick2) {
     invariant5(this.entry, "Entry not initialized.");
     await this.loadAndRegister();
     invariant5(this.entryExports, "Entry failed to get exports.");
-    await this.taskCallbacks?.onTaskExecutionStart?.();
-    const { shouldSkip, onSuccess, onError, onComplete, task } = this.entryExports;
+    const exports = this.entryExports;
+    const meta = { ...this.meta };
     const path = this.entry.paths.relativeEntry;
-    if (!task) {
-      await this.runtimeCallbacks?.onNotFound?.({ path });
+    const budgetMs = exports.budget == null ? null : toMs(exports.budget, `budget for ${path}`);
+    const exclusiveLocks = exclusiveNames(exports.exclusive, path);
+    const retry = resolveRetry(exports.retry, path);
+    tick2.retry = retry;
+    const run = await this.startRun({ retryOf: tick2.firstRunId });
+    const firstAttempt = tick2.firstRunId == null;
+    tick2.firstRunId ??= run.id;
+    if (!exports.task) {
+      await run.callbacks.onNotFound?.({ path });
       throw new Error("Task function not found");
     }
-    const taskContext = {
-      env: this.env,
-      meta: this.meta,
-      kv: this.kv,
-      log: this.log,
-      timing: this.timing,
-      sqlite: this.sqlite
-    };
-    if (await shouldSkip?.(taskContext)) {
-      await this.runtimeCallbacks?.onSkip?.({ path });
-      return;
+    const deadline = runDeadline({ startedAt: Date.now(), scheduledAt, nextAt, budgetMs });
+    const { signal, dispose } = deadlineSignal(deadline);
+    const taskContext = this.buildContext(run, meta, { scheduledAt, nextAt, deadline }, signal);
+    let exclusiveHeld = null;
+    try {
+      const gate = await this.holdBack(run, {
+        firstAttempt,
+        scheduled: scheduledAt != null,
+        exclusiveLocks,
+        retry
+      });
+      if ("reason" in gate) {
+        await run.callbacks.onSkip?.({ path, reason: gate.reason });
+        return;
+      }
+      exclusiveHeld = gate.held;
+      if (await exports.shouldSkip?.(taskContext)) {
+        await run.callbacks.onSkip?.({ path });
+        return;
+      }
+      tick2.failedContext = taskContext;
+      const { onSuccess, onError, onComplete } = exports;
+      const value = await this.runTask(
+        exports.task,
+        taskContext,
+        { onSuccess, onError, onComplete },
+        run
+      );
+      tick2.failedContext = null;
+      return value;
+    } finally {
+      dispose();
+      await exclusiveHeld?.release();
     }
-    return this.runTask(task, taskContext, { onSuccess, onError, onComplete });
   }
 };
 
@@ -539,9 +1511,46 @@ var TaskLibrary = class {
 };
 
 // src/runtime/taskLibraryScheduler.ts
-import { validate, schedule } from "node-cron";
-import invariant7 from "tiny-invariant";
+import invariant8 from "tiny-invariant";
 import { logTaskLibraryScheduler, logTaskLibrarySchedulerError } from "@apisurf/ngn-os";
+
+// src/runtime/schedule.ts
+import { Cron } from "croner";
+import invariant7 from "tiny-invariant";
+var CRON_OPTIONS = { mode: "5-or-6-parts" };
+function isCronPatternValid(pattern) {
+  try {
+    new Cron(pattern, { ...CRON_OPTIONS, paused: true }).stop();
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function tick(task, onError, schedule = {}) {
+  try {
+    if (task.isRunning && task.overlapPolicy === "skip") {
+      await task.skip("previous run still in progress");
+      return;
+    }
+    await task.execute(schedule);
+  } catch (error) {
+    onError(error);
+  }
+}
+function scheduleTask(task, pattern, onError) {
+  invariant7(isCronPatternValid(pattern), `Invalid cron pattern: ${pattern} for ${task.taskPath}`);
+  task.validateExports();
+  return new Cron(
+    pattern,
+    CRON_OPTIONS,
+    (job) => tick(task, onError, {
+      scheduledAt: job.currentRun()?.getTime() ?? Date.now(),
+      nextAt: job.nextRun()?.getTime() ?? null
+    })
+  );
+}
+
+// src/runtime/taskLibraryScheduler.ts
 var TaskLibraryScheduler = class {
   taskLibrary;
   scheduledTasks = /* @__PURE__ */ new Map();
@@ -573,14 +1582,16 @@ var TaskLibraryScheduler = class {
     logTaskLibraryScheduler(`Scheduling task: ${task.taskPath}`);
     await task.loadEntry();
     logTaskLibraryScheduler(`Scheduling: ${task.taskPath} with pattern: ${task.timingPattern}`);
-    invariant7(task.hasTimingExport(), `timing pattern is missing for ${task.taskPath}`);
-    invariant7(task.hasTaskExport(), `task function is missing for ${task.taskPath}`);
-    invariant7(
+    invariant8(task.hasTimingExport(), `timing pattern is missing for ${task.taskPath}`);
+    invariant8(task.hasTaskExport(), `task function is missing for ${task.taskPath}`);
+    invariant8(
       task.timingPattern && this.isCronPatternValid(task.timingPattern),
       `Invalid cron pattern: ${task.timingPattern} for ${task.taskPath}`
     );
-    const wrappedUserTask = async () => task.execute();
-    const scheduledTask = schedule(task.timingPattern, wrappedUserTask);
+    const scheduledTask = scheduleTask(task, task.timingPattern, (error) => {
+      logTaskLibrarySchedulerError(`Run failed: ${task.taskPath}`);
+      logTaskLibrarySchedulerError(error);
+    });
     this.scheduledTasks.set(task.taskPath, scheduledTask);
     logTaskLibraryScheduler(`Scheduled: ${task.taskPath}`);
   }
@@ -595,7 +1606,7 @@ var TaskLibraryScheduler = class {
     logTaskLibraryScheduler(`Unscheduled: ${task.taskPath}`);
   }
   isCronPatternValid(cronPattern) {
-    return validate(cronPattern);
+    return isCronPatternValid(cronPattern);
   }
   // startScheduledTask(path: string) {
   //   const task = this.scheduledTasks.get(path);
@@ -614,7 +1625,7 @@ var TaskLibraryScheduler = class {
 };
 
 // src/runtime/taskOnceRunner.ts
-import invariant8 from "tiny-invariant";
+import invariant9 from "tiny-invariant";
 import { logTaskOnceRunner, logTaskOnceRunnerError } from "@apisurf/ngn-os";
 var TaskOnceRunner = class {
   task;
@@ -625,7 +1636,7 @@ var TaskOnceRunner = class {
     logTaskOnceRunner(`Preparing to run task: ${this.task.taskPath}`);
     await this.task.loadEntry();
     logTaskOnceRunner(`Loaded task code: ${this.task.taskPath}`);
-    invariant8(this.task.hasTaskExport(), `task function is missing for ${this.task.taskPath}`);
+    invariant9(this.task.hasTaskExport(), `task function is missing for ${this.task.taskPath}`);
     logTaskOnceRunner(`Running task: ${this.task.taskPath}`);
     try {
       await this.task.execute();
@@ -644,10 +1655,10 @@ import {
   initDbFileIfNotExists,
   isDbPath
 } from "@apisurf/ngn-persistence";
-import invariant9 from "tiny-invariant";
+import invariant10 from "tiny-invariant";
 var db;
 async function setupDbClient(dbPath) {
-  invariant9(isDbPath(dbPath), "Invalid db path");
+  invariant10(isDbPath(dbPath), "Invalid db path");
   if (db) {
     return db;
   }
@@ -655,7 +1666,7 @@ async function setupDbClient(dbPath) {
   return db;
 }
 function getDbClient() {
-  invariant9(db, "DB client not initialized");
+  invariant10(db, "DB client not initialized");
   return db;
 }
 
@@ -666,114 +1677,7 @@ import {
   logTaskConsoleInfo,
   logTaskConsoleWarn
 } from "@apisurf/ngn-os";
-import invariant10 from "tiny-invariant";
-
-// src/runtime/taskSqlite.ts
-import { mkdirSync } from "node:fs";
-import { unlink } from "node:fs/promises";
-import { basename, dirname, extname, isAbsolute, join, resolve, sep } from "node:path";
-import {
-  openDbClient
-} from "@apisurf/ngn-persistence";
-var openClients = /* @__PURE__ */ new Map();
-async function runMigrations(client, migrations) {
-  if (!migrations.length) return;
-  await client.execute(`
-    CREATE TABLE IF NOT EXISTS _ngn_migrations (
-      id TEXT PRIMARY KEY,
-      applied_at TEXT NOT NULL
-    )
-  `);
-  const applied = await client.execute("SELECT id FROM _ngn_migrations");
-  const appliedIds = new Set(applied.rows.map((r) => r.id));
-  for (const migration of migrations) {
-    if (appliedIds.has(migration.id)) continue;
-    await client.execute(migration.up);
-    await client.execute({
-      sql: "INSERT INTO _ngn_migrations (id, applied_at) VALUES (?, ?)",
-      args: [migration.id, (/* @__PURE__ */ new Date()).toISOString()]
-    });
-  }
-}
-function resolveTaskDbPath(taskDir, file) {
-  if (typeof file !== "string" || !file.trim()) {
-    throw new Error("A database file name is required");
-  }
-  const relativePath = file.startsWith("file:") ? file.slice(5) : file;
-  if (!relativePath) {
-    throw new Error("A database file name is required");
-  }
-  if (isAbsolute(relativePath)) {
-    throw new Error(
-      `Database file must be relative to the task folder, got an absolute path: "${file}"`
-    );
-  }
-  const resolved = resolve(taskDir, relativePath);
-  const taskDirRoot = taskDir.endsWith(sep) ? taskDir : `${taskDir}${sep}`;
-  if (!resolved.startsWith(taskDirRoot)) {
-    throw new Error(
-      `Database file "${file}" resolves outside the task folder (${taskDir}). A task can only manage databases in its own folder.`
-    );
-  }
-  return resolved;
-}
-function getClient(absolutePath) {
-  const existing = openClients.get(absolutePath);
-  if (existing) {
-    return existing;
-  }
-  mkdirSync(dirname(absolutePath), { recursive: true });
-  const client = openDbClient(`file:${absolutePath}`);
-  openClients.set(absolutePath, client);
-  return client;
-}
-function closeClient(absolutePath) {
-  const client = openClients.get(absolutePath);
-  if (client) {
-    client.close();
-    openClients.delete(absolutePath);
-  }
-}
-function createTaskSqlite(taskSourcePath) {
-  const taskDir = dirname(taskSourcePath);
-  const defaultDbPath = join(taskDir, `${basename(taskSourcePath, extname(taskSourcePath))}.db`);
-  const defaultClient = () => getClient(defaultDbPath);
-  return {
-    get client() {
-      return defaultClient();
-    },
-    get path() {
-      return defaultDbPath;
-    },
-    execute: (sql, args) => defaultClient().execute(args ? { sql, args } : sql),
-    batch: (statements) => defaultClient().batch(statements),
-    async initDB(options) {
-      const dbPath = resolveTaskDbPath(taskDir, options.file);
-      const client = getClient(dbPath);
-      if (options.migrations?.length) {
-        await runMigrations(client, options.migrations);
-      }
-      return {
-        client,
-        path: dbPath,
-        execute: (sql, args) => client.execute(args ? { sql, args } : sql),
-        batch: (statements) => client.batch(statements),
-        close: () => closeClient(dbPath)
-      };
-    },
-    async destroyDB(file) {
-      const dbPath = resolveTaskDbPath(taskDir, file);
-      closeClient(dbPath);
-      await unlink(dbPath);
-    }
-  };
-}
-function closeTaskDatabases() {
-  for (const client of openClients.values()) {
-    client.close();
-  }
-  openClients.clear();
-}
+import invariant11 from "tiny-invariant";
 
 // src/db/services/fileTask.ts
 import { $fileTaskInsert } from "@apisurf/ngn-schema";
@@ -933,25 +1837,67 @@ async function registerFileTask(dbClient, md5Hash, compiledCode, paths) {
 }
 
 // src/db/services/taskRun.ts
+function serializeResult(value) {
+  if (value === void 0) return null;
+  try {
+    return JSON.stringify(value) ?? null;
+  } catch {
+    try {
+      return String(value);
+    } catch {
+      return null;
+    }
+  }
+}
 var TaskRunService = class {
   constructor(db2) {
     this.db = db2;
   }
   async initTaskRun(data) {
     const { rows } = await this.db.execute({
-      sql: "INSERT INTO task_runs (file_task_id, file_task_version_id, status) VALUES (:file_task_id, :file_task_version_id, 'pending') RETURNING id",
+      sql: "INSERT INTO task_runs (file_task_id, file_task_version_id, status, retry_of) VALUES (:file_task_id, :file_task_version_id, 'pending', :retry_of) RETURNING id",
       args: {
         file_task_id: data.file_task_id,
-        file_task_version_id: data.file_task_version_id
+        file_task_version_id: data.file_task_version_id,
+        retry_of: data.retry_of ?? null
       }
     });
     return rows[0].id;
   }
-  async skipTaskRun(taskRunId) {
+  async skipTaskRun(taskRunId, reason = null) {
     await this.db.execute({
-      sql: "UPDATE task_runs SET status = 'skipped', ended_at = :ended_at WHERE id = :id",
-      args: { id: taskRunId, ended_at: Date.now() }
+      sql: "UPDATE task_runs SET status = 'skipped', ended_at = :ended_at, skip_reason = :reason WHERE id = :id",
+      args: { id: taskRunId, ended_at: Date.now(), reason }
+    });
+  }
+  /**
+   * How the task's latest ticks ended, newest first: `failure` or `success`
+   * per tick, a tick's retries folded into it (its last attempt decides).
+   * Skipped ticks are left out; they neither break nor extend a streak.
+   */
+  async recentTickOutcomes(fileTaskId, limit) {
+    const { rows } = await this.db.execute({
+      sql: `SELECT r.id,
+                   COALESCE(
+                     (SELECT a.status FROM task_runs a WHERE a.retry_of = r.id ORDER BY a.id DESC LIMIT 1),
+                     r.status
+                   ) AS outcome
+            FROM task_runs r
+            WHERE r.file_task_id = :fileTaskId AND r.retry_of IS NULL
+              AND r.status IN ('success', 'failure')
+            ORDER BY r.id DESC LIMIT :limit`,
+      args: { fileTaskId, limit }
     });
+    return rows;
+  }
+  /** Runs skipped with `reason` after run `afterId`. */
+  async countSkipsSince(fileTaskId, reason, afterId) {
+    const { rows } = await this.db.execute({
+      sql: `SELECT COUNT(*) AS n FROM task_runs
+            WHERE file_task_id = :fileTaskId AND status = 'skipped' AND skip_reason = :reason AND id > :afterId`,
+      args: { fileTaskId, reason, afterId }
+    });
+    return Number(rows[0].n);
   }
   async startTaskRun(taskRunId) {
     await this.db.execute({
@@ -962,12 +1908,13 @@ var TaskRunService = class {
       }
     });
   }
-  async endTaskRun(taskRunId, status) {
+  async endTaskRun(taskRunId, status, result = null) {
     await this.db.execute({
-      sql: "UPDATE task_runs SET ended_at = :ended_at, status = :status WHERE id = :id",
+      sql: "UPDATE task_runs SET ended_at = :ended_at, status = :status, result = :result WHERE id = :id",
       args: {
         ended_at: Date.now(),
         status,
+        result,
         id: taskRunId
       }
     });
@@ -1081,6 +2028,46 @@ var TimingService = class {
   }
 };
 
+// src/db/services/lock.ts
+import { randomUUID } from "node:crypto";
+var LockService = class {
+  constructor(db2) {
+    this.db = db2;
+  }
+  /** The holder token on success, null when someone else holds an unexpired lease. */
+  async tryAcquire(name, ttlMs, taskRunId) {
+    const holder = `${process.pid}:${randomUUID()}`;
+    const now = Date.now();
+    const { rows } = await this.db.execute({
+      sql: `INSERT INTO locks (name, holder, task_run_id, acquired_at, expires_at)
+            VALUES (:name, :holder, :taskRunId, :now, :expiresAt)
+            ON CONFLICT(name) DO UPDATE SET
+              holder = excluded.holder,
+              task_run_id = excluded.task_run_id,
+              acquired_at = excluded.acquired_at,
+              expires_at = excluded.expires_at
+            WHERE locks.expires_at <= excluded.acquired_at
+            RETURNING holder`,
+      args: { name, holder, taskRunId, now, expiresAt: now + ttlMs }
+    });
+    return rows.length ? holder : null;
+  }
+  /** Push the lease out; false when it was lost (it expired and someone took it). */
+  async renew(name, holder, ttlMs) {
+    const { rowsAffected } = await this.db.execute({
+      sql: "UPDATE locks SET expires_at = :expiresAt WHERE name = :name AND holder = :holder",
+      args: { name, holder, expiresAt: Date.now() + ttlMs }
+    });
+    return rowsAffected > 0;
+  }
+  async release(name, holder) {
+    await this.db.execute({
+      sql: "DELETE FROM locks WHERE name = :name AND holder = :holder",
+      args: { name, holder }
+    });
+  }
+};
+
 // src/runtime/generateControls.ts
 function createControlsGenerator({
   dbClient,
@@ -1090,13 +2077,13 @@ function createControlsGenerator({
   const logService = new LogService(dbClient);
   const kvService = new KVService(dbClient);
   const timingService = new TimingService(dbClient);
+  const lockService = new LockService(dbClient);
   const generateControls = ({ sourcePath, compiledPath }) => {
     let fileTaskId;
     let fileTaskVersionId;
-    let fileTaskRunId;
     const assertMandatoryIds = () => {
-      invariant10(!!fileTaskId, "Task ID not found");
-      invariant10(!!fileTaskVersionId, "Task version ID not found");
+      invariant11(!!fileTaskId, "Task ID not found");
+      invariant11(!!fileTaskVersionId, "Task version ID not found");
     };
     const taskCallbacks = {
       async onTaskLoadComplete({ paths, md5Hash, compiledCode }) {
@@ -1111,54 +2098,88 @@ function createControlsGenerator({
           fileTaskVersionId
         };
       },
-      async onTaskExecutionStart() {
-        assertMandatoryIds();
-        fileTaskRunId = await taskRunService.initTaskRun({
-          file_task_id: fileTaskId,
-          file_task_version_id: fileTaskVersionId
-        });
-      },
       async onTaskCodeLoaded() {
       },
       async onTaskExportsLoaded() {
       }
     };
-    const runtimeCallbacks = {
-      async onNotFound() {
-        assertMandatoryIds();
-        await logService.logError(fileTaskId, fileTaskRunId, "Task not found");
-        logTaskCallback(`Task not found: ${fileTaskId}, run ID: ${fileTaskRunId}`);
-      },
-      async onSkip() {
-        assertMandatoryIds();
-        await taskRunService.skipTaskRun(fileTaskRunId);
-        await logService.logInfo(fileTaskId, fileTaskRunId, "Task skipped");
-        logTaskCallback(`Task skipped: ${fileTaskId}, run ID: ${fileTaskRunId}`);
-      },
-      async onStart() {
-        assertMandatoryIds();
-        await taskRunService.startTaskRun(fileTaskRunId);
-        await logService.logInfo(fileTaskId, fileTaskRunId, "Task started");
-        logTaskCallback(`Task started: ${fileTaskId}, run ID: ${fileTaskRunId}`);
-      },
-      async onFailure() {
-        assertMandatoryIds();
-        await taskRunService.endTaskRun(fileTaskRunId, "failure");
-        await logService.logError(fileTaskId, fileTaskRunId, "Task failed");
-        logTaskCallback(`Task failed: ${fileTaskId}, run ID: ${fileTaskRunId}`);
-      },
-      async onSuccess() {
-        assertMandatoryIds();
-        await taskRunService.endTaskRun(fileTaskRunId, "success");
-        await logService.logInfo(fileTaskId, fileTaskRunId, "Task succeeded");
-        logTaskCallback(`Task succeeded: ${fileTaskId}, run ID: ${fileTaskRunId}`);
-      }
-    };
+    async function startRun({
+      retryOf = null
+    } = {}) {
+      assertMandatoryIds();
+      const taskId = fileTaskId;
+      const runId = await taskRunService.initTaskRun({
+        file_task_id: taskId,
+        file_task_version_id: fileTaskVersionId,
+        retry_of: retryOf
+      });
+      const callbacks = {
+        async onNotFound() {
+          await logService.logError(taskId, runId, "Task not found");
+          logTaskCallback(`Task not found: ${taskId}, run ID: ${runId}`);
+        },
+        async onSkip({ reason }) {
+          await taskRunService.skipTaskRun(runId, reason ?? null);
+          await logService.logInfo(taskId, runId, "Task skipped");
+          if (reason) await logService.logInfo(taskId, runId, `Skipped: ${reason}`);
+          logTaskCallback(`Task skipped: ${taskId}, run ID: ${runId}`);
+        },
+        async onStart() {
+          await taskRunService.startTaskRun(runId);
+          await logService.logInfo(taskId, runId, "Task started");
+          logTaskCallback(`Task started: ${taskId}, run ID: ${runId}`);
+        },
+        async onFailure() {
+          await taskRunService.endTaskRun(runId, "failure");
+          await logService.logError(taskId, runId, "Task failed");
+          logTaskCallback(`Task failed: ${taskId}, run ID: ${runId}`);
+        },
+        async onSuccess({ result }) {
+          await taskRunService.endTaskRun(runId, "success", serializeResult(result));
+          await logService.logInfo(taskId, runId, "Task succeeded");
+          logTaskCallback(`Task succeeded: ${taskId}, run ID: ${runId}`);
+        }
+      };
+      return {
+        id: runId,
+        callbacks,
+        locks: createRunLocks(lockService, runId),
+        log: {
+          async info(value) {
+            logTaskConsoleInfo(value);
+            await logService.logInfo(taskId, runId, value);
+          },
+          async error(value) {
+            logTaskConsoleError(value);
+            await logService.logError(taskId, runId, value);
+          },
+          async warning(value) {
+            logTaskConsoleWarn(value);
+            await logService.logWarning(taskId, runId, value);
+          }
+        },
+        timing: {
+          start(label) {
+            return timingService.start(taskId, runId, label);
+          }
+        }
+      };
+    }
     return {
       compiledPath,
       sourcePath,
       taskCallbacks,
-      runtimeCallbacks,
+      startRun,
+      history: {
+        recentTickOutcomes(limit) {
+          assertMandatoryIds();
+          return taskRunService.recentTickOutcomes(fileTaskId, limit);
+        },
+        countSkipsSince(reason, afterId) {
+          assertMandatoryIds();
+          return taskRunService.countSkipsSince(fileTaskId, reason, afterId);
+        }
+      },
       env,
       // Scoped to this task's own folder — see createTaskSqlite
       sqlite: createTaskSqlite(sourcePath),
@@ -1172,25 +2193,6 @@ function createControlsGenerator({
         async delete(key) {
           await kvService.deleteValue(fileTaskId, key);
         }
-      },
-      log: {
-        async info(value) {
-          logTaskConsoleInfo(value);
-          await logService.logInfo(fileTaskId, fileTaskRunId, value);
-        },
-        async error(value) {
-          logTaskConsoleError(value);
-          await logService.logError(fileTaskId, fileTaskRunId, value);
-        },
-        async warning(value) {
-          logTaskConsoleWarn(value);
-          await logService.logWarning(fileTaskId, fileTaskRunId, value);
-        }
-      },
-      timing: {
-        start(label) {
-          return timingService.start(fileTaskId, fileTaskRunId, label);
-        }
       }
     };
   };
@@ -1198,6 +2200,8 @@ function createControlsGenerator({
 }
 export {
   Compiler,
+  LockBusyError,
+  Queue,
   Task,
   TaskLibrary,
   TaskLibraryScheduler,
@@ -1207,5 +2211,7 @@ export {
   executeEsm,
   getDbClient,
   initDbFileIfNotExists,
+  isCronPatternValid,
+  scheduleTask,
   setupDbClient
 };