@cosmicdrift/kumiko-bundled-features 0.365.1 → 0.366.0

package/dist/config/feature.js

@@ -24,7 +24,7 @@ export function createConfigFeature() {
         // projection write in one TX. Subscribers that need config-change
         // semantics listen to those auto-events via r.multiStreamProjection
         // (see docs/plans/architecture/event-sourcing-pivot.md §4.7).
-        r.entity("config-value", configValueEntity);
+        r.entity({ name: "config-value", ...configValueEntity });
         const handlers = {
             set: r.writeHandler(setWrite),
             reset: r.writeHandler(resetWrite),

package/dist/custom-fields/feature.js

@@ -10,7 +10,7 @@
 // (crypto-shredding, event ciphertext, forget pipeline).
 //
 // **Was diese Feature liefert (B1 + B2, 2026-05-23):**
-//   1. r.entity("field-definition") — Definition-Storage (event-sourced).
+//   1. r.entity({ name: "field-definition" }) — Definition-Storage (event-sourced).
 //   2. define-tenant-field / define-system-field — RBAC write-handlers für
 //      Definition-CRUD.
 //   3. delete-tenant-field / delete-system-field — RBAC write-handlers.
@@ -75,7 +75,7 @@ function registerCustomFields(r, variant) {
         category: "data",
         recommended: false,
     });
-    r.entity("field-definition", fieldDefinitionEntity);
+    r.entity({ name: "field-definition", ...fieldDefinitionEntity });
     // Event-types — qualified als "custom-fields:event:<short-name>".
     // Returned EventDefs liefern .name als compile-time literal-typed string,
     // den Handler + MSP-keys konsumieren statt Template-Literal-Konstruktion.

package/dist/custom-fields/wire-for-entity.js

@@ -28,8 +28,8 @@ export function customFieldsField() {
 // Consumer-side:
 //
 //   defineFeature("property-mgmt", (r) => {
-//     r.entity("property", propertyEntity);  // muss customFieldsField() haben
-//     r.requires(CUSTOM_FIELDS_FEATURE_NAME);
+//     r.entity({ name: "property", ...propertyEntity });  // muss customFieldsField() haben
+//     r.requires({ features: [CUSTOM_FIELDS_FEATURE_NAME] });
 //     wireCustomFieldsFor(r, "property", propertyTable);
 //   });
 //
@@ -158,18 +158,22 @@ export function wireCustomFieldsFor(r, entityName, entityTable) {
     });
     // postQuery-hook: flatten row.customFields jsonb auf root-level der
     // API-response. Spec-Promise Z.4 "indistinguishable von Stammfeldern".
-    r.hook("postQuery", { allOf: entityName }, async ({ rows }) => ({
-        rows: rows.map((row) => {
-            const customFields = row["customFields"];
-            if (customFields && typeof customFields === "object" && !Array.isArray(customFields)) {
-                return {
-                    ...customFields, // @cast-boundary db-row jsonb runtime-untyped
-                    ...row, // base fields win: a custom fieldKey named `id`/`name` must not shadow the real column
-                };
-            }
-            return row;
+    r.hook({
+        type: "postQuery",
+        target: { allOf: entityName },
+        handler: async ({ rows }) => ({
+            rows: rows.map((row) => {
+                const customFields = row["customFields"];
+                if (customFields && typeof customFields === "object" && !Array.isArray(customFields)) {
+                    return {
+                        ...customFields, // @cast-boundary db-row jsonb runtime-untyped
+                        ...row, // base fields win: a custom fieldKey named `id`/`name` must not shadow the real column
+                    };
+                }
+                return row;
+            }),
         }),
-    }));
+    });
     // Search-Payload-Extension: customFields-keys flach ins Index-Doc.
     // Anders als postQuery-hook (der ALLE keys merged) trägt der Search-
     // Contributor nur die als searchable=true definierten fields bei. v1

package/dist/data-retention/feature.js

@@ -37,7 +37,7 @@ export function createDataRetentionFeature() {
             category: "compliance",
             recommended: false,
         });
-        r.entity("tenant-retention-override", tenantRetentionOverrideEntity);
+        r.entity({ name: "tenant-retention-override", ...tenantRetentionOverrideEntity });
         // S2.D3: Cross-Feature-API fuer Forget-Flow + Cleanup-Job
         r.exposesApi("retention.policyFor");
         r.queryHandler(policyForQuery);

package/dist/data-retention/presets.d.ts

@@ -1,9 +1,9 @@
 import type { RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
 /**
- * Pro Entity-Name gemappte Retention-Policy. Entity-Namen sind der
- * String aus r.entity("name", ...) — kebab-case oder lowercase.
- * Cleanup-Job iteriert alle bekannten Entities; was nicht im Preset
- * steht, fällt auf Entity-Default (Layer 1) zurück.
+ * Retention policy keyed by entity name, i.e. the `name` from
+ * r.entity({ name, ... }) (kebab-case or lowercase). The cleanup job walks
+ * all known entities; anything missing from the preset falls back to the
+ * entity default (layer 1).
  */
 export type RetentionPreset = Readonly<Record<string, RetentionDef>>;
 export type RetentionPresetKey = "default" | "dsgvo-basic" | "dsgvo-hgb" | "swiss-dsg";

package/dist/delivery/db/queries/address-opt-outs.d.ts

@@ -2,4 +2,4 @@ import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 export type AddressOptOutKey = string;
 export declare function addressOptOutKey(addressHash: string, channel: string): AddressOptOutKey;
-export declare function selectOptedOutAddresses(db: DbConnection, tenantId: TenantId, notificationType: string, addressHashes: readonly string[]): Promise<ReadonlySet<AddressOptOutKey>>;
+export declare function selectOptedOutAddresses(db: DbConnection, tenantId: TenantId, notificationTypeNames: readonly string[], addressHashes: readonly string[]): Promise<ReadonlySet<AddressOptOutKey>>;

package/dist/delivery/db/queries/address-opt-outs.js

@@ -7,9 +7,13 @@ export function addressOptOutKey(addressHash, channel) {
 // ("*") semantics for address opt-outs, the token that creates a row always
 // carries one concrete notificationType/channel pair. One query covers every
 // recipient of a notify() call.
-export async function selectOptedOutAddresses(db, tenantId, notificationType, addressHashes) {
+export async function selectOptedOutAddresses(db, tenantId, notificationTypeNames, addressHashes) {
     if (addressHashes.length === 0)
         return new Set();
-    const rows = await selectMany(db, notificationAddressOptOutsTable, { tenantId, notificationType, addressHash: { in: addressHashes } });
+    const rows = await selectMany(db, notificationAddressOptOutsTable, {
+        tenantId,
+        notificationType: { in: notificationTypeNames },
+        addressHash: { in: addressHashes },
+    });
     return new Set(rows.map((row) => addressOptOutKey(row.addressHash, row.channel)));
 }

package/dist/delivery/db/queries/preferences.d.ts

@@ -5,4 +5,4 @@ export type NotificationPreferenceRow = {
     readonly channel: string;
     readonly enabled: boolean;
 };
-export declare function selectNotificationPreferences(db: DbConnection, tenantId: TenantId, userId: string, notificationType: string, channelName: string): Promise<readonly NotificationPreferenceRow[]>;
+export declare function selectNotificationPreferences(db: DbConnection, tenantId: TenantId, userId: string, notificationTypeNames: readonly string[], channelName: string): Promise<readonly NotificationPreferenceRow[]>;

package/dist/delivery/db/queries/preferences.js

@@ -1,13 +1,13 @@
 import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 // @wrapper-known semantic-alias
-export async function selectNotificationPreferences(db, tenantId, userId, notificationType, channelName) {
+export async function selectNotificationPreferences(db, tenantId, userId, notificationTypeNames, channelName) {
     return unsafeReadRetrying(db, `SELECT notification_type AS "notificationType", channel, enabled
      FROM read_notification_preferences
      WHERE tenant_id = $1
        AND user_id = $2
        AND (
-         (notification_type = $3 AND channel = $4)
+         (notification_type = ANY($3::text[]) AND channel = $4)
          OR (notification_type = '*' AND channel = $4)
-         OR (notification_type = $3 AND channel = '*')
-       )`, [tenantId, userId, notificationType, channelName]);
+         OR (notification_type = ANY($3::text[]) AND channel = '*')
+       )`, [tenantId, userId, notificationTypeNames, channelName]);
 }

package/dist/delivery/delivery-service.js

@@ -12,6 +12,7 @@ import { buildChannelContext } from "./channel-context.js";
 import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryIdempotencyRedisKey, deliveryPriorityRank, } from "./constants.js";
 import { addressOptOutKey, selectOptedOutAddresses, } from "./db/queries/address-opt-outs.js";
 import { selectNotificationPreferences } from "./db/queries/preferences.js";
+import { notificationTypeNames } from "./notification-type-aliases.js";
 import { isDeliveryChannelPlugin, } from "./types.js";
 export function redactedMessageOf(err) {
     return redactErrorText(err instanceof Error ? err.message : String(err));
@@ -292,7 +293,7 @@ export function createDeliveryService(options) {
             if (addressHash !== undefined)
                 addressHashes.add(addressHash);
         }
-        return selectOptedOutAddresses(run.db, tenantId, notificationType, [...addressHashes]);
+        return selectOptedOutAddresses(run.db, tenantId, notificationTypeNames(registry, notificationType), [...addressHashes]);
     }
     function isAddressSuppressed(suppressed, address, channelName) {
         const addressHash = hashUnsubscribeAddress(address);
@@ -354,13 +355,19 @@ export function createDeliveryService(options) {
     //   { type: "orderAssigned", channel: "*", enabled: true }  enables orderAssigned everywhere
     //   → orderAssigned on inApp: disabled (conservative) unless an exact entry overrides.
     async function isChannelEnabled(run, userId, tenantId, notificationType, channelName) {
-        const prefs = await selectNotificationPreferences(run.db, tenantId, userId, notificationType, channelName);
+        const prefs = await selectNotificationPreferences(run.db, tenantId, userId, notificationTypeNames(registry, notificationType), channelName);
         if (prefs.length === 0)
             return true;
         // Exact match (both specific) wins over any wildcard
         const exact = prefs.find((p) => p.notificationType === notificationType && p.channel === channelName);
         if (exact)
             return exact.enabled;
+        // Rows stored under a former name: the user's choice from before the rename
+        const aliasExact = prefs.filter((p) => p.notificationType !== "*" &&
+            p.notificationType !== notificationType &&
+            p.channel === channelName);
+        if (aliasExact.length > 0)
+            return !aliasExact.some((p) => p.enabled === false);
         // Only wildcards matched: any disabled entry disables delivery (deterministic
         // and conservative — DB ordering no longer decides the outcome).
         return !prefs.some((p) => p.enabled === false);

package/dist/delivery/feature.js

@@ -27,18 +27,22 @@ export function createDeliveryFeature(options) {
         });
         r.systemScope();
         // delivery-log's tenantId column has refEntity: "tenant:tenant" (boot-checked).
-        r.requires("tenant");
+        r.requires({ features: ["tenant"] });
         // Backing table: the (tenant,user,type,channel) uniqueIndex lives only on
         // the physical table, not on the entity fields, so the generator would
         // otherwise omit it → duplicate preference rows on concurrent upserts.
-        r.entity("notification-preference", notificationPreferenceEntity, {
-            table: notificationPreferencesTable,
+        r.entity({
+            name: "notification-preference",
+            ...notificationPreferenceEntity,
+            backingTable: notificationPreferencesTable,
         });
         // Same ride-along reason as notification-preference above: the
         // (tenant,addressHash,type,channel) uniqueIndex lives only on the
         // physical table.
-        r.entity("notification-address-opt-out", notificationAddressOptOutEntity, {
-            table: notificationAddressOptOutsTable,
+        r.entity({
+            name: "notification-address-opt-out",
+            ...notificationAddressOptOutEntity,
+            backingTable: notificationAddressOptOutsTable,
         });
         r.storeTable(deliveryAttemptsTableMeta, {
             reason: "read_side.delivery_attempt_log",

package/dist/delivery/handlers/resubscribe-address.write.js

@@ -2,6 +2,7 @@ import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { removeAddressOptOut } from "../address-opt-out.js";
+import { currentNotificationType, notificationTypeNames } from "../notification-type-aliases.js";
 export const resubscribeAddressWrite = defineWriteHandler({
     name: "resubscribeAddress",
     schema: z.object({
@@ -18,7 +19,8 @@ export const resubscribeAddressWrite = defineWriteHandler({
     agent: { expose: false, risk: "high" },
     description: "Removes a no-account address opt-out for one notificationType/channel combination; dispatched by the signed resubscribe route, not meant for UI callers.",
     handler: async (event, ctx) => {
-        const { addressHash, notificationType, channel } = event.payload;
+        const { addressHash, channel } = event.payload;
+        const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
         const { tenantId } = event.user;
         if (!ctx.systemDb) {
             throw new InternalError({
@@ -26,14 +28,16 @@ export const resubscribeAddressWrite = defineWriteHandler({
             });
         }
         const db = ctx.systemDb.assertTenantMatch(tenantId);
-        const result = await removeAddressOptOut(db, event.user, {
-            tenantId,
-            addressHash,
-            notificationType,
-            channel,
-        });
-        if (!result.isSuccess)
-            return result;
+        for (const name of notificationTypeNames(ctx.registry, notificationType)) {
+            const result = await removeAddressOptOut(db, event.user, {
+                tenantId,
+                addressHash,
+                notificationType: name,
+                channel,
+            });
+            if (!result.isSuccess)
+                return result;
+        }
         return { isSuccess: true, data: { notificationType, channel } };
     },
 });

package/dist/delivery/handlers/resubscribe-user.write.js

@@ -1,6 +1,7 @@
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { currentNotificationType } from "../notification-type-aliases.js";
 import { upsertPreference } from "../upsert-preference.js";
 export const resubscribeUserWrite = defineWriteHandler({
     name: "resubscribeUser",
@@ -16,7 +17,8 @@ export const resubscribeUserWrite = defineWriteHandler({
     agent: { expose: false },
     description: "Re-enables one notification type and channel combination for the userId carried in a verified unsubscribe token; dispatched by the signed resubscribe route, not meant for UI callers.",
     handler: async (event, ctx) => {
-        const { userId, notificationType, channel } = event.payload;
+        const { userId, channel } = event.payload;
+        const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
         const { tenantId } = event.user;
         if (!ctx.systemDb) {
             throw new InternalError({

package/dist/delivery/handlers/set-preference.write.js

@@ -1,6 +1,7 @@
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { currentNotificationType } from "../notification-type-aliases.js";
 import { upsertPreference } from "../upsert-preference.js";
 export const setPreferenceWrite = defineWriteHandler({
     name: "setPreference",
@@ -18,7 +19,8 @@ export const setPreferenceWrite = defineWriteHandler({
     },
     description: "Enables or disables one notification type and channel combination for the calling user, where either side may be the wildcard * as a catch-all; use it when a user changes their own notification settings.",
     handler: async (event, ctx) => {
-        const { notificationType, channel, enabled } = event.payload;
+        const { channel, enabled } = event.payload;
+        const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
         const { id: userId, tenantId } = event.user;
         // delivery runs in system-scope (feature.ts r.systemScope()) — ctx.systemDb
         // is guaranteed there. No client-supplied userId exists on this payload;

package/dist/delivery/handlers/unsubscribe-address.write.js

@@ -2,6 +2,7 @@ import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { upsertAddressOptOut } from "../address-opt-out.js";
+import { currentNotificationType } from "../notification-type-aliases.js";
 export const unsubscribeAddressWrite = defineWriteHandler({
     name: "unsubscribeAddress",
     schema: z.object({
@@ -16,7 +17,8 @@ export const unsubscribeAddressWrite = defineWriteHandler({
     agent: { expose: false },
     description: "Records a no-account address opt-out for one notificationType/channel combination; dispatched by the signed unsubscribe route, not meant for UI callers.",
     handler: async (event, ctx) => {
-        const { addressHash, notificationType, channel } = event.payload;
+        const { addressHash, channel } = event.payload;
+        const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
         const { tenantId } = event.user;
         if (!ctx.systemDb) {
             throw new InternalError({

package/dist/delivery/handlers/unsubscribe-user.write.js

@@ -1,6 +1,7 @@
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { currentNotificationType } from "../notification-type-aliases.js";
 import { upsertPreference } from "../upsert-preference.js";
 export const unsubscribeUserWrite = defineWriteHandler({
     name: "unsubscribeUser",
@@ -18,7 +19,8 @@ export const unsubscribeUserWrite = defineWriteHandler({
     handler: async (event, ctx) => {
         // userId comes from the payload, not event.user.id — the caller here is
         // the system user dispatchSystemWrite runs as, not the user unsubscribing.
-        const { userId, notificationType, channel } = event.payload;
+        const { userId, channel } = event.payload;
+        const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
         const { tenantId } = event.user;
         if (!ctx.systemDb) {
             throw new InternalError({

package/dist/delivery/notification-type-aliases.d.ts

@@ -0,0 +1,3 @@
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+export declare function notificationTypeNames(registry: Registry, type: string): readonly string[];
+export declare function currentNotificationType(registry: Registry, type: string): string;

package/dist/delivery/notification-type-aliases.js

@@ -0,0 +1,11 @@
+export function notificationTypeNames(registry, type) {
+    const renamedFrom = registry.getAllNotifications().get(type)?.renamedFrom ?? [];
+    return [type, ...renamedFrom];
+}
+export function currentNotificationType(registry, type) {
+    for (const [name, definition] of registry.getAllNotifications()) {
+        if (definition.renamedFrom?.includes(type))
+            return name;
+    }
+    return type;
+}

package/dist/derivatives-sharp/feature.js

@@ -9,7 +9,7 @@ export const derivativesSharpFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    r.requires("file-derivatives");
+    r.requires({ features: ["file-derivatives"] });
     const plugin = { render: renderImage };
     r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
 });

package/dist/document-ingest-foundation/feature.js

@@ -90,8 +90,8 @@ export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) =
     });
     // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
     // tenant-subject ciphertext and needs the destroy hook below.
-    r.requires("config", "tenant-lifecycle");
-    r.entity("documentExtract", documentExtractEntity);
+    r.requires({ features: ["config", "tenant-lifecycle"] });
+    r.entity({ name: "documentExtract", ...documentExtractEntity });
     r.useExtension(EXT_TENANT_DATA, "documentExtract", {
         destroy: documentExtractTenantDestroyHook,
     });

package/dist/file-derivatives/feature.js

@@ -53,12 +53,12 @@ export function createFileDerivativesFeature(opts = {}) {
         });
         // Needs a storage provider to read the original + write the variant —
         // without file-foundation there's nothing to derive from or write to.
-        r.requires("file-foundation");
+        r.requires({ features: ["file-foundation"] });
         // variant() reads fileRefsTable, which "files" (not file-foundation)
         // owns — without this, mounting file-derivatives + file-foundation
         // alone boots fine but fails at request-time with a SQL error the first
         // time variant() runs.
-        r.requires("files");
+        r.requires({ features: ["files"] });
         r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
             onRegister: () => {
                 // No side-effects at register-time — resolution (exact MIME match,
@@ -103,7 +103,7 @@ export function createFileDerivativesFeature(opts = {}) {
                 // tenant's public variants from staying reachable — require the
                 // dependency so a missing mount fails boot, not the tenant check
                 // silently no-op-ing at request time.
-                r.requires("tenant");
+                r.requires({ features: ["tenant"] });
                 r.queryHandler(publicVariantByFileRefQuery);
             }
             r.httpRoute({

package/dist/file-foundation/feature.js

@@ -27,7 +27,7 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    r.requires("config");
+    r.requires({ features: ["config"] });
     r.extendsRegistrar(EXT_FILE_PROVIDER, {
         onRegister: () => {
             // No side-effects at register-time — registry stores the usage,

package/dist/file-provider-inmemory/feature.js

@@ -49,10 +49,10 @@ export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    // Kein r.requires("config") + kein r.requires("secrets") — der
+    // Kein requires auf "config" oder "secrets" — der
     // In-Memory-Provider hat keine Config + kein Secret. Nur die
     // file-foundation muss da sein (Plugin-extension-point).
-    r.requires("file-foundation");
+    r.requires({ features: ["file-foundation"] });
     const plugin = {
         build: async (_ctx, tenantId) => {
             // Returnt den per-tenant Storage. Identitätsstabil zwischen calls

package/dist/file-provider-s3/feature.js

@@ -32,9 +32,9 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    r.requires("config");
-    r.requires("secrets");
-    r.requires("file-foundation");
+    r.requires({ features: ["config"] });
+    r.requires({ features: ["secrets"] });
+    r.requires({ features: ["file-foundation"] });
     const secretAccessKey = r.secret("s3.secretAccessKey", {
         label: { en: "S3 secret access key" },
         hint: {

package/dist/file-provider-s3-env/feature.js

@@ -32,10 +32,10 @@ export const fileProviderS3EnvFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "storage",
         recommended: false,
     });
-    // No r.requires("config") / r.requires("secrets") — credentials come from
+    // No requires on "config" or "secrets" — credentials come from
     // env, not the per-tenant config + secrets store. Only the file-foundation
     // plugin-extension-point must be mounted.
-    r.requires("file-foundation");
+    r.requires({ features: ["file-foundation"] });
     const plugin = {
         // tenantId ignored: one shared bucket serves all tenants (isolation via
         // tenant-prefixed / UUID keys). Built fresh per call like file-provider-s3;

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

@@ -23,7 +23,7 @@ export function createFilesTenantDataFeature() {
             category: "compliance",
             recommended: false,
         });
-        r.requires("tenant-lifecycle");
+        r.requires({ features: ["tenant-lifecycle"] });
         r.optionalRequires("files");
         r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy: fileRefTenantDestroyHook });
         r.useExtension(EXT_STORAGE_PROVIDER, "fileRef", { destroyTenant: fileRefStorageDestroyHook });

package/dist/folders/feature.js

@@ -31,8 +31,8 @@ function registerFolders(r, access, toggleable, ownership, parents) {
     if (toggleable !== undefined)
         r.toggleable(toggleable);
     const folderAssignmentEntity = createFolderAssignmentEntity(ownership, parents);
-    r.entity("folder", folderEntity);
-    r.entity("folder-assignment", folderAssignmentEntity);
+    r.entity({ name: "folder", ...folderEntity });
+    r.entity({ name: "folder-assignment", ...folderAssignmentEntity });
     // Folder catalog — plain CRUD, no custom logic. update is rename (and, in a
     // later stage, reparent: it accepts changes.parentId, optimistic-locked).
     r.writeHandler(defineEntityCreateHandler("folder", folderEntity, {

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

@@ -11,7 +11,7 @@ export const foldersUserDataFeature = defineFeature("folders-user-data", (r) =>
     // 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("user-data-rights");
+    r.requires({ features: ["user-data-rights"] });
     r.optionalRequires("folders");
     r.useExtension(EXT_USER_DATA, "folder", {
         export: folderExportHook,

package/dist/form-draft/feature.js

@@ -23,11 +23,11 @@ function registerFormDraft(r) {
     // config is optional: the retention-days key only resolves when the
     // config feature is mounted (ctx.configResolver present) — the cleanup
     // job already falls back to FORM_DRAFT_DEFAULT_RETENTION_DAYS otherwise
-    // (see handlers/cleanup.job.ts). A hard r.requires("config") would break
+    // (see handlers/cleanup.job.ts). A hard r.requires({ features: ["config"] }) would break
     // every app that mounts form-draft without config, which is a breaking
     // change no minor/patch release should introduce silently.
     r.optionalRequires("config");
-    r.entity("form-draft", formDraftEntity);
+    r.entity({ name: "form-draft", ...formDraftEntity });
     r.writeHandler(saveDraftWrite);
     r.writeHandler(discardDraftWrite);
     r.queryHandler(getDraftQuery);

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

@@ -8,7 +8,7 @@ import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engi
 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("user-data-rights");
+    r.requires({ features: ["user-data-rights"] });
     r.optionalRequires("form-draft");
     r.useExtension(EXT_USER_DATA, "form-draft", {
         export: formDraftExportHook,

package/dist/inbound-mail-foundation/connect-routes.d.ts

@@ -1,5 +1,6 @@
 import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 import { type OAuthAccessTokenManager } from "./oauth-access-token.js";
+import type { InboundMailContext } from "./types.js";
 export type InboundMailConnectRoutesOptions = {
     /** HMAC-secret for the state param (deploy-time env — `scope:"system"`
      *  secrets don't exist in secrets-v1). */
@@ -21,6 +22,8 @@ export type InboundMailConnectRoutesOptions = {
      *  lock and primes the access-token cache from the code exchange. Omitted
      *  → plain secret write, no cache priming. */
     readonly oauthTokens?: OAuthAccessTokenManager;
+    /** Handed to the provider plugin's context (`InboundMailContext.metricsFor`). */
+    readonly metricsFor?: InboundMailContext["metricsFor"];
 };
 /** Builds the `entry:"user"`/`entry:"signature"` extraRoute pair. Mount via
  *  `extraRoutes: createInboundMailConnectRoutes(options)`. */

package/dist/inbound-mail-foundation/connect-routes.js

@@ -80,7 +80,12 @@ export function createInboundMailConnectRoutes(options) {
             if (!deps.secrets) {
                 return errorJson(c, 500, "secrets_context_missing", `${INBOUND_MAIL_FOUNDATION_FEATURE}: no secrets context wired for the oauth callback route — the refresh token cannot be persisted`);
             }
-            const providerCtx = { registry: deps.registry, secrets: deps.secrets, config: undefined };
+            const providerCtx = {
+                registry: deps.registry,
+                secrets: deps.secrets,
+                config: undefined,
+                ...(options.metricsFor && { metricsFor: options.metricsFor }),
+            };
             let plugin;
             try {
                 plugin = resolveInboundProviderForKey(providerCtx, state.providerKey);

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

@@ -62,7 +62,7 @@ export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATIO
         recommended: false,
     });
     // EXT_TENANT_DATA-Hook braucht den tenant-lifecycle-Host.
-    r.requires("tenant-lifecycle");
+    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

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

@@ -1,20 +1,25 @@
 import type { ConfigAccessor, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { MetricsHandle } from "@cosmicdrift/kumiko-framework/observability";
 import { INBOUND_MAIL_PROVIDER_EXTENSION, type InboundMailAccountStatus } from "./constants.js";
 /**
- * Slim-Context für Provider-Plugins.
+ * Slim context for provider plugins.
  *
- * **Felder:**
- *   config   — tenant-config-reads (host/port/... der Plugins)
- *   registry — extension-Lookup in der Factory (nicht plugin-intern)
- *   secrets  — tenant-secret-reads (IMAP-Passwort, OAuth-Refresh-Token)
- *   _userId  — Audit-Identity für secret-reads. Handler-Pfad: dispatcher
- *              setzt Caller-User-ID; Worker-Pfad: System-Identity.
+ * **Fields:**
+ *   config   — tenant config reads (host/port/... of the plugins)
+ *   registry — extension lookup in the factory (not plugin-internal)
+ *   secrets  — tenant secret reads (IMAP password, OAuth refresh token)
+ *   _userId  — audit identity for secret reads. Handler path: the dispatcher
+ *              sets the caller user ID; worker path: system identity.
+ *   metricsFor — metrics handle of a feature by name, same behavior as
+ *              HandlerContext.metricsFor: unregistered metrics are a silent
+ *              no-op instead of a throw.
  */
 export type InboundMailContext = {
     readonly config?: ConfigAccessor;
     readonly registry?: Registry;
     readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
     readonly _userId?: string | undefined;
+    readonly metricsFor?: (featureName: string) => MetricsHandle;
 };
 /**
  * Plaintext-Sicht auf ein verbundenes Postfach, wie Provider sie sehen.
@@ -141,6 +146,11 @@ export type InboundMailProviderPlugin = {
          *  whose provider declares `oauth` (authMethod oauth/xoauth2). Absent
          *  for password accounts and providers without an oauth flow. */
         readonly accessToken?: string;
+        /** Batch lookup of the provider message ids not yet ingested for this
+         *  account (committed seen anchors, one query per call). Call it after
+         *  the listing/delta page and download MIME only for the returned ids.
+         *  Ingest dedup stays the correctness anchor; this only saves downloads. */
+        readonly filterUnknownMessageIds?: (providerMessageIds: readonly string[]) => Promise<ReadonlySet<string>>;
     }) => Promise<InboundFetchResult>;
     /** Nur OAuth-Provider. */
     readonly oauth?: InboundOAuthFlow;