cursedbelt-server 1.0.0

package/dist/server/index.js

@@ -0,0 +1,53 @@
+// cursedbelt server toolkit — native Hono on Bun.serve. Consumed by ca + ru.
+//
+// HTTP app + middleware + the canonical error envelope + a versioned SQLite
+// migration runner + Kysely-typed access for the plumbing tables. Business routes,
+// auth model, sharing, jobs, and `data JSON` tables stay in the apps; cursedbelt
+// owns the plumbing.
+// ── ctgr (isomorphic codec re-exports + the Hono GET-tunnel transport) ───────
+export { ChunkStore, CTGR_WIRE_VERSION, decodeRequest, encodeRequest, } from 'cursedbelt-core/ctgr';
+// ── HTTP app ────────────────────────────────────────────────────────────────
+export { createApp, serveBun } from './app';
+// ── Auth toolkit (task 26): jose JWT, cookies, CSRF, getOnly, session store, ──
+//    login throttle, argon2id passwords, TOTP, vault crypto, the composed middleware.
+export { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, clearAuthCookie, createAuthMiddleware, createCsrfMiddleware, clientKeyOf, clientKeyOfContext, createLoginThrottle, createSessionStore, createRs256FileTokenSigner, DEFAULT_TOTP_ISSUER, decryptVaultItem, deriveVaultKey, encryptVaultItem, generateRecoveryCodes, generateTotpSecret, getOnlyEnforcement, getTotpUri, hashPassword, isGetOnlyViolation, needsRehash, signToken, verifyPassword, verifyPurposeToken, verifyRecoveryCode, verifyToken, verifyTotpCode, } from './auth';
+export { buildRoutes, CTGR_ROUTE_PATTERN, getCtgrDecoded, unGETify } from './ctgr';
+// ── Kysely-typed plumbing tables ────────────────────────────────────────────
+export { createKysely } from './db/kysely';
+// ── Errors ──────────────────────────────────────────────────────────────────
+export { ApiError, isApiError, toErrorEnvelope, toValidationIssues, VALIDATION_ERROR_CODE, validationEnvelope, } from './errors';
+// ── Jobs & scheduler (task 29): plainjob-backed cron runner + restart-aware ───
+//    pollers + the due-row fire queue. App job *definitions* stay business.
+export { createFireQueue, createJobRunner, createPollingJob, DEFAULT_FIRE_INTERVAL_MS, DEFAULT_JOB_TIMEOUT_MS, defaultJobLogger, JobTimeoutError, } from './jobs';
+// ── Media adapter (task 19): image rendering via sharp (lazy/optional peer) + ──
+//    video trim / probe / thumbnail via native ffmpeg. Also at the dedicated
+//    media-bun entry below; sharp is imported lazily inside renderImage,
+//    so importing this barrel never loads the native binary.
+export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, extractThumbnail, ffmpegTimeToSeconds, isFfmpegAvailable, isFfprobeAvailable, parseFfmpegProgress, parseFfprobe, probeMedia, renderImage, trimVideo, videoCodecPlan, } from './media-bun';
+// ── Metrics ───────────────────────────────────────────────────────────────────
+export { createMetricsBuffer, } from './metrics/metricsBuffer';
+export { normalizeRoute } from './metrics/normalizeRoute';
+// ── Middleware ────────────────────────────────────────────────────────────────
+export { correlationId } from './middleware/correlationId';
+export { corsAllowlist, corsOptsFromEnv } from './middleware/corsAllowlist';
+export { errorEnvelope } from './middleware/errorEnvelope';
+export { crossOriginRefusal } from './middleware/localOrigin';
+export { clientIp, createRateLimiter } from './middleware/rateLimit';
+export { requestLogger } from './middleware/requestLogger';
+export { securityHeaders, } from './middleware/securityHeaders';
+// ── zod validation toolkit ────────────────────────────────────────────────────
+//    (the `validationEnvelope`/`toValidationIssues`/`ValidationIssue` builders now
+//     live with the canonical envelope in `./errors`, re-exported above.)
+export { zValidator } from './middleware/zValidator';
+// ── Migration runner ──────────────────────────────────────────────────────────
+export { addColumnIfMissing, applyRecommendedPragmas, columnExists, runMigrations } from './migration/runner';
+// ── Audit log: the SQLite-backed AuditSink cursedshell's service dispatch ─────
+//    writes to (see `cwip/audit` for the storage-agnostic contract + the
+//    zero-config in-memory default).
+export { AUDIT_LOG_MIGRATIONS, auditStateAt, auditStateAtVersion, auditStep, createSqliteAuditSink, } from './audit';
+// ── SQLite toolkit extras (task 30): FTS5 ranked search + DDL generator, the ───
+//    read-only DB viewer middleware, the VACUUM-INTO backup service, DB health probes.
+export { applyFtsSchema, buildFtsSchema, clampLimit, clampOffset, collectSqliteStats, createFts5Search, createSqliteBackupService, createSqliteHealthChecks, createSqliteViewerMiddleware, exportSqliteSnapshot, exportSqliteTable, importRowsIntoSqliteTable, isKnownTable, isReadOnlySql, listSqliteTables, NotReadOnlyError, quoteIdent, readSqliteTable, restoreSqliteSnapshot, runReadonlySqlite, sanitizeFtsQuery, snapshotSqlite, UnknownTableError, } from './sqlite';
+// ── WebSocket hub (task 28): Bun-native upgrade, channel registry, heartbeat, ──
+//    presence-as-a-view, room helpers, and the push-only event-bus subset (ru).
+export { computePresence, createEventBus, createWsHub, joinRoom, leaveRoom, ROOM_META_KEY, roomOf, } from './ws';

package/dist/server/jobs/fireQueue.d.ts

@@ -0,0 +1,12 @@
+import { 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 declare function createFireQueue<T>(opts: FireQueueOpts<T>): FireQueue;

package/dist/server/jobs/fireQueue.js

@@ -0,0 +1,37 @@
+import { defaultJobLogger } from './logger';
+import { createPollingJob } from './polling';
+import { DEFAULT_FIRE_INTERVAL_MS } 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(opts) {
+    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/dist/server/jobs/index.d.ts

@@ -0,0 +1,6 @@
+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/dist/server/jobs/index.js

@@ -0,0 +1,10 @@
+// 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 { DEFAULT_FIRE_INTERVAL_MS, DEFAULT_JOB_RETENTION, DEFAULT_JOB_TIMEOUT_MS, } from './types';

package/dist/server/jobs/logger.d.ts

@@ -0,0 +1,10 @@
+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 declare const defaultJobLogger: JobLogger;

package/dist/server/jobs/logger.js

@@ -0,0 +1,14 @@
+/**
+ * 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 = {
+    error: (message, ...meta) => console.error(message, ...meta),
+    warn: (message, ...meta) => console.warn(message, ...meta),
+    info: (message, ...meta) => console.info(message, ...meta),
+    debug: () => { },
+};

package/dist/server/jobs/plainjobAdapter.d.ts

@@ -0,0 +1,19 @@
+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 declare function createPlainjobConnection(database: Database): Connection;

package/dist/server/jobs/plainjobAdapter.js

@@ -0,0 +1,48 @@
+/**
+ * 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) {
+    const prefixKeys = (params) => params.map((param) => {
+        if (!param || typeof param !== 'object' || Array.isArray(param))
+            return param;
+        return Object.fromEntries(Object.entries(param).map(([key, value]) => [
+            /^[@$:]/.test(key) ? key : `@${key}`,
+            value,
+        ]));
+    });
+    return {
+        driver: 'bun:sqlite',
+        filename: database.filename,
+        pragma: (stmt) => {
+            database.exec(`PRAGMA ${stmt};`);
+        },
+        exec: (stmt) => {
+            database.exec(stmt);
+        },
+        transaction: database.transaction.bind(database),
+        prepare: (sql) => {
+            const stmt = database.query(sql);
+            return {
+                run: (...params) => stmt.run(...prefixKeys(params)),
+                get: (...params) => stmt.get(...prefixKeys(params)),
+                all: (...params) => stmt.all(...prefixKeys(params)),
+            };
+        },
+        close: () => {
+            // Intentionally empty — the app owns the shared DB's lifecycle.
+        },
+    };
+}

package/dist/server/jobs/polling.d.ts

@@ -0,0 +1,17 @@
+import type { 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 declare function createPollingJob(opts: PollingJobOpts): PollingJob;

package/dist/server/jobs/polling.js

@@ -0,0 +1,79 @@
+import { defaultJobLogger } from './logger';
+/**
+ * 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) {
+    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 = null;
+    let controller = null;
+    let inFlight = false;
+    const fire = async () => {
+        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 = { 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;
+        },
+    };
+}

package/dist/server/jobs/runner.d.ts

@@ -0,0 +1,24 @@
+import type { Database } from 'bun:sqlite';
+import { type CreateJobRunnerOptions, type JobRunner } from './types';
+/**
+ * Create the durable cron job runner — a thin facade over **plainjob** (MIT,
+ * SQLite-backed, no Redis). It generalizes ca's scattered `setInterval` cron-ish
+ * pollers + backup-target-hour check into one restart-aware runner whose schedules
+ * live in the *same* SQLite file as the business data (no separate store).
+ *
+ * Audit trail: every run (cron-fired or {@link JobRunner.runOnce}) writes a
+ * `job_runs` row — `running` on start, then `ok`/`error` on finish — so the admin
+ * "last run" view and {@link JobRunner.getLastRun} reflect reality. plainjob keeps
+ * its OWN internal tables (`plainjob_jobs`, `plainjob_scheduled_jobs`); the
+ * `job_runs`/`job_state` plumbing tables (task 22) are this wrapper's audit view
+ * and never collide with them.
+ *
+ * History is bounded by default ({@link DEFAULT_JOB_RETENTION}): `job_runs` is
+ * pruned lazily (age window + per-job row cap, at most once per prune interval),
+ * and plainjob's maintenance timer removes its internal done/failed rows on the
+ * configured horizons — so a sub-minute cron can run for months without the DB
+ * growing without bound.
+ *
+ * The `job_runs` table must already exist (the app's migration runner builds it).
+ */
+export declare function createJobRunner(db: Database, opts?: CreateJobRunnerOptions): JobRunner;

package/dist/server/jobs/runner.js

@@ -0,0 +1,186 @@
+import { defineQueue, defineWorker } from 'plainjob';
+import { ApiError } from '../errors';
+import { defaultJobLogger } from './logger';
+import { createPlainjobConnection } from './plainjobAdapter';
+import { withTimeout } from './timeout';
+import { DEFAULT_JOB_RETENTION, DEFAULT_JOB_TIMEOUT_MS, } from './types';
+/**
+ * Create the durable cron job runner — a thin facade over **plainjob** (MIT,
+ * SQLite-backed, no Redis). It generalizes ca's scattered `setInterval` cron-ish
+ * pollers + backup-target-hour check into one restart-aware runner whose schedules
+ * live in the *same* SQLite file as the business data (no separate store).
+ *
+ * Audit trail: every run (cron-fired or {@link JobRunner.runOnce}) writes a
+ * `job_runs` row — `running` on start, then `ok`/`error` on finish — so the admin
+ * "last run" view and {@link JobRunner.getLastRun} reflect reality. plainjob keeps
+ * its OWN internal tables (`plainjob_jobs`, `plainjob_scheduled_jobs`); the
+ * `job_runs`/`job_state` plumbing tables (task 22) are this wrapper's audit view
+ * and never collide with them.
+ *
+ * History is bounded by default ({@link DEFAULT_JOB_RETENTION}): `job_runs` is
+ * pruned lazily (age window + per-job row cap, at most once per prune interval),
+ * and plainjob's maintenance timer removes its internal done/failed rows on the
+ * configured horizons — so a sub-minute cron can run for months without the DB
+ * growing without bound.
+ *
+ * The `job_runs` table must already exist (the app's migration runner builds it).
+ */
+export function createJobRunner(db, opts = {}) {
+    const logger = opts.logger ?? defaultJobLogger;
+    const pollIntervalMs = opts.pollIntervalMs ?? 1000;
+    const retention = { ...DEFAULT_JOB_RETENTION, ...opts.retention };
+    const defs = new Map();
+    const workers = new Map();
+    let queue = null;
+    let started = false;
+    let stopped = false;
+    // Aborted on stop() so every in-flight handler's context signal fires.
+    const stopController = new AbortController();
+    const insertRun = db.prepare("INSERT INTO job_runs (id, job_name, started_at, status) VALUES (?, ?, ?, 'running')");
+    const finishRun = db.prepare('UPDATE job_runs SET ended_at = ?, status = ?, error = ? WHERE id = ?');
+    const lastRunQuery = db.query(`SELECT started_at AS startedAt, ended_at AS endedAt, status, error
+       FROM job_runs WHERE job_name = ? ORDER BY started_at DESC, rowid DESC LIMIT 1`);
+    let lastPruneAt = 0;
+    /**
+     * Lazily bound the `job_runs` audit table: an age window (ISO-8601 strings
+     * compare lexicographically, so plain `<` is correct) plus a newest-N cap per
+     * job name. Runs at most once per `pruneIntervalMs`, after a run finishes, and
+     * never lets a prune failure disturb the run that triggered it.
+     */
+    function maybePruneAudit() {
+        const now = Date.now();
+        if (now - lastPruneAt < retention.pruneIntervalMs)
+            return;
+        lastPruneAt = now;
+        try {
+            if (retention.auditMaxAgeMs > 0) {
+                db.query('DELETE FROM job_runs WHERE started_at < ?').run(new Date(now - retention.auditMaxAgeMs).toISOString());
+            }
+            if (retention.auditMaxRowsPerJob > 0) {
+                db.query(`DELETE FROM job_runs WHERE id IN (
+             SELECT id FROM (
+               SELECT id, ROW_NUMBER() OVER (
+                 PARTITION BY job_name ORDER BY started_at DESC, rowid DESC
+               ) AS rn FROM job_runs
+             ) WHERE rn > ?
+           )`).run(retention.auditMaxRowsPerJob);
+            }
+        }
+        catch (err) {
+            logger.warn('[jobs] audit prune failed (non-fatal)', err);
+        }
+    }
+    // plainjob's queue (and its maintenance timer) is created lazily — a runner with
+    // only manual (`runOnce`) jobs never touches plainjob at all. A retention field
+    // of 0 means "never remove"; plainjob has no explicit off switch, so it maps to
+    // an effectively-infinite horizon.
+    function ensureQueue() {
+        if (!queue) {
+            queue = defineQueue({
+                connection: createPlainjobConnection(db),
+                logger,
+                removeDoneJobsOlderThan: retention.doneJobsMaxAgeMs > 0 ? retention.doneJobsMaxAgeMs : Number.MAX_SAFE_INTEGER,
+                removeFailedJobsOlderThan: retention.failedJobsMaxAgeMs > 0 ? retention.failedJobsMaxAgeMs : Number.MAX_SAFE_INTEGER,
+            });
+        }
+        return queue;
+    }
+    /**
+     * Run one job: write the audit row, build a per-run abort signal (fires on stop
+     * OR timeout), run with the timeout, then record `ok`/`error`. Re-throws only
+     * when `rethrow` is set — the cron worker path swallows (the audit row is the
+     * record of truth, and plainjob would otherwise double-log + retain the failure),
+     * while `runOnce` surfaces the error to its admin caller.
+     */
+    async function executeJob(def, rethrow) {
+        const id = crypto.randomUUID();
+        insertRun.run(id, def.name, new Date().toISOString());
+        const runController = new AbortController();
+        const propagateStop = () => runController.abort(stopController.signal.reason);
+        if (stopController.signal.aborted)
+            propagateStop();
+        else
+            stopController.signal.addEventListener('abort', propagateStop, { once: true });
+        const context = { db, signal: runController.signal, logger };
+        try {
+            await withTimeout(Promise.resolve(def.run(context)), def.timeout ?? DEFAULT_JOB_TIMEOUT_MS, () => runController.abort(new Error(`job "${def.name}" timed out`)));
+            finishRun.run(new Date().toISOString(), 'ok', null, id);
+        }
+        catch (err) {
+            finishRun.run(new Date().toISOString(), 'error', String(err), id);
+            logger.error(`[jobs] ${def.name} failed`, err);
+            if (rethrow)
+                throw err;
+        }
+        finally {
+            stopController.signal.removeEventListener('abort', propagateStop);
+            maybePruneAudit();
+        }
+    }
+    function startWorker(def) {
+        const worker = defineWorker(def.name, () => executeJob(def, false), {
+            queue: ensureQueue(),
+            pollIntervall: pollIntervalMs,
+            logger,
+        });
+        workers.set(def.name, worker);
+        // start() resolves only when the worker stops; run it detached.
+        void worker.start().catch((err) => logger.error(`[jobs] worker "${def.name}" crashed`, err));
+    }
+    return {
+        register(job) {
+            if (stopped)
+                throw new Error('cannot register on a stopped job runner');
+            if (defs.has(job.name))
+                throw new Error(`job already registered: ${job.name}`);
+            defs.set(job.name, job);
+            if (job.cron) {
+                // schedule() upserts by type, so re-registering across restarts just
+                // refreshes the cron expression (no duplicate scheduled rows).
+                ensureQueue().schedule(job.name, { cron: job.cron });
+                if (started)
+                    startWorker(job);
+            }
+        },
+        start() {
+            if (stopped)
+                throw new Error('cannot restart a stopped job runner');
+            if (started)
+                return;
+            started = true;
+            for (const def of defs.values())
+                if (def.cron)
+                    startWorker(def);
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            started = false;
+            stopController.abort(new Error('job runner stopped'));
+            await Promise.all([...workers.values()].map((worker) => worker.stop()));
+            workers.clear();
+            // Closes the queue's maintenance timer; the adapter's no-op close keeps the
+            // shared DB open for the rest of shutdown.
+            queue?.close();
+            queue = null;
+        },
+        async runOnce(name) {
+            const def = defs.get(name);
+            if (!def)
+                throw new ApiError(404, `Unknown job: ${name}`);
+            await executeJob(def, true);
+        },
+        getLastRun(name) {
+            const row = lastRunQuery.get(name);
+            if (!row)
+                return null;
+            const record = { startedAt: row.startedAt, status: row.status };
+            if (row.endedAt !== null)
+                record.endedAt = row.endedAt;
+            if (row.error !== null)
+                record.error = row.error;
+            return record;
+        },
+    };
+}

package/dist/server/jobs/timeout.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A promise-timeout for in-process job handlers.
+ *
+ * NB: cwip's `runWithTimeout` is a *subprocess* runner (it spawns + kills a child
+ * process), so it is the wrong tool for racing an in-process handler promise — we
+ * own this tiny helper instead. The timer is `unref()`'d so it never keeps the
+ * event loop alive, and it is always cleared once the race settles.
+ */
+/** Thrown when a job handler exceeds its `timeout`. */
+export declare class JobTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Resolve/reject with `promise`, but reject with a {@link JobTimeoutError} if it
+ * has not settled within `timeoutMs`. `onTimeout` fires on timeout — the runner
+ * uses it to abort the handler's context signal so a cooperative handler can
+ * short-circuit (a pending promise cannot be force-cancelled).
+ *
+ * Order matters: the timeout promise is rejected BEFORE `onTimeout` runs. Aborting
+ * the signal can synchronously resolve a cooperative handler; if that resolution
+ * reached `Promise.race` first the run would be mis-recorded as `ok`. Rejecting
+ * first guarantees a timed-out run is recorded as a timeout, not a success.
+ *
+ * A non-positive / non-finite `timeoutMs` means "no timeout": `promise` is
+ * returned unchanged.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, onTimeout?: () => void): Promise<T>;

package/dist/server/jobs/timeout.js

@@ -0,0 +1,47 @@
+/**
+ * A promise-timeout for in-process job handlers.
+ *
+ * NB: cwip's `runWithTimeout` is a *subprocess* runner (it spawns + kills a child
+ * process), so it is the wrong tool for racing an in-process handler promise — we
+ * own this tiny helper instead. The timer is `unref()`'d so it never keeps the
+ * event loop alive, and it is always cleared once the race settles.
+ */
+/** Thrown when a job handler exceeds its `timeout`. */
+export class JobTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Job timed out after ${timeoutMs}ms`);
+        this.name = 'JobTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Resolve/reject with `promise`, but reject with a {@link JobTimeoutError} if it
+ * has not settled within `timeoutMs`. `onTimeout` fires on timeout — the runner
+ * uses it to abort the handler's context signal so a cooperative handler can
+ * short-circuit (a pending promise cannot be force-cancelled).
+ *
+ * Order matters: the timeout promise is rejected BEFORE `onTimeout` runs. Aborting
+ * the signal can synchronously resolve a cooperative handler; if that resolution
+ * reached `Promise.race` first the run would be mis-recorded as `ok`. Rejecting
+ * first guarantees a timed-out run is recorded as a timeout, not a success.
+ *
+ * A non-positive / non-finite `timeoutMs` means "no timeout": `promise` is
+ * returned unchanged.
+ */
+export function withTimeout(promise, timeoutMs, onTimeout) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return promise;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(new JobTimeoutError(timeoutMs));
+            onTimeout?.();
+        }, timeoutMs);
+        timer.unref?.();
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}