@cosmicdrift/kumiko-framework 0.165.0 → 2.0.0

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/geo-tz.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/geo-tz";
+export type * from "@cosmicdrift/kumiko-types/geo-tz";

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,25 +1,29 @@
-// 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.
+// `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.
 //
-// Die reinen Type-Contracts (TzContext, TzContextOptions, LocatedTimestampJson)
-// leben in @cosmicdrift/kumiko-types/tz-context — hier nur die Factories.
+// The pure type contracts (TzContext, TzContextOptions, LocatedTimestampJson)
+// live in @cosmicdrift/kumiko-types/tz-context — only the factories are here.
 
 import type { TzContext, TzContextOptions } from "@cosmicdrift/kumiko-types/tz-context";
-import { ensureTemporalPolyfill, getTemporal } from "./polyfill";
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import { ensureTemporalPolyfill } from "./polyfill";
 
+// 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,
@@ -27,12 +31,11 @@ export type {
 } 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;
@@ -40,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(
@@ -80,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();

package/src/utils/__tests__/safe-json-temporal.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { Temporal as PolyfillTemporal } from "temporal-polyfill";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { stringifyJson } from "../safe-json";
+
+describe("stringifyJson — Temporal.Instant (native + polyfill)", () => {
+  test("serializes polyfill Instant", () => {
+    const instant = PolyfillTemporal.Instant.from("2026-01-01T00:00:00Z");
+    expect(stringifyJson({ at: instant })).toBe('{"at":"2026-01-01T00:00:00Z"}');
+  });
+
+  test("serializes ambient/native Instant when present", async () => {
+    await ensureTemporalPolyfill();
+    const T = (globalThis as unknown as { Temporal: typeof PolyfillTemporal }).Temporal;
+    const instant = T.Instant.from("2026-06-15T12:00:00Z");
+    expect(stringifyJson({ at: instant })).toBe('{"at":"2026-06-15T12:00:00Z"}');
+  });
+});

package/src/utils/safe-json.ts

@@ -29,6 +29,15 @@ export function parseJsonOrThrow<T>(raw: string, context: string): T {
   }
 }
 
+/** True for native or polyfill Temporal.Instant (distinct constructors). */
+function isTemporalInstant(v: unknown): v is { toString(): string } {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    Object.prototype.toString.call(v) === "[object Temporal.Instant]"
+  );
+}
+
 /** JSON.stringify that survives BigInt / Temporal values from DB rows. */
 export function stringifyJson(value: unknown): string {
   return JSON.stringify(value, (_key, v) => {
@@ -43,7 +52,10 @@ export function stringifyJson(value: unknown): string {
       }
       return v.toString();
     }
-    if (v instanceof Temporal.Instant) return v.toString();
+    // Duck-tag, not instanceof: ensureTemporalPolyfill keeps native
+    // globalThis.Temporal when present, so DB Instants may be native while
+    // other code paths use temporal-polyfill's Instant (fw#1550 / Bugbot).
+    if (isTemporalInstant(v)) return v.toString();
     return v;
   });
 }

package/src/engine/__tests__/registry-facade-sweep.test.ts

@@ -1,80 +0,0 @@
-// Dilution reclaim: integration lcov registers every facade getter as DA:N,0
-// when the file loads, but unit only instruments getters that a test touches.
-// Calling every getter once in unit raises LF+LH so the badge merge stops
-// counting those one-liners as uncovered.
-
-import { describe, expect, test } from "bun:test";
-import { createRegistry } from "../registry";
-
-describe("buildRegistryFacade — getter sweep", () => {
-  test("empty registry: every getter is callable without throw", () => {
-    const r = createRegistry([]);
-
-    expect(r.features.size).toBe(0);
-    expect(r.getFeature("x")).toBeUndefined();
-    expect(r.hasRateLimitedHandler()).toBe(false);
-    expect(r.getEntity("x")).toBeUndefined();
-    expect(r.getAllEntities().size).toBe(0);
-    expect(r.getWriteHandler("x")).toBeUndefined();
-    expect(r.getQueryHandler("x")).toBeUndefined();
-    expect(r.getAllQueryHandlers().size).toBe(0);
-    expect(r.getSearchableFields("x")).toEqual([]);
-    expect(r.getSortableFields("x")).toEqual([]);
-    expect(r.getRelations("x")).toEqual({});
-    expect(r.getSearchIncludes("x").size).toBe(0);
-    expect(r.getIncomingRelations("x")).toEqual([]);
-    expect(r.getPreSaveHooks("x")).toEqual([]);
-    expect(r.getPostSaveHooks("x")).toEqual([]);
-    expect(r.getPreDeleteHooks("x")).toEqual([]);
-    expect(r.getPostDeleteHooks("x")).toEqual([]);
-    expect(r.getPreQueryHooks("x")).toEqual([]);
-    expect(r.getPostQueryHooks("x")).toEqual([]);
-    expect(r.getEntityPostSaveHooks("x")).toEqual([]);
-    expect(r.getEntityPreDeleteHooks("x")).toEqual([]);
-    expect(r.getEntityPostDeleteHooks("x")).toEqual([]);
-    expect(r.getEntityPostQueryHooks("x")).toEqual([]);
-    expect(r.getSearchPayloadExtensions("x")).toEqual([]);
-    expect(r.getAllTranslations()).toBeDefined();
-    expect(r.getHandlerEntity("x")).toBeUndefined();
-    expect(r.isHandlerSystemScoped("x")).toBe(false);
-    expect(r.getHandlerFeature("x")).toBeUndefined();
-    expect(r.getAllMetrics().size).toBe(0);
-    expect(r.getAllSecretKeys().size).toBe(0);
-    expect(r.getSecretKey("x")).toBeUndefined();
-    expect(r.getConfigKey("x")).toBeUndefined();
-    expect(r.getAllConfigKeys().size).toBe(0);
-    expect(r.getJob("x")).toBeUndefined();
-    expect(r.getAllJobs().size).toBe(0);
-    expect(r.getEvent("x")).toBeUndefined();
-    expect(r.getEventUpcasters().size).toBe(0);
-    expect(r.getExtension("x")).toBeUndefined();
-    expect(r.getExtensionUsages("x")).toEqual([]);
-    expect(r.getAllExtensionSelectors().size).toBe(0);
-    expect(r.getAllNotifications().size).toBe(0);
-    expect(r.getAllReferenceData()).toEqual([]);
-    expect(r.getAllConfigSeeds()).toEqual([]);
-    expect(r.getProjectionsForSource("x")).toEqual([]);
-    expect(r.getAllProjections().size).toBe(0);
-    expect(r.getAllStoreTables().size).toBe(0);
-    expect(r.getAllMultiStreamProjections().size).toBe(0);
-    expect(r.getMultiStreamProjectionFeature("x")).toBeUndefined();
-    expect(r.getAuthClaimsHooks()).toEqual([]);
-    expect(r.getAllClaimKeys().size).toBe(0);
-    expect(r.getClaimKey("x")).toBeUndefined();
-    expect(r.getAllScreens().size).toBe(0);
-    expect(r.getScreen("x")).toBeUndefined();
-    expect(r.getScreenFeature("x")).toBeUndefined();
-    expect(r.getScreensByEntity("x")).toEqual([]);
-    expect(r.getAllNavs().size).toBe(0);
-    expect(r.getNav("x")).toBeUndefined();
-    expect(r.getNavFeature("x")).toBeUndefined();
-    expect(r.getNavsByParent("x")).toEqual([]);
-    expect(r.getTopLevelNavs()).toEqual([]);
-    expect(r.getAllWorkspaces().size).toBe(0);
-    expect(r.getWorkspace("x")).toBeUndefined();
-    expect(r.getWorkspaceFeature("x")).toBeUndefined();
-    expect(r.getWorkspaceNavs("x")).toEqual([]);
-    expect(r.getDefaultWorkspace()).toBeUndefined();
-    expect(r.getTreeActions("x")).toBeUndefined();
-  });
-});