@cosmicdrift/kumiko-bundled-features 0.48.0 → 0.50.0

package/src/config/handlers/values.query.ts

@@ -1,13 +1,16 @@
 import {
+  type ConfigKeyDefinition,
   type ConfigScope,
   type ConfigValueSource,
   defineQueryHandler,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
-import { deserializeValue } from "../resolver";
+import { redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
 import { hasConfigAccess } from "../write-helpers";
 
+const MASKED = "••••••";
+
 export const valuesQuery = defineQueryHandler({
   name: "values",
   schema: z.object({}),
@@ -19,7 +22,24 @@ export const valuesQuery = defineQueryHandler({
     const resolver = requireConfigResolver(ctx, "config:query:values");
 
     const allKeys = registry.getAllConfigKeys();
-    const storedValues = await resolver.getAllWithSource(query.user.tenantId, query.user.id, db);
+    const keyDefs = new Map<string, ConfigKeyDefinition>();
+    const filteredKeys: string[] = [];
+    for (const [qualifiedKey, keyDef] of allKeys) {
+      if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
+      keyDefs.set(qualifiedKey, keyDef);
+      filteredKeys.push(qualifiedKey);
+    }
+
+    // Resolve through the full cascade (rows → app-override → computed →
+    // default) — the same path as config:query:cascade — so the mask shows the
+    // inherited default (e.g. an ENV-bridged app-override), not only DB rows.
+    const cascades = await resolver.getCascadeBatch(
+      filteredKeys,
+      keyDefs,
+      query.user.tenantId,
+      query.user.id,
+      db,
+    );
 
     const result: Record<
       string,
@@ -30,22 +50,24 @@ export const valuesQuery = defineQueryHandler({
       }
     > = {};
 
-    for (const [qualifiedKey, keyDef] of allKeys) {
-      if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
+    for (const [qualifiedKey, keyDef] of keyDefs) {
+      const rawCascade = cascades.get(qualifiedKey);
+      if (!rawCascade) continue;
 
-      const stored = storedValues.get(qualifiedKey);
-      let value: string | number | boolean | undefined;
-      const source: ConfigValueSource = stored?.source ?? "default";
+      // Redact inherited platform rungs BEFORE masking — masking alone leaves
+      // a value present and would leak "it is set" to a tenant-side viewer.
+      const cascade = shouldRedactInherited(keyDef, query.user.roles)
+        ? redactInheritedCascade(rawCascade)
+        : rawCascade;
 
+      let value: string | number | boolean | undefined;
       if (keyDef.encrypted) {
-        value = stored ? "••••••" : undefined;
-      } else if (stored?.value !== null && stored?.value !== undefined) {
-        value = deserializeValue(stored.value, keyDef.type);
+        value = cascade.value !== undefined ? MASKED : undefined;
       } else {
-        value = keyDef.default;
+        value = cascade.value;
       }
 
-      result[qualifiedKey] = { value, scope: keyDef.scope, source };
+      result[qualifiedKey] = { value, scope: keyDef.scope, source: cascade.source };
     }
 
     return result;

package/src/config/index.ts

@@ -21,7 +21,7 @@ export {
   collectMissingRequiredConfig,
 } from "./handlers/readiness.query";
 export type { AppConfigOverrides, ConfigResolver } from "./resolver";
-export { createConfigResolver, validateAppOverrides } from "./resolver";
+export { buildEnvConfigOverrides, createConfigResolver, validateAppOverrides } from "./resolver";
 export { configValuesTable } from "./table";
 
 // Boot helper for runDevApp / runProdApp: pulls every ConfigSeedDef from

package/src/config/read-redaction.ts

@@ -0,0 +1,54 @@
+import type {
+  ConfigCascade,
+  ConfigCascadeLevel,
+  ConfigKeyDefinition,
+  ConfigValueSource,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const SYSTEM_ADMIN_ROLE = "SystemAdmin";
+
+// The viewer's own cascade rungs. Every other rung (system-row, app-override,
+// computed, default) carries a platform-inherited value — for an
+// inheritedToTenant:false key those must stay hidden from a tenant-side viewer.
+const OWN_SOURCES: ReadonlySet<ConfigValueSource> = new Set(["user-row", "tenant-row"]);
+
+// A SystemAdmin owns the platform-level values and may always see them. Every
+// other viewer (TenantAdmin, User) is tenant-side — for an
+// inheritedToTenant:false key they must learn neither the inherited platform
+// value nor that it is set.
+export function mayViewInheritedValue(roles: readonly string[]): boolean {
+  return roles.includes(SYSTEM_ADMIN_ROLE);
+}
+
+export function shouldRedactInherited(
+  keyDef: Pick<ConfigKeyDefinition, "inheritedToTenant">,
+  roles: readonly string[],
+): boolean {
+  return keyDef.inheritedToTenant === false && !mayViewInheritedValue(roles);
+}
+
+// Strips every platform-inherited level (system-row, app-override, computed,
+// default — anything that is not the viewer's own user-/tenant-row) so a
+// tenant-side viewer sees an inheritedToTenant:false key as if no platform
+// value existed, then recomputes the winning level among the survivors. A
+// no-op when the cascade carries no inherited value.
+export function redactInheritedCascade(cascade: ConfigCascade): ConfigCascade {
+  let redacted = false;
+  const levels: ConfigCascadeLevel[] = cascade.levels.map((level) => {
+    if (!OWN_SOURCES.has(level.source) && level.hasValue) {
+      redacted = true;
+      return { ...level, value: undefined, hasValue: false, isActive: false };
+    }
+    return { ...level, isActive: false };
+  });
+  if (!redacted) return cascade;
+
+  for (let i = 0; i < levels.length; i++) {
+    const level = levels[i];
+    if (level?.hasValue) {
+      levels[i] = { ...level, isActive: true };
+      return { value: level.value, source: level.source, levels };
+    }
+  }
+  return { value: undefined, source: "missing", levels };
+}

package/src/config/resolver.ts

@@ -93,6 +93,12 @@ async function buildCascade(
     case "user":
       lookups.push({ tenantId, userId, source: "user-row", label: "User" });
       lookups.push({ tenantId, userId: null, source: "tenant-row", label: "Tenant" });
+      lookups.push({
+        tenantId: SYSTEM_TENANT_ID,
+        userId: null,
+        source: "system-row",
+        label: "System",
+      });
       break;
     case "tenant":
       lookups.push({ tenantId, userId: null, source: "tenant-row", label: "Tenant" });
@@ -240,7 +246,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
       db,
     ): Promise<ConfigValueWithSource> {
       // Resolution cascade based on scope
-      // user:   userId+tenantId → tenantId → default
+      // user:   userId+tenantId → tenantId → SYSTEM_TENANT_ID → default
       // tenant: tenantId → SYSTEM_TENANT_ID → default
       // system: SYSTEM_TENANT_ID → default
       const lookups: Array<{
@@ -253,6 +259,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
         case "user":
           lookups.push({ tenantId, userId, source: "user-row" });
           lookups.push({ tenantId, userId: null, source: "tenant-row" });
+          lookups.push({ tenantId: SYSTEM_TENANT_ID, userId: null, source: "system-row" });
           break;
         case "tenant":
           lookups.push({ tenantId, userId: null, source: "tenant-row" });
@@ -505,3 +512,65 @@ export function validateAppOverrides(
 
   return validated;
 }
+
+// --- ENV → App-Override Bridge ---
+//
+// Realises the `env` field of a config key: at boot every config
+// key that declares `env` reads its value from the process environment and
+// injects it as an app-override default (the cascade rung between the
+// tenant/system rows and the declared default). String env values are coerced
+// to the key's type; a mismatch fails the boot loudly rather than silently
+// resolving to the wrong value. Reuses validateAppOverrides for the
+// existence / bounds / options / computed-conflict gates.
+//
+// undefined OR empty-string env vars are skipped — an unset (or `FOO=`)
+// variable must not clobber a declared default.
+
+type EnvSource = Readonly<Record<string, string | undefined>>;
+
+type ConfigKeyRegistry = {
+  getAllConfigKeys: () => ReadonlyMap<string, ConfigKeyDefinition>;
+  getConfigKey: (key: string) => ConfigKeyDefinition | undefined;
+};
+
+function coerceEnvValue(
+  qualifiedKey: string,
+  envName: string,
+  type: ConfigKeyDefinition["type"],
+  raw: string,
+): string | number | boolean {
+  if (type === "number") {
+    const n = Number(raw.trim());
+    if (!Number.isFinite(n)) {
+      throw new Error(
+        `ENV config bridge: "${envName}" → "${qualifiedKey}" expects a number, got "${raw}".`,
+      );
+    }
+    return n;
+  }
+  if (type === "boolean") {
+    const v = raw.trim().toLowerCase();
+    if (v === "true" || v === "1") return true;
+    if (v === "false" || v === "0") return false;
+    throw new Error(
+      `ENV config bridge: "${envName}" → "${qualifiedKey}" expects a boolean (true/false/1/0), got "${raw}".`,
+    );
+  }
+  // text | select — select-option membership is validated by validateAppOverrides
+  return raw;
+}
+
+export function buildEnvConfigOverrides(
+  registry: ConfigKeyRegistry,
+  env: EnvSource,
+): AppConfigOverrides {
+  const record: Record<string, string | number | boolean> = {};
+  for (const [qualifiedKey, keyDef] of registry.getAllConfigKeys()) {
+    const envName = keyDef.env;
+    if (!envName) continue;
+    const raw = env[envName];
+    if (raw === undefined || raw === "") continue;
+    record[qualifiedKey] = coerceEnvValue(qualifiedKey, envName, keyDef.type, raw);
+  }
+  return validateAppOverrides(registry, record);
+}

package/src/config/web/client-plugin.ts

@@ -0,0 +1,24 @@
+// @runtime client
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import { CONFIG_FEATURE } from "../constants";
+import { defaultTranslations } from "./i18n";
+
+export type ConfigClientOptions = {
+  /** Key-wise overrides over the default bundles (de/en). */
+  readonly translations?: TranslationsByLocale;
+};
+
+export type ConfigClientFeature = {
+  readonly name: typeof CONFIG_FEATURE;
+  readonly translations: TranslationsByLocale;
+};
+
+// Ships the generic Settings-Hub labels (config.settings.*). Mount it in
+// clientFeatures next to the app's own feature client — without it the
+// audience groups render their raw i18n keys.
+export function configClient(options?: ConfigClientOptions): ConfigClientFeature {
+  return {
+    name: CONFIG_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+  };
+}

package/src/config/web/i18n.ts

@@ -0,0 +1,25 @@
+// @runtime client
+// Default labels for the auto-generated Settings-Hub. The generator
+// (buildConfigFeatureSchema) emits `config.settings.<scope>` for the audience
+// groups and `config.settings.title` for the synthetic workspace — generic
+// across every app, so they ship here. configClient() hangs them into the
+// LocaleProvider as a fallback; an app overrides individual keys via
+// configClient({ translations: { de: { ... } } }). The app only adds labels
+// for ITS keys (mask.title) and the per-feature group key `<feature>.settings`.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "config.settings.title": "Einstellungen",
+    "config.settings.system": "Plattform",
+    "config.settings.tenant": "Organisation",
+    "config.settings.user": "Persönlich",
+  },
+  en: {
+    "config.settings.title": "Settings",
+    "config.settings.system": "Platform",
+    "config.settings.tenant": "Organization",
+    "config.settings.user": "Personal",
+  },
+};

package/src/config/web/index.ts

@@ -0,0 +1,3 @@
+// @runtime client
+export { type ConfigClientFeature, type ConfigClientOptions, configClient } from "./client-plugin";
+export { defaultTranslations } from "./i18n";

package/src/custom-fields/aggregate-id.ts

@@ -24,6 +24,7 @@ const FIELD_DEFINITION_NAMESPACE = "f1d3b2c7-4e5a-4b9c-8d1f-2a3b4c5d6e7f";
  *   definieren (422 `fieldKey_conflict`). Verhindert Resolution-Ambiguität
  *   beim Read.
  */
+// @wrapper-known uuid-domain
 export function fieldDefinitionAggregateId(
   tenantId: string,
   entityName: string,

package/src/custom-fields/wire-for-entity.ts

@@ -29,6 +29,7 @@ import { customFieldsFeature } from "./feature";
 //
 // Spec-Promise: customFields verhält sich wie Stammfelder. Default `{}`,
 // NOT NULL — analog zu embedded-Spalten.
+// @wrapper-known semantic-alias
 export function customFieldsField(): JsonbFieldDef {
   return createJsonbField();
 }

package/src/delivery/upsert-preference.ts

@@ -27,6 +27,7 @@ const executor = createEventStoreExecutor(
 // im Helper (db-row-boundary), nicht 4× pro Callsite.
 type PreferenceLookupRow = { readonly id: string; readonly version: number };
 
+// @wrapper-known semantic-alias
 async function lookup(
   db: TenantDb,
   tenantId: TenantId,

package/src/file-provider-inmemory/feature.ts

@@ -73,7 +73,7 @@ export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
       // Returnt den per-tenant Storage. Identitätsstabil zwischen calls
       // damit accumulated state erhalten bleibt.
       return getOrCreateProviderForTenant(tenantId);
-    },
+    }, // @wrapper-known semantic-alias
   };
   r.useExtension("fileProvider", "inmemory", plugin);
 });

package/src/file-provider-s3/feature.ts

@@ -97,7 +97,7 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
   // Plugin-Registration. entityName "s3" ist was tenants in
   // file-foundation's `provider` config-key setzen.
   const plugin: FileProviderPlugin = {
-    build: async (ctx: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId),
+    build: async (ctx: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId), // @wrapper-known semantic-alias
   };
   r.useExtension("fileProvider", "s3", plugin);
 

package/src/mail-transport-inmemory/feature.ts

@@ -87,7 +87,7 @@ export const mailTransportInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
       // Returnt den per-tenant Buffer. Identitätsstabil zwischen calls
       // damit die Demo-Inbox accumulated bleibt.
       return getOrCreateTransportForTenant(tenantId);
-    },
+    }, // @wrapper-known semantic-alias
   };
   r.useExtension("mailTransport", "inmemory", plugin);
 });

package/src/mail-transport-smtp/feature.ts

@@ -110,7 +110,7 @@ export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
   // `entityName` "smtp" is what tenants set in mail-foundation's
   // `provider` config-key to pick this transport.
   const plugin: MailTransportPlugin = {
-    build: async (ctx: HandlerContext, tenantId: string) => buildSmtpTransport(ctx, tenantId),
+    build: async (ctx: HandlerContext, tenantId: string) => buildSmtpTransport(ctx, tenantId), // @wrapper-known semantic-alias
   };
   r.useExtension("mailTransport", "smtp", plugin);
 

package/src/step-dispatcher/mail-runner.ts

@@ -27,6 +27,7 @@ export function setMailRunner(fn: (spec: MailSpec) => Promise<MailDispatchResult
   mailRunner = fn;
 }
 
+// @wrapper-known entry-point
 export async function performMailDispatch(spec: MailSpec): Promise<MailDispatchResult> {
   return mailRunner(spec);
 }

package/src/subscription-stripe/__tests__/plugin-methods.test.ts

@@ -24,7 +24,7 @@ import type { StripeCtxRuntime } from "../runtime";
 const TEST_API_KEY = "sk_test_dummy";
 
 function buildStripe(): Stripe {
-  return new Stripe(TEST_API_KEY, { apiVersion: "2026-04-22.dahlia" });
+  return new Stripe(TEST_API_KEY);
 }
 
 /** Test-runtime: gibt den gespyten Client zurück + ein billing-live-Gate

package/src/subscription-stripe/__tests__/stripe-foundation.integration.test.ts

@@ -66,7 +66,7 @@ let webhookApp: Hono;
 let webhookAppWithSecrets: Hono;
 let secretsCtx: SecretsContext;
 
-const stripeForFixtures = new Stripe(TEST_API_KEY, { apiVersion: "2026-04-22.dahlia" });
+const stripeForFixtures = new Stripe(TEST_API_KEY);
 
 beforeAll(async () => {
   // subscription-stripe requires jetzt config + secrets. Scenarios 1–4

package/src/subscription-stripe/__tests__/verify-webhook.test.ts

@@ -27,7 +27,7 @@ const TEST_API_KEY = "sk_test_dummy_apikey";
 // Test-helpers
 // =============================================================================
 
-const stripeForFixtures = new Stripe(TEST_API_KEY, { apiVersion: "2026-04-22.dahlia" });
+const stripeForFixtures = new Stripe(TEST_API_KEY);
 
 /** Test-runtime: liefert den fixture-Client + TEST_SECRET (statt sie aus
  *  system-secrets aufzulösen — die Resolution testet runtime.test.ts). */

package/src/subscription-stripe/constants.ts

@@ -6,10 +6,6 @@ export const SUBSCRIPTION_STRIPE_FEATURE = "subscription-stripe" as const;
 // `/api/subscription/webhook/stripe`.
 export const STRIPE_PROVIDER_NAME = "stripe" as const;
 
-// Stripe-API-version-pin. Zentral, damit jeder Client (egal ob mount-time-
-// fallback oder runtime-rotiert) dieselbe API-Version spricht.
-export const STRIPE_API_VERSION = "2026-04-22.dahlia" as const;
-
 // Secret- + config-key short-names. Qualified zu `subscription-stripe:<name>`
 // (secrets) bzw. `subscription-stripe:config:<name>` (config) beim
 // registry-build.

package/src/subscription-stripe/runtime.ts

@@ -35,7 +35,7 @@ import {
 import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import Stripe from "stripe";
-import { STRIPE_API_VERSION, SUBSCRIPTION_STRIPE_FEATURE } from "./constants";
+import { SUBSCRIPTION_STRIPE_FEATURE } from "./constants";
 
 const API_KEY_HINT =
   "Set the system-scoped Stripe API key via secrets:write:set (or seed it from STRIPE_API_KEY during the env bridge).";
@@ -48,7 +48,9 @@ export function createStripeClientCache(): (apiKey: string) => Stripe {
   return (apiKey) => {
     const cached = cache.get(apiKey);
     if (cached) return cached;
-    const client = new Stripe(apiKey, { apiVersion: STRIPE_API_VERSION });
+    // No apiVersion pin — a string literal breaks consumers' typecheck on newer
+    // stripe SDKs (#256); the SDK's own default keeps wire-version and types aligned.
+    const client = new Stripe(apiKey);
     cache.set(apiKey, client);
     return client;
   };
@@ -126,6 +128,7 @@ export function createStripeRuntimes(deps: StripeRuntimeDeps): StripeRuntimes {
 
   return {
     ctx: {
+      // @wrapper-known semantic-alias
       clientForCtx: async (ctx) => clientFor(await ctxApiKey(ctx)),
       assertBillingLive: async (ctx) => {
         const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;

package/src/subscription-stripe/verify-webhook.ts

@@ -207,6 +207,7 @@ export function mapStripeStatus(stripeStatus: Stripe.Subscription.Status): Subsc
 /** Holt die Subscription aus dem Event. Subscription-events haben sie
  *  direkt im data.object; invoice-events haben nur die subscription-id
  *  und brauchen einen lazy-fetch via stripe.subscriptions.retrieve. */
+// @wrapper-known semantic-alias
 async function extractSubscriptionFromEvent(
   event: Stripe.Event,
   stripe: Stripe,

package/src/tenant/__tests__/multi-tenant.integration.test.ts

@@ -344,3 +344,51 @@ describe("disabled tenant", () => {
     expect(activeIds.data).toContain(testTenantId(2));
   });
 });
+
+// --- Scenario 7: memberships batch-load (#324) ---
+//
+// Die memberships-Query reichert alle Tenants in EINEM IN-Batch an statt eines
+// fetchOne pro Membership. Dieser Test deckt die zwei Dinge ab, die der
+// Batch-Refactor brechen könnte: korrektes Keying jeder Membership auf IHREN
+// Tenant (kein Kollaps/Vertauschen bei mehreren Memberships) und die Toleranz
+// gegenüber einer fehlenden Tenant-Projection-Row (Drift → Membership bleibt
+// gelistet, kein Login-Lockout). Läuft als letzter Block — eigener User, kein
+// geteilter Tenant-State.
+
+describe("memberships batch-load (#324)", () => {
+  const batchUserId = "11111111-0000-4000-8000-000000000020";
+  const driftTenantId = testTenantId(777);
+
+  test("enriches every membership from one IN-batch, keeps drift rows", async () => {
+    // tenant 1 (ACME) + tenant 2 (Beta Inc) existieren und sind enabled;
+    // driftTenant wurde nie erstellt → keine Projection-Row.
+    for (const tenantId of [testTenantId(1), testTenantId(2), driftTenantId]) {
+      const r = await writeApi(systemAdmin, TenantHandlers.addMember, {
+        userId: batchUserId,
+        tenantId,
+        roles: ["Viewer"],
+      });
+      expect(r.isSuccess).toBe(true);
+    }
+
+    const result = await queryApi(systemAdmin, TenantQueries.memberships, { userId: batchUserId });
+    const memberships: Array<Record<string, unknown>> = result.data;
+    expect(memberships.length).toBe(3);
+
+    const acme = memberships.find((m) => m["tenantId"] === testTenantId(1));
+    expect(acme?.["tenantName"]).toBe("ACME");
+    expect(acme?.["tenantKey"]).toBe("acme");
+
+    const beta = memberships.find((m) => m["tenantId"] === testTenantId(2));
+    expect(beta?.["tenantName"]).toBe("Beta Inc");
+    expect(beta?.["tenantKey"]).toBe("beta");
+
+    // Drift: Membership zeigt auf einen Tenant ohne Projection-Row → bleibt
+    // gelistet, nur ohne tenantName/tenantKey.
+    const drift = memberships.find((m) => m["tenantId"] === driftTenantId);
+    expect(drift).toBeDefined();
+    expect(drift?.["tenantName"]).toBeUndefined();
+    expect(drift?.["tenantKey"]).toBeUndefined();
+    expect(drift?.["roles"]).toEqual(["Viewer"]);
+  });
+});

package/src/tenant/handlers/list.query.ts

@@ -13,5 +13,5 @@ export const listQuery = defineQueryHandler({
     search: z.string().optional(),
   }),
   access: { roles: ["SystemAdmin"] },
-  handler: async (query, ctx) => crud.list(query.payload, query.user, ctx.db),
+  handler: async (query, ctx) => crud.list(query.payload, query.user, ctx.db), // @wrapper-known semantic-alias
 });

package/src/tenant/handlers/memberships.query.ts

@@ -1,4 +1,4 @@
-import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler, SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
@@ -13,18 +13,20 @@ export const membershipsQuery = defineQueryHandler({
   access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
   handler: async (query, ctx) => {
     const rows = await selectMany(ctx.db, tenantMembershipsTable, { userId: query.payload.userId });
+    if (rows.length === 0) return [];
 
-    // tenantName/tenantKey machen Memberships in der UI unterscheidbar
-    // (Tenant-Switcher zeigte sonst nur das UUID-Präfix — bei Seed-Tenants
-    // mit 00000000-…-Präfix sind die ununterscheidbar). Eine Handvoll
-    // Memberships pro User → Einzel-Fetches sind ok.
-    const enriched = await Promise.all(
-      rows.map(async (row) => {
-        const tenant = await fetchOne<{ name?: unknown; key?: unknown; isEnabled?: unknown }>(
-          ctx.db,
-          tenantTable,
-          { id: row["tenantId"] },
-        );
+    // tenantName/tenantKey machen Memberships im UI unterscheidbar (sonst nur
+    // das UUID-Präfix — Seed-Tenants mit 00000000-…-Präfix wären ununterscheidbar).
+    // Ein einzelner IN-Batch über alle tenantIds statt fetchOne pro Membership (#324).
+    type TenantRow = { id: unknown; name?: unknown; key?: unknown; isEnabled?: unknown };
+    const tenants = await selectMany<TenantRow>(ctx.db, tenantTable, {
+      id: rows.map((row) => row["tenantId"]),
+    });
+    const tenantById = new Map<unknown, TenantRow>(tenants.map((t) => [t.id, t]));
+
+    return rows
+      .map((row) => {
+        const tenant = tenantById.get(row["tenantId"]);
         // Disabled Tenants (tenant:write:disable) zählen nicht als Membership:
         // Login wählt sie nicht, /auth/tenants listet sie nicht, switch-tenant
         // antwortet not_a_member. Nur das explizite false filtert — eine
@@ -37,8 +39,7 @@ export const membershipsQuery = defineQueryHandler({
           ...(typeof tenant?.name === "string" && { tenantName: tenant.name }),
           ...(typeof tenant?.key === "string" && { tenantKey: tenant.key }),
         };
-      }),
-    );
-    return enriched.filter((m) => m !== null);
+      })
+      .filter((m) => m !== null);
   },
 });

package/src/tenant/handlers/toggle-enabled.write.ts

@@ -15,7 +15,7 @@ function createToggleTenantHandler(enable: boolean) {
     handler: async (event, ctx) =>
       crud.update({ id: event.payload.id, changes: { isEnabled: enable } }, event.user, ctx.db, {
         skipOptimisticLock: true,
-      }),
+      }), // @wrapper-known semantic-alias
   });
 }
 

package/src/tenant/handlers/update.write.ts

@@ -16,5 +16,5 @@ export const updateWrite = defineWriteHandler({
     changes: z.object({ name: z.string().min(1).max(200).optional() }),
   }),
   access: { roles: ["Admin", "SystemAdmin"] },
-  handler: async (event, ctx) => crud.update(event.payload, event.user, ctx.db),
+  handler: async (event, ctx) => crud.update(event.payload, event.user, ctx.db), // @wrapper-known semantic-alias
 });

package/src/text-content/api.ts

@@ -36,6 +36,7 @@ export type TextContentApi = {
   }) => Promise<TextBlock | null>;
 };
 
+// @wrapper-known semantic-alias
 export function createTextContentApi(db: DbConnection): TextContentApi {
   return {
     getBlock: async ({ tenantId, slug, lang }) => {

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

@@ -22,6 +22,7 @@ const TIER_ASSIGNMENT_NAMESPACE = "8e91d2fc-8b7a-4d3e-9f4a-1c5d6e7f8a9b";
  * 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/src/user/handlers/me.query.ts

@@ -11,5 +11,5 @@ export const meQuery = defineQueryHandler({
   name: "user:me",
   schema: z.object({}),
   access: { openToAll: true },
-  handler: async (query, ctx) => crud.detail({ id: query.user.id }, query.user, ctx.db),
+  handler: async (query, ctx) => crud.detail({ id: query.user.id }, query.user, ctx.db), // @wrapper-known semantic-alias
 });

package/src/user-data-rights/db/queries/export-jobs.ts

@@ -13,6 +13,7 @@ export type ExportJobCleanupCandidate = {
   readonly expiresAt: Temporal.Instant | null;
 };
 
+// @wrapper-known semantic-alias
 export async function selectExportJobsForStorageCleanup(
   db: DbConnection,
   doneStatus: string,

package/src/user-data-rights/deletion-token.ts

@@ -15,6 +15,7 @@ export type VerifyResult =
   | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
   | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
 
+// @wrapper-known semantic-alias
 export function signDeletionToken(
   userId: string,
   ttlMinutes: number,
@@ -24,6 +25,7 @@ export function signDeletionToken(
   return signToken(userId, DELETION_REQUEST_PURPOSE, ttlMinutes, secret, now);
 }
 
+// @wrapper-known semantic-alias
 export function verifyDeletionToken(
   token: string,
   secret: string,

package/src/user-data-rights/feature.ts

@@ -285,7 +285,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           db: ctx.db as import("@cosmicdrift/kumiko-framework/db").DbConnection, // @cast-boundary db-operator
           registry: ctx.registry,
           buildStorageProvider: async (tenantId) =>
-            createFileProviderForTenant(providerCtx, tenantId, "user-data-rights:run-export-jobs"),
+            createFileProviderForTenant(providerCtx, tenantId, "user-data-rights:run-export-jobs"), // @wrapper-known semantic-alias
           now: T.Now.instant(),
           // Atom 5 — App-Author-Callbacks fuer Email-Notification.
           // Optional: wenn nicht gesetzt, kein Email; User pollt