@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,242 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configuredPiiSubjectKms, type SubjectId } from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbRunner,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type EscapeHatchAuditSink,
+  EXT_EXTERNAL_RESOURCE,
+  EXT_INFRA_RESOURCE,
+  EXT_SEARCH_ADAPTER,
+  EXT_STORAGE_PROVIDER,
+  EXT_TENANT_DATA,
+  extensionUsageEscapeHatchReason,
+  isTenantDataExtensionHooks,
+  isTenantResourceExtensionHooks,
+  type Registry,
+  type TenantDataHookCtx,
+  type TenantId,
+  type TenantResourceExtensionName,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
+import {
+  createEscapeHatchReporter,
+  UNATTRIBUTED_ACTOR,
+} from "@cosmicdrift/kumiko-framework/pipeline";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import {
+  tenantEntity,
+  tenantMembershipEntity,
+  tenantMembershipsTable,
+  tenantTable,
+} from "../tenant/index.js";
+import type { TenantDestructionStageName } from "./constants.js";
+import { invalidateTenantLifecycleGate } from "./lifecycle-gate.js";
+
+export type DestructionStageCtx = {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+  readonly log?: (message: string) => void;
+  // Only threaded through for the "files" stage (EXT_STORAGE_PROVIDER
+  // "destroyTenant" hooks) — undefined when no file-provider is wired,
+  // which those hooks must treat as "nothing to clean up", not an error.
+  readonly fileProviderResolver?: FileProviderResolver;
+  // fw#2914 — 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;
+  readonly actor?: string;
+};
+
+export type DestructionStage = {
+  readonly name: TenantDestructionStageName;
+  readonly maxAttempts: number;
+  readonly run: (ctx: DestructionStageCtx) => Promise<void>;
+};
+
+const tenantCrud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+const tenantMembershipCrud = createEventStoreExecutor(
+  tenantMembershipsTable,
+  tenantMembershipEntity,
+  {
+    entityName: "tenant-membership",
+  },
+);
+
+async function runExtensionDestroyHooks(
+  registry: Registry,
+  extensionName: TenantResourceExtensionName,
+  ctx: DestructionStageCtx,
+): Promise<void> {
+  const usages = registry.getExtensionUsages(extensionName);
+  for (const usage of usages) {
+    if (!isTenantResourceExtensionHooks(usage.options)) {
+      throw new Error(
+        `${extensionName} registration for "${usage.entityName}" has no destroy function`,
+      );
+    }
+    await usage.options.destroyTenant(ctx.tenantId, ctx);
+  }
+}
+
+async function runTenantDataHooks(ctx: DestructionStageCtx): Promise<void> {
+  const usages = ctx.registry.getExtensionUsages(EXT_TENANT_DATA);
+  for (const usage of usages) {
+    if (!isTenantDataExtensionHooks(usage.options)) {
+      throw new Error(
+        `${EXT_TENANT_DATA} registration for "${usage.entityName}" has no destroy function`,
+      );
+    }
+    const destroy = usage.options.destroy;
+    const reason = extensionUsageEscapeHatchReason(usage);
+    const report = createEscapeHatchReporter({
+      handler: `${EXT_TENANT_DATA}:${usage.entityName}`,
+      tenantId: ctx.tenantId,
+      actor: ctx.actor ?? UNATTRIBUTED_ACTOR,
+      sink: ctx.escapeHatchAuditSink,
+    });
+    const hookCtx: TenantDataHookCtx = {
+      db: createTenantDb(ctx.db, ctx.tenantId, "tenant", undefined, undefined, undefined, {
+        unsafeRaw: reason !== undefined ? { reason } : undefined,
+        report,
+      }),
+      registry: ctx.registry,
+      tenantId: ctx.tenantId,
+      fileProviderResolver: ctx.fileProviderResolver,
+      log: ctx.log,
+    };
+    await destroy(hookCtx);
+  }
+}
+
+async function eraseSubjectKeys(ctx: DestructionStageCtx): Promise<void> {
+  const kms = configuredPiiSubjectKms();
+  if (!kms) {
+    ctx.log?.("[tenant-lifecycle] subject-keys stage skipped: no KMS adapter configured");
+    // skip: KMS optional — apps without crypto-shredding still run other destroy stages
+    return;
+  }
+  const memberships = await selectMany<{ userId: string }>(ctx.db, tenantMembershipsTable, {
+    tenantId: ctx.tenantId,
+  });
+  const subjects: SubjectId[] = [
+    { kind: "tenant", tenantId: ctx.tenantId },
+    ...memberships.map((m) => ({ kind: "user" as const, userId: m.userId })),
+  ];
+  for (const subject of subjects) {
+    await kms.eraseKey(subject, {
+      requestId: `tenant-lifecycle:destroy:${ctx.tenantId}`,
+      eraseReason: "tenant-destroy stage subject-keys",
+    });
+  }
+}
+
+async function purgeTenantCache(ctx: DestructionStageCtx): Promise<void> {
+  // ponytail: Redis SCAN+DEL is wired when ctx carries a redis client; until
+  // then this stage is a documented no-op (no cache layer in test stack).
+  ctx.log?.("[tenant-lifecycle] cache stage: no redis client in ctx — skipped");
+}
+
+async function tombstoneTenantRow(ctx: DestructionStageCtx): Promise<void> {
+  const now = getTemporal().Now.instant();
+  const user = createSystemUser(ctx.tenantId);
+  const db = createTenantDb(ctx.db, ctx.tenantId, "system");
+  // Per-row forget() through the executor, not a bulk deleteMany: memberships
+  // are an ES-managed projection (add/remove/update-roles all go through
+  // tenantMembershipCrud), so a store table write here is eventless — a future
+  // projection rebuild would replay the historical add-member events and
+  // resurrect rows this stage removed. forget() (Art.17 hard-purge) keeps the
+  // erasure rebuild-safe and gives each membership its own audit event.
+  const memberships = await selectMany<{ id: string }>(ctx.db, tenantMembershipsTable, {
+    tenantId: ctx.tenantId,
+  });
+  for (const membership of memberships) {
+    const result = await tenantMembershipCrud.forget({ id: membership.id }, user, db);
+    // executor writes return {isSuccess:false} on failure, they don't throw —
+    // a silently-discarded result here would report this stage "succeeded"
+    // while membership PII survives. Throw so the pipeline's retry/abandon
+    // handling (runNextDestructionStage) sees it instead.
+    if (!result.isSuccess) {
+      throw new Error(
+        `tenant-lifecycle: failed to forget membership ${membership.id} for tenant ${ctx.tenantId}: ${result.error.message}`,
+      );
+    }
+  }
+  await tenantCrud.update(
+    {
+      id: ctx.tenantId,
+      changes: {
+        status: "destroyed",
+        destroyedAt: now,
+        isEnabled: false,
+      },
+    },
+    user,
+    db,
+    { skipOptimisticLock: true },
+  );
+  invalidateTenantLifecycleGate(ctx.tenantId);
+}
+
+export const DESTRUCTION_STAGES: readonly DestructionStage[] = [
+  {
+    name: "external-resources",
+    maxAttempts: 3,
+    run: (ctx) => runExtensionDestroyHooks(ctx.registry, EXT_EXTERNAL_RESOURCE, ctx),
+  },
+  {
+    name: "search-indices",
+    maxAttempts: 3,
+    run: (ctx) => runExtensionDestroyHooks(ctx.registry, EXT_SEARCH_ADAPTER, ctx),
+  },
+  {
+    name: "cache",
+    maxAttempts: 1,
+    run: purgeTenantCache,
+  },
+  {
+    name: "app-data",
+    maxAttempts: 3,
+    run: runTenantDataHooks,
+  },
+  {
+    name: "subject-keys",
+    maxAttempts: 3,
+    run: eraseSubjectKeys,
+  },
+  {
+    name: "files",
+    maxAttempts: 3,
+    run: (ctx) => runExtensionDestroyHooks(ctx.registry, EXT_STORAGE_PROVIDER, ctx),
+  },
+  {
+    name: "infra-resources",
+    maxAttempts: 3,
+    run: (ctx) => runExtensionDestroyHooks(ctx.registry, EXT_INFRA_RESOURCE, ctx),
+  },
+  {
+    name: "tenant-row",
+    maxAttempts: 1,
+    run: tombstoneTenantRow,
+  },
+];
+
+export function pickNextStage(
+  completedStages: ReadonlySet<string>,
+  abandonedStages: ReadonlySet<string>,
+): DestructionStage | null {
+  if (abandonedStages.size > 0) return null;
+  for (const stage of DESTRUCTION_STAGES) {
+    if (completedStages.has(stage.name)) continue;
+    return stage;
+  }
+  return null;
+}
+
+export function isDestructionPipelineComplete(completedStages: ReadonlySet<string>): boolean {
+  return DESTRUCTION_STAGES.every((stage) => completedStages.has(stage.name));
+}

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

@@ -0,0 +1 @@
+[]

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

@@ -0,0 +1,43 @@
+import {
+  access,
+  type ConfigKeyDefinition,
+  createTenantConfig,
+  DEFAULT_CURRENCIES,
+  DEFAULT_LOCALES,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export type TenantSettingsKeyOptions = {
+  /** Selectable currencies. Default: DEFAULT_CURRENCIES (engine). */
+  readonly currencies?: readonly string[];
+  /** Fallback when a tenant never set the key. Default: "EUR". */
+  readonly defaultCurrency?: string;
+  /** Selectable locales. Default: DEFAULT_LOCALES (engine). */
+  readonly locales?: readonly string[];
+  /** Fallback when a tenant never set the key. Default: "en". */
+  readonly defaultLocale?: string;
+  /** Who may change the tenant's settings. Default: access.admin. */
+  readonly write?: readonly string[];
+};
+
+export function buildTenantSettingsKeys(
+  opts: TenantSettingsKeyOptions = {},
+): Record<string, ConfigKeyDefinition> {
+  const write = opts.write ?? access.admin;
+  return {
+    // `mask` surfaces the key in the self-populating Settings-Hub (Tenant-
+    // Audience) without a hand-written r.screen/r.nav — see
+    // samples/recipes/managed-config for the mechanism.
+    currency: createTenantConfig("select", {
+      default: opts.defaultCurrency ?? "EUR",
+      options: opts.currencies ?? DEFAULT_CURRENCIES,
+      write,
+      mask: { title: "tenant-settings.currency", icon: "coins", order: 1 },
+    }),
+    locale: createTenantConfig("select", {
+      default: opts.defaultLocale ?? "en",
+      options: opts.locales ?? DEFAULT_LOCALES,
+      write,
+      mask: { title: "tenant-settings.locale", icon: "languages", order: 2 },
+    }),
+  } satisfies Record<string, ConfigKeyDefinition>;
+}

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

@@ -0,0 +1,21 @@
+import { TENANT_CURRENCY_CONFIG_KEY } from "@cosmicdrift/kumiko-framework/engine";
+
+// tenant-settings bundle constants — feature-name + qualified config names.
+//
+// Motivation (solon#P19): apps kept hard-coding a single currency/locale
+// literal per money/select field ("EUR", "de") instead of one per-tenant
+// setting — expensive to retrofit once a second tenant needs a different
+// default. This bundle is the one place that setting lives.
+
+export const TENANT_SETTINGS_FEATURE_NAME = "tenant-settings";
+
+// Qualified config key names (QN format: scope:config:name) for
+// ctx.config(...) reads. Clients reference the object instead of magic
+// 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)
+  // resolves against this same key.
+  currency: TENANT_CURRENCY_CONFIG_KEY,
+  locale: "tenant-settings:config:locale",
+} as const;

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

@@ -0,0 +1,55 @@
+// tenant-settings — per-tenant Currency + Locale defaults.
+//
+// Any handler that needs a default (money-field currency, a locale-select
+// field, ...) reads it via `ctx.config(TenantSettingsConfig.currency)` /
+// `ctx.config(TenantSettingsConfig.locale)` — or use
+// `defineCreateWithTenantDefaults` (tenant-defaults.ts) to wire it into an
+// entity's create-handler without writing that plumbing by hand.
+//
+// No entities, no hand-written screen — `mask` on both keys makes them
+// surface in the self-populating Settings-Hub (Tenant-Audience) instead;
+// `buildConfigFeatureSchema` (config feature) derives the configEdit
+// screen + nav entry from the key's scope/type/mask, same mechanism as
+// samples/recipes/managed-config.
+
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { buildTenantSettingsKeys, type TenantSettingsKeyOptions } from "./config.js";
+import { TENANT_SETTINGS_FEATURE_NAME } from "./constants.js";
+
+export type TenantSettingsFeatureOptions = TenantSettingsKeyOptions;
+
+export function createTenantSettingsFeature(
+  opts: TenantSettingsFeatureOptions = {},
+): FeatureDefinition {
+  return defineFeature(TENANT_SETTINGS_FEATURE_NAME, (r) => {
+    r.requires("config");
+    r.describe(
+      "Per-tenant Currency + Locale defaults, exposed as two config keys (tenant-settings:config:currency, tenant-settings:config:locale) that surface in the self-populating Settings-Hub via `mask`. Pair with defineCreateWithTenantDefaults to auto-fill a money field's currency or a locale field on create instead of hard-coding a literal per entity.",
+    );
+    r.config({ keys: buildTenantSettingsKeys(opts) });
+    r.translations({
+      keys: {
+        "tenant-settings.currency": { en: "Default currency" },
+        "tenant-settings.locale": { en: "Default locale" },
+        // Settings-Hub-derived configEdit screen title (buildConfigFeatureSchema) —
+        // required by the i18n boot-validator whenever a feature masks config keys.
+        "screen:tenant-settings-system.title": { en: "Tenant defaults" },
+        "screen:tenant-settings-tenant.title": { en: "Tenant settings" },
+        // Settings-Hub nav label + configEdit section heading (same key, both
+        // scopes fall back here — see buildConfigFeatureSchema).
+        "tenant-settings.settings": { en: "Tenant settings" },
+        // Section heading below the page title (the page title is the same words as
+        // `.settings`, which RenderEdit would drop as a repeat).
+        "tenant-settings.settings.section": { en: "Currency and language" },
+        // Both currency/locale are tenant-home with admin write access, which
+        // cascades a SystemAdmin-only "set the platform default" screen up to
+        // the system audience — scoped override so its nav entry reads
+        // differently from the tenant-home entry instead of repeating the
+        // same words under both "Platform" and "Organization".
+        "tenant-settings.settings.system": { en: "Tenant defaults" },
+      },
+    });
+  });
+}
+
+export const tenantSettingsFeature: FeatureDefinition = createTenantSettingsFeature();

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

@@ -0,0 +1,8 @@
+export { buildTenantSettingsKeys, type TenantSettingsKeyOptions } from "./config.js";
+export { TENANT_SETTINGS_FEATURE_NAME, TenantSettingsConfig } from "./constants.js";
+export {
+  createTenantSettingsFeature,
+  type TenantSettingsFeatureOptions,
+  tenantSettingsFeature,
+} from "./feature.js";
+export { defineCreateWithTenantDefaults } from "./tenant-defaults.js";

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

@@ -0,0 +1,78 @@
+// Wrapper around defineEntityCreateHandler: fills currency/locale fields from
+// tenant-settings config when the caller omits them — instead of repeating
+// field literals ("EUR"/"de") on every entity.
+//
+// buildInsertSchema always requires `currency` inside a money field (even when
+// the field itself is optional), so the caller cannot simply omit currency
+// without failing schema validation before the handler runs. This helper uses
+// a schema extension that makes those sub-keys optional, instead of the
+// generic defineEntityCreateHandler.
+
+import {
+  type AccessRule,
+  buildInsertSchema,
+  createEntityExecutor,
+  type EntityDefinition,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { TenantSettingsConfig } from "./constants.js";
+
+const OPTIONAL_CURRENCY_MONEY = z.object({ amount: z.number(), currency: z.string().optional() });
+
+export 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). */
+    readonly access: AccessRule;
+    /** Money field names whose `currency` is filled from tenant-settings when missing. */
+    readonly currencyFields?: readonly string[];
+    /** Field name (select/text) that receives the tenant locale when missing. */
+    readonly localeField?: string;
+  },
+): WriteHandlerDef {
+  const { executor } = createEntityExecutor(entityName, entity);
+  const relax: Record<string, z.ZodTypeAny> = {};
+  for (const field of options.currencyFields ?? []) {
+    const def = entity.fields[field];
+    if (!def) throw new Error(`defineCreateWithTenantDefaults: unknown field "${field}"`);
+    const isRequired = "required" in def && def.required === true;
+    relax[field] = isRequired ? OPTIONAL_CURRENCY_MONEY : OPTIONAL_CURRENCY_MONEY.optional();
+  }
+  if (options.localeField && !entity.fields[options.localeField]) {
+    throw new Error(`defineCreateWithTenantDefaults: unknown field "${options.localeField}"`);
+  }
+  const baseSchema = buildInsertSchema(entity);
+  const schema = Object.keys(relax).length > 0 ? baseSchema.extend(relax) : baseSchema;
+
+  return {
+    name: `${entityName}:create`,
+    schema,
+    access: options.access,
+    handler: async (event, ctx) => {
+      const payload = { ...(event.payload as Record<string, unknown>) };
+
+      for (const field of options.currencyFields ?? []) {
+        const value = payload[field] as { amount?: number; currency?: string } | undefined;
+        if (value && typeof value === "object" && !value.currency) {
+          const currency = await ctx.config?.(TenantSettingsConfig.currency);
+          if (typeof currency === "string") payload[field] = { ...value, currency };
+        }
+      }
+      if (options.localeField && !payload[options.localeField]) {
+        const locale = await ctx.config?.(TenantSettingsConfig.locale);
+        if (typeof locale === "string") 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
+      // a missing currency after failed/missing tenant-settings mount fails
+      // loud instead of inserting half-filled money rows.
+      const filled = baseSchema.parse(payload);
+      return executor.create(filled, event.user, ctx.db);
+    },
+  };
+}

package/packages/bundled-features/src/tier-engine/aggregate-id.ts

@@ -0,0 +1,28 @@
+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.
+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.
+ *
+ * **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.
+ *
+ * **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.
+ */
+// @wrapper-known uuid-domain
+export function tierAssignmentAggregateId(tenantId: string): string {
+  return uuidv5(tenantId, TIER_ASSIGNMENT_NAMESPACE);
+}

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

@@ -0,0 +1,16 @@
+[
+  {
+    "version": "0.278.0",
+    "type": "breaking",
+    "title": "createTierResolver's resolveTier/resolveTierCaps take only a TenantDb — no separate tenantId argument (fw#2854).",
+    "detail": "`resolveTier(db)` and `resolveTierCaps(db)` (from `createTierResolver`) now read the tenant from `db.tenantId` instead of taking a second `tenantId` parameter, so a caller can no longer pass a `TenantDb` for one tenant alongside a different `tenantId` and resolve a foreign tenant's tier.",
+    "migration": "`resolveTier(ctx.db.raw|runner, tenantId)` → `resolveTier(ctx.db)` (same for `resolveTierCaps`). Outside a handler: `resolveTier(createTenantDb(runner, tenantId))`."
+  },
+  {
+    "version": "0.241.0",
+    "type": "breaking",
+    "title": "TierAdminScreen removed; tier-admin is now a declarative actionForm (fw#2312).",
+    "detail": "`tier-engine:screen:tier-admin` is now a declarative `actionForm` (a `reference` field for the tenant, a `select` field for the tier) instead of a custom React component: it dispatches `set-tenant-tier` directly, so the renderer's generic form handles tenant lookup, validation and submit. Two behaviors are intentionally not carried over: the current tier of the selected tenant is no longer shown before submit (declarative forms have no dependent-query support), and the success state no longer names the newly assigned tier (a generic actionForm success doesn't surface write-response data). Both are visible again after a page reload / re-navigation — the assignment itself is unchanged.",
+    "migration": "Breaking only if you imported `TierAdminScreen` directly (no shipped consumer app did — all reference the screen by its qualified id `tier-engine:screen:tier-admin`). Remove `import { TierAdminScreen } from \"@cosmicdrift/kumiko-bundled-features/tier-engine/web\"` and any `components: { TierAdminScreen: ... }` entry in your renderer setup — the bundled feature registers the `tier-admin` screen itself now, nothing left for an app to wire."
+  }
+]

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

@@ -0,0 +1,153 @@
+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.
+ *
+ * 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.
+ */
+export type TierDefinition<TCaps extends Readonly<Record<string, unknown>>> = {
+  /** Feature names to mount on top of the base set (no add-ons applied). */
+  readonly features: readonly string[];
+  /** Cap-Definition als app-spezifischer typed shape. */
+  readonly caps: TCaps;
+};
+
+/**
+ * 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.
+ */
+export type AddOnDefinition<TCaps extends Readonly<Record<string, unknown>>> = {
+  /** Feature names to mount additionally when this add-on is active. */
+  readonly features: readonly string[];
+  /** Cap-Overrides (replaces matching keys in the tier's cap set). */
+  readonly capOverrides?: Partial<TCaps>;
+};
+
+export type TierMap<TCaps extends Readonly<Record<string, unknown>>> = Readonly<
+  Record<string, TierDefinition<TCaps>>
+>;
+export type AddOnMap<TCaps extends Readonly<Record<string, unknown>>> = Readonly<
+  Record<string, AddOnDefinition<TCaps>>
+>;
+
+export type ComposeAppInput<TCaps extends Readonly<Record<string, unknown>>> = {
+  /** Features that mount unconditionally — auth, tenant, secrets, tier-engine itself. */
+  readonly base: readonly FeatureDefinition[];
+  /** All app-specific features keyed by their feature-name. */
+  readonly featureRegistry: Readonly<Record<string, FeatureDefinition>>;
+  /** App's tier definitions. */
+  readonly tierMap: TierMap<TCaps>;
+  /** App's add-on definitions. */
+  readonly addOnMap: AddOnMap<TCaps>;
+  /** Active tier name for the current platform-tenant. */
+  readonly tier: string;
+  /** Active add-on names for the current platform-tenant. */
+  readonly addOns: readonly string[];
+};
+
+export type ComposedApp<TCaps extends Readonly<Record<string, unknown>>> = {
+  /** Final feature list to pass to runProdApp / setupTestStack. */
+  readonly features: readonly FeatureDefinition[];
+  /** Effective caps after tier + add-on overrides — same shape as input.tierMap[*].caps. */
+  readonly caps: TCaps;
+};
+
+/**
+ * composeApp — compute the feature-set + caps for a platform-tenant.
+ *
+ * **Contract:**
+ *   1. base features always mount (Tier-Engine itself ist Teil davon)
+ *   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)
+ *
+ * **Failure modes:**
+ *   - tier not in tierMap → throws (config error, app must register valid tiers)
+ *   - addOn not in addOnMap → throws (same)
+ *   - feature-name not in featureRegistry → throws (same)
+ *
+ * **Why throw vs silently ignore:** unknown tier/add-on means a Stripe-webhook
+ * delivered something the platform doesn't understand. Failing loud at boot
+ * is safer than silently mounting the wrong feature-set and hoping nobody
+ * notices when "Pro" turns out to mean "Free".
+ *
+ * **No production callers, and that is not rot** — see
+ * docs/reference/tier-composition-boot-vs-runtime.md for why.
+ */
+export function composeApp<TCaps extends Readonly<Record<string, unknown>>>(
+  input: ComposeAppInput<TCaps>,
+): ComposedApp<TCaps> {
+  const tierDef = input.tierMap[input.tier];
+  if (!tierDef) {
+    throw new Error(
+      `composeApp: unknown tier "${input.tier}". Known tiers: ` +
+        `${Object.keys(input.tierMap).join(", ")}`,
+    );
+  }
+
+  const addOnDefs = input.addOns.map((name) => {
+    const def = input.addOnMap[name];
+    if (!def) {
+      throw new Error(
+        `composeApp: unknown add-on "${name}". Known add-ons: ` +
+          `${Object.keys(input.addOnMap).join(", ")}`,
+      );
+    }
+    return def;
+  });
+
+  const tierFeatureNames = tierDef.features;
+  const addOnFeatureNames = addOnDefs.flatMap((d) => d.features);
+  const allFeatureNames = [...tierFeatureNames, ...addOnFeatureNames];
+
+  const additionalFeatures = allFeatureNames.map((name) => {
+    const feature = input.featureRegistry[name];
+    if (!feature) {
+      throw new Error(
+        `composeApp: unknown feature "${name}". Registered features: ` +
+          `${Object.keys(input.featureRegistry).join(", ")}`,
+      );
+    }
+    return feature;
+  });
+
+  // Dedupe — a feature listed in both the tier and an add-on should only
+  // mount once. Order-preserving: first occurrence wins.
+  const seen = new Set<string>();
+  const dedupedFeatures = additionalFeatures.filter((f) => {
+    if (seen.has(f.name)) return false;
+    seen.add(f.name);
+    return true;
+  });
+
+  // Caps merge: tier.caps as base, each add-on's overrides applied on top.
+  // Later add-ons win — order in input.addOns matters for conflicting overrides.
+  // Object.assign mutates the local `merged` (allocated once, not in
+  // an accumulating-spread loop — Biome's noAccumulatingSpread is happy
+  // and we still avoid an `as TCaps` cast: TS narrows the assign-result
+  // back to TCaps when source is Partial<TCaps>.
+  const merged: TCaps = { ...tierDef.caps };
+  for (const def of addOnDefs) {
+    if (def.capOverrides) Object.assign(merged, def.capOverrides);
+  }
+  const effectiveCaps = merged;
+
+  return {
+    features: [...input.base, ...dedupedFeatures],
+    caps: effectiveCaps,
+  };
+}