@porulle/core 0.1.0

package/src/kernel/compensation/executor.ts

@@ -0,0 +1,123 @@
+import { resolveOrgId } from "../../auth/org.js";
+import type { CompensationContext, Step } from "./types.js";
+import type { Result } from "../result.js";
+
+function errorToRecordPayload(
+  err: unknown,
+): { message: string; code?: string; details?: unknown } {
+  if (err && typeof err === "object" && "message" in err) {
+    const o = err as {
+      message: unknown;
+      code?: unknown;
+      details?: unknown;
+    };
+    const message = String(o.message);
+    const code = o.code != null ? String(o.code) : undefined;
+    const details = o.details !== undefined ? o.details : undefined;
+    return {
+      message,
+      ...(code != null ? { code } : {}),
+      ...(details !== undefined ? { details } : {}),
+    };
+  }
+  return { message: String(err) };
+}
+
+function compensationThrownToPayload(
+  err: unknown,
+): { message: string; stack?: string; details?: unknown } {
+  if (err instanceof Error) {
+    return {
+      message: err.message,
+      ...(err.stack != null ? { stack: err.stack } : {}),
+    };
+  }
+  return { message: String(err) };
+}
+
+/**
+ * AnyStep erases the output type parameter so that heterogeneous step
+ * arrays can be passed to runCompensationChain without variance issues
+ * under exactOptionalPropertyTypes.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- erases output type for heterogeneous step arrays; unknown breaks contravariance on compensate()
+type AnyStep<TInput> = Step<TInput, any>;
+
+/**
+ * Runs a list of steps in order. If any step fails, compensates all
+ * previously completed steps in reverse. Steps share the same input
+ * object (they may mutate it to enrich downstream steps, following
+ * the same pattern established by BeforeHooks).
+ *
+ * Compensation failures are logged but do not override the original error.
+ * A failed compensation is a separate operational concern that requires
+ * manual review — it should never mask the root cause returned to the caller.
+ */
+export async function runCompensationChain<TInput>(
+  steps: ReadonlyArray<AnyStep<TInput>>,
+  input: TInput,
+  ctx: CompensationContext,
+): Promise<Result<TInput>> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches AnyStep output erasure
+  const completed: Array<{ step: AnyStep<TInput>; output: any }> = [];
+
+  for (const step of steps) {
+    const result = await step.run(input, ctx);
+
+    if (!result.ok) {
+      const originalErr = result.error;
+      ctx.hook.logger.error(
+        `Compensation chain failed at step "${step.id}". ` +
+          `Running ${completed.length} compensation(s).`,
+        { error: originalErr },
+      );
+
+      // Compensate in reverse order — most recently completed step first
+      for (const done of [...completed].reverse()) {
+        if (!done.step.compensate) continue;
+        try {
+          await done.step.compensate(done.output, ctx);
+          ctx.hook.logger.info(`Compensated step "${done.step.id}"`);
+        } catch (compensateError) {
+          ctx.hook.logger.error(
+            `Compensation for step "${done.step.id}" failed. Manual review required.`,
+            { compensateError },
+          );
+          if (ctx.failureRepository) {
+            try {
+              const orgId = resolveOrgId(ctx.hook.actor);
+              const recordResult = await ctx.failureRepository.record(
+                {
+                  organizationId: orgId,
+                  correlationId: ctx.correlationId ?? "",
+                  chainName: ctx.chainName ?? "unknown",
+                  stepName: done.step.id,
+                  originalError: errorToRecordPayload(originalErr),
+                  compensationError: compensationThrownToPayload(compensateError),
+                },
+                ctx.tx ?? undefined,
+              );
+              if (!recordResult.ok) {
+                console.warn(
+                  "[compensation] Failed to persist compensation failure:",
+                  recordResult.error,
+                );
+              }
+            } catch (persistErr) {
+              console.warn(
+                "[compensation] Failed to persist compensation failure:",
+                persistErr,
+              );
+            }
+          }
+        }
+      }
+
+      return result;
+    }
+
+    completed.push({ step, output: result.value });
+  }
+
+  return { ok: true, value: input };
+}

package/src/kernel/compensation/repository.ts

@@ -0,0 +1,157 @@
+import { eq, and, desc, isNull, isNotNull, sql } from "drizzle-orm";
+import type { DrizzleDatabase, DbOrTx } from "../database/drizzle-db.js";
+import type { TxContext } from "../database/tx-context.js";
+import { CommerceNotFoundError } from "../errors.js";
+import { Ok, Err, type Result } from "../result.js";
+import { compensationFailures, type CompensationFailure } from "./schema.js";
+
+export interface RecordFailureInput {
+  organizationId: string;
+  correlationId: string;
+  chainName: string;
+  stepName: string;
+  originalError: { message: string; code?: string; details?: unknown };
+  compensationError: { message: string; stack?: string; details?: unknown };
+}
+
+export interface ListFailuresInput {
+  organizationId: string;
+  resolved?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export interface MarkResolvedInput {
+  id: string;
+  organizationId: string;
+  resolvedBy: string;
+  notes?: string;
+}
+
+export class CompensationFailuresRepository {
+  constructor(private readonly db: DrizzleDatabase) {}
+
+  private getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? this.db;
+  }
+
+  private clampLimit(limit?: number): number {
+    const n = limit ?? 50;
+    return Math.min(Math.max(n, 1), 200);
+  }
+
+  async record(
+    input: RecordFailureInput,
+    ctx?: TxContext,
+  ): Promise<Result<CompensationFailure>> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .insert(compensationFailures)
+      .values({
+        organizationId: input.organizationId,
+        correlationId: input.correlationId,
+        chainName: input.chainName,
+        stepName: input.stepName,
+        originalError: input.originalError,
+        compensationError: input.compensationError,
+      })
+      .returning();
+    return Ok(rows[0]!);
+  }
+
+  async list(
+    input: ListFailuresInput,
+    ctx?: TxContext,
+  ): Promise<Result<{ items: CompensationFailure[]; total: number }>> {
+    const db = this.getDb(ctx);
+    const conditions = [
+      eq(compensationFailures.organizationId, input.organizationId),
+    ];
+    if (input.resolved === true) {
+      conditions.push(isNotNull(compensationFailures.resolvedAt));
+    } else if (input.resolved === false) {
+      conditions.push(isNull(compensationFailures.resolvedAt));
+    }
+    const whereClause =
+      conditions.length === 1 ? conditions[0]! : and(...conditions);
+    const limit = this.clampLimit(input.limit);
+    const offset = input.offset ?? 0;
+
+    const items = await db
+      .select()
+      .from(compensationFailures)
+      .where(whereClause)
+      .orderBy(desc(compensationFailures.occurredAt))
+      .limit(limit)
+      .offset(offset);
+
+    const countRows = await db
+      .select({ count: sql<number>`count(*)::int` })
+      .from(compensationFailures)
+      .where(whereClause);
+
+    const total = countRows[0]?.count ?? 0;
+    return Ok({ items, total });
+  }
+
+  async findById(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<Result<CompensationFailure | null>> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(compensationFailures)
+      .where(eq(compensationFailures.id, id))
+      .limit(1);
+    return Ok(rows[0] ?? null);
+  }
+
+  async getById(
+    id: string,
+    organizationId: string,
+    ctx?: TxContext,
+  ): Promise<Result<CompensationFailure | null>> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(compensationFailures)
+      .where(
+        and(
+          eq(compensationFailures.id, id),
+          eq(compensationFailures.organizationId, organizationId),
+        ),
+      );
+    return Ok(rows[0] ?? null);
+  }
+
+  async markResolved(
+    input: MarkResolvedInput,
+    ctx?: TxContext,
+  ): Promise<Result<CompensationFailure>> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(compensationFailures)
+      .set({
+        resolvedAt: new Date(),
+        resolvedBy: input.resolvedBy,
+        resolutionNotes: input.notes ?? null,
+      })
+      .where(
+        and(
+          eq(compensationFailures.id, input.id),
+          eq(compensationFailures.organizationId, input.organizationId),
+          isNull(compensationFailures.resolvedAt),
+        ),
+      )
+      .returning();
+    if (rows.length === 0) {
+      return Err(
+        new CommerceNotFoundError(
+          "Compensation failure not found, already resolved, or wrong organization",
+        ),
+      );
+    }
+    return Ok(rows[0]!);
+  }
+}

package/src/kernel/compensation/schema.ts

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+import { sql, desc } from "drizzle-orm";
+import {
+  pgTable,
+  text,
+  jsonb,
+  timestamp,
+  index,
+} from "drizzle-orm/pg-core";
+
+export const compensationFailures = pgTable(
+  "compensation_failures",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => randomUUID()),
+    organizationId: text("organization_id").notNull(),
+    correlationId: text("correlation_id").notNull(),
+    chainName: text("chain_name").notNull(),
+    stepName: text("step_name").notNull(),
+    originalError: jsonb("original_error")
+      .$type<{ message: string; code?: string; details?: unknown }>()
+      .notNull(),
+    compensationError: jsonb("compensation_error")
+      .$type<{ message: string; stack?: string; details?: unknown }>()
+      .notNull(),
+    occurredAt: timestamp("occurred_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    resolvedAt: timestamp("resolved_at", { withTimezone: true }),
+    resolvedBy: text("resolved_by"),
+    resolutionNotes: text("resolution_notes"),
+  },
+  (table) => ({
+    orgUnresolvedIdx: index("idx_compensation_failures_org_unresolved")
+      .on(table.organizationId, desc(table.occurredAt))
+      .where(sql`${table.resolvedAt} IS NULL`),
+    correlationIdx: index("idx_compensation_failures_correlation").on(
+      table.correlationId,
+    ),
+  }),
+);
+
+export type CompensationFailure = typeof compensationFailures.$inferSelect;
+export type NewCompensationFailure = typeof compensationFailures.$inferInsert;

package/src/kernel/compensation/types.ts

@@ -0,0 +1,30 @@
+import type { TxContext } from "../database/tx-context.js";
+import type { HookContext } from "../hooks/types.js";
+import type { Result } from "../result.js";
+import type { CompensationFailuresRepository } from "./repository.js";
+
+/**
+ * CompensationContext carries the transaction and hook context into
+ * both the run and compensate functions. Steps have access to services,
+ * the actor, and the logger through ctx.hook.
+ */
+export interface CompensationContext {
+  tx: TxContext | null;
+  hook: HookContext;
+  failureRepository?: CompensationFailuresRepository;
+  correlationId?: string;
+  chainName?: string;
+}
+
+/**
+ * A Step is one unit of work in a compensation chain.
+ *
+ * TInput is the data the step receives (typically the shared checkout data object).
+ * TOutput is what the step produces. This same value is passed to compensate()
+ * so the compensate function has everything it needs to reverse the work.
+ */
+export interface Step<TInput, TOutput> {
+  id: string;
+  run: (input: TInput, ctx: CompensationContext) => Promise<Result<TOutput>>;
+  compensate?: (output: TOutput, ctx: CompensationContext) => Promise<void>;
+}

package/src/kernel/database/adapter.ts

@@ -0,0 +1,21 @@
+/**
+ * Database adapter interface for the commerce engine.
+ *
+ * Generic defaults to `unknown` so that any driver-specific adapter
+ * (postgres-js, PGlite, etc.) can implement it without type conflicts.
+ * Internal code narrows to `PluginDb` at the consumption site — see
+ * PluginContext in manifest.ts and createHookContext.
+ */
+export interface DatabaseAdapter<TDatabase = unknown, TTransaction = unknown> {
+  provider: string;
+  db: TDatabase;
+  transaction<T>(fn: (tx: TTransaction) => Promise<T>): Promise<T>;
+}
+
+export interface DatabaseConnectionFactoryInput {
+  adapter: DatabaseAdapter;
+}
+
+export function createDatabaseConnection(input: DatabaseConnectionFactoryInput): DatabaseAdapter {
+  return input.adapter;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Drizzle Database Type Definitions
+ *
+ * This module provides type-safe, driver-agnostic database access for
+ * PostgreSQL repositories.
+ *
+ * We use `PgDatabase` from `drizzle-orm/pg-core` — the base class that all
+ * PostgreSQL drivers extend (postgres-js, pglite, node-postgres, bun-sql).
+ * This means:
+ *
+ * - Repositories accept any PG driver without casts
+ * - PGlite in tests and postgres-js in production use the same type
+ * - Row types are fully inferred from pgTable schema definitions
+ * - No coupling to any specific driver package
+ */
+
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import * as schema from "./schema.js";
+
+/**
+ * Combined schema type for type inference
+ */
+export type Schema = typeof schema;
+
+/**
+ * Driver-agnostic PostgreSQL database instance with full schema type
+ * information.
+ *
+ * Both `PostgresJsDatabase<Schema>` and `PgliteDatabase<Schema>` are
+ * assignable to this type, so repositories work identically in production
+ * and tests without any casts.
+ */
+export type DrizzleDatabase = PgDatabase<PgQueryResultHKT, Schema>;
+
+/**
+ * Transaction type extracted from the database type.
+ * Used when operating within a transaction context.
+ *
+ * This type is derived from the transaction callback parameter:
+ * db.transaction(async (tx) => { ... })
+ *                       ^^-- This is DrizzleTx
+ */
+export type DrizzleTx = Parameters<
+  Parameters<DrizzleDatabase["transaction"]>[0]
+>[0];
+
+/**
+ * Union type for database or transaction - repositories can accept either.
+ * Both have the same query builder interface.
+ */
+export type DbOrTx = DrizzleDatabase | DrizzleTx;
+
+/**
+ * Re-export schema for convenience
+ */
+export { schema };

package/src/kernel/database/migrate.ts

@@ -0,0 +1,76 @@
+/**
+ * Programmatic database schema management.
+ *
+ * For npm consumers who don't have access to the raw .ts schema files,
+ * this module provides:
+ *
+ * 1. `getSchemaFiles()` — returns schema module paths for use in drizzle.config.ts
+ * 2. `getSchema()` — returns the combined Drizzle schema object
+ * 3. `pushSchema()` — programmatic push (creates tables if not exist)
+ *
+ * Usage in consumer's drizzle.config.ts:
+ *
+ *   import { getSchema } from "@porulle/core";
+ *   import { defineConfig } from "drizzle-kit";
+ *
+ *   export default defineConfig({
+ *     dialect: "postgresql",
+ *     schema: getSchema(),
+ *     dbCredentials: { url: process.env.DATABASE_URL! },
+ *   });
+ */
+
+import type { CommerceConfig } from "../../config/types.js";
+import * as schema from "./schema.js";
+
+/**
+ * Returns the combined Drizzle schema object with all table definitions.
+ * Use this in your own drizzle.config.ts or for programmatic schema inspection.
+ */
+export function getSchema() {
+  return schema;
+}
+
+/**
+ * Returns core schema merged with all plugin schemas from `config.customSchemas[]`.
+ * Throws if a plugin table name collides with a core table name.
+ */
+export function buildSchema(config?: CommerceConfig): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...schema };
+
+  if (!config?.customSchemas?.length) return merged;
+
+  const coreKeys = new Set(Object.keys(schema));
+
+  for (const pluginSchema of config.customSchemas) {
+    for (const [key, value] of Object.entries(pluginSchema)) {
+      if (coreKeys.has(key)) {
+        throw new Error(
+          `Plugin schema name collision: "${key}" already exists in core schema`,
+        );
+      }
+      if (key in merged) {
+        throw new Error(
+          `Plugin schema name collision: "${key}" is defined by multiple plugins`,
+        );
+      }
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Returns a list of all schema table names defined by the commerce engine.
+ */
+export function getTableNames(): string[] {
+  return Object.entries(schema)
+    .filter(
+      ([_, value]) =>
+        value != null &&
+        typeof value === "object" &&
+        "getSQL" in (value as object),
+    )
+    .map(([key]) => key);
+}

package/src/kernel/database/plugin-db-context.ts

@@ -0,0 +1,14 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const pluginDbOrgStorage = new AsyncLocalStorage<{ organizationId: string }>();
+
+export function runWithPluginDatabaseScope<T>(
+  organizationId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return pluginDbOrgStorage.run({ organizationId }, fn);
+}
+
+export function getPluginDatabaseScopeOrganizationId(): string | undefined {
+  return pluginDbOrgStorage.getStore()?.organizationId;
+}

package/src/kernel/database/plugin-types.ts

@@ -0,0 +1,34 @@
+/**
+ * Canonical database types for plugin service constructors.
+ *
+ * Replaces the copy-pasted type definitions in every plugin's types.ts:
+ *   type Db = PgDatabase<PgQueryResultHKT, Record<string, unknown>>
+ *
+ * Import from core instead:
+ *   import type { PluginDb, PluginTxFn } from "@porulle/core";
+ */
+
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+
+/**
+ * Database instance type for plugin services.
+ * This is the Drizzle PgDatabase with an opaque schema record.
+ */
+export type PluginDb = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
+
+/**
+ * Transaction function type for plugin services that need
+ * transactional guarantees (e.g., POS transaction complete,
+ * gift card debit, inventory reservation).
+ *
+ * Usage:
+ *   constructor(private db: PluginDb, private txFn: PluginTxFn) {}
+ *
+ *   async doWork() {
+ *     return this.txFn(async (tx) => {
+ *       await tx.insert(...).values(...);
+ *       await tx.update(...).set(...);
+ *     });
+ *   }
+ */
+export type PluginTxFn = <T>(fn: (tx: PluginDb) => Promise<T>) => Promise<T>;

package/src/kernel/database/schema.ts

@@ -0,0 +1,53 @@
+/**
+ * Combined schema barrel for Drizzle.
+ *
+ * Single source of truth for all core table definitions. Both drizzle-kit
+ * (via drizzle.config.ts) and the TypeScript type system consume this file.
+ *
+ * Drizzle-kit resolves re-exports, so pointing the config schema option
+ * at this one file discovers every core table. Plugin schemas live in
+ * their own packages and are referenced via glob patterns.
+ */
+
+// Auth (Better Auth generated tables)
+export * from "../../auth/auth-schema.js";
+
+// Catalog module
+export * from "../../modules/catalog/schema.js";
+
+// Inventory module
+export * from "../../modules/inventory/schema.js";
+
+// Cart module
+export * from "../../modules/cart/schema.js";
+
+// Orders module
+export * from "../../modules/orders/schema.js";
+export * from "../../modules/orders/sequences.js";
+
+// Customers module
+export * from "../../modules/customers/schema.js";
+
+// Pricing module
+export * from "../../modules/pricing/schema.js";
+
+// Promotions module
+export * from "../../modules/promotions/schema.js";
+
+// Media module
+export * from "../../modules/media/schema.js";
+
+// Webhooks module
+export * from "../../modules/webhooks/schema.js";
+
+// Fulfillment module
+export * from "../../modules/fulfillment/schema.js";
+
+// Jobs (kernel)
+export * from "../jobs/schema.js";
+
+// Compensation failures (kernel)
+export * from "../compensation/schema.js";
+
+// Audit module
+export * from "../../modules/audit/schema.js";