@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/tier-engine/constants.ts

@@ -0,0 +1,28 @@
+// @runtime client
+// Pure string-literal QNs/ids — imported by both server (feature.ts) and
+// client (web/client-plugin.tsx). Marked `client`, the most permissive
+// category in the kumiko isolation model (runtime may import client, client
+// may only import client) — otherwise the runtime isolation guard throws on
+// the client imports. Same pattern as text-content/constants.
+// 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",
+  setTenantTier: "tier-engine:write:set-tenant-tier",
+} as const;
+
+// Qualified query handler names.
+export const TierEngineQueries = {
+  list: "tier-engine:query:tier-assignment:list",
+  getActiveTier: "tier-engine:query:get-active-tier",
+  getTenantTier: "tier-engine:query:get-tenant-tier",
+  tierOptions: "tier-engine:query:tier-options",
+} as const;
+
+// Screen-id für den manuellen Tier-Grant-Screen. Apps referenzieren ihn
+// qualifiziert in r.nav: `tier-engine:screen:tier-admin`.
+export const TIER_ADMIN_SCREEN_ID = "tier-admin" as const;

package/packages/bundled-features/src/tier-engine/entity.ts

@@ -0,0 +1,55 @@
+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",
+  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.",
+  fields: {
+    tier: createTextField({
+      required: true,
+      maxLength: 50,
+      personal: false,
+      reason: "catalog_label",
+    }),
+    // Woher das Assignment stammt: "manual" (Admin-Grant via tier-admin-Screen),
+    // "stripe" (future Billing-Sync), "default" (auto-default-on-signup-Hook).
+    // Optional für Back-Compat zu bestehenden Rows ohne source. Schützt manuelle
+    // Grants davor, von einem späteren Stripe→Tier-Sync geplättet zu werden.
+    source: createTextField({
+      required: false,
+      maxLength: 20,
+      personal: false,
+      reason: "technical_reference",
+    }),
+  },
+});
+
+export type TierAssignmentRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly tier: string;
+  readonly source: string | null;
+  readonly tenantId: string;
+};

package/packages/bundled-features/src/tier-engine/feature.ts

@@ -0,0 +1,549 @@
+// 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). Optional (mit `tierMap` in Options): per-tenant feature-set
+//   resolution via Framework's `tenantTierResolver`-extension — das
+//   dispatcher-feature-gate fragt automatisch pro request den resolver
+//   nach dem effective Set für den aktiven Tenant.
+//
+// **Zwei Use-Modes:**
+//   1. `createTierEngineFeature()` ohne opts — nur Storage (Standard-CRUD
+//      für tier-assignment-Entity). Apps die composeApp() oder eigene
+//      logic nutzen.
+//   2. `createTierEngineFeature({ defaultTier, tierMap })` — vollständige
+//      Tier-Composition. Sprint-8a Pattern für multi-tenant SaaS-Apps.
+//      Framework auto-wires effectiveFeatures via extension-pickup.
+//
+// **Generic über Tier-Werte:** das Feature kennt keine "free"/"pro"/etc.
+//   konkreten Tier-Werte. App definiert ihre TierMap.
+//
+// **Auto-Default-Tier on Tenant-Signup:** wenn `opts.defaultTier` gesetzt
+//   ist, schreibt ein r.entityHook("postSave", "tenant", phase: inTransaction)
+//   automatisch eine tier-assignment für den neuen Tenant. Atomic mit
+//   tenant-create — wenn tier-assignment fail't, tenant-create rolled back.
+//   Idempotent via deterministic aggregate-id (re-replay re-checkt stream-
+//   version, skip wenn schon da). Plus: cache-miss-fallback returnt
+//   defaultTier-features wenn assignment-row fehlt (defense-in-depth gegen
+//   replay-races wo der hook noch nicht durch ist).
+//
+// **In-Memory-Cache mit Push-Invalidation:**
+//   Closure-state pro feature-instance hält die effective Sets pro Tenant.
+//   r.entityHook auf tier-assignment:postSave/postDelete hält cache aktuell.
+//   Erste-Request-Cold-Cache: pre-load via build(deps) im extension-pickup
+//   Pfad (boot-time via runDevApp/runProdApp).
+//
+// **SYSTEM_TENANT_ID-Convention:**
+//   resolver-callback bei call mit SYSTEM_TENANT_ID returnt union aller
+//   tier-features (für event-dispatcher async-pass + operator-tooling).
+//   Siehe DispatcherOptions.effectiveFeatures-doc.
+//
+// **Boot-Dependencies:** config + tenant.
+
+// kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312 (feature.ts > 300 lines)
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  defineQueryHandler,
+  type FeatureDefinition,
+  HookPhases,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  TENANT_TIER_RESOLVER_EXT,
+  type TenantId,
+  type TierResolverPlugin,
+  type TrialGate,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { getUnscopedAggregateStreamMaxVersion } from "@cosmicdrift/kumiko-framework/event-store";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import * as z from "zod";
+import { tenantTable } from "../tenant/index.js";
+import { tierAssignmentAggregateId } from "./aggregate-id.js";
+import type { TierMap } from "./compose-app.js";
+import { TIER_ADMIN_SCREEN_ID, TIER_ENGINE_FEATURE, TierEngineHandlers } from "./constants.js";
+import { tierAssignmentEntity } from "./entity.js";
+import { getActiveTierQuery } from "./handlers/active-tier.query.js";
+import { getTenantTierQuery } from "./handlers/get-tenant-tier.query.js";
+import { createSetTenantTierWrite } from "./handlers/set-tenant-tier.write.js";
+import { TIER_ENGINE_I18N } from "./i18n.js";
+import { isTrialActive, type TrialPolicy } from "./trial.js";
+
+// Drizzle-table for the tier-assignment-entity. Built once at module-load
+// from the entity definition — same shape buildEntityTable would produce
+// in the App's drizzle/schema.generated.ts.
+const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
+
+// Event-store-executor für direct-write aus dem auto-default-tier-hook.
+// Pattern wie tenant/seeding.ts: hook sieht AppContext (kein ctx.write),
+// muss aber atomisch mit tenant-create im selben TX schreiben → executor
+// direkt aufrufen, nicht via dispatcher.
+const tierAssignmentExecutor = createEventStoreExecutor(tierAssignmentTable, tierAssignmentEntity, {
+  entityName: "tier-assignment",
+});
+
+const adminAccess = { access: { roles: ["TenantAdmin", "SystemAdmin"] } } as const;
+// Tier-Wechsel ist Plattform-/Billing-Hoheit — ein Tenant-Admin darf den
+// eigenen Tier NIE setzen (sonst Gratis-Self-Upgrade). Daher sind die
+// Writes SystemAdmin-only; Reads (list, get-active-tier) bleiben
+// TenantAdmin-sichtbar. Auto-default-Hook + Billing schreiben als System,
+// hängen also nicht an diesem Handler-Access.
+const writeAccess = { access: { roles: ["SystemAdmin"] } } as const;
+
+/**
+ * Options for createTierEngineFeature. Both fields optional — wenn beide
+ * leer, ist die feature nur Storage (back-compat zu legacy `tierEngineFeature`).
+ *
+ * @template TCaps - App-spezifischer Cap-Shape. Type-leakt durch tierMap →
+ * future capsFor() resolver returnt diesen Shape exakt.
+ */
+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.
+   */
+  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).
+   */
+  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.
+   */
+  readonly trial?: TrialPolicy;
+};
+
+/**
+ * Compute the union of features across all tiers — verwendet bei
+ * SYSTEM_TENANT_ID-resolver-call (operator-tooling, async-event-dispatch).
+ * Operator-UI sieht alle features unabhängig vom tier-cut, async-events
+ * laufen tier-agnostic durch.
+ */
+function unionAllTierFeatures<TCaps extends Readonly<Record<string, unknown>>>(
+  tierMap: TierMap<TCaps>,
+): ReadonlySet<string> {
+  const all = new Set<string>();
+  for (const tier of Object.values(tierMap)) {
+    for (const f of tier.features) all.add(f);
+  }
+  return all;
+}
+
+/**
+ * Compute the feature-set for a given tier-name. Unknown tier → empty Set
+ * (defensive — verwendete tier-namen werden nicht an boot-time validiert
+ * weil tier-engine generic über tier-Werte ist).
+ */
+function featuresForTier<TCaps extends Readonly<Record<string, unknown>>>(
+  tierMap: TierMap<TCaps>,
+  tierName: string,
+): ReadonlySet<string> {
+  const tier = tierMap[tierName];
+  if (!tier) return new Set();
+  return new Set(tier.features);
+}
+
+/**
+ * Merge always-on features (non-toggleable framework-base) mit tier-cut
+ * features (toggleable per tier). Canonical Kumiko: dispatcher-gate
+ * blockt nur features die explizit `r.toggleable()` haben — alle anderen
+ * sind immer aktiv. Tier-resolver muss das selbe pattern liefern.
+ */
+function mergeAlwaysOn(
+  alwaysOn: ReadonlySet<string>,
+  tierFeatures: ReadonlySet<string>,
+): ReadonlySet<string> {
+  const merged = new Set<string>(alwaysOn);
+  for (const f of tierFeatures) merged.add(f);
+  return merged;
+}
+
+/**
+ * Factory: create a tier-engine feature instance with optional auto-tier-
+ * resolution + default-tier-on-signup behavior. Returns FeatureDefinition
+ * mountable in run-config.
+ */
+export function createTierEngineFeature<
+  TCaps extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
+>(opts: CreateTierEngineOptions<TCaps> = {}): FeatureDefinition {
+  return defineFeature(TIER_ENGINE_FEATURE, (r) => {
+    r.describe(
+      'Stores a `tier-assignment` entity per tenant (which pricing tier is active) and, when configured with a `TierMap`, registers itself as the `tenantTierResolver` extension so the dispatcher automatically gates `r.toggleable()` features per tenant based on their assigned tier. Call `createTierEngineFeature({ defaultTier, tierMap })` to get full tier composition \u2014 including an `inTransaction` entity hook that atomically writes the default tier when a new tenant is created \u2014 or use `createTierEngineFeature()` without options for storage-only mode when you manage tier assignment yourself via `composeApp`. A SystemAdmin-only `set-tenant-tier` write plus `get-tenant-tier`/`tier-options` reads let an operator assign a tier to ANY tenant manually \u2014 without a billing purchase \u2014 stamping `source: "manual"` so a future Stripe\u2192tier sync won\'t overwrite the grant. Apps surface this via the `tier-admin` screen, which is always registered — in storage-only mode (no `tierMap`) it shows an honest "no tiers configured" message instead of a tier dropdown.',
+    );
+    r.uiHints({
+      displayLabel: "Tier Engine \u00b7 Plan Composition",
+      category: "billing",
+      recommended: false,
+    });
+    r.requires("config");
+    r.requires("tenant");
+
+    r.entity("tier-assignment", tierAssignmentEntity);
+
+    // Standard-CRUD via Helper.
+    r.writeHandler(
+      defineEntityCreateHandler("tier-assignment", tierAssignmentEntity, {
+        ...writeAccess,
+        // Bypasses the feature-gate refresh that set-tenant-tier performs.
+        agent: { expose: false },
+      }),
+    );
+    r.writeHandler(
+      defineEntityUpdateHandler("tier-assignment", tierAssignmentEntity, {
+        ...writeAccess,
+        agent: { expose: false },
+      }),
+    );
+
+    // Reads.
+    r.queryHandler(
+      defineEntityListHandler("tier-assignment", tierAssignmentEntity, {
+        ...adminAccess,
+        description:
+          "Lists the tier-assignment rows visible to the caller with tier name and assignment source; use it to see which plan is stored for a tenant.",
+      }),
+    );
+    r.queryHandler(getActiveTierQuery);
+
+    // \u2500\u2500 Manueller Tier-Grant (SystemAdmin, ohne Billing) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    // Cross-tenant set + read f\u00fcr den tier-admin-Screen. tier-options liefert
+    // dem Client die App-Tier-Namen aus der tierMap-Closure (sonst hartkodiert).
+    //
+    // onAssigned h\u00e4lt den Resolver-Cache nach einem direkten Executor-Write
+    // warm (der den postSave-Hook NICHT feuert). Late-bind via Holder: ohne
+    // tierMap bleibt es no-op (kein Resolver), im tierMap-Block unten wird
+    // die echte Cache-Update-Funktion eingeh\u00e4ngt \u2014 analog alwaysOnHolder.
+    const onTierAssigned: { fn: (tenantId: TenantId, tier: string) => void } = { fn: () => {} };
+    r.writeHandler(
+      createSetTenantTierWrite({
+        onAssigned: (tenantId, tier) => onTierAssigned.fn(tenantId, tier),
+        validTiers: opts.tierMap ? new Set(Object.keys(opts.tierMap)) : undefined,
+      }),
+    );
+    r.queryHandler(getTenantTierQuery);
+    r.queryHandler(
+      defineQueryHandler({
+        name: "tier-options",
+        description:
+          "Returns the tier names the application defines in its tier map; use it to find out which values `set-tenant-tier` accepts.",
+        schema: z.object({}),
+        access: { roles: ["SystemAdmin"] },
+        handler: async () => ({ tiers: opts.tierMap ? Object.keys(opts.tierMap) : [] }),
+      }),
+    );
+
+    // Declarative form for the manual grant. SystemAdmin-only, hard-wired
+    // (platform-admin authority, not app-configurable). Apps place it only
+    // via r.nav("tier-engine:screen:tier-admin"); tier options are built
+    // statically from the tierMap closure. Always registered — even in
+    // storage-only mode (no tierMap) — so the screen shows an honest
+    // "no tiers configured" message instead of vanishing (samples like
+    // use-all-bundled deliberately mount storage-only to screenshot that
+    // empty state).
+    r.translations({ keys: TIER_ENGINE_I18N });
+    r.screen({
+      id: TIER_ADMIN_SCREEN_ID,
+      type: "actionForm",
+      handler: TierEngineHandlers.setTenantTier,
+      fields: {
+        tenantId: {
+          type: "reference",
+          entity: "tenant:tenant",
+          labelField: "name",
+          required: true,
+        },
+        tier: {
+          type: "select",
+          options: opts.tierMap ? Object.keys(opts.tierMap) : [],
+          required: true,
+        },
+      },
+      layout: {
+        sections: [
+          {
+            fields: ["tenantId", "tier"],
+            description: opts.tierMap ? "tier-admin.explainer" : "tier-admin.error.noTiers",
+          },
+        ],
+      },
+      submitLabel: "tier-admin.submit",
+      cancelTarget: false,
+      description: "tier-admin.screen.subtitle",
+      access: { roles: ["SystemAdmin"] },
+      // Apps place it via r.nav() (see above) — no nav area to resolve in
+      // isolation.
+      dormant: true,
+    });
+
+    // ───────────────────────────────────────────────────────────────────
+    // Resolver-extension (only when tierMap is configured)
+    // ───────────────────────────────────────────────────────────────────
+    // skip: ohne tierMap ist die feature nur Storage (legacy back-compat
+    // zu `tierEngineFeature`). Resolver-extension + invalidation-hooks
+    // brauchen die tierMap zum Mapping tier-name → feature-set.
+    if (!opts.tierMap) return;
+
+    const tierMap = opts.tierMap;
+
+    // Closure-state: cache per-tenant effective Sets. Hooks halten den
+    // cache aktuell during process-lifetime; build() im extension-pickup
+    // pre-loaded existing assignments at boot.
+    const cache = new Map<TenantId, ReadonlySet<string>>();
+    // alwaysOn-Set wird in build(deps) aus registry.features berechnet (alle
+    // non-toggleable features). Hooks brauchen Zugriff darauf für
+    // mergeAlwaysOn-calls — Late-bind via mutable holder, gefüllt vor allen
+    // Requests (build läuft pre-listen via runDevApp/runProdApp-pickup).
+    const alwaysOnHolder: { set: ReadonlySet<string> } = { set: new Set() };
+
+    // Trial: zeit-abgeleitet aus tenant.inserted_at (≈ Signup), live am
+    // Feature-Gate geprüft — NICHT im Resolver-Cache. Der Resolver ist
+    // boot-cached + synchron und sieht weder frische Signups noch den
+    // Zeitablauf; der Trial-Status ändert sich aber mit der Zeit und gilt ab
+    // Sekunde 1 nach Signup. Darum lebt er als async trialGate (unten, am
+    // build-Ende angehängt), den der dispatcher nur auf dem disabled-Pfad
+    // konsultiert. trialFeatures = fixe Feature-Menge des Trial-Tiers.
+    if (opts.trial && !tierMap[opts.trial.tier]) {
+      throw new Error(
+        `tier-engine: trial.tier "${opts.trial.tier}" is not a key in tierMap — trial would unlock no features`,
+      );
+    }
+    const trialFeatures: ReadonlySet<string> = opts.trial
+      ? featuresForTier(tierMap, opts.trial.tier)
+      : new Set();
+    const nowMs = (): number => getTemporal().Now.instant().epochMilliseconds;
+
+    // set-tenant-tier schreibt direkt über den Executor → der postSave-Hook
+    // unten feuert dabei NICHT. Diese Funktion repliziert den Cache-Update
+    // des Hooks, damit ein manueller Grant das effektive Feature-Set sofort
+    // ändert (nicht nur die Projektion). Selber Cache, selbe mergeAlwaysOn-
+    // Semantik wie der Hook.
+    onTierAssigned.fn = (tenantId, tier) => {
+      cache.set(tenantId, mergeAlwaysOn(alwaysOnHolder.set, featuresForTier(tierMap, tier)));
+    };
+
+    // Invalidation: tier-assignment events update the cache.
+    r.hook("postSave", { allOf: "tier-assignment" }, async (result) => {
+      // result.data has tenantId + tier (after entity-update merge)
+      const data = result.data as { tenantId?: unknown; tier?: unknown }; // @cast-boundary engine-payload
+      // skip: defensive type-guard auf payload-shape. Bei korrekt gerenderten
+      // entity-events sind beide fields immer strings; ein malformed-payload
+      // (custom-handler-bug) würde hier silent zum cache-skip führen statt
+      // throwing — der lifecycle-pipeline darf nicht durch hook-fehler
+      // blocken (afterCommit-pattern, side-effect-best-effort).
+      if (typeof data.tenantId !== "string" || typeof data.tier !== "string") return;
+      const tenantId = data.tenantId as TenantId;
+      cache.set(tenantId, mergeAlwaysOn(alwaysOnHolder.set, featuresForTier(tierMap, data.tier)));
+    });
+    r.hook("postDelete", { allOf: "tier-assignment" }, async (payload) => {
+      const data = payload.data as { tenantId?: unknown }; // @cast-boundary engine-payload
+      // skip: gleiche type-guard semantik wie postSave-hook oben.
+      if (typeof data.tenantId !== "string") return;
+      cache.delete(data.tenantId as TenantId);
+    });
+
+    // Auto-default-tier-on-tenant-signup: hook fires inTransaction (atomic
+    // mit tenant-create rollback), schreibt tier-assignment via Direct-
+    // Executor (nicht ctx.write — hook hat AppContext). Pattern analog
+    // tenant/seeding.ts seedTenant.
+    //
+    // **Idempotency:** deterministic aggregate-id aus tenantId. Re-replay
+    // (nach projection-rebuild oder hook-retry) findet stream-version > 0
+    // und skipt, statt version_conflict zu werfen. Caller sieht erfolgreichen
+    // tenant-create + bestehende tier-assignment.
+    //
+    // **Cross-tenant write:** executor braucht systemUser MIT tenantId =
+    // neuer Tenant (Memory `feedback_event_store_tenant_consistency`).
+    if (opts.defaultTier !== undefined) {
+      const defaultTier = opts.defaultTier;
+      const autoDefaultTierHookReason =
+        "seeds the default tier-assignment stream of the tenant just created";
+      r.hook(
+        "postSave",
+        { allOf: "tenant" },
+        async (result, ctx) => {
+          // result-shape: kumiko-framework's SaveContext mit isNew + data
+          const saveResult = result as { isNew?: unknown; data?: unknown }; // @cast-boundary engine-payload
+          // skip: nur bei tenant-create (initial) — tenant-updates feuern
+          // auch postSave aber wir wollen kein neues tier-assignment bei
+          // re-keying oder name-update.
+          if (saveResult.isNew !== true) return;
+          const data = saveResult.data as { id?: unknown }; // @cast-boundary engine-payload
+          // skip: defensive type-guard. Tenant-entity hat id zwingend, aber
+          // CrudExecutor's payload-shape ist runtime-unknown.
+          if (typeof data.id !== "string") return;
+          const newTenantId = data.id as TenantId; // @cast-boundary engine-payload
+          const aggregateId = tierAssignmentAggregateId(newTenantId);
+
+          // tenant is an r.systemScope() feature, so this cross-feature hook gets a
+          // fail-closed ctx.db — reach for ctx.systemDb instead (see entity-handlers.ts).
+          // Event-store paths need the raw DbConnection — TenantDb only exposes
+          // select/insert/update/delete, not execute (db.execute(sql`SELECT pg_notify(...)`) would TypeError).
+          const rawDb = ctx.systemDb
+            ? ctx.systemDb.unsafeRaw(autoDefaultTierHookReason)
+            : ctx.db && "unsafeRaw" in ctx.db
+              ? ctx.db.unsafeRaw(autoDefaultTierHookReason)
+              : undefined;
+          // skip: defensive — inTransaction phase always sets db, but AppContext's
+          // type makes it optional. Throwing would be overreach (lifecycle
+          // blocking), silent-skip is defensive-soft.
+          if (!rawDb) return;
+
+          // Idempotency: stream-existence-check vor create. Pattern aus
+          // seedTenant.ts. Bei re-replay (rebuild) nicht versionsbumpen.
+          const streamVersion = await getUnscopedAggregateStreamMaxVersion(rawDb, aggregateId);
+          // skip: idempotent — tier-assignment stream already seeded (rebuild/replay).
+          if (streamVersion > 0) return;
+
+          // SystemUser für den NEUEN tenant — der Hook wird vom signup-
+          // user (anderer tenant, oder SystemAdmin) ausgelöst, aber das
+          // tier-assignment muss im stream des neu-erzeugten tenants
+          // landen (= aggregate-id deterministic auf newTenantId). Memory
+          // `feedback_event_store_tenant_consistency`: by.tenantId muss =
+          // ziel-tenant.
+          const systemUser: SessionUser = {
+            id: "00000000-0000-4000-8000-000000000001",
+            tenantId: newTenantId,
+            roles: ["SystemAdmin"],
+          };
+          const tdb = createTenantDb(rawDb, newTenantId, "system");
+
+          await tierAssignmentExecutor.create(
+            { id: aggregateId, tier: defaultTier, source: "default" },
+            systemUser,
+            tdb,
+          );
+        },
+        { phase: HookPhases.inTransaction, escapeHatch: { reason: autoDefaultTierHookReason } },
+      );
+    }
+
+    // Extension-point declaration + self-registration. Pattern analog
+    // mail-foundation/file-foundation: das feature deklariert den
+    // extension-point UND registriert sich als default-plugin. Andere
+    // features könnten später auch dort registrieren (z.B. ein future
+    // toggle-only-resolver), aber nur ein plugin gewinnt — siehe
+    // findTierResolverUsage's "single-plugin"-comment.
+    r.extendsRegistrar(TENANT_TIER_RESOLVER_EXT, { onRegister: () => {} });
+
+    // Plugin-registration: framework's runDevApp/runProdApp picks this up
+    // post-stack-setup, calls build(deps), wires effectiveFeatures.
+    const plugin: TierResolverPlugin = {
+      build: async (deps) => {
+        // Always-on-Set: alle non-toggleable features im registry. Canonical
+        // Kumiko-pattern (matches feature-toggles' resolver): nur features
+        // die explizit `r.toggleable()` registrieren sind tier-cuttable.
+        // Framework-base-features (auth-email-password, config, user, tenant,
+        // sessions, etc.) sind non-toggleable → IMMER aktiv für jeden Tenant
+        // unabhängig vom tier. Sonst würde dispatcher 403 auf login-handler
+        // werfen weil "feature auth-email-password disabled".
+        const computedAlwaysOn = new Set<string>();
+        for (const feature of deps.registry.features.values()) {
+          if (feature.toggleableDefault === undefined) computedAlwaysOn.add(feature.name);
+        }
+        alwaysOnHolder.set = computedAlwaysOn;
+
+        // Pre-load all existing assignments into cache. SaaS-Apps haben
+        // typischerweise <100k tenants — single-pass scan akzeptabel.
+        // Skalierungs-Pfad (lazy-load + LRU) ist Sprint-8b wenn echtes
+        // Bedürfnis entsteht.
+        type AssignmentRow = { tenantId: string; tier: string };
+        const rows = await selectMany<AssignmentRow>(deps.db, tierAssignmentTable);
+        for (const row of rows) {
+          cache.set(
+            row.tenantId as TenantId,
+            mergeAlwaysOn(computedAlwaysOn, featuresForTier(tierMap, row.tier)),
+          );
+        }
+
+        // Synchronous resolver-callback for dispatcher hot-path.
+        const resolver = (tenantId: TenantId): ReadonlySet<string> => {
+          // Operator-tooling + async-event-dispatch convention: SYSTEM_TENANT_ID
+          // gets the union of all tier-features (siehe DispatcherOptions doc).
+          if (tenantId === SYSTEM_TENANT_ID) {
+            return mergeAlwaysOn(computedAlwaysOn, unionAllTierFeatures(tierMap));
+          }
+          // Cache-miss: tenant ist noch nicht im cache (z.B. brandneu nach
+          // boot, oder defaultTier-hook hat noch nicht gefired). Default-Set
+          // ist least-privileged — typisch Free-Tier-features. Memory
+          // `feedback_security_default_on`: secure-by-default. Der Trial wird
+          // hier NICHT addiert (sync/boot-cached sieht den Zeitablauf nicht) —
+          // das macht der trialGate unten am disabled-Gate-Pfad.
+          const fallbackTier = opts.defaultTier;
+          return (
+            cache.get(tenantId) ??
+            (fallbackTier === undefined
+              ? computedAlwaysOn
+              : mergeAlwaysOn(computedAlwaysOn, featuresForTier(tierMap, fallbackTier)))
+          );
+        };
+
+        const trial = opts.trial;
+        if (trial === undefined) return resolver;
+
+        // Live-Trial-Gate: liest tenant.inserted_at (≈ Signup, existiert für
+        // JEDEN Tenant inkl. auth-signup via seedTenant — anders als die
+        // tier-assignment-Row, die der seed-Pfad nicht anlegt) und prüft das
+        // Fenster gegen die aktuelle Zeit. Nur auf dem disabled-Gate-Pfad
+        // konsultiert. inserted_at ist immutable → pro Tenant einmal lesen.
+        // Promise-memo (not a plain value cache): N concurrent requests for the
+        // same fresh tenant must await the SAME in-flight fetchOne, not each
+        // fire their own — a plain `Map<TenantId, number>` set AFTER the await
+        // lets every concurrent caller miss the cache and issue a redundant
+        // read (benign but wasteful on a signup burst).
+        const startedMemo = new Map<TenantId, Promise<number | undefined>>();
+        const trialGate: TrialGate = async (tenantId, featureName) => {
+          if (!trialFeatures.has(featureName)) return false;
+          let startedMsPromise = startedMemo.get(tenantId);
+          if (startedMsPromise === undefined) {
+            startedMsPromise = fetchOne<{ insertedAt?: Temporal.Instant }>(deps.db, tenantTable, {
+              id: tenantId,
+            }).then((row) => row?.insertedAt?.epochMilliseconds);
+            // Evict on rejection too — a transient DB error must not poison
+            // every future call for this tenant with the same cached rejection.
+            startedMsPromise.catch(() => startedMemo.delete(tenantId));
+            startedMemo.set(tenantId, startedMsPromise);
+          }
+          const startedMs = await startedMsPromise;
+          // Tenant-Row noch nicht projiziert (Replay-Race) → keinen Miss
+          // memoizen, beim nächsten Request neu lesen.
+          if (startedMs === undefined) {
+            startedMemo.delete(tenantId);
+            return false;
+          }
+          return isTrialActive(startedMs, nowMs(), trial.durationHours);
+        };
+        return Object.assign(resolver, { trialGate });
+      },
+    };
+    // biome-ignore lint/correctness/useHookAtTopLevel: r.useExtension is a framework registrar method, not a React hook.
+    r.useExtension(TENANT_TIER_RESOLVER_EXT, TIER_ENGINE_FEATURE, plugin);
+  });
+}
+
+/**
+ * Legacy named export — equivalent to `createTierEngineFeature()` ohne opts.
+ * Storage-only mode (no resolver, no auto-default). Existing apps die
+ * `tierEngineFeature` referenzieren bekommen identical behavior.
+ *
+ * Migration zu `createTierEngineFeature({ defaultTier, tierMap })` gibt
+ * volle Tier-Composition (Sprint-8a Pattern).
+ */
+export const tierEngineFeature: FeatureDefinition = createTierEngineFeature();

package/packages/bundled-features/src/tier-engine/handlers/active-tier.query.ts

@@ -0,0 +1,25 @@
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as 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",
+  description:
+    "Returns the tier-assignment row currently active for the caller's own tenant, or null when none is assigned; use it to answer which plan the caller is on.",
+  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;
+  },
+};