@cosmicdrift/kumiko-framework 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @cosmicdrift/kumiko-framework
 
+## 0.7.0
+
+### Minor Changes
+
+- bcf43b6: es-ops: `SeedMembershipRow` exposes `streamTenantId` (stream-tenant aus `kumiko_events.v1`) neben dem payload-`tenantId`. Seed-Authors müssen den `kumiko_events`-JOIN nicht mehr selbst bauen — `m.streamTenantId` ist der korrekte Wert für `systemWriteAs`'s `tenantIdOverride` wenn das Aggregate von einem fremden Executor angelegt wurde (typisches `seedTenantMembership(by=systemAdmin)`-Pattern).
+
 ## 0.6.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.6.0",
+  "version": "0.7.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>",
@@ -163,7 +163,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.6.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.7.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "drizzle-kit": "^0.31.10",

package/src/es-ops/README.md

@@ -32,7 +32,7 @@ export default {
       await ctx.systemWriteAs(
         "tenant:write:update-member-roles",
         { userId: admin.id, tenantId: m.tenantId, roles: [...m.roles, "TenantAdmin"] },
-        m.tenantId, // ← tenantIdOverride: Aggregate lebt im Tenant-Stream, NICHT SYSTEM
+        m.streamTenantId, // ← tenantIdOverride aus dem JOIN auf kumiko_events.v1
       );
     }
   },
@@ -47,9 +47,11 @@ Faustregel: **wenn das Ziel-Aggregate via Tenant-User erstellt wurde, brauchst D
 |---|---|---|
 | config-values (system-scope) | SYSTEM_TENANT | weglassen |
 | system text-content | SYSTEM_TENANT | weglassen |
-| tenant-membership | jeweiliger Tenant-Stream | ✅ `m.tenantId` |
+| tenant-membership | jeweiliger Stream-Tenant aus events.v1 | ✅ `m.streamTenantId` (NICHT `m.tenantId` — die beiden können divergieren!) |
 | App-Entity (orders, tasks, …) | Tenant-Stream | ✅ Tenant-Id aus dem Lookup |
 
+**Warum nicht `m.tenantId`?** read_tenant_memberships.tenant_id ist der payload-tenant (logisches Mitgliedschafts-Ziel), kumiko_events.tenant_id der v1-Row ist der stream-tenant (wo das Aggregate physisch lebt). seedTenantMembership mit `by=systemAdmin` lässt die zwei auseinanderlaufen — der Helper `findMembershipsOfUser` liefert beide getrennt, damit Seeds den richtigen wählen können.
+
 Ohne `tenantIdOverride` sucht der Executor den Stream gegen SYSTEM_TENANT → `version_conflict`. Memory: `feedback_event_store_tenant_consistency.md`.
 
 ## Deployment-Anforderungen

package/src/es-ops/__tests__/context.integration.ts

@@ -55,10 +55,34 @@ afterAll(async () => {
 
 beforeEach(async () => {
   await testDb.db.execute(sql`
-    TRUNCATE kumiko_es_operations, read_users, read_tenant_memberships, read_tenants
+    TRUNCATE kumiko_es_operations, kumiko_events, read_users, read_tenant_memberships, read_tenants
+    RESTART IDENTITY CASCADE
   `);
 });
 
+// Helper: simulate `seedTenantMembership` writing both the read-row and
+// its v1-event with a custom stream-tenant. Tests use this to construct
+// the stream-vs-payload-tenant scenarios that drive the JOIN-helper.
+async function insertMembershipWithEvent(args: {
+  readonly id: string;
+  readonly userId: string;
+  readonly payloadTenantId: string;
+  readonly streamTenantId: string;
+  readonly roles: string;
+}): Promise<void> {
+  await testDb.db.execute(sql`
+    INSERT INTO read_tenant_memberships (id, user_id, tenant_id, roles)
+    VALUES (${args.id}::uuid, ${args.userId}, ${args.payloadTenantId}::uuid, ${args.roles})
+  `);
+  await testDb.db.execute(sql`
+    INSERT INTO kumiko_events
+      (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
+    VALUES
+      (${args.id}::uuid, 'tenant-membership', ${args.streamTenantId}::uuid, 1,
+       'tenant-membership.created', '{}'::jsonb, '{"userId":"system"}'::jsonb, 'system')
+  `);
+}
+
 function makeMockDispatcher() {
   return {
     write: vi.fn(async () => ({ isSuccess: true as const, data: {} })),
@@ -107,13 +131,24 @@ describe("SeedMigrationContext.findUserByEmail (integration)", () => {
 describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
   test("parst JSON-encoded roles-Spalte zu string[]", async () => {
     const userId = "01900000-0000-7000-8000-000000000001";
+    const aggId1 = "00000000-0000-4000-8000-0000000000a1";
+    const aggId2 = "00000000-0000-4000-8000-0000000000a2";
     const tenantId1 = "00000000-0000-4000-8000-000000000001";
     const tenantId2 = "00000000-0000-4000-8000-000000000002";
-    await testDb.db.execute(sql`
-      INSERT INTO read_tenant_memberships (user_id, tenant_id, roles) VALUES
-        (${userId}, ${tenantId1}::uuid, '["Admin", "TenantAdmin"]'),
-        (${userId}, ${tenantId2}::uuid, '["User"]')
-    `);
+    await insertMembershipWithEvent({
+      id: aggId1,
+      userId,
+      payloadTenantId: tenantId1,
+      streamTenantId: tenantId1,
+      roles: '["Admin", "TenantAdmin"]',
+    });
+    await insertMembershipWithEvent({
+      id: aggId2,
+      userId,
+      payloadTenantId: tenantId2,
+      streamTenantId: tenantId2,
+      roles: '["User"]',
+    });
 
     const ctx = createSeedMigrationContext({
       dispatcher: makeMockDispatcher() as never,
@@ -129,14 +164,49 @@ describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
     expect(m2?.roles).toEqual(["User"]);
   });
 
+  test("stream-tenant != payload-tenant wird korrekt ausgewiesen (Driver-Bug)", async () => {
+    // Reproduziert den publicstatus-Driver-Fall: seedTenantMembership
+    // wurde mit by=systemAdmin aufgerufen → executor.tenantId=
+    // SYSTEM_TENANT_ID landet als events.tenant_id, während payload.
+    // tenantId der target-Tenant ist. Die beiden divergieren.
+    const userId = "01900000-0000-7000-8000-000000000001";
+    const aggId = "00000000-0000-4000-8000-0000000000b1";
+    const payloadTenant = "00000000-0000-4000-8000-000000000042";
+    const streamTenant = "00000000-0000-4000-8000-000000000001"; // SYSTEM_TENANT-Stil
+    await insertMembershipWithEvent({
+      id: aggId,
+      userId,
+      payloadTenantId: payloadTenant,
+      streamTenantId: streamTenant,
+      roles: '["Admin"]',
+    });
+
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const [m] = await ctx.findMembershipsOfUser(userId);
+    expect(m).toEqual({
+      userId,
+      tenantId: payloadTenant,
+      streamTenantId: streamTenant,
+      roles: ["Admin"],
+    });
+  });
+
   test("malformed roles-JSON → leeres Array (defensive, no throw)", async () => {
     // Defensive: wenn ein corrupted row kommt, soll der Seed nicht
     // explodieren — kann selbst entscheiden was zu tun ist.
     const userId = "01900000-0000-7000-8000-000000000002";
-    await testDb.db.execute(sql`
-      INSERT INTO read_tenant_memberships (user_id, tenant_id, roles) VALUES
-        (${userId}, '00000000-0000-4000-8000-000000000003'::uuid, 'not-json')
-    `);
+    const aggId = "00000000-0000-4000-8000-0000000000c1";
+    const tenantId = "00000000-0000-4000-8000-000000000003";
+    await insertMembershipWithEvent({
+      id: aggId,
+      userId,
+      payloadTenantId: tenantId,
+      streamTenantId: tenantId,
+      roles: "not-json",
+    });
     const ctx = createSeedMigrationContext({
       dispatcher: makeMockDispatcher() as never,
       dbRunner: testDb.db,
@@ -153,6 +223,26 @@ describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
     const memberships = await ctx.findMembershipsOfUser("01900000-0000-7000-8000-000000000099");
     expect(memberships).toEqual([]);
   });
+
+  test("membership ohne v1-Event wird vom INNER JOIN ausgefiltert (Drift-Detection)", async () => {
+    // Schutz vor Data-Drift: read-row ohne event-row ist kein legitimer
+    // Zustand für ein ES-Aggregate. Statt einer Half-Row zurückzugeben
+    // verschwindet die Row aus dem Result — Seed-Author sieht "0 memberships"
+    // statt einer mit fehlendem stream-tenant zu arbeiten und schwer
+    // diagnostizierbare version_conflict-Errors zu produzieren.
+    const userId = "01900000-0000-7000-8000-000000000003";
+    await testDb.db.execute(sql`
+      INSERT INTO read_tenant_memberships (id, user_id, tenant_id, roles) VALUES
+        ('00000000-0000-4000-8000-0000000000d1'::uuid, ${userId},
+         '00000000-0000-4000-8000-000000000005'::uuid, '["Admin"]')
+    `);
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const memberships = await ctx.findMembershipsOfUser(userId);
+    expect(memberships).toEqual([]);
+  });
 });
 
 describe("SeedMigrationContext.findTenants (integration)", () => {

package/src/es-ops/context.ts

@@ -76,17 +76,34 @@ export function createSeedMigrationContext(
     },
 
     findMembershipsOfUser: async (userId) => {
+      // INNER JOIN auf kumiko_events um den stream-tenant (events.tenant_id
+      // der v1-Row) neben dem payload-tenant (memberships.tenant_id) zu
+      // liefern. Die beiden divergieren wenn das Aggregate von einem
+      // Executor mit fremder tenantId angelegt wurde (seedTenantMembership
+      // by=systemAdmin) — typischer publicstatus-Driver-Use-Case.
+      // INNER (nicht LEFT): kein v1-Event bei vorhandener Read-Row wäre
+      // Data-Drift, kein legitimer Zustand für Seed-Migrations.
       // @cast-boundary db-row — roles ist JSON-string in der text-Spalte
       // (Memory: tenant-membership.created payload "[\"User\"]"), wird unten geparst
       const rows = (await args.dbRunner.execute(
-        sql`SELECT user_id::text AS user_id, tenant_id::text AS tenant_id, roles
-            FROM read_tenant_memberships
-            WHERE user_id = ${userId}`,
-      )) as unknown as readonly { user_id: string; tenant_id: string; roles: string }[];
+        sql`SELECT m.user_id::text AS user_id,
+                   m.tenant_id::text AS tenant_id,
+                   e.tenant_id::text AS stream_tenant_id,
+                   m.roles
+            FROM read_tenant_memberships m
+            JOIN kumiko_events e ON e.aggregate_id = m.id AND e.version = 1
+            WHERE m.user_id = ${userId}`,
+      )) as unknown as readonly {
+        user_id: string;
+        tenant_id: string;
+        stream_tenant_id: string;
+        roles: string;
+      }[];
       return rows.map(
         (r): SeedMembershipRow => ({
           userId: r.user_id,
           tenantId: r.tenant_id,
+          streamTenantId: r.stream_tenant_id,
           roles: safeParseRolesJson(r.roles),
         }),
       );

package/src/es-ops/types.ts

@@ -46,10 +46,23 @@ export type SeedUserRow = {
   readonly tenantId: string;
 };
 
-/** Read-shape eines Membership-Eintrags wie an Seed-Helpers exposed. */
+/** Read-shape eines Membership-Eintrags wie an Seed-Helpers exposed.
+ *  Unterscheidet zwei tenantIds: die "logische" aus dem Read-Projektion
+ *  (`tenantId`) und die "physische" aus dem Aggregate-Stream
+ *  (`streamTenantId`). Die beiden weichen voneinander ab wenn das
+ *  Aggregate von einem Executor mit anderer tenantId angelegt wurde
+ *  (z.B. seedTenantMembership-by=systemAdmin) — typischer
+ *  publicstatus-Driver-Use-Case. */
 export type SeedMembershipRow = {
   readonly userId: string;
+  /** Payload-tenant aus `read_tenant_memberships.tenant_id`. Geht ins
+   *  write-payload als `tenantId`. */
   readonly tenantId: string;
+  /** Stream-tenant aus `kumiko_events.tenant_id` der v1-Row. MUSS als
+   *  `tenantIdOverride` an `systemWriteAs` durchgereicht werden, sonst
+   *  sucht der Event-Store-Executor den Stream im falschen Tenant und
+   *  liefert `version_conflict`. */
+  readonly streamTenantId: string;
   readonly roles: readonly string[];
 };