@cosmicdrift/kumiko-framework 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @cosmicdrift/kumiko-framework
 
+## 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.6.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.6.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,72 @@ 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.tenantId, // ← tenantIdOverride: Aggregate lebt im Tenant-Stream, NICHT SYSTEM
+      );
     }
   },
 } 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 Tenant-Stream | ✅ `m.tenantId` |
+| App-Entity (orders, tasks, …) | Tenant-Stream | ✅ Tenant-Id aus dem Lookup |
+
+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/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

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";
 
@@ -67,8 +67,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