@openlup/platform 0.0.0-stage → 0.15.0

package/src/migrations/postgresRunner.ts

@@ -0,0 +1,255 @@
+// Public-platform MigrationRunnerPort for the experimental node-postgres bundle.
+// The manifest and its exact SQL bytes are validated before a pool is created.
+// Applied rows are an exact prefix of that catalog; path, digest or position
+// drift is fatal. Only the caller's catalogue is applied; no other migration
+// history is selected or reachable through a default.
+
+import type { Pool, PoolClient } from "pg";
+import type { MigrationRunnerPort } from "@openlup/core/platform-runtime";
+
+export interface PostgresMigrationRunnerEnv {
+  connectionString: string;
+}
+
+/** One migration file of the deployment's platform catalogue. */
+export type PlatformMigrationFile = { file: string; content: string };
+export type PlatformMigrationManifestEntry = { file: string; sha256: string };
+/** The validated manifest: a baseline, its ordered forwards and the expected object inventory. */
+export type PlatformMigrationManifest = {
+  schemaVersion: 1;
+  baseline: PlatformMigrationManifestEntry;
+  forward: PlatformMigrationManifestEntry[];
+  objectInventorySha256: string;
+};
+
+/**
+ * The deployment's migration catalogue and its validator. `evaluate` returns every refusal for a
+ * manifest against the catalogue files and, when given, the live object-inventory payload.
+ */
+export interface PlatformMigrationSource {
+  readMigrations(root: string): { migrations: PlatformMigrationFile[]; errors: string[] };
+  readManifest(root: string): unknown | null;
+  evaluate(input: {
+    manifest: unknown;
+    migrations: readonly PlatformMigrationFile[];
+    objectInventoryPayload?: string;
+  }): string[];
+}
+
+export interface PostgresMigrationRunnerOptions {
+  /** Name of the PostgreSQL advisory lock that serializes migration sessions. */
+  lockName: string;
+  /** The deployment's migration catalogue. */
+  source: PlatformMigrationSource;
+  /** Serializes the live object inventory that the manifest's `objectInventorySha256` pins. */
+  catalogProjectionPayload: (client: PoolClient) => Promise<string>;
+  /** Catalogue root; defaults to process.cwd(). */
+  root?: string;
+  poolFactory?: (env: PostgresMigrationRunnerEnv) => Pool | Promise<Pool>;
+}
+
+const LEDGER = "public.platform_schema_migrations";
+type PlannedMigration = Readonly<{ catalogPath: string; sha256: string; position: number; sql: string }>;
+type LoadedPlan = Readonly<{
+  manifest: PlatformMigrationManifest;
+  migrations: readonly PlatformMigrationFile[];
+  units: readonly PlannedMigration[];
+}>;
+type LedgerRow = { catalog_path: unknown; sha256: unknown; position: unknown };
+type LedgerExistenceRow = { ledger_exists: unknown };
+type AdvisoryUnlockRow = { unlocked: unknown };
+const ACQUIRE_MIGRATION_LOCK = "SELECT pg_advisory_lock(hashtextextended($1, 0))";
+const RELEASE_MIGRATION_LOCK = "SELECT pg_advisory_unlock(hashtextextended($1, 0)) AS unlocked";
+
+export function createPostgresMigrationRunner(
+  env: PostgresMigrationRunnerEnv,
+  options: PostgresMigrationRunnerOptions,
+): MigrationRunnerPort {
+  const root = options.root ?? process.cwd();
+  let pool: Pool | null = null;
+
+  async function getPool(): Promise<Pool> {
+    if (pool) return pool;
+    const factory = options.poolFactory ?? defaultPoolFactory;
+    pool = await factory(env);
+    return pool;
+  }
+
+  return {
+    async status(): Promise<{ pending: string[]; applied: string[] }> {
+      assertConnectionString(env);
+      const plan = loadPlan(root, options.source);
+      return withMigrationSession(await getPool(), options.lockName, async (client) => {
+        const applied = await readAppliedPrefix(client, plan.units);
+        if (applied.length === plan.units.length) await assertObjectInventory(client, plan, options);
+        return {
+          pending: plan.units.slice(applied.length).map((unit) => unit.catalogPath),
+          applied: applied.map((unit) => unit.catalogPath),
+        };
+      });
+    },
+
+    async apply(opts?: { dryRun?: boolean }): Promise<{ applied: string[] }> {
+      assertConnectionString(env);
+      const plan = loadPlan(root, options.source);
+      return withMigrationSession(await getPool(), options.lockName, async (client) => {
+        const already = await readAppliedPrefix(client, plan.units);
+        const pending = plan.units.slice(already.length);
+        if (opts?.dryRun) {
+          if (pending.length === 0) await assertObjectInventory(client, plan, options);
+          return { applied: pending.map((unit) => unit.catalogPath) };
+        }
+        const appliedNow: string[] = [];
+        for (const unit of pending) {
+          await client.query("BEGIN");
+          try {
+            await client.query(unit.sql);
+            await client.query(
+              `INSERT INTO ${LEDGER} (catalog_path, sha256, position) VALUES ($1, $2, $3)`,
+              [unit.catalogPath, unit.sha256, unit.position],
+            );
+            await client.query("COMMIT");
+            appliedNow.push(unit.catalogPath);
+          } catch (error) {
+            await client.query("ROLLBACK").catch(() => {});
+            throw new Error(`platform migration ${unit.catalogPath} failed: ${errorMessage(error)}`);
+          }
+        }
+        const complete = await readAppliedPrefix(client, plan.units);
+        if (complete.length !== plan.units.length) throw new Error("platform migration ledger is incomplete after apply");
+        await assertObjectInventory(client, plan, options);
+        return { applied: appliedNow };
+      });
+    },
+  };
+}
+
+async function withMigrationSession<T>(
+  pool: Pool,
+  lockName: string,
+  operation: (client: PoolClient) => Promise<T>,
+): Promise<T> {
+  const client = await pool.connect();
+  let locked = false;
+  let failed = false;
+  let operationFailure: unknown;
+  let result!: T;
+  try {
+    await client.query(ACQUIRE_MIGRATION_LOCK, [lockName]);
+    locked = true;
+    result = await operation(client);
+  } catch (error) {
+    failed = true;
+    operationFailure = error;
+  }
+
+  let unlockFailure: unknown;
+  if (locked) {
+    try {
+      const unlocked = await client.query<AdvisoryUnlockRow>(RELEASE_MIGRATION_LOCK, [lockName]);
+      if (unlocked.rows[0]?.unlocked !== true) throw new Error("PostgreSQL did not release the advisory lock");
+    } catch (error) {
+      unlockFailure = error;
+    }
+  }
+  client.release(unlockFailure !== undefined || (failed && !locked));
+
+  if (failed) {
+    if (unlockFailure !== undefined) {
+      throw new Error(
+        `platform migration operation failed: ${errorMessage(operationFailure)}; advisory lock release failed: ${errorMessage(unlockFailure)}`,
+      );
+    }
+    throw operationFailure;
+  }
+  if (unlockFailure !== undefined) {
+    throw new Error(`platform migration advisory lock release failed: ${errorMessage(unlockFailure)}`);
+  }
+  return result;
+}
+
+function assertConnectionString(env: PostgresMigrationRunnerEnv): void {
+  if (env.connectionString.trim() === "") {
+    throw new Error("DATABASE_URL is required for node-postgres migrations");
+  }
+}
+
+function loadPlan(root: string, source: PlatformMigrationSource): LoadedPlan {
+  const catalog = source.readMigrations(root);
+  const rawManifest = source.readManifest(root);
+  const errors = [...catalog.errors];
+  if (rawManifest === null) errors.push("platform migration manifest is missing");
+  else errors.push(...source.evaluate({ manifest: rawManifest, migrations: catalog.migrations }));
+  if (errors.length > 0) throw new Error(`platform migration catalog rejected: ${errors.join("; ")}`);
+
+  const manifest = rawManifest as PlatformMigrationManifest;
+  const byPath = new Map(catalog.migrations.map((migration) => [migration.file, migration.content]));
+  const entries = [manifest.baseline, ...manifest.forward];
+  const units = entries.map((entry, position) => Object.freeze({
+    catalogPath: entry.file,
+    sha256: entry.sha256,
+    position,
+    sql: byPath.get(entry.file)!,
+  }));
+  return Object.freeze({ manifest, migrations: catalog.migrations, units: Object.freeze(units) });
+}
+
+async function readAppliedPrefix(client: PoolClient, units: readonly PlannedMigration[]): Promise<readonly PlannedMigration[]> {
+  const exists = await client.query<LedgerExistenceRow>(
+    "SELECT to_regclass($1) IS NOT NULL AS ledger_exists",
+    [LEDGER],
+  );
+  if (exists.rows[0]?.ledger_exists !== true) return [];
+  const result = await client.query<LedgerRow>(
+    `SELECT catalog_path, sha256, position FROM ${LEDGER} ORDER BY position`,
+  );
+  if (result.rows.length > units.length) throw new Error("platform migration ledger contains an extra row");
+  for (let index = 0; index < result.rows.length; index += 1) {
+    const row = result.rows[index]!;
+    const unit = units[index]!;
+    if (row.catalog_path !== unit.catalogPath || row.sha256 !== unit.sha256 || row.position !== unit.position) {
+      throw new Error(`platform migration ledger is not the exact manifest prefix at position ${index}`);
+    }
+  }
+  return units.slice(0, result.rows.length);
+}
+
+async function assertObjectInventory(
+  client: PoolClient,
+  plan: LoadedPlan,
+  options: PostgresMigrationRunnerOptions,
+): Promise<void> {
+  const payload = await options.catalogProjectionPayload(client);
+  const errors = options.source.evaluate({
+    manifest: plan.manifest,
+    migrations: plan.migrations,
+    objectInventoryPayload: payload,
+  });
+  if (errors.length > 0) throw new Error(`platform migration inventory rejected: ${errors.join("; ")}`);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function defaultPoolFactory(env: PostgresMigrationRunnerEnv): Promise<Pool> {
+  const pg = await import("pg").catch(peerMissing);
+  const PoolCtor = (pg.default?.Pool ?? pg.Pool) as typeof import("pg").Pool;
+  return new PoolCtor({ connectionString: env.connectionString });
+}
+
+export function resolvePostgresMigrationRunnerEnv(
+  env: Record<string, string | undefined>,
+): PostgresMigrationRunnerEnv {
+  return { connectionString: env.DATABASE_URL ?? "" };
+}
+
+/** Translate only absence of this optional peer; preserve broken SDKs and other failures. */
+function peerMissing(cause: unknown): never {
+  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 migration runner; install it alongside @openlup/platform", { cause });
+  }
+  throw cause;
+}

package/src/scheduler/advisoryLock.ts

@@ -0,0 +1,145 @@
+// 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.
+
+/** 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 function advisoryLockKey(jobId: string): number {
+  // 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: AdvisoryLockQuerier,
+  closeClient: () => Promise<void> = () => client.end?.() ?? Promise.resolve(),
+): AdvisoryLock {
+  let closePromise: Promise<void> | null = null;
+  return {
+    durability: "cluster",
+    async tryAcquire(jobId) {
+      const key = advisoryLockKey(jobId);
+      const { rows } = await client.query<{ locked: boolean }>(
+        "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: Record<string, string | undefined>,
+  connect: (connectionString: string) => Promise<AdvisoryLockQuerier> = connectDedicatedClient,
+): AdvisoryLock | null {
+  const connectionString = env.DATABASE_URL?.trim() ?? "";
+  if (connectionString === "") return null;
+  let pending: Promise<AdvisoryLockQuerier> | null = null;
+  let closed = false;
+  let closePromise: Promise<void> | null = null;
+  const querier: AdvisoryLockQuerier = {
+    async query<T = unknown>(text: string, values?: unknown[]): Promise<{ rows: T[] }> {
+      if (closed) throw new Error("advisory_lock_closed");
+      pending ??= connect(connectionString);
+      const client = await pending;
+      return client.query<T>(text, values);
+    },
+  };
+  return createPgAdvisoryLock(querier, () => {
+    closed = true;
+    closePromise ??= pending?.then((client) => client.end?.() ?? undefined) ?? Promise.resolve();
+    return closePromise;
+  });
+}
+
+async function connectDedicatedClient(connectionString: string): Promise<AdvisoryLockQuerier> {
+  const pg = await import("pg").catch(peerMissing);
+  const ClientCtor = (pg.default?.Client ?? pg.Client) as typeof import("pg").Client;
+  const client = new ClientCtor({ connectionString });
+  await client.connect();
+  return client as unknown as AdvisoryLockQuerier;
+}
+
+/** Lock that always grants (single-instance / tests). Never use in multi-instance Node deploys. */
+export function createNoopAdvisoryLock(): AdvisoryLock {
+  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: unknown): never {
+  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/src/scheduler/cronGuard.ts

@@ -0,0 +1,30 @@
+import type { HttpRequest } from "../http/index.js";
+import { bearerToken, cronSecretMatches } from "./cronSecret.js";
+
+export { bearerToken };
+
+export interface CronAuthDenied {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+// 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: HttpRequest,
+  env: { CRON_SECRET?: string },
+): CronAuthDenied | null {
+  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/src/scheduler/cronSecret.ts

@@ -0,0 +1,26 @@
+// 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";
+
+import type { PlatformHttpRequest } from "@openlup/core/platform-runtime";
+
+/** Extract the Bearer token from a request Authorization header (case-insensitive). */
+export function bearerToken(req: PlatformHttpRequest): string | null {
+  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: string | null, expected: string): boolean {
+  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/src/scheduler/handlers.ts

@@ -0,0 +1,24 @@
+// 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.
+
+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 function mergeScheduledJobHandlers(
+  ...registries: ReadonlyArray<ScheduledJobHandlerRegistry | undefined>
+): ScheduledJobHandlerRegistry {
+  return Object.assign({}, ...registries.filter((registry) => registry !== undefined));
+}

package/src/scheduler/httpEntry.ts

@@ -0,0 +1,49 @@
+// 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 type { JobLeasePort } from "@openlup/core/platform-runtime";
+
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { authorizeCron } from "./cronGuard.js";
+import { runScheduledJob, 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 function createScheduledJobHttpEntry(
+  job: ScheduledJob,
+  options: ScheduledJobHttpEntryOptions,
+): (req: HttpRequest, res: HttpResponse) => Promise<void> {
+  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/src/scheduler/index.ts

@@ -0,0 +1,47 @@
+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/src/scheduler/jobRegistry.ts

@@ -0,0 +1,57 @@
+// 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";
+
+/** 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 function jobIdFromPath(path: string): string {
+  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: string): ScheduledJobDeclaration[] {
+  const raw = readFileSync(configPath, "utf8");
+  const config = JSON.parse(raw) as PlatformRuntimeConfig;
+  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: PlatformRuntimeConfig): ScheduledJobDeclaration[] {
+  return (config.crons ?? []).map((cron) => ({
+    jobId: jobIdFromPath(cron.path),
+    schedule: cron.schedule,
+    path: cron.path,
+  }));
+}