@cosmicdrift/kumiko-bundled-features 0.63.0 → 0.65.0

package/src/tags/web/tag-section.tsx

@@ -1,9 +1,9 @@
 // @runtime client
-// TagSection — drop-in tag manager for ANY entity. Given an entityName +
-// entityId it shows the entity's current tags and lets the user attach an
-// existing tag, create-and-attach a new one, or detach a tag. Tag writes are
-// immediate (assign/remove are idempotent), so the section owns its own state
-// and refetches after each action — it is NOT part of a host form's save.
+// TagSection — drop-in tag manager for ANY entity, GitLab-labels style: one
+// searchable multi-combobox showing the entity's tags as chips, with a compact
+// row below to create-and-attach a brand-new tag. Tag writes are immediate
+// (assign/remove are idempotent), so the section owns its state and refetches
+// after each action — it is NOT part of a host form's save.
 //
 // Two ways to mount (both need tagsClient() registered once, for i18n):
 //   - standalone:   <TagSection entityName="note" entityId={noteId} />
@@ -29,12 +29,20 @@ type AssignmentRow = {
 type TagListResponse = { readonly rows: readonly TagRow[] };
 type AssignmentListResponse = { readonly rows: readonly AssignmentRow[] };
 
-// Structural shape of a dispatcher write result for the generic action wrapper.
-// The real WriteResult (a discriminated union) is assignable to this; narrowing
-// on `isSuccess` reaches `error.i18nKey` without importing server-side types.
-type ActionResult =
-  | { readonly isSuccess: true }
-  | { readonly isSuccess: false; readonly error: { readonly i18nKey: string } };
+// What changed between the entity's current tags and the combobox's new
+// selection. A single combobox toggle yields one add or one remove; the diff
+// stays correct for a batch selection too.
+export function tagSelectionDelta(
+  prev: readonly string[],
+  next: readonly string[],
+): { readonly added: readonly string[]; readonly removed: readonly string[] } {
+  const prevSet = new Set(prev);
+  const nextSet = new Set(next);
+  return {
+    added: next.filter((id) => !prevSet.has(id)),
+    removed: prev.filter((id) => !nextSet.has(id)),
+  };
+}
 
 export function TagSection({
   entityName,
@@ -84,98 +92,101 @@ export function TagSection({
   }
 
   const catalogTags = catalog.data?.rows ?? [];
-  const byId = new Map(catalogTags.map((tg) => [tg.id, tg]));
-  const assignedRows = (assignments.data?.rows ?? []).filter((r) => r.entityType === entityName);
-  const assignedIds = new Set(assignedRows.map((r) => r.tagId));
-  const assignedTags = assignedRows.map((r) => byId.get(r.tagId) ?? { id: r.tagId, name: r.tagId });
-  const available = catalogTags.filter((tg) => !assignedIds.has(tg.id));
+  const assignedIds = (assignments.data?.rows ?? [])
+    .filter((r) => r.entityType === entityName)
+    .map((r) => r.tagId);
+  // Catalog drives the options; an assigned tag missing from the catalog (none
+  // in v1 — no delete-tag yet) is appended so it stays removable.
+  const nameById = new Map(catalogTags.map((tg) => [tg.id, tg.name]));
+  const options = [...new Set([...catalogTags.map((tg) => tg.id), ...assignedIds])].map((id) => ({
+    value: id,
+    label: nameById.get(id) ?? id,
+  }));
 
   const refetch = async (): Promise<void> => {
     await Promise.all([catalog.refetch(), assignments.refetch()]);
   };
 
-  const run = async (action: () => Promise<ActionResult>): Promise<void> => {
+  // Runs a write-sequence (each step returns false + sets errorKey on failure,
+  // stopping the sequence) and refetches to server-truth when it completes.
+  const apply = async (writes: () => Promise<boolean>): Promise<void> => {
     setBusy(true);
     setErrorKey(null);
     try {
-      const result = await action();
-      if (!result.isSuccess) {
-        setErrorKey(result.error.i18nKey);
-        return;
-      }
-      await refetch();
+      if (await writes()) await refetch();
     } finally {
       setBusy(false);
     }
   };
 
-  const assign = (tagId: string): Promise<void> =>
-    run(() =>
-      dispatcher.write(TagsHandlers.assignTag, { tagId, entityType: entityName, entityId }),
-    );
+  const writeOk = async (type: string, payload: Record<string, unknown>): Promise<boolean> => {
+    const result = await dispatcher.write(type, payload);
+    if (!result.isSuccess) {
+      setErrorKey(result.error.i18nKey);
+      return false;
+    }
+    return true;
+  };
 
-  const detach = (tagId: string): Promise<void> =>
-    run(() =>
-      dispatcher.write(TagsHandlers.removeTag, { tagId, entityType: entityName, entityId }),
-    );
+  const onSelectionChange = (next: readonly string[]): void => {
+    const { added, removed } = tagSelectionDelta(assignedIds, next);
+    if (added.length === 0 && removed.length === 0) return;
+    void apply(async () => {
+      for (const tagId of added) {
+        if (!(await writeOk(TagsHandlers.assignTag, { tagId, entityType: entityName, entityId })))
+          return false;
+      }
+      for (const tagId of removed) {
+        if (!(await writeOk(TagsHandlers.removeTag, { tagId, entityType: entityName, entityId })))
+          return false;
+      }
+      return true;
+    });
+  };
 
-  const createAndAssign = async (): Promise<void> => {
+  const createAndAssign = (): void => {
     const name = newName.trim();
     if (name === "") return;
-    setBusy(true);
-    setErrorKey(null);
-    try {
+    void apply(async () => {
       const created = await dispatcher.write<{ id: string }>(TagsHandlers.createTag, { name });
       if (!created.isSuccess) {
         setErrorKey(created.error.i18nKey);
-        return;
+        return false;
       }
-      const assigned = await dispatcher.write(TagsHandlers.assignTag, {
-        tagId: created.data.id,
-        entityType: entityName,
-        entityId,
-      });
-      if (!assigned.isSuccess) {
-        setErrorKey(assigned.error.i18nKey);
-        return;
+      if (
+        !(await writeOk(TagsHandlers.assignTag, {
+          tagId: created.data.id,
+          entityType: entityName,
+          entityId,
+        }))
+      ) {
+        return false;
       }
       setNewName("");
-      await refetch();
-    } finally {
-      setBusy(false);
-    }
+      return true;
+    });
   };
 
   return (
     <div data-testid="tags-section">
-      {assignedTags.length === 0 ? (
-        <Text>{t("tags.section.none")}</Text>
-      ) : (
-        assignedTags.map((tg) => (
-          <Button
-            key={tg.id}
-            variant="secondary"
-            disabled={busy}
-            onClick={() => void detach(tg.id)}
-            testId={`tags-section-remove-${tg.id}`}
-          >
-            {`${tg.name} ✕`}
-          </Button>
-        ))
-      )}
-
-      {available.map((tg) => (
-        <Button
-          key={tg.id}
-          variant="secondary"
+      <Field id="tags-section-select" label={t("tags.section.label")}>
+        <Input
+          kind="combobox"
+          multiple
+          id="tags-section-select"
+          name="tags"
+          options={options}
+          value={assignedIds}
+          onChange={onSelectionChange}
           disabled={busy}
-          onClick={() => void assign(tg.id)}
-          testId={`tags-section-assign-${tg.id}`}
-        >
-          {`+ ${tg.name}`}
-        </Button>
-      ))}
+          placeholder={t("tags.section.placeholder")}
+          emptyText={t("tags.section.empty")}
+        />
+      </Field>
 
+      {/* ponytail: separate create row — the shared combobox has no create-on-type
+          affordance. Fold create into the dropdown's Command.Empty if/when the
+          renderer-web combobox grows a freeSolo/onCreate prop. */}
       <Field id="tags-section-new" label={t("tags.section.newLabel")}>
         <Input
           kind="text"
@@ -186,9 +197,9 @@ export function TagSection({
         />
       </Field>
       <Button
-        variant="primary"
+        variant="secondary"
         disabled={busy || newName.trim() === ""}
-        onClick={() => void createAndAssign()}
+        onClick={() => createAndAssign()}
         testId="tags-section-create"
       >
         {busy ? t("tags.section.working") : t("tags.section.create")}

package/src/tier-engine/__tests__/resolver.integration.test.ts

@@ -71,6 +71,20 @@ const features = composeFeatures(
   { includeBundled: true },
 );
 
+// Zweite Komposition MIT Trial-Option: jeder Tenant bekommt 30 Tage ab
+// inserted_at die "pro"-Features (feat-pro), unabhängig vom gespeicherten Tier.
+const TRIAL_HOURS = 30 * 24;
+const featuresWithTrial = composeFeatures(
+  [
+    createTierEngineFeature({
+      tierMap: TEST_TIER_MAP,
+      trial: { tier: "pro", durationHours: TRIAL_HOURS },
+    }),
+    featProFeature,
+  ],
+  { includeBundled: true },
+);
+
 let stack: TestStack;
 const tenantA = "00000000-0000-4000-8000-0000000000a1" as TenantId;
 const tenantB = "00000000-0000-4000-8000-0000000000b2" as TenantId;
@@ -212,3 +226,56 @@ describe("createTierEngineFeature — per-tenant resolver", () => {
     expect(systemSet.size).toBeGreaterThanOrEqual(2);
   });
 });
+
+describe("createTierEngineFeature — Trial-Phase (zeit-abgeleitet)", () => {
+  function sysUser(tenantId: TenantId, id: string) {
+    return createTestUser({ id, tenantId, roles: ["SystemAdmin", "TenantAdmin"] });
+  }
+
+  test("neuer 'free'-Tenant sieht im Fenster die Trial-Features (feat-pro)", async () => {
+    const usage = findTierResolverUsage(featuresWithTrial);
+    if (!usage) throw new Error("setup failure: no trial resolver");
+    const plugin = usage.options as TierResolverPlugin;
+
+    // Gespeicherter Tier ist free (keine feat-pro), inserted_at = jetzt → Trial aktiv.
+    await stack.http.writeOk(
+      "tier-engine:write:tier-assignment:create",
+      { tier: "free" },
+      sysUser(tenantA, "trial-sys-1"),
+    );
+    const resolver = await plugin.build({ db: stack.db, registry: stack.registry });
+    expect(resolver(tenantA).has("feat-pro")).toBe(true);
+  });
+
+  test("Tenant außerhalb des Fensters (inserted_at > 30 Tage) fällt auf free zurück", async () => {
+    const usage = findTierResolverUsage(featuresWithTrial);
+    if (!usage) throw new Error("setup failure: no trial resolver");
+    const plugin = usage.options as TierResolverPlugin;
+
+    await stack.http.writeOk(
+      "tier-engine:write:tier-assignment:create",
+      { tier: "free" },
+      sysUser(tenantB, "trial-sys-2"),
+    );
+    // Anlage-Datum künstlich 31 Tage zurückdrehen → Trial abgelaufen. tenantB ist
+    // eine fixe Test-UUID (kein User-Input) → inline-Interpolation unkritisch.
+    await asRawClient(stack.db).unsafe(
+      `UPDATE read_tier_assignments SET inserted_at = now() - interval '31 days' WHERE tenant_id = '${tenantB}'::uuid`,
+    );
+    const resolver = await plugin.build({ db: stack.db, registry: stack.registry });
+    expect(resolver(tenantB).has("feat-pro")).toBe(false);
+  });
+
+  test("ohne Trial-Option ist der Resolver unverändert (free = keine feat-pro)", async () => {
+    const usage = findTierResolverUsage(features);
+    if (!usage) throw new Error("setup failure");
+    const plugin = usage.options as TierResolverPlugin;
+    await stack.http.writeOk(
+      "tier-engine:write:tier-assignment:create",
+      { tier: "free" },
+      sysUser(tenantA, "no-trial-sys"),
+    );
+    const resolver = await plugin.build({ db: stack.db, registry: stack.registry });
+    expect(resolver(tenantA).has("feat-pro")).toBe(false);
+  });
+});

package/src/tier-engine/__tests__/trial.test.ts

@@ -0,0 +1,27 @@
+// Trial-Fenster: reine epochMs-Arithmetik, Rand inklusive.
+
+import { describe, expect, test } from "bun:test";
+import { isTrialActive } from "../trial";
+
+const HOUR_MS = 3_600_000;
+const start = 1_700_000_000_000;
+
+describe("isTrialActive", () => {
+  test("innerhalb des Fensters → aktiv", () => {
+    expect(isTrialActive(start, start + 10 * 24 * HOUR_MS, 720)).toBe(true);
+    expect(isTrialActive(start, start, 720)).toBe(true);
+  });
+
+  test("exakt am Fenster-Ende → nicht mehr aktiv (halb-offen)", () => {
+    expect(isTrialActive(start, start + 720 * HOUR_MS, 720)).toBe(false);
+  });
+
+  test("nach dem Fenster → inaktiv", () => {
+    expect(isTrialActive(start, start + 721 * HOUR_MS, 720)).toBe(false);
+    expect(isTrialActive(start, start + 31 * 24 * HOUR_MS, 720)).toBe(false);
+  });
+
+  test("Dauer 0 → nie aktiv", () => {
+    expect(isTrialActive(start, start, 0)).toBe(false);
+  });
+});

package/src/tier-engine/entity.ts

@@ -33,3 +33,11 @@ export const tierAssignmentEntity = createEntity({
     source: createTextField({ required: false, maxLength: 20 }),
   },
 });
+
+export type TierAssignmentRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly tier: string;
+  readonly source: string | null;
+  readonly tenantId: string;
+};

package/src/tier-engine/feature.ts

@@ -62,6 +62,7 @@ import {
   type TierResolverPlugin,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { getAggregateStreamMaxVersion } from "@cosmicdrift/kumiko-framework/event-store";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { z } from "zod";
 import { tierAssignmentAggregateId } from "./aggregate-id";
 import type { TierMap } from "./compose-app";
@@ -70,6 +71,7 @@ import { tierAssignmentEntity } from "./entity";
 import { getActiveTierQuery } from "./handlers/active-tier.query";
 import { getTenantTierQuery } from "./handlers/get-tenant-tier.query";
 import { createSetTenantTierWrite } from "./handlers/set-tenant-tier.write";
+import { isTrialActive, type TrialPolicy } from "./trial";
 
 // Drizzle-table for the tier-assignment-entity. Built once at module-load
 // from the entity definition — same shape buildEntityTable would produce
@@ -115,6 +117,15 @@ export type CreateTierEngineOptions<TCaps extends Readonly<Record<string, unknow
    * oder eigene resolution-logic nutzen (legacy-pattern).
    */
   readonly tierMap?: TierMap<TCaps>;
+
+  /**
+   * Optionale Trial-Phase: jeder Tenant bekommt für `durationHours` ab seinem
+   * Anlage-Datum zusätzlich die Features von `trial.tier` freigeschaltet,
+   * danach fällt er automatisch auf sein gespeichertes Tier zurück. Erfordert
+   * `tierMap` (der Trial-Tier muss ein Key sein). Zeit-abgeleitet aus
+   * inserted_at — kein Stored-Flag, kein Scheduler.
+   */
+  readonly trial?: TrialPolicy;
 };
 
 /**
@@ -242,6 +253,17 @@ export function createTierEngineFeature<
     // Requests (build läuft pre-listen via runDevApp/runProdApp-pickup).
     const alwaysOnHolder: { set: ReadonlySet<string> } = { set: new Set() };
 
+    // Trial-State: tenantId → inserted_at als epochMilliseconds (Anlage-Datum
+    // der Assignment ≈ Signup, rebuild-stabil). Trial wird at-resolve-time aus
+    // (jetzt vs startedAt + durationHours) berechnet, NICHT gecacht — anders als
+    // das Feature-Set ändert sich der Trial-Status mit der Zeit. trialFeatures
+    // ist die fixe Feature-Menge des Trial-Tiers (einmal aufgelöst).
+    const trialClock = new Map<TenantId, number>();
+    const trialFeatures: ReadonlySet<string> = opts.trial
+      ? featuresForTier(tierMap, opts.trial.tier)
+      : new Set();
+    const nowMs = (): number => getTemporal().Now.instant().epochMilliseconds;
+
     // set-tenant-tier schreibt direkt über den Executor → der postSave-Hook
     // unten feuert dabei NICHT. Diese Funktion repliziert den Cache-Update
     // des Hooks, damit ein manueller Grant das effektive Feature-Set sofort
@@ -249,6 +271,9 @@ export function createTierEngineFeature<
     // Semantik wie der Hook.
     onTierAssigned.fn = (tenantId, tier) => {
       cache.set(tenantId, mergeAlwaysOn(alwaysOnHolder.set, featuresForTier(tierMap, tier)));
+      // Trial-Uhr nur setzen, wenn unbekannt: ein manueller Grant ändert nicht
+      // das Signup-Datum eines bestehenden Tenants (build() hat es bereits).
+      if (!trialClock.has(tenantId)) trialClock.set(tenantId, nowMs());
     };
 
     // Invalidation: tier-assignment events update the cache.
@@ -261,10 +286,12 @@ export function createTierEngineFeature<
       // throwing — der lifecycle-pipeline darf nicht durch hook-fehler
       // blocken (afterCommit-pattern, side-effect-best-effort).
       if (typeof data.tenantId !== "string" || typeof data.tier !== "string") return;
-      cache.set(
-        data.tenantId as TenantId,
-        mergeAlwaysOn(alwaysOnHolder.set, featuresForTier(tierMap, data.tier)),
-      );
+      const tenantId = data.tenantId as TenantId;
+      cache.set(tenantId, mergeAlwaysOn(alwaysOnHolder.set, featuresForTier(tierMap, data.tier)));
+      // Erstes Assignment eines Tenants = Signup → Trial-Uhr startet jetzt
+      // (inserted_at der frisch erzeugten Row ≈ now). Spätere Tier-Wechsel
+      // lassen die Uhr unberührt, sonst würde ein Upgrade das Fenster verlängern.
+      if (!trialClock.has(tenantId)) trialClock.set(tenantId, nowMs());
     });
     r.entityHook("postDelete", "tier-assignment", async (payload) => {
       const data = payload.data as { tenantId?: unknown }; // @cast-boundary engine-payload
@@ -385,15 +412,18 @@ export function createTierEngineFeature<
         // typischerweise <100k tenants — single-pass scan akzeptabel.
         // Skalierungs-Pfad (lazy-load + LRU) ist Sprint-8b wenn echtes
         // Bedürfnis entsteht.
-        type AssignmentRow = { tenantId: string; tier: string };
+        type AssignmentRow = { tenantId: string; tier: string; insertedAt: Temporal.Instant };
         const rows = await selectMany<AssignmentRow>(deps.db, tierAssignmentTable);
         for (const row of rows) {
           cache.set(
             row.tenantId as TenantId,
             mergeAlwaysOn(computedAlwaysOn, featuresForTier(tierMap, row.tier)),
           );
+          trialClock.set(row.tenantId as TenantId, row.insertedAt.epochMilliseconds);
         }
 
+        const trial = opts.trial;
+
         // Synchronous resolver-callback for dispatcher hot-path.
         return (tenantId: TenantId): ReadonlySet<string> => {
           // Operator-tooling + async-event-dispatch convention: SYSTEM_TENANT_ID
@@ -401,15 +431,25 @@ export function createTierEngineFeature<
           if (tenantId === SYSTEM_TENANT_ID) {
             return mergeAlwaysOn(computedAlwaysOn, unionAllTierFeatures(tierMap));
           }
-          const cached = cache.get(tenantId);
-          if (cached !== undefined) return cached;
           // Cache-miss: tenant ist noch nicht im cache (z.B. brandneu nach
           // boot, oder defaultTier-hook hat noch nicht gefired). Default-Set
           // ist least-privileged — typisch Free-Tier-features. Memory
           // `feedback_security_default_on`: secure-by-default.
           const fallbackTier = opts.defaultTier;
-          if (fallbackTier === undefined) return computedAlwaysOn;
-          return mergeAlwaysOn(computedAlwaysOn, featuresForTier(tierMap, fallbackTier));
+          const base =
+            cache.get(tenantId) ??
+            (fallbackTier === undefined
+              ? computedAlwaysOn
+              : mergeAlwaysOn(computedAlwaysOn, featuresForTier(tierMap, fallbackTier)));
+          // Trial: innerhalb des Fensters ab Signup zusätzlich die Trial-Tier-
+          // Features. Zeit-abgeleitet → pro Request geprüft, nie gecacht.
+          if (trial !== undefined) {
+            const startedMs = trialClock.get(tenantId);
+            if (startedMs !== undefined && isTrialActive(startedMs, nowMs(), trial.durationHours)) {
+              return mergeAlwaysOn(base, trialFeatures);
+            }
+          }
+          return base;
         };
       },
     };

package/src/tier-engine/handlers/get-tenant-tier.query.ts

@@ -6,7 +6,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
-import { tierAssignmentEntity } from "../entity";
+import { type TierAssignmentRow, tierAssignmentEntity } from "../entity";
 
 // Liest das Tier-Assignment eines BELIEBIGEN Tenants (cross-tenant) für den
 // tier-admin-Screen. SystemAdmin-only. get-active-tier liest nur den eigenen
@@ -15,14 +15,6 @@ import { tierAssignmentEntity } from "../entity";
 
 const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
 
-type TierAssignmentRow = {
-  readonly id: string;
-  readonly version: number;
-  readonly tier: string;
-  readonly source: string | null;
-  readonly tenantId: string;
-};
-
 export const getTenantTierQuery = defineQueryHandler({
   name: "get-tenant-tier",
   schema: z.object({ tenantId: z.string().min(1) }),

package/src/tier-engine/handlers/set-tenant-tier.write.ts

@@ -8,7 +8,7 @@ import {
 import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { tierAssignmentAggregateId } from "../aggregate-id";
-import { tierAssignmentEntity } from "../entity";
+import { type TierAssignmentRow, tierAssignmentEntity } from "../entity";
 
 // SystemAdmin setzt das Tier eines BELIEBIGEN Tenants — manueller Grant ohne
 // Billing. Cross-tenant, daher SystemAdmin-only (kein TenantAdmin: sonst
@@ -39,14 +39,6 @@ const executor = createEventStoreExecutor(tierAssignmentTable, tierAssignmentEnt
   entityName: "tier-assignment",
 });
 
-type TierAssignmentRow = {
-  readonly id: string;
-  readonly version: number;
-  readonly tier: string;
-  readonly source: string | null;
-  readonly tenantId: string;
-};
-
 export type SetTenantTierOptions = {
   /** Nach erfolgreichem Write aufgerufen, damit feature.ts den Resolver-
    *  Cache aktualisieren kann (der Executor-Write feuert den postSave-Hook

package/src/tier-engine/index.ts

@@ -24,3 +24,4 @@ export {
   createTierEngineFeature,
   tierEngineFeature,
 } from "./feature";
+export { isTrialActive, type TrialPolicy } from "./trial";

package/src/tier-engine/trial.ts

@@ -0,0 +1,26 @@
+// Trial-Phase: ein neuer Tenant bekommt für eine Karenzzeit ab seinem
+// Anlage-Datum (inserted_at der tier-assignment-Row — rebuild-stabil aus dem
+// Create-Event) zusätzlich die Features eines höheren Tiers, unabhängig vom
+// gespeicherten Tier. Rein zeit-abgeleitet: kein Stored-Flag, kein Scheduler,
+// automatischer Ablauf. Die App definiert die Policy (welcher Tier, wie lange);
+// die tier-engine wendet sie im Resolver an.
+
+export interface TrialPolicy {
+  // Tier, dessen Features während der Trial-Phase zusätzlich freigeschaltet
+  // werden (muss ein Key der tierMap sein, sonst greift kein Feature).
+  readonly tier: string;
+  // Länge der Trial-Phase ab inserted_at, in Stunden (720 = 30 Tage). Stunden
+  // statt Tage: Temporal.Instant kennt keine Kalender-Tage, 720h ist die
+  // ehrliche, DST-unabhängige Dauer.
+  readonly durationHours: number;
+}
+
+// Reine Millis-Arithmetik auf epochMilliseconds (die beide Seiten — Projektions-
+// Row und Now — liefern). Kein Date, keine TZ.
+export function isTrialActive(
+  startedAtEpochMs: number,
+  nowEpochMs: number,
+  durationHours: number,
+): boolean {
+  return nowEpochMs < startedAtEpochMs + durationHours * 3_600_000;
+}