@cosmicdrift/kumiko-samples 0.338.0

package/samples/recipes/search/README.md

@@ -0,0 +1,21 @@
+# Search
+
+Tenant-scoped full-text search (Meilisearch / in-memory adapter).
+
+## What it shows
+
+- `searchable` / `searchWeight` on fields
+- Handler reads via `ctx.searchAdapter`
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/search
+bun test
+```

package/samples/recipes/search/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-search",
+  "description": "Tenant-scoped Meilisearch. Because ILIKE is not search.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/search/src/feature.ts

@@ -0,0 +1,72 @@
+// Search Sample
+// Shows: searchable fields, searchWeight, search via InMemory SearchAdapter.
+// Each handler builds its executor inline so `ctx.searchAdapter` is read fresh
+// per call — tests swap the adapter between runs.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const productEntity = createEntity({
+  table: "read_sample_products",
+  fields: {
+    name: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      searchable: true,
+    }),
+    brand: createTextField({ personal: false, reason: "is_business_data", searchable: true }),
+    sku: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    category: createTextField({ personal: false, reason: "is_business_data" }),
+  },
+  searchWeight: 10,
+});
+
+const productTable = buildEntityTable("product", productEntity);
+
+export const productFeature = defineFeature("shop", (r) => {
+  r.entity("product", productEntity);
+
+  r.writeHandler(
+    "product:create",
+    z.object({
+      name: z.string().min(1),
+      brand: z.string().optional(),
+      sku: z.string().min(1),
+      category: z.string().optional(),
+    }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(productTable, productEntity, {
+        searchAdapter: ctx.searchAdapter,
+        entityName: "product",
+      });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.queryHandler(
+    "product:list",
+    z.object({
+      search: z.string().optional(),
+      limit: z.number().optional(),
+    }),
+    async (query, ctx) => {
+      const crud = createEventStoreExecutor(productTable, productEntity, {
+        searchAdapter: ctx.searchAdapter,
+        entityName: "product",
+      });
+      return crud.list(query.payload, query.user, ctx.db);
+    },
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in user may search and list products in this recipe; creating " +
+            "a product still requires the Admin role above",
+        },
+      },
+    },
+  );
+});

package/samples/recipes/secrets-demo/README.md

@@ -0,0 +1,21 @@
+# Secrets Demo
+
+Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation.
+
+## What it shows
+
+- `r.secret` + `ctx.secrets.get` (audited reads)
+- Charge-style handler that never returns the plaintext key
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/secrets-demo
+bun test
+```

package/samples/recipes/secrets-demo/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-secrets-demo",
+  "description": "Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/secrets-demo/src/feature.ts

@@ -0,0 +1,88 @@
+// A miniature "billing" feature that reads a Stripe API key from ctx.secrets
+// and simulates a charge. The point is to show how feature code uses the
+// plaintext secret without ever exposing it to clients — the charge endpoint
+// returns { chargeId } but never the apiKey.
+
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  defineFeature,
+  defineWriteHandler,
+  type FeatureDefinition,
+  type SecretKeyHandle,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+// Typed handle exported by the feature's setup. Bound to what r.secret
+// returns below — downstream code imports STRIPE_API_KEY.name for the
+// qualified string, but never has to retype "billing:secret:stripe-api-key".
+// Renaming the r.secret call updates every call-site through the import graph.
+export let STRIPE_API_KEY: SecretKeyHandle;
+
+const chargeWrite = defineWriteHandler({
+  name: "charge",
+  schema: z.object({
+    amount: z.number().positive(),
+    customerRef: z.string().min(1),
+  }),
+  access: { roles: ["TenantAdmin", "User"] },
+  handler: async (event, ctx) => {
+    const secrets = requireSecretsContext(ctx, "billing:write:charge");
+    // requireSecretsContext returned a wrapper that auto-fills the audit
+    // context (userId + "billing:write:charge") on every .get — the read
+    // lands in tenant_secret_reads without the handler having to remember.
+    const branded = await secrets.get(event.user.tenantId, STRIPE_API_KEY);
+    if (!branded) {
+      return failUnprocessable("stripe_key_missing", {
+        hint: `TenantAdmin must first set ${STRIPE_API_KEY} via /api/write/secrets:write:set`,
+      });
+    }
+    // reveal() is the explicit un-brand. Everything that comes out stays
+    // plaintext string — we're now responsible for not letting it escape
+    // into the response. Fingerprint is the deliberate, audited leak.
+    const apiKey = branded.reveal();
+
+    // Fake the external call — in real code this would be
+    //   stripe = new Stripe(apiKey)
+    //   await stripe.paymentIntents.create({...})
+    // The key is consumed in-memory only; the response to the client never
+    // mentions it.
+    const chargeId = `ch_${Date.now()}_${event.payload.customerRef}`;
+    const keyFingerprint = `${apiKey.slice(0, 5)}...${apiKey.slice(-4)}`;
+
+    return {
+      isSuccess: true,
+      data: {
+        chargeId,
+        amount: event.payload.amount,
+        // Include a harmless fingerprint so the test can assert the charge
+        // used the correct key without revealing the full plaintext.
+        keyFingerprint,
+      },
+    };
+  },
+});
+
+export function createBillingFeature(): FeatureDefinition {
+  return defineFeature("billing", (r) => {
+    // Typed declaration of the secret this feature needs. Admin UIs can
+    // list known secrets (label + hint) so tenant-admin doesn't have to
+    // guess the key name; rotation / audit work by qualified name. The
+    // handle's .name is the QN the registrar built for us.
+    STRIPE_API_KEY = r.secret("stripe.apiKey", {
+      label: { de: "Stripe API-Schlüssel", en: "Stripe API Key" },
+      hint: {
+        de: "Aus dem Stripe-Dashboard unter Developers → API Keys.",
+        en: "From the Stripe dashboard under Developers → API Keys.",
+      },
+      // Domain-aware redaction: Stripe keys have a documented prefix+last4
+      // shape, so show that instead of the generic first-3 policy.
+      redact: (plaintext) => {
+        if (plaintext.length < 10) return "•".repeat(plaintext.length);
+        return `${plaintext.slice(0, 7)}...${plaintext.slice(-4)}`;
+      },
+      scope: "tenant",
+    });
+    r.writeHandler(chargeWrite);
+  });
+}

package/samples/recipes/security-baseline/README.md

@@ -0,0 +1,81 @@
+# Security baseline
+
+Mount `securityBaselineFeatures()` instead of hand-picking the four features
+every prod app needs for basic account/security hygiene: `sessions`
+(revocable JWTs), `crypto-shredding` (operator-triggered subject-key erase),
+`rate-limiting` (ops-side bucket-status query, dispatcher wiring is
+automatic), and `audit` (tenant-scoped audit trail). Forgetting one of them
+used to be silent; now the boot validator warns at `NODE_ENV=production`.
+
+## What it shows
+
+- **`securityBaselineFeatures()`** (`@cosmicdrift/kumiko-bundled-features/presets`) —
+  returns the four features in one call, fresh instances per call.
+- **`warnOnMissingSecurityBaseline`** — wired into `validateBoot` (fw#2857).
+  At `NODE_ENV=production`, boot compares mounted feature names against
+  `SECURITY_BASELINE_FEATURE_NAMES` and logs a `console.warn` naming whatever
+  is missing. It never throws — the baseline is a strong recommendation, not
+  a hard requirement — and it is silent outside production.
+- **`includeSessions: false`** — an optional opt-out for dropping `sessions`
+  from the preset explicitly. Not required for combining with
+  `dsgvoSelfServiceFeatures()` any more: both mount `createSessionsFeature()`
+  with no-arg options, and the framework's `dedupeFeatures()` collapses the
+  two identical instances at boot instead of throwing.
+
+## Feature composition
+
+```
+config            → tenant's r.requires("config") dependency
+user              → cross-tenant identity (sessions' r.requires target)
+tenant            → memberships (audit's r.requires target)
+auth-foundation   → tokenVerifier extension point (sessions' r.requires target)
+sessions          → revocable JWTs
+crypto-shredding  → operator-triggered subject-key erase
+rate-limiting     → ops-side rate-limit status query
+audit             → tenant-scoped audit trail
+```
+
+## When to reach for it
+
+Any app that also mounts `dsgvoSelfServiceFeatures()` — that preset already
+mounts `sessions` as part of its own require-chain. Combine both directly;
+`dedupeFeatures()` collapses the two identical `sessions` instances at boot:
+
+```ts illustration
+import { dsgvoSelfServiceFeatures, securityBaselineFeatures } from "@cosmicdrift/kumiko-bundled-features/presets";
+
+export const APP_FEATURES = [
+  // ...config, user, tenant, auth-foundation...
+  ...dsgvoSelfServiceFeatures(),
+  ...securityBaselineFeatures(),
+];
+```
+
+For an app that does not mount `dsgvoSelfServiceFeatures()`, use
+`securityBaselineFeatures()` with its default options, as this recipe does.
+
+A `createSessionsFeature({ ... })` mounted with different options than the
+preset's own no-arg instance still produces a clear boot error — dedupe only
+collapses provably interchangeable instances, never silently picks one:
+
+```ts illustration
+export const APP_FEATURES = [
+  // ...
+  createSessionsFeature({ expiresInMs: 1000 }),
+  ...securityBaselineFeatures(),
+  // throws: Duplicate feature: "sessions" mounted twice with different
+  // options — mount it once or pass identical options
+];
+```
+
+## Tests
+
+```bash
+bun test samples/recipes/security-baseline/src/__tests__/feature.test.ts
+```
+
+Three cases: `APP_FEATURES` boots clean; at `NODE_ENV=production` it produces
+no security-baseline warning; dropping `crypto-shredding`/`rate-limiting`/
+`audit` (`sessions` stays mounted — `auth-foundation`'s own bootCheck requires
+a sessionStore) at `NODE_ENV=production` produces exactly one warning and
+still does not throw.

package/samples/recipes/security-baseline/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-security-baseline",
+  "description": "securityBaselineFeatures() preset: sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/security-baseline/src/feature.ts

@@ -0,0 +1,19 @@
+// Security-Baseline Sample
+// Shows: mounting securityBaselineFeatures() (sessions, crypto-shredding,
+// rate-limiting, audit) and how it silences the NODE_ENV=production boot
+// warning that fires when one of those four is missing.
+
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { securityBaselineFeatures } from "@cosmicdrift/kumiko-bundled-features/presets";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+export const APP_FEATURES: FeatureDefinition[] = [
+  createConfigFeature(),
+  createUserFeature(),
+  createTenantFeature(),
+  authFoundationFeature,
+  ...securityBaselineFeatures(),
+];

package/samples/recipes/seed-migration/README.md

@@ -0,0 +1,81 @@
+# Seed-Migration
+
+File-based migrations for Event-Sourcing operations — like `kumiko schema apply`, but for aggregate-state-changes after the initial seed.
+
+## What it shows
+
+- **`seedsDir`-Option** in `runProdApp({ seedsDir: "./seeds" })` — beim Boot werden pending Files in chronologischer Reihenfolge angewendet und in `kumiko_es_operations` markiert.
+- **`SeedMigration`-Interface** — default-Export einer seed-File mit `description` + `run(ctx)`. ctx liefert `systemWriteAs` (System-User bypassed Access-Check) + Read-Helpers (`findUserByEmail`, `findMembershipsOfUser`, `findTenants`).
+- **Idempotency** — Marker landet nach Erfolg in der Tracking-Tabelle, zweiter Boot skipped applied Seeds.
+- **Tx-Atomicity** — Jede Migration läuft in eigener Transaction; Failure rollt zurück + bricht Boot ab (kein Partial-Apply).
+- **Chronologische File-IDs** — Filename `<date>-<slug>.ts` (z.B. `2026-05-20-fix-admin-roles.ts`) ist die ID.
+
+### Phase 1.5 hinzugefügt
+
+- **`tenantIdOverride`** in `ctx.systemWriteAs(qn, payload, tenantId)` — Pflicht wenn das Aggregate in einem Tenant-Stream lebt (sonst `version_conflict`).
+- **Dry-Run-Validator** — Runner parsed seed-files vor Run + checked alle handler-QNs gegen registry. camelCase-typos & andere QN-Drift werden BEFORE the write erkannt.
+- **`scripts/smoke.ts`** — copy-paste-Template für lokalen Pre-Push-Smoke. Bun-runnable, validiert Module-Load + QN-Resolution + Access offline. **Pflicht-Pattern vor Push.**
+- **Docker-COPY-Pflicht** dokumentiert in `framework/src/es-ops/README.md`.
+
+## Lokaler Smoke vor Push (Pflicht)
+
+```bash
+# Im App-Root:
+bun samples/recipes/seed-migration/scripts/smoke.ts --seeds-dir ./seeds
+```
+
+Erwarteter Output:
+```
+seed: 2026-05-20-fix-admin-roles.ts
+  ✓ loads: "ergänze TenantAdmin-Rolle"
+  ✓ "tenant:write:update-member-roles" registered + accessible
+
+✓ all 1 seed-file(s) pass smoke.
+```
+
+Bei typo / drift fail-t mit klarer message + exit-code 1 — CI nutzt es als prä-build-step. App-Author muss in `smoke.ts` den `features`-Array gegen die eigene App-Feature-Set tauschen (siehe TODO im File).
+
+## When to reach for it
+
+Du hast einen idempotent-Seeder der bei initialer Erstellung „Insert wenn nicht existiert" macht (z.B. `auth.admin.memberships`), und dann ändern sich die Soll-Daten — neue Rolle, anderer Tier, korrigierte Bezeichnung. Idempotent-Seeder skippen die existing Rows → DB driftet vom Code-Stand ab.
+
+Seed-Migrations sind der saubere Fix: ein File schreibt das gewünschte Update einmalig in den Event-Store, Projection läuft automatisch.
+
+## Don't reach for it when
+
+- **Initial Seeding** (erste Daten beim leeren Stack). Dafür gibt es `r.config({seeds})` + `options.seeds`-Array — idempotent-by-design durch deterministische Aggregate-IDs.
+- **Schema-Migrations**. Dafür gibt es `kumiko schema generate`. Seed-migrations sind
+  Data-Layer, nicht Schema-Layer.
+- **Read-only Operationen / Reports**. Dafür gibt es App-spezifische Routes / Queries.
+
+## How it works
+
+1. Bei `runProdApp`-Boot scannt das Framework `seedsDir` nach `*.ts`-Files.
+2. SELECT `id` FROM `kumiko_es_operations` WHERE `operation_type='seed-migration'` → applied-Set.
+3. Pending = files-on-disk **minus** applied-set, sortiert chronologisch.
+4. Pro pending: Tx auf, `migration.run(ctx)` (kann beliebige Handler via `systemWriteAs` rufen), Marker einfügen, Tx commit.
+5. Failure → Tx rollback, kein Marker, Boot bricht ab. Operator fixt + Retry.
+
+## CLI
+
+```bash
+# Scaffold neue Migration mit Datum-Prefix
+bunx kumiko ops seed:new fix-admin-roles
+# → seeds/2026-05-20-fix-admin-roles.ts
+
+# Was applied, was pending
+bunx kumiko ops seed:status
+
+# (Phase 1.5) Direct apply ohne Boot
+bunx kumiko ops seed:apply [--dry-run]
+```
+
+## Skippable im Notfall
+
+Wenn eine kaputte Migration den Boot blockiert: setze `skippable: true` im seed-File und beim nächsten Boot `KUMIKO_SKIP_ES_OPS_<sanitized-id>=1` env-var. Marker wird nicht geschrieben → beim nächsten Boot ohne Flag würde der Seed wieder laufen. NICHT als Standard-Workflow — Recovery-only.
+
+## See also
+
+- **Plan-Doc:** your deployment team's private operations documentation —
+  Phase-2+ Operations (projection-rebuild, event-replay, stream-migration, ...)
+- **Driver-Use-Case:** `seeds/2026-02-01-fix-admin-roles.ts` in this recipe

package/samples/recipes/seed-migration/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-seed-migration",
+  "description": "ES-Operations seed-migrations — file-based diff-and-apply für Aggregate-Updates die idempotent-Seeder nicht erfassen.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-dev-server": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/seed-migration/scripts/smoke.ts

@@ -0,0 +1,125 @@
+// biome-ignore-all lint/suspicious/noConsole: CLI tool output
+//
+// Lokaler Smoke-Test für seed-migrations.
+//
+// Was er prüft (offline, ohne Pod-Deploy):
+//   1. Alle seed-files in ./seeds/ können dynamic-import geladen werden
+//      → catched syntax-errors + missing default-exports + falsche paths
+//   2. Jeder handler-QN den die seeds referenzieren ist in der echten
+//      App-Registry registriert → catched camelCase-typos + drift
+//      (Bug-Klasse 3 aus Phase 1 retro)
+//   3. Jeder system-user (mit oder ohne tenantIdOverride) hat Access auf
+//      die referenzierten Handler → catched access-rule-Drift
+//      (Bug-Klasse 4 aus Phase 1 retro)
+//
+// Schreibt NICHTS in die DB. Reine Read-only Validation.
+//
+// Usage:
+//   bun scripts/smoke.ts                  (gegen ./seeds/)
+//   bun scripts/smoke.ts --seeds-dir foo  (custom path)
+//
+// In CI: vor `build`-Step laufen lassen — fängt 80% der Phase-1-Bugs
+// lokal in <5 Sekunden statt nach 8-Minuten-Docker-Build im Pod-Boot.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+// App-spezifisch: nimm die EFFEKTIVEN Features die deine App zur Runtime
+// nutzt. Im typischen Setup mit `runProdApp({ features, auth })`:
+//
+//   import { composeFeatures } from "@cosmicdrift/kumiko-dev-server";
+//   import { APP_FEATURES } from "../src/run-config";
+//   const composed = composeFeatures(APP_FEATURES, { includeBundled: true, ... });
+//   const features = composed.features;
+//
+// Bei reiner App-Feature-Setup (kein auth-mode) reicht ein direkter
+// Import der App-Features. Hier im Recipe der minimale set für die
+// referenzierten Recipe-Seeds (tenant + config) — App-Author tauscht
+// gegen sein eigenes Feature-Set.
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import {
+  createRegistry,
+  createSystemUser,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const features = [createConfigFeature(), createTenantFeature()];
+
+const seedsDir = (() => {
+  const idx = process.argv.indexOf("--seeds-dir");
+  return idx >= 0 ? resolve(process.argv[idx + 1] ?? "./seeds") : resolve("./seeds");
+})();
+
+if (!existsSync(seedsDir)) {
+  console.log(`✓ no seeds-dir at ${seedsDir} — nothing to smoke-test`);
+  process.exit(0);
+}
+
+const seedFiles = readdirSync(seedsDir)
+  .filter((n) => n.endsWith(".ts") && !n.startsWith("_") && !n.startsWith("."))
+  .sort();
+
+if (seedFiles.length === 0) {
+  console.log(`✓ ${seedsDir} is empty — nothing to smoke-test`);
+  process.exit(0);
+}
+
+const registry = createRegistry(features);
+
+let failed = 0;
+
+for (const file of seedFiles) {
+  const filePath = resolve(seedsDir, file);
+  console.log(`\nseed: ${file}`);
+
+  // 1. Module-load
+  try {
+    const mod = await import(filePath);
+    if (!mod.default || typeof mod.default.run !== "function") {
+      console.error("  ✗ missing valid SeedMigration default-export");
+      failed++;
+      continue;
+    }
+    console.log(`  ✓ loads: "${mod.default.description}"`);
+  } catch (err) {
+    console.error(`  ✗ load fail: ${err instanceof Error ? err.message : String(err)}`);
+    failed++;
+    continue;
+  }
+
+  // 2 + 3. QN-Resolution + Access (regex-based, gleiche Logik wie runner's
+  // dry-run-validator). Pattern matched inline-string-QNs:
+  const source = readFileSync(filePath, "utf-8");
+  const qnPattern = /systemWriteAs\s*\(\s*["']([^"']+)["']/g;
+  const qns = new Set<string>();
+  for (const m of source.matchAll(qnPattern)) {
+    const qn = m[1];
+    if (qn) qns.add(qn);
+  }
+
+  for (const qn of qns) {
+    const handler = registry.getWriteHandler(qn);
+    if (!handler) {
+      console.error(`  ✗ handler "${qn}" not registered`);
+      failed++;
+      continue;
+    }
+    const accessRoles = (handler.access as { roles?: readonly string[] }).roles ?? [];
+    const systemUserRoles = createSystemUser(SYSTEM_TENANT_ID).roles;
+    const hasAccess = systemUserRoles.some((r) => accessRoles.includes(r));
+    if (!hasAccess) {
+      console.error(
+        `  ✗ system-user roles=${JSON.stringify([...systemUserRoles])} NOT in access.roles=${JSON.stringify([...accessRoles])} for "${qn}"`,
+      );
+      failed++;
+      continue;
+    }
+    console.log(`  ✓ "${qn}" registered + accessible`);
+  }
+}
+
+if (failed > 0) {
+  console.error(`\n${failed} issue(s) — fix before push.`);
+  process.exit(1);
+}
+console.log(`\n✓ all ${seedFiles.length} seed-file(s) pass smoke.`);

package/samples/recipes/seed-migration/seeds/2026-01-01-initial-tenants.ts

@@ -0,0 +1,32 @@
+// Initial-Seed: Demo-Tenants anlegen.
+//
+// Note: in real apps wäre "initial tenants" wahrscheinlich nicht als
+// seed-migration sondern als `r.config({seeds})` oder `auth.admin`-
+// Config umgesetzt — die laufen jedes-Boot idempotent. Hier ist es als
+// seed-migration gezeigt um das Pattern zu demonstrieren.
+//
+// Pattern: jede seed-migration arbeitet write-only via `systemWriteAs`
+// damit alles als Event-Stream persistiert wird. Read-only Lookups
+// (find*) am Context oder direkt via ctx.db.
+
+import type { SeedMigration } from "@cosmicdrift/kumiko-framework/es-ops";
+
+export default {
+  description: "initial demo tenants (alice-corp, beta-inc)",
+  run: async (ctx) => {
+    // Idempotent-Check: wenn Tenants schon existieren (z.B. via auth.admin-
+    // seed), skip diese Migration. Verhindert Konflikt beim re-boot wenn
+    // jemand den Marker manuell gelöscht hat.
+    const existing = await ctx.findTenants();
+    if (existing.some((t) => t.tenantKey === "alice-corp")) return;
+
+    await ctx.systemWriteAs("tenant:write:create", {
+      name: "Alice Corp",
+      tenantKey: "alice-corp",
+    });
+    await ctx.systemWriteAs("tenant:write:create", {
+      name: "Beta Inc",
+      tenantKey: "beta-inc",
+    });
+  },
+} satisfies SeedMigration;

package/samples/recipes/seed-migration/seeds/2026-02-01-fix-admin-roles.ts

@@ -0,0 +1,38 @@
+// Driver-Pattern: ergänze fehlende Rolle auf existierenden Memberships.
+// Spiegelt den realen publicstatus-Bug 2026-05-20 (admin@publicstatus.eu
+// hatte "Admin" aber nicht "TenantAdmin" → text-content + legal-pages
+// access_denied weil bundled-features TenantAdmin erwarten).
+//
+// Funktioniert für jede App mit dem gleichen Pattern: User-Lookup per
+// E-Mail → alle Memberships durchgehen → bei Bedarf via existierendem
+// updateMemberRoles-Handler korrigieren.
+
+import type { SeedMigration } from "@cosmicdrift/kumiko-framework/es-ops";
+
+export default {
+  description: "ergänze TenantAdmin-Rolle für admin@example.com auf allen Memberships",
+  run: async (ctx) => {
+    const admin = await ctx.findUserByEmail("admin@example.com");
+    if (!admin) return; // idempotent: admin nicht (mehr) vorhanden
+
+    for (const m of await ctx.findMembershipsOfUser(admin.id)) {
+      if (m.roles.includes("TenantAdmin")) continue; // bereits korrigiert
+
+      await ctx.systemWriteAs(
+        "tenant:write:update-member-roles", // kebab-case QN — wird vom Dry-Run-Validator gecheckt
+        {
+          userId: admin.id,
+          tenantId: m.tenantId,
+          roles: Array.from(new Set([...m.roles, "TenantAdmin"])),
+        },
+        // tenantIdOverride: stream-tenant aus kumiko_events.v1 — NICHT
+        // m.tenantId (payload-tenant). Beide stimmen oft überein, weichen
+        // aber ab wenn das Aggregate ursprünglich von einem fremden
+        // Executor angelegt wurde (seedTenantMembership by=systemAdmin —
+        // publicstatus-Pattern). findMembershipsOfUser liefert beide,
+        // kein eigener JOIN nötig.
+        m.streamTenantId,
+      );
+    }
+  },
+} satisfies SeedMigration;