@porulle/core 0.1.0

package/dist/kernel/compensation/repository.js

@@ -0,0 +1,93 @@
+import { eq, and, desc, isNull, isNotNull, sql } from "drizzle-orm";
+import { CommerceNotFoundError } from "../errors.js";
+import { Ok, Err } from "../result.js";
+import { compensationFailures } from "./schema.js";
+export class CompensationFailuresRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    getDb(ctx) {
+        return ctx?.tx ?? this.db;
+    }
+    clampLimit(limit) {
+        const n = limit ?? 50;
+        return Math.min(Math.max(n, 1), 200);
+    }
+    async record(input, ctx) {
+        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, ctx) {
+        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 `count(*)::int` })
+            .from(compensationFailures)
+            .where(whereClause);
+        const total = countRows[0]?.count ?? 0;
+        return Ok({ items, total });
+    }
+    async findById(id, ctx) {
+        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, organizationId, ctx) {
+        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, ctx) {
+        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/dist/kernel/compensation/schema.d.ts

@@ -0,0 +1,217 @@
+export declare const compensationFailures: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "compensation_failures";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "compensation_failures";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        organizationId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "organization_id";
+            tableName: "compensation_failures";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        correlationId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "correlation_id";
+            tableName: "compensation_failures";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        chainName: import("drizzle-orm/pg-core").PgColumn<{
+            name: "chain_name";
+            tableName: "compensation_failures";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        stepName: import("drizzle-orm/pg-core").PgColumn<{
+            name: "step_name";
+            tableName: "compensation_failures";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        originalError: import("drizzle-orm/pg-core").PgColumn<{
+            name: "original_error";
+            tableName: "compensation_failures";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: {
+                message: string;
+                code?: string;
+                details?: unknown;
+            };
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: {
+                message: string;
+                code?: string;
+                details?: unknown;
+            };
+        }>;
+        compensationError: import("drizzle-orm/pg-core").PgColumn<{
+            name: "compensation_error";
+            tableName: "compensation_failures";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: {
+                message: string;
+                stack?: string;
+                details?: unknown;
+            };
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: {
+                message: string;
+                stack?: string;
+                details?: unknown;
+            };
+        }>;
+        occurredAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "occurred_at";
+            tableName: "compensation_failures";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        resolvedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "resolved_at";
+            tableName: "compensation_failures";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        resolvedBy: import("drizzle-orm/pg-core").PgColumn<{
+            name: "resolved_by";
+            tableName: "compensation_failures";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        resolutionNotes: import("drizzle-orm/pg-core").PgColumn<{
+            name: "resolution_notes";
+            tableName: "compensation_failures";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+export type CompensationFailure = typeof compensationFailures.$inferSelect;
+export type NewCompensationFailure = typeof compensationFailures.$inferInsert;
+//# sourceMappingURL=schema.d.ts.map

package/dist/kernel/compensation/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/kernel/compensation/schema.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yBAWT,MAAM;uBAAS,MAAM;0BAAY,OAAO;;;;;;;;;;;;;;yBAAxC,MAAM;uBAAS,MAAM;0BAAY,OAAO;;;;;;;;;yBAGxC,MAAM;wBAAU,MAAM;0BAAY,OAAO;;;;;;;;;;;;;;yBAAzC,MAAM;wBAAU,MAAM;0BAAY,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBhE,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,OAAO,oBAAoB,CAAC,YAAY,CAAC;AAC3E,MAAM,MAAM,sBAAsB,GAAG,OAAO,oBAAoB,CAAC,YAAY,CAAC"}

package/dist/kernel/compensation/schema.js

@@ -0,0 +1,29 @@
+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()
+        .notNull(),
+    compensationError: jsonb("compensation_error")
+        .$type()
+        .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),
+}));

package/dist/kernel/compensation/types.d.ts

@@ -0,0 +1,29 @@
+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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/kernel/compensation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/kernel/compensation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,WAAW,CAAC;IAClB,iBAAiB,CAAC,EAAE,8BAA8B,CAAC;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,IAAI,CAAC,MAAM,EAAE,OAAO;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3E"}

package/dist/kernel/compensation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/kernel/database/adapter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare function createDatabaseConnection(input: DatabaseConnectionFactoryInput): DatabaseAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/kernel/database/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/kernel/database/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,SAAS,GAAG,OAAO,EAAE,YAAY,GAAG,OAAO;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,SAAS,CAAC;IACd,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,8BAA8B,GAAG,eAAe,CAE/F"}

package/dist/kernel/database/adapter.js

@@ -0,0 +1,3 @@
+export function createDatabaseConnection(input) {
+    return input.adapter;
+}

package/dist/kernel/database/drizzle-db.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 };
+//# sourceMappingURL=drizzle-db.d.ts.map

package/dist/kernel/database/drizzle-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle-db.d.ts","sourceRoot":"","sources":["../../../src/kernel/database/drizzle-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,CAChC,UAAU,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAC9C,CAAC,CAAC,CAAC,CAAC;AAEL;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;AAEjD;;GAEG;AACH,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/kernel/database/drizzle-db.js

@@ -0,0 +1,20 @@
+/**
+ * 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 * as schema from "./schema.js";
+/**
+ * Re-export schema for convenience
+ */
+export { schema };

package/dist/kernel/database/migrate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare function getSchema(): typeof 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 declare function buildSchema(config?: CommerceConfig): Record<string, unknown>;
+/**
+ * Returns a list of all schema table names defined by the commerce engine.
+ */
+export declare function getTableNames(): string[];
+//# sourceMappingURL=migrate.d.ts.map

package/dist/kernel/database/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/kernel/database/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC;;;GAGG;AACH,wBAAgB,SAAS,kBAExB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwB5E;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CASxC"}

package/dist/kernel/database/migrate.js

@@ -0,0 +1,61 @@
+/**
+ * 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 * 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) {
+    const merged = { ...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() {
+    return Object.entries(schema)
+        .filter(([_, value]) => value != null &&
+        typeof value === "object" &&
+        "getSQL" in value)
+        .map(([key]) => key);
+}

package/dist/kernel/database/plugin-db-context.d.ts

@@ -0,0 +1,3 @@
+export declare function runWithPluginDatabaseScope<T>(organizationId: string, fn: () => Promise<T>): Promise<T>;
+export declare function getPluginDatabaseScopeOrganizationId(): string | undefined;
+//# sourceMappingURL=plugin-db-context.d.ts.map

package/dist/kernel/database/plugin-db-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-db-context.d.ts","sourceRoot":"","sources":["../../../src/kernel/database/plugin-db-context.ts"],"names":[],"mappings":"AAIA,wBAAgB,0BAA0B,CAAC,CAAC,EAC1C,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,wBAAgB,oCAAoC,IAAI,MAAM,GAAG,SAAS,CAEzE"}

package/dist/kernel/database/plugin-db-context.js

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const pluginDbOrgStorage = new AsyncLocalStorage();
+export function runWithPluginDatabaseScope(organizationId, fn) {
+    return pluginDbOrgStorage.run({ organizationId }, fn);
+}
+export function getPluginDatabaseScopeOrganizationId() {
+    return pluginDbOrgStorage.getStore()?.organizationId;
+}

package/dist/kernel/database/plugin-types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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>;
+//# sourceMappingURL=plugin-types.d.ts.map

package/dist/kernel/database/plugin-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-types.d.ts","sourceRoot":"","sources":["../../../src/kernel/database/plugin-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAExE;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist/kernel/database/plugin-types.js

@@ -0,0 +1,10 @@
+/**
+ * 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";
+ */
+export {};