@cosmicdrift/kumiko-framework 0.92.0 → 0.93.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.92.0",
+  "version": "0.93.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.92.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.93.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/schema-builder.test.ts

@@ -8,6 +8,7 @@ import {
   createFilesField,
   createImageField,
   createImagesField,
+  createLocatedTimestampField,
   createMoneyField,
   createMultiSelectField,
   createNumberField,
@@ -339,6 +340,32 @@ describe("buildInsertSchema", () => {
     const schema = buildInsertSchema(entity);
     expect(schema.safeParse({}).success).toBe(false);
   });
+
+  test("tz field validates against the IANA zone list", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: { zone: { type: "tz", required: true } },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ zone: "Europe/Berlin" }).success).toBe(true);
+    expect(schema.safeParse({ zone: "UTC" }).success).toBe(true);
+    expect(schema.safeParse({ zone: "Mars/Phobos" }).success).toBe(false);
+    expect(schema.safeParse({ zone: "" }).success).toBe(false);
+  });
+
+  test("locatedTimestamp validates its tz against the IANA zone list", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: { pickup: createLocatedTimestampField({ required: true }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(
+      schema.safeParse({ pickup: { at: "2026-04-03T10:00:00", tz: "Europe/Lisbon" } }).success,
+    ).toBe(true);
+    expect(
+      schema.safeParse({ pickup: { at: "2026-04-03T10:00:00", tz: "Mars/Phobos" } }).success,
+    ).toBe(false);
+  });
 });
 
 // --- Update schema (all partial) ---

package/src/engine/schema-builder.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isValidIanaTimeZone } from "../time";
 import { assertUnreachable } from "../utils";
 import type { EmbeddedSubFieldDef, EntityDefinition, FieldDefinition } from "./types";
 import { DEFAULT_CURRENCIES } from "./types";
@@ -153,11 +154,10 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       return withDateBounds(schema, field.min, field.max);
     }
     case "tz": {
-      // IANA-Zonenname. Validierung gegen Intl.supportedValuesOf("timeZone")
-      // ist genau aber teuer (~600 Strings) — wir akzeptieren den freien
-      // String und prüfen via try/catch im Boot-Validator (kommt in
-      // späterer Iteration).
-      return z.string().min(1);
+      // IANA-Zonenname, validiert gegen die Runtime-Zonenliste
+      // (isValidIanaTimeZone). Ein ungültiger Name failt hier am
+      // Write-Boundary statt erst später in ctx.tz.parse / Temporal.
+      return z.string().refine(isValidIanaTimeZone, { message: "invalid IANA time zone" });
     }
     case "locatedTimestamp": {
       // Combined Wall-Clock+TZ Object. Beim Write akzeptieren wir entweder
@@ -167,7 +167,7 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       //
       // Hier nur die Schema-Garantie: mindestens tz + (at ODER utc).
       const at = z.iso.datetime({ local: true });
-      const tz = z.string().min(1);
+      const tz = z.string().refine(isValidIanaTimeZone, { message: "invalid IANA time zone" });
       const utc = z.iso.datetime();
       return z.union([
         z.object({ at, tz, utc: utc.optional() }),

package/src/time/__tests__/boot-tz-warning.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { warnIfNonUtcServerTimeZone } from "../boot-tz-warning";
+
+describe("warnIfNonUtcServerTimeZone", () => {
+  test("warnt nicht wenn die Prozess-TZ UTC ist", () => {
+    const messages: string[] = [];
+    const warned = warnIfNonUtcServerTimeZone("UTC", (m) => messages.push(m));
+    expect(warned).toBe(false);
+    expect(messages).toHaveLength(0);
+  });
+
+  test("warnt bei nicht-UTC Zone, nennt Zone + UTC-Hinweis", () => {
+    const messages: string[] = [];
+    const warned = warnIfNonUtcServerTimeZone("Europe/Berlin", (m) => messages.push(m));
+    expect(warned).toBe(true);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]).toContain("Europe/Berlin");
+    expect(messages[0]).toContain("UTC");
+  });
+
+  test("Default-Aufruf liest die Prozess-TZ ohne zu werfen", () => {
+    expect(() => warnIfNonUtcServerTimeZone(undefined, () => {})).not.toThrow();
+  });
+});

package/src/time/__tests__/iana.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { isValidIanaTimeZone } from "../iana";
+
+describe("isValidIanaTimeZone", () => {
+  // Die 5 Zonen der geplanten CI-TZ-Matrix (timezones.md) müssen alle gültig
+  // sein — sonst kann die Matrix sie nicht setzen.
+  test.each([
+    "UTC",
+    "Europe/Berlin",
+    "America/Los_Angeles",
+    "Asia/Tokyo",
+    "Pacific/Apia",
+  ])("akzeptiert kanonische Zone %s", (zone) => {
+    expect(isValidIanaTimeZone(zone)).toBe(true);
+  });
+
+  test.each([
+    "",
+    "Mars/Phobos",
+    "europe/berlin",
+    "Europe/Berlin ",
+    "GMT+2",
+    "not-a-zone",
+  ])("lehnt ungültigen / nicht-kanonischen String %p ab", (value) => {
+    expect(isValidIanaTimeZone(value)).toBe(false);
+  });
+
+  test("liefert über mehrere Aufrufe konsistent (lazy Set gecacht)", () => {
+    expect(isValidIanaTimeZone("Europe/Berlin")).toBe(true);
+    expect(isValidIanaTimeZone("Europe/Berlin")).toBe(true);
+    expect(isValidIanaTimeZone("Mars/Phobos")).toBe(false);
+  });
+});

package/src/time/__tests__/tz-dateline.test.ts

@@ -0,0 +1,36 @@
+// Pacific/Apia (Samoa) liegt weit östlich der Datumsgrenze bei UTC+13/+14 —
+// eine Vormittags-Wall-Clock dort fällt in UTC auf den VORHERIGEN Kalendertag.
+// Das Plan-Doc (timezones.md) nennt Apia explizit als Datumsgrenzen-Edge-Case
+// der TZ-Matrix. Als Datums-Ordnungs-Eigenschaft formuliert, damit der Test
+// unabhängig von der DST-Sicht der tzdata grün bleibt (UTC+13 wie +14 schieben
+// 10:00 auf den Vortag).
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import { ensureTemporalPolyfill } from "../polyfill";
+import { createTzContext } from "../tz-context";
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+});
+
+describe("ctx.tz — Pacific/Apia Datumsgrenze", () => {
+  test("Vormittags-Wall-Clock in Apia mappt auf den vorherigen UTC-Kalendertag", () => {
+    const tz = createTzContext();
+    const zdt = tz.parse("2026-01-15T10:00:00", "Pacific/Apia");
+    expect(zdt.timeZoneId).toBe("Pacific/Apia");
+
+    const utcDate = zdt.toInstant().toZonedDateTimeISO("UTC").toPlainDate().toString();
+    expect(utcDate).toBe("2026-01-14");
+
+    // Offset ist ein großer positiver Wert (UTC+13 oder +14).
+    expect(zdt.offsetNanoseconds).toBeGreaterThan(12 * 3600 * 1e9);
+  });
+
+  test("Round-Trip bewahrt Wall-Clock + Instant über die Datumsgrenze", () => {
+    const tz = createTzContext();
+    const original = tz.parse("2026-01-15T10:00:00", "Pacific/Apia");
+    const restored = tz.fromLocatedJson(tz.toLocatedJson(original));
+    expect(restored.toInstant().equals(original.toInstant())).toBe(true);
+    expect(restored.timeZoneId).toBe("Pacific/Apia");
+  });
+});

package/src/time/boot-tz-warning.ts

@@ -0,0 +1,26 @@
+// Boot-Warnung wenn die Prozess-Uhr nicht in UTC läuft. Der gesamte
+// Server-Code nimmt UTC an (System-TZ ist kein Konzept — siehe timezones.md);
+// eine abweichende Prozess-TZ lässt versehentliche new Date()-Pfade
+// lokal-abhängig brechen ("grün in UTC-CI, kaputt in Berlin-Prod"). Soft:
+// nicht-UTC ist in Dev legitim, daher Warnung statt Boot-Fehler.
+
+function resolvedServerTimeZone(): string {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+
+/**
+ * Warnt einmalig beim Server-Start, wenn die Prozess-TZ nicht UTC ist.
+ * Parameter sind für Tests injizierbar. Gibt zurück, ob gewarnt wurde.
+ */
+export function warnIfNonUtcServerTimeZone(
+  resolvedTimeZone: string = resolvedServerTimeZone(),
+  // biome-ignore lint/suspicious/noConsole: boot-time warning, no logger wired this early
+  warn: (message: string) => void = console.warn,
+): boolean {
+  if (resolvedTimeZone === "UTC") return false;
+  warn(
+    `[kumiko] Server time zone is "${resolvedTimeZone}" — the framework assumes UTC. ` +
+      "Set TZ=UTC for the server process to avoid time-zone-dependent bugs.",
+  );
+  return true;
+}

package/src/time/iana.ts

@@ -0,0 +1,17 @@
+// IANA-Zonenname-Validierung gegen die Runtime-eigene Zonenliste
+// (Intl.supportedValuesOf). Das Set wird lazy einmal gebaut — der Aufbau ist
+// der teure Teil (~400 kanonische Zonen), das Lookup danach O(1).
+
+let supportedZones: ReadonlySet<string> | undefined;
+
+function ianaZoneSet(): ReadonlySet<string> {
+  if (supportedZones === undefined) {
+    supportedZones = new Set(Intl.supportedValuesOf("timeZone"));
+  }
+  return supportedZones;
+}
+
+/** True wenn `value` ein gültiger kanonischer IANA-Zonenname ist (z.B. "Europe/Berlin", "UTC"). */
+export function isValidIanaTimeZone(value: string): boolean {
+  return ianaZoneSet().has(value);
+}

package/src/time/index.ts

@@ -5,12 +5,14 @@
 //   - getTemporal: type-safer Zugriff auf globalThis.Temporal
 //   - createTzContext: ctx.tz Factory mit now/today/parse/toLocatedJson/...
 //   - LocatedTimestampJson: API-Boundary-Form { at, tz }
+//   - isValidIanaTimeZone: IANA-Zonennamen-Validierung (type:"tz"-Felder)
+//   - warnIfNonUtcServerTimeZone: Boot-Warnung bei nicht-UTC Prozess-TZ
 //
 // Kommt:
-//   - DB-Wrapper (Wall-Clock+tz ↔ UTC transparent in Drizzle-Layer)
-//   - Lint-Regel "kein new Date() im Feature-Code"
 //   - UI-Komponenten <DateTimeInput>, <LocatedDateTimePicker>, <DateInput>
 
+export { warnIfNonUtcServerTimeZone } from "./boot-tz-warning";
+export { isValidIanaTimeZone } from "./iana";
 export { ensureTemporalPolyfill, getTemporal } from "./polyfill";
 export {
   createTzContext,