@porulle/core 0.9.0 → 0.10.0

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;

package/src/kernel/plugin/manifest.ts

@@ -14,6 +14,7 @@ import type {
   CommercePlugin,
   PluginPermission,
 } from "../../config/types.js";
+import type { TaskDefinition } from "../jobs/types.js";
 
 // ─── Plugin Logger ────────────────────────────────────────────────────
 
@@ -147,6 +148,7 @@ export interface CommercePluginManifest {
   hooks?: () => PluginHookRegistration[];
   routes?: (ctx: PluginContext) => PluginRouteRegistration[];
   analyticsModels?: () => unknown[];
+  jobs?: () => TaskDefinition[];
   /**
    * Named API-key scopes this plugin mints credentials under (issue #51),
    * merged into `config.auth.apiKeyScopes`. User-defined scopes with the
@@ -344,6 +346,16 @@ export function defineCommercePlugin(
       };
     }
 
+    if (manifest.jobs) {
+      result = {
+        ...result,
+        jobs: {
+          ...(result.jobs ?? {}),
+          tasks: [...(result.jobs?.tasks ?? []), ...manifest.jobs()],
+        },
+      };
+    }
+
     return result;
   };
 }

package/src/modules/catalog/entity-service.ts

@@ -98,6 +98,10 @@ export class EntityService {
     }
   }
 
+  private assertEntityWritable(entity: SellableEntity, actor: Actor | null): void {
+    if (entity.sourceStoreId != null) assertPermission(actor, "catalog:sync");
+  }
+
   private async validateAndCreateCustomFields(entityId: string, entityType: string, customFields: Record<string, unknown> | undefined, ctx?: TxContext): Promise<Result<void>> {
     if (!customFields) return Ok(undefined);
     const entityConfig = this.deps.config.entities?.[entityType];
@@ -212,7 +216,8 @@ export class EntityService {
     const afterHooks = this.deps.hooks.resolve("catalog.afterCreate") as CatalogCreateAfterHook[];
     const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.create"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
     const processedInput = await runBeforeHooks(beforeHooks, input, "create", context);
-    const entity = await this.repo.createEntity({ organizationId: orgId, type: processedInput.type, slug: processedInput.slug, status: "draft", isVisible: false, ...(processedInput.taxClass !== undefined ? { taxClass: processedInput.taxClass } : {}), metadata: processedInput.metadata ?? {} }, ctx);
+    if (processedInput.sourceStoreId != null) assertPermission(actor, "catalog:sync");
+    const entity = await this.repo.createEntity({ organizationId: orgId, type: processedInput.type, slug: processedInput.slug, status: "draft", isVisible: false, ...(processedInput.sourceStoreId !== undefined ? { sourceStoreId: processedInput.sourceStoreId } : {}), ...(processedInput.taxClass !== undefined ? { taxClass: processedInput.taxClass } : {}), metadata: processedInput.metadata ?? {} }, ctx);
     if (processedInput.attributes) {
       await this.repo.createAttribute({ entityId: entity.id, locale: processedInput.attributes.locale ?? "en", title: processedInput.attributes.title, subtitle: processedInput.attributes.subtitle, description: processedInput.attributes.description, richDescription: processedInput.attributes.richDescription, seoTitle: processedInput.attributes.seoTitle, seoDescription: processedInput.attributes.seoDescription }, ctx);
     }
@@ -228,6 +233,7 @@ export class EntityService {
     const existing = await this.repo.findEntityById(id, ctx);
     if (!existing) return Err(new CommerceNotFoundError("Entity not found."));
     this.assertSameOrg(existing, actor);
+    this.assertEntityWritable(existing, actor);
     const beforeHooks = this.deps.hooks.resolve("catalog.beforeUpdate") as CatalogUpdateBeforeHook[];
     const afterHooks = this.deps.hooks.resolve("catalog.afterUpdate") as CatalogUpdateAfterHook[];
     const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.update"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
@@ -244,6 +250,7 @@ export class EntityService {
     const existing = await this.repo.findEntityById(id, ctx);
     if (!existing) return Err(new CommerceNotFoundError("Entity not found."));
     this.assertSameOrg(existing, actor);
+    this.assertEntityWritable(existing, actor);
     await this.repo.deleteAttributesByEntityId(id, ctx);
     await this.repo.deleteCustomFieldsByEntityId(id, ctx);
     await this.repo.deleteEntityCategoriesByEntityId(id, ctx);
@@ -382,6 +389,7 @@ export class EntityService {
     const entity = await this.repo.findEntityById(id, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
     try { this.assertSameOrg(entity, actor); } catch (error) { return Err(toCommerceError(error)); }
+    try { this.assertEntityWritable(entity, actor); } catch (error) { return Err(toCommerceError(error)); }
     const updateData: Partial<SellableEntity> = { status };
     if (status === "active") { updateData.publishedAt = new Date(); updateData.isVisible = true; }
     const updated = await this.repo.updateEntity(id, updateData, ctx);

package/src/modules/catalog/repository/index.ts

@@ -1,5 +1,6 @@
 import { eq, and, inArray, type SQL } from "drizzle-orm";
 import type { TxContext } from "../../../kernel/database/tx-context.js";
+import { CommerceNotFoundError } from "../../../kernel/errors.js";
 import type {
   DrizzleDatabase,
   DbOrTx,
@@ -698,15 +699,24 @@ export class CatalogRepository {
     return rows[0];
   }
 
-  async createVariant(data: VariantInsert, ctx?: TxContext): Promise<Variant> {
+  async createVariant(
+    data: Omit<VariantInsert, "organizationId" | "sourceStoreId">,
+    ctx?: TxContext,
+  ): Promise<Variant> {
     const db = this.getDb(ctx);
-    const rows = await db.insert(variants).values(data).returning();
+    const entity = await this.findEntityById(data.entityId, ctx);
+    if (!entity) throw new CommerceNotFoundError("Entity not found.");
+    const rows = await db.insert(variants).values({
+      ...data,
+      organizationId: entity.organizationId,
+      sourceStoreId: entity.sourceStoreId,
+    }).returning();
     return rows[0]!;
   }
 
   async updateVariant(
     id: string,
-    data: Partial<Omit<VariantInsert, "id">>,
+    data: Partial<Omit<VariantInsert, "id" | "organizationId" | "sourceStoreId">>,
     ctx?: TxContext,
   ): Promise<Variant | undefined> {
     const db = this.getDb(ctx);