@cosmicdrift/kumiko-framework 0.1.0

package/src/db/__tests__/located-timestamp.test.ts

@@ -0,0 +1,184 @@
+// Pure Unit-Tests für die flatten/rehydrate Helpers — Auto-Convert für
+// locatedTimestamp-Felder. Keine DB, kein Stack, nur Daten-Transform.
+
+import { describe, expect, test } from "vitest";
+import { createEntity, createLocatedTimestampField, createTextField } from "../../engine";
+import type { EntityDefinition } from "../../engine/types";
+import { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "../located-timestamp";
+
+const orderEntity: EntityDefinition = createEntity({
+  fields: {
+    clientName: createTextField(),
+    pickup: createLocatedTimestampField(),
+    delivery: createLocatedTimestampField(),
+  },
+});
+
+// Sprint F: flattenLocatedTimestamp returnt jetzt Temporal.Instant für die
+// <name>Utc-Spalte (statt ISO-String). Tests vergleichen via .toString()
+// damit der Wert deterministisch lesbar bleibt — der canonical ISO-Output
+// von Temporal.Instant ist stabil.
+const utcStr = (v: unknown): string => (v as Temporal.Instant).toString();
+
+describe("flattenLocatedTimestamp — Insert/Update Convert", () => {
+  test("{ at, tz } → { <name>Utc, <name>Tz } (utc berechnet via Temporal)", () => {
+    const flat = flattenLocatedTimestamp(
+      { pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } },
+      orderEntity,
+    );
+    // Lisbon WEST im April = UTC+1, also 10:00 Lisbon = 09:00 UTC.
+    expect(utcStr(flat["pickupUtc"])).toBe("2026-04-15T09:00:00Z");
+    expect(flat["pickupTz"]).toBe("Europe/Lisbon");
+  });
+
+  test("{ utc, tz } → wird direkt gespeichert (utc gewinnt)", () => {
+    const flat = flattenLocatedTimestamp(
+      { pickup: { utc: "2026-04-15T09:00:00Z", tz: "Europe/Lisbon" } },
+      orderEntity,
+    );
+    expect(utcStr(flat["pickupUtc"])).toBe("2026-04-15T09:00:00Z");
+    expect(flat["pickupTz"]).toBe("Europe/Lisbon");
+  });
+
+  test("{ at, tz, utc } — utc gewinnt deterministisch", () => {
+    const flat = flattenLocatedTimestamp(
+      {
+        pickup: {
+          at: "2026-04-15T10:00:00",
+          tz: "Europe/Lisbon",
+          utc: "2026-04-15T07:00:00Z", // bewusst inkonsistent
+        },
+      },
+      orderEntity,
+    );
+    // utc gewinnt — wir speichern was der Caller explizit angegeben hat.
+    expect(utcStr(flat["pickupUtc"])).toBe("2026-04-15T07:00:00Z");
+  });
+
+  test("Mehrere locatedTimestamp-Felder am gleichen Object", () => {
+    const flat = flattenLocatedTimestamp(
+      {
+        pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" },
+        delivery: { at: "2026-04-16T18:00:00", tz: "Asia/Tokyo" },
+      },
+      orderEntity,
+    );
+    expect(utcStr(flat["pickupUtc"])).toBe("2026-04-15T09:00:00Z");
+    expect(flat["pickupTz"]).toBe("Europe/Lisbon");
+    // 18:00 Tokyo = 09:00 UTC
+    expect(utcStr(flat["deliveryUtc"])).toBe("2026-04-16T09:00:00Z");
+    expect(flat["deliveryTz"]).toBe("Asia/Tokyo");
+  });
+
+  test("andere Felder bleiben unverändert (clientName)", () => {
+    const flat = flattenLocatedTimestamp(
+      {
+        clientName: "Acme",
+        pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Berlin" },
+      },
+      orderEntity,
+    );
+    expect(flat["clientName"]).toBe("Acme");
+  });
+
+  test("fehlende Felder werden ignoriert (kein crash)", () => {
+    const flat = flattenLocatedTimestamp({ clientName: "X" }, orderEntity);
+    expect(flat).toEqual({ clientName: "X" });
+  });
+
+  test("DST-Übergang Berlin Spring-Forward 2026-03-29 — Konvertierung korrekt", () => {
+    // 04:30 Berlin am 29.03.2026 (nach DST-Sprung) = 02:30 UTC (CEST UTC+2)
+    const flat = flattenLocatedTimestamp(
+      { pickup: { at: "2026-03-29T04:30:00", tz: "Europe/Berlin" } },
+      orderEntity,
+    );
+    expect(utcStr(flat["pickupUtc"])).toBe("2026-03-29T02:30:00Z");
+  });
+
+  test("ist pure — input wird nicht mutiert", () => {
+    const input = { pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } };
+    const before = JSON.stringify(input);
+    flattenLocatedTimestamp(input, orderEntity);
+    expect(JSON.stringify(input)).toBe(before);
+  });
+});
+
+describe("rehydrateLocatedTimestamp — Read Convert", () => {
+  test("{ <name>Utc, <name>Tz } DB-Form → { at, tz, utc } API-Form (Pickup-Ort-lokal)", () => {
+    const out = rehydrateLocatedTimestamp(
+      { pickupUtc: "2026-04-15T09:00:00Z", pickupTz: "Europe/Lisbon" },
+      orderEntity,
+    );
+    // 09:00 UTC in Lissabon (WEST UTC+1 im April) = 10:00 lokal.
+    expect(out).toEqual({
+      pickup: {
+        at: "2026-04-15T10:00:00",
+        tz: "Europe/Lisbon",
+        utc: "2026-04-15T09:00:00Z",
+      },
+    });
+  });
+
+  test("PG-Wire-Format mit Space wird normalisiert (PG-mode:'string')", () => {
+    // Drizzle's mode:"string" liefert TIMESTAMPTZ als "2026-04-15 09:00:00+00".
+    const out = rehydrateLocatedTimestamp(
+      { pickupUtc: "2026-04-15 09:00:00+00", pickupTz: "Europe/Lisbon" },
+      orderEntity,
+    );
+    expect((out["pickup"] as { utc: string }).utc).toBe("2026-04-15T09:00:00Z");
+    expect((out["pickup"] as { at: string }).at).toBe("2026-04-15T10:00:00");
+  });
+
+  test("Round-Trip: flatten dann rehydrate ergibt original-equivalent", () => {
+    const original = { pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } };
+    const flat = flattenLocatedTimestamp(original, orderEntity);
+    const rehydrated = rehydrateLocatedTimestamp(flat, orderEntity);
+
+    const pickup = rehydrated["pickup"] as { at: string; tz: string; utc: string };
+    expect(pickup.at).toBe("2026-04-15T10:00:00");
+    expect(pickup.tz).toBe("Europe/Lisbon");
+    // utc wird IM Read zusätzlich befüllt — original hatte ihn nicht
+    expect(pickup.utc).toBe("2026-04-15T09:00:00Z");
+  });
+
+  test("Mehrere Felder: Pickup Lissabon + Delivery Tokyo gleichzeitig", () => {
+    const out = rehydrateLocatedTimestamp(
+      {
+        pickupUtc: "2026-04-15T09:00:00Z",
+        pickupTz: "Europe/Lisbon",
+        deliveryUtc: "2026-04-16T09:00:00Z",
+        deliveryTz: "Asia/Tokyo",
+      },
+      orderEntity,
+    );
+    expect((out["pickup"] as { tz: string }).tz).toBe("Europe/Lisbon");
+    expect((out["delivery"] as { tz: string }).tz).toBe("Asia/Tokyo");
+    // Tokyo: 09:00 UTC = 18:00 lokal (JST UTC+9)
+    expect((out["delivery"] as { at: string }).at).toBe("2026-04-16T18:00:00");
+  });
+
+  test("Tag-Wechsel: 23:30 Berlin → 21:30 UTC; Read in Tokyo gibt anderen Tag", () => {
+    // Beweis dass der Default `at` = Pickup-Ort-lokal IST. Hier speichern
+    // wir einen UTC-Instant mit Lissabon als gespeicherte tz, und prüfen
+    // dass der Read den Lissabon-Wall-Clock-Tag liefert (nicht z.B. Tokyo).
+    const out = rehydrateLocatedTimestamp(
+      { pickupUtc: "2026-04-15T22:30:00Z", pickupTz: "Europe/Lisbon" },
+      orderEntity,
+    );
+    // In Lissabon (WEST UTC+1) ist 22:30 UTC am 15.04 = 23:30 am 15.04 lokal
+    expect((out["pickup"] as { at: string }).at).toBe("2026-04-15T23:30:00");
+
+    // Wenn jemand User-Sicht "in Tokyo" wollte: muss er aus utc selbst ableiten.
+    // Dieser Test demonstriert nur die Server-Default-Sicht (Pickup-Ort-lokal).
+  });
+
+  test("fehlende Felder werden übersprungen (kein crash)", () => {
+    const out = rehydrateLocatedTimestamp({ clientName: "X" }, orderEntity);
+    expect(out).toEqual({ clientName: "X" });
+  });
+
+  test("partial: nur Tz ohne Utc → Pair wird nicht erzeugt (Daten korrupt, kein silent fix)", () => {
+    const out = rehydrateLocatedTimestamp({ pickupTz: "Europe/Lisbon" }, orderEntity);
+    expect(out["pickup"]).toBeUndefined();
+  });
+});

package/src/db/__tests__/money.test.ts

@@ -0,0 +1,199 @@
+// Pure Unit-Tests für money flatten/rehydrate Helpers.
+
+import { describe, expect, test } from "vitest";
+import { createEntity, createMoneyField, createTextField } from "../../engine";
+import type { EntityDefinition } from "../../engine/types";
+import { flattenMoney, rehydrateMoney } from "../money";
+
+const orderEntity: EntityDefinition = createEntity({
+  defaultCurrency: "EUR",
+  fields: {
+    label: createTextField(),
+    buyingPrice: createMoneyField(),
+    sellingPrice: createMoneyField(),
+  },
+});
+
+const usdEntity: EntityDefinition = createEntity({
+  defaultCurrency: "USD",
+  fields: {
+    fee: createMoneyField(),
+  },
+});
+
+describe("flattenMoney — Insert/Update Convert", () => {
+  test("{ amount, currency } → { <name>: amount, <name>Currency: currency }", () => {
+    const flat = flattenMoney({ buyingPrice: { amount: 45000, currency: "EUR" } }, orderEntity);
+    expect(flat).toEqual({ buyingPrice: 45000, buyingPriceCurrency: "EUR" });
+  });
+
+  test("primitive number (legacy) wird akzeptiert + entity.defaultCurrency angehängt", () => {
+    const flat = flattenMoney({ buyingPrice: 45000 }, orderEntity);
+    expect(flat).toEqual({ buyingPrice: 45000, buyingPriceCurrency: "EUR" });
+  });
+
+  test("primitive number nutzt USD wenn entity.defaultCurrency = USD", () => {
+    const flat = flattenMoney({ fee: 199 }, usdEntity);
+    expect(flat).toEqual({ fee: 199, feeCurrency: "USD" });
+  });
+
+  test("expliziter <name>Currency im Payload überschreibt nicht", () => {
+    const flat = flattenMoney({ buyingPrice: 45000, buyingPriceCurrency: "USD" }, orderEntity);
+    // Wenn bereits gesetzt, nicht überschreiben — caller-explicit gewinnt
+    expect(flat["buyingPriceCurrency"]).toBe("USD");
+  });
+
+  test("mehrere money-Felder am gleichen Object", () => {
+    const flat = flattenMoney(
+      {
+        buyingPrice: { amount: 45000, currency: "EUR" },
+        sellingPrice: { amount: 60000, currency: "USD" },
+      },
+      orderEntity,
+    );
+    expect(flat).toEqual({
+      buyingPrice: 45000,
+      buyingPriceCurrency: "EUR",
+      sellingPrice: 60000,
+      sellingPriceCurrency: "USD",
+    });
+  });
+
+  test("andere Felder bleiben unverändert", () => {
+    const flat = flattenMoney(
+      { label: "Premium", buyingPrice: { amount: 100, currency: "EUR" } },
+      orderEntity,
+    );
+    expect(flat["label"]).toBe("Premium");
+  });
+
+  test("null/undefined money-Field wird ignoriert (kein crash)", () => {
+    const flat = flattenMoney({ buyingPrice: undefined, sellingPrice: null }, orderEntity);
+    expect(flat["buyingPrice"]).toBeUndefined();
+    expect(flat["sellingPrice"]).toBeNull();
+  });
+
+  test("Framework-Default 'EUR' wenn entity.defaultCurrency nicht gesetzt", () => {
+    const noCurrencyEntity: EntityDefinition = createEntity({
+      fields: { fee: createMoneyField() },
+    });
+    const flat = flattenMoney({ fee: 50 }, noCurrencyEntity);
+    expect(flat["feeCurrency"]).toBe("EUR");
+  });
+
+  test("ist pure — input wird nicht mutiert", () => {
+    const input = { buyingPrice: { amount: 45000, currency: "EUR" } };
+    const before = JSON.stringify(input);
+    flattenMoney(input, orderEntity);
+    expect(JSON.stringify(input)).toBe(before);
+  });
+});
+
+describe("rehydrateMoney — Read Convert", () => {
+  test("{ <name>: number, <name>Currency: string } → { <name>: { amount, currency } }", () => {
+    const out = rehydrateMoney({ buyingPrice: 45000, buyingPriceCurrency: "EUR" }, orderEntity);
+    expect(out).toEqual({ buyingPrice: { amount: 45000, currency: "EUR" } });
+  });
+
+  test("PG-BIGINT als String wird zu number gecastet", () => {
+    // Postgres-driver liefert BIGINT manchmal als String (>2^53 sicher).
+    const out = rehydrateMoney({ buyingPrice: "45000", buyingPriceCurrency: "EUR" }, orderEntity);
+    expect(out["buyingPrice"]).toEqual({ amount: 45000, currency: "EUR" });
+  });
+
+  test("fehlende Currency-Spalte fällt auf entity.defaultCurrency", () => {
+    const out = rehydrateMoney({ buyingPrice: 45000 }, orderEntity);
+    expect(out["buyingPrice"]).toEqual({ amount: 45000, currency: "EUR" });
+  });
+
+  test("null/undefined amount → Field wird aus Output entfernt", () => {
+    const out = rehydrateMoney({ buyingPrice: null, buyingPriceCurrency: "EUR" }, orderEntity);
+    expect(out["buyingPrice"]).toBeUndefined();
+  });
+
+  test("Mehrere money-Felder am gleichen Object", () => {
+    const out = rehydrateMoney(
+      {
+        buyingPrice: 45000,
+        buyingPriceCurrency: "EUR",
+        sellingPrice: 60000,
+        sellingPriceCurrency: "USD",
+      },
+      orderEntity,
+    );
+    expect(out).toEqual({
+      buyingPrice: { amount: 45000, currency: "EUR" },
+      sellingPrice: { amount: 60000, currency: "USD" },
+    });
+  });
+
+  test("Round-Trip: flatten dann rehydrate ergibt dasselbe", () => {
+    const original = {
+      buyingPrice: { amount: 45000, currency: "EUR" },
+      sellingPrice: { amount: 60000, currency: "USD" },
+    };
+    const flat = flattenMoney(original, orderEntity);
+    const rehydrated = rehydrateMoney(flat, orderEntity);
+    expect(rehydrated).toEqual(original);
+  });
+
+  test("Round-Trip primitive-Insert: flatten(45000) → rehydrate → { amount:45000, currency:EUR }", () => {
+    const flat = flattenMoney({ buyingPrice: 45000 }, orderEntity);
+    const out = rehydrateMoney(flat, orderEntity);
+    expect(out["buyingPrice"]).toEqual({ amount: 45000, currency: "EUR" });
+  });
+
+  test("ist pure — input wird nicht mutiert", () => {
+    const input = { buyingPrice: 45000, buyingPriceCurrency: "EUR" };
+    const before = JSON.stringify(input);
+    rehydrateMoney(input, orderEntity);
+    expect(JSON.stringify(input)).toBe(before);
+  });
+
+  test("korrupte string-amount (kein number) → loud throw, kein silent drop", () => {
+    expect(() =>
+      rehydrateMoney({ buyingPrice: "not-a-number", buyingPriceCurrency: "EUR" }, orderEntity),
+    ).toThrow(/not a number — DB corruption/);
+  });
+
+  test("unerwarteter amount-Typ (boolean) → loud throw", () => {
+    expect(() =>
+      rehydrateMoney({ buyingPrice: true, buyingPriceCurrency: "EUR" }, orderEntity),
+    ).toThrow(/unexpected type/);
+  });
+});
+
+describe("Round-Trip im Update-Pfad (Helper-Verkettung wie im Executor)", () => {
+  test("Update-Changes-Payload mit money geht durch flatten + zurück durch rehydrate", () => {
+    // Simuliert was der Executor macht: changes → flatten → DB → rehydrate
+    const changes = { buyingPrice: { amount: 99_000, currency: "USD" } };
+    const flat = flattenMoney(changes, orderEntity);
+    expect(flat).toEqual({ buyingPrice: 99_000, buyingPriceCurrency: "USD" });
+
+    // DB liefert dieselben Spalten zurück
+    const out = rehydrateMoney(flat, orderEntity);
+    expect(out).toEqual({ buyingPrice: { amount: 99_000, currency: "USD" } });
+  });
+
+  test("List-Pfad: mehrere Rows hintereinander rehydraten", () => {
+    const dbRows = [
+      { buyingPrice: 100, buyingPriceCurrency: "EUR" },
+      { buyingPrice: 200, buyingPriceCurrency: "USD" },
+      { buyingPrice: 300, buyingPriceCurrency: "GBP" },
+    ];
+    const apiRows = dbRows.map((r) => rehydrateMoney(r, orderEntity));
+    expect(apiRows).toEqual([
+      { buyingPrice: { amount: 100, currency: "EUR" } },
+      { buyingPrice: { amount: 200, currency: "USD" } },
+      { buyingPrice: { amount: 300, currency: "GBP" } },
+    ]);
+  });
+});
+
+describe("flattenMoney — Strict-Mode Throw", () => {
+  test("string als Wert (statt number/object) → loud throw", () => {
+    expect(() => flattenMoney({ buyingPrice: "100" }, orderEntity)).toThrow(
+      /expects \{ amount, currency \} object or number/,
+    );
+  });
+});

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

@@ -0,0 +1,76 @@
+// Sanity test for the multi-row INSERT id-default behaviour.
+//
+// While building the publicstatus showcase, a multi-row INSERT into a
+// join-table appeared to drop one row silently. The fix in the showcase
+// was a per-row INSERT. This test pins down the actual behaviour at the
+// framework layer so we know whether buildBaseColumns / Drizzle / PG
+// have a real footgun, or whether the showcase bug had a different root
+// cause.
+
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { buildDrizzleTable } from "../../db/table-builder";
+import { createEntity, createTextField } from "../../engine";
+import { createEntityTable, setupTestStack, type TestStack } from "../../stack";
+
+const linkEntity = createEntity({
+  table: "mri_links",
+  fields: {
+    leftId: createTextField({ required: true }),
+    rightId: createTextField({ required: true }),
+  },
+});
+const linkTable = buildDrizzleTable("link", linkEntity);
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [] });
+  await createEntityTable(stack.db, linkEntity);
+});
+
+afterAll(async () => stack?.cleanup());
+
+describe("instant() customType is forgiving with ISO strings", () => {
+  // While building publicstatus we hit a footgun: Zod insert-schemas
+  // validate timestamp fields as z.iso.datetime() (string), but the
+  // instant() customType used to require Temporal.Instant on toDriver
+  // and crashed obscurely otherwise. Coercion at the customType boundary
+  // makes ISO-strings work without ceremony.
+
+  const tsEntity = createEntity({
+    table: "mri_ts",
+    fields: { name: createTextField({ required: true }) },
+  });
+  const tsTable = buildDrizzleTable("ts-row", tsEntity);
+
+  test("INSERT accepts an ISO string for an instant column (forgiving path)", async () => {
+    await createEntityTable(stack.db, tsEntity, "ts-row");
+    // insertedAt is base-column, type instant. Pass an ISO string —
+    // coercion in toDriver handles it. Without the fix, Drizzle-driver
+    // would call .toString() on a string and produce a malformed driver
+    // value that PG rejects.
+    const isoString = "2026-01-15T12:00:00Z";
+    await stack.db.insert(tsTable).values({
+      name: "x",
+      tenantId: "00000000-0000-4000-8000-000000000001",
+      insertedAt: isoString as unknown as Temporal.Instant,
+    });
+    const rows = await stack.db.select().from(tsTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["insertedAt"]).toBeInstanceOf(Temporal.Instant);
+  });
+});
+
+describe("multi-row INSERT", () => {
+  test("two rows with no id supplied → both rows persist (PG gen_random_uuid per row)", async () => {
+    await stack.db.insert(linkTable).values([
+      { leftId: "L1", rightId: "R1", tenantId: "00000000-0000-4000-8000-000000000001" },
+      { leftId: "L2", rightId: "R2", tenantId: "00000000-0000-4000-8000-000000000001" },
+    ]);
+    const rows = await stack.db.select().from(linkTable);
+    expect(rows).toHaveLength(2);
+    // Each row got its own id from the PG default.
+    const ids = new Set(rows.map((r) => r["id"] as string));
+    expect(ids.size).toBe(2);
+  });
+});

package/src/db/__tests__/parse-auto-verb.test.ts

@@ -0,0 +1,70 @@
+// Unit-Tests für parseAutoVerb — die Mapping-Logik die entscheidet
+// ob ein Event ein Auto-Verb auf seinem Aggregate ist (created/
+// updated/deleted/restored) oder ein Domain-Event. Production-Behavior:
+// die ImplicitProjection registriert Apply-Handler nur für die 4 Auto-
+// Verben; Domain-Events laufen durch explicit r.projection oder MSP.
+//
+// Wenn parseAutoVerb für ein Domain-Event versehentlich einen Verb
+// returnt, würde die ImplicitProjection den falschen Handler firen.
+
+import { describe, expect, test } from "vitest";
+import type { StoredEvent } from "../../event-store";
+import { parseAutoVerb } from "../apply-entity-event";
+
+function event(overrides: Partial<StoredEvent>): StoredEvent {
+  return {
+    id: "evt-1",
+    aggregateId: "agg-1",
+    aggregateType: "user",
+    tenantId: "tenant-1" as never,
+    version: 1,
+    type: "user.created",
+    eventVersion: 1,
+    payload: {},
+    metadata: { userId: "u-1" },
+    createdAt: { toString: () => "2026-04-27T00:00:00Z" } as never,
+    createdBy: "u-1",
+    ...overrides,
+  };
+}
+
+describe("parseAutoVerb", () => {
+  test.each([
+    ["user.created", "created"],
+    ["user.updated", "updated"],
+    ["user.deleted", "deleted"],
+    ["user.restored", "restored"],
+  ] as const)("'%s' → '%s'", (type, verb) => {
+    expect(parseAutoVerb(event({ type }))).toBe(verb);
+  });
+
+  test("domain-event auf demselben aggregate → null", () => {
+    expect(parseAutoVerb(event({ type: "user.password-changed" }))).toBeNull();
+  });
+
+  test("auto-verb-Suffix auf falschem aggregate → null", () => {
+    // type "tenant.created" auf einem user-Aggregate ist defensive ein
+    // Domain-Event aus Sicht der user-Implicit-Projection — nicht ihr
+    // eigener Auto-Verb.
+    expect(parseAutoVerb(event({ aggregateType: "user", type: "tenant.created" }))).toBeNull();
+  });
+
+  test("kebab-case Aggregate (incident-update.created)", () => {
+    expect(
+      parseAutoVerb(event({ aggregateType: "incident-update", type: "incident-update.created" })),
+    ).toBe("created");
+  });
+
+  test("custom verb → null", () => {
+    expect(parseAutoVerb(event({ type: "user.imported" }))).toBeNull();
+  });
+
+  test("type ohne dot-separator → null", () => {
+    expect(parseAutoVerb(event({ type: "userCreated" }))).toBeNull();
+  });
+
+  test("type mit verschachteltem prefix → null", () => {
+    // "user.profile.updated" hat zwei dots — kein clean Auto-Verb
+    expect(parseAutoVerb(event({ type: "user.profile.updated" }))).toBeNull();
+  });
+});

package/src/db/__tests__/required-not-null-migration-safety.integration.ts

@@ -0,0 +1,105 @@
+// Migration-Safety-Test: `ALTER TABLE … SET NOT NULL` schlägt fehl wenn
+// die Spalte vor der Migration NULL-Werte enthält.
+//
+// Hintergrund: Der A-Fix (required → notNull in fieldToColumns) erzeugt
+// für bestehende Apps eine drift-fix-Migration mit `SET NOT NULL` auf
+// jedem required-Feld. Das ist sicher gegen FRISCHE DBs (keine Daten
+// drin), aber gefährlich gegen Prod-DBs in denen historisch NULL-Werte
+// reingerutscht sein könnten — die Migration kracht beim apply mit:
+//
+//   ERROR: column "<name>" of relation "<table>" contains null values
+//   STATE: 23502 (not_null_violation)
+//
+// Dieser Test simuliert genau das. Schreibt eine Tabelle mit nullable
+// `key`, fügt eine Zeile mit NULL ein, versucht dann SET NOT NULL —
+// erwartet den Postgres-Error. Operations-Hinweis: vor dem deploy einer
+// solchen Migration eine Sanity-Query auf NULL-Counts in den betroffenen
+// Spalten laufen, oder DB drop'pen wenn der State Demo-State ist.
+
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createTestDb, type TestDb } from "../../stack";
+
+let testDb: TestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(sql`DROP TABLE IF EXISTS migration_safety_test`);
+});
+
+describe("ALTER TABLE SET NOT NULL — Daten-Sicherheits-Verhalten", () => {
+  test("SET NOT NULL kracht wenn die Spalte NULL-Zeilen enthält", async () => {
+    await testDb.db.execute(sql`
+      CREATE TABLE migration_safety_test (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        key text
+      )
+    `);
+    // NULL-Zeile einschleusen — simuliert prod state vor dem Drift-Fix.
+    await testDb.db.execute(sql`INSERT INTO migration_safety_test (key) VALUES (NULL)`);
+
+    let caught: unknown;
+    try {
+      await testDb.db.execute(sql`ALTER TABLE migration_safety_test ALTER COLUMN key SET NOT NULL`);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeDefined();
+    // Drizzle wrapped den PG-Error in einer DrizzleQueryError. Der echte
+    // not_null_violation steckt in `.cause` als postgres-js Error mit
+    // `.code === "23502"` und einem deutschsprachigen oder englischen
+    // `.message`. Wir prüfen pragmatisch beide Pfade.
+    const cause = (caught as { cause?: unknown }).cause;
+    const causeCode = (cause as { code?: string } | undefined)?.code;
+    expect(causeCode).toBe("23502");
+  });
+
+  test("SET NOT NULL läuft sauber durch wenn alle Zeilen Werte haben", async () => {
+    await testDb.db.execute(sql`
+      CREATE TABLE migration_safety_test (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        key text
+      )
+    `);
+    await testDb.db.execute(sql`INSERT INTO migration_safety_test (key) VALUES ('foo')`);
+    await testDb.db.execute(sql`INSERT INTO migration_safety_test (key) VALUES ('bar')`);
+
+    // Sollte ohne Throw durchlaufen.
+    await testDb.db.execute(sql`ALTER TABLE migration_safety_test ALTER COLUMN key SET NOT NULL`);
+
+    // Verifizieren: zukünftige NULL-Inserts werden jetzt blockiert.
+    let caught: unknown;
+    try {
+      await testDb.db.execute(sql`INSERT INTO migration_safety_test (key) VALUES (NULL)`);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeDefined();
+  });
+
+  test("SET NOT NULL auf leerer Tabelle ist trivial sicher", async () => {
+    // Frisch erstellt, keine Zeilen — der Fall in dem `migrate apply` nach
+    // einem DB-drop läuft. Dieser Pfad muss IMMER grün sein, sonst wäre
+    // jeder Greenfield-Deploy kaputt.
+    await testDb.db.execute(sql`
+      CREATE TABLE migration_safety_test (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        key text
+      )
+    `);
+    await testDb.db.execute(sql`ALTER TABLE migration_safety_test ALTER COLUMN key SET NOT NULL`);
+
+    // Beweis: information_schema zeigt die Spalte jetzt als NOT NULL.
+    const rows = await testDb.db.execute<{ is_nullable: string }>(
+      sql`SELECT is_nullable FROM information_schema.columns WHERE table_name = 'migration_safety_test' AND column_name = 'key'`,
+    );
+    expect(rows[0]?.is_nullable).toBe("NO");
+  });
+});