@cosmicdrift/kumiko-samples 0.366.0 → 0.368.0

package/packages/bundled-features/src/delivery/unsubscribe.ts

@@ -6,6 +6,7 @@ import {
   signatureRoute,
 } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { mailT, resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
 import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as jose from "jose";
@@ -17,6 +18,14 @@ import {
   DeliveryErrors,
   DeliveryHandlers,
 } from "./constants.js";
+import "./unsubscribe-page-strings.js";
+
+// The mail's locale, so the pages behind the link speak the mail's language. Optional: links
+// signed before the claim existed keep verifying and fall back to English.
+const localeClaimSchema = z
+  .string()
+  .regex(/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/)
+  .optional();
 
 // Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
 // wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
@@ -32,6 +41,7 @@ const unsubscribeJwtPayloadSchema = z.object({
   tenantId: z.string().min(1),
   notificationType: z.string().min(1),
   channel: z.string().min(1),
+  locale: localeClaimSchema,
 });
 
 // Address-token payload. `sub` and `addressHash` are the same value (the
@@ -45,6 +55,7 @@ const addressUnsubscribeJwtPayloadSchema = z.object({
   notificationType: z.string().min(1),
   channel: z.string().min(1),
   addressHash: z.string().min(1),
+  locale: localeClaimSchema,
 });
 
 export type UnsubscribeTokenPayload = {
@@ -52,6 +63,7 @@ export type UnsubscribeTokenPayload = {
   readonly tenantId: TenantId;
   readonly notificationType: string;
   readonly channel: string;
+  readonly locale?: string | undefined;
 };
 
 export type AddressUnsubscribeTokenPayload = {
@@ -59,6 +71,7 @@ export type AddressUnsubscribeTokenPayload = {
   readonly address: string;
   readonly notificationType: string;
   readonly channel: string;
+  readonly locale?: string | undefined;
 };
 
 /**
@@ -87,6 +100,11 @@ function assertUnsubscribeSecret(secret: string, caller: string): void {
   }
 }
 
+// An unusable locale is left out instead of failing the send; the pages then fall back to English.
+function localeClaim(locale: string | undefined): { locale?: string } {
+  return locale !== undefined && localeClaimSchema.safeParse(locale).success ? { locale } : {};
+}
+
 const UNSUBSCRIBE_TOKEN_INVALID_BODY = {
   error: { code: "unsubscribe_token_invalid", message: "Invalid or expired token" },
 } as const;
@@ -101,6 +119,7 @@ export async function signUnsubscribeToken(
     tenantId: payload.tenantId,
     notificationType: payload.notificationType,
     channel: payload.channel,
+    ...localeClaim(payload.locale),
   })
     .setProtectedHeader({ alg: "HS256" })
     .setSubject(String(payload.userId))
@@ -136,6 +155,7 @@ export async function signAddressUnsubscribeToken(
       channel: payload.channel,
       addressHash,
       kind: "address",
+      ...localeClaim(payload.locale),
     })
       .setProtectedHeader({ alg: "HS256" })
       .setSubject(addressHash)
@@ -154,6 +174,7 @@ type VerifiedUnsubscribe =
       readonly addressHash: string;
       readonly notificationType: string;
       readonly channel: string;
+      readonly locale: string | undefined;
     }
   | {
       readonly kind: "user";
@@ -161,6 +182,7 @@ type VerifiedUnsubscribe =
       readonly userId: string;
       readonly notificationType: string;
       readonly channel: string;
+      readonly locale: string | undefined;
     };
 
 // RFC 8058 fixed value — both the List-Unsubscribe-Post header and the body a
@@ -183,6 +205,7 @@ async function signResubscribeToken(
     tenantId: verified.tenantId,
     notificationType: verified.notificationType,
     channel: verified.channel,
+    ...localeClaim(verified.locale),
   };
   const jwt =
     verified.kind === "address"
@@ -254,6 +277,7 @@ async function verifyUnsubscribeToken(
         addressHash: parsed.addressHash,
         notificationType: parsed.notificationType,
         channel: parsed.channel,
+        locale: parsed.locale,
       };
     }
 
@@ -274,6 +298,7 @@ async function verifyUnsubscribeToken(
       userId: parsed.sub,
       notificationType: parsed.notificationType,
       channel: parsed.channel,
+      locale: parsed.locale,
     };
   } catch (err) {
     if (err instanceof ExtraRouteRejection) throw err;
@@ -358,40 +383,68 @@ async function dispatchResubscribeWrite(
   return isResubscribeLimitReached(dispatched.error) ? "limit_reached" : "failed";
 }
 
-function confirmationPage(token: string): string {
+function pageLocale(locale: string | undefined): string {
+  return resolveMailLocale(locale ?? "en");
+}
+
+function htmlPage(locale: string, title: string, bodyHtml: string): string {
   return `<!doctype html>
-<html>
+<html lang="${escapeHtmlAttr(locale)}">
 <head>
 <meta charset="utf-8">
 <meta name="robots" content="noindex">
-<title>Unsubscribe</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtmlAttr(title)}</title>
 </head>
 <body>
-<p>Unsubscribe from these emails?</p>
-<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
-<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
-<button type="submit">Unsubscribe</button>
-</form>
+${bodyHtml}
 </body>
 </html>`;
 }
 
-function unsubscribedPage(resubscribeToken: string): string {
-  return `<!doctype html>
-<html>
-<head>
-<meta charset="utf-8">
-<meta name="robots" content="noindex">
-<title>Unsubscribed</title>
-</head>
-<body>
-<p>You have been unsubscribed.</p>
+function confirmationPage(token: string, locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  return htmlPage(
+    lang,
+    mailT(lang, "mail.unsubscribe.confirmTitle"),
+    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmQuestion"))}</p>
+<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
+<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmButton"))}</button>
+</form>`,
+  );
+}
+
+function unsubscribedPage(resubscribeToken: string, locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  return htmlPage(
+    lang,
+    mailT(lang, "mail.unsubscribe.doneTitle"),
+    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.doneMessage"))}</p>
 <form method="post" action="${DELIVERY_RESUBSCRIBE_PATH}">
 <input type="hidden" name="token" value="${escapeHtmlAttr(resubscribeToken)}">
-<button type="submit">Undo</button>
-</form>
-</body>
-</html>`;
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.undoButton"))}</button>
+</form>`,
+  );
+}
+
+function resubscribedPage(locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  return htmlPage(
+    lang,
+    mailT(lang, "mail.unsubscribe.resubscribedTitle"),
+    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.resubscribedMessage"))}</p>`,
+  );
+}
+
+function failedPage(locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  const message = mailT(lang, "mail.unsubscribe.failed");
+  return htmlPage(lang, message, `<p>${escapeHtmlAttr(message)}</p>`);
+}
+
+function isFormRequest(contentType: string | undefined): boolean {
+  return contentType?.includes("application/x-www-form-urlencoded") === true;
 }
 
 // One-click clients put the token in the query string; only the
@@ -431,7 +484,7 @@ export function createUnsubscribeRoutes(
   assertUnsubscribeSecret(options.secret, "createUnsubscribeRoutes");
   const encodedSecret = new TextEncoder().encode(options.secret);
 
-  const confirmRoute = signatureRoute<{ token: string }>({
+  const confirmRoute = signatureRoute<{ token: string; locale: string | undefined }>({
     method: "GET",
     path: DELIVERY_UNSUBSCRIBE_PATH,
     entry: "signature",
@@ -444,11 +497,11 @@ export function createUnsubscribeRoutes(
           "missing unsubscribe token",
         );
       }
-      await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
-      return { token };
+      const verified = await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
+      return { token, locale: verified.locale };
     },
-    handler: async (c, { token }) =>
-      c.html(confirmationPage(token), 200, CONFIRMATION_PAGE_HEADERS),
+    handler: async (c, { token, locale }) =>
+      c.html(confirmationPage(token, locale), 200, CONFIRMATION_PAGE_HEADERS),
   });
 
   const writeRoute = signatureRoute<VerifiedUnsubscribe>({
@@ -463,11 +516,13 @@ export function createUnsubscribeRoutes(
       // (e.g. events-table missing, DB down) behind a misleading 400.
       const succeeded = await dispatchUnsubscribeWrite(verified, deps);
       if (!succeeded) {
-        return c.html("Unsubscribe failed", 500, { "Cache-Control": "no-store" });
+        return c.html(failedPage(verified.locale), 500, { "Cache-Control": "no-store" });
       }
-      return c.html(unsubscribedPage(await signResubscribeToken(verified, encodedSecret)), 200, {
-        "Cache-Control": "no-store",
-      });
+      return c.html(
+        unsubscribedPage(await signResubscribeToken(verified, encodedSecret), verified.locale),
+        200,
+        { "Cache-Control": "no-store" },
+      );
     },
   });
 
@@ -482,6 +537,14 @@ export function createUnsubscribeRoutes(
       verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret, "resubscribe"),
     handler: async (c, verified, deps) => {
       const outcome = await dispatchResubscribeWrite(verified, deps);
+      // The undo button on the unsubscribed page posts a form; a browser should land on a page.
+      if (isFormRequest(c.req.header("content-type"))) {
+        return outcome === "success"
+          ? c.html(resubscribedPage(verified.locale), 200, { "Cache-Control": "no-store" })
+          : c.html(failedPage(verified.locale), outcome === "limit_reached" ? 409 : 500, {
+              "Cache-Control": "no-store",
+            });
+      }
       if (outcome === "limit_reached") {
         return c.json({ error: { code: DeliveryErrors.resubscribeLimitReached } }, 409, {
           "Cache-Control": "no-store",

package/packages/bundled-features/src/delivery/upsert-preference.ts

@@ -13,8 +13,11 @@
 // fall through to update, or no-op if the winner already set the target
 // `enabled` state.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  fetchOne,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import { generateDeterministicId } from "@cosmicdrift/kumiko-framework/utils";
 import { notificationPreferenceEntity, notificationPreferencesTable } from "./tables.js";

package/packages/bundled-features/src/derivatives-sharp/feature.ts

@@ -6,17 +6,26 @@ import { renderImage } from "./render.js";
 
 const FEATURE_NAME = "derivatives-sharp";
 
-export const derivativesSharpFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    "Registers an `image/*` renderer against the `derivativeRenderer` extension point declared by `file-derivatives`, backed by sharp. Supports resize/fit (cover, inside, contain), format conversion with quality (webp, avif, jpeg), whole-image blur, and blurring individual regions burned in before resize (see BlurRegion). EXIF orientation is applied and then normalized away, and all other EXIF (including GPS) is dropped. Server-only: sharp is a native binding — never import this from client code.",
+export function createDerivativesSharpFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Registers an `image/*` renderer against the `derivativeRenderer` extension point declared by `file-derivatives`, backed by sharp. Supports resize/fit (cover, inside, contain), format conversion with quality (webp, avif, jpeg), whole-image blur, and blurring individual regions burned in before resize (see BlurRegion). EXIF orientation is applied and then normalized away, and all other EXIF (including GPS) is dropped. Server-only: sharp is a native binding — never import this from client code.",
+      );
+      r.uiHints({
+        displayLabel: "File Derivatives · Sharp",
+        category: "storage",
+        recommended: false,
+      });
+      r.requires({ features: ["file-derivatives"] });
+
+      const plugin: DerivativeRendererPlugin = { render: renderImage };
+      r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
+    },
+    { dedupeOptions: {} },
   );
-  r.uiHints({
-    displayLabel: "File Derivatives · Sharp",
-    category: "storage",
-    recommended: false,
-  });
-  r.requires({ features: ["file-derivatives"] });
+}
 
-  const plugin: DerivativeRendererPlugin = { render: renderImage };
-  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
-});
+/** @deprecated Use createDerivativesSharpFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const derivativesSharpFeature = createDerivativesSharpFeature();

package/packages/bundled-features/src/derivatives-sharp/index.ts

@@ -1,2 +1,2 @@
-export { derivativesSharpFeature } from "./feature.js";
+export { createDerivativesSharpFeature, derivativesSharpFeature } from "./feature.js";
 export { imageMetadata } from "./render.js";

package/packages/bundled-features/src/document-ingest-foundation/feature.ts

@@ -121,108 +121,117 @@ async function requestIngestForFileRef(
   });
 }
 
-export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    "Shared PDF/Scan/Image → normalized-text ingest primitive. Owns the `documentExtract` entity (fileRefId, storageKey, per-page text + metadata) as an implicit entity-projection, the per-tenant `ocrLanguage`/`maxPagesPerFile` config keys, the `documentIngestProvider` extension-point providers register accepted mimeTypes/size caps under, and a fileRef.created/fileRef.restored trigger that resolves the provider for a file's mimeType and requests ingest via `documentIngest.requested` tagged with the winning provider — a delete→restore round-trip re-requests ingest the same way a fresh upload does. An orphan-extract guard forgets any `documentExtract` whose fileRef is no longer live at processing time, regardless of how a provider's own write races the fileRef's delete/forget — providers should write through `writeDocumentExtractForLiveFileRef`.",
-  );
-  r.uiHints({
-    displayLabel: "Document Ingest Foundation",
-    category: "storage",
-    recommended: false,
-  });
-  // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
-  // tenant-subject ciphertext and needs the destroy hook below.
-  r.requires({ features: ["config", "tenant-lifecycle"] });
-
-  r.entity({ name: "documentExtract", ...documentExtractEntity });
-  r.useExtension(EXT_TENANT_DATA, "documentExtract", {
-    destroy: documentExtractTenantDestroyHook,
-  });
-
-  // No onRegister: resolution happens at boot and per-apply, not on register.
-  r.extendsRegistrar(EXT_DOCUMENT_INGEST_PROVIDER, {});
-  r.bootCheck(({ features }) => validateDocumentIngestProviderWiring(features));
-
-  const ocrLanguageConfigKey = r.config(
-    "ocrLanguage",
-    createTenantConfig("text", {
-      default: "deu+eng",
-      // Tesseract -l argument syntax: one or more 3-letter language codes
-      // joined by "+" (e.g. "deu+eng"). Unconstrained free text here would
-      // reach the OCR provider call unvalidated (#1501).
-      pattern: { regex: "^[a-z]{3}(\\+[a-z]{3})*$" },
-      write: access.roles("TenantAdmin", "SystemAdmin"),
-      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-    }),
-  );
-  const maxPagesPerFileConfigKey = r.config(
-    "maxPagesPerFile",
-    createTenantConfig("number", {
-      default: 50,
-      // Without a bound a tenant could set 0 (silently kills ingest) or an
-      // unbounded value (OCR worker runs per-file for as long as the PDF
-      // has pages — job-queue starvation) (#1501).
-      bounds: { min: 1, max: 500 },
-      write: access.roles("TenantAdmin", "SystemAdmin"),
-      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-    }),
-  );
-
-  // "fileName" can carry a real person's name, but it reaches both events already as the
-  // fileRef's own self-subject ciphertext (copied from fileRef.created/restored), which
-  // append() passes through; shredding the fileRef's key shreds it here too.
-  r.defineEvent(DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, documentIngestRequestedPayloadSchema, {
-    piiFields: "none",
-    version: 2,
-    migrations: [
-      {
-        fromVersion: 1,
-        toVersion: 2,
-        // The sentinel can never match a real where.provider filter (providers
-        // may not register under it) — an upcast v1 row reads as unclaimed
-        // instead of silently misrouting to a currently mounted provider.
-        transform: { default: { provider: UNCLAIMED_PROVIDER_SENTINEL } },
-      },
-    ],
-  });
-  r.defineEvent(DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestSkippedPayloadSchema, {
-    piiFields: "none",
-  });
-
-  r.multiStreamProjection({
-    name: "request-ingest",
-    apply: {
-      [FILE_REF_CREATED]: async (event, _tx, ctx) => {
-        // entity-event payloads are generic Record<string, unknown> — parse
-        // at the MSP boundary (same pattern as storage-tracking's readNumber).
-        const parsed = fileRefIngestFieldsSchema.safeParse(event.payload);
-        // skip: malformed / incomplete payload — don't poison the consumer
-        if (!parsed.success) return;
-        await requestIngestForFileRef(event, parsed.data, ctx);
-      },
-      [FILE_REF_RESTORED]: async (event, _tx, ctx) => {
-        // fileRef.restored carries { previous }, the pre-restore soft-deleted
-        // row (event-store-executor-write.ts restore()) — same field shape
-        // as fileRef.created's payload.
-        const parsed = fileRefIngestFieldsSchema.safeParse(event.payload["previous"]);
-        // skip: malformed / incomplete previous snapshot — don't poison the consumer
-        if (!parsed.success) return;
-        await requestIngestForFileRef(event, parsed.data, ctx);
-      },
-    },
-  });
-
-  // fileRef delete/forget cleanup: documentExtract rows are derived data —
-  // once the source file is gone (soft-deleted or Art.17-forgotten), the
-  // extracted text has no reason to survive it either.
-  r.multiStreamProjection({
-    name: "forget-extract-with-file-ref",
-    apply: {
-      [FILE_REF_DELETED]: forgetExtractOnFileRefDeletedHook,
-      [FILE_REF_FORGOTTEN]: forgetExtractOnFileRefForgottenHook,
-      [DOCUMENT_EXTRACT_CREATED]: forgetOrphanedDocumentExtractHook,
+export function createDocumentIngestFoundationFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Shared PDF/Scan/Image → normalized-text ingest primitive. Owns the `documentExtract` entity (fileRefId, storageKey, per-page text + metadata) as an implicit entity-projection, the per-tenant `ocrLanguage`/`maxPagesPerFile` config keys, the `documentIngestProvider` extension-point providers register accepted mimeTypes/size caps under, and a fileRef.created/fileRef.restored trigger that resolves the provider for a file's mimeType and requests ingest via `documentIngest.requested` tagged with the winning provider — a delete→restore round-trip re-requests ingest the same way a fresh upload does. An orphan-extract guard forgets any `documentExtract` whose fileRef is no longer live at processing time, regardless of how a provider's own write races the fileRef's delete/forget — providers should write through `writeDocumentExtractForLiveFileRef`.",
+      );
+      r.uiHints({
+        displayLabel: "Document Ingest Foundation",
+        category: "storage",
+        recommended: false,
+      });
+      // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
+      // tenant-subject ciphertext and needs the destroy hook below.
+      r.requires({ features: ["config", "tenant-lifecycle"] });
+
+      r.entity({ name: "documentExtract", ...documentExtractEntity });
+      r.useExtension(EXT_TENANT_DATA, "documentExtract", {
+        destroy: documentExtractTenantDestroyHook,
+      });
+
+      // No onRegister: resolution happens at boot and per-apply, not on register.
+      r.extendsRegistrar(EXT_DOCUMENT_INGEST_PROVIDER, {});
+      r.bootCheck(({ features }) => validateDocumentIngestProviderWiring(features));
+
+      const ocrLanguageConfigKey = r.config(
+        "ocrLanguage",
+        createTenantConfig("text", {
+          default: "deu+eng",
+          // Tesseract -l argument syntax: one or more 3-letter language codes
+          // joined by "+" (e.g. "deu+eng"). Unconstrained free text here would
+          // reach the OCR provider call unvalidated (#1501).
+          pattern: { regex: "^[a-z]{3}(\\+[a-z]{3})*$" },
+          write: access.roles("TenantAdmin", "SystemAdmin"),
+          read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+        }),
+      );
+      const maxPagesPerFileConfigKey = r.config(
+        "maxPagesPerFile",
+        createTenantConfig("number", {
+          default: 50,
+          // Without a bound a tenant could set 0 (silently kills ingest) or an
+          // unbounded value (OCR worker runs per-file for as long as the PDF
+          // has pages — job-queue starvation) (#1501).
+          bounds: { min: 1, max: 500 },
+          write: access.roles("TenantAdmin", "SystemAdmin"),
+          read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+        }),
+      );
+
+      // "fileName" can carry a real person's name, but it reaches both events already as the
+      // fileRef's own self-subject ciphertext (copied from fileRef.created/restored), which
+      // append() passes through; shredding the fileRef's key shreds it here too.
+      r.defineEvent(DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, documentIngestRequestedPayloadSchema, {
+        piiFields: "none",
+        version: 2,
+        migrations: [
+          {
+            fromVersion: 1,
+            toVersion: 2,
+            // The sentinel can never match a real where.provider filter (providers
+            // may not register under it) — an upcast v1 row reads as unclaimed
+            // instead of silently misrouting to a currently mounted provider.
+            transform: { default: { provider: UNCLAIMED_PROVIDER_SENTINEL } },
+          },
+        ],
+      });
+      r.defineEvent(DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestSkippedPayloadSchema, {
+        piiFields: "none",
+      });
+
+      r.multiStreamProjection({
+        name: "request-ingest",
+        apply: {
+          [FILE_REF_CREATED]: async (event, _tx, ctx) => {
+            // entity-event payloads are generic Record<string, unknown> — parse
+            // at the MSP boundary (same pattern as storage-tracking's readNumber).
+            const parsed = fileRefIngestFieldsSchema.safeParse(event.payload);
+            // skip: malformed / incomplete payload — don't poison the consumer
+            if (!parsed.success) return;
+            await requestIngestForFileRef(event, parsed.data, ctx);
+          },
+          [FILE_REF_RESTORED]: async (event, _tx, ctx) => {
+            // fileRef.restored carries { previous }, the pre-restore soft-deleted
+            // row (event-store-executor-write.ts restore()) — same field shape
+            // as fileRef.created's payload.
+            const parsed = fileRefIngestFieldsSchema.safeParse(event.payload["previous"]);
+            // skip: malformed / incomplete previous snapshot — don't poison the consumer
+            if (!parsed.success) return;
+            await requestIngestForFileRef(event, parsed.data, ctx);
+          },
+        },
+      });
+
+      // fileRef delete/forget cleanup: documentExtract rows are derived data —
+      // once the source file is gone (soft-deleted or Art.17-forgotten), the
+      // extracted text has no reason to survive it either.
+      r.multiStreamProjection({
+        name: "forget-extract-with-file-ref",
+        apply: {
+          [FILE_REF_DELETED]: forgetExtractOnFileRefDeletedHook,
+          [FILE_REF_FORGOTTEN]: forgetExtractOnFileRefForgottenHook,
+          [DOCUMENT_EXTRACT_CREATED]: forgetOrphanedDocumentExtractHook,
+        },
+      });
+
+      return { ocrLanguageConfigKey, maxPagesPerFileConfigKey };
     },
-  });
+    { dedupeOptions: {} },
+  );
+}
 
-  return { ocrLanguageConfigKey, maxPagesPerFileConfigKey };
-});
+/** @deprecated Use createDocumentIngestFoundationFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const documentIngestFoundationFeature = createDocumentIngestFoundationFeature();

package/packages/bundled-features/src/document-ingest-foundation/forget-extract-with-file-ref.ts

@@ -57,7 +57,7 @@ export const forgetOrphanedDocumentExtractHook: MultiStreamApplyFn = async (even
   const parsed = documentExtractCreatedPayloadSchema.safeParse(event.payload);
   // skip: malformed payload — don't poison the consumer
   if (!parsed.success) return;
-  const tenantDb = createTenantDb(tx, event.tenantId);
+  const tenantDb = createTenantDb({ db: tx, tenantId: event.tenantId });
   // skip: fileRef still live — the extract is legitimate
   if (await isFileRefLive(tenantDb, parsed.data.fileRefId)) return;
   const user = createSystemUser(event.tenantId);
@@ -70,7 +70,7 @@ export const forgetOrphanedDocumentExtractHook: MultiStreamApplyFn = async (even
 };
 
 export const forgetExtractOnFileRefDeletedHook: MultiStreamApplyFn = async (event, tx) => {
-  const tenantDb = createTenantDb(tx, event.tenantId);
+  const tenantDb = createTenantDb({ db: tx, tenantId: event.tenantId });
   // skip: fileRef is live again — request-ingest and this consumer poll via
   // separate cursors, so a delete→restore round-trip can finish before this
   // consumer sees fileRef.deleted; forgetting would drop the live file's extract.
@@ -79,6 +79,6 @@ export const forgetExtractOnFileRefDeletedHook: MultiStreamApplyFn = async (even
 };
 
 export const forgetExtractOnFileRefForgottenHook: MultiStreamApplyFn = async (event, tx) => {
-  const tenantDb = createTenantDb(tx, event.tenantId);
+  const tenantDb = createTenantDb({ db: tx, tenantId: event.tenantId });
   await forgetExtractsForFileRef(event, tenantDb);
 };

package/packages/bundled-features/src/document-ingest-foundation/index.ts

@@ -18,7 +18,10 @@ export {
   documentIngestRequestedPayloadSchema,
   documentIngestSkippedPayloadSchema,
 } from "./events.js";
-export { documentIngestFoundationFeature } from "./feature.js";
+export {
+  createDocumentIngestFoundationFeature,
+  documentIngestFoundationFeature,
+} from "./feature.js";
 export { readIngestPages, writeIngestPages } from "./pages.js";
 export {
   type DocumentIngestProviderOptions,

package/packages/bundled-features/src/feature-toggles/global-feature-state-table.ts

@@ -1,4 +1,3 @@
-import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   boolean,
   declareGlobalTenancy,
@@ -6,6 +5,7 @@ import {
   instant,
   integer,
   table as pgTable,
+  requireEntityTableMeta,
   type SchemaTable,
   sql,
   text,

package/packages/bundled-features/src/feature-toggles/handlers/set.write.ts

@@ -1,4 +1,4 @@
-import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import {
   UnprocessableError,
@@ -158,10 +158,8 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
       // and filtering by payload.featureName is trivial at query time.
       // This mirrors how `config` handles the same constraint for
       // its config-changed events.
-      // unsafeAppendEvent — bundled-features ohne lokalen Wrapper. Apps
-      // mit `bun kumiko codegen` kriegen `.kumiko/define.ts` als strict-
-      // path; bundled-features bleibt bei der unsafe-Variante. Schema-
-      // Validation läuft trotzdem via r.defineEvent("toggle-set", ...).
+      // unsafeAppendEvent: the strict appendEvent is bound to an app's own event map, which
+      // bundled-features cannot see. Schema validation still runs via r.defineEvent("toggle-set", ...).
       await ctx.unsafeAppendEvent({
         aggregateId: SYSTEM_TENANT_ID,
         aggregateType: FEATURE_TOGGLE_AGGREGATE_TYPE,

package/packages/bundled-features/src/feature-toggles/toggle-runtime.ts

@@ -1,5 +1,5 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import {
   computeEffectiveFeatures,
   type Registry,