@cosmicdrift/kumiko-framework 0.282.0 → 0.283.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.282.0",
+  "version": "0.283.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.282.0",
+    "@cosmicdrift/kumiko-types": "0.283.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.282.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.283.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.283.0",
+    "type": "improvement",
+    "title": "loadAggregate and ctx.fetchForWriting gain an optional aggregateType filter, plus handle.hasEvent(...)",
+    "detail": "`loadAggregate(db, aggregateId, tenantId, options)` accepts an optional `options.aggregateType`. Without it, behavior is unchanged — every event on the aggregateId's stream is returned, same as today. With it, only events matching that `aggregateType` are returned, so two features that happen to share an `aggregateId` (e.g. reusing an upstream id as the key for a second, unrelated aggregate type) no longer leak each other's events into a business-rule check that only expected its own type.\n`ctx.fetchForWriting({ aggregateId, aggregateType, ... })` now passes `aggregateType` through to `loadAggregate`, so `handle.events` is scoped the same way. The returned `AggregateStreamHandle` also gains `hasEvent(type: string): boolean`, an idempotency check against the fetch-time `events` snapshot — cheaper and safer than an `appendIfAbsent`-style helper, which risks masking a genuine optimistic-concurrency conflict as an already-applied write.",
+    "migration": "No action required — purely additive. Every existing loadAggregate/fetchForWriting\ncall keeps its current behavior; opt into the aggregateType filter only where an\naggregateId is shared across more than one aggregate type."
+  },
   {
     "version": "0.281.0",
     "type": "breaking",

package/src/event-store/__tests__/event-store.integration.test.ts

@@ -361,6 +361,97 @@ describe("event-store: tenant isolation", () => {
   });
 });
 
+describe("event-store: loadAggregate aggregateType filter (#2979)", () => {
+  test("without aggregateType, both types on one aggregateId are returned (no breaking change)", async () => {
+    const aggregateId = uuid();
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "cart",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "cart.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "reservation",
+      tenantId: tenantA,
+      expectedVersion: 1,
+      type: "reservation.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+
+    const events = await loadAggregate(testDb.db, aggregateId, tenantA);
+    expect(events.map((e) => e.type)).toEqual(["cart.created", "reservation.created"]);
+  });
+
+  test("with aggregateType, a foreign-type event on the same aggregateId is excluded (solon-style id collision)", async () => {
+    const aggregateId = uuid();
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "cart",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "cart.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "reservation",
+      tenantId: tenantA,
+      expectedVersion: 1,
+      type: "reservation.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "cart",
+      tenantId: tenantA,
+      expectedVersion: 2,
+      type: "cart.itemAdded",
+      payload: {},
+      metadata: { userId: userA },
+    });
+
+    const cartEvents = await loadAggregate(testDb.db, aggregateId, tenantA, {
+      aggregateType: "cart",
+    });
+    expect(cartEvents.map((e) => e.type)).toEqual(["cart.created", "cart.itemAdded"]);
+
+    const reservationEvents = await loadAggregate(testDb.db, aggregateId, tenantA, {
+      aggregateType: "reservation",
+    });
+    expect(reservationEvents.map((e) => e.type)).toEqual(["reservation.created"]);
+  });
+
+  test("aggregateType filter does not weaken tenant isolation", async () => {
+    const aggregateId = uuid();
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "cart",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "cart.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+
+    const crossTenant = await loadAggregate(testDb.db, aggregateId, tenantB, {
+      aggregateType: "cart",
+    });
+    expect(crossTenant).toHaveLength(0);
+
+    const sameTenant = await loadAggregate(testDb.db, aggregateId, tenantA, {
+      aggregateType: "cart",
+    });
+    expect(sameTenant).toHaveLength(1);
+  });
+});
+
 describe("event-store: requestId is a trace marker (no DB-level uniqueness)", () => {
   test("same (tenant, requestId) twice → both events persist, no collision", async () => {
     // Idempotency is an HTTP-level concern, handled via Redis in

package/src/event-store/event-store.ts

@@ -208,11 +208,17 @@ function buildStoredEvent(
 // { includeArchived: true } for ops tools / audit that must see the tail
 // of an archived aggregate. The archive check is a single indexed lookup —
 // negligible on the hot path.
+//
+// { aggregateType } is opt-in: without it, a stream is loaded by
+// aggregateId alone, matching prior behavior. Callers that share id
+// generation across multiple aggregate types on the same id (e.g. a solon-
+// style collision) must pass it to avoid folding a foreign type's events
+// into the loaded stream.
 export async function loadAggregate(
   db: DbRunner,
   aggregateId: string,
   tenantId: TenantId,
-  options?: { readonly includeArchived?: boolean },
+  options?: { readonly includeArchived?: boolean; readonly aggregateType?: string },
 ): Promise<readonly StoredEvent[]> {
   if (!options?.includeArchived) {
     const archived = await isStreamArchived(db, tenantId, aggregateId);
@@ -221,7 +227,9 @@ export async function loadAggregate(
   const rows = await selectMany<SelectedEvent>(
     db,
     eventsTable,
-    { aggregateId, tenantId },
+    options?.aggregateType
+      ? { aggregateId, tenantId, aggregateType: options.aggregateType }
+      : { aggregateId, tenantId },
     { orderBy: { col: "version", direction: "asc" } },
   );
   return rows.map(toStoredEvent);

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

@@ -14,7 +14,7 @@ import { asRawClient } from "../../db/query-api";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import { UnprocessableError, writeFailure } from "../../errors";
-import { loadAggregate } from "../../event-store";
+import { append, loadAggregate } from "../../event-store";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 
 // --- Feature ---
@@ -109,6 +109,28 @@ const cartFeature = defineFeature("f4w", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  // Reports the raw event types + a hasEvent probe seen through the handle —
+  // lets a test assert on both aggregateType-scoping and idempotency-checks
+  // without adding another executor.
+  r.writeHandler(
+    "cart:fetch-info",
+    z.object({ id: z.uuid(), probeType: z.string() }),
+    async (event, ctx) => {
+      const stream = await ctx.fetchForWriting({
+        aggregateId: event.payload.id,
+        aggregateType: "f4wCart",
+      });
+      return {
+        isSuccess: true as const,
+        data: {
+          types: stream.events.map((e) => e.type),
+          hasProbe: stream.hasEvent(event.payload.probeType),
+        },
+      };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   // Fetch with expectedVersion — OCC gate for external callers.
   r.writeHandler(
     "cart:add-with-occ",
@@ -282,4 +304,61 @@ describe("Runde 3 / C.2a — ctx.fetchForWriting", () => {
     expect(types).toContain("f4w:event:checked-out");
     expect(types).not.toContain("f4w:event:item-added");
   });
+
+  test("#2979: a foreign-type event planted on the same aggregateId is excluded from the handle", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "grace" },
+      admin,
+    );
+
+    // Solon-style id collision: another aggregateType lands its own event on
+    // the exact same aggregateId, outside the cart executor entirely.
+    await append(stack.db, {
+      aggregateId: created.id,
+      aggregateType: "reservation",
+      tenantId: admin.tenantId,
+      expectedVersion: 1,
+      type: "reservation:event:created",
+      payload: {},
+      metadata: { userId: String(admin.id) },
+    });
+
+    const info = await stack.http.writeOk<{ types: string[]; hasProbe: boolean }>(
+      "f4w:write:cart:fetch-info",
+      { id: created.id, probeType: "reservation:event:created" },
+      admin,
+    );
+
+    expect(info.types).toEqual(["f4wCart.created"]);
+    expect(info.hasProbe).toBe(false);
+  });
+
+  test("#2979: hasEvent reflects the fetch-time snapshot for the handle's own aggregateType", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "f4w:write:cart:create",
+      { customer: "heidi" },
+      admin,
+    );
+
+    const before = await stack.http.writeOk<{ hasProbe: boolean }>(
+      "f4w:write:cart:fetch-info",
+      { id: created.id, probeType: "f4w:event:checked-out" },
+      admin,
+    );
+    expect(before.hasProbe).toBe(false);
+
+    await stack.http.writeOk(
+      "f4w:write:cart:checkout",
+      { id: created.id, totalCents: 1500 },
+      admin,
+    );
+
+    const after = await stack.http.writeOk<{ hasProbe: boolean }>(
+      "f4w:write:cart:fetch-info",
+      { id: created.id, probeType: "f4w:event:checked-out" },
+      admin,
+    );
+    expect(after.hasProbe).toBe(true);
+  });
 });

package/src/pipeline/dispatch-shared.ts

@@ -549,7 +549,9 @@ export async function buildHandlerContext(
       // when the caller just wants to append — but most callers also want
       // the events (business-rule checks), so fetch both in parallel.
       const [storedEvents, fetchedVersion] = await Promise.all([
-        loadAggregate(dbSource, args.aggregateId, user.tenantId),
+        loadAggregate(dbSource, args.aggregateId, user.tenantId, {
+          aggregateType: args.aggregateType,
+        }),
         getStreamVersion(dbSource, args.aggregateId, user.tenantId),
       ]);
       const events = await upcastStoredEvents(storedEvents, registry.getEventUpcasters(), {
@@ -596,6 +598,7 @@ export async function buildHandlerContext(
           return handleVersion;
         },
         appendOne,
+        hasEvent: (type: string) => events.some((e) => e.type === type),
       };
     },
     loadAggregate: async (