@cosmicdrift/kumiko-framework 0.1.0

package/src/pipeline/__tests__/msp-rebuild.integration.ts

@@ -0,0 +1,368 @@
+// MSP-Rebuild — symmetric to projection-rebuild.integration.ts, exercises
+// the MultiStreamProjection rebuild path:
+//
+//   1. Live → drain → read-model X; rebuild → read-model X (idempotent).
+//   2. Corrupt read-model after live drain → rebuild restores the correct
+//      state (load-bearing "read-models are rebuildable" claim).
+//   3. Side-effect MSP (no table) → rebuild rejects with a clear error.
+//   4. Saga-style MSP emitting ctx.appendEvent → rebuild rejects when the
+//      apply reaches appendEvent (replaying events that already live in
+//      the log would be a double-write).
+//   5. cursor is advanced to the last processed event after rebuild so
+//      live dispatcher passes don't redeliver what rebuild consumed.
+//
+// Deliberately separate from projection-rebuild.integration.ts because MSPs
+// carry a different state row (kumiko_event_consumers, not kumiko_projections)
+// and a different apply signature (3rd ctx arg).
+
+import { eq, sql } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { integer as pgInteger, table as pgTable, uuid as pgUuid } from "../../db/dialect";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildDrizzleTable } from "../../db/table-builder";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import {
+  eventConsumerStateTable,
+  getConsumerState,
+  rebuildMultiStreamProjection,
+} from "../../pipeline";
+import {
+  createEntityTable,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "../../stack";
+
+// --- Fixtures: two aggregates feeding one MSP + two cornered MSPs ---
+
+const invoiceEntity = createEntity({
+  table: "read_mspreb_invoices",
+  fields: { customer: createTextField({ required: true }) },
+});
+const invoiceTable = buildDrizzleTable("msp-reb-invoice", invoiceEntity);
+
+const paymentEntity = createEntity({
+  table: "read_mspreb_payments",
+  fields: { customer: createTextField({ required: true }) },
+});
+const paymentTable = buildDrizzleTable("msp-reb-payment", paymentEntity);
+
+// Main read-model: running balance per customer.
+const balanceTable = pgTable("read_mspreb_balance", {
+  customer: pgUuid("customer").primaryKey(),
+  tenantId: pgUuid("tenant_id").notNull(),
+  invoicesCents: pgInteger("invoices_cents").notNull().default(0),
+  paymentsCents: pgInteger("payments_cents").notNull().default(0),
+});
+
+// Saga-MSP read-model — never actually written, exists to satisfy the
+// `table` requirement. The apply below calls ctx.appendEvent; during
+// rebuild that call must throw.
+const sagaStateTable = pgTable("read_mspreb_saga_state", {
+  id: pgUuid("id").primaryKey(),
+});
+
+const feature = defineFeature("mspreb", (r) => {
+  r.entity("msp-reb-invoice", invoiceEntity);
+  r.entity("msp-reb-payment", paymentEntity);
+
+  const invoiceBilled = r.defineEvent(
+    "invoice-billed",
+    z.object({ customer: z.uuid(), cents: z.number().int() }),
+  );
+  const paymentReceived = r.defineEvent(
+    "payment-received",
+    z.object({ customer: z.uuid(), cents: z.number().int() }),
+  );
+  const escalationTriggered = r.defineEvent(
+    "escalation-triggered",
+    z.object({ customer: z.uuid() }),
+  );
+
+  // 1) Main rebuildable MSP — table materialized from two event types.
+  r.multiStreamProjection({
+    name: "customer-balance",
+    table: balanceTable,
+    apply: {
+      [invoiceBilled.name]: async (event, tx) => {
+        const p = event.payload as { customer: string; cents: number };
+        await tx
+          .insert(balanceTable)
+          .values({
+            customer: p.customer,
+            tenantId: event.tenantId,
+            invoicesCents: p.cents,
+            paymentsCents: 0,
+          })
+          .onConflictDoUpdate({
+            target: balanceTable.customer,
+            set: { invoicesCents: sql`${balanceTable.invoicesCents} + ${p.cents}` },
+          });
+      },
+      [paymentReceived.name]: async (event, tx) => {
+        const p = event.payload as { customer: string; cents: number };
+        await tx
+          .insert(balanceTable)
+          .values({
+            customer: p.customer,
+            tenantId: event.tenantId,
+            invoicesCents: 0,
+            paymentsCents: p.cents,
+          })
+          .onConflictDoUpdate({
+            target: balanceTable.customer,
+            set: { paymentsCents: sql`${balanceTable.paymentsCents} + ${p.cents}` },
+          });
+      },
+    },
+  });
+
+  // 2) Side-effect-only MSP: no table. rebuild must reject.
+  r.multiStreamProjection({
+    name: "webhook-sink",
+    apply: {
+      [invoiceBilled.name]: async () => {
+        // would post to an external webhook; the test never exercises live
+        // delivery of this one — only the rebuild rejection path.
+      },
+    },
+  });
+
+  // 3) Saga-style MSP: has a table (so rebuild is allowed to start) but
+  // the apply calls ctx.appendEvent. Rebuild must throw when it reaches
+  // that call.
+  r.multiStreamProjection({
+    name: "saga-emitter",
+    table: sagaStateTable,
+    apply: {
+      [invoiceBilled.name]: async (event, _tx, ctx) => {
+        const p = event.payload as { customer: string };
+        await ctx.appendEventUnsafe({
+          aggregateId: p.customer,
+          aggregateType: "msp-reb-invoice",
+          type: escalationTriggered.name,
+          payload: { customer: p.customer },
+        });
+      },
+    },
+  });
+
+  const invoiceExecutor = createEventStoreExecutor(invoiceTable, invoiceEntity, {
+    entityName: "msp-reb-invoice",
+  });
+  const paymentExecutor = createEventStoreExecutor(paymentTable, paymentEntity, {
+    entityName: "msp-reb-payment",
+  });
+
+  r.writeHandler(
+    "invoice:bill",
+    z.object({ customer: z.uuid(), cents: z.number().int() }),
+    async (event, ctx) => {
+      const res = await invoiceExecutor.create(
+        { customer: event.payload.customer },
+        event.user,
+        ctx.db,
+      );
+      if (!res.isSuccess) return res;
+      await ctx.appendEventUnsafe({
+        aggregateId: String(res.data.id),
+        aggregateType: "msp-reb-invoice",
+        type: invoiceBilled.name,
+        payload: event.payload,
+      });
+      return res;
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "payment:receive",
+    z.object({ customer: z.uuid(), cents: z.number().int() }),
+    async (event, ctx) => {
+      const res = await paymentExecutor.create(
+        { customer: event.payload.customer },
+        event.user,
+        ctx.db,
+      );
+      if (!res.isSuccess) return res;
+      await ctx.appendEventUnsafe({
+        aggregateId: String(res.data.id),
+        aggregateType: "msp-reb-payment",
+        type: paymentReceived.name,
+        payload: event.payload,
+      });
+      return res;
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+const BALANCE_MSP = "mspreb:projection:customer-balance";
+const WEBHOOK_MSP = "mspreb:projection:webhook-sink";
+const SAGA_MSP = "mspreb:projection:saga-emitter";
+
+const admin = TestUsers.admin;
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [feature],
+    systemHooks: [],
+  });
+  await createEntityTable(stack.db, invoiceEntity, "msp-reb-invoice");
+  await createEntityTable(stack.db, paymentEntity, "msp-reb-payment");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  // Disable the saga MSP before truncating so its live pass doesn't land on
+  // a half-torn-down state between tests. The webhook MSP is idempotent for
+  // our purposes — it has no state to leak.
+  await resetEventStore(stack, [
+    "read_mspreb_invoices",
+    "read_mspreb_payments",
+    "read_mspreb_balance",
+    "read_mspreb_saga_state",
+  ]);
+});
+
+// --- Helpers ---
+
+async function runFullDispatcher(): Promise<void> {
+  // Drain the dispatcher twice — first pass delivers new events, second pass
+  // confirms cursor was saved (no redelivery).
+  await stack.eventDispatcher?.runOnce();
+}
+
+// --- Tests ---
+
+describe("rebuildMultiStreamProjection — rebuildable read-model", () => {
+  test("rebuild from live-produced log re-materializes the exact same state", async () => {
+    const alice = "00000000-0000-4000-8000-000000000a01";
+    const bob = "00000000-0000-4000-8000-000000000b02";
+    // Disable the saga MSP for this test — it runs on the same event types
+    // and would trip its own ctx.appendEvent path during live delivery
+    // (which is fine in production, but noise here).
+    await stack.db
+      .update(eventConsumerStateTable)
+      .set({ status: "disabled", updatedAt: sql`now()` })
+      .where(eq(eventConsumerStateTable.name, SAGA_MSP));
+
+    await stack.http.writeOk("mspreb:write:invoice:bill", { customer: alice, cents: 10_00 }, admin);
+    await stack.http.writeOk("mspreb:write:invoice:bill", { customer: alice, cents: 5_00 }, admin);
+    await stack.http.writeOk(
+      "mspreb:write:payment:receive",
+      { customer: alice, cents: 3_00 },
+      admin,
+    );
+    await stack.http.writeOk("mspreb:write:invoice:bill", { customer: bob, cents: 7_50 }, admin);
+    await runFullDispatcher();
+
+    const liveRows = await stack.db.select().from(balanceTable).orderBy(balanceTable.customer);
+    const aliceLive = liveRows.find((r) => r.customer === alice);
+    const bobLive = liveRows.find((r) => r.customer === bob);
+    expect(aliceLive).toMatchObject({ invoicesCents: 15_00, paymentsCents: 3_00 });
+    expect(bobLive).toMatchObject({ invoicesCents: 7_50, paymentsCents: 0 });
+
+    // Rebuild — the table is TRUNCATEd inside the rebuild TX, then events
+    // are replayed in-order. Final state must equal the live state.
+    const result = await rebuildMultiStreamProjection(BALANCE_MSP, {
+      db: stack.db,
+      registry: stack.registry,
+    });
+    expect(result.projection).toBe(BALANCE_MSP);
+    expect(result.eventsProcessed).toBe(4); // 2 invoices + 1 payment + 1 invoice
+    expect(result.lastProcessedEventId).toBeGreaterThan(0n);
+
+    const rebuiltRows = await stack.db.select().from(balanceTable).orderBy(balanceTable.customer);
+    expect(rebuiltRows).toEqual(liveRows);
+
+    // Consumer cursor is at head after rebuild — the live dispatcher should
+    // NOT redeliver those events on its next pass.
+    const state = await getConsumerState(stack.db, BALANCE_MSP);
+    expect(state?.status).toBe("idle");
+    expect(state?.lastProcessedEventId).toBe(result.lastProcessedEventId);
+  });
+
+  test("rebuild after table corruption restores the correct state", async () => {
+    const carol = "00000000-0000-4000-8000-000000000c03";
+    await stack.db
+      .update(eventConsumerStateTable)
+      .set({ status: "disabled", updatedAt: sql`now()` })
+      .where(eq(eventConsumerStateTable.name, SAGA_MSP));
+    await stack.http.writeOk("mspreb:write:invoice:bill", { customer: carol, cents: 42_00 }, admin);
+    await runFullDispatcher();
+
+    // Corrupt the read-model — simulate a buggy apply() landing bad numbers.
+    await stack.db
+      .update(balanceTable)
+      .set({ invoicesCents: -999, paymentsCents: 999 })
+      .where(eq(balanceTable.customer, carol));
+
+    await rebuildMultiStreamProjection(BALANCE_MSP, {
+      db: stack.db,
+      registry: stack.registry,
+    });
+
+    const [row] = await stack.db
+      .select()
+      .from(balanceTable)
+      .where(eq(balanceTable.customer, carol));
+    expect(row).toMatchObject({ invoicesCents: 42_00, paymentsCents: 0 });
+  });
+});
+
+describe("rebuildMultiStreamProjection — guard rails", () => {
+  test("side-effect MSP (no table) is rejected with a clear error", async () => {
+    await expect(
+      rebuildMultiStreamProjection(WEBHOOK_MSP, {
+        db: stack.db,
+        registry: stack.registry,
+      }),
+    ).rejects.toThrow(/no backing table|side-effect/i);
+  });
+
+  test("unknown MSP name lists the known ones in the error", async () => {
+    await expect(
+      rebuildMultiStreamProjection("does:not:exist", {
+        db: stack.db,
+        registry: stack.registry,
+      }),
+    ).rejects.toThrow(/not registered/i);
+  });
+
+  test("saga MSP using ctx.appendEvent fails rebuild at the first appendEvent call", async () => {
+    const dave = "00000000-0000-4000-8000-000000000d04";
+    // Disable the saga in live passes so we control when the apply runs.
+    await stack.db
+      .update(eventConsumerStateTable)
+      .set({ status: "disabled", updatedAt: sql`now()` })
+      .where(eq(eventConsumerStateTable.name, SAGA_MSP));
+    await stack.http.writeOk("mspreb:write:invoice:bill", { customer: dave, cents: 1_00 }, admin);
+    // Put the consumer back to idle so rebuild doesn't treat it as "just
+    // disabled on purpose" — rebuild is opinionated about WHEN it refuses,
+    // not about the consumer's live-status.
+    await stack.db
+      .update(eventConsumerStateTable)
+      .set({ status: "idle", updatedAt: sql`now()` })
+      .where(eq(eventConsumerStateTable.name, SAGA_MSP));
+
+    await expect(
+      rebuildMultiStreamProjection(SAGA_MSP, {
+        db: stack.db,
+        registry: stack.registry,
+      }),
+    ).rejects.toThrow(/appendEvent.*not supported during rebuild/);
+
+    // Failure path: outer catch wrote status="dead" + lastError — ops sees
+    // the break after the TX rolled back.
+    const state = await getConsumerState(stack.db, SAGA_MSP);
+    expect(state?.status).toBe("dead");
+    expect(state?.lastError).toMatch(/appendEvent/);
+  });
+});

package/src/pipeline/__tests__/multi-stream-projection.integration.ts

@@ -0,0 +1,341 @@
+// C3 — r.multiStreamProjection (Marten-aligned, async-only).
+//
+// The cross-aggregate read model. A single MSP reacts to events from many
+// streams, groups by an identity the apply handler extracts from the
+// payload, and materializes into one projection table. Runs async via the
+// event-dispatcher — at-least-once delivery, strictly ordered by events.id
+// per MSP consumer, dead-letters on repeated handler failures.
+
+import { eq, sql } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { integer as pgInteger, table as pgTable, uuid as pgUuid } from "../../db/dialect";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildDrizzleTable } from "../../db/table-builder";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import {
+  createEntityTable,
+  createTestUser,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "../../stack";
+
+// --- Two aggregate types that feed one MSP ---
+
+const shipmentEntity = createEntity({
+  table: "read_msp_shipments",
+  fields: { customer: createTextField({ required: true }) },
+});
+const shipmentTable = buildDrizzleTable("msp-shipment", shipmentEntity);
+
+const refundEntity = createEntity({
+  table: "read_msp_refunds",
+  fields: { customer: createTextField({ required: true }) },
+});
+const refundTable = buildDrizzleTable("msp-refund", refundEntity);
+
+// Cross-cutting MSP: one row per customer, sums shipments − refunds. Key
+// differences from a single-stream projection:
+//   - feeds off TWO aggregate types (shipment + refund), no shared entity
+//   - identity key (customer UUID) lives in the event payload, not
+//     aggregate_id — extracted inside the apply handler
+const customerBalanceTable = pgTable("read_msp_customer_balance", {
+  customer: pgUuid("customer").primaryKey(),
+  tenantId: pgUuid("tenant_id").notNull(),
+  shipments: pgInteger("shipments").notNull().default(0),
+  refunds: pgInteger("refunds").notNull().default(0),
+  netCents: pgInteger("net_cents").notNull().default(0),
+});
+
+const mspFeature = defineFeature("msptest", (r) => {
+  r.entity("msp-shipment", shipmentEntity);
+  r.entity("msp-refund", refundEntity);
+
+  const shipmentBilled = r.defineEvent(
+    "shipment-billed",
+    z.object({ customer: z.uuid(), cents: z.number().int() }),
+  );
+  const refundIssued = r.defineEvent(
+    "refund-issued",
+    z.object({ customer: z.uuid(), cents: z.number().int() }),
+  );
+
+  r.multiStreamProjection({
+    name: "customer-balance",
+    table: customerBalanceTable,
+    apply: {
+      [shipmentBilled.name]: async (event, tx) => {
+        const p = event.payload as { customer: string; cents: number };
+        await tx
+          .insert(customerBalanceTable)
+          .values({
+            customer: p.customer,
+            tenantId: event.tenantId,
+            shipments: 1,
+            refunds: 0,
+            netCents: p.cents,
+          })
+          .onConflictDoUpdate({
+            target: customerBalanceTable.customer,
+            set: {
+              shipments: sql`${customerBalanceTable.shipments} + 1`,
+              netCents: sql`${customerBalanceTable.netCents} + ${p.cents}`,
+            },
+          });
+      },
+      [refundIssued.name]: async (event, tx) => {
+        const p = event.payload as { customer: string; cents: number };
+        await tx
+          .insert(customerBalanceTable)
+          .values({
+            customer: p.customer,
+            tenantId: event.tenantId,
+            shipments: 0,
+            refunds: 1,
+            netCents: -p.cents,
+          })
+          .onConflictDoUpdate({
+            target: customerBalanceTable.customer,
+            set: {
+              refunds: sql`${customerBalanceTable.refunds} + 1`,
+              netCents: sql`${customerBalanceTable.netCents} - ${p.cents}`,
+            },
+          });
+      },
+    },
+  });
+
+  const shipmentExecutor = createEventStoreExecutor(shipmentTable, shipmentEntity, {
+    entityName: "msp-shipment",
+  });
+  const refundExecutor = createEventStoreExecutor(refundTable, refundEntity, {
+    entityName: "msp-refund",
+  });
+
+  r.writeHandler(
+    "shipment:bill",
+    z.object({ customer: z.uuid(), cents: z.number().int() }),
+    async (event, ctx) => {
+      const res = await shipmentExecutor.create(
+        { customer: event.payload.customer },
+        event.user,
+        ctx.db,
+      );
+      if (!res.isSuccess) return res;
+      await ctx.appendEventUnsafe({
+        aggregateId: String(res.data.id),
+        aggregateType: "msp-shipment",
+        type: shipmentBilled.name,
+        payload: { customer: event.payload.customer, cents: event.payload.cents },
+      });
+      return res;
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "refund:issue",
+    z.object({ customer: z.uuid(), cents: z.number().int() }),
+    async (event, ctx) => {
+      const res = await refundExecutor.create(
+        { customer: event.payload.customer },
+        event.user,
+        ctx.db,
+      );
+      if (!res.isSuccess) return res;
+      await ctx.appendEventUnsafe({
+        aggregateId: String(res.data.id),
+        aggregateType: "msp-refund",
+        type: refundIssued.name,
+        payload: { customer: event.payload.customer, cents: event.payload.cents },
+      });
+      return res;
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [mspFeature], systemHooks: [] });
+  await createEntityTable(stack.db, shipmentEntity, "msp-shipment");
+  await createEntityTable(stack.db, refundEntity, "msp-refund");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  await resetEventStore(stack, [
+    "read_msp_shipments",
+    "read_msp_refunds",
+    "read_msp_customer_balance",
+  ]);
+});
+
+describe("r.multiStreamProjection — Marten MultiStreamProjection equivalent", () => {
+  test("events from two aggregate types roll up into one customer row", async () => {
+    const customerA = "00000000-0000-4000-8000-000000000a11";
+    const customerB = "00000000-0000-4000-8000-000000000b22";
+
+    await stack.http.writeOk(
+      "msptest:write:shipment:bill",
+      { customer: customerA, cents: 1000 },
+      admin,
+    );
+    await stack.http.writeOk(
+      "msptest:write:shipment:bill",
+      { customer: customerA, cents: 500 },
+      admin,
+    );
+    await stack.http.writeOk(
+      "msptest:write:refund:issue",
+      { customer: customerA, cents: 200 },
+      admin,
+    );
+    await stack.http.writeOk(
+      "msptest:write:shipment:bill",
+      { customer: customerB, cents: 300 },
+      admin,
+    );
+
+    // Drain the dispatcher — MSPs run async.
+    await stack.eventDispatcher?.runOnce();
+
+    const rows = await stack.db
+      .select()
+      .from(customerBalanceTable)
+      .orderBy(customerBalanceTable.customer);
+    const byCustomer = new Map(rows.map((r) => [r.customer, r]));
+
+    expect(byCustomer.get(customerA)).toMatchObject({
+      shipments: 2,
+      refunds: 1,
+      netCents: 1300, // 1000 + 500 - 200
+    });
+    expect(byCustomer.get(customerB)).toMatchObject({
+      shipments: 1,
+      refunds: 0,
+      netCents: 300,
+    });
+  });
+
+  test("MSP consumer owns a cursor — second runOnce is a no-op when caught up", async () => {
+    const cust = "00000000-0000-4000-8000-000000000c33";
+    await stack.http.writeOk("msptest:write:shipment:bill", { customer: cust, cents: 42 }, admin);
+
+    const pass1 = await stack.eventDispatcher?.runOnce();
+    const pass2 = await stack.eventDispatcher?.runOnce();
+
+    // The MSP consumer processed the single event once; the cursor then
+    // holds it, so pass2 sees zero events for that consumer.
+    const mspName = "msptest:projection:customer-balance";
+    expect(pass1?.byConsumer[mspName]?.processed).toBeGreaterThanOrEqual(1);
+    expect(pass2?.byConsumer[mspName]?.processed ?? 0).toBe(0);
+
+    // Row state is stable across the no-op pass.
+    const [row] = await stack.db
+      .select()
+      .from(customerBalanceTable)
+      .where(eq(customerBalanceTable.customer, cust));
+    expect(row?.shipments).toBe(1);
+    expect(row?.netCents).toBe(42);
+  });
+
+  test("MSP apply receives event.tenantId correctly across tenants (isolation pin)", async () => {
+    // Regression pin: MSP apply does NOT get a tenant-scoped TenantDb (the
+    // old r.postEvent wrap). Instead the apply handler reads event.tenantId
+    // and writes it into the projection row. Verify that two tenants feeding
+    // the same MSP land in distinct rows carrying their own tenantId — not
+    // cross-tenant leaks, not hardcoded wrong tenant.
+    const otherAdmin = createTestUser({
+      id: 77,
+      roles: ["Admin"],
+      tenantId: "00000000-0000-4000-8000-000000000099",
+    });
+    const customerAlpha = "00000000-0000-4000-8000-000000000aa1";
+    const customerBeta = "00000000-0000-4000-8000-000000000bb2";
+
+    await stack.http.writeOk(
+      "msptest:write:shipment:bill",
+      { customer: customerAlpha, cents: 1000 },
+      admin,
+    );
+    await stack.http.writeOk(
+      "msptest:write:shipment:bill",
+      { customer: customerBeta, cents: 2000 },
+      otherAdmin,
+    );
+    await stack.eventDispatcher?.runOnce();
+
+    const rows = await stack.db
+      .select()
+      .from(customerBalanceTable)
+      .orderBy(customerBalanceTable.customer);
+    const alpha = rows.find((r) => r.customer === customerAlpha);
+    const beta = rows.find((r) => r.customer === customerBeta);
+
+    expect(alpha).toBeDefined();
+    expect(beta).toBeDefined();
+    expect(alpha?.tenantId).toBe(admin.tenantId);
+    expect(beta?.tenantId).toBe(otherAdmin.tenantId);
+    expect(alpha?.netCents).toBe(1000);
+    expect(beta?.netCents).toBe(2000);
+  });
+
+  test("events the MSP does not subscribe to pass through untouched", async () => {
+    // A pure CRUD create (mspShipment.created) is not in the MSP's apply
+    // map — the handler should ignore it without throwing, even though the
+    // dispatcher still routes it past the consumer.
+    const cust = "00000000-0000-4000-8000-000000000d44";
+    await stack.http.writeOk("msptest:write:shipment:bill", { customer: cust, cents: 77 }, admin);
+    await stack.eventDispatcher?.runOnce();
+
+    // Only the shipment-billed event was folded in; the auto "created"
+    // event was silently skipped.
+    const [row] = await stack.db
+      .select()
+      .from(customerBalanceTable)
+      .where(eq(customerBalanceTable.customer, cust));
+    expect(row?.shipments).toBe(1);
+  });
+});
+
+describe("r.multiStreamProjection — registrar validation", () => {
+  test("empty apply map is rejected", () => {
+    expect(() =>
+      defineFeature("mspbad", (r) => {
+        r.entity("msp-shipment", shipmentEntity);
+        r.multiStreamProjection({
+          name: "empty",
+          table: customerBalanceTable,
+          apply: {},
+        });
+      }),
+    ).toThrow(/no apply handlers/);
+  });
+
+  test("name collision with single-stream projection is rejected", () => {
+    expect(() =>
+      defineFeature("mspcollision", (r) => {
+        r.entity("msp-shipment", shipmentEntity);
+        r.projection({
+          name: "shared",
+          source: "msp-shipment",
+          table: customerBalanceTable,
+          apply: { "msp-shipment.created": async () => {} },
+        });
+        r.multiStreamProjection({
+          name: "shared",
+          table: customerBalanceTable,
+          apply: { "msptest:event:shipment-billed": async () => {} },
+        });
+      }),
+    ).toThrow(/already registered/);
+  });
+});