@cosmicdrift/kumiko-bundled-features 0.1.0

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

@@ -0,0 +1,21 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { tenantEntity, tenantTable } from "../schema/tenant";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+// Optional `id`: SystemAdmin-only handler — legitimer Pfad für Seeds und
+// externe Provisionierung (SCIM, IdP-Sync, Migration aus bestehenden Systemen),
+// wo der Tenant mit einer vom Caller gewählten UUID angelegt werden muss.
+// Wenn nicht gesetzt, Postgres vergibt via gen_random_uuid() eine neue UUID.
+export const createWrite = defineWriteHandler({
+  name: "create",
+  schema: z.object({
+    id: z.uuid().optional(),
+    key: z.string().min(1).max(50),
+    name: z.string().min(1).max(200),
+  }),
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => crud.create(event.payload, event.user, ctx.db),
+});

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

@@ -0,0 +1,18 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { tenantEntity, tenantTable } from "../schema/tenant";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+export const disableWrite = defineWriteHandler({
+  name: "disable",
+  schema: z.object({ id: z.uuid() }),
+  access: { roles: ["SystemAdmin"] },
+  // Admin flip: last-writer-wins is fine. SystemAdmin is the only caller and
+  // there's no meaningful concurrent-edit race on this single boolean.
+  handler: async (event, ctx) =>
+    crud.update({ id: event.payload.id, changes: { isEnabled: false } }, event.user, ctx.db, {
+      skipOptimisticLock: true,
+    }),
+});

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

@@ -0,0 +1,31 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+import { INVITATION_STATUS, tenantInvitationsTable } from "../invitation-table";
+
+// Pending-Invitations-Liste für den aktuellen Tenant. Admin-only.
+// Filter: status="pending" — accepted/cancelled/expired sind für die
+// UI uninteressant (UI zeigt nur "ausstehende Einladungen"; Audit-Log
+// für historische gehört in ein separates Audit-Feature).
+//
+// SQL-side filter (vorher JS-side .filter): bei Tenants mit vielen
+// historischen invitations lädt die Query sonst alle Rows in den
+// Node-process um die meisten wegzuwerfen — DB indexed das auf den
+// (tenantId, …)-key, JS-filter ist redundant.
+export const invitationsQuery = defineQueryHandler({
+  name: "invitations",
+  schema: z.object({}),
+  access: { roles: ["Admin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    const rows = await ctx.db
+      ?.select()
+      .from(tenantInvitationsTable)
+      .where(
+        and(
+          eq(tenantInvitationsTable.tenantId, query.user.tenantId),
+          eq(tenantInvitationsTable.status, INVITATION_STATUS.pending),
+        ),
+      );
+    return rows ?? [];
+  },
+});

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

@@ -0,0 +1,17 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { tenantEntity, tenantTable } from "../schema/tenant";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+export const listQuery = defineQueryHandler({
+  name: "list",
+  schema: z.object({
+    cursor: z.string().optional(),
+    limit: z.number().optional(),
+    search: z.string().optional(),
+  }),
+  access: { roles: ["SystemAdmin"] },
+  handler: async (query, ctx) => crud.list(query.payload, query.user, ctx.db),
+});

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

@@ -0,0 +1,17 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { tenantTable } from "../schema/tenant";
+
+// Direct query — query-handlers haben keinen tenant-crud-Handle. Direct-select
+// ist trivial: WHERE id = tenantId (beides UUID). Kein CRUD-Detour nötig.
+export const meQuery = defineQueryHandler({
+  name: "me",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const row = await fetchOne(ctx.db, tenantTable, eq(tenantTable["id"], query.user.tenantId));
+    return row ?? null;
+  },
+});

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

@@ -0,0 +1,22 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { tenantMembershipsTable } from "../membership-table";
+
+export const membersQuery = defineQueryHandler({
+  name: "members",
+  schema: z.object({}),
+  access: { roles: ["Admin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    const rows = await ctx.db
+      ?.select()
+      .from(tenantMembershipsTable)
+      .where(eq(tenantMembershipsTable.tenantId, query.user.tenantId));
+
+    return rows.map((row) => ({
+      ...row,
+      roles: parseRoles(row["roles"]),
+    }));
+  },
+});

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

@@ -0,0 +1,24 @@
+import { defineQueryHandler, SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { tenantMembershipsTable } from "../membership-table";
+
+export const membershipsQuery = defineQueryHandler({
+  name: "memberships",
+  schema: z.object({ userId: z.string() }),
+  // Called via ctx.queryAs(systemUser, ...) during login/switch-tenant, or
+  // directly by tenant admins managing memberships in the admin UI.
+  access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    const rows = await ctx.db
+      ?.select()
+      .from(tenantMembershipsTable)
+      .where(eq(tenantMembershipsTable.userId, query.payload.userId));
+
+    return rows.map((row) => ({
+      ...row,
+      roles: parseRoles(row["roles"]),
+    }));
+  },
+});

package/src/tenant/handlers/remove-member.write.ts

@@ -0,0 +1,40 @@
+import { createEventStoreExecutor, type DbRow, fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler, withResponseData } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { tenantMembershipEntity, tenantMembershipsTable } from "../membership-table";
+
+const executor = createEventStoreExecutor(tenantMembershipsTable, tenantMembershipEntity, {
+  entityName: "tenant-membership",
+});
+
+export const removeMemberWrite = defineWriteHandler({
+  name: "removeMember",
+  schema: z.object({ userId: z.string(), tenantId: z.string() }),
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const db = ctx.db;
+    const existing = await fetchOne(
+      db,
+      tenantMembershipsTable,
+      eq(tenantMembershipsTable.userId, event.payload.userId),
+      eq(tenantMembershipsTable.tenantId, event.payload.tenantId),
+    );
+    if (!existing) {
+      return writeFailure(
+        new NotFoundError("membership", undefined, {
+          i18nKey: "tenant.errors.membershipNotFound",
+          i18nParams: { userId: event.payload.userId, tenantId: event.payload.tenantId },
+        }),
+      );
+    }
+
+    const result = await executor.delete(
+      { id: (existing as DbRow)["id"] as string },
+      event.user,
+      db,
+    );
+    return withResponseData(result, event.payload);
+  },
+});

package/src/tenant/handlers/resolve-user-ids.query.ts

@@ -0,0 +1,43 @@
+import { defineQueryHandler, SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { tenantMembershipsTable } from "../membership-table";
+
+// Cross-feature query: resolve user IDs by tenantId or userId.
+// Other features (delivery, jobs, etc.) use this to get user lists
+// without knowing about membership internals.
+//
+// Examples:
+//   { tenantId: 1 }  → all user IDs in tenant 1
+//   { userId: 5 }    → [5] if member of any tenant, [] if not
+export const resolveUserIdsQuery = defineQueryHandler({
+  name: "resolveUserIds",
+  schema: z.object({
+    tenantId: z.string().optional(),
+    userId: z.string().optional(),
+  }),
+  // System-internal: invoked by other features (delivery, jobs) through queryAs(systemUser, ...).
+  // Never called directly by an end-user request.
+  access: { roles: [SYSTEM_ROLE] },
+  handler: async (query, ctx) => {
+    const { tenantId, userId } = query.payload;
+
+    if (tenantId !== undefined) {
+      const rows = await ctx.db
+        .select({ userId: tenantMembershipsTable.userId })
+        .from(tenantMembershipsTable)
+        .where(eq(tenantMembershipsTable.tenantId, tenantId));
+      return rows.map((r) => r["userId"] as number);
+    }
+
+    if (userId !== undefined) {
+      const rows = await ctx.db
+        .select({ userId: tenantMembershipsTable.userId })
+        .from(tenantMembershipsTable)
+        .where(eq(tenantMembershipsTable.userId, userId));
+      return rows.length > 0 ? [userId] : [];
+    }
+
+    return [];
+  },
+});

package/src/tenant/handlers/update-member-roles.write.ts

@@ -0,0 +1,54 @@
+import { createEventStoreExecutor, type DbRow, fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler, withResponseData } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { tenantMembershipEntity, tenantMembershipsTable } from "../membership-table";
+
+const executor = createEventStoreExecutor(tenantMembershipsTable, tenantMembershipEntity, {
+  entityName: "tenant-membership",
+});
+
+export const updateMemberRolesWrite = defineWriteHandler({
+  name: "updateMemberRoles",
+  schema: z.object({
+    userId: z.string(),
+    tenantId: z.string(),
+    roles: z.array(z.string()).min(1),
+  }),
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const db = ctx.db;
+    const existing = await fetchOne(
+      db,
+      tenantMembershipsTable,
+      eq(tenantMembershipsTable.userId, event.payload.userId),
+      eq(tenantMembershipsTable.tenantId, event.payload.tenantId),
+    );
+    if (!existing) {
+      return writeFailure(
+        new NotFoundError("membership", undefined, {
+          i18nKey: "tenant.errors.membershipNotFound",
+          i18nParams: { userId: event.payload.userId, tenantId: event.payload.tenantId },
+        }),
+      );
+    }
+
+    // fetchOne already gave us the stream version — hand it to the executor
+    // instead of skipping the lock. Race window (another SystemAdmin writing
+    // between this read and append) surfaces as version_conflict rather than
+    // silent overwrite. Per-membership parallelism is rare; if it happens,
+    // the client retries on the error.
+    const row = existing as DbRow;
+    const result = await executor.update(
+      {
+        id: row["id"] as string,
+        version: row["version"] as number,
+        changes: { roles: JSON.stringify(event.payload.roles) },
+      },
+      event.user,
+      db,
+    );
+    return withResponseData(result, event.payload);
+  },
+});

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

@@ -0,0 +1,20 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { tenantEntity, tenantTable } from "../schema/tenant";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+export const updateWrite = defineWriteHandler({
+  name: "update",
+  schema: z.object({
+    id: z.uuid(),
+    // Clients must send the version they read. The CrudExecutor rejects
+    // missing versions with version_conflict — see the optimistic-locking
+    // design note in crud-executor.ts.
+    version: z.number(),
+    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),
+});

package/src/tenant/index.ts

@@ -0,0 +1,12 @@
+export { TenantCommandSchemas } from "./command-schemas";
+export { TENANT_FEATURE, TenantErrors, TenantHandlers, TenantQueries } from "./constants";
+export { createTenantFeature } from "./feature";
+export type { InvitationStatus } from "./invitation-table";
+export {
+  INVITATION_STATUS,
+  INVITATION_STATUSES,
+  tenantInvitationEntity,
+  tenantInvitationsTable,
+} from "./invitation-table";
+export { tenantMembershipsTable } from "./membership-table";
+export { tenantEntity, tenantTable } from "./schema/tenant";

package/src/tenant/invitation-table.ts

@@ -0,0 +1,93 @@
+// Tenant-Invitations: Pre-Membership-Records mit Magic-Link-Token-Flow.
+//
+// Lifecycle:
+//   1. Admin invitet email → DB-Row entsteht mit status="pending",
+//      Random-Token in Redis (signup-style bidirektional)
+//   2. Mail an die invited Email mit Activation-URL
+//   3. Klick auf Link → 3 Branches:
+//      a) Eingeloggt + Email matched session-user → Membership-Add
+//      b) Anonymous + Email existiert in users → Login → Auto-Accept
+//      c) Anonymous + Email neu → Password setzen → user+membership entstehen
+//   4. Bei Erfolg: status="accepted", token aus Redis gelöscht (single-use-burn)
+//   5. Bei Cancel durch Admin: status="cancelled", token aus Redis gelöscht
+//   6. Bei TTL-Ablauf: Redis räumt Token, DB-Row bleibt mit status="pending"
+//      (Cleanup-Job marked sie als "expired" — separater Concern)
+//
+// Single-Truth für expiry: Redis-TTL. DB-row.expiresAt ist nur UI-
+// Anzeige ("läuft in 6 Tagen ab"). Bei Lookup: pending in DB + token
+// nicht mehr in Redis → effectively expired, accept schlägt fehl mit
+// invalid-token.
+//
+// Idempotenz: zweiter invite für gleiche (tenantId, email) während
+// pending → re-use existing row + refresh Redis-token + send mail
+// (analog zu signup-Resend).
+
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createSelectField,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Status-const-Object damit Handler-Code keine Magic-Strings nutzt.
+// Bei rename (z.B. "cancelled" → "revoked") fällt jeder caller auf
+// einmal auf statt verstreut über 5 Stellen.
+export const INVITATION_STATUS = {
+  pending: "pending",
+  accepted: "accepted",
+  cancelled: "cancelled",
+  expired: "expired",
+} as const;
+export type InvitationStatus = (typeof INVITATION_STATUS)[keyof typeof INVITATION_STATUS];
+
+// Order MUSS bit-identisch zur DB-Migration sein. Object.values
+// bewahrt insertion-order (JS-spec-stable für string-keys). Wenn
+// jemand INVITATION_STATUS reordnet, generiert drizzle-kit eine
+// neue Migration. Hardcoded-Tuple zur Sicherheit gegen versehentliches
+// Refactoring der Object-Keys.
+export const INVITATION_STATUSES = [
+  INVITATION_STATUS.pending,
+  INVITATION_STATUS.accepted,
+  INVITATION_STATUS.cancelled,
+  INVITATION_STATUS.expired,
+] as const;
+
+export const tenantInvitationEntity = createEntity({
+  table: "read_tenant_invitations",
+  fields: {
+    // Eingeladene Email — case-insensitive normalisiert beim Insert.
+    email: createTextField({ required: true, maxLength: 320 }),
+    // Membership-Rolle die dem User nach Accept gegeben wird. Default
+    // im handler ist "Admin" (Co-Admin-Pattern für kleine Teams).
+    role: createTextField({ required: true, maxLength: 50 }),
+    // Lifecycle-State. Default "pending"; transitions:
+    //   pending → accepted | cancelled | expired
+    status: createSelectField({
+      options: INVITATION_STATUSES,
+      required: true,
+      default: "pending",
+    }),
+    // userId des einladenden Admins (für Audit-Trail "wer hat eingeladen").
+    invitedBy: createTextField({ required: true }),
+    // UI-Anzeige — Wahrheit liegt in Redis-TTL.
+    expiresAt: createTimestampField({ required: true }),
+  },
+  // Eine Invitation-Row pro (tenantId, email). Bei Re-Invite (Admin
+  // invitet zweite Mal nach Cancel/Accept) wird die existing row
+  // updated: status pending → cancelled → pending zurück, expiresAt
+  // refreshed. Verhindert Token-Doppel-Gabe + macht Resend-Idempotenz
+  // im handler trivial.
+  indexes: [
+    {
+      unique: true,
+      columns: ["tenantId", "email"],
+      name: "read_tenant_invitations_tenant_email_unique",
+    },
+  ],
+});
+
+export const tenantInvitationsTable = buildDrizzleTable(
+  "tenant-invitation",
+  tenantInvitationEntity,
+);

package/src/tenant/membership-table.ts

@@ -0,0 +1,35 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+// Membership is event-sourced. Each (userId, tenantId) pair is its own
+// aggregate stream — lifecycle events `tenantMembership.created /
+// .updated / .deleted` flow through createEventStoreExecutor, which writes
+// the stream + this projection in one TX. Queries read straight from the
+// projection.
+//
+// UUID PK is mandatory for the event-store (aggregateId is uuid). The
+// unique index on (userId, tenantId) stays — it was the effective PK under
+// the old serial-id design and keeps duplicate-write protection at the
+// database level independent of the handler lookup.
+//
+// Single-Source-of-Truth: `tenantMembershipEntity`. Die DB-Tabelle wird
+// aus der EntityDefinition über buildDrizzleTable abgeleitet, der
+// unique-Index ist via entity.indexes deklariert.
+export const tenantMembershipEntity = createEntity({
+  table: "read_tenant_memberships",
+  fields: {
+    userId: createTextField({ required: true }),
+    // JSON-encoded string[] — parseRoles() deserializes at read time.
+    // Mirrors how roles were stored under the pre-ES row model so the
+    // read-side stays byte-compatible and no MSP/consumer needs rewrites.
+    roles: createTextField({ required: true }),
+  },
+  indexes: [
+    { unique: true, columns: ["userId", "tenantId"], name: "read_tenant_memberships_unique" },
+  ],
+});
+
+export const tenantMembershipsTable = buildDrizzleTable(
+  "tenant-membership",
+  tenantMembershipEntity,
+);

package/src/tenant/schema/index.ts

@@ -0,0 +1,5 @@
+// Re-exports aus den schema/<entity>.ts Files. Eine Datei pro Entity
+// — wenn das Feature später weitere Entities hinzubekommt, kommen sie
+// als zusätzliche Datei rein und werden hier exportiert.
+
+export * from "./tenant";

package/src/tenant/schema/tenant.ts

@@ -0,0 +1,27 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const tenantEntity = createEntity({
+  table: "read_tenants",
+  // tenant.id IS the tenantId-value that every other table references as FK.
+  // Alle tenantId-Spalten sind UUID (Migration 2026-04-16) → tenant.id muss
+  // UUID sein, sonst findet der tenants-Lookup nie. Default gen_random_uuid().
+  fields: {
+    key: createTextField({ required: true, maxLength: 50 }),
+    name: createTextField({ required: true, maxLength: 200, searchable: true }),
+    isEnabled: createBooleanField({ default: true }),
+  },
+  // tenant.key wird in Admin-URLs verwendet (`admin.<host>/<key>/...`) und
+  // muss eindeutig sein. Ohne unique-constraint hätte ein konkurrenter
+  // Self-Signup-Confirm einen TOCTOU-Race zwischen generateUniqueName-
+  // isAvailable-check und insert: zwei Tabs könnten sequentiell denselben
+  // Slug claimen, beide commits durch, der dritte User landet auf einem
+  // shared admin-URL-prefix.
+  indexes: [{ unique: true, columns: ["key"] }],
+});
+
+export const tenantTable = buildDrizzleTable("tenant", tenantEntity);

package/src/tenant/seeding.ts

@@ -0,0 +1,155 @@
+// Testing helpers for the tenant feature. `seedTenantMembership` replaces
+// the pre-ES pattern of `db.insert(tenantMembershipsTable).values({...})`
+// in test fixtures — a direct-write bypasses the event-store executor, so
+// seeded memberships have no stream, no `.created` event, and projections
+// that consume membership events stay empty.
+//
+// The helper runs through the executor (same TX-semantics as the
+// add-member handler), which means fixtures are event-sourced end-to-end:
+//   - events table gets a `tenantMembership.created` row
+//   - projection row (tenant_memberships) is written in the same TX
+//   - consumers (MSPs, audit) see the event just like a real call would
+//
+// Why this lives in bundled-features/tenant/testing rather than
+// framework/testing: the helper closes over `tenantMembershipEntity` +
+// `tenantMembershipsTable`, both owned by this feature. framework/testing
+// stays shape-independent.
+//
+// Why not "just call the addMember handler via stack.http.writeOk":
+//   1. Handler requires SystemAdmin — test fixtures often seed OTHER users
+//      before any admin exists, so the handler would 403.
+//   2. Handler goes through HTTP → JWT mint → dispatcher. Overhead for
+//      fixture state-setup that the test doesn't exercise.
+// The executor path skips access-checks by design (no HTTP, no JWT — this
+// IS a test fixture, not a user request) while still producing the
+// correct event + projection.
+//
+// Idempotent: calling twice for the same (userId, tenantId) is a no-op on
+// the second call. Test fixtures that seed the same membership across
+// `beforeEach` runs don't need explicit cleanup. A real `addMember` handler
+// returns ConflictError on duplicates — that's the user-facing contract.
+// Fixture-seeding prioritises "make the state exist" over "detect duplicate
+// seeding", which is usually a test-author bug we don't need to surface.
+
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  fetchOne,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { eq } from "drizzle-orm";
+import { tenantMembershipEntity, tenantMembershipsTable } from "./membership-table";
+import { tenantEntity, tenantTable } from "./schema/tenant";
+
+const tenantExecutor = createEventStoreExecutor(tenantTable, tenantEntity, {
+  entityName: "tenant",
+});
+
+const executor = createEventStoreExecutor(tenantMembershipsTable, tenantMembershipEntity, {
+  entityName: "tenant-membership",
+});
+
+export type SeedTenantMembershipOptions = {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+  readonly roles: readonly string[];
+  /**
+   * SessionUser to bill the event against (goes into event.metadata.userId +
+   * the projection's inserted_by_id column). Defaults to TestUsers.systemAdmin
+   * — mirrors the real call-path, where add-member is SystemAdmin-only.
+   */
+  readonly by?: SessionUser;
+};
+
+export type SeedTenantOptions = {
+  /** Stable UUID — required for fixtures so the FE/BE können dieselbe ID
+   *  hardcoden (Sample-Switcher zeigt den Tenant beim Namen, der Test
+   *  prüft Memberships gegen exakt diese ID). Ohne ID müsste der Caller
+   *  den lookup-by-key extra machen. */
+  readonly id: TenantId;
+  /** URL-/Slug-Form (z.B. "dev", "acme"). Indexed unique in der DB. */
+  readonly key: string;
+  /** Human-readable label (im Switcher angezeigt). */
+  readonly name: string;
+  readonly by?: SessionUser;
+};
+
+/**
+ * Seed a tenant through the event-store executor. Idempotent: a second
+ * call for the same `id` is a no-op. Same TX-semantics as the real
+ * `TenantHandlers.create`, minus the SystemAdmin-access-check and minus
+ * ConflictError-on-duplicate.
+ */
+export async function seedTenant(db: DbConnection, options: SeedTenantOptions): Promise<TenantId> {
+  const by = options.by ?? TestUsers.systemAdmin;
+  // executor.create erwartet eine TenantDb (mit .insert()-API), nicht
+  // die rohe DbConnection. Auch wenn das Tenant-Aggregat selbst NICHT
+  // tenant-scoped ist, braucht der Wrap-Layer für die runtime-API zu
+  // existieren. by.tenantId reicht — keine Override-Semantik wie bei
+  // seedTenantMembership nötig.
+  const tdb = createTenantDb(db, by.tenantId, "system");
+
+  const existing = await fetchOne(db, tenantTable, eq(tenantTable["id"], options.id));
+  if (existing) return options.id;
+
+  const result = await tenantExecutor.create(
+    { id: options.id, key: options.key, name: options.name },
+    by,
+    tdb,
+  );
+  if (!result.isSuccess) {
+    throw new Error(
+      `seedTenant failed: ${result.error.code} — ${JSON.stringify(result.error.details ?? {})}`,
+    );
+  }
+  return options.id;
+}
+
+/**
+ * Seed a tenant membership through the event-store executor. Writes
+ * both a `tenantMembership.created` event and the corresponding
+ * projection row in one transaction — identical effect to
+ * `TenantHandlers.addMember`, minus the access-check and minus the
+ * ConflictError on duplicates (duplicate calls no-op).
+ */
+export async function seedTenantMembership(
+  db: DbConnection,
+  options: SeedTenantMembershipOptions,
+): Promise<void> {
+  const by = options.by ?? TestUsers.systemAdmin;
+  // Wrap into a system-scoped TenantDb so the insert respects the tenant-
+  // override (we write into options.tenantId, which may differ from by.tenantId).
+  const tdb = createTenantDb(db, by.tenantId, "system");
+
+  // Idempotency: duplicate seeds are common across beforeEach-resets where
+  // only certain tables get truncated. A plain executor.create would trip
+  // the (user_id, tenant_id) unique index; the fixture call-site would then
+  // have to juggle try/catch. Lookup-first keeps call-sites clean.
+  const existing = await fetchOne(
+    db,
+    tenantMembershipsTable,
+    eq(tenantMembershipsTable.userId, options.userId),
+    eq(tenantMembershipsTable.tenantId, options.tenantId),
+  );
+  // skip: idempotent no-op — duplicate seed is expected across beforeEach-
+  // resets that don't truncate this table. Cheaper than try/catch on the
+  // unique-index, and documented in the function JSDoc above.
+  if (existing) return;
+
+  const result = await executor.create(
+    {
+      userId: options.userId,
+      tenantId: options.tenantId,
+      roles: JSON.stringify(options.roles),
+    },
+    by,
+    tdb,
+  );
+  if (!result.isSuccess) {
+    throw new Error(
+      `seedTenantMembership failed: ${result.error.code} — ${JSON.stringify(result.error.details ?? {})}`,
+    );
+  }
+}

package/src/tenant/testing.ts

@@ -0,0 +1,8 @@
+// /testing re-exportiert /seeding. Ehemalige Heimat der seed-Helpers,
+// jetzt nur noch Aggregation. Die Helpers leben in `/seeding` weil sie
+// genauso vom Dev-Server-Bootstrap (runDevApp) konsumiert werden — nicht
+// nur von Tests. Vertrag der Helpers ist stabil, test-spezifische
+// Knöpfe gehören NICHT hier rein (würde dev-boots brechen wenn jemand
+// einen lockout-test-Knopf einbaut).
+
+export * from "./seeding";