@porulle/core 0.1.0

package/dist/interfaces/rest/schemas/webhooks.d.ts

@@ -0,0 +1,221 @@
+import { z } from "@hono/zod-openapi";
+export declare const CreateWebhookEndpointBodySchema: z.ZodObject<{
+    url: z.ZodString;
+    events: z.ZodArray<z.ZodString>;
+    secret: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const listWebhookEndpointsRoute: {
+    method: "get";
+    path: "/";
+    tags: string[];
+    summary: string;
+    responses: {
+        200: {
+            content: {
+                "application/json": {
+                    schema: z.ZodObject<{
+                        data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    }, z.core.$strip>;
+                };
+            };
+            description: string;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+export declare const deleteWebhookEndpointRoute: {
+    method: "delete";
+    path: "/{id}";
+    tags: string[];
+    summary: string;
+    request: {
+        params: z.ZodObject<{
+            id: z.ZodUUID;
+        }, z.core.$strip>;
+    };
+    responses: {
+        400: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Business logic error.";
+        };
+        401: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Authentication required.";
+        };
+        403: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Insufficient permissions.";
+        };
+        404: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Resource not found.";
+        };
+        422: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Validation error.";
+        };
+        200: {
+            content: {
+                "application/json": {
+                    schema: z.ZodObject<{
+                        data: z.ZodObject<{
+                            deleted: z.ZodLiteral<true>;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            description: string;
+        };
+    };
+} & {
+    getRoutingPath(): "/:id";
+};
+export declare const createWebhookEndpointRoute: {
+    method: "post";
+    path: "/";
+    tags: string[];
+    summary: string;
+    description: string;
+    request: {
+        body: {
+            content: {
+                "application/json": {
+                    schema: z.ZodObject<{
+                        url: z.ZodString;
+                        events: z.ZodArray<z.ZodString>;
+                        secret: z.ZodOptional<z.ZodString>;
+                        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    }, z.core.$strip>;
+                };
+            };
+            required: true;
+        };
+    };
+    responses: {
+        400: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Business logic error.";
+        };
+        401: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Authentication required.";
+        };
+        403: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Insufficient permissions.";
+        };
+        404: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Resource not found.";
+        };
+        422: {
+            readonly content: {
+                readonly "application/json": {
+                    readonly schema: z.ZodObject<{
+                        error: z.ZodObject<{
+                            code: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                };
+            };
+            readonly description: "Validation error.";
+        };
+        201: {
+            content: {
+                "application/json": {
+                    schema: z.ZodObject<{
+                        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    }, z.core.$strip>;
+                };
+            };
+            description: string;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/interfaces/rest/schemas/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/rest/schemas/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAe,MAAM,mBAAmB,CAAC;AAKnD,eAAO,MAAM,+BAA+B;;;;;iBAKF,CAAC;AAI3C,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;CAWpC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiBrC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqBrC,CAAC"}

package/dist/interfaces/rest/schemas/webhooks.js

@@ -0,0 +1,62 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+// ─── Request Schema ──────────────────────────────────────────────────────────
+export const CreateWebhookEndpointBodySchema = z.object({
+    url: z.string().url().openapi({ example: "https://example.com/webhooks" }),
+    events: z.array(z.string()).openapi({ example: ["order.created", "order.fulfilled"] }),
+    secret: z.string().optional().openapi({ example: "whsec_abc123" }),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateWebhookEndpointRequest");
+// ─── Route Definitions ──────────────────────────────────────────────────────
+export const listWebhookEndpointsRoute = createRoute({
+    method: "get",
+    path: "/",
+    tags: ["Webhooks"],
+    summary: "List webhook endpoints",
+    responses: {
+        200: {
+            content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+            description: "Webhook endpoints",
+        },
+    },
+});
+export const deleteWebhookEndpointRoute = createRoute({
+    method: "delete",
+    path: "/{id}",
+    tags: ["Webhooks"],
+    summary: "Delete a webhook endpoint",
+    request: {
+        params: z.object({
+            id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+        }),
+    },
+    responses: {
+        200: {
+            content: { "application/json": { schema: z.object({ data: z.object({ deleted: z.literal(true) }) }) } },
+            description: "Webhook endpoint deleted.",
+        },
+        ...errorResponses,
+    },
+});
+export const createWebhookEndpointRoute = createRoute({
+    method: "post",
+    path: "/",
+    tags: ["Webhooks"],
+    summary: "Create a webhook endpoint",
+    description: "Registers a new webhook endpoint that will receive event notifications.",
+    request: {
+        body: {
+            content: {
+                "application/json": { schema: CreateWebhookEndpointBodySchema },
+            },
+            required: true,
+        },
+    },
+    responses: {
+        201: {
+            content: { "application/json": { schema: z.object({ data: z.record(z.string(), z.unknown()) }) } },
+            description: "Webhook endpoint created.",
+        },
+        ...errorResponses,
+    },
+});

package/dist/interfaces/rest/utils.d.ts

@@ -0,0 +1,45 @@
+import { mapErrorToStatus } from "../../kernel/error-mapper.js";
+import type { Actor } from "../../auth/types.js";
+/**
+ * Shared Hono environment type for all sub-routers.
+ * Matches the Variables set by middleware in the top-level server app.
+ */
+export type AppEnv = {
+    Variables: {
+        actor: Actor | null;
+        requestId: string;
+        logger: unknown;
+        kernel: unknown;
+    };
+};
+export declare function parsePagination(query: Record<string, string | undefined>): {
+    page: number;
+    limit: number;
+};
+export declare function parseInclude(value?: string): Set<string>;
+/**
+ * Map an error to a safe client response. Internal errors are sanitized
+ * to prevent leaking SQL, schema, or stack trace details.
+ */
+export declare function mapErrorToResponse(error: unknown): {
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export { mapErrorToStatus };
+/**
+ * Hono middleware that requires a specific permission on the actor.
+ * Returns 401 if no actor, 403 if permission denied.
+ * Usage: router.post("/", requirePerm("webhooks:manage"), handler);
+ */
+export declare function requirePerm(permission: string): (c: {
+    get(key: string): unknown;
+    json(data: unknown, status: number): unknown;
+}, next: () => Promise<void>) => Promise<unknown>;
+export declare function parseSort(value?: string): {
+    field: "createdAt" | "updatedAt" | "slug";
+    direction: "asc" | "desc";
+} | undefined;
+export declare function isUUID(value: string): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/dist/interfaces/rest/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/interfaces/rest/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,SAAS,EAAE;QACT,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;CACH,CAAC;AAIF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAOA;AAED,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAQxD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAO/F;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,IAC9B,GAAG;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,sBAkBxH;AAED,wBAAgB,SAAS,CACvB,KAAK,CAAC,EAAE,MAAM,GAEZ;IACF,KAAK,EAAE,WAAW,GAAG,WAAW,GAAG,MAAM,CAAC;IAC1C,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CAC3B,GACG,SAAS,CASZ;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7C"}

package/dist/interfaces/rest/utils.js

@@ -0,0 +1,71 @@
+import { mapErrorToStatus } from "../../kernel/error-mapper.js";
+import { toCommerceError } from "../../kernel/errors.js";
+const MAX_PAGE_LIMIT = 100;
+export function parsePagination(query) {
+    const page = Number.parseInt(query.page ?? "1", 10);
+    const limit = Number.parseInt(query.limit ?? "20", 10);
+    return {
+        page: Number.isFinite(page) && page > 0 ? page : 1,
+        limit: Math.min(MAX_PAGE_LIMIT, Number.isFinite(limit) && limit > 0 ? limit : 20),
+    };
+}
+export function parseInclude(value) {
+    if (!value)
+        return new Set();
+    return new Set(value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean));
+}
+/**
+ * Map an error to a safe client response. Internal errors are sanitized
+ * to prevent leaking SQL, schema, or stack trace details.
+ */
+export function mapErrorToResponse(error) {
+    const ce = toCommerceError(error);
+    if (ce.code === "INTERNAL_ERROR") {
+        // Sanitize internal errors -- do not expose raw messages to clients
+        return { error: { code: "INTERNAL_ERROR", message: "An unexpected error occurred." } };
+    }
+    return { error: { code: ce.code, message: ce.message } };
+}
+export { mapErrorToStatus };
+/**
+ * Hono middleware that requires a specific permission on the actor.
+ * Returns 401 if no actor, 403 if permission denied.
+ * Usage: router.post("/", requirePerm("webhooks:manage"), handler);
+ */
+export function requirePerm(permission) {
+    return async (c, next) => {
+        const actor = c.get("actor");
+        if (!actor) {
+            return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
+        }
+        const perms = actor.permissions ?? [];
+        if (perms.includes(permission) || perms.includes("*:*")) {
+            await next();
+            return;
+        }
+        // Check resource-level wildcard (e.g., "catalog:*" matches "catalog:create")
+        const [resource] = permission.split(":");
+        if (resource && perms.includes(`${resource}:*`)) {
+            await next();
+            return;
+        }
+        return c.json({ error: { code: "FORBIDDEN", message: `Permission '${permission}' is required.` } }, 403);
+    };
+}
+export function parseSort(value) {
+    if (!value)
+        return undefined;
+    const [fieldRaw, directionRaw] = value.split(":");
+    const selectedField = fieldRaw ?? "createdAt";
+    const field = ["createdAt", "updatedAt", "slug"].includes(selectedField)
+        ? selectedField
+        : "createdAt";
+    const direction = directionRaw === "asc" ? "asc" : "desc";
+    return { field, direction };
+}
+export function isUUID(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}

package/dist/interfaces/rest/webhook-router.d.ts

@@ -0,0 +1,41 @@
+/**
+ * webhookRouter() — route builder for external webhook receivers.
+ *
+ * Unlike router() which uses UC authentication (.auth(), .permission()),
+ * webhookRouter() uses HMAC signature verification. This is for routes
+ * that receive callbacks from external services (Shopify, WooCommerce,
+ * Stripe, BNPL providers) that authenticate via provider-specific signatures.
+ *
+ * Provides typed access to kernel.services, kernel.database.db, and
+ * kernel.logger without casting through `unknown`.
+ *
+ * Usage:
+ *
+ *   import { webhookRouter } from "@porulle/core";
+ *
+ *   export function createMyWebhookRoutes(kernel: Kernel) {
+ *     const { app, services, db, logger } = webhookRouter(kernel);
+ *
+ *     app.post("/product-updated", async (c) => {
+ *       const body = await c.req.json();
+ *       await services.catalog.update(body.id, { ... }, systemActor);
+ *       return c.json({ status: "ok" });
+ *     });
+ *
+ *     return app;
+ *   }
+ */
+import { Hono } from "hono";
+import type { Kernel } from "../../runtime/kernel.js";
+export interface WebhookRouterResult {
+    /** Raw Hono app — mount routes on this. No UC auth middleware attached. */
+    app: Hono;
+    /** Kernel services (catalog, inventory, orders, etc.). Typed properly. */
+    services: Kernel["services"];
+    /** Drizzle database instance for direct queries. */
+    db: Kernel["database"]["db"];
+    /** Structured Pino logger. */
+    logger: Kernel["logger"];
+}
+export declare function webhookRouter(kernel: Kernel): WebhookRouterResult;
+//# sourceMappingURL=webhook-router.d.ts.map

package/dist/interfaces/rest/webhook-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-router.d.ts","sourceRoot":"","sources":["../../../src/interfaces/rest/webhook-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,GAAG,EAAE,IAAI,CAAC;IACV,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7B,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;CAC1B;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAOjE"}

package/dist/interfaces/rest/webhook-router.js

@@ -0,0 +1,36 @@
+/**
+ * webhookRouter() — route builder for external webhook receivers.
+ *
+ * Unlike router() which uses UC authentication (.auth(), .permission()),
+ * webhookRouter() uses HMAC signature verification. This is for routes
+ * that receive callbacks from external services (Shopify, WooCommerce,
+ * Stripe, BNPL providers) that authenticate via provider-specific signatures.
+ *
+ * Provides typed access to kernel.services, kernel.database.db, and
+ * kernel.logger without casting through `unknown`.
+ *
+ * Usage:
+ *
+ *   import { webhookRouter } from "@porulle/core";
+ *
+ *   export function createMyWebhookRoutes(kernel: Kernel) {
+ *     const { app, services, db, logger } = webhookRouter(kernel);
+ *
+ *     app.post("/product-updated", async (c) => {
+ *       const body = await c.req.json();
+ *       await services.catalog.update(body.id, { ... }, systemActor);
+ *       return c.json({ status: "ok" });
+ *     });
+ *
+ *     return app;
+ *   }
+ */
+import { Hono } from "hono";
+export function webhookRouter(kernel) {
+    return {
+        app: new Hono(),
+        services: kernel.services,
+        db: kernel.database.db,
+        logger: kernel.logger,
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { CompensationContext, Step } from "./types.js";
+import type { Result } from "../result.js";
+/**
+ * AnyStep erases the output type parameter so that heterogeneous step
+ * arrays can be passed to runCompensationChain without variance issues
+ * under exactOptionalPropertyTypes.
+ */
+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 declare function runCompensationChain<TInput>(steps: ReadonlyArray<AnyStep<TInput>>, input: TInput, ctx: CompensationContext): Promise<Result<TInput>>;
+export {};
+//# sourceMappingURL=executor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/kernel/compensation/executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAmC3C;;;;GAIG;AAEH,KAAK,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEzC;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAC/C,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EACrC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,mBAAmB,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CA+DzB"}

package/dist/kernel/compensation/executor.js

@@ -0,0 +1,80 @@
+import { resolveOrgId } from "../../auth/org.js";
+function errorToRecordPayload(err) {
+    if (err && typeof err === "object" && "message" in err) {
+        const o = err;
+        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) {
+    if (err instanceof Error) {
+        return {
+            message: err.message,
+            ...(err.stack != null ? { stack: err.stack } : {}),
+        };
+    }
+    return { message: String(err) };
+}
+/**
+ * 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(steps, input, ctx) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches AnyStep output erasure
+    const completed = [];
+    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/dist/kernel/compensation/repository.d.ts

@@ -0,0 +1,47 @@
+import type { DrizzleDatabase } from "../database/drizzle-db.js";
+import type { TxContext } from "../database/tx-context.js";
+import { type Result } from "../result.js";
+import { 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 declare class CompensationFailuresRepository {
+    private readonly db;
+    constructor(db: DrizzleDatabase);
+    private getDb;
+    private clampLimit;
+    record(input: RecordFailureInput, ctx?: TxContext): Promise<Result<CompensationFailure>>;
+    list(input: ListFailuresInput, ctx?: TxContext): Promise<Result<{
+        items: CompensationFailure[];
+        total: number;
+    }>>;
+    findById(id: string, ctx?: TxContext): Promise<Result<CompensationFailure | null>>;
+    getById(id: string, organizationId: string, ctx?: TxContext): Promise<Result<CompensationFailure | null>>;
+    markResolved(input: MarkResolvedInput, ctx?: TxContext): Promise<Result<CompensationFailure>>;
+}
+//# sourceMappingURL=repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../src/kernel/compensation/repository.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAU,MAAM,2BAA2B,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE7E,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,iBAAiB,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3E;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,8BAA8B;IAC7B,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,eAAe;IAEhD,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,UAAU;IAKZ,MAAM,CACV,KAAK,EAAE,kBAAkB,EACzB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAgBjC,IAAI,CACR,KAAK,EAAE,iBAAiB,EACxB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,CAAC;QAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAgC7D,QAAQ,CACZ,EAAE,EAAE,MAAM,EACV,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;IAUxC,OAAO,CACX,EAAE,EAAE,MAAM,EACV,cAAc,EAAE,MAAM,EACtB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;IAcxC,YAAY,CAChB,KAAK,EAAE,iBAAiB,EACxB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;CA0BxC"}