@cosmicdrift/kumiko-framework 0.105.1 → 0.108.0

package/src/bun-db/__tests__/write-brand.test.ts

@@ -0,0 +1,48 @@
+// Type-level contract for the ES-write brand (#742): the public write helpers
+// reject a managed EntityTable at COMPILE time (executor-only), while reads on
+// it and writes on unmanaged tables stay allowed. The bodies below are never
+// invoked — tsc checks them, bun:test does not run them. Each `@ts-expect-error`
+// turns into an "unused directive" compile error if the brand ever stops firing,
+// so a regression breaks the build, not just this test.
+
+import { expect, test } from "bun:test";
+import { defineUnmanagedTable } from "../../db/entity-table-meta";
+import { buildEntityTable } from "../../db/table-builder";
+import { createEntity, createTextField } from "../../engine";
+import { type AnyDb, deleteMany, insertOne, selectMany, updateMany } from "../query";
+
+const brandedEntity = buildEntityTable(
+  "brandSample",
+  createEntity({ table: "brand_sample", fields: { title: createTextField({ required: true }) } }),
+);
+
+const unmanagedTable = defineUnmanagedTable({
+  tableName: "brand_unmanaged",
+  columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true }],
+});
+
+async function _writeRejectsManagedEntity(db: AnyDb): Promise<void> {
+  // @ts-expect-error — managed EntityTable is executor-only; direct insert is a compile error.
+  await insertOne(db, brandedEntity, { title: "x" });
+  // @ts-expect-error — direct update on a managed EntityTable is rejected.
+  await updateMany(db, brandedEntity, { title: "y" }, { id: "1" });
+  // @ts-expect-error — direct delete on a managed EntityTable is rejected.
+  await deleteMany(db, brandedEntity, { id: "1" });
+}
+
+async function _writeAllowsUnmanagedTable(db: AnyDb): Promise<void> {
+  // Unmanaged tables carry no brand — direct writes stay allowed.
+  await insertOne(db, unmanagedTable, { id: "1" });
+  await deleteMany(db, unmanagedTable, { id: "1" });
+}
+
+async function _readAllowsManagedEntity(db: AnyDb): Promise<void> {
+  // Reads on a managed EntityTable are always fine (reads keep the permissive param).
+  await selectMany(db, brandedEntity, { id: "1" });
+}
+
+test("ES-write brand: compile-time contracts are wired", () => {
+  expect(_writeRejectsManagedEntity).toBeDefined();
+  expect(_writeAllowsUnmanagedTable).toBeDefined();
+  expect(_readAllowsManagedEntity).toBeDefined();
+});

package/src/bun-db/query.ts

@@ -20,7 +20,7 @@
 //     reference, NICHT als runtime-API-call)
 
 import type { EntityTableMeta } from "../db/entity-table-meta";
-import { toSnakeCase } from "../db/table-builder";
+import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
 import { parseJsonSafe } from "../utils/safe-json";
 
@@ -109,6 +109,23 @@ export function asRawClient(db: unknown): RawClient {
   );
 }
 
+// postgres.js / Bun.SQL reject the WHOLE begin() when any statement inside
+// it errored — even if the JS error was caught (the driver tracks per-block
+// query failures). Error confinement therefore must go through the driver's
+// own savepoint(), not manual SAVEPOINT statements. The callback receives
+// the savepoint-scoped tx; run every confined statement on THAT handle.
+export async function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T> {
+  const raw = asRawClient(tx) as unknown as {
+    savepoint?: <TR>(cb: (sp: unknown) => Promise<TR>) => Promise<TR>;
+  };
+  if (typeof raw.savepoint !== "function") {
+    throw new Error(
+      "runInSavepoint: transaction handle has no savepoint() — pass the driver tx (postgres.js TransactionSql / Bun.SQL).",
+    );
+  }
+  return raw.savepoint(fn);
+}
+
 /**
  * When handlers call `selectMany(ctx.db, …)` instead of `ctx.db.selectMany(…)`,
  * unwrap via asRawClient would bypass TenantDb scoping. Duck-type TenantDb and
@@ -204,6 +221,16 @@ export type SelectOptions = {
 // biome-ignore lint/suspicious/noExplicitAny: legacy drizzle pgTable surface
 type TableLike = EntityTableMeta | any;
 
+// Write-Param: alles was TableLike akzeptiert AUSSER einer gebrandeten
+// EntityTable (managed projection). Ein direkter Write auf eine Entity ist ein
+// Compile-Fehler — der einzige Schreibweg ist der Executor (Event ->
+// rebuild-safe). Unmanaged EntityTableMeta + die am Executor-Seam auf
+// TableColumns<any> eraste Table tragen den Brand nicht -> erlaubt. Test-Seeds
+// gehen über den sanktionierten testing-Seam (seedRow/…), der den Brand strippt.
+// Method-form writes (ctx.db.insertOne/…) keep an erased param and are covered
+// by the guard-direct-entity-writes AST guard instead (see tenant-db.ts).
+type WritableTable = EntityTableMeta & NotExecutorOnly;
+
 export type TableInfo = {
   readonly name: string;
   // field-name (camelCase oder snake_case) → snake_case column-name
@@ -566,7 +593,7 @@ export async function fetchOne<TRow = any>(
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function insertMany<TRow = any>(
   db: AnyDb,
-  table: TableLike,
+  table: WritableTable,
   rows: ReadonlyArray<Record<string, unknown>>,
 ): Promise<readonly TRow[]> {
   if (rows.length === 0) return [];
@@ -604,7 +631,7 @@ export async function insertMany<TRow = any>(
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function insertOne<TRow = any>(
   db: AnyDb,
-  table: TableLike,
+  table: WritableTable,
   values: Record<string, unknown>,
 ): Promise<TRow | undefined> {
   const scoped = tenantDbDelegate(db);
@@ -642,7 +669,7 @@ export async function insertOne<TRow = any>(
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function updateMany<TRow = any>(
   db: AnyDb,
-  table: TableLike,
+  table: WritableTable,
   set: Record<string, unknown>,
   where: WhereObject,
 ): Promise<readonly TRow[]> {
@@ -679,7 +706,11 @@ export async function updateMany<TRow = any>(
   return coerceRows(raw, info) as readonly TRow[];
 }
 
-export async function deleteMany(db: AnyDb, table: TableLike, where: WhereObject): Promise<void> {
+export async function deleteMany(
+  db: AnyDb,
+  table: WritableTable,
+  where: WhereObject,
+): Promise<void> {
   const scoped = tenantDbDelegate(db);
   if (scoped) {
     return scoped.deleteMany(table, where);
@@ -783,7 +814,7 @@ export async function countWhere(
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function upsertOnConflict<TRow = any>(
   db: AnyDb,
-  table: TableLike,
+  table: WritableTable,
   values: Record<string, unknown>,
   options: UpsertOnConflictOptions,
 ): Promise<TRow | undefined> {
@@ -833,7 +864,7 @@ export async function upsertOnConflict<TRow = any>(
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function upsertByPk<TRow = any>(
   db: AnyDb,
-  table: TableLike,
+  table: WritableTable,
   values: Record<string, unknown>,
   updateOnConflict?: Record<string, unknown>,
 ): Promise<TRow | undefined> {
@@ -855,7 +886,7 @@ export type IncrementCounterOptions = {
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function incrementCounter<TRow = any>(
   db: AnyDb,
-  table: TableLike,
+  table: WritableTable,
   values: Record<string, unknown>,
   increments: Record<string, number>,
   options: IncrementCounterOptions = {},
@@ -914,7 +945,7 @@ export async function incrementCounter<TRow = any>(
 
 export async function deleteManyBatched(
   db: AnyDb,
-  table: TableLike,
+  table: WritableTable,
   where: WhereObject,
   options: DeleteManyBatchedOptions,
 ): Promise<DeleteManyBatchedResult> {

package/src/db/__tests__/assert-exists-in.integration.test.ts

@@ -4,7 +4,7 @@
 // eine dangling/cross-tenant Reference. Schwerpunkt: Tenant-Isolation.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { insertMany } from "../../bun-db";
+import { seedRows } from "@cosmicdrift/kumiko-framework/testing";
 import { createEntity, createTextField } from "../../engine";
 import { NotFoundError } from "../../errors";
 import { setupTestStack, type TestStack, testTenantId, unsafeCreateEntityTable } from "../../stack";
@@ -29,7 +29,7 @@ let stack: TestStack;
 beforeAll(async () => {
   stack = await setupTestStack({ features: [] });
   await unsafeCreateEntityTable(stack.db, orderEntity);
-  await insertMany(stack.db, orderTable, [
+  await seedRows(stack.db, orderTable, [
     { id: ID_A, tenantId: tenantA, name: "A-Order" },
     { id: ID_B, tenantId: tenantB, name: "B-Order" },
   ]);

package/src/db/__tests__/eagerload.integration.test.ts

@@ -3,7 +3,7 @@
 // werden (TenantDb filtert), sonst leakt eagerload fremde Rows nach _refs.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { insertMany } from "../../bun-db";
+import { seedRows } from "@cosmicdrift/kumiko-framework/testing";
 import { createEntity, createTextField } from "../../engine";
 import type { EntityDefinition } from "../../engine/types";
 import { setupTestStack, type TestStack, testTenantId, unsafeCreateEntityTable } from "../../stack";
@@ -55,7 +55,7 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, authorEntity);
   dbA = createTenantDb(stack.db, tenantA, "tenant");
 
-  await insertMany(stack.db, authorTable, [
+  await seedRows(stack.db, authorTable, [
     { id: A1, tenantId: tenantA, name: "Ada" },
     { id: A2, tenantId: tenantA, name: "Linus" },
     { id: BX, tenantId: tenantB, name: "Foreign" },

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

@@ -313,6 +313,16 @@ const encryptedEntity = createEntity({
 });
 const encryptedTable = buildEntityTable("esExecEncrypted", encryptedEntity);
 
+const encryptedSoftDeleteEntity = createEntity({
+  table: "read_es_exec_enc_soft",
+  fields: {
+    email: createTextField({ required: true }),
+    secretNote: createTextField({ encrypted: true }),
+  },
+  softDelete: true,
+});
+const encryptedSoftDeleteTable = buildEntityTable("esExecEncSoft", encryptedSoftDeleteEntity);
+
 describe("event-store-executor — encrypted fields", () => {
   const encryption = createEncryptionProvider(ENCRYPTION_TEST_KEY);
   const crud = createEventStoreExecutor(encryptedTable, encryptedEntity, {
@@ -320,15 +330,22 @@ describe("event-store-executor — encrypted fields", () => {
     encryption,
   });
 
+  const softDeleteCrud = createEventStoreExecutor(
+    encryptedSoftDeleteTable,
+    encryptedSoftDeleteEntity,
+    { entityName: "esExecEncSoft", encryption },
+  );
+
   beforeAll(async () => {
     process.env["ENCRYPTION_KEY"] = ENCRYPTION_TEST_KEY;
     resetEntityFieldEncryptionCacheForTests();
     await unsafeCreateEntityTable(testDb.db, encryptedEntity, "esExecEncrypted");
+    await unsafeCreateEntityTable(testDb.db, encryptedSoftDeleteEntity, "esExecEncSoft");
   });
 
   beforeEach(async () => {
     await asRawClient(testDb.db).unsafe(
-      `TRUNCATE kumiko_events, read_es_exec_encrypted RESTART IDENTITY CASCADE`,
+      `TRUNCATE kumiko_events, read_es_exec_encrypted, read_es_exec_enc_soft RESTART IDENTITY CASCADE`,
     );
   });
 
@@ -372,6 +389,76 @@ describe("event-store-executor — encrypted fields", () => {
     if (!updated.isSuccess) throw new Error("update failed");
     expect(updated.data.data["secretNote"]).toBe("new-note");
   });
+
+  test("update's persisted event carries ciphertext (not plaintext) for an encrypted field in `previous`", async () => {
+    // Regression: `previous` in the STORED event came from loadById(), which
+    // decrypts — appending it unchanged would put the plaintext of an
+    // `encrypted` field into the immutable kumiko_events log even though the
+    // row itself is stored as ciphertext.
+    const created = await crud.create(
+      { email: "prev-enc@test.de", secretNote: "old-plaintext-note" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    // Change an UNRELATED field — `secretNote` still rides along in `previous`
+    // unchanged, at its pre-update (decrypted) value.
+    const updated = await crud.update(
+      { id: created.data.id, version: 1, changes: { email: "prev-enc-2@test.de" } },
+      adminUser,
+      tdb,
+    );
+    if (!updated.isSuccess) throw new Error("update failed");
+
+    const rows = (await asRawClient(testDb.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE type = 'esExecEncrypted.updated' ORDER BY id DESC LIMIT 1`,
+    )) as Array<{ payload: { previous?: { secretNote?: string } } }>;
+    const storedPrevious = rows[0]?.payload.previous?.secretNote;
+    expect(storedPrevious).toBeDefined();
+    expect(storedPrevious).not.toBe("old-plaintext-note");
+  });
+
+  test("delete's persisted event carries ciphertext (not plaintext) for an encrypted field in `previous`", async () => {
+    const created = await crud.create(
+      { email: "del-enc@test.de", secretNote: "delete-plaintext-note" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const deleted = await crud.delete({ id: created.data.id }, adminUser, tdb);
+    if (!deleted.isSuccess) throw new Error("delete failed");
+
+    const rows = (await asRawClient(testDb.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE type = 'esExecEncrypted.deleted' ORDER BY id DESC LIMIT 1`,
+    )) as Array<{ payload: { previous?: { secretNote?: string } } }>;
+    const storedPrevious = rows[0]?.payload.previous?.secretNote;
+    expect(storedPrevious).toBeDefined();
+    expect(storedPrevious).not.toBe("delete-plaintext-note");
+  });
+
+  test("restore returns plaintext (data + previous) for an encrypted field, not ciphertext (725/2)", async () => {
+    // Regression: restore() read `restored`/`data` straight from
+    // applyEntityEvent/selectMany (both ciphertext for an `encrypted` field)
+    // and returned them without decryptForRead — unlike create/update/list/
+    // detail, which all decrypt before handing the row to the caller.
+    const created = await softDeleteCrud.create(
+      { email: "restore-enc@test.de", secretNote: "restore-plaintext-note" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const deleted = await softDeleteCrud.delete({ id: created.data.id }, adminUser, tdb);
+    if (!deleted.isSuccess) throw new Error("delete failed");
+
+    const restored = await softDeleteCrud.restore({ id: created.data.id }, adminUser, tdb);
+    if (!restored.isSuccess) throw new Error("restore failed");
+
+    expect(restored.data.data["secretNote"]).toBe("restore-plaintext-note");
+    expect(restored.data.previous?.["secretNote"]).toBe("restore-plaintext-note");
+  });
 });
 
 describe("event-store-executor — entity cache read-through", () => {
@@ -418,3 +505,53 @@ describe("event-store-executor — entity cache read-through", () => {
     expect(second?.["email"]).toBe("from-cache@test.de");
   });
 });
+
+describe("event-store-executor — entity cache + encrypted fields", () => {
+  // Regression: detail() cached the already-decrypted row verbatim, so an
+  // `encrypted` field's plaintext ended up in a second at-rest store (Redis)
+  // the field-encryption feature doesn't cover.
+  const store = new Map<string, Record<string, unknown>>();
+  const entityCache: EntityCache = {
+    get: async (tenantId, name, id) => store.get(`${tenantId}:${name}:${id}`) ?? null,
+    mget: async () => new Map(),
+    set: async (tenantId, name, id, data) => {
+      store.set(`${tenantId}:${name}:${id}`, data);
+    },
+    mset: async (tenantId, name, entries) => {
+      for (const { id, data } of entries) store.set(`${tenantId}:${name}:${id}`, data);
+    },
+    del: async (tenantId, name, id) => {
+      store.delete(`${tenantId}:${name}:${id}`);
+    },
+  };
+  const encryption = createEncryptionProvider(ENCRYPTION_TEST_KEY);
+  const cachedEncryptedCrud = createEventStoreExecutor(encryptedTable, encryptedEntity, {
+    entityName: "esExecEncrypted",
+    entityCache,
+    encryption,
+  });
+
+  beforeEach(() => store.clear());
+
+  test("cached row is ciphertext at rest; detail() still returns plaintext to the caller", async () => {
+    const created = await cachedEncryptedCrud.create(
+      { email: "cache-enc@test.de", secretNote: "cache-plaintext-note" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+    const id = created.data.id;
+    const storeKey = `${adminUser.tenantId}:esExecEncrypted:${id}`;
+
+    const first = await cachedEncryptedCrud.detail({ id }, adminUser, tdb);
+    expect(first?.["secretNote"]).toBe("cache-plaintext-note");
+
+    const cachedRaw = store.get(storeKey);
+    expect(cachedRaw?.["secretNote"]).toBeDefined();
+    expect(cachedRaw?.["secretNote"]).not.toBe("cache-plaintext-note");
+
+    // Second read (cache hit) must still decrypt back to the real plaintext.
+    const second = await cachedEncryptedCrud.detail({ id }, adminUser, tdb);
+    expect(second?.["secretNote"]).toBe("cache-plaintext-note");
+  });
+});

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

@@ -190,10 +190,11 @@ describe("implicit-projection / Live==Rebuild equivalence", () => {
     const projection = registry.getAllProjections().get("implicittest:projection:user-entity");
     expect(projection).toBeDefined();
     if (!projection) return;
-    // 4 Auto-Verben weil softDelete=true → restored kommt dazu
+    // Auto-Verben: created/updated/deleted/forgotten immer, restored nur bei softDelete=true
     expect(Object.keys(projection.apply).sort()).toEqual([
       "user.created",
       "user.deleted",
+      "user.forgotten",
       "user.restored",
       "user.updated",
     ]);
@@ -215,6 +216,7 @@ describe("implicit-projection / Live==Rebuild equivalence", () => {
     expect(Object.keys(projection.apply).sort()).toEqual([
       "widget.created",
       "widget.deleted",
+      "widget.forgotten",
       "widget.updated",
     ]);
   });

package/src/db/__tests__/multi-row-insert.integration.test.ts

@@ -8,7 +8,8 @@
 // cause.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { insertOne, selectMany } from "../../db/query";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField } from "../../engine";
 import { setupTestStack, type TestStack, unsafeCreateEntityTable } from "../../stack";
@@ -51,7 +52,7 @@ describe("instant() customType is forgiving with ISO strings", () => {
     // would call .toString() on a string and produce a malformed driver
     // value that PG rejects.
     const isoString = "2026-01-15T12:00:00Z";
-    await insertOne(stack.db, tsTable, {
+    await seedRow(stack.db, tsTable, {
       name: "x",
       tenantId: "00000000-0000-4000-8000-000000000001",
       insertedAt: isoString as unknown as Temporal.Instant,
@@ -64,12 +65,12 @@ describe("instant() customType is forgiving with ISO strings", () => {
 
 describe("multi-row INSERT", () => {
   test("two rows with no id supplied → both rows persist (PG gen_random_uuid per row)", async () => {
-    await insertOne(stack.db, linkTable, {
+    await seedRow(stack.db, linkTable, {
       leftId: "L1",
       rightId: "R1",
       tenantId: "00000000-0000-4000-8000-000000000001",
     });
-    await insertOne(stack.db, linkTable, {
+    await seedRow(stack.db, linkTable, {
       leftId: "L2",
       rightId: "R2",
       tenantId: "00000000-0000-4000-8000-000000000001",

package/src/db/__tests__/schema-migration.integration.test.ts

@@ -1,6 +1,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
-import { asRawClient, insertOne, selectMany } from "../../db/query";
+import { asRawClient, selectMany } from "../../db/query";
 import {
   createBooleanField,
   createDateField,
@@ -172,7 +173,7 @@ describe("schema migration workflows", () => {
     await unsafePushTables(testDb.db, { project: initialTable });
 
     // Insert a row first (to prove ADD COLUMN with default doesn't break existing rows)
-    await insertOne(testDb.db, initialTable, {
+    await seedRow(testDb.db, initialTable, {
       tenantId: "00000000-0000-4000-8000-000000000001",
       name: "Test Project",
     });
@@ -205,7 +206,7 @@ describe("schema migration workflows", () => {
     const initialTable = buildEntityTable("user", initialEntity);
     await unsafePushTables(testDb.db, { user: initialTable });
 
-    await insertOne(testDb.db, initialTable, {
+    await seedRow(testDb.db, initialTable, {
       tenantId: "00000000-0000-4000-8000-000000000001",
       email: "x@y.z",
     });

package/src/db/__tests__/source-shadow-create.integration.test.ts

@@ -12,7 +12,8 @@
 // integration proof the unit test cannot give.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { insertOne, selectMany } from "../../db/query";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField } from "../../engine";
 import { setupTestStack, type TestStack, unsafeCreateEntityTable } from "../../stack";
@@ -40,7 +41,7 @@ describe("entity with a `source` field — create-path is shadow-proof", () => {
     // Passing a real Temporal.Instant exercises the timestamptz serializer
     // path that the shadow used to bypass. Pre-fix this threw "Cannot use
     // valueOf"; post-fix the row persists and round-trips as a Temporal.Instant.
-    await insertOne(stack.db, sourceTable, {
+    await seedRow(stack.db, sourceTable, {
       source: "import",
       tenantId: "00000000-0000-4000-8000-000000000001",
       insertedAt: Temporal.Instant.from("2026-01-15T12:00:00Z"),

package/src/db/__tests__/tenant-db-where-merge.integration.test.ts

@@ -5,8 +5,9 @@
 // bleibt als Schnell-Pin bestehen).
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { updateRows } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
-import { selectMany, updateMany } from "../../bun-db";
+import { selectMany } from "../../bun-db";
 import {
   createEntity,
   createTextField,
@@ -53,7 +54,7 @@ const probeFeature = defineFeature("where-merge-probe", (r) => {
     schema: z.object({ tenantId: z.string(), title: z.string() }),
     access: { roles: ["User"] },
     handler: async (event, ctx) => {
-      const count = await updateMany(
+      const count = await updateRows(
         ctx.db,
         noteTable,
         { tenantId: event.payload.tenantId },

package/src/db/__tests__/tenant-db.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { asRawClient, insertOne, selectMany } from "../../db/query";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { asRawClient, selectMany } from "../../db/query";
 import { createBooleanField, createEntity, createTextField } from "../../engine";
 import {
   createTestDb,
@@ -197,7 +198,7 @@ describe("scoped mode (default)", () => {
   describe("reference data (tenantId = 0)", () => {
     test("scoped select includes rows with tenantId = 0", async () => {
       // Seed reference data with tenantId = 0 (like seedReferenceData does)
-      await insertOne(testDb.db, table, {
+      await seedRow(testDb.db, table, {
         name: "GlobalRef",
         status: "ref",
         tenantId: "00000000-0000-4000-8000-000000000000",
@@ -217,7 +218,7 @@ describe("scoped mode (default)", () => {
     });
 
     test("scoped update does NOT affect tenantId = 0 rows", async () => {
-      await insertOne(testDb.db, table, {
+      await seedRow(testDb.db, table, {
         name: "RefNoUpdate",
         status: "ref",
         tenantId: "00000000-0000-4000-8000-000000000000",
@@ -238,7 +239,7 @@ describe("scoped mode (default)", () => {
     });
 
     test("scoped delete does NOT affect tenantId = 0 rows", async () => {
-      await insertOne(testDb.db, table, {
+      await seedRow(testDb.db, table, {
         name: "RefNoDelete",
         status: "ref",
         tenantId: "00000000-0000-4000-8000-000000000000",
@@ -350,8 +351,8 @@ describe("system mode (r.systemScope())", () => {
 describe("tables without tenantId column", () => {
   test("select returns all rows (no tenant filter)", async () => {
     // Insert two rows via raw db
-    await insertOne(testDb.db, systemTable, { label: "System-A" });
-    await insertOne(testDb.db, systemTable, { label: "System-B" });
+    await seedRow(testDb.db, systemTable, { label: "System-A" });
+    await seedRow(testDb.db, systemTable, { label: "System-B" });
 
     const tdb = createTenantDb(testDb.db, tenant1.tenantId);
     const rows = await tdb.selectMany(systemTable);

package/src/db/apply-entity-event.ts

@@ -33,12 +33,14 @@
 //   <entity>.updated   → UPDATE WHERE id=aggregateId
 //   <entity>.deleted   → soft-delete-UPDATE wenn entity.softDelete, sonst hard-DELETE
 //   <entity>.restored  → undelete-UPDATE (nur bei softDelete sinnvoll)
+//   <entity>.forgotten → hard-DELETE immer (Art.17-Purge, auch bei softDelete);
+//                        via executor.forget(). Rebuild replayt created→forgotten
+//                        → Row weg, rebuild-safe (was ein direktes deleteMany nicht ist).
 //
 // Domain-Events (r.defineEvent) auf demselben Aggregate werden hier NICHT
 // behandelt — die liefen im Live-Pfad nie durch den Executor und müssen
 // von expliziten r.projection-apply-Handlern oder r.multiStreamProjection
-// behandelt werden. ImplicitProjection registriert daher nur die 4
-// Auto-Verben.
+// behandelt werden. ImplicitProjection registriert die Auto-Verben.
 //
 // Return-Shape: ApplyResult mit `kind` + optionaler `row`.
 //   - "applied" → Schreibung lief durch. `row` enthält die geschriebene
@@ -57,22 +59,22 @@ import type { TableColumns } from "./dialect";
 // biome-ignore lint/suspicious/noExplicitAny: Drizzle-Tabellen sind generisch typed; framework code erasiert die Spalten-Union absichtlich.
 type Table = TableColumns<any>;
 
-export type AutoVerb = "created" | "updated" | "deleted" | "restored";
+export type AutoVerb = "created" | "updated" | "deleted" | "restored" | "forgotten";
+
+const AUTO_VERBS: readonly AutoVerb[] = ["created", "updated", "deleted", "restored", "forgotten"];
 
 export type ApplyResult =
   | { readonly kind: "applied"; readonly verb: AutoVerb; readonly row: DbRow | null }
   | { readonly kind: "skipped" };
 
-/** Parsed event.type → AutoVerb wenn das Event eines der 4 Auto-Verben
+/** Parsed event.type → AutoVerb wenn das Event eines der Auto-Verben
  *  auf dem gegebenen Aggregate ist. null sonst (Domain-Event). */
 export function parseAutoVerb(event: StoredEvent): AutoVerb | null {
   const prefix = `${event.aggregateType}.`;
   if (!event.type.startsWith(prefix)) return null;
   const verb = event.type.slice(prefix.length);
-  if (verb === "created" || verb === "updated" || verb === "deleted" || verb === "restored") {
-    return verb;
-  }
-  return null;
+  // @cast-boundary: verb is validated against the AutoVerb list before the cast.
+  return (AUTO_VERBS as readonly string[]).includes(verb) ? (verb as AutoVerb) : null;
 }
 
 /** Idempotente Anwendung eines Auto-Events auf die Entity-Tabelle.
@@ -193,5 +195,14 @@ export async function applyEntityEvent(
       );
       return { kind: "applied", verb, row: rows[0] ?? null };
     }
+
+    case "forgotten": {
+      // Hard-delete regardless of softDelete: forget/purge (Art. 17) removes the
+      // row entirely. On rebuild the aggregate replays created → forgotten, so
+      // the row ends up gone — the rebuild-safe erasure the soft-delete verb
+      // (which only flips isDeleted) cannot provide.
+      await deleteMany(tx, table, { id: event.aggregateId });
+      return { kind: "applied", verb, row: null };
+    }
   }
 }