@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -1,17 +1,16 @@
-// createInboundMailSupervisor — der langlebige Sync-Prozess der
-// Foundation: startet pro aktivem Account `plugin.watch()` (IMAP IDLE,
-// Push in Sekunden) mit Reconnect-Backoff und fährt zusätzlich den
-// periodischen Reconciliation-Poll (Default 5 min) über `plugin.fetch()`.
-// Dedup im ingest-Handler macht Watch/Poll-Überschneidung idempotent —
-// der Poll ist Korrektheits-Anker, watch nur Latenz-Optimierung.
+// createInboundMailSupervisor — the long-lived Foundation sync process:
+// starts `plugin.watch()` (IMAP IDLE, seconds-level push) for each active
+// account with reconnect backoff, and also runs the periodic reconciliation
+// poll (default: 5 min) through `plugin.fetch()`.
+// Deduplication in the ingest handler makes watch/poll overlap idempotent:
+// the poll is the correctness anchor, while watch only reduces latency.
 //
-// **Plan deviation (documented):** the plan had the poll as an `r.job`
-// cron trigger. At the time this was written, JobContext had no
-// dispatcher (verified against run-export-jobs.ts). It now does
-// (`ctx.write`/`ctx.queryAs`, job-runner.ts) — but converting the poll to
-// a cron job is a separate migration (job concurrency instead of this
-// dispatcher contract), not part of #1719, and stays untouched here. The
-// app owner still wires the supervisor in bin/server.ts:
+// **Documented deviation:** the poll was originally intended as an `r.job`
+// cron trigger. JobContext previously had no dispatcher (see
+// run-export-jobs.ts), but now has one (`ctx.write`/`ctx.queryAs`,
+// job-runner.ts). Converting the poll to a cron job is a separate migration
+// because it changes the concurrency model, so this dispatcher contract
+// remains in place. The app owner wires the supervisor in bin/server.ts:
 //
 //   const supervisor = createInboundMailSupervisor({
 //     providerCtx: { registry: deps.registry, secrets, metricsFor: deps.metricsFor },
@@ -20,29 +19,29 @@
 //       deps.dispatchSystemWrite({ handlerQn, payload, tenantId: tenantId as TenantId }),
 //     // Multi-worker deployments: share one DistributedLock (same Redis,
 //     // same key prefix) across every worker process so only one of them
-//     // holds the IMAP IDLE connection per account (#1719). Omit `lock`
+//     // holds the IMAP IDLE connection per account. Omit `lock`
 //     // for a single-process deployment — every active account gets
-//     // watched locally, same as before.
+//     // watched locally, as before.
 //     lock: createDistributedLock(redis, `${RedisKeys.lock}inbound-mail:watch:`),
 //   });
 //   await supervisor.start();
 //   // shutdown-hook: await supervisor.stop();
 //
-// **IDLE operational risk (plan §7.3):** long-lived sockets in-process.
-// Mitigated here via backoff-restart on onError, a clean stop() of every
-// watcher on shutdown, and the poll covering every gap.
+// **IDLE operational risk:** long-lived sockets run in-process.
+// Backoff restart on onError, clean shutdown of every watcher, and the poll
+// covering every gap mitigate this risk.
 //
-// **Multi-worker coordination (#1719):** the reconciliation poll stays
-// deliberately N-fold — every worker polls every active account, which
-// is idempotent and cheap. Only `plugin.watch()` holds a long-lived
-// connection, and only one worker may hold it per account. With
-// `deps.lock`, `ensureWatcher` claims a TTL lease (`lock.acquire`) for
-// the account before connecting; a worker that doesn't get it leaves the
-// account to its current holder — the poll still covers it. The holder
-// renews the claim via heartbeat (`lock.renew`, every ttl/3) for as long
-// as the watcher state lives, including across reconnect backoff, not
-// only while the connection is open. Losing the claim (Redis outage, TTL
-// exceeded) tears down the local watcher instead of racing a new holder.
+// **Multi-worker coordination:** the reconciliation poll remains deliberately
+// N-fold: every worker polls every active account, which is idempotent and
+// cheap. Only `plugin.watch()` holds a long-lived connection, and only one
+// worker may hold it per account. With `deps.lock`, `ensureWatcher` claims a
+// TTL lease (`lock.acquire`) before connecting; a worker that fails to claim
+// it leaves the account to its current holder, while the poll still covers
+// it. The holder renews the lease via heartbeat (`lock.renew`, every ttl/3)
+// for as long as the watcher state exists, including reconnect backoff, not
+// only while the connection is open. Losing the claim (for example through
+// a Redis outage or expired TTL) tears down the local watcher instead of
+// racing a new holder.
 
 import {
   configuredPiiSubjectKms,
@@ -85,18 +84,20 @@ const DEFAULT_MAX_MESSAGES_PER_POLL = 200;
 const DEFAULT_WATCH_BACKOFF_INITIAL_MS = 5_000;
 const DEFAULT_WATCH_BACKOFF_MAX_MS = 5 * 60 * 1000;
 const DEFAULT_WATCH_LEASE_TTL_SECONDS = 90;
-/** V1: ein Cursor pro Account (eine Mailbox-Inbox). Multi-Folder später
- *  über weitere scopes ohne Schema-Änderung. */
+/** One cursor per account (one mailbox inbox) for now; multi-folder support
+ *  can add further scopes later without a schema change. */
 const CURSOR_SCOPE = "default";
 
+const SEEN_LOOKUP_CHUNK_SIZE = 1000;
+
 export type InboundMailSupervisorDeps = {
-  /** Slim-Context für Provider-Calls (registry Pflicht, secrets für
-   *  Credential-Reads der Provider). */
+  /** Slim context for provider calls (`registry` is required; `secrets` is
+   *  used for provider credential reads). */
   readonly providerCtx: InboundMailContext;
-  /** App-DB — direct reads auf read_mail_accounts (Account-Snapshot)
-   *  + direct writes auf store_mail_sync_cursors (unmanaged store). */
+  /** App database — direct reads from read_mail_accounts (account snapshot)
+   *  and direct writes to store_mail_sync_cursors (unmanaged store). */
   readonly db: DbConnection;
-  /** Standard-Dispatcher mit SystemUser — trägt ingest-message +
+  /** Standard dispatcher with SystemUser — carries ingest-message and
    *  update-account. */
   readonly dispatchWrite: (args: {
     readonly handlerQn: string;
@@ -107,8 +108,8 @@ export type InboundMailSupervisorDeps = {
     readonly data?: unknown;
     readonly error?: unknown;
   }>;
-  /** Persisted den raw MIME-Body (file-foundation) und liefert den
-   *  bodyRef fürs Event. Fehlt der Hook, läuft snippet-only-Mode
+  /** Persists the raw MIME body (file-foundation) and returns its bodyRef
+   *  for the event. Without this hook, runs in snippet-only mode
    *  (bodyRef = ""). */
   readonly storeBody?: (account: MailAccountRecord, msg: RawInboundMessage) => Promise<string>;
   readonly pollIntervalMs?: number;
@@ -120,7 +121,7 @@ export type InboundMailSupervisorDeps = {
    *  before `plugin.watch()`, ensureWatcher claims a TTL lease for the
    *  account via `lock.acquire` and renews it via `lock.renew` while the
    *  watcher lives. Omit for single-process deployments — every active
-   *  account is watched locally, same as before #1719. */
+   *  account is watched locally, same as before. */
   readonly lock?: DistributedLock;
   /** Access-token lifecycle for OAuth accounts. Defaults to a manager built
    *  from `db` + `providerCtx.secrets`; pass the instance shared with
@@ -136,8 +137,8 @@ type WatcherState = {
   stop: (() => Promise<void>) | null;
   backoffMs: number;
   restartTimer: ReturnType<typeof setTimeout> | null;
-  /** Bump beim stop() — verhindert dass ein nachzügelnder Restart einen
-   *  bereits gestoppten Watcher wiederbelebt. */
+  /** Incremented by stop() to prevent a delayed restart from reviving
+   *  an already stopped watcher. */
   generation: number;
   /** Token from `deps.lock.acquire` while this worker owns the account's
    *  watch lease; null when unclaimed (no `deps.lock`, or claim lost). */
@@ -153,8 +154,8 @@ type WatchLeaseResult = "acquired" | "no-token" | "stale";
 
 export type InboundMailSupervisor = {
   readonly start: () => Promise<void>;
-  /** Ein Reconciliation-Durchlauf über alle aktiven Accounts — auch
-   *  standalone nutzbar (Tests, manueller Ops-Trigger). */
+  /** Reconciliation run across all active accounts; also usable standalone
+   *  for tests and manual operational triggers. */
   readonly pollOnce: () => Promise<void>;
   readonly stop: () => Promise<void>;
 };
@@ -214,8 +215,8 @@ export function createInboundMailSupervisor(
   const watchers = new Map<string, WatcherState>();
 
   // ---------------------------------------------------------------
-  // Account-Snapshot: aktive Accounts aller Tenants, address decrypted
-  // (Provider arbeiten nie mit Ciphertext).
+  // Account snapshot: active accounts of all tenants with the address
+  // decrypted (providers never work with ciphertext).
   // ---------------------------------------------------------------
   async function listActiveAccounts(): Promise<readonly MailAccountRecord[]> {
     const rows = await selectMany<ActiveMailAccountRow>(deps.db, mailAccountsProjectionTable, {
@@ -224,11 +225,19 @@ export function createInboundMailSupervisor(
     const piiKms = configuredPiiSubjectKms();
     const records: MailAccountRecord[] = [];
     for (const row of rows) {
-      const decrypted = piiKms
-        ? await decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
-            requestId: "inbound-mail-foundation:supervisor:list-accounts",
-          })
-        : row;
+      let decrypted: Record<string, unknown>;
+      try {
+        decrypted = piiKms
+          ? await decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+              requestId: "inbound-mail-foundation:supervisor:list-accounts",
+            })
+          : row;
+      } catch (error) {
+        // Class name only: the message may carry ciphertext or key details.
+        const errorName = error instanceof Error ? error.name : "unknown error";
+        log(`inbound-mail: account ${row.id} skipped — address did not decrypt (${errorName})`);
+        continue;
+      }
       const decryptedAddress = decrypted["address"];
       // Falling back to row.address would hand the ciphertext to a provider.
       // One undecryptable account must not stop polling of every other tenant's accounts.
@@ -264,7 +273,7 @@ export function createInboundMailSupervisor(
       const parsed: unknown = JSON.parse(row.cursor);
       return isPlainObject(parsed) ? parsed : null;
     } catch {
-      return null; // korrupter Cursor = wie kein Cursor → Backfill, Dedup fängt Dubletten
+      return null; // a corrupt cursor counts as none → backfill; dedup catches duplicates
     }
   }
 
@@ -286,7 +295,7 @@ export function createInboundMailSupervisor(
         { cursor: serialized, updatedAt: now },
         { accountId, scope: CURSOR_SCOPE },
       );
-      // skip: update-Pfad fertig — nicht in den insert-Zweig durchfallen.
+      // skip: the update path is complete; do not fall through to the insert branch.
       return;
     }
     await insertOne(deps.db, syncCursorTable, {
@@ -301,8 +310,8 @@ export function createInboundMailSupervisor(
   }
 
   async function resetCursor(accountId: string): Promise<void> {
-    // Kein deleteMany-Import nötig: leerer Cursor-String parsed zu null
-    // → nächster fetch läuft als Backfill.
+    // No deleteMany import is needed: an empty cursor parses to null, so the
+    // next fetch runs as a backfill.
     await updateMany(
       deps.db,
       syncCursorTable,
@@ -312,7 +321,7 @@ export function createInboundMailSupervisor(
   }
 
   // ---------------------------------------------------------------
-  // Ingest — jede Message durch den Standard-Write-Handler.
+  // Ingest: every message goes through the standard write handler.
   // ---------------------------------------------------------------
   async function ingestBatch(
     account: MailAccountRecord,
@@ -344,9 +353,9 @@ export function createInboundMailSupervisor(
         },
       });
       if (!result.isSuccess) {
-        // Einzel-Message-Fehler bricht den Batch: Cursor wird NICHT
-        // persistiert → nächster Tick re-fetcht ab altem Cursor, Dedup
-        // überspringt die bereits verarbeiteten.
+        // A single-message failure aborts the batch without persisting the cursor.
+        // The next tick refetches from the old cursor, and deduplication skips
+        // messages that were already processed.
         throw new Error(
           `ingest-message failed for account ${account.id}: ${JSON.stringify(result.error ?? {})}`,
         );
@@ -367,8 +376,8 @@ export function createInboundMailSupervisor(
   }
 
   // ---------------------------------------------------------------
-  // Fehler-Semantik (Plan §2-Tabelle) — geteilt von Poll und Watch.
-  // Liefert true wenn der Account weiterlaufen darf.
+  // Error semantics, shared by poll and watch. Returns true when the
+  // account may keep running.
   // ---------------------------------------------------------------
   async function handleSyncError(account: MailAccountRecord, err: unknown): Promise<boolean> {
     if (isInboundAuthError(err)) {
@@ -383,14 +392,14 @@ export function createInboundMailSupervisor(
     }
     if (isInboundRateLimitError(err)) {
       log(`inbound-mail: account ${account.id} rate-limited (retryAfter ${err.retryAfterMs}ms)`);
-      return true; // nächster Tick versucht es erneut
+      return true; // The next tick retries it
     }
     if (isInboundCursorInvalidError(err)) {
       log(`inbound-mail: account ${account.id} cursor invalid — full resync in backfill window`);
       await resetCursor(account.id);
       return true;
     }
-    // Transient/unbekannt: loggen, nächster Tick retried.
+    // Transient or unknown error: log it and retry on the next tick.
     log(`inbound-mail: account ${account.id} sync error: ${describeError(err)}`);
     return true;
   }
@@ -401,17 +410,23 @@ export function createInboundMailSupervisor(
   function unknownMessageIdsFilterFor(account: MailAccountRecord) {
     return async (providerMessageIds: readonly string[]): Promise<ReadonlySet<string>> => {
       if (providerMessageIds.length === 0) return new Set();
-      const seen = await selectMany<{ providerMessageId: string }>(
-        deps.db,
-        seenMessageTable,
-        {
-          tenantId: account.tenantId,
-          accountId: account.id,
-          providerMessageId: { in: providerMessageIds },
-        },
-        { fields: ["providerMessageId"] },
-      );
-      const seenIds = new Set(seen.map((row) => row.providerMessageId));
+      // One bind parameter per id: a full-mailbox listing would exceed Postgres' 65535 limit.
+      const seenIds = new Set<string>();
+      for (let start = 0; start < providerMessageIds.length; start += SEEN_LOOKUP_CHUNK_SIZE) {
+        const seen = await selectMany<{ providerMessageId: string }>(
+          deps.db,
+          seenMessageTable,
+          {
+            tenantId: account.tenantId,
+            accountId: account.id,
+            providerMessageId: {
+              in: providerMessageIds.slice(start, start + SEEN_LOOKUP_CHUNK_SIZE),
+            },
+          },
+          { fields: ["providerMessageId"] },
+        );
+        for (const row of seen) seenIds.add(row.providerMessageId);
+      }
       return new Set(providerMessageIds.filter((id) => !seenIds.has(id)));
     };
   }
@@ -423,7 +438,8 @@ export function createInboundMailSupervisor(
     let cursor = await loadCursor(account.id);
     let budget = maxMessagesPerPoll;
     try {
-      // hasMore-Schleife: Pagination innerhalb eines Ticks bis Budget.
+      // hasMore loop: paginate within this tick until the message budget is
+      // exhausted.
       for (;;) {
         const accessToken = await resolveAccessToken(account, plugin);
         const result = await plugin.fetch(deps.providerCtx, account, cursor, {
@@ -456,7 +472,7 @@ export function createInboundMailSupervisor(
       await pollAccount(account, plugin);
       if (running) await ensureWatcher(account, plugin);
     }
-    // Accounts die nicht mehr aktiv sind: Watcher abbauen.
+    // Remove watchers for accounts that are no longer active.
     const activeIds = new Set(accounts.map((a) => a.id));
     for (const accountId of watchers.keys()) {
       if (!activeIds.has(accountId)) await stopWatcher(accountId);
@@ -464,7 +480,7 @@ export function createInboundMailSupervisor(
   }
 
   // ---------------------------------------------------------------
-  // Watch-Lifecycle mit Backoff-Restart.
+  // Watch lifecycle with backoff restart.
   // ---------------------------------------------------------------
   // Heartbeat for a held watch lease. Independent of the connection's own
   // lifecycle — it keeps renewing across reconnect backoff, not just while
@@ -538,7 +554,7 @@ export function createInboundMailSupervisor(
     }
   }
 
-  // kumiko-lint-ignore complexity-budget yield-point stale-map check after acquire is intentional (#2460)
+  // kumiko-lint-ignore complexity-budget yield-point stale-map check after acquire is intentional
   async function acquireWatchLease(
     account: MailAccountRecord,
     state: WatcherState,
@@ -565,10 +581,10 @@ export function createInboundMailSupervisor(
     account: MailAccountRecord,
     plugin: InboundMailProviderPlugin,
   ): Promise<void> {
-    // skip: Provider ohne Live-Push — der Reconciliation-Poll deckt den Account ab.
+    // skip: provider without live push; the reconciliation poll covers the account.
     if (!plugin.watch) return;
     const existing = watchers.get(account.id);
-    // skip: Watcher läuft bereits, startet gerade, oder Restart ist geplant.
+    // skip: the watcher is already running, starting, or scheduled for restart.
     if (existing?.stop || existing?.restartTimer || existing?.starting) return;
 
     const state: WatcherState = existing ?? {
@@ -601,7 +617,8 @@ export function createInboundMailSupervisor(
     const generation = state.generation;
 
     const scheduleRestart = (err: unknown) => {
-      // skip: Supervisor gestoppt oder Watcher-Generation gewechselt — Restart wäre ein Zombie.
+      // skip: the supervisor stopped or the watcher generation changed; a restart
+      // would create a zombie watcher.
       if (!running || state.generation !== generation) return;
       state.stop = null;
       const delay = state.backoffMs;
@@ -647,7 +664,7 @@ export function createInboundMailSupervisor(
       );
       if (state.generation !== generation || !running) {
         await stop();
-        // skip: stop() kam während des Connects — Watcher wurde sofort wieder abgebaut.
+        // skip: stop() ran while connecting; the watcher was torn down right away.
         return;
       }
       state.stop = stop;
@@ -674,7 +691,7 @@ export function createInboundMailSupervisor(
 
   async function stopWatcher(accountId: string): Promise<void> {
     const state = watchers.get(accountId);
-    // skip: kein Watcher-State für diesen Account — bereits abgebaut.
+    // skip: no watcher state for this account; it is already torn down.
     if (!state) return;
     state.generation += 1;
     if (state.restartTimer) {
@@ -715,7 +732,7 @@ export function createInboundMailSupervisor(
   // Lifecycle.
   // ---------------------------------------------------------------
   function scheduleNextPoll(): void {
-    // skip: Supervisor gestoppt — keinen weiteren Poll-Tick planen.
+    // skip: the supervisor is stopped; do not schedule another poll tick.
     if (!running) return;
     pollTimer = setTimeout(() => {
       pollTimer = null;
@@ -730,7 +747,7 @@ export function createInboundMailSupervisor(
 
   return {
     async start() {
-      // skip: bereits gestartet — start() ist idempotent.
+      // skip: already started; start() is idempotent.
       if (running) return;
       running = true;
       await pollOnce();

package/packages/bundled-features/src/inbound-provider-imap/credential-document.ts

@@ -1,19 +1,19 @@
-// Connection-Dokument im per-Account-Secret-Slot
-// (inboundCredentialSecretKey(accountId), Plan §4).
+// Connection document stored in the per-account secret slot
+// (inboundCredentialSecretKey(accountId)).
 //
-// **Warum JSON im Secret statt Tenant-Config-Keys:** anders als
-// mail-transport-smtp (EIN SMTP pro Tenant) hat Inbound MEHRERE
-// Accounts pro Tenant mit verschiedenen Hosts — per-Tenant-Config-Keys
-// können das nicht tragen. Host/Port/User sind zusammen mit dem
-// Passwort ein zusammengehöriges Verbindungs-Dokument; der Slot ist
-// ohnehin encrypted-at-rest.
+// **Why JSON in the secret instead of tenant config keys:** unlike
+// mail-transport-smtp (one SMTP configuration per tenant), inbound mail
+// supports multiple accounts per tenant with different hosts, which
+// per-tenant config keys cannot represent. Host, port, and user belong
+// with the password in one connection document; the slot is encrypted
+// at rest.
 //
-// authMethod des Accounts bestimmt die Interpretation:
+// The account's authMethod determines the interpretation:
 //   password → { host, port, secure, user, password }
-//   xoauth2  → { host, port, secure, user, accessToken } — V1-Fallback:
-//              Token-Beschaffung/-Refresh gehört den OAuth-Providern
-//              (M365/Gmail, Phase 4/5); der imap-Provider konsumiert
-//              nur einen gültigen Access-Token aus dem Slot.
+//   xoauth2  → { host, port, secure, user, accessToken } — V1 fallback:
+//              OAuth providers (M365/Gmail) handle token acquisition and
+//              refresh; the imap provider only consumes a valid access
+//              token from the slot.
 
 import * as z from "zod";
 

package/packages/bundled-features/src/inbound-provider-imap/feature.ts

@@ -1,27 +1,27 @@
 // kumiko-feature-version: 1
 //
-// inbound-provider-imap — IMAP-Implementierung der inbound-mail-
-// foundation Plugin-API. Deckt den DACH-Long-Tail (IONOS, Telekom,
-// Strato, GMX/Web.de, mailbox.org, Hetzner, all-inkl) via Passwort/
-// App-Passwort ab — komplett OHNE OAuth. XOAUTH2 als Fallback für
-// M365-/Gmail-Konten (Access-Token aus dem Secret-Slot; Token-Refresh
-// gehört den OAuth-Providern, Phase 4/5).
+// inbound-provider-imap — IMAP implementation of the inbound-mail-
+// foundation plugin API. Covers the DACH long tail (IONOS, Telekom,
+// Strato, GMX/Web.de, mailbox.org, Hetzner, all-inkl) via password/
+// app-password authentication, without OAuth. XOAUTH2 is available as
+// a fallback for M365/Gmail accounts (access token from the secret slot;
+// token refresh is handled by the OAuth providers).
 //
-// **Was diese Feature liefert:**
-//   1. Plugin-Registration via r.useExtension("inboundMailProvider",
+// **What this feature provides:**
+//   1. Plugin registration via r.useExtension("inboundMailProvider",
 //      "imap", { verify, fetch, watch }).
-//   2. verify: connect+logout mit typisiertem Fehler-Mapping.
-//   3. fetch: inkrementeller Sync über UIDVALIDITY:lastUid-Cursor —
-//      UIDVALIDITY-Wechsel wirft InboundCursorInvalidError (Foundation
-//      resettet + resynct im Backfill-Fenster). Erst-Befüllung via
-//      SEARCH since=backfillWindowDays.
-//   4. watch: IMAP IDLE via imapflow — 'exists'-Event → neue UIDs
-//      fetchen → onMessages; Verbindungs-Tod → onError (Supervisor
-//      restartet mit Backoff, der Provider reconnected NICHT selbst).
+//   2. verify: connect+logout with typed error mapping.
+//   3. fetch: incremental sync using a UIDVALIDITY:lastUid cursor —
+//      a UIDVALIDITY change throws InboundCursorInvalidError (the
+//      foundation resets and resyncs within the backfill window). Initial
+//      population uses SEARCH since=backfillWindowDays.
+//   4. watch: IMAP IDLE via imapflow — the 'exists' event triggers fetching
+//      new UIDs and then onMessages; connection loss triggers onError (the
+//      supervisor restarts with backoff; the provider does not reconnect).
 //
-// Credentials: JSON-Dokument im per-Account-Secret-Slot
-// (credential-document.ts) — kein Tenant-Config, weil mehrere Accounts
-// pro Tenant verschiedene Hosts haben.
+// Credentials: JSON document in the per-account secret slot
+// (credential-document.ts), not tenant configuration, because one tenant
+// can have multiple accounts with different hosts.
 
 import { mailAllowedPrivateHostsEnvSchema } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
@@ -102,17 +102,17 @@ async function fetchMessages(
     const parsedCursor = parseImapCursor(cursor);
     assertUidValidity(parsedCursor, serverUidValidity);
 
-    // UID-Menge bestimmen: inkrementell ab lastUid+1, sonst Backfill
-    // über SEARCH since (Fenster begrenzt die Erst-Befüllung).
+    // Determine the UID set: incrementally from lastUid+1, or use a backfill
+    // via SEARCH since (the window limits the initial population).
     let uids: number[];
     if (parsedCursor) {
       const found = await client.search({ uid: `${parsedCursor.lastUid + 1}:*` }, { uid: true });
-      // `N:*`-Gotcha: liegt N über der höchsten UID, liefert IMAP
-      // trotzdem die letzte Message — rausfiltern.
+      // `N:*` gotcha: when N exceeds the highest UID, IMAP still returns the
+      // last message, so filter it out.
       uids = (found || []).filter((uid) => uid > parsedCursor.lastUid);
     } else {
       const since = Temporal.Now.instant().subtract({ hours: opts.backfillWindowDays * 24 });
-      // imapflow-API-Boundary: search() verlangt ein JS-Date.
+      // imapflow API boundary: search() requires a JS Date.
       uids = (await client.search({ since: instantToLegacyDate(since) }, { uid: true })) || [];
     }
     uids.sort((a, b) => a - b);
@@ -155,8 +155,8 @@ async function fetchMessages(
 }
 
 // =============================================================================
-// watch — IMAP IDLE (imapflow idlet automatisch bei offener Mailbox und
-// emittet 'exists' bei neuen Messages).
+// watch — IMAP IDLE (imapflow idles automatically while the mailbox is open
+// and emits 'exists' for new messages).
 // =============================================================================
 
 async function watchMailbox(
@@ -175,7 +175,8 @@ async function watchMailbox(
     await client.connect();
     const mailbox = (await client.mailboxOpen(IMAP_MAILBOX)) as MailboxObject;
     const uidValidity = String(mailbox.uidValidity);
-    // uidNext = nächste zu vergebende UID — alles ab hier ist "neu".
+    // uidNext is the next UID to be assigned, so everything from here is
+    // "new".
     let nextUid = Number(mailbox.uidNext ?? 1);
 
     const drainNew = async () => {
@@ -186,7 +187,7 @@ async function watchMailbox(
         { uid: true, internalDate: true, source: true },
         { uid: true },
       )) {
-        // `N:*`-Gotcha (siehe fetch): alte letzte Message rausfiltern.
+        // `N:*` gotcha (see fetch): filter out the previous last message.
         if (msg.uid < nextUid || !msg.source) continue;
         messages.push(
           await toRawInboundMessage({
@@ -203,14 +204,14 @@ async function watchMailbox(
     };
 
     client.on("exists", () => {
-      // skip: Watcher gestoppt — exists-Nachzügler ignorieren.
+      // skip: ignore delayed exists events after the watcher has stopped.
       if (stopped) return;
       void drainNew().catch((err) => {
         if (!stopped) handlers.onError(mapImapError(err, doc.host));
       });
     });
     const die = (err: unknown) => {
-      // skip: bereits gestoppt/gestorben — onError nur einmal feuern.
+      // skip: already stopped or terminated; fire onError only once.
       if (stopped) return;
       stopped = true;
       handlers.onError(mapImapError(err, doc.host));
@@ -218,17 +219,18 @@ async function watchMailbox(
     client.on("error", die);
     client.on("close", () => die(new Error("connection closed")));
 
-    // IDLE-Loop: 'exists' feuert NUR während client.idle() läuft
-    // (empirisch gegen greenmail verifiziert). Jedes zwischengeschobene
-    // Kommando (drainNew-fetch) beendet idle() — die Loop re-idlet,
-    // bis stop() die Verbindung schließt.
+    // IDLE loop: 'exists' fires ONLY while client.idle() is running
+    // (verified empirically against greenmail). Each intervening command
+    // (drainNew-fetch) ends idle(), so the loop re-enters idle() until
+    // stop() closes the connection.
     void (async () => {
       while (!stopped) {
         try {
           await client.idle();
         } catch (err) {
           if (!stopped) die(err);
-          // skip: idle-Loop endet — die() hat den Supervisor informiert (bzw. stop() war die Ursache).
+          // skip: the idle loop ends; die() has informed the supervisor (or stop()
+          // was the cause).
           return;
         }
       }
@@ -251,8 +253,8 @@ async function watchMailbox(
 // Plugin + Feature-definition
 // =============================================================================
 
-/** Exportiert für den Live-Test (imap-live.integration.test.ts) —
- *  Apps nutzen das Feature, nie das Plugin direkt. */
+/** Exported for the live test (imap-live.integration.test.ts) —
+ *  applications use the feature, never the plugin directly. */
 export const imapInboundMailPlugin: InboundMailProviderPlugin = {
   verify: async (ctx, account) => {
     const doc = await readCredentialDocument(ctx, account);
@@ -267,9 +269,9 @@ export const imapInboundMailPlugin: InboundMailProviderPlugin = {
   },
   fetch: fetchMessages,
   watch: watchMailbox,
-  // Kein oauth-Block: Passwort-Connect läuft über das Credential-
-  // Formular (connect-account + Secret-Write); XOAUTH2-Token-Flows
-  // gehören den OAuth-Providern (M365/Gmail).
+  // No oauth block: password authentication runs through the credential
+  // form (connect-account + Secret-Write); XOAUTH2 token flows belong to
+  // the OAuth providers (M365/Gmail).
 };
 
 export function createInboundProviderImapFeature() {