@rebasepro/server 0.23.0 → 0.24.1-canary.g19596ef

package/dist/cron/cron-loader.d.ts

@@ -1,5 +1,19 @@
 import { type CronJobDefinition, type CronResourceOptions } from "@rebasepro/types";
 import { type ModuleImporter } from "../utils/dynamic-import.js";
+import type { LoadDirectoryOptions } from "../functions/function-loader.js";
+/**
+ * Cron jobs as values: the job id, to its definition.
+ *
+ * `crons: { "nightly-report": nightlyReport }` schedules `nightlyReport` as the
+ * job `nightly-report` — the same thing a file named `crons/nightly-report.ts`
+ * does. {@link loadCrons} returns exactly this shape, so
+ * `crons: await loadCrons(dir)` and `cronsDir: dir` schedule the same jobs.
+ *
+ * A value is what the author wrote — `defineCron({...})` — with no defaults
+ * filled in. The scheduler fills them in when it registers the job.
+ */
+export type CronsRecord = Record<string, CronJobDefinition>;
+/** A job as the scheduler registers it: its id, and its definition with defaults filled in. */
 export interface LoadedCronJob {
     /** Job ID derived from filename (e.g. "cleanup-sessions"). */
     id: string;
@@ -13,34 +27,79 @@ export interface LoadedCronJobs {
     problems: string[];
 }
 /**
- * Auto-discover cron job files from a directory.
+ * Load the cron jobs in a directory, as values.
+ *
+ * Each file default-exports a `CronJobDefinition` — `defineCron({...})`. The
+ * filename without its extension is the record key, which is the job id:
+ * `crons/cleanup-sessions.ts` → `{ "cleanup-sessions": definition }`.
+ *
+ * Loading declares nothing: the definitions come back exactly as written, and
+ * whoever uses them decides what they are for — a backend schedules them, the
+ * build's derive step records them in the resource graph ({@link declareCrons}).
+ *
+ * Never throws for a bad file: it is skipped, logged, and passed to
+ * `options.onSkip`.
+ *
+ * @example
+ * ```ts
+ * const crons = await loadCrons(path.resolve("crons"));
+ * const backend = await createRebaseBackend({ database, crons, provision: true });
+ * ```
+ */
+export declare function loadCrons(directory: string, options?: LoadDirectoryOptions): Promise<CronsRecord>;
+/**
+ * Record each cron in the project's resource graph — what `rebase resources`
+ * lists and a host reads to know a schedule exists, without running it.
  *
- * Each file should default-export a `CronJobDefinition`.
- * The filename (without extension) becomes the job ID:
- *   `crons/cleanup-sessions.ts` → id = "cleanup-sessions"
+ * Keyed by the same id the scheduler, the routes and the Studio use, and built
+ * from the definitions as written: a default the scheduler fills in
+ * (`enabled: true`, `timeoutSeconds: 300`) is this process's, not something the
+ * author declared.
+ */
+export declare function declareCrons(crons: CronsRecord): void;
+/**
+ * The jobs a scheduler registers, from cron values: the definitions with this
+ * process's defaults filled in.
+ *
+ * Spread first, then normalise. Rebuilding the object field by field dropped
+ * `catchUpWindowSeconds` once — and since this is the path every job takes to
+ * the scheduler, catch-up never ran for any job authored the documented way. A
+ * field added to `CronJobDefinition` tomorrow would be dropped the same way.
  *
- * Follows the same discovery pattern as `loadFunctionsFromDirectory` — see
- * {@link loadCronJobsWithDiagnostics} for what happens to the files it cannot
- * load.
+ * @throws when a value has no `schedule` or no `handler`. A file like that is
+ * skipped by the loader with a reason; a value handed over in code is refused,
+ * because the caller is right there to fix it.
+ */
+export declare function cronJobsFrom(crons: CronsRecord): LoadedCronJob[];
+/**
+ * @deprecated Use `loadCrons` instead, which returns the jobs as a record keyed
+ * by id. Will be removed in a future release.
  */
 export declare function loadCronJobsFromDirectory(directory: string, importModule?: ModuleImporter): Promise<LoadedCronJob[]>;
 /**
- * {@link loadCronJobsFromDirectory}, plus the list of files that were skipped.
+ * @deprecated Use `loadCrons` instead, with `onSkip` to collect the files it
+ * skipped — and `declareCrons` where the jobs belong in the resource graph,
+ * which this used to do as a side effect of loading. Will be removed in a
+ * future release.
+ */
+export declare function loadCronJobsWithDiagnostics(directory: string, importModule?: ModuleImporter): Promise<LoadedCronJobs>;
+/**
+ * Read a directory of cron files: the definitions that loaded, keyed by id, and
+ * one `<file> (<reason>)` per file that will NOT be scheduled.
  *
- * A job that does not load does not run, and until now the only trace was one
+ * A job that does not load does not run, and the only trace used to be one
  * `warn` per file in the boot log — next to nothing at 3am when the report that
- * should have been mailed was not. A cron file is written once and then trusted
- * for months, so "it silently never ran" is the failure mode this surface has,
- * and a log line is not a surface.
+ * should have been mailed was not. So the skips are counted, summarised in one
+ * place, and answered by `GET /api/admin/cron`.
  *
- * Never throws, for the same reason `loadFunctionsWithDiagnostics` does not: one
+ * Never throws, for the same reason the function loader does not: one
  * malformed file must not take the server down, and the other jobs in the
- * directory are still worth scheduling. The difference is that the skips are now
- * counted, summarised in one place, and answered by `GET /api/cron` — so the
- * question "why did nothing run?" has an answer that does not require log
- * access.
+ * directory are still worth scheduling.
  */
-export declare function loadCronJobsWithDiagnostics(directory: string, importModule?: ModuleImporter): Promise<LoadedCronJobs>;
+export declare function readCronsDirectory(directory: string, importModule?: ModuleImporter): Promise<{
+    crons: CronsRecord;
+    problems: string[];
+}>;
 /**
  * The declaration a definition makes: every field a host can read without the
  * handler. Spelled once here so the graph and the scheduler cannot disagree

package/dist/cron/cron-routes.d.ts

@@ -7,7 +7,7 @@ import { type CronScheduler } from "./cron-scheduler.js";
  * Routes:
  *   GET    /          → list all cron jobs
  *   GET    /:id       → get a single job's status
- *   POST   /:id/trigger → manually trigger a job
+ *   POST   /:id/trigger → manually trigger a job (`?async=1`: 202 once it has started)
  *   GET    /:id/logs  → get execution logs for a job
  *   PUT    /:id       → update job (enable/disable, or `null` to follow the code)
  *

package/dist/cron/cron-scheduler.d.ts

@@ -1,4 +1,4 @@
-import type { CronJobStatus, CronJobLogEntry } from "@rebasepro/types";
+import type { CronJobDefinition, CronJobStatus, CronJobLogEntry, RejectedCronJob } from "@rebasepro/types";
 import type { RebaseServerClient } from "@rebasepro/types";
 import type { LoadedCronJob } from "./cron-loader.js";
 import type { CronStore } from "./cron-store.js";
@@ -30,9 +30,9 @@ export declare function parseCronExpression(expression: string, after: Date, tim
  * The latest slot matching `expression` within the inclusive window
  * `[from, to]`, or `undefined` when the expression has no slot in it.
  *
- * Walks backwards a minute at a time from `to`, so the first hit is already
- * the answer — in the common case (a job that ran normally moments ago) that
- * is a handful of iterations, not a scan of the whole window.
+ * Walks backwards from `to`, so the first hit is already the answer — in the
+ * common case (a job that ran normally moments ago) that is a handful of
+ * steps, not a scan of the whole window.
  *
  * `to`'s own minute is included: an instance booting at 06:00:30 has *not* run
  * the 06:00 slot — `parseCronExpression` already skipped past it to tomorrow —
@@ -43,6 +43,29 @@ export declare function parseCronExpression(expression: string, after: Date, tim
  * ISO string down either path. The claim key depends on that.
  */
 export declare function findMostRecentSlot(expression: string, from: Date, to: Date, timezone?: string): Date | undefined;
+/**
+ * What one run keeps of its `ctx.log` lines: up to 500 lines or 64 KB,
+ * whichever comes first. The lines past that are counted, and one line at the
+ * end says how many there were; every line still reaches the server log.
+ *
+ * Uncapped, a job logging one line per item kept them all — in the 50-run ring
+ * per job, in a `cron_logs` row, and in every history read: a per-minute sync
+ * of 1,000 items held 4 MB per job in memory and wrote 115 MB a day.
+ */
+export declare const MAX_CAPTURED_LOG_LINES = 500;
+export declare const MAX_CAPTURED_LOG_BYTES: number;
+/**
+ * What {@link CronScheduler.startJob} answers: the run began at `startedAt`
+ * (its history entry will carry the same timestamp), or it did not start and
+ * `log` is the skip that says why.
+ */
+export type StartedCronRun = {
+    started: true;
+    startedAt: string;
+} | {
+    started: false;
+    log: CronJobLogEntry;
+};
 /**
  * Whether a log entry records a run that did not happen because one was
  * already executing — on this process, or on another that holds the job's run
@@ -50,19 +73,6 @@ export declare function findMostRecentSlot(expression: string, from: Date, to: D
  * panel reads.
  */
 export declare function isAlreadyExecutingSkip(entry: CronJobLogEntry): boolean;
-/**
- * A job the scheduler refused, and why.
- *
- * It is not a `CronJobStatus`: it has no state, no next run and no counters,
- * because it was never registered. Reporting it as a job with `state: "error"`
- * would be a lie in the other direction — nothing is going to run it.
- */
-export interface RejectedCronJob {
-    id: string;
-    name: string;
-    schedule: string;
-    reason: string;
-}
 export declare class CronScheduler {
     private jobs;
     private rejected;
@@ -82,6 +92,10 @@ export declare class CronScheduler {
      * ever clear the lease that run took.
      */
     private readonly instanceLabel;
+    /** The hourly claim- and log-retention sweep, while the scheduler is started with a store. */
+    private claimSweepTimer?;
+    private sweepingClaims;
+    private sweepingLogs;
     /**
      * Set the server singleton to make it available to cron job handlers.
      *
@@ -111,6 +125,14 @@ export declare class CronScheduler {
      * Start the scheduler — begins ticking all enabled jobs.
      */
     start(): void;
+    /** Delete slot claims past retention. Failures are logged; the next hour tries again. */
+    private sweepClaims;
+    /**
+     * Delete run history past retention, and count the runs not counted yet.
+     * Failures are logged; the next hour tries again, from where this one
+     * stopped — each batch it finished is committed.
+     */
+    private sweepLogs;
     /**
      * Stop the scheduler: clear every timer, then wait for the runs executing
      * right now — for at most `timeoutMs` when given.
@@ -128,6 +150,8 @@ export declare class CronScheduler {
      * List all registered jobs with their current status.
      */
     listJobs(): CronJobStatus[];
+    /** Keep a refused job, so the admin surface can say why it never runs. */
+    private refuse;
     /**
      * Jobs that loaded but whose schedule the scheduler refused.
      *
@@ -136,6 +160,17 @@ export declare class CronScheduler {
      * cron will never fire" look identical from the admin panel.
      */
     listRejectedJobs(): RejectedCronJob[];
+    /**
+     * {@link listRejectedJobs}, those whose definition matches — how a surface
+     * finds a refused job by what it is, as {@link jobIdsWhere} does for the
+     * registered ones.
+     */
+    rejectedJobsWhere(predicate: (definition: CronJobDefinition) => boolean): RejectedCronJob[];
+    /**
+     * The ids of the registered jobs whose definition matches — how a surface
+     * finds a job by what it is rather than by the file it happens to live in.
+     */
+    jobIdsWhere(predicate: (definition: CronJobDefinition) => boolean): string[];
     /**
      * Get a single job status by ID.
      */
@@ -144,11 +179,11 @@ export declare class CronScheduler {
      * {@link listJobs}, as the fleet sees it rather than this process alone.
      *
      * Reads the store: every job's enabled state — a pause another replica
-     * made — and whether another process holds its run lease. On a process
-     * whose scheduler is not started (the `api` role) it also reads each job's
-     * run count and last run from `cron_logs`, since that process runs nothing
-     * and its own counters would say 0 runs for a job the worker has run a
-     * thousand times.
+     * made — whether another process holds its run lease, and each job's run
+     * count and last run from `cron_logs`. The counters in this process's
+     * memory count only the runs it made: the `api` role runs nothing and
+     * would say 0 runs for a job the worker has run a thousand times, and one
+     * of two scheduling replicas never sees the slots the other one claimed.
      *
      * A store that cannot answer leaves this process's own view, with a
      * warning: a listing is not worth failing.
@@ -162,7 +197,12 @@ export declare class CronScheduler {
     getJobLogs(id: string, limit?: number): CronJobLogEntry[];
     /**
      * Get log entries for a job from the database (if store is available).
-     * Falls back to in-memory logs if no store is configured.
+     * Falls back to in-memory logs if no store is configured, or if the store
+     * has none — a run whose row is still being written.
+     *
+     * Throws when the store cannot read the history. This process's memory is
+     * not a stand-in for it: it is empty on the `api` role and after a
+     * restart, and holds one replica's runs at most.
      */
     getJobLogsFromDb(id: string, limit?: number): Promise<CronJobLogEntry[]>;
     /**
@@ -199,6 +239,22 @@ export declare class CronScheduler {
      * recognises it.
      */
     triggerJob(id: string): Promise<CronJobLogEntry | undefined>;
+    /**
+     * Start a job now and answer as soon as the run has begun, not when it
+     * ends — the manual trigger's `?async=1`.
+     *
+     * The synchronous {@link triggerJob} holds its HTTP request open for the
+     * whole run, and a proxy in front of the server (many stop at 60 s) cuts
+     * a long job's answer while the run carries on. This resolves once the
+     * run lease is held and the handler is about to be called, so a run that
+     * cannot start — already executing here or on the lease holder — is still
+     * answered as the skip it is. The run itself is tracked like any other:
+     * `stop()` waits for it, and its outcome lands in the run history, where
+     * the entry carries `manual: true` and the `startedAt` returned here.
+     *
+     * Returns `undefined` if the job doesn't exist.
+     */
+    startJob(id: string): Promise<StartedCronRun | undefined>;
     /**
      * Record a run that did not happen because the previous one had not
      * finished.
@@ -262,6 +318,21 @@ export declare class CronScheduler {
      * rest as a view for {@link toStatus}. Never throws.
      */
     private readFleet;
+    /**
+     * The next slot of `job` after `now`, for a listing on a process whose
+     * scheduler is not started — the `api` role, which Studio's Cron panel
+     * polls every 15 seconds.
+     *
+     * Cached on the job. The key is the job's schedule and zone (a re-register
+     * replaces the job, and with it the cache); the entry holds while
+     * `computedAt <= now < slot`. That is the same answer, not an
+     * approximation: the search found no matching minute between
+     * `computedAt`'s next minute and `slot`, so from any later instant before
+     * `slot` it lands on `slot` again. A clock that moves back, or reaching the
+     * slot, recomputes. The cache holds a pure function of the schedule, so
+     * there is nothing user- or role-scoped in it.
+     */
+    private listedNextRun;
     /**
      * Warn once at start when the process looks like it is running on a
      * platform that freezes or evicts instances between requests, where the

package/dist/cron/cron-store.d.ts

@@ -11,12 +11,21 @@ import type { DataDriver } from "@rebasepro/types";
  * occurs, and a pause or a trigger's "already executing" is per process.
  */
 export interface CronStore {
-    /** Ensure the backing table exists. Called once on startup. */
+    /**
+     * Ensure the backing tables exist and are locked away from end users. Runs
+     * once per process per database, however many stores ask: concurrent
+     * callers share the attempt in flight, and an attempt that fell short is
+     * made again on the next call.
+     */
     ensureTable(): Promise<void>;
     /** Persist a single log entry after execution. */
     insertLog(entry: CronJobLogEntry): Promise<void>;
     /**
      * Fetch the most recent logs for a job.
+     *
+     * Throws when the history cannot be read. An empty array is a claim — the
+     * job has no recorded runs — and a caller shows it as "never ran".
+     *
      * @param jobId  The job identifier
      * @param limit  Max entries to return (default 50)
      * @returns Logs sorted newest-first
@@ -24,7 +33,8 @@ export interface CronStore {
     fetchLogs(jobId: string, limit?: number): Promise<CronJobLogEntry[]>;
     /**
      * Fetch aggregate stats for all jobs (totalRuns, totalFailures, lastRunAt).
-     * Used to seed in-memory counters on startup.
+     * Used to seed in-memory counters on startup. The SQL store reads them from
+     * the all-time counters on `cron_job_state`, not from the history.
      */
     fetchJobStats(): Promise<Map<string, {
         totalRuns: number;
@@ -82,11 +92,33 @@ export interface CronStore {
     /** Release a lease taken with {@link tryAcquireRunLease} — only if `holder` still holds it. */
     releaseRunLease?(jobId: string, holder: string): Promise<void>;
     /**
-     * Run count, failure count and last run of each job, read from
-     * `cron_logs` — for a process whose scheduler is not started (the `api`
-     * role), which runs nothing and so counts nothing of its own.
+     * Run count, failure count and last run of each job — every process's
+     * runs, where the scheduler's own counters hold only the ones it made. The
+     * SQL store keeps them as all-time counters on `cron_job_state`, so they
+     * outlive the history's retention.
      */
     fetchRunSummaries?(jobIds: readonly string[]): Promise<Map<string, CronJobRunSummary>>;
+    /**
+     * Delete slot claims past retention — all but each job's most recent one —
+     * in batches. Resolves with how many went. The scheduler runs it on a
+     * timer while it is started; a store without it keeps every claim.
+     */
+    sweepClaims?(): Promise<number>;
+    /**
+     * Delete run history past retention, and count into the job counters any
+     * run that is not counted yet — a history written before the counters
+     * existed, or by an older server during a rolling deploy. Both in batches.
+     * The scheduler runs it with {@link sweepClaims}; a store without it keeps
+     * every run.
+     */
+    sweepLogs?(): Promise<CronLogSweep>;
+}
+/** What one {@link CronStore.sweepLogs} did. */
+export interface CronLogSweep {
+    /** History rows deleted past retention. */
+    deleted: number;
+    /** Runs counted into the job counters that were not counted before. */
+    counted: number;
 }
 /** One job's row in `rebase.cron_job_state`, as the scheduler reads it. */
 export interface CronJobPersistedState {

package/dist/cron/define-cron.d.ts

@@ -1,4 +1,4 @@
-import type { CronJobDefinition } from "@rebasepro/types";
+import type { CronJobDefinition, RegisteredDatabase } from "@rebasepro/types";
 /**
  * Typed authoring helper for a cron job file. Identity at runtime —
  * a plain default-exported {@link CronJobDefinition} works identically;
@@ -38,5 +38,9 @@ import type { CronJobDefinition } from "@rebasepro/types";
  *     },
  * });
  * ```
+ *
+ * `ctx.rebase` is typed from the `Database` the project registered on
+ * `Register` (see the typed server data guide), and untyped when it registered
+ * none. `defineCron<Database>({…})` types one job without the registration.
  */
-export declare function defineCron(definition: CronJobDefinition): CronJobDefinition;
+export declare function defineCron<DB = RegisteredDatabase>(definition: CronJobDefinition<DB>): CronJobDefinition<DB>;

package/dist/cron/index.d.ts

@@ -1,8 +1,8 @@
-export { loadCronJobsFromDirectory, loadCronJobsWithDiagnostics } from "./cron-loader.js";
-export type { LoadedCronJob, LoadedCronJobs } from "./cron-loader.js";
+export { loadCrons, declareCrons, cronJobsFrom, loadCronJobsFromDirectory, loadCronJobsWithDiagnostics } from "./cron-loader.js";
+export type { CronsRecord, LoadedCronJob, LoadedCronJobs } from "./cron-loader.js";
 export { defineCron } from "./define-cron.js";
 export { CronScheduler, validateCronExpression } from "./cron-scheduler.js";
 export { createCronRoutes } from "./cron-routes.js";
 export { createCronStore } from "./cron-store.js";
 export { detectFreezableRuntime, buildScaleToZeroWarning, CRON_ALWAYS_ON_ENV } from "./scale-to-zero.js";
-export type { CronStore, CronJobPersistedState, CronRunLease, CronJobRunSummary } from "./cron-store.js";
+export type { CronStore, CronJobPersistedState, CronRunLease, CronJobRunSummary, CronLogSweep } from "./cron-store.js";

package/dist/cron-loader-NHqRfKF0.js

@@ -0,0 +1,202 @@
+import { createRequire as __rebaseCreateRequire } from "module";
+import __rebaseProcess from "process";
+globalThis.process ??= __rebaseProcess;
+__rebaseCreateRequire(import.meta.url);
+import { n as __exportAll } from "./rolldown-runtime-dW7B1o5h.js";
+import { x as declareCron } from "./src-D5Y3N-S4.js";
+import { r as logger } from "./logger-Bt32sHFw.js";
+import { i as warnDeprecated, n as describeLoadFailure, r as nativeDynamicImport, t as SYNTAX_ERROR_ADVICE } from "./load-failure-L5hvfDoG.js";
+import * as fs$1 from "fs";
+import * as path$1 from "path";
+import { pathToFileURL } from "url";
+//#region src/cron/cron-loader.ts
+var cron_loader_exports = /* @__PURE__ */ __exportAll({
+	cronJobsFrom: () => cronJobsFrom,
+	cronResourceOptions: () => cronResourceOptions,
+	declareCrons: () => declareCrons,
+	loadCronJobsFromDirectory: () => loadCronJobsFromDirectory,
+	loadCronJobsWithDiagnostics: () => loadCronJobsWithDiagnostics,
+	loadCrons: () => loadCrons,
+	readCronsDirectory: () => readCronsDirectory
+});
+/**
+* Load the cron jobs in a directory, as values.
+*
+* Each file default-exports a `CronJobDefinition` — `defineCron({...})`. The
+* filename without its extension is the record key, which is the job id:
+* `crons/cleanup-sessions.ts` → `{ "cleanup-sessions": definition }`.
+*
+* Loading declares nothing: the definitions come back exactly as written, and
+* whoever uses them decides what they are for — a backend schedules them, the
+* build's derive step records them in the resource graph ({@link declareCrons}).
+*
+* Never throws for a bad file: it is skipped, logged, and passed to
+* `options.onSkip`.
+*
+* @example
+* ```ts
+* const crons = await loadCrons(path.resolve("crons"));
+* const backend = await createRebaseBackend({ database, crons, provision: true });
+* ```
+*/
+async function loadCrons(directory, options = {}) {
+	const { crons, problems } = await readCronsDirectory(directory, options.importModule);
+	if (options.onSkip) for (const problem of problems) options.onSkip(problem);
+	return crons;
+}
+/**
+* Record each cron in the project's resource graph — what `rebase resources`
+* lists and a host reads to know a schedule exists, without running it.
+*
+* Keyed by the same id the scheduler, the routes and the Studio use, and built
+* from the definitions as written: a default the scheduler fills in
+* (`enabled: true`, `timeoutSeconds: 300`) is this process's, not something the
+* author declared.
+*/
+function declareCrons(crons) {
+	for (const [id, definition] of Object.entries(crons)) declareCron(id, cronResourceOptions(definition));
+}
+/**
+* The jobs a scheduler registers, from cron values: the definitions with this
+* process's defaults filled in.
+*
+* Spread first, then normalise. Rebuilding the object field by field dropped
+* `catchUpWindowSeconds` once — and since this is the path every job takes to
+* the scheduler, catch-up never ran for any job authored the documented way. A
+* field added to `CronJobDefinition` tomorrow would be dropped the same way.
+*
+* @throws when a value has no `schedule` or no `handler`. A file like that is
+* skipped by the loader with a reason; a value handed over in code is refused,
+* because the caller is right there to fix it.
+*/
+function cronJobsFrom(crons) {
+	return Object.entries(crons).map(([id, definition]) => {
+		const def = definition;
+		if (!def || typeof def.schedule !== "string" || typeof def.handler !== "function") throw new Error(`crons["${id}"] is not a cron job: it needs a \`schedule\` string and a \`handler\` function. Author it with \`defineCron({ schedule, handler })\`.`);
+		return {
+			id,
+			definition: {
+				...def,
+				schedule: def.schedule,
+				name: def.name || id,
+				enabled: def.enabled !== false,
+				timeoutSeconds: def.timeoutSeconds ?? 300,
+				handler: def.handler
+			}
+		};
+	});
+}
+/**
+* @deprecated Use `loadCrons` instead, which returns the jobs as a record keyed
+* by id. Will be removed in a future release.
+*/
+async function loadCronJobsFromDirectory(directory, importModule = nativeDynamicImport) {
+	warnDeprecated("server.loadCronJobsFromDirectory", "`loadCronJobsFromDirectory` is deprecated; use `loadCrons(dir)`, which returns `{ [id]: definition }`.");
+	return (await legacyLoad(directory, importModule)).jobs;
+}
+/**
+* @deprecated Use `loadCrons` instead, with `onSkip` to collect the files it
+* skipped — and `declareCrons` where the jobs belong in the resource graph,
+* which this used to do as a side effect of loading. Will be removed in a
+* future release.
+*/
+async function loadCronJobsWithDiagnostics(directory, importModule = nativeDynamicImport) {
+	warnDeprecated("server.loadCronJobsWithDiagnostics", "`loadCronJobsWithDiagnostics` is deprecated; use `loadCrons(dir, { onSkip })`, which returns `{ [id]: definition }`, and `declareCrons(crons)` to record them in the resource graph.");
+	return legacyLoad(directory, importModule);
+}
+/**
+* What the deprecated loaders did: load, declare every job in the resource
+* graph, and hand back normalised jobs. A job the graph refuses is skipped as a
+* problem, as it was when the declaration ran inside the loader.
+*/
+async function legacyLoad(directory, importModule) {
+	const { crons, problems } = await readCronsDirectory(directory, importModule);
+	const declared = {};
+	for (const [id, definition] of Object.entries(crons)) try {
+		declareCron(id, cronResourceOptions(definition));
+		declared[id] = definition;
+	} catch (err) {
+		problems.push(describeLoadFailure(id, err));
+	}
+	return {
+		jobs: cronJobsFrom(declared),
+		problems
+	};
+}
+/**
+* Read a directory of cron files: the definitions that loaded, keyed by id, and
+* one `<file> (<reason>)` per file that will NOT be scheduled.
+*
+* A job that does not load does not run, and the only trace used to be one
+* `warn` per file in the boot log — next to nothing at 3am when the report that
+* should have been mailed was not. So the skips are counted, summarised in one
+* place, and answered by `GET /api/admin/cron`.
+*
+* Never throws, for the same reason the function loader does not: one
+* malformed file must not take the server down, and the other jobs in the
+* directory are still worth scheduling.
+*/
+async function readCronsDirectory(directory, importModule = nativeDynamicImport) {
+	const crons = {};
+	const problems = [];
+	if (!fs$1.existsSync(directory)) return {
+		crons,
+		problems
+	};
+	const files = fs$1.readdirSync(directory);
+	for (const file of files) if ((file.endsWith(".ts") || file.endsWith(".js")) && !file.startsWith(".") && !file.includes(".test.") && !file.endsWith(".d.ts") && file !== "index.ts" && file !== "index.js") {
+		const filePath = path$1.join(directory, file);
+		try {
+			const fileUrl = pathToFileURL(filePath).href;
+			const exported = (await importModule(fileUrl)).default;
+			if (!exported || typeof exported !== "object") {
+				problems.push(`${file} (no default export)`);
+				logger.warn(`[cron] ${file}: no valid default export. Skipping.`);
+				continue;
+			}
+			const def = exported;
+			if (typeof def.schedule !== "string" || def.schedule.trim() === "" || typeof def.handler !== "function") {
+				problems.push(`${file} (default export has no 'schedule' or no 'handler')`);
+				logger.warn(`[cron] ${file}: default export missing required 'schedule' or 'handler'. Skipping.`);
+				continue;
+			}
+			const id = path$1.basename(file, path$1.extname(file));
+			const definition = exported;
+			crons[id] = definition;
+			logger.info(`⏰ Loaded cron job: ${id} (${definition.schedule}${definition.timezone ? ` ${definition.timezone}` : " in the process's local time"})`);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			problems.push(describeLoadFailure(file, err));
+			logger.debug(`[cron] Failed to load ${file}: ${message}`);
+		}
+	}
+	if (problems.length > 0) {
+		const syntax = problems.some((p) => p.includes("(syntax error"));
+		const other = problems.some((p) => !p.includes("(syntax error"));
+		logger.warn(`[cron] ${problems.length} cron file(s) were skipped and will NOT be scheduled:\n` + problems.map((p) => `  - ${p}`).join("\n") + "\n" + [...syntax ? [SYNTAX_ERROR_ADVICE] : [], ...other ? ["  Fix these or author them with `defineCron(...)` for a typed, compile-checked contract."] : []].join("\n"));
+	}
+	return {
+		crons,
+		problems
+	};
+}
+/**
+* The declaration a definition makes: every field a host can read without the
+* handler. Spelled once here so the graph and the scheduler cannot disagree
+* about what a cron is.
+*/
+function cronResourceOptions(definition) {
+	return {
+		schedule: definition.schedule,
+		...definition.timezone !== void 0 ? { timezone: definition.timezone } : {},
+		...definition.description !== void 0 ? { description: definition.description } : {},
+		...definition.enabled !== void 0 ? { enabled: definition.enabled } : {},
+		...definition.timeoutSeconds !== void 0 ? { timeoutSeconds: definition.timeoutSeconds } : {},
+		...definition.catchUpWindowSeconds !== void 0 ? { catchUpWindowSeconds: definition.catchUpWindowSeconds } : {},
+		...definition.name ? { label: definition.name } : {}
+	};
+}
+//#endregion
+export { loadCrons as a, loadCronJobsWithDiagnostics as i, declareCrons as n, loadCronJobsFromDirectory as r, cron_loader_exports as t };
+
+//# sourceMappingURL=cron-loader-NHqRfKF0.js.map