@cosmicdrift/kumiko-framework 0.1.0

package/src/pipeline/__tests__/fetch-for-writing.integration.ts

@@ -0,0 +1,281 @@
+// Runde 3 / C.2a — ctx.fetchForWriting (Marten FetchForWriting equivalent).
+//
+// Claims pinned here:
+//   1. Returns the current stream (upcasted) + its version.
+//   2. expectedVersion mismatch throws VersionConflictError BEFORE any write.
+//   3. appendOne reuses the handle's aggregateId/aggregateType + inherits
+//      the stream version internally — a sequence of appendOne calls writes
+//      consecutive versions without re-reading the DB.
+
+import { sql } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildDrizzleTable } from "../../db/table-builder";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import { UnprocessableError, writeFailure } from "../../errors";
+import { loadAggregate } from "../../event-store";
+import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+// --- Feature ---
+
+const cartEntity = createEntity({
+  table: "read_f4w_carts",
+  fields: {
+    customer: createTextField({ required: true }),
+  },
+});
+
+const cartTable = buildDrizzleTable("f4wCart", cartEntity);
+
+const cartFeature = defineFeature("f4w", (r) => {
+  r.entity("f4wCart", cartEntity);
+
+  const itemAdded = r.defineEvent("itemAdded", z.object({ sku: z.string(), qty: z.number() }));
+  const checkedOut = r.defineEvent("checkedOut", z.object({ totalCents: z.number() }));
+
+  const cartExecutor = createEventStoreExecutor(cartTable, cartEntity, {
+    entityName: "f4wCart",
+  });
+
+  // Root: create a cart.
+  r.writeHandler(
+    "cart:create",
+    z.object({ customer: z.string() }),
+    async (event, ctx) => cartExecutor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Fetch handle, inspect events, append one atom.
+  r.writeHandler(
+    "cart:add-item",
+    z.object({ id: z.uuid(), sku: z.string(), qty: z.number() }),
+    async (event, ctx) => {
+      const stream = await ctx.fetchForWriting({
+        aggregateId: event.payload.id,
+        aggregateType: "f4wCart",
+      });
+      // Business rule probe: if already checked out, refuse.
+      const alreadyDone = stream.events.some((e) => e.type === checkedOut.name);
+      if (alreadyDone) {
+        return writeFailure(new UnprocessableError("already_checked_out"));
+      }
+      await stream.appendOne({
+        type: itemAdded.name,
+        payload: { sku: event.payload.sku, qty: event.payload.qty },
+      });
+      return { isSuccess: true as const, data: { version: stream.version } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Fetch + multi-append in one handler (proves local version bumping).
+  r.writeHandler(
+    "cart:bulk-add",
+    z.object({ id: z.uuid(), skus: z.array(z.string()) }),
+    async (event, ctx) => {
+      const stream = await ctx.fetchForWriting({
+        aggregateId: event.payload.id,
+        aggregateType: "f4wCart",
+      });
+      for (const sku of event.payload.skus) {
+        await stream.appendOne({ type: itemAdded.name, payload: { sku, qty: 1 } });
+      }
+      return { isSuccess: true as const, data: { finalVersion: stream.version } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Drives the cart to checked-out state — lets the add-item handler's
+  // business-rule branch be exercised in a test.
+  r.writeHandler(
+    "cart:checkout",
+    z.object({ id: z.uuid(), totalCents: z.number() }),
+    async (event, ctx) => {
+      const stream = await ctx.fetchForWriting({
+        aggregateId: event.payload.id,
+        aggregateType: "f4wCart",
+      });
+      await stream.appendOne({
+        type: checkedOut.name,
+        payload: { totalCents: event.payload.totalCents },
+      });
+      return { isSuccess: true as const, data: {} };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Fetch with expectedVersion — OCC gate for external callers.
+  r.writeHandler(
+    "cart:add-with-occ",
+    z.object({
+      id: z.uuid(),
+      expectedVersion: z.number(),
+      sku: z.string(),
+    }),
+    async (event, ctx) => {
+      const stream = await ctx.fetchForWriting({
+        aggregateId: event.payload.id,
+        aggregateType: "f4wCart",
+        expectedVersion: event.payload.expectedVersion,
+      });
+      await stream.appendOne({
+        type: itemAdded.name,
+        payload: { sku: event.payload.sku, qty: 1 },
+      });
+      return { isSuccess: true as const, data: {} };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+// --- Stack ---
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [cartFeature], systemHooks: [] });
+  await createEntityTable(stack.db, cartEntity, "f4wCart");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  await stack.db.execute(
+    sql`TRUNCATE kumiko_events, read_f4w_carts, kumiko_event_consumers RESTART IDENTITY CASCADE`,
+  );
+  await stack.eventDispatcher?.ensureRegistered();
+});
+
+// --- Tests ---
+
+describe("Runde 3 / C.2a — ctx.fetchForWriting", () => {
+  test("returns current stream + version; appendOne advances the stream", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "alice" },
+      admin,
+    );
+
+    const result = await stack.http.writeOk<{ version: number }>(
+      "f4w:write:cart:add-item",
+      { id: created.id, sku: "apple", qty: 3 },
+      admin,
+    );
+    // CRUD create = v1, appendOne = v2.
+    expect(result.version).toBe(2);
+
+    const events = await loadAggregate(stack.db, created.id, admin.tenantId);
+    expect(events.map((e) => e.type)).toEqual(["f4wCart.created", "f4w:event:item-added"]);
+  });
+
+  test("multi-appendOne in one handler writes consecutive versions without re-reading", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "bob" },
+      admin,
+    );
+
+    const result = await stack.http.writeOk<{ finalVersion: number }>(
+      "f4w:write:cart:bulk-add",
+      { id: created.id, skus: ["a", "b", "c"] },
+      admin,
+    );
+    // CRUD = v1, then three appendOne = v2, v3, v4. Handle reports v4.
+    expect(result.finalVersion).toBe(4);
+
+    const events = await loadAggregate(stack.db, created.id, admin.tenantId);
+    expect(events.map((e) => e.version)).toEqual([1, 2, 3, 4]);
+  });
+
+  test("expectedVersion mismatch throws VersionConflictError before any write lands", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "carol" },
+      admin,
+    );
+
+    // Stream is at v1 (the create event). Caller thinks it's at v0 → conflict.
+    const res = await stack.http.write(
+      "f4w:write:cart:add-with-occ",
+      { id: created.id, expectedVersion: 0, sku: "pear" },
+      admin,
+    );
+    const body = (await res.json()) as { error?: { code?: string } };
+    expect(body.error?.code).toBe("version_conflict");
+
+    // Stream untouched — only the original create event is present.
+    const events = await loadAggregate(stack.db, created.id, admin.tenantId);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.type).toBe("f4wCart.created");
+  });
+
+  test("expectedVersion match lets the append proceed", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "dave" },
+      admin,
+    );
+
+    const res = await stack.http.write(
+      "f4w:write:cart:add-with-occ",
+      { id: created.id, expectedVersion: 1, sku: "peach" },
+      admin,
+    );
+    expect(res.status).toBe(200);
+
+    const events = await loadAggregate(stack.db, created.id, admin.tenantId);
+    expect(events).toHaveLength(2);
+  });
+
+  test("handle.events reflects business state — happy path keeps working", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "eve" },
+      admin,
+    );
+    // First add — no checked-out yet, rule-probe passes.
+    const first = await stack.http.write(
+      "f4w:write:cart:add-item",
+      { id: created.id, sku: "plum", qty: 1 },
+      admin,
+    );
+    expect(first.status).toBe(200);
+  });
+
+  test("business-rule probe on handle.events: after checkout, add-item refuses", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "frank" },
+      admin,
+    );
+
+    // Checkout lands a `checkedOut` event on the stream.
+    const checkoutRes = await stack.http.write(
+      "f4w:write:cart:checkout",
+      { id: created.id, totalCents: 4200 },
+      admin,
+    );
+    expect(checkoutRes.status).toBe(200);
+
+    // Now add-item should observe checkedOut via stream.events and refuse.
+    const res = await stack.http.write(
+      "f4w:write:cart:add-item",
+      { id: created.id, sku: "late-banana", qty: 1 },
+      admin,
+    );
+    const body = (await res.json()) as { isSuccess: boolean; error?: { code?: string } };
+    expect(body.isSuccess).toBe(false);
+    expect(body.error?.code).toBe("unprocessable");
+
+    // Stream untouched by the refused add — only create + checkedOut remain.
+    const events = await loadAggregate(stack.db, created.id, admin.tenantId);
+    const types = events.map((e) => e.type);
+    expect(types).toContain("f4wCart.created");
+    expect(types).toContain("f4w:event:checked-out");
+    expect(types).not.toContain("f4w:event:item-added");
+  });
+});

package/src/pipeline/__tests__/lifecycle-pipeline.test.ts

@@ -0,0 +1,430 @@
+import { describe, expect, test, vi } from "vitest";
+import { z } from "zod";
+import {
+  createEntity,
+  createRegistry,
+  createTextField,
+  defineFeature,
+  type PostSaveHookFn,
+  type PreSaveHookFn,
+  type SaveContext,
+} from "../../engine";
+import { buildEventId, createLifecycleHooks, type SystemHooks } from "../lifecycle-pipeline";
+
+function makeRegistry(hooks?: { preSave?: PreSaveHookFn[]; postSave?: PostSaveHookFn[] }) {
+  const feature = defineFeature("test", (r) => {
+    r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+    // Dummy handler so hook targets resolve (boot validation requires it)
+    r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+      access: { openToAll: true },
+    });
+    if (hooks?.preSave) {
+      for (const h of hooks.preSave) r.hook("preSave", "user", h);
+    }
+    if (hooks?.postSave) {
+      for (const h of hooks.postSave) r.hook("postSave", "user", h);
+    }
+  });
+  return createRegistry([feature]);
+}
+
+const savectx: SaveContext = {
+  kind: "save",
+  id: 1,
+  data: { email: "test@test.de", tenantId: "00000000-0000-4000-8000-000000000001" },
+  changes: { email: "test@test.de" },
+  previous: {},
+  isNew: true,
+};
+
+// --- PreSave pipeline ---
+
+describe("runPreSave", () => {
+  test("runs feature hooks in order", async () => {
+    const calls: string[] = [];
+    const registry = makeRegistry({
+      preSave: [
+        async (changes) => {
+          calls.push("a");
+          return changes;
+        },
+        async (changes) => {
+          calls.push("b");
+          return changes;
+        },
+      ],
+    });
+
+    const pipeline = createLifecycleHooks(registry);
+    await pipeline.runPreSave("test:write:user", { email: "x" }, {}, true, {});
+    expect(calls).toEqual(["a", "b"]);
+  });
+
+  test("feature hooks can modify changes", async () => {
+    const registry = makeRegistry({
+      preSave: [
+        async (changes) => ({ ...changes, email: (changes["email"] as string).toLowerCase() }),
+      ],
+    });
+
+    const pipeline = createLifecycleHooks(registry);
+    const result = await pipeline.runPreSave(
+      "test:write:user",
+      { email: "MARC@TEST.DE" },
+      {},
+      true,
+      {},
+    );
+    expect(result["email"]).toBe("marc@test.de");
+  });
+
+  test("system hooks run after feature hooks", async () => {
+    const calls: string[] = [];
+    const registry = makeRegistry({
+      preSave: [
+        async (changes) => {
+          calls.push("feature");
+          return changes;
+        },
+      ],
+    });
+
+    const systemHooks: SystemHooks = {
+      preSave: [
+        {
+          name: "sys",
+          priority: 1000,
+          fn: async (changes) => {
+            calls.push("system");
+            return changes;
+          },
+        },
+      ],
+    };
+
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPreSave("test:write:user", {}, {}, true, {});
+    expect(calls).toEqual(["feature", "system"]);
+  });
+
+  test("system hooks sorted by priority", async () => {
+    const calls: string[] = [];
+    const registry = makeRegistry();
+
+    const systemHooks: SystemHooks = {
+      preSave: [
+        {
+          name: "b",
+          priority: 2000,
+          fn: async (changes) => {
+            calls.push("b");
+            return changes;
+          },
+        },
+        {
+          name: "a",
+          priority: 1000,
+          fn: async (changes) => {
+            calls.push("a");
+            return changes;
+          },
+        },
+      ],
+    };
+
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPreSave("test:write:user", {}, {}, true, {});
+    expect(calls).toEqual(["a", "b"]);
+  });
+
+  test("preSave abort stops pipeline", async () => {
+    const registry = makeRegistry({
+      preSave: [
+        async () => {
+          throw new Error("blocked");
+        },
+      ],
+    });
+
+    const pipeline = createLifecycleHooks(registry);
+    await expect(pipeline.runPreSave("test:write:user", {}, {}, true, {})).rejects.toThrow(
+      "blocked",
+    );
+  });
+});
+
+// --- PostSave pipeline ---
+
+describe("runPostSave", () => {
+  test("runs feature hooks then system hooks", async () => {
+    const calls: string[] = [];
+    const registry = makeRegistry({
+      postSave: [
+        async () => {
+          calls.push("feature");
+        },
+      ],
+    });
+
+    const systemHooks: SystemHooks = {
+      postSave: [
+        {
+          name: "search",
+          priority: 1000,
+          fn: async () => {
+            calls.push("search");
+          },
+        },
+        {
+          name: "sse",
+          priority: 1001,
+          fn: async () => {
+            calls.push("sse");
+          },
+        },
+        {
+          name: "audit",
+          priority: 1002,
+          fn: async () => {
+            calls.push("audit");
+          },
+        },
+      ],
+    };
+
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPostSave("test:write:user", savectx, {});
+    expect(calls).toEqual(["feature", "search", "sse", "audit"]);
+  });
+
+  test("postSave errors don't throw — logged and continued", async () => {
+    const calls: string[] = [];
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const registry = makeRegistry({
+      postSave: [
+        async () => {
+          throw new Error("feature-fail");
+        },
+      ],
+    });
+
+    const systemHooks: SystemHooks = {
+      postSave: [
+        {
+          name: "search",
+          priority: 1000,
+          fn: async () => {
+            calls.push("search-ran");
+          },
+        },
+      ],
+    };
+
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    // Should not throw
+    await pipeline.runPostSave("test:write:user", savectx, {});
+
+    // System hook still ran despite feature hook failure
+    expect(calls).toContain("search-ran");
+    expect(consoleSpy).toHaveBeenCalled();
+    consoleSpy.mockRestore();
+  });
+
+  test("system hook failure doesn't block other system hooks", async () => {
+    const calls: string[] = [];
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const registry = makeRegistry();
+
+    const systemHooks: SystemHooks = {
+      postSave: [
+        {
+          name: "search",
+          priority: 1000,
+          fn: async () => {
+            throw new Error("meili-down");
+          },
+        },
+        {
+          name: "sse",
+          priority: 1001,
+          fn: async () => {
+            calls.push("sse-ran");
+          },
+        },
+        {
+          name: "audit",
+          priority: 1002,
+          fn: async () => {
+            calls.push("audit-ran");
+          },
+        },
+      ],
+    };
+
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPostSave("test:write:user", savectx, {});
+
+    expect(calls).toEqual(["sse-ran", "audit-ran"]);
+    consoleSpy.mockRestore();
+  });
+});
+
+// --- Phase routing ---
+//
+// runPostSave takes a phase parameter and fires ONLY hooks matching that phase.
+// Error semantics also differ per phase:
+//   - inTransaction hooks throw on error (to roll back the transaction)
+//   - afterCommit hooks are best-effort (errors are logged, never thrown)
+
+describe("runPostSave phase routing", () => {
+  test("runs only hooks matching the given phase", async () => {
+    const calls: string[] = [];
+    const feature = defineFeature("phases", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook(
+        "postSave",
+        "user",
+        async () => {
+          calls.push("inTx");
+        },
+        { phase: "inTransaction" },
+      );
+      r.hook("postSave", "user", async () => {
+        calls.push("afterCommit");
+      });
+    });
+    const registry = createRegistry([feature]);
+    const pipeline = createLifecycleHooks(registry);
+
+    await pipeline.runPostSave("phases:write:user", savectx, {}, "inTransaction");
+    expect(calls).toEqual(["inTx"]);
+
+    calls.length = 0;
+    await pipeline.runPostSave("phases:write:user", savectx, {}, "afterCommit");
+    expect(calls).toEqual(["afterCommit"]);
+  });
+
+  test("inTransaction phase: hook errors throw (to roll back)", async () => {
+    const feature = defineFeature("phases", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook(
+        "postSave",
+        "user",
+        async () => {
+          throw new Error("inTx-hook-boom");
+        },
+        { phase: "inTransaction" },
+      );
+    });
+    const registry = createRegistry([feature]);
+    const pipeline = createLifecycleHooks(registry);
+
+    await expect(
+      pipeline.runPostSave("phases:write:user", savectx, {}, "inTransaction"),
+    ).rejects.toThrow("inTx-hook-boom");
+  });
+
+  test("afterCommit phase: hook errors are logged, never thrown", async () => {
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const afterRan: string[] = [];
+    const feature = defineFeature("phases", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("postSave", "user", async () => {
+        throw new Error("afterCommit-boom");
+      });
+      r.hook("postSave", "user", async () => {
+        afterRan.push("second");
+      });
+    });
+    const registry = createRegistry([feature]);
+    const pipeline = createLifecycleHooks(registry);
+
+    // Must not throw — errors are swallowed + logged
+    await pipeline.runPostSave("phases:write:user", savectx, {}, "afterCommit");
+
+    // Subsequent hooks still fire (failure in one hook doesn't block the rest)
+    expect(afterRan).toEqual(["second"]);
+    expect(consoleSpy).toHaveBeenCalled();
+    consoleSpy.mockRestore();
+  });
+
+  test("system hooks respect their phase setting", async () => {
+    const feature = defineFeature("phases", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true, data: null }), {
+        access: { openToAll: true },
+      });
+    });
+    const registry = createRegistry([feature]);
+
+    const calls: string[] = [];
+    const systemHooks: SystemHooks = {
+      postSave: [
+        {
+          name: "audit",
+          priority: 1002,
+          phase: "inTransaction",
+          fn: async () => {
+            calls.push("audit");
+          },
+        },
+        {
+          name: "sse",
+          priority: 1001,
+          phase: "afterCommit",
+          fn: async () => {
+            calls.push("sse");
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+
+    await pipeline.runPostSave("phases:write:user", savectx, {}, "inTransaction");
+    expect(calls).toEqual(["audit"]);
+
+    calls.length = 0;
+    await pipeline.runPostSave("phases:write:user", savectx, {}, "afterCommit");
+    expect(calls).toEqual(["sse"]);
+  });
+});
+
+describe("buildEventId — dedup key construction", () => {
+  test("includes handler, id, version and phase when payload is complete", () => {
+    const payload = { id: 42, data: { version: 3 } };
+    expect(buildEventId("users:write:user:create", payload, "postSave:afterCommit")).toBe(
+      "users:write:user:create:42:3:postSave:afterCommit",
+    );
+  });
+
+  test("falls back to version 0 when payload has no data.version", () => {
+    const payload = { id: 42 };
+    expect(buildEventId("handler", payload, "phase")).toBe("handler:42:0:phase");
+  });
+
+  test("returns null when payload is not an object (no dedup possible)", () => {
+    expect(buildEventId("handler", null, "phase")).toBeNull();
+    expect(buildEventId("handler", undefined, "phase")).toBeNull();
+    expect(buildEventId("handler", "string", "phase")).toBeNull();
+    expect(buildEventId("handler", 123, "phase")).toBeNull();
+  });
+
+  test("returns null when payload has no id — triggers the warn-log path in runHookSet", () => {
+    expect(buildEventId("handler", {}, "phase")).toBeNull();
+    expect(buildEventId("handler", { data: { version: 5 } }, "phase")).toBeNull();
+    // id=0 is also treated as absent: serial PKs start at 1, so 0 means
+    // "never inserted" — safer to skip dedup than to collide on a sentinel.
+    expect(buildEventId("handler", { id: 0 }, "phase")).toBeNull();
+  });
+});