@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/tier-engine/compose-app.ts

@@ -3,17 +3,17 @@ import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 /**
  * Tier definition — a named bundle of features + caps.
  *
- * **Generic über `TCaps`:** die App definiert ihren Cap-Shape als konkreten
- * Type (z.B. `{ apps: number, mailsPerMonth: number, aiTokens: number }`)
- * und der composeApp-Aufruf liefert exakt diesen Shape zurück. Keine
- * `as Record<string, unknown>`-Casts in App-Code, alle Cap-Reads sind
- * compile-time-checked.
+ * **Generic over `TCaps`:** the app defines its cap shape as a concrete
+ * type (e.g. `{ apps: number, mailsPerMonth: number, aiTokens: number }`)
+ * and the composeApp call returns exactly that shape. No
+ * `as Record<string, unknown>` casts are needed in app code; all cap reads
+ * are compile-time checked.
  *
- * Die Tier-Engine selbst ist **agnostisch** zu konkreten Tier-Werten und
- * Cap-Dimensionen. Jede App definiert ihre TierMap: kumiko.rocks hat
- * free/pro/business/enterprise/self-host, PublicStatus hat
- * free/starter/team/agency. Die Engine speichert nur den Tier-Namen als
- * String und vertraut der App's TierMap, was das beim Boot bedeutet.
+ * The tier engine itself is **agnostic** to concrete tier values and cap
+ * dimensions. Each app defines its TierMap: kumiko.rocks has
+ * free/pro/business/enterprise/self-host, while PublicStatus has
+ * free/starter/team/agency. The engine stores only the tier name as a
+ * string and trusts the app's TierMap to define what it means at boot.
  */
 export type TierDefinition<TCaps extends Readonly<Record<string, unknown>>> = {
   /** Feature names to mount on top of the base set (no add-ons applied). */
@@ -26,9 +26,9 @@ export type TierDefinition<TCaps extends Readonly<Record<string, unknown>>> = {
  * Add-On definition — a tier-orthogonal feature bundle that can be added
  * to any tier (BYOK-Encryption, Dedicated-Stack, Custom-SLA, ...).
  *
- * `capOverrides` ist `Partial<TCaps>` weil ein Add-On nur einzelne Cap-
- * Werte überschreibt (z.B. „Dedicated-Stack erhöht mailsPerMonth auf
- * 100k"), nicht den ganzen Shape neu definiert.
+ * `capOverrides` is `Partial<TCaps>` because an add-on overrides only
+ * individual cap values (e.g. “Dedicated-Stack increases mailsPerMonth to
+ * 100k”), rather than redefining the entire shape.
  */
 export type AddOnDefinition<TCaps extends Readonly<Record<string, unknown>>> = {
   /** Feature names to mount additionally when this add-on is active. */
@@ -70,7 +70,7 @@ export type ComposedApp<TCaps extends Readonly<Record<string, unknown>>> = {
  * composeApp — compute the feature-set + caps for a platform-tenant.
  *
  * **Contract:**
- *   1. base features always mount (Tier-Engine itself ist Teil davon)
+ *   1. base features always mount (the Tier-Engine itself is part of them)
  *   2. plus tier-specific features (from tierMap[tier].features)
  *   3. plus add-on features (from addOnMap[addOn].features for each active add-on)
  *   4. caps = tier.caps ⊕ add-on.capOverrides (later add-ons override earlier)

package/packages/bundled-features/src/tier-engine/entity.ts

@@ -5,28 +5,27 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { type TierAssignmentSource, TierAssignmentSources } from "./web/constants.ts";
 
-// tier-assignment — pro Plattform-Tenant genau ein Aggregat. Aggregate-ID
-// wird deterministisch aus tenantId abgeleitet (uuidv5, siehe aggregate-id.ts).
+// tier-assignment — exactly one aggregate per platform tenant. The aggregate ID
+// is derived deterministically from tenantId (uuidv5; see aggregate-id.ts).
 //
-// **Tenant-Scope:** automatisch via Kumiko's tenant-scoped projection — die
-// `tenantId`-Spalte wird vom Framework als Base-Column hinzugefügt, der
-// CrudExecutor befüllt sie aus `event.user.tenantId`. Pro Plattform-Tenant
-// gibt es genau eine Tier-Assignment-Row.
+// **Tenant scope:** applied automatically by Kumiko's tenant-scoped projection —
+// the framework adds `tenantId` as a base column, and the CrudExecutor populates
+// it from `event.user.tenantId`. Each platform tenant has exactly one
+// Tier-Assignment row.
 //
-// **Felder**
-//   - tier: TierName-String (z.B. "free", "pro", "business", "enterprise",
-//     "self-host"). Welche Tier-Werte gültig sind, definiert die App in
-//     ihrer TierMap (siehe compose-app.ts) — die Engine selbst hat keine
-//     enumerierte Tier-Liste.
+// **Fields**
+//   - tier: a TierName string (for example, "free", "pro", "business",
+//     "enterprise", or "self-host"). The app defines valid tier values in its
+//     TierMap (see compose-app.ts); the engine has no enumerated tier list.
 //
-// **Was bewusst NICHT in der Entity steht**
-//   - tenantId: kommt automatisch als Base-Column.
-//   - validFrom/validTo: ES-redundant (Events tragen Timestamps nativ,
-//     time-travel über `ctx.loadAggregate({ asOf })`).
-//   - addOns: Sprint 1 hat keine Add-Ons. Sprint 4 fügt sie als separate
-//     `tier-add-on`-Entity hinzu (1:n Relation, ES-saubere Add/Remove-Events
-//     mit klarer Audit-Granularität statt JSON-Array-Replace).
-//   - Caps-Werte: pro-Tier-Cap-Definitionen leben in der TierMap der App.
+// **Intentionally omitted from the entity**
+//   - tenantId: added automatically as a base column.
+//   - validFrom/validTo: redundant for event sourcing (events carry timestamps
+//     natively; time travel uses `ctx.loadAggregate({ asOf })`).
+//   - addOns: represented by a separate `tier-add-on` entity (1:n relation),
+//     allowing event-sourced Add/Remove events with clear audit granularity
+//     instead of replacing a JSON array.
+//   - Cap values: per-tier cap definitions belong in the app's TierMap.
 export const tierAssignmentEntity = createEntity({
   table: "read_tier_assignments",
   description:

package/packages/bundled-features/src/tier-engine/feature.ts

@@ -1,46 +1,45 @@
-// tier-engine — Pricing-Tier-Mechanik als reguläres Bundled-Feature.
+// tier-engine — pricing-tier mechanics as a regular bundled feature.
 //
-// **Was diese Feature macht:**
-//   Speichert pro Plattform-Tenant ein Tier-Assignment (welcher Tier ist
-//   aktiv). Optional (mit `tierMap` in Options): per-tenant feature-set
-//   resolution via Framework's `tenantTierResolver`-extension — das
-//   dispatcher-feature-gate fragt automatisch pro request den resolver
-//   nach dem effective Set für den aktiven Tenant.
+// **What this feature does:**
+//   Stores one tier assignment per platform tenant (the active tier). With
+//   `tierMap` in the options, it also resolves the per-tenant feature set via
+//   the framework's `tenantTierResolver` extension; the dispatcher feature gate
+//   automatically asks the resolver for the active tenant's effective set.
 //
-// **Zwei Use-Modes:**
-//   1. `createTierEngineFeature()` ohne opts — nur Storage (Standard-CRUD
-//      für tier-assignment-Entity). Apps die composeApp() oder eigene
-//      logic nutzen.
-//   2. `createTierEngineFeature({ defaultTier, tierMap })` — vollständige
-//      Tier-Composition. Sprint-8a Pattern für multi-tenant SaaS-Apps.
-//      Framework auto-wires effectiveFeatures via extension-pickup.
+// **Two usage modes:**
+//   1. `createTierEngineFeature()` without options — storage only (standard CRUD
+//      for the tier-assignment entity). Apps can use `composeApp()` or their
+//      own logic.
+//   2. `createTierEngineFeature({ defaultTier, tierMap })` — complete tier
+//      composition for multi-tenant SaaS apps. The framework auto-wires
+//      effectiveFeatures through extension pickup.
 //
-// **Generic über Tier-Werte:** das Feature kennt keine "free"/"pro"/etc.
-//   konkreten Tier-Werte. App definiert ihre TierMap.
+// **Generic over tier values:** the feature knows no concrete `free`/`pro`/etc.
+//   tier values. The app defines its tier map.
 //
-// **Auto-Default-Tier on Tenant-Signup:** wenn `opts.defaultTier` gesetzt
-//   ist, schreibt ein r.entityHook("postSave", "tenant", phase: inTransaction)
-//   automatisch eine tier-assignment für den neuen Tenant. Atomic mit
-//   tenant-create — wenn tier-assignment fail't, tenant-create rolled back.
-//   Idempotent via deterministic aggregate-id (re-replay re-checkt stream-
-//   version, skip wenn schon da). Plus: cache-miss-fallback returnt
-//   defaultTier-features wenn assignment-row fehlt (defense-in-depth gegen
-//   replay-races wo der hook noch nicht durch ist).
+// **Auto-default tier on tenant signup:** when `opts.defaultTier` is set, an
+//   `r.entityHook("postSave", "tenant", phase: inTransaction)` automatically
+//   writes a tier assignment for the new tenant. The write is atomic with
+//   tenant creation: if it fails, tenant creation is rolled back. It is
+//   idempotent through a deterministic aggregate ID; replay re-checks the
+//   stream version and skips the write if it already exists. A cache-miss
+//   fallback also returns the default tier's features when the assignment row
+//   is missing, protecting against races while the hook is still running.
 //
-// **In-Memory-Cache mit Push-Invalidation:**
-//   Closure-state pro feature-instance hält die effective Sets pro Tenant.
-//   r.entityHook auf tier-assignment:postSave/postDelete hält cache aktuell.
-//   Erste-Request-Cold-Cache: pre-load via build(deps) im extension-pickup
-//   Pfad (boot-time via runDevApp/runProdApp).
+// **In-memory cache with push invalidation:**
+//   Closure state per feature instance stores each tenant's effective sets.
+//   `r.entityHook` on tier-assignment postSave/postDelete keeps the cache
+//   current. The extension-pickup path pre-loads the cache through build(deps)
+//   at boot via runDevApp/runProdApp.
 //
-// **SYSTEM_TENANT_ID-Convention:**
-//   resolver-callback bei call mit SYSTEM_TENANT_ID returnt union aller
-//   tier-features (für event-dispatcher async-pass + operator-tooling).
-//   Siehe DispatcherOptions.effectiveFeatures-doc.
+// **SYSTEM_TENANT_ID convention:**
+//   A resolver callback invoked with SYSTEM_TENANT_ID returns the union of all
+//   tier features for asynchronous event dispatch and operator tooling.
+//   See the DispatcherOptions.effectiveFeatures documentation.
 //
-// **Boot-Dependencies:** config + tenant.
+// **Boot dependencies:** config + tenant.
 
-// kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312 (feature.ts > 300 lines)
+// kumiko-lint-ignore app-feature-structure feature.ts is over 300 lines and not yet split
 import {
   buildEntityTable,
   createEventStoreExecutor,
@@ -95,61 +94,63 @@ import { TIER_ENGINE_I18N } from "./web/i18n.ts";
 const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
 const log = createFallbackLogger("tier-engine");
 
-// Event-store-executor für direct-write aus dem auto-default-tier-hook.
-// Pattern wie tenant/seeding.ts: hook sieht AppContext (kein ctx.write),
-// muss aber atomisch mit tenant-create im selben TX schreiben → executor
-// direkt aufrufen, nicht via dispatcher.
+// Event-store executor for direct writes from the auto-default-tier hook.
+// Like tenant/seeding.ts, the hook receives AppContext (not ctx.write), but it
+// must write atomically with tenant creation in the same transaction. Call the
+// executor directly rather than going through the dispatcher.
 const tierAssignmentExecutor = createEventStoreExecutor(tierAssignmentTable, tierAssignmentEntity, {
   entityName: "tier-assignment",
 });
 
 const adminAccess = { access: { roles: ["TenantAdmin", "SystemAdmin"] } } as const;
-// Tier-Wechsel ist Plattform-/Billing-Hoheit — ein Tenant-Admin darf den
-// eigenen Tier NIE setzen (sonst Gratis-Self-Upgrade). Daher sind die
-// Writes SystemAdmin-only; Reads (list, get-active-tier) bleiben
-// TenantAdmin-sichtbar. Auto-default-Hook + Billing schreiben als System,
-// hängen also nicht an diesem Handler-Access.
+// Tier changes are controlled by the platform and billing: a TenantAdmin must
+// never set its own tier, which would allow a free self-upgrade. Writes are
+// therefore SystemAdmin-only, while reads (list, get-active-tier) remain visible
+// to TenantAdmin. The auto-default hook and billing write as the system, so they
+// are not subject to this handler access.
 const writeAccess = { access: { roles: ["SystemAdmin"] } } as const;
 
 /**
- * Options for createTierEngineFeature. Both fields optional — wenn beide
- * leer, ist die feature nur Storage (back-compat zu legacy `tierEngineFeature`).
+ * Options for createTierEngineFeature. Both fields are optional; when both are
+ * omitted, the feature provides storage only (backward compatibility with the
+ * legacy `tierEngineFeature`).
  *
- * @template TCaps - App-spezifischer Cap-Shape. Type-leakt durch tierMap →
- * future capsFor() resolver returnt diesen Shape exakt.
+ * @template TCaps - App-specific capability shape. It flows through tierMap,
+ * so a future capsFor() resolver returns this exact shape.
  */
 export type CreateTierEngineOptions<TCaps extends Readonly<Record<string, unknown>>> = {
   /**
-   * Tier-Name der bei Tenant-signup automatisch geschrieben wird. Erfordert
-   * dass `tierMap` diesen Tier-Namen kennt (Boot-Validation).
-   * Wenn weggelassen, kein auto-assign — App schreibt manuell.
+   * Tier name written automatically when a tenant signs up. `tierMap` must
+   * contain this tier name; this is validated at boot.
+   * When omitted, no tier is assigned automatically and the app writes it
+   * manually.
    */
   readonly defaultTier?: string;
 
   /**
-   * App-spezifische Tier-Map. Wenn gesetzt, registriert das feature sich
-   * als plugin für `tenantTierResolver`-extension → framework auto-wires
-   * effectiveFeatures pro tenant.
-   * Wenn weggelassen, keine Resolver-extension — App muss `composeApp`
-   * oder eigene resolution-logic nutzen (legacy-pattern).
+   * App-specific tier map. When set, the feature registers as a plugin for the
+   * `tenantTierResolver` extension, so the framework automatically wires
+   * effectiveFeatures per tenant.
+   * When omitted, no resolver extension is registered; the app must use
+   * `composeApp` or its own resolution logic.
    */
   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.
+   * Optional trial phase: each tenant receives the features of `trial.tier` in
+   * addition to its stored tier for `durationHours` after creation, then
+   * automatically falls back to its stored tier. Requires `tierMap` to contain
+   * the trial tier. The result is derived from inserted_at; no stored flag or
+   * scheduler is used.
    */
   readonly trial?: TrialPolicy;
 };
 
 /**
- * Compute the union of features across all tiers — verwendet bei
- * SYSTEM_TENANT_ID-resolver-call (operator-tooling, async-event-dispatch).
- * Operator-UI sieht alle features unabhängig vom tier-cut, async-events
- * laufen tier-agnostic durch.
+ * Computes the union of features across all tiers for a
+ * SYSTEM_TENANT_ID resolver call used by operator tooling and asynchronous
+ * event dispatch. The operator UI sees every feature regardless of tier, and
+ * asynchronous events run without tier restrictions.
  */
 function unionAllTierFeatures<TCaps extends Readonly<Record<string, unknown>>>(
   tierMap: TierMap<TCaps>,
@@ -162,9 +163,9 @@ function unionAllTierFeatures<TCaps extends Readonly<Record<string, unknown>>>(
 }
 
 /**
- * Compute the feature-set for a given tier-name. Unknown tier → empty Set
- * (defensive — verwendete tier-namen werden nicht an boot-time validiert
- * weil tier-engine generic über tier-Werte ist).
+ * Computes the feature set for a tier name. An unknown tier returns an empty
+ * Set defensively because tier names are not validated at boot; tier-engine is
+ * generic over tier values.
  */
 function featuresForTier<TCaps extends Readonly<Record<string, unknown>>>(
   tierMap: TierMap<TCaps>,
@@ -176,10 +177,10 @@ function featuresForTier<TCaps extends Readonly<Record<string, unknown>>>(
 }
 
 /**
- * Merge always-on features (non-toggleable framework-base) mit tier-cut
- * features (toggleable per tier). Canonical Kumiko: dispatcher-gate
- * blockt nur features die explizit `r.toggleable()` haben — alle anderen
- * sind immer aktiv. Tier-resolver muss das selbe pattern liefern.
+ * Merges always-on features (non-toggleable framework base) with tier-specific
+ * features (toggleable per tier). The dispatcher gate blocks only features
+ * that explicitly register `r.toggleable()`; all others are always active.
+ * The tier resolver must provide the same shape.
  */
 function mergeAlwaysOn(
   alwaysOn: ReadonlySet<string>,
@@ -239,13 +240,14 @@ export function createTierEngineFeature<
       );
       r.queryHandler(getActiveTierQuery);
 
-      // \u2500\u2500 Manueller Tier-Grant (SystemAdmin, ohne Billing) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-      // Cross-tenant set + read f\u00fcr den tier-admin-Screen. tier-options liefert
-      // dem Client die App-Tier-Namen aus der tierMap-Closure (sonst hartkodiert).
+      // ── Manual tier grant (SystemAdmin, without billing) ───────────────────────
+      // Cross-tenant set and read for the tier-admin screen. tier-options gives
+      // the client the app's tier names from the tierMap closure rather than
+      // hard-coding them.
       //
       // onAssigned runs after commit (the direct executor write fires no postSave
-      // hook). Late-bound: without tierMap it stays a no-op, the tierMap block
-      // below installs the real cache update + publish.
+      // hook). It is late-bound: without tierMap it remains a no-op; the tierMap
+      // block below installs the actual cache update and publication.
       const onTierAssigned: { fn: (tenantId: TenantId, tier: string) => void } = { fn: () => {} };
       r.writeHandler(
         createSetTenantTierWrite({
@@ -310,11 +312,11 @@ export function createTierEngineFeature<
       });
 
       // ───────────────────────────────────────────────────────────────────
-      // Resolver-extension (only when tierMap is configured)
+      // Resolver extension (only when tierMap is configured)
       // ───────────────────────────────────────────────────────────────────
-      // skip: ohne tierMap ist die feature nur Storage (legacy back-compat
-      // zu `tierEngineFeature`). Resolver-extension + invalidation-hooks
-      // brauchen die tierMap zum Mapping tier-name → feature-set.
+      // skip: without tierMap, the feature provides storage only (backward
+      // compatibility with `tierEngineFeature`). The resolver extension and
+      // invalidation hooks need tierMap to map tier names to feature sets.
       if (!opts.tierMap) return;
 
       const tierMap = opts.tierMap;
@@ -414,7 +416,7 @@ export function createTierEngineFeature<
       // tier-assignment.
       //
       // **Cross-tenant write:** the executor needs a systemUser WITH tenantId =
-      // the new tenant (memory `feedback_event_store_tenant_consistency`).
+      // the new tenant.
       if (opts.defaultTier !== undefined) {
         const defaultTier = opts.defaultTier;
         const autoDefaultTierHookReason =
@@ -459,8 +461,7 @@ export function createTierEngineFeature<
             // SystemUser for the NEW tenant — the hook is triggered by the signup
             // user (another tenant, or SystemAdmin), but the tier-assignment has
             // to land in the stream of the newly created tenant (= aggregate id
-            // deterministic on newTenantId). Memory
-            // `feedback_event_store_tenant_consistency`: by.tenantId must equal
+            // deterministic on newTenantId), so by.tenantId must equal
             // the target tenant.
             const systemUser: SessionUser = {
               id: "00000000-0000-4000-8000-000000000001",
@@ -506,7 +507,7 @@ export function createTierEngineFeature<
 
           // Pre-load all existing assignments into the cache. SaaS apps typically
           // have <100k tenants, so a single-pass scan is acceptable. The scaling
-          // path (lazy load + LRU) is Sprint-8b, once a real need arises.
+          // path (lazy load + LRU) is planned once a real need arises.
           type AssignmentRow = { tenantId: string; tier: string };
           const rows = await selectMany<AssignmentRow>(deps.db, tierAssignmentTable);
           for (const row of rows) {
@@ -586,8 +587,8 @@ export function createTierEngineFeature<
             }
             // Cache miss: the tenant is not in the cache yet (e.g. brand new after
             // boot, or the defaultTier hook has not fired yet). The default set
-            // is least-privileged — typically free-tier features. Memory
-            // `feedback_security_default_on`: secure by default. The trial is NOT
+            // is least-privileged, secure by default: typically free-tier features.
+            // The trial is NOT
             // added here (sync/boot-cached, cannot see the passage of time) — the
             // trialGate below does that on the disabled-gate path.
             const fallbackTier = opts.defaultTier;

package/packages/bundled-features/src/tier-engine/handlers/active-tier.query.ts

@@ -1,15 +1,14 @@
 import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 
-// get-active-tier — return the current tier-assignment for the calling tenant.
+// get-active-tier — returns the current tier assignment for the calling tenant.
 //
-// **Convenience-wrapper** über `ctx.queryProjection` für die häufigste Frage
-// gegen die Engine: „welcher Tier ist gerade aktiv?". Returns null wenn
-// noch kein Tier gesetzt — der Caller (composeApp) mappt null → Default-Tier.
+// Wraps `ctx.queryProjection` for the most common engine query: which tier is
+// currently active. Returns null when no tier is assigned; the caller (composeApp)
+// maps null to the default tier.
 //
-// **Tenant-scope:** ctx.queryProjection filtert automatisch nach tenantId.
-// Pro Plattform-Tenant existiert per Konvention genau eine
-// tier-assignment-Row.
+// **Tenant scope:** `ctx.queryProjection` automatically filters by tenantId.
+// By convention, each platform tenant has exactly one tier-assignment row.
 export const getActiveTierQuery: QueryHandlerDef = {
   name: "get-active-tier",
   description:

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

@@ -3,10 +3,10 @@ import { defineQueryHandler, type TenantId } from "@cosmicdrift/kumiko-framework
 import * as z from "zod";
 import { type TierAssignmentRow, tierAssignmentEntity } from "../entity.ts";
 
-// Liest das Tier-Assignment eines BELIEBIGEN Tenants (cross-tenant) für den
-// tier-admin-Screen. SystemAdmin-only. get-active-tier liest nur den eigenen
-// Tenant — hier ein "system"-mode TenantDb auf den Ziel-Tenant (kein Filter),
-// damit der Admin das Tier fremder Tenants sehen kann. null wenn noch keins.
+// Reads the tier assignment of ANY tenant (cross-tenant) for the
+// tier-admin screen. SystemAdmin-only. get-active-tier reads only its own
+// tenant; this uses a "system"-mode TenantDb for the target tenant (no filter),
+// so the admin can view another tenant's tier. Returns null if none exists yet.
 
 const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
 

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

@@ -10,9 +10,9 @@ import { tierAssignmentAggregateId } from "../aggregate-id.ts";
 import { type TierAssignmentRow, tierAssignmentEntity } from "../entity.ts";
 import { type TierAssignmentSource, TierAssignmentSources } from "../web/constants.ts";
 
-// SystemAdmin setzt das Tier eines BELIEBIGEN Tenants — manueller Grant ohne
-// Billing. Cross-tenant, daher SystemAdmin-only (kein TenantAdmin: sonst
-// Gratis-Self-Upgrade).
+// A SystemAdmin can set the tier of ANY tenant as a manual grant without
+// billing. This is cross-tenant, so it is restricted to SystemAdmin (not
+// TenantAdmin, which would allow free self-upgrades).
 //
 // Cross-tenant mechanics: ctx.forTenant(tenantId) yields a tenant-mode db bound to the target plus
 // the streamTenantId, so the event lands in the target's stream with the operator as actor.
@@ -39,11 +39,11 @@ export type SetTenantTierOptions = {
    *  and notify the other processes. Without a tierMap there is no resolver
    *  and this is a no-op. */
   readonly onAssigned?: (tenantId: TenantId, tier: string) => void;
-  /** Tier-Namen aus der tierMap-Closure — ohne sie (storage-only-Mode) bleibt
-   *  `tier` unvalidiert außer Length/Non-Empty. Mit ihr rejected der Handler
-   *  einen unbekannten Tier-Namen statt ihn stillschweigend durchzuschreiben
-   *  (featuresForTier gibt für unbekannte Namen defensiv ein leeres Set
-   *  zurück — der Tenant verliert sonst lautlos alle Tier-Gates). */
+  /** Without the tierMap closure (storage-only mode), `tier` is validated only for
+   *  length and non-emptiness. With it, the handler rejects unknown tier names
+   *  instead of silently writing them through. (featuresForTier defensively
+   *  returns an empty set for unknown names; otherwise the tenant would silently
+   *  lose all tier gates.) */
   readonly validTiers?: ReadonlySet<string>;
 };
 

package/packages/bundled-features/src/tier-engine/tier-resolver.ts

@@ -1,6 +1,6 @@
 // Generic tier-resolver factory. Extracted from the near-identical
-// tier-resolver.ts app copies in show-pony and publicstatus (infra#446) — the
-// only per-app variables were the TierName union and its caps/defaults, so
+// tier-resolver.ts app copies in show-pony and publicstatus — the only
+// per-app variables were the TierName union and its caps/defaults, so
 // both are now factory parameters.
 
 import { buildEntityTable, type TenantDb } from "@cosmicdrift/kumiko-framework/db";

package/packages/bundled-features/src/tier-engine/trial.ts

@@ -1,22 +1,22 @@
-// 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.
+// Trial phase: a new tenant receives the features of a higher tier for a grace
+// period starting at its creation date (`inserted_at` of the tier-assignment Row —
+// stable across rebuilds because it comes from the Create Event), regardless of
+// the stored tier. It is derived solely from time: no stored flag, no scheduler,
+// and automatic expiration. The app defines the policy (which tier, how long);
+// the tier-engine applies it in the resolver.
 
 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).
+  // Tier whose features are additionally enabled during the trial phase
+  // (must be a key in tierMap; otherwise no feature takes effect).
   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.
+  // Length of the trial phase from inserted_at, in hours (720 = 30 days). Hours
+  // are used instead of days because Temporal.Instant has no calendar days; 720h
+  // is the accurate, DST-independent duration.
   readonly durationHours: number;
 }
 
-// Reine Millis-Arithmetik auf epochMilliseconds (die beide Seiten — Projektions-
-// Row und Now — liefern). Kein Date, keine TZ.
+// Pure millisecond arithmetic on epochMilliseconds, which both sides—the
+// projection Row and Now—provide. No Date and no time zone.
 export function isTrialActive(
   startedAtEpochMs: number,
   nowEpochMs: number,

package/packages/bundled-features/src/tier-engine/web/index.ts

@@ -1,6 +1,6 @@
-// Public exports für die Browser-Seite des tier-engine Features. Konsumiert
-// über `@cosmicdrift/kumiko-bundled-features/tier-engine/web` — die
-// Server-Seite (createTierEngineFeature) lebt unter
-// `@cosmicdrift/kumiko-bundled-features/tier-engine` und hat keine React-Deps.
+// Public exports for the browser side of the tier-engine feature. Import via
+// `@cosmicdrift/kumiko-bundled-features/tier-engine/web` — the server side
+// (createTierEngineFeature) is under
+// `@cosmicdrift/kumiko-bundled-features/tier-engine` and has no React deps.
 
 export { type TierEngineClientOptions, tierEngineClient } from "./client-plugin.tsx";

package/packages/bundled-features/src/user/db/queries/stream-tenant-backfill.ts

@@ -1,11 +1,11 @@
-// #762 — one-time migration tooling for pre-#497 user event streams.
+// One-time migration tooling for older user event streams.
 //
-// #497 made `user` a systemStream entity: every executor op addresses the
+// Making `user` a systemStream entity means every executor op addresses the
 // stream on SYSTEM_TENANT_ID. Streams created before that live on whichever
-// tenant created them ("scattered"), so post-#497 writes version-conflict
-// against the empty SYSTEM stream. The raw UPDATE documented in the #497
-// changeset breaks as soon as an aggregate has BOTH a legacy stream and
-// post-#497 SYSTEM events (split stream — e.g. a skipOptimisticLock
+// tenant created them ("scattered"), so newer writes version-conflict
+// against the empty SYSTEM stream. The raw UPDATE breaks as soon as an
+// aggregate has BOTH a legacy stream and newer SYSTEM events
+// (split stream — e.g. a skipOptimisticLock
 // lifecycle write appended v1 on SYSTEM while v1..n live on the old
 // tenant): retenanting then trips events_aggregate_version_uq.
 //
@@ -75,7 +75,7 @@ async function migrateAggregate(db: DbConnection, aggregateId: string): Promise<
       [aggregateId],
     );
 
-    // Phase 1: negative interim versions — real versions are always >= 1, so
+    // Negative interim versions — real versions are always >= 1, so
     // nothing can collide with events_aggregate_version_uq mid-migration.
     for (const [i, ev] of events.entries()) {
       await raw.unsafe(
@@ -83,7 +83,7 @@ async function migrateAggregate(db: DbConnection, aggregateId: string): Promise<
         [SYSTEM_TENANT_ID, -(i + 1), ev.id],
       );
     }
-    // Phase 2: final contiguous 1..n.
+    // Final contiguous 1..n.
     for (const [i, ev] of events.entries()) {
       await raw.unsafe(`UPDATE "kumiko_events" SET "version" = $1 WHERE "id" = $2`, [i + 1, ev.id]);
     }

package/packages/bundled-features/src/user/handlers/create.write.ts

@@ -22,14 +22,14 @@ const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user
 
 // Only the Auth features (running as SYSTEM) or a SystemAdmin may create users.
 //
-// Email uniqueness has two layers (fw#2134):
+// Email uniqueness has two layers:
 // 1. A pre-flight fetchOne — fast-fails with a friendly error on the
 // common case, but is race-prone on its own: two concurrent requests
 // can both see "no duplicate" and both proceed to crud.create.
 // 2. The real guard is the unique index over email's blind-index column
 // (schema/user.ts). A losing concurrent create hits that constraint
-// and crud.create returns a UniqueViolationError (framework's F8
-// pg-23505 mapping) instead of throwing — remapped below to the same
+// and crud.create returns a UniqueViolationError (framework's pg-23505
+// mapping) instead of throwing — remapped below to the same
 // emailAlreadyExists shape the pre-flight path returns, so callers see
 // one consistent error regardless of which layer caught the race.
 export const createWrite = defineWriteHandler({
@@ -114,7 +114,7 @@ export const createWrite = defineWriteHandler({
 // schema/user.ts's `read_users_email_unique` (+ its generated `_bidx`
 // pendant) is the actual race-safety net behind the pre-flight check
 // above — a losing concurrent create surfaces here as a generic
-// UniqueViolationError (framework F8 pg-23505 mapping). Only the email
+// UniqueViolationError (framework pg-23505 mapping). Only the email
 // constraint gets remapped; any other unique_violation on this entity
 // passes through unchanged.
 function isRecord(value: unknown): value is Record<string, unknown> {