@openlup/platform 0.0.0 → 0.15.0

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";

package/src/data/postgresGateway.ts

@@ -0,0 +1,186 @@
+// Vanilla-Postgres DataGatewayPort plus capability-local role-free transaction
+// lanes. Actor/service role changes use SET LOCAL; every call owns one pooled
+// BEGIN/COMMIT|ROLLBACK/release lifecycle, so claims never leak between calls.
+import type { Pool, PoolClient } from "pg";
+import type { DataGatewayPort } from "@openlup/core/platform-runtime";
+import { PgGatewayClient } from "./queryBuilder.js";
+
+type ActorClaims = { sub?: string; role?: string } | null;
+
+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 function postgresTimestampTzToRfc3339(value: string): string {
+  const parts = /^(\d{4,}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}(?:\.\d+)?)([+-])(\d{2})(?::?(\d{2}))?$/.exec(value);
+  if (!parts) return value;
+  const [, date, time, sign, offsetHours, offsetMinutes = "00"] = parts;
+  return `${date}T${time}${sign}${offsetHours}:${offsetMinutes}`;
+}
+/** Keep PostgREST-compatible, lossless timestamp strings at the gateway edge. */
+export function createPostgresGatewayTypeOverrides(
+  TypeOverridesCtor: typeof import("pg").TypeOverrides,
+): import("pg").TypeOverrides {
+  const overrides = new TypeOverridesCtor();
+  // node-postgres otherwise turns timestamptz into a millisecond Date and drops
+  // PostgreSQL microseconds, making an immediate schedule round-trip look stale.
+  overrides.setTypeParser(1184, "text", postgresTimestampTzToRfc3339);
+  return overrides;
+}
+
+/**
+ * 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 function createPostgresDataGateway(
+  env: PostgresDataGatewayEnv,
+  options: PostgresDataGatewayOptions = {},
+): DataGatewayPort {
+  const transactions = createPooledPostgresTransactions(env, options);
+
+  return {
+    async asService<T>(work: (gateway: unknown) => Promise<T>): Promise<T> {
+      return transactions.run(async (client) => {
+        await client.query("SET LOCAL ROLE service_role");
+      }, work);
+    },
+
+    async asActor<T>(claims: ActorClaims, work: (gateway: unknown) => Promise<T>): Promise<T> {
+      return transactions.run(async (client) => {
+        const jwtClaims = buildJwtClaims(claims);
+        if (jwtClaims) {
+          // Parameterized: the claims JSON is bound as $1, never interpolated into the SET statement.
+          await client.query("SELECT set_config('request.jwt.claims', $1, true)", [jwtClaims]);
+          await client.query("SET LOCAL ROLE authenticated");
+        } else {
+          // No usable principal → drop to the `anon` role so RLS evaluates the request as
+          // unauthenticated. CRITICAL: the connection's own login role may be a superuser/owner
+          // (which BYPASSes RLS), so we MUST switch roles rather than leave the default — otherwise an
+          // unauthenticated actor would silently see everything. Fail-safe: anon is RLS-bound, never
+          // elevated. (No request.jwt.claims is set, so auth.uid() returns NULL.)
+          await client.query("SET LOCAL ROLE anon");
+        }
+      }, work);
+    },
+  };
+}
+
+/**
+ * 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 function createPostgresRoleFreeTransactionLane(
+  env: PostgresDataGatewayEnv,
+  options: PostgresDataGatewayOptions = {},
+): PostgresRoleFreeTransactionLane {
+  const transactions = createPooledPostgresTransactions(env, options);
+  return { run: (work) => transactions.run(async () => {}, work), close: transactions.close };
+}
+
+function createPooledPostgresTransactions(
+  env: PostgresDataGatewayEnv,
+  options: PostgresDataGatewayOptions,
+): {
+  run<T>(setup: (client: PoolClient) => Promise<void>, work: (gateway: unknown) => Promise<T>): Promise<T>;
+  close(): Promise<void>;
+} {
+  let poolPromise: Promise<Pool> | null = null;
+
+  async function getPool(): Promise<Pool> {
+    // Cache the in-flight promise (not the resolved Pool) so concurrent first calls share ONE pool
+    // rather than racing to build two. Promise.resolve normalizes the factory's Pool | Promise<Pool>.
+    if (!poolPromise) {
+      const factory = options.poolFactory ?? defaultPoolFactory;
+      poolPromise = Promise.resolve(factory(env));
+    }
+    return poolPromise;
+  }
+
+  async function withClient<T>(setup: (client: PoolClient) => Promise<void>, work: (gw: unknown) => Promise<T>): Promise<T> {
+    const activePool = await getPool();
+    const client = await activePool.connect();
+    try {
+      await client.query("BEGIN");
+      await setup(client);
+      const result = await work(new PgGatewayClient(client));
+      await client.query("COMMIT");
+      return result;
+    } catch (error) {
+      try {
+        await client.query("ROLLBACK");
+      } catch {
+        // ignore rollback failure; surface the original error
+      }
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  return {
+    run: withClient,
+    async close(): Promise<void> {
+      if (poolPromise) await (await poolPromise).end();
+    },
+  };
+}
+
+/**
+ * Build the request.jwt.claims JSON PostgREST would set. Returns null when there is no usable
+ * principal (no sub) so the caller stays anon rather than asserting an authenticated-but-empty role.
+ */
+function buildJwtClaims(claims: ActorClaims): string | null {
+  if (!claims || !claims.sub) return null;
+  const role = claims.role && claims.role.trim() !== "" ? claims.role : "authenticated";
+  return JSON.stringify({ sub: claims.sub, role });
+}
+
+// Lazy default: only import `pg` and build the Pool when actually invoked, so typecheck/test paths
+// that never run work do not load the driver. SET LOCAL keeps pooled-connection reuse safe.
+async function defaultPoolFactory(env: PostgresDataGatewayEnv): Promise<Pool> {
+  const pg = await import("pg").catch(peerMissing);
+  const PoolCtor = (pg.default?.Pool ?? pg.Pool) as typeof import("pg").Pool;
+  const TypeOverridesCtor = (pg.default?.TypeOverrides ?? pg.TypeOverrides) as typeof import("pg").TypeOverrides;
+  return new PoolCtor({
+    connectionString: env.connectionString,
+    types: createPostgresGatewayTypeOverrides(TypeOverridesCtor),
+  });
+}
+
+/** Resolve the gateway env from process env (DATABASE_URL), mirroring the supabase binding shape. */
+export function resolvePostgresDataGatewayEnv(env: Record<string, string | undefined>): PostgresDataGatewayEnv {
+  return { connectionString: env.DATABASE_URL ?? "" };
+}
+
+/** Translate only absence of this optional peer; preserve broken SDKs and other failures. */
+function peerMissing(cause: unknown): never {
+  if (cause instanceof Error && "code" in cause
+    && (cause.code === "ERR_MODULE_NOT_FOUND" || cause.code === "MODULE_NOT_FOUND")
+    && /^Cannot find (?:package|module) ['"]pg['"]/.test(cause.message)) {
+    throw new Error("OPENLUP_E_PEER_MISSING: pg is required by the Postgres data gateway; install it alongside @openlup/platform", { cause });
+  }
+  throw cause;
+}