@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/testing/e2e-generator.ts

@@ -112,6 +112,14 @@ export function generateE2ESpec(
     // pro Field geschrieben, ohne CRUD-Zustand zu generieren wäre der
     // Spec wertlos. Branding/SMTP/etc. sind Author-spezifisch.
     if (screen.type === "configEdit") continue;
+    // projectionList: query-getrieben, Author-spezifische Projection —
+    // kein generischer CRUD-Spec ableitbar (wie actionForm/configEdit).
+    if (screen.type === "projectionList") continue;
+    // projectionDetail: dito — read-only single-row inspector, kein CRUD-Zustand.
+    if (screen.type === "projectionDetail") continue;
+    // dashboard: panel-getrieben (Stat/Chart/List-Queries) — dito, keine
+    // generische CRUD-Annahme möglich.
+    if (screen.type === "dashboard") continue;
     const { scope: feature, name: short } = parseQn(screenQn);
     const urlPath = `/t/${tenant}/${feature}/${short}`;
     const title = `${feature}/${short}`;

package/src/testing/file-provider-contract.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { FileStorageProvider } from "../files/types";
+
+const bytes = (s: string) => new TextEncoder().encode(s);
+const decode = (u: Uint8Array) => new TextDecoder().decode(u);
+
+async function* fromChunks(chunks: Uint8Array[]): AsyncIterable<Uint8Array> {
+  for (const c of chunks) yield c;
+}
+
+// Mirrors describeKmsAdapterContract (crypto/__tests__/kms-adapter-contract.ts):
+// pins the FileStorageProvider contract against whatever implementation the
+// factory returns. Provider-specific behavior (error messages, buffer
+// copies, multipart details) stays in each provider's dedicated tests.
+export function describeFileProviderContract(
+  name: string,
+  factory: () => FileStorageProvider | Promise<FileStorageProvider>,
+): void {
+  describe(`${name} — FileStorageProvider contract`, () => {
+    let provider: FileStorageProvider;
+    // Self-cleaning: every key this contract creates gets deleted in
+    // afterEach, so a persistent backend (local `kumiko dev` against a
+    // long-lived Minio, as opposed to CI's ephemeral one) doesn't leak
+    // `contract/<uuid>` objects into the next developer's session. delete()
+    // on a key that was never actually written is covered by the
+    // "no-op on a missing key" contract test above, so tracking generated
+    // keys unconditionally (even ones a test never got around to writing)
+    // is safe.
+    let writtenKeys: string[];
+
+    function trackedKey(ext: string): string {
+      const key = `contract/${crypto.randomUUID()}.${ext}`;
+      writtenKeys.push(key);
+      return key;
+    }
+
+    beforeEach(async () => {
+      provider = await factory();
+      writtenKeys = [];
+    });
+
+    afterEach(async () => {
+      for (const key of writtenKeys) await provider.delete(key);
+    });
+
+    test("write + read roundtrip preserves bytes", async () => {
+      const key = trackedKey("bin");
+      await provider.write(key, bytes("hello contract"));
+      expect(decode(await provider.read(key))).toBe("hello contract");
+    });
+
+    test("write on an existing key overwrites it (last-write-wins)", async () => {
+      const key = trackedKey("bin");
+      await provider.write(key, bytes("first"));
+      await provider.write(key, bytes("second"));
+      expect(decode(await provider.read(key))).toBe("second");
+    });
+
+    test("read throws for a missing key", async () => {
+      await expect(provider.read(`contract/missing-${crypto.randomUUID()}`)).rejects.toThrow();
+    });
+
+    test("exists reflects write + delete", async () => {
+      const key = trackedKey("txt");
+      expect(await provider.exists(key)).toBe(false);
+      await provider.write(key, bytes("x"));
+      expect(await provider.exists(key)).toBe(true);
+      await provider.delete(key);
+      expect(await provider.exists(key)).toBe(false);
+    });
+
+    test("delete on a missing key is a no-op", async () => {
+      await expect(
+        provider.delete(`contract/never-existed-${crypto.randomUUID()}`),
+      ).resolves.toBeUndefined();
+    });
+
+    test("writeStream + readStream roundtrip preserves bytes", async () => {
+      const key = trackedKey("stream");
+      await provider.writeStream(key, fromChunks([bytes("foo"), bytes("bar")]));
+      let out = "";
+      for await (const chunk of provider.readStream(key)) out += decode(chunk);
+      expect(out).toBe("foobar");
+    });
+
+    test("readStream on a missing key throws on the first chunk pull", async () => {
+      const it = provider
+        .readStream(`contract/missing-${crypto.randomUUID()}`)
+        [Symbol.asyncIterator]();
+      await expect(it.next()).rejects.toThrow();
+    });
+
+    test("getSignedUrl, when implemented, returns a URL string", async () => {
+      // skip: getSignedUrl is optional on the contract — feature-detected
+      if (!provider.getSignedUrl) return;
+
+      const key = trackedKey("txt");
+      await provider.write(key, bytes("signed"));
+      const url = await provider.getSignedUrl(key, 60);
+      expect(typeof url).toBe("string");
+      expect(url.length).toBeGreaterThan(0);
+    });
+  });
+}

package/src/testing/handler-context.ts

@@ -46,6 +46,7 @@ export function bridgeStub(opts?: {
   | "writeAs"
   | "appendEvent"
   | "unsafeAppendEvent"
+  | "tryAppendEvent"
   | "fetchForWriting"
   | "loadAggregate"
   | "archiveStream"
@@ -92,6 +93,7 @@ export function bridgeStub(opts?: {
     unsafeAppendEvent: notAvailable("unsafeAppendEvent") as unknown as (
       args: AppendEventArgs,
     ) => Promise<void>,
+    tryAppendEvent: notAvailable("tryAppendEvent") as unknown as HandlerContext["tryAppendEvent"],
     fetchForWriting: notAvailable("fetchForWriting") as unknown as (
       args: FetchForWritingArgs,
     ) => ReturnType<HandlerContext["fetchForWriting"]>,
@@ -115,7 +117,7 @@ export function bridgeStub(opts?: {
     ) as unknown as HandlerContext["resolveAuthClaims"],
     // Stub defaults to always-enabled — matches the dispatcher's behaviour
     // when no effectiveFeatures resolver is wired (tests without toggles).
-    hasFeature: () => true,
+    hasFeature: async () => true,
     metrics: createNoopMetricsHandle(),
     tracer: noopTracer,
     // Echter TzContext, kein notAvailable — Test-Code nutzt ctx.tz häufig

package/src/testing/index.ts

@@ -5,6 +5,7 @@
 
 export { rolesOf } from "./access-assertions";
 export { expectError, expectSuccess } from "./assertions";
+export { withBootValidatorFixture } from "./boot-validator-fixture";
 export { type ClearableTable, clearTables, resetTestTables } from "./db-cleanup";
 export {
   type E2EGeneratorOptions,
@@ -14,6 +15,7 @@ export {
   generateZodFixture,
 } from "./e2e-generator";
 export { expectErrorIncludes } from "./expect-error";
+export { describeFileProviderContract } from "./file-provider-contract";
 export { bridgeStub } from "./handler-context";
 export {
   getSetCookieRaw,
@@ -25,6 +27,8 @@ export { createLateBoundHolder, type LateBoundHolder } from "./late-bound";
 export { buildMultipartBody, patchFileInstanceofForBunTest } from "./multipart-helper";
 export {
   createMutableMasterKeyProvider,
+  createTestEnvelopeCipher,
+  createTestMasterKeyProvider,
   type MutableMasterKeyProvider,
 } from "./mutable-master-key-provider";
 export {
@@ -42,3 +46,4 @@ export {
 } from "./shared-entities";
 export { sleep } from "./utils";
 export { waitFor } from "./wait-for";
+export { withoutAmbientTemporal } from "./without-ambient-temporal";

package/src/testing/late-bound.ts

@@ -22,18 +22,20 @@ export type LateBoundHolder<T> = {
 
 export function createLateBoundHolder<T>(label = "value"): LateBoundHolder<T> {
   let value: T | undefined;
+  let isSet = false;
   return {
     set(v) {
       value = v;
+      isSet = true;
     },
     get() {
-      if (value === undefined) {
+      if (!isSet) {
         throw new Error(`late-bound ${label} accessed before set() was called`);
       }
-      return value;
+      return value as T;
     },
     isReady() {
-      return value !== undefined;
+      return isSet;
     },
   };
 }

package/src/testing/mutable-master-key-provider.ts

@@ -6,7 +6,14 @@
 // tests that want to exercise pre- and post-rotation behaviour in a
 // single suite.
 
-import type { MasterKeyProvider } from "../secrets";
+import { randomBytes } from "node:crypto";
+import {
+  createEnvelopeCipher,
+  createEnvMasterKeyProvider,
+  type EnvelopeCipher,
+  type EnvelopeCipherOptions,
+  type MasterKeyProvider,
+} from "../secrets";
 
 export type MutableMasterKeyProvider = MasterKeyProvider & {
   // Replace the backing provider. All future wrapDek/unwrapDek/currentVersion
@@ -20,8 +27,8 @@ export function createMutableMasterKeyProvider(
 ): MutableMasterKeyProvider {
   let current = initial;
   return {
-    wrapDek: (dek) => current.wrapDek(dek),
-    unwrapDek: (e, v) => current.unwrapDek(e, v),
+    wrapDek: (dek, scope) => current.wrapDek(dek, scope),
+    unwrapDek: (e, v, scope) => current.unwrapDek(e, v, scope),
     currentVersion: () => current.currentVersion(),
     isAvailable: () => current.isAvailable(),
     replace: (next) => {
@@ -29,3 +36,22 @@ export function createMutableMasterKeyProvider(
     },
   };
 }
+
+// Single-version env provider for tests — the shape every integration test
+// needs to exercise encrypted config keys / entity fields without caring
+// about keyring mechanics. Pass a fixed key to share it across stacks.
+export function createTestMasterKeyProvider(keyBase64?: string): MasterKeyProvider {
+  return createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      KUMIKO_SECRETS_MASTER_KEY_V1: keyBase64 ?? randomBytes(32).toString("base64"),
+    },
+  });
+}
+
+export function createTestEnvelopeCipher(
+  keyBase64?: string,
+  opts?: EnvelopeCipherOptions,
+): EnvelopeCipher {
+  return createEnvelopeCipher(createTestMasterKeyProvider(keyBase64), opts ?? {});
+}

package/src/testing/wait-for.ts

@@ -14,6 +14,9 @@ export async function waitFor(
   options?: { delays?: number[] },
 ): Promise<void> {
   const delays = options?.delays ?? [250, 1000, 3000];
+  if (delays.length === 0) {
+    throw new Error("waitFor: empty delay schedule");
+  }
   let lastError: unknown;
 
   for (let i = 0; i < delays.length; i++) {

package/src/testing/without-ambient-temporal.ts

@@ -0,0 +1,14 @@
+/**
+ * Run `fn` with `globalThis.Temporal` deleted, then restore.
+ * Used by ambient-independence regression tests (kumiko-framework#1525/#1550).
+ */
+export async function withoutAmbientTemporal<T>(fn: () => T | Promise<T>): Promise<T> {
+  const savedGlobal = (globalThis as { Temporal?: unknown }).Temporal;
+  delete (globalThis as { Temporal?: unknown }).Temporal;
+  try {
+    return await fn();
+  } finally {
+    if (savedGlobal === undefined) delete (globalThis as { Temporal?: unknown }).Temporal;
+    else (globalThis as { Temporal?: unknown }).Temporal = savedGlobal;
+  }
+}

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

@@ -1,9 +1,7 @@
-// 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).
+// Pacific/Apia sits far east of the dateline at UTC+13/+14 — a morning wall
+// clock there falls on the PREVIOUS UTC calendar day. Phrased as a date-
+// ordering property (not a fixed offset) so the test stays green regardless
+// of the tzdata DST view (UTC+13 and +14 both push 10:00 to the prior day).
 
 import { beforeAll, describe, expect, test } from "bun:test";
 import { ensureTemporalPolyfill } from "../polyfill";
@@ -13,8 +11,8 @@ beforeAll(async () => {
   await ensureTemporalPolyfill();
 });
 
-describe("ctx.tz — Pacific/Apia Datumsgrenze", () => {
-  test("Vormittags-Wall-Clock in Apia mappt auf den vorherigen UTC-Kalendertag", () => {
+describe("ctx.tz — Pacific/Apia dateline", () => {
+  test("a morning wall clock in Apia maps to the previous UTC calendar day", () => {
     const tz = createTzContext();
     const zdt = tz.parse("2026-01-15T10:00:00", "Pacific/Apia");
     expect(zdt.timeZoneId).toBe("Pacific/Apia");
@@ -22,11 +20,11 @@ describe("ctx.tz — Pacific/Apia Datumsgrenze", () => {
     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).
+    // Offset is a large positive value (UTC+13 or +14).
     expect(zdt.offsetNanoseconds).toBeGreaterThan(12 * 3600 * 1e9);
   });
 
-  test("Round-Trip bewahrt Wall-Clock + Instant über die Datumsgrenze", () => {
+  test("round-trip preserves wall clock + instant across the dateline", () => {
     const tz = createTzContext();
     const original = tz.parse("2026-01-15T10:00:00", "Pacific/Apia");
     const restored = tz.fromLocatedJson(tz.toLocatedJson(original));

package/src/time/geo-tz.ts

@@ -1,32 +1 @@
-// 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>;
-};
+export type * from "@cosmicdrift/kumiko-types/geo-tz";

package/src/time/index.ts

@@ -12,6 +12,7 @@
 export { warnIfNonUtcServerTimeZone } from "./boot-tz-warning";
 export type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
 export { isValidIanaTimeZone } from "./iana";
+export { instantToLegacyDate, legacyDateToInstant } from "./legacy-date";
 export { ensureTemporalPolyfill, getTemporal } from "./polyfill";
 export {
   createTzContext,

package/src/time/legacy-date.ts

@@ -0,0 +1,18 @@
+import { Temporal } from "temporal-polyfill";
+
+// Temporal→Date-Bridge für Lib-APIs die JS-Date verlangen (imapflow
+// search({since}), nodemailer-Header, ...). Gegenstück zur
+// dateToInstant-Richtung der DB-/Event-Store-Boundaries: Feature-Code
+// rechnet in Temporal, konvertiert erst am Aufruf der Fremd-API — der
+// no-date-api-Guard bleibt für Feature-Code scharf, die Konstruktion
+// lebt hier im allowlisteten Time-Layer.
+
+export function instantToLegacyDate(instant: Temporal.Instant): Date {
+  return new Date(instant.epochMilliseconds);
+}
+
+/** Gegenrichtung: Date aus einer Fremd-Lib (imapflow INTERNALDATE,
+ *  mailparser Date-Header) → Temporal.Instant. */
+export function legacyDateToInstant(date: Date): Temporal.Instant {
+  return Temporal.Instant.fromEpochMilliseconds(date.getTime());
+}

package/src/time/polyfill.ts

@@ -1,66 +1,49 @@
-// Temporal-Polyfill-Initialisierung.
+// Temporal polyfill bootstrap.
 //
-// Hintergrund: Temporal ist seit Anfang 2026 in Chromium 144+ und Firefox 139+
-// nativ verfügbar, aber nicht in Safari, iOS, oder Hermes (React Native).
-// Bun/Node haben es teilweise (V8-abhängig, instabil).
+// Temporal is native in Chromium 144+ / Firefox 139+, but missing in Safari,
+// iOS, and Hermes. Bun/Node coverage is incomplete. Boot installs
+// `temporal-polyfill` once so server/web/mobile share one API.
 //
-// Damit kumiko-Apps universal laufen — Server (Bun), Web (alle Browser),
-// Mobile (Hermes) — installiert das Framework beim Boot einmal den
-// `temporal-polyfill` (FullCalendar, ~25 KB). Auf Runtimes mit nativem
-// Temporal ist der Aufruf ein No-Op.
-//
-// Idempotent: mehrfacher Aufruf ist sicher (Polyfill prüft selbst ob
-// `globalThis.Temporal` schon existiert). Wir cachen das Ergebnis trotzdem
-// in einem Modul-Singleton, damit Boot-Performance nicht jedes Mal das
-// Polyfill-Modul-Loading triggert.
+// Idempotent: if `globalThis.Temporal` already exists the call is a no-op.
+// The cache is the live global check — not a sticky module flag — so tests
+// that delete the ambient global (fw#1550) still re-install on the next call.
 
-let polyfillInstalled = false;
 let polyfillPromise: Promise<void> | null = null;
 
 /**
- * Stellt sicher dass `globalThis.Temporal` verfügbar ist. Idempotent.
- *
- * - Wenn Native Temporal existiert (moderne Browser, neueres Bun): No-Op.
- * - Sonst: lädt `temporal-polyfill/global` (installiert globalThis.Temporal).
- *
- * Wird einmal beim Framework-Boot aufgerufen. Feature-Code muss das nicht
- * selbst tun — `Temporal` ist nach dem Boot überall verfügbar.
+ * Ensure `globalThis.Temporal` is available. Idempotent.
  */
 export async function ensureTemporalPolyfill(): Promise<void> {
-  // skip: Idempotenz — Polyfill bereits installiert in einem früheren Aufruf.
-  if (polyfillInstalled) return;
+  if ("Temporal" in globalThis) {
+    // skip: Temporal already on globalThis (native or prior polyfill)
+    return;
+  }
   if (polyfillPromise) {
     await polyfillPromise;
-    // skip: Concurrent-Boot — anderer Aufruf hat die Installation übernommen.
-    return;
+    if ("Temporal" in globalThis) {
+      // skip: Concurrent boot — peer call finished install
+      return;
+    }
+    // Peer resolved but global still missing (torn down mid-flight).
+    polyfillPromise = null;
   }
 
   polyfillPromise = (async () => {
-    // Runtime-Check entgegen Type-System-Annahme: temporal-spec deklariert
-    // Temporal ambient, aber ohne Polyfill fehlt es zur Laufzeit. `in`-Check
-    // ist die sauberste Prüfung, ohne Cast + ohne TS-Truthy-Warnings.
     if ("Temporal" in globalThis) {
-      polyfillInstalled = true;
-      // skip: Native Temporal vorhanden — Polyfill nicht nötig.
+      // skip: raced native/peer install
       return;
     }
-    // Polyfill globally installieren — der Side-Effect-Import setzt
-    // globalThis.Temporal.
     await import("temporal-polyfill/global");
-    polyfillInstalled = true;
   })();
 
   await polyfillPromise;
 }
 
 /**
- * Type-safe Zugriff auf globalThis.Temporal. Wirft wenn der Polyfill noch
- * nicht installiert ist (Boot-Reihenfolge-Bug). Feature-Code sollte
- * `ensureTemporalPolyfill()` einmal awaiten und danach `Temporal` global
- * nutzen, oder über diesen Helper die Sicherheit haben.
+ * Type-safe access to globalThis.Temporal. Throws if the polyfill has not
+ * been installed yet (boot-order bug).
  */
 export function getTemporal(): typeof Temporal {
-  // Runtime-Check entgegen Type-System-Annahme — siehe ensureTemporalPolyfill.
   if (!("Temporal" in globalThis)) {
     throw new Error(
       "Temporal not available. Call ensureTemporalPolyfill() during framework boot before any time-related code runs.",

package/src/time/tz-context.ts

@@ -1,85 +1,41 @@
-// ctx.tz — die Feature-Code-API für TZ-Operationen.
+// ctx.tz — the feature-code API for TZ operations.
 //
-// Eine konsistente Form für jeden Date/Time-Bedarf im Handler-Code:
-//   - "Jetzt als UTC-Instant"        → ctx.tz.now()
-//   - "Heute in Tenant-TZ"           → ctx.tz.today(ctx.tz.tenant)
-//   - "Wall-Clock parsen"            → ctx.tz.parse("2026-04-03T10:00", "Europe/Lisbon")
-//   - "ZonedDateTime → JSON-Pair"    → ctx.tz.toLocatedJson(zdt)
-//   - "JSON-Pair → ZonedDateTime"    → ctx.tz.fromLocatedJson({ at, tz })
+// A consistent shape for every date/time need in handler code:
+//   - "now as a UTC instant"          → ctx.tz.now()
+//   - "today in the tenant's TZ"      → ctx.tz.today(ctx.tz.tenant)
+//   - "parse a wall-clock string"     → ctx.tz.parse("2026-04-03T10:00", "Europe/Lisbon")
+//   - "ZonedDateTime → JSON pair"     → ctx.tz.toLocatedJson(zdt)
+//   - "JSON pair → ZonedDateTime"     → ctx.tz.fromLocatedJson({ at, tz })
 //
-// Feature-Code soll NICHT mehr `new Date()` aufrufen — die Lint-Regel dafür
-// kommt in einer späteren Iteration, wenn alle existing usages migriert sind.
+// Feature code should no longer call `new Date()` — the lint rule for that
+// lands in a later iteration, once all existing usages are migrated.
 //
-// `tenant` + `user` sind die TZ-Defaults für den aktuellen Request. Aktueller
-// 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
-// engine/factories.ts. Zwei Felder, idiotensicher.
-export type LocatedTimestampJson = {
-  /** Wall-Clock-ISO ohne Offset, z.B. "2026-04-03T10:00:00" */
-  readonly at: string;
-  /** IANA-Zone, z.B. "Europe/Lisbon" */
-  readonly tz: string;
-};
-
-export type TzContext = {
-  /** Default-TZ des Mandanten (aus tenant.timezone, default "UTC"). */
-  readonly tenant: string;
-  /** Anzeige-TZ des aktuellen Users (User-Profil-Override, fallback Tenant). */
-  readonly user: string;
-
-  /** Aktueller Moment als UTC-Instant. */
-  now(): Temporal.Instant;
-  /** Aktueller Moment als ZonedDateTime in der gewünschten Zone. */
-  nowIn(tz: string): Temporal.ZonedDateTime;
-
-  /** Heutiges Kalender-Datum in der gewünschten Zone. */
-  today(tz: string): Temporal.PlainDate;
-  /** Tagesgrenzen (00:00 bis 24:00 nächster Tag) als UTC-Instants — für DB-Range-Queries. */
-  todayRange(tz: string): { readonly start: Temporal.Instant; readonly end: Temporal.Instant };
-
-  /** Wall-Clock-String + IANA-Zone → ZonedDateTime. */
-  parse(wallClock: string, tz: string): Temporal.ZonedDateTime;
-
-  /** ZonedDateTime → UTC-Instant. */
-  toInstant(zdt: Temporal.ZonedDateTime): Temporal.Instant;
-
-  /** ZonedDateTime → JSON-Pair { at, tz } (API-Boundary). */
-  toLocatedJson(zdt: Temporal.ZonedDateTime): LocatedTimestampJson;
-
-  /** JSON-Pair { at, tz } → ZonedDateTime (Wall-Clock + IANA). */
-  fromLocatedJson(obj: LocatedTimestampJson): Temporal.ZonedDateTime;
+// `tenant` + `user` are the TZ defaults for the current request. Currently
+// both default to "UTC" — once tenant.timezone + user.timezone fields
+// exist, they get read from the request context here.
+//
+// The pure type contracts (TzContext, TzContextOptions, LocatedTimestampJson)
+// live in @cosmicdrift/kumiko-types/tz-context — only the factories are here.
 
-  /** 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>;
-};
+import type { TzContext, TzContextOptions } from "@cosmicdrift/kumiko-types/tz-context";
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import { ensureTemporalPolyfill } from "./polyfill";
 
-export type TzContextOptions = {
-  /** Tenant-Default-TZ. Default "UTC" wenn nicht gesetzt. */
-  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;
-};
+// Back-compat shim: re-exported so existing `from "@cosmicdrift/kumiko-framework/time/tz-context"`
+// imports keep working. Prefer importing from @cosmicdrift/kumiko-types/tz-context directly in
+// new code — drop this re-export once no framework-path imports remain.
+export type {
+  LocatedTimestampJson,
+  TzContext,
+  TzContextOptions,
+} from "@cosmicdrift/kumiko-types/tz-context";
 
 /**
- * Factory: erzeugt einen TzContext für den aktuellen Request.
- * Erwartet dass ensureTemporalPolyfill() bereits gelaufen ist (passiert beim
- * Framework-Boot). Wenn nicht, wirft getTemporal() — kein silent failure.
+ * Factory: creates a TzContext for the current request.
+ * Uses temporal-polyfill's module export (not globalThis.Temporal) so
+ * buildHandlerContext stays ambient-free (fw#1525/#1550).
  */
 export function createTzContext(options: TzContextOptions = {}): TzContext {
-  const T = getTemporal();
   const tenant = options.tenant ?? "UTC";
   const user = options.user ?? tenant;
   const geoTz = options.geoTz;
@@ -87,25 +43,26 @@ export function createTzContext(options: TzContextOptions = {}): TzContext {
   return {
     tenant,
     user,
-    now: () => T.Now.instant(), // @wrapper-known semantic-alias
-    nowIn: (tz: string) => T.Now.zonedDateTimeISO(tz), // @wrapper-known semantic-alias
-    today: (tz: string) => T.Now.plainDateISO(tz), // @wrapper-known semantic-alias
+    now: () => TemporalPolyfill.Now.instant(), // @wrapper-known semantic-alias
+    nowIn: (tz: string) => TemporalPolyfill.Now.zonedDateTimeISO(tz), // @wrapper-known semantic-alias
+    today: (tz: string) => TemporalPolyfill.Now.plainDateISO(tz), // @wrapper-known semantic-alias
     todayRange: (tz: string) => {
-      const today = T.Now.plainDateISO(tz);
+      const today = TemporalPolyfill.Now.plainDateISO(tz);
       const startZdt = today.toZonedDateTime({ timeZone: tz });
       const endZdt = today.add({ days: 1 }).toZonedDateTime({ timeZone: tz });
       return { start: startZdt.toInstant(), end: endZdt.toInstant() };
     },
-    parse: (wallClock: string, tz: string) => T.PlainDateTime.from(wallClock).toZonedDateTime(tz),
+    parse: (wallClock: string, tz: string) =>
+      TemporalPolyfill.PlainDateTime.from(wallClock).toZonedDateTime(tz),
     toInstant: (zdt) => zdt.toInstant(),
     toLocatedJson: (zdt) => ({
-      // Wall-Clock OHNE Offset (kein "Z", kein "+01:00") plus IANA-Name.
-      // .toPlainDateTime().toString() liefert "YYYY-MM-DDTHH:MM:SS[.fff]"
-      // ohne Offset — exakt unser Vertrag.
+      // Wall-clock WITHOUT offset (no "Z", no "+01:00") plus the IANA name.
+      // .toPlainDateTime().toString() returns "YYYY-MM-DDTHH:MM:SS[.fff]"
+      // without an offset — exactly our contract.
       at: zdt.toPlainDateTime().toString(),
       tz: zdt.timeZoneId,
     }),
-    fromLocatedJson: (obj) => T.PlainDateTime.from(obj.at).toZonedDateTime(obj.tz),
+    fromLocatedJson: (obj) => TemporalPolyfill.PlainDateTime.from(obj.at).toZonedDateTime(obj.tz),
     fromCoordinates: async (coords) => {
       if (geoTz === undefined) {
         throw new Error(
@@ -127,12 +84,14 @@ export function createTzContext(options: TzContextOptions = {}): TzContext {
       }
       return geoTz.fromAddress(address);
     },
-  };
+    // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal values at
+    // runtime; TzContext is typed against ambient Temporal from temporal-spec.
+  } as TzContext;
 }
 
 /**
- * Convenience: stellt sicher dass der Polyfill geladen ist UND erzeugt
- * den TzContext in einem await. Bevorzugt verwenden in Boot-Code.
+ * Convenience: ensures the polyfill is loaded AND creates the TzContext in
+ * one await. Prefer this in boot code.
  */
 export async function createTzContextAsync(options?: TzContextOptions): Promise<TzContext> {
   await ensureTemporalPolyfill();