@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/inbound-mail-foundation/watch-supervisor.js

@@ -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, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { fetchOne, insertOne, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/db";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
@@ -64,9 +63,10 @@ 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 function createInboundMailSupervisor(deps) {
     const pollIntervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     const backfillWindowDays = deps.backfillWindowDays ?? DEFAULT_BACKFILL_WINDOW_DAYS;
@@ -103,8 +103,8 @@ export function createInboundMailSupervisor(deps) {
     let pollInFlight = null;
     const watchers = new Map();
     // ---------------------------------------------------------------
-    // 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() {
         const rows = await selectMany(deps.db, mailAccountsProjectionTable, {
@@ -113,11 +113,20 @@ export function createInboundMailSupervisor(deps) {
         const piiKms = configuredPiiSubjectKms();
         const records = [];
         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;
+            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.
@@ -154,7 +163,7 @@ export function createInboundMailSupervisor(deps) {
             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
         }
     }
     async function saveCursor(account, cursor) {
@@ -167,7 +176,7 @@ export function createInboundMailSupervisor(deps) {
         });
         if (existing) {
             await updateMany(deps.db, syncCursorTable, { 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, {
@@ -181,12 +190,12 @@ export function createInboundMailSupervisor(deps) {
         });
     }
     async function resetCursor(accountId) {
-        // 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, { cursor: "", updatedAt: Temporal.Now.instant().toString() }, { accountId, scope: CURSOR_SCOPE });
     }
     // ---------------------------------------------------------------
-    // Ingest — jede Message durch den Standard-Write-Handler.
+    // Ingest: every message goes through the standard write handler.
     // ---------------------------------------------------------------
     async function ingestBatch(account, msgs, cursorSnapshot) {
         for (const msg of msgs) {
@@ -214,9 +223,9 @@ export function createInboundMailSupervisor(deps) {
                 },
             });
             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 ?? {})}`);
             }
         }
@@ -229,8 +238,8 @@ export function createInboundMailSupervisor(deps) {
         });
     }
     // ---------------------------------------------------------------
-    // 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, err) {
         if (isInboundAuthError(err)) {
@@ -241,14 +250,14 @@ export function createInboundMailSupervisor(deps) {
         }
         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;
     }
@@ -259,12 +268,19 @@ export function createInboundMailSupervisor(deps) {
         return async (providerMessageIds) => {
             if (providerMessageIds.length === 0)
                 return new Set();
-            const seen = await selectMany(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();
+            for (let start = 0; start < providerMessageIds.length; start += SEEN_LOOKUP_CHUNK_SIZE) {
+                const seen = await selectMany(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)));
         };
     }
@@ -272,7 +288,8 @@ export function createInboundMailSupervisor(deps) {
         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, {
@@ -308,7 +325,7 @@ export function createInboundMailSupervisor(deps) {
             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))
@@ -316,7 +333,7 @@ export function createInboundMailSupervisor(deps) {
         }
     }
     // ---------------------------------------------------------------
-    // 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
@@ -368,7 +385,7 @@ export function createInboundMailSupervisor(deps) {
             scheduleRenew(account, state, generation);
         }
     }
-    // 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, state) {
         if (!deps.lock || state.lockToken)
             return "acquired";
@@ -390,11 +407,11 @@ export function createInboundMailSupervisor(deps) {
     }
     // kumiko-lint-ignore complexity-budget watch lifecycle (start/stop/restart) stays cohesive
     async function ensureWatcher(account, plugin) {
-        // 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 = existing ?? {
@@ -425,7 +442,8 @@ export function createInboundMailSupervisor(deps) {
         }
         const generation = state.generation;
         const scheduleRestart = (err) => {
-            // 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;
@@ -464,7 +482,7 @@ export function createInboundMailSupervisor(deps) {
             }, accessToken !== undefined ? { accessToken } : undefined);
             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;
@@ -492,7 +510,7 @@ export function createInboundMailSupervisor(deps) {
     }
     async function stopWatcher(accountId) {
         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;
@@ -533,7 +551,7 @@ export function createInboundMailSupervisor(deps) {
     // Lifecycle.
     // ---------------------------------------------------------------
     function scheduleNextPoll() {
-        // skip: Supervisor gestoppt — keinen weiteren Poll-Tick planen.
+        // skip: the supervisor is stopped; do not schedule another poll tick.
         if (!running)
             return;
         pollTimer = setTimeout(() => {
@@ -548,7 +566,7 @@ export function createInboundMailSupervisor(deps) {
     }
     return {
         async start() {
-            // skip: bereits gestartet — start() ist idempotent.
+            // skip: already started; start() is idempotent.
             if (running)
                 return;
             running = true;

package/dist/inbound-provider-imap/credential-document.js

@@ -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";
 export const imapCredentialDocumentSchema = z.object({
     host: z.string().min(1).max(255),

package/dist/inbound-provider-imap/feature.d.ts

@@ -1,8 +1,8 @@
 import { type InboundMailProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 export declare const IMAP_PROVIDER_KEY = "imap";
 export { setImapMailHostLookup } from "./imap-client.ts";
-/** 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 declare const imapInboundMailPlugin: InboundMailProviderPlugin;
 export declare function createInboundProviderImapFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;

package/dist/inbound-provider-imap/feature.js

@@ -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 { INBOUND_MAIL_PROVIDER_EXTENSION, InboundAuthError, inboundCredentialSecretKey, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
@@ -63,18 +63,18 @@ async function fetchMessages(ctx, account, cursor, opts) {
         const serverUidValidity = String(mailbox.uidValidity);
         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;
         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);
@@ -111,8 +111,8 @@ async function fetchMessages(ctx, account, cursor, opts) {
     }
 }
 // =============================================================================
-// 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(ctx, account, handlers) {
     const doc = await readCredentialDocument(ctx, account);
@@ -122,13 +122,14 @@ async function watchMailbox(ctx, account, handlers) {
         await client.connect();
         const mailbox = (await client.mailboxOpen(IMAP_MAILBOX));
         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 () => {
             const messages = [];
             let maxSeen = nextUid - 1;
             for await (const msg of client.fetch(`${nextUid}:*`, { 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({
@@ -145,7 +146,7 @@ async function watchMailbox(ctx, account, handlers) {
                 await handlers.onMessages(messages);
         };
         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) => {
@@ -154,7 +155,7 @@ async function watchMailbox(ctx, account, handlers) {
             });
         });
         const die = (err) => {
-            // skip: bereits gestoppt/gestorben — onError nur einmal feuern.
+            // skip: already stopped or terminated; fire onError only once.
             if (stopped)
                 return;
             stopped = true;
@@ -162,10 +163,10 @@ async function watchMailbox(ctx, account, handlers) {
         };
         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 {
@@ -174,7 +175,8 @@ async function watchMailbox(ctx, account, handlers) {
                 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;
                 }
             }
@@ -195,8 +197,8 @@ async function watchMailbox(ctx, account, handlers) {
 // =============================================================================
 // 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 = {
     verify: async (ctx, account) => {
         const doc = await readCredentialDocument(ctx, account);
@@ -213,9 +215,9 @@ export const imapInboundMailPlugin = {
     },
     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() {
     return defineFeature(FEATURE_NAME, (r) => {

package/dist/inbound-provider-imap/imap-client.d.ts

@@ -13,23 +13,24 @@ export type ImapCursor = {
     readonly lastUid: number;
 };
 export declare function parseImapCursor(cursor: SyncCursorPayload | null): ImapCursor | null;
-/** Wirft InboundCursorInvalidError bei UIDVALIDITY-Wechsel — die
- *  Foundation resettet den Cursor und macht einen Voll-Resync im
- *  Backfill-Fenster (Dedup fängt Dubletten). */
+/** Throws InboundCursorInvalidError when UIDVALIDITY changes; the
+ *  foundation resets the cursor and performs a full resync within the
+ *  backfill window (deduplication catches duplicates). */
 export declare function assertUidValidity(cursor: ImapCursor | null, serverUidValidity: string): void;
-/** References-Chain normalisieren: mailparser liefert string | string[]
- *  | undefined; fehlt References, trägt In-Reply-To den Thread-Anker. */
+/** Normalizes the References chain: mailparser returns string | string[]
+ *  | undefined; when References is missing, In-Reply-To provides the thread
+ *  anchor. */
 export declare function normalizeReferences(parsed: {
     references?: string | string[];
     inReplyTo?: string;
 }): string[];
-/** imapflow liefert internalDate je nach Codepfad als Date ODER string.
- *  String-Form verwerfen wir bewusst (kein Date-Parsing im Feature-Code,
- *  no-date-api) — toRawInboundMessage fällt dann auf mailparsers
- *  Date-Header zurück, der immer als echtes Date kommt. */
+/** imapflow provides internalDate as either a Date or string depending on
+ *  the code path. The string form is deliberately discarded (no date parsing
+ *  in feature code, no-date-api); toRawInboundMessage then falls back to the
+ *  mailparser Date header, which is always a real Date. */
 export declare function coerceDate(d: Date | string | undefined): Date | undefined;
-/** providerMessageId: UID ist nur innerhalb einer UIDVALIDITY eindeutig
- *  — beides zusammen ist der stabile Idempotency-Anchor. */
+/** providerMessageId: a UID is unique only within a UIDVALIDITY; together,
+ *  they form the stable idempotency anchor. */
 export declare function buildProviderMessageId(uidValidity: string, uid: number): string;
 export declare function toRawInboundMessage(args: {
     readonly source: Uint8Array;