@openlup/platform 0.0.0 → 0.16.0

package/dist/blob/supabase.js

@@ -0,0 +1,59 @@
+// Supabase Storage adapter for the platform-runtime BlobStoragePort.
+//
+// Wraps `client.storage.from(bucket)` 1:1 with the existing application storage usage:
+// upsert uploads, public-URL resolution via getPublicUrl, and bucket-scoped list/remove. Keys
+// are bucket-relative paths. Behavior matches the current inline storage calls so the default
+// vercel-supabase bundle (which uses this for storage buckets) is byte-identical.
+export function createSupabaseBlobStorage(client, bucket, options = {}) {
+    const from = () => client.storage.from(bucket);
+    const defaultContentType = options.defaultContentType ?? "application/octet-stream";
+    return {
+        urlFor(key) {
+            return from().getPublicUrl(key).data.publicUrl;
+        },
+        async upload(key, data, opts) {
+            const bucketApi = from();
+            const result = await bucketApi.upload(key, data, {
+                contentType: opts?.contentType ?? defaultContentType,
+                upsert: true,
+            });
+            if (result.error) {
+                throw new Error(`supabase_storage_upload_failed:${result.error.message ?? "unknown"}`);
+            }
+            return { url: bucketApi.getPublicUrl(key).data.publicUrl, pathname: key };
+        },
+        async exists(key) {
+            // Supabase has no head(); list the parent folder and match the leaf name.
+            const slash = key.lastIndexOf("/");
+            const folder = slash >= 0 ? key.slice(0, slash) : "";
+            const leaf = slash >= 0 ? key.slice(slash + 1) : key;
+            const result = await from().list(folder || undefined);
+            if (result.error)
+                return false;
+            return (result.data ?? []).some((entry) => entry.name === leaf);
+        },
+        async delete(keyOrUrl) {
+            const result = await from().remove([toBucketKey(keyOrUrl, bucket)]);
+            if (result.error) {
+                throw new Error(`supabase_storage_remove_failed:${result.error.message ?? "unknown"}`);
+            }
+        },
+        async list(prefix) {
+            const result = await from().list(prefix);
+            if (result.error) {
+                throw new Error(`supabase_storage_list_failed:${result.error.message ?? "unknown"}`);
+            }
+            const base = prefix ? `${prefix.replace(/\/$/, "")}/` : "";
+            return { keys: (result.data ?? []).map((entry) => `${base}${entry.name}`) };
+        },
+    };
+}
+// Accept either a bucket-relative key or a full public URL; strip everything up to and
+// including the bucket segment so remove() always gets a bucket-relative path.
+function toBucketKey(keyOrUrl, bucket) {
+    const marker = `/storage/v1/object/public/${bucket}/`;
+    const idx = keyOrUrl.indexOf(marker);
+    if (idx >= 0)
+        return keyOrUrl.slice(idx + marker.length);
+    return keyOrUrl;
+}

package/dist/blob/vercel.d.ts

@@ -0,0 +1,63 @@
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+/**
+ * The `@vercel/blob` functions this adapter calls, supplied by the application (pass the module
+ * itself). The SDK reads its own credentials from the environment, as before.
+ */
+export interface VercelBlobSdk {
+    put(pathname: string, body: Buffer, options: {
+        access: "public";
+        contentType: string;
+        addRandomSuffix: boolean;
+        cacheControlMaxAge: number;
+    }): Promise<{
+        url: string;
+        pathname: string;
+    }>;
+    head(url: string): Promise<{
+        url?: string;
+    } | null | undefined>;
+    del(url: string): Promise<unknown>;
+    list(options: {
+        prefix?: string;
+    }): Promise<{
+        blobs: Array<{
+            pathname: string;
+            url: string;
+            uploadedAt: Date;
+        }>;
+    }>;
+}
+export interface VercelBlobAdapterOptions {
+    /** The `@vercel/blob` module. */
+    sdk: VercelBlobSdk;
+    /** Environment whose BLOB_READ_WRITE_TOKEN is read at each call when `token` is absent. */
+    env: Record<string, string | undefined>;
+    /**
+     * Explicit token for deriving the public store URL (`urlFor`, `exists`); takes precedence over
+     * `env`. Upload, list and delete use the credentials the injected SDK reads itself, so `env` and
+     * `token` must name the same store as the SDK's own configuration.
+     */
+    token?: string;
+    /** Default content-type when an upload omits one (image/png when absent). */
+    defaultContentType?: string;
+    cacheControlMaxAge?: number;
+}
+/** A listed blob plus the Vercel-specific metadata (uploadedAt) used by TTL cleanup. */
+export interface VercelBlobEntry {
+    pathname: string;
+    url: string;
+    uploadedAt: Date;
+}
+/**
+ * Vercel-specific extension over the neutral BlobStoragePort.list(): also surfaces uploadedAt
+ * so the TTL cron can prune by age. Not part of the port contract (other backends carry no
+ * equivalent metadata); consumers needing it depend on this adapter shape explicitly.
+ */
+export interface VercelBlobStorage extends BlobStoragePort {
+    listDetailed(prefix?: string): Promise<{
+        blobs: VercelBlobEntry[];
+    }>;
+}
+/** Parse the public store id from a `vercel_blob_rw_{storeId}_{secret}` token. */
+export declare function parseVercelStoreId(token: string | undefined): string;
+export declare function createVercelBlobStorage(options: VercelBlobAdapterOptions): VercelBlobStorage;

package/dist/blob/vercel.js

@@ -0,0 +1,69 @@
+// Vercel Blob adapter for the platform-runtime BlobStoragePort.
+//
+// Wraps the CURRENT `@vercel/blob` behavior 1:1 so the default vercel-supabase bundle is
+// byte-identical: public access, image content-type pass-through, no random suffix, the same
+// 30-day cache-control, O(1) head() existence checks, and the deterministic public CDN URL
+// derived from the store id encoded in BLOB_READ_WRITE_TOKEN. Operates on FULL keys
+// (pathnames); any key prefix or suffix stays in the consuming facade.
+const DEFAULT_CACHE_MAX_AGE_SECONDS = 60 * 60 * 24 * 30; // 30 days
+/** Parse the public store id from a `vercel_blob_rw_{storeId}_{secret}` token. */
+export function parseVercelStoreId(token) {
+    if (!token)
+        throw new Error("BLOB_READ_WRITE_TOKEN missing");
+    const m = token.match(/^vercel_blob_rw_([a-zA-Z0-9]+)_/);
+    if (!m)
+        throw new Error("invalid BLOB_READ_WRITE_TOKEN format");
+    return m[1].toLowerCase();
+}
+export function createVercelBlobStorage(options) {
+    const resolveToken = () => options.token ?? options.env.BLOB_READ_WRITE_TOKEN;
+    const cacheControlMaxAge = options.cacheControlMaxAge ?? DEFAULT_CACHE_MAX_AGE_SECONDS;
+    const defaultContentType = options.defaultContentType ?? "image/png";
+    return {
+        urlFor(key) {
+            const storeId = parseVercelStoreId(resolveToken());
+            return `https://${storeId}.public.blob.vercel-storage.com/${key}`;
+        },
+        async upload(key, data, opts) {
+            const result = await options.sdk.put(key, toUploadBody(data), {
+                access: "public",
+                contentType: opts?.contentType ?? defaultContentType,
+                addRandomSuffix: false,
+                cacheControlMaxAge,
+            });
+            return { url: result.url, pathname: result.pathname };
+        },
+        async exists(key) {
+            try {
+                const result = await options.sdk.head(this.urlFor(key));
+                return Boolean(result?.url);
+            }
+            catch {
+                return false;
+            }
+        },
+        async delete(keyOrUrl) {
+            // del() accepts a full blob URL or pathname; pass through unchanged.
+            await options.sdk.del(keyOrUrl);
+        },
+        async list(prefix) {
+            const result = await options.sdk.list(prefix ? { prefix } : {});
+            return { keys: result.blobs.map((blob) => blob.pathname) };
+        },
+        async listDetailed(prefix) {
+            const result = await options.sdk.list(prefix ? { prefix } : {});
+            return {
+                blobs: result.blobs.map((blob) => ({
+                    pathname: blob.pathname,
+                    url: blob.url,
+                    uploadedAt: blob.uploadedAt,
+                })),
+            };
+        },
+    };
+}
+// @vercel/blob's put() accepts string | Buffer | Blob | ReadableStream etc. Buffer is a
+// Uint8Array subclass, so both port input shapes pass straight through.
+function toUploadBody(data) {
+    return Buffer.isBuffer(data) ? data : Buffer.from(data);
+}

package/dist/composition/composeBundle.d.ts

@@ -0,0 +1,47 @@
+import type { AnalyticsPort, BlobStoragePort, DataGatewayPort, HttpRuntimePort, MigrationRunnerPort, SchedulerPort, TransactionalRuntimePort } from "@openlup/core/platform-runtime";
+import { type PlatformBundleDescriptor, type PlatformBundleId } from "../kernel/index.js";
+type Env = Record<string, string | undefined>;
+export interface PlatformBundlePorts {
+    http: HttpRuntimePort | null;
+    scheduler: SchedulerPort | null;
+    blob: BlobStoragePort | null;
+    data: DataGatewayPort | null;
+    migrations: MigrationRunnerPort | null;
+    analytics: AnalyticsPort | null;
+    transactional: TransactionalRuntimePort | null;
+}
+export interface PlatformBundle {
+    id: PlatformBundleId;
+    descriptor: PlatformBundleDescriptor;
+    ports: PlatformBundlePorts;
+}
+/**
+ * One binder per port slot. Each receives the slot's capability and the environment; the blob
+ * binder receives the selected blob capability (`PLATFORM_BLOB`, else the bundle's own), and the
+ * transactional binder also receives the bundle's data capability.
+ */
+export interface PlatformBundleBinders {
+    /**
+     * The supabase-js `createClient` used by the default Supabase Storage blob binder. Declared
+     * structurally here so the composition entry's declarations reference no data-module type.
+     */
+    createSupabaseClient?: (url: string, key: string, options?: {
+        auth?: {
+            persistSession?: boolean;
+            autoRefreshToken?: boolean;
+        };
+    }) => unknown;
+    http?: (capability: string, env: Env) => HttpRuntimePort | null;
+    scheduler?: (capability: string, env: Env) => SchedulerPort | null;
+    /** Defaults to `bindBlobPort`. */
+    blob?: (capability: string, env: Env) => BlobStoragePort | null;
+    /** For example `createDataBindings(...).bindDataPort`. */
+    data?: (capability: string, env: Env) => DataGatewayPort | null;
+    migrations?: (capability: string, env: Env) => MigrationRunnerPort | null;
+    analytics?: (capability: string, env: Env) => AnalyticsPort | null;
+    transactional?: (capability: string, dataCapability: string, env: Env) => TransactionalRuntimePort | null;
+}
+export type ComposeBundle = (env: Env) => PlatformBundle;
+/** Build the deployment's composition root from its port binders. */
+export declare function createBundleComposer(binders?: PlatformBundleBinders): ComposeBundle;
+export {};

package/dist/composition/composeBundle.js

@@ -0,0 +1,45 @@
+// Platform-runtime bundle composition.
+//
+// Resolves the active bundle from the environment and returns its descriptor and port table. Each
+// port slot is filled by one binder, keyed by the bundle's declared capability for that slot. A
+// slot without a binder, or whose binder declines the capability, stays null: callers treat an
+// unbound port as "use the deployment's direct path", never as a silent substitute.
+//
+// The package supplies a default binder for the blob slot. The HTTP, scheduler, data, migrations,
+// analytics and transactional slots carry deployment values (route tables, jobs, the database
+// client factory, migration catalogue, analytics provider, delivery runtime), so the deployment
+// supplies them; `createDataBindings` builds the data binder.
+import { bindBlobPort } from "../blob/index.js";
+import { createServiceClient, readSupabaseDataGatewayEnv } from "../data/index.js";
+import { getBundleDescriptor, resolveBlobCapability, resolveBundleId, } from "../kernel/index.js";
+/** Build the deployment's composition root from its port binders. */
+export function createBundleComposer(binders = {}) {
+    const bindBlob = binders.blob ?? ((capability, env) => {
+        const settings = capability === "supabase" ? readSupabaseDataGatewayEnv({
+            ...env,
+            SUPABASE_URL: env.SUPABASE_URL?.trim() || env.VITE_SUPABASE_URL?.trim(),
+        }) : null;
+        const createSupabaseClient = binders.createSupabaseClient;
+        return bindBlobPort(capability, env, {
+            supabaseStorageClient: settings && createSupabaseClient
+                ? () => createServiceClient(settings, createSupabaseClient)
+                : undefined,
+        });
+    });
+    return function composeBundle(env) {
+        const id = resolveBundleId(env);
+        const descriptor = getBundleDescriptor(id);
+        const { capabilities } = descriptor;
+        const ports = {
+            http: binders.http?.(capabilities.http, env) ?? null,
+            scheduler: null,
+            blob: bindBlob(resolveBlobCapability(descriptor, env), env),
+            data: binders.data?.(capabilities.data, env) ?? null,
+            migrations: binders.migrations?.(capabilities.migrations, env) ?? null,
+            analytics: binders.analytics?.(capabilities.analytics, env) ?? null,
+            transactional: binders.transactional?.(capabilities.transactional, capabilities.data, env) ?? null,
+        };
+        ports.scheduler = binders.scheduler?.(capabilities.scheduler, env) ?? null;
+        return { id, descriptor, ports };
+    };
+}

package/dist/composition/httpBinding.d.ts

@@ -0,0 +1,8 @@
+import type { HttpRuntimePort } from "@openlup/core/platform-runtime";
+import type { EntrypointLoader } from "../http/index.js";
+import { type NodeHttpRuntimeOptions } from "../http/index.js";
+import type { ScheduledJobDeclaration } from "../scheduler/index.js";
+/** Mount only the scheduled routes declared by the job registry. */
+export declare function createScheduledEntrypointResolver(jobs: readonly ScheduledJobDeclaration[], load: (jobId: string) => ReturnType<EntrypointLoader>): (jobId: string) => EntrypointLoader | null;
+/** Build the http port for a bundle capability ("node" => Node runtime; else null). */
+export declare function bindNodeHttpPort(capability: string, options: () => NodeHttpRuntimeOptions): HttpRuntimePort | null;

package/dist/composition/httpBinding.js

@@ -0,0 +1,18 @@
+// HTTP slot binding for the Node runtime.
+//
+// Only a bundle whose `http` capability is "node" receives a Node runtime; a hosted bundle keeps
+// `http: null` and serves its route table through its own function entrypoint. The scheduled-route
+// resolver mounts exactly the jobs the deployment declared, so an undeclared `/api/cron/<id>`
+// path stays a 404 and a declared job without an entrypoint fails visibly when called.
+import { createNodeHttpRuntime } from "../http/index.js";
+/** Mount only the scheduled routes declared by the job registry. */
+export function createScheduledEntrypointResolver(jobs, load) {
+    const declared = new Set(jobs.map((job) => job.jobId));
+    return (jobId) => declared.has(jobId) ? () => load(jobId) : null;
+}
+/** Build the http port for a bundle capability ("node" => Node runtime; else null). */
+export function bindNodeHttpPort(capability, options) {
+    if (capability !== "node")
+        return null;
+    return createNodeHttpRuntime(options());
+}

package/dist/composition/index.d.ts

@@ -0,0 +1,3 @@
+export { createBundleComposer, type ComposeBundle, type PlatformBundle, type PlatformBundleBinders, type PlatformBundlePorts, } from "./composeBundle.js";
+export { bindNodeHttpPort, createScheduledEntrypointResolver } from "./httpBinding.js";
+export { createNodeHost, type NodeHost, type NodeHostAdmission, type NodeHostDependencies, type NodeSchedulerProfile, type ServeNodeOptions, type ServeNodeResult, } from "./nodeHost.js";

package/dist/composition/index.js

@@ -0,0 +1,3 @@
+export { createBundleComposer, } from "./composeBundle.js";
+export { bindNodeHttpPort, createScheduledEntrypointResolver } from "./httpBinding.js";
+export { createNodeHost, } from "./nodeHost.js";

package/dist/composition/nodeHost.d.ts

@@ -0,0 +1,103 @@
+import type { HttpRuntimePort, JobLeasePort } from "@openlup/core/platform-runtime";
+import type { StaticAssetReader } from "../http/index.js";
+import { type AdvisoryLock, type CronScheduler, type ScheduledJob, type ScheduledJobDeclaration, type ScheduledJobHandler, type ScheduledJobHandlerRegistry } from "../scheduler/index.js";
+import type { ComposeBundle, PlatformBundlePorts } from "./composeBundle.js";
+type Env = Record<string, string | undefined>;
+/** What the host hands its admission check before it serves or schedules anything. */
+export interface NodeHostAdmission {
+    kind: "node";
+    nodeJobHandlers: ScheduledJobHandlerRegistry;
+    /** The path-declared jobs this process will time; empty when it does not run the scheduler. */
+    nodeJobs: readonly ScheduledJobDeclaration[];
+    /** The registry jobs this process will run directly; empty when it does not run the scheduler. */
+    scheduledJobs: readonly ScheduledJob[];
+}
+export interface NodeHostDependencies {
+    /** The deployment's composition root (see `createBundleComposer`). */
+    composeBundle: ComposeBundle;
+    /**
+     * Build the HTTP runtime this host serves, for the declared jobs and its static reader. The
+     * bundle's `http` port only proves that the bundle is a Node bundle at readiness time.
+     */
+    createHttpRuntime: (input: {
+        schedulerJobs: readonly ScheduledJobDeclaration[];
+        staticReader: StaticAssetReader;
+        /** The composed ports (blob storage, data gateway and the rest) for routes to use. */
+        ports: PlatformBundlePorts;
+    }) => HttpRuntimePort;
+    /** The deployment's declared jobs, used when the caller passes none. */
+    loadSchedulerJobs: () => readonly ScheduledJobDeclaration[];
+    /** Transport-neutral jobs contributed to the registry; run in-process with no HTTP secret. */
+    scheduledJobs?: (env: Env, ports: PlatformBundlePorts) => readonly ScheduledJob[];
+    /** The job-lease port for registry jobs that declare a lease. */
+    jobLease?: (env: Env) => JobLeasePort;
+    /** Direct bindings the deployment and its domains contribute; caller overrides win. */
+    scheduledJobHandlers?: (env: Env) => ScheduledJobHandlerRegistry;
+    /** Runs first, before readiness (for example, process-wide configuration checks). */
+    prepareHost?: (env: Env) => void;
+    /** Admits the host before it serves or schedules; a rejection stops the boot. */
+    admitHost?: (env: Env, admission: NodeHostAdmission) => Promise<void>;
+    /** Operational log sink (defaults to console.log). */
+    log?: (message: string) => void;
+}
+/**
+ * A deployment's scheduler profile: a fenced projection of the declared jobs with its own
+ * validation, applied at the host's boot boundaries. Each hook may throw to stop the boot.
+ */
+export interface NodeSchedulerProfile {
+    /** Replaces the declared jobs with this profile's projection. Runs after any migration replay. */
+    projectJobs(env: Env, jobs: readonly ScheduledJobDeclaration[]): readonly ScheduledJobDeclaration[];
+    /** Direct bindings the profile adds; they replace the deployment's and the caller's for a job. */
+    handlers?(env: Env): ScheduledJobHandlerRegistry;
+    /** Runs once the advisory lock is resolved and before any job is registered. */
+    validateSchedule?(input: {
+        lock: AdvisoryLock | undefined;
+        jobs: readonly ScheduledJobDeclaration[];
+        overrides: ScheduledJobHandlerRegistry | undefined;
+    }): void;
+    /**
+     * Runs for each job, in order, immediately before it is registered, with its direct binding if
+     * any. A refusal stops the boot; jobs registered before it keep their timers, as the boot fails.
+     */
+    validateJob?(job: ScheduledJobDeclaration, directHandler: ScheduledJobHandler | undefined): void;
+}
+export interface ServeNodeOptions {
+    /** The process environment of this host. */
+    env: Env;
+    /** dist/ root for static serving (defaults to <cwd>/dist). */
+    distDir?: string;
+    /** node-cron instance; injected so the dependency stays optional for typecheck and tests. */
+    cron?: CronScheduler;
+    /** Direct bindings added over the deployment's own for this boot. */
+    scheduledJobHandlers?: ScheduledJobHandlerRegistry;
+    /** Explicit scheduler projection; production uses the deployment's job registry. */
+    schedulerJobs?: readonly ScheduledJobDeclaration[];
+    /** Optional scheduler profile applied to the declared jobs (see `NodeSchedulerProfile`). */
+    schedulerProfile?: NodeSchedulerProfile;
+    /**
+     * Per-job cluster mutex. Defaults to the one the environment's connection string describes, so a
+     * host that runs more than one instance stops executing every timer once per instance.
+     */
+    advisoryLock?: AdvisoryLock;
+    /** Skip binding the network listener (unit tests build the runtime without opening a socket). */
+    listen?: boolean;
+    port?: number;
+    host?: string;
+}
+export interface ServeNodeResult {
+    bundleId: string;
+    httpRuntime: HttpRuntimePort;
+    registeredJobs: string[];
+    /** Stop timers and the local listener after a host signal; safe to call repeatedly. */
+    stop(): Promise<void>;
+}
+export interface NodeHost {
+    /** Readiness gate: the active bundle's descriptor decides, and the bundle must bind a Node runtime. */
+    assertBundleReady(env: Env): {
+        bundleId: string;
+    };
+    /** Build (and optionally start) the Node host. */
+    serveNode(options: ServeNodeOptions): Promise<ServeNodeResult>;
+}
+export declare function createNodeHost(deps: NodeHostDependencies): NodeHost;
+export {};

package/dist/composition/nodeHost.js

@@ -0,0 +1,145 @@
+// Node (self-hosted) host bootstrap.
+//
+// Boots a Node platform bundle: prepare the host, check the bundle's readiness, apply the
+// node-postgres migration replay before serving, admit the host, build the HTTP runtime, register
+// the declared jobs with node-cron, and listen. A bundle whose migrations are managed outside the
+// process (node-supabase) is expected to be migrated before the container starts.
+//
+// The deployment supplies its composition root, HTTP runtime options, job registry, direct job
+// bindings and host admission; this module owns the order and the failure modes.
+import { resolve } from "node:path";
+import { createDistStaticReader } from "../http/index.js";
+import { createEnvAdvisoryLock, createNodeScheduler, mergeScheduledJobHandlers, runScheduledJob, } from "../scheduler/index.js";
+export function createNodeHost(deps) {
+    const log = deps.log ?? ((message) => console.log(message));
+    function assertBundleReady(env) {
+        const bundle = deps.composeBundle(env);
+        const readiness = bundle.descriptor.readReadiness(env);
+        if (!readiness.ok) {
+            throw new Error(`[serve.node] bundle "${bundle.id}" not ready: ${readiness.error}`);
+        }
+        if (!bundle.ports.http) {
+            throw new Error(`[serve.node] bundle "${bundle.id}" has no http runtime (expected node bundle)`);
+        }
+        return { bundleId: bundle.id };
+    }
+    async function serveNode(options) {
+        const env = options.env;
+        deps.prepareHost?.(env);
+        const { bundleId } = assertBundleReady(env);
+        // Deploy parity (migrate -> health -> serve): the node-postgres bundle has no external migration
+        // step, so it applies the composed MigrationRunnerPort BEFORE serving. Gated on the data
+        // capability so managed-schema bundles are untouched. A listening node-postgres process has no
+        // bypass: unit tests that need no database use the non-listening seam.
+        const bundle = deps.composeBundle(env);
+        const shouldMigrate = options.listen !== false &&
+            bundle.descriptor.capabilities.data === "postgres" &&
+            bundle.ports.migrations !== null;
+        if (shouldMigrate) {
+            const { applied } = await bundle.ports.migrations.apply();
+            log(`[serve.node] bundle=${bundleId} applied ${applied.length} migration(s) before serve`);
+        }
+        const distDir = options.distDir ?? resolve(process.cwd(), "dist");
+        const staticReader = createDistStaticReader(distDir);
+        const declaredSchedulerJobs = options.schedulerJobs ?? deps.loadSchedulerJobs();
+        const profile = options.schedulerProfile;
+        const schedulerJobs = profile ? profile.projectJobs(env, declaredSchedulerJobs) : declaredSchedulerJobs;
+        const handlers = mergeScheduledJobHandlers(deps.scheduledJobHandlers?.(env), options.scheduledJobHandlers, profile?.handlers?.(env));
+        const registryJobs = deps.scheduledJobs?.(env, bundle.ports) ?? [];
+        for (const job of registryJobs) {
+            if (schedulerJobs.some((declared) => declared.jobId === job.id)) {
+                throw new Error(`scheduled_job_declared_twice:${job.id}`);
+            }
+        }
+        if (deps.admitHost && (options.listen !== false || options.cron)) {
+            await deps.admitHost(env, {
+                kind: "node",
+                nodeJobHandlers: handlers,
+                nodeJobs: options.cron ? schedulerJobs : [],
+                scheduledJobs: options.cron ? registryJobs : [],
+            });
+        }
+        const httpRuntime = deps.createHttpRuntime({ schedulerJobs, staticReader, ports: bundle.ports });
+        // Node cron invokes a direct binding where one exists. Every other job takes the HTTP
+        // compatibility bridge to its own entrypoint, which the runtime mounts from the same registry,
+        // so a routing miss cannot masquerade as a scheduler failure and a job without an entrypoint
+        // fails visibly. The scheduler holds the cluster mutex: without it every instance of a
+        // horizontally scaled host fires the same timer in the same minute.
+        const registeredJobs = [];
+        let scheduler = null;
+        let schedulerLock;
+        if (options.cron) {
+            schedulerLock = options.advisoryLock ?? createEnvAdvisoryLock(env) ?? undefined;
+            scheduler = createNodeScheduler({
+                cron: options.cron,
+                env,
+                jobs: schedulerJobs,
+                lock: schedulerLock,
+            });
+            profile?.validateSchedule?.({
+                lock: schedulerLock,
+                jobs: scheduler.jobs,
+                overrides: options.scheduledJobHandlers,
+            });
+            const baseUrl = env.APP_BASE_URL ?? "http://localhost:3000";
+            const cronSecret = env.CRON_SECRET ?? "";
+            for (const job of scheduler.jobs) {
+                const directHandler = handlers[job.jobId];
+                profile?.validateJob?.(job, directHandler);
+                scheduler.register({
+                    jobId: job.jobId,
+                    schedule: job.schedule,
+                    handler: async () => {
+                        if (directHandler) {
+                            await directHandler({ jobId: job.jobId, invocationSource: "node_cron" });
+                            return;
+                        }
+                        const response = await fetch(new URL(job.path, baseUrl).toString(), {
+                            method: "GET",
+                            headers: cronSecret ? { Authorization: `Bearer ${cronSecret}` } : {},
+                        });
+                        if (!response.ok) {
+                            throw new Error(`node scheduler compatibility bridge for "${job.jobId}" returned HTTP ${response.status}`);
+                        }
+                    },
+                });
+                registeredJobs.push(job.jobId);
+            }
+            const lease = registryJobs.some((job) => job.lease) ? deps.jobLease?.(env) : undefined;
+            for (const job of registryJobs) {
+                scheduler.register({
+                    jobId: job.id,
+                    schedule: job.schedule,
+                    handler: async () => {
+                        await runScheduledJob(job, { invocation: { triggerKind: "scheduler", invocationSource: "node_cron" }, lease });
+                    },
+                });
+                registeredJobs.push(job.id);
+            }
+        }
+        if (options.listen !== false) {
+            const port = options.port ?? Number(env.PORT ?? 3000);
+            await httpRuntime.listen?.({ port, host: options.host ?? "0.0.0.0" });
+            log(`[serve.node] bundle=${bundleId} listening on :${port} (${registeredJobs.length} cron jobs)`);
+        }
+        let stopPromise = null;
+        return {
+            bundleId,
+            httpRuntime,
+            registeredJobs,
+            stop: () => (stopPromise ??= stopNodeHost(scheduler, schedulerLock, httpRuntime)),
+        };
+    }
+    return { assertBundleReady, serveNode };
+}
+async function stopNodeHost(scheduler, advisoryLock, httpRuntime) {
+    const timers = Promise.resolve().then(() => scheduler?.stopAll());
+    const server = httpRuntime.server;
+    const listener = server
+        ? new Promise((resolveClose, reject) => server.close((error) => error ? reject(error) : resolveClose()))
+        : Promise.resolve();
+    const results = await Promise.allSettled([timers, advisoryLock?.close(), listener]);
+    const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+    if (failures.length > 0)
+        throw new AggregateError(failures, "node_host_shutdown_failed");
+}

package/dist/data/binding.d.ts

@@ -0,0 +1,34 @@
+import { type PostgresDataGatewayEnv } from "./postgresGateway.js";
+import type { DataGatewayPort } from "@openlup/core/platform-runtime";
+import type { SupabaseCreateClient } from "./supabaseClientFactory.js";
+type Env = Record<string, string | undefined>;
+type ActorClaims = {
+    sub?: string;
+    role?: string;
+} | null;
+/** Actor-only data access for one request. */
+export type ActorOnlyDataPort = {
+    asActor: <T>(claims: ActorClaims, work: (gateway: unknown) => Promise<T>) => Promise<T>;
+};
+export interface DataPortBindingOptions {
+    /** Replaces the bindings' supabase-js `createClient` for this call (tests). */
+    createClientImpl?: SupabaseCreateClient;
+    resolveAccessToken?: (claims: ActorClaims) => string | null;
+}
+export interface DataBindingDependencies {
+    /** The supabase-js `createClient` used by every supabase gateway these bindings build. */
+    createSupabaseClient: SupabaseCreateClient;
+    /** Builds the direct-PostgreSQL gateway; defaults to `createPostgresDataGateway`. */
+    createPostgresGateway?: (env: PostgresDataGatewayEnv) => DataGatewayPort;
+}
+export interface DataBindings {
+    /** Resolve the DataGatewayPort for a bundle's declared data capability kind. */
+    bindDataPort(dataKind: string, env: Env, requestOptions?: DataPortBindingOptions): DataGatewayPort | null;
+    /** Bind one request to actor-only data access. */
+    bindRequestActorDataPort(accessToken: string, env: Env, requestOptions?: DataPortBindingOptions): ActorOnlyDataPort | null;
+    /** Resolve and bind the active bundle's data gateway, cached per bundle and data configuration. */
+    bindBundleDataPort(env: Env): DataGatewayPort | null;
+}
+/** Create one set of data bindings; the bundle data port cache belongs to this set. */
+export declare function createDataBindings(deps: DataBindingDependencies): DataBindings;
+export {};