@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -1,24 +1,24 @@
-// ingest-message — programmatic entry-point für Provider-Plugins
-// (watch-callback + fetchSince-Sync). Nimmt eine normalisierte
-// RawInboundMessage und macht atomic in EINER TX:
+// ingest-message — programmatic entry point for provider plugins
+// (watch callback + fetchSince sync). Accepts a normalized
+// RawInboundMessage and performs atomically in ONE TX:
 //
-//   1. Idempotency-Check (cheap: store_mail_seen_messages; Defense-in-
-//      depth: Stream-Existenz auf der deterministic aggregateId).
-//   2. threadKey-Normalisierung (Provider-Thread-ID bevorzugt, sonst
-//      References-Chain-Root, sonst Message-ID = Single-Message-Thread).
-//   3. PII-Encrypt (from/to/cc/subject/snippet) VOR dem append —
-//      Event-Log UND Projection tragen Ciphertext (#800-Muster).
-//   4. inbound-message-received-append (Inline-Projection schreibt
-//      read_inbound_messages in derselben TX). Savepoint-scoped
+//   1. Idempotency check (cheap: store_mail_seen_messages; defense in
+//      depth: stream existence check on the deterministic aggregateId).
+//   2. threadKey normalization (provider thread ID preferred, otherwise
+//      References chain root, otherwise Message-ID = single-message thread).
+//   3. PII encryption (from/to/cc/subject/snippet) BEFORE the append —
+//      both the event log AND projection contain ciphertext.
+//   4. inbound-message-received append (inline projection writes
+//      read_inbound_messages in the same TX). Savepoint-scoped
 //      (ctx.tryAppendEvent) — a losing concurrent ingest for the same
 //      messageAggId returns { duplicate: true } instead of failing the TX.
-//   5. Thread-Rollup: mail-thread-updated-append mit neu berechnetem
-//      Snapshot (count+1, max(lastMessageAt)) — die apply ist ein
-//      dummer UPSERT.
-//   6. seen-message-Dedup-Anchor einfügen.
+//   5. Thread rollup: mail-thread-updated append with a recalculated
+//      snapshot (count+1, max(lastMessageAt)) — the apply is a
+//      dumb UPSERT.
+//   6. Insert the seen-message deduplication anchor.
 //
-// SystemAdmin-only: Aufrufer ist der Watch/Sync-Supervisor bzw. der
-// Poll-Cron mit programmatic SystemUser — nie ein Tenant-Request.
+// SystemAdmin-only: the caller is the watch/sync supervisor or
+// the poll cron with a programmatic SystemUser — never a tenant request.
 
 import {
   configuredPiiSubjectKms,
@@ -49,25 +49,25 @@ import {
 import { inboundMessagesProjectionTable } from "../projection.ts";
 
 // =============================================================================
-// Input-Schema — der normalisierte Provider-Output (RawInboundMessage,
-// types.ts) + Envelope (accountId/providerName/providerCursor). rawMime
-// ist hier bewusst NICHT dabei: der Aufrufer persisted den Body VOR dem
-// ingest-Call nach file-foundation und übergibt nur bodyRef — der
-// Handler-Payload bleibt blob-frei (Event-Store-Disziplin).
+// Input schema — the normalized provider output (RawInboundMessage,
+// types.ts) plus the envelope (accountId/providerName/providerCursor). rawMime
+// is intentionally excluded: the caller persists the body to
+// file-foundation BEFORE the ingest call and passes only bodyRef — the
+// handler payload remains blob-free (event-store discipline).
 // =============================================================================
 
 export const ingestMessageSchema = z.object({
   accountId: z.uuid(),
-  /** Scope-Vererbung vom Account — der Supervisor kennt den
-   *  MailAccountRecord und reicht ownerUserId durch. */
+  /** Scope inherited from the account — the supervisor knows the
+   *  MailAccountRecord and passes ownerUserId through. */
   ownerUserId: z.string().max(36).nullable(),
   providerName: z.string().min(1).max(50),
-  /** Provider-native Message-ID — Idempotency-Anchor mit accountId. */
+  /** Provider-native Message-ID — idempotency anchor with accountId. */
   providerMessageId: z.string().min(1).max(500),
-  /** RFC-5322 Message-ID ohne <>; null → deterministischer Ersatz. */
+  /** RFC-5322 Message-ID without <>; null → deterministic fallback. */
   messageIdHeader: z.string().min(1).max(500).nullable(),
   providerThreadId: z.string().min(1).max(500).nullable(),
-  /** References/In-Reply-To-Chain, älteste zuerst. */
+  /** References/In-Reply-To chain, oldest first. */
   references: z.array(z.string().min(1).max(500)).max(200),
   from: z.string().min(1).max(2000),
   to: z.array(z.string().max(2000)).max(200),
@@ -78,20 +78,20 @@ export const ingestMessageSchema = z.object({
   /** file-foundation-Ref; leer im snippet-only-Mode. */
   bodyRef: z.string().max(500),
   scope: z.string().min(1).max(200),
-  /** Cursor-Snapshot zum Ingest-Zeitpunkt — Debug/Replay, landet in
-   *  metadata.headers, nie im payload. */
+  /** Cursor snapshot at ingest time — used for debugging/replay and stored in
+   *  metadata.headers, never in the payload. */
   providerCursor: z.string().max(2000),
 });
 type IngestMessagePayload = z.infer<typeof ingestMessageSchema>;
 
 /**
- * threadKey-Normalisierung (Plan §3.2):
- *   1. Provider-Thread-ID falls vorhanden — provider-präfixed, damit
- *      IMAP-References-Keys und Graph-conversationIds nie kollidieren.
- *   2. Sonst Root der References-Chain (älteste Message-ID = der
- *      Thread-Anker, den alle Replies teilen).
- *   3. Sonst die eigene Message-ID → Single-Message-Thread; ein späteres
- *      Reply trägt sie als References-Root und landet im selben Thread.
+ * Normalizes threadKey:
+ *   1. Use the provider thread ID when present — prefix it with the provider
+ *      so IMAP References keys and Graph conversationIds never collide.
+ *   2. Otherwise use the root of the References chain (the oldest Message-ID,
+ *      which is the thread anchor shared by all replies).
+ *   3. Otherwise use the own Message-ID → single-message thread; a later
+ *      reply carries it as the References root and joins the same thread.
  */
 function buildThreadKey(p: IngestMessagePayload, effectiveMessageIdHeader: string): string {
   if (p.providerThreadId) return `${p.providerName}:${p.providerThreadId}`.slice(0, 500);
@@ -123,12 +123,12 @@ export const ingestMessageHandler: WriteHandlerDef = {
     const messageAggId = inboundMessageAggregateId(payload.accountId, payload.providerMessageId);
 
     // ---------------------------------------------------------------
-    // 1. Idempotency. Cheap path zuerst: Dedup-Anchor-Row. Der
-    //    Stream-Check dahinter ist Defense-in-depth für den Fall dass
-    //    ein früherer ingest NACH dem append aber VOR dem seen-insert
-    //    gestorben ist (kann in einer TX nicht passieren — aber der
-    //    Check ist billig und macht den Handler rebuild-robust falls
-    //    store_mail_seen_messages je getruncated wird).
+    // 1. Idempotency. Use the deduplication anchor row first because it is
+    //    cheap. The stream check afterward provides defense in depth if
+    //    an earlier ingest died AFTER the append but BEFORE the seen insert
+    //    (this cannot happen within one TX, but the check is cheap and makes
+    //    the handler robust to rebuilding if store_mail_seen_messages is
+    //    ever truncated).
     // ---------------------------------------------------------------
     const seenRows = await ctx.db.selectMany(seenMessageTable, {
       accountId: payload.accountId,
@@ -163,11 +163,10 @@ export const ingestMessageHandler: WriteHandlerDef = {
     const threadAggId = mailThreadAggregateId(tenantId, threadKey);
 
     // ---------------------------------------------------------------
-    // 3. PII-Encrypt. to/cc werden VOR encryption JSON-stringified —
-    //    im Payload steht der Ciphertext-String, nicht das Array
-    //    (primitives only, upcaster-safe). Kein KMS konfiguriert =
-    //    plaintext-passthrough (Engine-off-Verhalten, Muster
-    //    billing-foundation process-event #724/#800).
+    // 3. PII encryption. Serialize to/cc as JSON BEFORE encryption so the
+    //    payload contains a ciphertext string rather than an array
+    //    (primitives only, upcaster-safe). If no KMS is configured, pass
+    //    through plaintext (engine-off behavior).
     // ---------------------------------------------------------------
     const piiKms = configuredPiiSubjectKms();
     const messagePlainPii = {
@@ -243,14 +242,14 @@ export const ingestMessageHandler: WriteHandlerDef = {
     //    concurrent ingests on the same thread (Watch-Push vs.
     //    Poll-Reconciliation overlap, or two different messages of the
     //    same thread arriving at once) converge on the true count.
-    //    acquireNamespacedAdvisoryLock below (issue #2155) serializes this whole
+    //    acquireNamespacedAdvisoryLock below serializes this whole
     //    countWhere+append section per threadAggId — transaction-scoped,
     //    so it survives tryAppendEvent's inner SAVEPOINT and releases at
     //    the enclosing TX's commit/rollback. Without it, a concurrent
     //    commit landing between countWhere and tryAppendEvent's own fresh
     //    version-read makes the append succeed with a stale count instead
     //    of a VersionConflictError, so the retry loop below never sees it
-    //    as a conflict to retry (#1229's original gap). Unlike step 4, a
+    //    as a conflict to retry (the original gap). Unlike step 4, a
     //    lost version-conflict race here must NOT be treated as a no-op
     //    duplicate — skipping would leave this message's contribution to
     //    messageCount/lastMessageAt out of the thread forever. Exhausting
@@ -315,8 +314,8 @@ export const ingestMessageHandler: WriteHandlerDef = {
     }
 
     // ---------------------------------------------------------------
-    // 6. Dedup-Anchor. Läuft in derselben TX wie die appends — stirbt
-    //    der Handler, rollt alles zusammen zurück.
+    // 6. Deduplication anchor. It runs in the same TX as the appends, so
+    //    if the handler fails, everything is rolled back together.
     // ---------------------------------------------------------------
     await ctx.db.insertOne(seenMessageTable, {
       tenantId,

package/packages/bundled-features/src/inbound-mail-foundation/handlers/list-accounts.query.ts

@@ -1,12 +1,12 @@
-// list-accounts — tenant-scoped Liste der verbundenen Postfächer fürs
-// Connect-/Settings-UI. PII (address) wird beim Read decrypted (Muster
-// billing-foundation list-subscriptions).
+// list-accounts — tenant-scoped list of connected mailboxes for the
+// Connect/Settings UI. PII (address) is decrypted on read, following the
+// billing-foundation list-subscriptions pattern.
 //
-// **Scope-Sichtbarkeit (Plan Entscheidung 2):** shared-Postfächer
-// (ownerUserId=null) sieht jeder Berechtigte; persönliche nur der Owner
-// selbst + TenantAdmin/SystemAdmin (Compliance-Sicht). Filter läuft
-// in-memory nach dem tenant-scoped select — Volumen ist die Anzahl
-// verbundener Postfächer eines Tenants (einstellig bis zweistellig).
+// **Scope visibility:** authorized users can see shared mailboxes
+// (ownerUserId=null); personal mailboxes are visible only to their owner,
+// TenantAdmin, or SystemAdmin for compliance access. Filtering runs in memory
+// after the tenant-scoped select because a tenant has only a single- to
+// double-digit number of connected mailboxes.
 import {
   configuredPiiSubjectKms,
   decryptPiiFieldValues,

package/packages/bundled-features/src/inbound-mail-foundation/handlers/list-messages.query.ts

@@ -1,12 +1,12 @@
-// list-messages — tenant-scoped Message-Liste (Inbox-Cockpit).
-// Optionale Filter: accountId (ein Postfach), threadKey (eine
-// Konversation), scope (Folder-Hint). PII (from/to/cc/subject/snippet)
-// wird beim Read decrypted; to/cc bleiben JSON-stringified strings —
-// der Client parsed sie (dokumentiert im Event-Payload).
+// list-messages — tenant-scoped message list for the inbox cockpit.
+// Optional filters: accountId (one mailbox), threadKey (one conversation),
+// scope (folder hint). PII (from/to/cc/subject/snippet) is decrypted on read;
+// to/cc remain JSON-stringified strings, which the client parses as documented
+// in the event payload.
 //
-// Bewusst KEINE Pagination in V1: die Projection ist tenant-scoped und
-// das Inbox-Cockpit lädt begrenzte Zeiträume; ein `limit`-Feld ist
-// vorwärtskompatibel ergänzbar ohne den QN zu brechen.
+// Deliberately no pagination in V1: the projection is tenant-scoped and the
+// inbox cockpit loads bounded time ranges; a `limit` field can be added
+// compatibly without breaking the QN.
 
 import {
   configuredPiiSubjectKms,
@@ -42,8 +42,8 @@ export const listMessagesQuery: QueryHandlerDef = {
     if (payload.scope) filter["scope"] = payload.scope;
 
     const allRows = await ctx.db.selectMany(inboundMessagesProjectionTable, filter);
-    // Scope-Sichtbarkeit (Plan Entscheidung 2): Messages persönlicher
-    // Postfächer nur für Owner + TenantAdmin/SystemAdmin.
+    // Scope visibility: messages in personal mailboxes are visible only to the
+    // owner or TenantAdmin/SystemAdmin.
     const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));
     const piiKms = configuredPiiSubjectKms();
     if (!piiKms) return { rows };

package/packages/bundled-features/src/inbound-mail-foundation/handlers/scope-visibility.ts

@@ -1,7 +1,6 @@
-// Scope-Sichtbarkeit (Plan Entscheidung 2): shared-Rows
-// (ownerUserId=null) sieht jeder Berechtigte; persönliche nur der Owner
-// selbst + TenantAdmin/SystemAdmin (Compliance-Sicht). Gilt identisch
-// für read_mail_accounts und read_inbound_messages (Scope-Vererbung).
+// Scope visibility: shared rows (`ownerUserId=null`) are visible to any authorized caller;
+// personal rows are visible only to the owner, `TenantAdmin`, or `SystemAdmin` for compliance.
+// The same rule applies to `read_mail_accounts` and `read_inbound_messages`.
 
 export function isVisibleToCaller(
   row: Readonly<Record<string, unknown>>,

package/packages/bundled-features/src/inbound-mail-foundation/handlers/update-account.write.ts

@@ -1,9 +1,14 @@
-// update-account — Account-Status-Übergänge: Watch-Supervisor meldet
-// error/backoff, OAuth-Refresh scheitert (auth_error), Tenant-Admin
-// re-enabled nach Credential-Fix. Full-snapshot-Event: lädt den letzten
-// Stand, merged die Delta-Felder, appendet den neuen Snapshot.
+// update-account — Account status transitions: the watch supervisor reports
+// error/backoff, OAuth refresh fails (auth_error), or a tenant admin re-enables
+// the account after fixing its credentials. Full-snapshot event: loads the
+// latest state, merges the delta fields, and appends the new snapshot.
 
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import {
+  type SessionUser,
+  SYSTEM_USER_ID,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { InboundMailAccountStatuses } from "../constants.ts";
@@ -27,12 +32,19 @@ export const updateAccountSchema = z.object({
   /** Ops-Signal ("idle", "watching", "backoff:3", ...). */
   watchState: z.string().max(100).optional(),
   displayName: z.string().max(200).optional(),
-  /** Audit-Grund für metadata.headers ("watch_supervisor",
-   *  "oauth_refresh", "tenant_admin"). */
-  reason: z.string().min(1).max(100),
+  /** Audit reason for metadata.headers, honored for the system identity only
+   *  ("watch_supervisor", "oauth_refresh"); user callers get a role-derived reason. */
+  reason: z.string().min(1).max(100).optional(),
 });
 type UpdateAccountPayload = z.infer<typeof updateAccountSchema>;
 
+const SYSTEM_FALLBACK_REASON = "system";
+
+function auditReasonFor(user: SessionUser, requestedReason: string | undefined): string {
+  if (user.id === SYSTEM_USER_ID) return requestedReason ?? SYSTEM_FALLBACK_REASON;
+  return user.roles.includes(ROLES.SystemAdmin) ? "system_admin" : "tenant_admin";
+}
+
 export const updateAccountHandler: WriteHandlerDef = {
   name: "update-account",
   schema: updateAccountSchema,
@@ -48,15 +60,15 @@ export const updateAccountHandler: WriteHandlerDef = {
       return failNotFound("mail-account", payload.accountId);
     }
     if (current.status === InboundMailAccountStatuses.disconnected) {
-      // Getrennte Accounts sind final — Re-Enable läuft über einen
-      // frischen connect (neuer Stream, neuer Secret-Slot). Verhindert
-      // dass ein nachzügelnder Supervisor-Tick einen disconnected
-      // Account wieder auf active hebt (Race Disconnect vs. Poll).
+      // Disconnected accounts are final; re-enabling requires a fresh connect
+      // (new stream, new secret slot). This prevents a delayed supervisor tick
+      // from restoring a disconnected account to active (disconnect vs. poll
+      // race).
       return failUnprocessable("account_disconnected", { accountId: payload.accountId });
     }
 
-    // Merge: address/provider/authMethod kommen 1:1 aus dem letzten
-    // Snapshot (address bleibt Ciphertext — nie re-encrypten).
+    // address/provider/authMethod come unchanged from the latest snapshot
+    // (address remains ciphertext—never re-encrypt it).
     const eventPayload: MailAccountEventPayload = {
       ...current,
       ...(payload.status !== undefined ? { status: payload.status } : {}),
@@ -65,7 +77,7 @@ export const updateAccountHandler: WriteHandlerDef = {
     };
     const headers: MailAccountEventHeaders = {
       providerName: current.provider,
-      reason: payload.reason,
+      reason: auditReasonFor(event.user, payload.reason),
     };
     await ctx.unsafeAppendEvent({
       aggregateId: payload.accountId,

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

@@ -38,5 +38,4 @@ export const INBOUND_MAIL_FOUNDATION_I18N: Readonly<Record<string, { readonly en
   },
   [formFieldKey("accountId")]: { en: "Mailbox" },
   [formFieldKey("displayName")]: { en: "Name" },
-  [formFieldKey("reason")]: { en: "Reason" },
 };

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

@@ -1,14 +1,15 @@
-// HMAC-signierter OAuth-`state`-Parameter für den Connect-Flow.
+// HMAC-signed OAuth-`state` parameter for the connect flow.
 //
-// Bindet {tenantId, ownerUserId?, providerKey, mailbox, nonce} an den
-// Redirect: der anonyme Callback (außerhalb /api/*) vertraut NUR dem
-// verifizierten state — verhindert CSRF und Fremd-Claiming (ein
-// Angreifer kann den Callback nicht auf einen fremden Tenant/User
-// umbiegen, ohne die Signatur zu brechen).
+// Binds {tenantId, ownerUserId?, providerKey, mailbox, nonce} to the
+// redirect: the anonymous callback (outside /api/*) trusts only the
+// verified state, preventing CSRF and cross-tenant or cross-user claiming
+// because an attacker cannot redirect the callback to another tenant or
+// user without breaking the signature.
 //
 // Format: <payload-base64url>.<expiresAtMs>.<hmac-base64url>
-// Muster: auth-email-password/signed-token.ts (HMAC-SHA256, purpose im
-// HMAC-Input, timing-safe compare, Expiry im Klartext-Segment).
+// Patterned after auth-email-password/signed-token.ts (HMAC-SHA256, purpose
+// in the HMAC input, timing-safe comparison, expiry in the clear-text
+// segment).
 
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
@@ -18,14 +19,14 @@ const STATE_PURPOSE = "inbound-mail-oauth-connect";
 
 export type OAuthStatePayload = {
   readonly tenantId: string;
-  /** null = shared-Postfach, sonst persönliches Postfach dieses Users. */
+  /** null = shared mailbox; otherwise this user's personal mailbox. */
   readonly ownerUserId: string | null;
   readonly providerKey: string;
-  /** Postfach-Adresse aus dem Connect-Request — landet nach dem
-   *  Token-Exchange im MailAccount. */
+  /** Mailbox address from the connect request; after token exchange, it is
+   * stored in the MailAccount. */
   readonly mailbox: string;
-  /** Einmal-Nonce — macht jeden state einzigartig (kein Replay über
-   *  zwei parallele Connect-Flows hinweg). */
+  /** One-time nonce makes each state unique, preventing replay across
+   * two parallel connect flows. */
   readonly nonce: string;
 };
 
@@ -72,8 +73,8 @@ export function verifyOAuthState(
   const expected = sign(hmacInput(payloadB64, expiresAtMs), secret);
   const expectedBuf = Buffer.from(expected, "base64url");
   const providedBuf = Buffer.from(providedSig, "base64url");
-  // Length-check VOR timingSafeEqual — die würde bei Längen-Mismatch
-  // werfen, und der Throw selbst leakt via Timing.
+  // Check the length before timingSafeEqual: it throws on a length mismatch,
+  // and the throw itself leaks information through timing.
   if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
   if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
 

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

@@ -1,21 +1,22 @@
-// Inline-projections für die drei event-sourced Streams:
+// Inline projections for the three event-sourced streams:
 //   mail-account     → read_mail_accounts     (UPSERT, current state)
 //   inbound-message  → read_inbound_messages  (INSERT-ignore, append-only)
-//   mail-thread      → read_mail_threads      (UPSERT, Rollup)
+//   mail-thread      → read_mail_threads      (UPSERT, rollup)
 //
-// Apply läuft in derselben TX wie ctx.unsafeAppendEvent — read-your-
-// own-write ohne dispatcher-tick (Muster billing-foundation).
+// Apply runs in the same transaction as ctx.unsafeAppendEvent, providing
+// read-your-own-write without waiting for a dispatcher tick (as in
+// billing-foundation).
 //
-// **Production-deployment caveat** (gleich wie billing-foundation):
-// die Tables sind als raw drizzle-pgTable in r.projection registriert,
-// NICHT als r.entity — Apps müssen sie in ihre drizzle/generate.ts
-// aufnehmen (via *-ProjectionTable-Imports). setupTestStack pusht sie
-// automatisch via r.projection.table.
+// **Production-deployment caveat** (same as billing-foundation):
+// The tables are registered as raw drizzle-pgTable instances in r.projection,
+// NOT as r.entity. Apps must include them in their drizzle/generate.ts
+// (via *-ProjectionTable imports). setupTestStack pushes them automatically
+// via r.projection.table.
 //
-// **PII:** die Payload-Felder (address/from/to/cc/subject/snippet)
-// kommen bereits als Ciphertext an — encrypted VOR dem append im
-// write-handler. Die applies kopieren nur durch; decrypted wird erst
-// in den list-queries.
+// **PII:** The payload fields (address/from/to/cc/subject/snippet) already
+// arrive as ciphertext because they are encrypted BEFORE the append in the
+// write handler. The applies only copy them through; decryption happens only
+// in the list queries.
 
 import {
   buildEntityTable,
@@ -32,8 +33,8 @@ import type {
   MailThreadEventPayload,
 } from "./events.ts";
 
-// Drizzle-table-instances aus den entity-shapes — geteilt zwischen
-// projection-applies und list-queries (ein column-namespace).
+// Drizzle table instances derived from the entity shapes, shared between
+// projection applies and list queries to provide one column namespace.
 export const mailAccountsProjectionTable = buildEntityTable("mail-account", mailAccountEntity);
 export const inboundMessagesProjectionTable = buildEntityTable(
   "inbound-message",
@@ -57,9 +58,10 @@ const mailThreadsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
 );
 
 // =============================================================================
-// mail-account — connected/updated/disconnected teilen den payload-shape,
-// der event-type taggt was passiert ist. Alle drei UPSERT-full für
-// defensive consistency (rebuild-aus-dem-Nichts, out-of-order).
+// mail-account — connected/updated/disconnected share the payload shape;
+// the event type identifies what happened. All three perform a full UPSERT
+// for defensive consistency during from-scratch rebuilds and out-of-order
+// processing.
 // =============================================================================
 
 const applyMailAccountUpsert = defineApply<MailAccountEventPayload>(async (event, tx) => {
@@ -91,16 +93,16 @@ const applyMailAccountUpsert = defineApply<MailAccountEventPayload>(async (event
 
 /** mail-account-connected → UPSERT full. */
 export const applyMailAccountConnected = applyMailAccountUpsert;
-/** mail-account-updated → UPSERT full (status/watchState-Übergänge). */
+/** mail-account-updated → full UPSERT for status/watchState transitions. */
 export const applyMailAccountUpdated = applyMailAccountUpsert;
-/** mail-account-disconnected → UPSERT full (payload.status=disconnected).
- *  Row bleibt (Audit-Sicht in der Account-Liste), Stream bleibt. */
+/** mail-account-disconnected → full UPSERT (payload.status=disconnected).
+ *  The row and stream remain for audit visibility in the account list. */
 export const applyMailAccountDisconnected = applyMailAccountUpsert;
 
 // =============================================================================
-// inbound-message — genau EIN received-event pro Stream (deterministic
-// aggregateId). INSERT-ignore: Replays no-op'en auf der PK statt zu
-// knallen; es gibt keinen update-Fall.
+// inbound-message — exactly one received event per stream (deterministic
+// aggregateId). INSERT-ignore makes replays no-ops on the primary key;
+// there is no update case.
 // =============================================================================
 
 /** inbound-message-received → INSERT ... ON CONFLICT DO NOTHING. */
@@ -127,13 +129,13 @@ export const applyInboundMessageReceived = defineApply<InboundMessageEventPayloa
 );
 
 // =============================================================================
-// mail-thread — Rollup pro (tenantId, threadKey). Der write-handler
-// berechnet messageCount/lastMessageAt und appendet den updated-event
-// mit dem NEUEN Stand — die apply ist ein dummer UPSERT-full (kein
-// increment in der apply: Replays wären sonst nicht idempotent).
+// mail-thread — rollup per (tenantId, threadKey). The write handler computes
+// messageCount/lastMessageAt and appends the updated event with the NEW state.
+// The apply performs a full UPSERT rather than incrementing, because
+// replays would otherwise not be idempotent.
 // =============================================================================
 
-/** mail-thread-updated → UPSERT full mit dem Payload-Snapshot. */
+/** mail-thread-updated → full UPSERT with the payload snapshot. */
 export const applyMailThreadUpdated = defineApply<MailThreadEventPayload>(async (event, tx) => {
   const p = event.payload;
   const mutable = {

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

@@ -1,8 +1,8 @@
-// Provider-Factory — Mirror von mail-foundation's createTransportForTenant
-// inkl. der drei Fehlerpfade (kein registry / nicht registriert / falsche
-// Plugin-Shape). Abweichung zum Outbound-Muster (Plan §1.3): KEIN
-// per-Tenant-Config-Selector — der Provider steht pro MailAccount
-// (`account.provider`), ein Tenant kann mehrere Provider parallel nutzen.
+// Provider factory — mirrors mail-foundation's createTransportForTenant, including
+// the three error paths (missing registry, unregistered provider, invalid plugin
+// shape). Unlike the outbound pattern, there is no per-tenant config selector:
+// the provider is specified per MailAccount (`account.provider`), so a tenant can
+// use multiple providers in parallel.
 
 import { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION } from "./constants.ts";
 import {
@@ -12,8 +12,8 @@ import {
   type MailAccountRecord,
 } from "./types.ts";
 
-/** Lookup per Provider-Key ("imap", "m365-graph", ...) — genutzt von den
- *  OAuth-Connect-Routen, wo noch kein Account existiert. */
+/** Looks up a provider by key ("imap", "m365-graph", ...); used by OAuth
+ *  connect routes before an account exists. */
 export function resolveInboundProviderForKey(
   ctx: InboundMailContext,
   providerKey: string,
@@ -42,8 +42,8 @@ export function resolveInboundProviderForKey(
   return usage.options;
 }
 
-/** Lookup für einen konkreten Account — der Standard-Pfad in Poll-Job
- *  und Watch-Supervisor. */
+/** Looks up the provider for a specific account; the standard path for poll jobs
+ *  and the watch supervisor. */
 export function resolveInboundProviderForAccount(
   ctx: InboundMailContext,
   account: MailAccountRecord,