@openlup/platform 0.0.0 → 0.16.0

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;
+        },
+    };
+}

package/dist/scheduler/vercelScheduler.d.ts

@@ -0,0 +1,29 @@
+import type { PlatformHttpRequest, SchedulerPort } from "@openlup/core/platform-runtime";
+import type { ScheduledJobDeclaration } from "./jobRegistry.js";
+type CronEnv = Record<string, string | undefined> & {
+    CRON_SECRET?: string;
+};
+export { bearerToken } from "./cronSecret.js";
+/**
+ * Verify a cron invocation is authentic. Fail-CLOSED:
+ *  - CRON_SECRET unset                         -> false (never authorize when no secret configured)
+ *  - presented Bearer token != CRON_SECRET     -> false
+ *  - presented Bearer token == CRON_SECRET     -> true
+ * This is the single canonical check that replaces the per-handler inline comparisons.
+ */
+export declare function verifyCronAuth(req: PlatformHttpRequest, env: CronEnv): boolean;
+export interface VercelSchedulerAdapter extends SchedulerPort {
+    /** The jobs this scheduler knows about, derived from the platform-runtime single source. */
+    readonly jobs: readonly ScheduledJobDeclaration[];
+}
+/**
+ * Build the Vercel cron scheduler adapter.
+ *
+ * `register()` validates the job is part of the declared registry (so callers can't silently
+ * register a job Vercel will never fire) but does NOT start a timer — Vercel's cron does that.
+ */
+export declare function createVercelScheduler(options: {
+    env: CronEnv;
+    /** The deployment's declared jobs (see `loadJobRegistry`). */
+    jobs: readonly ScheduledJobDeclaration[];
+}): VercelSchedulerAdapter;

package/dist/scheduler/vercelScheduler.js

@@ -0,0 +1,51 @@
+// Vercel cron SchedulerPort adapter.
+//
+// On Vercel, scheduling is declarative: an adopter-owned `crons` manifest generated from the
+// platform-runtime configuration (the same single source as `jobs`) tells Vercel to GET
+// each `/api/cron/*` endpoint on its schedule. So `register()` is a no-op verification step here —
+// the platform owns the timer. What this adapter OWNS is invocation authenticity: every cron
+// endpoint must verify `Authorization: Bearer ${CRON_SECRET}`, fail-closed when the secret is unset.
+//
+// `verifyCronAuth(req, env)` is the reusable form of a bearer check against CRON_SECRET; cron
+// handlers and the Node host call it instead of re-implementing the comparison.
+import { bearerToken, cronSecretMatches } from "./cronSecret.js";
+export { bearerToken } from "./cronSecret.js";
+/**
+ * Verify a cron invocation is authentic. Fail-CLOSED:
+ *  - CRON_SECRET unset                         -> false (never authorize when no secret configured)
+ *  - presented Bearer token != CRON_SECRET     -> false
+ *  - presented Bearer token == CRON_SECRET     -> true
+ * This is the single canonical check that replaces the per-handler inline comparisons.
+ */
+export function verifyCronAuth(req, env) {
+    const expected = env.CRON_SECRET;
+    if (!expected) {
+        return false;
+    }
+    return cronSecretMatches(bearerToken(req), expected);
+}
+/**
+ * Build the Vercel cron scheduler adapter.
+ *
+ * `register()` validates the job is part of the declared registry (so callers can't silently
+ * register a job Vercel will never fire) but does NOT start a timer — Vercel's cron does that.
+ */
+export function createVercelScheduler(options) {
+    const env = options.env;
+    const jobs = options.jobs;
+    const knownIds = new Set(jobs.map((job) => job.jobId));
+    return {
+        jobs,
+        register(input) {
+            // Vercel owns the timer through the adopter manifest. We only guard that the job is declared,
+            // surfacing drift between code and the single-source registry at registration time.
+            if (!knownIds.has(input.jobId)) {
+                throw new Error(`vercel-scheduler: job "${input.jobId}" is not declared in config/platform-runtime.json crons`);
+            }
+            // No-op timer: the handler at the cron path is invoked by Vercel directly.
+        },
+        verifyInvocation(req) {
+            return verifyCronAuth(req, env);
+        },
+    };
+}

package/package.json

@@ -1,7 +1,120 @@
 {
   "name": "@openlup/platform",
-  "version": "0.0.0",
-  "description": "Inert package-name registration placeholder; no platform implementation.",
+  "version": "0.16.0",
+  "private": false,
+  "description": "Runnable server substrate: Node HTTP runtime, BFF dispatch, scheduler, storage, data gateways and bundle composition; development preview.",
   "license": "Apache-2.0",
-  "files": ["README.md"]
+  "type": "module",
+  "engines": {
+    "node": "24.x"
+  },
+  "packageManager": "npm@11.19.0",
+  "sideEffects": false,
+  "files": [
+    "dist/**",
+    "src/**",
+    "sql/**",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "release-gates.json"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "test": "vitest run test",
+    "ci": "npm run build && npm run test && npm run api:check",
+    "api:check": "node --experimental-strip-types ./scripts/api-contract.ts",
+    "test:consumer": "node --experimental-strip-types ./scripts/consumer-proof.ts",
+    "ci:required": "npm run test:consumer",
+    "prepack": "npm run build",
+    "prepublishOnly": "node -e \"throw new Error('PLATFORM_DIRECTORY_PUBLISH_REFUSED')\"",
+    "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update"
+  },
+  "peerDependencies": {
+    "@openlup/core": "0.16.0",
+    "pg": "^8.22.0",
+    "@aws-sdk/client-s3": "^3.1144.0",
+    "@types/pg": "^8.20.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@types/pg": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "exports": {
+    "./http": {
+      "types": "./dist/http/index.d.ts",
+      "import": "./dist/http/index.js",
+      "default": "./dist/http/index.js"
+    },
+    "./bff": {
+      "types": "./dist/bff/index.d.ts",
+      "import": "./dist/bff/index.js",
+      "default": "./dist/bff/index.js"
+    },
+    "./scheduler": {
+      "types": "./dist/scheduler/index.d.ts",
+      "import": "./dist/scheduler/index.js",
+      "default": "./dist/scheduler/index.js"
+    },
+    "./blob": {
+      "types": "./dist/blob/index.d.ts",
+      "import": "./dist/blob/index.js",
+      "default": "./dist/blob/index.js"
+    },
+    "./data": {
+      "types": "./dist/data/index.d.ts",
+      "import": "./dist/data/index.js",
+      "default": "./dist/data/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "import": "./dist/migrations/index.js",
+      "default": "./dist/migrations/index.js"
+    },
+    "./job-ledger": {
+      "types": "./dist/job-ledger/index.d.ts",
+      "import": "./dist/job-ledger/index.js",
+      "default": "./dist/job-ledger/index.js"
+    },
+    "./kernel": {
+      "types": "./dist/kernel/index.d.ts",
+      "import": "./dist/kernel/index.js",
+      "default": "./dist/kernel/index.js"
+    },
+    "./composition": {
+      "types": "./dist/composition/index.d.ts",
+      "import": "./dist/composition/index.js",
+      "default": "./dist/composition/index.js"
+    },
+    "./identity": {
+      "types": "./dist/identity/index.d.ts",
+      "import": "./dist/identity/index.js",
+      "default": "./dist/identity/index.js"
+    },
+    "./identity/contracts": {
+      "types": "./dist/identity/contracts/index.d.ts",
+      "import": "./dist/identity/contracts/index.js",
+      "default": "./dist/identity/contracts/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openlup/openlup.git",
+    "directory": "packages/platform"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "preview"
+  }
 }