@fidelios/server 0.0.1

package/dist/services/plugin-job-scheduler.js

@@ -0,0 +1,454 @@
+/**
+ * PluginJobScheduler — tick-based scheduler for plugin scheduled jobs.
+ *
+ * The scheduler is the central coordinator for all plugin cron jobs. It
+ * periodically ticks (default every 30 seconds), queries the `plugin_jobs`
+ * table for jobs whose `nextRunAt` has passed, dispatches `runJob` RPC calls
+ * to the appropriate worker processes, records each execution in the
+ * `plugin_job_runs` table, and advances the scheduling pointer.
+ *
+ * ## Responsibilities
+ *
+ * 1. **Tick loop** — A `setInterval`-based loop fires every `tickIntervalMs`
+ *    (default 30s). Each tick scans for due jobs and dispatches them.
+ *
+ * 2. **Cron parsing & next-run calculation** — Uses the lightweight built-in
+ *    cron parser ({@link parseCron}, {@link nextCronTick}) to compute the
+ *    `nextRunAt` timestamp after each run or when a new job is registered.
+ *
+ * 3. **Overlap prevention** — Before dispatching a job, the scheduler checks
+ *    for an existing `running` run for the same job. If one exists, the job
+ *    is skipped for that tick.
+ *
+ * 4. **Job run recording** — Every execution creates a `plugin_job_runs` row:
+ *    `queued` → `running` → `succeeded` | `failed`. Duration and error are
+ *    captured.
+ *
+ * 5. **Lifecycle integration** — The scheduler exposes `registerPlugin()` and
+ *    `unregisterPlugin()` so the host lifecycle manager can wire up job
+ *    scheduling when plugins start/stop. On registration, the scheduler
+ *    computes `nextRunAt` for all active jobs that don't already have one.
+ *
+ * @see PLUGIN_SPEC.md §17 — Scheduled Jobs
+ * @see ./plugin-job-store.ts — Persistence layer
+ * @see ./cron.ts — Cron parsing utilities
+ */
+import { and, eq, lte, or } from "drizzle-orm";
+import { pluginJobs, pluginJobRuns } from "@fidelios/db";
+import { parseCron, nextCronTick, validateCron } from "./cron.js";
+import { logger } from "../middleware/logger.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default interval between scheduler ticks (30 seconds). */
+const DEFAULT_TICK_INTERVAL_MS = 30_000;
+/** Default timeout for a runJob RPC call (5 minutes). */
+const DEFAULT_JOB_TIMEOUT_MS = 5 * 60 * 1_000;
+/** Maximum number of concurrent job executions across all plugins. */
+const DEFAULT_MAX_CONCURRENT_JOBS = 10;
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Create a new PluginJobScheduler.
+ *
+ * @example
+ * ```ts
+ * const scheduler = createPluginJobScheduler({
+ *   db,
+ *   jobStore,
+ *   workerManager,
+ * });
+ *
+ * // Start the tick loop
+ * scheduler.start();
+ *
+ * // When a plugin comes online, register it
+ * await scheduler.registerPlugin(pluginId);
+ *
+ * // Manually trigger a job
+ * const { runId } = await scheduler.triggerJob(jobId);
+ *
+ * // On server shutdown
+ * scheduler.stop();
+ * ```
+ */
+export function createPluginJobScheduler(options) {
+    const { db, jobStore, workerManager, tickIntervalMs = DEFAULT_TICK_INTERVAL_MS, jobTimeoutMs = DEFAULT_JOB_TIMEOUT_MS, maxConcurrentJobs = DEFAULT_MAX_CONCURRENT_JOBS, } = options;
+    const log = logger.child({ service: "plugin-job-scheduler" });
+    // -----------------------------------------------------------------------
+    // State
+    // -----------------------------------------------------------------------
+    /** Timer handle for the tick loop. */
+    let tickTimer = null;
+    /** Whether the scheduler is running. */
+    let running = false;
+    /** Set of job IDs currently being executed (for overlap prevention). */
+    const activeJobs = new Set();
+    /** Total number of ticks since start. */
+    let tickCount = 0;
+    /** Timestamp of the last tick. */
+    let lastTickAt = null;
+    /** Guard against concurrent tick execution. */
+    let tickInProgress = false;
+    // -----------------------------------------------------------------------
+    // Core: tick
+    // -----------------------------------------------------------------------
+    /**
+     * A single scheduler tick. Queries for due jobs and dispatches them.
+     */
+    async function tick() {
+        // Prevent overlapping ticks (in case a tick takes longer than the interval)
+        if (tickInProgress) {
+            log.debug("skipping tick — previous tick still in progress");
+            return;
+        }
+        tickInProgress = true;
+        tickCount++;
+        lastTickAt = new Date();
+        try {
+            const now = new Date();
+            // Query for jobs whose nextRunAt has passed and are active.
+            // We include jobs with null nextRunAt since they may have just been
+            // registered and need their first run calculated.
+            const dueJobs = await db
+                .select()
+                .from(pluginJobs)
+                .where(and(eq(pluginJobs.status, "active"), lte(pluginJobs.nextRunAt, now)));
+            if (dueJobs.length === 0) {
+                return;
+            }
+            log.debug({ count: dueJobs.length }, "found due jobs");
+            // Dispatch each due job (respecting concurrency limits)
+            const dispatches = [];
+            for (const job of dueJobs) {
+                // Concurrency limit
+                if (activeJobs.size >= maxConcurrentJobs) {
+                    log.warn({ maxConcurrentJobs, activeJobCount: activeJobs.size }, "max concurrent jobs reached, deferring remaining jobs");
+                    break;
+                }
+                // Overlap prevention: skip if this job is already running
+                if (activeJobs.has(job.id)) {
+                    log.debug({ jobId: job.id, jobKey: job.jobKey, pluginId: job.pluginId }, "skipping job — already running (overlap prevention)");
+                    continue;
+                }
+                // Check if the worker is available
+                if (!workerManager.isRunning(job.pluginId)) {
+                    log.debug({ jobId: job.id, pluginId: job.pluginId }, "skipping job — worker not running");
+                    continue;
+                }
+                // Validate cron expression before dispatching
+                if (!job.schedule) {
+                    log.warn({ jobId: job.id, jobKey: job.jobKey }, "skipping job — no schedule defined");
+                    continue;
+                }
+                dispatches.push(dispatchJob(job));
+            }
+            if (dispatches.length > 0) {
+                await Promise.allSettled(dispatches);
+            }
+        }
+        catch (err) {
+            log.error({ err: err instanceof Error ? err.message : String(err) }, "scheduler tick error");
+        }
+        finally {
+            tickInProgress = false;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Core: dispatch a single job
+    // -----------------------------------------------------------------------
+    /**
+     * Dispatch a single job run — create the run record, call the worker,
+     * record the result, and advance the schedule pointer.
+     */
+    async function dispatchJob(job) {
+        const { id: jobId, pluginId, jobKey, schedule } = job;
+        const jobLog = log.child({ jobId, pluginId, jobKey });
+        // Mark as active (overlap prevention)
+        activeJobs.add(jobId);
+        let runId;
+        const startedAt = Date.now();
+        try {
+            // 1. Create run record
+            const run = await jobStore.createRun({
+                jobId,
+                pluginId,
+                trigger: "schedule",
+            });
+            runId = run.id;
+            jobLog.info({ runId }, "dispatching scheduled job");
+            // 2. Mark run as running
+            await jobStore.markRunning(runId);
+            // 3. Call worker via RPC
+            await workerManager.call(pluginId, "runJob", {
+                job: {
+                    jobKey,
+                    runId,
+                    trigger: "schedule",
+                    scheduledAt: (job.nextRunAt ?? new Date()).toISOString(),
+                },
+            }, jobTimeoutMs);
+            // 4. Mark run as succeeded
+            const durationMs = Date.now() - startedAt;
+            await jobStore.completeRun(runId, {
+                status: "succeeded",
+                durationMs,
+            });
+            jobLog.info({ runId, durationMs }, "job completed successfully");
+        }
+        catch (err) {
+            const durationMs = Date.now() - startedAt;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            jobLog.error({ runId, durationMs, err: errorMessage }, "job execution failed");
+            // Record the failure
+            if (runId) {
+                try {
+                    await jobStore.completeRun(runId, {
+                        status: "failed",
+                        error: errorMessage,
+                        durationMs,
+                    });
+                }
+                catch (completeErr) {
+                    jobLog.error({
+                        runId,
+                        err: completeErr instanceof Error ? completeErr.message : String(completeErr),
+                    }, "failed to record job failure");
+                }
+            }
+        }
+        finally {
+            // Remove from active set
+            activeJobs.delete(jobId);
+            // 5. Always advance the schedule pointer (even on failure)
+            try {
+                await advanceSchedulePointer(job);
+            }
+            catch (err) {
+                jobLog.error({ err: err instanceof Error ? err.message : String(err) }, "failed to advance schedule pointer");
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Core: manual trigger
+    // -----------------------------------------------------------------------
+    async function triggerJob(jobId, trigger = "manual") {
+        const job = await jobStore.getJobById(jobId);
+        if (!job) {
+            throw new Error(`Job not found: ${jobId}`);
+        }
+        if (job.status !== "active") {
+            throw new Error(`Job "${job.jobKey}" is not active (status: ${job.status})`);
+        }
+        // Overlap prevention
+        if (activeJobs.has(jobId)) {
+            throw new Error(`Job "${job.jobKey}" is already running — cannot trigger while in progress`);
+        }
+        // Also check DB for running runs (defensive — covers multi-instance)
+        const existingRuns = await db
+            .select()
+            .from(pluginJobRuns)
+            .where(and(eq(pluginJobRuns.jobId, jobId), eq(pluginJobRuns.status, "running")));
+        if (existingRuns.length > 0) {
+            throw new Error(`Job "${job.jobKey}" already has a running execution — cannot trigger while in progress`);
+        }
+        // Check worker availability
+        if (!workerManager.isRunning(job.pluginId)) {
+            throw new Error(`Worker for plugin "${job.pluginId}" is not running — cannot trigger job`);
+        }
+        // Create the run and dispatch (non-blocking)
+        const run = await jobStore.createRun({
+            jobId,
+            pluginId: job.pluginId,
+            trigger,
+        });
+        // Dispatch in background — don't block the caller
+        void dispatchManualRun(job, run.id, trigger);
+        return { runId: run.id, jobId };
+    }
+    /**
+     * Dispatch a manually triggered job run.
+     */
+    async function dispatchManualRun(job, runId, trigger) {
+        const { id: jobId, pluginId, jobKey } = job;
+        const jobLog = log.child({ jobId, pluginId, jobKey, runId, trigger });
+        activeJobs.add(jobId);
+        const startedAt = Date.now();
+        try {
+            await jobStore.markRunning(runId);
+            await workerManager.call(pluginId, "runJob", {
+                job: {
+                    jobKey,
+                    runId,
+                    trigger,
+                    scheduledAt: new Date().toISOString(),
+                },
+            }, jobTimeoutMs);
+            const durationMs = Date.now() - startedAt;
+            await jobStore.completeRun(runId, {
+                status: "succeeded",
+                durationMs,
+            });
+            jobLog.info({ durationMs }, "manual job completed successfully");
+        }
+        catch (err) {
+            const durationMs = Date.now() - startedAt;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            jobLog.error({ durationMs, err: errorMessage }, "manual job failed");
+            try {
+                await jobStore.completeRun(runId, {
+                    status: "failed",
+                    error: errorMessage,
+                    durationMs,
+                });
+            }
+            catch (completeErr) {
+                jobLog.error({
+                    err: completeErr instanceof Error ? completeErr.message : String(completeErr),
+                }, "failed to record manual job failure");
+            }
+        }
+        finally {
+            activeJobs.delete(jobId);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Schedule pointer management
+    // -----------------------------------------------------------------------
+    /**
+     * Advance the `lastRunAt` and `nextRunAt` timestamps on a job after a run.
+     */
+    async function advanceSchedulePointer(job) {
+        const now = new Date();
+        let nextRunAt = null;
+        if (job.schedule) {
+            const validationError = validateCron(job.schedule);
+            if (validationError) {
+                log.warn({ jobId: job.id, schedule: job.schedule, error: validationError }, "invalid cron schedule — cannot compute next run");
+            }
+            else {
+                const cron = parseCron(job.schedule);
+                nextRunAt = nextCronTick(cron, now);
+            }
+        }
+        await jobStore.updateRunTimestamps(job.id, now, nextRunAt);
+    }
+    /**
+     * Ensure all active jobs for a plugin have a `nextRunAt` value.
+     * Called when a plugin is registered with the scheduler.
+     */
+    async function ensureNextRunTimestamps(pluginId) {
+        const jobs = await jobStore.listJobs(pluginId, "active");
+        for (const job of jobs) {
+            // Skip jobs that already have a valid nextRunAt in the future
+            if (job.nextRunAt && job.nextRunAt.getTime() > Date.now()) {
+                continue;
+            }
+            // Skip jobs without a schedule
+            if (!job.schedule) {
+                continue;
+            }
+            const validationError = validateCron(job.schedule);
+            if (validationError) {
+                log.warn({ jobId: job.id, jobKey: job.jobKey, schedule: job.schedule, error: validationError }, "skipping job with invalid cron schedule");
+                continue;
+            }
+            const cron = parseCron(job.schedule);
+            const nextRunAt = nextCronTick(cron, new Date());
+            if (nextRunAt) {
+                await jobStore.updateRunTimestamps(job.id, job.lastRunAt ?? new Date(0), nextRunAt);
+                log.debug({ jobId: job.id, jobKey: job.jobKey, nextRunAt: nextRunAt.toISOString() }, "computed nextRunAt for job");
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Plugin registration
+    // -----------------------------------------------------------------------
+    async function registerPlugin(pluginId) {
+        log.info({ pluginId }, "registering plugin with job scheduler");
+        await ensureNextRunTimestamps(pluginId);
+    }
+    async function unregisterPlugin(pluginId) {
+        log.info({ pluginId }, "unregistering plugin from job scheduler");
+        // Cancel any in-flight run records for this plugin that are still
+        // queued or running. Active jobs in-memory will finish naturally.
+        try {
+            const runningRuns = await db
+                .select()
+                .from(pluginJobRuns)
+                .where(and(eq(pluginJobRuns.pluginId, pluginId), or(eq(pluginJobRuns.status, "running"), eq(pluginJobRuns.status, "queued"))));
+            for (const run of runningRuns) {
+                await jobStore.completeRun(run.id, {
+                    status: "cancelled",
+                    error: "Plugin unregistered",
+                    durationMs: run.startedAt
+                        ? Date.now() - run.startedAt.getTime()
+                        : null,
+                });
+            }
+        }
+        catch (err) {
+            log.error({
+                pluginId,
+                err: err instanceof Error ? err.message : String(err),
+            }, "error cancelling in-flight runs during unregister");
+        }
+        // Remove any active tracking for jobs owned by this plugin
+        const jobs = await jobStore.listJobs(pluginId);
+        for (const job of jobs) {
+            activeJobs.delete(job.id);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Lifecycle: start / stop
+    // -----------------------------------------------------------------------
+    function start() {
+        if (running) {
+            log.debug("scheduler already running");
+            return;
+        }
+        running = true;
+        tickTimer = setInterval(() => {
+            void tick();
+        }, tickIntervalMs);
+        log.info({ tickIntervalMs, maxConcurrentJobs }, "plugin job scheduler started");
+    }
+    function stop() {
+        // Always clear the timer defensively, even if `running` is already false,
+        // to prevent leaked interval timers.
+        if (tickTimer !== null) {
+            clearInterval(tickTimer);
+            tickTimer = null;
+        }
+        if (!running)
+            return;
+        running = false;
+        log.info({ activeJobCount: activeJobs.size }, "plugin job scheduler stopped");
+    }
+    // -----------------------------------------------------------------------
+    // Diagnostics
+    // -----------------------------------------------------------------------
+    function diagnostics() {
+        return {
+            running,
+            activeJobCount: activeJobs.size,
+            activeJobIds: [...activeJobs],
+            tickCount,
+            lastTickAt: lastTickAt?.toISOString() ?? null,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    return {
+        start,
+        stop,
+        registerPlugin,
+        unregisterPlugin,
+        triggerJob,
+        tick,
+        diagnostics,
+    };
+}
+//# sourceMappingURL=plugin-job-scheduler.js.map

package/dist/services/plugin-job-scheduler.js.map

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

package/dist/services/plugin-job-store.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Plugin Job Store — persistence layer for scheduled plugin jobs and their
+ * execution history.
+ *
+ * This service manages the `plugin_jobs` and `plugin_job_runs` tables. It is
+ * the server-side backing store for the `ctx.jobs` SDK surface exposed to
+ * plugin workers.
+ *
+ * ## Responsibilities
+ *
+ * 1. **Sync job declarations** — When a plugin is installed or started, the
+ *    host calls `syncJobDeclarations()` to upsert the manifest's declared jobs
+ *    into the `plugin_jobs` table. Jobs removed from the manifest are marked
+ *    `paused` (not deleted) to preserve history.
+ *
+ * 2. **Job CRUD** — List, get, pause, and resume jobs for a given plugin.
+ *
+ * 3. **Run lifecycle** — Create job run records, update their status, and
+ *    record results (duration, errors, logs).
+ *
+ * 4. **Next-run calculation** — After a run completes the host should call
+ *    `updateNextRunAt()` with the next cron tick so the scheduler knows when
+ *    to fire next.
+ *
+ * The capability check (`jobs.schedule`) is enforced upstream by the host
+ * client factory and manifest validator — this store trusts that the caller
+ * has already been authorised.
+ *
+ * @see PLUGIN_SPEC.md §17 — Scheduled Jobs
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_jobs` / `plugin_job_runs` tables
+ */
+import type { Db } from "@fidelios/db";
+import { pluginJobs, pluginJobRuns } from "@fidelios/db";
+import type { PluginJobDeclaration, PluginJobRunStatus, PluginJobRunTrigger, PluginJobRecord } from "@fidelios/shared";
+/**
+ * The statuses used for job *definitions* in the `plugin_jobs` table.
+ * Aliased from `PluginJobRecord` to keep the store API aligned with
+ * the domain type (`"active" | "paused" | "failed"`).
+ */
+type JobDefinitionStatus = PluginJobRecord["status"];
+/**
+ * Input for creating a job run record.
+ */
+export interface CreateJobRunInput {
+    /** FK to the plugin_jobs row. */
+    jobId: string;
+    /** FK to the plugins row. */
+    pluginId: string;
+    /** What triggered this run. */
+    trigger: PluginJobRunTrigger;
+}
+/**
+ * Input for completing (or failing) a job run.
+ */
+export interface CompleteJobRunInput {
+    /** Final run status. */
+    status: PluginJobRunStatus;
+    /** Error message if the run failed. */
+    error?: string | null;
+    /** Run duration in milliseconds. */
+    durationMs?: number | null;
+}
+/**
+ * Create a PluginJobStore backed by the given Drizzle database instance.
+ *
+ * @example
+ * ```ts
+ * const jobStore = pluginJobStore(db);
+ *
+ * // On plugin install/start — sync declared jobs into the DB
+ * await jobStore.syncJobDeclarations(pluginId, manifest.jobs ?? []);
+ *
+ * // Before dispatching a runJob RPC — create a run record
+ * const run = await jobStore.createRun({ jobId, pluginId, trigger: "schedule" });
+ *
+ * // After the RPC completes — record the result
+ * await jobStore.completeRun(run.id, {
+ *   status: "succeeded",
+ *   durationMs: Date.now() - startedAt,
+ * });
+ * ```
+ */
+export declare function pluginJobStore(db: Db): {
+    /**
+     * Sync declared jobs from a plugin manifest into the `plugin_jobs` table.
+     *
+     * This is called at plugin install and on each worker startup so the DB
+     * always reflects the manifest's declared jobs:
+     *
+     * - **New jobs** are inserted with status `active`.
+     * - **Existing jobs** have their `schedule` updated if it changed.
+     * - **Removed jobs** (present in DB but absent from the manifest) are
+     *   set to `paused` so their history is preserved.
+     *
+     * The unique constraint `(pluginId, jobKey)` is used for conflict
+     * resolution.
+     *
+     * @param pluginId - UUID of the owning plugin
+     * @param declarations - Job declarations from the plugin manifest
+     */
+    syncJobDeclarations(pluginId: string, declarations: PluginJobDeclaration[]): Promise<void>;
+    /**
+     * List all jobs for a plugin, optionally filtered by status.
+     *
+     * @param pluginId - UUID of the owning plugin
+     * @param status - Optional status filter
+     */
+    listJobs(pluginId: string, status?: JobDefinitionStatus): Promise<(typeof pluginJobs.$inferSelect)[]>;
+    /**
+     * Get a single job by its composite key `(pluginId, jobKey)`.
+     *
+     * @param pluginId - UUID of the owning plugin
+     * @param jobKey - Stable job identifier from the manifest
+     * @returns The job row, or `null` if not found
+     */
+    getJobByKey(pluginId: string, jobKey: string): Promise<(typeof pluginJobs.$inferSelect) | null>;
+    /**
+     * Get a single job by its primary key (UUID).
+     *
+     * @param jobId - UUID of the job row
+     * @returns The job row, or `null` if not found
+     */
+    getJobById(jobId: string): Promise<(typeof pluginJobs.$inferSelect) | null>;
+    /**
+     * Fetch a single job by ID, scoped to a specific plugin.
+     *
+     * Returns `null` if the job does not exist or does not belong to the
+     * given plugin — callers should treat both cases as "not found".
+     */
+    getJobByIdForPlugin(pluginId: string, jobId: string): Promise<(typeof pluginJobs.$inferSelect) | null>;
+    /**
+     * Update a job's status.
+     *
+     * @param jobId - UUID of the job row
+     * @param status - New status
+     */
+    updateJobStatus(jobId: string, status: JobDefinitionStatus): Promise<void>;
+    /**
+     * Update the `lastRunAt` and `nextRunAt` timestamps on a job.
+     *
+     * Called by the scheduler after a run completes to advance the
+     * scheduling pointer.
+     *
+     * @param jobId - UUID of the job row
+     * @param lastRunAt - When the last run started
+     * @param nextRunAt - When the next run should fire
+     */
+    updateRunTimestamps(jobId: string, lastRunAt: Date, nextRunAt: Date | null): Promise<void>;
+    /**
+     * Delete all jobs (and cascaded runs) owned by a plugin.
+     *
+     * Called during plugin uninstall when `removeData = true`.
+     *
+     * @param pluginId - UUID of the owning plugin
+     */
+    deleteAllJobs(pluginId: string): Promise<void>;
+    /**
+     * Create a new job run record with status `queued`.
+     *
+     * The caller should create the run record *before* dispatching the
+     * `runJob` RPC to the worker, then update it to `running` once the
+     * worker begins execution.
+     *
+     * @param input - Job run input (jobId, pluginId, trigger)
+     * @returns The newly created run row
+     */
+    createRun(input: CreateJobRunInput): Promise<typeof pluginJobRuns.$inferSelect>;
+    /**
+     * Mark a run as `running` and set its `startedAt` timestamp.
+     *
+     * @param runId - UUID of the run row
+     */
+    markRunning(runId: string): Promise<void>;
+    /**
+     * Complete a run — set its final status, error, duration, and
+     * `finishedAt` timestamp.
+     *
+     * @param runId - UUID of the run row
+     * @param input - Completion details
+     */
+    completeRun(runId: string, input: CompleteJobRunInput): Promise<void>;
+    /**
+     * Get a run by its primary key.
+     *
+     * @param runId - UUID of the run row
+     * @returns The run row, or `null` if not found
+     */
+    getRunById(runId: string): Promise<(typeof pluginJobRuns.$inferSelect) | null>;
+    /**
+     * List runs for a specific job, ordered by creation time descending.
+     *
+     * @param jobId - UUID of the job
+     * @param limit - Maximum number of rows to return (default: 50)
+     */
+    listRunsByJob(jobId: string, limit?: number): Promise<(typeof pluginJobRuns.$inferSelect)[]>;
+    /**
+     * List runs for a plugin, optionally filtered by status.
+     *
+     * @param pluginId - UUID of the owning plugin
+     * @param status - Optional status filter
+     * @param limit - Maximum number of rows to return (default: 50)
+     */
+    listRunsByPlugin(pluginId: string, status?: PluginJobRunStatus, limit?: number): Promise<(typeof pluginJobRuns.$inferSelect)[]>;
+};
+/** Type alias for the return value of `pluginJobStore()`. */
+export type PluginJobStore = ReturnType<typeof pluginJobStore>;
+export {};
+//# sourceMappingURL=plugin-job-store.d.ts.map