@cosmicdrift/kumiko-framework 0.1.0

package/src/pipeline/__tests__/load-aggregate-query.integration.ts

@@ -0,0 +1,266 @@
+// B2 — ctx.loadAggregate HTTP-surface for live aggregation + asOf.
+//
+// Marten's AggregateStreamAsync<T>(id[, version|timestamp]) in TypeScript
+// shape: ctx.loadAggregate(id[, { asOf }]). A queryHandler reduces the
+// returned events into whatever domain-state shape the feature wants.
+// Events are upcasted by the dispatcher, so the reducer sees the current
+// payload shape even for old v1 events.
+
+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 { append, loadAggregate as loadAggregateRaw } from "../../event-store";
+import {
+  createEntityTable,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "../../stack";
+
+// --- Fixture entity ---
+
+const invoiceEntity = createEntity({
+  table: "read_asof_invoices",
+  fields: {
+    customer: createTextField({ required: true }),
+    status: createTextField({ required: true }),
+  },
+});
+const invoiceTable = buildDrizzleTable("asof-invoice", invoiceEntity);
+
+// --- Feature ---
+
+const asOfFeature = defineFeature("asoftest", (r) => {
+  r.entity("asof-invoice", invoiceEntity);
+
+  // Two domain events at different versions. v1→v2 migration bumps the
+  // "amount" field from string to integer cents, same pattern as B1.
+  const approved = r.defineEvent(
+    "approved",
+    z.object({ amount: z.number().int(), approvedBy: z.string() }),
+    { version: 2 },
+  );
+  r.eventMigration("approved", 1, 2, (payload) => {
+    const p = payload as { amount: string; approvedBy: string };
+    return {
+      amount: Math.round(Number.parseFloat(p.amount) * 100),
+      approvedBy: p.approvedBy,
+    };
+  });
+
+  const executor = createEventStoreExecutor(invoiceTable, invoiceEntity, {
+    entityName: "asof-invoice",
+  });
+
+  r.writeHandler(
+    "invoice:create",
+    z.object({ customer: z.string(), status: z.string() }),
+    async (event, ctx) => executor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "invoice:approve",
+    z.object({ id: z.uuid(), amount: z.number().int(), approvedBy: z.string() }),
+    async (event, ctx) => {
+      await ctx.appendEventUnsafe({
+        aggregateId: event.payload.id,
+        aggregateType: "asof-invoice",
+        type: approved.name,
+        payload: { amount: event.payload.amount, approvedBy: event.payload.approvedBy },
+      });
+      return { isSuccess: true as const, data: { id: event.payload.id } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Query handler — reduces raw events into a derived shape via
+  // ctx.loadAggregate. Exposes live aggregation over HTTP.
+  r.queryHandler(
+    "invoice:state",
+    z.object({
+      id: z.uuid(),
+      asOf: z.iso.datetime().optional(),
+    }),
+    async (query, ctx) => {
+      const events = await ctx.loadAggregate(query.payload.id, {
+        ...(query.payload.asOf ? { asOf: Temporal.Instant.from(query.payload.asOf) } : {}),
+      });
+      // Simple reducer: collect created + approved facts, ignore the rest.
+      const state: {
+        id: string | null;
+        customer: string | null;
+        status: string;
+        approved: boolean;
+        approvedAmountCents: number | null;
+        approvedBy: string | null;
+      } = {
+        id: null,
+        customer: null,
+        status: "unknown",
+        approved: false,
+        approvedAmountCents: null,
+        approvedBy: null,
+      };
+      for (const evt of events) {
+        if (evt.type === "asof-invoice.created") {
+          const p = evt.payload as { id: string; customer: string; status: string };
+          state.id = p.id;
+          state.customer = p.customer;
+          state.status = p.status;
+        } else if (evt.type === approved.name) {
+          const p = evt.payload as { amount: number; approvedBy: string };
+          state.approved = true;
+          state.approvedAmountCents = p.amount;
+          state.approvedBy = p.approvedBy;
+        }
+      }
+      return state;
+    },
+    { access: { openToAll: true } },
+  );
+});
+
+// --- Test stack ---
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [asOfFeature], systemHooks: [] });
+  await createEntityTable(stack.db, invoiceEntity, "asof-invoice");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  await resetEventStore(stack, ["read_asof_invoices"]);
+});
+
+// --- Tests ---
+
+describe("ctx.loadAggregate via queryHandler — Marten AggregateStreamAsync equivalent", () => {
+  test("reduces created + approved events into current state", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "asoftest:write:invoice:create",
+      { customer: "Acme", status: "draft" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "asoftest:write:invoice:approve",
+      { id: created.id, amount: 1500, approvedBy: "boss" },
+      admin,
+    );
+
+    const state = await stack.http.queryOk<{
+      id: string;
+      customer: string;
+      status: string;
+      approved: boolean;
+      approvedAmountCents: number | null;
+      approvedBy: string | null;
+    }>("asoftest:query:invoice:state", { id: created.id }, admin);
+
+    expect(state.customer).toBe("Acme");
+    expect(state.approved).toBe(true);
+    expect(state.approvedAmountCents).toBe(1500);
+    expect(state.approvedBy).toBe("boss");
+  });
+
+  test("asOf excludes events after the given timestamp — Marten point-in-time read", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "asoftest:write:invoice:create",
+      { customer: "TimeTraveler", status: "draft" },
+      admin,
+    );
+    // Capture the event timestamp from the events-table for a precise cutoff.
+    // A too-small offset risks clock granularity flakes — we rely on the
+    // millisecond-precision timestamp column.
+    const preApprove = new Date();
+    // Make sure the next event's createdAt is strictly after the cutoff.
+    await new Promise((r) => setTimeout(r, 10));
+    await stack.http.writeOk(
+      "asoftest:write:invoice:approve",
+      { id: created.id, amount: 9999, approvedBy: "late" },
+      admin,
+    );
+
+    // "Current" state sees the approval.
+    const now = await stack.http.queryOk<{ approved: boolean }>(
+      "asoftest:query:invoice:state",
+      { id: created.id },
+      admin,
+    );
+    expect(now.approved).toBe(true);
+
+    // asOf preApprove: the approval is in the future, not yet visible.
+    const past = await stack.http.queryOk<{ approved: boolean; status: string }>(
+      "asoftest:query:invoice:state",
+      { id: created.id, asOf: preApprove.toISOString() },
+      admin,
+    );
+    expect(past.approved).toBe(false);
+    expect(past.status).toBe("draft");
+  });
+
+  test("payloads are upcasted — v1-on-disk events reach the reducer as v2", async () => {
+    // Appending directly at eventVersion=1 (older shape) simulates data
+    // that predates the current event version. The reducer is written
+    // against v2 (integer cents) — without upcasting it would blow up or
+    // produce garbage.
+    const invoiceId = "00000000-0000-4000-8000-000000000042";
+    await stack.db.transaction(async (tx) => {
+      await tx.insert(invoiceTable).values({
+        id: invoiceId,
+        tenantId: admin.tenantId,
+        customer: "LegacyCo",
+        status: "imported",
+      });
+
+      // Initial "created" event at v1 of that too — but asofInvoice.created
+      // has no migration, its eventVersion is irrelevant here.
+      await append(tx, {
+        aggregateId: invoiceId,
+        aggregateType: "asof-invoice",
+        tenantId: admin.tenantId,
+        expectedVersion: 0,
+        type: "asof-invoice.created",
+        payload: { id: invoiceId, customer: "LegacyCo", status: "imported" },
+        metadata: { userId: admin.id },
+      });
+      await append(tx, {
+        aggregateId: invoiceId,
+        aggregateType: "asof-invoice",
+        tenantId: admin.tenantId,
+        expectedVersion: 1,
+        type: "asoftest:event:approved",
+        eventVersion: 1,
+        payload: { amount: "42.50", approvedBy: "legacy" },
+        metadata: { userId: admin.id },
+      });
+    });
+
+    const state = await stack.http.queryOk<{
+      approved: boolean;
+      approvedAmountCents: number | null;
+      approvedBy: string | null;
+    }>("asoftest:query:invoice:state", { id: invoiceId }, admin);
+
+    // "42.50" EUR → 4250 cents after the v1→v2 upcaster runs on read.
+    expect(state.approved).toBe(true);
+    expect(state.approvedAmountCents).toBe(4250);
+    expect(state.approvedBy).toBe("legacy");
+
+    // Raw reader (no upcasting) still sees the original shape on disk —
+    // upcasting is a read-time transform, writes stay immutable.
+    const raw = await loadAggregateRaw(stack.db, invoiceId, admin.tenantId);
+    const rawApproved = raw.find((e) => e.type === "asoftest:event:approved");
+    expect(rawApproved?.eventVersion).toBe(1);
+    expect(rawApproved?.payload).toEqual({ amount: "42.50", approvedBy: "legacy" });
+  });
+});

package/src/pipeline/__tests__/msp-error-mode.integration.ts

@@ -0,0 +1,149 @@
+// Runde 2 / C.4 — MSP errorMode.continuous.skipApplyErrors
+//
+// Default (strict) behaviour: a throwing apply retries up to maxAttempts,
+// then the consumer status flips to "dead" and delivery pauses. Correct for
+// read-models that must stay consistent.
+//
+// For best-effort sinks (notifications, webhooks, metrics fan-out) a single
+// bad event shouldn't stall the whole consumer. skipApplyErrors=true logs the
+// error on the skip counter, advances the cursor, and keeps delivering. The
+// consumer stays "idle".
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { defineFeature } from "../../engine";
+import { getConsumerState } from "../../pipeline";
+import {
+  createEntityTable,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "../../stack";
+import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+
+// --- Feature ---
+
+const executor = createEventStoreExecutor(sharedWidgetTable, sharedWidgetEntity, {
+  entityName: "widget",
+});
+
+// Two MSPs reacting to the same event type:
+//   - strict: default behavior, poison event kills the consumer
+//   - lenient: skipApplyErrors, poison event gets skipped, delivery continues
+// Poison selector is by payload.name so each test can inject a bad event
+// at a known position in the stream.
+const POISON_MARKER = "poison";
+
+const strictObserved: string[] = [];
+const lenientObserved: string[] = [];
+
+const z2Feature = defineFeature("errmode", (r) => {
+  r.entity("widget", sharedWidgetEntity);
+
+  r.multiStreamProjection({
+    name: "strict",
+    apply: {
+      "widget.created": async (event) => {
+        const name = event.payload["name"] as string;
+        if (name === POISON_MARKER) throw new Error("boom-strict");
+        strictObserved.push(name);
+      },
+    },
+    // errorMode omitted → default strict
+  });
+
+  r.multiStreamProjection({
+    name: "lenient",
+    apply: {
+      "widget.created": async (event) => {
+        const name = event.payload["name"] as string;
+        if (name === POISON_MARKER) throw new Error("boom-lenient");
+        lenientObserved.push(name);
+      },
+    },
+    errorMode: { continuous: { skipApplyErrors: true } },
+  });
+});
+
+// --- Stack ---
+
+let stack: TestStack;
+let tdb: TenantDb;
+const admin = TestUsers.admin;
+const strictQn = "errmode:projection:strict";
+const lenientQn = "errmode:projection:lenient";
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [z2Feature],
+    systemHooks: [],
+  });
+  await createEntityTable(stack.db, sharedWidgetEntity, "widget");
+  tdb = createTenantDb(stack.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  strictObserved.length = 0;
+  lenientObserved.length = 0;
+  await resetEventStore(stack, ["read_widgets"]);
+});
+
+async function appendWidget(name: string): Promise<void> {
+  await executor.create({ name }, admin, tdb);
+}
+
+// --- Tests ---
+
+describe("Runde 2 / C.4 — MSP skipApplyErrors", () => {
+  test("default strict: poison event halts the consumer, cursor stops at predecessor", async () => {
+    await appendWidget("a");
+    await appendWidget(POISON_MARKER);
+    await appendWidget("c"); // would only be delivered AFTER the poison is resolved
+
+    // Drive the dispatcher hard enough to exhaust maxAttempts on the poison.
+    for (let i = 0; i < 15; i++) {
+      await stack.eventDispatcher?.runOnce();
+    }
+
+    // Strict consumer saw "a" but nothing past it — the poison blocked it.
+    expect(strictObserved).toEqual(["a"]);
+    const state = await getConsumerState(stack.db, strictQn);
+    expect(state?.status).toBe("dead");
+    expect(state?.lastError).toMatch(/boom-strict/);
+  });
+
+  test("lenient: poison event is skipped, cursor advances, later events are delivered", async () => {
+    await appendWidget("a");
+    await appendWidget(POISON_MARKER);
+    await appendWidget("c");
+
+    await stack.eventDispatcher?.runOnce();
+
+    // Lenient consumer skipped the poison and saw "c".
+    expect(lenientObserved).toEqual(["a", "c"]);
+    // State stays idle — no dead-letter, no retry.
+    const state = await getConsumerState(stack.db, lenientQn);
+    expect(state?.status).toBe("idle");
+    // Cursor advanced past all three events (latest event id = 3).
+    expect(state?.lastProcessedEventId).toBe(3n);
+  });
+
+  test("lenient: multiple poison events in a row all get skipped", async () => {
+    await appendWidget(POISON_MARKER);
+    await appendWidget(POISON_MARKER);
+    await appendWidget("survivor");
+
+    await stack.eventDispatcher?.runOnce();
+
+    expect(lenientObserved).toEqual(["survivor"]);
+    const state = await getConsumerState(stack.db, lenientQn);
+    expect(state?.status).toBe("idle");
+    expect(state?.lastProcessedEventId).toBe(3n);
+  });
+});

package/src/pipeline/__tests__/msp-multi-hop.integration.ts

@@ -0,0 +1,228 @@
+// Runde 3 / C.2b — MSP-apply ctx.appendEvent cascades (saga / process-manager).
+//
+// Claims pinned here:
+//   1. MSP-apply receives an optional 3rd ctx arg with appendEvent + loadAggregate.
+//   2. ctx.appendEvent from inside apply writes a follow-up event into the
+//      CURRENT transaction on the aggregate stream the caller picks.
+//   3. The follow-up event inherits correlationId from the triggering event
+//      and records causationId = triggering event.id.
+//   4. A second MSP reacting to the follow-up appends its own event, completing
+//      a three-hop causal chain (order.placed → order.confirmed → order.shipped).
+//   5. ctx.loadAggregate reads the triggering stream's full history.
+
+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 { eventsTable } from "../../event-store";
+import {
+  createEntityTable,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "../../stack";
+
+// --- Feature ---
+
+const orderEntity = createEntity({
+  table: "read_mmh_orders",
+  fields: {
+    item: createTextField({ required: true }),
+  },
+});
+
+const orderTable = buildDrizzleTable("mmh-order", orderEntity);
+
+// Snapshot what each MSP-apply observed via ctx.loadAggregate.
+const confirmLoadCounts: number[] = [];
+
+const mmhFeature = defineFeature("mmh", (r) => {
+  r.entity("mmh-order", orderEntity);
+
+  const placed = r.defineEvent("placed", z.object({ orderId: z.uuid() }));
+  const confirmed = r.defineEvent("confirmed", z.object({ orderId: z.uuid() }));
+  const shipped = r.defineEvent("shipped", z.object({ orderId: z.uuid() }));
+
+  const orderExecutor = createEventStoreExecutor(orderTable, orderEntity, {
+    entityName: "mmh-order",
+  });
+
+  r.writeHandler(
+    "order:place",
+    z.object({ item: z.string() }),
+    async (event, ctx) => {
+      const created = await orderExecutor.create({ item: event.payload.item }, event.user, ctx.db);
+      if (!created.isSuccess) return created;
+      await ctx.appendEventUnsafe({
+        aggregateId: String(created.data.id),
+        aggregateType: "mmh-order",
+        type: placed.name,
+        payload: { orderId: String(created.data.id) },
+      });
+      return created;
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Hop 1: placed → confirmed. Uses ctx.loadAggregate to observe the current
+  // stream before deciding + ctx.appendEvent to cascade.
+  r.multiStreamProjection({
+    name: "confirm-on-placed",
+    apply: {
+      [placed.name]: async (event, _tx, ctx) => {
+        if (!ctx) throw new Error("MSP-apply ctx missing — regression of C.2b wiring");
+        const history = await ctx.loadAggregate(event.aggregateId);
+        confirmLoadCounts.push(history.length);
+        await ctx.appendEventUnsafe({
+          aggregateId: event.aggregateId,
+          aggregateType: "mmh-order",
+          type: confirmed.name,
+          payload: { orderId: event.aggregateId },
+        });
+      },
+    },
+  });
+
+  // Hop 2: confirmed → shipped.
+  r.multiStreamProjection({
+    name: "ship-on-confirmed",
+    apply: {
+      [confirmed.name]: async (event, _tx, ctx) => {
+        if (!ctx) throw new Error("MSP-apply ctx missing — regression of C.2b wiring");
+        await ctx.appendEventUnsafe({
+          aggregateId: event.aggregateId,
+          aggregateType: "mmh-order",
+          type: shipped.name,
+          payload: { orderId: event.aggregateId },
+        });
+      },
+    },
+  });
+});
+
+// --- Stack ---
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [mmhFeature], systemHooks: [] });
+  await createEntityTable(stack.db, orderEntity, "mmh-order");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  confirmLoadCounts.length = 0;
+  await resetEventStore(stack, ["read_mmh_orders"]);
+});
+
+// --- Helpers ---
+
+async function postWrite(correlationId: string, item: string) {
+  return stack.http.writeWithHeaders("mmh:write:order:place", { item }, admin, {
+    "X-Correlation-ID": correlationId,
+  });
+}
+
+async function drainUntilShipped(aggregateId: string, maxPasses = 10): Promise<void> {
+  for (let i = 0; i < maxPasses; i++) {
+    await stack.eventDispatcher?.runOnce();
+    const rows = await stack.db.select().from(eventsTable);
+    if (rows.some((r) => r.aggregateId === aggregateId && r.type === "mmh:event:shipped")) return;
+  }
+  throw new Error(`drainUntilShipped: never saw shipped event for ${aggregateId}`);
+}
+
+// --- Tests ---
+
+describe("Runde 3 / C.2b — MSP-apply ctx cascades", () => {
+  test("single-hop: apply appends a follow-up on the triggering aggregate", async () => {
+    const res = await postWrite("hop-1", "widget");
+    expect(res.status).toBe(200);
+
+    await stack.eventDispatcher?.runOnce();
+
+    const rows = await stack.db.select().from(eventsTable);
+    const types = rows.map((r) => r.type).sort();
+    // Order: CRUD create, placed, confirmed (hop 1 fired).
+    expect(types).toContain("mmh-order.created");
+    expect(types).toContain("mmh:event:placed");
+    expect(types).toContain("mmh:event:confirmed");
+  });
+
+  test("three-hop chain: all events share correlationId, causation traces placed→confirmed→shipped", async () => {
+    await postWrite("chain-xyz", "rotor");
+
+    // Find the aggregateId from the first placed event.
+    await stack.eventDispatcher?.runOnce();
+    const placedRow = (await stack.db.select().from(eventsTable)).find(
+      (r) => r.type === "mmh:event:placed",
+    );
+    expect(placedRow).toBeDefined();
+    const aggregateId = placedRow?.aggregateId as string;
+
+    await drainUntilShipped(aggregateId);
+
+    const rows = (await stack.db.select().from(eventsTable))
+      .filter((r) => r.aggregateId === aggregateId)
+      .sort((a, b) => Number(a.id - b.id));
+
+    const placed = rows.find((r) => r.type === "mmh:event:placed");
+    const confirmed = rows.find((r) => r.type === "mmh:event:confirmed");
+    const shipped = rows.find((r) => r.type === "mmh:event:shipped");
+
+    expect(placed).toBeDefined();
+    expect(confirmed).toBeDefined();
+    expect(shipped).toBeDefined();
+
+    const placedMeta = placed?.metadata as {
+      correlationId?: string;
+      causationId?: string;
+    };
+    const confirmedMeta = confirmed?.metadata as {
+      correlationId?: string;
+      causationId?: string;
+    };
+    const shippedMeta = shipped?.metadata as {
+      correlationId?: string;
+      causationId?: string;
+    };
+
+    // All three carry the same correlationId.
+    expect(placedMeta.correlationId).toBe("chain-xyz");
+    expect(confirmedMeta.correlationId).toBe("chain-xyz");
+    expect(shippedMeta.correlationId).toBe("chain-xyz");
+
+    // Causation chain: placed is root; each later hop points back to the
+    // event that triggered its MSP.
+    expect(placedMeta.causationId).toBeUndefined();
+    expect(confirmedMeta.causationId).toBe(String(placed?.id));
+    expect(shippedMeta.causationId).toBe(String(confirmed?.id));
+  });
+
+  test("ctx.loadAggregate inside apply sees the stream as it was when the trigger event landed", async () => {
+    await postWrite("load-chk", "sprocket");
+    await stack.eventDispatcher?.runOnce();
+
+    // The confirm-apply loads the stream on each invocation. At the time
+    // the placed event fires, the stream has exactly 2 events: the CRUD
+    // create + placed itself.
+    expect(confirmLoadCounts).toEqual([2]);
+  });
+
+  test("tenant isolation: ctx.appendEvent writes into the triggering event's tenant", async () => {
+    await postWrite("tenant-iso", "gear");
+    await stack.eventDispatcher?.runOnce();
+
+    // Every event written on this chain belongs to the admin's tenant.
+    const rows = await stack.db.select().from(eventsTable);
+    for (const row of rows) {
+      expect(row.tenantId).toBe(admin.tenantId);
+    }
+  });
+});