@porulle/core 0.8.0 → 0.10.0

package/src/interfaces/rest/routes/admin/staff.ts

@@ -55,6 +55,35 @@ export function adminStaffRoutes(kernel: Kernel) {
     );
   }
 
+  const BUILTIN_ROLE_RANK: Record<string, number> = {
+    owner: 3,
+    admin: 2,
+  };
+  const CUSTOM_ROLE_RANK = 1;
+
+  function roleRank(role: string): number {
+    return BUILTIN_ROLE_RANK[role] ?? CUSTOM_ROLE_RANK;
+  }
+
+  function canGrantRole(actorRole: string, targetRole: string): boolean {
+    return roleRank(actorRole) >= roleRank(targetRole);
+  }
+
+  function insufficientPrivilege(
+    c: { json: (d: unknown, s: number) => unknown },
+    targetRole: string,
+  ) {
+    return c.json(
+      {
+        error: {
+          code: "FORBIDDEN",
+          message: `Cannot assign role "${targetRole}": your role does not have sufficient privilege.`,
+        },
+      },
+      403,
+    );
+  }
+
   async function countOwners(orgId: string): Promise<number> {
     const rows = await db
       .select({ id: member.id })
@@ -83,9 +112,11 @@ export function adminStaffRoutes(kernel: Kernel) {
   // @ts-expect-error -- openapi handler union return type
   router.openapi(createStaffRoute, async (c) => {
     const body = c.req.valid("json") as { userId: string; role: string };
-    const orgId = resolveOrgId(c.get("actor"));
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
 
     if (!validRoles().has(body.role)) return invalidRole(c, body.role);
+    if (!canGrantRole(actor!.role, body.role)) return insufficientPrivilege(c, body.role);
 
     const users = await db.select().from(user).where(eq(user.id, body.userId));
     if (users.length === 0) {
@@ -160,10 +191,12 @@ export function adminStaffRoutes(kernel: Kernel) {
   // @ts-expect-error -- openapi handler union return type
   router.openapi(updateStaffRoleRoute, async (c) => {
     const body = c.req.valid("json") as { role: string };
-    const orgId = resolveOrgId(c.get("actor"));
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
     const id = c.req.param("id");
 
     if (!validRoles().has(body.role)) return invalidRole(c, body.role);
+    if (!canGrantRole(actor!.role, body.role)) return insufficientPrivilege(c, body.role);
 
     const rows = await db
       .select()
@@ -174,6 +207,10 @@ export function adminStaffRoutes(kernel: Kernel) {
       return c.json({ error: { code: "NOT_FOUND", message: "Staff member not found." } }, 404);
     }
 
+    // SEC-18/R-02: the actor must also outrank (or equal) the target's CURRENT
+    // role, else an admin could demote an owner they do not outrank.
+    if (!canGrantRole(actor!.role, target.role)) return insufficientPrivilege(c, target.role);
+
     if (target.role === "owner" && body.role !== "owner" && (await countOwners(orgId)) <= 1) {
       return c.json(
         { error: { code: "VALIDATION_FAILED", message: "Cannot demote the organization's last owner." } },
@@ -191,7 +228,8 @@ export function adminStaffRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(revokeStaffRoute, async (c) => {
-    const orgId = resolveOrgId(c.get("actor"));
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
     const id = c.req.param("id");
 
     const rows = await db
@@ -203,6 +241,10 @@ export function adminStaffRoutes(kernel: Kernel) {
       return c.json({ error: { code: "NOT_FOUND", message: "Staff member not found." } }, 404);
     }
 
+    // SEC-18/R-02: the actor must outrank (or equal) the target's current role
+    // to revoke it — an admin cannot revoke an owner.
+    if (!canGrantRole(actor!.role, target.role)) return insufficientPrivilege(c, target.role);
+
     if (target.role === "owner" && (await countOwners(orgId)) <= 1) {
       return c.json(
         { error: { code: "VALIDATION_FAILED", message: "Cannot revoke the organization's last owner." } },

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

@@ -21,8 +21,58 @@ import type { AfterHook, BeforeHook, ServiceContainer } from "../../../kernel/ho
 import type { PluginDb } from "../../../kernel/database/plugin-types.js";
 import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
 import { isCommerceError } from "../../../kernel/errors.js";
+import { assertPermission } from "../../../auth/permissions.js";
 import { makeId } from "../../../utils/id.js";
 import type { ShippingAddress } from "../../../modules/shipping/calculator.js";
+import type { Actor } from "../../../auth/types.js";
+
+/**
+ * SEC-07 — resolve the customer profile a checkout order is attributed to.
+ * A self-service actor may ONLY attribute the order to its own customer
+ * profile; only actors with org-level `customers:read` (staff/clienteling) may
+ * name an arbitrary `customerId`. Returns undefined for guests / unresolved
+ * (guest checkout). Exported for unit testing.
+ */
+export async function resolveCheckoutCustomerUuid(
+  customers: Kernel["services"]["customers"],
+  actor: Actor | null,
+  customerId: string | undefined,
+): Promise<string | undefined> {
+  const actorUserId = actor?.userId;
+  let canActForOthers = false;
+  if (actorUserId) {
+    try {
+      assertPermission(actor, "customers:read");
+      canActForOthers = true;
+    } catch {
+      canActForOthers = false;
+    }
+  }
+
+  if (customerId) {
+    const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (uuidRe.test(customerId)) {
+      const byId = await customers.getById(customerId, actor);
+      // Honor a profile UUID only if it is the actor's own, or the actor may
+      // act for other customers.
+      if (byId.ok && (canActForOthers || byId.value.userId === actorUserId)) {
+        return byId.value.id;
+      }
+    }
+    if (canActForOthers) {
+      // Staff may resolve/create a customer by a supplied user_id.
+      const byUser = await customers.getByUserId(customerId, actor);
+      if (byUser.ok) return byUser.value.id;
+    }
+  }
+
+  // Self-service default: the authenticated actor's own customer profile.
+  if (actorUserId && !canActForOthers) {
+    const own = await customers.getByUserId(actorUserId, actor);
+    if (own.ok) return own.value.id;
+  }
+  return undefined;
+}
 
 export function checkoutRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
@@ -44,7 +94,35 @@ export function checkoutRoutes(kernel: Kernel) {
         actor,
       );
       if (replay.ok && replay.value) {
-        return c.json({ data: replay.value }, 201);
+        // IDOR guard: an idempotency key must only replay the requester's OWN
+        // order. Without this, a same-org customer who supplies/guesses another
+        // customer's key would receive that customer's order (PII, totals, lines).
+        let canActForOthers = false;
+        try {
+          assertPermission(actor, "customers:read");
+          canActForOthers = true;
+        } catch {
+          canActForOthers = false;
+        }
+        const ownCustomer = actor
+          ? await resolveCheckoutCustomerUuid(kernel.services.customers, actor, undefined)
+          : undefined;
+        const replayCustomer = replay.value.customerId ?? null;
+        const ownsOrder =
+          (replayCustomer !== null && replayCustomer === ownCustomer) ||
+          (replayCustomer === null && !ownCustomer);
+        if (canActForOthers || ownsOrder) {
+          return c.json({ data: replay.value }, 201);
+        }
+        return c.json(
+          {
+            error: {
+              code: "IDEMPOTENCY_CONFLICT",
+              message: "Idempotency key does not belong to this account.",
+            },
+          },
+          409,
+        );
       }
     }
 
@@ -135,32 +213,14 @@ export function checkoutRoutes(kernel: Kernel) {
         context,
       );
 
-      // Resolve customer profile UUID from customerId (may be a profile UUID or a Better Auth user_id)
-      let customerUuid: string | undefined = undefined;
-      if (processed.customerId) {
-        const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-        if (uuidRe.test(processed.customerId)) {
-          // Looks like a profile UUID — try direct lookup (no auto-create)
-          const byIdResult = await kernel.services.customers.getById(
-            processed.customerId,
-            actor,
-          );
-          if (byIdResult.ok) {
-            customerUuid = byIdResult.value.id;
-          }
-        }
-        if (!customerUuid) {
-          // Fall back to user_id lookup (auto-creates customer profile if needed)
-          const byUserIdResult = await kernel.services.customers.getByUserId(
-            processed.customerId,
-            actor,
-          );
-          if (byUserIdResult.ok) {
-            customerUuid = byUserIdResult.value.id;
-          }
-        }
-        // If both lookups fail, we still allow guest checkout (customerUuid remains undefined)
-      }
+      // SEC-07: resolve the order's customer server-side. A self-service actor
+      // can only attribute the order to its own profile; a client-supplied
+      // foreign customerId is ignored unless the actor is staff.
+      const customerUuid = await resolveCheckoutCustomerUuid(
+        kernel.services.customers,
+        actor,
+        processed.customerId,
+      );
 
       const orderPayload = {
         ...(body.idempotencyKey !== undefined
@@ -209,7 +269,12 @@ export function checkoutRoutes(kernel: Kernel) {
           : {}),
       };
 
-      const order = await kernel.services.orders.create(orderPayload, actor);
+      // Checkout is a trusted, already-server-priced pipeline (resolveCurrentPrices
+      // + promotions/tax) and reserves stock in its own after-hooks — so it hands
+      // the order primitive precomputed totals rather than re-deriving them.
+      const order = await kernel.services.orders.create(orderPayload, actor, undefined, {
+        trustedPricing: true,
+      });
 
       if (!order.ok) {
         return c.json(
@@ -221,6 +286,7 @@ export function checkoutRoutes(kernel: Kernel) {
       if (order.ok && (processed.appliedPromotions?.length ?? 0) > 0) {
         await kernel.services.promotions.recordUsage({
           promotions: processed.appliedPromotions ?? [],
+          organizationId: order.value.organizationId,
           orderId: order.value.id,
           ...(customerUuid !== undefined
             ? { customerId: customerUuid }

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

@@ -17,6 +17,14 @@ export function inventoryRoutes(kernel: Kernel) {
   // Inventory levels listing requires inventory:read
   router.use("/levels", requirePerm("inventory:read"));
 
+  // Warehouse config + reservation are staff operations, never public. Gate them
+  // at the route (reserve/release are also called internally by checkout with the
+  // customer's actor, so the service itself must stay callable — the boundary is
+  // the HTTP route). Blocks anonymous (401) and customers lacking the perm (403).
+  router.use("/warehouses", requirePerm("inventory:read"));
+  router.use("/reserve", requirePerm("inventory:adjust"));
+  router.use("/release", requirePerm("inventory:adjust"));
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listInventoryLevelsRoute, async (c) => {
     const actor = c.get("actor");
@@ -78,6 +86,12 @@ export function inventoryRoutes(kernel: Kernel) {
   router.openapi(createWarehouseRoute, async (c) => {
     const body = c.req.valid("json") as Parameters<typeof kernel.services.inventory.createWarehouse>[0];
     const actor = c.get("actor");
+    // Creating a warehouse (write) needs the higher inventory:adjust perm; the
+    // router.use above already requires inventory:read for the /warehouses path.
+    const perms = (actor as { permissions?: string[] } | null)?.permissions ?? [];
+    if (!(perms.includes("inventory:adjust") || perms.includes("inventory:*") || perms.includes("*:*"))) {
+      return c.json({ error: { code: "FORBIDDEN", message: "Permission 'inventory:adjust' is required." } }, 403);
+    }
     const result = await kernel.services.inventory.createWarehouse(body, actor);
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     return c.json({ data: result.value }, 201);

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

@@ -3,6 +3,7 @@ import type { Kernel } from "../../../runtime/kernel.js";
 import { changeOrderStatusRoute, listOrdersRoute, orderLookupRoute, getOrderRoute, getOrderFulfillmentsRoute, createOrderRoute, refundOrderRoute, captureOrderRoute, createOrderFulfillmentRoute, addOrderLineItemRoute, updateOrderLineItemRoute, removeOrderLineItemRoute, refundOrderLinesRoute, undoOrderRefundRoute, listOrderRefundsRoute, refundCapStatusRoute, createOrderNoteRoute, listOrderNotesRoute, deleteOrderNoteRoute, orderTimelineRoute } from "../schemas/orders.js";
 import { type AppEnv, isUUID, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
 import type { CreateOrderInput } from "../../../modules/orders/service.js";
+import { assertPermission } from "../../../auth/permissions.js";
 
 export function orderRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
@@ -62,6 +63,11 @@ export function orderRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(createOrderRoute, async (c) => {
+    try {
+      assertPermission(c.get("actor"), "orders:manage");
+    } catch (error) {
+      return c.json(mapErrorToResponse(error), mapErrorToStatus(error));
+    }
     const body = c.req.valid("json") as CreateOrderInput;
     const result = await kernel.services.orders.create(body, c.get("actor"));
     if (!result.ok) return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
@@ -170,6 +176,11 @@ export function orderRoutes(kernel: Kernel) {
 
   // @ts-expect-error -- openapi handler union return type
   router.openapi(addOrderLineItemRoute, async (c) => {
+    try {
+      assertPermission(c.get("actor"), "orders:manage");
+    } catch (error) {
+      return c.json(mapErrorToResponse(error), mapErrorToStatus(error));
+    }
     const body = c.req.valid("json");
     const result = await kernel.services.orders.addLineItem(
       c.req.param("id"),

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

@@ -184,7 +184,7 @@ export const createOrderRoute = createRoute({
   path: "/",
   tags: ["Orders"],
   summary: "Create a draft / manual order",
-  description: "Operator-created order (phone / POS / manual) with line items and totals, optionally without immediate payment.",
+  description: "Requires `orders:manage`. Creates an operator-entered order (phone / POS / manual); supplied line prices are stored as audited manual overrides.",
   request: {
     body: {
       content: { "application/json": { schema: CreateOrderBodySchema } },
@@ -272,7 +272,7 @@ export const addOrderLineItemRoute = createRoute({
   path: "/{id}/line-items",
   tags: ["Orders"],
   summary: "Add a line item to a placed order",
-  description: "Adds a line item to a non-terminal order and recalculates subtotal/tax/grand totals. Records an audit entry.",
+  description: "Requires `orders:manage`. Adds a line item to a non-terminal order, records its supplied price as a manual override, and recalculates totals.",
   request: {
     params: OrderIdParam,
     body: {

package/src/kernel/database/scoped-db.ts

@@ -3,7 +3,8 @@
  *
  * Wraps a Drizzle PgDatabase instance so that INSERT operations on
  * org-scoped tables automatically include the actor's organizationId,
- * and SELECT ... FROM org-scoped tables constrain rows to that organization.
+ * and SELECT / UPDATE / DELETE against org-scoped tables constrain rows to
+ * that organization — including when the caller supplies no WHERE clause.
  *
  * Plugin route handlers receive this scoped db via PluginContext.database.db
  * (organization resolved per operation from AsyncLocalStorage when used from
@@ -30,6 +31,45 @@ function tableHasOrganizationId(table: unknown): boolean {
   }
 }
 
+/**
+ * Wrap a WHERE-able Drizzle builder so every `.where()` call AND-s `orgEq` in
+ * AND re-wraps its result. Re-wrapping is what makes a chained
+ * `.where(a).where(b)` safe: Drizzle's second `.where()` REPLACES the first, so
+ * without re-wrapping the chained call would reach the raw builder and execute
+ * with only the caller's condition — dropping the org predicate and leaking
+ * across tenants. Every link in the chain re-injects `orgEq`.
+ */
+function wrapWhereable(builder: unknown, orgEq: SQL): unknown {
+  return new Proxy(builder as Record<string, unknown>, {
+    get(st, sp, sr) {
+      const sv = Reflect.get(st, sp, sr);
+      if (sp === "where" && typeof sv === "function") {
+        return (condition?: unknown, ...wRest: unknown[]) => {
+          const c = condition as SQL | undefined;
+          const merged = c ? and(orgEq, c) : orgEq;
+          const next = (sv as (...a: unknown[]) => unknown).call(st, merged, ...wRest);
+          return wrapWhereable(next, orgEq);
+        };
+      }
+      return typeof sv === "function" ? sv.bind(st) : sv;
+    },
+  });
+}
+
+/**
+ * Pre-apply the org predicate to a WHERE-able builder (UPDATE/DELETE) and wrap
+ * its `.where()` so a caller-supplied condition is AND-ed with the org filter
+ * rather than replacing it. Pre-applying `orgEq` immediately means a builder
+ * executed with NO caller `.where()` (e.g. `update(t).set(...)`) is still
+ * constrained to the org — it can never touch another tenant's rows.
+ */
+function scopeWhereBuilder(
+  builder: { where: (c: SQL | undefined) => unknown },
+  orgEq: SQL,
+): unknown {
+  return wrapWhereable(builder.where(orgEq), orgEq);
+}
+
 export function createScopedDb<TDb>(rawDb: TDb, orgSource: ScopedOrganizationId): TDb {
   if (!rawDb || typeof rawDb !== "object") return rawDb;
 
@@ -84,20 +124,7 @@ export function createScopedDb<TDb>(rawDb: TDb, orgSource: ScopedOrganizationId)
 
                   const orgEq = eq(orgCol, resolveOrganizationId(orgSource));
                   const inner = chain as { where: (c: SQL | undefined) => unknown };
-                  const scoped = inner.where(orgEq);
-                  return new Proxy(scoped as Record<string, unknown>, {
-                    get(st, sp, sr) {
-                      const sv = Reflect.get(st, sp, sr);
-                      if (sp === "where" && typeof sv === "function") {
-                        return (condition?: unknown, ...wRest: unknown[]) => {
-                          const c = condition as SQL | undefined;
-                          const merged = c ? and(orgEq, c) : orgEq;
-                          return sv.call(st, merged, ...wRest);
-                        };
-                      }
-                      return typeof sv === "function" ? sv.bind(st) : sv;
-                    },
-                  });
+                  return wrapWhereable(inner.where(orgEq), orgEq);
                 };
               }
               return typeof sbVal === "function" ? sbVal.bind(sbTarget) : sbVal;
@@ -106,6 +133,47 @@ export function createScopedDb<TDb>(rawDb: TDb, orgSource: ScopedOrganizationId)
         };
       }
 
+      if (prop === "update" && typeof value === "function") {
+        return (table: PgTable) => {
+          const builder = value.call(target, table);
+          if (!tableHasOrganizationId(table)) return builder;
+          const orgCol = getTableColumns(table).organizationId;
+          if (!orgCol) return builder;
+          const orgEq = eq(orgCol, resolveOrganizationId(orgSource));
+          // The org filter lives after `.set()`, so wrap `.set()` and scope the
+          // resulting WHERE-able builder.
+          return new Proxy(builder as Record<string, unknown>, {
+            get(t, p, r) {
+              const v = Reflect.get(t, p, r);
+              if (p === "set" && typeof v === "function") {
+                return (data: unknown) => {
+                  const setBuilder = (v as (...a: unknown[]) => unknown).call(t, data);
+                  return scopeWhereBuilder(
+                    setBuilder as { where: (c: SQL | undefined) => unknown },
+                    orgEq,
+                  );
+                };
+              }
+              return typeof v === "function" ? v.bind(t) : v;
+            },
+          });
+        };
+      }
+
+      if (prop === "delete" && typeof value === "function") {
+        return (table: PgTable) => {
+          const builder = value.call(target, table);
+          if (!tableHasOrganizationId(table)) return builder;
+          const orgCol = getTableColumns(table).organizationId;
+          if (!orgCol) return builder;
+          const orgEq = eq(orgCol, resolveOrganizationId(orgSource));
+          return scopeWhereBuilder(
+            builder as { where: (c: SQL | undefined) => unknown },
+            orgEq,
+          );
+        };
+      }
+
       return typeof value === "function" ? value.bind(target) : value;
     },
   }) as TDb;

package/src/kernel/errors.ts

@@ -32,6 +32,26 @@ export class CommerceValidationError extends Error implements CommerceError {
   }
 }
 
+/** Canonical message for a missing inventory record — the single source used by
+ * the inventory repository and mapped to the typed error below. */
+export const INVENTORY_RECORD_NOT_FOUND_MESSAGE =
+  "No inventory record found for this entity.";
+
+/** Raised when an inventory reserve/release targets an entity with no inventory
+ * record. Consumers (e.g. order status transitions that tolerate a missing
+ * record) discriminate on `code === "INVENTORY_RECORD_NOT_FOUND"`, never the
+ * message string. */
+export class CommerceInventoryRecordNotFoundError extends Error implements CommerceError {
+  code = "INVENTORY_RECORD_NOT_FOUND" as const;
+  constructor(
+    message: string = INVENTORY_RECORD_NOT_FOUND_MESSAGE,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = "CommerceInventoryRecordNotFoundError";
+  }
+}
+
 export class CommerceForbiddenError extends Error implements CommerceError {
   code = "FORBIDDEN" as const;
   constructor(

package/src/kernel/jobs/adapter.ts

@@ -1,9 +1,10 @@
-/**
- * Minimal interface for enqueueing background jobs.
- * The full DrizzleJobsAdapter implements this; hooks receive
- * it on HookContext.jobs so they can defer work without caring
- * about the underlying storage.
- */
+import type {
+  JobProcessingOrder,
+  TaskContext,
+  TaskDefinition,
+} from "./types.js";
+
+/** Enqueue-only surface exposed to hooks and services. */
 export interface JobsAdapter {
   enqueue(
     taskSlug: string,
@@ -12,6 +13,37 @@ export interface JobsAdapter {
   ): Promise<string>;
 }
 
+export interface RunJobsOptions {
+  queue?: string;
+  limit?: number;
+}
+
+export interface RunJobsResult {
+  processed: number;
+  failed: number;
+}
+
+export interface ExecutionEngineSetup {
+  tasks: ReadonlyMap<string, TaskDefinition>;
+  context: TaskContext;
+  processingOrder?: JobProcessingOrder;
+}
+
+export type ExecutionDriver =
+  | {
+      mode: "pull";
+      run(options?: RunJobsOptions): Promise<RunJobsResult>;
+    }
+  | {
+      mode: "push";
+    };
+
+/** Full job-engine contract selected through `config.jobs.adapter`. */
+export interface ExecutionEngine extends JobsAdapter {
+  readonly execution: ExecutionDriver;
+  register(setup: ExecutionEngineSetup): void;
+}
+
 export interface EnqueueOptions {
   organizationId: string;
   queue?: string;
@@ -22,8 +54,7 @@ export interface EnqueueOptions {
 }
 
 /**
- * No-op adapter used when no jobs backend is configured.
- * All enqueue calls silently succeed and return a placeholder ID.
+ * No-op enqueue surface used by isolated hook contexts.
  */
 export class NullJobsAdapter implements JobsAdapter {
   async enqueue(

package/src/kernel/jobs/drizzle-adapter.ts

@@ -1,21 +1,79 @@
 import { eq, and } from "drizzle-orm";
 import type { DrizzleDatabase } from "../database/drizzle-db.js";
 import type { TaskDefinition } from "./types.js";
-import type { JobsAdapter, EnqueueOptions } from "./adapter.js";
+import type {
+  EnqueueOptions,
+  ExecutionEngine,
+  ExecutionEngineSetup,
+  RunJobsOptions,
+} from "./adapter.js";
 import { OrgResolutionError } from "../errors.js";
 import { commerceJobs } from "./schema.js";
+import { runPendingJobs } from "./runner.js";
+import {
+  getJobReapThresholdMs,
+  getJobsReaperIntervalMs,
+  runStaleJobReaper,
+} from "./reaper.js";
 
 /**
  * PostgreSQL-backed job queue adapter using the application's own database.
  * Stores jobs in the `commerce_jobs` table. Supports concurrency keys
  * and supersede semantics for deduplication.
  */
-export class DrizzleJobsAdapter implements JobsAdapter {
+export class DrizzleJobsAdapter implements ExecutionEngine {
+  private setup: ExecutionEngineSetup | undefined;
+  private lastStaleJobReaperAt = 0;
+
+  readonly execution = {
+    mode: "pull" as const,
+    run: async (options: RunJobsOptions = {}) => {
+      if (!this.setup) {
+        throw new Error(
+          "DrizzleJobsAdapter must be registered before running jobs.",
+        );
+      }
+
+      const now = Date.now();
+      if (now - this.lastStaleJobReaperAt >= getJobsReaperIntervalMs()) {
+        this.lastStaleJobReaperAt = now;
+        try {
+          await runStaleJobReaper(
+            this.db,
+            getJobReapThresholdMs(),
+            this.setup.context.logger,
+          );
+        } catch (error) {
+          this.setup.context.logger.error("Stale job reaper failed", {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      return runPendingJobs({
+        db: this.db,
+        tasks: new Map(this.setup.tasks),
+        logger: this.setup.context.logger,
+        services: this.setup.context.services,
+        ...(options.queue !== undefined ? { queue: options.queue } : {}),
+        ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(this.setup.processingOrder !== undefined
+          ? { processingOrder: this.setup.processingOrder }
+          : {}),
+      });
+    },
+  };
+
   constructor(
     private db: DrizzleDatabase,
-    private tasks: Map<string, TaskDefinition>,
+    private tasks: Map<string, TaskDefinition> = new Map(),
   ) {}
 
+  register(setup: ExecutionEngineSetup): void {
+    this.setup = setup;
+    this.tasks = new Map(setup.tasks);
+  }
+
   async enqueue(
     taskSlug: string,
     input: Record<string, unknown>,
@@ -28,22 +86,27 @@ export class DrizzleJobsAdapter implements JobsAdapter {
       );
     }
 
+    const task = this.tasks.get(taskSlug);
+    const concurrencyKey =
+      options.concurrencyKey ?? task?.concurrency?.key(input);
+    const supersedes = options.supersedes ?? task?.concurrency?.supersedes;
+
     // If supersedes is set, delete existing pending jobs with the same concurrency key
-    if (options.concurrencyKey && options.supersedes) {
+    if (concurrencyKey && supersedes) {
       await this.db
         .delete(commerceJobs)
         .where(
           and(
-            eq(commerceJobs.concurrencyKey, options.concurrencyKey),
+            eq(commerceJobs.organizationId, organizationId),
+            eq(commerceJobs.taskSlug, taskSlug),
+            eq(commerceJobs.concurrencyKey, concurrencyKey),
             eq(commerceJobs.status, "pending"),
           ),
         );
     }
 
     // Look up task definition for default retry config
-    const task = this.tasks.get(taskSlug);
-    const maxAttempts =
-      options.maxAttempts ?? task?.retries?.attempts ?? 1;
+    const maxAttempts = options.maxAttempts ?? task?.retries?.attempts ?? 1;
 
     const rows = await this.db
       .insert(commerceJobs)
@@ -56,7 +119,7 @@ export class DrizzleJobsAdapter implements JobsAdapter {
         waitUntil: options.delayMs
           ? new Date(Date.now() + options.delayMs)
           : null,
-        concurrencyKey: options.concurrencyKey ?? null,
+        concurrencyKey: concurrencyKey ?? null,
       })
       .returning({ id: commerceJobs.id });