@cosmicdrift/kumiko-samples 0.367.0 → 0.369.0

package/packages/bundled-features/src/folders/feature.ts

@@ -107,7 +107,7 @@ function registerFolders(
   );
 }
 
-export const foldersFeature = defineFeature(FOLDERS_FEATURE_NAME, (r) =>
+const defaultFoldersFeature = defineFeature(FOLDERS_FEATURE_NAME, (r) =>
   registerFolders(r, DEFAULT_FOLDER_ACCESS, undefined, undefined, undefined),
 );
 
@@ -156,7 +156,9 @@ function resolveAccess(opts: FoldersFeatureOptions): AccessRule {
 
 // Options wrapper. Without options returns the module-level singleton (no
 // rebuild). access/roles/toggleable build a fresh feature-definition.
-export function createFoldersFeature(opts: FoldersFeatureOptions = {}): typeof foldersFeature {
+export function createFoldersFeature(
+  opts: FoldersFeatureOptions = {},
+): typeof defaultFoldersFeature {
   if (
     opts.access === undefined &&
     opts.roles === undefined &&
@@ -164,7 +166,7 @@ export function createFoldersFeature(opts: FoldersFeatureOptions = {}): typeof f
     opts.ownership === undefined &&
     opts.parents === undefined
   ) {
-    return foldersFeature;
+    return defaultFoldersFeature;
   }
   assertNoWhereRuleInOwnershipWrite("createFoldersFeature", opts.ownership?.write);
   if (opts.parents !== undefined && opts.parents.length === 0) {
@@ -180,3 +182,6 @@ export function createFoldersFeature(opts: FoldersFeatureOptions = {}): typeof f
     registerFolders(r, access, opts.toggleable, opts.ownership, opts.parents),
   );
 }
+
+/** @deprecated Use createFoldersFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const foldersFeature = createFoldersFeature();

package/packages/bundled-features/src/folders-user-data/index.ts

@@ -12,22 +12,31 @@ import {
   folderExportHook,
 } from "./hooks.js";
 
-export const foldersUserDataFeature = defineFeature("folders-user-data", (r) => {
-  r.describe(
-    "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `folders` feature's `folder` + `folder-assignment` entities. Mounts the EXT_USER_DATA export + delete hooks so a tenant's folder tree and its entity-to-folder assignments are included in the user-data export bundle and erased on a tenant-scoped forget (single-user tenants only; multi-user + anonymize are no-ops since folder rows carry no per-user PII). Kept separate from `folders` so folder consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `folders`.",
+export function createFoldersUserDataFeature() {
+  return defineFeature(
+    "folders-user-data",
+    (r) => {
+      r.describe(
+        "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `folders` feature's `folder` + `folder-assignment` entities. Mounts the EXT_USER_DATA export + delete hooks so a tenant's folder tree and its entity-to-folder assignments are included in the user-data export bundle and erased on a tenant-scoped forget (single-user tenants only; multi-user + anonymize are no-ops since folder rows carry no per-user PII). Kept separate from `folders` so folder consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `folders`.",
+      );
+      // user-data-rights is the hard dependency (EXT_USER_DATA host). `folders` is
+      // OPTIONAL: if it's mounted toggleable(default=false) (e.g. per-tenant via
+      // tier), a hard r.requires would throw an "effectively disabled" boot
+      // warning even though the folder entities exist and the hooks work fine.
+      r.requires({ features: ["user-data-rights"] });
+      r.optionalRequires("folders");
+      r.useExtension(EXT_USER_DATA, "folder", {
+        export: folderExportHook,
+        delete: folderDeleteHook,
+      });
+      r.useExtension(EXT_USER_DATA, "folder-assignment", {
+        export: folderAssignmentExportHook,
+        delete: folderAssignmentDeleteHook,
+      });
+    },
+    { dedupeOptions: {} },
   );
-  // user-data-rights is the hard dependency (EXT_USER_DATA host). `folders` is
-  // OPTIONAL: if it's mounted toggleable(default=false) (e.g. per-tenant via
-  // tier), a hard r.requires would throw an "effectively disabled" boot
-  // warning even though the folder entities exist and the hooks work fine.
-  r.requires({ features: ["user-data-rights"] });
-  r.optionalRequires("folders");
-  r.useExtension(EXT_USER_DATA, "folder", {
-    export: folderExportHook,
-    delete: folderDeleteHook,
-  });
-  r.useExtension(EXT_USER_DATA, "folder-assignment", {
-    export: folderAssignmentExportHook,
-    delete: folderAssignmentDeleteHook,
-  });
-});
+}
+
+/** @deprecated Use createFoldersUserDataFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const foldersUserDataFeature = createFoldersUserDataFeature();

package/packages/bundled-features/src/form-draft/db/queries/cleanup.ts

@@ -1,5 +1,5 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { FormDraftBlob } from "../../schemas.js";

package/packages/bundled-features/src/form-draft/db/queries/draft-count.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";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 // COUNT(*), not selectMany(...).length — save.write.ts checks this on every

package/packages/bundled-features/src/form-draft/db/queries/owned-file-refs.ts

@@ -1,8 +1,9 @@
 import {
+  type DbRunner,
   instantToTimestamptzParam,
+  toPostgresArrayLiteral,
   unsafeReadRetrying,
-} from "@cosmicdrift/kumiko-framework/bun-db";
-import { type DbRunner, toPostgresArrayLiteral } from "@cosmicdrift/kumiko-framework/db";
+} from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 

package/packages/bundled-features/src/form-draft/feature.ts

@@ -56,4 +56,9 @@ function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>):
   });
 }
 
-export const formDraftFeature = defineFeature(FORM_DRAFT_FEATURE_NAME, registerFormDraft);
+export function createFormDraftFeature() {
+  return defineFeature(FORM_DRAFT_FEATURE_NAME, registerFormDraft, { dedupeOptions: {} });
+}
+
+/** @deprecated Use createFormDraftFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const formDraftFeature = createFormDraftFeature();

package/packages/bundled-features/src/form-draft/handlers/cleanup.job.ts

@@ -77,7 +77,7 @@ async function releaseRowFileRefs(
     isCreateMode,
   );
   const systemUser = createSystemUser(row.tenantId);
-  const tenantDb = createTenantDb(db, row.tenantId, "system");
+  const tenantDb = createTenantDb({ db, tenantId: row.tenantId, mode: "system" });
   for (const ref of ownedRefs) {
     const forgetResult = await fileRefExecutor.forget({ id: ref.id }, systemUser, tenantDb);
     if (!forgetResult.isSuccess) {
@@ -132,7 +132,7 @@ export async function deleteStaleDraftsBatch(
   const byId = new Map(batch.map((row) => [row.id, row]));
   for (const [tenantId, ids] of groupStaleDraftIdsByTenant(batch)) {
     const systemUser = createSystemUser(tenantId);
-    const tenantDb = createTenantDb(db, tenantId, "system");
+    const tenantDb = createTenantDb({ db, tenantId, mode: "system" });
     for (const id of ids) {
       // Race: user may have saved between select and here — skip if no longer stale.
       if (!(await isDraftStillStale(db, tenantId, id, retentionDays))) {

package/packages/bundled-features/src/form-draft/index.ts

@@ -8,7 +8,7 @@ export {
 } from "./constants.js";
 export { formDraftEntity } from "./entity.js";
 export { formDraftExecutor, formDraftTable } from "./executor.js";
-export { formDraftFeature } from "./feature.js";
+export { createFormDraftFeature, formDraftFeature } from "./feature.js";
 export { discardDraftWrite } from "./handlers/discard.write.js";
 export { type GetDraftResult, getDraftQuery } from "./handlers/get.query.js";
 export { type ListDraftsResult, listDraftsQuery } from "./handlers/list.query.js";

package/packages/bundled-features/src/form-draft/lookup.ts

@@ -1,5 +1,5 @@
-import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { formDraftTable } from "./executor.js";

package/packages/bundled-features/src/form-draft-user-data/index.ts

@@ -8,14 +8,23 @@
 import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import { formDraftDeleteHook, formDraftExportHook } from "./hooks.js";
 
-export const formDraftUserDataFeature = defineFeature("form-draft-user-data", (r) => {
-  r.describe(
-    "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `form-draft` feature's `form-draft` entity. Mounts the EXT_USER_DATA export hook so a user's saved drafts are included in the user-data export bundle, and a delete hook that physically removes the user's own draft rows on forget. Kept separate from `form-draft` so form-draft consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `form-draft`.",
+export function createFormDraftUserDataFeature() {
+  return defineFeature(
+    "form-draft-user-data",
+    (r) => {
+      r.describe(
+        "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `form-draft` feature's `form-draft` entity. Mounts the EXT_USER_DATA export hook so a user's saved drafts are included in the user-data export bundle, and a delete hook that physically removes the user's own draft rows on forget. Kept separate from `form-draft` so form-draft consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `form-draft`.",
+      );
+      r.requires({ features: ["user-data-rights"] });
+      r.optionalRequires("form-draft");
+      r.useExtension(EXT_USER_DATA, "form-draft", {
+        export: formDraftExportHook,
+        delete: formDraftDeleteHook,
+      });
+    },
+    { dedupeOptions: {} },
   );
-  r.requires({ features: ["user-data-rights"] });
-  r.optionalRequires("form-draft");
-  r.useExtension(EXT_USER_DATA, "form-draft", {
-    export: formDraftExportHook,
-    delete: formDraftDeleteHook,
-  });
-});
+}
+
+/** @deprecated Use createFormDraftUserDataFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const formDraftUserDataFeature = createFormDraftUserDataFeature();

package/packages/bundled-features/src/inbound-mail-foundation/feature.ts

@@ -97,169 +97,180 @@ import {
   mailThreadTenantDestroyHook,
 } from "./tenant-destroy-hook.js";
 
-export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATION_FEATURE, (r) => {
-  r.describe(
-    "Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.",
-  );
-  r.uiHints({
-    displayLabel: "Inbound Mail · Foundation",
-    category: "notifications",
-    recommended: false,
-  });
-  // EXT_TENANT_DATA-Hook braucht den tenant-lifecycle-Host.
-  r.requires({ features: ["tenant-lifecycle"] });
+export function createInboundMailFoundationFeature() {
+  return defineFeature(
+    INBOUND_MAIL_FOUNDATION_FEATURE,
+    (r) => {
+      r.describe(
+        "Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.",
+      );
+      r.uiHints({
+        displayLabel: "Inbound Mail · Foundation",
+        category: "notifications",
+        recommended: false,
+      });
+      // EXT_TENANT_DATA-Hook braucht den tenant-lifecycle-Host.
+      r.requires({ features: ["tenant-lifecycle"] });
 
-  // 5 fine-grained domain-events (Payload-Schemas: events.ts).
-  // piiFields: "none" — address/subject/snippet are already ciphertext under the tenant subject key before append (see events.ts).
-  // "displayName" stays plaintext (often the mailbox owner's real name for
-  // personal accounts); encrypting it would break the entity-projection read
-  // path that carries it as `personal: false`.
-  r.defineEvent(MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
-    piiFields: "none",
-  });
-  r.defineEvent(MAIL_ACCOUNT_UPDATED_EVENT_SHORT, mailAccountEventPayloadSchema, {
-    piiFields: "none",
-  });
-  r.defineEvent(MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
-    piiFields: "none",
-  });
-  r.defineEvent(INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, inboundMessageEventPayloadSchema, {
-    piiFields: "none",
-  });
-  r.defineEvent(MAIL_THREAD_UPDATED_EVENT_SHORT, mailThreadEventPayloadSchema, {
-    piiFields: "none",
-  });
+      // 5 fine-grained domain-events (Payload-Schemas: events.ts).
+      // piiFields: "none" — address/subject/snippet are already ciphertext under the tenant subject key before append (see events.ts).
+      // "displayName" stays plaintext (often the mailbox owner's real name for
+      // personal accounts); encrypting it would break the entity-projection read
+      // path that carries it as `personal: false`.
+      r.defineEvent(MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
+        piiFields: "none",
+      });
+      r.defineEvent(MAIL_ACCOUNT_UPDATED_EVENT_SHORT, mailAccountEventPayloadSchema, {
+        piiFields: "none",
+      });
+      r.defineEvent(MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
+        piiFields: "none",
+      });
+      r.defineEvent(INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, inboundMessageEventPayloadSchema, {
+        piiFields: "none",
+      });
+      r.defineEvent(MAIL_THREAD_UPDATED_EVENT_SHORT, mailThreadEventPayloadSchema, {
+        piiFields: "none",
+      });
 
-  // Inline projections — apply in derselben TX wie der Append.
-  r.projection({
-    name: "mail-account",
-    source: MAIL_ACCOUNT_AGGREGATE_TYPE,
-    table: mailAccountsProjectionTable,
-    entity: mailAccountEntity,
-    apply: {
-      [MAIL_ACCOUNT_CONNECTED_EVENT_QN]: applyMailAccountConnected,
-      [MAIL_ACCOUNT_UPDATED_EVENT_QN]: applyMailAccountUpdated,
-      [MAIL_ACCOUNT_DISCONNECTED_EVENT_QN]: applyMailAccountDisconnected,
-    },
-  });
-  r.projection({
-    name: "inbound-message",
-    source: INBOUND_MESSAGE_AGGREGATE_TYPE,
-    table: inboundMessagesProjectionTable,
-    entity: inboundMessageEntity,
-    apply: {
-      [INBOUND_MESSAGE_RECEIVED_EVENT_QN]: applyInboundMessageReceived,
-    },
-  });
-  r.projection({
-    name: "mail-thread",
-    source: MAIL_THREAD_AGGREGATE_TYPE,
-    table: mailThreadsProjectionTable,
-    entity: mailThreadEntity,
-    apply: {
-      [MAIL_THREAD_UPDATED_EVENT_QN]: applyMailThreadUpdated,
-    },
-  });
+      // Inline projections — apply in derselben TX wie der Append.
+      r.projection({
+        name: "mail-account",
+        source: MAIL_ACCOUNT_AGGREGATE_TYPE,
+        table: mailAccountsProjectionTable,
+        entity: mailAccountEntity,
+        apply: {
+          [MAIL_ACCOUNT_CONNECTED_EVENT_QN]: applyMailAccountConnected,
+          [MAIL_ACCOUNT_UPDATED_EVENT_QN]: applyMailAccountUpdated,
+          [MAIL_ACCOUNT_DISCONNECTED_EVENT_QN]: applyMailAccountDisconnected,
+        },
+      });
+      r.projection({
+        name: "inbound-message",
+        source: INBOUND_MESSAGE_AGGREGATE_TYPE,
+        table: inboundMessagesProjectionTable,
+        entity: inboundMessageEntity,
+        apply: {
+          [INBOUND_MESSAGE_RECEIVED_EVENT_QN]: applyInboundMessageReceived,
+        },
+      });
+      r.projection({
+        name: "mail-thread",
+        source: MAIL_THREAD_AGGREGATE_TYPE,
+        table: mailThreadsProjectionTable,
+        entity: mailThreadEntity,
+        apply: {
+          [MAIL_THREAD_UPDATED_EVENT_QN]: applyMailThreadUpdated,
+        },
+      });
 
-  // Plugin extension-point — Provider registrieren sich via
-  // r.useExtension("inboundMailProvider", "<key>", plugin).
-  r.extendsRegistrar(INBOUND_MAIL_PROVIDER_EXTENSION, {
-    onRegister: () => {
-      // No side-effects at register-time — Lookup läuft zur Laufzeit
-      // über resolveInboundProviderForKey/-Account.
-    },
-  });
+      // Plugin extension point — providers register via
+      // r.useExtension("inboundMailProvider", "<key>", plugin).
+      r.extendsRegistrar(INBOUND_MAIL_PROVIDER_EXTENSION, {
+        onRegister: () => {
+          // No side-effects at register-time — lookup happens at runtime
+          // via resolveInboundProviderForKey/-Account.
+        },
+      });
+
+      // Sync machinery: high-frequency tick state, deliberately NOT
+      // event-sourced — r.storeTable keeps the migration DDL but excludes the
+      // tables from the projection rebuild (#494/#498 class).
+      r.storeTable(syncCursorTable, {
+        reason: "read_side.mail_sync_cursors_direct_write",
+      });
+      r.storeTable(seenMessageTable, {
+        reason: "read_side.mail_seen_messages_direct_write",
+      });
 
-  // Sync-Maschinerie: hochfrequenter Tick-State, bewusst NICHT
-  // event-sourced — r.storeTable hält die Migration-DDL, nimmt die
-  // Tabellen aber aus dem Projection-Rebuild (#494/#498-Klasse).
-  r.storeTable(syncCursorTable, {
-    reason: "read_side.mail_sync_cursors_direct_write",
-  });
-  r.storeTable(seenMessageTable, {
-    reason: "read_side.mail_seen_messages_direct_write",
-  });
+      // Write-Handler:
+      //   - ingest-message: programmatic (Supervisor/Poll, SystemAdmin)
+      //   - connect/update/disconnect-account: Lifecycle
+      r.writeHandler(ingestMessageHandler);
+      r.writeHandler(connectAccountHandler);
+      r.writeHandler(updateAccountHandler);
+      r.writeHandler(disconnectAccountHandler);
 
-  // Write-Handler:
-  //   - ingest-message: programmatic (Supervisor/Poll, SystemAdmin)
-  //   - connect/update/disconnect-account: Lifecycle
-  r.writeHandler(ingestMessageHandler);
-  r.writeHandler(connectAccountHandler);
-  r.writeHandler(updateAccountHandler);
-  r.writeHandler(disconnectAccountHandler);
+      // List-Queries (PII-decrypted, scope-gefiltert).
+      r.queryHandler(listAccountsQuery);
+      r.queryHandler(listMessagesQuery);
 
-  // List-Queries (PII-decrypted, scope-gefiltert).
-  r.queryHandler(listAccountsQuery);
-  r.queryHandler(listMessagesQuery);
+      // Entity-genaue GDPR-Destroy-Hooks — der gdpr-storage-Boot-Validator
+      // prueft die EXT_TENANT_DATA-Registrierung pro tenant-subject-Entity.
+      r.useExtension(EXT_TENANT_DATA, "mail-account", {
+        destroy: mailAccountTenantDestroyHook,
+        escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
+      });
+      r.useExtension(EXT_TENANT_DATA, "inbound-message", {
+        destroy: inboundMessageTenantDestroyHook,
+        escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
+      });
+      r.useExtension(EXT_TENANT_DATA, "mail-thread", {
+        destroy: mailThreadTenantDestroyHook,
+        escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
+      });
 
-  // Entity-genaue GDPR-Destroy-Hooks — der gdpr-storage-Boot-Validator
-  // prueft die EXT_TENANT_DATA-Registrierung pro tenant-subject-Entity.
-  r.useExtension(EXT_TENANT_DATA, "mail-account", {
-    destroy: mailAccountTenantDestroyHook,
-    escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
-  });
-  r.useExtension(EXT_TENANT_DATA, "inbound-message", {
-    destroy: inboundMessageTenantDestroyHook,
-    escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
-  });
-  r.useExtension(EXT_TENANT_DATA, "mail-thread", {
-    destroy: mailThreadTenantDestroyHook,
-    escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
-  });
+      // Data-Retention (#957) — perTenant fan-out (one run per tenant, like
+      // data-retention:retention-cleanup): runInboundMailRetention's raw query
+      // helpers need the unfiltered runner, so the handler declares escapeHatch
+      // and reaches for ctx.db.unsafeRaw(). Without this cron, read_inbound_messages
+      // + the bodies grow unbounded (GDPR Art. 5).
+      const INBOUND_MAIL_RETENTION_REASON =
+        "inbound-mail retention runs raw deletes; every statement filters by this run's tenantId";
+      r.job({
+        name: "inbound-mail-retention",
+        trigger: { cron: "0 3 * * *" },
+        perTenant: true,
+        concurrency: "skip",
+        escapeHatch: { reason: INBOUND_MAIL_RETENTION_REASON },
+        handler: async (_payload, ctx) => {
+          if (!ctx.registry) {
+            throw new Error(
+              "inbound-mail-retention: ctx.registry required (JobContext incomplete)",
+            );
+          }
+          const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+          if (tenantId === undefined) {
+            // skip: cron fired without a perTenant fan-out tenant — nothing scoped
+            return;
+          }
+          const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
+          const retentionDb = ctx.db.unsafeRaw() as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
 
-  // Data-Retention (#957) — perTenant fan-out (one run per tenant, like
-  // data-retention:retention-cleanup): runInboundMailRetention's raw query
-  // helpers need the unfiltered runner, so the handler declares escapeHatch
-  // and reaches for ctx.db.unsafeRaw(). Without this cron, read_inbound_messages
-  // + the bodies grow unbounded (GDPR Art. 5).
-  const INBOUND_MAIL_RETENTION_REASON =
-    "inbound-mail retention runs raw deletes; every statement filters by this run's tenantId";
-  r.job({
-    name: "inbound-mail-retention",
-    trigger: { cron: "0 3 * * *" },
-    perTenant: true,
-    concurrency: "skip",
-    escapeHatch: { reason: INBOUND_MAIL_RETENTION_REASON },
-    handler: async (_payload, ctx) => {
-      if (!ctx.registry) {
-        throw new Error("inbound-mail-retention: ctx.registry required (JobContext incomplete)");
-      }
-      const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
-      if (tenantId === undefined) {
-        // skip: cron fired without a perTenant fan-out tenant — nothing scoped
-        return;
-      }
-      const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
-      const retentionDb = ctx.db.unsafeRaw() as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+          // Body-Objekte liegen in file-foundation. Provider lazy + memoized —
+          // heute schreibt der Ingest kein bodyRef (storeBody-Hook ungebunden),
+          // der Provider wird also nie gebaut. Sobald storeBody wired ist, raeumt
+          // die Retention die Bodies mit ab.
+          let providerPromise: Promise<FileStorageProvider> | null = null;
+          const deleteBodyObject = async (bodyRef: string): Promise<void> => {
+            if (!providerPromise) {
+              providerPromise = createFileProviderForTenant(
+                { config: ctx.config, registry: ctx.registry },
+                tenantId,
+              );
+            }
+            const provider = await providerPromise;
+            await provider.delete(bodyRef);
+          };
 
-      // Body-Objekte liegen in file-foundation. Provider lazy + memoized —
-      // heute schreibt der Ingest kein bodyRef (storeBody-Hook ungebunden),
-      // der Provider wird also nie gebaut. Sobald storeBody wired ist, raeumt
-      // die Retention die Bodies mit ab.
-      let providerPromise: Promise<FileStorageProvider> | null = null;
-      const deleteBodyObject = async (bodyRef: string): Promise<void> => {
-        if (!providerPromise) {
-          providerPromise = createFileProviderForTenant(
-            { config: ctx.config, registry: ctx.registry },
+          const report = await runInboundMailRetention({
+            db: retentionDb,
             tenantId,
-          );
-        }
-        const provider = await providerPromise;
-        await provider.delete(bodyRef);
-      };
-
-      const report = await runInboundMailRetention({
-        db: retentionDb,
-        tenantId,
-        now: T.Now.instant(),
-        deleteBodyObject,
+            now: T.Now.instant(),
+            deleteBodyObject,
+          });
+          if (report.bodyObjectErrors > 0) {
+            // biome-ignore lint/suspicious/noConsole: operator-visibility for failed body deletes
+            console.warn(
+              `[inbound-mail-foundation:inbound-mail-retention] tenant=${tenantId} bodyObjectErrors=${report.bodyObjectErrors}`,
+            );
+          }
+        },
       });
-      if (report.bodyObjectErrors > 0) {
-        // biome-ignore lint/suspicious/noConsole: operator-visibility for failed body deletes
-        console.warn(
-          `[inbound-mail-foundation:inbound-mail-retention] tenant=${tenantId} bodyObjectErrors=${report.bodyObjectErrors}`,
-        );
-      }
     },
-  });
-});
+    { dedupeOptions: {} },
+  );
+}
+
+/** @deprecated Use createInboundMailFoundationFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const inboundMailFoundationFeature = createInboundMailFoundationFeature();

package/packages/bundled-features/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -20,12 +20,11 @@
 // SystemAdmin-only: Aufrufer ist der Watch/Sync-Supervisor bzw. der
 // Poll-Cron mit programmatic SystemUser — nie ein Tenant-Request.
 
-import { countWhere } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
   encryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import { acquireNamespacedAdvisoryLock } from "@cosmicdrift/kumiko-framework/db";
+import { acquireNamespacedAdvisoryLock, countWhere } from "@cosmicdrift/kumiko-framework/db";
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";

package/packages/bundled-features/src/inbound-mail-foundation/index.ts

@@ -54,7 +54,7 @@ export {
   mailAccountEventPayloadSchema,
   mailThreadEventPayloadSchema,
 } from "./events.js";
-export { inboundMailFoundationFeature } from "./feature.js";
+export { createInboundMailFoundationFeature, inboundMailFoundationFeature } from "./feature.js";
 export {
   createOAuthAccessTokenManager,
   inboundRefreshTokenSecretOptions,

package/packages/bundled-features/src/inbound-mail-foundation/oauth-access-token.ts

@@ -16,8 +16,11 @@
 // audit context. SecretsContext does not cache values (only unwrapped DEKs),
 // so the read always reflects the latest committed write.
 
-import { transaction } from "@cosmicdrift/kumiko-framework/bun-db";
-import { acquireNamespacedAdvisoryLock, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  acquireNamespacedAdvisoryLock,
+  type DbConnection,
+  transaction,
+} from "@cosmicdrift/kumiko-framework/db";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { InboundMailAuthMethods, inboundCredentialSecretKey } from "./constants.js";

package/packages/bundled-features/src/inbound-mail-foundation/projection.ts

@@ -18,11 +18,12 @@
 // in den list-queries.
 
 import {
+  buildEntityTable,
+  type EntityTableMeta,
   insertOnConflictDoNothing,
   requireEntityTableMeta,
   upsertOnConflict,
-} from "@cosmicdrift/kumiko-framework/bun-db";
-import { buildEntityTable, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+} from "@cosmicdrift/kumiko-framework/db";
 import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
 import { inboundMessageEntity, mailAccountEntity, mailThreadEntity } from "./entities.js";
 import type {

package/packages/bundled-features/src/inbound-mail-foundation/watch-supervisor.ts

@@ -44,12 +44,12 @@
 // only while the connection is open. Losing the claim (Redis outage, TTL
 // exceeded) tears down the local watcher instead of racing a new holder.
 
-import { fetchOne, insertOne, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
   decryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne, insertOne, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/db";
 import type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";