@openlup/platform 0.0.0 → 0.15.0

package/dist/scheduler/advisoryLock.d.ts

@@ -0,0 +1,44 @@
+/** A cluster-wide, per-job mutex. Returns true iff THIS caller acquired the lock. */
+export interface AdvisoryLock {
+    /** Explicit capability marker; a host that must not run a job twice requires a cluster lock. */
+    readonly durability?: "cluster" | "process";
+    /** Try to acquire the lock for `jobId` without blocking. */
+    tryAcquire(jobId: string): Promise<boolean>;
+    /** Release a previously-acquired lock for `jobId`. */
+    release(jobId: string): Promise<void>;
+    /** Release the dedicated session when the host stops; safe to call repeatedly. */
+    close(): Promise<void>;
+}
+/** Minimal pg-query surface (a `pg` Pool/Client satisfies this) — keeps `pg` out of the import graph. */
+export interface AdvisoryLockQuerier {
+    query<T = unknown>(text: string, values?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    end?(): Promise<void>;
+}
+/**
+ * Deterministic 64-bit-ish key from a jobId for pg_try_advisory_lock(bigint).
+ * Postgres advisory locks key on bigint; we hash the job name to a stable signed-32-bit int
+ * (the single-arg `pg_try_advisory_lock(key bigint)` accepts it). Stable across processes.
+ */
+export declare function advisoryLockKey(jobId: string): number;
+/**
+ * pg-backed advisory lock. Uses `pg_try_advisory_lock` (session-scoped, non-blocking) on acquire
+ * and `pg_advisory_unlock` on release. NOTE: session-scoped locks require the same connection for
+ * acquire+release, so the supplied querier should be a single dedicated client/connection, not a
+ * pool that hands out a different connection per query.
+ */
+export declare function createPgAdvisoryLock(client: AdvisoryLockQuerier, closeClient?: () => Promise<void>): AdvisoryLock;
+/**
+ * Build the lock a long-running host should actually use, from the connection string the
+ * environment declares. Returns null when no connection string is configured, which leaves the
+ * scheduler on its always-granting default — the exact behaviour of a host with a single instance.
+ *
+ * The connection is opened LAZILY, on the first acquire, and then reused: a session-scoped
+ * try-lock must acquire and release on the SAME connection, and a host that never fires a timer
+ * must never open one. `pg` stays out of the static import graph (dynamic import), so the default
+ * hosted path and typecheck are untouched.
+ */
+export declare function createEnvAdvisoryLock(env: Record<string, string | undefined>, connect?: (connectionString: string) => Promise<AdvisoryLockQuerier>): AdvisoryLock | null;
+/** Lock that always grants (single-instance / tests). Never use in multi-instance Node deploys. */
+export declare function createNoopAdvisoryLock(): AdvisoryLock;

package/dist/scheduler/advisoryLock.js

@@ -0,0 +1,114 @@
+// Per-job advisory lock for the Node scheduler.
+//
+// On Vercel exactly one cron timer fires per schedule. On a self-hosted Node bundle the SAME
+// process image can run on MULTIPLE instances (horizontal scale, blue/green overlap, a stray
+// second pod) — each with its own node-cron timer. Without coordination, every instance would
+// fire the same job at the same minute => double-run (double emails, double polls, double
+// dispatch). `pg_try_advisory_lock` gives us a cluster-wide, connection-scoped mutex keyed per job:
+// only the instance that ACQUIRES the lock runs the job body; the rest skip and release nothing
+// (try-lock returns false without blocking). The lock is released after the job body finishes.
+//
+// Injectable: the adapter depends on the AdvisoryLock interface, not on `pg` directly, so tests
+// run without a database and a non-Supabase bundle can supply its own pg-backed implementation.
+/**
+ * Deterministic 64-bit-ish key from a jobId for pg_try_advisory_lock(bigint).
+ * Postgres advisory locks key on bigint; we hash the job name to a stable signed-32-bit int
+ * (the single-arg `pg_try_advisory_lock(key bigint)` accepts it). Stable across processes.
+ */
+export function advisoryLockKey(jobId) {
+    // FNV-1a 32-bit, then coerce to signed 32-bit so it fits a Postgres int safely.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < jobId.length; i += 1) {
+        hash ^= jobId.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash | 0;
+}
+/**
+ * pg-backed advisory lock. Uses `pg_try_advisory_lock` (session-scoped, non-blocking) on acquire
+ * and `pg_advisory_unlock` on release. NOTE: session-scoped locks require the same connection for
+ * acquire+release, so the supplied querier should be a single dedicated client/connection, not a
+ * pool that hands out a different connection per query.
+ */
+export function createPgAdvisoryLock(client, closeClient = () => client.end?.() ?? Promise.resolve()) {
+    let closePromise = null;
+    return {
+        durability: "cluster",
+        async tryAcquire(jobId) {
+            const key = advisoryLockKey(jobId);
+            const { rows } = await client.query("SELECT pg_try_advisory_lock($1) AS locked", [key]);
+            return rows[0]?.locked === true;
+        },
+        async release(jobId) {
+            const key = advisoryLockKey(jobId);
+            await client.query("SELECT pg_advisory_unlock($1)", [key]);
+        },
+        close() {
+            closePromise ??= closeClient();
+            return closePromise;
+        },
+    };
+}
+/**
+ * Build the lock a long-running host should actually use, from the connection string the
+ * environment declares. Returns null when no connection string is configured, which leaves the
+ * scheduler on its always-granting default — the exact behaviour of a host with a single instance.
+ *
+ * The connection is opened LAZILY, on the first acquire, and then reused: a session-scoped
+ * try-lock must acquire and release on the SAME connection, and a host that never fires a timer
+ * must never open one. `pg` stays out of the static import graph (dynamic import), so the default
+ * hosted path and typecheck are untouched.
+ */
+export function createEnvAdvisoryLock(env, connect = connectDedicatedClient) {
+    const connectionString = env.DATABASE_URL?.trim() ?? "";
+    if (connectionString === "")
+        return null;
+    let pending = null;
+    let closed = false;
+    let closePromise = null;
+    const querier = {
+        async query(text, values) {
+            if (closed)
+                throw new Error("advisory_lock_closed");
+            pending ??= connect(connectionString);
+            const client = await pending;
+            return client.query(text, values);
+        },
+    };
+    return createPgAdvisoryLock(querier, () => {
+        closed = true;
+        closePromise ??= pending?.then((client) => client.end?.() ?? undefined) ?? Promise.resolve();
+        return closePromise;
+    });
+}
+async function connectDedicatedClient(connectionString) {
+    const pg = await import("pg").catch(peerMissing);
+    const ClientCtor = (pg.default?.Client ?? pg.Client);
+    const client = new ClientCtor({ connectionString });
+    await client.connect();
+    return client;
+}
+/** Lock that always grants (single-instance / tests). Never use in multi-instance Node deploys. */
+export function createNoopAdvisoryLock() {
+    return {
+        durability: "process",
+        async tryAcquire() {
+            return true;
+        },
+        async release() {
+            /* no-op */
+        },
+        async close() {
+            /* no-op */
+        },
+    };
+}
+/** Translate only absence of this optional peer; preserve broken SDKs and other failures. */
+function peerMissing(cause) {
+    if (cause instanceof Error && "code" in cause
+        && (cause.code === "ERR_MODULE_NOT_FOUND" || cause.code === "MODULE_NOT_FOUND")
+        && /^Cannot find (?:package|module) ['"]pg['"]/.test(cause.message)) {
+        throw new Error("OPENLUP_E_PEER_MISSING: pg is required by the Postgres scheduler advisory lock; install it alongside @openlup/platform", { cause });
+    }
+    throw cause;
+}

package/dist/scheduler/cronGuard.d.ts

@@ -0,0 +1,10 @@
+import type { HttpRequest } from "../http/index.js";
+import { bearerToken } from "./cronSecret.js";
+export { bearerToken };
+export interface CronAuthDenied {
+    status: number;
+    body: Record<string, unknown>;
+}
+export declare function authorizeCron(req: HttpRequest, env: {
+    CRON_SECRET?: string;
+}): CronAuthDenied | null;

package/dist/scheduler/cronGuard.js

@@ -0,0 +1,19 @@
+import { bearerToken, cronSecretMatches } from "./cronSecret.js";
+export { bearerToken };
+// Shared cron entrypoint guard: method allowlist + CRON_SECRET presence + constant-time bearer
+// match (see ./cronSecret.ts). Returns a response to return verbatim when denied, or null when the
+// request is authorized. Per-job flag kill-switches and provider/env readiness
+// checks intentionally stay in each job — they differ per job and must run after
+// this guard but before any ledger write.
+export function authorizeCron(req, env) {
+    if (req.method !== "GET" && req.method !== "POST") {
+        return { status: 405, body: { ok: false, error: "method_not_allowed" } };
+    }
+    if (!env.CRON_SECRET) {
+        return { status: 503, body: { ok: false, error: "cron_secret_required" } };
+    }
+    if (!cronSecretMatches(bearerToken(req), env.CRON_SECRET)) {
+        return { status: 401, body: { ok: false, error: "unauthorized" } };
+    }
+    return null;
+}

package/dist/scheduler/cronSecret.d.ts

@@ -0,0 +1,5 @@
+import type { PlatformHttpRequest } from "@openlup/core/platform-runtime";
+/** Extract the Bearer token from a request Authorization header (case-insensitive). */
+export declare function bearerToken(req: PlatformHttpRequest): string | null;
+/** True when the presented token equals the configured secret, compared in constant time. */
+export declare function cronSecretMatches(presented: string | null, expected: string): boolean;

package/dist/scheduler/cronSecret.js

@@ -0,0 +1,23 @@
+// The one cron bearer check shared by the cron entrypoint guard and the scheduler verifier.
+//
+// Grammar: `Authorization: Bearer <token>`, scheme case-insensitive, the first value of a repeated
+// header, the presented token trimmed and the configured secret compared as-is. The comparison takes
+// the same time for every presented token of the secret's byte length, so a mismatch reveals no
+// matching prefix; a token of another byte length (including any non-ASCII one) is refused first.
+import { timingSafeEqual } from "node:crypto";
+/** Extract the Bearer token from a request Authorization header (case-insensitive). */
+export function bearerToken(req) {
+    const auth = req.headers.authorization;
+    const header = Array.isArray(auth) ? auth[0] : auth;
+    return header?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim() ?? null;
+}
+/** True when the presented token equals the configured secret, compared in constant time. */
+export function cronSecretMatches(presented, expected) {
+    if (presented === null)
+        return false;
+    const presentedBytes = Buffer.from(presented, "utf8");
+    const expectedBytes = Buffer.from(expected, "utf8");
+    if (presentedBytes.length !== expectedBytes.length)
+        return false;
+    return timingSafeEqual(presentedBytes, expectedBytes);
+}

package/dist/scheduler/handlers.d.ts

@@ -0,0 +1,9 @@
+export type ScheduledInvocationSource = "node_cron" | "scheduler";
+export interface ScheduledJobInvocation {
+    jobId: string;
+    invocationSource: ScheduledInvocationSource;
+}
+export type ScheduledJobHandler = (invocation: ScheduledJobInvocation) => Promise<void> | void;
+export type ScheduledJobHandlerRegistry = Readonly<Partial<Record<string, ScheduledJobHandler>>>;
+/** Merge contributed bindings in order; a later contribution replaces an earlier one for the same job. */
+export declare function mergeScheduledJobHandlers(...registries: ReadonlyArray<ScheduledJobHandlerRegistry | undefined>): ScheduledJobHandlerRegistry;

package/dist/scheduler/handlers.js

@@ -0,0 +1,10 @@
+// Direct scheduled-job bindings for self-hosted runtimes.
+//
+// The Node host mounts every declared `/api/cron/<jobId>` route, so any job can be reached
+// through the HTTP compatibility bridge. A direct binding skips that hop: it calls the
+// application runtime in-process and records an honest invocation source instead of a
+// hosted-cron one. Deployments and domains contribute bindings; this module only merges them.
+/** Merge contributed bindings in order; a later contribution replaces an earlier one for the same job. */
+export function mergeScheduledJobHandlers(...registries) {
+    return Object.assign({}, ...registries.filter((registry) => registry !== undefined));
+}

package/dist/scheduler/httpEntry.d.ts

@@ -0,0 +1,16 @@
+import type { JobLeasePort } from "@openlup/core/platform-runtime";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { type ScheduledJob } from "./jobs.js";
+export interface ScheduledJobHttpEntryOptions {
+    /** Environment whose CRON_SECRET authenticates the caller, read on each request. */
+    env: () => {
+        CRON_SECRET?: string;
+    };
+    /** Evidence recorded for HTTP invocations, for example the hosting platform's cron. */
+    invocationSource: string;
+    /** The job-lease port, required when the job declares a lease. */
+    lease?: JobLeasePort;
+    /** Error sink for a failed run (defaults to console.error). */
+    onError?: (jobId: string, error: unknown) => void;
+}
+export declare function createScheduledJobHttpEntry(job: ScheduledJob, options: ScheduledJobHttpEntryOptions): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/scheduler/httpEntry.js

@@ -0,0 +1,31 @@
+// Authenticated HTTP cron entry for a transport-neutral scheduled job.
+//
+// The entry is an adapter: it applies the cron guard (method, configured secret, bearer token) and
+// only then runs the job with an HTTP invocation. A refusal answers the guard's own status and
+// body. A run answers 200 with its result, a lease held elsewhere answers 200 as skipped, and a
+// failed run answers 500 without error detail; the error goes to the host's error sink.
+import { authorizeCron } from "./cronGuard.js";
+import { runScheduledJob } from "./jobs.js";
+export function createScheduledJobHttpEntry(job, options) {
+    const onError = options.onError ?? ((jobId, error) => console.error(`[scheduled-job] "${jobId}" failed`, error));
+    return async function scheduledJobEntry(req, res) {
+        const denied = authorizeCron(req, options.env());
+        if (denied) {
+            res.status(denied.status).json(denied.body);
+            return;
+        }
+        try {
+            const result = await runScheduledJob(job, {
+                invocation: { triggerKind: "scheduler", invocationSource: options.invocationSource },
+                lease: options.lease,
+            });
+            res.status(200).json(result.status === "skipped"
+                ? { ok: true, skipped: true, reason: result.reason }
+                : { ok: true, result: result.summary });
+        }
+        catch (error) {
+            onError(job.id, error);
+            res.status(500).json({ ok: false, error: "scheduled_job_failed" });
+        }
+    };
+}

package/dist/scheduler/index.d.ts

@@ -0,0 +1,9 @@
+export { jobIdFromPath, jobRegistryFromConfig, loadJobRegistry, type PlatformRuntimeConfig, type ScheduledJobDeclaration, } from "./jobRegistry.js";
+export { advisoryLockKey, createEnvAdvisoryLock, createNoopAdvisoryLock, createPgAdvisoryLock, type AdvisoryLock, type AdvisoryLockQuerier, } from "./advisoryLock.js";
+export { createNodeScheduler, withAdvisoryLock, type CreateNodeSchedulerOptions, type CronScheduler, type NodeSchedulerAdapter, } from "./nodeScheduler.js";
+export { bearerToken, createVercelScheduler, verifyCronAuth, type VercelSchedulerAdapter, } from "./vercelScheduler.js";
+export { authorizeCron, type CronAuthDenied } from "./cronGuard.js";
+export { cronSecretMatches } from "./cronSecret.js";
+export { mergeScheduledJobHandlers, type ScheduledInvocationSource, type ScheduledJobHandler, type ScheduledJobHandlerRegistry, type ScheduledJobInvocation, } from "./handlers.js";
+export { createScheduledJobRegistry, cronFromCadenceSeconds, runScheduledJob, scheduledJobsFromContribution, type ScheduledJob, type ScheduledJobContext, type ScheduledJobRunResult, } from "./jobs.js";
+export { createScheduledJobHttpEntry, type ScheduledJobHttpEntryOptions } from "./httpEntry.js";

package/dist/scheduler/index.js

@@ -0,0 +1,9 @@
+export { jobIdFromPath, jobRegistryFromConfig, loadJobRegistry, } from "./jobRegistry.js";
+export { advisoryLockKey, createEnvAdvisoryLock, createNoopAdvisoryLock, createPgAdvisoryLock, } from "./advisoryLock.js";
+export { createNodeScheduler, withAdvisoryLock, } from "./nodeScheduler.js";
+export { bearerToken, createVercelScheduler, verifyCronAuth, } from "./vercelScheduler.js";
+export { authorizeCron } from "./cronGuard.js";
+export { cronSecretMatches } from "./cronSecret.js";
+export { mergeScheduledJobHandlers, } from "./handlers.js";
+export { createScheduledJobRegistry, cronFromCadenceSeconds, runScheduledJob, scheduledJobsFromContribution, } from "./jobs.js";
+export { createScheduledJobHttpEntry } from "./httpEntry.js";

package/dist/scheduler/jobRegistry.d.ts

@@ -0,0 +1,21 @@
+/** A scheduled job declared by path in the platform-runtime configuration (HTTP-invoked). */
+export interface ScheduledJobDeclaration {
+    /** Stable job id used for advisory locking + job-run accounting (derived from the cron path). */
+    jobId: string;
+    /** Crontab expression (UTC), exactly as authored in the platform-runtime configuration. */
+    schedule: string;
+    /** The app endpoint a self-hosted scheduler invokes (Vercel cron hits this directly). */
+    path: string;
+}
+export interface PlatformRuntimeConfig {
+    crons?: Array<{
+        path: string;
+        schedule: string;
+    }>;
+}
+/** Derive the canonical jobId from a cron path: `/api/cron/nightly-report` -> `nightly-report`. */
+export declare function jobIdFromPath(path: string): string;
+/** Build the job registry from the deployment's platform-runtime configuration file. */
+export declare function loadJobRegistry(configPath: string): ScheduledJobDeclaration[];
+/** Same registry but built from an already-parsed config object (pure; no filesystem). */
+export declare function jobRegistryFromConfig(config: PlatformRuntimeConfig): ScheduledJobDeclaration[];

package/dist/scheduler/jobRegistry.js

@@ -0,0 +1,39 @@
+// Scheduler job registry.
+//
+// SINGLE SOURCE: the cron job list is DERIVED from the deployment's platform-runtime
+// configuration `crons` (the single source from which an adopter may generate a provider
+// manifest), never a hand-copied list. Both scheduler adapters (hosted cron and node-cron) read
+// this same registry so the set of jobs, their schedules, and their endpoint paths can never drift
+// between providers.
+//
+// Pure: reads the configuration file the caller names, or an already-parsed object. No infra
+// imports, no I/O against the network.
+import { readFileSync } from "node:fs";
+/** Derive the canonical jobId from a cron path: `/api/cron/nightly-report` -> `nightly-report`. */
+export function jobIdFromPath(path) {
+    const trimmed = path.replace(/\/+$/, "");
+    const last = trimmed.split("/").filter(Boolean).pop();
+    if (!last) {
+        throw new Error(`scheduler: cannot derive jobId from cron path "${path}"`);
+    }
+    return last;
+}
+/** Build the job registry from the deployment's platform-runtime configuration file. */
+export function loadJobRegistry(configPath) {
+    const raw = readFileSync(configPath, "utf8");
+    const config = JSON.parse(raw);
+    const crons = config.crons ?? [];
+    return crons.map((cron) => ({
+        jobId: jobIdFromPath(cron.path),
+        schedule: cron.schedule,
+        path: cron.path,
+    }));
+}
+/** Same registry but built from an already-parsed config object (pure; no filesystem). */
+export function jobRegistryFromConfig(config) {
+    return (config.crons ?? []).map((cron) => ({
+        jobId: jobIdFromPath(cron.path),
+        schedule: cron.schedule,
+        path: cron.path,
+    }));
+}

package/dist/scheduler/jobs.d.ts

@@ -0,0 +1,48 @@
+import type { JobLeasePort, PlatformJobFinishSummary, PlatformJobInvocation } from "@openlup/core/platform-runtime";
+export interface ScheduledJobContext {
+    /** Who triggered this run; evidence only, never an authorization control. */
+    readonly invocation: PlatformJobInvocation;
+    /** The lease's run id when the job declares a lease. */
+    readonly runId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ScheduledJob {
+    readonly id: string;
+    /** Crontab expression (UTC). */
+    readonly schedule: string;
+    /** Claim a job-run lease of this many seconds before running. */
+    readonly lease?: {
+        readonly seconds: number;
+    };
+    run(context: ScheduledJobContext): Promise<PlatformJobFinishSummary | void> | PlatformJobFinishSummary | void;
+}
+export type ScheduledJobRunResult = {
+    readonly status: "completed";
+    readonly summary: PlatformJobFinishSummary | null;
+} | {
+    readonly status: "skipped";
+    readonly reason: string;
+};
+/** Merge contributed jobs into one registry; refuses a duplicate id or an empty id or schedule. */
+export declare function createScheduledJobRegistry(...contributions: ReadonlyArray<readonly ScheduledJob[]>): readonly ScheduledJob[];
+/**
+ * The cron expression for a fixed cadence: a whole number of minutes that divides an hour, or a
+ * whole number of hours that divides a day. Any other cadence is refused rather than approximated.
+ */
+export declare function cronFromCadenceSeconds(cadenceSeconds: number): string;
+/**
+ * Jobs for a package contribution's cadence schedules; each run passes the invocation through. A
+ * run that reports `{ outcome: "failed" }` instead of throwing fails the job, so neither transport
+ * reports it as completed.
+ */
+export declare function scheduledJobsFromContribution(schedules: ReadonlyArray<{
+    id: string;
+    cadenceSeconds: number;
+    run: (invocation: PlatformJobInvocation) => unknown;
+}>): ScheduledJob[];
+/** Run one job once, under its lease when it declares one. */
+export declare function runScheduledJob(job: ScheduledJob, options: {
+    invocation: PlatformJobInvocation;
+    lease?: JobLeasePort;
+    signal?: AbortSignal;
+}): Promise<ScheduledJobRunResult>;

package/dist/scheduler/jobs.js

@@ -0,0 +1,92 @@
+// Transport-neutral scheduled jobs.
+//
+// A job is `{ id, schedule, lease?, run(context) }`. Domains and packages contribute jobs to a
+// registry; a host runs them on its own timer or through an authenticated HTTP cron entry, and both
+// call the same `run`. The in-process path carries no HTTP secret. When a job declares a lease, the
+// runner claims it through the deployment's job-lease port first and skips the run when another
+// instance holds it; a job that fences its own work (for example the outbox) declares no lease.
+const EMPTY_SUMMARY = { checked: 0, updated: 0, failures: 0, skipped: false };
+/** Merge contributed jobs into one registry; refuses a duplicate id or an empty id or schedule. */
+export function createScheduledJobRegistry(...contributions) {
+    const seen = new Set();
+    const jobs = [];
+    for (const job of contributions.flat()) {
+        if (!job.id?.trim())
+            throw new Error("scheduled_job_id_required");
+        if (!job.schedule?.trim())
+            throw new Error(`scheduled_job_schedule_required:${job.id}`);
+        if (seen.has(job.id))
+            throw new Error(`scheduled_job_duplicate:${job.id}`);
+        seen.add(job.id);
+        jobs.push(job);
+    }
+    return Object.freeze(jobs);
+}
+/**
+ * The cron expression for a fixed cadence: a whole number of minutes that divides an hour, or a
+ * whole number of hours that divides a day. Any other cadence is refused rather than approximated.
+ */
+export function cronFromCadenceSeconds(cadenceSeconds) {
+    if (Number.isInteger(cadenceSeconds) && cadenceSeconds > 0 && cadenceSeconds % 60 === 0) {
+        const minutes = cadenceSeconds / 60;
+        if (minutes < 60 && 60 % minutes === 0)
+            return minutes === 1 ? "* * * * *" : `*/${minutes} * * * *`;
+        if (minutes % 60 === 0) {
+            const hours = minutes / 60;
+            if (hours === 24)
+                return "0 0 * * *";
+            if (hours < 24 && 24 % hours === 0)
+                return hours === 1 ? "0 * * * *" : `0 */${hours} * * *`;
+        }
+    }
+    throw new Error(`scheduled_job_cadence_unsupported:${cadenceSeconds}`);
+}
+/**
+ * Jobs for a package contribution's cadence schedules; each run passes the invocation through. A
+ * run that reports `{ outcome: "failed" }` instead of throwing fails the job, so neither transport
+ * reports it as completed.
+ */
+export function scheduledJobsFromContribution(schedules) {
+    return schedules.map((schedule) => ({
+        id: schedule.id,
+        schedule: cronFromCadenceSeconds(schedule.cadenceSeconds),
+        async run({ invocation }) {
+            const result = await schedule.run(invocation);
+            if (typeof result === "object" && result !== null && result.outcome === "failed") {
+                throw new Error(`scheduled_job_outcome_failed:${schedule.id}`);
+            }
+        },
+    }));
+}
+/** Run one job once, under its lease when it declares one. */
+export async function runScheduledJob(job, options) {
+    if (!job.lease) {
+        const summary = await job.run({ invocation: options.invocation, signal: options.signal });
+        return { status: "completed", summary: summary ?? null };
+    }
+    if (!options.lease)
+        throw new Error(`scheduled_job_lease_port_required:${job.id}`);
+    const claim = await options.lease.claimJobRun(job.id, options.invocation, job.lease.seconds);
+    if (!claim.acquired)
+        return { status: "skipped", reason: claim.reason };
+    if (!claim.runId)
+        throw new Error(`scheduled_job_lease_without_run_id:${job.id}`);
+    let summary;
+    try {
+        summary = await job.run({ invocation: options.invocation, runId: claim.runId, signal: options.signal });
+    }
+    catch (error) {
+        try {
+            await options.lease.finishJobRun(job.id, claim.runId, options.invocation, "failed", { ...EMPTY_SUMMARY, failures: 1 });
+        }
+        catch (finishError) {
+            throw new AggregateError([error, finishError], `scheduled_job_failed_unfinished:${job.id}`);
+        }
+        throw error;
+    }
+    const finished = await options.lease.finishJobRun(job.id, claim.runId, options.invocation, "success", summary ?? EMPTY_SUMMARY);
+    // A refused finish means the lease no longer belongs to this run; its result cannot be recorded.
+    if (!finished)
+        throw new Error(`scheduled_job_finish_refused:${job.id}`);
+    return { status: "completed", summary: summary ?? null };
+}

package/dist/scheduler/nodeScheduler.d.ts

@@ -0,0 +1,42 @@
+import type { SchedulerPort } from "@openlup/core/platform-runtime";
+import type { ScheduledJobDeclaration } from "./jobRegistry.js";
+import { type AdvisoryLock } from "./advisoryLock.js";
+type CronEnv = Record<string, string | undefined> & {
+    CRON_SECRET?: string;
+};
+/** Minimal node-cron surface we depend on (keeps the package optional at type level). */
+export interface CronScheduler {
+    schedule(expression: string, handler: () => void | Promise<void>, options?: {
+        timezone?: string;
+    }): {
+        stop: () => void;
+    };
+}
+export interface NodeSchedulerAdapter extends SchedulerPort {
+    readonly jobs: readonly ScheduledJobDeclaration[];
+    /** Stop all registered node-cron timers (graceful shutdown). */
+    stopAll(): void;
+}
+export interface CreateNodeSchedulerOptions {
+    /** node-cron instance (inject `import("node-cron")` at the host boot site). */
+    cron: CronScheduler;
+    /** Per-job advisory lock; defaults to a no-op (single-instance) — supply pg-backed in prod. */
+    lock?: AdvisoryLock;
+    /** Environment whose CRON_SECRET verifies an invocation. */
+    env: CronEnv;
+    /** The deployment's declared jobs (see `loadJobRegistry`). */
+    jobs: readonly ScheduledJobDeclaration[];
+    /** crontab timezone; jobs are authored in UTC to match Vercel. */
+    timezone?: string;
+    /** Structured error sink for failed job bodies (defaults to console.error). */
+    onError?: (jobId: string, error: unknown) => void;
+}
+/**
+ * Wrap a job body with the per-job advisory lock. Returns a guarded runner that:
+ *  - tries to acquire the lock; if not acquired (another instance is running it) -> skip silently;
+ *  - runs the body; always releases the lock in finally.
+ */
+export declare function withAdvisoryLock(jobId: string, lock: AdvisoryLock, body: () => Promise<void> | void, onError: (jobId: string, error: unknown) => void): () => Promise<void>;
+/** Build the Node scheduler adapter backed by node-cron + per-job advisory locks. */
+export declare function createNodeScheduler(options: CreateNodeSchedulerOptions): NodeSchedulerAdapter;
+export {};

package/dist/scheduler/nodeScheduler.js

@@ -0,0 +1,73 @@
+// Node (self-hosted) SchedulerPort adapter.
+//
+// Unlike a managed host with an adopter-owned declarative cron manifest, a self-hosted Node bundle owns the timers itself.
+// This adapter:
+//   1. Takes its job set from the platform-runtime configuration `crons` (the SAME single source
+//      the managed-host adapter also reads), never a hand-copied list.
+//   2. Registers each job with node-cron (injected lazily so `pg`/`node-cron` aren't required to
+//      typecheck or to run the default vercel-supabase path).
+//   3. Wraps every job body in a PER-JOB advisory lock: multi-instance Node must not
+//      double-run a cron. Only the instance that acquires `pg_try_advisory_lock(<job>)` runs; others
+//      skip. The lock is released in a finally, even if the body throws.
+import { verifyCronAuth } from "./vercelScheduler.js";
+import { createNoopAdvisoryLock } from "./advisoryLock.js";
+/**
+ * Wrap a job body with the per-job advisory lock. Returns a guarded runner that:
+ *  - tries to acquire the lock; if not acquired (another instance is running it) -> skip silently;
+ *  - runs the body; always releases the lock in finally.
+ */
+export function withAdvisoryLock(jobId, lock, body, onError) {
+    return async () => {
+        const acquired = await lock.tryAcquire(jobId);
+        if (!acquired) {
+            // Another instance holds the lock for this minute — skip (no double-run).
+            return;
+        }
+        try {
+            await body();
+        }
+        catch (error) {
+            onError(jobId, error);
+        }
+        finally {
+            await lock.release(jobId);
+        }
+    };
+}
+/** Build the Node scheduler adapter backed by node-cron + per-job advisory locks. */
+export function createNodeScheduler(options) {
+    const env = options.env;
+    const jobs = options.jobs;
+    const lock = options.lock ?? createNoopAdvisoryLock();
+    const onError = options.onError ??
+        ((jobId, error) => {
+            console.error(`[node-scheduler] job "${jobId}" failed`, error);
+        });
+    const scheduleById = new Map(jobs.map((job) => [job.jobId, job.schedule]));
+    const timers = [];
+    return {
+        jobs,
+        register(input) {
+            // Prefer an explicit schedule; fall back to the single-source registry when the caller
+            // omits one (empty string or undefined both fall back).
+            const explicit = input.schedule?.trim();
+            const schedule = explicit && explicit.length > 0 ? explicit : scheduleById.get(input.jobId);
+            if (!schedule) {
+                throw new Error(`node-scheduler: job "${input.jobId}" is not declared in config/platform-runtime.json crons`);
+            }
+            const guarded = withAdvisoryLock(input.jobId, lock, input.handler, onError);
+            const timer = options.cron.schedule(schedule, guarded, { timezone: options.timezone });
+            timers.push({ jobId: input.jobId, stop: timer.stop });
+        },
+        verifyInvocation(req) {
+            // Self-hosted invocations still present the shared CRON_SECRET; reuse the canonical check.
+            return verifyCronAuth(req, env);
+        },
+        stopAll() {
+            for (const timer of timers) {
+                timer.stop();
+            }
+            timers.length = 0;
+        },
+    };
+}