@openlup/platform 0.0.0 → 0.16.0

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

package/src/data/queryBuilder.ts

@@ -0,0 +1,300 @@
+// Vanilla-Postgres query-builder shim.
+//
+// Option A (approved): a SCOPED, injection-safe builder that emulates ONLY the supabase-js methods
+// the 6 existing gateway consumers actually call — never a full PostgREST reimplementation. It
+// translates a builder chain into a single PARAMETERIZED `pg` query ($1,$2,…). Values are never
+// string-interpolated and identifiers are allowlist-validated; both invariants live in the pure SQL
+// layer (queryBuilderSql.ts), which this file composes.
+//
+// Result semantics mirror PostgREST for the methods used:
+//   - default (await builder)            -> { data: Row[], error }
+//   - .maybeSingle()                     -> { data: Row | null, error } (0/1 row; >1 is an error)
+//   - .single()                          -> { data: Row, error }       (exactly 1 row; else error)
+//   - .range(from,to)/.limit(n)          -> LIMIT/OFFSET, returns { data: Row[], error }
+//   - .select(c, {count:"exact"[,head]}) -> { data, count } from a separate aggregate; head omits rows
+//   - .insert(v).select(c).maybeSingle() -> INSERT ... RETURNING c, single row
+//   - .update(v)...                      -> UPDATE ... [RETURNING c]
+//   - error.code carries the pg SQLSTATE (e.g. 23505 unique-violation) so consumers' code-based
+//     branches (idempotency replay) keep working unchanged.
+//
+// The shim is constructed over a SINGLE acquired pg client (one per asActor/asService tx in the
+// DataGatewayPort), so every query here runs inside that request's transaction with its RLS GUCs set.
+
+import type { PoolClient } from "pg";
+
+import {
+  ParamAccumulator,
+  joinParts,
+  quoteIdent,
+  rangeNotSatisfiable,
+  renderColumns,
+  renderCountQuery,
+  renderFilter,
+  renderInsertStatement,
+  toShimError,
+  unwrapRpcRows,
+  type Filter,
+  type OrderBy,
+  type PgQueryExecutor,
+  type PgShimError,
+  type PgShimResult,
+} from "./queryBuilderSql.js";
+
+// Re-export the result/error/executor shapes so consumers import them from the builder entrypoint.
+export type { PgQueryExecutor, PgShimError, PgShimResult };
+
+interface BuilderState {
+  table: string;
+  mode: "select" | "insert" | "update";
+  columns: string; // RETURNING / SELECT projection
+  filters: Filter[];
+  orders: OrderBy[];
+  limit: number | null;
+  offset: number | null;
+  insertRows: Array<Record<string, unknown>> | null;
+  updateValues: Record<string, unknown> | null;
+  exactCount: boolean;
+  head: boolean;
+  rangeRequested: boolean;
+}
+
+/**
+ * Builder over one pg client. Chainable + awaitable (PromiseLike). Every value flows through a param
+ * accumulator, so the rendered SQL contains only $N placeholders for values.
+ */
+export class PgQueryBuilder<T = unknown> implements PromiseLike<PgShimResult<T>> {
+  private state: BuilderState;
+
+  constructor(
+    private readonly client: PgQueryExecutor,
+    table: string,
+  ) {
+    this.state = {
+      table,
+      mode: "select",
+      columns: "*",
+      filters: [],
+      orders: [],
+      limit: null,
+      offset: null,
+      insertRows: null,
+      updateValues: null,
+      exactCount: false,
+      head: false,
+      rangeRequested: false,
+    };
+  }
+
+  select(columns: string, options?: { count?: string; head?: boolean }): this {
+    this.state.columns = columns;
+    this.state.exactCount = options?.count === "exact";
+    this.state.head = options?.head === true;
+    return this;
+  }
+
+  insert(values: Record<string, unknown> | Array<Record<string, unknown>>): this {
+    this.state.mode = "insert";
+    this.state.insertRows = Array.isArray(values) ? values : [values];
+    return this;
+  }
+
+  update(values: Record<string, unknown>): this {
+    this.state.mode = "update";
+    this.state.updateValues = values;
+    return this;
+  }
+
+  eq(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "eq", column, value });
+    return this;
+  }
+
+  gt(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "gt", column, value });
+    return this;
+  }
+
+  gte(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "gte", column, value });
+    return this;
+  }
+
+  lte(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "lte", column, value });
+    return this;
+  }
+
+  in(column: string, values: unknown[]): this {
+    this.state.filters.push({ kind: "in", column, values });
+    return this;
+  }
+
+  is(column: string, value: unknown): this {
+    this.state.filters.push({ kind: "is", column, value });
+    return this;
+  }
+
+  ilike(column: string, value: string): this {
+    this.state.filters.push({ kind: "ilike", column, value });
+    return this;
+  }
+
+  order(column: string, options?: { ascending?: boolean }): this {
+    this.state.orders.push({ column, ascending: options?.ascending !== false });
+    return this;
+  }
+
+  limit(count: number): this {
+    this.state.limit = count;
+    return this;
+  }
+
+  range(from: number, to: number): Promise<PgShimResult<T>> {
+    // PostgREST range is inclusive on both ends → LIMIT (to-from+1) OFFSET from.
+    this.state.offset = from;
+    this.state.limit = to - from + 1;
+    this.state.rangeRequested = true;
+    return this.run("many");
+  }
+
+  async maybeSingle(): Promise<PgShimResult<T>> {
+    return this.run("maybe");
+  }
+
+  async single(): Promise<PgShimResult<T>> {
+    return this.run("single");
+  }
+
+  then<R1 = PgShimResult<T>, R2 = never>(
+    onfulfilled?: ((value: PgShimResult<T>) => R1 | PromiseLike<R1>) | null,
+    onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): Promise<R1 | R2> {
+    return this.run("many").then(onfulfilled, onrejected);
+  }
+
+  private async run(cardinality: "many" | "maybe" | "single"): Promise<PgShimResult<T>> {
+    try {
+      const count = this.state.exactCount ? await this.runExactCount() : null;
+      // A page past the end is a REFUSAL upstream, not an empty answer — but only once the total is
+      // known, which is why this sits behind the count and not behind `.range()` itself.
+      const unsatisfiable = this.state.rangeRequested ? rangeNotSatisfiable(this.state.offset, count) : null;
+      if (unsatisfiable) return { data: [] as T, error: unsatisfiable, count: null };
+      // head:true is a HEAD request: no body, so the client contract reports data:null and no row query.
+      if (this.state.head) return { data: null as T, error: null, count };
+      const { text, values } = this.compile();
+      const { rows } = await this.client.query(text, values);
+      // The client contract reports count: null unless a count was requested; `shape` must not invent one.
+      return { ...this.shape(rows, cardinality), count };
+    } catch (error) {
+      return { data: (cardinality === "many" ? [] : null) as T, error: toShimError(error), count: null };
+    }
+  }
+
+  private async runExactCount(): Promise<number> {
+    const params = new ParamAccumulator();
+    const { rows } = await this.client.query(renderCountQuery(this.state.table, this.state.filters, params), params.values);
+    return Number(rows[0]?.exact_count ?? 0);
+  }
+
+  private shape(rows: Record<string, unknown>[], cardinality: "many" | "maybe" | "single"): PgShimResult<T> {
+    if (cardinality === "many") {
+      return { data: rows as T, error: null };
+    }
+    if (rows.length > 1) {
+      // PostgREST returns 406 (PGRST116) when maybeSingle/single match multiple rows.
+      return { data: null as T, error: { code: "PGRST116", message: "multiple rows returned" } };
+    }
+    if (cardinality === "single" && rows.length === 0) {
+      return { data: null as T, error: { code: "PGRST116", message: "no rows returned" } };
+    }
+    return { data: (rows[0] ?? null) as T, error: null };
+  }
+
+  private compile(): { text: string; values: unknown[] } {
+    const params = new ParamAccumulator();
+    if (this.state.mode === "insert") return this.compileInsert(params);
+    if (this.state.mode === "update") return this.compileUpdate(params);
+    return this.compileSelect(params);
+  }
+
+  private compileSelect(params: ParamAccumulator): { text: string; values: unknown[] } {
+    const parts = [`SELECT ${renderColumns(this.state.columns)} FROM ${quoteIdent(this.state.table)}`];
+    parts.push(this.renderWhere(params));
+    parts.push(this.renderOrder());
+    parts.push(this.renderLimitOffset(params));
+    return { text: joinParts(parts), values: params.values };
+  }
+
+  private compileInsert(params: ParamAccumulator): { text: string; values: unknown[] } {
+    const text = renderInsertStatement(this.state.table, this.state.insertRows ?? [], this.state.columns, params);
+    return { text, values: params.values };
+  }
+
+  private compileUpdate(params: ParamAccumulator): { text: string; values: unknown[] } {
+    const values = this.state.updateValues ?? {};
+    const assignments = Object.keys(values)
+      .map((c) => `${quoteIdent(c)} = ${params.add(values[c])}`)
+      .join(", ");
+    if (assignments === "") throw new Error("pg-shim: update requires at least one column");
+    const parts = [`UPDATE ${quoteIdent(this.state.table)} SET ${assignments}`];
+    parts.push(this.renderWhere(params));
+    const returning = this.state.columns && this.state.columns !== "*"
+      ? `RETURNING ${renderColumns(this.state.columns)}`
+      : "";
+    if (returning) parts.push(returning);
+    return { text: joinParts(parts), values: params.values };
+  }
+
+  private renderWhere(params: ParamAccumulator): string {
+    if (this.state.filters.length === 0) return "";
+    const clauses = this.state.filters.map((f) => renderFilter(f, params));
+    return `WHERE ${clauses.join(" AND ")}`;
+  }
+
+  private renderOrder(): string {
+    if (this.state.orders.length === 0) return "";
+    const cols = this.state.orders
+      .map((o) => `${quoteIdent(o.column)} ${o.ascending ? "ASC" : "DESC"}`)
+      .join(", ");
+    return `ORDER BY ${cols}`;
+  }
+
+  private renderLimitOffset(params: ParamAccumulator): string {
+    const parts: string[] = [];
+    if (this.state.limit !== null) parts.push(`LIMIT ${params.add(this.state.limit)}`);
+    if (this.state.offset !== null) parts.push(`OFFSET ${params.add(this.state.offset)}`);
+    return parts.join(" ");
+  }
+}
+
+/** supabase-js-style client over one acquired pg client: `.from(t)` + `.rpc(fn, args)`. */
+export class PgGatewayClient {
+  constructor(private readonly client: PgQueryExecutor) {}
+
+  query(text: string, values?: unknown[]) { return this.client.query(text, values); }
+
+  from<T = Record<string, unknown>>(table: string): PgQueryBuilder<T> {
+    return new PgQueryBuilder<T>(this.client, table);
+  }
+
+  async rpc(functionName: string, args: Record<string, unknown> = {}): Promise<PgShimResult> {
+    try {
+      const name = quoteIdent(functionName);
+      const params = new ParamAccumulator();
+      // Named-arg invocation: every existing RPC uses `p_*` named params. `name => $n` binds by name
+      // so arg order is irrelevant and values are fully parameterized.
+      const namedArgs = Object.keys(args)
+        .map((key) => `${quoteIdent(key)} => ${params.add(args[key])}`)
+        .join(", ");
+      const text = `SELECT * FROM ${name}(${namedArgs})`;
+      const { rows } = await this.client.query(text, params.values);
+      // RPCs returning a scalar set-returning function expose the value under the function name;
+      // a single-column single-row result unwraps to that value (matches supabase-js rpc shape).
+      return { data: unwrapRpcRows(rows, functionName), error: null };
+    } catch (error) {
+      return { data: null, error: toShimError(error) };
+    }
+  }
+}
+
+export type { PoolClient };

package/src/data/queryBuilderSql.ts

@@ -0,0 +1,183 @@
+// Vanilla-Postgres query-builder SQL primitives.
+//
+// Extracted from queryBuilder.ts (300-LOC cap) — the pure, stateless SQL-fragment layer the builder
+// composes: result/error shapes, the injection-safety chokepoint (ParamAccumulator), identifier
+// quoting (allowlist), column projection, and filter rendering. VALUES ARE NEVER string-interpolated;
+// they flow through ParamAccumulator as $N placeholders. Identifiers (table/column names) are validated
+// against a strict allowlist regex and double-quoted, so they cannot smuggle SQL either.
+
+/** PostgREST-shaped error the consumers narrow on (`.code`, `.message`, `.details`, `.hint`). */
+export interface PgShimError {
+  code?: string;
+  message?: string;
+  details?: string;
+  hint?: string;
+}
+
+export interface PgShimResult<T = unknown> {
+  data: T;
+  error: PgShimError | null;
+  count?: number | null;
+}
+
+/** Minimal query surface we need from a pg client (Pool acquires a PoolClient per request). */
+export interface PgQueryExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+export type Filter =
+  | { kind: "eq" | "gte" | "lte" | "gt"; column: string; value: unknown }
+  | { kind: "in"; column: string; values: unknown[] }
+  | { kind: "ilike"; column: string; value: string }
+  | { kind: "is"; column: string; value: unknown };
+
+export interface OrderBy {
+  column: string;
+  ascending: boolean;
+}
+
+// Identifiers (table + column names) are NEVER parameterizable in SQL, so they are validated against
+// a strict allowlist and quoted. Consumers only ever pass static, code-literal identifiers; this
+// guard turns any attempt to pass a crafted identifier into a thrown error rather than injected SQL.
+const IDENTIFIER_RE = /^[a-z_][a-z0-9_]*$/i;
+
+export function quoteIdent(raw: string): string {
+  if (!IDENTIFIER_RE.test(raw)) {
+    throw new Error(`pg-shim: unsafe identifier ${JSON.stringify(raw)}`);
+  }
+  return `"${raw}"`;
+}
+
+// `select("a, b")` etc. — a comma list of identifiers or "*". Each segment is validated; "*" passes
+// through. PostgREST embedding syntax (foo(bar)) is NOT used by any consumer, so it is rejected
+// (fail-closed) rather than silently mistranslated.
+export function renderColumns(columns: string): string {
+  const trimmed = columns.trim();
+  if (trimmed === "" || trimmed === "*") return "*";
+  return trimmed
+    .split(",")
+    .map((c) => c.trim())
+    .map((c) => (c === "*" ? "*" : quoteIdent(c)))
+    .join(", ");
+}
+
+export function renderFilter(filter: Filter, params: ParamAccumulator): string {
+  const col = quoteIdent(filter.column);
+  switch (filter.kind) {
+    case "eq":
+      return `${col} = ${params.add(filter.value)}`;
+    case "gt":
+      return `${col} > ${params.add(filter.value)}`;
+    case "gte":
+      return `${col} >= ${params.add(filter.value)}`;
+    case "lte":
+      return `${col} <= ${params.add(filter.value)}`;
+    case "ilike":
+      return `${col} ILIKE ${params.add(filter.value)}`;
+    case "in": {
+      // Empty IN () is invalid SQL; PostgREST treats `.in([])` as matching nothing.
+      if (filter.values.length === 0) return "false";
+      const placeholders = filter.values.map((v) => params.add(v)).join(", ");
+      return `${col} IN (${placeholders})`;
+    }
+    case "is":
+      // .is(col, null) → IS NULL; .is(col, true/false) → IS TRUE/FALSE. Value is a literal keyword,
+      // not user data (consumers only pass null/true/false), so it is rendered, not parameterized.
+      if (filter.value === null) return `${col} IS NULL`;
+      if (filter.value === true) return `${col} IS TRUE`;
+      if (filter.value === false) return `${col} IS FALSE`;
+      throw new Error("pg-shim: .is() only supports null/true/false");
+  }
+}
+
+/**
+ * PostgREST `count=exact` rendered as a SEPARATE aggregate over the same FROM/WHERE — deliberately
+ * NOT a `COUNT(*) OVER()` folded into the row query. PostgREST's exact count ignores limit/offset,
+ * and a window function emits no row at all for an empty page, so an offset past the end would
+ * report 0 instead of the true total. Keeping it separate also leaves the row projection
+ * byte-identical: there is no synthetic column to strip before cardinality shaping.
+ */
+export function renderCountQuery(table: string, filters: readonly Filter[], params: ParamAccumulator): string {
+  const where = filters.length === 0
+    ? ""
+    : `WHERE ${filters.map((filter) => renderFilter(filter, params)).join(" AND ")}`;
+  return joinParts([`SELECT count(*) AS exact_count FROM ${quoteIdent(table)}`, where]);
+}
+
+/**
+ * PostgREST refuses an out-of-bounds page instead of answering an empty one -- but ONLY when it
+ * knows the total, i.e. when an exact count was requested; without one it answers 200 and `[]`,
+ * which is what this shim already did. The boundary is strict: offset === total is a legal empty
+ * page, offset === total + 1 is not. Measured against PostgREST 14.10 before this was written,
+ * including the `details` sentence, which carries the two numbers a caller pages on.
+ */
+export function rangeNotSatisfiable(offset: number | null, total: number | null): PgShimError | null {
+  if (offset === null || total === null || offset <= total) return null;
+  return {
+    code: "PGRST103",
+    message: "Requested range not satisfiable",
+    details: `An offset of ${offset} was requested, but there are only ${total} rows.`,
+  };
+}
+
+/**
+ * INSERT ... VALUES ... RETURNING, with the column list taken from the FIRST row and every later
+ * row required to carry the same key set. Deriving the columns from row 0 alone and binding the
+ * rest positionally is how a batch used to lose a column silently: an extra key vanished, a missing
+ * one bound NULL over a DEFAULT. PostgREST answers PGRST102 "All object keys must match" to exactly
+ * this payload -- and keeps answering it under `Prefer: missing=default`, measured -- so the shim
+ * refuses too. Refusal, not union: parity is the point, and this builder exposes no Prefer header
+ * through which a caller could ask for anything else.
+ */
+export function renderInsertStatement(
+  table: string,
+  rows: readonly Record<string, unknown>[],
+  projection: string,
+  params: ParamAccumulator,
+): string {
+  if (rows.length === 0) throw new Error("pg-shim: insert requires at least one row");
+  const columns = Object.keys(rows[0]!);
+  const signature = [...columns].sort().join("\u0000");
+  for (const row of rows) {
+    if ([...Object.keys(row)].sort().join("\u0000") !== signature) {
+      throw Object.assign(new Error("All object keys must match"), { code: "PGRST102" });
+    }
+  }
+  const tuples = rows.map((row) => `(${columns.map((column) => params.add(row[column])).join(", ")})`).join(", ");
+  return `INSERT INTO ${quoteIdent(table)} (${columns.map(quoteIdent).join(", ")}) VALUES ${tuples} `
+    + `RETURNING ${renderColumns(projection)}`;
+}
+
+// supabase-js rpc() returns the function's return value directly: a scalar/json function yields that
+// value; a TABLE/SETOF function yields the row array. Heuristic mirrors that: 1 row × 1 column whose
+// name equals the function → the scalar; otherwise the rows array (TABLE-returning).
+export function unwrapRpcRows(rows: Record<string, unknown>[], functionName: string): unknown {
+  if (rows.length === 1) {
+    const keys = Object.keys(rows[0]);
+    if (keys.length === 1 && keys[0] === functionName) return rows[0][functionName];
+  }
+  return rows;
+}
+
+/** Accumulates values and hands back $1,$2,… placeholders — the single injection-safety chokepoint. */
+export class ParamAccumulator {
+  readonly values: unknown[] = [];
+  add(value: unknown): string {
+    this.values.push(value);
+    return `$${this.values.length}`;
+  }
+}
+
+export function joinParts(parts: string[]): string {
+  return parts.filter((p) => p.trim() !== "").join(" ");
+}
+
+export function toShimError(error: unknown): PgShimError {
+  const e = error as { code?: string; message?: string; detail?: string; hint?: string };
+  return {
+    code: e?.code,
+    message: e?.message ?? "query failed",
+    details: e?.detail,
+    hint: e?.hint,
+  };
+}