@nexpress/core 0.1.0

package/dist/index-B6-_vr_m.d.ts

@@ -0,0 +1,590 @@
+import { I as NpJobType, d as NpCollectionConfig, e as NpAuthUser, F as NpPrincipal } from './types-TlsbXS0T.js';
+import { ConstructorOptions, PgBoss } from 'pg-boss';
+import { N as NpLogLevel } from './logger-DqGaOU_j.js';
+
+type NpJobHandler = (data: unknown) => Promise<void>;
+declare function registerJobHandler(type: NpJobType, handler: NpJobHandler): void;
+declare function getJobHandler(type: NpJobType): NpJobHandler | undefined;
+declare function getAllJobHandlers(): ReadonlyMap<NpJobType, NpJobHandler>;
+
+/**
+ * Phase 13 — admin-side job introspection. pg-boss tracks jobs
+ * across two tables (`pgboss.job` for active/scheduled,
+ * `pgboss.archive` for completed/failed); the framework
+ * surfaces a unified shape so the admin UI doesn't have to
+ * know the storage split.
+ */
+type NpJobState = "created" | "active" | "completed" | "failed" | "retry" | "cancelled" | "expired";
+interface NpJobSummary {
+    id: string;
+    /** pg-boss queue name (after `:` → `.` translation). */
+    name: string;
+    state: NpJobState;
+    data: unknown;
+    /** Number of retries pg-boss has attempted so far. */
+    retryCount?: number;
+    /** Last failure message, if any. */
+    output?: string | null;
+    createdOn: string;
+    startedOn?: string | null;
+    completedOn?: string | null;
+    /**
+     * Phase 20.4 — which pg-boss table the row was read from.
+     * `"live"` = pgboss.job (still pending / active / retry),
+     * `"archive"` = pgboss.archive (rolled out by pg-boss after
+     * `keepUntil`). The admin Jobs view uses this to split the
+     * Failed tab into "live failures" (still actionable via
+     * `/api/admin/jobs/{id}/retry`) vs "archived" (kept for
+     * forensics; retry would re-create the row in `job`).
+     */
+    source?: "live" | "archive";
+}
+interface NpJobListOptions {
+    /** Filter to one queue name (e.g. `"media.processImage"`). */
+    name?: string;
+    /** Filter to one state. Defaults to all. */
+    state?: NpJobState;
+    /** Page size. Default 50, capped at 200. */
+    limit?: number;
+    /** Skip count for pagination. */
+    offset?: number;
+    /**
+     * Phase 13.2 — only include jobs whose `created_on` is at or
+     * after this timestamp. Common operational query: "jobs from
+     * the last 24 hours" without paging through history.
+     */
+    since?: Date;
+    /**
+     * Phase 20.4 — partition the result by pg-boss table:
+     *   - `"live"` — pending / active / retry rows still in
+     *     `pgboss.job`. Retryable.
+     *   - `"archive"` — rolled rows in `pgboss.archive`. Read-only
+     *     (pg-boss won't pick them up; retry routes refuse to
+     *     touch archive rows).
+     * Default (undefined) keeps the historical UNION behavior.
+     */
+    source?: "live" | "archive";
+}
+interface NpJobListResult {
+    jobs: NpJobSummary[];
+    total: number;
+}
+/**
+ * Phase 23.5 — counts per terminal-and-transient state across the
+ * union of `pgboss.job` and `pgboss.archive`. Drives the stuck-job
+ * widget in `/admin/jobs` and is the building block plugin authors
+ * use to roll their own monitoring without taking a hard dep on
+ * pg-boss schema knowledge.
+ *
+ * Every state key is always present (defaulting to 0) so the
+ * caller can index without optional chaining and the UI can render
+ * a stable row order.
+ */
+interface NpJobStateCounts {
+    created: number;
+    active: number;
+    completed: number;
+    failed: number;
+    retry: number;
+    cancelled: number;
+    expired: number;
+}
+interface NpJobCountOptions {
+    /**
+     * Time-bounded query: include only jobs whose `created_on` is at
+     * or after this timestamp. Useful for "failures in the last 24
+     * hours" without paging through history.
+     */
+    since?: Date;
+}
+/**
+ * Phase 13.2 — registered cron schedule (one row per
+ * `boss.schedule()` call). Surfaces in the admin so
+ * operators can confirm `system:revisionPrune` and friends
+ * are actually registered, not just declared in code.
+ */
+interface NpScheduleSummary {
+    /** pg-boss queue name (after `:` → `.` translation). */
+    name: string;
+    /**
+     * Issue #217 — the second half of `pgboss.schedule`'s primary
+     * key. Empty string for single-cadence schedules; `"daily"` /
+     * `"weekly"` (etc.) for jobs that need multiple cadences under
+     * one queue name. The admin UI uses `(name, key)` as a stable
+     * React key so duplicate-name rows render cleanly.
+     */
+    key: string;
+    /** Cron expression as registered. */
+    cron: string;
+    /** Timezone the cron runs in (defaults to UTC in pg-boss). */
+    timezone: string | null;
+    /** Default payload used when the cron fires. */
+    data: unknown;
+    createdOn: string;
+    updatedOn?: string | null;
+}
+interface NpJobQueue {
+    enqueue(type: NpJobType, data: unknown): Promise<string>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Phase 13 — admin introspection. Optional on the interface
+     * so test stubs / mock queues don't have to implement them;
+     * the admin endpoint returns 501 when the active queue
+     * doesn't support introspection.
+     */
+    listJobs?(options: NpJobListOptions): Promise<NpJobListResult>;
+    /** Re-enqueue a failed/cancelled job's payload as a new job. Returns the new job id. */
+    retryJob?(id: string): Promise<string>;
+    /** Cancel a pending job (no-op for already-running / completed jobs). */
+    cancelJob?(id: string): Promise<void>;
+    /**
+     * Phase 13.2 — list every cron schedule registered with the
+     * queue. Surfaces in the admin so operators can confirm
+     * recurring jobs are actually registered, not just declared
+     * in code.
+     */
+    listSchedules?(): Promise<NpScheduleSummary[]>;
+    /**
+     * Phase 20.2 — stop the worker from claiming new jobs without
+     * tearing down the queue. In-flight jobs run to completion;
+     * the producer keeps enqueueing. Optional on the interface
+     * because non-pg-boss test stubs don't implement it.
+     */
+    pauseProcessing?(): Promise<void>;
+    /** Phase 20.2 — undo `pauseProcessing()`. Idempotent. */
+    resumeProcessing?(): Promise<void>;
+    /** Phase 20.2 — `true` when this adapter is currently paused. */
+    isProcessingPaused?(): boolean;
+    /**
+     * Phase 22.4 — readiness probe. Issues a cheap round-trip against
+     * the queue backing store and returns `true` when the connection
+     * is alive AND the queue's schema is installed. Adapters that
+     * can't tell return `true` (a missing answer is not a failure
+     * signal). Errors are caught and reported as `false` — the probe
+     * caller never sees an exception.
+     */
+    isHealthy?(): Promise<boolean>;
+    /**
+     * Phase 23.5 — return job counts grouped by state across both
+     * pg-boss tables. Optional on the interface so test stubs that
+     * don't model state need not implement it; the admin endpoint
+     * omits the stuck-job widget when missing.
+     */
+    countByState?(options?: NpJobCountOptions): Promise<NpJobStateCounts>;
+    /**
+     * Phase 4.2 — per-plugin schedule observability. Returns one row per
+     * `(pluginId, taskId)` aggregated over the plugin's history in
+     * `pgboss.job` + `pgboss.archive`: last completion, last failure, and
+     * counts split by state over the last `windowDays` (default 7). The
+     * registry-side cron / description is overlaid on top by the caller.
+     *
+     * Optional so test stubs that don't model job history can omit it; the
+     * admin surface degrades to "registered schedules only" without it.
+     */
+    getPluginScheduleStats?(pluginId: string, options?: {
+        windowDays?: number;
+    }): Promise<NpPluginScheduleStats[]>;
+    /**
+     * Issue #461 — bring the queue's `pgboss.schedule` rows in sync with
+     * what `getRegisteredPluginSchedules()` reports today. Bootstrap
+     * registers schedules once at worker startup; without this method,
+     * `reloadPlugins()` could only update the in-memory registry, leaving
+     * pg-boss firing the *old* set of crons until the worker restarted.
+     *
+     * Behavior:
+     *   - schedule entry in registry but missing from pg-boss → added
+     *   - schedule entry in pg-boss but missing from registry → removed
+     *   - same name + different cron expression → re-added (unschedule
+     *     then schedule, since pg-boss has no in-place cron update)
+     *
+     * `boss.work()` registration is NOT touched: in production deploys
+     * the worker lives in a separate process from the admin web server,
+     * so the web process can't install / drop work loops on its boss
+     * instance for the worker process to pick up. Operators see their
+     * cron rows updated immediately; jobs that fire for newly-added
+     * schedules will still need a worker restart to be processed.
+     * Documented in the admin reload toast.
+     *
+     * Optional on the interface so test stubs / non-pg-boss adapters
+     * skip cleanly.
+     */
+    reconcilePluginSchedules?(): Promise<NpReconcileSchedulesResult>;
+}
+interface NpReconcileSchedulesResult {
+    /** New schedule rows written to `pgboss.schedule`. */
+    added: number;
+    /** Existing rows whose cron expression changed (unschedule → reschedule). */
+    updated: number;
+    /** Stale rows removed (plugin was uninstalled / disabled / renamed). */
+    removed: number;
+    /**
+     * `true` when this process holds the worker `boss.work()` registrations
+     * for the affected schedules. When false, operators should restart the
+     * worker to pick up newly-added schedules. Adapters that can't tell
+     * (in-memory test queue, future adapters) return `null`.
+     */
+    workerOwnsRegistrations: boolean | null;
+}
+interface NpPluginScheduleStats {
+    taskId: string;
+    /** Most recent run, regardless of state. ISO timestamp or null. */
+    lastRunAt: string | null;
+    /** Most recent successful run. ISO timestamp or null. */
+    lastSuccessAt: string | null;
+    /** Most recent failed run. ISO timestamp or null. */
+    lastFailureAt: string | null;
+    /** Count of successful runs inside the window. */
+    completedCount: number;
+    /** Count of failed runs inside the window. */
+    failedCount: number;
+    /** The window the counts cover, in days. Echoed for UI labels. */
+    windowDays: number;
+}
+declare function setJobQueue(queue: NpJobQueue | null): void;
+declare function getJobQueue(): NpJobQueue;
+declare function getOptionalJobQueue(): NpJobQueue | null;
+/**
+ * Enqueues a job if the queue is wired up; otherwise no-ops so callers
+ * (content pipeline, media processing) can run without pg-boss during MVP
+ * blog-only workloads. Return value is an empty string in the no-op path.
+ */
+declare function enqueueJob(type: NpJobType, data: unknown): Promise<string>;
+
+declare function startWorker(connectionString: string, options?: {
+    schema?: string;
+    heartbeat?: boolean | {
+        meta?: Record<string, unknown>;
+    };
+    /**
+     * When true (default), startWorker installs SIGINT / SIGTERM
+     * listeners that call `stopWorker()` and `process.exit(0)`.
+     * Set false in environments that manage their own shutdown
+     * sequencing (custom supervisors, embedded test harnesses).
+     */
+    installSignalHandlers?: boolean;
+}): Promise<void>;
+/**
+ * Enqueue-only setup for the web/API process. Wires pg-boss as the job queue
+ * singleton without attaching any `boss.work()` loops — those belong in the
+ * dedicated worker process. Calling `enqueueJob` after this will actually
+ * send jobs instead of no-op'ing.
+ */
+declare function startProducer(connectionString: string, options?: {
+    schema?: string;
+}): Promise<void>;
+declare function stopWorker(): Promise<void>;
+declare function stopProducer(): Promise<void>;
+
+declare class PgBossAdapter implements NpJobQueue {
+    private readonly boss;
+    /**
+     * Phase 20.2 — every queue we've called `boss.work()` on, plus
+     * the function that re-registers it. We need both because
+     * `pauseProcessing()` calls `boss.offWork(name)` (drops the
+     * worker) and `resumeProcessing()` has to re-call the original
+     * `boss.work(...)` to bring it back. Order is preserved so
+     * resume registers in the same order as start did.
+     */
+    private readonly workRegistrations;
+    private paused;
+    /**
+     * Flips `true` after `start()` runs (full worker mode). `startProducer()`
+     * doesn't set it. Used by `reconcilePluginSchedules()` to tell admins
+     * whether this process owns the `boss.work()` loops for plugin schedules
+     * — the same boss instance can act as producer-only in the web server
+     * and full worker in the worker process.
+     */
+    private workerStarted;
+    constructor(connectionString: string, options?: ConstructorOptions);
+    enqueue(type: NpJobType, data: unknown): Promise<string>;
+    /**
+     * Opens the pg-boss connection and runs its migrations. Safe to call from a
+     * non-worker process (e.g. the Next.js server) so it can enqueue jobs.
+     */
+    startProducer(): Promise<void>;
+    /**
+     * Full start: opens the connection (idempotent with startProducer) and
+     * registers `boss.work()` loops for every handler in the registry. Call
+     * this from the dedicated worker process.
+     */
+    start(): Promise<void>;
+    /**
+     * Phase 20.2 — drop every registered worker so the boss stops
+     * claiming new jobs. The pg-boss connection stays open; the
+     * producer can keep enqueueing while paused. In-flight jobs
+     * picked up before pause finish normally because pg-boss only
+     * cancels the polling loop, not the fetch already in flight.
+     */
+    pauseProcessing(): Promise<void>;
+    /** Phase 20.2 — re-run every captured `boss.work()` registration. Idempotent. */
+    resumeProcessing(): Promise<void>;
+    isProcessingPaused(): boolean;
+    /**
+     * Phase 22.4 — readiness probe round-trip. `boss.isInstalled()`
+     * issues a single SELECT against `pgboss.version`, so a true
+     * answer proves both that the DB connection is alive AND that
+     * pg-boss's schema migrations have applied. Any throw — pool
+     * dead, schema missing, permissions revoked — is caught and
+     * reported as `false`; the readiness probe never sees an
+     * exception bubble out of the queue check.
+     */
+    isHealthy(): Promise<boolean>;
+    stop(): Promise<void>;
+    scheduleRecurring(): Promise<void>;
+    getBoss(): PgBoss;
+    /**
+     * Phase 13 — admin job introspection. Joins pgboss.job
+     * (pending / active / retry) and pgboss.archive (completed
+     * / failed / expired) into one unified list.
+     *
+     * Phase 13.2 — `since` filter for time-bounded queries
+     * ("last 24 hours") and accurate `total` via a parallel
+     * COUNT(*) so the admin pagination shows the right count.
+     * The COUNT runs against the same UNION; the per-page
+     * SELECT still gets the row data.
+     */
+    listJobs(options: NpJobListOptions): Promise<NpJobListResult>;
+    /**
+     * Phase 13.2 — list every cron schedule registered in the
+     * queue. Reads from `pgboss.schedule`, which is the table
+     * pg-boss writes to on each `boss.schedule()` call. Sorted
+     * by name for stable display.
+     */
+    listSchedules(): Promise<NpScheduleSummary[]>;
+    /**
+     * Phase 4.2 — pulls per-(pluginId, taskId) execution stats from the
+     * union of `pgboss.job` (in-flight + recently-completed) and
+     * `pgboss.archive` (rolled-over history). One row per taskId so the
+     * caller can index without a second pass.
+     *
+     * The window default is 7 days because longer windows force the
+     * archive table into the hot path and admins typically want recent
+     * health, not lifetime totals. Increase via `windowDays` if surfacing
+     * a "30-day reliability" widget.
+     */
+    getPluginScheduleStats(pluginId: string, options?: {
+        windowDays?: number;
+    }): Promise<NpPluginScheduleStats[]>;
+    /**
+     * Issue #461 — diff the in-memory plugin schedule registry against the
+     * `pgboss.schedule` rows whose name starts with `plugin.scheduledTask.*`
+     * and bring pg-boss in line. Without this, `reloadPlugins()` only
+     * rebuilt the in-process registry and pg-boss kept firing the old set
+     * of crons until the worker process restarted — the admin "Reload all"
+     * toast was promising behavior the system didn't deliver.
+     *
+     * Worker `boss.work()` registrations stay untouched. In production the
+     * worker is a separate process with its own boss instance; the web
+     * process can't add or drop work loops there. We surface that via
+     * `workerOwnsRegistrations` so the admin UI can warn the operator.
+     */
+    reconcilePluginSchedules(): Promise<NpReconcileSchedulesResult>;
+    /**
+     * Phase 23.5 — `GROUP BY state` across the union of pgboss.job
+     * (live) and pgboss.archive (rolled). Returns a fully-populated
+     * record so callers can index without optional chaining.
+     *
+     * Uses `created_on` for the optional `since` filter. Both tables
+     * carry the same column, so the union pre-filter is a single
+     * predicate.
+     */
+    countByState(options?: NpJobCountOptions): Promise<NpJobStateCounts>;
+    retryJob(id: string): Promise<string>;
+    cancelJob(id: string): Promise<void>;
+}
+
+interface ContentJobData {
+    collection: string;
+    documentId: string;
+    operation: "create" | "update";
+    userId: string;
+}
+interface ContentDeleteJobData {
+    collection: string;
+    documentId: string;
+    userId: string;
+}
+interface ResolvedHookContext {
+    collectionConfig: NpCollectionConfig;
+    data: Record<string, unknown>;
+    /**
+     * Resolved staff session, or `null` when the originating actor
+     * was a member (Phase 9.7o widened the hook surface so member
+     * writes also fire `afterCreate` / `afterUpdate`).
+     */
+    user: NpAuthUser | null;
+    /**
+     * Polymorphic actor reference. Resolvers should derive this
+     * from whatever actor metadata they recorded with the job —
+     * e.g. by checking whether the saved `userId` is null
+     * (member-authored) and looking up the member id separately.
+     */
+    principal: NpPrincipal;
+    originalDoc?: Record<string, unknown> | null;
+}
+interface ResolvedDeleteHookContext {
+    collectionConfig: NpCollectionConfig;
+    data: Record<string, unknown>;
+    user: NpAuthUser | null;
+    principal: NpPrincipal;
+}
+interface BuiltinJobContext {
+    resolveContentAfterSaveContext?: (data: ContentJobData) => Promise<ResolvedHookContext | null> | ResolvedHookContext | null;
+    resolveContentAfterDeleteContext?: (data: ContentDeleteJobData) => Promise<ResolvedDeleteHookContext | null> | ResolvedDeleteHookContext | null;
+    processImage?: (data: unknown) => Promise<void> | void;
+    cleanupMedia?: (data: unknown) => Promise<void> | void;
+    runScheduledPluginTask?: (data: unknown) => Promise<void> | void;
+    pruneRevisions?: () => Promise<void> | void;
+    cleanupSessions?: () => Promise<void> | void;
+    sendPasswordReset?: (data: unknown) => Promise<void> | void;
+    sendMemberVerifyEmail?: (data: unknown) => Promise<void> | void;
+    sendMemberPasswordReset?: (data: unknown) => Promise<void> | void;
+}
+declare function configureBuiltinJobContext(context: Partial<BuiltinJobContext>): void;
+declare function registerBuiltinHandlers(): void;
+
+/**
+ * Phase 19 — worker liveness signal.
+ *
+ * The worker process upserts its row every
+ * `WORKER_HEARTBEAT_INTERVAL_MS` so admins can tell whether the
+ * pg-boss queue actually has a draining process attached.
+ * Without this the only signal was "Pending stays high while
+ * Completed doesn't grow," which a stuck DB or a stopped
+ * worker look identical from outside.
+ *
+ * Stale rows (no heartbeat in `WORKER_STALE_THRESHOLD_MS`) are
+ * reported `unhealthy`; the row stays in place until an
+ * operator GCs it or a worker with the same id rejoins. The
+ * id is `hostname:pid` so a restarted process on the same host
+ * naturally reclaims its row instead of stacking duplicates.
+ */
+/**
+ * How often a running worker pings its row. Tightening lets
+ * `lastSeenAt` track wall-clock more closely; loosening cuts
+ * write traffic on idle workers. `NP_WORKER_HEARTBEAT_SECONDS`.
+ */
+declare const WORKER_HEARTBEAT_INTERVAL_MS: number;
+/**
+ * After how long with no heartbeat a worker is treated as
+ * unhealthy in the admin UI / health check. Default 90s is
+ * `3 × HEARTBEAT_INTERVAL` so a single missed beat doesn't trip
+ * the alarm. `NP_WORKER_STALE_THRESHOLD_SECONDS`.
+ */
+declare const WORKER_STALE_THRESHOLD_MS: number;
+interface NpWorkerHeartbeat {
+    id: string;
+    status: string;
+    startedAt: Date;
+    lastSeenAt: Date;
+    meta: Record<string, unknown>;
+}
+interface NpWorkerHealthSummary {
+    workers: Array<NpWorkerHeartbeat & {
+        alive: boolean;
+        lastSeenAgoMs: number;
+    }>;
+    aliveCount: number;
+    totalCount: number;
+    /** ISO timestamp of the most recent heartbeat across all workers. */
+    newestHeartbeat: string | null;
+}
+/**
+ * Stamp a single heartbeat row. Used by `startHeartbeatLoop`
+ * and exposed for tests so they can inject fake worker rows
+ * without spinning up a real interval.
+ */
+declare function recordHeartbeat(workerId: string, meta?: Record<string, unknown>): Promise<void>;
+/**
+ * Mark the row as `stopped` so the admin sees a graceful
+ * shutdown rather than the row drifting into `unhealthy`.
+ */
+declare function markWorkerStopped(workerId: string): Promise<void>;
+/**
+ * Read every worker row, decorate with `alive` + `lastSeenAgoMs`
+ * relative to `now`. Sorted with the most recent heartbeat
+ * first so the admin's first row is the freshest worker.
+ */
+declare function listWorkerHealth(now?: Date): Promise<NpWorkerHealthSummary>;
+/**
+ * Manual GC hook — purge worker rows whose `last_seen_at` is
+ * older than `olderThan`. Operators can call this from a
+ * cron / admin action when the table accumulates ghosts.
+ */
+declare function purgeStaleWorkers(olderThan?: Date): Promise<number>;
+/** Return only the rows currently considered alive. Cheap probe for boot health. */
+declare function countAliveWorkers(now?: Date): Promise<number>;
+
+interface NpJobsPauseState {
+    paused: boolean;
+    /** ISO timestamp captured the last time the flag flipped. */
+    changedAt: string;
+    /** User id (staff) who flipped the flag, when known. */
+    changedByUserId: string | null;
+    /** Optional note an operator can leave for the next person. */
+    reason: string | null;
+}
+declare function getJobsPauseState(): Promise<NpJobsPauseState>;
+interface SetJobsPauseStateInput {
+    paused: boolean;
+    changedByUserId?: string | null;
+    reason?: string | null;
+}
+declare function setJobsPauseState(input: SetJobsPauseStateInput): Promise<NpJobsPauseState>;
+declare const PAUSE_SYNC_INTERVAL_MS = 30000;
+
+declare function runInJobContext<T>(jobId: string, fn: () => Promise<T> | T): Promise<T> | T;
+declare function getCurrentJobId(): string | null;
+/**
+ * Record one log entry for the currently-running job. Async because
+ * it writes to Postgres; callers can `void` the promise if they
+ * don't need to wait. No-ops outside a job context (returns
+ * immediately without touching the DB).
+ *
+ * Errors writing to the log table are swallowed via the framework
+ * logger at `warn` — a logging failure must never cascade into a
+ * job failure or shutdown loop.
+ */
+declare function recordJobLog(level: NpLogLevel, message: string, context?: Record<string, unknown>): Promise<void>;
+interface NpJobLogEntry {
+    id: string;
+    jobId: string;
+    level: NpLogLevel;
+    message: string;
+    context: Record<string, unknown> | null;
+    createdAt: Date;
+}
+interface ListJobLogsOptions {
+    /** Cap on rows returned. Default 200, max 1000 to keep the admin UI snappy. */
+    limit?: number;
+    /** Skip this many rows for pagination. */
+    offset?: number;
+}
+/**
+ * Fetch log entries for one job in chronological order. Paged so
+ * a runaway handler doesn't blow up the admin UI.
+ */
+declare function listJobLogs(jobId: string, options?: ListJobLogsOptions): Promise<NpJobLogEntry[]>;
+/**
+ * How long per-job log rows survive before the cleanup handler
+ * deletes them. Compliance regimes (GDPR, SOX) frequently dictate
+ * a specific window — override via `NP_JOB_LOG_RETENTION_DAYS`.
+ */
+declare const DEFAULT_JOB_LOG_RETENTION_MS: number;
+/**
+ * Delete log rows older than the cutoff. Safe to call from a
+ * scheduled handler — does not touch logs for active or recent
+ * jobs unless they pre-date the cutoff.
+ *
+ * Returns the row count deleted so the cron handler can log a
+ * useful retention summary.
+ */
+declare function pruneJobLogsOlderThan(cutoff: Date): Promise<number>;
+/**
+ * Count entries for a job — drives the admin badge "37 log lines"
+ * without paying for the page payload until the operator expands.
+ */
+declare function countJobLogs(jobId: string, sinceCreatedAt?: Date): Promise<number>;
+
+export { listJobLogs as A, listWorkerHealth as B, markWorkerStopped as C, DEFAULT_JOB_LOG_RETENTION_MS as D, pruneJobLogsOlderThan as E, purgeStaleWorkers as F, recordHeartbeat as G, recordJobLog as H, registerBuiltinHandlers as I, registerJobHandler as J, runInJobContext as K, type ListJobLogsOptions as L, setJobQueue as M, type NpJobCountOptions as N, setJobsPauseState as O, PAUSE_SYNC_INTERVAL_MS as P, startProducer as Q, startWorker as R, type SetJobsPauseStateInput as S, stopProducer as T, stopWorker as U, WORKER_HEARTBEAT_INTERVAL_MS as W, type NpJobHandler as a, type NpJobListOptions as b, type NpJobListResult as c, type NpJobLogEntry as d, type NpJobQueue as e, type NpJobState as f, type NpJobStateCounts as g, type NpJobSummary as h, type NpJobsPauseState as i, type NpPluginScheduleStats as j, type NpReconcileSchedulesResult as k, type NpScheduleSummary as l, type NpWorkerHealthSummary as m, type NpWorkerHeartbeat as n, PgBossAdapter as o, WORKER_STALE_THRESHOLD_MS as p, configureBuiltinJobContext as q, countAliveWorkers as r, countJobLogs as s, enqueueJob as t, getAllJobHandlers as u, getCurrentJobId as v, getJobHandler as w, getJobQueue as x, getJobsPauseState as y, getOptionalJobQueue as z };