@cosmicdrift/kumiko-framework 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @cosmicdrift/kumiko-framework
 
+## 0.7.0
+
+### Minor Changes
+
+- bcf43b6: es-ops: `SeedMembershipRow` exposes `streamTenantId` (stream-tenant aus `kumiko_events.v1`) neben dem payload-`tenantId`. Seed-Authors müssen den `kumiko_events`-JOIN nicht mehr selbst bauen — `m.streamTenantId` ist der korrekte Wert für `systemWriteAs`'s `tenantIdOverride` wenn das Aggregate von einem fremden Executor angelegt wurde (typisches `seedTenantMembership(by=systemAdmin)`-Pattern).
+
+## 0.6.0
+
+### Minor Changes
+
+- 8489d18: feat(es-ops): Phase 1.5 — tenantIdOverride + dry-run-validator + E2E-Test + Doku
+
+  Phase 1.5 schließt die Lücken aus Phase 1 die den ersten Driver-Use-Case
+  (publicstatus admin-roles) blockten. Siehe Retro:
+  `kumiko-platform/docs/plans/features/es-ops-phase1-retro.md` (PR #9).
+
+  **A1 — tenantIdOverride:**
+  `SeedMigrationContext.systemWriteAs(qn, payload, tenantIdOverride?)`.
+  Default SYSTEM_TENANT_ID (unverändert für System-scope-Aggregates wie
+  config-values). Mit override: `createSystemUser(tenantIdOverride)` als
+  Executor, damit der Event-Store-Executor den Aggregate-Stream im
+  richtigen Tenant findet. Fix für die `version_conflict`-Klasse-Bug
+  (Memory `feedback_event_store_tenant_consistency.md`).
+
+  **A2 — dry-run-validator:**
+  Runner parsed seed-files vor `migration.run()` per regex
+  `systemWriteAs\(["']([^"']+)["']`, sammelt handler-QNs, validiert
+  gegen `registry.getWriteHandler(qn)`. Fail-fast mit klarer Message
+
+  - Datei + QN statt zur Runtime "handler not found". Catched camelCase-
+    typos (kebab-case-vs-camelCase Drift) + andere QN-Drift zur Boot-Zeit.
+    runProdApp reicht den richtigen Registry rein (`registry` neu in
+    RunPendingSeedMigrationsArgs).
+
+  **A3 — E2E-Test:**
+  `packages/bundled-features/src/__tests__/es-ops-e2e.integration.ts`
+  mit `setupTestStack`-Pattern: tenant+config Features echt geladen,
+  echtes Membership-Aggregate via TenantHandlers.addMember im Demo-Tenant,
+  seed-migration ruft update-member-roles mit tenantIdOverride → write
+  geht durch, Marker landed, Event in Store, Read-Model aktualisiert.
+  Plus typo-Test: seed mit camelCase fail-t Dry-Run mit
+  `/dry-run found.*unknown handler-QN/`. **TDD-First**: ohne A1+A2 wäre
+  der test rot.
+
+  **A4 — Doku:**
+  `framework/src/es-ops/README.md` erweitert um „Wann brauche ich
+  tenantIdOverride?" + „Deployment-Anforderungen" (Docker COPY, Idempotenz,
+  Multi-Replica) + „Lokaler Smoke vor Push". Recipe-README + seed-files
+  auf neue API aktualisiert.
+
+  **A5 — Smoke-Skript-Template:**
+  `samples/recipes/seed-migration/scripts/smoke.ts` als copy-paste-Template
+  für App-Authors: Bun-runnable, offline (read-only, kein DB-Write),
+  validiert Module-Load + QN-Resolution + System-User-Access. Recipe-
+  README dokumentiert Pflicht-Pattern.
+
+  **Bonus-Fix:**
+  `tenant:write:create`-access auf `["system", "SystemAdmin"]` erweitert
+  (symmetrisch zu update-member-roles). Aufgedeckt durch Recipe-Smoke +
+  initial-tenants-Seed. Pinning-Test in `tenant.integration.ts` updated.
+
+  **Test-State:** 45/45 grün (Pre-Push). Typecheck clean. Biome clean.
+  as-cast-Audit clean. Guard-silent-skip clean. Recipe-Smoke clean.
+
+  **Folge-Step (separater PR):** publicstatus driver-sample reaktivieren
+  mit lokalem Pre-Push-Smoke gegen publicstatus' echtes Feature-Set.
+
 ## 0.5.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "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>",
@@ -163,7 +163,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.5.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.7.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "drizzle-kit": "^0.31.10",

package/src/es-ops/README.md

@@ -1,6 +1,8 @@
 # es-ops
 
-ES-Operations für Kumiko-Apps. Phase 1 liefert `seed-migrations` als file-basiertes Diff-and-Apply für Aggregate-State-Updates, die idempotent-Seeder nicht erfassen können.
+ES-Operations für Kumiko-Apps. Phase 1+1.5 liefert `seed-migrations` als file-basiertes Diff-and-Apply für Aggregate-State-Updates, die idempotent-Seeder nicht erfassen können.
+
+> **Phase 1 vs 1.5:** Phase 1 hatte den Foundation-Code, Phase 1.5 hat den ersten realen Driver-Use-Case durch (publicstatus admin-roles) und brachte: `tenantIdOverride` für Tenant-scope-Aggregates, Dry-Run-Validator für Handler-QNs, Deploy-Doku, lokales Smoke-Pattern. Pflicht-Lesen: [Retro](../../../../kumiko-platform/docs/plans/features/es-ops-phase1-retro.md).
 
 ## Quick API
 
@@ -27,16 +29,74 @@ export default {
     if (!admin) return;
     for (const m of await ctx.findMembershipsOfUser(admin.id)) {
       if (m.roles.includes("TenantAdmin")) continue;
-      await ctx.systemWriteAs("tenant:write:updateMemberRoles", {
-        userId: admin.id,
-        tenantId: m.tenantId,
-        roles: [...m.roles, "TenantAdmin"],
-      });
+      await ctx.systemWriteAs(
+        "tenant:write:update-member-roles",
+        { userId: admin.id, tenantId: m.tenantId, roles: [...m.roles, "TenantAdmin"] },
+        m.streamTenantId, // ← tenantIdOverride aus dem JOIN auf kumiko_events.v1
+      );
     }
   },
 } satisfies SeedMigration;
 ```
 
+### Wann brauche ich `tenantIdOverride`?
+
+Faustregel: **wenn das Ziel-Aggregate via Tenant-User erstellt wurde, brauchst Du den Override.**
+
+| Aggregate-Typ | Stream-Tenant | `tenantIdOverride` |
+|---|---|---|
+| config-values (system-scope) | SYSTEM_TENANT | weglassen |
+| system text-content | SYSTEM_TENANT | weglassen |
+| 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
+
+Wichtig — wird gerne übersehen:
+
+### Docker / Bun-Bundle
+
+Seeds werden zur Runtime via `await import(absolutePath)` geladen. Bun's Bundler strippt dynamic-import-Targets → seeds/-Tree muss **als raw-TS-Tree** ins Image kopiert werden:
+
+```dockerfile
+# Nach dem dist-server/-COPY:
+COPY --from=build --chown=app:app /app/seeds ./seeds
+```
+
+Plus: in der `bun build` Stage NICHT mit `--minify` durch die seed-Files laufen (sie sind keine Eingabe — der Bundler bundlet `bin/main.ts`, nicht das seeds-Verzeichnis).
+
+### Idempotenz-Pflicht
+
+Seed-Body läuft **NICHT** atomic mit dem Marker (siehe „Was NICHT garantiert ist" unten). Wenn ein Seed mid-way thrown wirft, sind die schon committed Events drin, der Marker aber nicht → Retry beim nächsten Boot. **Seeds müssen idempotent sein.**
+
+Standard-Pattern:
+```ts
+const memberships = await ctx.findMembershipsOfUser(adminId);
+for (const m of memberships) {
+  if (m.roles.includes("TenantAdmin")) continue; // ← check-then-write
+  await ctx.systemWriteAs(...);
+}
+```
+
+Anti-Pattern (NICHT idempotent):
+```ts
+for (let i = 0; i < 5; i++) {
+  await ctx.systemWriteAs("create-something", { ... }); // ← Re-Run produziert Duplikate
+}
+```
+
+### Multi-Replica-Boot
+
+`pg_advisory_xact_lock` sequentialisiert parallele Pod-Boots. Lock-Key ist global (`0x65736f70` / „esop"), nicht migration-spezifisch → bei N pending Migrationen läuft N-mal sequentiell, nicht parallel. Für die typische seed-Migration-Workload ist das schnell genug; bei sehr langen Migrationen (>30s) auf einem Multi-Replica-Stack: erst manuell als CLI-Step laufen lassen (`bunx kumiko ops seed:apply`), dann Pod-Rollout.
+
+### Lokaler Smoke vor Push
+
+Pflicht-Pattern: bevor Du seeds in main pushst, einmal lokal gegen Dev-DB den Boot-Loop laufen lassen. Siehe `samples/recipes/seed-migration/scripts/smoke.ts` als copy-paste-Template.
+
 ## CLI
 
 ```bash

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

@@ -29,11 +29,20 @@ export type CreateSeedMigrationContextArgs = {
 export function createSeedMigrationContext(
   args: CreateSeedMigrationContextArgs,
 ): SeedMigrationContext {
-  const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+  // Default-Executor für System-scope-Aggregates (config-values, system
+  // text-content, etc.). Bei Tenant-scope-Aggregates muss der Caller
+  // explizit `tenantIdOverride` übergeben — siehe types.ts Doku.
+  const defaultSystemUser = createSystemUser(SYSTEM_TENANT_ID);
 
   return {
-    systemWriteAs: async (handlerQualifiedName, payload) => {
-      const result = await args.dispatcher.write(handlerQualifiedName, payload, systemUser);
+    systemWriteAs: async (handlerQualifiedName, payload, tenantIdOverride) => {
+      // tenantIdOverride: baut einen System-User mit der Stream-tenantId
+      // damit der Event-Store-Executor das Aggregate im richtigen Stream
+      // findet. Verhindert die version_conflict-Falle (siehe Memory
+      // feedback_event_store_tenant_consistency.md).
+      const executor =
+        tenantIdOverride !== undefined ? createSystemUser(tenantIdOverride) : defaultSystemUser;
+      const result = await args.dispatcher.write(handlerQualifiedName, payload, executor);
       // Critical: WriteResult{isSuccess: false} würde sonst silent durchlaufen
       // → Marker landet trotz failed-Write → Migration falsch als "applied"
       // markiert. Hier throw damit der Runner's outer-tx rollback macht und
@@ -67,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/runner.ts

@@ -20,10 +20,11 @@
 // überspringen ohne ihr Code touchen zu müssen. NICHT als
 // Standard-Workflow — wirklich Notfall.
 
-import { readdir } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { eq, sql } from "drizzle-orm";
 import type { DbConnection, DbRunner } from "../db";
+import type { Registry } from "../engine";
 import { esOperationsTable } from "./operations-schema";
 import type { EsOperationAppliedBy, SeedMigration, SeedMigrationContext } from "./types";
 
@@ -45,6 +46,14 @@ export type RunPendingSeedMigrationsArgs = {
   readonly createContext: (dbRunner: DbRunner) => SeedMigrationContext;
   /** Trace-marker: boot | cli | ci-pipeline. Landet in applied_by. */
   readonly appliedBy: EsOperationAppliedBy;
+  /** Optional registry für Dry-Run-Validation: parsed jeden seed-file und
+   *  checkt dass alle referenzierten handler-QNs in der Registry existieren
+   *  BEVOR die Migration läuft. Catched camelCase-typos + andere QN-Drift
+   *  zur Boot-Zeit statt mitten im write-cycle (Phase 1.5 / A2).
+   *
+   *  Wenn weggelassen → kein Dry-Run (backward-compat für tests die ohne
+   *  Registry arbeiten). runProdApp reicht den richtigen Registry rein. */
+  readonly registry?: Registry;
   /** Optional log-prefix override, default "[es-ops/seed-migration]". */
   readonly logger?: (line: string) => void;
 };
@@ -84,6 +93,31 @@ export async function runPendingSeedMigrations(
   const appliedIds: string[] = [];
   const skippedIds: string[] = [];
 
+  // Dry-Run-Pass (Phase 1.5 / A2): vor JEDER migration alle handler-QNs aus
+  // den seed-files parsen + gegen registry checken. Fail-fast vor erstem
+  // write — gibt klare error-message mit Datei + qn statt zur runtime
+  // "handler not found" mitten im migration-flow.
+  if (args.registry !== undefined) {
+    const unknownQns: Array<{ id: string; qn: string }> = [];
+    for (const entry of pending) {
+      const source = await readFile(entry.filePath, "utf-8");
+      for (const qn of extractWriteHandlerQns(source)) {
+        if (!args.registry.getWriteHandler(qn)) {
+          unknownQns.push({ id: entry.id, qn });
+        }
+      }
+    }
+    if (unknownQns.length > 0) {
+      const lines = unknownQns.map((u) => `  - ${u.id}: "${u.qn}" not registered`);
+      throw new Error(
+        `[es-ops/seed-migration] dry-run found ${unknownQns.length} unknown handler-QN(s):\n${lines.join(
+          "\n",
+        )}\n  Check spelling against your TenantHandlers/AuthHandlers constants (kebab-case after the colon).`,
+      );
+    }
+    log(`${LOG_PREFIX} dry-run ok — all referenced handler-QNs registered`);
+  }
+
   for (const entry of pending) {
     const migration = await loadSeedModule(entry.filePath);
 
@@ -203,6 +237,26 @@ function sanitizeForEnv(id: string): string {
   return id.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
 }
 
+// Parse seed-file source + extract handler-QNs aus `systemWriteAs(...)`-
+// Calls. Reine regex (kein AST) — fängt die häufigen Inline-String-Cases:
+//   ctx.systemWriteAs("foo:write:bar", payload)
+//   systemWriteAs("foo:write:bar", ...)  (destructured)
+//
+// Edge-Cases die NICHT geguckt werden:
+//   - QN aus Variable: `const qn = "..."; ctx.systemWriteAs(qn, ...)`
+//   - String-Concat / Template-Literals mit dynamic vars
+// Diese Pattern sind selten in real seed-migrations + bleibt als known-
+// limitation dokumentiert. Wer dynamic-QN braucht, weiß was er tut.
+function extractWriteHandlerQns(source: string): readonly string[] {
+  const pattern = /systemWriteAs\s*\(\s*["']([^"']+)["']/g;
+  const out = new Set<string>();
+  for (const match of source.matchAll(pattern)) {
+    const qn = match[1];
+    if (qn) out.add(qn);
+  }
+  return [...out];
+}
+
 function stringifyError(err: unknown): string {
   if (err instanceof Error) return `${err.name}: ${err.message}`;
   try {

package/src/es-ops/types.ts

@@ -13,7 +13,7 @@
 // (Source-of-Truth + Projection läuft automatisch).
 
 import type { DbRunner } from "../db";
-import type { WriteResult } from "../engine";
+import type { TenantId, WriteResult } from "../engine";
 
 export type EsOperationAppliedBy = "boot" | "cli" | "ci-pipeline";
 
@@ -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[];
 };
 
@@ -67,8 +80,27 @@ export type SeedMigrationContext = {
    *
    *  Typ-Signatur folgt existing ctx.writeAs (payload als unknown) — Type-
    *  Safety kommt über handler-spezifische Wrapper im Aufrufer ("ich weiß
-   *  was updateMemberRoles braucht"). Versucht NICHT Generic-Magic. */
-  readonly systemWriteAs: (handlerQualifiedName: string, payload: unknown) => Promise<WriteResult>;
+   *  was updateMemberRoles braucht"). Versucht NICHT Generic-Magic.
+   *
+   *  **tenantIdOverride (Phase 1.5):** wenn das Ziel-Aggregate in einem
+   *  spezifischen Tenant-Stream lebt (nicht SYSTEM_TENANT_ID, was Default
+   *  ist), MUSS der Caller die Stream-tenantId mitgeben — sonst sucht der
+   *  Event-Store-Executor den Aggregate-Stream gegen `SYSTEM_TENANT_ID`
+   *  und liefert `version_conflict` (siehe Memory
+   *  `feedback_event_store_tenant_consistency.md` + Driver-Use-Case
+   *  publicstatus-admin-roles in `project_es_ops_phase1_retro.md`).
+   *
+   *  Typische Pattern:
+   *    - System-scope-Aggregate (config-values, system text-content) →
+   *      tenantIdOverride weglassen (Default SYSTEM_TENANT_ID).
+   *    - Tenant-scope-Aggregate (memberships, tenant-config, app-data) →
+   *      `tenantIdOverride: m.tenantId` (oder den Stream-Tenant aus
+   *      einem find*-Helper). */
+  readonly systemWriteAs: (
+    handlerQualifiedName: string,
+    payload: unknown,
+    tenantIdOverride?: TenantId,
+  ) => Promise<WriteResult>;
 
   // Read-helpers für die häufigsten Lookups. Wachsen on-demand —
   // Phase 1 deckt den admin-roles-Driver-Use-Case ab; weitere Lookups