@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/tenant/web/constants.js

@@ -14,11 +14,11 @@ export const MEMBER_STATUS_CELL_COMPONENT = "MemberStatusCell";
 export const MEMBER_ROLES_CELL_COMPONENT = "MemberRolesCell";
 /** 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"];
 // 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/dist/tenant-handover/events.js

@@ -1,11 +1,9 @@
 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/dist/tenant-handover/feature.js

@@ -3,7 +3,7 @@ import { EXT_SIGNUP_HANDOVER } from "../shared/index.js";
 import { TENANT_HANDOVER_CLAIMED_EVENT_SHORT, tenantHandoverClaimedSchema } from "./events.js";
 import { createClaimTenantHandoverHandler, } from "./handlers/claim.write.js";
 import { createSignupHandoverProvider } from "./signup-handover-provider.js";
-// 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/dist/tenant-handover/grant.js

@@ -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/dist/tenant-handover/handlers/claim.write.js

@@ -17,7 +17,7 @@ function notTransferable(entityType) {
         details: { entityType },
     }));
 }
-// 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/dist/tenant-handover/move-entity-graph.js

@@ -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.
 import { entityTableFromRegistry, executeRawQuery, extractTableName, physicalColumnName, toPostgresArrayLiteral, } from "@cosmicdrift/kumiko-framework/db";
@@ -41,8 +41,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) {
     if (args.entityIds.length === 0)
         return 0;
@@ -136,7 +135,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
@@ -170,7 +169,7 @@ export async function moveTransferGraph(args) {
         transferredBy,
     }));
     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
@@ -180,7 +179,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 = [
         { entityName: rootEntityName, rowIds: [rootRowId] },
     ];

package/dist/tenant-handover/signup-handover-provider.js

@@ -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/dist/tenant-handover/transfer-graph.js

@@ -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/dist/tenant-lifecycle/boot-checks.js

@@ -4,7 +4,7 @@ import { entitiesOf } from "../shared/index.js";
 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/dist/tenant-lifecycle/constants.d.ts

@@ -27,3 +27,4 @@ export declare const TenantLifecycleHandlers: {
 export declare const TENANT_DESTRUCTION_STAGES: readonly ["external-resources", "search-indices", "cache", "app-data", "subject-keys", "files", "infra-resources", "tenant-row"];
 export type TenantDestructionStageName = (typeof TENANT_DESTRUCTION_STAGES)[number];
 export declare const DESTRUCTION_STAGE_TICK_BUDGET_MS = 30000;
+export declare const DESTRUCTION_STAGE_MIN_SLICE_MS = 2000;

package/dist/tenant-lifecycle/constants.js

@@ -38,3 +38,7 @@ export const TENANT_DESTRUCTION_STAGES = [
 // 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/dist/tenant-lifecycle/feature.js

@@ -31,7 +31,7 @@ export function createTenantLifecycleFeature() {
         // AND fulfils tenantLifecycleStatus so teardown state is visible with no per-app wiring.
         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/dist/tenant-lifecycle/run-tenant-destroy.js

@@ -3,7 +3,7 @@ import { createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
 import { append, loadAggregate, VersionConflictError, } from "@cosmicdrift/kumiko-framework/event-store";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { tenantEntity, tenantTable } from "../tenant/index.js";
-import { DESTRUCTION_STAGE_TICK_BUDGET_MS, TENANT_AGGREGATE_TYPE, TENANT_DESTRUCTION_COMPLETED_EVENT_QN, TENANT_DESTRUCTION_FAILED_EVENT_QN, TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT, TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT, TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT, TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT, TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT, TENANT_DESTRUCTION_STARTED_EVENT_SHORT, } from "./constants.js";
+import { DESTRUCTION_STAGE_MIN_SLICE_MS, DESTRUCTION_STAGE_TICK_BUDGET_MS, TENANT_AGGREGATE_TYPE, TENANT_DESTRUCTION_COMPLETED_EVENT_QN, TENANT_DESTRUCTION_FAILED_EVENT_QN, TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT, TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT, TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT, TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT, TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT, TENANT_DESTRUCTION_STARTED_EVENT_SHORT, } from "./constants.js";
 import { invalidateTenantLifecycleGate, TEARDOWN_GATE_SETTLE_MS } from "./lifecycle-gate.js";
 import { isDestructionPipelineComplete, pickNextStage, } from "./stages.js";
 const tenantCrud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
@@ -251,7 +251,7 @@ 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 {

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;
 };