@cosmicdrift/kumiko-framework 0.6.0 → 0.8.0

package/src/env/index.ts

@@ -0,0 +1,349 @@
+// Env-Schema composition for Kumiko apps.
+//
+// Each feature declares its required env-vars via `r.envSchema(z.object({...}))`.
+// `composeEnvSchema({ features, extend })` merges those into one app-wide
+// Zod-object that `runProdApp` validates `process.env` against at boot.
+//
+// On invalid/missing vars `parseEnv` throws `KumikoBootError` with ALL
+// problems aggregated (Zod's safeParse traverses every field before
+// short-circuiting). `runProdApp` catches at its top level and renders
+// via `KumikoBootError.format()` — so apps don't repeat the try/catch.
+//
+// Per-var metadata for deploy-time tooling (Pulumi-config-key override,
+// generator command, k8s hints) lives in Zod's `.meta({ kumiko: {...} })`.
+// Without meta, defaults: `camelCase(envVarName)` for the Pulumi key,
+// `<set-me>` placeholder for the value, no `--secret` flag.
+
+import { z } from "zod";
+import type { FeatureDefinition } from "../engine/types/feature";
+import { zodDef, zodDescription, zodMeta, zodShape, zodShapeField } from "./_zod-introspect";
+
+// --- Per-env-var metadata (attach via Zod's `.meta()`) ---
+
+export type KumikoEnvMeta = {
+  readonly pulumi?: {
+    /** Override the auto-derived camelCase Pulumi-config-key name. Apps
+     *  setting `pulumiPrefix: "studio"` and authoring `STUDIO_ADMIN_EMAIL`
+     *  would otherwise get `studioStudioAdminEmail` — set
+     *  `.meta({ kumiko: { pulumi: { name: "adminEmail" } } })` to drop the
+     *  duplicated prefix. */
+    readonly name?: string;
+    /** Shell expression that generates a value, e.g. `openssl rand -base64 32`.
+     *  Without this, dry-run-pulumi emits `<set-me>` as the placeholder. */
+    readonly generator?: string;
+    /** Force the `--secret` flag in `pulumi config set`. Default false. */
+    readonly secret?: boolean;
+  };
+};
+
+function isKumikoMeta(value: unknown): value is KumikoEnvMeta {
+  if (value === null || typeof value !== "object") return false;
+  // @cast-boundary schema-walk — runtime-shape narrowing of zod-meta payload
+  const v = value as { pulumi?: unknown };
+  if (v.pulumi === undefined) return true;
+  if (v.pulumi === null || typeof v.pulumi !== "object") return false;
+  // @cast-boundary schema-walk
+  const p = v.pulumi as { name?: unknown; generator?: unknown; secret?: unknown };
+  if (p.name !== undefined && typeof p.name !== "string") return false;
+  if (p.generator !== undefined && typeof p.generator !== "string") return false;
+  if (p.secret !== undefined && typeof p.secret !== "boolean") return false;
+  return true;
+}
+
+export function readKumikoMeta(field: z.ZodType): KumikoEnvMeta {
+  const meta = zodMeta(field);
+  if (meta && typeof meta === "object" && meta !== null && "kumiko" in meta) {
+    // @cast-boundary schema-walk
+    const k = (meta as { kumiko?: unknown }).kumiko;
+    if (isKumikoMeta(k)) return k;
+  }
+  return {};
+}
+
+// --- Field-classification helpers (Zod v4 introspection) ---
+
+export type EnvFieldClass = "required" | "optional" | "withDefault";
+
+export function classifyField(field: z.ZodType): EnvFieldClass {
+  // Drill through ZodEffects/ZodPipe wrappers to find the inner kind.
+  let current: z.ZodType = field;
+  for (let i = 0; i < 8; i++) {
+    if (current instanceof z.ZodDefault) return "withDefault";
+    if (current instanceof z.ZodOptional || current instanceof z.ZodNullable) {
+      return "optional";
+    }
+    const inner = zodDef(current);
+    if (inner?.innerType) {
+      current = inner.innerType;
+      continue;
+    }
+    if (inner?.in) {
+      current = inner.in;
+      continue;
+    }
+    break;
+  }
+  return "required";
+}
+
+export function getDefaultValue(field: z.ZodType): unknown {
+  let current: z.ZodType = field;
+  for (let i = 0; i < 8; i++) {
+    if (current instanceof z.ZodDefault) {
+      // Zod v4: defaultValue is the raw value (v3 was a factory function).
+      // Support both shapes for forward/backward safety.
+      const raw = zodDef(current)?.defaultValue;
+      // @cast-boundary schema-walk — Zod v3 stored a thunk, v4 a raw value
+      return typeof raw === "function" ? (raw as () => unknown)() : raw;
+    }
+    const inner = zodDef(current);
+    if (inner?.innerType) {
+      current = inner.innerType;
+      continue;
+    }
+    break;
+  }
+  return undefined;
+}
+
+export function getFieldDescription(field: z.ZodType): string | undefined {
+  return zodDescription(field);
+}
+
+// --- Compose ---
+
+export type ComposeEnvSchemaOptions = {
+  /** All features whose envSchemas should be merged. */
+  readonly features: readonly FeatureDefinition[];
+  /** App-specific env-vars (e.g. `STUDIO_ADMIN_EMAIL`). Keys here are
+   *  tagged as source "app" in the resulting sources map. */
+  readonly extend?: z.ZodObject<z.ZodRawShape>;
+  /** Feature-names whose env-vars should be auto-`.optional()`-wrapped.
+   *  Lets an app opt out of e.g. `channel-email-smtp`'s vars without
+   *  manually `.partial()`-ing each shape at the call-site. */
+  readonly optionalFeatures?: readonly string[];
+  /** Framework-core env-vars (PORT, DATABASE_URL, REDIS_URL, …) from
+   *  `@cosmicdrift/kumiko-dev-server`. Keys here are tagged as source
+   *  "framework-core" in error output. Conflict-detection runs across
+   *  core/features/extend as one merged pool — same key declared in two
+   *  layers throws KumikoBootError at compose-time. */
+  readonly core?: z.ZodObject<z.ZodRawShape>;
+};
+
+export type ComposedEnvSchema = {
+  /** The merged Zod schema. Type-erased to `ZodObject<ZodRawShape>` — TS
+   *  can't variadic-merge N generic feature schemas without tuple gymnastics
+   *  that hurt readability. For type-safe `z.infer` in app code, build a
+   *  parallel typed schema manually (see Plan-Doc
+   *  `kumiko-studio/docs/plans/sprint-9-env-schemas.md` → API-Design)
+   *  and only pass `composed.schema` to `runProdApp` for validation. */
+  readonly schema: z.ZodObject<z.ZodRawShape>;
+  /** env-var-name → declaring source-name: feature-name from `r.envSchema()`,
+   *  "app" from `extend`, or "framework-core" from `core`. */
+  readonly sources: Readonly<Record<string, string>>;
+};
+
+export function composeEnvSchema(options: ComposeEnvSchemaOptions): ComposedEnvSchema {
+  const optionalSet = new Set(options.optionalFeatures ?? []);
+  const merged: Record<string, z.ZodType> = {};
+  const sources: Record<string, string> = {};
+
+  // Framework-core first so a feature that accidentally declares the same
+  // var (e.g. PORT) gets a clear conflict error citing "framework-core"
+  // rather than silently overwriting a deploy-critical default. The
+  // conflict-detection makes the order safe in both directions — both
+  // throw — but downstream tools that consume `sources` (e.g. the
+  // upcoming Phase-5 lint-guard) may rely on this insertion order.
+  if (options.core) {
+    for (const [key, field] of Object.entries(zodShape(options.core))) {
+      merged[key] = field;
+      sources[key] = "framework-core";
+    }
+  }
+
+  for (const feature of options.features) {
+    if (!feature.envSchema) continue;
+    const shape = zodShape(feature.envSchema);
+    const wrap = optionalSet.has(feature.name);
+    for (const [key, field] of Object.entries(shape)) {
+      if (merged[key] !== undefined) {
+        throw new KumikoBootError([
+          {
+            name: key,
+            kind: "invalid",
+            message:
+              `env-var conflict: "${key}" declared by both ` +
+              `"${sources[key]}" and "${feature.name}" — pick one owner.`,
+          },
+        ]);
+      }
+      merged[key] = wrap ? field.optional() : field;
+      sources[key] = feature.name;
+    }
+  }
+
+  if (options.extend) {
+    for (const [key, field] of Object.entries(zodShape(options.extend))) {
+      if (merged[key] !== undefined) {
+        throw new KumikoBootError([
+          {
+            name: key,
+            kind: "invalid",
+            message:
+              `env-var conflict: "${key}" declared by both "${sources[key]}" ` +
+              `and the app's extend block — rename one.`,
+          },
+        ]);
+      }
+      merged[key] = field;
+      sources[key] = "app";
+    }
+  }
+
+  return {
+    schema: z.object(merged),
+    sources,
+  };
+}
+
+// --- Errors ---
+
+export type EnvErrorKind = "missing" | "invalid";
+
+export type EnvError = {
+  readonly name: string;
+  readonly kind: EnvErrorKind;
+  readonly message: string;
+  /** Declaring source-name from `composeEnvSchema`'s sources map:
+   *  feature-name, "app" from `extend`, or "framework-core" from `core`.
+   *  Populated when parseEnv received `options.sources`. Surfaced by
+   *  `KumikoBootError.format()` so operators see WHICH source wants the
+   *  missing var, not just the var name. */
+  readonly source?: string;
+  /** "Set via: pulumi config set ..." line. Computed when pulumiPrefix is
+   *  passed to parseEnv. */
+  readonly suggestion?: string;
+};
+
+export class KumikoBootError extends Error {
+  readonly errors: readonly EnvError[];
+
+  constructor(errors: readonly EnvError[]) {
+    super(`Boot failed: ${errors.length} env-var problem${errors.length === 1 ? "" : "s"}`);
+    this.name = "KumikoBootError";
+    this.errors = errors;
+  }
+
+  format(): string {
+    const lines: string[] = [
+      `Boot failed: ${this.errors.length} env-var problem${this.errors.length === 1 ? "" : "s"}`,
+      "",
+    ];
+    for (const err of this.errors) {
+      const tag = err.kind === "missing" ? "required, missing" : "invalid";
+      const sourceTag = err.source ? `${err.source}, ${tag}` : tag;
+      lines.push(`  ✗ ${err.name} (${sourceTag})`);
+      lines.push(`    ${err.message}`);
+      if (err.suggestion) {
+        lines.push(`    ${err.suggestion}`);
+      }
+    }
+    lines.push("");
+    lines.push(
+      "See: kumiko-platform/docs/runbooks/standard-deploy-app.md#step-1-boot-dry-run-lokal",
+    );
+    return lines.join("\n");
+  }
+}
+
+// --- Parse ---
+
+export type ParseEnvOptions = {
+  /** From composeEnvSchema's return — enables per-var feature-source
+   *  attribution in suggestions. */
+  readonly sources?: Readonly<Record<string, string>>;
+  /** When set, error suggestions include `pulumi config set <prefix>...`. */
+  readonly pulumiPrefix?: string;
+};
+
+export function parseEnv<S extends z.ZodObject<z.ZodRawShape>>(
+  schema: S,
+  env: Record<string, string | undefined>,
+  options: ParseEnvOptions = {},
+): z.infer<S> {
+  // Filter undefined values to keep Zod's required-vs-invalid signal clean.
+  // (process.env returns string|undefined; passing undefined would parse
+  // as "field is set to undefined" which clouds the missing-key heuristic.)
+  const cleaned: Record<string, string> = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (v !== undefined) cleaned[k] = v;
+  }
+
+  const result = schema.safeParse(cleaned);
+  if (result.success) {
+    // @cast-boundary schema-walk — z.infer<S> erasure across safeParse result
+    return result.data as z.infer<S>;
+  }
+
+  // Map Zod-issues → EnvError[], augmenting with suggestions when meta+prefix.
+  const errors: EnvError[] = result.error.issues.map((issue) => {
+    const name = String(issue.path[0] ?? "<unknown>");
+    const field = zodShapeField(schema, name);
+    // Zod v4 dropped the `received` property on invalid_type issues; the
+    // canonical signal for "value was missing" is now "the key isn't in
+    // the input object". Use input-presence as the missing/invalid switch.
+    const isMissing = issue.code === "invalid_type" && !(name in cleaned);
+    const kind: EnvErrorKind = isMissing ? "missing" : "invalid";
+    const desc = field ? getFieldDescription(field) : undefined;
+    const message = desc ? `${issue.message} — ${desc}` : issue.message;
+    const suggestion = field ? buildPulumiSuggestion(name, field, options.pulumiPrefix) : undefined;
+    const source = options.sources?.[name];
+    return {
+      name,
+      kind,
+      message,
+      ...(source ? { source } : {}),
+      ...(suggestion ? { suggestion } : {}),
+    };
+  });
+
+  throw new KumikoBootError(errors);
+}
+
+// --- Pulumi-suggestion ---
+
+function ucfirst(s: string): string {
+  return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export function camelCase(snakeShout: string): string {
+  const parts = snakeShout.toLowerCase().split("_").filter(Boolean);
+  if (parts.length === 0) return snakeShout.toLowerCase();
+  return parts[0] + parts.slice(1).map(ucfirst).join("");
+}
+
+export function pulumiConfigKey(
+  envName: string,
+  field: z.ZodType | undefined,
+  prefix: string | undefined,
+): string {
+  const meta = field ? readKumikoMeta(field) : {};
+  if (meta.pulumi?.name) {
+    return prefix ? prefix + ucfirst(meta.pulumi.name) : meta.pulumi.name;
+  }
+  const camel = camelCase(envName);
+  return prefix ? prefix + ucfirst(camel) : camel;
+}
+
+export function buildPulumiSuggestion(
+  envName: string,
+  field: z.ZodType,
+  prefix: string | undefined,
+): string | undefined {
+  if (!prefix) return undefined;
+  const meta = readKumikoMeta(field);
+  const key = pulumiConfigKey(envName, field, prefix);
+  const secretFlag = meta.pulumi?.secret ? " --secret" : "";
+  const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
+  return `Set via: pulumi config set${secretFlag} ${key} ${value}`;
+}

package/src/es-ops/README.md

@@ -32,7 +32,7 @@ export default {
       await ctx.systemWriteAs(
         "tenant:write:update-member-roles",
         { userId: admin.id, tenantId: m.tenantId, roles: [...m.roles, "TenantAdmin"] },
-        m.tenantId, // ← tenantIdOverride: Aggregate lebt im Tenant-Stream, NICHT SYSTEM
+        m.streamTenantId, // ← tenantIdOverride aus dem JOIN auf kumiko_events.v1
       );
     }
   },
@@ -47,9 +47,11 @@ Faustregel: **wenn das Ziel-Aggregate via Tenant-User erstellt wurde, brauchst D
 |---|---|---|
 | config-values (system-scope) | SYSTEM_TENANT | weglassen |
 | system text-content | SYSTEM_TENANT | weglassen |
-| tenant-membership | jeweiliger Tenant-Stream | ✅ `m.tenantId` |
+| tenant-membership | jeweiliger Stream-Tenant aus events.v1 | ✅ `m.streamTenantId` (NICHT `m.tenantId` — die beiden können divergieren!) |
 | App-Entity (orders, tasks, …) | Tenant-Stream | ✅ Tenant-Id aus dem Lookup |
 
+**Warum nicht `m.tenantId`?** read_tenant_memberships.tenant_id ist der payload-tenant (logisches Mitgliedschafts-Ziel), kumiko_events.tenant_id der v1-Row ist der stream-tenant (wo das Aggregate physisch lebt). seedTenantMembership mit `by=systemAdmin` lässt die zwei auseinanderlaufen — der Helper `findMembershipsOfUser` liefert beide getrennt, damit Seeds den richtigen wählen können.
+
 Ohne `tenantIdOverride` sucht der Executor den Stream gegen SYSTEM_TENANT → `version_conflict`. Memory: `feedback_event_store_tenant_consistency.md`.
 
 ## Deployment-Anforderungen

package/src/es-ops/__tests__/context.integration.ts

@@ -55,10 +55,34 @@ afterAll(async () => {
 
 beforeEach(async () => {
   await testDb.db.execute(sql`
-    TRUNCATE kumiko_es_operations, read_users, read_tenant_memberships, read_tenants
+    TRUNCATE kumiko_es_operations, kumiko_events, read_users, read_tenant_memberships, read_tenants
+    RESTART IDENTITY CASCADE
   `);
 });
 
+// Helper: simulate `seedTenantMembership` writing both the read-row and
+// its v1-event with a custom stream-tenant. Tests use this to construct
+// the stream-vs-payload-tenant scenarios that drive the JOIN-helper.
+async function insertMembershipWithEvent(args: {
+  readonly id: string;
+  readonly userId: string;
+  readonly payloadTenantId: string;
+  readonly streamTenantId: string;
+  readonly roles: string;
+}): Promise<void> {
+  await testDb.db.execute(sql`
+    INSERT INTO read_tenant_memberships (id, user_id, tenant_id, roles)
+    VALUES (${args.id}::uuid, ${args.userId}, ${args.payloadTenantId}::uuid, ${args.roles})
+  `);
+  await testDb.db.execute(sql`
+    INSERT INTO kumiko_events
+      (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
+    VALUES
+      (${args.id}::uuid, 'tenant-membership', ${args.streamTenantId}::uuid, 1,
+       'tenant-membership.created', '{}'::jsonb, '{"userId":"system"}'::jsonb, 'system')
+  `);
+}
+
 function makeMockDispatcher() {
   return {
     write: vi.fn(async () => ({ isSuccess: true as const, data: {} })),
@@ -107,13 +131,24 @@ describe("SeedMigrationContext.findUserByEmail (integration)", () => {
 describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
   test("parst JSON-encoded roles-Spalte zu string[]", async () => {
     const userId = "01900000-0000-7000-8000-000000000001";
+    const aggId1 = "00000000-0000-4000-8000-0000000000a1";
+    const aggId2 = "00000000-0000-4000-8000-0000000000a2";
     const tenantId1 = "00000000-0000-4000-8000-000000000001";
     const tenantId2 = "00000000-0000-4000-8000-000000000002";
-    await testDb.db.execute(sql`
-      INSERT INTO read_tenant_memberships (user_id, tenant_id, roles) VALUES
-        (${userId}, ${tenantId1}::uuid, '["Admin", "TenantAdmin"]'),
-        (${userId}, ${tenantId2}::uuid, '["User"]')
-    `);
+    await insertMembershipWithEvent({
+      id: aggId1,
+      userId,
+      payloadTenantId: tenantId1,
+      streamTenantId: tenantId1,
+      roles: '["Admin", "TenantAdmin"]',
+    });
+    await insertMembershipWithEvent({
+      id: aggId2,
+      userId,
+      payloadTenantId: tenantId2,
+      streamTenantId: tenantId2,
+      roles: '["User"]',
+    });
 
     const ctx = createSeedMigrationContext({
       dispatcher: makeMockDispatcher() as never,
@@ -129,14 +164,49 @@ describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
     expect(m2?.roles).toEqual(["User"]);
   });
 
+  test("stream-tenant != payload-tenant wird korrekt ausgewiesen (Driver-Bug)", async () => {
+    // Reproduziert den publicstatus-Driver-Fall: seedTenantMembership
+    // wurde mit by=systemAdmin aufgerufen → executor.tenantId=
+    // SYSTEM_TENANT_ID landet als events.tenant_id, während payload.
+    // tenantId der target-Tenant ist. Die beiden divergieren.
+    const userId = "01900000-0000-7000-8000-000000000001";
+    const aggId = "00000000-0000-4000-8000-0000000000b1";
+    const payloadTenant = "00000000-0000-4000-8000-000000000042";
+    const streamTenant = "00000000-0000-4000-8000-000000000001"; // SYSTEM_TENANT-Stil
+    await insertMembershipWithEvent({
+      id: aggId,
+      userId,
+      payloadTenantId: payloadTenant,
+      streamTenantId: streamTenant,
+      roles: '["Admin"]',
+    });
+
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const [m] = await ctx.findMembershipsOfUser(userId);
+    expect(m).toEqual({
+      userId,
+      tenantId: payloadTenant,
+      streamTenantId: streamTenant,
+      roles: ["Admin"],
+    });
+  });
+
   test("malformed roles-JSON → leeres Array (defensive, no throw)", async () => {
     // Defensive: wenn ein corrupted row kommt, soll der Seed nicht
     // explodieren — kann selbst entscheiden was zu tun ist.
     const userId = "01900000-0000-7000-8000-000000000002";
-    await testDb.db.execute(sql`
-      INSERT INTO read_tenant_memberships (user_id, tenant_id, roles) VALUES
-        (${userId}, '00000000-0000-4000-8000-000000000003'::uuid, 'not-json')
-    `);
+    const aggId = "00000000-0000-4000-8000-0000000000c1";
+    const tenantId = "00000000-0000-4000-8000-000000000003";
+    await insertMembershipWithEvent({
+      id: aggId,
+      userId,
+      payloadTenantId: tenantId,
+      streamTenantId: tenantId,
+      roles: "not-json",
+    });
     const ctx = createSeedMigrationContext({
       dispatcher: makeMockDispatcher() as never,
       dbRunner: testDb.db,
@@ -153,6 +223,26 @@ describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
     const memberships = await ctx.findMembershipsOfUser("01900000-0000-7000-8000-000000000099");
     expect(memberships).toEqual([]);
   });
+
+  test("membership ohne v1-Event wird vom INNER JOIN ausgefiltert (Drift-Detection)", async () => {
+    // Schutz vor Data-Drift: read-row ohne event-row ist kein legitimer
+    // Zustand für ein ES-Aggregate. Statt einer Half-Row zurückzugeben
+    // verschwindet die Row aus dem Result — Seed-Author sieht "0 memberships"
+    // statt einer mit fehlendem stream-tenant zu arbeiten und schwer
+    // diagnostizierbare version_conflict-Errors zu produzieren.
+    const userId = "01900000-0000-7000-8000-000000000003";
+    await testDb.db.execute(sql`
+      INSERT INTO read_tenant_memberships (id, user_id, tenant_id, roles) VALUES
+        ('00000000-0000-4000-8000-0000000000d1'::uuid, ${userId},
+         '00000000-0000-4000-8000-000000000005'::uuid, '["Admin"]')
+    `);
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const memberships = await ctx.findMembershipsOfUser(userId);
+    expect(memberships).toEqual([]);
+  });
 });
 
 describe("SeedMigrationContext.findTenants (integration)", () => {

package/src/es-ops/context.ts

@@ -76,17 +76,34 @@ export function createSeedMigrationContext(
     },
 
     findMembershipsOfUser: async (userId) => {
+      // INNER JOIN auf kumiko_events um den stream-tenant (events.tenant_id
+      // der v1-Row) neben dem payload-tenant (memberships.tenant_id) zu
+      // liefern. Die beiden divergieren wenn das Aggregate von einem
+      // Executor mit fremder tenantId angelegt wurde (seedTenantMembership
+      // by=systemAdmin) — typischer publicstatus-Driver-Use-Case.
+      // INNER (nicht LEFT): kein v1-Event bei vorhandener Read-Row wäre
+      // Data-Drift, kein legitimer Zustand für Seed-Migrations.
       // @cast-boundary db-row — roles ist JSON-string in der text-Spalte
       // (Memory: tenant-membership.created payload "[\"User\"]"), wird unten geparst
       const rows = (await args.dbRunner.execute(
-        sql`SELECT user_id::text AS user_id, tenant_id::text AS tenant_id, roles
-            FROM read_tenant_memberships
-            WHERE user_id = ${userId}`,
-      )) as unknown as readonly { user_id: string; tenant_id: string; roles: string }[];
+        sql`SELECT m.user_id::text AS user_id,
+                   m.tenant_id::text AS tenant_id,
+                   e.tenant_id::text AS stream_tenant_id,
+                   m.roles
+            FROM read_tenant_memberships m
+            JOIN kumiko_events e ON e.aggregate_id = m.id AND e.version = 1
+            WHERE m.user_id = ${userId}`,
+      )) as unknown as readonly {
+        user_id: string;
+        tenant_id: string;
+        stream_tenant_id: string;
+        roles: string;
+      }[];
       return rows.map(
         (r): SeedMembershipRow => ({
           userId: r.user_id,
           tenantId: r.tenant_id,
+          streamTenantId: r.stream_tenant_id,
           roles: safeParseRolesJson(r.roles),
         }),
       );

package/src/es-ops/types.ts

@@ -46,10 +46,23 @@ export type SeedUserRow = {
   readonly tenantId: string;
 };
 
-/** Read-shape eines Membership-Eintrags wie an Seed-Helpers exposed. */
+/** Read-shape eines Membership-Eintrags wie an Seed-Helpers exposed.
+ *  Unterscheidet zwei tenantIds: die "logische" aus dem Read-Projektion
+ *  (`tenantId`) und die "physische" aus dem Aggregate-Stream
+ *  (`streamTenantId`). Die beiden weichen voneinander ab wenn das
+ *  Aggregate von einem Executor mit anderer tenantId angelegt wurde
+ *  (z.B. seedTenantMembership-by=systemAdmin) — typischer
+ *  publicstatus-Driver-Use-Case. */
 export type SeedMembershipRow = {
   readonly userId: string;
+  /** Payload-tenant aus `read_tenant_memberships.tenant_id`. Geht ins
+   *  write-payload als `tenantId`. */
   readonly tenantId: string;
+  /** Stream-tenant aus `kumiko_events.tenant_id` der v1-Row. MUSS als
+   *  `tenantIdOverride` an `systemWriteAs` durchgereicht werden, sonst
+   *  sucht der Event-Store-Executor den Stream im falschen Tenant und
+   *  liefert `version_conflict`. */
+  readonly streamTenantId: string;
   readonly roles: readonly string[];
 };