@porulle/core 0.9.0 → 0.10.1

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

@@ -32,25 +32,23 @@ function tableHasOrganizationId(table: unknown): boolean {
 }
 
 /**
- * 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.
+ * 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 scopeWhereBuilder(
-  builder: { where: (c: SQL | undefined) => unknown },
-  orgEq: SQL,
-): unknown {
-  const scoped = builder.where(orgEq);
-  return new Proxy(scoped as Record<string, unknown>, {
+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;
-          return (sv as (...a: unknown[]) => unknown).call(st, merged, ...wRest);
+          const next = (sv as (...a: unknown[]) => unknown).call(st, merged, ...wRest);
+          return wrapWhereable(next, orgEq);
         };
       }
       return typeof sv === "function" ? sv.bind(st) : sv;
@@ -58,6 +56,20 @@ function scopeWhereBuilder(
   });
 }
 
+/**
+ * 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;
 
@@ -112,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;

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

package/src/kernel/jobs/runner.ts

@@ -1,7 +1,7 @@
 import { eq, and, sql } from "drizzle-orm";
 import type { DrizzleDatabase } from "../database/drizzle-db.js";
 import type { Logger, ServiceContainer } from "../hooks/types.js";
-import type { TaskDefinition } from "./types.js";
+import type { JobProcessingOrder, TaskDefinition } from "./types.js";
 import { commerceJobs } from "./schema.js";
 
 export interface RunPendingJobsArgs {
@@ -9,10 +9,53 @@ export interface RunPendingJobsArgs {
   tasks: Map<string, TaskDefinition>;
   queue?: string;
   limit?: number;
+  processingOrder?: JobProcessingOrder;
   logger: Logger;
   services: ServiceContainer;
 }
 
+type CommerceJob = typeof commerceJobs.$inferSelect;
+
+function isExclusiveTask(task: TaskDefinition | undefined): boolean {
+  return Boolean(task?.concurrency && task.concurrency.exclusive !== false);
+}
+
+function compareByProcessingOrder(
+  processingOrder: JobProcessingOrder | undefined,
+): (left: CommerceJob, right: CommerceJob) => number {
+  if (typeof processingOrder === "function") {
+    return (left, right) =>
+      processingOrder(
+        {
+          ...left,
+          input: left.input as Record<string, unknown>,
+        },
+        {
+          ...right,
+          input: right.input as Record<string, unknown>,
+        },
+      );
+  }
+
+  const field = processingOrder?.field ?? "createdAt";
+  const direction = processingOrder?.direction === "desc" ? -1 : 1;
+  return (left, right) => {
+    const leftValue = left[field];
+    const rightValue = right[field];
+    const compared =
+      leftValue instanceof Date && rightValue instanceof Date
+        ? leftValue.getTime() - rightValue.getTime()
+        : typeof leftValue === "number" && typeof rightValue === "number"
+          ? leftValue - rightValue
+          : String(leftValue).localeCompare(String(rightValue));
+    if (compared !== 0) return compared * direction;
+    return (
+      left.createdAt.getTime() - right.createdAt.getTime() ||
+      left.id.localeCompare(right.id)
+    );
+  };
+}
+
 /**
  * Claims and processes pending jobs from the `commerce_jobs` table.
  *
@@ -29,16 +72,24 @@ export async function runPendingJobs(
     tasks,
     queue = "default",
     limit = 10,
+    processingOrder,
     logger,
     services,
   } = args;
 
-  let processed = 0;
-  let failed = 0;
-
   // Phase 1: Claim jobs atomically
   const claimed = await db.transaction(async (tx) => {
-    const pending = await tx
+    const processing = await tx
+      .select({ concurrencyKey: commerceJobs.concurrencyKey })
+      .from(commerceJobs)
+      .where(eq(commerceJobs.status, "processing"));
+    const processingKeys = new Set(
+      processing.flatMap((job) =>
+        job.concurrencyKey ? [job.concurrencyKey] : [],
+      ),
+    );
+
+    const candidates = await tx
       .select()
       .from(commerceJobs)
       .where(
@@ -48,9 +99,34 @@ export async function runPendingJobs(
           sql`(${commerceJobs.waitUntil} IS NULL OR ${commerceJobs.waitUntil} <= now())`,
         ),
       )
-      .orderBy(commerceJobs.createdAt)
-      .limit(limit)
-      .for("update", { skipLocked: true });
+      .orderBy(commerceJobs.createdAt);
+
+    candidates.sort(compareByProcessingOrder(processingOrder));
+
+    const pending: CommerceJob[] = [];
+    for (const candidate of candidates) {
+      if (pending.length >= limit) break;
+      if (
+        candidate.concurrencyKey &&
+        isExclusiveTask(tasks.get(candidate.taskSlug)) &&
+        processingKeys.has(candidate.concurrencyKey)
+      ) {
+        continue;
+      }
+
+      const [locked] = await tx
+        .select()
+        .from(commerceJobs)
+        .where(
+          and(
+            eq(commerceJobs.id, candidate.id),
+            eq(commerceJobs.status, "pending"),
+          ),
+        )
+        .limit(1)
+        .for("update", { skipLocked: true });
+      if (locked) pending.push(locked);
+    }
 
     for (const job of pending) {
       await tx
@@ -63,95 +139,141 @@ export async function runPendingJobs(
         .where(eq(commerceJobs.id, job.id));
     }
 
-    return pending;
-  });
+    const oldestByKey = new Map<string, CommerceJob>();
+    const jobsToRun: CommerceJob[] = [];
+    const jobsToRelease: CommerceJob[] = [];
 
-  // Phase 2: Execute each claimed job outside the claim transaction
-  for (const job of claimed) {
-    const task = tasks.get(job.taskSlug);
-
-    if (!task) {
-      logger.warn("Unknown task slug — job marked as failed. Register the task handler in config.jobs.tasks.", {
-        taskSlug: job.taskSlug,
-        jobId: job.id,
-      });
-      await db
-        .update(commerceJobs)
-        .set({
-          status: "failed",
-          error: `Unknown task slug: ${job.taskSlug}`,
-          updatedAt: new Date(),
-          completedAt: new Date(),
-        })
-        .where(eq(commerceJobs.id, job.id));
-      failed++;
-      continue;
+    for (const job of pending) {
+      if (!job.concurrencyKey || !isExclusiveTask(tasks.get(job.taskSlug))) {
+        jobsToRun.push(job);
+        continue;
+      }
+
+      const oldest = oldestByKey.get(job.concurrencyKey);
+      if (!oldest) {
+        oldestByKey.set(job.concurrencyKey, job);
+        continue;
+      }
+
+      if (job.createdAt < oldest.createdAt) {
+        oldestByKey.set(job.concurrencyKey, job);
+        jobsToRelease.push(oldest);
+      } else {
+        jobsToRelease.push(job);
+      }
     }
 
-    try {
-      const result = await task.handler({
-        input: job.input as Record<string, unknown>,
-        ctx: { logger, db, services },
-        job: {
-          attemptNumber: job.attempts + 1,
-          maxAttempts: job.maxAttempts,
-        },
-      });
+    jobsToRun.push(...oldestByKey.values());
 
-      await db
+    for (const job of jobsToRelease) {
+      await tx
         .update(commerceJobs)
         .set({
-          status: "succeeded",
-          output: result.output,
-          attempts: job.attempts + 1,
+          status: "pending",
+          processingStartedAt: null,
           updatedAt: new Date(),
-          completedAt: new Date(),
         })
         .where(eq(commerceJobs.id, job.id));
+    }
+
+    return jobsToRun.sort(compareByProcessingOrder(processingOrder));
+  });
 
-      processed++;
-    } catch (err) {
-      logger.error("Job handler failed", {
-        taskSlug: job.taskSlug,
-        jobId: job.id,
-        error: err instanceof Error ? err.message : String(err),
-      });
-      const attempts = job.attempts + 1;
-      const maxAttempts = job.maxAttempts;
-
-      if (attempts >= maxAttempts) {
+  // Phase 2: Execute each claimed job outside the claim transaction
+  const outcomes = await Promise.all(
+    claimed.map(async (job) => {
+      const task = tasks.get(job.taskSlug);
+
+      if (!task) {
+        logger.warn(
+          "Unknown task slug — job marked as failed. Register the task handler in config.jobs.tasks.",
+          {
+            taskSlug: job.taskSlug,
+            jobId: job.id,
+          },
+        );
         await db
           .update(commerceJobs)
           .set({
             status: "failed",
-            error: err instanceof Error ? err.message : String(err),
-            attempts,
+            error: `Unknown task slug: ${job.taskSlug}`,
             updatedAt: new Date(),
             completedAt: new Date(),
           })
           .where(eq(commerceJobs.id, job.id));
-        failed++;
-      } else {
-        // Compute backoff delay
-        const retries = task.retries;
-        const delay =
-          retries?.backoff?.type === "exponential"
-            ? retries.backoff.delay * Math.pow(2, attempts - 1)
-            : (retries?.backoff?.delay ?? 1000);
+        return "failed" as const;
+      }
+
+      try {
+        const result = await task.handler({
+          input: job.input as Record<string, unknown>,
+          ctx: { logger, db, services },
+          job: {
+            attemptNumber: job.attempts + 1,
+            maxAttempts: job.maxAttempts,
+          },
+        });
 
         await db
           .update(commerceJobs)
           .set({
-            status: "pending",
-            error: err instanceof Error ? err.message : String(err),
-            attempts,
-            waitUntil: new Date(Date.now() + delay),
+            status: "succeeded",
+            output: result.output,
+            attempts: job.attempts + 1,
             updatedAt: new Date(),
+            completedAt: new Date(),
           })
           .where(eq(commerceJobs.id, job.id));
+
+        return "processed" as const;
+      } catch (err) {
+        logger.error("Job handler failed", {
+          taskSlug: job.taskSlug,
+          jobId: job.id,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        const attempts = job.attempts + 1;
+        const maxAttempts = job.maxAttempts;
+
+        if (attempts >= maxAttempts) {
+          await db
+            .update(commerceJobs)
+            .set({
+              status: "failed",
+              error: err instanceof Error ? err.message : String(err),
+              attempts,
+              updatedAt: new Date(),
+              completedAt: new Date(),
+            })
+            .where(eq(commerceJobs.id, job.id));
+          return "failed" as const;
+        } else {
+          // Compute backoff delay
+          const retries = task.retries;
+          const delay =
+            retries?.backoff?.type === "exponential"
+              ? retries.backoff.delay * Math.pow(2, attempts - 1)
+              : (retries?.backoff?.delay ?? 1000);
+
+          await db
+            .update(commerceJobs)
+            .set({
+              status: "pending",
+              error: err instanceof Error ? err.message : String(err),
+              attempts,
+              waitUntil: new Date(Date.now() + delay),
+              processingStartedAt: null,
+              updatedAt: new Date(),
+            })
+            .where(eq(commerceJobs.id, job.id));
+          return "retrying" as const;
+        }
       }
-    }
-  }
+    }),
+  );
 
-  return { processed, failed };
+  return {
+    processed: outcomes.filter((outcome) => outcome === "processed").length,
+    failed: outcomes.filter((outcome) => outcome === "failed").length,
+  };
 }

package/src/kernel/jobs/types.ts

@@ -17,6 +17,31 @@ export interface TaskRetryConfig {
   backoff?: { type: "fixed" | "exponential"; delay: number };
 }
 
+export interface JobProcessingOrderRecord {
+  id: string;
+  taskSlug: string;
+  input: Record<string, unknown>;
+  attempts: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export type JobProcessingOrderField =
+  | "createdAt"
+  | "updatedAt"
+  | "attempts"
+  | "taskSlug";
+
+export type JobProcessingOrder =
+  | {
+      field: JobProcessingOrderField;
+      direction?: "asc" | "desc";
+    }
+  | ((
+      left: JobProcessingOrderRecord,
+      right: JobProcessingOrderRecord,
+    ) => number);
+
 /** Present when the handler is invoked by `runPendingJobs` (not for ad-hoc calls). */
 export interface TaskJobMeta {
   attemptNumber: number;