@cosmicdrift/kumiko-framework 0.1.0

package/src/pipeline/__tests__/cascade-handler.integration.ts

@@ -0,0 +1,419 @@
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import type { TableColumns } from "../../db/dialect";
+import { createEventStoreExecutor, type EventStoreExecutor } from "../../db/event-store-executor";
+import { buildDrizzleTable } from "../../db/table-builder";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import {
+  createEntity,
+  createRegistry,
+  createTextField,
+  defineFeature,
+  type Registry,
+} from "../../engine";
+import { createEventsTable } from "../../event-store";
+import { createEntityTable, createTestDb, type TestDb, TestUsers } from "../../stack";
+import { createCascadeDeleteHook } from "../cascade-handler";
+
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic tables
+type Table = TableColumns<any>;
+
+let testDb: TestDb;
+let tdb: TenantDb;
+let registry: Registry;
+let departmentTable: Table;
+let userTable: Table;
+let sessionTable: Table;
+let groupTable: Table;
+let userGroupRestrictTable: Table;
+let userGroupCascadeTable: Table;
+let teamTable: Table;
+let memberTable: Table;
+let departmentExecutor: EventStoreExecutor;
+let userExecutor: EventStoreExecutor;
+let sessionExecutor: EventStoreExecutor;
+let groupExecutor: EventStoreExecutor;
+let userGroupRestrictExecutor: EventStoreExecutor;
+let userGroupCascadeExecutor: EventStoreExecutor;
+let teamExecutor: EventStoreExecutor;
+let memberExecutor: EventStoreExecutor;
+
+const admin = TestUsers.admin;
+
+const departmentEntity = createEntity({
+  table: "cascade_departments",
+  fields: { name: createTextField() },
+});
+const userEntity = createEntity({
+  table: "cascade_users",
+  fields: { name: createTextField(), departmentId: createTextField() },
+});
+const sessionEntity = createEntity({
+  table: "cascade_sessions",
+  fields: { userId: createTextField(), token: createTextField() },
+});
+const groupEntity = createEntity({
+  table: "cascade_groups",
+  fields: { name: createTextField() },
+});
+// Two separate junction tables so one Registry can host both onDelete
+// strategies (restrict + cascade) on the same user→group pair.
+const userGroupRestrictEntity = createEntity({
+  table: "cascade_user_group_restrict",
+  fields: { userId: createTextField(), groupId: createTextField() },
+});
+const userGroupCascadeEntity = createEntity({
+  table: "cascade_user_group_cascade",
+  fields: { userId: createTextField(), groupId: createTextField() },
+});
+// setNull pair: team→member with onDelete "setNull" — members survive
+// the team deletion with teamId nulled out.
+const teamEntity = createEntity({
+  table: "cascade_teams",
+  fields: { name: createTextField() },
+});
+const memberEntity = createEntity({
+  table: "cascade_members",
+  fields: { name: createTextField(), teamId: createTextField() },
+});
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEventsTable(testDb.db);
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+
+  await createEntityTable(testDb.db, departmentEntity);
+  await createEntityTable(testDb.db, userEntity);
+  await createEntityTable(testDb.db, sessionEntity);
+  await createEntityTable(testDb.db, groupEntity);
+  await createEntityTable(testDb.db, userGroupRestrictEntity);
+  await createEntityTable(testDb.db, userGroupCascadeEntity);
+  await createEntityTable(testDb.db, teamEntity);
+  await createEntityTable(testDb.db, memberEntity);
+
+  departmentTable = buildDrizzleTable("department", departmentEntity);
+  userTable = buildDrizzleTable("user", userEntity);
+  sessionTable = buildDrizzleTable("session", sessionEntity);
+  groupTable = buildDrizzleTable("group", groupEntity);
+  userGroupRestrictTable = buildDrizzleTable("user-group-restrict", userGroupRestrictEntity);
+  userGroupCascadeTable = buildDrizzleTable("user-group-cascade", userGroupCascadeEntity);
+  teamTable = buildDrizzleTable("team", teamEntity);
+  memberTable = buildDrizzleTable("member", memberEntity);
+
+  const feature = defineFeature("cascade", (r) => {
+    r.entity("department", departmentEntity);
+    r.entity("user", userEntity);
+    r.entity("session", sessionEntity);
+    r.entity("group", groupEntity);
+    r.entity("user-group-restrict", userGroupRestrictEntity);
+    r.entity("user-group-cascade", userGroupCascadeEntity);
+    r.entity("team", teamEntity);
+    r.entity("member", memberEntity);
+
+    r.relation("department", "users", {
+      type: "hasMany",
+      target: "user",
+      foreignKey: "departmentId",
+      onDelete: "restrict",
+    });
+
+    r.relation("user", "sessions", {
+      type: "hasMany",
+      target: "session",
+      foreignKey: "userId",
+      onDelete: "cascade",
+    });
+
+    r.relation("user", "groupsRestrict", {
+      type: "manyToMany",
+      target: "group",
+      through: { table: "user-group-restrict", sourceKey: "userId", targetKey: "groupId" },
+      onDelete: "restrict",
+    });
+
+    r.relation("user", "groupsCascade", {
+      type: "manyToMany",
+      target: "group",
+      through: { table: "user-group-cascade", sourceKey: "userId", targetKey: "groupId" },
+      onDelete: "cascade",
+    });
+
+    r.relation("team", "members", {
+      type: "hasMany",
+      target: "member",
+      foreignKey: "teamId",
+      onDelete: "setNull",
+    });
+  });
+
+  registry = createRegistry([feature]);
+  departmentExecutor = createEventStoreExecutor(departmentTable, departmentEntity, {
+    entityName: "department",
+  });
+  userExecutor = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+  sessionExecutor = createEventStoreExecutor(sessionTable, sessionEntity, {
+    entityName: "session",
+  });
+  groupExecutor = createEventStoreExecutor(groupTable, groupEntity, { entityName: "group" });
+  userGroupRestrictExecutor = createEventStoreExecutor(
+    userGroupRestrictTable,
+    userGroupRestrictEntity,
+    { entityName: "user-group-restrict" },
+  );
+  userGroupCascadeExecutor = createEventStoreExecutor(
+    userGroupCascadeTable,
+    userGroupCascadeEntity,
+    { entityName: "user-group-cascade" },
+  );
+  teamExecutor = createEventStoreExecutor(teamTable, teamEntity, { entityName: "team" });
+  memberExecutor = createEventStoreExecutor(memberTable, memberEntity, { entityName: "member" });
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+describe("cascade delete: restrict", () => {
+  test("blocks delete when related records exist", async () => {
+    const dept = await departmentExecutor.create({ name: "Engineering" }, admin, tdb);
+    if (!dept.isSuccess) throw new Error("Setup failed");
+
+    await userExecutor.create({ name: "Marc", departmentId: dept.data.id }, admin, tdb);
+
+    const cascadeHook = createCascadeDeleteHook(registry, new Map([["user", userTable]]));
+
+    await expect(
+      cascadeHook.fn(
+        {
+          kind: "delete",
+          id: dept.data.id,
+          data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+          entityName: "department",
+        },
+        { db: tdb },
+      ),
+    ).rejects.toMatchObject({ code: "conflict", details: { reason: "delete_restricted" } });
+  });
+
+  test("allows delete when no related records", async () => {
+    const dept = await departmentExecutor.create({ name: "Empty" }, admin, tdb);
+    if (!dept.isSuccess) throw new Error("Setup failed");
+
+    const cascadeHook = createCascadeDeleteHook(registry, new Map([["user", userTable]]));
+
+    await expect(
+      cascadeHook.fn(
+        {
+          kind: "delete",
+          id: dept.data.id,
+          data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+          entityName: "department",
+        },
+        { db: tdb },
+      ),
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe("cascade delete: cascade", () => {
+  test("deletes related records when parent is deleted", async () => {
+    const user = await userExecutor.create({ name: "Cascade User" }, admin, tdb);
+    if (!user.isSuccess) throw new Error("Setup failed");
+
+    await sessionExecutor.create({ userId: user.data.id, token: "abc" }, admin, tdb);
+    await sessionExecutor.create({ userId: user.data.id, token: "def" }, admin, tdb);
+
+    // Verify sessions exist
+    const before = await sessionExecutor.list({}, admin, tdb);
+    const sessionsBefore = before.rows.filter((r) => r["userId"] === user.data.id);
+    expect(sessionsBefore.length).toBe(2);
+
+    // Run cascade
+    const cascadeHook = createCascadeDeleteHook(registry, new Map([["session", sessionTable]]));
+
+    await cascadeHook.fn(
+      {
+        kind: "delete",
+        id: user.data.id,
+        data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+        entityName: "user",
+      },
+      { db: tdb },
+    );
+
+    // Sessions should be gone
+    const after = await sessionExecutor.list({}, admin, tdb);
+    const sessionsAfter = after.rows.filter((r) => r["userId"] === user.data.id);
+    expect(sessionsAfter.length).toBe(0);
+  });
+});
+
+describe("cascade delete: manyToMany restrict", () => {
+  test("blocks delete when through-records exist", async () => {
+    const user = await userExecutor.create({ name: "M2M Restrict User" }, admin, tdb);
+    const group = await groupExecutor.create({ name: "Admins" }, admin, tdb);
+    if (!user.isSuccess || !group.isSuccess) throw new Error("Setup failed");
+
+    await userGroupRestrictExecutor.create(
+      { userId: user.data.id, groupId: group.data.id },
+      admin,
+      tdb,
+    );
+
+    const cascadeHook = createCascadeDeleteHook(
+      registry,
+      new Map([["user-group-restrict", userGroupRestrictTable]]),
+    );
+
+    await expect(
+      cascadeHook.fn(
+        {
+          kind: "delete",
+          id: user.data.id,
+          data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+          entityName: "user",
+        },
+        { db: tdb },
+      ),
+    ).rejects.toMatchObject({
+      code: "conflict",
+      details: {
+        reason: "delete_restricted",
+        blockingEntity: "user-group-restrict",
+      },
+    });
+  });
+
+  test("allows delete when no through-records reference this entity", async () => {
+    const user = await userExecutor.create({ name: "M2M Free User" }, admin, tdb);
+    if (!user.isSuccess) throw new Error("Setup failed");
+
+    const cascadeHook = createCascadeDeleteHook(
+      registry,
+      new Map([["user-group-restrict", userGroupRestrictTable]]),
+    );
+
+    await expect(
+      cascadeHook.fn(
+        {
+          kind: "delete",
+          id: user.data.id,
+          data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+          entityName: "user",
+        },
+        { db: tdb },
+      ),
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe("cascade delete: manyToMany cascade", () => {
+  test("deletes through-records but keeps target entities", async () => {
+    const user = await userExecutor.create({ name: "M2M Cascade User" }, admin, tdb);
+    const groupA = await groupExecutor.create({ name: "Group A" }, admin, tdb);
+    const groupB = await groupExecutor.create({ name: "Group B" }, admin, tdb);
+    if (!user.isSuccess || !groupA.isSuccess || !groupB.isSuccess) throw new Error("Setup failed");
+
+    await userGroupCascadeExecutor.create(
+      { userId: user.data.id, groupId: groupA.data.id },
+      admin,
+      tdb,
+    );
+    await userGroupCascadeExecutor.create(
+      { userId: user.data.id, groupId: groupB.data.id },
+      admin,
+      tdb,
+    );
+
+    const before = await userGroupCascadeExecutor.list({}, admin, tdb);
+    expect(before.rows.filter((r) => r["userId"] === user.data.id).length).toBe(2);
+
+    const cascadeHook = createCascadeDeleteHook(
+      registry,
+      new Map([["user-group-cascade", userGroupCascadeTable]]),
+    );
+
+    await cascadeHook.fn(
+      {
+        kind: "delete",
+        id: user.data.id,
+        data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+        entityName: "user",
+      },
+      { db: tdb },
+    );
+
+    // Through-records for this user must be gone
+    const after = await userGroupCascadeExecutor.list({}, admin, tdb);
+    expect(after.rows.filter((r) => r["userId"] === user.data.id).length).toBe(0);
+
+    // Target groups themselves must remain — cascade drops the M:N link,
+    // not the referenced entities.
+    const groups = await groupExecutor.list({}, admin, tdb);
+    const groupIds = groups.rows.map((r) => r["id"]);
+    expect(groupIds).toContain(groupA.data.id);
+    expect(groupIds).toContain(groupB.data.id);
+  });
+});
+
+describe("cascade delete: hasMany setNull", () => {
+  test("nulls out FK on related records when parent is deleted", async () => {
+    const team = await teamExecutor.create({ name: "SetNull Team" }, admin, tdb);
+    if (!team.isSuccess) throw new Error("Setup failed");
+
+    const m1 = await memberExecutor.create({ name: "Alice", teamId: team.data.id }, admin, tdb);
+    const m2 = await memberExecutor.create({ name: "Bob", teamId: team.data.id }, admin, tdb);
+    if (!m1.isSuccess || !m2.isSuccess) throw new Error("Setup failed");
+
+    // Verify FK is set before cascade
+    const before = await memberExecutor.list({}, admin, tdb);
+    const teamMembers = before.rows.filter((r) => r["id"] === m1.data.id || r["id"] === m2.data.id);
+    expect(teamMembers.every((r) => r["teamId"] === team.data.id)).toBe(true);
+
+    const cascadeHook = createCascadeDeleteHook(registry, new Map([["member", memberTable]]));
+
+    await cascadeHook.fn(
+      {
+        kind: "delete",
+        id: team.data.id,
+        data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+        entityName: "team",
+      },
+      { db: tdb },
+    );
+
+    // Members still exist, but teamId is now null
+    const after = await memberExecutor.list({}, admin, tdb);
+    const afterMembers = after.rows.filter((r) => r["id"] === m1.data.id || r["id"] === m2.data.id);
+    expect(afterMembers.length).toBe(2);
+    expect(afterMembers.every((r) => r["teamId"] === null)).toBe(true);
+  });
+
+  test("leaves unrelated records untouched", async () => {
+    const teamA = await teamExecutor.create({ name: "Team A" }, admin, tdb);
+    const teamB = await teamExecutor.create({ name: "Team B" }, admin, tdb);
+    if (!teamA.isSuccess || !teamB.isSuccess) throw new Error("Setup failed");
+
+    const mA = await memberExecutor.create({ name: "A-member", teamId: teamA.data.id }, admin, tdb);
+    const mB = await memberExecutor.create({ name: "B-member", teamId: teamB.data.id }, admin, tdb);
+    if (!mA.isSuccess || !mB.isSuccess) throw new Error("Setup failed");
+
+    const cascadeHook = createCascadeDeleteHook(registry, new Map([["member", memberTable]]));
+
+    // Delete team A — only mA should lose its teamId, mB must stay intact
+    await cascadeHook.fn(
+      {
+        kind: "delete",
+        id: teamA.data.id,
+        data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+        entityName: "team",
+      },
+      { db: tdb },
+    );
+
+    const after = await memberExecutor.list({}, admin, tdb);
+    const aAfter = after.rows.find((r) => r["id"] === mA.data.id);
+    const bAfter = after.rows.find((r) => r["id"] === mB.data.id);
+    expect(aAfter?.["teamId"]).toBeNull();
+    expect(bAfter?.["teamId"]).toBe(teamB.data.id);
+  });
+});

package/src/pipeline/__tests__/cascade-handler.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "vitest";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+
+describe("getIncomingRelations", () => {
+  const feature = defineFeature("core", (r) => {
+    r.entity(
+      "department",
+      createEntity({ table: "Departments", fields: { name: createTextField() } }),
+    );
+    r.entity("user", createEntity({ table: "Users", fields: { departmentId: createTextField() } }));
+    r.entity("session", createEntity({ table: "Sessions", fields: { userId: createTextField() } }));
+
+    r.relation("department", "users", {
+      type: "hasMany",
+      target: "user",
+      foreignKey: "departmentId",
+      onDelete: "restrict",
+    });
+    r.relation("user", "sessions", {
+      type: "hasMany",
+      target: "session",
+      foreignKey: "userId",
+      onDelete: "cascade",
+    });
+  });
+
+  const registry = createRegistry([feature]);
+
+  test("finds hasMany relation pointing to user from department", () => {
+    const incoming = registry.getIncomingRelations("user");
+    const match = incoming.find(
+      (r) => r.sourceEntity === "department" && r.relation.type === "hasMany",
+    );
+    expect(match?.relation.type === "hasMany" && match.relation.onDelete).toBe("restrict");
+  });
+
+  test("finds hasMany relation pointing to session from user", () => {
+    const incoming = registry.getIncomingRelations("session");
+    expect(incoming).toHaveLength(1);
+    const rel = incoming[0]?.relation;
+    expect(rel?.type === "hasMany" && rel.onDelete).toBe("cascade");
+  });
+
+  test("no incoming relations for department", () => {
+    expect(registry.getIncomingRelations("department")).toEqual([]);
+  });
+
+  test("onDelete strategy preserved", () => {
+    const rel = registry.getRelations("department")["users"];
+    expect(rel?.type === "hasMany" && rel.onDelete).toBe("restrict");
+  });
+});

package/src/pipeline/__tests__/causation-chain.integration.ts

@@ -0,0 +1,206 @@
+// Runde 2 — correlationId + causationId propagation.
+//
+// Claims pinned here:
+//   1. Root HTTP request without x-correlation-id → correlationId == requestId,
+//      causationId absent.
+//   2. Root with x-correlation-id header → correlationId == header value,
+//      stamped on every event the request writes (CRUD + ctx.appendEvent).
+//   3. The event-dispatcher wraps MSP-apply in requestContext.run so downstream
+//      writes from the apply inherit correlationId and set causationId to the
+//      triggering event.id.
+//
+// Note on MSP → new events: this test predates Runde 3 / C.2b. Claim 3 is
+// observable via `requestContext.get()` inside the apply — the wrap carries
+// the right values even when the apply doesn't call ctx.appendEvent.
+// The active propagation into cascaded writes is covered by
+// msp-multi-hop.integration.ts.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { requestContext } from "../../api/request-context";
+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_causation_orders",
+  fields: {
+    item: createTextField({ required: true }),
+  },
+});
+
+const orderTable = buildDrizzleTable("causation-order", orderEntity);
+
+// MSP-apply observation sink — every apply run pushes its reqCtx snapshot
+// here so the tests can assert what the event-dispatcher wrapped it with.
+type ReqCtxSnapshot = {
+  readonly forEventId: string;
+  readonly correlationId: string | undefined;
+  readonly causationId: string | undefined;
+};
+const applyObservations: ReqCtxSnapshot[] = [];
+
+const causationFeature = defineFeature("causation", (r) => {
+  r.entity("causation-order", orderEntity);
+
+  const placed = r.defineEvent("placed", z.object({ orderId: z.uuid() }));
+
+  const orderExecutor = createEventStoreExecutor(orderTable, orderEntity, {
+    entityName: "causation-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: "causation-order",
+        type: placed.name,
+        payload: { orderId: String(created.data.id) },
+      });
+      return created;
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Observation-only MSP — records what the dispatcher's requestContext.run
+  // wrap set for each event. Proves that the wrap is live and carries the
+  // triggering event's id as causationId.
+  r.multiStreamProjection({
+    name: "observer",
+    apply: {
+      [placed.name]: async (event) => {
+        const ctx = requestContext.get();
+        applyObservations.push({
+          forEventId: String(event.id),
+          correlationId: ctx?.correlationId,
+          causationId: ctx?.causationId,
+        });
+      },
+    },
+  });
+});
+
+// --- Stack ---
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [causationFeature],
+    systemHooks: [],
+  });
+  await createEntityTable(stack.db, orderEntity, "causation-order");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  applyObservations.length = 0;
+  await resetEventStore(stack, ["read_causation_orders"]);
+});
+
+// --- Helpers ---
+
+type EventRow = typeof eventsTable.$inferSelect;
+
+async function eventsByType(type: string): Promise<EventRow[]> {
+  const rows = await stack.db.select().from(eventsTable);
+  return rows.filter((r) => r.type === type);
+}
+
+// --- Tests ---
+
+describe("Runde 2 — correlationId on root HTTP request", () => {
+  test("no x-correlation-id: correlationId mirrors requestId, causationId absent", async () => {
+    await stack.http.writeOk("causation:write:order:place", { item: "widget" }, admin);
+
+    const [placedEvent] = await eventsByType("causation:event:placed");
+    expect(placedEvent).toBeDefined();
+    const meta = placedEvent?.metadata as {
+      requestId?: string;
+      correlationId?: string;
+      causationId?: string;
+    };
+    // Default: correlationId == requestId so single-call tracing works
+    // without any client co-operation.
+    expect(meta.correlationId).toBeDefined();
+    expect(meta.requestId).toBe(meta.correlationId);
+    expect(meta.causationId).toBeUndefined();
+  });
+
+  test("with x-correlation-id header: every event this request writes carries the header value", async () => {
+    const res = await stack.http.writeWithHeaders(
+      "causation:write:order:place",
+      { item: "sprocket" },
+      admin,
+      { "X-Correlation-ID": "test-chain-abc123" },
+    );
+    expect(res.status).toBe(200);
+
+    // The handler writes TWO events: one CRUD (causationOrder.created) and
+    // one domain (causation:event:placed). Both share the correlationId.
+    const crudEvent = (await eventsByType("causation-order.created"))[0];
+    const placedEvent = (await eventsByType("causation:event:placed"))[0];
+
+    expect((crudEvent?.metadata as { correlationId?: string })?.correlationId).toBe(
+      "test-chain-abc123",
+    );
+    expect((placedEvent?.metadata as { correlationId?: string })?.correlationId).toBe(
+      "test-chain-abc123",
+    );
+  });
+
+  test("response echoes x-correlation-id back in the same header", async () => {
+    const res = await stack.http.writeWithHeaders(
+      "causation:write:order:place",
+      { item: "rotor" },
+      admin,
+      { "X-Correlation-ID": "echo-me-xyz" },
+    );
+    expect(res.headers.get("x-correlation-id")).toBe("echo-me-xyz");
+  });
+});
+
+describe("Runde 2 — event-dispatcher propagates correlation + causation to MSP-apply", () => {
+  test("MSP-apply sees the triggering event.id as causationId and inherits correlationId", async () => {
+    // Root write with a known correlation token.
+    await stack.http.writeWithHeaders("causation:write:order:place", { item: "gasket" }, admin, {
+      "X-Correlation-ID": "msp-chain-token",
+    });
+
+    // Drain the dispatcher — MSP-apply fires, pushes its reqCtx snapshot.
+    await stack.eventDispatcher?.runOnce();
+
+    // Find the placed event by row id (BigInt). Its id is what the MSP
+    // should have seen as causationId.
+    const [placedEvent] = await eventsByType("causation:event:placed");
+    expect(placedEvent).toBeDefined();
+    const placedId = String(placedEvent?.id);
+
+    // Observation recorded inside the MSP apply.
+    expect(applyObservations).toHaveLength(1);
+    const obs = applyObservations[0];
+    expect(obs?.forEventId).toBe(placedId);
+    // Correlation inherited from the triggering event.
+    expect(obs?.correlationId).toBe("msp-chain-token");
+    // Causation = the id of the event that triggered this apply.
+    expect(obs?.causationId).toBe(placedId);
+  });
+});