@cosmicdrift/kumiko-samples 0.367.0 → 0.369.0

package/packages/bundled-features/src/channel-email/email-channel.ts

@@ -6,6 +6,7 @@ import {
   type AttachmentOrigin,
   type ChannelContext,
   type ChannelMessage,
+  currentNotificationType,
   DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE,
   DELIVERY_UNSUBSCRIBE_PATH,
   type DeliveryChannel,
@@ -163,18 +164,36 @@ async function resolveAttachments(
   return { kind: "resolved", attachments: resolved };
 }
 
-export type EmailChannelOptions = {
-  /** The app-wide transport, used for every tenant `tenantTransport` returns null for. */
-  readonly transport: EmailTransport;
-  /** Resolves the sending tenant's own transport, null when it has none. Built per send and
-   *  never cached, so a provider change applies to the next mail; a throw fails the send. */
-  readonly tenantTransport?: (ctx: ChannelContext) => Promise<EmailTransport | null>;
+/** Resolves the sending tenant's own transport, null when it has none. Built per send and
+ *  never cached, so a provider change applies to the next mail; a throw fails the send. */
+export type TenantTransportResolver = (ctx: ChannelContext) => Promise<EmailTransport | null>;
+
+// The app transport may only be left out when tenant transports exist: a channel with
+// neither could never send.
+type EmailChannelTransports =
+  | {
+      /** The app-wide transport for every mail that does not go through a tenant transport. */
+      readonly transport: EmailTransport;
+      /** Used only for notifications declared with `tenantTransport: true`. */
+      readonly tenantTransport?: TenantTransportResolver;
+    }
+  | {
+      readonly transport?: undefined;
+      readonly tenantTransport: TenantTransportResolver;
+    };
+
+export type EmailChannelOptions = EmailChannelTransports & {
   readonly resolveEmail: (
     userId: string,
     ctx: { db: unknown; tenantId: TenantId },
   ) => Promise<string | null>;
 };
 
+function isTenantTransportNotification(ctx: ChannelContext, notificationType: string): boolean {
+  const current = currentNotificationType(ctx.registry, notificationType);
+  return ctx.registry.getAllNotifications().get(current)?.tenantTransport === true;
+}
+
 export function createEmailChannel(options: EmailChannelOptions): DeliveryChannel {
   const { transport, resolveEmail, tenantTransport } = options;
 
@@ -213,8 +232,12 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
     };
   }
 
-  async function transportFor(ctx: ChannelContext): Promise<EmailTransport> {
+  async function transportFor(
+    message: ChannelMessage,
+    ctx: ChannelContext,
+  ): Promise<EmailTransport | undefined> {
     if (tenantTransport === undefined) return transport;
+    if (!isTenantTransportNotification(ctx, message.notificationType)) return transport;
     return (await tenantTransport(ctx)) ?? transport;
   }
 
@@ -260,7 +283,15 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
         return { status: "failed", error: "send_failed", address };
       }
       const resolvedAttachments = resolution.attachments;
-      const sendTransport = await transportFor(ctx);
+      const sendTransport = await transportFor(message, ctx);
+      if (sendTransport === undefined) {
+        // Configuration, not a transient error: a retry cannot conjure a transport.
+        createFallbackLogger("delivery").warn("no mail transport for this mail, send failed", {
+          tenantId: ctx.tenantId,
+          notificationType: message.notificationType,
+        });
+        return { status: "failed", error: "missing_credentials", address };
+      }
       await sendTransport.send(
         guardEmailMessage({
           to: address,

package/packages/bundled-features/src/channel-email/feature.ts

@@ -10,7 +10,7 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
 
   return defineFeature("channel-email", (r) => {
     r.describe(
-      "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.",
+      "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.",
     );
     r.uiHints({
       displayLabel: "Email Channel",

package/packages/bundled-features/src/channel-email/index.ts

@@ -1,4 +1,8 @@
-export { createEmailChannel, type EmailChannelOptions } from "./email-channel.js";
+export {
+  createEmailChannel,
+  type EmailChannelOptions,
+  type TenantTransportResolver,
+} from "./email-channel.js";
 export { createChannelEmailFeature } from "./feature.js";
 export { guardEmailMessage, withPiiCiphertextGuard } from "./pii-guard.js";
 export {

package/packages/bundled-features/src/channel-in-app/handlers/inbox.query.ts

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { inAppMessagesTable } from "../tables.js";

package/packages/bundled-features/src/channel-in-app/handlers/mark-all-read.write.ts

@@ -1,4 +1,4 @@
-import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { updateMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { inAppMessagesTable } from "../tables.js";

package/packages/bundled-features/src/channel-in-app/handlers/mark-read.write.ts

@@ -1,4 +1,4 @@
-import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { updateMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";

package/packages/bundled-features/src/channel-in-app/handlers/unread-count.query.ts

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { inAppMessagesTable } from "../tables.js";

package/packages/bundled-features/src/channel-in-app/tables.ts

@@ -1,10 +1,10 @@
-import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   boolean,
   type EntityTableMeta,
   index,
   instant,
   table as pgTable,
+  requireEntityTableMeta,
   serial,
   sql,
   text,

package/packages/bundled-features/src/compliance-profiles/handlers/for-tenant.query.ts

@@ -1,9 +1,9 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   type ComplianceProfileKey,
   type EffectiveComplianceProfile,
   resolveComplianceProfile,
 } from "@cosmicdrift/kumiko-framework/compliance";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { parseComplianceProfileOverride } from "../_internal/parse-override.js";

package/packages/bundled-features/src/compliance-profiles/handlers/needs-profile.query.ts

@@ -1,6 +1,6 @@
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { ComplianceProfileKey } from "@cosmicdrift/kumiko-framework/compliance";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { tenantComplianceProfileTable } from "../schema/profile-selection.js";

package/packages/bundled-features/src/compliance-profiles/handlers/set-profile.write.ts

@@ -1,9 +1,8 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   complianceProfileOverrideSchema,
   SELECTABLE_PROFILE_KEYS,
 } from "@cosmicdrift/kumiko-framework/compliance";
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   UnprocessableError,

package/packages/bundled-features/src/compliance-profiles/resolve-for-tenant.ts

@@ -8,13 +8,13 @@
 // Beide Pfade nutzen `resolveComplianceProfile` aus framework/compliance,
 // also kein Drift zwischen Query-API und Worker-Pfad.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   type ComplianceProfileKey,
   type EffectiveComplianceProfile,
   resolveComplianceProfile,
 } from "@cosmicdrift/kumiko-framework/compliance";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { isTenantDb } from "../shared/index.js";
 import { parseComplianceProfileOverride } from "./_internal/parse-override.js";

package/packages/bundled-features/src/compliance-profiles/seeding.ts

@@ -10,7 +10,6 @@
 //
 // Pattern matched seedTextBlock aus text-content.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type {
   ComplianceProfileKey,
   ComplianceProfileOverride,
@@ -19,10 +18,15 @@ import {
   createEventStoreExecutor,
   createTenantDb,
   type DbConnection,
+  fetchOne,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import {
+  runEventStoreSeed,
+  type SeedIfExists,
+  TestUsers,
+} from "@cosmicdrift/kumiko-framework/seeding";
+
 import {
   tenantComplianceProfileEntity,
   tenantComplianceProfileTable,
@@ -50,7 +54,7 @@ export async function seedComplianceProfile(
   // + Projection im selben Tenant-Bucket landen (Memory:
   // feedback_event_store_tenant_consistency).
   const by = opts.by ?? { ...TestUsers.systemAdmin, tenantId: opts.tenantId };
-  const tdb = createTenantDb(db, opts.tenantId, "system");
+  const tdb = createTenantDb({ db, tenantId: opts.tenantId, mode: "system" });
   const overrideJson = opts.override !== undefined ? JSON.stringify(opts.override) : null;
 
   const existing = (await fetchOne(db, tenantComplianceProfileTable, {

package/packages/bundled-features/src/compliance-profiles-ops/index.ts

@@ -13,22 +13,31 @@
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { tenantsMissingProfileQuery } from "./handlers/tenants-missing-profile.query.js";
 
-export const complianceProfilesOpsFeature = defineFeature("compliance-profiles-ops", (r) => {
-  r.describe(
-    "Platform-wide SystemAdmin counterpart to `compliance-profiles`' `needs-profile` query (#2089): `tenants-missing-profile` lists every enabled tenant with no row in `tenantComplianceProfile` at all, tenant-wide instead of scoped to the caller's own tenant. Mount alongside `compliance-profiles` and `tenant` when an operator UI needs to see which tenants still silently run on `minimal-no-region`.",
-  );
-  r.uiHints({
-    displayLabel: "Compliance Profiles · Operator Visibility",
-    category: "compliance",
-    recommended: false,
-  });
-  r.systemScope();
-  r.requires({ features: ["compliance-profiles"] });
-  r.requires({ features: ["tenant"] });
+export function createComplianceProfilesOpsFeature() {
+  return defineFeature(
+    "compliance-profiles-ops",
+    (r) => {
+      r.describe(
+        "Platform-wide SystemAdmin counterpart to `compliance-profiles`' `needs-profile` query (#2089): `tenants-missing-profile` lists every enabled tenant with no row in `tenantComplianceProfile` at all, tenant-wide instead of scoped to the caller's own tenant. Mount alongside `compliance-profiles` and `tenant` when an operator UI needs to see which tenants still silently run on `minimal-no-region`.",
+      );
+      r.uiHints({
+        displayLabel: "Compliance Profiles · Operator Visibility",
+        category: "compliance",
+        recommended: false,
+      });
+      r.systemScope();
+      r.requires({ features: ["compliance-profiles"] });
+      r.requires({ features: ["tenant"] });
+
+      const queries = {
+        tenantsMissingProfile: r.queryHandler(tenantsMissingProfileQuery),
+      };
 
-  const queries = {
-    tenantsMissingProfile: r.queryHandler(tenantsMissingProfileQuery),
-  };
+      return { queries };
+    },
+    { dedupeOptions: {} },
+  );
+}
 
-  return { queries };
-});
+/** @deprecated Use createComplianceProfilesOpsFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const complianceProfilesOpsFeature = createComplianceProfilesOpsFeature();

package/packages/bundled-features/src/config/db/queries/resolver.ts

@@ -1,5 +1,5 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { configValuesTable } from "../../table.js";
 

package/packages/bundled-features/src/config/handlers/reencrypt.job.ts

@@ -125,7 +125,7 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   function tdbFor(tenantId: TenantId): TenantDb {
     let existing = tdbCache.get(tenantId);
     if (!existing) {
-      existing = createTenantDb(db, tenantId, "system");
+      existing = createTenantDb({ db, tenantId, mode: "system" });
       tdbCache.set(tenantId, existing);
     }
     return existing;
@@ -146,7 +146,7 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   // tenant's writes — sharing it with sdbFor(SYSTEM_TENANT_ID) would make a
   // write-path cache entry double as the scan's ack gate.
   const scanDb = createSystemDbView(
-    createTenantDb(db, SYSTEM_TENANT_ID, "system"),
+    createTenantDb({ db, tenantId: SYSTEM_TENANT_ID, mode: "system" }),
     undefined,
     reportEscapeHatchFor(SYSTEM_TENANT_ID),
   );

package/packages/bundled-features/src/config/resolver.ts

@@ -1,11 +1,11 @@
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
   decryptPiiValueForSubject,
   type KmsContext,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import type {
   ConfigCascade,
   ConfigCascadeLevel,

package/packages/bundled-features/src/config/web/i18n.ts

@@ -32,9 +32,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "config.errors.unknownKey": "Unknown configuration key.",
     "config.errors.unknownExtensionPlugin": "This provider is not available.",
     "config.settings.extensionSelectorHint":
-      "Choose a provider and save. Its settings appear below.",
+      "Choose a provider. Its settings appear below and are saved together with it.",
     "config.settings.provider": "Provider",
-    "config.settings.saveProvider": "Save provider",
     "config.settings.audience.system":
       "Applies to every tenant unless a tenant sets its own value.",
     "config.settings.audience.tenant":

package/packages/bundled-features/src/config/write-helpers.ts

@@ -2,9 +2,9 @@
 // Extracted from set.write.ts so reset.write.ts + values.query.ts don't
 // have to cross-import from another handler file.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { SubjectId } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
   type ConfigKeyDefinition,
   type ConfigScope,

package/packages/bundled-features/src/crypto-shredding/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.368.0",
+    "type": "fix",
+    "title": "forget-subject closes the login door for users whose stream is already deleted",
+    "detail": "forget-subject returned 500 (\"user lifecycle update failed ... not_found\") when the user stream was deleted but the read_users status still read active, leaving sessions and PATs alive. The erasure now appends the status-deleted user.updated event to that stream too, so the login door closes, the handler returns 200 and a read_users rebuild keeps the state."
+  },
   {
     "version": "0.366.0",
     "type": "fix",

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -1,11 +1,6 @@
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
-import {
-  fetchOne,
-  runInSavepointIfSupported,
-  runnerCanBeginTransaction,
-  transaction,
-} from "@cosmicdrift/kumiko-framework/bun-db";
+
 import {
   computeBlindIndex,
   configuredBlindIndexKey,
@@ -16,11 +11,15 @@ import {
 } from "@cosmicdrift/kumiko-framework/crypto";
 import {
   type DbRunner,
+  fetchOne,
   nullBlindIndexesForSubject,
   recordEventsOwnedExclusivelyByTenant,
   recordRowExistsInTenant,
   recordRowOwningTenantId,
+  runInSavepointIfSupported,
+  runnerCanBeginTransaction,
   subjectRowExistsInTenant,
+  transaction,
   WritePurposes,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
@@ -365,7 +364,10 @@ async function closeUserLoginDoor(
       runner,
       userId,
       { status: USER_STATUS.Deleted },
-      { writePurpose: WritePurposes.erasure },
+      // includeDeleted: a user whose stream is already deleted but whose status
+      // still reads active would otherwise fail with not_found (500) and keep
+      // sessions and PATs alive.
+      { writePurpose: WritePurposes.erasure, includeDeleted: true },
     );
     if (ctx.registry.features.has("personal-access-tokens")) {
       await revokeAllPatTokensForUser(runner, userId);

package/packages/bundled-features/src/custom-fields/db/queries/field-access.ts

@@ -1,5 +1,5 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectSerializedFieldDefinition(
   runner: DbRunner,

package/packages/bundled-features/src/custom-fields/db/queries/projection.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";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 function quoteTable(tableName: string): string {

package/packages/bundled-features/src/custom-fields/db/queries/quota.ts

@@ -1,5 +1,5 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 
 export async function countTenantFieldDefinitions(
   runner: DbRunner,

package/packages/bundled-features/src/custom-fields/db/queries/retention.ts

@@ -1,5 +1,9 @@
-import { asRawClient, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
-import { type DbRunner, toPostgresArrayLiteral } from "@cosmicdrift/kumiko-framework/db";
+import {
+  asRawClient,
+  type DbRunner,
+  toPostgresArrayLiteral,
+  unsafeReadRetrying,
+} from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectHostRowsWithCustomFields(
   db: DbRunner,

package/packages/bundled-features/src/custom-fields/db/queries/user-data-rights.ts

@@ -1,5 +1,5 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 
 function quoteTable(tableName: string): string {
   return `"${tableName.replace(/"/g, '""')}"`;

package/packages/bundled-features/src/custom-fields/feature.ts

@@ -33,7 +33,7 @@
 //   `customFieldsField()` (jsonb) deklarieren.
 //
 // **Exports-Pattern (2026-05-23 refactor)**:
-//   `customFieldsFeature.exports.{setEvent,clearedEvent,fieldDefinitionDeletedEvent}`
+//   `createCustomFieldsFeature().exports.{setEvent,clearedEvent,fieldDefinitionDeletedEvent}`
 //   liefern typed EventDef-handles. Handler + wire-for-entity nutzen
 //   `<event>.name` als compile-time-literal-typed qualified-string — keine
 //   hand-gebauten Template-Literals mehr (T1 hat den toKebab-collapse-drift
@@ -179,12 +179,9 @@ function registerCustomFields(
   return { setEvent, clearedEvent, fieldDefinitionDeletedEvent };
 }
 
-// Singleton feature-definition mit typed exports. Handler + wire-for-entity
-// importieren diesen `customFieldsFeature` und greifen lazy in ihrer
-// runtime-arrow-fn auf `.exports.<event>.name` zu — der module-cycle
-// (feature.ts -> handlers/*.write.ts -> feature.ts) löst sich auf weil
-// kein top-level-access stattfindet.
-export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
+// Handlers and wire-for-entity read `.exports.<event>.name` lazily inside their runtime
+// arrow functions, which resolves the module cycle (feature.ts -> handlers/*.write.ts -> feature.ts).
+const defaultCustomFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
   registerCustomFields(r, {
     defineTenantHandler: defineTenantFieldHandler,
     updateTenantHandler: updateTenantFieldHandler,
@@ -246,21 +243,18 @@ export function resolveFieldDefinitionListRoles(
   ];
 }
 
-// Backwards-compat-wrapper. Bestehende Caller (z.B. integration-tests,
-// host-apps) nutzen weiterhin `createCustomFieldsFeature()`. Returnt den
-// module-level-Singleton — kein neuer build pro Aufruf, was für consumer
-// nicht erkennbar ist (read-only inspection). Jede gesetzte Option baut
-// eine frische Feature-Definition mit den Varianten-Handlern.
+// Without options this returns the module-level singleton (no rebuild per call); every
+// option builds a fresh feature definition with the variant handlers.
 export function createCustomFieldsFeature(
   opts: CustomFieldsFeatureOptions = {},
-): typeof customFieldsFeature {
+): typeof defaultCustomFieldsFeature {
   const hasOptions =
     opts.fieldDefinitionLimitPerTenant !== undefined ||
     opts.valueWriteRoles !== undefined ||
     opts.fieldDefinitionListRoles !== undefined ||
     opts.fieldDefinitionWriteRoles !== undefined;
   if (!hasOptions) {
-    return customFieldsFeature;
+    return defaultCustomFieldsFeature;
   }
   const limit = opts.fieldDefinitionLimitPerTenant;
   const definitionWriteRoles = opts.fieldDefinitionWriteRoles;
@@ -287,3 +281,6 @@ export function createCustomFieldsFeature(
     }),
   );
 }
+
+/** @deprecated Use createCustomFieldsFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const customFieldsFeature = createCustomFieldsFeature();

package/packages/bundled-features/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -2,7 +2,7 @@ import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { DEFAULT_VALUE_WRITE_ROLES } from "../constants.js";
-import { customFieldsFeature } from "../feature.js";
+import { createCustomFieldsFeature } from "../feature.js";
 import { checkFieldAccessForWrite } from "../lib/field-access.js";
 
 export const clearCustomFieldPayloadSchema = z.object({
@@ -62,7 +62,7 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
     await ctx.unsafeAppendEvent({
       aggregateId: payload.entityId,
       aggregateType: payload.entityName,
-      type: customFieldsFeature.exports.clearedEvent.name,
+      type: createCustomFieldsFeature().exports.clearedEvent.name,
       payload: { fieldKey: payload.fieldKey },
     });
 

package/packages/bundled-features/src/custom-fields/handlers/delete-system-field.write.ts

@@ -3,7 +3,7 @@ import { requireForTenant } from "../../shared/index.js";
 import { fieldDefinitionAggregateId } from "../aggregate-id.js";
 import { FIELD_DEFINITION_AGGREGATE_TYPE } from "../constants.js";
 import { fieldDefinitionExecutor } from "../executor.js";
-import { customFieldsFeature } from "../feature.js";
+import { createCustomFieldsFeature } from "../feature.js";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas.js";
 
 // delete-system-field — SystemAdmin entfernt eine system-weite Field-
@@ -38,7 +38,7 @@ export const deleteSystemFieldHandler: WriteHandlerDef = {
       await ctx.unsafeAppendEvent({
         aggregateId,
         aggregateType: FIELD_DEFINITION_AGGREGATE_TYPE,
-        type: customFieldsFeature.exports.fieldDefinitionDeletedEvent.name,
+        type: createCustomFieldsFeature().exports.fieldDefinitionDeletedEvent.name,
         payload: {
           entityName: payload.entityName,
           fieldKey: payload.fieldKey,

package/packages/bundled-features/src/custom-fields/handlers/delete-tenant-field.write.ts

@@ -5,7 +5,7 @@ import {
   FIELD_DEFINITION_AGGREGATE_TYPE,
 } from "../constants.js";
 import { fieldDefinitionExecutor } from "../executor.js";
-import { customFieldsFeature } from "../feature.js";
+import { createCustomFieldsFeature } from "../feature.js";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas.js";
 
 // delete-tenant-field — TenantAdmin löscht eigene Field-Definition.
@@ -59,7 +59,7 @@ export function createDeleteTenantFieldHandler(
         await ctx.unsafeAppendEvent({
           aggregateId,
           aggregateType: FIELD_DEFINITION_AGGREGATE_TYPE,
-          type: customFieldsFeature.exports.fieldDefinitionDeletedEvent.name,
+          type: createCustomFieldsFeature().exports.fieldDefinitionDeletedEvent.name,
           payload: { entityName: payload.entityName, fieldKey: payload.fieldKey, tenantId },
         });
       }

package/packages/bundled-features/src/custom-fields/handlers/set-custom-field.write.ts

@@ -2,7 +2,7 @@ import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { DEFAULT_VALUE_WRITE_ROLES } from "../constants.js";
-import { customFieldsFeature } from "../feature.js";
+import { createCustomFieldsFeature } from "../feature.js";
 import { fieldWriteAccessDeniedRoles, loadFieldDefinition } from "../lib/field-access.js";
 import { buildCustomFieldValueSchema } from "../lib/value-schema.js";
 
@@ -103,7 +103,7 @@ export const setCustomFieldHandler: WriteHandlerDef = {
     await ctx.unsafeAppendEvent({
       aggregateId: payload.entityId,
       aggregateType: payload.entityName,
-      type: customFieldsFeature.exports.setEvent.name,
+      type: createCustomFieldsFeature().exports.setEvent.name,
       payload: { fieldKey: payload.fieldKey, value: payload.value },
     });
 

package/packages/bundled-features/src/custom-fields/wire-for-entity.ts

@@ -16,7 +16,7 @@ import {
 } from "./db/queries/projection.js";
 
 import type { CustomFieldClearedPayload, CustomFieldSetPayload } from "./events.js";
-import { customFieldsFeature } from "./feature.js";
+import { createCustomFieldsFeature } from "./feature.js";
 
 // Helper für entity-definitions — fügt eine `customFields jsonb`-Spalte
 // hinzu. Consumer:
@@ -90,9 +90,9 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
   // Qualified event-type-names — sourced from typed EventDef.name handles
   // (compile-time literal-typed, no Template-Literal-Drift à la toKebab-
   // collapse-bug die T1 aufgedeckt hat).
-  const setEventType = customFieldsFeature.exports.setEvent.name;
-  const clearedEventType = customFieldsFeature.exports.clearedEvent.name;
-  const fieldDefDeletedType = customFieldsFeature.exports.fieldDefinitionDeletedEvent.name;
+  const setEventType = createCustomFieldsFeature().exports.setEvent.name;
+  const clearedEventType = createCustomFieldsFeature().exports.clearedEvent.name;
+  const fieldDefDeletedType = createCustomFieldsFeature().exports.fieldDefinitionDeletedEvent.name;
 
   // Geteilte apply-Bodies: die MSP liefert sie live (async cursor), die
   // entity-projection-extension replayt sie in rebuildProjection — gleiche

package/packages/bundled-features/src/data-retention/resolve-for-tenant.ts

@@ -2,8 +2,8 @@
 // the forget runner and the `policy-for` query all go through here, so a caller
 // cannot skip a layer (e.g. the tenant preset) by accident.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { isTenantDb } from "../shared/index.js";
 import { parseRetentionOverrideOrNull } from "./_internal/parse-override.js";