@cosmicdrift/kumiko-bundled-features 0.385.0 → 0.387.0

package/dist/tenant-settings/constants.js

@@ -11,7 +11,7 @@ export const TENANT_SETTINGS_FEATURE_NAME = "tenant-settings";
 // strings (mirror tags' Handlers/Queries constants).
 export const TenantSettingsConfig = {
     // Shared with engine/constants.ts's TENANT_CURRENCY_CONFIG_KEY — a
-    // `money` field's `currency: { kind: "tenant" }` declaration (fw#2933)
+    // `money` field's `currency: { kind: "tenant" }` declaration
     // resolves against this same key.
     currency: TENANT_CURRENCY_CONFIG_KEY,
     locale: "tenant-settings:config:locale",

package/dist/tenant-settings/tenant-defaults.d.ts

@@ -2,7 +2,7 @@ import { type AccessRule, type EntityDefinition, type WriteHandlerDef } from "@c
 export declare function defineCreateWithTenantDefaults(entityName: string, entity: EntityDefinition, options: {
     /** Required — this is a write-path helper; making it optional let a
      *  forgetful caller register a create handler with no access rule at
-     *  all (fw#1581). */
+     *  all. */
     readonly access: AccessRule;
     /** Money field names whose `currency` is filled from tenant-settings when missing. */
     readonly currencyFields?: readonly string[];

package/dist/tenant-settings/tenant-defaults.js

@@ -8,6 +8,8 @@
 // a schema extension that makes those sub-keys optional, instead of the
 // generic defineEntityCreateHandler.
 import { buildInsertSchema, createEntityExecutor, } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { TenantSettingsConfig } from "./constants.js";
 const OPTIONAL_CURRENCY_MONEY = z.object({ amount: z.number(), currency: z.string().optional() });
@@ -31,10 +33,15 @@ export function defineCreateWithTenantDefaults(entityName, entity, options) {
         schema,
         access: options.access,
         handler: async (event, ctx) => {
+            if (!isPlainObject(event.payload)) {
+                throw new InternalError({
+                    message: `${entityName}:create payload must be an object after schema validation`,
+                });
+            }
             const payload = { ...event.payload };
             for (const field of options.currencyFields ?? []) {
                 const value = payload[field];
-                if (value && typeof value === "object" && !value.currency) {
+                if (isPlainObject(value) && !value["currency"]) {
                     const currency = await ctx.config?.(TenantSettingsConfig.currency);
                     if (typeof currency === "string")
                         payload[field] = { ...value, currency };
@@ -46,7 +53,7 @@ export function defineCreateWithTenantDefaults(entityName, entity, options) {
                     payload[options.localeField] = locale;
             }
             // Re-validate against the unrelaxed entity schema so config-filled
-            // values still honor select/enum field constraints (fw#1581) — and so
+            // values still honor select/enum field constraints — and so
             // a missing currency after failed/missing tenant-settings mount fails
             // loud instead of inserting half-filled money rows.
             const filled = baseSchema.parse(payload);

package/dist/tier-engine/aggregate-id.d.ts

@@ -1,16 +1,16 @@
 /**
- * Deterministic aggregate-id für ein Tier-Assignment aus dem tenantId.
- * Pro Plattform-Tenant existiert genau ein Aggregat — uuidv5 ist
- * namespace-deterministic, identische Eingabe ergibt identischen UUID.
+ * Deterministic aggregate ID for a tier assignment derived from `tenantId`.
+ * Each platform tenant has exactly one aggregate; uuidv5 is namespace-
+ * deterministic, so identical input produces the same UUID.
  *
- * **Wann nutzen:** Sprint 5 (`stripe-sync`-Feature) wrapt einen
- * idempotent-set-tier-Handler darum: zweiter Stripe-Webhook-Retry mit
- * derselben tenantId → derselbe aggregate-Stream → version_conflict
- * vom Event-Store statt pg-23505 von der Read-Model-DB. ES-saubere
- * Path-Uniqueness statt DB-Constraint.
+ * **When to use:** The `stripe-sync` feature wraps an idempotent
+ * set-tier handler with this function: a second Stripe webhook retry for
+ * the same `tenantId` targets the same aggregate stream, causing
+ * `version_conflict` from the event store instead of `pg-23505` from the
+ * read-model database. This enforces path uniqueness rather than a database
+ * constraint.
  *
- * **Sprint 1 nutzt das nicht aktiv** — Standard-CRUD-Handlers vergeben
- * UUID via `gen_random_uuid()`. Die Funktion lebt hier als Utility-
- * Export bereit für Sprint 5.
+ * Standard CRUD handlers instead generate UUIDs via `gen_random_uuid()`.
+ * This utility is exported for use by the `stripe-sync` feature.
  */
 export declare function tierAssignmentAggregateId(tenantId: string): string;

package/dist/tier-engine/aggregate-id.js

@@ -1,24 +1,23 @@
 import { v5 as uuidv5 } from "uuid";
-// Fixed UUID-namespace für die tier-assignment-aggregate-id-Ableitung.
-// Generiert einmalig (2026-05-02), in Stein gemeißelt: ein Wechsel würde
-// jeden existing aggregate-Stream re-keyen → kaputter event-replay,
-// kaputte projection-rebuilds, verlorener Tier-Wechsel-Audit. Der
-// drift-pin-Test in feature.test.ts pinnt diese Konstante.
+// Fixed UUID namespace for deriving tier-assignment aggregate IDs.
+// Generated once and immutable: changing it would re-key every existing
+// aggregate stream, breaking event replay and projection rebuilds and losing
+// the tier-change audit. The drift-pin test in feature.test.ts pins this constant.
 const TIER_ASSIGNMENT_NAMESPACE = "8e91d2fc-8b7a-4d3e-9f4a-1c5d6e7f8a9b";
 /**
- * Deterministic aggregate-id für ein Tier-Assignment aus dem tenantId.
- * Pro Plattform-Tenant existiert genau ein Aggregat — uuidv5 ist
- * namespace-deterministic, identische Eingabe ergibt identischen UUID.
+ * Deterministic aggregate ID for a tier assignment derived from `tenantId`.
+ * Each platform tenant has exactly one aggregate; uuidv5 is namespace-
+ * deterministic, so identical input produces the same UUID.
  *
- * **Wann nutzen:** Sprint 5 (`stripe-sync`-Feature) wrapt einen
- * idempotent-set-tier-Handler darum: zweiter Stripe-Webhook-Retry mit
- * derselben tenantId → derselbe aggregate-Stream → version_conflict
- * vom Event-Store statt pg-23505 von der Read-Model-DB. ES-saubere
- * Path-Uniqueness statt DB-Constraint.
+ * **When to use:** The `stripe-sync` feature wraps an idempotent
+ * set-tier handler with this function: a second Stripe webhook retry for
+ * the same `tenantId` targets the same aggregate stream, causing
+ * `version_conflict` from the event store instead of `pg-23505` from the
+ * read-model database. This enforces path uniqueness rather than a database
+ * constraint.
  *
- * **Sprint 1 nutzt das nicht aktiv** — Standard-CRUD-Handlers vergeben
- * UUID via `gen_random_uuid()`. Die Funktion lebt hier als Utility-
- * Export bereit für Sprint 5.
+ * Standard CRUD handlers instead generate UUIDs via `gen_random_uuid()`.
+ * This utility is exported for use by the `stripe-sync` feature.
  */
 // @wrapper-known uuid-domain
 export function tierAssignmentAggregateId(tenantId) {

package/dist/tier-engine/compose-app.d.ts

@@ -2,17 +2,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). */
@@ -24,9 +24,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. */
@@ -60,7 +60,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/dist/tier-engine/compose-app.js

@@ -2,7 +2,7 @@
  * 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/dist/tier-engine/entity.js

@@ -1,27 +1,26 @@
 import { createEntity, createSelectField, createTextField, } from "@cosmicdrift/kumiko-framework/engine";
 import { TierAssignmentSources } from "./web/constants.js";
-// 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: "The pricing tier currently assigned to a tenant, plus where the assignment came from (manual grant, billing sync or signup default) — one row per tenant.",

package/dist/tier-engine/feature.d.ts

@@ -2,33 +2,35 @@ import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import type { TierMap } from "./compose-app.ts";
 import { type TrialPolicy } from "./trial.ts";
 /**
- * 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;
 };

package/dist/tier-engine/feature.js

@@ -1,45 +1,44 @@
-// 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.
-// kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312 (feature.ts > 300 lines)
+// **Boot dependencies:** config + tenant.
+// kumiko-lint-ignore app-feature-structure feature.ts is over 300 lines and not yet split
 import { buildEntityTable, createEventStoreExecutor, createTenantDb, fetchOne, selectMany, } from "@cosmicdrift/kumiko-framework/db";
 import { defineEntityCreateHandler, defineEntityListHandler, defineEntityUpdateHandler, defineFeature, defineQueryHandler, HookPhases, SYSTEM_TENANT_ID, TENANT_TIER_RESOLVER_EXT, } from "@cosmicdrift/kumiko-framework/engine";
 import { getUnscopedAggregateStreamMaxVersion } from "@cosmicdrift/kumiko-framework/event-store";
@@ -61,25 +60,25 @@ import { TIER_ENGINE_I18N } from "./web/i18n.js";
 // in the App's drizzle/schema.generated.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"] } };
-// 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"] } };
 /**
- * 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(tierMap) {
     const all = new Set();
@@ -90,9 +89,9 @@ function unionAllTierFeatures(tierMap) {
     return all;
 }
 /**
- * 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(tierMap, tierName) {
     const tier = tierMap[tierName];
@@ -101,10 +100,10 @@ function featuresForTier(tierMap, tierName) {
     return new Set(tier.features);
 }
 /**
- * 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, tierFeatures) {
     const merged = new Set(alwaysOn);
@@ -144,13 +143,14 @@ export function createTierEngineFeature(opts = {}) {
             description: "Lists the tier-assignment rows visible to the caller with tier name and assignment source; use it to see which plan is stored for a tenant.",
         }));
         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: () => { } };
         r.writeHandler(createSetTenantTierWrite({
             onAssigned: (tenantId, tier) => onTierAssigned.fn(tenantId, tier),
@@ -208,11 +208,11 @@ export function createTierEngineFeature(opts = {}) {
             dormant: true,
         });
         // ───────────────────────────────────────────────────────────────────
-        // 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;
@@ -307,7 +307,7 @@ export function createTierEngineFeature(opts = {}) {
         // 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 = "seeds the default tier-assignment stream of the tenant just created";
@@ -352,8 +352,7 @@ export function createTierEngineFeature(opts = {}) {
                     // 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 = {
                         id: "00000000-0000-4000-8000-000000000001",
@@ -458,8 +457,8 @@ export function createTierEngineFeature(opts = {}) {
                     }
                     // 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/dist/tier-engine/handlers/active-tier.query.js

@@ -1,13 +1,12 @@
 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 = {
     name: "get-active-tier",
     description: "Returns the tier-assignment row currently active for the caller's own tenant, or null when none is assigned; use it to answer which plan the caller is on.",

package/dist/tier-engine/handlers/get-tenant-tier.query.js

@@ -2,10 +2,10 @@ import { buildEntityTable, createTenantDb, fetchOne } from "@cosmicdrift/kumiko-
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { tierAssignmentEntity } from "../entity.js";
-// 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);
 const GET_TENANT_TIER_REASON = "SystemAdmin reads the tier of the tenant named in the payload";
 export const getTenantTierQuery = defineQueryHandler({

package/dist/tier-engine/handlers/set-tenant-tier.write.d.ts

@@ -5,11 +5,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>;
 };
 export declare function createSetTenantTierWrite(opts?: SetTenantTierOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"set-tenant-tier", z.ZodObject<{

package/dist/tier-engine/handlers/set-tenant-tier.write.js

@@ -5,9 +5,9 @@ import { requireForTenant } from "../../shared/index.js";
 import { tierAssignmentAggregateId } from "../aggregate-id.js";
 import { tierAssignmentEntity } from "../entity.js";
 import { TierAssignmentSources } from "../web/constants.js";
-// 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.