@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/state-machine.md

@@ -0,0 +1,920 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/state-machine. Do not edit. -->
+
+# state-machine
+
+Enforced entity state transitions. No more illegal state changes.
+
+## README
+
+# State Machine
+
+Enforced entity state transitions.
+
+## What it shows
+
+- `defineTransitions` + `guardTransition`
+- Each transition as its own domain event for a readable audit trail
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/state-machine
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// State Machine Sample — Integration Test
+// Proves: valid transitions work, invalid transitions rejected,
+// state skipping rejected, role-based access, business logic in handler,
+// non-linear transitions (reopen)
+//
+// Workflow:
+//   draft → sent → paid
+//                 → cancelled → draft (reopen)
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { stateMachineFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+const accounting = createTestUser({ id: 2, roles: ["Accounting"] });
+const viewer = createTestUser({ id: 3, roles: ["Viewer"] });
+const otherTenantAdmin = createTestUser({
+  id: 4,
+  tenantId: "00000000-0000-4000-8000-000000000002",
+  roles: ["Admin"],
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [stateMachineFeature],
+    systemHooks: [],
+  });
+  // The projection table (sample_sm_invoices) is auto-pushed by setupTestStack
+  // because r.projection() declares it in feature.ts.
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+// Helper: create a draft invoice. The writeOk return-shape carries the
+// SaveContext envelope (`{ data: { id, data: { status, ... }, ... } }`)
+// — typed here so individual call sites don't need to cast.
+type InvoiceWriteResult = {
+  id: string;
+  data: { status: string };
+};
+async function createDraftInvoice(title = "Test Invoice"): Promise<InvoiceWriteResult> {
+  return stack.http.writeOk<InvoiceWriteResult>(
+    "billing:write:invoice:create",
+    { title, amount: 100, amountCurrency: "EUR" },
+    admin,
+  );
+}
+
+// --- Happy path ---
+
+describe("happy path: draft → sent → paid", () => {
+  test("create starts in draft", async () => {
+    const data = await createDraftInvoice();
+    expect(data["data"]["status"]).toBe("draft");
+  });
+
+  test("send moves draft → sent", async () => {
+    const created = await createDraftInvoice();
+    const sent = await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      admin,
+    );
+    expect(sent["data"]["status"]).toBe("sent");
+  });
+
+  test("markPaid moves sent → paid", async () => {
+    const created = await createDraftInvoice();
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      admin,
+    );
+    const paid = await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:mark-paid",
+      { id: created["id"] },
+      accounting,
+    );
+    expect(paid["data"]["status"]).toBe("paid");
+  });
+});
+
+// --- Invalid transitions ---
+
+describe("invalid transitions rejected", () => {
+  test("cannot skip draft → paid (must go through sent)", async () => {
+    const created = await createDraftInvoice();
+    const error = await stack.http.writeErr(
+      "billing:write:invoice:mark-paid",
+      { id: created["id"] },
+      accounting,
+    );
+    expectErrorIncludes(error, "Invalid transition");
+  });
+
+  test("cannot cancel from draft (only from sent)", async () => {
+    const created = await createDraftInvoice();
+    const error = await stack.http.writeErr(
+      "billing:write:invoice:cancel",
+      { id: created["id"] },
+      admin,
+    );
+    expectErrorIncludes(error, "Invalid transition");
+  });
+
+  test("cannot send from paid (terminal state)", async () => {
+    const created = await createDraftInvoice();
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      admin,
+    );
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:mark-paid",
+      { id: created["id"] },
+      accounting,
+    );
+
+    const error = await stack.http.writeErr(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      admin,
+    );
+    expectErrorIncludes(error, "Invalid transition");
+  });
+});
+
+// --- Non-linear: reopen ---
+
+describe("non-linear transitions", () => {
+  test("cancelled invoice can be reopened to draft", async () => {
+    const created = await createDraftInvoice("Reopen Test");
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      admin,
+    );
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:cancel",
+      { id: created["id"] },
+      admin,
+    );
+
+    const reopened = await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:reopen",
+      { id: created["id"] },
+      admin,
+    );
+    expect(reopened["data"]["status"]).toBe("draft");
+  });
+
+  test("cannot reopen from sent (only from cancelled)", async () => {
+    const created = await createDraftInvoice();
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(
+      "billing:write:invoice:reopen",
+      { id: created["id"] },
+      admin,
+    );
+    expectErrorIncludes(error, "Invalid transition");
+  });
+});
+
+// --- Role-based access ---
+
+describe("role-based access per transition", () => {
+  test("Viewer cannot send invoice", async () => {
+    const created = await createDraftInvoice();
+    const error = await stack.http.writeErr(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      viewer,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+
+  test("Admin cannot markPaid (Accounting only)", async () => {
+    const created = await createDraftInvoice();
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(
+      "billing:write:invoice:mark-paid",
+      { id: created["id"] },
+      admin,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+
+  test("Accounting can markPaid", async () => {
+    const created = await createDraftInvoice();
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      admin,
+    );
+
+    const paid = await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:mark-paid",
+      { id: created["id"] },
+      accounting,
+    );
+    expect(paid["data"]["status"]).toBe("paid");
+  });
+});
+
+// --- Tenant isolation ---
+
+describe("tenant isolation", () => {
+  test("other tenant cannot transition invoice", async () => {
+    const created = await createDraftInvoice("Tenant1 Invoice");
+
+    const error = await stack.http.writeErr(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      otherTenantAdmin,
+    );
+    expect(error.code).toBe("not_found");
+  });
+});
+
+// --- Business logic in handler ---
+
+describe("business logic with transitions", () => {
+  test("cannot markPaid if amount is 0", async () => {
+    const created = await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:create",
+      { title: "Zero Invoice", amount: 0, amountCurrency: "EUR" },
+      admin,
+    );
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:send",
+      { id: created["id"] },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(
+      "billing:write:invoice:mark-paid",
+      { id: created["id"] },
+      accounting,
+    );
+    expectErrorIncludes(error, "cannot_pay_zero_amount");
+  });
+});
+
+// --- Auto transition guard (pipeline) ---
+
+describe("auto transition guard from pipeline", () => {
+  test("updateStatus with valid transition succeeds (no manual guard)", async () => {
+    const created = await createDraftInvoice("Auto Guard OK");
+    const updated = await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:update-status",
+      { id: created["id"], changes: { status: "sent" }, version: 1 },
+      admin,
+    );
+    expect(updated["data"]["status"]).toBe("sent");
+  });
+
+  test("updateStatus with invalid transition rejected by auto guard", async () => {
+    const created = await createDraftInvoice("Auto Guard Fail");
+    const error = await stack.http.writeErr(
+      "billing:write:invoice:update-status",
+      { id: created["id"], changes: { status: "paid" }, version: 1 },
+      admin,
+    );
+    expectErrorIncludes(error, "Invalid transition");
+  });
+});
+
+// --- skipTransitionGuard ---
+
+describe("skipTransitionGuard", () => {
+  test("forceStatus bypasses transition guard (draft → paid directly)", async () => {
+    const created = await createDraftInvoice("Force Status");
+    const forced = await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:force-status",
+      { id: created["id"], status: "paid" },
+      admin,
+    );
+    expect(forced["data"]["status"]).toBe("paid");
+  });
+
+  test("forceStatus can set any state from any state", async () => {
+    const created = await createDraftInvoice("Force Any");
+    // draft → paid (skip sent)
+    await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:force-status",
+      { id: created["id"], status: "paid" },
+      admin,
+    );
+    // paid → draft (normally impossible)
+    const back = await stack.http.writeOk<InvoiceWriteResult>(
+      "billing:write:invoice:force-status",
+      { id: created["id"], status: "draft" },
+      admin,
+    );
+    expect(back["data"]["status"]).toBe("draft");
+  });
+});
+```
+
+### src/__tests__/reducer.test.ts
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { eventName, INVOICE_CREATED_EVENT, INVOICE_EVENTS } from "../events";
+import { type InvoiceState, initialInvoiceState, reduceInvoice } from "../reducer";
+
+function reduce(...events: { type: string; payload?: unknown }[]): InvoiceState {
+  const state: InvoiceState = { ...initialInvoiceState };
+  for (const evt of events) reduceInvoice(state, evt);
+  return state;
+}
+
+describe("reduceInvoice", () => {
+  test("initial state is missing + amount 0", () => {
+    expect(initialInvoiceState).toEqual({ status: "missing", amount: 0 });
+  });
+
+  test("invoice.created sets status=draft and copies amount from payload", () => {
+    const state = reduce({ type: INVOICE_CREATED_EVENT, payload: { amount: 250 } });
+    expect(state.status).toBe("draft");
+    expect(state.amount).toBe(250);
+  });
+
+  test("invoice.created without amount in payload defaults amount to 0", () => {
+    const state = reduce({ type: INVOICE_CREATED_EVENT, payload: {} });
+    expect(state.status).toBe("draft");
+    expect(state.amount).toBe(0);
+  });
+
+  test("invoice-sent moves status to sent", () => {
+    const state = reduce(
+      { type: INVOICE_CREATED_EVENT, payload: { amount: 100 } },
+      { type: eventName(INVOICE_EVENTS.sent) },
+    );
+    expect(state.status).toBe("sent");
+  });
+
+  test("invoice-marked-paid moves status to paid", () => {
+    const state = reduce(
+      { type: INVOICE_CREATED_EVENT, payload: { amount: 100 } },
+      { type: eventName(INVOICE_EVENTS.sent) },
+      { type: eventName(INVOICE_EVENTS.markedPaid) },
+    );
+    expect(state.status).toBe("paid");
+  });
+
+  test("invoice-cancelled moves status to cancelled", () => {
+    const state = reduce(
+      { type: INVOICE_CREATED_EVENT, payload: { amount: 100 } },
+      { type: eventName(INVOICE_EVENTS.sent) },
+      { type: eventName(INVOICE_EVENTS.cancelled) },
+    );
+    expect(state.status).toBe("cancelled");
+  });
+
+  test("invoice-reopened moves status back to draft", () => {
+    const state = reduce(
+      { type: INVOICE_CREATED_EVENT, payload: { amount: 100 } },
+      { type: eventName(INVOICE_EVENTS.sent) },
+      { type: eventName(INVOICE_EVENTS.cancelled) },
+      { type: eventName(INVOICE_EVENTS.reopened) },
+    );
+    expect(state.status).toBe("draft");
+  });
+
+  test("invoice-status-forced applies the newStatus from payload", () => {
+    const state = reduce(
+      { type: INVOICE_CREATED_EVENT, payload: { amount: 100 } },
+      { type: eventName(INVOICE_EVENTS.statusForced), payload: { newStatus: "paid" } },
+    );
+    expect(state.status).toBe("paid");
+  });
+
+  test("amount stays after status transitions (only created mutates amount)", () => {
+    const state = reduce(
+      { type: INVOICE_CREATED_EVENT, payload: { amount: 999 } },
+      { type: eventName(INVOICE_EVENTS.sent) },
+      { type: eventName(INVOICE_EVENTS.cancelled) },
+    );
+    expect(state.amount).toBe(999);
+  });
+
+  test("unknown event types are ignored, state stays untouched", () => {
+    const state = reduce(
+      { type: INVOICE_CREATED_EVENT, payload: { amount: 100 } },
+      { type: "some-other-feature:event:nonsense", payload: { ignored: true } },
+    );
+    expect(state.status).toBe("draft");
+    expect(state.amount).toBe(100);
+  });
+});
+```
+
+### src/entities/invoice.ts
+
+```ts
+import {
+  createEntity,
+  createMoneyField,
+  createSelectField,
+  createTextField,
+  defineTransitions,
+} from "@app/define";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+
+export const INVOICE_STATES = ["draft", "sent", "paid", "cancelled"] as const;
+
+// Single source of truth for transitions — used by entity AND handlers
+const TRANSITION_CONFIG = {
+  draft: ["sent"],
+  sent: ["paid", "cancelled"],
+  paid: [],
+  cancelled: ["draft"], // reopen: cancelled → draft
+} as const;
+
+export const INVOICE_TRANSITIONS = defineTransitions(TRANSITION_CONFIG);
+
+export const invoiceEntity = createEntity({
+  table: "read_sample_sm_invoices",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    amount: createMoneyField({ required: true }),
+    status: createSelectField({ options: INVOICE_STATES, default: "draft" }),
+  },
+  defaultCurrency: "EUR",
+  transitions: {
+    status: TRANSITION_CONFIG,
+  },
+});
+
+export const invoiceTable = buildEntityTable("invoice", invoiceEntity);
+```
+
+### src/events.ts
+
+```ts
+// Single source of truth for event names. Keeps the reducer and the feature
+// in sync — both use INVOICE_EVENTS + eventName() to derive the qualified
+// strings, so a rename here propagates everywhere instead of silently
+// breaking the reducer.
+
+export const FEATURE_NAME = "billing";
+export const ENTITY_NAME = "invoice";
+
+// Short event names — passed to r.defineEvent("...") in feature.ts. The
+// framework qualifies them as "billing:event:<short>" at registration time.
+export const INVOICE_EVENTS = {
+  sent: "invoice-sent",
+  markedPaid: "invoice-marked-paid",
+  cancelled: "invoice-cancelled",
+  reopened: "invoice-reopened",
+  statusForced: "invoice-status-forced",
+} as const;
+
+// Qualifier used by the reducer to match events from the stream.
+// `<const TShort>` preserves the literal-string at the call-site, so
+// `eventName(INVOICE_EVENTS.sent)` carries `"billing:event:invoice-sent"`
+// as a literal type. That literal is what `ctx.appendEvent({ type, ... })`
+// strict-checks against the augmented `KumikoEventTypeMap`.
+export function eventName<const TShort extends string>(
+  short: TShort,
+): `${typeof FEATURE_NAME}:event:${TShort}` {
+  return `${FEATURE_NAME}:event:${short}` as `${typeof FEATURE_NAME}:event:${TShort}`;
+}
+
+// The auto-generated event the executor emits on create — entity name dot
+// "created", no feature prefix (executor convention).
+export const INVOICE_CREATED_EVENT = `${ENTITY_NAME}.created` as const;
+```
+
+### src/feature.ts
+
+```ts
+// State Machine Sample
+// Shows: defineTransitions, guardTransition (manual + auto), state machine via
+// event-sourced status changes. Each transition is its own domain event so the
+// audit log reads like the workflow ("invoice-sent", "invoice-cancelled"), not
+// like a SQL changelog ("status updated to sent").
+//
+// Workflow:
+//   draft → sent → paid       (happy path)
+//                 → cancelled  (abort)
+//   cancelled → draft          (reopen)
+//
+// Roles:
+//   Admin      — create, send, cancel, reopen, updateStatus, forceStatus
+//   Accounting — markPaid
+//
+// Files:
+//   entities/invoice.ts       — entity + table + transition config
+//   events.ts                 — single source of truth for event names
+//   reducer.ts                — derives status + amount from the event stream
+//   handlers/_helpers.ts      — shared transitionHandler + successResult
+//   handlers/create.ts        — invoice:create (uses executor)
+//   handlers/transitions.ts   — the six state-change handlers
+
+import { defineFeature, setFields } from "@app/define";
+import { z } from "zod";
+import { invoiceEntity, invoiceTable } from "./entities/invoice";
+import { eventName, INVOICE_EVENTS } from "./events";
+import { invoiceCreate } from "./handlers/create";
+import {
+  invoiceCancel,
+  invoiceForceStatus,
+  invoiceMarkPaid,
+  invoiceReopen,
+  invoiceSend,
+  invoiceUpdateStatus,
+} from "./handlers/transitions";
+import type { InvoiceStatus } from "./reducer";
+
+export { invoiceEntity } from "./entities/invoice";
+
+export const stateMachineFeature = defineFeature("billing", (r) => {
+  r.entity("invoice", invoiceEntity);
+
+  // Domain events — one per intent. Names live in events.ts so the reducer
+  // and the projection stay in sync. The auto "invoice.created" event from
+  // the executor's create-path covers the initial insert, so we only declare
+  // the state-change events here.
+  r.defineEvent(INVOICE_EVENTS.sent, z.object({}), { piiFields: "none" });
+  r.defineEvent(INVOICE_EVENTS.markedPaid, z.object({}), { piiFields: "none" });
+  r.defineEvent(INVOICE_EVENTS.cancelled, z.object({}), { piiFields: "none" });
+  r.defineEvent(INVOICE_EVENTS.reopened, z.object({}), { piiFields: "none" });
+  r.defineEvent(
+    INVOICE_EVENTS.statusForced,
+    z.object({
+      newStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
+      fromStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
+    }),
+    { piiFields: "none" },
+  );
+
+  // The aggregate table (sample_sm_invoices) is INSERTed by the executor on
+  // invoice:create. State-change events update the same row via this inline
+  // projection — keeps reads consistent with writes inside the same TX.
+  // setFields collapses "UPDATE <table> SET <cols> WHERE id = aggregateId"
+  // into a one-liner. Pass a literal for fixed-target events, a reducer fn
+  // for events that carry the new value in their payload.
+  r.projection({
+    name: "invoice-status",
+    source: "invoice",
+    table: invoiceTable,
+    apply: {
+      [eventName(INVOICE_EVENTS.sent)]: setFields(invoiceTable, { status: "sent" }),
+      [eventName(INVOICE_EVENTS.markedPaid)]: setFields(invoiceTable, { status: "paid" }),
+      [eventName(INVOICE_EVENTS.cancelled)]: setFields(invoiceTable, { status: "cancelled" }),
+      [eventName(INVOICE_EVENTS.reopened)]: setFields(invoiceTable, { status: "draft" }),
+      [eventName(INVOICE_EVENTS.statusForced)]: setFields(invoiceTable, (e) => ({
+        status: (e.payload as { newStatus: InvoiceStatus }).newStatus,
+      })),
+    },
+  });
+
+  r.writeHandler(invoiceCreate);
+  r.writeHandler(invoiceSend);
+  r.writeHandler(invoiceMarkPaid);
+  r.writeHandler(invoiceCancel);
+  r.writeHandler(invoiceReopen);
+  r.writeHandler(invoiceUpdateStatus);
+  r.writeHandler(invoiceForceStatus);
+});
+```
+
+### src/handlers/_helpers.ts
+
+```ts
+// Shared shape for every state-changing handler: load the current state,
+// optionally guardTransition, append the domain event, return a WriteResult
+// that reflects the post-write status.
+
+import type { AccessRule, KumikoEventTypeMap } from "@app/define";
+import { defineWriteHandler, guardTransition } from "@app/define";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { INVOICE_TRANSITIONS } from "../entities/invoice";
+import { ENTITY_NAME } from "../events";
+import { type InvoiceStatus, loadInvoiceState } from "../reducer";
+
+// Narrow TEvent to event-types whose payload is `{}` — this helper
+// always emits an empty payload. Anyone trying to use it with a non-
+// empty-payload event-type gets caught at the call-site, not at runtime.
+type EmptyPayloadEvent = {
+  [K in keyof KumikoEventTypeMap]: KumikoEventTypeMap[K] extends Record<string, never> ? K : never;
+}[keyof KumikoEventTypeMap];
+
+export function transitionHandler<const TEvent extends EmptyPayloadEvent>(opts: {
+  name: string;
+  toStatus: InvoiceStatus;
+  eventType: TEvent;
+  access: AccessRule;
+  skipGuard?: boolean;
+}) {
+  return defineWriteHandler({
+    name: opts.name,
+    schema: z.object({ id: z.uuid() }),
+    access: opts.access,
+    handler: async (event, ctx) => {
+      const state = await loadInvoiceState(ctx, event.payload.id);
+      if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
+
+      // state.status carries the "missing" virtual-state for aggregates
+      // that haven't been seen yet; loadInvoiceState already filters
+      // null, so at this point we know we're past existence. Cast to
+      // InvoiceStatus for the guard — "missing" can never appear after
+      // the !state check above.
+      if (!opts.skipGuard) {
+        guardTransition(INVOICE_TRANSITIONS, state.status as InvoiceStatus, opts.toStatus);
+      }
+
+      await ctx.appendEvent({
+        aggregateId: event.payload.id,
+        aggregateType: ENTITY_NAME,
+        type: opts.eventType,
+        payload: {},
+      });
+
+      return successResult(event.payload.id, opts.toStatus, state.status);
+    },
+  });
+}
+
+export function successResult(id: string, newStatus: InvoiceStatus, previousStatus: string) {
+  return {
+    isSuccess: true as const,
+    data: {
+      id,
+      data: { status: newStatus },
+      changes: { status: newStatus },
+      previous: { status: previousStatus },
+      isNew: false,
+      entityName: ENTITY_NAME,
+    },
+  };
+}
+```
+
+### src/handlers/create.ts
+
+```ts
+// Initial create — uses createEventStoreExecutor.create so the executor
+// generates the UUID, writes the auto "invoice.created" event onto the
+// stream, and inserts the projection row with status="draft" (entity-default).
+//
+// Schema is hand-written (not buildInsertSchema) because the public API
+// keeps amount + amountCurrency flat, while the entity stores them as a
+// money pair.
+
+import { defineWriteHandler } from "@app/define";
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { z } from "zod";
+import { invoiceEntity, invoiceTable } from "../entities/invoice";
+
+const invoiceExecutor = createEventStoreExecutor(invoiceTable, invoiceEntity, {
+  entityName: "invoice",
+});
+
+export const invoiceCreate = defineWriteHandler({
+  name: "invoice:create",
+  schema: z.object({
+    title: z.string().min(1),
+    amount: z.number(),
+    amountCurrency: z.string().length(3),
+  }),
+  access: { roles: ["Admin"] },
+  handler: async (event, ctx) => invoiceExecutor.create(event.payload, event.user, ctx.db),
+});
+```
+
+### src/handlers/transitions.ts
+
+```ts
+// All six state-change handlers in one place. Five of them follow the
+// transitionHandler shape verbatim; mark-paid and update-status carry a
+// little extra logic (amount-check, verb routing, dedicated forced-event)
+// and stay inline so the variation is visible at the call site.
+
+import { defineWriteHandler, guardTransition } from "@app/define";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { INVOICE_STATES, INVOICE_TRANSITIONS } from "../entities/invoice";
+import { ENTITY_NAME, eventName, INVOICE_EVENTS } from "../events";
+import { type InvoiceStatus, loadInvoiceState } from "../reducer";
+import { successResult, transitionHandler } from "./_helpers";
+
+const adminOnly = { roles: ["Admin"] } as const;
+
+// --- Standard transitions (same shape, different target status) ---
+
+export const invoiceSend = transitionHandler({
+  name: "invoice:send",
+  toStatus: "sent",
+  eventType: eventName(INVOICE_EVENTS.sent),
+  access: adminOnly,
+});
+
+export const invoiceCancel = transitionHandler({
+  name: "invoice:cancel",
+  toStatus: "cancelled",
+  eventType: eventName(INVOICE_EVENTS.cancelled),
+  access: adminOnly,
+});
+
+export const invoiceReopen = transitionHandler({
+  name: "invoice:reopen",
+  toStatus: "draft",
+  eventType: eventName(INVOICE_EVENTS.reopened),
+  access: adminOnly,
+});
+
+// --- markPaid: same shape + business rule (amount must be > 0).
+//     The amount is reduced from the event stream, so the check stays
+//     consistent with everything else (no out-of-band DB query).
+
+export const invoiceMarkPaid = defineWriteHandler({
+  name: "invoice:mark-paid",
+  schema: z.object({ id: z.uuid() }),
+  access: { roles: ["Accounting"] },
+  handler: async (event, ctx) => {
+    const state = await loadInvoiceState(ctx, event.payload.id);
+    if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
+
+    guardTransition(INVOICE_TRANSITIONS, state.status as InvoiceStatus, "paid");
+
+    if (state.amount === 0) {
+      return failUnprocessable("cannot_pay_zero_amount");
+    }
+
+    await ctx.appendEvent({
+      aggregateId: event.payload.id,
+      aggregateType: ENTITY_NAME,
+      type: eventName(INVOICE_EVENTS.markedPaid),
+      payload: {},
+    });
+
+    return successResult(event.payload.id, "paid", state.status);
+  },
+});
+
+// --- updateStatus: relies on the pipeline's auto transition guard.
+//     Routes the requested status to the matching domain event so the audit
+//     log still reads as a workflow step ("invoice-sent"), not a generic
+//     "status set to ...".
+
+// `as const satisfies` keeps the literal-strings alive (so each value is
+// `"billing:event:invoice-..."` literally typed, not just `string`) AND
+// type-checks the shape against `Record<InvoiceStatus, string>` —
+// missing-status entries fail at compile-time. Strict-mode for
+// ctx.appendEvent kicks in because `VERB_TO_EVENT[target]` resolves to
+// a union of literal event-names, all of which are augmented keys.
+const VERB_TO_EVENT = {
+  draft: eventName(INVOICE_EVENTS.reopened),
+  sent: eventName(INVOICE_EVENTS.sent),
+  paid: eventName(INVOICE_EVENTS.markedPaid),
+  cancelled: eventName(INVOICE_EVENTS.cancelled),
+} as const satisfies Record<InvoiceStatus, string>;
+
+export const invoiceUpdateStatus = defineWriteHandler({
+  name: "invoice:update-status",
+  schema: z.object({
+    id: z.uuid(),
+    changes: z.object({
+      status: z.enum(INVOICE_STATES),
+    }),
+  }),
+  access: adminOnly,
+  // No skipTransitionGuard — pipeline auto-guards.
+  handler: async (event, ctx) => {
+    const state = await loadInvoiceState(ctx, event.payload.id);
+    if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
+
+    const target = event.payload.changes.status;
+    await ctx.appendEvent({
+      aggregateId: event.payload.id,
+      aggregateType: ENTITY_NAME,
+      type: VERB_TO_EVENT[target],
+      payload: {},
+    });
+
+    return successResult(event.payload.id, target, state.status);
+  },
+});
+
+// --- forceStatus: skips the guard and emits a dedicated "forced" event so
+//     admin overrides stay visually distinct from normal workflow events in
+//     the audit log.
+
+export const invoiceForceStatus = defineWriteHandler({
+  name: "invoice:force-status",
+  schema: z.object({
+    id: z.uuid(),
+    status: z.enum(INVOICE_STATES),
+  }),
+  access: adminOnly,
+  unsafeSkipTransitionGuard: true,
+  handler: async (event, ctx) => {
+    const state = await loadInvoiceState(ctx, event.payload.id);
+    if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
+
+    await ctx.appendEvent({
+      aggregateId: event.payload.id,
+      aggregateType: ENTITY_NAME,
+      type: eventName(INVOICE_EVENTS.statusForced),
+      payload: { newStatus: event.payload.status, fromStatus: state.status as InvoiceStatus },
+    });
+
+    return successResult(event.payload.id, event.payload.status, state.status);
+  },
+});
+```
+
+### src/reducer.ts
+
+```ts
+// Reducer that derives invoice state from the event stream.
+//
+// Tracks `status` (used by transition guards + reported back in the
+// WriteResult) and `amount` (used by the mark-paid business rule).
+//
+// Adding a new state field? Extend InvoiceState, set it in `initialInvoiceState`,
+// and update the relevant `case` in `reduceInvoice` — that's the whole
+// contract.
+
+import type { HandlerContext } from "@app/define";
+import { eventName, INVOICE_CREATED_EVENT, INVOICE_EVENTS } from "./events";
+
+export type InvoiceStatus = "draft" | "sent" | "paid" | "cancelled";
+export type InvoiceState = {
+  status: InvoiceStatus | "missing";
+  amount: number;
+};
+
+export const initialInvoiceState: InvoiceState = { status: "missing", amount: 0 };
+
+export function reduceInvoice(state: InvoiceState, evt: { type: string; payload?: unknown }): void {
+  if (evt.type === INVOICE_CREATED_EVENT) {
+    const payload = evt.payload as { amount?: number };
+    state.status = "draft";
+    state.amount = payload.amount ?? 0;
+  } else if (evt.type === eventName(INVOICE_EVENTS.sent)) {
+    state.status = "sent";
+  } else if (evt.type === eventName(INVOICE_EVENTS.markedPaid)) {
+    state.status = "paid";
+  } else if (evt.type === eventName(INVOICE_EVENTS.cancelled)) {
+    state.status = "cancelled";
+  } else if (evt.type === eventName(INVOICE_EVENTS.reopened)) {
+    state.status = "draft";
+  } else if (evt.type === eventName(INVOICE_EVENTS.statusForced)) {
+    const payload = evt.payload as { newStatus: InvoiceStatus };
+    state.status = payload.newStatus;
+  }
+}
+
+export async function loadInvoiceState(
+  ctx: HandlerContext,
+  id: string,
+): Promise<InvoiceState | null> {
+  const events = await ctx.loadAggregate(id);
+  if (events.length === 0) return null;
+  const state: InvoiceState = { ...initialInvoiceState };
+  for (const evt of events) reduceInvoice(state, evt);
+  if (state.status === "missing") return null;
+  return state;
+}
+```