@cosmicdrift/kumiko-bundled-features 0.367.0 → 0.369.0

package/dist/files-tenant-data/hooks.js

@@ -45,8 +45,7 @@
 //     matches would still delete it out from under the tenant that claimed
 //     its original. Batched: one existence query per chunk of listed keys,
 //     not one query per key.
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser, parseTenantId, } from "@cosmicdrift/kumiko-framework/engine";
 import { assertSafeStorageKey, fileRefEntity, fileRefsTable, storageKeyStemPrefix, tenantStoragePrefixes, } from "@cosmicdrift/kumiko-framework/files";
 import { runChunkedMigration } from "../shared/index.js";

package/dist/folders/feature.d.ts

@@ -2,7 +2,7 @@ import { type AccessRule, type EntityDefinition } from "@cosmicdrift/kumiko-fram
 type FoldersToggleable = {
     readonly default: boolean;
 };
-export declare const foldersFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+declare const defaultFoldersFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;
 };
 export type FoldersFeatureOptions = {
@@ -41,5 +41,9 @@ export type FoldersFeatureOptions = {
      *  otherwise considers every registered entity as a candidate host. */
     readonly parents?: readonly string[];
 };
-export declare function createFoldersFeature(opts?: FoldersFeatureOptions): typeof foldersFeature;
+export declare function createFoldersFeature(opts?: FoldersFeatureOptions): typeof defaultFoldersFeature;
+/** @deprecated Use createFoldersFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export declare const foldersFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};
 export {};

package/dist/folders/feature.js

@@ -62,7 +62,7 @@ function registerFolders(r, access, toggleable, ownership, parents) {
         description: "Lists the folder-membership rows of the caller's tenant; filter on entityId to learn which folder one entity sits in, or on folderId to list everything filed into a folder.",
     }));
 }
-export const foldersFeature = defineFeature(FOLDERS_FEATURE_NAME, (r) => registerFolders(r, DEFAULT_FOLDER_ACCESS, undefined, undefined, undefined));
+const defaultFoldersFeature = defineFeature(FOLDERS_FEATURE_NAME, (r) => registerFolders(r, DEFAULT_FOLDER_ACCESS, undefined, undefined, undefined));
 function resolveAccess(opts) {
     if (opts.access !== undefined)
         return opts.access;
@@ -78,7 +78,7 @@ export function createFoldersFeature(opts = {}) {
         opts.toggleable === undefined &&
         opts.ownership === undefined &&
         opts.parents === undefined) {
-        return foldersFeature;
+        return defaultFoldersFeature;
     }
     assertNoWhereRuleInOwnershipWrite("createFoldersFeature", opts.ownership?.write);
     if (opts.parents !== undefined && opts.parents.length === 0) {
@@ -90,3 +90,5 @@ export function createFoldersFeature(opts = {}) {
     const access = resolveAccess(opts);
     return defineFeature(FOLDERS_FEATURE_NAME, (r) => 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/dist/folders-user-data/index.d.ts

@@ -1,3 +1,7 @@
+export declare function createFoldersUserDataFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};
+/** @deprecated Use createFoldersUserDataFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
 export declare const foldersUserDataFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;
 };

package/dist/folders-user-data/index.js

@@ -5,20 +5,24 @@
 // folders stays usable without the user-data-rights stack. Mirrors credit-user-data.
 import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import { folderAssignmentDeleteHook, folderAssignmentExportHook, folderDeleteHook, 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`.");
-    // 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,
-    });
-});
+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: {} });
+}
+/** @deprecated Use createFoldersUserDataFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const foldersUserDataFeature = createFoldersUserDataFeature();

package/dist/form-draft/db/queries/cleanup.js

@@ -1,4 +1,4 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 // COALESCE(modified_at, inserted_at) — a draft's "last touched" timestamp is
 // modified_at once the upsert path (save.write.ts) has updated it at least

package/dist/form-draft/db/queries/draft-count.js

@@ -1,4 +1,4 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 // COUNT(*), not selectMany(...).length — save.write.ts checks this on every
 // create, and a draft's `values` blob can be up to FORM_DRAFT_VALUES_MAX_BYTES
 // (64KB); loading up to FORM_DRAFT_MAX_PER_OWNER full rows just to count them

package/dist/form-draft/db/queries/owned-file-refs.js

@@ -1,5 +1,4 @@
-import { instantToTimestamptzParam, unsafeReadRetrying, } from "@cosmicdrift/kumiko-framework/bun-db";
-import { toPostgresArrayLiteral } from "@cosmicdrift/kumiko-framework/db";
+import { instantToTimestamptzParam, toPostgresArrayLiteral, unsafeReadRetrying, } from "@cosmicdrift/kumiko-framework/db";
 // Narrows a draft blob's raw FileRef-shaped storageKeys (collectDraftFileRefKeys
 // output — extracted from free-form, client-supplied JSON, issue #1889) down to
 // the ones with a real, non-deleted file_refs row owned by this exact

package/dist/form-draft/feature.d.ts

@@ -1,3 +1,7 @@
+export declare function createFormDraftFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};
+/** @deprecated Use createFormDraftFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
 export declare const formDraftFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;
 };

package/dist/form-draft/feature.js

@@ -41,4 +41,8 @@ function registerFormDraft(r) {
         handler: (payload, ctx) => cleanupDraftsJob(payload, ctx, ctx.db.unsafeRaw()),
     });
 }
-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/dist/form-draft/handlers/cleanup.job.js

@@ -37,7 +37,7 @@ async function releaseRowFileRefs(row, db, fileProviderResolver, log) {
     const isCreateMode = row.draftKey.includes(":new:");
     const ownedRefs = await filterOwnedFileRefs(db, row.tenantId, row.ownerId, keys, row.insertedAt, 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) {
@@ -78,7 +78,7 @@ export async function deleteStaleDraftsBatch(batch, db, retentionDays, log) {
     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/dist/form-draft/index.d.ts

@@ -1,7 +1,7 @@
 export { FORM_DRAFT_ACCESS, FORM_DRAFT_FEATURE_NAME, FORM_DRAFT_KEY_MAX_LENGTH, FORM_DRAFT_UNIQUE_KEY_CONSTRAINT, FormDraftHandlers, FormDraftQueries, } 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/dist/form-draft/index.js

@@ -1,7 +1,7 @@
 export { FORM_DRAFT_ACCESS, FORM_DRAFT_FEATURE_NAME, FORM_DRAFT_KEY_MAX_LENGTH, FORM_DRAFT_UNIQUE_KEY_CONSTRAINT, FormDraftHandlers, FormDraftQueries, } 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 { getDraftQuery } from "./handlers/get.query.js";
 export { listDraftsQuery } from "./handlers/list.query.js";

package/dist/form-draft/lookup.js

@@ -1,4 +1,4 @@
-import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { formDraftTable } from "./executor.js";
 // Shared by save (upsert lookup + race re-lookup), discard, and get — always
 // scoped by tenantId + ownerId + draftKey, tenantId included explicitly

package/dist/form-draft-user-data/index.d.ts

@@ -1,3 +1,7 @@
+export declare function createFormDraftUserDataFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};
+/** @deprecated Use createFormDraftUserDataFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
 export declare const formDraftUserDataFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;
 };

package/dist/form-draft-user-data/index.js

@@ -6,12 +6,16 @@
 // pull a hard dependency. Mirrors notes-history-user-data.
 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`.");
-    r.requires({ features: ["user-data-rights"] });
-    r.optionalRequires("form-draft");
-    r.useExtension(EXT_USER_DATA, "form-draft", {
-        export: formDraftExportHook,
-        delete: formDraftDeleteHook,
-    });
-});
+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: {} });
+}
+/** @deprecated Use createFormDraftUserDataFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const formDraftUserDataFeature = createFormDraftUserDataFeature();

package/dist/inbound-mail-foundation/feature.d.ts

@@ -1,3 +1,7 @@
+export declare function createInboundMailFoundationFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};
+/** @deprecated Use createInboundMailFoundationFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
 export declare const inboundMailFoundationFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;
 };

package/dist/inbound-mail-foundation/feature.js

@@ -54,151 +54,155 @@ import { updateAccountHandler } from "./handlers/update-account.write.js";
 import { applyInboundMessageReceived, applyMailAccountConnected, applyMailAccountDisconnected, applyMailAccountUpdated, applyMailThreadUpdated, inboundMessagesProjectionTable, mailAccountsProjectionTable, mailThreadsProjectionTable, } from "./projection.js";
 import { runInboundMailRetention } from "./retention-sweep.js";
 import { INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON, inboundMessageTenantDestroyHook, mailAccountTenantDestroyHook, 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"] });
-    // 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,
-        },
-    });
-    // 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.
-        },
-    });
-    // 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);
-    // 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 },
-    });
-    // 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(); // @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 = null;
-            const deleteBodyObject = async (bodyRef) => {
-                if (!providerPromise) {
-                    providerPromise = createFileProviderForTenant({ config: ctx.config, registry: ctx.registry }, tenantId);
+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",
+        });
+        // 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 — 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",
+        });
+        // 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);
+        // 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 provider = await providerPromise;
-                await provider.delete(bodyRef);
-            };
-            const report = await runInboundMailRetention({
-                db: retentionDb,
-                tenantId,
-                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}`);
-            }
-        },
-    });
-});
+                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(); // @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 = null;
+                const deleteBodyObject = async (bodyRef) => {
+                    if (!providerPromise) {
+                        providerPromise = createFileProviderForTenant({ config: ctx.config, registry: ctx.registry }, tenantId);
+                    }
+                    const provider = await providerPromise;
+                    await provider.delete(bodyRef);
+                };
+                const report = await runInboundMailRetention({
+                    db: retentionDb,
+                    tenantId,
+                    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}`);
+                }
+            },
+        });
+    }, { dedupeOptions: {} });
+}
+/** @deprecated Use createInboundMailFoundationFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const inboundMailFoundationFeature = createInboundMailFoundationFeature();

package/dist/inbound-mail-foundation/handlers/ingest-message.write.js

@@ -19,9 +19,8 @@
 //
 // 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 { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";

package/dist/inbound-mail-foundation/index.d.ts

@@ -3,7 +3,7 @@ export { createInboundMailConnectRoutes, type InboundMailConnectRoutesOptions, }
 export { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION, type InboundMailAccountStatus, InboundMailAccountStatuses, type InboundMailAuthMethod, InboundMailAuthMethods, InboundMailFoundationHandlers, InboundMailFoundationQueries, inboundCredentialSecretKey, } from "./constants.js";
 export { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity, MAIL_ACCOUNT_PII_FIELDS, MAIL_THREAD_PII_FIELDS, mailAccountEntity, mailThreadEntity, seenMessageEntity, seenMessageTable, syncCursorEntity, syncCursorTable, } from "./entities.js";
 export { INBOUND_MESSAGE_AGGREGATE_TYPE, INBOUND_MESSAGE_RECEIVED_EVENT_QN, INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, type InboundMessageEventHeaders, type InboundMessageEventPayload, inboundMessageEventPayloadSchema, MAIL_ACCOUNT_AGGREGATE_TYPE, MAIL_ACCOUNT_CONNECTED_EVENT_QN, MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, MAIL_ACCOUNT_DISCONNECTED_EVENT_QN, MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, MAIL_ACCOUNT_UPDATED_EVENT_QN, MAIL_ACCOUNT_UPDATED_EVENT_SHORT, MAIL_THREAD_AGGREGATE_TYPE, MAIL_THREAD_UPDATED_EVENT_QN, MAIL_THREAD_UPDATED_EVENT_SHORT, type MailAccountEventHeaders, type MailAccountEventPayload, type MailThreadEventPayload, mailAccountEventPayloadSchema, mailThreadEventPayloadSchema, } from "./events.js";
-export { inboundMailFoundationFeature } from "./feature.js";
+export { createInboundMailFoundationFeature, inboundMailFoundationFeature } from "./feature.js";
 export { createOAuthAccessTokenManager, inboundRefreshTokenSecretOptions, type OAuthAccessTokenManager, type OAuthAccessTokenManagerDeps, usesFoundationManagedOAuth, } from "./oauth-access-token.js";
 export { type OAuthStatePayload, signOAuthState, type VerifyOAuthStateResult, verifyOAuthState, } from "./oauth-state.js";
 export { inboundMessagesProjectionTable, mailAccountsProjectionTable, mailThreadsProjectionTable, } from "./projection.js";

package/dist/inbound-mail-foundation/index.js

@@ -4,7 +4,7 @@ export { createInboundMailConnectRoutes, } from "./connect-routes.js";
 export { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION, InboundMailAccountStatuses, InboundMailAuthMethods, InboundMailFoundationHandlers, InboundMailFoundationQueries, inboundCredentialSecretKey, } from "./constants.js";
 export { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity, MAIL_ACCOUNT_PII_FIELDS, MAIL_THREAD_PII_FIELDS, mailAccountEntity, mailThreadEntity, seenMessageEntity, seenMessageTable, syncCursorEntity, syncCursorTable, } from "./entities.js";
 export { INBOUND_MESSAGE_AGGREGATE_TYPE, INBOUND_MESSAGE_RECEIVED_EVENT_QN, INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, inboundMessageEventPayloadSchema, MAIL_ACCOUNT_AGGREGATE_TYPE, MAIL_ACCOUNT_CONNECTED_EVENT_QN, MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, MAIL_ACCOUNT_DISCONNECTED_EVENT_QN, MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, MAIL_ACCOUNT_UPDATED_EVENT_QN, MAIL_ACCOUNT_UPDATED_EVENT_SHORT, MAIL_THREAD_AGGREGATE_TYPE, MAIL_THREAD_UPDATED_EVENT_QN, MAIL_THREAD_UPDATED_EVENT_SHORT, mailAccountEventPayloadSchema, mailThreadEventPayloadSchema, } from "./events.js";
-export { inboundMailFoundationFeature } from "./feature.js";
+export { createInboundMailFoundationFeature, inboundMailFoundationFeature } from "./feature.js";
 export { createOAuthAccessTokenManager, inboundRefreshTokenSecretOptions, usesFoundationManagedOAuth, } from "./oauth-access-token.js";
 export { signOAuthState, verifyOAuthState, } from "./oauth-state.js";
 export { inboundMessagesProjectionTable, mailAccountsProjectionTable, mailThreadsProjectionTable, } from "./projection.js";