@cosmicdrift/kumiko-framework 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# @cosmicdrift/kumiko-framework
+
+## 0.2.2
+
+### Patch Changes
+
+- 7a7da3e: Re-publish 0.2.1 → 0.2.2 mit korrekt aufgelösten cross-package-Versionen.
+  0.2.1 hatte `workspace:*` als Wert in den dependencies (npm publish ohne
+  yarn-pack rewrite), Konsumenten bekamen "Workspace not found".
+
+  publish-with-oidc.sh nutzt jetzt `yarn pack` (rewrited workspace:\*) +
+  `npm publish <tarball>` (OIDC + provenance).
+
+## 0.2.1
+
+### Patch Changes
+
+- 48b7f6a: CI: switch publish to npm-CLI with OIDC Trusted Publishing + provenance.
+  No source changes — verifies the new publish path produces a verified-
+  provenance attestation on npmjs.com instead of token-based publish.
+
+## 0.2.0
+
+### Minor Changes
+
+- 6c70b6f: fix(tenant): seedTenant idempotent gegen Event-Store-Projection-Drift.
+
+  Verhindert version_conflict beim App-Boot wenn Aggregat existiert aber
+  Projection-Row fehlt (rebuild-drift, async-lag, manueller DB-Eingriff).
+
+## 0.1.0
+
+### Minor Changes
+
+- 59ba6d7: Initial public release of Kumiko — AI-native backend builder.
+
+  What ships in 0.1.0:
+
+  - **Engine** (`@cosmicdrift/kumiko-framework`): `defineFeature`, `r.entity`, `r.writeHandler`, `r.queryHandler`, `r.projection`, `r.multiStreamProjection`, `r.hook`, `r.translations`, `r.crud`, `r.referenceData`, `r.screen`, `r.nav`, `r.authClaims`, full lifecycle pipeline with field-level access checks
+  - **Pipeline** (`@cosmicdrift/kumiko-framework`): `createDispatcher`, JWT auth via jose, Zod schema validation, role-based access checks, command/write/query split
+  - **DB** (`@cosmicdrift/kumiko-framework`): Drizzle helpers (`buildDrizzleTable`, `applyCursorQuery`), CRUD executor, Postgres dialect, optimistic locking, soft delete, multi-tenant scoping
+  - **Event sourcing** (`@cosmicdrift/kumiko-framework`): aggregate streams, single + multi-stream projections, event upcasters, asOf queries, archive support, AsyncDaemon-pattern dispatcher
+  - **Bundled features** (`@cosmicdrift/kumiko-bundled-features`): auth-email-password, sessions, tenants, users, jobs, secrets, file-provider-s3, mail-transport-smtp/inmemory, billing-foundation, cap-counter, channel-in-app, delivery, feature-toggles, legal-pages
+  - **Renderer** (`@cosmicdrift/kumiko-renderer`, `@cosmicdrift/kumiko-renderer-web`): schema-driven CRUD UI for React + Expo Web, override paths, list debounce, theme tokens
+  - **Headless** (`@cosmicdrift/kumiko-headless`): view-models for list/edit screens, locale-aware
+  - **Dev server** (`@cosmicdrift/kumiko-dev-server`): `runDevApp`, `runProdApp`, `kumiko-build` for production bundles (client + server), Docker-ready
+  - **Realtime** (`@cosmicdrift/kumiko-dispatcher-live`): SSE broadcast across tenants, Redis Pub/Sub backend
+  - **CLI** (`bin/kumiko.ts`): interactive dev menu, test runners, check pipeline (Biome + TypeScript + 18 guards + Vitest)
+
+  This is a pre-1.0 release — APIs may change between minor versions. Breaking changes will be documented per release.

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cosmicdriftgamestudio/kumiko-framework.git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
     "directory": "packages/framework"
   },
   "bugs": {
-    "url": "https://github.com/cosmicdriftgamestudio/kumiko-framework/issues"
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
   },
   "homepage": "https://kumiko.so",
   "keywords": [
@@ -73,7 +73,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "workspace:*",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.2.2",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.2.9",
     "drizzle-kit": "^0.31.0",
@@ -88,4 +88,4 @@
     "README.md",
     "LICENSE"
   ]
-}
+}

package/src/engine/index.ts

@@ -126,6 +126,12 @@ export {
   SYSTEM_ROLE,
   SYSTEM_USER_ID,
 } from "./system-user";
+export {
+  type EffectiveFeaturesResolver,
+  findTierResolverUsage,
+  TENANT_TIER_RESOLVER_EXT,
+  type TierResolverPlugin,
+} from "./tier-resolver-extension";
 // Types
 export type {
   AccessRule,

package/src/engine/tier-resolver-extension.ts

@@ -0,0 +1,78 @@
+// Sprint-8a Tier-Composition: framework-extension-point für per-tenant
+// effective-feature resolution.
+//
+// **Pattern (analog mail-foundation / file-foundation):** ein Feature
+// declares `r.extendsRegistrar("tenantTierResolver")` und plugins
+// implementieren via `r.useExtension("tenantTierResolver", "id", { build })`.
+//
+// **Auto-wiring im Framework:** runDevApp + runProdApp scannen das registry
+// nach genau diesem extension-name. Wenn ein plugin gefunden ist UND der
+// App-Author nicht selbst eine `effectiveFeatures`-callback gesetzt hat,
+// wird `plugin.build({ db, registry })` einmalig in onAfterSetup aufgerufen.
+// Der returned callback landet als `effectiveFeatures` im dispatcher.
+//
+// **Warum dieser Pattern:** App-Author mountet `createTierEngineFeature(opts)`
+// und das war's — kein Late-Bound-Holder im run-config, kein
+// effectiveFeatures-callback wiren. Das Framework macht den Late-Bound-Trick
+// intern. Memory `feedback_alles_ist_ein_feature`: Tier-Composition ist
+// ein Feature, nicht ein Subsystem mit App-spezifischem Wiring.
+//
+// **Apps ohne tier-engine:** wenn keine plugin registriert ist, framework
+// macht nichts — `effectiveFeatures` bleibt undefined, alle features sind on.
+
+import type { DbConnection } from "../db/connection";
+import type { RegistrarExtensionRegistration } from "./types/config";
+import type { FeatureDefinition, Registry } from "./types/feature";
+import type { TenantId } from "./types/identifiers";
+
+/**
+ * Extension-name unter dem ein tier-resolver-plugin im registry registriert
+ * werden muss. Konstante damit `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
+ * + framework's `getExtensionUsages(TENANT_TIER_RESOLVER_EXT)` typo-resistent
+ * gegen den selben Wert prüfen.
+ */
+export const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
+
+/**
+ * Resolver-callback shape: synchron (dispatcher hot-path), per-tenant.
+ * Returnt das effective feature-Set für den tenant. Implementations sollten
+ * einen in-memory cache pflegen + per `r.entityHook` invalidieren.
+ *
+ * **System-context convention:** call mit SYSTEM_TENANT_ID erwartet die union
+ * aller tier-features (siehe DispatcherOptions.effectiveFeatures doc-block).
+ */
+export type EffectiveFeaturesResolver = (tenantId: TenantId) => ReadonlySet<string>;
+
+/**
+ * Plugin-shape für tier-resolver-extension. Plugins implementieren `build`
+ * als boot-time factory: kriegen `db` + `registry` (post-stack-setup),
+ * laden initial cache aus DB, returnen den synchronen resolver-callback.
+ */
+export type TierResolverPlugin = {
+  readonly build: (deps: {
+    readonly db: DbConnection;
+    readonly registry: Registry;
+  }) => Promise<EffectiveFeaturesResolver>;
+};
+
+/**
+ * Scan a composed feature-list for a `tenantTierResolver`-extension usage.
+ * Single plugin assumption — multiple wären ambiguous (welcher resolver
+ * gewinnt). Memory `feedback_no_options_without_need`: kein multi-merge-
+ * pattern bis es echten Use-Case gibt.
+ *
+ * Geteilter helper für runDevApp + runProdApp damit der Pickup-Pfad
+ * bit-identisch ist (drift-resistent).
+ */
+export function findTierResolverUsage(
+  features: readonly FeatureDefinition[],
+): RegistrarExtensionRegistration | undefined {
+  for (const feature of features) {
+    for (const usage of feature.extensionUsages) {
+      if (usage.extensionName === TENANT_TIER_RESOLVER_EXT) {
+        return usage;
+      }
+    }
+  }
+  return undefined;
+}

package/src/engine/types/handlers.ts

@@ -261,11 +261,13 @@ type SharedContextFields = {
   // rebuildProjection) honour it automatically.
   readonly signal?: AbortSignal;
   // Effective feature-toggle resolver. Wired by the dispatcher when the
-  // feature-toggles feature is loaded — the lifecycle pipeline, MSP runner,
-  // and ctx.hasFeature all read from this single source. Returns the Set
-  // of feature names that are currently effectively enabled (after global
-  // overrides and r.requires() cascade). Absent = all features on.
-  readonly effectiveFeatures?: () => ReadonlySet<string>;
+  // feature-toggles or tier-engine feature is loaded — the lifecycle
+  // pipeline, MSP runner, and ctx.hasFeature all read from this single
+  // source. Per-tenant: tenantId argument enables tier-cuts (Sprint 8a)
+  // where Tenant-A sees Pro features and Tenant-B sees Free features in
+  // the same process. Returns the Set of feature names effectively
+  // enabled for that tenant. Absent = all features on (back-compat).
+  readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
 };
 
 // All optional — used at pipeline/system boundaries.
@@ -286,6 +288,12 @@ export type AppContext = SharedContextFields & {
   readonly triggerName?: string;
   readonly _userId?: string | undefined;
   readonly _handlerType?: string | undefined;
+  /** Tenant des aktuellen Pipeline-Calls. Wird vom Dispatcher beim Bauen
+   *  des HandlerContext aus `user.tenantId` gespiegelt, damit lifecycle-
+   *  pipeline + system-hooks den Wert ohne Zugriff auf user-Object haben.
+   *  Sprint-8a Tier-Composition: `effectiveFeatures(ctx._tenantId)`-call
+   *  in den hook-filter-Stellen. */
+  readonly _tenantId?: TenantId;
 };
 
 // Handler execution: db (tenant-scoped) + registry guaranteed.

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "vitest";
 import { z } from "zod";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import type { TenantId } from "../../engine/types/identifiers";
 import { createTestUser } from "../../stack";
 import { createDispatcher } from "../dispatcher";
 
@@ -321,6 +322,78 @@ describe("dispatcher feature-gate", () => {
       items: [],
     });
   });
+
+  test("Sprint 8a: per-tenant gating — Tenant A passes, Tenant B gets feature_disabled", async () => {
+    // Beweist die Phase-1-Architektur: dispatcher ruft effectiveFeatures
+    // mit user.tenantId, resolver kann pro Tenant unterschiedliche Sets
+    // returnen → Tier-A sieht feature, Tier-B nicht.
+    const registry = createRegistry([toggled()]);
+    const tenantA = "00000000-0000-4000-8000-0000000000a1" as TenantId;
+    const tenantB = "00000000-0000-4000-8000-0000000000b2" as TenantId;
+
+    const dispatcher = createDispatcher(
+      registry,
+      {},
+      {
+        effectiveFeatures: (tenantId) => (tenantId === tenantA ? new Set(["toggled"]) : new Set()),
+      },
+    );
+
+    const userA = createTestUser({ id: "u-a", tenantId: tenantA, roles: ["Admin"] });
+    const userB = createTestUser({ id: "u-b", tenantId: tenantB, roles: ["Admin"] });
+
+    await expect(dispatcher.query("toggled:query:widget:list", {}, userA)).resolves.toEqual({
+      items: [],
+    });
+    await expect(dispatcher.query("toggled:query:widget:list", {}, userB)).rejects.toThrow(
+      /feature toggled is disabled/,
+    );
+
+    const writeA = await dispatcher.write("toggled:write:widget:create", { name: "from-a" }, userA);
+    expect(writeA.isSuccess).toBe(true);
+
+    const writeB = await dispatcher.write("toggled:write:widget:create", { name: "from-b" }, userB);
+    expect(writeB.isSuccess).toBe(false);
+    if (!writeB.isSuccess) {
+      expect(writeB.error.code).toBe("feature_disabled");
+    }
+  });
+
+  test("Sprint 8a: ctx.hasFeature is current-user-scoped", async () => {
+    // Pin: hasFeature() in handler-bodies resolves against ctx.user.tenantId,
+    // NICHT gegen einen globalen Set. Two tenants call same handler,
+    // beide rufen hasFeature("toggled") — A bekommt true, B false.
+    const tenantA = "00000000-0000-4000-8000-0000000000a3" as TenantId;
+    const tenantB = "00000000-0000-4000-8000-0000000000b4" as TenantId;
+
+    const probe = defineFeature("probe", (r) => {
+      r.queryHandler(
+        "check",
+        z.object({}).passthrough(),
+        async (_event, ctx) => ({ enabled: ctx.hasFeature("toggled") }),
+        { access: { openToAll: true } },
+      );
+    });
+    const registry = createRegistry([toggled(), probe]);
+    const dispatcher = createDispatcher(
+      registry,
+      {},
+      {
+        effectiveFeatures: (tenantId) =>
+          tenantId === tenantA ? new Set(["toggled", "probe"]) : new Set(["probe"]),
+      },
+    );
+
+    const userA = createTestUser({ id: "u-a2", tenantId: tenantA, roles: ["Admin"] });
+    const userB = createTestUser({ id: "u-b2", tenantId: tenantB, roles: ["Admin"] });
+
+    await expect(dispatcher.query("probe:query:check", {}, userA)).resolves.toEqual({
+      enabled: true,
+    });
+    await expect(dispatcher.query("probe:query:check", {}, userB)).resolves.toEqual({
+      enabled: false,
+    });
+  });
 });
 
 describe("write-handler shape guard", () => {

package/src/pipeline/__tests__/lifecycle-pipeline.test.ts

@@ -9,6 +9,7 @@ import {
   type PreSaveHookFn,
   type SaveContext,
 } from "../../engine";
+import type { TenantId } from "../../engine/types/identifiers";
 import { buildEventId, createLifecycleHooks, type SystemHooks } from "../lifecycle-pipeline";
 
 function makeRegistry(hooks?: { preSave?: PreSaveHookFn[]; postSave?: PostSaveHookFn[] }) {
@@ -400,6 +401,105 @@ describe("runPostSave phase routing", () => {
   });
 });
 
+// =============================================================================
+// Sprint 8a: per-tenant entity-hook filter
+// =============================================================================
+//
+// Setup: Feature A owns the entity. Feature B registers an entity-hook
+// on A's entity (cross-feature pattern). lifecycle-pipeline must filter
+// B's hook based on the active tenant's effectiveFeatures-set.
+
+describe("Sprint 8a: per-tenant entity-hook filter", () => {
+  function setupTwoFeatures() {
+    const calls: Array<{ tenant: string }> = [];
+
+    const featureA = defineFeature("feat-a", (r) => {
+      r.entity("widget", createEntity({ table: "Widgets", fields: { name: createTextField() } }));
+      r.writeHandler(
+        "widget:create",
+        z.object({ name: z.string() }),
+        async () => ({ isSuccess: true as const, data: null }),
+        { access: { openToAll: true } },
+      );
+    });
+
+    const featureB = defineFeature("feat-b", (r) => {
+      r.entityHook("postSave", "widget", async (_result, ctx) => {
+        calls.push({ tenant: ctx._tenantId ?? "no-tenant" });
+      });
+    });
+
+    return { registry: createRegistry([featureA, featureB]), calls };
+  }
+
+  const tenantA = "00000000-0000-4000-8000-0000000000a1" as TenantId;
+  const tenantB = "00000000-0000-4000-8000-0000000000b2" as TenantId;
+
+  const baseSaveCtx: SaveContext = {
+    kind: "save",
+    id: 1,
+    data: { name: "x", tenantId: tenantA },
+    changes: { name: "x" },
+    previous: {},
+    isNew: true,
+    entityName: "widget",
+  };
+
+  test("Tenant A (feat-b enabled) → hook fires; Tenant B (feat-b disabled) → hook skipped", async () => {
+    const { registry, calls } = setupTwoFeatures();
+    const pipeline = createLifecycleHooks(registry);
+    const effectiveFeatures = (tenantId: TenantId) =>
+      tenantId === tenantA ? new Set(["feat-a", "feat-b"]) : new Set(["feat-a"]);
+
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {
+      _tenantId: tenantA,
+      effectiveFeatures,
+    });
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {
+      _tenantId: tenantB,
+      effectiveFeatures,
+    });
+
+    expect(calls).toEqual([{ tenant: tenantA }]);
+  });
+
+  test("ctx without _tenantId → hook fires (legacy back-compat: undefined = skip filter)", async () => {
+    // System-jobs / boot-time pipeline-calls have no user → no _tenantId.
+    // currentEffectiveFeatures returns undefined; registry filterByPhase
+    // treats undefined as "skip filter" → all hooks fire (back-compat).
+    const { registry, calls } = setupTwoFeatures();
+    const pipeline = createLifecycleHooks(registry);
+
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {});
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.tenant).toBe("no-tenant");
+  });
+
+  test("effectiveFeatures wird PRO call konsultiert (kein staler Cache zwischen runPostSave-aufrufen)", async () => {
+    // Pin: currentEffectiveFeatures-helper ruft effectiveFeatures jedes
+    // mal neu — keine pipeline-internal Memoization. Toggle-flips müssen
+    // sofort greifen, nicht erst nach pipeline-restart.
+    const { registry, calls } = setupTwoFeatures();
+    const pipeline = createLifecycleHooks(registry);
+    const enabled = new Set<string>(["feat-a", "feat-b"]);
+    const effectiveFeatures = (_tenantId: TenantId) => enabled;
+
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {
+      _tenantId: tenantA,
+      effectiveFeatures,
+    });
+    enabled.delete("feat-b");
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {
+      _tenantId: tenantA,
+      effectiveFeatures,
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.tenant).toBe(tenantA);
+  });
+});
+
 describe("buildEventId — dedup key construction", () => {
   test("includes handler, id, version and phase when payload is complete", () => {
     const payload = { id: 42, data: { version: 3 } };

package/src/pipeline/dispatcher.ts

@@ -7,6 +7,7 @@ import { hasAccess } from "../engine/access";
 import { checkWriteFieldRoles, filterReadFields } from "../engine/field-access";
 import { parseQn, qn } from "../engine/qualified-name";
 import { defineTransitions, guardTransition } from "../engine/state-machine";
+import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
 import type {
   AggregateStreamHandle,
   AppContext,
@@ -25,6 +26,7 @@ import type {
   WriteResult,
 } from "../engine/types";
 import { HookPhases } from "../engine/types";
+import type { TenantId } from "../engine/types/identifiers";
 
 // Re-export for callers that reach for dispatcher-adjacent types (tests,
 // HTTP-layer stubs) — dispatch consumes these, grouping the type-surface
@@ -318,13 +320,26 @@ export type DispatcherOptions = {
   idempotency?: IdempotencyGuard;
   lifecycle?: LifecycleHooks;
   jobRunner?: JobRunnerRef;
-  // Resolves the current effective-feature set — the dispatcher uses it
-  // to gate calls to handlers of disabled features (403 feature_disabled)
+  // Resolves the effective-feature set per tenant — the dispatcher uses
+  // it to gate calls to handlers of disabled features (403 feature_disabled)
   // and to populate ctx.hasFeature. Absent = all features treated as
-  // always-on (no feature-toggles feature loaded). The resolver must be
-  // fast and synchronous per call; implementations cache a DB snapshot
-  // under the hood and refresh on toggle events.
-  effectiveFeatures?: () => ReadonlySet<string>;
+  // always-on (no feature-toggles or tier-engine feature loaded). The
+  // resolver must be fast and synchronous per call; implementations cache
+  // tenant-keyed sets and refresh on tier-assignment / toggle events.
+  //
+  // **System-context convention:** when called with SYSTEM_TENANT_ID, the
+  // resolver should return the union/superset of all tier-features. Two
+  // contexts call with this sentinel:
+  //   1. event-dispatcher async-pass (consumers tagged with feature X
+  //      should not silently skip events from a tenant where X is off —
+  //      events are immutable, async work runs through).
+  //   2. operator-tooling queries (e.g. feature-toggles:registered) where
+  //      a SystemAdmin needs to see platform-truth, not their own
+  //      tier-cut.
+  // Returning a non-superset for SYSTEM_TENANT_ID will cause silent
+  // event-skips and a confusing operator-UI — the framework cannot
+  // enforce this contract, but the recipe-test pins the convention.
+  effectiveFeatures?: EffectiveFeaturesResolver;
 };
 
 type HandlerType = string | HandlerRef;
@@ -729,11 +744,14 @@ export function createDispatcher(
       // dispatcher.resolveAuthClaims) cannot drift.
       resolveAuthClaims: (claimsUser: SessionUser) => resolveAuthClaimsFn(claimsUser),
 
-      // Feature-effective check for in-handler opt-in logic. When the
-      // feature-toggles feature isn't wired (no effectiveFeatures callback),
-      // always returns true — apps without toggles treat all features on.
+      // Feature-effective check for in-handler opt-in logic. Scope:
+      // **current user's tenant** — for cross-tenant lookups (rare,
+      // SysAdmin operations) read effectiveFeatures(otherTenantId) directly.
+      // When the feature-toggles or tier-engine feature isn't wired (no
+      // effectiveFeatures callback), always returns true — apps without
+      // tier-cuts treat all features on.
       hasFeature: (featureName: string): boolean =>
-        effectiveFeatures ? effectiveFeatures().has(featureName) : true,
+        effectiveFeatures ? effectiveFeatures(user.tenantId).has(featureName) : true,
     };
 
     // Registry is always the dispatcher's registry — injecting it here lets
@@ -771,6 +789,7 @@ export function createDispatcher(
       // event.user-Wert; Identity-Switches nutzen weiterhin queryAs/writeAs.
       user,
       _userId: user.id,
+      _tenantId: user.tenantId,
       _handlerType: type,
       ...bridge,
     } as HandlerContext;
@@ -860,6 +879,7 @@ export function createDispatcher(
   // pass-through in that common case.
   function checkFeatureEnabled(
     qualifiedHandler: string,
+    tenantId: TenantId,
   ): import("../errors").FeatureDisabledError | undefined {
     if (!effectiveFeatures) return undefined;
     const owner = registry.getHandlerFeature(qualifiedHandler);
@@ -867,13 +887,13 @@ export function createDispatcher(
     // happen for registry-built handlers, but guards against edge-case
     // runtime injections.
     if (!owner) return undefined;
-    const set = effectiveFeatures();
+    const set = effectiveFeatures(tenantId);
     if (set.has(owner)) return undefined;
     return new FeatureDisabledError(owner, qualifiedHandler);
   }
 
-  function ensureFeatureEnabled(qualifiedHandler: string): void {
-    const err = checkFeatureEnabled(qualifiedHandler);
+  function ensureFeatureEnabled(qualifiedHandler: string, tenantId: TenantId): void {
+    const err = checkFeatureEnabled(qualifiedHandler, tenantId);
     if (err) throw err;
   }
 
@@ -935,7 +955,7 @@ export function createDispatcher(
     // disabled feature must not consume the rate-limit quota — the call
     // never happened from the feature's perspective. Order is: lookup →
     // feature-gate → rate-limit → access → validation → handler.
-    ensureFeatureEnabled(type);
+    ensureFeatureEnabled(type, user.tenantId);
 
     // Rate-limit gate runs BEFORE access-check on purpose: anonymous /
     // unauthorized callers must hit the cap too (otherwise the limit
@@ -1173,7 +1193,7 @@ export function createDispatcher(
 
     // Feature-toggle gate: disabled handlers must short-circuit before any
     // rate-limit/access/validation work — see executeQueryInner comment.
-    const disabledErr = checkFeatureEnabled(type);
+    const disabledErr = checkFeatureEnabled(type, user.tenantId);
     if (disabledErr) return writeFailure(disabledErr);
 
     // Rate-limit gate before access (same reasoning as in executeQueryInner).

package/src/pipeline/event-dispatcher.ts

@@ -2,6 +2,7 @@ import { and, asc, eq, gt, sql } from "drizzle-orm";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbTx, PgClient } from "../db/connection";
 import type { AppContext } from "../engine/types";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
 import {
   EVENTS_PUBSUB_CHANNEL,
   eventsTable,
@@ -487,7 +488,15 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
     // Feature-toggle snapshot taken once per pass (not per consumer): all
     // consumers see the same disabled-set even if an operator flips a
     // toggle mid-pass, so "this event batch" decisions stay consistent.
-    const effective = context.effectiveFeatures?.();
+    //
+    // Sprint-8a tier-composition: per-tenant resolver per-pass-konsultiert
+    // mit SYSTEM_TENANT_ID. Async-events sind tier-agnostic — wenn ein
+    // Tenant downgrade'd, sollen seine queued events trotzdem verarbeitet
+    // werden (events sind immutable, projection ist eventually-consistent).
+    // Tier-cuts wirken request-time im sync-dispatcher + lifecycle-pipeline,
+    // nicht im async-replay. App-level resolver entscheidet was er bei
+    // SYSTEM_TENANT_ID returnt (typisch: union-of-all-tier-features).
+    const effective = context.effectiveFeatures?.(SYSTEM_TENANT_ID);
 
     // Seriell pro consumer. Parallelisierung wäre möglich (je eigene TX), aber
     // das einfache Modell reicht für v1 — jeder consumer hat geringe

package/src/pipeline/lifecycle-pipeline.ts

@@ -20,6 +20,24 @@ function resolveTracer(context: AppContext): Tracer {
   return context.tracer ?? getFallbackTracer();
 }
 
+/**
+ * Resolve effective-feature set for the active context's tenant.
+ *
+ * `_tenantId` wird vom dispatcher beim HandlerContext-Bau aus `user.tenantId`
+ * gespiegelt. Bei legacy-callsites ohne user (system-jobs, boot-time
+ * pipeline) ist es undefined — `effectiveFeatures(undefined)` wäre type-
+ * unsafe; wir return undefined und behandeln das als "all features on"
+ * (registry filterhooks akzeptieren undefined als "skip filter").
+ *
+ * Single source — die 4 lifecycle-hook-callsites (preSave, postSave,
+ * preDelete, postDelete) rufen alle hier durch, damit der tenant-
+ * scoping-Pfad nie inkonsistent ist.
+ */
+function currentEffectiveFeatures(context: AppContext): ReadonlySet<string> | undefined {
+  if (context._tenantId === undefined) return undefined;
+  return context.effectiveFeatures?.(context._tenantId);
+}
+
 export type SystemHookDef<TFn> = {
   readonly name: string;
   readonly priority: number;
@@ -250,7 +268,7 @@ export function createLifecycleHooks(
     async runPreSave(handlerName, changes, previous, isNew, context) {
       let currentChanges = changes;
       const hookContext = { ...context, previous, isNew };
-      const eff = context.effectiveFeatures?.();
+      const eff = currentEffectiveFeatures(context);
 
       for (const hook of registry.getPreSaveHooks(handlerName, eff)) {
         currentChanges = await hook(currentChanges, hookContext);
@@ -266,7 +284,7 @@ export function createLifecycleHooks(
     },
 
     async runPostSave(handlerName, result, context, phase = HookPhases.afterCommit) {
-      const eff = context.effectiveFeatures?.();
+      const eff = currentEffectiveFeatures(context);
       await runHookSet({
         handlerName,
         payload: result,
@@ -283,7 +301,7 @@ export function createLifecycleHooks(
     async runPreDelete(handlerName, payload, context) {
       // preDelete hooks run in-transaction and throw on failure (not best-effort).
       // They're used to check invariants before delete, so phase filter is "inTransaction".
-      const eff = context.effectiveFeatures?.();
+      const eff = currentEffectiveFeatures(context);
       for (const hook of registry.getPreDeleteHooks(handlerName, HookPhases.inTransaction, eff)) {
         await hook(payload, context);
       }
@@ -308,7 +326,7 @@ export function createLifecycleHooks(
     },
 
     async runPostDelete(handlerName, payload, context, phase = HookPhases.afterCommit) {
-      const eff = context.effectiveFeatures?.();
+      const eff = currentEffectiveFeatures(context);
       await runHookSet({
         handlerName,
         payload,

package/src/stack/test-stack.ts

@@ -89,7 +89,7 @@ export type TestStackOptions = {
    *  GlobalFeatureToggleRuntime.effectiveFeatures for real DB-backed
    *  toggles, or a plain `() => new Set<string>(registry.features.keys())`
    *  to force a specific snapshot in a unit-style setup. */
-  effectiveFeatures?: () => ReadonlySet<string>;
+  effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
   /** Pin the underlying Postgres DB name instead of the default
    *  `kumiko_test_<8chars>`. Forwarded to createTestDb. Primary use
    *  case: dev servers that want persistent storage across restarts —