@adminiumjs/adminium 0.1.0-rc.1

package/dist/jobs/report-run.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `report-run` job handler (M7 reports track; 07-meta-store.md §3.24,
+ * 09-generated-app.md §5.4).
+ *
+ * LOCKED v1 SEMANTICS: a run resolves the report's page, produces a **CSV
+ * data snapshot THROUGH the M7-T07 export pipeline** (the export-run handler
+ * is invoked in-process via the shared registry — reuse, not a fork), stamps
+ * `last_run_at`/`next_run_at`, and delivers an in-app notification linking
+ * page + export. The stored `format` stays `pdf | png` (§3.24 vocabulary):
+ * that is the user's rendering INTENT, preserved for the release where a
+ * renderer exists; the UI labels delivery "Data snapshot (PDF/PNG rendering
+ * arrives in a later release)".
+ *
+ * Grants: the snapshot always runs MASKED (`unmasked: false`). An export
+ * request captures the caller's live PII capability at request time; a
+ * scheduled run has no request to capture from, and replaying a capability
+ * the creator held at schedule time could outlive a revocation — masked is
+ * the only honest default. The same revocation logic applies to ROW data:
+ * every run re-resolves the creator's live permission set and requires the
+ * `table:<conn>:<table>:export` grant before creating the export row (this
+ * path bypasses POST /exports, the only other place that grant is checked).
+ *
+ * Failures advance the schedule (recordRun still fires) so a misconfigured
+ * report never hot-loops the queue, and the creator is TOLD via a
+ * `report.failed` notification instead of a silent skip.
+ */
+import { type Job, type MetaDb } from '@adminium/meta';
+import type { EnqueueJobInput } from '@adminium/meta';
+import { z } from 'zod';
+import { type NotificationPublisher } from '../notifications/notify.js';
+import type { JobRegistry } from './registry.js';
+export declare const REPORT_RUN_KIND = "report-run";
+export declare const reportRunPayloadSchema: z.ZodObject<{
+    reportId: z.ZodString;
+    userId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReportRunPayload = z.infer<typeof reportRunPayloadSchema>;
+/** Notification kinds this handler produces (stable localization keys). */
+export declare const REPORT_READY_KIND = "report.ready";
+export declare const REPORT_FAILED_KIND = "report.failed";
+/** compose.ts poll-schedule identity (jobs.scheduler.registerSchedule). */
+export declare const SCHEDULED_REPORTS_POLL_NAME = "scheduled-reports-poll";
+export declare const SCHEDULED_REPORTS_POLL_CRON = "* * * * *";
+export interface ReportRunDeps {
+    meta: MetaDb;
+    /**
+     * The SAME registry the export-run handler is registered on — report-run
+     * drives the export pipeline through it (`registry.get(EXPORT_RUN_KIND)`),
+     * so the two handlers can never drift apart on snapshot semantics.
+     */
+    registry: JobRegistry;
+    /** `app.realtime` — notifications fan out on `notifications:<userId>`. */
+    hub?: NotificationPublisher | undefined;
+    now?: (() => number) | undefined;
+}
+export declare function registerReportRunHandler(registry: JobRegistry, deps: ReportRunDeps): void;
+/**
+ * The compose.ts poll body (scheduler → queue seam): enqueue one `report-run`
+ * per due report. The `dedupeKey` carries the due stamp, so a poll tick that
+ * fires while the previous run of the SAME occurrence is still queued/running
+ * collapses into it, while the next occurrence gets a fresh key.
+ */
+export declare function enqueueDueReports(meta: MetaDb, enqueue: (input: EnqueueJobInput) => Promise<Job>, at?: number): Promise<Job | null>;
+//# sourceMappingURL=report-run.d.ts.map

package/dist/jobs/report-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-run.d.ts","sourceRoot":"","sources":["../../src/jobs/report-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAgD,KAAK,GAAG,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACrG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAU,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGhF,OAAO,KAAK,EAAqB,WAAW,EAAE,MAAM,eAAe,CAAC;AAEpE,eAAO,MAAM,eAAe,eAAe,CAAC;AAE5C,eAAO,MAAM,sBAAsB;;;iBAIjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAChD,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,2EAA2E;AAC3E,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AACpE,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,WAAW,CAAC;IACtB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACxC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAClC;AAOD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAKzF;AAoKD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,GAAG,CAAC,EACjD,EAAE,GAAE,MAAmB,GACtB,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAcrB"}

package/dist/jobs/report-run.js

@@ -0,0 +1,221 @@
+/**
+ * `report-run` job handler (M7 reports track; 07-meta-store.md §3.24,
+ * 09-generated-app.md §5.4).
+ *
+ * LOCKED v1 SEMANTICS: a run resolves the report's page, produces a **CSV
+ * data snapshot THROUGH the M7-T07 export pipeline** (the export-run handler
+ * is invoked in-process via the shared registry — reuse, not a fork), stamps
+ * `last_run_at`/`next_run_at`, and delivers an in-app notification linking
+ * page + export. The stored `format` stays `pdf | png` (§3.24 vocabulary):
+ * that is the user's rendering INTENT, preserved for the release where a
+ * renderer exists; the UI labels delivery "Data snapshot (PDF/PNG rendering
+ * arrives in a later release)".
+ *
+ * Grants: the snapshot always runs MASKED (`unmasked: false`). An export
+ * request captures the caller's live PII capability at request time; a
+ * scheduled run has no request to capture from, and replaying a capability
+ * the creator held at schedule time could outlive a revocation — masked is
+ * the only honest default. The same revocation logic applies to ROW data:
+ * every run re-resolves the creator's live permission set and requires the
+ * `table:<conn>:<table>:export` grant before creating the export row (this
+ * path bypasses POST /exports, the only other place that grant is checked).
+ *
+ * Failures advance the schedule (recordRun still fires) so a misconfigured
+ * report never hot-loops the queue, and the creator is TOLD via a
+ * `report.failed` notification instead of a silent skip.
+ */
+import { exportsRepo, pagesRepo, scheduledReportsRepo } from '@adminium/meta';
+import { z } from 'zod';
+import { loadSnapshotView } from '../data-io/snapshot-view.js';
+import { nextRunAtOf } from '../reports/schedule.js';
+import { notify } from '../notifications/notify.js';
+import { permissionSetAllows, resolvePermissionSet } from '../rbac/resolver.js';
+import { EXPORT_RUN_KIND, exportRunPayloadSchema } from './export-run.js';
+export const REPORT_RUN_KIND = 'report-run';
+export const reportRunPayloadSchema = z.object({
+    reportId: z.string().min(1),
+    /** Owner convention (routes/jobs): the report's creator. */
+    userId: z.string().optional(),
+});
+/** Notification kinds this handler produces (stable localization keys). */
+export const REPORT_READY_KIND = 'report.ready';
+export const REPORT_FAILED_KIND = 'report.failed';
+/** compose.ts poll-schedule identity (jobs.scheduler.registerSchedule). */
+export const SCHEDULED_REPORTS_POLL_NAME = 'scheduled-reports-poll';
+export const SCHEDULED_REPORTS_POLL_CRON = '* * * * *';
+/** The page-envelope slice a report needs (01-architecture.md §6.1). */
+const envelopeSourceSchema = z.object({
+    source: z.object({ connectionId: z.string().nullable(), table: z.string().nullable() }),
+});
+export function registerReportRunHandler(registry, deps) {
+    const now = deps.now ?? Date.now;
+    registry.registerJobHandler(REPORT_RUN_KIND, reportRunPayloadSchema, async (payload, ctx) => {
+        return executeReportRun(payload, ctx, deps, now);
+    });
+}
+async function executeReportRun(payload, ctx, deps, now) {
+    const reports = scheduledReportsRepo(deps.meta);
+    const report = await reports.findById(payload.reportId);
+    if (report === null) {
+        ctx.log('report-run: report not found, skipping', { reportId: payload.reportId });
+        return { reportId: payload.reportId, exportId: null };
+    }
+    if (!report.enabled) {
+        ctx.log('report-run: report disabled, skipping', { reportId: report.id });
+        return { reportId: report.id, exportId: null };
+    }
+    /** Stamp the run + park the next occurrence — fires on EVERY outcome. */
+    const finishRun = async () => {
+        const at = now();
+        await reports.recordRun(report.id, { lastRunAt: at, nextRunAt: nextRunAtOf(report.schedule, at) });
+    };
+    const fail = async (reason) => {
+        ctx.log('report-run: failed', { reportId: report.id, reason });
+        // Schedule advance FIRST: it must never depend on notification delivery —
+        // a lost notification is recoverable, a per-minute re-run loop is not.
+        await finishRun();
+        if (report.createdBy !== null) {
+            try {
+                await notify(deps.meta, {
+                    userId: report.createdBy,
+                    kind: REPORT_FAILED_KIND,
+                    title: `Report failed: ${report.name}`,
+                    body: reason,
+                    entity: { reportId: report.id, pageId: report.pageId, reason },
+                    actionUrl: '/reports',
+                }, { hub: deps.hub, at: now() });
+            }
+            catch (error) {
+                ctx.log('report-run: failed-notification delivery failed', {
+                    reportId: report.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return { reportId: report.id, exportId: null };
+    };
+    const page = await pagesRepo(deps.meta).findById(report.pageId);
+    if (page === null)
+        return fail('The report’s page no longer exists.');
+    const parsed = envelopeSourceSchema.safeParse(page.config);
+    const source = parsed.success ? parsed.data.source : null;
+    if (source === null || source.connectionId === null || source.table === null) {
+        return fail('The report’s page has no table source to snapshot.');
+    }
+    if (report.createdBy === null) {
+        // adminium_exports.requested_by is NOT NULL — without a creator there is
+        // no principal to own the artifact (or receive the notification).
+        return fail('The report has no owner to run as (its creator was deleted).');
+    }
+    // LIVE grant re-check (wave-2 audit): scheduling requires only
+    // `system:reports:manage`, and the export row below is created OUTSIDE the
+    // POST /exports route — the only place `table:<conn>:<table>:export` is
+    // otherwise enforced. The creator must STILL hold the export grant at run
+    // time, so a revoked creator stops receiving snapshots (the doc-comment's
+    // revocation concern, applied to row data, not just PII).
+    let resolvedTableId;
+    try {
+        const view = await loadSnapshotView(deps.meta, source.connectionId);
+        resolvedTableId = view.table(source.table).id;
+    }
+    catch {
+        return fail('The report’s table no longer exists in the schema snapshot.');
+    }
+    const exportPermission = `table:${source.connectionId}:${resolvedTableId}:export`;
+    const creatorSet = await resolvePermissionSet(deps.meta, {
+        kind: 'user',
+        id: report.createdBy,
+        label: report.createdBy,
+    });
+    if (!permissionSetAllows(creatorSet, exportPermission)) {
+        return fail('You no longer have export access to this report’s table.');
+    }
+    const exportEntry = deps.registry.get(EXPORT_RUN_KIND);
+    if (exportEntry === undefined) {
+        // Registration bug, not a data problem — surface it as a job failure.
+        throw new Error('report-run: the export-run handler is not registered on this registry');
+    }
+    ctx.progress(10, { step: 'snapshot', message: `Snapshotting ${source.table}` });
+    const exportRow = await exportsRepo(deps.meta).create({
+        connectionId: source.connectionId,
+        requestedBy: report.createdBy,
+        source: { kind: 'table', table: source.table },
+        format: 'csv',
+    });
+    try {
+        const exportPayload = exportRunPayloadSchema.parse({
+            exportId: exportRow.id,
+            userId: report.createdBy,
+            unmasked: false,
+        });
+        await exportEntry.run(exportPayload, ctx);
+    }
+    catch (error) {
+        // export-run absorbs deterministic failures itself (marks the row); a
+        // throw here is unexpected — mark our side and advance the schedule.
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+    const finished = await exportsRepo(deps.meta).findById(exportRow.id);
+    if (finished === null || finished.status !== 'ready') {
+        return fail(finished?.error ?? `Snapshot export ended ${finished?.status ?? 'missing'}.`);
+    }
+    // Advance the schedule BEFORE the ready-notification: a notify/hub throw
+    // with `next_run_at` still in the past would re-run the whole snapshot on
+    // every poll tick — one fresh export artifact per minute (wave-2 audit).
+    await finishRun();
+    try {
+        await notify(deps.meta, {
+            userId: report.createdBy,
+            kind: REPORT_READY_KIND,
+            title: `Report ready: ${report.name}`,
+            body: `${String(finished.rowCount ?? 0)} rows · CSV data snapshot`,
+            entity: {
+                reportId: report.id,
+                reportName: report.name,
+                pageId: report.pageId,
+                pageSlug: page.slug,
+                pageTitle: page.title,
+                exportId: finished.id,
+                rowCount: finished.rowCount,
+                // The stored intent vs. what this build delivers — the client copy
+                // explains the degradation (§8.2), it is never hidden.
+                requestedFormat: report.format,
+                delivered: 'csv-snapshot',
+            },
+            actionUrl: '/exports',
+        }, { hub: deps.hub, at: now() });
+    }
+    catch (error) {
+        // The export is ready and listed under /exports — a lost notification is
+        // recoverable there and must not fail (and re-loop) the run.
+        ctx.log('report-run: ready-notification delivery failed', {
+            reportId: report.id,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    ctx.progress(100, { step: 'done', message: `Report ${report.name} ready` });
+    ctx.log('report-run: ready', { reportId: report.id, exportId: finished.id });
+    return { reportId: report.id, exportId: finished.id };
+}
+/**
+ * The compose.ts poll body (scheduler → queue seam): enqueue one `report-run`
+ * per due report. The `dedupeKey` carries the due stamp, so a poll tick that
+ * fires while the previous run of the SAME occurrence is still queued/running
+ * collapses into it, while the next occurrence gets a fresh key.
+ */
+export async function enqueueDueReports(meta, enqueue, at = Date.now()) {
+    const due = await scheduledReportsRepo(meta).listDue(at);
+    let last = null;
+    for (const report of due) {
+        last = await enqueue({
+            kind: REPORT_RUN_KIND,
+            payload: {
+                reportId: report.id,
+                ...(report.createdBy === null ? {} : { userId: report.createdBy }),
+            },
+            dedupeKey: `report-run:${report.id}:${String(report.nextRunAt ?? at)}`,
+        });
+    }
+    return last;
+}
+//# sourceMappingURL=report-run.js.map

package/dist/jobs/report-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-run.js","sourceRoot":"","sources":["../../src/jobs/report-run.ts"],"names":[],"mappings":"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"}

package/dist/jobs/scheduler.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Croner-based schedule registry (08-server-api.md §2 jobs plugin, BRIEF §3:
+ * croner + no Redis; M2-T07). Each named schedule fires an enqueue function;
+ * a no-overlap guard skips the tick when the previously enqueued job is
+ * still pending/running, and optional jitter de-synchronizes fleets.
+ *
+ * Timezone is fixed to UTC for now — it becomes settings-driven
+ * (`adminium_settings`) in a later wave (10-i18n-theming.md).
+ */
+import type { Job } from '@adminium/meta';
+import type { WorkerLogger } from './worker.js';
+/** Default scheduler timezone until settings wiring lands. */
+export declare const SCHEDULER_TIMEZONE = "UTC";
+/** Enqueue callback: returns the created job (or null/void when skipped). */
+export type ScheduleEnqueue = () => Promise<{
+    id: string;
+} | null | undefined | void>;
+export interface RegisterScheduleOptions {
+    /** Random 0..jitterMs delay before enqueueing; default scheduler-wide value. */
+    jitterMs?: number | undefined;
+}
+export type ScheduleTriggerResult = {
+    status: 'enqueued';
+    jobId: string | null;
+} | {
+    status: 'skipped-overlap';
+    jobId: string;
+} | {
+    status: 'skipped-inflight';
+};
+export interface JobSchedulerOptions {
+    /** Status lookup for the no-overlap guard (`jobsRepo` satisfies it). */
+    jobs: {
+        findById(id: string): Promise<Job | null>;
+    };
+    /** IANA zone for cron evaluation; default UTC (settings-driven later). */
+    timezone?: string | undefined;
+    /** Default jitter applied to every schedule; default 0. */
+    defaultJitterMs?: number | undefined;
+    logger?: WorkerLogger | undefined;
+    /** Injectable randomness for deterministic jitter tests. */
+    random?: (() => number) | undefined;
+}
+export declare class JobScheduler {
+    private readonly jobs;
+    private readonly timezone;
+    private readonly defaultJitterMs;
+    private readonly logger;
+    private readonly random;
+    private readonly schedules;
+    private started;
+    constructor(opts: JobSchedulerOptions);
+    /**
+     * Register a named cron schedule. The Cron instance is created immediately
+     * (invalid expressions throw here) but stays paused until `start()`.
+     */
+    registerSchedule(name: string, cronExpr: string, enqueue: ScheduleEnqueue, opts?: RegisterScheduleOptions): void;
+    /** Resume all schedules; schedules registered later start immediately. */
+    start(): void;
+    /** Stop every cron; safe to call repeatedly. */
+    stop(): void;
+    names(): string[];
+    /** Next run time of a schedule, or null when stopped/unknown. */
+    nextRun(name: string): Date | null;
+    /**
+     * The guarded fire path — called by cron ticks and directly by tests.
+     * Skips when the previous enqueued job is still pending/running (no
+     * overlap) or when a previous tick's enqueue has not returned yet.
+     */
+    trigger(name: string): Promise<ScheduleTriggerResult>;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/jobs/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/jobs/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,6EAA6E;AAC7E,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;AAEtF,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAEnC,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAA;KAAE,CAAC;IACpD,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAClC,4DAA4D;IAC5D,MAAM,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CACrC;AAgBD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAC9D,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,mBAAmB;IAQrC;;;OAGG;IACH,gBAAgB,CACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE,uBAA4B,GACjC,IAAI;IAmCP,0EAA0E;IAC1E,KAAK,IAAI,IAAI;IAKb,gDAAgD;IAChD,IAAI,IAAI,IAAI;IAKZ,KAAK,IAAI,MAAM,EAAE;IAIjB,iEAAiE;IACjE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIlC;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CA6B5D"}

package/dist/jobs/scheduler.js

@@ -0,0 +1,121 @@
+/**
+ * Croner-based schedule registry (08-server-api.md §2 jobs plugin, BRIEF §3:
+ * croner + no Redis; M2-T07). Each named schedule fires an enqueue function;
+ * a no-overlap guard skips the tick when the previously enqueued job is
+ * still pending/running, and optional jitter de-synchronizes fleets.
+ *
+ * Timezone is fixed to UTC for now — it becomes settings-driven
+ * (`adminium_settings`) in a later wave (10-i18n-theming.md).
+ */
+import { Cron } from 'croner';
+/** Default scheduler timezone until settings wiring lands. */
+export const SCHEDULER_TIMEZONE = 'UTC';
+const noopLogger = { info() { }, warn() { }, error() { } };
+export class JobScheduler {
+    jobs;
+    timezone;
+    defaultJitterMs;
+    logger;
+    random;
+    schedules = new Map();
+    started = false;
+    constructor(opts) {
+        this.jobs = opts.jobs;
+        this.timezone = opts.timezone ?? SCHEDULER_TIMEZONE;
+        this.defaultJitterMs = opts.defaultJitterMs ?? 0;
+        this.logger = opts.logger ?? noopLogger;
+        this.random = opts.random ?? Math.random;
+    }
+    /**
+     * Register a named cron schedule. The Cron instance is created immediately
+     * (invalid expressions throw here) but stays paused until `start()`.
+     */
+    registerSchedule(name, cronExpr, enqueue, opts = {}) {
+        if (this.schedules.has(name)) {
+            throw new Error(`schedule "${name}" is already registered`);
+        }
+        const cron = new Cron(cronExpr, {
+            name,
+            paused: true,
+            timezone: this.timezone,
+            // croner's own overlap guard for the callback itself; the job-status
+            // guard in trigger() covers the enqueued job's lifetime.
+            protect: true,
+            catch: (err) => {
+                this.logger.error({ schedule: name, err }, 'schedule tick failed');
+            },
+        }, () => {
+            void this.trigger(name).catch((err) => {
+                this.logger.error({ schedule: name, err }, 'schedule trigger failed');
+            });
+        });
+        this.schedules.set(name, {
+            name,
+            cronExpr,
+            enqueue,
+            jitterMs: opts.jitterMs ?? this.defaultJitterMs,
+            cron,
+            inFlight: false,
+            lastJobId: null,
+        });
+        if (this.started)
+            cron.resume();
+    }
+    /** Resume all schedules; schedules registered later start immediately. */
+    start() {
+        this.started = true;
+        for (const entry of this.schedules.values())
+            entry.cron.resume();
+    }
+    /** Stop every cron; safe to call repeatedly. */
+    stop() {
+        this.started = false;
+        for (const entry of this.schedules.values())
+            entry.cron.stop();
+    }
+    names() {
+        return [...this.schedules.keys()];
+    }
+    /** Next run time of a schedule, or null when stopped/unknown. */
+    nextRun(name) {
+        return this.schedules.get(name)?.cron.nextRun() ?? null;
+    }
+    /**
+     * The guarded fire path — called by cron ticks and directly by tests.
+     * Skips when the previous enqueued job is still pending/running (no
+     * overlap) or when a previous tick's enqueue has not returned yet.
+     */
+    async trigger(name) {
+        const entry = this.schedules.get(name);
+        if (entry === undefined)
+            throw new Error(`unknown schedule "${name}"`);
+        if (entry.inFlight)
+            return { status: 'skipped-inflight' };
+        if (entry.lastJobId !== null) {
+            const previous = await this.jobs.findById(entry.lastJobId);
+            if (previous !== null && (previous.status === 'pending' || previous.status === 'running')) {
+                this.logger.info({ schedule: name, jobId: entry.lastJobId, status: previous.status }, 'schedule tick skipped — previous job still active');
+                return { status: 'skipped-overlap', jobId: entry.lastJobId };
+            }
+        }
+        entry.inFlight = true;
+        try {
+            if (entry.jitterMs > 0) {
+                await sleep(Math.floor(this.random() * entry.jitterMs));
+            }
+            const job = await entry.enqueue();
+            entry.lastJobId = job?.id ?? null;
+            return { status: 'enqueued', jobId: entry.lastJobId };
+        }
+        finally {
+            entry.inFlight = false;
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/jobs/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/jobs/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAM9B,8DAA8D;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAuCxC,MAAM,UAAU,GAAiB,EAAE,IAAI,KAAI,CAAC,EAAE,IAAI,KAAI,CAAC,EAAE,KAAK,KAAI,CAAC,EAAE,CAAC;AAEtE,MAAM,OAAO,YAAY;IACN,IAAI,CAA8B;IAClC,QAAQ,CAAS;IACjB,eAAe,CAAS;IACxB,MAAM,CAAe;IACrB,MAAM,CAAe;IACrB,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;IACtD,OAAO,GAAG,KAAK,CAAC;IAExB,YAAY,IAAyB;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,kBAAkB,CAAC;QACpD,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACH,gBAAgB,CACd,IAAY,EACZ,QAAgB,EAChB,OAAwB,EACxB,OAAgC,EAAE;QAElC,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,yBAAyB,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,IAAI,CACnB,QAAQ,EACR;YACE,IAAI;YACJ,MAAM,EAAE,IAAI;YACZ,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,qEAAqE;YACrE,yDAAyD;YACzD,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,CAAC,GAAY,EAAE,EAAE;gBACtB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,sBAAsB,CAAC,CAAC;YACrE,CAAC;SACF,EACD,GAAG,EAAE;YACH,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBAC7C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,yBAAyB,CAAC,CAAC;YACxE,CAAC,CAAC,CAAC;QACL,CAAC,CACF,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE;YACvB,IAAI;YACJ,QAAQ;YACR,OAAO;YACP,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,eAAe;YAC/C,IAAI;YACJ,QAAQ,EAAE,KAAK;YACf,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAClC,CAAC;IAED,0EAA0E;IAC1E,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACnE,CAAC;IAED,gDAAgD;IAChD,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACjE,CAAC;IAED,KAAK;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,iEAAiE;IACjE,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC;IAC1D,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,GAAG,CAAC,CAAC;QAEvE,IAAI,KAAK,CAAC,QAAQ;YAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;QAE1D,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAC7B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YAC3D,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,CAAC,EAAE,CAAC;gBAC1F,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,EACnE,mDAAmD,CACpD,CAAC;gBACF,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;YAC/D,CAAC;QACH,CAAC;QAED,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC;YACH,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;gBACvB,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC1D,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YAClC,KAAK,CAAC,SAAS,GAAG,GAAG,EAAE,EAAE,IAAI,IAAI,CAAC;YAClC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;QACxD,CAAC;gBAAS,CAAC;YACT,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC;QACzB,CAAC;IACH,CAAC;CACF;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/jobs/worker.d.ts

@@ -0,0 +1,110 @@
+/**
+ * In-process polling worker over `adminium_jobs` (01-architecture.md §5
+ * background path, 07-meta-store.md §3.12, M2-T07).
+ *
+ * Loop: claim via the portable UPDATE guard (`jobsRepo.claim`) → parse the
+ * payload against the registered handler's schema → run the handler with a
+ * progress/log/cancel context → `complete` or `fail` with exponential backoff
+ * (base 30 s, doubling, capped at 1 h) until `maxAttempts`, after which the
+ * row lands in terminal `failed` (the dead-letter state). One failing job
+ * never kills the process (08-server-api.md §6.10); `stop()` drains in-flight
+ * jobs before resolving (graceful shutdown).
+ *
+ * Progress is kept in-memory (`getProgress`) and published on `jobs:<jobId>`
+ * — the meta schema has no progress column in wave 0001, and the worker runs
+ * in-process with the API (01 §5), so route reads stay consistent.
+ */
+import { type MetaDb } from '@adminium/meta';
+import type { RealtimeHub } from '../realtime/hub.js';
+import type { JobProgress, JobRegistry } from './registry.js';
+/** Backoff ceiling: no retry waits longer than an hour. */
+export declare const JOB_BACKOFF_MAX_MS = 3600000;
+/** Default number of jobs executing concurrently in one worker. */
+export declare const JOB_WORKER_CONCURRENCY = 2;
+/** Default idle delay between claim polls. */
+export declare const JOB_POLL_INTERVAL_MS = 1000;
+/** Minimal structured logger (satisfied by `app.log` / pino). */
+export interface WorkerLogger {
+    info(obj: Record<string, unknown>, msg?: string): void;
+    warn(obj: Record<string, unknown>, msg?: string): void;
+    error(obj: Record<string, unknown>, msg?: string): void;
+}
+export interface JobWorkerOptions {
+    meta: MetaDb;
+    registry: JobRegistry;
+    hub: RealtimeHub;
+    /** Parallel job slots; default {@link JOB_WORKER_CONCURRENCY}. */
+    concurrency?: number | undefined;
+    /** Idle poll delay; default {@link JOB_POLL_INTERVAL_MS}. */
+    pollIntervalMs?: number | undefined;
+    /** `<hostname>:<pid>` per §3.12 unless overridden (tests). */
+    workerId?: string | undefined;
+    /** First-retry delay; default 30 s (§3.12 / repo constant). */
+    backoffBaseMs?: number | undefined;
+    /** Retry-delay ceiling; default 1 h. */
+    backoffMaxMs?: number | undefined;
+    /** Clock, injectable for deterministic backoff tests. */
+    now?: (() => number) | undefined;
+    logger?: WorkerLogger | undefined;
+}
+/** Channel name for a job's realtime events. */
+export declare function jobChannel(jobId: string): string;
+export declare class JobWorker {
+    private readonly meta;
+    private readonly jobs;
+    private readonly registry;
+    private readonly hub;
+    private readonly concurrency;
+    private readonly pollIntervalMs;
+    private readonly backoffBaseMs;
+    private readonly backoffMaxMs;
+    private readonly now;
+    private readonly logger;
+    readonly workerId: string;
+    private readonly running;
+    private readonly progressByJob;
+    private stopped;
+    private pollTimer;
+    constructor(opts: JobWorkerOptions);
+    /** Jobs currently executing in this worker. */
+    get activeCount(): number;
+    /** Last reported progress for a job known to this process, else `null`. */
+    getProgress(jobId: string): JobProgress | null;
+    /**
+     * Cooperative cancel (08 §2.17): aborts the run's signal if this worker is
+     * executing the job. Returns whether a running job was signalled.
+     */
+    requestCancel(jobId: string): boolean;
+    /** Start the poll loop; idempotent. */
+    start(): void;
+    /**
+     * Graceful drain: stop claiming, wait up to `drainTimeoutMs` for in-flight
+     * jobs, then abort stragglers and wait for them to settle.
+     */
+    stop(opts?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Deterministic single pass (tests/manual ticks): claims due jobs up to the
+     * concurrency limit and resolves when all of them finished. Returns how
+     * many jobs this call executed.
+     */
+    runOnce(): Promise<number>;
+    private schedulePoll;
+    private poll;
+    /** Registers the job as running and executes it; never rejects. */
+    private launch;
+    private execute;
+    /** Retry with capped exponential backoff, or dead-letter at maxAttempts. */
+    private handleFailure;
+    /**
+     * Terminal `cancelled` for a job this worker was running (repo `cancel`
+     * only covers pending rows). Guarded on our own lock so a reclaimed stale
+     * job is never clobbered.
+     */
+    private markCancelled;
+    private reportProgress;
+    /** Insertion-ordered map as a tiny LRU: oldest snapshots fall off first. */
+    private setProgress;
+}
+//# sourceMappingURL=worker.d.ts.map

package/dist/jobs/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/jobs/worker.ts"],"names":[],"mappings":"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"}