@openlup/platform 0.0.0 → 0.16.0

package/src/composition/composeBundle.ts

@@ -0,0 +1,109 @@
+// 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 type {
+  AnalyticsPort,
+  BlobStoragePort,
+  DataGatewayPort,
+  HttpRuntimePort,
+  MigrationRunnerPort,
+  SchedulerPort,
+  TransactionalRuntimePort,
+} from "@openlup/core/platform-runtime";
+
+import { bindBlobPort, type SupabaseStorageClient } from "../blob/index.js";
+import { createServiceClient, readSupabaseDataGatewayEnv } from "../data/index.js";
+import {
+  getBundleDescriptor,
+  resolveBlobCapability,
+  resolveBundleId,
+  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 function createBundleComposer(binders: PlatformBundleBinders = {}): ComposeBundle {
+  const bindBlob = binders.blob ?? ((capability: string, env: 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) as SupabaseStorageClient
+        : undefined,
+    });
+  });
+  return function composeBundle(env: Env): PlatformBundle {
+    const id = resolveBundleId(env);
+    const descriptor = getBundleDescriptor(id);
+    const { capabilities } = descriptor;
+    const ports: PlatformBundlePorts = {
+      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/src/composition/httpBinding.ts

@@ -0,0 +1,30 @@
+// 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 type { HttpRuntimePort } from "@openlup/core/platform-runtime";
+
+import type { EntrypointLoader } from "../http/index.js";
+import { createNodeHttpRuntime, type NodeHttpRuntimeOptions } from "../http/index.js";
+import type { ScheduledJobDeclaration } from "../scheduler/index.js";
+
+/** Mount only the scheduled routes declared by the job registry. */
+export function createScheduledEntrypointResolver(
+  jobs: readonly ScheduledJobDeclaration[],
+  load: (jobId: string) => ReturnType<EntrypointLoader>,
+): (jobId: string) => EntrypointLoader | null {
+  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: string,
+  options: () => NodeHttpRuntimeOptions,
+): HttpRuntimePort | null {
+  if (capability !== "node") return null;
+  return createNodeHttpRuntime(options());
+}

package/src/composition/index.ts

@@ -0,0 +1,17 @@
+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/src/composition/nodeHost.ts

@@ -0,0 +1,289 @@
+// 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 type { HttpRuntimePort, JobLeasePort } from "@openlup/core/platform-runtime";
+
+import { createDistStaticReader } from "../http/index.js";
+import type { StaticAssetReader } from "../http/index.js";
+import {
+  createEnvAdvisoryLock,
+  createNodeScheduler,
+  mergeScheduledJobHandlers,
+  runScheduledJob,
+  type AdvisoryLock,
+  type CronScheduler,
+  type NodeSchedulerAdapter,
+  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 function createNodeHost(deps: NodeHostDependencies): NodeHost {
+  const log = deps.log ?? ((message: string) => console.log(message));
+
+  function assertBundleReady(env: Env): { bundleId: string } {
+    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: ServeNodeOptions): Promise<ServeNodeResult> {
+    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: string[] = [];
+    let scheduler: NodeSchedulerAdapter | null = null;
+    let schedulerLock: AdvisoryLock | undefined;
+    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: Promise<void> | null = null;
+    return {
+      bundleId,
+      httpRuntime,
+      registeredJobs,
+      stop: () => (stopPromise ??= stopNodeHost(scheduler, schedulerLock, httpRuntime)),
+    };
+  }
+
+  return { assertBundleReady, serveNode };
+}
+
+async function stopNodeHost(
+  scheduler: NodeSchedulerAdapter | null,
+  advisoryLock: AdvisoryLock | undefined,
+  httpRuntime: HttpRuntimePort,
+): Promise<void> {
+  const timers = Promise.resolve().then(() => scheduler?.stopAll());
+  const server = (httpRuntime as HttpRuntimePort & {
+    server?: { close(callback: (error?: Error) => void): void } | null;
+  }).server;
+  const listener = server
+    ? new Promise<void>((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/src/data/binding.ts

@@ -0,0 +1,157 @@
+// 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,
+  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;
+}
+
+interface CachedBundleDataPort {
+  cacheKey: string;
+  port: DataGatewayPort | 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 function createDataBindings(deps: DataBindingDependencies): DataBindings {
+  let cachedBundleDataPort: CachedBundleDataPort | null = null;
+  const createPostgresGateway = deps.createPostgresGateway ?? ((env: PostgresDataGatewayEnv) => createPostgresDataGateway(env));
+
+  /** Resolve the DataGatewayPort for a bundle's declared data capability kind. */
+  function bindDataPort(
+    dataKind: string,
+    env: Env,
+    requestOptions: DataPortBindingOptions = {},
+  ): DataGatewayPort | null {
+    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: string,
+    env: Env,
+    requestOptions: DataPortBindingOptions = {},
+  ): ActorOnlyDataPort | null {
+    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: Env): DataGatewayPort | null {
+    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: string, dataKind: string, env: Env): string {
+  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/src/data/index.ts

@@ -0,0 +1,33 @@
+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";