@cosmicdrift/kumiko-framework 0.1.0

package/src/db/__tests__/event-store-executor.integration.ts

@@ -0,0 +1,235 @@
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createBooleanField, createEntity, createTextField } from "../../engine";
+import { createEventsTable } from "../../event-store";
+import { createEntityTable, createTestDb, type TestDb, TestUsers, testTenantId } from "../../stack";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { buildDrizzleTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const entity = createEntity({
+  table: "read_es_exec_users",
+  fields: {
+    email: createTextField({ required: true, searchable: true }),
+    firstName: createTextField(),
+    isEnabled: createBooleanField({ default: true }),
+  },
+  softDelete: true,
+});
+const table = buildDrizzleTable("esExecUser", entity);
+
+let testDb: TestDb;
+let tdb: TenantDb;
+const adminUser = TestUsers.admin;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEntityTable(testDb.db, entity, "esExecUser");
+  await createEventsTable(testDb.db);
+  tdb = createTenantDb(testDb.db, adminUser.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(sql`TRUNCATE kumiko_events, read_es_exec_users RESTART IDENTITY CASCADE`);
+});
+
+describe("event-store-executor", () => {
+  const crud = createEventStoreExecutor(table, entity, { entityName: "esExecUser" });
+
+  test("create appends event v1 + inserts projection row", async () => {
+    const result = await crud.create({ email: "test@test.de", firstName: "Test" }, adminUser, tdb);
+    expect(result.isSuccess).toBe(true);
+    if (!result.isSuccess) return;
+    expect(result.data.isNew).toBe(true);
+    expect(typeof result.data.id).toBe("string");
+    expect(result.data.data["email"]).toBe("test@test.de");
+    expect(result.data.data["tenantId"]).toBe(testTenantId(1));
+    expect(result.data.data["version"]).toBe(1);
+  });
+
+  test("update increments version + appends event", async () => {
+    const created = await crud.create({ email: "u@test.de" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.update(
+      { id: created.data.id, version: 1, changes: { firstName: "Updated" } },
+      adminUser,
+      tdb,
+    );
+    expect(result.isSuccess).toBe(true);
+    if (!result.isSuccess) return;
+    expect(result.data.data["version"]).toBe(2);
+    expect(result.data.data["firstName"]).toBe("Updated");
+  });
+
+  test("stale version → version_conflict", async () => {
+    const created = await crud.create({ email: "v@test.de" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    await crud.update(
+      { id: created.data.id, version: 1, changes: { firstName: "First" } },
+      adminUser,
+      tdb,
+    );
+    const stale = await crud.update(
+      { id: created.data.id, version: 1, changes: { firstName: "Stale" } },
+      adminUser,
+      tdb,
+    );
+    expect(stale.isSuccess).toBe(false);
+    if (stale.isSuccess) return;
+    expect(stale.error.code).toBe("version_conflict");
+  });
+
+  test("delete soft-deletes + appends event", async () => {
+    const created = await crud.create({ email: "d@test.de" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const deleted = await crud.delete({ id: created.data.id }, adminUser, tdb);
+    expect(deleted.isSuccess).toBe(true);
+
+    const detail = await crud.detail({ id: created.data.id }, adminUser, tdb);
+    expect(detail).toBeNull();
+  });
+});
+
+// Sensitive-field stripping: passwords/tokens/IBANs stay in the entity row
+// but MUST NOT land in the immutable event log (GDPR right-to-be-forgotten,
+// secrets-rotation, audit discoverability). Fields marked `sensitive: true`
+// are excluded from every event payload: create data, update changes,
+// update previous, delete previous, restore previous.
+const sensitiveEntity = createEntity({
+  table: "read_es_exec_sensitive",
+  fields: {
+    email: createTextField({ required: true }),
+    passwordHash: createTextField({ sensitive: true }),
+    apiToken: createTextField({ sensitive: true }),
+  },
+  softDelete: true,
+});
+const sensitiveTable = buildDrizzleTable("esExecSensitive", sensitiveEntity);
+
+describe("event-store-executor — sensitive fields", () => {
+  const crud = createEventStoreExecutor(sensitiveTable, sensitiveEntity, {
+    entityName: "esExecSensitive",
+  });
+
+  beforeAll(async () => {
+    await createEntityTable(testDb.db, sensitiveEntity, "esExecSensitive");
+  });
+
+  beforeEach(async () => {
+    await testDb.db.execute(
+      sql`TRUNCATE kumiko_events, read_es_exec_sensitive RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  async function lastEvent<TPayload = Record<string, unknown>>(): Promise<{
+    type: string;
+    payload: TPayload;
+  }> {
+    const rows = await testDb.db.execute<{ type: string; payload: TPayload }>(
+      sql`SELECT type, payload FROM kumiko_events ORDER BY id DESC LIMIT 1`,
+    );
+    const row = rows[0];
+    if (!row) throw new Error("no events in store");
+    return row;
+  }
+
+  test("create event payload excludes sensitive fields but entity row keeps them", async () => {
+    const result = await crud.create(
+      { email: "s@test.de", passwordHash: "pw-hash-123", apiToken: "tok-abc" },
+      adminUser,
+      tdb,
+    );
+    if (!result.isSuccess) throw new Error("create failed");
+    // Entity row: full data preserved.
+    expect(result.data.data["passwordHash"]).toBe("pw-hash-123");
+    expect(result.data.data["apiToken"]).toBe("tok-abc");
+
+    // Event payload: sensitive stripped, public retained.
+    const event = await lastEvent();
+    expect(event.type).toBe("esExecSensitive.created");
+    expect(event.payload["email"]).toBe("s@test.de");
+    expect(event.payload["passwordHash"]).toBeUndefined();
+    expect(event.payload["apiToken"]).toBeUndefined();
+  });
+
+  test("update event strips sensitive from BOTH changes and previous", async () => {
+    const created = await crud.create(
+      { email: "u@test.de", passwordHash: "old-hash", apiToken: "old-tok" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const result = await crud.update(
+      {
+        id: created.data.id,
+        version: 1,
+        changes: { passwordHash: "new-hash", email: "u2@test.de" },
+      },
+      adminUser,
+      tdb,
+    );
+    if (!result.isSuccess) throw new Error("update failed");
+
+    const event = await lastEvent<{
+      changes: { email?: string; passwordHash?: string };
+      previous: { email?: string; passwordHash?: string; apiToken?: string };
+    }>();
+    expect(event.type).toBe("esExecSensitive.updated");
+    // Changes: email retained (public), passwordHash stripped.
+    expect(event.payload.changes.email).toBe("u2@test.de");
+    expect(event.payload.changes.passwordHash).toBeUndefined();
+    // Previous: email retained, passwordHash + apiToken stripped.
+    expect(event.payload.previous.email).toBe("u@test.de");
+    expect(event.payload.previous.passwordHash).toBeUndefined();
+    expect(event.payload.previous.apiToken).toBeUndefined();
+  });
+
+  test("delete event strips sensitive from previous", async () => {
+    const created = await crud.create(
+      { email: "d@test.de", passwordHash: "pw", apiToken: "tk" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    await crud.delete({ id: created.data.id }, adminUser, tdb);
+
+    type SensitivePrevious = {
+      previous: { email?: string; passwordHash?: string; apiToken?: string };
+    };
+    const event = await lastEvent<SensitivePrevious>();
+    expect(event.type).toBe("esExecSensitive.deleted");
+    expect(event.payload.previous.email).toBe("d@test.de");
+    expect(event.payload.previous.passwordHash).toBeUndefined();
+    expect(event.payload.previous.apiToken).toBeUndefined();
+  });
+
+  test("restore event strips sensitive from previous", async () => {
+    const created = await crud.create(
+      { email: "r@test.de", passwordHash: "pw", apiToken: "tk" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+    await crud.delete({ id: created.data.id }, adminUser, tdb);
+
+    await crud.restore({ id: created.data.id }, adminUser, tdb);
+
+    type SensitivePrevious = {
+      previous: { email?: string; passwordHash?: string; apiToken?: string };
+    };
+    const event = await lastEvent<SensitivePrevious>();
+    expect(event.type).toBe("esExecSensitive.restored");
+    expect(event.payload.previous.email).toBe("r@test.de");
+    expect(event.payload.previous.passwordHash).toBeUndefined();
+    expect(event.payload.previous.apiToken).toBeUndefined();
+  });
+});

package/src/db/__tests__/implicit-projection-equivalence.integration.ts

@@ -0,0 +1,304 @@
+// Live==Rebuild-Equivalence für die ImplicitProjection (Sprint G).
+//
+// Beweist: für jede r.entity erzeugt der EventStoreExecutor (live) und
+// rebuildProjection (replay über Implicit-Projection) **denselben**
+// Tabellen-Stand. Ohne diesen Test können live + rebuild zwischen den
+// Releases auseinanderdriften (z.B. wenn jemand die Live-Schreib-Logik
+// im Executor ändert ohne applyEntityEvent anzupassen).
+//
+// Test-Strategie:
+//   1. Live: 4 Aggregate mit verschiedenen Lifecycles (create / update /
+//      soft-delete / restore) durch den EventStoreExecutor jagen
+//   2. Snapshot der Entity-Tabelle (nach Sortierung — ORDER BY id)
+//   3. TRUNCATE der Entity-Tabelle
+//   4. rebuildProjection für die ImplicitProjection
+//   5. Snapshot erneut nehmen
+//   6. deep-equal: identische Rows in identischer Reihenfolge
+
+import { asc, sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createBooleanField, createEntity, createTextField, defineFeature } from "../../engine";
+import { createRegistry } from "../../engine/registry";
+import { createEventsTable } from "../../event-store";
+import { rebuildProjection } from "../../pipeline";
+import { createProjectionStateTable } from "../../pipeline/projection-state";
+import { createEntityTable, createTestDb, type TestDb, TestUsers } from "../../stack";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { buildDrizzleTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const userEntity = createEntity({
+  table: "read_implicit_users",
+  fields: {
+    email: createTextField({ required: true }),
+    firstName: createTextField(),
+    isEnabled: createBooleanField({ default: true }),
+  },
+  softDelete: true,
+});
+
+const userFeature = defineFeature("implicittest", (r) => {
+  r.entity("user", userEntity);
+});
+
+const userTable = buildDrizzleTable("user", userEntity);
+
+let testDb: TestDb;
+let tdb: TenantDb;
+const adminUser = TestUsers.admin;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEntityTable(testDb.db, userEntity, "user");
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+  tdb = createTenantDb(testDb.db, adminUser.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(
+    sql`TRUNCATE kumiko_events, read_implicit_users, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+});
+
+async function snapshotTable(): Promise<readonly Record<string, unknown>[]> {
+  const rows = await testDb.db.select().from(userTable).orderBy(asc(userTable["id"]));
+  return rows as readonly Record<string, unknown>[];
+}
+
+describe("implicit-projection / Live==Rebuild equivalence", () => {
+  test("4 aggregates × create/update/delete/restore round-trip identical to rebuild", async () => {
+    const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+
+    // 1. Live writes — verschiedene Lifecycle-Pfade über die 4 Aggregate.
+    //    Aggregate A: create + update
+    //    Aggregate B: create + update + delete (soft)
+    //    Aggregate C: create + delete + restore
+    //    Aggregate D: create only
+    const a = await crud.create({ email: "a@test.de", firstName: "Alice" }, adminUser, tdb);
+    if (!a.isSuccess) throw new Error("setup A failed");
+    await crud.update(
+      { id: a.data.id, version: 1, changes: { firstName: "Alice Updated" } },
+      adminUser,
+      tdb,
+    );
+
+    const b = await crud.create({ email: "b@test.de", firstName: "Bob" }, adminUser, tdb);
+    if (!b.isSuccess) throw new Error("setup B failed");
+    await crud.update({ id: b.data.id, version: 1, changes: { isEnabled: false } }, adminUser, tdb);
+    await crud.delete({ id: b.data.id }, adminUser, tdb);
+
+    const c = await crud.create({ email: "c@test.de", firstName: "Carol" }, adminUser, tdb);
+    if (!c.isSuccess) throw new Error("setup C failed");
+    await crud.delete({ id: c.data.id }, adminUser, tdb);
+    await crud.restore({ id: c.data.id }, adminUser, tdb);
+
+    await crud.create({ email: "d@test.de", firstName: "Dave" }, adminUser, tdb);
+
+    const liveSnapshot = await snapshotTable();
+
+    // Konkrete Erwartung an den Live-Stand: 4 erzeugte Aggregate, B ist
+    // soft-deleted (isDeleted=true), C ist restored (isDeleted=false),
+    // A und D sind unangetastet. Wenn das nicht stimmt, ist der Test
+    // setup buggy bevor wir den Rebuild überhaupt vergleichen.
+    expect(liveSnapshot).toHaveLength(4);
+    const byEmail = new Map(liveSnapshot.map((r) => [r["email"] as string, r]));
+    expect(byEmail.get("a@test.de")).toMatchObject({
+      firstName: "Alice Updated",
+      version: 2,
+      isDeleted: false,
+    });
+    expect(byEmail.get("b@test.de")).toMatchObject({
+      isEnabled: false,
+      version: 3,
+      isDeleted: true,
+    });
+    expect(byEmail.get("c@test.de")).toMatchObject({
+      version: 3,
+      isDeleted: false,
+    });
+    expect(byEmail.get("d@test.de")).toMatchObject({
+      firstName: "Dave",
+      version: 1,
+      isDeleted: false,
+    });
+
+    // 2. Rebuild from event-log — registry baut die ImplicitProjection,
+    //    rebuildProjection findet sie über getAllProjections().
+    const registry = createRegistry([userFeature]);
+    const implicitName = "implicittest:projection:user-entity";
+    expect(registry.getAllProjections().has(implicitName)).toBe(true);
+
+    const result = await rebuildProjection(implicitName, {
+      db: testDb.db,
+      registry,
+    });
+
+    // 4 creates + 2 updates + 2 deletes + 1 restore = 9 Events. Wenn
+    // die ImplicitProjection silently nichts apply'd hätte, wäre der
+    // Count 0 — der Test würde dann den nachfolgenden deep-equal trotzdem
+    // verfehlen, aber explizit der Count fängt den Sub-Bug "apply lief,
+    // aber für die falsche Event-Anzahl".
+    expect(result.eventsProcessed).toBe(9);
+
+    // 3. Vergleich. Erst ID-für-ID strikt prüfen damit klar ist welche
+    // Felder verglichen werden — dann das Array-deep-equal als Catch-all.
+    const rebuildSnapshot = await snapshotTable();
+    expect(rebuildSnapshot).toHaveLength(liveSnapshot.length);
+    for (let i = 0; i < liveSnapshot.length; i++) {
+      const live = liveSnapshot[i];
+      const rebuilt = rebuildSnapshot[i];
+      // Diese Felder sind die User-sichtbare Truth (was sieht die UI?
+      // was schreibt der Audit-Log?). Wenn eines davon driftet, ist
+      // Live==Rebuild nicht mehr gegeben.
+      const fields = [
+        "id",
+        "tenantId",
+        "version",
+        "email",
+        "firstName",
+        "isEnabled",
+        "isDeleted",
+        "insertedAt",
+        "modifiedAt",
+        "deletedAt",
+        "insertedById",
+        "modifiedById",
+        "deletedById",
+      ] as const;
+      for (const f of fields) {
+        expect(rebuilt?.[f], `field "${f}" at row ${i}`).toEqual(live?.[f]);
+      }
+    }
+    // Catch-all: irgendein Feld das wir nicht explizit listen?
+    expect(rebuildSnapshot).toEqual(liveSnapshot);
+  });
+
+  test("ImplicitProjection ist im Registry registriert mit korrekten apply-keys", () => {
+    const registry = createRegistry([userFeature]);
+    const projection = registry.getAllProjections().get("implicittest:projection:user-entity");
+    expect(projection).toBeDefined();
+    if (!projection) return;
+    // 4 Auto-Verben weil softDelete=true → restored kommt dazu
+    expect(Object.keys(projection.apply).sort()).toEqual([
+      "user.created",
+      "user.deleted",
+      "user.restored",
+      "user.updated",
+    ]);
+    expect(projection.source).toBe("user");
+  });
+
+  test("ohne softDelete → keine restore-apply-key registriert", () => {
+    const hardDeleteEntity = createEntity({
+      table: "read_implicit_hard",
+      fields: { name: createTextField({ required: true }) },
+    });
+    const hardFeature = defineFeature("implicithard", (r) => {
+      r.entity("widget", hardDeleteEntity);
+    });
+    const registry = createRegistry([hardFeature]);
+    const projection = registry.getAllProjections().get("implicithard:projection:widget-entity");
+    expect(projection).toBeDefined();
+    if (!projection) return;
+    expect(Object.keys(projection.apply).sort()).toEqual([
+      "widget.created",
+      "widget.deleted",
+      "widget.updated",
+    ]);
+  });
+});
+
+// Sensitive-Drift ist eine bekannte Welle-3-Lücke: das Event-Log strippt
+// sensitive-Felder VOR dem Append (GDPR-Annahme), die Live-Read-Tabelle
+// bekommt sie über den unstripped flatData, der Rebuild-Pfad nur den
+// stripped event.payload. Bei Schema-Rebuilds gehen sensitive Daten
+// verloren.
+//
+// Dieser Test pinst die Drift explizit: Live row hat das sensitive Feld,
+// Rebuild row hat NULL. Wenn Welle 3 das fixt (z.B. via separater
+// sensitive-Spalte oder verschlüsseltem Event-Payload), bricht der Test
+// und zwingt zu Aufmerksamkeit.
+
+import { sql as drizzleSql, eq } from "drizzle-orm";
+
+const sensitiveTable = "read_implicit_sensitive_users";
+
+const sensitiveEntity = createEntity({
+  table: sensitiveTable,
+  fields: {
+    email: createTextField({ required: true }),
+    apiKey: createTextField({ sensitive: true }),
+  },
+});
+
+const sensitiveFeature = defineFeature("implicitsensitive", (r) => {
+  r.entity("sensitive-user", sensitiveEntity);
+});
+
+const sensitiveDrizzleTable = buildDrizzleTable("sensitive-user", sensitiveEntity);
+
+describe("implicit-projection / dokumentierte Sensitive-Drift", () => {
+  beforeAll(async () => {
+    await createEntityTable(testDb.db, sensitiveEntity, "sensitive-user");
+  });
+
+  beforeEach(async () => {
+    await testDb.db.execute(
+      drizzleSql.raw(
+        `TRUNCATE ${sensitiveTable}, kumiko_events, kumiko_projections RESTART IDENTITY CASCADE`,
+      ),
+    );
+  });
+
+  test("Live schreibt sensitive-Felder, Rebuild lässt sie NULL (Welle-3-Roadmap)", async () => {
+    const crud = createEventStoreExecutor(sensitiveDrizzleTable, sensitiveEntity, {
+      entityName: "sensitive-user",
+    });
+
+    // 1. Live: create mit apiKey (sensitive). Read-Tabelle bekommt den
+    //    Wert direkt vom Live-Pfad (unstripped flatData).
+    const created = await crud.create(
+      { email: "x@test.de", apiKey: "secret-token-abc" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const [liveRow] = await testDb.db
+      .select()
+      .from(sensitiveDrizzleTable)
+      .where(eq(sensitiveDrizzleTable["id"], created.data.id as string));
+    expect(liveRow?.["apiKey"]).toBe("secret-token-abc");
+    expect(liveRow?.["email"]).toBe("x@test.de");
+
+    // 2. Verifiziere dass das Event-Log das Feld NICHT enthält (stripped).
+    const events = await testDb.db.execute<{ payload: Record<string, unknown> }>(
+      drizzleSql`SELECT payload FROM kumiko_events WHERE aggregate_id = ${created.data.id}::uuid`,
+    );
+    expect(events[0]?.payload).toBeDefined();
+    expect(events[0]?.payload?.["apiKey"]).toBeUndefined();
+    expect(events[0]?.payload?.["email"]).toBe("x@test.de");
+
+    // 3. Rebuild über die ImplicitProjection. Read-Tabelle wird aus
+    //    event.payload neu materialisiert — apiKey ist nicht im Log,
+    //    landet also als NULL/undefined in der rebuilt Row.
+    const registry = createRegistry([sensitiveFeature]);
+    await rebuildProjection("implicitsensitive:projection:sensitive-user-entity", {
+      db: testDb.db,
+      registry,
+    });
+
+    const [rebuiltRow] = await testDb.db
+      .select()
+      .from(sensitiveDrizzleTable)
+      .where(eq(sensitiveDrizzleTable["id"], created.data.id as string));
+    expect(rebuiltRow?.["email"]).toBe("x@test.de");
+    // DAS ist die Drift: sensitive Feld ist nach Rebuild weg.
+    expect(rebuiltRow?.["apiKey"]).toBeNull();
+  });
+});