@cosmicdrift/kumiko-samples 0.366.0 → 0.368.0

package/packages/bundled-features/src/workflow-runner/feature.ts

@@ -35,55 +35,66 @@ import { workflowRunPendingTableMeta } from "./tables.js";
 // use-all-bundled's check-coverage matches exports to mounted features by it.
 const FEATURE_NAME = "workflow-runner";
 
-export const workflowRunnerFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    "Writes the run-envelope (`workflow.run-started` / `workflow.run-completed` / `workflow.run-failed`) for a workflow run onto its `workflow-run` aggregate stream. Provides `startAndRunWorkflow` and `registerEventTrigger` for consumer features to wire up `defineWorkflow`-based workflows against domain events. Registers no workflows itself. Runs the resume loop for suspended `wait`/`retry`/`waitForEvent` steps (`resume-due-runs` job + `resume-run` handler); `registerEventTrigger` wires an event-wakeup subscriber per workflow that declares `awaits` so a `waitForEvent` step resumes as soon as its awaited event arrives, not just on timeout.",
-  );
-  r.uiHints({
-    displayLabel: "Workflow Runner",
-    category: "infrastructure",
-    recommended: false,
-  });
-  // resume-run needs a full HandlerContext + ctx.systemDb (the pending-row
-  // scan crosses whatever tenant the row belongs to relative to the job's
-  // own tenant loop iteration) — same reasoning as tenant/feature.ts.
-  r.systemScope();
-  r.storeTable(workflowRunPendingTableMeta, {
-    reason: "resume_loop.pending_suspended_steps",
-  });
-  registerWorkflowRunPendingProjection(r);
-  r.writeHandler(resumeRunHandler);
-
-  r.job(
-    "resume-due-runs",
-    { trigger: { cron: "* * * * *" }, perTenant: true, concurrency: "skip" },
-    async (_payload, ctx) => {
-      if (!ctx.systemDb) {
-        throw new Error("resume-due-runs: ctx.systemDb required (r.systemScope() feature)");
-      }
-      const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
-      if (tenantId === undefined) {
-        // skip: cron fired without a perTenant fan-out tenant — nothing scoped
-        return;
-      }
+export function createWorkflowRunnerFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Writes the run-envelope (`workflow.run-started` / `workflow.run-completed` / `workflow.run-failed`) for a workflow run onto its `workflow-run` aggregate stream. Provides `startAndRunWorkflow` and `registerEventTrigger` for consumer features to wire up `defineWorkflow`-based workflows against domain events. Registers no workflows itself. Runs the resume loop for suspended `wait`/`retry`/`waitForEvent` steps (`resume-due-runs` job + `resume-run` handler); `registerEventTrigger` wires an event-wakeup subscriber per workflow that declares `awaits` so a `waitForEvent` step resumes as soon as its awaited event arrives, not just on timeout.",
+      );
+      r.uiHints({
+        displayLabel: "Workflow Runner",
+        category: "infrastructure",
+        recommended: false,
+      });
+      // resume-run needs a full HandlerContext + ctx.systemDb (the pending-row
+      // scan crosses whatever tenant the row belongs to relative to the job's
+      // own tenant loop iteration) — same reasoning as tenant/feature.ts.
+      r.systemScope();
+      r.storeTable(workflowRunPendingTableMeta, {
+        reason: "resume_loop.pending_suspended_steps",
+      });
+      registerWorkflowRunPendingProjection(r);
+      r.writeHandler(resumeRunHandler);
 
-      const dueRows = await selectDueWorkflowRunPending(ctx.systemDb.assertTenantMatch(tenantId));
+      r.job(
+        "resume-due-runs",
+        { trigger: { cron: "* * * * *" }, perTenant: true, concurrency: "skip" },
+        async (_payload, ctx) => {
+          if (!ctx.systemDb) {
+            throw new Error("resume-due-runs: ctx.systemDb required (r.systemScope() feature)");
+          }
+          const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+          if (tenantId === undefined) {
+            // skip: cron fired without a perTenant fan-out tenant — nothing scoped
+            return;
+          }
 
-      for (const row of dueRows) {
-        try {
-          await ctx.write("workflow-runner:write:resume-run", {
-            runId: row.runId,
-            stepIndex: row.stepIndex,
-          });
-        } catch (error) {
-          // skip: one row's dispatch failing (infra hiccup, not a business
-          // outcome — resume-run itself never throws for expected cases)
-          // must not stop the rest of this tenant's due rows from resuming.
-          ctx.log.warn(
-            `[workflow-runner:resume-due-runs] runId=${row.runId} stepIndex=${row.stepIndex} dispatch failed: ${String(error)}`,
+          const dueRows = await selectDueWorkflowRunPending(
+            ctx.systemDb.assertTenantMatch(tenantId),
           );
-        }
-      }
+
+          for (const row of dueRows) {
+            try {
+              await ctx.write("workflow-runner:write:resume-run", {
+                runId: row.runId,
+                stepIndex: row.stepIndex,
+              });
+            } catch (error) {
+              // skip: one row's dispatch failing (infra hiccup, not a business
+              // outcome — resume-run itself never throws for expected cases)
+              // must not stop the rest of this tenant's due rows from resuming.
+              ctx.log.warn(
+                `[workflow-runner:resume-due-runs] runId=${row.runId} stepIndex=${row.stepIndex} dispatch failed: ${String(error)}`,
+              );
+            }
+          }
+        },
+      );
     },
+    { dedupeOptions: {} },
   );
-});
+}
+
+/** @deprecated Use createWorkflowRunnerFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const workflowRunnerFeature = createWorkflowRunnerFeature();

package/packages/bundled-features/src/workflow-runner/handlers/resume-run.write.ts

@@ -30,7 +30,7 @@
 // resultKey on steps/wait-for-event.ts) — pre-seeded into stepsAcc below so
 // a subsequent step's resolver can read `ctx.steps[awaits.someKey]`.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
   buildPipelineSteps,
   computeDefinitionFingerprint,

package/packages/bundled-features/src/workflow-runner/index.ts

@@ -2,7 +2,7 @@
 
 export { workflowRunAggregateId } from "./aggregate-id.js";
 export { registerEventTrigger } from "./event-trigger.js";
-export { workflowRunnerFeature } from "./feature.js";
+export { createWorkflowRunnerFeature, workflowRunnerFeature } from "./feature.js";
 export {
   startAndRunWorkflow,
   type WorkflowRunCompletedPayload,

package/packages/bundled-features/src/workflow-runner/pending-projection.ts

@@ -12,8 +12,8 @@
 // this table and dispatches the actual resume. This projection only writes
 // the rows.
 
-import { deleteMany, fetchOne, upsertOnConflict } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { deleteMany, fetchOne, upsertOnConflict } from "@cosmicdrift/kumiko-framework/db";
 import type {
   FeatureRegistrar,
   MultiStreamProjectionDefinition,

package/samples/apps/admin-console/src/run-config.ts

@@ -14,7 +14,7 @@ import {
   tenantJobFailuresMetric,
 } from "@cosmicdrift/kumiko-bundled-features/metrics";
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
-import { tierEngineFeature } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
+import { createTierEngineFeature } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { localeDe } from "@cosmicdrift/kumiko-locale-de";
 
@@ -50,7 +50,7 @@ export const APP_FEATURES = [
   createAuditFeature(),
   createDeliveryFeature(),
   createJobsFeature(),
-  tierEngineFeature,
+  createTierEngineFeature(),
   createMetricsFeature({ metrics: CONSOLE_METRICS }),
   createSystemMetricsFeature({ metrics: CONSOLE_METRICS }),
   createAdminShellFeature({ metrics: CONSOLE_METRICS }),

package/samples/apps/cap-billing-demo/package.json

@@ -12,5 +12,8 @@
     "@cosmicdrift/kumiko-framework": "workspace:*",
     "zod": "^4.4.3",
     "@cosmicdrift/kumiko-locale-de": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/apps/cap-billing-demo/src/feature.ts

@@ -38,8 +38,8 @@ import {
 } from "@cosmicdrift/kumiko-bundled-features/cap-counter";
 import type { EmailMessage } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import {
+  createMailFoundationFeature,
   createTransportForTenant,
-  mailFoundationFeature,
 } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import {
   access,
@@ -185,7 +185,7 @@ export const newsletterFeature = defineFeature(FEATURE_NAME, (r) => {
   // klarer für boot-Validator-Errors).
   r.requires({ features: ["config"] });
   r.requires({ features: ["cap-counter"] });
-  r.requires({ features: [mailFoundationFeature.name] });
+  r.requires({ features: [createMailFoundationFeature().name] });
   r.requires({ features: [BILLING_FOUNDATION_FEATURE] });
 
   // Tier-config-key. Tenant-Admin setzt's; default "free".

package/samples/apps/cap-billing-demo/src/run-config.ts

@@ -18,11 +18,11 @@
 //                               der eigenen run-config.
 //   - newsletter             — die Demo-Domain mit cap-aware send
 
-import { billingFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
-import { capCounterFeature } from "@cosmicdrift/kumiko-bundled-features/cap-counter";
+import { createBillingFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { createCapCounterFeature } from "@cosmicdrift/kumiko-bundled-features/cap-counter";
 import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
-import { mailFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
-import { mailTransportInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory";
+import { createMailFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import { createMailTransportInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory";
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { createTenantLifecycleFeature } from "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle";
 import { localeDe } from "@cosmicdrift/kumiko-locale-de";
@@ -39,12 +39,12 @@ import { newsletterFeature } from "./feature";
 export const APP_FEATURES = [
   localeDe(),
   createSecretsFeature(),
-  capCounterFeature,
-  mailFoundationFeature,
-  mailTransportInMemoryFeature,
+  createCapCounterFeature(),
+  createMailFoundationFeature(),
+  createMailTransportInMemoryFeature(),
   createComplianceProfilesFeature(),
   createTenantLifecycleFeature(),
-  billingFoundationFeature,
+  createBillingFoundationFeature(),
   newsletterFeature,
 ] as const;
 

package/samples/apps/marketing-demo/src/app/seed.ts

@@ -9,7 +9,7 @@
 // nur Logik: Random-Generator, Datums-Helper, der eigentliche Seed.
 
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { countAssetsForTenant, countTicketsForTenant } from "../db/queries/seed-counts";
 import { ASSET_STATUSES } from "../features/assets/schema";

package/samples/apps/marketing-demo/src/db/queries/seed-counts.ts

@@ -1,5 +1,5 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/db";
 
 export async function countAssetsForTenant(db: DbRunner, tenantId: string): Promise<number> {
   const rows = await asRawClient(db).unsafe<{ count: number }>(

package/samples/apps/showcase/package.json

@@ -19,5 +19,8 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "@cosmicdrift/kumiko-locale-de": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/apps/showcase/src/app/seed-items.ts

@@ -9,7 +9,7 @@
 // bei jedem Restart neu geseeded sonst.
 
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 
 const STATUSES = ["draft", "active", "blocked", "done"] as const;
 

package/samples/apps/styleguide/src/app/seed.ts

@@ -1,7 +1,7 @@
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 
 import { demoEntity } from "../features/demo/feature";
 
@@ -26,7 +26,7 @@ export const seedStyleguideItems: SeedFn = async (stack) => {
   // Calling the executor directly is the framework's documented "seed
   // pattern" for a caller-chosen aggregate id (event-store-executor-write.ts).
   const { executor } = createEntityExecutor("item", demoEntity);
-  const tenantDb = createTenantDb(stack.db, TestUsers.admin.tenantId);
+  const tenantDb = createTenantDb({ db: stack.db, tenantId: TestUsers.admin.tenantId });
 
   for (let i = 0; i < 8; i++) {
     const payload = {

package/samples/apps/styleguide/src/features/ai-settings/seed.ts

@@ -1,14 +1,14 @@
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 
 import { ANTHROPIC_CONNECTION_ID, OPENROUTER_CONNECTION_ID } from "./catalog";
 import { connectionEntity } from "./feature";
 
 export const seedAiConnections: SeedFn = async (stack) => {
   const { executor } = createEntityExecutor("connection", connectionEntity);
-  const tenantDb = createTenantDb(stack.db, TestUsers.admin.tenantId);
+  const tenantDb = createTenantDb({ db: stack.db, tenantId: TestUsers.admin.tenantId });
   const connections = [
     {
       id: ANTHROPIC_CONNECTION_ID,

package/samples/apps/ui-walkthrough/scripts/emit-e2e-data.ts

@@ -7,7 +7,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
-import { generateE2ESpec } from "@cosmicdrift/kumiko-framework/testing/e2e-generator";
+import { generateE2ESpec } from "@cosmicdrift/kumiko-testing/helpers/e2e-generator";
 import { taskFeature } from "../src/features/tasks";
 
 const outPath = resolve(import.meta.dir, "..", "e2e", ".e2e-data.json");

package/samples/apps/ui-walkthrough/src/app/auth-constants.ts

@@ -3,7 +3,7 @@
 // `e2e/_helpers/login.ts` gelesen.
 //
 // Warum getrennt: e2e-Specs laufen im Playwright-Worker, der nichts aus
-// `@cosmicdrift/kumiko-framework/testing` (zieht `vitest`) oder
+// `@cosmicdrift/kumiko-testing/helpers` (zieht `vitest`) oder
 // `@cosmicdrift/kumiko-bundled-features/.../testing` (zieht das ebenfalls) ertragen
 // kann — Vitest's expect redefined Object.prototype-Symbole und kollidiert
 // mit Playwrights expect. Diese Datei bleibt importchain-leer und ist die

package/samples/apps/ui-walkthrough/src/app/seed-rental.ts

@@ -3,7 +3,7 @@
 
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { countRowsForTenant } from "../db/queries/row-counts";
 import { leaseExecutor, partyExecutor, positionExecutor } from "../features/rental/lease-support";
 
@@ -214,7 +214,7 @@ function generatedLease(index: number): BoardLease & { readonly terminated: bool
 export const seedRental: SeedFn = async (stack) => {
   const { tenantId } = TestUsers.admin;
   if ((await countRowsForTenant(stack.db, "read_ui_walkthrough_leases", tenantId)) > 0) return;
-  const db = createTenantDb(stack.db, tenantId);
+  const db = createTenantDb({ db: stack.db, tenantId });
 
   const createLease = async (lease: BoardLease, terminated: boolean, id?: string) => {
     const result = await leaseExecutor.create(

package/samples/apps/ui-walkthrough/src/app/seed-templates.ts

@@ -32,6 +32,7 @@ import {
   SYSTEM_INVOICE_ISSUED,
   SYSTEM_PDF_LAYOUT,
   SYSTEM_TENANCY_CERTIFICATE,
+  SYSTEM_TERMS_CHANGED,
   TENANT_INVOICE_OVERRIDES,
   TENANT_MAIL_LAYOUT_VERSIONS,
   TENANT_UTILITY_STATEMENT,
@@ -165,6 +166,7 @@ export const seedTemplates: SeedFn = async (stack) => {
   await upsertSystem(SYSTEM_PDF_LAYOUT);
   for (const mail of SYSTEM_AUTH_MAILS) await upsertSystem(mail);
   await upsertSystem(SYSTEM_INVOICE_ISSUED);
+  await upsertSystem(SYSTEM_TERMS_CHANGED);
   for (const document of SYSTEM_INVOICE_DOCUMENTS) await upsertSystem(document);
   const certificate = await upsertSystem(SYSTEM_TENANCY_CERTIFICATE);
   await stack.http.writeOk(

package/samples/apps/ui-walkthrough/src/app/seed-vehicles.ts

@@ -1,5 +1,5 @@
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { countRowsForTenant } from "../db/queries/row-counts";
 
 const OCTAVIA_DESCRIPTION = [

package/samples/apps/ui-walkthrough/src/app/seed.ts

@@ -5,7 +5,7 @@
 // tenant already has tasks (persistent KUMIKO_DEV_DB_NAME survives reboots).
 
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { countTasksForTenant } from "../db/queries/task-counts";
 
 const DEMO_TASKS = [

package/samples/apps/ui-walkthrough/src/app/template-seed-data.ts

@@ -276,6 +276,18 @@ export const INVOICE_CORRECTED_DRAFT: SeedTemplate = {
   meta: invoiceIssuedMeta("Ihre Rechnung {{invoiceNumber}} von {{tenantName}}"),
 };
 
+export const SYSTEM_TERMS_CHANGED: SeedTemplate = {
+  slug: "billing:notify:terms-changed",
+  kind: "mail",
+  locale: "de",
+  title: "AGB-Änderung",
+  content: [
+    `<p>Guten Tag ${v("customerName")},</p>`,
+    `<p>zum ${v("effectiveDate")} ändern sich die Allgemeinen Geschäftsbedingungen des Mieterportals.</p>`,
+  ].join(""),
+  meta: { subject: "Änderung der Geschäftsbedingungen" },
+};
+
 export const PAYMENT_REMINDER_TEMPLATES: readonly SeedTemplate[] = [
   {
     slug: "billing:notify:payment-reminder",

package/samples/apps/ui-walkthrough/src/db/queries/row-counts.ts

@@ -1,5 +1,5 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/db";
 
 type CountedTable = "read_ui_walkthrough_leases" | "read_ui_walkthrough_vehicles";
 

package/samples/apps/ui-walkthrough/src/db/queries/task-counts.ts

@@ -1,5 +1,5 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/db";
 
 export async function countTasksForTenant(db: DbRunner, tenantId: string): Promise<number> {
   const rows = await asRawClient(db).unsafe<{ count: number }>(

package/samples/apps/ui-walkthrough/src/features/billing/feature.ts

@@ -63,10 +63,17 @@ const PAYMENT_REMINDER_VARIABLES = {
   invoiceUrl: templateVariable.link({ required: true }),
 } as const;
 
+const TERMS_CHANGED_VARIABLES = {
+  customerName: templateVariable.text({ required: true, example: "Familie Yilmaz" }),
+  effectiveDate: templateVariable.date({ required: true, example: "2026-12-01" }),
+} as const;
+
 export const billingFeature = defineFeature("billing", (r) => {
   r.translations({ keys: toKeyFirst(billingTranslations) });
 
   r.notification("invoice-issued", { variables: INVOICE_ISSUED_VARIABLES });
   r.notification("invoice-corrected", { variables: INVOICE_ISSUED_VARIABLES });
   r.notification("payment-reminder", { variables: PAYMENT_REMINDER_VARIABLES });
+  // Legal wording the platform owns: tenant admins neither see nor override it.
+  r.notification("terms-changed", { variables: TERMS_CHANGED_VARIABLES, systemOnly: true });
 });

package/samples/apps/ui-walkthrough/src/features/billing/i18n.ts

@@ -8,11 +8,13 @@ export const billingTranslations: TranslationsByLocale = {
     "billing:notify.invoice-issued.label": "Rechnung gestellt",
     "billing:notify.invoice-corrected.label": "Rechnung korrigiert",
     "billing:notify.payment-reminder.label": "Mahnlauf",
+    "billing:notify.terms-changed.label": "AGB-Änderung",
   },
   en: {
     "billing:feature.label": "Invoices",
     "billing:notify.invoice-issued.label": "Invoice issued",
     "billing:notify.invoice-corrected.label": "Invoice corrected",
     "billing:notify.payment-reminder.label": "Dunning run",
+    "billing:notify.terms-changed.label": "Terms update",
   },
 };

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -407,7 +407,7 @@
     },
     {
       "name": "channel-email",
-      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails.",
+      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.",
       "toggleableDefault": null,
       "requires": [
         "delivery"
@@ -725,7 +725,7 @@
     },
     {
       "name": "delivery",
-      "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route.",
+      "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (`runProdApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.",
       "toggleableDefault": null,
       "requires": [
         "tenant"
@@ -1507,7 +1507,7 @@
     },
     {
       "name": "mail-foundation",
-      "description": "Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences.",
+      "description": "Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences. Pass `tenantMailTransport` as `tenantTransport` to `createChannelEmailFeature` so a tenant with a provider configured sends delivery mails through its own transport and other tenants through the app transport.",
       "toggleableDefault": null,
       "requires": [
         "config"
@@ -2122,7 +2122,7 @@
     },
     {
       "name": "renderer-mail-html",
-      "description": "A `renderer-foundation` plugin that handles `RenderRequest { kind: \"mail\" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: \"mail\"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: \"mail-layout\"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, and an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.",
+      "description": "A `renderer-foundation` plugin that handles `RenderRequest { kind: \"mail\" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: \"mail\"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: \"mail-layout\"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout, and an optional `siteUrl` resolver supplies the site link of the card when the tenant branding has no site URL (without either, the link is left out). The brand row and `data-resource=\"logo\"` images use the branding logo upload, or the branding logo https address when no file is uploaded. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.",
       "toggleableDefault": null,
       "requires": [
         "renderer-foundation",

package/samples/apps/use-all-bundled/package.json

@@ -21,6 +21,7 @@
     "@cosmicdrift/kumiko-document-designer": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*",
     "@cosmicdrift/kumiko-headless": "workspace:*",
+    "@cosmicdrift/kumiko-renderer-mail-html": "workspace:*",
     "@cosmicdrift/kumiko-renderer-puppeteer-client": "workspace:*",
     "@cosmicdrift/kumiko-renderer-web": "workspace:*",
     "@cosmicdrift/kumiko-server-runtime": "workspace:*",
@@ -30,5 +31,8 @@
     "zod": "^4.4.3",
     "@cosmicdrift/kumiko-locale-de": "workspace:*",
     "@cosmicdrift/kumiko-locale-es": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/apps/use-all-bundled/scripts/check-coverage.ts

@@ -23,10 +23,10 @@ const FRAMEWORK_ROOT = resolve(ROOT, "..", "..", "..");
 // Held-back exports: existieren in bundled-features, sind aber nicht
 // als runtime-feature in use-all-bundled mountbar.
 //
-// Nur Utilities ohne defineFeature (foundation-shared, files-provider-s3 sind pure helpers)
+// Nur Utilities ohne defineFeature (foundation-shared sowie files-provider-s3, der deprecated Alias von file-provider-s3/lib, sind pure helpers)
 // und scaffold-only Features. Gemountete Features gehören nicht hierher.
 const EXPECTED_HELD_BACK = new Set([
-  "files-provider-s3", // utility (createS3Provider helpers), kein defineFeature
+  "files-provider-s3", // deprecated alias of file-provider-s3/lib (createS3Provider helpers), kein defineFeature
   "foundation-shared", // utilities (requireDefined/requireNonEmpty), kein feature
   "page-render", // shared HTML render/cache helpers (legal/managed-pages), kein defineFeature
   "presets", // feature-bundle helpers (dsgvoSelfServiceFeatures, securityBaselineFeatures), kein defineFeature

package/samples/apps/use-all-bundled/src/app/auth-constants.ts

@@ -1,6 +1,6 @@
 // Reine Konstanten — kein Framework-Import, damit der E2E-Login-Helper
 // (Playwright-Worker) sie lesen kann, ohne die vitest-Importchain aus
-// `@cosmicdrift/kumiko-framework/testing` mitzuziehen (kollidiert mit
+// `@cosmicdrift/kumiko-testing/helpers` mitzuziehen (kollidiert mit
 // Playwrights expect über Object.prototype-Symbole).
 
 export const ADMIN_EMAIL = "admin@kumiko.dev";

package/samples/apps/use-all-bundled/src/app/cap-overview-caps.ts

@@ -2,8 +2,8 @@ import type { CapSpec } from "@cosmicdrift/kumiko-bundled-features/cap-overview"
 import { noteEntryTable } from "@cosmicdrift/kumiko-bundled-features/notes-history";
 import { tagEntity } from "@cosmicdrift/kumiko-bundled-features/tags";
 import { tenantMembershipsTable } from "@cosmicdrift/kumiko-bundled-features/tenant";
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+
+import { buildEntityTable, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 const tagTable = buildEntityTable("tag", tagEntity);

package/samples/apps/use-all-bundled/src/app/dev-app-options.ts

@@ -19,7 +19,7 @@ import { notesFeature } from "./notes-feature";
 import { appScreensFeature } from "./screens-feature";
 import { seedScreenshotData } from "./seed";
 
-// tier-admin rendert mit dem bare tierEngineFeature (aus APP_FEATURES) den
+// tier-admin rendert mit dem bare createTierEngineFeature() (aus APP_FEATURES) den
 // ehrlichen Empty-State ("no TierMap configured"). Eine konfigurierte tierMap
 // würde den Resolver auf jedem Write aktivieren (inkl. Login) und braucht
 // per-Tenant Tier-Assignments — disproportional für einen Preview-Screenshot.

package/samples/apps/use-all-bundled/src/app/seed-documents.ts

@@ -9,7 +9,7 @@ import { TemplateResolverHandlers } from "@cosmicdrift/kumiko-bundled-features/t
 import { seedSystemTemplate } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { BETA_TENANT_ID, DEV_TENANT_ID, INVOICE_TEMPLATE_SLUG } from "./auth-constants";
 
 type Stack = Parameters<SeedFn>[0];

package/samples/apps/use-all-bundled/src/app/seed.ts

@@ -24,16 +24,22 @@ import {
 } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
 import { userTable } from "@cosmicdrift/kumiko-bundled-features/user";
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
-import { fetchOne, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+
+import {
+  createTenantDb,
+  type DbConnection,
+  fetchOne,
+  insertOne,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntityExecutor,
   type SessionUser,
   SYSTEM_TENANT_ID,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { TestUsers, unsafeCreateEntityTable } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { unsafeCreateEntityTable } from "@cosmicdrift/kumiko-testing/stack";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { ADMIN_EMAIL, BETA_TENANT_ID, DEMO_NOTE_ID, DEV_TENANT_ID } from "./auth-constants";
 import { noteEntity } from "./notes-feature";
@@ -80,7 +86,7 @@ async function seedTierAssignment(
   adminUserId: string,
 ): Promise<void> {
   const by: SessionUser = { ...TestUsers.systemAdmin, tenantId, id: adminUserId };
-  const tdb = createTenantDb(db, tenantId, "system");
+  const tdb = createTenantDb({ db, tenantId, mode: "system" });
   const result = await tierAssignmentExecutor.create(
     { id: tierAssignmentAggregateId(tenantId), tier, source: "manual", tenantId },
     by,
@@ -104,7 +110,7 @@ async function seedTagsAndNotes(
   adminUserId: string,
 ): Promise<void> {
   const by: SessionUser = { ...TestUsers.systemAdmin, tenantId, id: adminUserId };
-  const tdb = createTenantDb(db, tenantId, "system");
+  const tdb = createTenantDb({ db, tenantId, mode: "system" });
 
   const created = async (
     label: string,