@openlup/platform 0.0.0 → 0.15.0

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 {};

package/dist/data/binding.js

@@ -0,0 +1,92 @@
+// DataGatewayPort bindings for bundle composition.
+//
+// Maps a bundle's declared `data` capability to a concrete DataGatewayPort. The supabase gateway is
+// constructed eagerly (pure factory; no client/network until a port method runs work), so the
+// default vercel-supabase path binds the slot with no secrets needed: env is read with
+// empty-string fallbacks and validated lazily inside asActor/asService. The application supplies
+// the supabase-js `createClient` once, when it creates its bindings.
+//
+// The `postgres` capability (node-postgres) uses the existing direct-PG DataGatewayPort. Its
+// PgGatewayClient exposes the same narrow RPC surface used by Supabase-backed domain ports.
+import { getBundleDescriptor, resolveBundleId, } from "../kernel/index.js";
+import { createSupabaseDataGateway } from "./supabaseGateway.js";
+import { createPostgresDataGateway, resolvePostgresDataGatewayEnv, } from "./postgresGateway.js";
+/** Create one set of data bindings; the bundle data port cache belongs to this set. */
+export function createDataBindings(deps) {
+    let cachedBundleDataPort = null;
+    const createPostgresGateway = deps.createPostgresGateway ?? ((env) => createPostgresDataGateway(env));
+    /** Resolve the DataGatewayPort for a bundle's declared data capability kind. */
+    function bindDataPort(dataKind, env, requestOptions = {}) {
+        switch (dataKind) {
+            case "supabase":
+                // Construct from env with empty-string fallbacks; the actual supabase client is created
+                // lazily when asActor/asService runs work, so the slot binds even before secrets are present
+                // (same as the blob/transactional/analytics slots — keeps composeBundle({}) non-null).
+                return createSupabaseDataGateway({
+                    url: env.SUPABASE_URL ?? env.VITE_SUPABASE_URL ?? "",
+                    anonKey: env.VITE_SUPABASE_PUBLISHABLE_KEY ??
+                        env.VITE_SUPABASE_ANON_KEY ??
+                        env.SUPABASE_ANON_KEY ??
+                        "",
+                    serviceRoleKey: env.SUPABASE_SERVICE_ROLE_KEY ?? "",
+                }, { ...requestOptions, createClientImpl: requestOptions.createClientImpl ?? deps.createSupabaseClient });
+            case "postgres":
+                // Direct-PG gateway (pg.Pool, tx-per-request RLS via SET LOCAL). Pure factory — no pool
+                // until asActor/asService runs work, so the slot binds even before DATABASE_URL is present
+                // (matches the supabase case's lazy null-is-no-op convention; keeps composeBundle non-null).
+                return createPostgresGateway(resolvePostgresDataGatewayEnv(env));
+            default:
+                return null;
+        }
+    }
+    /**
+     * Bind one request to actor-only data access.
+     *
+     * HTTP-backed bundles receive a fresh gateway so the raw bearer resolver cannot
+     * cross request boundaries. The direct database bundle reuses the existing
+     * cached port (and therefore its lazy pool); only this actor-only facade is new.
+     */
+    function bindRequestActorDataPort(accessToken, env, requestOptions = {}) {
+        const bundleId = resolveBundleId(env);
+        const dataKind = getBundleDescriptor(bundleId).capabilities.data;
+        const port = dataKind === "postgres"
+            ? bindBundleDataPort(env)
+            : bindDataPort(dataKind, env, {
+                ...requestOptions,
+                resolveAccessToken: () => accessToken,
+            });
+        if (!port)
+            return null;
+        return {
+            asActor: (claims, work) => port.asActor(claims, work),
+        };
+    }
+    /** Resolve and bind the active bundle's data gateway without composing the whole runtime. */
+    function bindBundleDataPort(env) {
+        const bundleId = resolveBundleId(env);
+        const descriptor = getBundleDescriptor(bundleId);
+        const cacheKey = bundleDataPortCacheKey(bundleId, descriptor.capabilities.data, env);
+        if (cachedBundleDataPort?.cacheKey === cacheKey) {
+            return cachedBundleDataPort.port;
+        }
+        const port = bindDataPort(descriptor.capabilities.data, env);
+        cachedBundleDataPort = { cacheKey, port };
+        return port;
+    }
+    return { bindDataPort, bindRequestActorDataPort, bindBundleDataPort };
+}
+function bundleDataPortCacheKey(bundleId, dataKind, env) {
+    const dataConfig = dataKind === "postgres"
+        ? [env.DATABASE_URL ?? ""]
+        : dataKind === "supabase"
+            ? [
+                env.SUPABASE_URL ?? env.VITE_SUPABASE_URL ?? "",
+                env.VITE_SUPABASE_PUBLISHABLE_KEY ??
+                    env.VITE_SUPABASE_ANON_KEY ??
+                    env.SUPABASE_ANON_KEY ??
+                    "",
+                env.SUPABASE_SERVICE_ROLE_KEY ?? "",
+            ]
+            : [];
+    return JSON.stringify([bundleId, dataKind, ...dataConfig]);
+}

package/dist/data/index.d.ts

@@ -0,0 +1,5 @@
+export { createPostgresDataGateway, createPostgresGatewayTypeOverrides, createPostgresRoleFreeTransactionLane, postgresTimestampTzToRfc3339, resolvePostgresDataGatewayEnv, type PostgresDataGatewayEnv, type PostgresDataGatewayOptions, type PostgresRoleFreeTransactionLane, } from "./postgresGateway.js";
+export { PgGatewayClient, PgQueryBuilder, type PgQueryExecutor, type PgShimError, type PgShimResult, } from "./queryBuilder.js";
+export { createActorClient, createServiceClient, readSupabaseActorDataGatewayEnv, readSupabaseDataGatewayEnv, type SupabaseCreateClient, type SupabaseDataGatewayEnv, } from "./supabaseClientFactory.js";
+export { createSupabaseDataGateway, type SupabaseDataGatewayOptions } from "./supabaseGateway.js";
+export { createDataBindings, type ActorOnlyDataPort, type DataBindingDependencies, type DataBindings, type DataPortBindingOptions, } from "./binding.js";

package/dist/data/index.js

@@ -0,0 +1,5 @@
+export { createPostgresDataGateway, createPostgresGatewayTypeOverrides, createPostgresRoleFreeTransactionLane, postgresTimestampTzToRfc3339, resolvePostgresDataGatewayEnv, } from "./postgresGateway.js";
+export { PgGatewayClient, PgQueryBuilder, } from "./queryBuilder.js";
+export { createActorClient, createServiceClient, readSupabaseActorDataGatewayEnv, readSupabaseDataGatewayEnv, } from "./supabaseClientFactory.js";
+export { createSupabaseDataGateway } from "./supabaseGateway.js";
+export { createDataBindings, } from "./binding.js";

package/dist/data/postgresGateway.d.ts

@@ -0,0 +1,42 @@
+import type { Pool } from "pg";
+import type { DataGatewayPort } from "@openlup/core/platform-runtime";
+export interface PostgresDataGatewayEnv {
+    /** Postgres connection string (DATABASE_URL). Empty until a node-postgres deploy supplies it. */
+    connectionString: string;
+}
+export interface PostgresDataGatewayOptions {
+    /** Injection seam: tests pass a stub pool; production lazily builds a real pg.Pool from env. */
+    poolFactory?: (env: PostgresDataGatewayEnv) => Pool | Promise<Pool>;
+}
+/** Convert node-postgres timestamptz text to lossless RFC 3339. */
+export declare function postgresTimestampTzToRfc3339(value: string): string;
+/** Keep PostgREST-compatible, lossless timestamp strings at the gateway edge. */
+export declare function createPostgresGatewayTypeOverrides(TypeOverridesCtor: typeof import("pg").TypeOverrides): import("pg").TypeOverrides;
+/**
+ * Capability-local, role-free transaction lane.
+ *
+ * The platform manifest intentionally creates no service role. This is not an
+ * alternate DataGatewayPort access mode: a deployment hands one lane to exactly
+ * one adapter that calls its own rail RPCs, and names that lane after the
+ * capability, because the name is the access rule. Its lifecycle reuses the same
+ * pooled BEGIN/callback/COMMIT|ROLLBACK/release implementation as the public
+ * gateway below, but it never changes the connection role.
+ */
+export interface PostgresRoleFreeTransactionLane {
+    run<T>(work: (gateway: unknown) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/**
+ * Build a node-postgres-backed DataGatewayPort. Pure: NO pool/connection is created until a port
+ * method runs work (lazy, like the supabase adapter), so the slot binds even before DATABASE_URL is
+ * present (keeps composeBundle({}) non-null). The pool is created once and reused across calls.
+ */
+export declare function createPostgresDataGateway(env: PostgresDataGatewayEnv, options?: PostgresDataGatewayOptions): DataGatewayPort;
+/**
+ * Build one role-free, per-operation lane. Do not use this for generic service
+ * work: DataGatewayPort.asService remains the mandatory service_role boundary.
+ * Only a named owner-authority capability of the deployment may hold a lane.
+ */
+export declare function createPostgresRoleFreeTransactionLane(env: PostgresDataGatewayEnv, options?: PostgresDataGatewayOptions): PostgresRoleFreeTransactionLane;
+/** Resolve the gateway env from process env (DATABASE_URL), mirroring the supabase binding shape. */
+export declare function resolvePostgresDataGatewayEnv(env: Record<string, string | undefined>): PostgresDataGatewayEnv;