@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/error-contract.md

@@ -0,0 +1,539 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/error-contract. Do not edit. -->
+
+# error-contract
+
+Typed errors on the wire. With snake_case reasons, because we care.
+
+## README
+
+# Sample: Error Contract
+
+**I want to write a handler that handles errors cleanly — no HTTP codes, no JSON bodies, no try/catch chains.**
+
+## What this sample shows
+
+Every Kumiko error class in a real handler context. A single feature `orders-lite`, four handlers, 7 test cases each demonstrating a typical error situation.
+
+## The recipe in 3 sentences
+
+1. The handler throws or returns a `KumikoError` via `writeFailure(...)` or `failNotFound(...)` / `failUnprocessable(...)`.
+2. The dispatcher translates it into HTTP status + wire format — always `{ code, i18nKey, message, details?, requestId?, timestamp }`.
+3. The client reads `error.code` (stable category) or `error.details.reason` (feature-specific subtype).
+
+## The classes — when do I use which?
+
+| Class | HTTP | Use in handler |
+|---|---|---|
+| `ValidationError` | 400 | Automatic from Zod. Never throw manually, only for validation-hook errors. |
+| `AccessDeniedError` | 403 | "You're not allowed" — ownership, role check, field lock. |
+| `NotFoundError` | 404 | Entity doesn't exist. Automatic via `failNotFound(entity, id)`. |
+| `ConflictError` | 409 | State collision without a version (e.g. "paid orders can't be cancelled"). |
+| `VersionConflictError` | 409 | Optimistic lock — comes out of CrudExecutor automatically. You never throw it. |
+| `UnprocessableError` | 422 | Business rule violated. The reason string describes what. |
+| `InternalError` | 500 | You **don't throw it yourself**. The framework wraps unexpected throws automatically. |
+
+## Convenience helpers
+
+Instead of
+
+```ts illustration
+return { isSuccess: false, error: toWriteErrorInfo(new NotFoundError("order", id)) };
+```
+
+write
+
+```ts illustration
+return failNotFound("order", id);
+```
+
+Likewise: `failUnprocessable("reason", details?)` and `writeFailure(new AnyKumikoError(...))`.
+
+## Reason codes — the convention
+
+When your feature needs its own differentiation (e.g. `already_paid` vs. `already_cancelled`), use `UnprocessableError` or `ConflictError` and set `details.reason`:
+
+```ts illustration
+export const OrdersLiteReasons = {
+  alreadyPaid: "already_paid",
+  alreadyCancelled: "already_cancelled",
+} as const;
+
+return failUnprocessable(OrdersLiteReasons.alreadyPaid, { orderId });
+```
+
+**Rules:**
+- `snake_case`, no spaces
+- One `<Feature>Reasons` const-object per feature
+- Framework reasons (`stale_state`, `invalid_transition`, `field_access_denied`, `delete_restricted`) come from `FrameworkReasons` — **reuse, don't duplicate**
+
+## Throw vs. writeFailure
+
+Both end up in the same wire format. Rule of thumb:
+
+- **Handler top-level** → `return writeFailure(new X())` or the `failX(...)` helpers. The return type is explicit.
+- **Deep inside a helper function** → `throw new KumikoError(...)`. Otherwise you'd have to thread `WriteResult` through every function signature.
+
+## Cause chain
+
+When you throw a KumikoError that has another error as its cause:
+
+```ts illustration
+try {
+  await externalApi.call();
+} catch (e) {
+  throw new ConflictError({
+    message: "upstream rejected the sync",
+    i18nKey: "orders-lite.errors.upstreamReject",
+    details: { reason: "upstream_reject" },
+    cause: e instanceof Error ? e : undefined,
+  });
+}
+```
+
+The chain lands in the log (for forensics), but **not** in the response to the client. No manual filter required.
+
+## What you should **not** do
+
+- `throw new Error("string")` — becomes `InternalError` (500), the client sees no helpful error
+- `return { isSuccess: false, error: "string" }` — not a valid `WriteErrorInfo`, TypeScript blocks it but it's a typical pre-v1 pattern
+- Custom `class MyError extends Error` — also becomes `InternalError`. Use `UnprocessableError` + `details.reason` for feature subtypes
+- Reason strings like `"userNotAllowedToEditRecord"` (camelCase) or with spaces — the convention is `snake_case`
+
+## Further reading
+
+- Full class definitions: `packages/framework/src/errors/classes.ts`
+- Gold-standard integration test: `packages/framework/src/__tests__/error-contract.integration.test.ts`
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Error-Contract Sample — integration test
+//
+// Proves every pattern in feature.ts makes it through the real stack with the
+// documented wire shape. If you extend the sample, add a matching test here
+// so the "copy this" guarantee stays valid.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { updateRows } from "@cosmicdrift/kumiko-framework/testing";
+import { OrdersLiteReasons, orderEntity, ordersLiteFeature } from "../feature";
+
+let stack: TestStack;
+const orderTable = buildEntityTable("order", orderEntity);
+
+const admin = TestUsers.admin;
+const alice = createTestUser({ id: 10, roles: ["User"] });
+const bob = createTestUser({ id: 11, roles: ["User"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [ordersLiteFeature], systemHooks: [] });
+  await unsafeCreateEntityTable(stack.db, orderEntity);
+  await createEventsTable(stack.db);
+});
+afterAll(async () => stack.cleanup());
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${orderTable.tableName}"`);
+});
+
+// --- 1) Zod validation error via schema: empty cart rejected ---
+
+describe("Zod validation → ValidationError", () => {
+  test("totalCents < 1 rejects with validation_error + details.fields", async () => {
+    const error = await stack.http.writeErr(
+      "orders-lite:write:order:create",
+      { totalCents: 0 },
+      alice,
+    );
+    expect(error.code).toBe("validation_error");
+    const fields = (error.details as { fields: Array<{ path: string; code: string }> }).fields;
+    expect(fields).toContainEqual(expect.objectContaining({ path: "totalCents" }));
+  });
+});
+
+// --- 2) NotFoundError from failNotFound helper ---
+
+describe("failNotFound → NotFoundError", () => {
+  test("pay on missing order → 404, reason = order_not_found", async () => {
+    const error = await stack.http.writeErr(
+      "orders-lite:write:order:pay",
+      { id: "00000000-0000-4000-8000-000000000999" },
+      alice,
+    );
+    expect(error.code).toBe("not_found");
+    expect(error.httpStatus).toBe(404);
+    expect(error.details).toMatchObject({ reason: "order_not_found", entity: "order" });
+  });
+});
+
+// --- 3) AccessDeniedError for ownership mismatch ---
+
+describe("writeFailure(AccessDeniedError) → 403", () => {
+  test("Bob cannot pay Alice's order", async () => {
+    const alicesOrder = await stack.http.writeOk<{ id: number }>(
+      "orders-lite:write:order:create",
+      { totalCents: 100 },
+      alice,
+    );
+    const error = await stack.http.writeErr(
+      "orders-lite:write:order:pay",
+      { id: alicesOrder.id },
+      bob,
+    );
+    expect(error.code).toBe("access_denied");
+    expect(error.httpStatus).toBe(403);
+    expect(error.details).toMatchObject({ reason: "not_yours", orderId: alicesOrder.id });
+  });
+});
+
+// --- 4) UnprocessableError with feature reason ---
+
+describe("failUnprocessable(OrdersLiteReasons.X) → 422", () => {
+  test("cancelling an already-cancelled order fails with reason=already_cancelled", async () => {
+    const order = await stack.http.writeOk<{ id: number }>(
+      "orders-lite:write:order:create",
+      { totalCents: 100 },
+      alice,
+    );
+    await stack.http.writeOk("orders-lite:write:order:cancel", { id: order.id }, alice);
+
+    const error = await stack.http.writeErr(
+      "orders-lite:write:order:cancel",
+      { id: order.id },
+      alice,
+    );
+    expect(error.code).toBe("unprocessable");
+    expect(error.httpStatus).toBe(422);
+    expect(error.details).toMatchObject({ reason: OrdersLiteReasons.alreadyCancelled });
+  });
+});
+
+// --- 5) ConflictError for a domain conflict ---
+
+describe("ConflictError → 409", () => {
+  test("cancelling a paid order is a refund-required conflict", async () => {
+    const order = await stack.http.writeOk<{ id: number }>(
+      "orders-lite:write:order:create",
+      { totalCents: 100 },
+      alice,
+    );
+    // Force the row into `paid` via direct DB update. The sample feature
+    // doesn't expose a "place" action, so we can't walk the state machine —
+    // the point of this test is ConflictError semantics, not the transition
+    // path itself.
+    await updateRows(stack.db, orderTable, { status: "paid" }, { id: order.id });
+
+    const error = await stack.http.writeErr(
+      "orders-lite:write:order:cancel",
+      { id: order.id },
+      alice,
+    );
+    expect(error.code).toBe("conflict");
+    expect(error.httpStatus).toBe(409);
+    expect(error.details).toMatchObject({ reason: "refund_required" });
+  });
+});
+
+// --- 6) guardTransition → UnprocessableError with FrameworkReasons ---
+
+describe("guardTransition → FrameworkReasons.invalidTransition", () => {
+  test("paying a cancelled order is an invalid transition", async () => {
+    const order = await stack.http.writeOk<{ id: number }>(
+      "orders-lite:write:order:create",
+      { totalCents: 100 },
+      admin,
+    );
+    await stack.http.writeOk("orders-lite:write:order:cancel", { id: order.id }, admin);
+
+    const error = await stack.http.writeErr("orders-lite:write:order:pay", { id: order.id }, admin);
+    expect(error.code).toBe("unprocessable");
+    expect(error.details).toMatchObject({
+      reason: "invalid_transition",
+      from: "cancelled",
+      to: "paid",
+    });
+  });
+});
+
+// --- 7) Throw-based KumikoError (not via writeFailure) ---
+
+describe("direct throw of KumikoError", () => {
+  test("thrown NotFoundError round-trips to the same wire format", async () => {
+    const error = await stack.http.writeErr(
+      "orders-lite:write:order:rename",
+      { id: "00000000-0000-4000-8000-000000000999", nickname: "Anything" },
+      alice,
+    );
+    expect(error.code).toBe("not_found");
+    expect(error.details).toMatchObject({ entity: "order" });
+  });
+
+  test("thrown UnprocessableError with literal reason", async () => {
+    const order = await stack.http.writeOk<{ id: number }>(
+      "orders-lite:write:order:create",
+      { totalCents: 100 },
+      alice,
+    );
+    const error = await stack.http.writeErr(
+      "orders-lite:write:order:rename",
+      { id: order.id, nickname: "banned" },
+      alice,
+    );
+    expect(error.code).toBe("unprocessable");
+    expect(error.details).toMatchObject({ reason: "nickname_not_allowed" });
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Error-Contract Sample
+//
+// Shows: how a feature raises each Kumiko error class in the places a real
+// handler would — pre-flight checks, business-rule violations, stale writes,
+// access guards. Every pattern here is copy-pasteable into a real feature.
+//
+// Key idea: the handler only decides *which* Kumiko class fits. The framework
+// does the rest — HTTP status, response shape, Zod parsing, cause chain,
+// tx rollback. The handler author never has to touch HTTP codes or assemble
+// JSON error bodies.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createNumberField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+  defineTransitions,
+  guardTransition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  ConflictError,
+  failNotFound,
+  failUnprocessable,
+  NotFoundError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+// --- Feature-local reasons: snake_case, no feature prefix needed since the
+//     feature name is already namespaced by defineFeature("orders-lite", ...).
+//     The framework convention: one const object per feature that needs its
+//     own reason strings. For framework-level reasons (stale_state,
+//     invalid_transition, ...) use FrameworkReasons instead.
+export const OrdersLiteReasons = {
+  alreadyPaid: "already_paid",
+  alreadyCancelled: "already_cancelled",
+  emptyCart: "cart_is_empty",
+} as const;
+
+// --- Entity with a state machine so we can show guardTransition + version
+//     conflicts. Prices in cents (integer minor unit — see money-type.md).
+
+const ORDER_STATES = ["draft", "placed", "paid", "cancelled"] as const;
+type OrderState = (typeof ORDER_STATES)[number];
+
+const ORDER_TRANSITIONS = defineTransitions({
+  draft: ["placed", "cancelled"],
+  placed: ["paid", "cancelled"],
+  paid: [],
+  cancelled: [],
+});
+
+export const orderEntity = createEntity({
+  table: "read_errctr_orders",
+  fields: {
+    ownerId: createTextField({ personal: "ref", required: true }),
+    status: createSelectField({ options: ORDER_STATES, default: "draft" }),
+    totalCents: createNumberField({ default: 0 }),
+  },
+  transitions: {
+    status: {
+      draft: ["placed", "cancelled"],
+      placed: ["paid", "cancelled"],
+      paid: [],
+      cancelled: [],
+    },
+  },
+});
+
+const orderTable = buildEntityTable("order", orderEntity);
+
+export const ordersLiteFeature = defineFeature("orders-lite", (r) => {
+  r.entity("order", orderEntity);
+
+  // 1) Create — standard path. Zod schema rejects an empty cart; the
+  //    dispatcher converts the ZodIssue into a ValidationError with
+  //    details.fields[] (no handler code needed).
+  r.writeHandler(
+    "order:create",
+    z.object({
+      totalCents: z.number().int().min(1, "cart_is_empty"),
+    }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" });
+      return crud.create(
+        { ...event.payload, ownerId: event.user.id, status: "draft" },
+        event.user,
+        ctx.db,
+      );
+    },
+    { access: { roles: ["User", "Admin"] } },
+  );
+
+  // 2) Pay — business rule: only placed orders can be paid. Shows three
+  //    different failure shapes in a single handler:
+  //      - NotFoundError (order doesn't exist)
+  //      - AccessDeniedError (someone else's order, distinct from not_found
+  //        so the caller knows it's a permissions issue)
+  //      - UnprocessableError with reason from OrdersLiteReasons
+  //      - Framework-generated UnprocessableError with reason
+  //        FrameworkReasons.invalidTransition via guardTransition
+  r.writeHandler(
+    "order:pay",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => {
+      const [current] = await ctx.db.selectMany(orderTable, { id: event.payload.id });
+
+      // NotFoundError — automatic reason = "order_not_found" via snake-case
+      // derivation of the entity name.
+      if (!current) return failNotFound("order", event.payload.id);
+
+      const data = current as Record<string, unknown>;
+
+      // AccessDeniedError — intentional info-leak-prevention. We *could*
+      // return NotFoundError here too, but splitting the two lets the
+      // admin UI distinguish "doesn't exist" from "exists but foreign".
+      if (data["ownerId"] !== event.user.id && !event.user.roles.includes("Admin")) {
+        return writeFailure(
+          new AccessDeniedError({
+            message: "order is not yours",
+            i18nKey: "orders-lite.errors.notYours",
+            details: { reason: "not_yours", orderId: event.payload.id },
+          }),
+        );
+      }
+
+      // UnprocessableError with feature reason — "this order is already in
+      // the terminal paid state". Uses the OrdersLiteReasons const so the
+      // literal string lives in one place.
+      if (data["status"] === "paid") {
+        return failUnprocessable(OrdersLiteReasons.alreadyPaid, {
+          orderId: event.payload.id,
+        });
+      }
+
+      // guardTransition throws UnprocessableError with
+      // reason = FrameworkReasons.invalidTransition. Callers can branch on
+      // that framework-level reason uniformly across entities.
+      guardTransition(ORDER_TRANSITIONS, data["status"] as OrderState, "paid");
+
+      const crud = createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" });
+      return crud.update(
+        {
+          id: event.payload.id,
+          changes: { status: "paid" },
+          version: data["version"] as number,
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+    { access: { roles: ["User", "Admin"] } },
+  );
+
+  // 3) Cancel — shows ConflictError for a business conflict that isn't a
+  //    transition or a stale write. E.g. a refund window expired; the row
+  //    is fine but the action is no longer allowed.
+  r.writeHandler(
+    "order:cancel",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => {
+      const [current] = await ctx.db.selectMany(orderTable, { id: event.payload.id });
+      if (!current) return failNotFound("order", event.payload.id);
+
+      const data = current as Record<string, unknown>;
+
+      if (data["status"] === "cancelled") {
+        return failUnprocessable(OrdersLiteReasons.alreadyCancelled);
+      }
+      if (data["status"] === "paid") {
+        return writeFailure(
+          new ConflictError({
+            message: "paid orders cannot be cancelled — issue a refund instead",
+            i18nKey: "orders-lite.errors.cannotCancelPaid",
+            details: { reason: "refund_required", orderId: event.payload.id },
+          }),
+        );
+      }
+
+      const crud = createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" });
+      return crud.update(
+        {
+          id: event.payload.id,
+          changes: { status: "cancelled" },
+          version: data["version"] as number,
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+    { access: { roles: ["User", "Admin"] } },
+  );
+
+  // 4) Update — demonstrates the throw-based path (KumikoError raised
+  //    directly, not via writeFailure return). The dispatcher catches it
+  //    and wraps it in a WriteErrorInfo the same as the return path.
+  //    Use this style when a helper deep in the call tree needs to abort
+  //    without threading a WriteResult back up.
+  r.writeHandler(
+    "order:rename",
+    z.object({ id: z.uuid(), nickname: z.string().min(1) }),
+    async (event, ctx) => {
+      const [current] = await ctx.db.selectMany(orderTable, { id: event.payload.id });
+
+      if (!current) {
+        // Throwing a KumikoError is equivalent to `return writeFailure(...)`
+        // — both land on the same wire format. Prefer throws from deeper
+        // helper functions, writeFailure from the handler's top level.
+        throw new NotFoundError("order", event.payload.id);
+      }
+      if (event.payload.nickname === "banned") {
+        throw new UnprocessableError("nickname_not_allowed", {
+          i18nKey: "orders-lite.errors.bannedNickname",
+        });
+      }
+
+      // No real rename yet — the entity has no nickname column. Return a
+      // synthetic save context so the handler stays well-typed.
+      return {
+        isSuccess: true,
+        data: {
+          kind: "save",
+          id: event.payload.id,
+          data: current as Record<string, unknown>,
+          changes: event.payload,
+          previous: current as Record<string, unknown>,
+          isNew: false,
+          entityName: "order",
+        },
+      };
+    },
+    { access: { roles: ["User", "Admin"] } },
+  );
+});
+```