@cosmicdrift/kumiko-framework 0.1.0

package/src/testing/http-cookies.ts

@@ -0,0 +1,52 @@
+// Shared Set-Cookie parser for tests. Cookie-auth tests (auth-middleware,
+// csrf-middleware, auth-routes, auth.integration) all need the same
+// primitive: "given a Response, give me the cookies the server tried to
+// set". Before this helper each test file rolled its own — three near-
+// duplicates that drift the moment one adds Domain/Partitioned/Priority
+// parsing the others don't.
+//
+// The helper returns both the parsed value AND the raw string so callers
+// can assert on attributes like SameSite, HttpOnly, Max-Age without a
+// second parse step.
+
+export type ParsedSetCookie = {
+  readonly value: string;
+  readonly raw: string;
+};
+
+// Pull every Set-Cookie the response carries. Prefers the standard
+// `Headers.getSetCookie()` (Node 20+, Bun, modern undici/whatwg-fetch);
+// falls back to the single-header-value for environments that don't
+// expose it. The fallback path only sees the FIRST cookie if multiple
+// were set in one response — a limitation of RFC 7230 headers — which
+// is acceptable here because tests that set multiple cookies run on a
+// runtime that supports getSetCookie.
+export function getSetCookies(res: Response): Map<string, ParsedSetCookie> {
+  const getter = (res.headers as { getSetCookie?: () => string[] }).getSetCookie;
+  const raws = getter ? getter.call(res.headers) : [res.headers.get("set-cookie") ?? ""];
+  const out = new Map<string, ParsedSetCookie>();
+  for (const raw of raws) {
+    if (!raw) continue;
+    const first = raw.split(";")[0];
+    if (!first) continue;
+    const eq = first.indexOf("=");
+    if (eq === -1) continue;
+    const name = first.slice(0, eq).trim();
+    const value = first.slice(eq + 1).trim();
+    out.set(name, { value, raw });
+  }
+  return out;
+}
+
+// Convenience for the common case: "give me the value of cookie X".
+// Returns undefined when the cookie isn't set — no throw, so negative
+// assertions read cleanly (`expect(cookies.get("foo")).toBeUndefined()`).
+export function getSetCookieValue(res: Response, name: string): string | undefined {
+  return getSetCookies(res).get(name)?.value;
+}
+
+// Raw Set-Cookie header for attribute assertions
+// (`expect(raw).toMatch(/SameSite=Lax/)`). Returns undefined when missing.
+export function getSetCookieRaw(res: Response, name: string): string | undefined {
+  return getSetCookies(res).get(name)?.raw;
+}

package/src/testing/index.ts

@@ -0,0 +1,41 @@
+// Test-Assertions, Domain-Test-Fixtures und Vitest-spezifische Helpers.
+// Production-Code (dev-server, bin/) darf NICHTS aus diesem Sub-Path importieren —
+// die Stack-Builder leben in `@cosmicdrift/kumiko-framework/stack`, dieses Modul darf
+// vitest-Imports top-level enthalten (siehe expect-error.ts).
+
+export { rolesOf } from "./access-assertions";
+export { expectError, expectSuccess } from "./assertions";
+export {
+  type E2EGeneratorOptions,
+  type E2ETestSpec,
+  type EditFillOp,
+  generateE2ESpec,
+  generateZodFixture,
+} from "./e2e-generator";
+export { expectErrorIncludes } from "./expect-error";
+export { bridgeStub } from "./handler-context";
+export {
+  getSetCookieRaw,
+  getSetCookies,
+  getSetCookieValue,
+  type ParsedSetCookie,
+} from "./http-cookies";
+export { createLateBoundHolder, type LateBoundHolder } from "./late-bound";
+export {
+  createMutableMasterKeyProvider,
+  type MutableMasterKeyProvider,
+} from "./mutable-master-key-provider";
+export {
+  createRecordingProvider,
+  type RecordingProvider,
+} from "./observability-recorder";
+export {
+  sharedItemEntity,
+  sharedItemTable,
+  sharedUserEntity,
+  sharedUserTable,
+  sharedWidgetEntity,
+  sharedWidgetTable,
+} from "./shared-entities";
+export { sleep } from "./utils";
+export { waitFor } from "./wait-for";

package/src/testing/late-bound.ts

@@ -0,0 +1,39 @@
+// Late-bound reference for values that only exist AFTER setupTestStack
+// returns — typically the session-callbacks, which close over stack.db.
+//
+// Without this helper, integration tests repeat the same trampoline
+// pattern (let real; async wrapper; null-check on each call). The holder
+// inverts the dependency: the test passes the trampolines into setupTestStack
+// first, then injects the concrete impl once db is available.
+//
+// Production wiring (runDevApp / runProdApp) doesn't reuse this — those
+// wrappers inline an equivalent let-closure-throw pattern to avoid the
+// runtime-isolation cross from dev → test packages. Same idea, different
+// file.
+
+export type LateBoundHolder<T> = {
+  /** Store the concrete value. Must be called before any trampoline fires. */
+  set(value: T): void;
+  /** Fetch the concrete value or throw if set() hasn't been called yet. */
+  get(): T;
+  /** True after set() has been called. */
+  isReady(): boolean;
+};
+
+export function createLateBoundHolder<T>(label = "value"): LateBoundHolder<T> {
+  let value: T | undefined;
+  return {
+    set(v) {
+      value = v;
+    },
+    get() {
+      if (value === undefined) {
+        throw new Error(`late-bound ${label} accessed before set() was called`);
+      }
+      return value;
+    },
+    isReady() {
+      return value !== undefined;
+    },
+  };
+}

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

@@ -0,0 +1,31 @@
+// Test utility: a MasterKeyProvider wrapper whose backing provider can be
+// swapped mid-test. Use-case: simulating KEK-rotation ("ops flipped
+// CURRENT=2") without rebuilding the whole stack + SecretsContext.
+//
+// Prod analogue: ENV swap + process restart. This helper is purely for
+// tests that want to exercise pre- and post-rotation behaviour in a
+// single suite.
+
+import type { MasterKeyProvider } from "../secrets";
+
+export type MutableMasterKeyProvider = MasterKeyProvider & {
+  // Replace the backing provider. All future wrapDek/unwrapDek/currentVersion
+  // calls delegate to `next`. Existing in-flight calls already hold a
+  // reference to the old provider's closure and finish under its contract.
+  replace(next: MasterKeyProvider): void;
+};
+
+export function createMutableMasterKeyProvider(
+  initial: MasterKeyProvider,
+): MutableMasterKeyProvider {
+  let current = initial;
+  return {
+    wrapDek: (dek) => current.wrapDek(dek),
+    unwrapDek: (e, v) => current.unwrapDek(e, v),
+    currentVersion: () => current.currentVersion(),
+    isAvailable: () => current.isAvailable(),
+    replace: (next) => {
+      current = next;
+    },
+  };
+}

package/src/testing/observability-recorder.ts

@@ -0,0 +1,54 @@
+import {
+  DEFAULT_SENSITIVE_CONFIG,
+  type MetricEvent,
+  mergeSensitiveConfig,
+  type ObservabilityOptions,
+  type ObservabilityProvider,
+  type RecordedSpan,
+  RecordingMeter,
+  RecordingTracer,
+} from "../observability";
+
+// Provider that keeps every emitted span + metric event in arrays for
+// assertion in integration tests. Use instead of ConsoleProvider when the
+// test needs to inspect the trace tree or verify metric emissions.
+export type RecordingProvider = ObservabilityProvider & {
+  readonly spans: readonly RecordedSpan[];
+  readonly metricEvents: readonly MetricEvent[];
+  // Returns spans filtered by name — handy for `.find(s => s.name === "http.request")`.
+  spansByName(name: string): readonly RecordedSpan[];
+  // All spans sharing a trace id — use this to reconstruct a single request's tree.
+  spansByTraceId(traceId: string): readonly RecordedSpan[];
+  reset(): void;
+};
+
+export function createRecordingProvider(options: ObservabilityOptions = {}): RecordingProvider {
+  const sensitiveConfig = mergeSensitiveConfig(options.sensitiveFilter ?? DEFAULT_SENSITIVE_CONFIG);
+  const spans: RecordedSpan[] = [];
+  const metricEvents: MetricEvent[] = [];
+
+  const tracer = new RecordingTracer({
+    sensitiveConfig,
+    onSpanEnd: (s) => spans.push(s),
+  });
+  const meter = new RecordingMeter((e) => metricEvents.push(e));
+
+  return {
+    name: "recording",
+    tracer,
+    meter,
+    spans,
+    metricEvents,
+    spansByName(name: string) {
+      return spans.filter((s) => s.name === name);
+    },
+    spansByTraceId(traceId: string) {
+      return spans.filter((s) => s.traceId === traceId);
+    },
+    reset() {
+      spans.length = 0;
+      metricEvents.length = 0;
+    },
+    async shutdown() {},
+  };
+}

package/src/testing/shared-entities.ts

@@ -0,0 +1,49 @@
+import { buildDrizzleTable } from "../db/table-builder";
+import {
+  createBooleanField,
+  createEntity,
+  createNumberField,
+  createTextField,
+} from "../engine/factories";
+
+// --- Shared Entity Fixtures -------------------------------------------------
+//
+// Replaces inline `createEntity(...) + buildDrizzleTable(...)` boilerplate
+// that appeared in 20+ integration tests. Pick the shape closest to what
+// the test needs; if a feature needs extras (hooks, state-machine, fields),
+// keep a local inline entity rather than bloating these shared ones.
+
+// "Just a name" — minimal entity with `name: text`, softDelete on.
+// Used by every pipeline test that only needs SOMETHING to write events
+// against (event-dispatcher*, event-retention, event-dedup, …).
+export const sharedWidgetEntity = createEntity({
+  fields: { name: createTextField({ required: true }) },
+  softDelete: true,
+});
+export const sharedWidgetTable = buildDrizzleTable("widget", sharedWidgetEntity);
+
+// User with searchable name/email fields. Used by full-stack, cascade,
+// and any test that exercises search-indexing or field-access on a
+// realistic-looking user record.
+export const sharedUserEntity = createEntity({
+  fields: {
+    email: createTextField({ required: true, format: "email", searchable: true }),
+    firstName: createTextField({ searchable: true }),
+    lastName: createTextField({ searchable: true }),
+    isEnabled: createBooleanField({ default: true }),
+  },
+  softDelete: true,
+  searchWeight: 10,
+});
+export const sharedUserTable = buildDrizzleTable("user", sharedUserEntity);
+
+// Item with name + optional price. Used by error-contract, batch,
+// projection-rebuild — tests that need "a thing you can CRUD".
+export const sharedItemEntity = createEntity({
+  fields: {
+    name: createTextField({ required: true }),
+    price: createNumberField(),
+  },
+  softDelete: true,
+});
+export const sharedItemTable = buildDrizzleTable("item", sharedItemEntity);

package/src/testing/utils.ts

@@ -0,0 +1 @@
+export const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

package/src/testing/wait-for.ts

@@ -0,0 +1,31 @@
+/**
+ * Polls a condition with escalating timeouts.
+ *
+ * Default schedule: 250ms → 1s → 3s (3 attempts).
+ * Returns immediately on success. Throws the last assertion error if all attempts fail.
+ *
+ * Usage:
+ *   await waitFor(() => {
+ *     expect(events).toHaveLength(1);
+ *   });
+ */
+export async function waitFor(
+  fn: () => void | Promise<void>,
+  options?: { delays?: number[] },
+): Promise<void> {
+  const delays = options?.delays ?? [250, 1000, 3000];
+  let lastError: unknown;
+
+  for (let i = 0; i < delays.length; i++) {
+    await new Promise((r) => setTimeout(r, delays[i]));
+    try {
+      await fn();
+      // skip: retry attempt succeeded, no further polling needed
+      return;
+    } catch (err) {
+      lastError = err;
+    }
+  }
+
+  throw lastError;
+}

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

@@ -0,0 +1,73 @@
+// Smoke-Test für die Temporal-Polyfill-Initialisierung.
+// Sicher dass nach ensureTemporalPolyfill() die wichtigsten Temporal-Typen
+// (Instant, PlainDate, ZonedDateTime) konstruktor-fähig sind.
+
+import { describe, expect, test } from "vitest";
+import { ensureTemporalPolyfill, getTemporal } from "../polyfill";
+
+describe("Temporal Polyfill", () => {
+  test("ensureTemporalPolyfill ist idempotent + Temporal nach dreifachem Aufruf nutzbar", async () => {
+    await ensureTemporalPolyfill();
+    await ensureTemporalPolyfill();
+    await ensureTemporalPolyfill();
+    // Idempotenz beweisen: nach mehrfachem Aufruf muss Temporal weiterhin
+    // konstruktor-fähig sein (kein zerstörter global state, kein verschütteter
+    // Singleton).
+    const T = getTemporal();
+    expect(T.Instant.from("2026-04-18T10:00:00Z").epochMilliseconds).toBe(
+      Date.UTC(2026, 3, 18, 10, 0, 0),
+    );
+  });
+
+  test("Temporal.Instant ist nach Polyfill konstruktor-fähig", async () => {
+    await ensureTemporalPolyfill();
+    const T = getTemporal();
+    const instant = T.Instant.from("2026-04-18T10:00:00Z");
+    expect(instant.toString()).toBe("2026-04-18T10:00:00Z");
+  });
+
+  test("Temporal.PlainDate funktioniert", async () => {
+    await ensureTemporalPolyfill();
+    const T = getTemporal();
+    const date = T.PlainDate.from("2026-04-18");
+    expect(date.toString()).toBe("2026-04-18");
+    expect(date.year).toBe(2026);
+    expect(date.month).toBe(4);
+    expect(date.day).toBe(18);
+  });
+
+  test("Temporal.ZonedDateTime mit IANA-Zone (Europe/Lisbon) funktioniert", async () => {
+    await ensureTemporalPolyfill();
+    const T = getTemporal();
+    const zdt = T.ZonedDateTime.from("2026-04-18T10:00:00[Europe/Lisbon]");
+    expect(zdt.timeZoneId).toBe("Europe/Lisbon");
+    expect(zdt.hour).toBe(10);
+    // Lisbon ist im April auf WEST (UTC+1 wegen DST), deshalb 09:00 UTC.
+    expect(zdt.toInstant().toString()).toBe("2026-04-18T09:00:00Z");
+  });
+
+  test("DST-Übergang 2026-03-29 02:30 Europe/Berlin existiert nicht", async () => {
+    await ensureTemporalPolyfill();
+    const T = getTemporal();
+    // Deutschland Spring-Forward 2026: 02:00 → 03:00 in der Nacht 28→29 März.
+    // 02:30 existiert NICHT in Berlin-TZ. Temporal handhabt das via
+    // `disambiguation: "reject"` korrekt.
+    expect(() =>
+      T.ZonedDateTime.from(
+        { year: 2026, month: 3, day: 29, hour: 2, minute: 30, timeZone: "Europe/Berlin" },
+        { disambiguation: "reject" },
+      ),
+    ).toThrow();
+  });
+
+  test("getTemporal vor Polyfill-Init throwt wenn Native fehlt", () => {
+    // Note: in unserem Test-Run ist Temporal nach dem ersten ensureTemporalPolyfill()
+    // schon installiert (Module-Singleton). Daher prüfen wir das `throws`-Verhalten
+    // nur indirekt über die Implementierung — direkter Test wäre flaky weil
+    // global state geteilt wird.
+    // Stattdessen: einfach sicherstellen dass nach Init getTemporal nicht throwt.
+    const T = getTemporal();
+    expect(T).toBeDefined();
+    expect(typeof T.Instant.from).toBe("function");
+  });
+});

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

@@ -0,0 +1,121 @@
+// Unit-Tests für ctx.tz API.
+// Test-Fokus: korrekte Konvertierung Wall-Clock+TZ ↔ Instant ↔ JSON-Pair.
+
+import { beforeAll, describe, expect, test } from "vitest";
+import { ensureTemporalPolyfill } from "../polyfill";
+import { createTzContext } from "../tz-context";
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+});
+
+describe("ctx.tz — defaults", () => {
+  test("ohne Options: tenant + user beide UTC", () => {
+    const tz = createTzContext();
+    expect(tz.tenant).toBe("UTC");
+    expect(tz.user).toBe("UTC");
+  });
+
+  test("nur tenant gesetzt: user fällt auf tenant zurück", () => {
+    const tz = createTzContext({ tenant: "Europe/Berlin" });
+    expect(tz.tenant).toBe("Europe/Berlin");
+    expect(tz.user).toBe("Europe/Berlin");
+  });
+
+  test("user-Override sticht tenant", () => {
+    const tz = createTzContext({ tenant: "Europe/Berlin", user: "Asia/Tokyo" });
+    expect(tz.tenant).toBe("Europe/Berlin");
+    expect(tz.user).toBe("Asia/Tokyo");
+  });
+});
+
+describe("ctx.tz — now / today", () => {
+  test("now() liefert Temporal.Instant", () => {
+    const tz = createTzContext();
+    const instant = tz.now();
+    expect(typeof instant.epochMilliseconds).toBe("number");
+    // Sollte nahe an aktueller Wall-Time sein (innerhalb 5 Sekunden).
+    expect(Math.abs(instant.epochMilliseconds - Date.now())).toBeLessThan(5000);
+  });
+
+  test("nowIn(tz) liefert ZonedDateTime in der richtigen Zone", () => {
+    const tz = createTzContext();
+    const zdt = tz.nowIn("Europe/Berlin");
+    expect(zdt.timeZoneId).toBe("Europe/Berlin");
+  });
+
+  test("today(tz) liefert PlainDate ohne Zeit-Komponente", () => {
+    const tz = createTzContext();
+    const today = tz.today("Europe/Lisbon");
+    // PlainDate hat keine .hour-Property — wenn es eines hätte, wäre's ein
+    // ZonedDateTime und der Test würde TypeError werfen.
+    expect("hour" in today).toBe(false);
+    expect(today.toString()).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+
+  test("todayRange(tz) liefert UTC-Instants für DB-Range-Query", () => {
+    const tz = createTzContext();
+    const range = tz.todayRange("Europe/Berlin");
+    // Differenz zwischen start + end ist genau 24h (oder 23/25h bei DST).
+    const diffHours =
+      (range.end.epochMilliseconds - range.start.epochMilliseconds) / (1000 * 60 * 60);
+    expect(diffHours).toBeGreaterThanOrEqual(23);
+    expect(diffHours).toBeLessThanOrEqual(25);
+  });
+});
+
+describe("ctx.tz — parse + JSON-Pair Konvertierungen", () => {
+  test("parse(wallClock, tz) liefert ZonedDateTime mit korrekter UTC-Konvertierung", () => {
+    const tz = createTzContext();
+    // 2026-04-03 10:00 Lisbon = 09:00 UTC (WEST = UTC+1)
+    const zdt = tz.parse("2026-04-03T10:00:00", "Europe/Lisbon");
+    expect(zdt.timeZoneId).toBe("Europe/Lisbon");
+    expect(zdt.toInstant().toString()).toBe("2026-04-03T09:00:00Z");
+  });
+
+  test("toLocatedJson(zdt) liefert { at, tz } OHNE Offset-Marker", () => {
+    const tz = createTzContext();
+    const zdt = tz.parse("2026-04-03T10:00:00", "Europe/Lisbon");
+    const json = tz.toLocatedJson(zdt);
+    expect(json).toEqual({ at: "2026-04-03T10:00:00", tz: "Europe/Lisbon" });
+    // Kein "Z", kein "+01:00" im at-Feld — sonst ist die JSON-Form nicht
+    // mehr idiotensicher.
+    expect(json.at).not.toContain("Z");
+    expect(json.at).not.toContain("+");
+  });
+
+  test("fromLocatedJson({ at, tz }) ist Inverse zu toLocatedJson", () => {
+    const tz = createTzContext();
+    const original = tz.parse("2026-04-03T10:00:00", "Europe/Lisbon");
+    const json = tz.toLocatedJson(original);
+    const restored = tz.fromLocatedJson(json);
+    expect(restored.toInstant().equals(original.toInstant())).toBe(true);
+    expect(restored.timeZoneId).toBe(original.timeZoneId);
+  });
+
+  test("Round-Trip funktioniert über DST-Übergang (Lisbon-Sommerzeit-Ende)", () => {
+    const tz = createTzContext();
+    // 2026-10-25 in Lisbon: Fall-Back von 02:00 → 01:00. Wir nehmen 14:00,
+    // was eindeutig im WET ist (UTC+0).
+    const zdt = tz.parse("2026-10-25T14:00:00", "Europe/Lisbon");
+    const json = tz.toLocatedJson(zdt);
+    expect(json.at).toBe("2026-10-25T14:00:00");
+    expect(json.tz).toBe("Europe/Lisbon");
+    const restored = tz.fromLocatedJson(json);
+    // Nach DST-Wechsel ist Lisbon UTC+0 → 14:00 lokal = 14:00 UTC.
+    expect(restored.toInstant().toString()).toBe("2026-10-25T14:00:00Z");
+  });
+});
+
+describe("ctx.tz — Cross-Server-TZ Garantie", () => {
+  test("derselbe Wall-Clock+TZ liefert denselben UTC-Instant unabhängig vom Server-TZ", () => {
+    // Das ist der Kern der Migration: ein Server in Berlin und einer in
+    // Tokyo schicken denselben "Pickup 10:00 Lissabon" — beide müssen den
+    // gleichen UTC-Instant produzieren. Temporal erfüllt das per Design,
+    // wir prüfen es zur Sicherheit.
+    const tz = createTzContext();
+    const zdt1 = tz.parse("2026-04-03T10:00:00", "Europe/Lisbon");
+    const zdt2 = tz.fromLocatedJson({ at: "2026-04-03T10:00:00", tz: "Europe/Lisbon" });
+    expect(zdt1.toInstant().equals(zdt2.toInstant())).toBe(true);
+  });
+});

package/src/time/index.ts

@@ -0,0 +1,21 @@
+// Time-Modul: Temporal-Polyfill + ctx.tz Helper.
+//
+// Aktueller Stand (Iteration 1-4 von Gap-03 in samples/beammycar/MIGRATION.md):
+//   - ensureTemporalPolyfill: installiert Temporal global wenn nötig
+//   - getTemporal: type-safer Zugriff auf globalThis.Temporal
+//   - createTzContext: ctx.tz Factory mit now/today/parse/toLocatedJson/...
+//   - LocatedTimestampJson: API-Boundary-Form { at, 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 { ensureTemporalPolyfill, getTemporal } from "./polyfill";
+export {
+  createTzContext,
+  createTzContextAsync,
+  type LocatedTimestampJson,
+  type TzContext,
+  type TzContextOptions,
+} from "./tz-context";

package/src/time/polyfill.ts

@@ -0,0 +1,70 @@
+// Temporal-Polyfill-Initialisierung.
+//
+// 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).
+//
+// 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.
+
+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.
+ */
+export async function ensureTemporalPolyfill(): Promise<void> {
+  // skip: Idempotenz — Polyfill bereits installiert in einem früheren Aufruf.
+  if (polyfillInstalled) return;
+  if (polyfillPromise) {
+    await polyfillPromise;
+    // skip: Concurrent-Boot — anderer Aufruf hat die Installation übernommen.
+    return;
+  }
+
+  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.
+      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.
+ */
+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.",
+    );
+  }
+  return Temporal;
+}