@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @cosmicdrift/kumiko-framework
 
+## 0.3.0
+
+### Minor Changes
+
+- 0.3.0 bringt zwei neue Subsysteme (Step-Engine Tier-3 + Visual-Tree) plus
+  eine AST-Codemod-Pipeline als Vorarbeit für den L2-AI-Layer.
+
+  ### Breaking Changes
+
+  - `skipTransitionGuard` → `unsafeSkipTransitionGuard` (Rename in
+    feature-ast + engine). Der `unsafe`-Prefix macht die Tragweite des
+    Casts sichtbar und ist konsistent zur `unsafeProjectionUpsert`- und
+    `r.rawTable`-Konvention. Migration: 1:1-Ersetzung, keine Verhaltens-Änderung.
+
+  ### Features
+
+  - **Step-Engine M.4 — Tier-3 Workflow-Engine.** Neue Step-Vocabulary
+    `wait`, `waitForEvent`, `retry` ermöglicht persistierte Long-Running-Flows
+    über Job-Boundaries hinweg. Q7 Snapshot-at-Start hängt jedem Step-Run
+    einen SHA-256-Fingerprint des Aggregat-Zustands an, sodass Replays
+    deterministisch gegen den ursprünglichen Eingangszustand laufen.
+  - **Visual-Tree V.1.x — Tree-API + Editor-Panel.** Neue `VisualTree`-
+    Component plus TreeProvider-Pattern; erste TreeProviders für
+    `text-content` und `legal-pages` (CMS-light + Impressum/Privacy).
+    Fundament für den späteren No-Code-Designer (~3000 LOC, 98 Tests).
+  - **Codemod-Pipeline.** AST-basierte Patcher-Module für strukturelle
+    Feature-Edits — wird vom kommenden L2-AI-Layer als Tool-Surface
+    verwendet, ist aber eigenständig nutzbar für ts-morph-style Migrationen.
+  - **user-data-rights Sample-Recipe.** DSGVO Art. 15/17/18/20 vollständig
+    als Sample-Recipe (`samples/recipes/`) inklusive README — zeigt die
+    Export- und Forget-Pipeline gegen den `compliance-profiles`-Default
+    (`eu-dsgvo`).
+
+  ### Fixes
+
+  - `tier-engine`: auto-default-tier-Hook benutzt jetzt `ctx.db.raw` für
+    Event-Store-Operationen (#37, vorher: stiller Bug, 22 Tage live).
+  - `engine`: unsafe-projection-upsert nutzt `as never` statt `as any` —
+    schmaler Cast-Surface, weniger Compiler-Knebel.
+  - `visual-tree`: runtime-isolation marker für client-konsumierte Files,
+    damit der Multi-Entry-Build den richtigen Bundle-Split bekommt.
+  - `feature-ast`: vollständiger `unsafeSkipTransitionGuard`-Rename (war
+    in zwei Modulen noch der alte Name).
+  - `framework`: Error-Reasons + `noConsole`-Lint + No-Date-API-Guard
+    wieder push-ready.
+
+  ### Library-Updates
+
+  hono 4.12, jose 6.2, stripe 22.1, meilisearch 0.58, marked 18,
+  bun-types 1.3.13, lucide-react 1.14, bullmq 5.76, ioredis 5.10,
+  i18next 26.0, react + radix-ui-primitives auf aktuelle Minors.
+
+## 0.2.3
+
 ## 0.2.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -28,55 +28,141 @@
     "runtime": "runtime"
   },
   "exports": {
-    "./engine": "./src/engine/index.ts",
-    "./engine/types": "./src/engine/types/index.ts",
-    "./errors": "./src/errors/index.ts",
-    "./db": "./src/db/index.ts",
-    "./event-store": "./src/event-store/index.ts",
-    "./event-store/admin-api": "./src/event-store/admin-api.ts",
-    "./pipeline": "./src/pipeline/index.ts",
-    "./api": "./src/api/index.ts",
-    "./i18n": "./src/i18n/index.ts",
-    "./auth": "./src/auth/index.ts",
-    "./files": "./src/files/index.ts",
-    "./jobs": "./src/jobs/index.ts",
-    "./migrations": "./src/migrations/index.ts",
-    "./entrypoint": "./src/entrypoint/index.ts",
-    "./random": "./src/random/index.ts",
-    "./redis": "./src/redis/index.ts",
-    "./search": "./src/search/index.ts",
-    "./search/meilisearch": "./src/search/meilisearch-adapter.ts",
-    "./secrets": "./src/secrets/index.ts",
-    "./stack": "./src/stack/index.ts",
-    "./testing": "./src/testing/index.ts",
-    "./testing/handler-context": "./src/testing/handler-context.ts",
-    "./testing/e2e-generator": "./src/testing/e2e-generator.ts",
-    "./time": "./src/time/index.ts",
-    "./ui-types": "./src/ui-types/index.ts",
-    "./utils": "./src/utils/index.ts"
+    "./compliance": {
+      "types": "./src/compliance/index.ts",
+      "default": "./src/compliance/index.ts"
+    },
+    "./engine": {
+      "types": "./src/engine/index.ts",
+      "default": "./src/engine/index.ts"
+    },
+    "./engine/types": {
+      "types": "./src/engine/types/index.ts",
+      "default": "./src/engine/types/index.ts"
+    },
+    "./engine/codemod": {
+      "types": "./src/engine/codemod/index.ts",
+      "default": "./src/engine/codemod/index.ts"
+    },
+    "./errors": {
+      "types": "./src/errors/index.ts",
+      "default": "./src/errors/index.ts"
+    },
+    "./db": {
+      "types": "./src/db/index.ts",
+      "default": "./src/db/index.ts"
+    },
+    "./event-store": {
+      "types": "./src/event-store/index.ts",
+      "default": "./src/event-store/index.ts"
+    },
+    "./event-store/admin-api": {
+      "types": "./src/event-store/admin-api.ts",
+      "default": "./src/event-store/admin-api.ts"
+    },
+    "./pipeline": {
+      "types": "./src/pipeline/index.ts",
+      "default": "./src/pipeline/index.ts"
+    },
+    "./api": {
+      "types": "./src/api/index.ts",
+      "default": "./src/api/index.ts"
+    },
+    "./i18n": {
+      "types": "./src/i18n/index.ts",
+      "default": "./src/i18n/index.ts"
+    },
+    "./auth": {
+      "types": "./src/auth/index.ts",
+      "default": "./src/auth/index.ts"
+    },
+    "./files": {
+      "types": "./src/files/index.ts",
+      "default": "./src/files/index.ts"
+    },
+    "./jobs": {
+      "types": "./src/jobs/index.ts",
+      "default": "./src/jobs/index.ts"
+    },
+    "./migrations": {
+      "types": "./src/migrations/index.ts",
+      "default": "./src/migrations/index.ts"
+    },
+    "./entrypoint": {
+      "types": "./src/entrypoint/index.ts",
+      "default": "./src/entrypoint/index.ts"
+    },
+    "./random": {
+      "types": "./src/random/index.ts",
+      "default": "./src/random/index.ts"
+    },
+    "./redis": {
+      "types": "./src/redis/index.ts",
+      "default": "./src/redis/index.ts"
+    },
+    "./search": {
+      "types": "./src/search/index.ts",
+      "default": "./src/search/index.ts"
+    },
+    "./search/meilisearch": {
+      "types": "./src/search/meilisearch-adapter.ts",
+      "default": "./src/search/meilisearch-adapter.ts"
+    },
+    "./secrets": {
+      "types": "./src/secrets/index.ts",
+      "default": "./src/secrets/index.ts"
+    },
+    "./stack": {
+      "types": "./src/stack/index.ts",
+      "default": "./src/stack/index.ts"
+    },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "default": "./src/testing/index.ts"
+    },
+    "./testing/handler-context": {
+      "types": "./src/testing/handler-context.ts",
+      "default": "./src/testing/handler-context.ts"
+    },
+    "./testing/e2e-generator": {
+      "types": "./src/testing/e2e-generator.ts",
+      "default": "./src/testing/e2e-generator.ts"
+    },
+    "./time": {
+      "types": "./src/time/index.ts",
+      "default": "./src/time/index.ts"
+    },
+    "./ui-types": {
+      "types": "./src/ui-types/index.ts",
+      "default": "./src/ui-types/index.ts"
+    },
+    "./utils": {
+      "types": "./src/utils/index.ts",
+      "default": "./src/utils/index.ts"
+    }
   },
   "dependencies": {
-    "bullmq": "^5.73.5",
-    "bun-types": "^1.3.12",
+    "bullmq": "^5.76.7",
+    "bun-types": "^1.3.13",
     "drizzle-kit": "^0.31.10",
     "drizzle-orm": "^0.45.2",
-    "hono": "^4.12.12",
-    "i18next": "^26.0.4",
-    "ioredis": "^5.6.0",
-    "jose": "^6.0.11",
-    "meilisearch": "^0.57.0",
+    "hono": "^4.12.18",
+    "i18next": "^26.1.0",
+    "ioredis": "^5.10.1",
+    "jose": "^6.2.3",
+    "meilisearch": "^0.58.0",
     "pino": "^10.3.1",
     "postgres": "^3.4.9",
     "temporal-polyfill": "^0.3.2",
     "ts-morph": "^28.0.0",
     "uuid": "^14.0.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.2.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.3.0",
     "@types/uuid": "^11.0.0",
-    "bun-types": "^1.2.9",
-    "drizzle-kit": "^0.31.0",
+    "bun-types": "^1.3.13",
+    "drizzle-kit": "^0.31.10",
     "pino-pretty": "^13.1.3"
   },
   "publishConfig": {

package/src/__tests__/full-stack.integration.ts

@@ -46,11 +46,11 @@ let USER_CREATED_EVENT: string;
 const domainEventSubscriberCalls: Array<{ type: string; payload: unknown }> = [];
 
 async function emitUserCreated(
-  ctx: Pick<HandlerContext, "appendEventUnsafe">,
+  ctx: Pick<HandlerContext, "unsafeAppendEvent">,
   id: EntityId,
   email: string,
 ): Promise<void> {
-  await ctx.appendEventUnsafe({
+  await ctx.unsafeAppendEvent({
     aggregateId: String(id),
     aggregateType: "user",
     type: USER_CREATED_EVENT,

package/src/api/auth-routes.ts

@@ -650,7 +650,7 @@ export function createAuthRoutes(
       }
       const result = await dispatcher.write(inv.acceptWithLoginHandler, parsed.data, GUEST_USER);
       if (!result.isSuccess) {
-        const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500;
+        const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500; // @cast-boundary engine-payload
         return c.json({ isSuccess: false, error: result.error }, status);
       }
       const data = result.data as {
@@ -658,7 +658,7 @@ export function createAuthRoutes(
         session: SessionUser;
         tenantId: TenantId;
         role: string;
-      };
+      }; // @cast-boundary engine-payload
       let sessionForJwt: SessionUser = data.session;
       if (config.sessionCreator) {
         const sid = await config.sessionCreator(data.session, requestMeta(c));
@@ -690,7 +690,7 @@ export function createAuthRoutes(
       }
       const result = await dispatcher.write(inv.signupCompleteHandler, parsed.data, GUEST_USER);
       if (!result.isSuccess) {
-        const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500;
+        const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500; // @cast-boundary engine-payload
         return c.json({ isSuccess: false, error: result.error }, status);
       }
       const data = result.data as {
@@ -698,7 +698,7 @@ export function createAuthRoutes(
         session: SessionUser;
         tenantId: TenantId;
         role: string;
-      };
+      }; // @cast-boundary engine-payload
       let sessionForJwt: SessionUser = data.session;
       if (config.sessionCreator) {
         const sid = await config.sessionCreator(data.session, requestMeta(c));
@@ -967,7 +967,7 @@ function registerTokenConfirmRoute(opts: {
     }
     const result = await opts.dispatcher.write(opts.confirmHandler, parsed.data, GUEST_USER);
     if (!result.isSuccess) {
-      const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500;
+      const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500; // @cast-boundary engine-payload
       return c.json({ isSuccess: false, error: result.error }, status);
     }
     return c.json({ isSuccess: true });

package/src/api/jwt.ts

@@ -50,8 +50,8 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
       const { payload } = await jose.jwtVerify(token, encodedSecret, { issuer });
       const result: JwtPayload = {
         sub: String(payload.sub),
-        tenantId: payload["tenantId"] as string,
-        roles: payload["roles"] as string[],
+        tenantId: payload["tenantId"] as string, // @cast-boundary dynamic-key
+        roles: payload["roles"] as string[], // @cast-boundary dynamic-key
       };
       const claims = payload["claims"];
       if (claims && typeof claims === "object") {

package/src/api/route-registrars.ts

@@ -68,7 +68,7 @@ function constantTimeEqual(a: string, b: string): boolean {
 // Prometheus-compatible meter (future OTLP bridge) works without an
 // explicit union — if it exposes `snapshot()` it's serialisable.
 function isPrometheusMeter(m: Meter): m is PrometheusMeter {
-  return typeof (m as { snapshot?: unknown }).snapshot === "function";
+  return typeof (m as { snapshot?: unknown }).snapshot === "function"; // @cast-boundary schema-walk
 }
 
 // Mount `/metrics` (or the caller-supplied path). Takes just the Meter —

package/src/api/routes.ts

@@ -73,7 +73,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
             failedIndex: result.failedIndex,
             results: result.results,
           },
-          err.httpStatus as ContentfulStatusCode,
+          err.httpStatus as ContentfulStatusCode, // @cast-boundary engine-payload
         );
       }
       return c.json(result);
@@ -121,7 +121,7 @@ function toKumiko(e: unknown): KumikoError {
 function writeErrorResponse(c: Context, err: KumikoError, statusOverride?: number) {
   const requestId = requestContext.get()?.requestId;
   const { error } = serializeError(err, requestId);
-  const status = (statusOverride ?? err.httpStatus) as ContentfulStatusCode;
+  const status = (statusOverride ?? err.httpStatus) as ContentfulStatusCode; // @cast-boundary engine-payload
   return c.json({ isSuccess: false, error }, status);
 }
 
@@ -130,6 +130,6 @@ function writeErrorResponse(c: Context, err: KumikoError, statusOverride?: numbe
 function queryErrorResponse(c: Context, err: KumikoError, statusOverride?: number) {
   const requestId = requestContext.get()?.requestId;
   const body = serializeError(err, requestId);
-  const status = (statusOverride ?? err.httpStatus) as ContentfulStatusCode;
+  const status = (statusOverride ?? err.httpStatus) as ContentfulStatusCode; // @cast-boundary engine-payload
   return c.json(body, status);
 }

package/src/api/server.ts

@@ -42,7 +42,7 @@ import {
   globalIpRateLimit,
 } from "../rate-limit";
 import type { SearchAdapter } from "../search/types";
-import { generateId } from "../utils";
+import { assertUnreachable, generateId } from "../utils";
 import { PUBLIC_API_PATHS } from "./api-constants";
 import { type AnonymousAccessConfig, authMiddleware } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
@@ -383,7 +383,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
     // can pause this consumer when the feature is globally disabled. Events
     // queue up in the store and replay cleanly from the same cursor on resume.
     ...(options.registry.getMultiStreamProjectionFeature(msp.name) && {
-      featureName: options.registry.getMultiStreamProjectionFeature(msp.name) as string,
+      featureName: options.registry.getMultiStreamProjectionFeature(msp.name) as string, // @cast-boundary engine-bridge
     }),
     // Copy the continuous-lifecycle error policy straight onto the consumer.
     // Rebuild uses its own policy (rebuildProjection reads msp.errorMode.rebuild
@@ -409,10 +409,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
       // Hand the raw DbRunner to apply(): MSPs write to their projection
       // table directly, they don't go through the TenantDb wrapper.
       const rawRunner =
-        event.tenantId === SYSTEM_TENANT_ID
-          ? baseDb
-          : // @cast-boundary engine-bridge — TenantDb exposes its raw DbRunner via .raw
-            (scopedDb as { raw: typeof baseDb }).raw;
+        event.tenantId === SYSTEM_TENANT_ID ? baseDb : (scopedDb as { raw: typeof baseDb }).raw; // @cast-boundary engine-bridge
       // Saga/process-manager ctx: apply can call ctx.appendEvent to cascade
       // a follow-up event onto another aggregate. Uses the triggering event's
       // tenantId + userId so the causal chain stays tenant-consistent.
@@ -563,7 +560,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   app.route("/api", createSseRoute(sseBroker));
 
   if (options.files) {
-    const fileDb = options.files.db ?? (options.context.db as FileRoutesOptions["db"]);
+    const fileDb = options.files.db ?? (options.context.db as FileRoutesOptions["db"]); // @cast-boundary engine-bridge
     if (!fileDb) throw new Error("files option requires db in context or files.db");
     app.route(
       "/api",
@@ -605,6 +602,8 @@ export function buildServer(options: ServerOptions): KumikoServer {
           // Hono-on() für die Methoden ohne Convenience-Method.
           app.on(route.method, route.path, honoHandler);
           break;
+        default:
+          assertUnreachable(route.method, "http method");
       }
     }
   }

package/src/auth/__tests__/roles.test.ts

@@ -0,0 +1,24 @@
+// Snapshot-Tests fuer ROLES — faengt stille Drift ab.
+
+import { describe, expect, test } from "vitest";
+import { ROLES } from "../roles";
+
+describe("ROLES constants", () => {
+  test("Snapshot — explizit zu updaten bei Aenderungen", () => {
+    expect(ROLES).toMatchInlineSnapshot(`
+      {
+        "DataProtectionOfficer": "DataProtectionOfficer",
+        "Member": "Member",
+        "SystemAdmin": "SystemAdmin",
+        "TenantAdmin": "TenantAdmin",
+        "TenantOwner": "TenantOwner",
+      }
+    `);
+  });
+
+  test("ROLES-Werte sind identisch zu den Keys (keine Drift im Mapping)", () => {
+    for (const [key, value] of Object.entries(ROLES)) {
+      expect(value).toBe(key);
+    }
+  });
+});

package/src/auth/index.ts

@@ -0,0 +1,7 @@
+// `@cosmicdrift/kumiko-framework/auth` — Auth-Foundation (Roles, Token-
+// Helpers, Session-Types). Wird von Bundled-Features (auth-email-password,
+// tenant, user) und Datenschutz-Sprints (S1+ user-data-rights, S5 tenant-
+// lifecycle, S6 legal-hold) genutzt.
+
+export type { Role } from "./roles";
+export { ROLES } from "./roles";

package/src/auth/roles.ts

@@ -0,0 +1,42 @@
+// Zentrale Role-Konstanten der Plattform.
+//
+// Hintergrund: Bundled-Features driften zwischen "Admin" (text-content,
+// secrets, ai-foundation, file-provider-s3) und "TenantAdmin" (tenant-
+// handler, publicstatus, platform). App-Builder fallen in diese Falle.
+// Diese Datei ist die Single Source of Truth — Bundled-Features
+// migrieren schrittweise auf die ROLES-Constants in den Sprint-
+// Touchpoints, an denen sie ohnehin angefasst werden.
+//
+// Canonical-Names:
+//   TenantOwner            — Volle Tenant-Hoheit, einzige Rolle die
+//                            Tenant-Destroy triggern darf.
+//   TenantAdmin            — Tenant-Konfiguration + User-Management.
+//                            Bestehender String "Admin" wird hierauf
+//                            migriert.
+//   DataProtectionOfficer  — DPO; setzt Legal-Holds, sieht Authority-
+//                            Audit-Stream auch im silentMode (Sprint 6).
+//   SystemAdmin            — Plattform-Operator (NICHT Tenant-scoped).
+//                            Authority-Export, KMS-Recovery, Cross-
+//                            Tenant-Setup. Matched den bestehenden
+//                            "SystemAdmin"-String in text-content,
+//                            secrets, auth-email-password, etc.
+//   Member                 — Standard-Mitglied eines Tenants ohne
+//                            Admin-Rechte.
+
+/**
+ * Plattform-weit standardisierte Role-Namen. Alle Datenschutz-Sprints
+ * (1+) nutzen ausschliesslich diese Constants statt String-Literale.
+ */
+export const ROLES = {
+  TenantOwner: "TenantOwner",
+  TenantAdmin: "TenantAdmin",
+  DataProtectionOfficer: "DataProtectionOfficer",
+  SystemAdmin: "SystemAdmin",
+  Member: "Member",
+} as const;
+
+/**
+ * Type-Union aller bekannten Role-Namen (Compile-Time-Check fuer
+ * Handler-Access-Rules + Ownership-Maps).
+ */
+export type Role = (typeof ROLES)[keyof typeof ROLES];

package/src/compliance/__tests__/duration-spec.test.ts

@@ -0,0 +1,72 @@
+// Unit-Tests fuer DurationSpec-Helpers (S2.U5a.fix2).
+//
+// Pinst beide Discriminated-Union-Branches (`{days}` + `{hours}`) plus
+// Edge-Cases die in den Integration-Tests nicht auftauchen (0-Werte,
+// Singular/Plural). Der Bug aus dem U5a-Review (`{hours: 6}` fiel auf
+// 30d-Default) wird hier zentral verhindert.
+
+import { ensureTemporalPolyfill, getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { beforeAll, describe, expect, test } from "vitest";
+import { addDurationSpec, describeDurationSpec, durationSpecToMs } from "../duration-spec";
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+});
+
+describe("durationSpecToMs", () => {
+  test("days → days * 86_400_000", () => {
+    expect(durationSpecToMs({ days: 30 })).toBe(30 * 24 * 60 * 60 * 1000);
+    expect(durationSpecToMs({ days: 1 })).toBe(24 * 60 * 60 * 1000);
+  });
+
+  test("hours → hours * 3_600_000", () => {
+    expect(durationSpecToMs({ hours: 6 })).toBe(6 * 60 * 60 * 1000);
+    expect(durationSpecToMs({ hours: 72 })).toBe(72 * 60 * 60 * 1000);
+  });
+
+  test("0-Werte ergeben 0", () => {
+    expect(durationSpecToMs({ days: 0 })).toBe(0);
+    expect(durationSpecToMs({ hours: 0 })).toBe(0);
+  });
+});
+
+describe("addDurationSpec", () => {
+  test("days addiert exakt zu Instant.epochMilliseconds", () => {
+    const T = getTemporal();
+    const t0 = T.Instant.fromEpochMilliseconds(1_700_000_000_000);
+    const t1 = addDurationSpec(t0, { days: 30 });
+    expect(t1.epochMilliseconds - t0.epochMilliseconds).toBe(30 * 24 * 60 * 60 * 1000);
+  });
+
+  test("hours addiert exakt zu Instant.epochMilliseconds", () => {
+    const T = getTemporal();
+    const t0 = T.Instant.fromEpochMilliseconds(1_700_000_000_000);
+    const t1 = addDurationSpec(t0, { hours: 6 });
+    expect(t1.epochMilliseconds - t0.epochMilliseconds).toBe(6 * 60 * 60 * 1000);
+  });
+
+  // Regression-Guard fuer den U5a-Bug: vorher fiel `{hours: 6}` auf
+  // `30 * 86_400_000`-Default zurueck. Wenn jemand den Branch wieder
+  // verliert, faellt dieser Test sofort um.
+  test("hours-Branch ist NICHT auf days-Default mappable (U5a-Regression)", () => {
+    const T = getTemporal();
+    const t0 = T.Instant.fromEpochMilliseconds(1_700_000_000_000);
+    const tHours = addDurationSpec(t0, { hours: 6 });
+    const tDaysDefault = addDurationSpec(t0, { days: 30 });
+    expect(tHours.epochMilliseconds).not.toBe(tDaysDefault.epochMilliseconds);
+  });
+});
+
+describe("describeDurationSpec", () => {
+  test("days mit Pluralisierung", () => {
+    expect(describeDurationSpec({ days: 30 })).toBe("30 days");
+    expect(describeDurationSpec({ days: 1 })).toBe("1 day");
+    expect(describeDurationSpec({ days: 0 })).toBe("0 days");
+  });
+
+  test("hours mit Pluralisierung", () => {
+    expect(describeDurationSpec({ hours: 72 })).toBe("72 hours");
+    expect(describeDurationSpec({ hours: 1 })).toBe("1 hour");
+    expect(describeDurationSpec({ hours: 0 })).toBe("0 hours");
+  });
+});