@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/tier-engine/__tests__/tier-engine.integration.ts

@@ -0,0 +1,241 @@
+import { randomBytes } from "node:crypto";
+import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createEntityTable,
+  createTestUser,
+  pushTables,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createConfigFeature } from "../../config";
+import { type ConfigResolver, createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { TierEngineHandlers, TierEngineQueries } from "../constants";
+import { tierAssignmentEntity } from "../entity";
+import { tierEngineFeature } from "../feature";
+
+// --- Setup ---
+//
+// Test-Isolation-Pattern: jeder Test nutzt einen eigenen Tenant über
+// `createTestUser({ id: N, tenantId: testTenantId(N) })`. Dadurch teilen
+// die Tests keinen Zustand — wenn ein Test fehlschlägt, bleiben die anderen
+// aussagekräftig. Zusätzlicher Vorteil: list-Test sieht garantiert genau
+// 1 Row, weil sonst keine andere Test-Aktivität in seinem Tenant läuft.
+
+let stack: TestStack;
+let db: DbConnection;
+let resolver: ConfigResolver;
+
+const configFeature = createConfigFeature();
+const tenantFeature = createTenantFeature();
+const testEncryptionKey = randomBytes(32).toString("base64");
+
+beforeAll(async () => {
+  const encryption = createEncryptionProvider(testEncryptionKey);
+  resolver = createConfigResolver({ encryption });
+
+  stack = await setupTestStack({
+    features: [configFeature, tenantFeature, tierEngineFeature],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+  });
+  db = stack.db;
+
+  await createEntityTable(db, tenantEntity);
+  await createEntityTable(db, tierAssignmentEntity);
+  await pushTables(db, { configValuesTable });
+  await createEventsTable(db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+// Per-test admin-user factory — fresh tenant per scenario.
+function adminFor(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+}
+
+// --- Scenario 1: create ---
+
+describe("scenario 1: create", () => {
+  test("admin creates a tier-assignment for the calling tenant", async () => {
+    const admin = adminFor(101);
+
+    const result = await stack.http.writeOk(TierEngineHandlers.create, { tier: "pro" }, admin);
+
+    const data = result!["data"] as Record<string, unknown>;
+    expect(data["tier"]).toBe("pro");
+    expect(typeof data["id"]).toBe("string");
+    expect(result!["isNew"]).toBe(true);
+  });
+});
+
+// --- Scenario 2: update ---
+
+describe("scenario 2: update", () => {
+  test("admin updates the tier value via {id, version, changes}", async () => {
+    const admin = adminFor(102);
+
+    const created = await stack.http.writeOk(TierEngineHandlers.create, { tier: "pro" }, admin);
+    const id = (created!["data"] as Record<string, unknown>)["id"] as string;
+
+    const updated = await stack.http.writeOk(
+      TierEngineHandlers.update,
+      { id, version: 1, changes: { tier: "business" } },
+      admin,
+    );
+
+    const data = updated!["data"] as Record<string, unknown>;
+    expect(data["tier"]).toBe("business");
+    expect(updated!["isNew"]).toBe(false);
+  });
+});
+
+// --- Scenario 3: get-active-tier ---
+
+describe("scenario 3: get-active-tier", () => {
+  test("returns the current tier for the calling tenant", async () => {
+    const admin = adminFor(103);
+    await stack.http.writeOk(TierEngineHandlers.create, { tier: "starter" }, admin);
+
+    const result = await stack.http.queryOk<Record<string, unknown> | null>(
+      TierEngineQueries.getActiveTier,
+      {},
+      admin,
+    );
+
+    expect(result).not.toBeNull();
+    expect(result!["tier"]).toBe("starter");
+  });
+
+  test("returns null when no tier is set for the calling tenant", async () => {
+    const adminWithoutTier = adminFor(104);
+
+    const result = await stack.http.queryOk<Record<string, unknown> | null>(
+      TierEngineQueries.getActiveTier,
+      {},
+      adminWithoutTier,
+    );
+
+    expect(result).toBeNull();
+  });
+});
+
+// --- Scenario 4: list (auto tenant-scoped) ---
+
+describe("scenario 4: list", () => {
+  test("returns the tier-assignment(s) for the calling tenant only", async () => {
+    const admin = adminFor(105);
+    await stack.http.writeOk(TierEngineHandlers.create, { tier: "team" }, admin);
+
+    const result = await stack.http.queryOk<{
+      rows: Record<string, unknown>[];
+      nextCursor: string | null;
+    }>(TierEngineQueries.list, {}, admin);
+
+    expect(Array.isArray(result.rows)).toBe(true);
+    expect(result.rows.length).toBe(1);
+    expect(result.rows[0]!["tier"]).toBe("team");
+  });
+});
+
+// --- Scenario 5: tenant isolation (Kern-Versprechen) ---
+
+describe("scenario 5: tenant isolation", () => {
+  test("two tenants have independent tier-assignments — no cross-bleed", async () => {
+    const adminA = adminFor(201);
+    const adminB = adminFor(202);
+
+    await stack.http.writeOk(TierEngineHandlers.create, { tier: "pro" }, adminA);
+    await stack.http.writeOk(TierEngineHandlers.create, { tier: "business" }, adminB);
+
+    const tierA = await stack.http.queryOk<Record<string, unknown> | null>(
+      TierEngineQueries.getActiveTier,
+      {},
+      adminA,
+    );
+    const tierB = await stack.http.queryOk<Record<string, unknown> | null>(
+      TierEngineQueries.getActiveTier,
+      {},
+      adminB,
+    );
+
+    expect(tierA!["tier"]).toBe("pro");
+    expect(tierB!["tier"]).toBe("business");
+
+    // List as A returns only A's row, never B's.
+    const listA = await stack.http.queryOk<{
+      rows: Record<string, unknown>[];
+      nextCursor: string | null;
+    }>(TierEngineQueries.list, {}, adminA);
+    expect(listA.rows.length).toBe(1);
+    expect(listA.rows[0]!["tier"]).toBe("pro");
+
+    const listB = await stack.http.queryOk<{
+      rows: Record<string, unknown>[];
+      nextCursor: string | null;
+    }>(TierEngineQueries.list, {}, adminB);
+    expect(listB.rows.length).toBe(1);
+    expect(listB.rows[0]!["tier"]).toBe("business");
+  });
+});
+
+// --- Scenario 6: access control (negative tests) ---
+
+describe("scenario 6: access control", () => {
+  test("normal User (no admin role) cannot create a tier-assignment", async () => {
+    const normalUser = TestUsers.user; // tenant 1, role: User
+
+    const error = await stack.http.writeErr(TierEngineHandlers.create, { tier: "pro" }, normalUser);
+
+    expectErrorIncludes(error, "access_denied");
+  });
+
+  test("normal User cannot update a tier-assignment", async () => {
+    const admin = adminFor(301);
+    const created = await stack.http.writeOk(TierEngineHandlers.create, { tier: "pro" }, admin);
+    const id = (created!["data"] as Record<string, unknown>)["id"] as string;
+
+    // Same tenant as admin (tenant 301), but a User role instead of admin.
+    const normalUserSameTenant = createTestUser({
+      id: 302,
+      tenantId: testTenantId(301),
+      roles: ["User"],
+    });
+
+    const error = await stack.http.writeErr(
+      TierEngineHandlers.update,
+      { id, version: 1, changes: { tier: "business" } },
+      normalUserSameTenant,
+    );
+
+    expectErrorIncludes(error, "access_denied");
+  });
+
+  test("query handlers carry the admin-only access rule (config-level check)", () => {
+    // Read-access is enforced by the same role-rule set on the query handler.
+    // We assert the rule is registered correctly — covers regression when
+    // someone changes adminAccess to openToAll without noticing.
+    const listRule = stack.registry.getQueryHandler(TierEngineQueries.list)?.access;
+    const activeTierRule = stack.registry.getQueryHandler(TierEngineQueries.getActiveTier)?.access;
+
+    expect(listRule).toBeDefined();
+    expect(activeTierRule).toBeDefined();
+    // Roles array contains TenantAdmin + SystemAdmin (no anonymous, no User).
+    expect(JSON.stringify(listRule)).toMatch(/TenantAdmin/);
+    expect(JSON.stringify(listRule)).toMatch(/SystemAdmin/);
+    expect(JSON.stringify(activeTierRule)).toMatch(/TenantAdmin/);
+    expect(JSON.stringify(activeTierRule)).toMatch(/SystemAdmin/);
+  });
+});

package/src/tier-engine/aggregate-id.ts

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

package/src/tier-engine/compose-app.ts

@@ -0,0 +1,150 @@
+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.so 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".
+ */
+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,
+  };
+}

package/src/tier-engine/constants.ts

@@ -0,0 +1,15 @@
+// Feature name
+export const TIER_ENGINE_FEATURE = "tier-engine" as const;
+
+// Qualified write handler names (QN format: scope:type:name).
+// Auto-generated by defineEntityCreateHandler / defineEntityUpdateHandler.
+export const TierEngineHandlers = {
+  create: "tier-engine:write:tier-assignment:create",
+  update: "tier-engine:write:tier-assignment:update",
+} as const;
+
+// Qualified query handler names.
+export const TierEngineQueries = {
+  list: "tier-engine:query:tier-assignment:list",
+  getActiveTier: "tier-engine:query:get-active-tier",
+} as const;

package/src/tier-engine/entity.ts

@@ -0,0 +1,30 @@
+import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+// tier-assignment — pro Plattform-Tenant genau ein Aggregat. Aggregate-ID
+// wird deterministisch aus tenantId abgeleitet (uuidv5, siehe 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.
+//
+// **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.
+//
+// **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.
+export const tierAssignmentEntity = createEntity({
+  table: "read_tier_assignments",
+  fields: {
+    tier: createTextField({ required: true, maxLength: 50 }),
+  },
+});

package/src/tier-engine/feature.ts

@@ -0,0 +1,72 @@
+// tier-engine — Pricing-Tier-Mechanik als reguläres Bundled-Feature.
+//
+// **Was diese Feature macht:**
+//   Speichert pro Plattform-Tenant ein Tier-Assignment (welcher Tier ist
+//   aktiv). composeApp-Helper liest diesen Stand und leitet daraus ab,
+//   welche Features für den Tenant gemountet werden.
+//
+// **Generic über Tier-Werte:** das Feature kennt keine "free"/"pro"/etc.
+//   konkreten Tier-Werte. Es speichert nur den Tier-Namen als String. Die
+//   App definiert ihre TierMap (siehe compose-app.ts), damit kumiko.so,
+//   PublicStatus, und andere Kumiko-Apps je eigene Tier-Sets nutzen können.
+//
+// **Standard-CRUD-Handler in Sprint 1:** Create/Update/List/Detail per
+//   `defineEntityXxxHandler`. Idempotente set-tier-Logic (deterministic
+//   aggregate-id, create-or-update-Routing) kommt im stripe-sync-Feature
+//   in Sprint 5 als Wrapper darum.
+//
+// **Tenant-Scope:** tier-engine ist tenant-scoped. Plattform-Tenant verwaltet
+//   seinen eigenen Tier (Self-Service-Upgrade-UI). Stripe-Webhook (Sprint 5)
+//   wird im stripe-sync-Feature die tenant-resolution machen und den
+//   tier-assignment:create/update-Handler mit dem aufgelösten Context
+//   aufrufen.
+//
+// **Was Sprint 1 NICHT macht:**
+//   - Custom Domain-Events (`tier-changed`) — emittiert werden derzeit nur
+//     die CRUD-Auto-Events. Sprint 4 (Add-On-Marketplace) erweitert das auf
+//     semantische Domain-Events.
+//   - Add-Ons im Schema — Sprint 4 fügt sie als separate
+//     `tier-add-on`-Entity hinzu (1:n Relation, ES-saubere Add/Remove-Events).
+//   - Cap-Counter-Integration — kommt mit `cap-counter`-Feature in Sprint 3.
+//   - Stripe-Sync + Idempotent-Set-Tier-Wrapper — kommt mit `stripe-sync`-
+//     Feature in Sprint 5.
+//
+// **Boot-Dependencies:**
+//   r.requires("config") — transitiv für tenant.
+//   r.requires("tenant") — tier-assignment lebt im Plattform-Tenant-Kontext.
+
+import {
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { TIER_ENGINE_FEATURE } from "./constants";
+import { tierAssignmentEntity } from "./entity";
+import { getActiveTierQuery } from "./handlers/active-tier.query";
+
+const adminAccess = { access: { roles: ["TenantAdmin", "SystemAdmin"] } } as const;
+
+export const tierEngineFeature: FeatureDefinition = defineFeature(TIER_ENGINE_FEATURE, (r) => {
+  r.requires("config");
+  r.requires("tenant");
+
+  r.entity("tier-assignment", tierAssignmentEntity);
+
+  // Standard-CRUD via Helper. Sprint 5 wraps these in a custom set-tier
+  // handler with deterministic aggregate-id for Stripe-Webhook idempotency.
+  r.writeHandler(defineEntityCreateHandler("tier-assignment", tierAssignmentEntity, adminAccess));
+  r.writeHandler(defineEntityUpdateHandler("tier-assignment", tierAssignmentEntity, adminAccess));
+
+  // Reads.
+  //   - list: cross-tenant view for SystemAdmin (debug/migration-tooling)
+  //     and per-tenant 0-or-1-row view for TenantAdmin (auto-tenant-scoped)
+  //   - get-active-tier: convenience-wrapper for the only sensible per-tenant
+  //     query — returns the single row or null. composeApp consumes this.
+  //
+  // Detail-by-id-handler bewusst weggelassen — kein Use-Case, weil pro Tenant
+  // genau eine Row existiert; get-active-tier ist die richtige Lookup-Form.
+  r.queryHandler(defineEntityListHandler("tier-assignment", tierAssignmentEntity, adminAccess));
+  r.queryHandler(getActiveTierQuery);
+});

package/src/tier-engine/handlers/active-tier.query.ts

@@ -0,0 +1,23 @@
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// get-active-tier — return 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.
+//
+// **Tenant-scope:** ctx.queryProjection filtert automatisch nach tenantId.
+// Pro Plattform-Tenant existiert per Konvention genau eine
+// tier-assignment-Row.
+export const getActiveTierQuery: QueryHandlerDef = {
+  name: "get-active-tier",
+  schema: z.object({}),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  handler: async (_query, ctx) => {
+    const rows = await ctx.queryProjection<Record<string, unknown>>(
+      "tier-engine:projection:tier-assignment-entity",
+    );
+    return rows[0] ?? null;
+  },
+};

package/src/tier-engine/index.ts

@@ -0,0 +1,22 @@
+// Public API of the tier-engine bundled-feature.
+//
+// **What downstream apps import:**
+//   - `tierEngineFeature` — register at app boot via runProdApp/setupTestStack
+//   - `composeApp` — call to derive feature-set + caps from tier+addOns
+//   - `TierMap` / `AddOnMap` — types for the app's own tier/add-on definitions
+//   - `tierAssignmentEntity` — for migrations + drizzle-schema-generation
+//   - `TierEngineHandlers` / `TierEngineQueries` — qualified handler names
+
+export { tierAssignmentAggregateId } from "./aggregate-id";
+export {
+  type AddOnDefinition,
+  type AddOnMap,
+  type ComposeAppInput,
+  type ComposedApp,
+  composeApp,
+  type TierDefinition,
+  type TierMap,
+} from "./compose-app";
+export { TIER_ENGINE_FEATURE, TierEngineHandlers, TierEngineQueries } from "./constants";
+export { tierAssignmentEntity } from "./entity";
+export { tierEngineFeature } from "./feature";