@cosmicdrift/kumiko-framework 0.105.1 → 0.108.0

package/src/pipeline/dispatcher.ts

@@ -1,7 +1,7 @@
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbRow, DbTx } from "../db/connection";
 import { selectRowForUpdateById } from "../db/queries/entity-read";
-import { selectMany, transaction } from "../db/query";
+import { asEntityTableMeta, selectMany, transaction } from "../db/query";
 import { buildEntityTable, toSnakeCase } from "../db/table-builder";
 import { createTenantDb } from "../db/tenant-db";
 import { hasAccess } from "../engine/access";
@@ -717,12 +717,8 @@ export function createDispatcher(
       user,
       ip: reqCtx?.ip,
     });
-    // skip: ip-bucketed handler called from a non-HTTP entry point (job, seed,
-    //       MSP-apply) — no client IP to bucket on, nothing to enforce. Pass
-    //       through BEFORE requiring a resolver, so system/seed writes through
-    //       such a handler don't need a RateLimitResolver wired (the es-ops
-    //       seed dispatcher has none). L1/L2 middleware handle the HTTP-side
-    //       ip caps.
+    // skip: ip-bucket + no IP (non-HTTP entry point) — pass through before
+    // requiring a resolver; HTTP path always has an IP + L1/L2 middleware.
     if (bucket.kind === "skip") return;
     if (!context.rateLimit) {
       throw new InternalError({
@@ -1162,9 +1158,7 @@ export function createDispatcher(
           // can false-pass; optimistic locking would catch it later, but with
           // a less specific error. Falls back to a plain SELECT if no tx is
           // active (tests without a DB connection).
-          const tableName = String(
-            (table as { [key: symbol]: unknown })[Symbol.for("kumiko:schema:Name")],
-          );
+          const tableName = asEntityTableMeta(table)?.tableName ?? "";
           const rows = tx
             ? await selectRowForUpdateById(handlerContext.db, tableName, id)
             : await selectMany(handlerContext.db, table, { id });

package/src/pipeline/msp-rebuild.ts

@@ -11,11 +11,16 @@ import {
   rebuildMetaOrThrow,
   swapShadowIntoLive,
 } from "../db/queries/shadow-swap";
-import { selectMany } from "../db/query";
+import { runInSavepoint, selectMany } from "../db/query";
 import type { Registry, TenantId } from "../engine/types";
 import { InternalError } from "../errors";
 import { eventsTable, type StoredEvent, upcastStoredEvent } from "../event-store";
 import { loadAggregate, loadAggregateAsOf } from "../event-store/event-store";
+import {
+  createRebuildDeadLetterTable,
+  recordRebuildDeadLetters,
+  type SkippedApply,
+} from "../event-store/rebuild-dead-letter";
 import { upcastStoredEvents } from "../event-store/upcaster";
 import { emitProjectionRebuild } from "../observability/standard-metrics";
 import type { Meter } from "../observability/types/metric";
@@ -123,12 +128,21 @@ export async function rebuildMultiStreamProjection(
 
   const meta = rebuildMetaOrThrow(msp.table, mspName);
 
+  // Declared per-projection (MspErrorMode): the rebuild policy falls back to
+  // continuous when omitted — previously declared but never honored here.
+  const skipApplyErrors =
+    (msp.errorMode?.rebuild ?? msp.errorMode?.continuous)?.skipApplyErrors === true;
+
   const startedAt = Date.now();
   let eventsProcessed = 0;
   let lastProcessedEventId = 0n;
+  const skipped: SkippedApply[] = [];
 
   try {
     await ensureRebuildSchema(db);
+    // Outside the rebuild tx, like the schema: idempotent DDL colliding
+    // inside the tx would roll the whole replay back.
+    if (skipApplyErrors) await createRebuildDeadLetterTable(db);
     await db.begin(async (tx: DbTx) => {
       await resetConsumerForMspRebuild(tx, mspName, SHARED_INSTANCE_SENTINEL);
       await selectConsumerForUpdate(tx, mspName, SHARED_INSTANCE_SENTINEL);
@@ -178,13 +192,31 @@ export async function rebuildMultiStreamProjection(
           });
           const applyFn = msp.apply[row.type];
           if (!applyFn) continue;
-          const rebuildCtx = createRebuildCtx(registry, tx, row.tenantId);
-          await applyFn(storedEvent, tx, rebuildCtx);
+          if (skipApplyErrors) {
+            // Driver-native savepoint: a throwing SQL statement would
+            // otherwise poison the rebuild tx (25P02) AND make the driver
+            // reject the whole begin() even after a caught error. Apply +
+            // ctx run on the savepoint-scoped handle.
+            try {
+              await runInSavepoint(tx, async (sp) => {
+                const rebuildCtx = createRebuildCtx(registry, sp as DbRunner, row.tenantId);
+                await applyFn(storedEvent, sp as DbRunner, rebuildCtx);
+              });
+            } catch (e) {
+              skipped.push({ event: storedEvent, error: e });
+            }
+          } else {
+            const rebuildCtx = createRebuildCtx(registry, tx, row.tenantId);
+            await applyFn(storedEvent, tx, rebuildCtx);
+          }
           eventsProcessed++;
           lastProcessedEventId = row.id;
         }
       }
 
+      if (skipped.length > 0) {
+        await recordRebuildDeadLetters(tx, mspName, skipped);
+      }
       await updateConsumerRebuildCursor(
         tx,
         mspName,
@@ -210,6 +242,7 @@ export async function rebuildMultiStreamProjection(
   const result: RebuildResult = {
     projection: mspName,
     eventsProcessed,
+    eventsSkipped: skipped.length,
     lastProcessedEventId,
     durationMs: Date.now() - startedAt,
   };

package/src/pipeline/projection-rebuild.ts

@@ -13,7 +13,7 @@ import {
   rebuildMetaOrThrow,
   swapShadowIntoLive,
 } from "../db/queries/shadow-swap";
-import { coerceRow, extractTableInfo, selectMany } from "../db/query";
+import { coerceRow, extractTableInfo, runInSavepoint, selectMany } from "../db/query";
 import type { Registry, TenantId } from "../engine/types";
 import {
   eventsTable,
@@ -22,6 +22,11 @@ import {
   upcastStoredEvent,
 } from "../event-store";
 import type { EventMetadata } from "../event-store/event-store";
+import {
+  createRebuildDeadLetterTable,
+  recordRebuildDeadLetters,
+  type SkippedApply,
+} from "../event-store/rebuild-dead-letter";
 import { emitProjectionRebuild } from "../observability/standard-metrics";
 import type { Meter } from "../observability/types/metric";
 import { projectionStateTable } from "./projection-state";
@@ -119,7 +124,12 @@ function rowToStoredEvent(row: StoredEventRow): StoredEvent {
 
 export type RebuildResult = {
   readonly projection: string;
+  // Events consumed from the log — includes quarantined ones (the cursor
+  // advanced past them).
   readonly eventsProcessed: number;
+  // Poison events quarantined into kumiko_rebuild_dead_letters this run.
+  // Always 0 unless quarantine mode was active (#760).
+  readonly eventsSkipped: number;
   readonly lastProcessedEventId: bigint;
   readonly durationMs: number;
 };
@@ -145,12 +155,25 @@ type RebuildDeps = {
   // on the live table; if a long-running writer holds it past this, the rebuild
   // fails loud instead of hanging. Defaults to DEFAULT_FENCE_LOCK_TIMEOUT_MS.
   readonly fenceLockTimeoutMs?: number;
+  // Apply-error policy for THIS run. Default strict: the first throwing
+  // apply aborts the rebuild (tx rollback, status "failed") — a poison
+  // event makes the projection permanently un-rebuildable (#760).
+  // skipApplyErrors: true confines every apply to a savepoint; a throwing
+  // apply is rolled back, recorded into kumiko_rebuild_dead_letters and
+  // skipped, and the rebuild completes without its effect. Opt-in for
+  // operators unblocking a pinned rebuild — the projection then knowingly
+  // misses the quarantined events until they are repaired and replayed.
+  readonly errorPolicy?: { readonly skipApplyErrors?: boolean };
   // Test-only seam: fires once after the unlocked bulk drain and before the
   // cutover fence. Lets a concurrency test inject a committed write into the
   // replay window deterministically. The `__test_` prefix marks it test-only:
   // a slow callback here delays the cutover fence acquisition, widening the
   // window in which concurrent writers can still commit below the cursor.
   readonly __test_onBeforeFence?: () => void | Promise<void>;
+  // Test-only seam: fires each time the shadow table is (re)built. The #443
+  // recompute is idempotent on final values, so only a call-count seam like
+  // this can prove it didn't fire on a clean, non-concurrent rebuild.
+  readonly __test_onBuildShadowTable?: () => void;
 };
 
 export async function rebuildProjection(
@@ -170,7 +193,7 @@ export async function rebuildProjection(
   const meta = rebuildMetaOrThrow(projection.table, projectionName);
 
   const sources = Array.isArray(projection.source) ? projection.source : [projection.source];
-  const sourcesList = [...sources];
+  const sourcesList = [...sources, ...(projection.extraSources ?? [])];
   const subscribedList = Object.keys(projection.apply);
   // Upcasters run at read time: older stored payloads get walked through the
   // registered r.eventMigration chain until their shape matches the current
@@ -181,6 +204,11 @@ export async function rebuildProjection(
   const startedAt = Date.now();
   let eventsProcessed = 0;
   let lastProcessedEventId = 0n;
+  const skipApplyErrors = deps.errorPolicy?.skipApplyErrors === true;
+  // Quarantined events, collected in memory and written once after the
+  // replay settles — the #443 full-re-replay path would otherwise duplicate
+  // the dead-letter rows.
+  let skipped: SkippedApply[] = [];
 
   // One chronological batch of events after lastProcessedEventId, applied into
   // the shadow. Returns the batch size so the caller can detect the tail
@@ -204,7 +232,21 @@ export async function rebuildProjection(
       // skip: apply-key validation ensures every subscribed type has a handler;
       //       defensive check against runtime-mutated registry
       if (!applyFn) continue;
-      await applyFn(storedEvent, tx);
+      if (skipApplyErrors) {
+        // Driver-native savepoint: a throwing SQL statement would otherwise
+        // poison the rebuild tx (25P02) AND make the driver reject the whole
+        // begin() even after a caught error. The apply runs on the
+        // savepoint-scoped handle so its statements are confined.
+        try {
+          await runInSavepoint(tx, async (sp) => {
+            await applyFn(storedEvent, sp as DbTx, projection.table);
+          });
+        } catch (e) {
+          skipped.push({ event: storedEvent, error: e });
+        }
+      } else {
+        await applyFn(storedEvent, tx, projection.table);
+      }
       eventsProcessed++;
       lastProcessedEventId = row.id;
     }
@@ -213,9 +255,13 @@ export async function rebuildProjection(
 
   try {
     await ensureRebuildSchema(db);
+    // Outside the rebuild tx, like the schema: idempotent DDL colliding
+    // inside the tx would roll the whole replay back.
+    if (skipApplyErrors) await createRebuildDeadLetterTable(db);
     await db.begin(async (tx: DbTx) => {
       await markProjectionRebuilding(tx, projectionName);
       await buildShadowTable(tx, meta);
+      deps.__test_onBuildShadowTable?.();
 
       // A projection that subscribes to nothing has no events to replay and no
       // live writer touching its table — skip straight to swapping the empty
@@ -253,14 +299,19 @@ export async function rebuildProjection(
         const expectedEvents = await countSubscribedEvents(tx, sourcesList, subscribedList);
         if (expectedEvents > BigInt(eventsProcessed)) {
           await buildShadowTable(tx, meta);
+          deps.__test_onBuildShadowTable?.();
           lastProcessedEventId = 0n;
           eventsProcessed = 0;
+          skipped = [];
           while ((await drainBatch(tx)) === REBUILD_BATCH_SIZE) {
             // re-replay the full log into the fresh shadow
           }
         }
       }
 
+      if (skipped.length > 0) {
+        await recordRebuildDeadLetters(tx, projectionName, skipped);
+      }
       await finalizeProjectionRebuild(tx, projectionName, lastProcessedEventId);
       await swapShadowIntoLive(tx, meta.tableName);
     });
@@ -286,6 +337,7 @@ export async function rebuildProjection(
   const result: RebuildResult = {
     projection: projectionName,
     eventsProcessed,
+    eventsSkipped: skipped.length,
     lastProcessedEventId,
     durationMs: Date.now() - startedAt,
   };

package/src/pipeline/projections-runner.ts

@@ -51,6 +51,6 @@ export async function runProjectionsForEvent(
     const applyFn = proj.apply[event.type];
     // skip: this projection doesn't care about this event type
     if (!applyFn) continue;
-    await applyFn(event, tx);
+    await applyFn(event, tx, proj.table);
   }
 }

package/src/schema-cli.ts

@@ -44,17 +44,28 @@ export type SchemaCliOut = {
 
 const SNAPSHOT_FILENAME = ".snapshot.json";
 
-async function loadEntityMetasFromApp(
-  schemaFile: string,
-): Promise<Parameters<typeof renderTablesDdl>[0]> {
+type SchemaMod = {
+  readonly entityMetas: Parameters<typeof renderTablesDdl>[0];
+  readonly features?: unknown;
+};
+
+// Single load-path for kumiko/schema.ts (512/3) — `generate` and `validate`
+// both need ENTITY_METAS (and validate additionally wants FEATURES); this is
+// the one place that enforces "ENTITY_METAS must be an array" so the two
+// commands can't drift on the check or its wording. Throws — callers that
+// want a graceful exit code (validate) catch it themselves.
+async function loadSchemaModFromApp(schemaFile: string): Promise<SchemaMod> {
   // bun imports TS directly — no spawn needed.
-  const mod = (await import(schemaFile)) as { ENTITY_METAS?: unknown };
+  const mod = (await import(schemaFile)) as { ENTITY_METAS?: unknown; FEATURES?: unknown };
   if (!Array.isArray(mod.ENTITY_METAS)) {
     throw new Error(
       `Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`,
     );
   }
-  return mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0];
+  return {
+    entityMetas: mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0],
+    features: mod.FEATURES,
+  };
 }
 
 function nextSequenceNumber(migrationsDir: string): number {
@@ -132,7 +143,7 @@ export async function runSchemaCli(
         out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
         return 1;
       }
-      const metas = await loadEntityMetasFromApp(schemaFile);
+      const { entityMetas: metas } = await loadSchemaModFromApp(schemaFile);
       const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
       const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
       const result = generateMigration({
@@ -191,20 +202,18 @@ export async function runSchemaCli(
         out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
         return 1;
       }
-      const mod = (await import(schemaFile)) as {
-        ENTITY_METAS?: unknown;
-        FEATURES?: unknown;
-      };
-      if (!Array.isArray(mod.ENTITY_METAS)) {
-        out.err(
-          `  Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`,
-        );
+      let schemaMod: SchemaMod;
+      try {
+        schemaMod = await loadSchemaModFromApp(schemaFile);
+      } catch (e) {
+        out.err(`  ${e instanceof Error ? e.message : String(e)}`);
         return 1;
       }
+      const mod = { FEATURES: schemaMod.features };
       let ok = true;
 
       // 1. Schema drift — compute the diff, never write.
-      const metas = mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0];
+      const metas = schemaMod.entityMetas;
       const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
       const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
       const drift = generateMigration({

package/src/secrets/__tests__/contains-secret.test.ts

@@ -32,6 +32,18 @@ export type _R6TypeAssertions = [
   // the backstop. This is what keeps generic-over-response handlers compiling.
   Expect<Equal<ContainsSecret<unknown>, false>>,
   Expect<Equal<ContainsSecret<never>, false>>,
+  // 556/3: ContainsSecret<A | B> distributes over the union (naked type
+  // param) to `ContainsSecret<A> | ContainsSecret<B>` = `boolean`, not the
+  // literal `true` — pinned here so a future change to this predicate can't
+  // silently regress it. The actual leak-guard in define-handler.ts compares
+  // via `true extends ContainsSecret<TData>` (556/1) instead of `ContainsSecret<
+  // TData> extends true`, which is fail-closed for `boolean` either way.
+  Expect<Equal<ContainsSecret<{ ok: true } | { s: Secret<string> }>, boolean>>,
+  // 556/2: Map/Set are explicit SafeLeaf members now — pins that the runtime
+  // guard's "walk Map/Set entries separately" intent is mirrored, not an
+  // accidental compile-time blind spot.
+  Expect<Equal<ContainsSecret<Map<string, Secret<string>>>, false>>,
+  Expect<Equal<ContainsSecret<Set<Secret<string>>>, false>>,
 ];
 
 const schema = z.object({ q: z.string() });
@@ -57,6 +69,28 @@ function genericResponseHandler<K extends string>(kind: K) {
 }
 void genericResponseHandler;
 
+// 556/1: ContainsSecret<A | B> distributes over the union (naked type param
+// in the condition) to `ContainsSecret<A> | ContainsSecret<B>` = `boolean`,
+// not the literal `true` — a check written as `ContainsSecret<TData> extends
+// true` silently passes a union with a leak hidden in ONE branch. Both
+// assertions below must hold: the guard rejects the leaking union AND still
+// accepts the clean one, proving the fix (membership form on the phantom
+// param) is fail-closed for unions, not just for a bare Secret<>.
+declare const leakingUnion: { ok: true } | { apiKey: Secret<string> };
+// @ts-expect-error — R6: a Secret<> hidden in one union branch must still leak-guard
+defineQueryHandler({
+  name: "t:query:union-leak",
+  schema,
+  handler: async () => leakingUnion,
+});
+
+declare const cleanUnion: { ok: true } | { id: string };
+defineQueryHandler({
+  name: "t:query:union-clean",
+  schema,
+  handler: async () => cleanUnion,
+});
+
 describe("R6 ContainsSecret", () => {
   test("a clean query handler still builds — the guard param is invisible", () => {
     const def = defineQueryHandler({

package/src/secrets/types.ts

@@ -56,6 +56,11 @@ type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 
 // Opaque built-in leaves a response legitimately carries; never recurse into
 // them. Extend when the bundled-features tsc sweep surfaces a real leaf type.
+// Map/Set (556/2): `keyof Map<K,V>` yields method names, not V, so these
+// already fell through to `false` via the object-mapped-type branch — listed
+// explicitly here so the compile-time treatment matches leak-guard.ts's
+// runtime `instanceof Map`/`instanceof Set` branch (walk entries separately)
+// instead of looking like an oversight.
 type SafeLeaf =
   | Date
   | RegExp
@@ -66,7 +71,9 @@ type SafeLeaf =
   | Temporal.PlainTime
   | Temporal.PlainYearMonth
   | Temporal.PlainMonthDay
-  | Temporal.Duration;
+  | Temporal.Duration
+  | Map<unknown, unknown>
+  | Set<unknown>;
 
 export type ContainsSecret<T> = [T] extends [never]
   ? false

package/src/testing/db-cleanup.ts

@@ -32,7 +32,10 @@ function resolveClearableTable(table: ClearableTable): unknown {
 /** Delete all rows from each table (order preserved — FK-sensitive callers order explicitly). */
 export async function clearTables(db: AnyDb, tables: readonly ClearableTable[]): Promise<void> {
   for (const table of tables) {
-    await deleteMany(db, resolveClearableTable(table), {});
+    // Test-teardown truncate: resolveClearableTable returns `unknown` (string
+    // name or table object). The brand-strip cast is the sanctioned bypass —
+    // clearing a managed projection between tests is not a production write.
+    await deleteMany(db, resolveClearableTable(table) as EntityTableMeta, {});
   }
 }
 

package/src/testing/index.ts

@@ -31,6 +31,7 @@ export {
   createRecordingProvider,
   type RecordingProvider,
 } from "./observability-recorder";
+export { deleteRows, seedRow, seedRows, updateRows } from "./seed";
 export {
   sharedItemEntity,
   sharedItemTable,

package/src/testing/seed.ts

@@ -0,0 +1,50 @@
+// Test-only ES-bypass: seed / mutate a managed projection directly, skipping
+// the event log. Production code CANNOT do this — the write helpers reject a
+// branded EntityTable at compile time (#742). Tests seed read-model state to
+// arrange a scenario without driving the full event path; a projection rebuild
+// is not part of the test lifecycle, so eventless writes are safe here. The
+// `as EntityTableMeta` strips the executor-only brand at this single sanctioned
+// seam — the signatures mirror the query helpers so a call-site migration is a
+// plain identifier rename.
+
+import {
+  type AnyDb,
+  deleteMany,
+  insertMany,
+  insertOne,
+  updateMany,
+  type WhereObject,
+} from "../bun-db/query";
+import type { EntityTableMeta } from "../db/entity-table-meta";
+import type { EntityTable } from "../db/table-builder";
+
+type SeedTable = EntityTable | EntityTableMeta;
+
+export function seedRow<TRow = unknown>(
+  db: AnyDb,
+  table: SeedTable,
+  values: Record<string, unknown>,
+): Promise<TRow | undefined> {
+  return insertOne<TRow>(db, table as EntityTableMeta, values);
+}
+
+export function seedRows<TRow = unknown>(
+  db: AnyDb,
+  table: SeedTable,
+  rows: ReadonlyArray<Record<string, unknown>>,
+): Promise<readonly TRow[]> {
+  return insertMany<TRow>(db, table as EntityTableMeta, rows);
+}
+
+export function updateRows<TRow = unknown>(
+  db: AnyDb,
+  table: SeedTable,
+  set: Record<string, unknown>,
+  where: WhereObject,
+): Promise<readonly TRow[]> {
+  return updateMany<TRow>(db, table as EntityTableMeta, set, where);
+}
+
+export function deleteRows(db: AnyDb, table: SeedTable, where: WhereObject): Promise<void> {
+  return deleteMany(db, table as EntityTableMeta, where);
+}

package/src/time/__tests__/boot-tz-warning.test.ts

@@ -9,6 +9,13 @@ describe("warnIfNonUtcServerTimeZone", () => {
     expect(messages).toHaveLength(0);
   });
 
+  test.each(["GMT", "Etc/UTC"])("warnt nicht bei UTC-äquivalenter Zone %s", (zone) => {
+    const messages: string[] = [];
+    const warned = warnIfNonUtcServerTimeZone(zone, (m) => messages.push(m));
+    expect(warned).toBe(false);
+    expect(messages).toHaveLength(0);
+  });
+
   test("warnt bei nicht-UTC Zone, nennt Zone + UTC-Hinweis", () => {
     const messages: string[] = [];
     const warned = warnIfNonUtcServerTimeZone("Europe/Berlin", (m) => messages.push(m));
@@ -18,7 +25,22 @@ describe("warnIfNonUtcServerTimeZone", () => {
     expect(messages[0]).toContain("UTC");
   });
 
-  test("Default-Aufruf liest die Prozess-TZ ohne zu werfen", () => {
-    expect(() => warnIfNonUtcServerTimeZone(undefined, () => {})).not.toThrow();
+  test("Default-Aufruf liest die ECHTE Prozess-TZ (ambient, nicht injiziert)", () => {
+    // Das ist der einzige Test der ambient-TZ liest statt sie zu injizieren —
+    // der Grund warum der tz-matrix-CI-Job (4 Legs: LA/Berlin/Tokyo/Apia)
+    // überhaupt einen Unterschied zwischen den Legs sehen kann. Ohne diese
+    // Assertion wäre "läuft in jeder Zone ohne zu werfen" in allen 4 Legs
+    // identisch grün — die beworbene Schutzwirkung ("ein `new Date(wallClock)`-
+    // Bug bricht HIER") würde nicht existieren.
+    const ambientTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const messages: string[] = [];
+    const warned = warnIfNonUtcServerTimeZone(undefined, (m) => messages.push(m));
+    if (ambientTz === "UTC") {
+      expect(warned).toBe(false);
+      expect(messages).toHaveLength(0);
+    } else {
+      expect(warned).toBe(true);
+      expect(messages[0]).toContain(ambientTz);
+    }
   });
 });

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

@@ -55,11 +55,17 @@ describe("ctx.tz — GeoTzProvider seam", () => {
   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/);
+    // Regression (680/2): this message must say the PROVIDER lacks
+    // fromAddress, not the misleading "no provider configured" message.
+    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(
+      /GeoTzProvider that implements fromAddress/,
+    );
   });
 
-  test("fromAddress wirft ohne Provider", async () => {
+  test("fromAddress wirft ohne Provider — eigene Message, nicht die Provider-ohne-fromAddress-Message", async () => {
     const tz = createTzContext();
-    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(/GeoTzProvider/);
+    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(
+      /requires a GeoTzProvider — inject one/,
+    );
   });
 });

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

@@ -25,6 +25,15 @@ describe("isValidIanaTimeZone", () => {
     expect(isValidIanaTimeZone(value)).toBe(false);
   });
 
+  // Intl.supportedValuesOf("timeZone") listet nur kanonische Namen — gültige
+  // IANA-Aliase fehlen darin, obwohl Intl.DateTimeFormat/Temporal/ctx.tz.parse
+  // sie klaglos akzeptieren. Ein valider Alias darf hier nicht als "invalid"
+  // rejected werden (stiller Breaking-Change für Consumer, die Alias-Zonen
+  // speichern).
+  test.each(["US/Pacific", "GMT", "Etc/UTC"])("akzeptiert gültigen IANA-Alias %s", (zone) => {
+    expect(isValidIanaTimeZone(zone)).toBe(true);
+  });
+
   test("liefert über mehrere Aufrufe konsistent (lazy Set gecacht)", () => {
     expect(isValidIanaTimeZone("Europe/Berlin")).toBe(true);
     expect(isValidIanaTimeZone("Europe/Berlin")).toBe(true);

package/src/time/boot-tz-warning.ts

@@ -17,7 +17,11 @@ export function warnIfNonUtcServerTimeZone(
   // biome-ignore lint/suspicious/noConsole: boot-time warning, no logger wired this early
   warn: (message: string) => void = console.warn,
 ): boolean {
-  if (resolvedTimeZone === "UTC") return false;
+  // GMT and Etc/UTC are UTC-equivalent (no offset, no DST) — TZ=GMT is a
+  // legitimate way to pin a process to UTC and must not trip this warning.
+  if (resolvedTimeZone === "UTC" || resolvedTimeZone === "GMT" || resolvedTimeZone === "Etc/UTC") {
+    return false;
+  }
   warn(
     `[kumiko] Server time zone is "${resolvedTimeZone}" — the framework assumes UTC. ` +
       "Set TZ=UTC for the server process to avoid time-zone-dependent bugs.",

package/src/time/iana.ts

@@ -1,17 +1,19 @@
-// IANA-Zonenname-Validierung gegen die Runtime-eigene Zonenliste
-// (Intl.supportedValuesOf). Das Set wird lazy einmal gebaut — der Aufbau ist
-// der teure Teil (~400 kanonische Zonen), das Lookup danach O(1).
-
-let supportedZones: ReadonlySet<string> | undefined;
-
-function ianaZoneSet(): ReadonlySet<string> {
-  if (supportedZones === undefined) {
-    supportedZones = new Set(Intl.supportedValuesOf("timeZone"));
-  }
-  return supportedZones;
-}
-
-/** True wenn `value` ein gültiger kanonischer IANA-Zonenname ist (z.B. "Europe/Berlin", "UTC"). */
+// IANA-Zonenname-Validierung. Intl.supportedValuesOf("timeZone") liefert nur
+// KANONISCHE Namen — gültige Aliase wie "US/Pacific", "GMT", "Etc/UTC" fehlen
+// darin, obwohl Intl.DateTimeFormat, Temporal und ctx.tz.parse sie alle
+// klaglos akzeptieren. Intl.DateTimeFormat selbst ist aber case-INSENSITIVE
+// ("europe/berlin" resolved klaglos zu "Europe/Berlin") — ein reines
+// try/catch würde also Tippfehler in der Groß-/Kleinschreibung durchlassen.
+// Der exakte Vergleich mit resolvedOptions().timeZone schließt das: ein
+// gültiger kanonischer Name ODER Alias resolved IMMER zu sich selbst
+// (empirisch verifiziert für US/Pacific, GMT, Etc/UTC), ein falsch-gecasteter
+// String resolved zur kanonischen Form und matcht damit nicht mehr exakt.
 export function isValidIanaTimeZone(value: string): boolean {
-  return ianaZoneSet().has(value);
+  try {
+    return (
+      new Intl.DateTimeFormat(undefined, { timeZone: value }).resolvedOptions().timeZone === value
+    );
+  } catch {
+    return false;
+  }
 }

package/src/time/tz-context.ts

@@ -115,7 +115,12 @@ export function createTzContext(options: TzContextOptions = {}): TzContext {
       return geoTz.fromCoordinates(coords);
     },
     fromAddress: async (address) => {
-      if (geoTz?.fromAddress === undefined) {
+      if (geoTz === undefined) {
+        throw new Error(
+          "ctx.tz.fromAddress requires a GeoTzProvider — inject one via the app context (e.g. buildServer({ context: { geoTzProvider } }) or runProdApp({ extraContext: { geoTzProvider } })) or install a provider package.",
+        );
+      }
+      if (geoTz.fromAddress === undefined) {
         throw new Error(
           "ctx.tz.fromAddress requires a GeoTzProvider that implements fromAddress (geocoding). Offline lat/lng providers only support fromCoordinates.",
         );

package/src/utils/__tests__/serialization.test.ts

@@ -21,4 +21,10 @@ describe("parseRoles", () => {
     expect(parseRoles(42)).toEqual([]);
     expect(parseRoles({ roles: ["Admin"] })).toEqual([]);
   });
+
+  test("filters out non-string entries instead of returning a type-lying array (517/1)", () => {
+    expect(parseRoles([42, "Admin", true, null])).toEqual(["Admin"]);
+    expect(parseRoles("[42, true]")).toEqual([]);
+    expect(parseRoles('[42, "Admin"]')).toEqual(["Admin"]);
+  });
 });