@porulle/core 0.1.0

package/src/runtime/server.ts

@@ -0,0 +1,470 @@
+import { Hono } from "hono";
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { cors } from "hono/cors";
+import { csrf } from "hono/csrf";
+import { bodyLimit } from "hono/body-limit";
+import { rateLimiter } from "hono-rate-limiter";
+import { createHash } from "node:crypto";
+import type { Actor } from "../auth/types.js";
+import type { AuthInstance } from "../auth/setup.js";
+import type { CommerceConfig } from "../config/types.js";
+import { authMiddleware } from "../auth/middleware.js";
+import { createRestRoutes } from "../interfaces/rest/index.js";
+import { createCustomerPortalRoutes } from "../interfaces/rest/customer-portal.js";
+import { createKernel } from "./kernel.js";
+import { ensureDefaultOrg } from "../auth/org.js";
+import { createLogger, type Logger } from "./logger.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+import { createCommerce, type CommerceInstance } from "./commerce.js";
+import { rewriteCommerceAliasRequest } from "./url-alias-rewrite.js";
+import { mapErrorToResponse } from "../kernel/error-mapper.js";
+
+type ServerEnv = {
+  Variables: {
+    auth: AuthInstance;
+    actor: Actor | null;
+    requestId: string;
+    logger: Logger;
+  };
+};
+
+/**
+ * Returns true if running in a Node-like runtime that supports
+ * `process.on()` + `process.exit()`. Edge runtimes (Cloudflare Workers,
+ * Vercel Edge) return false — caller should skip process-crash handlers
+ * and defer unhandled errors to the platform.
+ *
+ * Exposed for direct unit testing — see test/server-edge-runtime.test.ts.
+ */
+export function isNodeRuntime(): boolean {
+  return (
+    typeof process !== "undefined" &&
+    typeof process.on === "function" &&
+    typeof process.exit === "function"
+  );
+}
+
+function hashRateLimitEmail(email: string): string {
+  return createHash("sha256")
+    .update(email.trim().toLowerCase())
+    .digest("hex");
+}
+
+function matchPathPattern(path: string, pattern: string): boolean {
+  if (pattern.endsWith("*")) {
+    return path.startsWith(pattern.slice(0, -1));
+  }
+  return path === pattern;
+}
+
+/**
+ * Create a full HTTP server (Hono) with all REST routes, auth, and middleware.
+ *
+ * For server-side frameworks (Next.js, TanStack Start, SvelteKit), use
+ * `createCommerce()` instead — it gives you a local API without HTTP overhead.
+ */
+export async function createServer(config: CommerceConfig) {
+  const commerce = await createCommerce(config);
+  const { kernel, auth, logger } = commerce;
+  const isProdEnv = process.env.NODE_ENV === "production";
+
+  const app = new OpenAPIHono<ServerEnv>({
+    defaultHook: (result, c) => {
+      if (!result.success) {
+        return c.json({
+          error: {
+            code: "VALIDATION_FAILED",
+            message: isProdEnv
+              ? "Invalid input."
+              : result.error.issues
+                  .map((i) => `${i.path.join(".")}: ${i.message}`)
+                  .join("; "),
+          },
+        }, 422);
+      }
+    },
+  });
+
+  // ─── Security Guards ──────────────────────────────────────────────
+  if ((config.auth as Record<string, unknown>)?.enableDevKey !== undefined) {
+    throw new Error(
+      "FATAL: auth.enableDevKey has been removed. " +
+      "Use 'bunx @porulle/cli api-key create --scope admin' to generate a real API key. " +
+      "See RFC-050: https://github.com/octalpixel/unified-commerce/blob/main/RFC-050-AUTH-KEY-SCOPING.md",
+    );
+  }
+  if ((config.auth as Record<string, unknown>)?.devKey !== undefined) {
+    throw new Error(
+      "FATAL: auth.devKey has been removed. " +
+      "Use 'bunx @porulle/cli api-key create --scope admin' to generate a real API key. " +
+      "See RFC-050: https://github.com/octalpixel/unified-commerce/blob/main/RFC-050-AUTH-KEY-SCOPING.md",
+    );
+  }
+
+  // exposed for direct unit testing — see test/server-edge-runtime.test.ts
+  // ─── Process Crash Handlers (F4) ─────────────────────────────────────
+  if (isNodeRuntime()) {
+    process.on("unhandledRejection", (reason) => {
+      logger.fatal({ err: reason }, "unhandled promise rejection -- exiting");
+      process.exit(1);
+    });
+
+    process.on("uncaughtException", (err) => {
+      logger.fatal({ err }, "uncaught exception -- exiting");
+      process.exit(1);
+    });
+  } else {
+    logger.info("running on edge runtime — process crash handlers skipped");
+  }
+
+  // ─── Security Response Headers ──────────────────────────────────────
+  app.use("*", async (c, next) => {
+    c.header("X-Content-Type-Options", "nosniff");
+    c.header("X-Frame-Options", "DENY");
+    c.header("Referrer-Policy", "strict-origin-when-cross-origin");
+    c.header("Permissions-Policy", "camera=(), microphone=(), geolocation=()");
+    if (isProdEnv) {
+      c.header("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+    }
+    await next();
+  });
+
+  // ─── Request ID + Logging (F2, F12) ──────────────────────────────────
+  app.use("*", async (c, next) => {
+    const requestId = c.req.header("x-request-id") ?? crypto.randomUUID();
+    c.header("x-request-id", requestId);
+    c.set("requestId", requestId);
+    const child = logger.child({ requestId, method: c.req.method, path: c.req.path });
+    c.set("logger", child);
+
+    const start = performance.now();
+    await next();
+
+    // Sanitize ZodError responses in production.
+    // @hono/zod-openapi returns { success: false, error: { name: "ZodError" } }
+    // which leaks schema details. The library does not respect defaultHook for
+    // this format, so we intercept at the response level.
+    if (isProdEnv && c.res.status >= 400 && c.res.status < 500) {
+      const ct = c.res.headers.get("content-type");
+      if (ct?.includes("json")) {
+        try {
+          const body = await c.res.clone().json();
+          if (body?.error?.name === "ZodError") {
+            c.res = new Response(
+              JSON.stringify({ error: { code: "VALIDATION_FAILED", message: "Invalid input." } }),
+              { status: 422, headers: { "content-type": "application/json" } },
+            );
+          }
+        } catch { /* non-parseable, skip */ }
+      }
+    }
+
+    const duration = Math.round(performance.now() - start);
+
+    child.info({ status: c.res.status, durationMs: duration }, "request completed");
+  });
+
+  // ─── CORS (hardened by default) ──────────────────────────────────────
+  const trustedOrigins = config.auth?.trustedOrigins ?? [];
+  app.use("*", cors({
+    origin: trustedOrigins.length > 0
+      ? trustedOrigins
+      : (process.env.NODE_ENV === "production" ? [] : ["http://localhost:*"]),
+    credentials: true,
+    allowMethods: ["GET", "POST", "PATCH", "PUT", "DELETE", "OPTIONS"],
+    allowHeaders: ["Content-Type", "Authorization", "x-api-key", "x-request-id"],
+    maxAge: 86400,
+  }));
+
+  // ─── CSRF Protection (F14) ──────────────────────────────────────────
+  app.use("/api/*", csrf({
+    origin: trustedOrigins.length > 0
+      ? trustedOrigins
+      : (process.env.NODE_ENV === "production" ? [] : ["http://localhost:*"]),
+  }));
+
+  // ─── Body Size Limit (F6) ──────────────────────────────────────────
+  app.use("*", bodyLimit({
+    maxSize: 1024 * 1024,  // 1 MB default
+    onError: (c) => c.json({
+      error: { code: "PAYLOAD_TOO_LARGE", message: "Request body exceeds 1MB limit." },
+    }, 413),
+  }));
+
+  // ─── Rate Limiting (F1) ──────────────────────────────────────────────
+  // Trust X-Forwarded-For ONLY from a known reverse proxy IP.
+  // Set TRUSTED_PROXY_IP env var to the proxy's IP (e.g., "127.0.0.1").
+  const trustedProxyIp = process.env.TRUSTED_PROXY_IP;
+  const signInEmailRateKeyCache = new WeakMap<Request, string>();
+  const getClientIp = (c: { req: { raw: unknown; header: (name: string) => string | undefined } }): string => {
+    const raw = c.req.raw as { socket?: { remoteAddress?: string } };
+    const remoteAddress = raw.socket?.remoteAddress;
+    // Only trust X-Forwarded-For when the direct connection is from a trusted proxy
+    if (trustedProxyIp && remoteAddress === trustedProxyIp) {
+      const xff = c.req.header("x-forwarded-for")?.split(",")[0]?.trim();
+      if (xff) return xff;
+    }
+    return remoteAddress ?? "unknown";
+  };
+  const keyGenerator = getClientIp;
+
+  app.use("/api/auth/*", rateLimiter({
+    windowMs: 60 * 1000,
+    limit: config.rateLimits?.auth ?? 10,
+    keyGenerator,
+  }));
+
+  app.use("/api/auth/sign-in/email", async (c, next) => {
+    if (c.req.method !== "POST") {
+      await next();
+      return;
+    }
+    try {
+      const payload = await c.req.raw.clone().json() as { email?: unknown };
+      if (typeof payload.email === "string" && payload.email.trim().length > 0) {
+        signInEmailRateKeyCache.set(c.req.raw, hashRateLimitEmail(payload.email));
+      }
+    } catch {
+      // Ignore parse failures; endpoint validation will handle malformed bodies.
+    }
+    await next();
+  });
+
+  app.use("/api/auth/sign-in/email", rateLimiter({
+    windowMs: 15 * 60 * 1000,
+    limit: config.rateLimits?.signInPerEmail ?? 10,
+    keyGenerator: (c) =>
+      signInEmailRateKeyCache.get(c.req.raw) ?? "signin-email:unknown",
+  }));
+
+  app.use("/api/checkout", rateLimiter({
+    windowMs: 60 * 1000,
+    limit: config.rateLimits?.checkout ?? 5,
+    keyGenerator,
+  }));
+
+  app.use("/api/*", rateLimiter({
+    windowMs: 60 * 1000,
+    limit: config.rateLimits?.api ?? 100,
+    keyGenerator,
+  }));
+
+  app.use("*", async (c, next) => {
+    await next();
+    const csp = config.security?.csp;
+    if (!csp) return;
+    // Recommended checkout policy baseline (adjust provider domains):
+    // default-src 'self'; script-src 'self' https://js.stripe.com; frame-src https://js.stripe.com https://hooks.stripe.com; object-src 'none'; base-uri 'self'; frame-ancestors 'none'
+    const routePolicy = Object.entries(csp.perRoute ?? {}).find(([pattern]) =>
+      matchPathPattern(c.req.path, pattern),
+    )?.[1];
+    const policy = routePolicy ?? csp.default;
+    if (policy) {
+      c.header("Content-Security-Policy", policy);
+    }
+  });
+
+  // ─── Custom Middleware ──────────────────────────────────────────────
+  if (config.middleware) {
+    for (const middleware of config.middleware) {
+      app.use("*", middleware);
+    }
+  }
+
+  // ─── Auth ──────────────────────────────────────────────────────────
+  app.use("/api/auth/*", async (c, next) => {
+    if (c.req.path.startsWith("/api/auth/pos/")) {
+      await next();
+      return;
+    }
+    return auth.handler(c.req.raw);
+  });
+
+  app.use("*", authMiddleware(auth, config));
+  app.use("*", async (c, next) => {
+    c.set("auth", auth);
+    await next();
+  });
+
+  // ─── Global Error Handler ─────────────────────────────────────────
+  const isProd = process.env.NODE_ENV === "production";
+  app.onError((err, c) => {
+    const { body, status } = mapErrorToResponse(err, isProd, logger);
+    return c.json(body, status);
+  });
+
+  // ─── Routes ──────────────────────────────────────────────────────────
+  app.route("/api", createRestRoutes(kernel));
+  // Mounted under /api so the auth middleware, rate limiter, CSRF, and
+  // body-limit stack apply (all are scoped to /api/*).
+  app.route("/api/me", createCustomerPortalRoutes(kernel));
+
+  if (config.routes) {
+    config.routes(app, kernel);
+  }
+
+  // OpenAPI spec — disabled in production unless explicitly enabled
+  const exposeSpec = config.exposeOpenApiSpec ?? !isProd;
+  if (exposeSpec) {
+    app.doc("/api/doc", {
+      openapi: "3.0.0",
+      info: {
+        title: "UnifiedCommerce API",
+        version: config.version ?? "0.0.1",
+        description: "Headless commerce engine REST API. Includes core and plugin endpoints.",
+      },
+      tags: [
+        // ── Entity aliases (generated from config.entities[type].alias) ──
+        ...Object.entries(config.entities ?? {})
+          .filter(([, cfg]) => cfg.alias)
+          .map(([type, cfg]) => {
+            const name = cfg.alias!.charAt(0).toUpperCase() + cfg.alias!.slice(1);
+            return { name, description: `Ergonomic alias for ${type} entities — CRUD, variants, attributes` };
+          }),
+        // ── Storefront ──
+        { name: "Catalog", description: "Products, categories, brands, variants, and option types (unified entity API)" },
+        { name: "Search", description: "Full-text search and typeahead suggestions" },
+        { name: "Pricing", description: "Base prices, price modifiers, and customer group pricing" },
+        { name: "Carts", description: "Shopping cart lifecycle — create, add items, update quantities" },
+        { name: "Checkout", description: "Convert a cart into a paid order" },
+        { name: "Promotions", description: "Discount codes, validation, and usage tracking" },
+        // ── Admin ──
+        { name: "Orders", description: "Order management — list, detail, status transitions, fulfillments" },
+        { name: "Customers", description: "Customer profiles, addresses, groups, and order history" },
+        { name: "Inventory", description: "Stock levels, warehouse management, adjustments, and reservations" },
+        { name: "Media", description: "File uploads, entity attachments, and signed URLs" },
+        { name: "Payments", description: "Payment provider webhooks and event processing" },
+        // ── Operations ──
+        { name: "Webhooks", description: "Outbound webhook endpoint registration and management" },
+        { name: "Audit", description: "Immutable audit log — who changed what and when" },
+        { name: "Admin Jobs", description: "Background job queue — view failed jobs and retry" },
+      ],
+    });
+
+    // Serve enriched spec with x-tagGroups vendor extension (Scalar/Redocly sidebar grouping)
+    const aliasTags = Object.values(config.entities ?? {})
+      .filter((cfg) => cfg.alias)
+      .map((cfg) => cfg.alias!.charAt(0).toUpperCase() + cfg.alias!.slice(1));
+    const tagGroups = [
+      ...(aliasTags.length > 0 ? [{ name: "Quick Access", tags: aliasTags }] : []),
+      { name: "Storefront", tags: ["Catalog", "Search", "Pricing", "Carts", "Checkout", "Promotions"] },
+      { name: "Admin", tags: ["Orders", "Customers", "Inventory", "Media", "Payments"] },
+      { name: "Operations", tags: ["Webhooks", "Audit", "Admin Jobs"] },
+    ];
+    app.get("/api/doc-ext", (c) => {
+      const spec = app.getOpenAPIDocument({ openapi: "3.0.0", info: { title: "UnifiedCommerce API", version: config.version ?? "0.0.1" } });
+      return c.json({ ...spec, "x-tagGroups": tagGroups });
+    });
+  } else {
+    app.get("/api/doc", (c) => c.json({ error: { code: "NOT_FOUND", message: "Not found." } }, 404));
+  }
+
+  // ─── Job Queue ───────────────────────────────────────────────────────
+  // Background job processing: webhook delivery, stale-job reaper, scheduled work.
+  //
+  // Three runner strategies (inspired by Payload CMS):
+  //   1. autorun: in-process polling (long-running servers)
+  //   2. GET /api/jobs/run: cron endpoint (serverless — Vercel, Cloudflare)
+  //   3. runPendingJobs() export (custom worker process)
+
+  const { runPendingJobs } = await import("../kernel/jobs/runner.js");
+  const { runStaleJobReaper, getJobReapThresholdMs, getJobsReaperIntervalMs } =
+    await import("../kernel/jobs/reaper.js");
+  const taskMap = new Map<string, unknown>();
+  for (const task of config.jobs?.tasks ?? []) {
+    const t = task as { slug?: string; name?: string };
+    taskMap.set(t.slug ?? t.name ?? "", task);
+  }
+
+  const jobLogger = {
+    info: (msg: string, data?: unknown) => logger.info(data != null ? { data } : {}, msg),
+    warn: (msg: string, data?: unknown) => logger.warn(data != null ? { data } : {}, msg),
+    error: (msg: string, data?: unknown) => logger.error(data != null ? { data } : {}, msg),
+  };
+
+  let lastStaleJobReaperAt = 0;
+
+  const maybeRunStaleJobReaper = async () => {
+    const interval = getJobsReaperIntervalMs();
+    const now = Date.now();
+    if (now - lastStaleJobReaperAt < interval) return;
+    lastStaleJobReaperAt = now;
+    try {
+      await runStaleJobReaper(
+        kernel.database.db as DrizzleDatabase,
+        getJobReapThresholdMs(),
+        jobLogger,
+      );
+    } catch (err) {
+      logger.error({ err }, "Stale job reaper failed");
+    }
+  };
+
+  const runJobs = async (queue?: string, limit?: number) => {
+    await maybeRunStaleJobReaper();
+    return runPendingJobs({
+      db: kernel.database.db as DrizzleDatabase,
+      tasks: taskMap as Parameters<typeof runPendingJobs>[0]["tasks"],
+      queue: queue ?? "default",
+      limit: limit ?? 10,
+      logger: jobLogger,
+      services: kernel.services as Parameters<typeof runPendingJobs>[0]["services"],
+    });
+  };
+
+  // Strategy 1: Built-in cron endpoint for serverless deployments.
+  // Point Vercel Cron or Cloudflare Cron Trigger at GET /api/jobs/run
+  // Optional query params: ?queue=emails&limit=20
+  app.get("/api/jobs/run", async (c) => {
+    // Always require admin — cron triggers must authenticate
+    const actor = c.get("actor") as { permissions?: string[] } | null;
+    if (!actor?.permissions?.includes("*:*")) {
+      return c.json({ error: { code: "FORBIDDEN", message: "Job runner requires admin access" } }, 403);
+    }
+
+    const queue = c.req.query("queue") ?? "default";
+    const limit = parseInt(c.req.query("limit") ?? "10", 10);
+
+    try {
+      const result = await runJobs(queue, limit);
+      return c.json({ data: result });
+    } catch (err) {
+      logger.error({ err }, "Job runner endpoint failed");
+      return c.json({ error: { code: "INTERNAL_ERROR", message: "Job processing failed" } }, 500);
+    }
+  });
+
+  // Strategy 2: In-process polling for long-running servers (ECS, Cloud Run, Docker).
+  // Enable via config.jobs.autorun.enabled = true
+  if (config.jobs?.autorun?.enabled) {
+    const intervalMs = config.jobs.autorun.intervalMs ?? 10_000;
+
+    const jobInterval = setInterval(async () => {
+      try {
+        await runJobs();
+      } catch (err) {
+        logger.error({ err }, "Job runner iteration failed");
+      }
+    }, intervalMs);
+
+    const cleanup = () => clearInterval(jobInterval);
+    process.on("SIGTERM", cleanup);
+    process.on("SIGINT", cleanup);
+
+    logger.info({ intervalMs }, "Job queue autorun started (in-process polling)");
+  } else {
+    logger.info(
+      "Job queue autorun disabled. Use GET /api/jobs/run for serverless cron, " +
+      "or set config.jobs.autorun.enabled = true for in-process polling.",
+    );
+  }
+
+  const dispatchFetch = app.fetch.bind(app);
+  app.fetch = ((input: RequestInfo | URL, env?: unknown, executionCtx?: unknown) => {
+    const req = input instanceof Request ? input : new Request(input);
+    const rewritten = rewriteCommerceAliasRequest(req, config.entities);
+    return dispatchFetch(rewritten as Request, env as never, executionCtx as never);
+  }) as typeof app.fetch;
+
+  return { app, kernel, logger, commerce };
+}

package/src/runtime/shutdown.ts

@@ -0,0 +1,43 @@
+import type { Logger } from "./logger.js";
+
+/**
+ * Sets up graceful shutdown handlers for SIGTERM and SIGINT.
+ *
+ * On signal:
+ * 1. Stops accepting new connections
+ * 2. Runs cleanup (close DB pool, flush logs)
+ * 3. Force-exits after timeout if cleanup hangs
+ */
+export function setupGracefulShutdown(opts: {
+  cleanup: () => Promise<void>;
+  logger: Logger;
+  timeoutMs?: number;
+}): void {
+  const { cleanup, logger, timeoutMs = 30_000 } = opts;
+  let isShuttingDown = false;
+
+  async function shutdown(signal: string) {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+
+    logger.info({ signal }, "shutdown signal received, draining connections");
+
+    const forceTimer = setTimeout(() => {
+      logger.error("shutdown timeout exceeded, forcing exit");
+      process.exit(1);
+    }, timeoutMs);
+    forceTimer.unref();
+
+    try {
+      await cleanup();
+      logger.info("graceful shutdown complete");
+      process.exit(0);
+    } catch (err) {
+      logger.error({ err }, "error during shutdown");
+      process.exit(1);
+    }
+  }
+
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+}

package/src/runtime/url-alias-rewrite.ts

@@ -0,0 +1,40 @@
+import type { CommerceConfig } from "../config/types.js";
+
+export function rewriteCommerceAliasRequest(
+  request: Request,
+  entities: CommerceConfig["entities"] | undefined,
+): Request {
+  const url = new URL(request.url);
+  const path = url.pathname;
+
+  for (const [entityType, entityConfig] of Object.entries(entities ?? {})) {
+    if (!entityConfig.alias) continue;
+    const alias = entityConfig.alias;
+    const prefix = `/api/${alias}`;
+    if (path === prefix) {
+      url.pathname = "/api/catalog/entities";
+      if (request.method === "GET") {
+        url.searchParams.set("type", entityType);
+      }
+      return new Request(url.toString(), request);
+    }
+    if (path.startsWith(`${prefix}/`)) {
+      url.pathname = path.replace(prefix, "/api/catalog/entities");
+      return new Request(url.toString(), request);
+    }
+  }
+
+  for (const [shortcut, target] of [["categories", "catalog/categories"], ["brands", "catalog/brands"]] as const) {
+    const prefix = `/api/${shortcut}`;
+    if (path === prefix) {
+      url.pathname = `/api/${target}`;
+      return new Request(url.toString(), request);
+    }
+    if (path.startsWith(`${prefix}/`)) {
+      url.pathname = path.replace(prefix, `/api/${target}`);
+      return new Request(url.toString(), request);
+    }
+  }
+
+  return request;
+}

package/src/test-utils/create-pglite-adapter.ts

@@ -0,0 +1,129 @@
+/**
+ * PGlite-backed test adapter for real PostgreSQL behavior in tests.
+ *
+ * Creates an in-memory PGlite (WASM PostgreSQL) instance, pushes the
+ * core Drizzle schema programmatically via drizzle-kit/api, and provides
+ * a cleanup function to reset data between tests.
+ *
+ * Benefits over in-memory repository doubles:
+ * - Real SQL execution (Drizzle query generation)
+ * - PostgreSQL type coercion and constraint enforcement
+ * - Real transaction rollback semantics
+ * - Production parity for query edge cases
+ */
+
+import { PGlite } from "@electric-sql/pglite";
+import { drizzle } from "drizzle-orm/pglite";
+import { sql } from "drizzle-orm";
+import { createRequire } from "node:module";
+import type { DatabaseAdapter } from "../kernel/database/adapter.js";
+import { getSchema } from "../kernel/database/migrate.js";
+import { ensureDefaultOrg } from "../auth/org.js";
+
+// Single barrel import --- includes all core modules + auth tables
+import * as fullSchema from "../kernel/database/schema.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+
+// drizzle-kit/api uses CJS internally; createRequire provides ESM compat.
+const require = createRequire(import.meta.url);
+
+/**
+ * Pushes the core Drizzle schema to the database using drizzle-kit/api.
+ *
+ * drizzle-kit introspects the live database via information_schema, diffs
+ * against the pgTable definitions, and generates the minimal DDL needed.
+ * Typed as DrizzleDatabase (our concrete schema type) to avoid the
+ * PGlite → PgDatabase<HKT> invariance cast — drizzle-kit accepts any
+ * Drizzle instance at runtime regardless of the schema generic.
+ */
+async function pushCoreSchema(db: DrizzleDatabase): Promise<void> {
+  const coreSchema = getSchema();
+  const drizzleKit = require("drizzle-kit/api") as {
+    pushSchema(
+      imports: Record<string, unknown>,
+      drizzleInstance: DrizzleDatabase,
+    ): Promise<{ apply: () => Promise<void> }>;
+  };
+  const { apply } = await drizzleKit.pushSchema(coreSchema, db);
+  await apply();
+}
+
+/**
+ * Creates a PGlite-backed database adapter for testing.
+ *
+ * Each call creates a new isolated PGlite instance with its own
+ * in-memory database. Core schema is pushed once during initialization.
+ *
+ * @returns A promise resolving to an object containing:
+ *   - adapter: The DatabaseAdapter for use with createKernel
+ *   - db: The Drizzle ORM instance for direct queries
+ *   - cleanup: Function to truncate all tables (call between tests)
+ */
+export async function createPGliteTestAdapter(): Promise<{
+  adapter: DatabaseAdapter;
+  db: DrizzleDatabase;
+  cleanup: () => Promise<void>;
+}> {
+  // Create in-memory PGlite instance
+  const pg = new PGlite();
+
+  // Wrap with Drizzle ORM first (pushSchema needs the Drizzle instance)
+  const db = drizzle(pg, { schema: fullSchema });
+
+  // Push core schema via drizzle-kit/api (no migration files needed)
+  // PgliteDatabase<Schema> and DrizzleDatabase share the same Schema type;
+  // the HKT parameter differs (PgliteQueryResultHKT vs PgQueryResultHKT)
+  // but drizzle-kit's pushSchema doesn't use it at runtime.
+  await pushCoreSchema(db as DrizzleDatabase);
+
+  // Ensure the default organization exists for all tests
+  await ensureDefaultOrg(db);
+
+  /**
+   * PGlite-compatible transaction wrapper.
+   *
+   * Drizzle's transaction() method can hang with PGlite due to how
+   * the adapter manages transaction state. This implementation uses
+   * manual BEGIN/COMMIT control which works more reliably.
+   */
+  async function transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+    await pg.exec("BEGIN");
+    try {
+      const result = await fn(db);
+      await pg.exec("COMMIT");
+      return result;
+    } catch (error) {
+      await pg.exec("ROLLBACK");
+      throw error;
+    }
+  }
+
+  const adapter: DatabaseAdapter = {
+    provider: "postgresql",
+    db,
+    transaction,
+  };
+
+  /**
+   * Cleanup function to reset data between tests.
+   * Truncates all tables in reverse dependency order with CASCADE.
+   */
+  async function cleanup(): Promise<void> {
+    await db.execute(sql`
+      DO $$ DECLARE
+        r RECORD;
+      BEGIN
+        FOR r IN (
+          SELECT tablename FROM pg_tables
+          WHERE schemaname = 'public'
+        ) LOOP
+          EXECUTE 'TRUNCATE TABLE ' || quote_ident(r.tablename) || ' CASCADE';
+        END LOOP;
+      END $$;
+    `);
+    // Re-insert default org after truncation (CASCADE wipes it)
+    await ensureDefaultOrg(db);
+  }
+
+  return { adapter, db, cleanup };
+}