@porulle/core 0.1.0 → 0.5.0

package/src/interfaces/rest/parse-json.ts

@@ -0,0 +1,81 @@
+import type { Context } from "hono";
+import type { z } from "zod";
+
+/**
+ * A single field-level validation failure. Shape is stable across the API
+ * so clients can bind form errors without ad-hoc parsing.
+ */
+export interface ValidationIssue {
+  /** Dotted path to the offending field (e.g. "address.zip"). Empty for whole-body errors. */
+  path: string;
+  /** Human-readable message. */
+  message: string;
+  /** Machine code (zod issue code, or "invalid_json"). */
+  code: string;
+}
+
+/** The error envelope's optional `details` payload. */
+export interface ErrorDetails {
+  issues?: ValidationIssue[];
+  [key: string]: unknown;
+}
+
+/**
+ * Build the uniform error envelope `{ error: { code, message, details? } }`.
+ * `details` is omitted when not provided so existing responses are unchanged.
+ */
+export function err(
+  c: Context,
+  status: 400 | 401 | 403 | 404 | 409 | 422 | 500,
+  code: string,
+  message: string,
+  details?: ErrorDetails,
+): Response {
+  return c.json(
+    { error: { code, message, ...(details ? { details } : {}) } },
+    status,
+  );
+}
+
+/**
+ * Parse and validate a request body against a Zod schema.
+ *
+ * Returns the typed value on success, or a 422 `Response` (the uniform error
+ * envelope, with `details.issues[]` populated from the Zod failure) that the
+ * caller returns as-is. Replaces the unsafe `(await c.req.json()) as T` cast.
+ *
+ * ```ts
+ * const body = await parseJson(c, MyBodySchema);
+ * if (body instanceof Response) return body;
+ * // body is z.infer<typeof MyBodySchema>
+ * ```
+ */
+export async function parseJson<S extends z.ZodType>(
+  c: Context,
+  schema: S,
+): Promise<z.infer<S> | Response> {
+  let raw: unknown;
+  try {
+    raw = await c.req.json();
+  } catch {
+    return err(c, 422, "VALIDATION_FAILED", "Request body must be valid JSON.", {
+      issues: [{ path: "", message: "Request body must be valid JSON.", code: "invalid_json" }],
+    });
+  }
+
+  const result = schema.safeParse(raw);
+  if (!result.success) {
+    const issues: ValidationIssue[] = result.error.issues.map((issue) => ({
+      path: issue.path.map(String).join("."),
+      message: issue.message,
+      code: issue.code,
+    }));
+    const first = issues[0];
+    const message = first
+      ? `${first.path ? `${first.path}: ` : ""}${first.message}`
+      : "Validation failed.";
+    return err(c, 422, "VALIDATION_FAILED", message, { issues });
+  }
+
+  return result.data;
+}

package/src/interfaces/rest/routes/catalog.ts

@@ -35,6 +35,8 @@ import {
   updateEntityRoute,
   setEntityAttributesRoute,
   createCategoryRoute,
+  archiveCategoryRoute,
+  restoreCategoryRoute,
   updateCategoryRoute,
   createBrandRoute,
   updateBrandRoute,
@@ -280,7 +282,11 @@ export function catalogRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listCategoriesRoute, async (c) => {
-    const result = await kernel.services.catalog.listCategories({ actor: c.get("actor"), tx: null, requestId: "" });
+    const includeArchived = c.req.query("includeArchived") === "true";
+    const result = await kernel.services.catalog.listCategories(
+      { actor: c.get("actor"), tx: null, requestId: "" },
+      { includeArchived },
+    );
     if (!result.ok)
       return c.json(
         mapErrorToResponse(result.error),
@@ -289,6 +295,20 @@ export function catalogRoutes(kernel: Kernel) {
     return c.json({ data: result.value });
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(archiveCategoryRoute, async (c) => {
+    const result = await kernel.services.catalog.archiveCategory(c.req.param("categoryId"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(restoreCategoryRoute, async (c) => {
+    const result = await kernel.services.catalog.restoreCategory(c.req.param("categoryId"), c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(createCategoryRoute, async (c) => {
     const result = await kernel.services.catalog.createCategory(

package/src/interfaces/rest/routes/customers.ts

@@ -2,12 +2,17 @@ import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
 import {
   listCustomersRoute,
+  createCustomerRoute,
   getCustomerRoute,
   updateCustomerRoute,
   getCustomerOrdersRoute,
   getCustomerAddressesRoute,
+  listInteractionsRoute,
+  createInteractionRoute,
+  updateInteractionRoute,
+  deleteInteractionRoute,
 } from "../schemas/customers.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus, parsePagination, requirePerm } from "../utils.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, parsePagination, parseInclude, requirePerm } from "../utils.js";
 
 export function customerRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
@@ -37,6 +42,14 @@ export function customerRoutes(kernel: Kernel) {
     });
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createCustomerRoute, async (c) => {
+    const body = c.req.valid("json");
+    const result = await kernel.services.customers.createWalkIn(body, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getCustomerRoute, async (c) => {
     const { id } = c.req.valid("param");
@@ -58,7 +71,10 @@ export function customerRoutes(kernel: Kernel) {
     for (const [k, v] of Object.entries(body)) {
       if (v !== undefined) updates[k] = v;
     }
-    const result = await kernel.services.customers.update(id, updates, actor);
+    const replaceMetadata = c.req.query("metadataReplace") === "true";
+    const result = await kernel.services.customers.update(id, updates, actor, undefined, {
+      replaceMetadata,
+    });
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     return c.json({ data: result.value });
   });
@@ -69,13 +85,22 @@ export function customerRoutes(kernel: Kernel) {
     const actor = c.get("actor");
     const { page, limit } = parsePagination(c.req.query());
     const status = c.req.query("status") || undefined;
+    const includeTotals = parseInclude(c.req.query("include")).has("totals");
 
     const result = await kernel.services.orders.listByCustomer(
       id,
-      { page, limit, ...(status ? { status } : {}) },
+      { page, limit, ...(status ? { status } : {}), ...(includeTotals ? { includeTotals: true } : {}) },
       actor,
     );
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    if (includeTotals) {
+      // Wrapped shape: { data: { items, totals } } (+ pagination meta).
+      return c.json({
+        data: { items: result.value.items, totals: result.value.totals },
+        meta: { pagination: result.value.pagination },
+      });
+    }
+    // Default (back-compat): flat array.
     return c.json({ data: result.value.items, meta: { pagination: result.value.pagination } });
   });
 
@@ -96,5 +121,41 @@ export function customerRoutes(kernel: Kernel) {
     return c.json({ data: addressResult.value });
   });
 
+  // ─── Customer interactions (#3) ──────────────────────────────────────────
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listInteractionsRoute, async (c) => {
+    const { id } = c.req.valid("param");
+    const result = await kernel.services.customers.listInteractions(id, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createInteractionRoute, async (c) => {
+    const { id } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const result = await kernel.services.customers.createInteraction(id, body, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateInteractionRoute, async (c) => {
+    const { id, iid } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const result = await kernel.services.customers.updateInteraction(id, iid, body, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteInteractionRoute, async (c) => {
+    const { id, iid } = c.req.valid("param");
+    const result = await kernel.services.customers.deleteInteraction(id, iid, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: { deleted: true } });
+  });
+
   return router;
 }

package/src/interfaces/rest/routes/inventory.ts

@@ -51,9 +51,11 @@ export function inventoryRoutes(kernel: Kernel) {
   // @ts-expect-error -- openapi handler union return type
   router.openapi(inventoryAdjustRoute, async (c) => {
     const body = c.req.valid("json");
-    const result = await kernel.services.inventory.adjust(body, c.get("actor"));
+    const result = await kernel.services.inventory.adjustDetailed(body, c.get("actor"));
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
-    return c.json({ data: result.value });
+    const { level, before, after, delta, movementId } = result.value;
+    // Additive: level fields (back-compat) plus before/after/delta/movementId.
+    return c.json({ data: { ...level, before, after, delta, movementId } });
   });
 
   // @ts-expect-error -- openapi handler union return type

package/src/interfaces/rest/routes/media.ts

@@ -11,6 +11,13 @@ export function mediaRoutes(kernel: Kernel) {
   router.use("/upload", requirePerm("media:write"));
 
   router.post("/upload", async (c) => {
+    // No storage configured (the default no-op adapter) → media is disabled.
+    if (kernel.config.storage?.providerId === "noop") {
+      return c.json({
+        error: { code: "storage_not_supported", message: "Media storage is not configured." },
+      }, 501);
+    }
+
     const body = await c.req.parseBody();
     const file = body.file as File;
 

package/src/interfaces/rest/routes/orders.ts

@@ -1,6 +1,6 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Kernel } from "../../../runtime/kernel.js";
-import { changeOrderStatusRoute, listOrdersRoute, getOrderRoute, getOrderFulfillmentsRoute } from "../schemas/orders.js";
+import { changeOrderStatusRoute, listOrdersRoute, orderLookupRoute, getOrderRoute, getOrderFulfillmentsRoute } from "../schemas/orders.js";
 import { type AppEnv, isUUID, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
 
 export function orderRoutes(kernel: Kernel) {
@@ -28,6 +28,26 @@ export function orderRoutes(kernel: Kernel) {
     });
   });
 
+  // Registered before getOrderRoute so "/lookup" isn't matched as an idOrNumber.
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(orderLookupRoute, async (c) => {
+    const q = c.req.query("q") ?? "";
+    const fromRaw = c.req.query("from");
+    const toRaw = c.req.query("to");
+    const opts: { from?: Date; to?: Date } = {};
+    if (fromRaw) {
+      const d = new Date(fromRaw);
+      if (!Number.isNaN(d.getTime())) opts.from = d;
+    }
+    if (toRaw) {
+      const d = new Date(toRaw);
+      if (!Number.isNaN(d.getTime())) opts.to = d;
+    }
+    const result = await kernel.services.orders.lookup(q, opts, c.get("actor"));
+    if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    return c.json({ data: result.value });
+  });
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getOrderRoute, async (c) => {
     const idOrNumber = c.req.param("idOrNumber");

package/src/interfaces/rest/routes/promotions.ts

@@ -1,7 +1,7 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { rateLimiter } from "hono-rate-limiter";
 import type { Kernel } from "../../../runtime/kernel.js";
-import { createPromotionRoute, validatePromotionRoute, deactivatePromotionRoute, listPromotionsRoute } from "../schemas/promotions.js";
+import { createPromotionRoute, updatePromotionRoute, validatePromotionRoute, deactivatePromotionRoute, listPromotionsRoute } from "../schemas/promotions.js";
 import type { PromotionStatusFilter } from "../../../modules/promotions/service.js";
 import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
 import { resolveOrgId } from "../../../auth/org.js";
@@ -77,6 +77,27 @@ export function promotionRoutes(kernel: Kernel) {
     return c.json({ data: result.value });
   });
 
+  // Guard inline (not via router.use("/:id")) because a "/:id" middleware
+  // would also match single-segment routes like POST /validate.
+  router.use("/:id", async (c, next) => {
+    if (c.req.method !== "PATCH") return next();
+    return requirePerm("promotions:manage")(c, next);
+  });
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (200 | 400 | 404 | 422). The route definition
+  // documents the contract; the handler returns dynamic status.
+  router.openapi(updatePromotionRoute, async (c) => {
+    const body = c.req.valid("json");
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+    const result = await kernel.services.promotions.update(orgId, c.req.param("id"), body, actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
+
   router.use("/:id/deactivate", requirePerm("promotions:manage"));
 
   // @ts-expect-error -- openapi() enforces strict response typing but our handler

package/src/interfaces/rest/schemas/catalog.ts

@@ -108,7 +108,12 @@ export const listCategoriesRoute = createRoute({
   method: "get",
   path: "/categories",
   tags: ["Catalog"],
-  summary: "List all categories",
+  summary: "List categories (active by default)",
+  request: {
+    query: z.object({
+      includeArchived: z.string().optional().openapi({ example: "true" }),
+    }),
+  },
   responses: {
     200: { content: { "application/json": { schema: DataResponse } }, description: "Success" },
   },
@@ -342,6 +347,30 @@ export const updateCategoryRoute = createRoute({
   },
 });
 
+export const archiveCategoryRoute = createRoute({
+  method: "post",
+  path: "/categories/{categoryId}/archive",
+  tags: ["Catalog"],
+  summary: "Archive a category (soft delete)",
+  request: { params: CategoryIdParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Archived" },
+    ...errorResponses,
+  },
+});
+
+export const restoreCategoryRoute = createRoute({
+  method: "post",
+  path: "/categories/{categoryId}/restore",
+  tags: ["Catalog"],
+  summary: "Restore an archived category",
+  request: { params: CategoryIdParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Restored" },
+    ...errorResponses,
+  },
+});
+
 export const createBrandRoute = createRoute({
   method: "post",
   path: "/brands",

package/src/interfaces/rest/schemas/customers.ts

@@ -1,6 +1,34 @@
 import { z, createRoute } from "@hono/zod-openapi";
 import { errorResponses } from "./shared.js";
 
+export const CreateCustomerBodySchema = z.object({
+  // Optional: omit for walk-in / POS customers who never log in. A synthetic
+  // anonymous_<uuid> id is generated and metadata.walkIn is set.
+  userId: z.string().optional().openapi({ example: "user_123" }),
+  firstName: z.string().optional().openapi({ example: "Nimali" }),
+  lastName: z.string().optional().openapi({ example: "Perera" }),
+  phone: z.string().optional().openapi({ example: "+94 77 412 6601" }),
+  email: z.string().optional().openapi({ example: "nimali@example.com" }),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateCustomerBody");
+
+export const createCustomerRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Customers"],
+  summary: "Create a customer (supports walk-in / userId-less)",
+  request: {
+    body: { content: { "application/json": { schema: CreateCustomerBodySchema } }, required: true },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } },
+      description: "Customer created.",
+    },
+    ...errorResponses,
+  },
+});
+
 export const listCustomersRoute = createRoute({
   method: "get",
   path: "/",
@@ -153,3 +181,74 @@ export const getCustomerAddressesRoute = createRoute({
     ...errorResponses,
   },
 });
+
+// ─── Customer interactions (#3) ──────────────────────────────────────────────
+
+export const InteractionKindEnum = z.enum([
+  "visit", "call", "inquiry", "fitting", "follow_up", "message",
+]);
+
+export const CreateInteractionBodySchema = z.object({
+  kind: InteractionKindEnum.openapi({ example: "visit" }),
+  notes: z.string().min(1).openapi({ example: "Asked about the navy blazer in M." }),
+  relatedEntityId: z.string().uuid().nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateInteractionBody");
+
+export const UpdateInteractionBodySchema = CreateInteractionBodySchema.partial().openapi("UpdateInteractionBody");
+
+const InteractionDataResponse = z.object({ data: z.record(z.string(), z.unknown()) });
+
+export const listInteractionsRoute = createRoute({
+  method: "get",
+  path: "/{id}/interactions",
+  tags: ["Customers"],
+  summary: "List a customer's interactions",
+  request: { params: z.object({ id: z.string().uuid() }) },
+  responses: {
+    200: { content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } }, description: "Interactions" },
+    ...errorResponses,
+  },
+});
+
+export const createInteractionRoute = createRoute({
+  method: "post",
+  path: "/{id}/interactions",
+  tags: ["Customers"],
+  summary: "Log a customer interaction",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+    body: { content: { "application/json": { schema: CreateInteractionBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: InteractionDataResponse } }, description: "Interaction logged" },
+    ...errorResponses,
+  },
+});
+
+export const updateInteractionRoute = createRoute({
+  method: "patch",
+  path: "/{id}/interactions/{iid}",
+  tags: ["Customers"],
+  summary: "Edit a customer interaction",
+  request: {
+    params: z.object({ id: z.string().uuid(), iid: z.string().uuid() }),
+    body: { content: { "application/json": { schema: UpdateInteractionBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: InteractionDataResponse } }, description: "Interaction updated" },
+    ...errorResponses,
+  },
+});
+
+export const deleteInteractionRoute = createRoute({
+  method: "delete",
+  path: "/{id}/interactions/{iid}",
+  tags: ["Customers"],
+  summary: "Delete a customer interaction",
+  request: { params: z.object({ id: z.string().uuid(), iid: z.string().uuid() }) },
+  responses: {
+    200: { content: { "application/json": { schema: z.object({ data: z.object({ deleted: z.literal(true) }) }) } }, description: "Deleted" },
+    ...errorResponses,
+  },
+});

package/src/interfaces/rest/schemas/orders.ts

@@ -44,6 +44,27 @@ export const listOrdersRoute = createRoute({
   },
 });
 
+export const orderLookupRoute = createRoute({
+  method: "get",
+  path: "/lookup",
+  tags: ["Orders"],
+  summary: "Fuzzy order lookup (receipt-less return / support)",
+  description: "Find orders by order number, customer email/name/phone, or walk-in label. Minimum query length is 3 characters.",
+  request: {
+    query: z.object({
+      q: z.string().optional().openapi({ example: "Perera" }),
+      from: z.string().optional().openapi({ example: "2026-01-01" }),
+      to: z.string().optional().openapi({ example: "2026-12-31" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.object({ items: z.array(z.record(z.string(), z.unknown())), hint: z.string().optional() }) }) } },
+      description: "Lookup results",
+    },
+  },
+});
+
 export const getOrderRoute = createRoute({
   method: "get",
   path: "/{idOrNumber}",

package/src/interfaces/rest/schemas/promotions.ts

@@ -3,9 +3,16 @@ import { ErrorSchema, errorResponses, UuidParamSchema } from "./shared.js";
 
 // ─── Request Schemas ────────────────────────────────────────────────────────
 
-import { CreatePromotionBodySchema } from "../../../modules/promotions/schemas.js";
+import {
+  CreatePromotionBodySchema,
+  UpdatePromotionBodySchema as UpdatePromotionBodySchemaBase,
+} from "../../../modules/promotions/schemas.js";
 export { CreatePromotionBodySchema };
 
+export const UpdatePromotionBodySchema = UpdatePromotionBodySchemaBase.openapi(
+  "UpdatePromotionRequest",
+);
+
 export const ValidatePromotionBodySchema = z.object({
   code: z.string().openapi({ example: "SUMMER10" }),
   currency: z.string().length(3).openapi({ example: "USD" }),
@@ -98,6 +105,30 @@ export const validatePromotionRoute = createRoute({
   },
 });
 
+export const updatePromotionRoute = createRoute({
+  method: "patch",
+  path: "/{id}",
+  tags: ["Promotions"],
+  summary: "Edit a promotion",
+  description: "Update any subset of a promotion's fields (name, code, type, value, validity dates, scope, metadata, isActive). Validated the same way create is.",
+  request: {
+    params: PromotionIdParam,
+    body: {
+      content: {
+        "application/json": { schema: UpdatePromotionBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: PromotionResponseSchema } },
+      description: "Promotion updated.",
+    },
+    ...errorResponses,
+  },
+});
+
 export const deactivatePromotionRoute = createRoute({
   method: "post",
   path: "/{id}/deactivate",

package/src/interfaces/rest/schemas/shared.ts

@@ -2,10 +2,19 @@ import { z } from "@hono/zod-openapi";
 
 // ─── Error Response ──────────────────────────────────────────────────────────
 
+export const ValidationIssueSchema = z.object({
+  path: z.string().openapi({ example: "cartId" }),
+  message: z.string().openapi({ example: "Invalid uuid" }),
+  code: z.string().openapi({ example: "invalid_string" }),
+}).openapi("ValidationIssue");
+
 export const ErrorSchema = z.object({
   error: z.object({
     code: z.string().openapi({ example: "VALIDATION_FAILED" }),
     message: z.string().openapi({ example: "cartId: Invalid uuid" }),
+    details: z.object({
+      issues: z.array(ValidationIssueSchema).optional(),
+    }).optional(),
   }),
 }).openapi("Error");
 

package/src/kernel/database/adapter.ts

@@ -16,6 +16,69 @@ export interface DatabaseConnectionFactoryInput {
   adapter: DatabaseAdapter;
 }
 
+/**
+ * Marker used to retrieve the raw, un-normalized driver from a wrapped db.
+ * Tools that drive the driver directly (drizzle-kit's `pushSchema`, which
+ * relies on the native `db.execute()` shape) must unwrap first via {@link unwrapDb}.
+ */
+const RAW_DB = Symbol.for("porulle.rawDb");
+
+/**
+ * Return the raw driver behind a db normalized by {@link normalizeExecuteShape}.
+ * If `db` isn't wrapped, it is returned unchanged. Use before handing a db to
+ * drizzle-kit (`pushSchema`/introspection), which needs the native result shape.
+ */
+export function unwrapDb<T>(db: T): T {
+  if (db != null && typeof db === "object") {
+    const raw = (db as Record<symbol, unknown>)[RAW_DB];
+    if (raw) return raw as T;
+  }
+  return db;
+}
+
+/**
+ * Normalize `db.execute()` so it returns a row array regardless of the
+ * underlying driver. postgres-js returns the rows directly, while neon-http
+ * and node-postgres (and PGlite) return `{ rows, command, rowCount }`.
+ * Without this, raw-SQL code that destructures the result as an array breaks
+ * on the `{ rows }` drivers. We intercept only `execute`; every other method
+ * is bound to the real driver instance so its internals are untouched.
+ */
+function normalizeExecuteShape<T extends object>(db: T): T {
+  return new Proxy(db, {
+    get(target, prop, receiver) {
+      if (prop === RAW_DB) return target;
+      if (prop === "execute") {
+        const orig = Reflect.get(target, prop, receiver);
+        if (typeof orig !== "function") return orig;
+        return async (...args: unknown[]) => {
+          const result = await (orig as (...a: unknown[]) => Promise<unknown>).apply(target, args);
+          if (
+            result != null &&
+            typeof result === "object" &&
+            !Array.isArray(result) &&
+            Array.isArray((result as { rows?: unknown }).rows)
+          ) {
+            return (result as { rows: unknown[] }).rows;
+          }
+          return result;
+        };
+      }
+      const value = Reflect.get(target, prop, target);
+      // Bind methods to the real instance so drizzle's internals (incl. any
+      // private fields) are never accessed through the proxy.
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
 export function createDatabaseConnection(input: DatabaseConnectionFactoryInput): DatabaseAdapter {
-  return input.adapter;
+  const adapter = input.adapter;
+  return {
+    provider: adapter.provider,
+    db: normalizeExecuteShape(adapter.db as object),
+    transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+      return adapter.transaction((tx) => fn(normalizeExecuteShape(tx as object)));
+    },
+  };
 }