@cosmicdrift/kumiko-framework 0.92.0 → 0.94.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.92.0",
+  "version": "0.94.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.94.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/derived-fields.integration.test.ts

@@ -0,0 +1,126 @@
+// Full-stack proof for EntityDefinition.derivedFields: a derived field is
+// computed read-time by the list-query handler and appended to each row — it
+// has no DB column, is never written, and the clock comes from ctx.asOf.
+//
+// Bun.SQL-only setup via setupTestStack.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient, selectMany } from "../db/query";
+import { buildEntityTable } from "../db/table-builder";
+import {
+  createDerivedField,
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineFeature,
+} from "../engine";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../stack";
+
+// `priceCents` + `name` are stored; the three derived fields are computed from
+// them (and the clock) at read-time only.
+const gadgetEntity = createEntity({
+  table: "derived_gadgets",
+  fields: {
+    name: createTextField({ required: true }),
+    priceCents: createNumberField({ required: true }),
+  },
+  derivedFields: {
+    // Pure row→value: the canonical "one live-computed column" case.
+    grossCents: createDerivedField({
+      valueType: "number",
+      derive: (row) => Math.round(Number(row["priceCents"]) * 1.19),
+    }),
+    label: createDerivedField({
+      valueType: "text",
+      derive: (row) => `${String(row["name"])} (${String(row["priceCents"])})`,
+    }),
+    // Proves the clock is injected — never reads Temporal.Now itself.
+    asOfStamp: createDerivedField({
+      valueType: "text",
+      derive: (_row, ctx) => ctx.asOf.toString(),
+    }),
+  },
+});
+const gadgetTable = buildEntityTable("gadget", gadgetEntity);
+
+const shopFeature = defineFeature("gadgetshop", (r) => {
+  r.entity("gadget", gadgetEntity);
+  r.writeHandler(
+    defineEntityCreateHandler("gadget", gadgetEntity, { access: { roles: ["Admin"] } }),
+  );
+  r.queryHandler(defineEntityListHandler("gadget", gadgetEntity, { access: { roles: ["Admin"] } }));
+});
+
+describe("EntityDefinition.derivedFields — read-time computed columns", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [shopFeature] });
+    await unsafeCreateEntityTable(stack.db, gadgetEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  beforeEach(async () => {
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${gadgetTable.tableName}"`);
+  });
+
+  test("list query appends the computed value (gross = net × 1.19)", async () => {
+    await stack.http.writeOk(
+      "gadgetshop:write:gadget:create",
+      { name: "Cable", priceCents: 1000 },
+      TestUsers.admin,
+    );
+    await stack.http.writeOk(
+      "gadgetshop:write:gadget:create",
+      { name: "Hub", priceCents: 4200 },
+      TestUsers.admin,
+    );
+
+    const res = await stack.http.query("gadgetshop:query:gadget:list", {}, TestUsers.admin);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      data: { rows: Array<Record<string, unknown>> };
+    };
+    const byName = new Map(body.data.rows.map((r) => [r["name"], r]));
+
+    expect(byName.get("Cable")?.["grossCents"]).toBe(1190);
+    expect(byName.get("Hub")?.["grossCents"]).toBe(4998);
+    expect(byName.get("Cable")?.["label"]).toBe("Cable (1000)");
+  });
+
+  test("derived value comes from ctx.asOf, parseable as an instant", async () => {
+    await stack.http.writeOk(
+      "gadgetshop:write:gadget:create",
+      { name: "Cable", priceCents: 1000 },
+      TestUsers.admin,
+    );
+
+    const res = await stack.http.query("gadgetshop:query:gadget:list", {}, TestUsers.admin);
+    const body = (await res.json()) as { data: { rows: Array<Record<string, unknown>> } };
+    const stamp = body.data.rows[0]?.["asOfStamp"];
+
+    expect(typeof stamp).toBe("string");
+    // A real read-time instant — Temporal parses it and it's within a minute.
+    const parsed = Temporal.Instant.from(String(stamp));
+    const skewSeconds = Math.abs(parsed.until(Temporal.Now.instant()).total("seconds"));
+    expect(skewSeconds).toBeLessThan(60);
+  });
+
+  test("derived fields produce no DB column — the stored row has only name + priceCents", async () => {
+    await stack.http.writeOk(
+      "gadgetshop:write:gadget:create",
+      { name: "Cable", priceCents: 1000 },
+      TestUsers.admin,
+    );
+
+    const rows = await selectMany(stack.db, gadgetTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).not.toHaveProperty("grossCents");
+    expect(rows[0]).not.toHaveProperty("label");
+    expect(rows[0]).not.toHaveProperty("asOfStamp");
+    expect(rows[0]?.["name"]).toBe("Cable");
+  });
+});

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/__tests__/screen.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { validateBoot } from "../boot-validator";
 import { defineFeature } from "../define-feature";
-import { createEntity, createTextField } from "../factories";
+import { createDerivedField, createEntity, createTextField } from "../factories";
 import { createRegistry } from "../registry";
 import type { ScreenDefinition } from "../types/screen";
 
@@ -15,6 +15,21 @@ function productEntity() {
   });
 }
 
+function derivedProductEntity() {
+  return createEntity({
+    table: "derived_products",
+    fields: {
+      name: createTextField(),
+    },
+    derivedFields: {
+      summary: createDerivedField({
+        valueType: "text",
+        derive: (row) => String(row["name"]),
+      }),
+    },
+  });
+}
+
 describe("r.screen() — registration", () => {
   test("stores an entityList screen on the FeatureDefinition", () => {
     const feature = defineFeature("shop", (r) => {
@@ -279,6 +294,33 @@ describe("validateBoot — screen validation", () => {
     expect(() => validateBoot([feature])).toThrow(/field "nonexistent"/);
   });
 
+  test("entityList with a derived-field column boots (derived is a valid column)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", derivedProductEntity());
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name", "summary"],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("entityList defaultSort on a derived field fails boot (server sort can't apply)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", derivedProductEntity());
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name", "summary"],
+        defaultSort: { field: "summary", dir: "asc" },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/defaultSort references unknown field "summary"/);
+  });
+
   test("entityEdit with unknown field (string form in sections) fails boot", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

package/src/engine/boot-validator/screens-nav.ts

@@ -309,6 +309,14 @@ export function validateScreens(
     }
 
     const fieldNames = new Set(Object.keys(entityDef.fields));
+    // List columns may also name a read-time derived field (not a stored
+    // column). Allowed for display; deliberately NOT added to `fieldNames`, so
+    // defaultSort/filter on a derived field still fails — server-side sort over
+    // a non-column is a silent no-op (see DerivedFieldDef).
+    const columnFieldNames =
+      entityDef.derivedFields !== undefined
+        ? new Set([...fieldNames, ...Object.keys(entityDef.derivedFields)])
+        : fieldNames;
     const rowMeta = rowMetaFieldNames(entityDef.softDelete ?? false);
     if (screen.type === "entityList") {
       // Empty column list would render as a blank table — almost always the
@@ -323,14 +331,14 @@ export function validateScreens(
       }
       for (const col of screen.columns) {
         const normalized = normalizeListColumn(col);
-        if (!fieldNames.has(normalized.field)) {
+        if (!columnFieldNames.has(normalized.field)) {
           throw new Error(
             buildUnknownFieldMessage(
               feature.name,
               screenId,
               normalized.field,
               screen.entity,
-              fieldNames,
+              columnFieldNames,
             ),
           );
         }

package/src/engine/entity-handlers.ts

@@ -10,7 +10,13 @@ import { createEventStoreExecutor, type EventStoreExecutor } from "../db/event-s
 import { buildEntityTable } from "../db/table-builder";
 import { assertUnreachable } from "../utils";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
-import type { AccessRule, EntityDefinition, QueryHandlerDef, WriteHandlerDef } from "./types";
+import type {
+  AccessRule,
+  DeriveContext,
+  EntityDefinition,
+  QueryHandlerDef,
+  WriteHandlerDef,
+} from "./types";
 
 // Convention-based handler factories for event-sourced aggregates.
 //
@@ -190,6 +196,29 @@ export function defineEntityWriteHandler(
   };
 }
 
+// Append read-time derived-field values (EntityDefinition.derivedFields) to
+// each row, after the SQL fetch + reference eagerload — i.e. on the row shape
+// the view-model will see. The clock is the read instant; derive bodies must
+// read it from ctx.asOf, never their own Date/Temporal.Now. No-op (returns the
+// rows untouched) when the entity declares no derived fields.
+function augmentDerivedFields(
+  rows: readonly Record<string, unknown>[],
+  entity: EntityDefinition,
+): readonly Record<string, unknown>[] {
+  const derived = entity.derivedFields;
+  if (derived === undefined) return rows;
+  const entries = Object.entries(derived);
+  if (entries.length === 0) return rows;
+  const ctx: DeriveContext = { asOf: Temporal.Now.instant() };
+  return rows.map((row) => {
+    const out: Record<string, unknown> = { ...row };
+    for (const [fieldName, def] of entries) {
+      out[fieldName] = def.derive(row, ctx);
+    }
+    return out;
+  });
+}
+
 export function defineEntityQueryHandler(
   name: string,
   entity: EntityDefinition,
@@ -225,14 +254,15 @@ export function defineEntityQueryHandler(
           ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
           ...(ctx.includeDeleted === true && { includeDeleted: true }),
         });
-        if (!hasRefFields) return result;
-        const enrichedRows = await enrichWithReferences(
-          result.rows,
-          entity,
-          (name) => ctx.registry.getEntity(name),
-          ctx.db,
-        );
-        return { ...result, rows: enrichedRows };
+        const enrichedRows = hasRefFields
+          ? await enrichWithReferences(
+              result.rows,
+              entity,
+              (name) => ctx.registry.getEntity(name),
+              ctx.db,
+            )
+          : result.rows;
+        return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
       };
       break;
     case "detail":

package/src/engine/factories.ts

@@ -3,6 +3,7 @@ import type {
   BooleanFieldDef,
   DateFieldDef,
   DecimalFieldDef,
+  DerivedFieldDef,
   EmbeddedFieldDef,
   EntityDefinition,
   EntityIndexDef,
@@ -54,6 +55,17 @@ export function createTextField<R extends true | false = false>(
  * Setze einen explicit `maxLength` wenn du ein verirrtes Browser-Paste
  * früh ablehnen willst (z.B. 1_000_000 = 1 MB).
  */
+/**
+ * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
+ * The value is derived per row from the stored columns + the clock at query
+ * time, never persisted. Display only — server-side sort/filter/search don't
+ * apply and there's no client-side sort path (see DerivedFieldDef). `derive`
+ * must take its clock from `ctx.asOf`, never `Temporal.Now`/`Date`.
+ */
+export function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef {
+  return { ...spec };
+}
+
 export function createLongTextField<R extends true | false = false>(
   overrides?: Partial<Omit<LongTextFieldDef, "type" | "required">> & { required?: R },
 ): LongTextFieldDef & { required: R } {
@@ -373,6 +385,7 @@ export function createEntity<F>(def: {
   readonly idType?: "serial" | "uuid";
   readonly access?: EntityDefinition["access"];
   readonly retention?: RetentionDef;
+  readonly derivedFields?: EntityDefinition["derivedFields"];
 }): F extends FieldsMap ? EntityDefinition<F> : never {
   return {
     softDelete: false,

package/src/engine/index.ts

@@ -95,6 +95,7 @@ export {
   createBooleanField,
   createDateField,
   createDecimalField,
+  createDerivedField,
   createEmbeddedField,
   createEntity,
   createFileField,
@@ -263,6 +264,10 @@ export type {
   DateFieldDef,
   DecimalFieldDef,
   DeleteContext,
+  DeriveContext,
+  DerivedFieldDef,
+  DerivedFieldsMap,
+  DerivedValueType,
   EditExtensionSection,
   EditFieldSpec,
   EditFieldsSection,

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/engine/types/fields.ts

@@ -516,6 +516,47 @@ export function isFileField(field: FieldDefinition | undefined): field is AnyFil
   );
 }
 
+// --- Derived (computed) fields ---
+//
+// A derived field is read-time only: its value is computed from the stored row
+// (and the clock) when a list/detail query runs, never persisted. It lives in
+// `EntityDefinition.derivedFields` — deliberately NOT in `fields`, so it
+// produces no DB column, never enters a write schema, and can't be the target
+// of an entityEdit. A declarative `entityList` can name it like any column and
+// the view-model renders the appended value.
+//
+// LIMIT: derived columns are DISPLAY ONLY. A declarative `entityList` loads its
+// rows server-side and a column-header sort round-trips to the server, where
+// `executor.list` sorts/filters/searches over real SQL columns — so a derived
+// field (no column) silently no-ops. There is no client-side sort path. Need a
+// derived value sortable/searchable? Materialize it as a stored field; it then
+// rides the existing `searchable`/`sortable` machinery. Time-dependent values
+// (as-of-today) can't be materialized without a daily re-index anyway.
+
+/** Display type a derived value formats as — drives the column's renderer
+ *  choice in the view-model, parallel to FieldDefinition["type"]. Single-column
+ *  types only: `money` is excluded because it needs a `<name>Currency`
+ *  companion column a derived field has no place to put — use `number`/
+ *  `decimal` plus a `{ format: "currency" }` column renderer instead. */
+export type DerivedValueType = "text" | "number" | "decimal" | "boolean" | "date" | "timestamp";
+
+/** Clock injected into `derive` — never read `Temporal.Now`/`Date` inside a
+ *  derive body (no-date-api guard + testability). The list-query handler passes
+ *  the read-time instant; unit tests pass a fixed one. */
+export type DeriveContext = {
+  readonly asOf: Temporal.Instant;
+};
+
+export type DerivedFieldDef = {
+  readonly valueType: DerivedValueType;
+  /** Pure function of the stored row + clock. Returns the JSON-safe display
+   *  value (e.g. integer minor units for a currency column, ISO string for a
+   *  `date`). */
+  readonly derive: (row: Readonly<Record<string, unknown>>, ctx: DeriveContext) => unknown;
+};
+
+export type DerivedFieldsMap = Readonly<Record<string, DerivedFieldDef>>;
+
 // --- Entity ---
 
 // --- State Transitions ---
@@ -613,4 +654,10 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
    * Siehe docs/plans/features/core-data-retention.md.
    */
   readonly retention?: RetentionDef;
+  /**
+   * Read-time computed fields, keyed by name. Not stored, not a DB column,
+   * not writable — appended to each row by the list/detail query handler and
+   * nameable as a column in a declarative `entityList`. See DerivedFieldDef.
+   */
+  readonly derivedFields?: DerivedFieldsMap;
 };

package/src/engine/types/index.ts

@@ -86,6 +86,10 @@ export type {
   DateFieldDef,
   DecimalFieldDef,
   DefaultCurrency,
+  DeriveContext,
+  DerivedFieldDef,
+  DerivedFieldsMap,
+  DerivedValueType,
   EmbeddedFieldDef,
   EmbeddedSubFieldDef,
   EntityDefinition,

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,