@cosmicdrift/kumiko-samples 0.367.0 → 0.369.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-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/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/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. 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.",
+      "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 the notifications declared with `tenantTransport: true` through the sending tenant's own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`; every other notification (password reset, sign-in) always goes through the app `transport`. `transport` may be left out when `tenantTransport` is set; a mail that then has no transport fails with `missing_credentials`. 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. 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.",
+      "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` (the `runProdApp` and `runDevApp` 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. An app serving its own (e.g. legacy) unsubscribe links renders the same result page with `renderUnsubscribeResultPage({ kind, locale })`. 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. 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.",
+      "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`: notifications declared with `tenantTransport: true` then go through the tenant's own transport when it has a provider and through the app transport otherwise. Tenant admins pick the provider and fill in its settings on the generated Email sending settings screen; an empty provider is a valid choice and means the platform sends.",
       "toggleableDefault": null,
       "requires": [
         "config"
@@ -1531,8 +1531,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "TenantAdmin",
@@ -1603,8 +1603,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "TenantAdmin",
@@ -1624,8 +1624,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "TenantAdmin",
@@ -1645,8 +1645,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "TenantAdmin",
@@ -1669,8 +1669,8 @@
           },
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "all"
@@ -1689,8 +1689,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "all"
@@ -2191,7 +2191,7 @@
     },
     {
       "name": "secrets",
-      "description": "Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: [\"TenantAdmin\"] }; adopt the host's role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins).",
+      "description": "Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: [\"TenantAdmin\"] }; adopt the host's role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins). Server-side code writes a tenant secret with `dispatchSystemWrite({ handlerQn: \"secrets:write:set\", payload, tenantId })`: set and delete also admit the in-process system identity, so such writes pass the same declared-key and value checks.",
       "toggleableDefault": null,
       "requires": [],
       "optionalRequires": [],

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

@@ -31,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,