@cosmicdrift/kumiko-samples 0.338.0

package/samples/recipes/auth-foundation-providers/src/feature.ts

@@ -0,0 +1,76 @@
+// Auth-foundation providers — custom tenantResolver + tenantExistence
+//
+// After #1374, apps do NOT pass tenantResolver/tenantExists on
+// anonymousAccess. They mount a feature that registers providers via
+// r.useExtension(EXT_TENANT_RESOLVER / EXT_TENANT_EXISTENCE). Boot
+// (runProdApp / runDevApp) merges them through
+// resolveAnonymousAccessFromRegistry.
+//
+// What to copy:
+//
+//   composeFeatures([
+//     authFoundationFeature,
+//     createSubdomainTenantRoutingFeature({ lookupBySubdomain, existsById }),
+//     …appFeatures,
+//   ], { includeBundled: true })
+//
+//   anonymousAccess: { /* defaultTenantId only, if single-tenant */ }
+//
+// Pair with samples/recipes/anonymous-access-multitenant for the
+// subdomain+cache lookup helpers (reuse createSubdomainResolver inside
+// the provider build).
+
+import {
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  type TenantExistenceProvider,
+  type TenantResolverProvider,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import {
+  defineFeature,
+  type FeatureDefinition,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export type SubdomainTenantRoutingOptions = {
+  readonly lookupBySubdomain: (subdomain: string) => Promise<TenantId | null>;
+  readonly existsById: (tenantId: TenantId) => Promise<boolean>;
+  readonly reservedSubdomains?: readonly string[];
+  /** Provider trust — usually "authoritative" for Host-derived tenants. */
+  readonly trust?: "authoritative" | "fallback-only";
+};
+
+export function createSubdomainTenantRoutingFeature(
+  opts: SubdomainTenantRoutingOptions,
+): FeatureDefinition {
+  const trust = opts.trust ?? "authoritative";
+  const reserved = new Set(opts.reservedSubdomains ?? ["www", "app", "api", "admin"]);
+
+  return defineFeature("sample-subdomain-tenant-routing", (r) => {
+    r.requires("auth-foundation");
+
+    const resolverPlugin: TenantResolverProvider = {
+      trust,
+      build: () => async (c: unknown) => {
+        const ctx = c as {
+          req: { header: (n: string) => string | undefined };
+        };
+        const host = ctx.req.header("Host");
+        if (!host) return null;
+        const noPort = host.split(":")[0] ?? host;
+        const labels = noPort.split(".");
+        if (labels.length < 3) return null;
+        const subdomain = labels[0] ?? null;
+        if (subdomain === null || reserved.has(subdomain)) return null;
+        return opts.lookupBySubdomain(subdomain);
+      },
+    };
+
+    const existencePlugin: TenantExistenceProvider = {
+      build: () => (tenantId) => opts.existsById(tenantId as TenantId),
+    };
+
+    r.useExtension(EXT_TENANT_RESOLVER, "subdomain", resolverPlugin);
+    r.useExtension(EXT_TENANT_EXISTENCE, "db", existencePlugin);
+  });
+}

package/samples/recipes/auth-mfa/README.md

@@ -0,0 +1,67 @@
+# Sample: Auth MFA (TOTP/2FA)
+
+**I want users to be able to enable TOTP-based 2FA, and login to become a two-step challenge once they have.**
+
+## What this sample shows
+
+The production wiring shape: mount `createAuthMfaFeature()` next to `createAuthEmailPasswordFeature()`, thread its status-checker into the login handler, and give `auth: { mfaVerifyHandler: ... }` to `buildServer`. From there the framework handles the rest — a password-only login for an MFA-enrolled user returns a challenge token instead of a JWT, and `POST /auth/mfa/verify` completes it with a TOTP or recovery code.
+
+## The wiring in 4 sentences
+
+1. `createAuthMfaFeature({ setupTokenSecret, challengeTokenSecret, issuer })` builds the feature; `mfaStatusCheckerFromFeature(mfaFeature)` reads its login-status callback back off.
+2. That callback goes into `createAuthEmailPasswordFeature({ mfaStatusChecker: ... })` — `login.write.ts` calls it after the password check to decide whether to mint a JWT or a challenge.
+3. `buildServer({ auth: { mfaVerifyHandler: AuthMfaHandlers.verify } })` mounts `POST /auth/mfa/verify`, a framework route (not a dispatcher write-handler) with its own rate limiter, since it runs before a JWT exists.
+4. If `sessions` is mounted too, `bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(sessionCallbacks.sessionRevokeAllOthers)` wires "enable/disable/regenerate signs out every other session."
+
+## What to copy into your app
+
+```ts illustration
+const mfaFeature = createAuthMfaFeature({
+  setupTokenSecret: config.mfaSetupSecret,
+  challengeTokenSecret: config.mfaChallengeSecret,
+  issuer: "Your App",
+});
+const sessionCallbacks = createSessionCallbacks({ db });
+bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(
+  sessionCallbacks.sessionRevokeAllOthers,
+);
+
+const server = buildServer({
+  registry: buildRegistry([
+    createAuthEmailPasswordFeature({
+      mfaStatusChecker: mfaStatusCheckerFromFeature(mfaFeature),
+    }),
+    createSessionsFeature({
+      autoRevokeOnPasswordChange: sessionCallbacks.sessionMassRevoker,
+    }),
+    mfaFeature,
+    // ... other features
+  ]),
+  context: { db, /* ... */ },
+  jwtSecret: process.env.JWT_SECRET,
+  auth: {
+    membershipQuery: "tenant:query:memberships",
+    loginHandler: "auth-email-password:[REDACTED:API key param]",
+    mfaVerifyHandler: AuthMfaHandlers.verify,
+    sessionCreator: sessionCallbacks.sessionCreator,
+    sessionRevoker: sessionCallbacks.sessionRevoker,
+    sessionChecker: sessionCallbacks.sessionChecker,
+  },
+});
+```
+
+Apps built via `runDevApp`/`runProdApp` (the dev-server bootstrap used by `create-kumiko-app`) get all of this automatically — just add `createAuthMfaFeature(...)` to `APP_FEATURES`. `composeFeatures` threads the status-checker and the bootstrap wires the session-revoke bind and the verify route for you. This sample shows the raw contract those helpers implement.
+
+## Design rules
+
+1. **Enrollment is stateless until confirmed.** `enable-start` returns a signed setup token (QR + secret + 8 recovery codes) — nothing is persisted until `enable-confirm` proves the user scanned it with a valid TOTP code.
+2. **The TOTP secret is envelope-encrypted at rest**, same `MasterKeyProvider` as `secrets`/`config` — no separate crypto story to maintain.
+3. **`/auth/mfa/verify` is a framework route, not a dispatcher handler.** It runs before a JWT exists, so it gets its own IP-keyed rate limiter (`mfaVerifyRateLimit`), independent of the login rate limiter.
+4. **Recovery codes are single-use.** Each of the 8 generated codes completes exactly one login challenge, then it's burned.
+5. **MFA state changes revoke every OTHER live session** (stolen-session defense) — never the session that made the change.
+6. **Enforcement is opt-in.** Without a tenant enabling `auth-mfa:config:required`, users choose for themselves whether to enroll.
+
+## Tests
+
+- **Baseline:** a user without MFA enrolled still gets a JWT straight from `/auth/login`.
+- **End-to-end:** enroll via `enable-start`/`enable-confirm`, log in (gets a challenge, no JWT), complete via `/auth/mfa/verify` (gets a JWT) — copies the `buildServer({ auth: ... })` block from the sample comment verbatim.

package/samples/recipes/auth-mfa/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-auth-mfa",
+  "description": "createAuthMfaFeature — TOTP/2FA enrollment, login challenge, and recovery codes wired into auth-email-password.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/auth-mfa/src/feature.ts

@@ -0,0 +1,72 @@
+// Auth MFA (TOTP/2FA) Sample
+//
+// Shows the production-wiring shape: mount `createAuthMfaFeature()` next to
+// `createAuthEmailPasswordFeature()`, thread its status-checker into the
+// login handler, and (if `sessions` is mounted) bind its revoke-all-other-
+// sessions callback. From there the framework handles the rest — login
+// returns a challenge instead of a JWT when MFA is enabled, POST
+// /auth/mfa/verify completes it, and every OTHER live session gets signed
+// out whenever the account's MFA state changes (enable/disable/regenerate).
+//
+// What to copy into your own app:
+//
+//   const mfaFeature = createAuthMfaFeature({
+//     setupTokenSecret: config.mfaSetupSecret,
+//     challengeTokenSecret: config.mfaChallengeSecret,
+//     issuer: "Your App",
+//   });
+//   const sessionCallbacks = createSessionCallbacks({ db });
+//   bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(
+//     sessionCallbacks.sessionRevokeAllOthers,
+//   );
+//
+//   const server = buildServer({
+//     registry: buildRegistry([
+//       createAuthEmailPasswordFeature({
+//         mfaStatusChecker: mfaStatusCheckerFromFeature(mfaFeature),
+//       }),
+//       createSessionsFeature({
+//         autoRevokeOnPasswordChange: sessionCallbacks.sessionMassRevoker,
+//       }),
+//       mfaFeature,
+//       // ... other features
+//     ]),
+//     context: { db, ... },
+//     jwtSecret: config.jwtSecret,
+//     auth: {
+//       membershipQuery: "tenant:query:memberships",
+//       loginHandler: "auth-email-password:[REDACTED:API key param]",
+//       mfaVerifyHandler: AuthMfaHandlers.verify,
+//       sessionCreator: sessionCallbacks.sessionCreator,
+//       sessionRevoker: sessionCallbacks.sessionRevoker,
+//       sessionChecker: sessionCallbacks.sessionChecker,
+//     },
+//   });
+//
+// Apps built via runDevApp/runProdApp (the dev-server bootstrap) get all of
+// this for free just by adding `createAuthMfaFeature(...)` to APP_FEATURES —
+// composeFeatures threads the status-checker and the bootstrap wraps the
+// session-revoke bind and the /auth/mfa/verify route automatically. This
+// sample shows the raw wiring contract those helpers implement.
+//
+// Design rules the sample demonstrates:
+//
+//  1. Login becomes two-step once MFA is enabled. `POST /auth/login` returns
+//     `{ mfaRequired: true, challengeToken }` instead of a JWT; the client
+//     completes with `POST /auth/mfa/verify`.
+//  2. Enrollment is stateless until confirmed. `enable-start` returns a
+//     signed setup token (QR + recovery codes) — nothing is persisted until
+//     `enable-confirm` proves the user scanned it with a valid TOTP code.
+//  3. Recovery codes are single-use. Each of the 8 generated codes can
+//     complete exactly one login challenge, then it's burned.
+//  4. Every MFA state change signs out every OTHER live session (stolen-
+//     session defense) — but never the session that made the change.
+export {
+  AuthMfaHandlers,
+  base32Decode,
+  bindMfaRevokeAllOtherSessionsFromFeature,
+  createAuthMfaFeature,
+  mfaStatusCheckerFromFeature,
+  userMfaEntity,
+} from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+export { currentTotpCode } from "@cosmicdrift/kumiko-bundled-features/auth-mfa/testing";

package/samples/recipes/basic-entity/README.md

@@ -0,0 +1,64 @@
+# Basic entity
+
+Wire one event-sourced aggregate end-to-end with the framework's built-in CRUD
+helpers. The recipe ships a `task` entity with the standard verbs — create,
+update, delete, restore, list, detail — via `r.crud`, plus
+soft-delete enabled.
+
+This is the smallest useful sample: it demonstrates the path from
+`createEntity({ fields })` to a working API surface without writing any Zod
+schemas or handler bodies by hand.
+
+## What it shows
+
+- **`createEntity` with field factories** — typed text, boolean, number
+  fields with options like `required`, `sortable`, `softDelete`.
+- **`r.crud`** — entity + standard handlers in one call; skip
+  verbs in `verbs` and register explicitly when access differs per verb.
+- **Per-verb access rules** — different roles can create vs. update vs.
+  delete. Editor and User roles can write; only Admin can delete or restore.
+- **Soft delete** — `softDelete: true` on the entity gives the executor an
+  `isDeleted` column and the `delete` handler flips it instead of dropping
+  the row. `restore` flips it back.
+
+## Feature composition
+
+```
+task-management → single feature, single `task` entity, six CRUD handlers
+```
+
+No bundled features required — this is the baseline before you add
+`r.requires("tenant")`, auth, or cross-feature extensions.
+
+## Flow
+
+1. Define fields with `createEntity({ fields: { … } })`.
+2. Call `r.crud("task", taskEntity, { write, read, verbs })`.
+3. Client calls `task-management:write:task:create` → row + event appended.
+4. `delete` soft-flips `isDeleted`; `restore` flips back; `list` excludes
+   deleted rows by default.
+
+## When to reach for it
+
+You're starting a new feature with a single entity and want CRUD without
+inventing your own handlers. Replace any single line with an explicit
+`r.writeHandler({ name, schema, handler })` when you outgrow the defaults
+— see [custom-handlers](/en/samples/recipes-custom-handlers/) for that path.
+
+## Tests
+
+```bash
+bun kumiko test integration samples/basic-entity
+```
+
+Integration tests under `src/__tests__/` exercise list-with-sort,
+soft-delete + restore, and per-verb access boundaries (Editor vs Admin).
+
+## Related samples
+
+- [custom-handlers](/en/samples/recipes-custom-handlers/) — replace generated
+  CRUD helpers with explicit handlers.
+- [field-access](/en/samples/recipes-field-access/) — per-field read/write
+  rules on top of the same entity pattern.
+- [custom-fields-basic](/en/samples/recipes-custom-fields-basic/) — tenant-
+  defined extra columns without migrations.

package/samples/recipes/basic-entity/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-basic-entity",
+  "description": "The simplest possible CRUD demo. About six lines of actual code.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/basic-entity/src/feature.ts

@@ -0,0 +1,45 @@
+// Basic Entity Sample
+// Shows: how to wire one event-sourced aggregate end-to-end via r.crud.
+// Custom logic or per-verb access? Skip a verb in `verbs` and register explicitly.
+
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+  defineEntityDeleteHandler,
+  defineEntityRestoreHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const taskEntity = createEntity({
+  table: "read_sample_tasks",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    description: createTextField({ personal: false, reason: "is_business_data" }),
+    // sortable: true so the integration test can exercise list-with-sort.
+    status: createTextField({ personal: false, reason: "is_business_data", sortable: true }),
+    isArchived: createBooleanField({ default: false }),
+  },
+  softDelete: true,
+});
+
+const editorWrite = { access: { roles: ["Admin", "User"] } } as const;
+const adminWrite = { access: { roles: ["Admin"] } } as const;
+const openRead = {
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may list and view tasks; writes are still gated by the roles below",
+    },
+  },
+} as const;
+
+export const taskFeature = defineFeature("tasks", (r) => {
+  r.crud("task", taskEntity, {
+    write: editorWrite,
+    read: openRead,
+    verbs: { delete: false, restore: false },
+  });
+  r.writeHandler(defineEntityDeleteHandler("task", taskEntity, adminWrite));
+  r.writeHandler(defineEntityRestoreHandler("task", taskEntity, adminWrite));
+});

package/samples/recipes/boot-check/README.md

@@ -0,0 +1,54 @@
+# Boot check
+
+Declare a feature's own mount-invariant with `r.bootCheck(...)` instead of
+relying on framework-internal knowledge. The recipe reproduces the
+prompt-store integration trap: a feature ships PII-annotated
+fields but the companion feature that's supposed to govern user data was
+never mounted, and nothing caught it — until now.
+
+## What it shows
+
+- **`r.bootCheck(fn)`** — a check function that runs once at boot with a
+  ctx exposing every mounted feature. Throw to fail the boot with a clear,
+  feature-prefixed message.
+- **Conditional invariants `r.requires` can't express** — the check only
+  fails when *this* feature's own shape demands it (has a PII field), not
+  unconditionally. A plain `r.requires("user-data-hook")` would fail even
+  for a prompt-store variant with no PII fields at all.
+- **`validateBoot`** — the framework's boot-time validator, run directly
+  against a feature list. `bootCheck` has no DB dependency, so this is the
+  cheapest way to exercise it — no `setupTestStack` needed.
+
+## Feature composition
+
+```
+prompt-store   → entity with a PII field, declares the bootCheck
+user-data-hook → companion feature the check requires when PII is present
+```
+
+## Flow
+
+1. `prompt-store` defines an entity with a `pii: true` field.
+2. It registers `r.bootCheck(({ features }) => { ... })`, closing over its
+   own field definitions to decide whether the invariant applies.
+3. At boot, `validateBoot` runs every registered check. If `prompt-store` is
+   mounted without `user-data-hook`, the check throws and boot fails with
+   `[Feature prompt-store] r.bootCheck failed: ...`.
+4. Mount `user-data-hook` alongside it, and the same check passes.
+
+## When to reach for it
+
+You're writing a feature whose validity depends on *another* feature being
+mounted, but only under a condition your feature alone can evaluate (e.g.
+"only if I have PII fields", "only if I expose more than N screens"). If the
+requirement is unconditional, `r.requires`/`r.optionalRequires` is simpler
+and already covered by the boot validator.
+
+## Tests
+
+```bash
+bun test samples/recipes/boot-check/src/__tests__/feature.test.ts
+```
+
+Two cases: companion mounted → boot succeeds; companion missing → boot
+fails with the feature-prefixed message.

package/samples/recipes/boot-check/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-boot-check",
+  "description": "A feature declares its own mount-invariant via r.bootCheck.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/boot-check/src/feature.ts

@@ -0,0 +1,29 @@
+// Boot-Check Sample
+// Shows: how a feature declares its own mount-invariant via r.bootCheck,
+// for conditional cross-feature requirements r.requires can't express.
+
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+// A prompt-store integration trap: a feature with a PII field was mounted
+// without its required companion feature, and nothing caught it at boot.
+// r.requires("user-data-hook") can't express this — it would
+// fail even for a prompt-store variant with no PII fields at all.
+const promptFields = {
+  text: createTextField({
+    personal: "self",
+    find: "none",
+  }),
+};
+
+export const promptStoreFeature = defineFeature("prompt-store", (r) => {
+  r.entity("prompt", createEntity({ fields: promptFields }));
+  r.bootCheck(({ features }) => {
+    const hasPiiField = Object.values(promptFields).some((field) => field.pii);
+    const hasUserDataHook = features.some((f) => f.name === "user-data-hook");
+    if (hasPiiField && !hasUserDataHook) {
+      throw new Error("prompt-store has PII fields but no user-data-hook feature is mounted");
+    }
+  });
+});
+
+export const userDataHookFeature = defineFeature("user-data-hook", () => {});

package/samples/recipes/compliance-profiles-demo/README.md

@@ -0,0 +1,68 @@
+# compliance-profiles-demo
+
+Same app code, three tenants, three regulatory profiles — no `if (region)`
+branches in your domain handlers.
+
+## What it shows
+
+How a multi-tenant platform uses `compliance-profiles` to deliver different
+regulatory behaviour per tenant:
+
+| Tenant | Profile | Supervisory authority | Languages | Tenant-destroy grace |
+|---|---|---|---|---|
+| **A** (DACH) | `eu-dsgvo` | BlnBDI Berlin | de / en | 30 days |
+| **B** (Switzerland) | `swiss-dsg` | EDÖB Bern | de / fr / it / en | 30 days |
+| **C** (DACH-HR) | `de-hr-dsgvo-hgb` | State DPA | de | 60 days (HR override) |
+
+Plus tenant B with an override (`gracePeriod: { days: 90 }`) extending
+user-rights grace without losing other profile fields — deep-merge on the
+base profile; atomic paths replace, the rest inherits from `swiss-dsg` (which
+itself extends `eu-dsgvo`).
+
+## Feature composition
+
+The sample imports one feature:
+
+```ts illustration
+import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+
+export const features = [createComplianceProfilesFeature()];
+```
+
+The feature exposes `compliance.forTenant` — other features (`user-data-rights`,
+`data-retention`, tenant lifecycle) resolve the effective profile via this API
+instead of hard-coding region rules.
+
+## Flow
+
+1. Operator assigns a profile to each tenant (`eu-dsgvo`, `swiss-dsg`, …).
+2. Tenant B adds a partial override (longer grace) — merged atomically.
+3. `compliance.forTenant(tenantId)` returns resolved fields (languages,
+   supervisory authority, grace periods, retention presets).
+4. Downstream features read the resolver — forget grace, retention policy, and
+   audit obligations follow the profile without app-level branching.
+
+## 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
+# From kumiko-framework repo root:
+bun test samples/recipes/compliance-profiles-demo/src/__tests__/feature.integration.test.ts
+```
+
+Five full-stack tests via `setupTestStack` + real HTTP — profile assignment,
+override merge, and cross-tenant isolation.
+
+## Local dev
+
+This recipe has no standalone server bootstrap — tests are self-contained. To
+try interactively, mount `complianceProfilesDemoFeatures` in your own
+`runDevApp` config.
+
+## Related samples
+
+- [user-data-rights](/en/samples/recipes-user-data-rights/) — forget grace from
+  `compliance.forTenant` drives deletion timing.
+- [apps-user-data-rights-demo](/en/samples/apps-user-data-rights-demo/) — full
+  GDPR app with `eu-dsgvo` profile wired.

package/samples/recipes/compliance-profiles-demo/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-compliance-profiles-demo",
+  "description": "Two-tenant demo: EU + Swiss compliance profiles deliver different authority contacts, languages, and grace periods through the same App-code.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/compliance-profiles-demo/src/feature.ts

@@ -0,0 +1,27 @@
+// Compliance-Profiles Demo
+//
+// Same App-Code, two different tenants, two different DSGVO-Profile —
+// das ist die Sales-Story von Compliance-Profiles. Tenant-Admin waehlt
+// einmal beim Onboarding, danach laufen alle User-Rights-Grace-Periods,
+// Notification-Sprachen, Breach-Disclosure-Pflichten und Audit-Log-
+// Retentions automatisch profil-spezifisch.
+//
+// Demo-Szenario:
+//   Tenant A (DACH-Customer)        → eu-dsgvo
+//     - 30d Grace-Period fuer Forget
+//     - DE/EN-Notifications
+//     - Aufsicht: BlnBDI Berlin
+//
+//   Tenant B (Swiss-Customer)       → swiss-dsg
+//     - 30d Grace-Period (geerbt aus eu-dsgvo via extends)
+//     - DE/FR/IT/EN-Notifications
+//     - Aufsicht: EDÖB Bern
+//
+// Beide Tenants laufen auf derselben App-Instance. Das compliance-
+// profiles-Feature haelt den Profile-State pro Tenant; jedes consumer-
+// Feature ruft `compliance.forTenant` (Sprint 2+) und sieht das
+// effektive Profile fuer den aktuellen Tenant.
+
+import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+
+export const complianceProfilesDemoFeatures = [createComplianceProfilesFeature()];

package/samples/recipes/cross-feature-events/README.md

@@ -0,0 +1,63 @@
+# Cross-Feature Reactions
+
+A handler emits a typed domain event onto the aggregate stream, and an
+async MultiStreamProjection reacts. Since Sprint E this is the
+Marten-gold-standard path for cross-feature reactions — the old
+`ctx.emit` + `r.postEvent` branch was removed in E.2.
+
+## What the sample shows
+
+Three building blocks:
+
+- **`r.defineEvent("name", zodSchema)`** declares the name and payload.
+  The qualified name (e.g. `pubsub-orders:event:order-placed`) comes
+  back as `.name` — pass it directly to `ctx.appendEvent`. Events that
+  aren't registered are rejected by `ctx.appendEvent` at the emit site.
+
+- **`ctx.appendEvent({ aggregateId, aggregateType, type, payload })`**
+  appends the event onto the aggregate stream within the same TX.
+  Version lineage is continued automatically — no synthetic
+  `"pubsub"` stream anymore, the event truly lives on the aggregate.
+
+- **`r.multiStreamProjection({ name, apply })`** declares a consumer.
+  The event dispatcher walks the `events` table via cursor and
+  delivers **at-least-once** in event-ID order. `table` can be omitted
+  — the MSP then becomes a pure side effect (send mail, webhook,
+  external system). With `table`, the apply materializes a persistent
+  read model.
+
+## Flow
+
+```
+HTTP → writeHandler
+         ↓ TX begin
+         orderExecutor.create(...)     ← business row + auto-event (pubsubOrder.created, v1)
+         ctx.appendEvent({...})        ← domain event (pubsub-orders:event:order-placed, v2)
+         ↓ TX commit
+         (async, post-commit)
+         event-dispatcher runOnce
+         ↓ per-consumer cursor advance
+         MSP apply → capture side effect
+```
+
+## Migration note
+
+`r.postEvent` was removed in Sprint E.2. `ctx.appendEvent` +
+`r.multiStreamProjection` is the unified Marten API for CRUD events,
+domain events, and cross-feature reactions.
+
+## Test
+
+The integration test pins three guarantees:
+
+1. **TX atomicity** — after commit the event row sits in the `events`
+   table on the aggregate stream (not on a synthetic `"pubsub"`
+   stream).
+2. **MSP delivery** — `runOnce()` delivers the event to the handler
+   with the correct `tenantId` + payload.
+3. **Rollback safety** — when the write fails, neither the business
+   row nor the event row nor the MSP side effect exists.
+
+```bash
+bun kumiko test integration samples/cross-feature-events
+```

package/samples/recipes/cross-feature-events/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-cross-feature-events",
+  "description": "Feature appends a typed domain event via ctx.appendEvent; a r.multiStreamProjection reacts asynchronously.",
+  "private": true,
+  "dependencies": {
+    "@app/define": "file:./.kumiko",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}