@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/tenant/testing.ts

@@ -1,8 +1,7 @@
-// /testing re-exportiert /seeding. Ehemalige Heimat der seed-Helpers,
-// jetzt nur noch Aggregation. Die Helpers leben in `/seeding` weil sie
-// genauso vom Dev-Server-Bootstrap (runDevApp) konsumiert werden — nicht
-// nur von Tests. Vertrag der Helpers ist stabil, test-spezifische
-// Knöpfe gehören NICHT hier rein (würde dev-boots brechen wenn jemand
-// einen lockout-test-Knopf einbaut).
+// `/testing` re-exports `/seeding`; it is no longer the home of the seed helpers.
+// The helpers live in `/seeding` because they are also consumed by the
+// development-server bootstrap (`runDevApp`), not only by tests. Keep their
+// stable contract here; test-specific options do not belong in this module,
+// because they could break development boots when a lockout-test option is added.
 
 export * from "./seeding.ts";

package/packages/bundled-features/src/tenant/web/constants.ts

@@ -21,11 +21,11 @@ export const MEMBER_ROLES_CELL_COMPONENT = "MemberRolesCell" as const;
 
 /** Closed allowlist for invite-role picker — never free text (escalation guard). */
 // Admin (rank 2) shares the invite-create screen with TenantAdmin — TenantAdmin
-// must not appear here or Admin sees an unassignable option (fw#2414).
+// must not appear here or Admin sees an unassignable option.
 export const DEFAULT_INVITE_ROLE_OPTIONS = ["User", "Editor", "Admin"] as const;
 // Full rank list for memberRolesEditScreen: it is prefilled with a member's
 // *current* roles, so it must represent every rank a membership can hold,
-// including TenantAdmin (fw#2452). The screen hides what the caller may not
+// including TenantAdmin. The screen hides what the caller may not
 // assign via TenantQueries.memberRoleAvailability.
 export const OWNER_INVITE_ROLE_OPTIONS = [
   "User",

package/packages/bundled-features/src/tenant-handover/events.ts

@@ -1,12 +1,10 @@
 import * as z from "zod";
 
-// Audit trail for a completed claim (kumiko-framework#3035's audit-entry
-// requirement: names the source tenant, destination tenant, entities and
-// their counts). Its own aggregate, decoupled from the transferred root's
-// stream — same reasoning as
-// sessions' SESSION_REVOKED_EVENT: a fresh aggregate id per occurrence needs
-// no predecessor version and can never conflict with a concurrent write on
-// the entity it describes.
+// Audit trail for a completed claim (audit-entry requirement: names the source tenant, destination
+// tenant, entities and their counts). Its own aggregate, decoupled from the transferred root's
+// stream — same reasoning as sessions' SESSION_REVOKED_EVENT: a fresh aggregate id per occurrence
+// needs no predecessor version and can never conflict with a concurrent write on the entity it
+// describes.
 //
 // _SHORT — r.defineEvent(short, schema) in feature.ts, framework prefixes it
 //          to the QN below.

package/packages/bundled-features/src/tenant-handover/feature.ts

@@ -9,7 +9,7 @@ import { createSignupHandoverProvider } from "./signup-handover-provider.ts";
 
 export type TenantHandoverFeatureOptions = ClaimTenantHandoverOptions;
 
-// tenant-handover — Option A from kumiko-framework#3035: the ONE write a
+// tenant-handover — the ONE write a
 // try-before-signup (or guest-checkout, demo-to-account) flow needs once an
 // anonymous run is done and the visitor has a fresh tenant. No general
 // tenant-merge tool, no copy — this is an ownership change on rows a

package/packages/bundled-features/src/tenant-handover/grant.ts

@@ -1,4 +1,4 @@
-// Try-before-signup ownership handover (kumiko-framework#3035), expressed as a
+// Try-before-signup ownership handover, expressed as a
 // row-bound grant: the subject is the transferred run's own row id, the
 // anchor is the SOURCE tenant id it currently lives under. Redeeming the
 // grant is the ownership change itself — the claim handler's commitAnchor

package/packages/bundled-features/src/tenant-handover/handlers/claim.write.ts

@@ -31,7 +31,7 @@ function notTransferable(entityType: string): ReturnType<typeof writeFailure> {
   );
 }
 
-// The try-before-signup ownership handover (kumiko-framework#3035): claims an
+// The try-before-signup ownership handover: claims an
 // anonymous run into the caller's own tenant, legitimized by a row-bound
 // grant the anonymous flow minted (see ../grant.ts). Idempotent — a second
 // call with the same token fails the same way a forged one would, because

package/packages/bundled-features/src/tenant-handover/move-entity-graph.ts

@@ -1,4 +1,4 @@
-// The actual ownership change (kumiko-framework#3035): raw SQL against the
+// The actual ownership change: raw SQL against the
 // read-model tables, because moving a row across the tenant boundary is
 // exactly the kind of write the framework's entity write map cannot express
 // (it is single-tenant-scoped by design — that boundary is the whole point
@@ -15,10 +15,10 @@
 // `transaction()` call, rolling back everything the handler already did).
 // `moveRootRow` — called as row-bound-grant's `commitAnchor` — is therefore
 // the ONLY statement that must itself combine the anchor-spend with the
-// first write (#3023's hard rule: a write issued after `ok: true` can lose
-// its work to a crash while the grant is already burned). Everything after
+// first write: a write issued after `ok: true` can lose
+// its work to a crash while the grant is already burned. Everything after
 // it rides the same transaction: if a later step throws (an undeclared
-// child entity, kumiko-framework#3035's named-error requirement), the WHOLE
+// child entity, the named-error requirement), the WHOLE
 // transaction — root row included — rolls back, so a caller can safely
 // retry the same token after fixing the app's `transferable` declarations.
 
@@ -64,8 +64,7 @@ export async function moveRootRow(args: {
 // history + storage-usage counters — fileRef is a standard ES entity (see
 // files-storage-tracking.md), so without those two follow-ups a later write
 // against a moved fileRef can't load its stream, and a projection rebuild
-// would put the row back into the source tenant (kumiko-framework#3131-adjacent
-// gap, item 4).
+// would put the row back into the source tenant.
 async function moveFileRefs(args: {
   readonly db: DbRunner;
   readonly registry: Registry;
@@ -210,7 +209,7 @@ async function moveEdgeRows(args: {
 // Everything the root ownership write does NOT cover: the root's own event
 // history + attached files, plus the rows, event history and attached files of
 // every descendant the declared transfer graph reaches, however deep and by
-// however many paths (#3088, #3131).
+// however many paths.
 // Returns a count per moved entity name (the
 // write handler turns this into the audit entry) — `fileRef` is a single
 // pooled count across root + every child, since it is not itself part of the
@@ -264,7 +263,7 @@ export async function moveTransferGraph(args: {
 
   const adjacency = resolveTransferAdjacency(registry, rootEntityName);
 
-  // A worklist, not a level-wise walk (#3131): each batch of rows that actually
+  // A worklist, not a level-wise walk: each batch of rows that actually
   // changed hands becomes the parent ids for the edges leading away from its
   // type. The same edge therefore runs again whenever a later round discovers
   // more rows of its parent type, which is what a type reachable by two paths
@@ -274,7 +273,7 @@ export async function moveTransferGraph(args: {
   // every statement filters on `tenantCol = sourceTenantId` and RETURNS only
   // the rows it flipped, so a row enters this worklist exactly once and the
   // source tenant holds finitely many. Do not add an edge-level visited set to
-  // "bound" this — that is precisely the bug #3131 removed.
+  // "bound" this — that would reintroduce the bug.
   let pending: readonly { readonly entityName: string; readonly rowIds: readonly string[] }[] = [
     { entityName: rootEntityName, rowIds: [rootRowId] },
   ];

package/packages/bundled-features/src/tenant-handover/signup-handover-provider.ts

@@ -1,6 +1,5 @@
 // tenant-handover's implementation of the shared signup-handover extension
-// point (kumiko-framework#3035 follow-up, offlot-app#454): lets
-// auth-email-password's signup-request verify a grant against its root row
+// point: lets auth-email-password's signup-request verify a grant against its root row
 // WITHOUT spending the anchor (the anchor is spent once, by the claim
 // signup-confirm runs afterwards, via a fresh short-lived grant this module
 // mints) — see shared/signup-handover.ts for the extension contract and

package/packages/bundled-features/src/tenant-handover/transfer-graph.ts

@@ -1,15 +1,14 @@
 // Resolves the declared transfer graph for a root entity type: the root
 // itself, plus every registered entity that reaches it through a declared
-// schema edge (kumiko-framework#3035, #3088; framework CLAUDE.md premise 4 —
-// the graph depth is read off the existing declarations, never a hand-
-// maintained per-app list).
+// schema edge (framework CLAUDE.md premise 4 — the graph depth is read off
+// the existing declarations, never a hand-maintained per-app list).
 //
 // The edge definition (parentRef + single-valued reference fields, minus
 // `handover: "stay"`) lives in the framework so the boot validator's depth
 // limit and the mover's traversal measure the same graph. What comes out is
 // static adjacency, not a walk: the mover drives the actual traversal from the
-// row ids it moves (#3131), because how deep a type sits depends on the rows
-// found, not on the schema alone.
+// row ids it moves, because how deep a type sits depends on the rows found,
+// not on the schema alone.
 //
 // `transferable: true` stays the only gate on what actually moves, and it is
 // enforced by the caller against edges that turn out to have rows rather than

package/packages/bundled-features/src/tenant-lifecycle/boot-checks.ts

@@ -16,7 +16,7 @@ const log = createFallbackLogger("kumiko:boot");
 
 // V4: tenantOwned-entity-without-hook gate. Mirrors user-data-rights' V3
 // (validateGdprPiiHookCoverage) but for EXT_TENANT_DATA. Registered as this
-// feature's own `r.bootCheck()` (#1314, moved off the framework-internal
+// feature's own `r.bootCheck()` (moved off the framework-internal
 // boot-validator) — tenant-lifecycle owns EXT_TENANT_DATA
 // (r.extendsRegistrar), so its own mount is the trigger, matching the
 // original guard's "tenant-lifecycle mounted" gate exactly (unlike gating on

package/packages/bundled-features/src/tenant-lifecycle/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Destroy sweep keeps a minimum time slice per tenant",
+    "detail": "With many tenants in destroying state the shared tick budget no longer shrinks a tenant's slice below two seconds, so chunking hooks make progress instead of failing the stage as no-progress attempts."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/tenant-lifecycle/constants.ts

@@ -62,3 +62,8 @@ export type TenantDestructionStageName = (typeof TENANT_DESTRUCTION_STAGES)[numb
 // The sweep cron fires every minute with concurrency "skip", so a tick must
 // finish well inside that window or the next one is skipped.
 export const DESTRUCTION_STAGE_TICK_BUDGET_MS = 30_000;
+
+// Lower bound of a tenant's share of the tick budget. Below it a chunking hook
+// without a guaranteed first batch processes nothing, and a no-progress stage
+// counts as a failed attempt, which would abandon the pipeline under load.
+export const DESTRUCTION_STAGE_MIN_SLICE_MS = 2_000;

package/packages/bundled-features/src/tenant-lifecycle/feature.ts

@@ -78,7 +78,7 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
     r.extendsRegistrar(EXT_TENANT_LIFECYCLE_STATUS, {});
     r.useExtension(EXT_TENANT_LIFECYCLE_STATUS, "tenant-lifecycle", tenantLifecycleStatusPlugin);
 
-    // GDPR-storage guard V4 (#1314) — moved off the framework-internal
+    // GDPR-storage guard V4 — moved off the framework-internal
     // boot-validator onto this feature's own r.bootCheck(), since it owns
     // EXT_TENANT_DATA: its own mount is the trigger, matching the original
     // guard's "tenant-lifecycle mounted" gate exactly.

package/packages/bundled-features/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -23,6 +23,7 @@ import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { tenantEntity, tenantTable } from "../tenant/index.ts";
 import {
+  DESTRUCTION_STAGE_MIN_SLICE_MS,
   DESTRUCTION_STAGE_TICK_BUDGET_MS,
   TENANT_AGGREGATE_TYPE,
   TENANT_DESTRUCTION_COMPLETED_EVENT_QN,
@@ -427,7 +428,7 @@ export async function runTenantDestructionSweep(args: {
 
   let triggered = 0;
   for (const row of due) {
-    const tenantId = row.id as TenantId;
+    const tenantId = row.id;
     const events = await loadAggregate(args.db, tenantId, tenantId);
     const version = lastEventVersion(events);
     const user = createSystemUser(tenantId);
@@ -461,7 +462,10 @@ export async function runTenantDestructionSweep(args: {
   // window and starve the ones behind it. Each slice starts when its tenant
   // starts: anchoring to a shared tick deadline would hand tenants after an
   // overrun a zero slice, and a no-progress stage counts as a failed attempt.
-  const sliceMs = DESTRUCTION_STAGE_TICK_BUDGET_MS / Math.max(1, destroying.length);
+  const sliceMs = Math.max(
+    DESTRUCTION_STAGE_MIN_SLICE_MS,
+    DESTRUCTION_STAGE_TICK_BUDGET_MS / Math.max(1, destroying.length),
+  );
   for (const row of destroying) {
     const tenantDeadlineAt = Date.now() + sliceMs;
     try {
@@ -469,7 +473,7 @@ export async function runTenantDestructionSweep(args: {
         deadlineAt: tenantDeadlineAt,
         db: args.db,
         registry: args.registry,
-        tenantId: row.id as TenantId,
+        tenantId: row.id,
         log: args.log,
         fileProviderResolver: args.fileProviderResolver,
         searchAdapter: args.searchAdapter,

package/packages/bundled-features/src/tenant-lifecycle/stages.ts

@@ -60,7 +60,7 @@ export type DestructionStageCtx = {
   // Derived search docs of the tenant record (its name) live in the writer's
   // index, not the destroyed tenant's, so the subject-keys stage purges them.
   readonly searchAdapter?: SearchAdapter;
-  // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
+  // Sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); runTenantDataHooks uses them to attribute+audit any
   // EXT_TENANT_DATA usage's declared escapeHatch.
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;

package/packages/bundled-features/src/tenant-settings/constants.ts

@@ -14,7 +14,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/packages/bundled-features/src/tenant-settings/tenant-defaults.ts

@@ -15,6 +15,8 @@ import {
   type EntityDefinition,
   type WriteHandlerDef,
 } 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.ts";
 
@@ -26,7 +28,7 @@ export function defineCreateWithTenantDefaults(
   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[];
@@ -53,11 +55,16 @@ export function defineCreateWithTenantDefaults(
     schema,
     access: options.access,
     handler: async (event, ctx) => {
-      const payload = { ...(event.payload as Record<string, unknown>) };
+      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] as { amount?: number; currency?: string } | undefined;
-        if (value && typeof value === "object" && !value.currency) {
+        const value = payload[field];
+        if (isPlainObject(value) && !value["currency"]) {
           const currency = await ctx.config?.(TenantSettingsConfig.currency);
           if (typeof currency === "string") payload[field] = { ...value, currency };
         }
@@ -68,7 +75,7 @@ export function defineCreateWithTenantDefaults(
       }
 
       // 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/packages/bundled-features/src/tier-engine/aggregate-id.ts

@@ -1,26 +1,25 @@
 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: string): string {

package/packages/bundled-features/src/tier-engine/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "set-tenant-tier no longer accepts source default",
+    "detail": "The source field of set-tenant-tier is limited to manual and billing. The value default is reserved for the signup default tier and made a manual grant look like a billing row that the next sync overwrites."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

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: