@cosmicdrift/kumiko-framework 0.93.0 → 0.95.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.93.0",
+  "version": "0.95.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.93.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.95.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__/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/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/handlers.ts

@@ -7,7 +7,7 @@ import type { Logger } from "../../logging/types";
 import type { Meter, MetricsHandle, Tracer } from "../../observability/types";
 import type { EntityCache } from "../../pipeline/entity-cache";
 import type { SearchAdapter } from "../../search/types";
-import type { TzContext } from "../../time";
+import type { GeoTzProvider, TzContext } from "../../time";
 import type { ConfigAccessor, ConfigAccessorFactory, ConfigResolver } from "./config";
 import type { KumikoEventTypeMap } from "./event-type-map";
 
@@ -288,6 +288,10 @@ export type AppContext = SharedContextFields & {
   readonly triggerName?: string;
   readonly _userId?: string | undefined;
   readonly _handlerType?: string | undefined;
+  /** Optionaler Geo→Zone-Adapter. Wenn gesetzt (via buildServer-context oder
+   *  runProdApp/runDevApp extraContext), reicht der Dispatcher ihn an
+   *  ctx.tz.fromCoordinates / fromAddress weiter. Ohne Provider werfen diese. */
+  readonly geoTzProvider?: GeoTzProvider;
   /** Tenant des aktuellen Pipeline-Calls. Wird vom Dispatcher beim Bauen
    *  des HandlerContext aus `user.tenantId` gespiegelt, damit lifecycle-
    *  pipeline + system-hooks den Wert ohne Zugriff auf user-Object haben.

package/src/engine/types/index.ts

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

package/src/pipeline/dispatcher.ts

@@ -544,8 +544,12 @@ export function createDispatcher(
     // `context` can be overridden, but we want the authoritative registry
     // from the dispatcher's own closure to win.
     // ctx.tz ist immer da. Tenant + User-Defaults kommen aus dem
-    // SessionUser sobald die Felder existieren — bis dahin "UTC".
-    const tz = createTzContext();
+    // SessionUser sobald die Felder existieren — bis dahin "UTC". Ein
+    // app-injizierter GeoTzProvider (context.geoTzProvider) speist
+    // ctx.tz.fromCoordinates / fromAddress.
+    const tz = createTzContext(
+      context.geoTzProvider !== undefined ? { geoTz: context.geoTzProvider } : {},
+    );
 
     return {
       ...context,

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

@@ -0,0 +1,65 @@
+// ctx.tz.fromCoordinates / fromAddress — der GeoTzProvider-Injection-Seam.
+// Das Framework liefert nur Interface + Delegation; ohne Provider wird klar
+// geworfen statt still zu raten.
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import type { GeoTzProvider } from "../geo-tz";
+import { ensureTemporalPolyfill } from "../polyfill";
+import { createTzContext } from "../tz-context";
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+});
+
+const BERLIN = { latitude: 52.52, longitude: 13.405 };
+
+describe("ctx.tz — GeoTzProvider seam", () => {
+  test("fromCoordinates delegiert an den Provider (sync)", async () => {
+    const provider: GeoTzProvider = { fromCoordinates: () => "Europe/Berlin" };
+    const tz = createTzContext({ geoTz: provider });
+    expect(await tz.fromCoordinates(BERLIN)).toBe("Europe/Berlin");
+  });
+
+  test("fromCoordinates delegiert an den Provider (async)", async () => {
+    const provider: GeoTzProvider = { fromCoordinates: async () => "Asia/Tokyo" };
+    const tz = createTzContext({ geoTz: provider });
+    expect(await tz.fromCoordinates({ latitude: 35.68, longitude: 139.69 })).toBe("Asia/Tokyo");
+  });
+
+  test("fromCoordinates reicht die Koordinaten unverändert durch", async () => {
+    let seen: { latitude: number; longitude: number } | undefined;
+    const provider: GeoTzProvider = {
+      fromCoordinates: (c) => {
+        seen = c;
+        return "Europe/Berlin";
+      },
+    };
+    await createTzContext({ geoTz: provider }).fromCoordinates(BERLIN);
+    expect(seen).toEqual(BERLIN);
+  });
+
+  test("fromCoordinates wirft ohne Provider", async () => {
+    const tz = createTzContext();
+    await expect(tz.fromCoordinates(BERLIN)).rejects.toThrow(/GeoTzProvider/);
+  });
+
+  test("fromAddress delegiert wenn der Provider es unterstützt", async () => {
+    const provider: GeoTzProvider = {
+      fromCoordinates: () => "UTC",
+      fromAddress: (a) => (a.country === "PT" ? "Europe/Lisbon" : "UTC"),
+    };
+    const tz = createTzContext({ geoTz: provider });
+    expect(await tz.fromAddress({ country: "PT" })).toBe("Europe/Lisbon");
+  });
+
+  test("fromAddress wirft wenn der Provider kein fromAddress hat (offline lat/lng)", async () => {
+    const provider: GeoTzProvider = { fromCoordinates: () => "UTC" };
+    const tz = createTzContext({ geoTz: provider });
+    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(/fromAddress/);
+  });
+
+  test("fromAddress wirft ohne Provider", async () => {
+    const tz = createTzContext();
+    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(/GeoTzProvider/);
+  });
+});

package/src/time/geo-tz.ts

@@ -0,0 +1,32 @@
+// GeoTzProvider — optionaler Adapter Geo-Position → IANA-Zone. Das Framework
+// definiert NUR das Interface + den Injection-Seam (ctx.tz.fromCoordinates /
+// fromAddress); eine konkrete Implementation kommt aus einem separaten Paket
+// (z.B. ein geo-tz-basiertes Offline-Paket). v1-Default: kein Provider — die
+// fromCoordinates/fromAddress-Methoden werfen klar statt still falsch zu raten.
+//
+// `fromCoordinates` ist die PRIMÄRE Methode: Offline-geo-tz-Libs lösen
+// lat/lng → Zone (genau, offline, kostenlos) — sie kennen keine Postadressen.
+// `fromAddress` ist optional, für Provider die eine Geocoding-API (Adresse →
+// Zone, online) anbinden. Diese Trennung hält das Interface kompatibel mit
+// beiden Provider-Klassen, statt eine Adress-Form zu erzwingen die der
+// Offline-Fall gar nicht bedienen kann.
+
+export type GeoCoordinates = {
+  readonly latitude: number;
+  readonly longitude: number;
+};
+
+export type GeoAddress = {
+  readonly street?: string;
+  readonly city?: string;
+  readonly region?: string;
+  readonly postalCode?: string;
+  readonly country?: string;
+};
+
+export type GeoTzProvider = {
+  /** Geo-Koordinaten → IANA-Zone (offline lat/lng → tz). */
+  readonly fromCoordinates: (coords: GeoCoordinates) => string | Promise<string>;
+  /** Optional: Postadresse → IANA-Zone (Geocoding-API-Provider). */
+  readonly fromAddress?: (address: GeoAddress) => string | Promise<string>;
+};

package/src/time/index.ts

@@ -7,11 +7,10 @@
 //   - LocatedTimestampJson: API-Boundary-Form { at, tz }
 //   - isValidIanaTimeZone: IANA-Zonennamen-Validierung (type:"tz"-Felder)
 //   - warnIfNonUtcServerTimeZone: Boot-Warnung bei nicht-UTC Prozess-TZ
-//
-// Kommt:
-//   - UI-Komponenten <DateTimeInput>, <LocatedDateTimePicker>, <DateInput>
+//   - GeoTzProvider: optionaler Geo→Zone-Adapter (ctx.tz.fromCoordinates/fromAddress)
 
 export { warnIfNonUtcServerTimeZone } from "./boot-tz-warning";
+export type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
 export { isValidIanaTimeZone } from "./iana";
 export { ensureTemporalPolyfill, getTemporal } from "./polyfill";
 export {

package/src/time/tz-context.ts

@@ -14,6 +14,7 @@
 // Stand: beide default auf "UTC" — sobald tenant.timezone +
 // user.timezone Felder existieren, lese ich sie aus dem Request-Context.
 
+import type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
 import { ensureTemporalPolyfill, getTemporal } from "./polyfill";
 
 // JSON-Form für Wall-Clock+TZ — siehe locatedTimestamp(name) Helper in
@@ -52,6 +53,14 @@ export type TzContext = {
 
   /** JSON-Pair { at, tz } → ZonedDateTime (Wall-Clock + IANA). */
   fromLocatedJson(obj: LocatedTimestampJson): Temporal.ZonedDateTime;
+
+  /** Geo-Koordinaten → IANA-Zone via konfiguriertem GeoTzProvider.
+   *  Wirft wenn kein Provider konfiguriert ist (v1-Default). */
+  fromCoordinates(coords: GeoCoordinates): Promise<string>;
+  /** Postadresse → IANA-Zone via GeoTzProvider. Wirft wenn kein Provider
+   *  konfiguriert ist ODER der Provider kein fromAddress unterstützt (der
+   *  Offline-lat/lng-Provider tut das nicht). */
+  fromAddress(address: GeoAddress): Promise<string>;
 };
 
 export type TzContextOptions = {
@@ -59,6 +68,9 @@ export type TzContextOptions = {
   readonly tenant?: string;
   /** User-Override. Default = tenant. */
   readonly user?: string;
+  /** Optionaler Geo→Zone-Adapter für ctx.tz.fromCoordinates / fromAddress.
+   *  Ohne Provider werfen diese Methoden. */
+  readonly geoTz?: GeoTzProvider;
 };
 
 /**
@@ -70,6 +82,7 @@ export function createTzContext(options: TzContextOptions = {}): TzContext {
   const T = getTemporal();
   const tenant = options.tenant ?? "UTC";
   const user = options.user ?? tenant;
+  const geoTz = options.geoTz;
 
   return {
     tenant,
@@ -93,6 +106,22 @@ export function createTzContext(options: TzContextOptions = {}): TzContext {
       tz: zdt.timeZoneId,
     }),
     fromLocatedJson: (obj) => T.PlainDateTime.from(obj.at).toZonedDateTime(obj.tz),
+    fromCoordinates: async (coords) => {
+      if (geoTz === undefined) {
+        throw new Error(
+          "ctx.tz.fromCoordinates requires a GeoTzProvider — inject one via the app context (e.g. buildServer({ context: { geoTzProvider } }) or runProdApp({ extraContext: { geoTzProvider } })) or install a provider package.",
+        );
+      }
+      return geoTz.fromCoordinates(coords);
+    },
+    fromAddress: async (address) => {
+      if (geoTz?.fromAddress === undefined) {
+        throw new Error(
+          "ctx.tz.fromAddress requires a GeoTzProvider that implements fromAddress (geocoding). Offline lat/lng providers only support fromCoordinates.",
+        );
+      }
+      return geoTz.fromAddress(address);
+    },
   };
 }