@porulle/core 0.1.0

package/src/kernel/hooks/executor.ts

@@ -0,0 +1,95 @@
+import type { AfterHook, BeforeHook, HookContext, HookOperation } from "./types.js";
+
+export interface HookError {
+  hookName: string;
+  message: string;
+}
+
+export interface HookReport {
+  errors: HookError[];
+  hasErrors: boolean;
+}
+
+export function mergeHookReports(a: HookReport, b: HookReport): HookReport {
+  return {
+    errors: [...a.errors, ...b.errors],
+    hasErrors: a.hasErrors || b.hasErrors,
+  };
+}
+
+/** Default hook timeout: 20 seconds */
+const HOOK_TIMEOUT_MS = 20_000;
+
+function withTimeout<T>(promiseOrValue: Promise<T> | T, timeoutMs: number, hookName: string): Promise<T> {
+  const promise = Promise.resolve(promiseOrValue);
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`Hook "${hookName}" timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    promise.then(
+      (val) => { clearTimeout(timer); resolve(val); },
+      (err) => { clearTimeout(timer); reject(err); },
+    );
+  });
+}
+
+export async function runBeforeHooks<T>(
+  hooks: BeforeHook<T>[],
+  data: T,
+  operation: HookOperation,
+  context: HookContext,
+): Promise<T> {
+  let current = data;
+  for (const hook of hooks) {
+    const hookName = hook.name || "(anonymous beforeHook)";
+    try {
+      current = await withTimeout(
+        hook({ data: current, operation, context }),
+        HOOK_TIMEOUT_MS,
+        hookName,
+      );
+    } catch (error) {
+      context.logger.error(`Before-hook "${hookName}" failed during ${operation}`, {
+        error: error instanceof Error ? error.message : String(error),
+        requestId: context.requestId,
+      });
+      throw error; // Re-throw — beforeHooks MUST succeed
+    }
+  }
+  return current;
+}
+
+export async function runAfterHooks<T>(
+  hooks: AfterHook<T>[],
+  originalData: T | null,
+  committedResult: T,
+  operation: HookOperation,
+  context: HookContext,
+): Promise<HookReport> {
+  const errors: HookError[] = [];
+  for (const hook of hooks) {
+    const hookName = hook.name || "(anonymous afterHook)";
+    try {
+      await withTimeout(
+        hook({
+          data: originalData,
+          result: committedResult,
+          operation,
+          context,
+        }),
+        HOOK_TIMEOUT_MS,
+        hookName,
+      );
+    } catch (error) {
+      errors.push({
+        hookName,
+        message: error instanceof Error ? error.message : String(error),
+      });
+      context.logger.error(`After-hook "${hookName}" failed`, {
+        error,
+      });
+    }
+  }
+  return { errors, hasErrors: errors.length > 0 };
+}

package/src/kernel/hooks/registry.ts

@@ -0,0 +1,74 @@
+export type HookHandler = (...args: never[]) => unknown;
+
+type HookEntry = {
+  prepended: HookHandler[];
+  configured: HookHandler[];
+  appended: HookHandler[];
+};
+
+export class HookRegistry {
+  private registry = new Map<string, HookEntry>();
+  private logger?: { error: (obj: Record<string, unknown>, msg: string) => void };
+
+  registerConfigHooks(hookName: string, handlers: HookHandler[]): void {
+    this.ensureEntry(hookName);
+    this.registry.get(hookName)!.configured = [...handlers];
+  }
+
+  append(hookName: string, handler: HookHandler): void {
+    this.ensureEntry(hookName);
+    this.registry.get(hookName)!.appended.push(handler);
+  }
+
+  prepend(hookName: string, handler: HookHandler): void {
+    this.ensureEntry(hookName);
+    this.registry.get(hookName)!.prepended.push(handler);
+  }
+
+  resolve(hookName: string): HookHandler[] {
+    const entry = this.registry.get(hookName);
+    if (!entry) return [];
+    return [...entry.prepended, ...entry.configured, ...entry.appended];
+  }
+
+  /**
+   * Emit a plugin event to all registered listeners.
+   *
+   * Unlike the before/after hook pattern (which transforms data through
+   * a pipeline), emit is fire-and-forget notification. Errors in handlers
+   * are caught and logged but do not propagate to the emitter.
+   *
+   * Usage:
+   *   kernel.hooks.emit("production.afterComplete", { orderId, quantity });
+   *
+   * Any plugin can listen:
+   *   hooks: () => [{ key: "production.afterComplete", handler: async (payload) => { ... } }]
+   */
+  setLogger(logger: { error: (obj: Record<string, unknown>, msg: string) => void }): void {
+    this.logger = logger;
+  }
+
+  async emit(key: string, payload: unknown): Promise<void> {
+    const handlers = this.resolve(key);
+    for (const handler of handlers) {
+      try {
+        await (handler as (payload: unknown) => unknown)(payload);
+      } catch (err) {
+        this.logger?.error(
+          { err, hookKey: key },
+          `Event handler failed for "${key}"`,
+        );
+      }
+    }
+  }
+
+  private ensureEntry(hookName: string): void {
+    if (!this.registry.has(hookName)) {
+      this.registry.set(hookName, {
+        prepended: [],
+        configured: [],
+        appended: [],
+      });
+    }
+  }
+}

package/src/kernel/hooks/types.ts

@@ -0,0 +1,55 @@
+import type { Actor } from "../../auth/types.js";
+import type { JobsAdapter } from "../jobs/adapter.js";
+import type { PluginDb } from "../database/plugin-types.js";
+
+export type HookOperation =
+  | "create"
+  | "update"
+  | "delete"
+  | "read"
+  | "list"
+  | "statusChange"
+  | "addItem"
+  | "removeItem"
+  | "custom";
+
+export interface Logger {
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+
+export interface ServiceContainer {
+  [key: string]: unknown;
+}
+
+export type HookOrigin = "rest" | "local";
+
+export interface HookContext {
+  actor: Actor | null;
+  tx: unknown;
+  logger: Logger;
+  services: ServiceContainer;
+  context: Record<string, unknown>;
+  requestId: string;
+  origin: HookOrigin;
+  jobs: JobsAdapter;
+  /**
+   * Drizzle database instance for hook handlers.
+   * Populated by `createHookContext` when callers pass `db`, `database`, or `kernel`.
+   */
+  db: PluginDb;
+}
+
+export type BeforeHook<TData> = (args: {
+  data: TData;
+  operation: HookOperation;
+  context: HookContext;
+}) => Promise<TData> | TData;
+
+export type AfterHook<TData> = (args: {
+  data: TData | null;
+  result: TData;
+  operation: HookOperation;
+  context: HookContext;
+}) => Promise<void> | void;

package/src/kernel/http-error.ts

@@ -0,0 +1,44 @@
+/**
+ * Converts a PluginResultErr into a structured HTTP error response.
+ *
+ * Replaces the `throw new Error(result.error)` pattern in plugin routes
+ * which always produces HTTP 500 with no structured error code.
+ *
+ * Usage in routes:
+ *   const result = await service.doSomething(orgId, input);
+ *   if (!result.ok) return toHttpError(result);
+ *   return result.value;
+ *
+ * The function infers HTTP status from the error code or message content:
+ *   - "NOT_FOUND" or "not found"        --> 404
+ *   - "FORBIDDEN" or "permission"        --> 403
+ *   - "CONFLICT" or "already exists"     --> 409
+ *   - "VALIDATION" or "cannot/must"      --> 422
+ *   - Everything else                    --> 400
+ */
+
+import type { PluginResultErr } from "./result.js";
+
+export interface HttpErrorResponse {
+  status: 400 | 403 | 404 | 409 | 422;
+  body: { error: { code: string; message: string } };
+}
+
+export function toHttpError(result: PluginResultErr): HttpErrorResponse {
+  const message = result.error;
+  const code = result.code;
+
+  if (code === "NOT_FOUND" || /not found/i.test(message)) {
+    return { status: 404, body: { error: { code: "NOT_FOUND", message } } };
+  }
+  if (code === "FORBIDDEN" || /permission|forbidden|unauthorized/i.test(message)) {
+    return { status: 403, body: { error: { code: "FORBIDDEN", message } } };
+  }
+  if (code === "CONFLICT" || /already|duplicate|exists|unique/i.test(message)) {
+    return { status: 409, body: { error: { code: "CONFLICT", message } } };
+  }
+  if (code === "VALIDATION" || /invalid|cannot|must|required|exceeded|negative/i.test(message)) {
+    return { status: 422, body: { error: { code: "VALIDATION_FAILED", message } } };
+  }
+  return { status: 400, body: { error: { code: code ?? "BAD_REQUEST", message } } };
+}

package/src/kernel/jobs/adapter.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+export interface JobsAdapter {
+  enqueue(
+    taskSlug: string,
+    input: Record<string, unknown>,
+    options: EnqueueOptions,
+  ): Promise<string>;
+}
+
+export interface EnqueueOptions {
+  organizationId: string;
+  queue?: string;
+  maxAttempts?: number;
+  delayMs?: number;
+  concurrencyKey?: string;
+  supersedes?: boolean;
+}
+
+/**
+ * No-op adapter used when no jobs backend is configured.
+ * All enqueue calls silently succeed and return a placeholder ID.
+ */
+export class NullJobsAdapter implements JobsAdapter {
+  async enqueue(
+    _taskSlug: string,
+    _input: Record<string, unknown>,
+    _options: EnqueueOptions,
+  ): Promise<string> {
+    return "null-job-id";
+  }
+}

package/src/kernel/jobs/builtin-job-tasks.ts

@@ -0,0 +1,17 @@
+import { webhookDeliveryTask } from "../../modules/webhooks/tasks.js";
+import { staleJobReaperTask } from "./reaper.js";
+import type { TaskDefinition } from "./types.js";
+
+export const defaultKernelJobTasks: TaskDefinition<
+  Record<string, unknown>,
+  Record<string, unknown>
+>[] = [
+  webhookDeliveryTask as TaskDefinition<
+    Record<string, unknown>,
+    Record<string, unknown>
+  >,
+  staleJobReaperTask as TaskDefinition<
+    Record<string, unknown>,
+    Record<string, unknown>
+  >,
+];

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

@@ -0,0 +1,65 @@
+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 { OrgResolutionError } from "../errors.js";
+import { commerceJobs } from "./schema.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 {
+  constructor(
+    private db: DrizzleDatabase,
+    private tasks: Map<string, TaskDefinition>,
+  ) {}
+
+  async enqueue(
+    taskSlug: string,
+    input: Record<string, unknown>,
+    options: EnqueueOptions,
+  ): Promise<string> {
+    const organizationId = options.organizationId.trim();
+    if (!organizationId) {
+      throw new OrgResolutionError(
+        "Jobs enqueue requires a non-empty organizationId.",
+      );
+    }
+
+    // If supersedes is set, delete existing pending jobs with the same concurrency key
+    if (options.concurrencyKey && options.supersedes) {
+      await this.db
+        .delete(commerceJobs)
+        .where(
+          and(
+            eq(commerceJobs.concurrencyKey, options.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 rows = await this.db
+      .insert(commerceJobs)
+      .values({
+        organizationId,
+        taskSlug,
+        input,
+        queue: options.queue ?? "default",
+        maxAttempts,
+        waitUntil: options.delayMs
+          ? new Date(Date.now() + options.delayMs)
+          : null,
+        concurrencyKey: options.concurrencyKey ?? null,
+      })
+      .returning({ id: commerceJobs.id });
+
+    return rows[0]!.id;
+  }
+}

package/src/kernel/jobs/reaper.ts

@@ -0,0 +1,95 @@
+import { and, eq, lt, sql } from "drizzle-orm";
+import type { DbOrTx } from "../database/drizzle-db.js";
+import type { Logger } from "../hooks/types.js";
+import { commerceJobs } from "./schema.js";
+import type { TaskDefinition } from "./types.js";
+
+export function getJobReapThresholdMs(): number {
+  const raw = process.env.JOB_REAP_THRESHOLD_MS;
+  if (raw === undefined || raw === "") return 300_000;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : 300_000;
+}
+
+export function getJobsReaperIntervalMs(): number {
+  const raw = process.env.JOBS_REAPER_INTERVAL_MS;
+  if (raw === undefined || raw === "") return 60_000;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : 60_000;
+}
+
+export async function runStaleJobReaper(
+  db: DbOrTx,
+  thresholdMs: number,
+  logger: Logger,
+): Promise<{ reapedCount: number }> {
+  const cutoff = new Date(Date.now() - thresholdMs);
+
+  return db.transaction(async (tx) => {
+    const stuck = await tx
+      .select({
+        id: commerceJobs.id,
+        taskSlug: commerceJobs.taskSlug,
+        processingStartedAt: commerceJobs.processingStartedAt,
+        attempts: commerceJobs.attempts,
+      })
+      .from(commerceJobs)
+      .where(
+        and(
+          eq(commerceJobs.status, "processing"),
+          sql`${commerceJobs.processingStartedAt} IS NOT NULL`,
+          lt(commerceJobs.processingStartedAt, cutoff),
+        ),
+      )
+      .for("update");
+
+    let reapedCount = 0;
+    for (const row of stuck) {
+      const newAttempts = Math.max(row.attempts - 1, 0);
+      const updated = await tx
+        .update(commerceJobs)
+        .set({
+          status: "pending",
+          processingStartedAt: null,
+          attempts: newAttempts,
+          updatedAt: new Date(),
+        })
+        .where(
+          and(
+            eq(commerceJobs.id, row.id),
+            eq(commerceJobs.status, "processing"),
+            lt(commerceJobs.processingStartedAt, cutoff),
+          ),
+        )
+        .returning({ id: commerceJobs.id });
+
+      if (updated.length === 0) continue;
+
+      reapedCount++;
+      logger.info("Reaped stale processing job", {
+        id: row.id,
+        taskSlug: row.taskSlug,
+        processingStartedAt: row.processingStartedAt,
+        attemptsAfter: newAttempts,
+      });
+    }
+
+    return { reapedCount };
+  });
+}
+
+export const staleJobReaperTask: TaskDefinition<
+  Record<string, unknown>,
+  { reapedCount: number }
+> = {
+  slug: "jobs/reap-stale",
+
+  async handler({ ctx }) {
+    const reaped = await runStaleJobReaper(
+      ctx.db,
+      getJobReapThresholdMs(),
+      ctx.logger,
+    );
+    return { output: { reapedCount: reaped.reapedCount } };
+  },
+};

package/src/kernel/jobs/runner.ts

@@ -0,0 +1,157 @@
+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 { commerceJobs } from "./schema.js";
+
+export interface RunPendingJobsArgs {
+  db: DrizzleDatabase;
+  tasks: Map<string, TaskDefinition>;
+  queue?: string;
+  limit?: number;
+  logger: Logger;
+  services: ServiceContainer;
+}
+
+/**
+ * Claims and processes pending jobs from the `commerce_jobs` table.
+ *
+ * Uses `FOR UPDATE SKIP LOCKED` to allow multiple runners to process
+ * jobs in parallel without conflicts. Each runner claims a batch,
+ * marks them as processing, then executes handlers outside the
+ * claim transaction.
+ */
+export async function runPendingJobs(
+  args: RunPendingJobsArgs,
+): Promise<{ processed: number; failed: number }> {
+  const {
+    db,
+    tasks,
+    queue = "default",
+    limit = 10,
+    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
+      .select()
+      .from(commerceJobs)
+      .where(
+        and(
+          eq(commerceJobs.status, "pending"),
+          eq(commerceJobs.queue, queue),
+          sql`(${commerceJobs.waitUntil} IS NULL OR ${commerceJobs.waitUntil} <= now())`,
+        ),
+      )
+      .orderBy(commerceJobs.createdAt)
+      .limit(limit)
+      .for("update", { skipLocked: true });
+
+    for (const job of pending) {
+      await tx
+        .update(commerceJobs)
+        .set({
+          status: "processing",
+          processingStartedAt: new Date(),
+          updatedAt: new Date(),
+        })
+        .where(eq(commerceJobs.id, job.id));
+    }
+
+    return pending;
+  });
+
+  // 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;
+    }
+
+    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: "succeeded",
+          output: result.output,
+          attempts: job.attempts + 1,
+          updatedAt: new Date(),
+          completedAt: new Date(),
+        })
+        .where(eq(commerceJobs.id, job.id));
+
+      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) {
+        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));
+        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);
+
+        await db
+          .update(commerceJobs)
+          .set({
+            status: "pending",
+            error: err instanceof Error ? err.message : String(err),
+            attempts,
+            waitUntil: new Date(Date.now() + delay),
+            updatedAt: new Date(),
+          })
+          .where(eq(commerceJobs.id, job.id));
+      }
+    }
+  }
+
+  return { processed, failed };
+}

package/src/kernel/jobs/schema.ts

@@ -0,0 +1,46 @@
+import {
+  pgTable,
+  uuid,
+  text,
+  jsonb,
+  integer,
+  timestamp,
+  index,
+} from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema.js";
+
+export const commerceJobs = pgTable("commerce_jobs", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  queue: text("queue").notNull().default("default"),
+  taskSlug: text("task_slug").notNull(),
+  input: jsonb("input").notNull().default("{}"),
+  output: jsonb("output"),
+  status: text("status", {
+    enum: ["pending", "processing", "succeeded", "failed"],
+  })
+    .notNull()
+    .default("pending"),
+  attempts: integer("attempts").notNull().default(0),
+  maxAttempts: integer("max_attempts").notNull().default(1),
+  error: text("error"),
+  waitUntil: timestamp("wait_until", { withTimezone: true }),
+  concurrencyKey: text("concurrency_key"),
+  createdAt: timestamp("created_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+  processingStartedAt: timestamp("processing_started_at", {
+    withTimezone: true,
+  }),
+  completedAt: timestamp("completed_at", { withTimezone: true }),
+}, (table) => ({
+  statusQueueIdx: index("idx_jobs_status_queue").on(table.status, table.queue),
+  taskSlugIdx: index("idx_jobs_task_slug").on(table.taskSlug),
+  waitUntilIdx: index("idx_jobs_wait_until").on(table.waitUntil),
+  orgIdx: index("idx_jobs_org").on(table.organizationId),
+}));