cursedbelt-server 1.0.0

package/src/server/jobs/fireQueue.spec.ts

@@ -0,0 +1,85 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { createFireQueue } from './fireQueue';
+
+const JOB_STATE_DDL = `CREATE TABLE job_state (name TEXT PRIMARY KEY, last_run_at TEXT, meta TEXT)`;
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+const quietLogger = { error() {}, warn() {}, info() {}, debug() {} };
+
+describe('createFireQueue', () => {
+  let db: Database;
+  beforeEach(() => {
+    db = new Database(':memory:');
+    db.run(JOB_STATE_DDL);
+  });
+  afterEach(() => db.close());
+
+  test('delivers each due item (acceptance)', async () => {
+    const items: string[] = [];
+    const queue = createFireQueue<string>({
+      name: 'test-q',
+      db,
+      intervalMs: 30,
+      getDue: () => ['item-1'],
+      async deliver(item) {
+        items.push(item);
+      },
+      markSent: () => {},
+    });
+    queue.start();
+    await sleep(50);
+    queue.stop();
+    expect(items).toContain('item-1');
+  });
+
+  test('a delivery failure routes to onError and the loop continues (integration)', async () => {
+    const delivered: string[] = [];
+    const errored: string[] = [];
+    let drained = false;
+    const queue = createFireQueue<string>({
+      name: 'resilient-q',
+      db,
+      intervalMs: 1000, // single boot fire is enough
+      logger: quietLogger,
+      getDue: () => (drained ? [] : ['bad', 'good']),
+      async deliver(item) {
+        if (item === 'bad') throw new Error('delivery boom');
+        delivered.push(item);
+      },
+      markSent: () => {
+        drained = true;
+      },
+      onError(item) {
+        errored.push(item);
+      },
+    });
+    queue.start();
+    await sleep(40);
+    queue.stop();
+    expect(errored).toEqual(['bad']);
+    expect(delivered).toEqual(['good']); // continued past the failure
+  });
+
+  test('markSent is only called after a successful deliver', async () => {
+    const sent: string[] = [];
+    let drained = false;
+    const queue = createFireQueue<string>({
+      name: 'mark-q',
+      db,
+      intervalMs: 1000,
+      logger: quietLogger,
+      getDue: () => (drained ? [] : ['a', 'fail', 'b']),
+      async deliver(item) {
+        if (item === 'fail') throw new Error('nope');
+      },
+      markSent: (item) => {
+        sent.push(item);
+        if (item === 'b') drained = true;
+      },
+    });
+    queue.start();
+    await sleep(40);
+    queue.stop();
+    expect(sent).toEqual(['a', 'b']); // 'fail' never marked sent
+  });
+});

package/src/server/jobs/fireQueue.ts

@@ -0,0 +1,37 @@
+import { defaultJobLogger } from './logger';
+import { createPollingJob } from './polling';
+import { DEFAULT_FIRE_INTERVAL_MS, type FireQueue, type FireQueueOpts } from './types';
+
+/**
+ * The "select due rows → deliver each → mark sent" pattern, as a {@link PollingJob}.
+ * This is ca's `event_reminders` / `alarms` delivery loop generalized: each poll
+ * pulls the due rows, delivers them one at a time, and marks each sent only after a
+ * successful delivery. A failed `deliver` routes to `onError` and is logged, and
+ * the loop CONTINUES with the next item — one bad row never stalls the queue.
+ *
+ * Because it fires once on boot (default), any rows that came due while the process
+ * was down are delivered on the first poll after restart.
+ */
+export function createFireQueue<T>(opts: FireQueueOpts<T>): FireQueue {
+  const logger = opts.logger ?? defaultJobLogger;
+
+  return createPollingJob({
+    name: opts.name,
+    db: opts.db,
+    intervalMs: opts.intervalMs ?? DEFAULT_FIRE_INTERVAL_MS,
+    runOnBoot: opts.runOnBoot,
+    logger,
+    async run({ db, signal }) {
+      for (const item of opts.getDue(db)) {
+        if (signal.aborted) break;
+        try {
+          await opts.deliver(item, db);
+          opts.markSent(item, db);
+        } catch (err) {
+          opts.onError?.(item, err);
+          logger.error(`[fireQueue] ${opts.name} delivery failed`, err);
+        }
+      }
+    },
+  });
+}

package/src/server/jobs/index.ts

@@ -0,0 +1,26 @@
+// cursedbelt jobs & scheduler — the in-process scheduled-work engine shared by
+// ca + ru. cursedbelt owns the mechanism (durable cron scheduling via plainjob,
+// restart-aware pollers, the due-row fire queue, run auditing); app job
+// *definitions* stay business and consume these primitives.
+
+export { createFireQueue } from './fireQueue';
+export { defaultJobLogger } from './logger';
+export { createPollingJob } from './polling';
+export { createJobRunner } from './runner';
+export { JobTimeoutError } from './timeout';
+export {
+  type CreateJobRunnerOptions,
+  DEFAULT_FIRE_INTERVAL_MS,
+  DEFAULT_JOB_RETENTION,
+  DEFAULT_JOB_TIMEOUT_MS,
+  type FireQueue,
+  type FireQueueOpts,
+  type JobContext,
+  type JobDef,
+  type JobLogger,
+  type JobRetentionOptions,
+  type JobRunner,
+  type JobRunRecord,
+  type PollingJob,
+  type PollingJobOpts,
+} from './types';

package/src/server/jobs/logger.ts

@@ -0,0 +1,16 @@
+import type { JobLogger } from './types';
+
+/**
+ * The default job logger: warn/info/error go to the console, `debug` is a no-op.
+ *
+ * The underlying plainjob worker logs at `debug` on *every* poll ("checking for
+ * scheduled jobs", once per second by default), so a console `debug` would spam.
+ * Silencing it here keeps the default quiet while still surfacing real problems.
+ * Inject your own {@link JobLogger} (e.g. the app logger) to capture debug.
+ */
+export const defaultJobLogger: JobLogger = {
+  error: (message, ...meta) => console.error(message, ...meta),
+  warn: (message, ...meta) => console.warn(message, ...meta),
+  info: (message, ...meta) => console.info(message, ...meta),
+  debug: () => {},
+};

package/src/server/jobs/plainjobAdapter.spec.ts

@@ -0,0 +1,34 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { createPlainjobConnection } from './plainjobAdapter';
+
+describe('createPlainjobConnection', () => {
+  let db: Database;
+  beforeEach(() => {
+    db = new Database(':memory:');
+    db.run('CREATE TABLE t (type TEXT NOT NULL, n INTEGER)');
+  });
+  afterEach(() => db.close());
+
+  test('binds bare-key params that bun:sqlite would otherwise reject (the plainjob fix)', () => {
+    const conn = createPlainjobConnection(db);
+    const insert = conn.prepare('INSERT INTO t (type, n) VALUES (@type, @n)');
+    // plainjob passes bare keys; on Bun ≥ 1.3 these bind NULL without the adapter.
+    insert.run({ type: 'a', n: 1 });
+    const row = db.query('SELECT type, n FROM t').get() as { type: string; n: number };
+    expect(row).toEqual({ type: 'a', n: 1 });
+  });
+
+  test('leaves already-sigilled keys and positional params untouched', () => {
+    const conn = createPlainjobConnection(db);
+    conn.prepare('INSERT INTO t (type, n) VALUES (@type, @n)').run({ '@type': 'b', '@n': 2 });
+    const got = conn.prepare('SELECT n FROM t WHERE type = ?').get('b') as { n: number };
+    expect(got.n).toBe(2);
+  });
+
+  test('close() is a no-op so the shared db stays open', () => {
+    const conn = createPlainjobConnection(db);
+    conn.close();
+    expect(() => db.query('SELECT 1 AS x').get()).not.toThrow();
+  });
+});

package/src/server/jobs/plainjobAdapter.ts

@@ -0,0 +1,54 @@
+import type { Database } from 'bun:sqlite';
+import type { Connection } from 'plainjob';
+
+/**
+ * A plainjob {@link Connection} over a `bun:sqlite` Database, with two deliberate
+ * deviations from plainjob's own `bun()` adapter:
+ *
+ *  1. **Named-parameter binding fix.** plainjob binds its prepared statements with
+ *     *bare* object keys (`{ type, cronExpression }`). On Bun ≥ 1.3 `bun:sqlite`
+ *     requires the sigil — bare keys silently bind NULL (→ `NOT NULL constraint
+ *     failed`). This adapter rewrites each object key to `@key` (leaving keys that
+ *     already carry an `@ $ :` sigil, and non-object/positional params, untouched),
+ *     so plainjob runs unmodified on current Bun. Remove once plainjob ships a fix.
+ *
+ *  2. **`close()` is a no-op.** plainjob's queue and the app share ONE connection;
+ *     `queue.close()` would otherwise close the app's database out from under it.
+ *     Closing is the app's job — the runner only stops the queue's maintenance
+ *     timer (which `queue.close()` still does). The DB outlives the runner.
+ */
+export function createPlainjobConnection(database: Database): Connection {
+  const prefixKeys = (params: unknown[]): unknown[] =>
+    params.map((param) => {
+      if (!param || typeof param !== 'object' || Array.isArray(param)) return param;
+      return Object.fromEntries(
+        Object.entries(param as Record<string, unknown>).map(([key, value]) => [
+          /^[@$:]/.test(key) ? key : `@${key}`,
+          value,
+        ]),
+      );
+    });
+
+  return {
+    driver: 'bun:sqlite',
+    filename: database.filename,
+    pragma: (stmt: string) => {
+      database.exec(`PRAGMA ${stmt};`);
+    },
+    exec: (stmt: string) => {
+      database.exec(stmt);
+    },
+    transaction: database.transaction.bind(database) as Connection['transaction'],
+    prepare: (sql: string) => {
+      const stmt = database.query(sql);
+      return {
+        run: (...params: unknown[]) => stmt.run(...(prefixKeys(params) as never[])),
+        get: (...params: unknown[]) => stmt.get(...(prefixKeys(params) as never[])),
+        all: (...params: unknown[]) => stmt.all(...(prefixKeys(params) as never[])),
+      };
+    },
+    close: () => {
+      // Intentionally empty — the app owns the shared DB's lifecycle.
+    },
+  };
+}

package/src/server/jobs/polling.spec.ts

@@ -0,0 +1,219 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { createPollingJob } from './polling';
+
+const JOB_STATE_DDL = `CREATE TABLE job_state (
+  name TEXT PRIMARY KEY,
+  last_run_at TEXT,
+  meta TEXT
+)`;
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+const lastRunAt = (db: Database, name: string) =>
+  (db.query('SELECT last_run_at FROM job_state WHERE name = ?').get(name) as
+    | { last_run_at: string | null }
+    | undefined) ?? undefined;
+
+describe('createPollingJob', () => {
+  let db: Database;
+  beforeEach(() => {
+    db = new Database(':memory:');
+    db.run(JOB_STATE_DDL);
+  });
+  afterEach(() => db.close());
+
+  test('fires on boot and again on each interval (acceptance)', async () => {
+    let count = 0;
+    const job = createPollingJob({
+      name: 'test',
+      intervalMs: 50,
+      db,
+      runOnBoot: true,
+      async run() {
+        count++;
+      },
+    });
+    job.start();
+    await sleep(120);
+    job.stop();
+    expect(count).toBeGreaterThanOrEqual(2); // boot + at least one interval
+  });
+
+  test('runOnBoot:false skips the immediate fire', async () => {
+    let count = 0;
+    const job = createPollingJob({
+      name: 'no-boot',
+      intervalMs: 1000,
+      db,
+      runOnBoot: false,
+      async run() {
+        count++;
+      },
+    });
+    job.start();
+    await sleep(20);
+    job.stop();
+    expect(count).toBe(0);
+  });
+
+  test('records last_run_at on success', async () => {
+    const job = createPollingJob({
+      name: 'stamps',
+      intervalMs: 1000,
+      db,
+      async run() {},
+    });
+    job.start();
+    await sleep(20);
+    job.stop();
+    expect(lastRunAt(db, 'stamps')?.last_run_at).toBeTruthy();
+  });
+
+  test('a thrown handler is swallowed and does NOT advance last_run_at', async () => {
+    const job = createPollingJob({
+      name: 'boom',
+      intervalMs: 1000,
+      db,
+      logger: { error() {}, warn() {}, info() {}, debug() {} },
+      async run() {
+        throw new Error('handler failed');
+      },
+    });
+    job.start();
+    await sleep(20);
+    job.stop();
+    expect(lastRunAt(db, 'boom')).toBeUndefined();
+  });
+
+  test('preserves an existing job_state.meta on the last_run_at upsert', async () => {
+    db.run("INSERT INTO job_state (name, last_run_at, meta) VALUES ('keep', NULL, '{\"n\":1}')");
+    const job = createPollingJob({ name: 'keep', intervalMs: 1000, db, async run() {} });
+    job.start();
+    await sleep(20);
+    job.stop();
+    const row = db.query('SELECT last_run_at, meta FROM job_state WHERE name = ?').get('keep') as {
+      last_run_at: string | null;
+      meta: string | null;
+    };
+    expect(row.last_run_at).toBeTruthy();
+    expect(row.meta).toBe('{"n":1}');
+  });
+
+  test('ticks are non-reentrant — a slow run never overlaps itself', async () => {
+    let concurrent = 0;
+    let maxConcurrent = 0;
+    const job = createPollingJob({
+      name: 'slow',
+      intervalMs: 20,
+      db,
+      async run() {
+        concurrent++;
+        maxConcurrent = Math.max(maxConcurrent, concurrent);
+        await sleep(70);
+        concurrent--;
+      },
+    });
+    job.start();
+    await sleep(160);
+    job.stop();
+    await sleep(80); // let the final slow run unwind
+    expect(maxConcurrent).toBe(1);
+  });
+
+  test('stop() aborts the in-flight run signal', async () => {
+    let abortedDuringRun = false;
+    const job = createPollingJob({
+      name: 'abortable',
+      intervalMs: 1000,
+      db,
+      async run({ signal }) {
+        await new Promise<void>((resolve) => {
+          signal.addEventListener(
+            'abort',
+            () => {
+              abortedDuringRun = true;
+              resolve();
+            },
+            { once: true },
+          );
+        });
+      },
+    });
+    job.start();
+    await sleep(20);
+    job.stop();
+    await sleep(20);
+    expect(abortedDuringRun).toBe(true);
+  });
+});
+
+/**
+ * The teardown race (2026-08-06, found while draining the orch board).
+ *
+ * `stop()` is what a host or a test calls immediately before closing the
+ * database. A run that was already awaiting `opts.run` then resumed and wrote
+ * `last_run_at` to a closed handle — "Database has closed", thrown out of a
+ * timer callback after the owning test had ended. It reddened
+ * cursed-satellites' orch-engine suite about one run in three with a stack
+ * pointing into this file and no relation to the test it failed.
+ */
+describe("a run that is stopped mid-flight", () => {
+	test("does not stamp a completion", async () => {
+		const db = new Database(":memory:");
+		db.run(JOB_STATE_DDL);
+		let release: (() => void) | undefined;
+		const started = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		let running: (() => void) | undefined;
+		const inRun = new Promise<void>((resolve) => {
+			running = resolve;
+		});
+
+		const job = createPollingJob({
+			db,
+			name: "slow",
+			intervalMs: 60_000,
+			runOnBoot: true,
+			run: async () => {
+				running?.();
+				await started;
+			},
+		});
+		job.start();
+		await inRun;
+
+		// The exact order a teardown takes: stop, then close.
+		job.stop();
+		release?.();
+		await Promise.resolve();
+		await Promise.resolve();
+
+		// Nothing was stamped, because nothing completed on this job's terms.
+		const row = db.query("SELECT last_run_at FROM job_state WHERE name = ?").get("slow");
+		expect(row).toBeNull();
+		db.close();
+	});
+
+	test("a run that finishes BEFORE stop still stamps", async () => {
+		// The guard must not swallow the normal case.
+		const db = new Database(":memory:");
+		db.run(JOB_STATE_DDL);
+		const job = createPollingJob({
+			db,
+			name: "quick",
+			intervalMs: 60_000,
+			runOnBoot: true,
+			run: () => {},
+		});
+		job.start();
+		await Promise.resolve();
+		await Promise.resolve();
+		job.stop();
+		const row = db.query("SELECT last_run_at FROM job_state WHERE name = ?").get("quick") as
+			| { last_run_at: string }
+			| null;
+		expect(row?.last_run_at).toBeTruthy();
+		db.close();
+	});
+});

package/src/server/jobs/polling.ts

@@ -0,0 +1,81 @@
+import { defaultJobLogger } from './logger';
+import type { JobContext, PollingJob, PollingJobOpts } from './types';
+
+/**
+ * A periodic, restart-aware poller — the engine behind ca's `setInterval`
+ * scheduler, alarm check, and metrics flush. On each tick it runs the handler and,
+ * on success, upserts `job_state.last_run_at` so the *last successful* time
+ * survives a restart (the `runOnBoot` + `last_run_at` pair is how a missed daily
+ * job catches up: fire on boot, and the handler skips if it already ran recently).
+ *
+ * Hardening over a bare `setInterval`:
+ *  - the timer is `unref()`'d, so a poller never keeps the process alive on its own;
+ *  - ticks are non-reentrant — a slow run can't pile up overlapping fires;
+ *  - {@link PollingJob.stop} aborts the in-flight run's context signal;
+ *  - a thrown handler is logged and does NOT advance `last_run_at`.
+ *
+ * `job_state` must already exist (the app's migration runner builds it).
+ */
+export function createPollingJob(opts: PollingJobOpts): PollingJob {
+  const logger = opts.logger ?? defaultJobLogger;
+  const runOnBoot = opts.runOnBoot !== false;
+
+  // Preserve any existing `meta` JSON on conflict — only last_run_at moves.
+  const upsertState = opts.db.prepare(
+    `INSERT INTO job_state (name, last_run_at) VALUES (?, ?)
+       ON CONFLICT(name) DO UPDATE SET last_run_at = excluded.last_run_at`,
+  );
+
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let controller: AbortController | null = null;
+  let inFlight = false;
+
+  const fire = async (): Promise<void> => {
+    if (inFlight || !controller) return;
+    inFlight = true;
+    // Captured, not re-read: `stop()` nulls `controller` and a later `start()`
+    // installs a fresh one, so the identity check below is what tells "still the
+    // run I began" from "stopped, and possibly restarted, while I was awaiting".
+    const mine = controller;
+    const context: JobContext = { db: opts.db, signal: mine.signal, logger };
+    try {
+      await opts.run(context);
+      // 🔴 STOPPED while this run was in flight — do not stamp a completion.
+      //
+      // Two reasons, and the second is the one that showed up. Semantically, a
+      // job whose owner pulled the plug mid-run did not finish on its own terms,
+      // so recording `last_run_at` would make the next boot skip work that never
+      // happened. Practically, `stop()` is what a host or a test calls just
+      // before closing the database — so this statement ran against a closed
+      // handle and threw "Database has closed" out of a timer callback, after
+      // the test that owned it had ended. That surfaced as an unhandled error
+      // reddening cursed-satellites' orch-engine suite roughly one run in three,
+      // with a stack pointing here and nothing to do with the test that failed.
+      if (controller !== mine) return;
+      upsertState.run(opts.name, new Date().toISOString());
+    } catch (err) {
+      logger.error(`[polling] ${opts.name} failed`, err);
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  return {
+    name: opts.name,
+    start() {
+      if (timer) return;
+      controller = new AbortController();
+      if (runOnBoot) void fire();
+      timer = setInterval(() => void fire(), opts.intervalMs);
+      timer.unref?.();
+    },
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      controller?.abort(new Error(`polling job "${opts.name}" stopped`));
+      controller = null;
+    },
+  };
+}